Update comments for the MD functions managing contexts for new

threads, to make it less confusing and using modern kernel terms.

Rename the functions to reflect current use of the functions, instead
of the historic KSE conventions:
  cpu_set_fork_handler -> cpu_fork_kthread_handler (for kthreads)
  cpu_set_upcall -> cpu_copy_thread (for forks)
  cpu_set_upcall_kse -> cpu_set_upcall (for new threads creation)

Reviewed by:	jhb (previous version)
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Approved by:	re (hrs)
Differential revision:	https://reviews.freebsd.org/D6731

sys/amd64/amd64/vm_machdep.c

@@ -285,10 +285,7 @@ cpu_fork(td1, p2, td2, flags)
  * This is needed to make kernel threads stay in kernel mode.
  */
 void
-cpu_set_fork_handler(td, func, arg)
+cpu_fork_kthread_handler(struct thread *td, void (*func)(void *), void *arg)
-	struct thread *td;
-	void (*func)(void *);
-	void *arg;
 {
 	/*
 	 * Note that the trap frame follows the args, so the function
@@ -421,14 +418,14 @@ cpu_set_syscall_retval(struct thread *td, int error)
 }
 
 /*
- * Initialize machine state (pcb and trap frame) for a new thread about to
+ * Initialize machine state, mostly pcb and trap frame for a new
- * upcall. Put enough state in the new thread's PCB to get it to go back 
+ * thread, about to return to userspace.  Put enough state in the new
- * userret(), where we can intercept it again to set the return (upcall)
+ * thread's PCB to get it to go back to the fork_return(), which
- * Address and stack, along with those from upcals that are from other sources
+ * finalizes the thread state and handles peculiarities of the first
- * such as those generated in thread_userret() itself.
+ * return to userspace for the new thread.
  */
 void
-cpu_set_upcall(struct thread *td, struct thread *td0)
+cpu_copy_thread(struct thread *td, struct thread *td0)
 {
 	struct pcb *pcb2;
 
@@ -484,12 +481,11 @@ cpu_set_upcall(struct thread *td, struct thread *td0)
 }
 
 /*
- * Set that machine state for performing an upcall that has to
+ * Set that machine state for performing an upcall that starts
- * be done in thread_userret() so that those upcalls generated
+ * the entry function with the given argument.
- * in thread_userret() itself can be done as well.
  */
 void
-cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
+cpu_set_upcall(struct thread *td, void (*entry)(void *), void *arg,
     stack_t *stack)
 {
 
@@ -505,7 +501,7 @@ cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
 #ifdef COMPAT_FREEBSD32
 	if (SV_PROC_FLAG(td->td_proc, SV_ILP32)) {
 		/*
-	 	 * Set the trap frame to point at the beginning of the uts
+		 * Set the trap frame to point at the beginning of the entry
 		 * function.
 		 */
 		td->td_frame->tf_rbp = 0;
@@ -513,10 +509,7 @@ cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
 		   (((uintptr_t)stack->ss_sp + stack->ss_size - 4) & ~0x0f) - 4;
 		td->td_frame->tf_rip = (uintptr_t)entry;
 
-		/*
+		/* Pass the argument to the entry point. */
-		 * Pass the address of the mailbox for this kse to the uts
-		 * function as a parameter on the stack.
-		 */
 		suword32((void *)(td->td_frame->tf_rsp + sizeof(int32_t)),
 		    (uint32_t)(uintptr_t)arg);
 
@@ -539,10 +532,7 @@ cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
 	td->td_frame->tf_gs = _ugssel;
 	td->td_frame->tf_flags = TF_HASSEGS;
 
-	/*
+	/* Pass the argument to the entry point. */
-	 * Pass the address of the mailbox for this kse to the uts
-	 * function as a parameter on the stack.
-	 */
 	td->td_frame->tf_rdi = (register_t)arg;
 }
 

sys/amd64/cloudabi64/cloudabi64_sysvec.c

@@ -172,7 +172,7 @@ cloudabi64_thread_setregs(struct thread *td,
 	/* Perform standard register initialization. */
 	stack.ss_sp = (void *)attr->stack;
 	stack.ss_size = tcbptr - attr->stack;
-	cpu_set_upcall_kse(td, (void *)attr->entry_point, NULL, &stack);
+	cpu_set_upcall(td, (void *)attr->entry_point, NULL, &stack);
 
 	/*
 	 * Pass in the thread ID of the new thread and the argument

sys/arm/arm/swtch-v6.S

@@ -450,8 +450,8 @@ sw1:
 
 	/*
 	 * Restore all saved registers and return. Note that some saved
-	 * registers can be changed when either cpu_fork(), cpu_set_upcall(),
+	 * registers can be changed when either cpu_fork(), cpu_copy_thread(),
-	 * cpu_set_fork_handler(), or makectx() was called.
+	 * cpu_fork_kthread_handler(), or makectx() was called.
 	 */
 	add	r3, r7, #PCB_R4
 	ldmia	r3, {r4-r12, sp, pc}

sys/arm/arm/vm_machdep.c

@@ -226,14 +226,14 @@ cpu_set_syscall_retval(struct thread *td, int error)
 }
 
 /*
- * Initialize machine state (pcb and trap frame) for a new thread about to
+ * Initialize machine state, mostly pcb and trap frame for a new
- * upcall. Put enough state in the new thread's PCB to get it to go back
+ * thread, about to return to userspace.  Put enough state in the new
- * userret(), where we can intercept it again to set the return (upcall)
+ * thread's PCB to get it to go back to the fork_return(), which
- * Address and stack, along with those from upcals that are from other sources
+ * finalizes the thread state and handles peculiarities of the first
- * such as those generated in thread_userret() itself.
+ * return to userspace for the new thread.
  */
 void
-cpu_set_upcall(struct thread *td, struct thread *td0)
+cpu_copy_thread(struct thread *td, struct thread *td0)
 {
 
 	bcopy(td0->td_frame, td->td_frame, sizeof(struct trapframe));
@@ -253,12 +253,11 @@ cpu_set_upcall(struct thread *td, struct thread *td0)
 }
 
 /*
- * Set that machine state for performing an upcall that has to
+ * Set that machine state for performing an upcall that starts
- * be done in thread_userret() so that those upcalls generated
+ * the entry function with the given argument.
- * in thread_userret() itself can be done as well.
  */
 void
-cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
+cpu_set_upcall(struct thread *td, void (*entry)(void *), void *arg,
 	stack_t *stack)
 {
 	struct trapframe *tf = td->td_frame;
@@ -327,7 +326,7 @@ cpu_thread_clean(struct thread *td)
  * This is needed to make kernel threads stay in kernel mode.
  */
 void
-cpu_set_fork_handler(struct thread *td, void (*func)(void *), void *arg)
+cpu_fork_kthread_handler(struct thread *td, void (*func)(void *), void *arg)
 {
 	td->td_pcb->pcb_regs.sf_r4 = (register_t)func;	/* function */
 	td->td_pcb->pcb_regs.sf_r5 = (register_t)arg;	/* first arg */

sys/arm64/arm64/vm_machdep.c

@@ -153,14 +153,14 @@ cpu_set_syscall_retval(struct thread *td, int error)
 }
 
 /*
- * Initialize machine state (pcb and trap frame) for a new thread about to
+ * Initialize machine state, mostly pcb and trap frame for a new
- * upcall. Put enough state in the new thread's PCB to get it to go back
+ * thread, about to return to userspace.  Put enough state in the new
- * userret(), where we can intercept it again to set the return (upcall)
+ * thread's PCB to get it to go back to the fork_return(), which
- * Address and stack, along with those from upcals that are from other sources
+ * finalizes the thread state and handles peculiarities of the first
- * such as those generated in thread_userret() itself.
+ * return to userspace for the new thread.
  */
 void
-cpu_set_upcall(struct thread *td, struct thread *td0)
+cpu_copy_thread(struct thread *td, struct thread *td0)
 {
 	bcopy(td0->td_frame, td->td_frame, sizeof(struct trapframe));
 	bcopy(td0->td_pcb, td->td_pcb, sizeof(struct pcb));
@@ -177,12 +177,11 @@ cpu_set_upcall(struct thread *td, struct thread *td0)
 }
 
 /*
- * Set that machine state for performing an upcall that has to
+ * Set that machine state for performing an upcall that starts
- * be done in thread_userret() so that those upcalls generated
+ * the entry function with the given argument.
- * in thread_userret() itself can be done as well.
  */
 void
-cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
+cpu_set_upcall(struct thread *td, void (*entry)(void *), void *arg,
 	stack_t *stack)
 {
 	struct trapframe *tf = td->td_frame;
@@ -238,7 +237,7 @@ cpu_thread_clean(struct thread *td)
  * This is needed to make kernel threads stay in kernel mode.
  */
 void
-cpu_set_fork_handler(struct thread *td, void (*func)(void *), void *arg)
+cpu_fork_kthread_handler(struct thread *td, void (*func)(void *), void *arg)
 {
 
 	td->td_pcb->pcb_x[8] = (uintptr_t)func;

sys/arm64/cloudabi64/cloudabi64_sysvec.c

@@ -140,7 +140,7 @@ cloudabi64_thread_setregs(struct thread *td,
 	/* Perform standard register initialization. */
 	stack.ss_sp = (void *)attr->stack;
 	stack.ss_size = attr->stack_size;
-	cpu_set_upcall_kse(td, (void *)attr->entry_point, NULL, &stack);
+	cpu_set_upcall(td, (void *)attr->entry_point, NULL, &stack);
 
 	/*
 	 * Pass in the thread ID of the new thread and the argument

sys/compat/linux/linux_fork.c

@@ -300,7 +300,7 @@ linux_clone_thread(struct thread *td, struct linux_clone_args *args)
 	if (error)
 		goto fail;
 
-	cpu_set_upcall(newtd, td);
+	cpu_copy_thread(newtd, td);
 
 	bzero(&newtd->td_startzero,
 	    __rangeof(struct thread, td_startzero, td_endzero));

sys/i386/i386/vm_machdep.c

@@ -324,10 +324,7 @@ cpu_fork(td1, p2, td2, flags)
  * This is needed to make kernel threads stay in kernel mode.
  */
 void
-cpu_set_fork_handler(td, func, arg)
+cpu_fork_kthread_handler(struct thread *td, void (*func)(void *), void *arg)
-	struct thread *td;
-	void (*func)(void *);
-	void *arg;
 {
 	/*
 	 * Note that the trap frame follows the args, so the function
@@ -458,14 +455,14 @@ cpu_set_syscall_retval(struct thread *td, int error)
 }
 
 /*
- * Initialize machine state (pcb and trap frame) for a new thread about to
+ * Initialize machine state, mostly pcb and trap frame for a new
- * upcall. Put enough state in the new thread's PCB to get it to go back 
+ * thread, about to return to userspace.  Put enough state in the new
- * userret(), where we can intercept it again to set the return (upcall)
+ * thread's PCB to get it to go back to the fork_return(), which
- * Address and stack, along with those from upcals that are from other sources
+ * finalizes the thread state and handles peculiarities of the first
- * such as those generated in thread_userret() itself.
+ * return to userspace for the new thread.
  */
 void
-cpu_set_upcall(struct thread *td, struct thread *td0)
+cpu_copy_thread(struct thread *td, struct thread *td0)
 {
 	struct pcb *pcb2;
 
@@ -527,12 +524,11 @@ cpu_set_upcall(struct thread *td, struct thread *td0)
 }
 
 /*
- * Set that machine state for performing an upcall that has to
+ * Set that machine state for performing an upcall that starts
- * be done in thread_userret() so that those upcalls generated
+ * the entry function with the given argument.
- * in thread_userret() itself can be done as well.
  */
 void
-cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
+cpu_set_upcall(struct thread *td, void (*entry)(void *), void *arg,
     stack_t *stack)
 {
 
@@ -546,7 +542,7 @@ cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
 	cpu_thread_clean(td);
 
 	/*
-	 * Set the trap frame to point at the beginning of the uts
+	 * Set the trap frame to point at the beginning of the entry
 	 * function.
 	 */
 	td->td_frame->tf_ebp = 0; 
@@ -554,10 +550,7 @@ cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
 	    (((int)stack->ss_sp + stack->ss_size - 4) & ~0x0f) - 4;
 	td->td_frame->tf_eip = (int)entry;
 
-	/*
+	/* Pass the argument to the entry point. */
-	 * Pass the address of the mailbox for this kse to the uts
-	 * function as a parameter on the stack.
-	 */
 	suword((void *)(td->td_frame->tf_esp + sizeof(void *)),
 	    (int)arg);
 }

sys/kern/init_main.c

@@ -862,7 +862,8 @@ create_init(const void *udata __unused)
 	PROC_UNLOCK(initproc);
 	sx_xunlock(&proctree_lock);
 	crfree(oldcred);
-	cpu_set_fork_handler(FIRST_THREAD_IN_PROC(initproc), start_init, NULL);
+	cpu_fork_kthread_handler(FIRST_THREAD_IN_PROC(initproc),
+	    start_init, NULL);
 }
 SYSINIT(init, SI_SUB_CREATE_INIT, SI_ORDER_FIRST, create_init, NULL);
 

sys/kern/kern_fork.c

@@ -1030,7 +1030,7 @@ fork_exit(void (*callout)(void *, struct trapframe *), void *arg,
 	thread_unlock(td);
 
 	/*
-	 * cpu_set_fork_handler intercepts this function call to
+	 * cpu_fork_kthread_handler intercepts this function call to
 	 * have this call a non-return function to stay in kernel mode.
 	 * initproc has its own fork handler, but it does return.
 	 */

sys/kern/kern_kthread.c

@@ -124,7 +124,7 @@ kproc_create(void (*func)(void *), void *arg,
 #endif
 
 	/* call the processes' main()... */
-	cpu_set_fork_handler(td, func, arg);
+	cpu_fork_kthread_handler(td, func, arg);
 
 	/* Avoid inheriting affinity from a random parent. */
 	cpuset_setthread(td->td_tid, cpuset_root);
@@ -281,14 +281,11 @@ kthread_add(void (*func)(void *), void *arg, struct proc *p,
 	vsnprintf(newtd->td_name, sizeof(newtd->td_name), fmt, ap);
 	va_end(ap);
 
-	newtd->td_proc = p;  /* needed for cpu_set_upcall */
+	newtd->td_proc = p;  /* needed for cpu_copy_thread */
-
+	/* might be further optimized for kthread */
-	/* XXX optimise this probably? */
+	cpu_copy_thread(newtd, oldtd);
-	/* On x86 (and probably the others too) it is way too full of junk */
-	/* Needs a better name */
-	cpu_set_upcall(newtd, oldtd);
 	/* put the designated function(arg) as the resume context */
-	cpu_set_fork_handler(newtd, func, arg);
+	cpu_fork_kthread_handler(newtd, func, arg);
 
 	newtd->td_pflags |= TDP_KTHREAD;
 	thread_cow_get_proc(newtd, p);

sys/kern/kern_thr.c

@@ -163,7 +163,7 @@ thr_new_initthr(struct thread *td, void *thunk)
 	stack.ss_sp = param->stack_base;
 	stack.ss_size = param->stack_size;
 	/* Set upcall address to user thread entry function. */
-	cpu_set_upcall_kse(td, param->start_func, param->arg, &stack);
+	cpu_set_upcall(td, param->start_func, param->arg, &stack);
 	/* Setup user TLS address and TLS pointer register. */
 	return (cpu_set_user_tls(td, param->tls_base));
 }
@@ -227,7 +227,7 @@ thread_create(struct thread *td, struct rtprio *rtp,
 	if (error)
 		goto fail;
 
-	cpu_set_upcall(newtd, td);
+	cpu_copy_thread(newtd, td);
 
 	bzero(&newtd->td_startzero,
 	    __rangeof(struct thread, td_startzero, td_endzero));

sys/mips/mips/vm_machdep.c

@@ -194,7 +194,7 @@ cpu_fork(register struct thread *td1,register struct proc *p2,
  * This is needed to make kernel threads stay in kernel mode.
  */
 void
-cpu_set_fork_handler(struct thread *td, void (*func) __P((void *)), void *arg)
+cpu_fork_kthread_handler(struct thread *td, void (*func)(void *), void *arg)
 {
 	/*
 	 * Note that the trap frame follows the args, so the function
@@ -352,14 +352,14 @@ cpu_set_syscall_retval(struct thread *td, int error)
 }
 
 /*
- * Initialize machine state (pcb and trap frame) for a new thread about to
+ * Initialize machine state, mostly pcb and trap frame for a new
- * upcall. Put enough state in the new thread's PCB to get it to go back
+ * thread, about to return to userspace.  Put enough state in the new
- * userret(), where we can intercept it again to set the return (upcall)
+ * thread's PCB to get it to go back to the fork_return(), which
- * Address and stack, along with those from upcalls that are from other sources
+ * finalizes the thread state and handles peculiarities of the first
- * such as those generated in thread_userret() itself.
+ * return to userspace for the new thread.
  */
 void
-cpu_set_upcall(struct thread *td, struct thread *td0)
+cpu_copy_thread(struct thread *td, struct thread *td0)
 {
 	struct pcb *pcb2;
 
@@ -415,12 +415,11 @@ cpu_set_upcall(struct thread *td, struct thread *td0)
 }
 
 /*
- * Set that machine state for performing an upcall that has to
+ * Set that machine state for performing an upcall that starts
- * be done in thread_userret() so that those upcalls generated
+ * the entry function with the given argument.
- * in thread_userret() itself can be done as well.
  */
 void
-cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
+cpu_set_upcall(struct thread *td, void (*entry)(void *), void *arg,
     stack_t *stack)
 {
 	struct trapframe *tf;

sys/powerpc/powerpc/exec_machdep.c

@@ -955,7 +955,7 @@ cpu_set_user_tls(struct thread *td, void *tls_base)
 }
 
 void
-cpu_set_upcall(struct thread *td, struct thread *td0)
+cpu_copy_thread(struct thread *td, struct thread *td0)
 {
 	struct pcb *pcb2;
 	struct trapframe *tf;
@@ -996,7 +996,7 @@ cpu_set_upcall(struct thread *td, struct thread *td0)
 }
 
 void
-cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
+cpu_set_upcall(struct thread *td, void (*entry)(void *), void *arg,
     stack_t *stack)
 {
 	struct trapframe *tf;

sys/powerpc/powerpc/vm_machdep.c

@@ -179,7 +179,7 @@ cpu_fork(struct thread *td1, struct proc *p2, struct thread *td2, int flags)
  * This is needed to make kernel threads stay in kernel mode.
  */
 void
-cpu_set_fork_handler(struct thread *td, void (*func)(void *), void *arg)
+cpu_fork_kthread_handler(struct thread *td, void (*func)(void *), void *arg)
 {
 	struct callframe *cf;
 

sys/riscv/riscv/vm_machdep.c

@@ -146,14 +146,14 @@ cpu_set_syscall_retval(struct thread *td, int error)
 }
 
 /*
- * Initialize machine state (pcb and trap frame) for a new thread about to
+ * Initialize machine state, mostly pcb and trap frame for a new
- * upcall. Put enough state in the new thread's PCB to get it to go back
+ * thread, about to return to userspace.  Put enough state in the new
- * userret(), where we can intercept it again to set the return (upcall)
+ * thread's PCB to get it to go back to the fork_return(), which
- * Address and stack, along with those from upcals that are from other sources
+ * finalizes the thread state and handles peculiarities of the first
- * such as those generated in thread_userret() itself.
+ * return to userspace for the new thread.
  */
 void
-cpu_set_upcall(struct thread *td, struct thread *td0)
+cpu_copy_thread(struct thread *td, struct thread *td0)
 {
 
 	bcopy(td0->td_frame, td->td_frame, sizeof(struct trapframe));
@@ -170,12 +170,11 @@ cpu_set_upcall(struct thread *td, struct thread *td0)
 }
 
 /*
- * Set that machine state for performing an upcall that has to
+ * Set that machine state for performing an upcall that starts
- * be done in thread_userret() so that those upcalls generated
+ * the entry function with the given argument.
- * in thread_userret() itself can be done as well.
  */
 void
-cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
+cpu_set_upcall(struct thread *td, void (*entry)(void *), void *arg,
 	stack_t *stack)
 {
 	struct trapframe *tf = td->td_frame;
@@ -231,7 +230,7 @@ cpu_thread_clean(struct thread *td)
  * This is needed to make kernel threads stay in kernel mode.
  */
 void
-cpu_set_fork_handler(struct thread *td, void (*func)(void *), void *arg)
+cpu_fork_kthread_handler(struct thread *td, void (*func)(void *), void *arg)
 {
 
 	td->td_pcb->pcb_s[0] = (uintptr_t)func;

sys/sparc64/sparc64/vm_machdep.c

@@ -174,7 +174,7 @@ cpu_set_syscall_retval(struct thread *td, int error)
 }
 
 void
-cpu_set_upcall(struct thread *td, struct thread *td0)
+cpu_copy_thread(struct thread *td, struct thread *td0)
 {
 	struct trapframe *tf;
 	struct frame *fr;
@@ -197,7 +197,7 @@ cpu_set_upcall(struct thread *td, struct thread *td0)
 }
 
 void
-cpu_set_upcall_kse(struct thread *td, void (*entry)(void *), void *arg,
+cpu_set_upcall(struct thread *td, void (*entry)(void *), void *arg,
     stack_t *stack)
 {
 	struct trapframe *tf;
@@ -360,7 +360,7 @@ cpu_reset(void)
  * This is needed to make kernel threads stay in kernel mode.
  */
 void
-cpu_set_fork_handler(struct thread *td, void (*func)(void *), void *arg)
+cpu_fork_kthread_handler(struct thread *td, void (*func)(void *), void *arg)
 {
 	struct frame *fp;
 	struct pcb *pcb;

sys/sys/proc.h

@@ -1005,12 +1005,12 @@ void	userret(struct thread *, struct trapframe *);
 
 void	cpu_exit(struct thread *);
 void	exit1(struct thread *, int, int) __dead2;
+void	cpu_copy_thread(struct thread *td, struct thread *td0);
 int	cpu_fetch_syscall_args(struct thread *td, struct syscall_args *sa);
 void	cpu_fork(struct thread *, struct proc *, struct thread *, int);
-void	cpu_set_fork_handler(struct thread *, void (*)(void *), void *);
+void	cpu_fork_kthread_handler(struct thread *, void (*)(void *), void *);
 void	cpu_set_syscall_retval(struct thread *, int);
-void	cpu_set_upcall(struct thread *td, struct thread *td0);
+void	cpu_set_upcall(struct thread *, void (*)(void *), void *,
-void	cpu_set_upcall_kse(struct thread *, void (*)(void *), void *,
 	    stack_t *);
 int	cpu_set_user_tls(struct thread *, void *tls_base);
 void	cpu_thread_alloc(struct thread *);