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 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"        This product includes software developed by the NetBSD
  20 .\"        Foundation, Inc. and its contributors.
  21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  22 .\"    contributors may be used to endorse or promote products derived
  23 .\"    from this software without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  28 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
  29 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  35 .\" POSSIBILITY OF SUCH DAMAGE.
  36 .\"
  37 .\" $FreeBSD$
  38 .\"
  39 .Dd November 24, 1996
  40 .Dt MI_SWITCH 9
  41 .Os
  42 .Sh NAME
  43 .Nm mi_switch ,
  44 .Nm cpu_switch ,
  45 .Nm cpu_throw
  46 .Nd switch to another process context
  47 .Sh SYNOPSIS
  48 .Fd #include <sys/param.h>
  49 .Fd #include <sys/proc.h>
  50 .Ft void
  51 .Fn mi_switch "void"
  52 .Ft void
  53 .Fn cpu_switch "void"
  54 .Ft void
  55 .Fn cpu_throw "void"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn mi_switch
  59 function implements the machine independent prelude to a process context
  60 switch.
  61 It is called from only a few distinguished places in the kernel
  62 code as a result of the principle of non-preemtable kernel mode execution.
  63 The three major uses of
  64 .Nm
  65 can be enumerated as follows:
  66 .Bl -enum -offset indent
  67 .It
  68 from within
  69 .Xr sleep 9
  70 and
  71 .Xr tsleep 9
  72 when the current process
  73 voluntarily relinquishes the CPU to wait for some resource to become
  74 available.
  75 .It
  76 after handling a trap
  77 (e.g. a system call, device interrupt)
  78 when the kernel prepares a return to user-mode execution.
  79 This case is
  80 typically handled by machine dependent trap-handling code after detection
  81 of a change in the signal disposition of the current process, or when a
  82 higher priority process might be available to run.
  83 The latter event is
  84 communicated by the machine independent scheduling routines by calling
  85 the machine defined
  86 .Fn need_resched .
  87 .It
  88 in the signal handling code
  89 (see
  90 .Xr issignal 9 )
  91 if a signal is delivered that causes a process to stop.
  92 .El
  93 .Pp
  94 .Fn mi_switch
  95 records the amount of time the current process has been running in the
  96 process structure and checks this value against the CPU time limits
  97 allocated to the process
  98 (see
  99 .Xr getrlimit 2 ) .
 100 Exceeding the soft limit results in a
 101 .Dv SIGXCPU
 102 signal to be posted to the process, while exceeding the hard limit will
 103 cause a
 104 .Dv SIGKILL .
 105 After these administrative tasks are done,
 106 .Fn mi_switch
 107 hands over control to the machine dependent routine
 108 .Fn cpu_switch ,
 109 which will perform the actual process context switch.
 110 .Pp
 111 .Fn cpu_switch
 112 first saves the context of the current process.
 113 Next, it calls
 114 .Fn chooseproc
 115 to determine which process to run next.
 116 Finally, it reads in the saved context of the new process and starts to
 117 execute the new process.
 118 .Pp
 119 .Fn cpu_throw
 120 is similar to
 121 .Fn cpu_switch
 122 except that it does not save the context of the old process.
 123 This function is useful when the kernel does not have an old process
 124 context to save, such as when CPUs other than the boot CPU perform their
 125 first task switch, or when the kernel does not care about the state of the
 126 old process, such as in
 127 .Fn cpu_exit
 128 when the kernel terminates the current process and switches into a new
 129 process.
 130 .Pp
 131 To protect the
 132 .Xr runqueue 9 ,
 133 all of these functions must be called with the
 134 .Va sched_lock
 135 mutex held.
 136 .Sh SEE ALSO
 137 .Xr issignal 9 ,
 138 .Xr mutex 9 ,
 139 .Xr runqueue 9 ,
 140 .Xr tsleep 9 ,
 141 .Xr wakeup 9