---
name: "cpu_copy_thread"
section: "9"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/cpu_copy_thread"
---

# cpu\_copy\_thread(9)

machine-dependent interfaces to handle CPU and thread state

## NAME

**cpu\_machdep**, **cpu\_copy\_thread**, **cpu\_exec\_vmspace\_reuse**, **cpu\_exit**, **cpu\_fetch\_syscall\_args**, **cpu\_fork**, **cpu\_fork\_kthread\_handler**, **cpu\_idle**, **cpu\_idle\_wakeup**, **cpu\_procctl**, **cpu\_set\_syscall\_retval**, **cpu\_set\_upcall**, **cpu\_set\_user\_tls**, **cpu\_switch**, **cpu\_sync\_core**, **cpu\_thread\_alloc**, **cpu\_thread\_clean**, **cpu\_thread\_exit**, **cpu\_thread\_free**, **cpu\_thread\_new\_kstack**, **cpu\_throw**, **cpu\_update\_pcb** – machine-dependent interfaces to handle CPU and thread state

## SYNOPSIS

**#include \<sys/proc.h\>**

**#include \<sys/ptrace.h\>**

*void*\

**cpu\_copy\_thread**(*struct thread \*td*, *struct thread \*td0*);

*bool*\

**cpu\_exec\_vmspace\_reuse**(*struct proc \*p*, *struct vm\_map \*map*);

*void*\

**cpu\_exit**(*struct thread \*td*);

*int*\

**cpu\_fetch\_syscall\_args**(*struct thread \*td*);

*void*\

**cpu\_fork**(*struct thread \*td1*, *struct proc \*p2*, *struct thread \*td2*, *int flags*);

*void*\

**cpu\_fork\_kthread\_handler**(*struct thread \*td*, *void (\*func)(void \*)*, *void \*arg*);

*void*\

**cpu\_idle**(*int busy*);

*int*\

**cpu\_idle\_wakeup**(*int cpu*);

*int*\

**cpu\_procctl**(*struct thread \*td*, *int idtype*, *id\_t id*, *int com*, *void \*data*);

*int*\

**cpu\_ptrace**(*struct thread \*\_td*, *int req*, *void \*addr*, *int data*);

*void*\

**cpu\_set\_syscall\_retval**(*struct thread \*td*, *int error*);

*int*\

**cpu\_set\_upcall**(*struct thread \*td*, *void (\*entry)(void \*)*, *void \*arg*, *stack\_t \*stack*);

*int*\

**cpu\_set\_user\_tls**(*struct thread \*td*, *void \*tls\_base*, *int thr\_flags*);

*void*\

**cpu\_switch**(*struct thread \*old*, *struct thread \*new*, *struct mtx \*mtx*);

*void*\

**cpu\_sync\_core**(*void*);

*void*\

**cpu\_thread\_alloc**(*struct thread \*td*);

*void*\

**cpu\_thread\_clean**(*struct thread \*td*);

*void*\

**cpu\_thread\_exit**(*struct thread \*td*);

*void*\

**cpu\_thread\_free**(*struct thread \*td*);

*void*\

**cpu\_thread\_new\_kstack**(*struct thread \*td*);

*void*\

**cpu\_throw**(*struct thread \*old*, *struct thread \*new*);

*void*\

**cpu\_update\_pcb**(*struct thread \*td*);

## DESCRIPTION

These functions provide architecture-specific implementations of machine-independent abstractions.

**cpu\_exec\_vmspace\_reuse**() returns true if **exec\_new\_vmspace**() can reuse an existing *struct* *vmspace* (*map*) for the process *p* during [execve(2)](/execve/2.md). This is only invoked if *map* is not shared with any other consumers. If this returns false, **exec\_new\_vmspace**() will create a new *struct* *vmspace*.

**cpu\_exit**() releases machine-dependent resources other than the address space for the process containing *td* during process exit.

**cpu\_fork**() copies and updates machine-dependent state (for example, the pcb and user registers) from the forking thread *td1* in an existing process to the new thread *td2* in the new process *p2*. This function must set up the new thread's kernel stack and pcb so that *td2* calls **fork\_exit**() when it begins execution passing a pointer to **fork\_return**() as the *callout* argument and *td2* as the *arg* argument.

**cpu\_fork\_kthread\_handler**() adjusts a new thread's initial pcb and/or kernel stack to pass *func* and *arg* as the *callout* and *arg* arguments to **fork\_exit**(). This must be called before a new thread is scheduled to run and is used to set the “main” function for kernel threads.

**cpu\_copy\_thread**() copies machine-dependent state (for example, the pcb and user registers) from *td* to *td0* when creating a new thread in the same process. This function must set up the new thread's kernel stack and pcb so that *td0* calls **fork\_exit**() when it begins execution passing a pointer to **fork\_return**() as the *callout* argument and *td0* as the *arg* argument.

**cpu\_set\_upcall**() updates a new thread's initial user register state to call *entry* with *arg* as the sole argument using the user stack described in *stack*.

**cpu\_set\_user\_tls**() sets a new thread's initial user thread pointer register to reference the user TLS base pointer *tls\_base*. The *thr\_flags* argument provides flags bits, from the same namespace as *flags* member of the *struct* *thr\_param* argument to the [thr\_new(2)](/thr_new/2.md) syscall.

**cpu\_update\_pcb**() updates the pcb of the current thread with current user register values. This is invoked before writing out register notes in a core dump. This function typically only has to update user registers for the current thread that are saved in the pcb during context switches rather than in the trapframe on kernel entry.

