share/man/man9/mi_switch.9

   1 .\"     $NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls Exp $
   2 .\"
   3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Paul Kranenburg.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
  22 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd November 24, 1996
  33 .Dt MI_SWITCH 9
  34 .Os
  35 .Sh NAME
  36 .Nm mi_switch ,
  37 .Nm cpu_switch ,
  38 .Nm cpu_throw
  39 .Nd switch to another thread context
  40 .Sh SYNOPSIS
  41 .In sys/param.h
  42 .In sys/proc.h
  43 .Ft void
  44 .Fn mi_switch "void"
  45 .Ft void
  46 .Fn cpu_switch "void"
  47 .Ft void
  48 .Fn cpu_throw "void"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn mi_switch
  52 function implements the machine independent prelude to a thread context
  53 switch.
  54 It is called from only a few distinguished places in the kernel
  55 code as a result of the principle of non-preemptable kernel mode execution.
  56 The various major uses of
  57 .Nm
  58 can be enumerated as follows:
  59 .Bl -enum -offset indent
  60 .It
  61 From within a function such as
  62 .Xr cv_wait 9 ,
  63 .Xr mtx_lock 9 ,
  64 or
  65 .Xr tsleep 9
  66 when the current thread
  67 voluntarily relinquishes the CPU to wait for some resource or lock to become
  68 available.
  69 .It
  70 After handling a trap
  71 (e.g.\& a system call, device interrupt)
  72 when the kernel prepares a return to user-mode execution.
  73 This case is
  74 typically handled by machine dependent trap-handling code after detection
  75 of a change in the signal disposition of the current process, or when a
  76 higher priority thread might be available to run.
  77 The latter event is
  78 communicated by the machine independent scheduling routines by calling
  79 the machine defined
  80 .Fn need_resched .
  81 .It
  82 In the signal handling code
  83 (see
  84 .Xr issignal 9 )
  85 if a signal is delivered that causes a process to stop.
  86 .It
  87 When a thread dies in
  88 .Xr thread_exit 9
  89 and control of the processor can be passed to the next runnable thread.
  90 .It
  91 In
  92 .Xr thread_suspend_check 9
  93 where a thread needs to stop execution due to the suspension state of
  94 the process as a whole.
  95 .El
  96 .Pp
  97 .Fn mi_switch
  98 records the amount of time the current thread has been running in the
  99 process structures and checks this value against the CPU time limits
 100 allocated to the process
 101 (see
 102 .Xr getrlimit 2 ) .
 103 Exceeding the soft limit results in a
 104 .Dv SIGXCPU
 105 signal to be posted to the process, while exceeding the hard limit will
 106 cause a
 107 .Dv SIGKILL .
 108 .Pp
 109 If the thread is still in the
 110 .Dv TDS_RUNNING
 111 state,
 112 .Fn mi_switch
 113 will put it back onto the run queue, assuming that
 114 it will want to run again soon.
 115 If it is in one of the other
 116 states and KSE threading is enabled, the associated
 117 .Em KSE
 118 will be made available to any higher priority threads from the same
 119 group, to allow them to be scheduled next.
 120 .Pp
 121 After these administrative tasks are done,
 122 .Fn mi_switch
 123 hands over control to the machine dependent routine
 124 .Fn cpu_switch ,
 125 which will perform the actual thread context switch.
 126 .Pp
 127 .Fn cpu_switch
 128 first saves the context of the current thread.
 129 Next, it calls
 130 .Fn choosethread
 131 to determine which thread to run next.
 132 Finally, it reads in the saved context of the new thread and starts to
 133 execute the new thread.
 134 .Pp
 135 .Fn cpu_throw
 136 is similar to
 137 .Fn cpu_switch
 138 except that it does not save the context of the old thread.
 139 This function is useful when the kernel does not have an old thread
 140 context to save, such as when CPUs other than the boot CPU perform their
 141 first task switch, or when the kernel does not care about the state of the
 142 old thread, such as in
 143 .Fn thread_exit
 144 when the kernel terminates the current thread and switches into a new
 145 thread.
 146 .Pp
 147 To protect the
 148 .Xr runqueue 9 ,
 149 all of these functions must be called with the
 150 .Va sched_lock
 151 mutex held.
 152 .Sh SEE ALSO
 153 .Xr cv_wait 9 ,
 154 .Xr issignal 9 ,
 155 .Xr mutex 9 ,
 156 .Xr runqueue 9 ,
 157 .Xr tsleep 9 ,
 158 .Xr wakeup 9