Return to v_sleep CVS log

Up to [MW Coherent from dump] / coherent / f / usr / man / KERNEL

Annotation of coherent/f/usr/man/KERNEL/v_sleep, revision 1.1

1.1     ! root        1: vv_sslleeeepp() -- Accessible Kernel Routine
        !             2: 
        !             3: #iinncclluuddee <ssyyss/sscchheedd.hh>
        !             4: vvooiidd
        !             5: vv_sslleeeepp(_e, _c_v, _i_v, _s_v, _s_t_r)
        !             6: cchhaarr *_e;
        !             7: iinntt _c_v, _i_v, _s_v;
        !             8: cchhaarr *_s_t_r;
        !             9: 
        !            10: vv_sslleeeepp() suspends processing of a  process until event _e has completed.  _e
        !            11: normally represents a data item's address in the static kernel data space.
        !            12: 
        !            13: _s_t_r  is a  human readable  event name  displayed by command  ppss. _c_v  is the
        !            14: scheduling value set  to obtain the CPU as soon  as the process awakes.  _i_v
        !            15: is the swap  value obtained to keep the process  in memory for the duration
        !            16: of the sleep.   _s_v is the swap value that  allows the process to be swapped
        !            17: in if  it has  been swapped  out.  The following  table gives  the manifest
        !            18: constants to use with _c_v, _i_v, and _s_v for normal processing tasks, as set in
        !            19: the header file <ssyyss/sscchheedd.hh>:
        !            20: 
        !            21: Child Process            CCVVCCHHIILLDD   IIVVCCHHIILLDD   SSVVCCHHIILLDD
        !            22: Swapper                  CCVVSSWWAAPP    IIVVSSWWAAPP    SSVVSSWWAAPP
        !            23: Wait for Block I/O to Complete     CCVVBBLLKKIIOO   IIVVBBLLKKIIOOSSVVBBLLKKIIOO
        !            24: Wait for Gate to Open    CCVVGGAATTEE    IIVVGGAATTEE    SSVVGGAATTEE
        !            25: Terminal Output          CCVVTTTTOOUUTT   IIVVTTTTOOUUTT   SSVVTTTTOOUUTT
        !            26: Wait for Free clists     CCVVCCLLIISSTT   IIVVCCLLIISSTT   SSVVCCLLIISSTT
        !            27: Process Trace            CCVVPPTTSSEETT   IIVVPPTTSSEETT   SSVVPPTTSSEETT
        !            28: Process Trace Stop       CCVVPPTTRREETT   IIVVPPTTRREETT   SSVVPPTTRREETT
        !            29: Waiting for a Pipe       CCVVPPIIPPEE    IIVVPPIIPPEE    SSVVPPIIPPEE
        !            30: Terminal Input           CCVVTTTTIINN    IIVVTTTTIINN    SSVVTTTTIINN
        !            31: Pause                    CCVVPPAAUUSSEE   IIVVPPAAUUSSEE   SSVVPPAAUUSSEE
        !            32: Wait                     CCVVWWAAIITT    IIVVWWAAIITT    SSVVWWAAIITT
        !            33: 
        !            34: If _c_v  is less  than _C_V_N_O_S_I_G,  then signals may  abort the  process without
        !            35: returning from the sleep.
        !            36: 
        !            37: Please note  the following caveats  when using vv_sslleeeepp().  Disobeying these
        !            38: rules can jeopardize the health of your system.
        !            39: 
        !            40: First, your  driver can vv_sslleeeepp() while  it waits for some  condition to be
        !            41: satisfied.  However,  the vv_sslleeeepp() may return  prematurely; therefore, you
        !            42: must place  the call to vv_sslleeeepp()  within a loop and  check for the initial
        !            43: condition  to  still be  valid.   Normally,  a sleep  is  performed in  the
        !            44: following manner:
        !            45: 
        !            46:     set interrupt priority to keep out the gremlins
        !            47:     while (work is not yet completed)
        !            48:         v_sleep( &some_variable_in_the_kernel_data_area, ... )
        !            49:     restore interrupt mask
        !            50: 
        !            51: The  interrupt routine  will, in  turn, call wwaakkeeuupp()  or defer  wakeup for
        !            52: later background processing  if time is not an issue.   This will cause the
        !            53: aforementioned code to return from the call to vv_sslleeeepp().
        !            54: 
        !            55: As you can  see, there is an inherent race  condition between the wwhhiillee and
        !            56: vv_sslleeeepp(). If  the work is  serviced while the driver  is vv_sslleeeepp()ing, the
        !            57: wwhhiillee loop will work  correctly.  However, should the last interrupt happen
        !            58: after the  wwhhiillee but before the  vv_sslleeeepp(), the driver will  deadlock -- it
        !            59: will, in effect, be waiting for Godot.
        !            60: 
        !            61: vv_sslleeeepp() returns  for various reasons, but you cannot  always depend on it
        !            62: to return for reasons other than a process calling wwaakkeeuupp() on the variable
        !            63: that  your driver  fell  asleep on.   So,  if your  driver  is waiting  for
        !            64: something to happen based upon an interrupt, be sure to bracket the call to
        !            65: vv_sslleeeepp() with calls to the kernel routines sspphhii() and ssppll().
        !            66: 
        !            67: _S_e_e _A_l_s_o
        !            68: aacccceessssiibbllee kkeerrnneell rroouuttiinneess, sspphhii(), ssppll(), wwaakkeeuupp()
        !            69: 
        !            70: _N_o_t_e_s
        !            71: Please note the following warnings:
        !            72: 
        !            73: ->   Do not  call vv_sslleeeepp(), either directly or  indirectly, from the block
        !            74:      routine of a driver.
        !            75: 
        !            76: ->   Do not  call vv_sslleeeepp(),  either directly  or indirectly, from  with an
        !            77:      interrupt  handler.  When  the interrupt occurs,  the driver  does not
        !            78:      know which  process was running  at the time,  so it does  not whose _u
        !            79:      _a_r_e_a it  will be sleeping on.  Thus, calling  vv_sslleeeepp() from within an
        !            80:      interrupt handler will deadlock your driver.
        !            81: 
        !            82: ->   Calling  vv_sslleeeepp() from  the load  routine of a  driver linked  to the
        !            83:      kernel will cause a panic.
        !            84: 
        !            85: ->   Always check for signals while sleeping.  Failure to do so will result
        !            86:      in user  processes which cannot be terminated  due to an uncooperative
        !            87:      device driver.   For example, the following code  fragment can be used
        !            88:      in a blocking  driver _x_xooppeenn() routine to allow the  user to break out
        !            89:      of a sleep by hitting the interrupt character on the keyboard.
        !            90: 
        !            91:          if (SELF->p_ssig && nondsig()) {  /* received a signal? */
        !            92:              u.u_error = EINTR;    /* indicate that we were interrupted */
        !            93:              return;           /* return to user process */
        !            94:          }

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.