From b388e223f27923163179105b76537b0bee840cc1 Mon Sep 17 00:00:00 2001 From: Julian Elischer Date: Mon, 8 Jul 2002 07:34:46 +0000 Subject: [PATCH] Slight changes to reflect some of the changes in -current. mi_switch(9) is still wildly innacurate. I suggest that every kernel developer takes 20 minutes a day for the next few days and updates one or two of his favourite chapter 9 man pages as they are now WAY out of date in general. I will add a couple of KSE related pages soon. --- share/man/man9/mi_switch.9 | 61 +++++++++++++++++++++++++------------- share/man/man9/ucred.9 | 10 +++++++ 2 files changed, 51 insertions(+), 20 deletions(-) diff --git a/share/man/man9/mi_switch.9 b/share/man/man9/mi_switch.9 index f24d47763320..988c02f9b409 100644 --- a/share/man/man9/mi_switch.9 +++ b/share/man/man9/mi_switch.9 @@ -43,7 +43,7 @@ .Nm mi_switch , .Nm cpu_switch , .Nm cpu_throw -.Nd switch to another process context +.Nd switch to another thread context .Sh SYNOPSIS .In sys/param.h .In sys/proc.h @@ -56,20 +56,22 @@ .Sh DESCRIPTION The .Fn mi_switch -function implements the machine independent prelude to a process context +function implements the machine independent prelude to a thread context switch. It is called from only a few distinguished places in the kernel code as a result of the principle of non-preemtable kernel mode execution. -The three major uses of +The various major uses of .Nm can be enumerated as follows: .Bl -enum -offset indent .It from within .Xr sleep 9 -and +, .Xr tsleep 9 -when the current process +and +.Xr msleep 9 +when the current thread voluntarily relinquishes the CPU to wait for some resource to become available. .It @@ -79,7 +81,7 @@ when the kernel prepares a return to user-mode execution. This case is typically handled by machine dependent trap-handling code after detection of a change in the signal disposition of the current process, or when a -higher priority process might be available to run. +higher priority thread might be available to run. The latter event is communicated by the machine independent scheduling routines by calling the machine defined @@ -89,11 +91,20 @@ in the signal handling code (see .Xr issignal 9 ) if a signal is delivered that causes a process to stop. +.It +When a thread dies in +.Xr thread_exit 9 +and control of the processor can be passed to the next runnable thread. +.It +In +.Xr thread_suspend_check 9 +where a thread needs to stop execution due to the suspension state of +the process as a whole. .El .Pp .Fn mi_switch -records the amount of time the current process has been running in the -process structure and checks this value against the CPU time limits +records the amount of time the current thread has been running in the +process structures and checks this value against the CPU time limits allocated to the process (see .Xr getrlimit 2 ) . @@ -102,31 +113,41 @@ Exceeding the soft limit results in a signal to be posted to the process, while exceeding the hard limit will cause a .Dv SIGKILL . +.Pp +If the thread is still in +.Em TDS_RUNNING +state mi_switch will put it back onto the run queue, assuming that +it will want to run again soon. If it is in one of the other +states and KSE threading is enabled, the associated +.Em KSE +will be made available to to any higher priority threads from the same +group, to allow them to be scheduled next. +.Pp After these administrative tasks are done, .Fn mi_switch hands over control to the machine dependent routine .Fn cpu_switch , -which will perform the actual process context switch. +which will perform the actual thread context switch. .Pp .Fn cpu_switch -first saves the context of the current process. +first saves the context of the current thread. Next, it calls -.Fn chooseproc -to determine which process to run next. -Finally, it reads in the saved context of the new process and starts to -execute the new process. +.Fn choosethread +to determine which thread to run next. +Finally, it reads in the saved context of the new thread and starts to +execute the new thread. .Pp .Fn cpu_throw is similar to .Fn cpu_switch -except that it does not save the context of the old process. -This function is useful when the kernel does not have an old process +except that it does not save the context of the old thread. +This function is useful when the kernel does not have an old thread context to save, such as when CPUs other than the boot CPU perform their first task switch, or when the kernel does not care about the state of the -old process, such as in -.Fn cpu_exit -when the kernel terminates the current process and switches into a new -process. +old thread, such as in +.Fn thread_exit +when the kernel terminates the current thread and switches into a new +thread. .Pp To protect the .Xr runqueue 9 , diff --git a/share/man/man9/ucred.9 b/share/man/man9/ucred.9 index aa80cc9d1763..a9526319f332 100644 --- a/share/man/man9/ucred.9 +++ b/share/man/man9/ucred.9 @@ -143,6 +143,16 @@ structure. .Fn crshared returns 0 if the credential has a reference count greater than 1; otherwise, 1 is returned. +.Sh USAGE NOTES +In general in a system call, +you should always use the +.Vt ucred +associated with the +thread doing the work rather than that of the process attached to it, +As that associated with the thread is guaranteed to be safely accessed +under SMP, and will remain stable for the duration of the call, even +in the face of a multithreaded application changing the process credentials +from another thread. .Sh SEE ALSO .Xr uihold 9 .Sh AUTHORS