share/man/man9/cpu_switchto.9

   1 .\"     $NetBSD: cpu_switchto.9,v 1.9 2008/01/24 23:06:10 ad Exp $
   2 .\"
   3 .\" Copyright (c)2007 YAMAMOTO Takashi,
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" ------------------------------------------------------------
  28 .Dd May 21, 2007
  29 .Dt CPU_SWITCHTO 9
  30 .Os
  31 .\" ------------------------------------------------------------
  32 .Sh NAME
  33 .Nm cpu_switchto
  34 .Nd machine-dependent LWP context switching interface
  35 .\" ------------------------------------------------------------
  36 .Sh SYNOPSIS
  37 .In sys/cpu.h
  38 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  39 .Ft lwp_t *
  40 .Fn cpu_switchto \
  41 "lwp_t *oldlwp" "lwp_t *newlwp" "bool returning"
  42 .\" ------------------------------------------------------------
  43 .Sh DESCRIPTION
  44 .Fn cpu_switchto
  45 saves the context of the LWP which is currently running on the processor,
  46 and restores the context of the LWP specified by
  47 .Fa newlwp .
  48 .Pp
  49 .Fn cpu_switchto
  50 doesn't switch address spaces.
  51 .Pp
  52 .Fn cpu_switchto
  53 sets
  54 .Dv curlwp
  55 to
  56 .Fa newlwp .
  57 .Pp
  58 .Fn cpu_switchto
  59 should be called at
  60 .Dv IPL_SCHED .
  61 When
  62 .Fn cpu_switchto
  63 returns, the caller should lower the priority level as soon as possible.
  64 .Pp
  65 .Fn cpu_switchto
  66 might be called with spin mutexes held.
  67 .Pp
  68 It takes the following arguments.
  69 .Bl -tag -width oldlwp
  70 .It Fa oldlwp
  71 Specify the lwp from which we are going to switch, i.e.,
  72 the calling LWP.
  73 If it was
  74 .Dv NULL ,
  75 the context of the LWP currently running on this processor is not saved.
  76 .It Fa newlwp
  77 Specify the lwp to which we are going to switch.
  78 It must not be
  79 .Dv NULL .
  80 .It Fa returning
  81 Only meaningful if the architecture implements fast software interrupts.
  82 If true, it indicates that
  83 .Fa oldlwp
  84 is a soft interrupt LWP that is blocking.
  85 It's a good indication that any kind of address space or user activity
  86 can be completely ignored.
  87 For example:
  88 .Fn ras_lookup ,
  89 cache flushes, TLB wirings, adjusting lazy FPU
  90 state.
  91 All that is required is to restore the register state and stack, and
  92 return to the interrupted LWP.
  93 .El
  94 .\" ------------------------------------------------------------
  95 .Sh RETURN VALUES
  96 .Fn cpu_switchto
  97 does not return until another LWP calls
  98 .Fn cpu_switchto
  99 to switch to us.
 100 It returns the
 101 .Dv oldlwp
 102 argument of the
 103 .Fn cpu_switchto
 104 which is called to switch back to our LWP.
 105 It's either an LWP which called
 106 .Fa cpu_switchto
 107 to switch to us or
 108 .Dv NULL
 109 in the case that the LWP was exiting.
 110 .\" ------------------------------------------------------------
 111 .Sh SEE ALSO
 112 .Xr swapcontext 3 ,
 113 .Xr intro 9 ,
 114 .Xr mutex 9 ,
 115 .Xr spl 9