Note that when **cpu\_update\_pcb**() is used, threads in a process other than the current thread are stopped, typically by **thread\_single**(). The pcbs of those stopped threads should already be updated by **cpu\_switch**().

**cpu\_fetch\_syscall\_args**() fetches the current system call arguments for the native FreeBSD ABI from the current thread's user register state and/or user stack. The arguments are saved in the *td\_sa* member of *td*.

**cpu\_set\_syscall\_retval**() updates the user register state for *td* to store system call error and return values. If *error* is 0, indicate success and return the two values in *td\_retval*. If *error* is ERESTART, adjust the user PC to re-invoke the current system call after returning to user mode. If *error* is EJUSTRETURN, leave the current user register state unchanged. For any other value of *error*, indicate error and return *error* as the error code.

**cpu\_idle**() waits for the next interrupt to occur on the current CPU. If an architecture supports low power idling, this function should place the CPU into a low power state while waiting. *busy* is a hint from the scheduler. If *busy* is non-zero, the scheduler expects a short sleep, so the CPU should prefer low-latency over maximum power savings. If *busy* is zero, the CPU should maximumize power savings including deferring unnecessary clock interrupts via **cpu\_idleclock**().

**cpu\_idle\_wakeup**() awakens the idle CPU with the ID *cpu* from a low-power state.

**cpu\_procctl**() handles any machine-dependent [procctl(2)](/procctl/2.md) requests.

**cpu\_ptrace**() handles any machine-dependent [ptrace(2)](/ptrace/2.md) requests.

**cpu\_switch**() switches the current CPU between threads by swapping register state. This function saves the current CPU register state in the pcb of *old* and loads register values from the pcb of *new* before returning. While the pcb generally contains caller-save kernel register state, it can also contain user registers that are not saved in the trapframe.

After saving the current CPU register state of *old*, **cpu\_switch**() stores *mtx* in the *td\_lock* member of *old* transferring ownership of the old thread. No data belonging to *old* can be accessed after that store. Specifically, the old thread's kernel stack must not be accessed after this point.

When SCHED\_ULE is being used, this function must wait (via spinning) for the *td\_lock* member of *new* to change to a value not equal to *&blocked\_lock* before loading register values from *new* or accessing its kernel stack.

From the caller's perspective, **cpu\_switch**() returns when *old* is rescheduled in the future, possibly on a different CPU. However, the implementation of **cpu\_switch**() returns immediately on the same CPU into the previously-saved context of *new*.

**cpu\_throw**() is similar to **cpu\_switch**() but does not save any state for *old* or write to the old thread's *td\_lock* member.

**cpu\_sync\_core**() ensures that all possible speculation and out-of-order execution is serialized on the current CPU. Note that this is called from an IPI handler so only has to handle additional serialization beyond that provided by handling an IPI.

### Thread Object Lifecycle

These functions support the management of machine-dependent thread state in conjunction with a thread object's lifecycle.

The general model is that a thread object is allocated each time a new kernel thread is created either by system calls like [fork(2)](/fork/2.md) or [thr\_new(2)](/thr_new/2.md) or when kernel-only threads are created via [kproc\_create(9)](/kproc_create/9.md), [kproc\_kthread\_add(9)](/kproc_kthread_add/9.md), or [kthread\_add(9)](/kthread_add/9.md). When a kernel thread exits, the thread object is freed. However, there is one special case to support an optimization where each free process object caches a thread object. When a process exits, the last thread object is not freed but remains attached to the process. When the process object is later reused for a new process in [fork(2)](/fork/2.md), the kernel recycles that last thread object and uses it as the initial thread in the new process. When a thread is recycled, a new kernel stack may be allocated if the existing kernel stack is not suitable for the new process.

**cpu\_thread\_alloc**() initializes machine-dependent fields in *td* when allocating a new thread object.

**cpu\_thread\_new\_kstack**() initializes kernel stack-related machine-dependent fields in *td* after allocating a new kernel stack. This function typically sets the *td\_pcb* (on architectures which store the pcb in the kernel stack) and initial *td\_frame* pointers. **cpu\_thread\_new\_kstack**() is called both when allocating a new thread object and when a recycled thread allocates a new kernel stack. Note that this function is *not* called if a recycled thread reuses its existing kernel stack.

**cpu\_thread\_clean**() releases machine-dependent resources for the last thread in a process during [wait(2)](/wait/2.md). Since the thread is a candidate for recycling, machine-dependent fields should be reset to run as a new thread in case it is recycled by a future [fork(2)](/fork/2.md). In particular, if the thread reuses its existing kernel stack, no other **cpu\_thread\_\***() function will be invoked before the thread is reused as the main thread of a new process.

**cpu\_thread\_exit**() cleans any machine-dependent state in *td* while it is exiting. This is called by the exiting thread so cannot free state needed during in-kernel execution.

**cpu\_thread\_free**() releases any machine-dependent state in *td* when it is being freed. This is called for any thread that was not the last thread in a process once it has finished execution.

## SEE ALSO

[fork(2)](/fork/2.md), [procctl(2)](/procctl/2.md), [ptrace(2)](/ptrace/2.md), [thr\_new(2)](/thr_new/2.md), [wait(2)](/wait/2.md), [kproc\_create(9)](/kproc_create/9.md), [kproc\_kthread\_add(9)](/kproc_kthread_add/9.md), [kthread\_add(9)](/kthread_add/9.md), [mi\_switch(9)](/mi_switch/9.md)

## AUTHORS

This manual page was developed by SRI International, the University of Cambridge Computer Laboratory (Department of Computer Science and Technology), and Capabilities Limited under contract (FA8750-24-C-B047) (“DEC”).