sys/sys/msgport.h

   1 /*
   2  * SYS/MSGPORT.H
   3  *
   4  *      Implements LWKT messages and ports.
   5  *
   6  * $DragonFly: src/sys/sys/msgport.h,v 1.26 2007/05/24 20:51:19 dillon Exp $
   7  */
   8
   9 #ifndef _SYS_MSGPORT_H_
  10 #define _SYS_MSGPORT_H_
  11
  12 #ifndef _SYS_QUEUE_H_
  13 #include <sys/queue.h>          /* TAILQ_* macros */
  14 #endif
  15 #ifndef _SYS_STDINT_H_
  16 #include <sys/stdint.h>
  17 #endif
  18 #ifndef _SYS_SPINLOCK_H_
  19 #include <sys/spinlock.h>
  20 #endif
  21
  22 #ifdef _KERNEL
  23
  24 #ifndef _SYS_MALLOC_H_
  25 #include <sys/malloc.h>
  26 #endif
  27
  28 #endif
  29
  30 struct lwkt_msg;
  31 struct lwkt_port;
  32 struct thread;
  33
  34 typedef struct lwkt_msg         *lwkt_msg_t;
  35 typedef struct lwkt_port        *lwkt_port_t;
  36
  37 typedef TAILQ_HEAD(lwkt_msg_queue, lwkt_msg) lwkt_msg_queue;
  38
  39 /*
  40  * The standard message and port structure for communications between
  41  * threads.  See kern/lwkt_msgport.c for documentation on how messages and
  42  * ports work.
  43  *
  44  * A message may only be manipulated by whomever currently owns it,
  45  * which generally means the originating port if the message has
  46  * not been sent yet or has been replied, and the target port if the message
  47  * has been sent and/or is undergoing processing.
  48  *
  49  * NOTE! 64-bit-align this structure.
  50  */
  51 typedef struct lwkt_msg {
  52     TAILQ_ENTRY(lwkt_msg) ms_node;      /* link node */
  53     lwkt_port_t ms_target_port;         /* current target or relay port */
  54     lwkt_port_t ms_reply_port;          /* async replies returned here */
  55     void        (*ms_abortfn)(struct lwkt_msg *);
  56     int         ms_flags;               /* message flags */
  57     int         ms_error;               /* positive error code or 0 */
  58     union {
  59         void    *ms_resultp;            /* misc pointer data or result */
  60         int     ms_result;              /* standard 'int'eger result */
  61         long    ms_lresult;             /* long result */
  62         int     ms_fds[2];              /* two int bit results */
  63         __int32_t ms_result32;          /* 32 bit result */
  64         __int64_t ms_result64;          /* 64 bit result */
  65         __off_t ms_offset;              /* off_t result */
  66     } u;
  67     int         ms_pad[2];              /* future use */
  68 } lwkt_msg;
  69
  70 /*
  71  * Message state flags are manipulated by the current owner only.
  72  *
  73  * DONE         Indicates completion of the reply.  This flag is also set
  74  *              for unsent messages.
  75  *
  76  * REPLY        Indicates message is being replied but may or may not
  77  *              have been queued or returned yet.  This bit is left set
  78  *              when a message is retrieved from a reply port so the caller
  79  *              can distinguish between requests and replies.
  80  *
  81  * QUEUED       Indicates message is queued on reply or target port, or
  82  *              some other port.
  83  *
  84  * SYNC         Indicates that the originator is blocked directly on the
  85  *              message and that the message should be signaled on
  86  *              completion instead of queued.
  87  *
  88  * INTRANSIT    Indicates that the message state is indeterminant (e.g.
  89  *              being passed through an IPI).
  90  *
  91  * ABORTABLE    Static flag indicates that ms_abortfn is valid.
  92  */
  93 #define MSGF_DONE       0x0001          /* message is complete */
  94 #define MSGF_REPLY      0x0002          /* asynch message has been returned */
  95 #define MSGF_QUEUED     0x0004          /* message has been queued sanitychk */
  96 #define MSGF_SYNC       0x0008          /* synchronous message operation */
  97 #define MSGF_INTRANSIT  0x0010          /* in-transit (IPI) */
  98 #define MSGF_ABORTABLE  0x0080          /* message supports abort */
  99
 100 #define MSG_CMD_CDEV    0x00010000
 101 #define MSG_CMD_VFS     0x00020000
 102 #define MSG_CMD_SYSCALL 0x00030000
 103 #define MSG_SUBCMD_MASK 0x0000FFFF
 104
 105 #ifdef _KERNEL
 106 MALLOC_DECLARE(M_LWKTMSG);
 107 #endif
 108
 109 /*
 110  * Notes on port processing requirements:
 111  *
 112  * mp_putport():
 113  *      - may return synchronous error code (error != EASYNC) directly and
 114  *        does not need to check or set MSGF_DONE if so, or set ms_target_port
 115  *      - for asynch procesing should clear MSGF_DONE and set ms_target_port
 116  *        to port prior to initiation of the command.
 117  *
 118  * mp_waitmsg():
 119  *      - wait for a particular message to be returned.
 120  *
 121  * mp_waitport():
 122  *      - wait for a new message on the specified port.
 123  *
 124  * mp_replyport():
 125  *      - reply a message (executed on the originating port to return a
 126  *        message to it).  This can be rather involved if abort is to be
 127  *        supported, see lwkt_default_replyport().  Generally speaking
 128  *        one sets MSGF_DONE.  If MSGF_SYNC is set the message is not
 129  *        queued to the port and the reply code wakes up the waiter
 130  *        directly.
 131  *
 132  * The use of mp_u.td and mp_u.spin is specific to the port callback function
 133  * set.  Default ports are tied to specific threads and use cpu locality
 134  * of reference and mp_u.td (and not mp_u.spin at all).  Descriptor ports
 135  * assume access via descriptors, signal interruption, etc.  Such ports use
 136  * mp_u.spin (and not mp_u.td at all) and may be accessed by multiple threads.
 137  */
 138 typedef struct lwkt_port {
 139     lwkt_msg_queue      mp_msgq;
 140     int                 mp_flags;
 141     union {
 142         struct spinlock spin;
 143         struct thread   *td;
 144         void            *data;
 145     } mp_u;
 146     void *              (*mp_getport)(lwkt_port_t);
 147     int                 (*mp_putport)(lwkt_port_t, lwkt_msg_t);
 148     int                 (*mp_waitmsg)(lwkt_msg_t, int flags);
 149     void *              (*mp_waitport)(lwkt_port_t, int flags);
 150     void                (*mp_replyport)(lwkt_port_t, lwkt_msg_t);
 151 } lwkt_port;
 152
 153 #ifdef _KERNEL
 154
 155 #define mpu_td          mp_u.td
 156 #define mpu_spin        mp_u.spin
 157 #define mpu_data        mp_u.data
 158
 159 #endif
 160
 161 #define MSGPORTF_WAITING        0x0001
 162
 163 /*
 164  * These functions are good for userland as well as the kernel.  The
 165  * messaging function support for userland is provided by the kernel's
 166  * kern/lwkt_msgport.c.  The port functions are provided by userland.
 167  */
 168
 169 void lwkt_initport_thread(lwkt_port_t, struct thread *);
 170 void lwkt_initport_spin(lwkt_port_t);
 171 void lwkt_initport_panic(lwkt_port_t);
 172 void lwkt_initport_replyonly_null(lwkt_port_t);
 173 void lwkt_initport_replyonly(lwkt_port_t,
 174                                 void (*rportfn)(lwkt_port_t, lwkt_msg_t));
 175 void lwkt_initport_putonly(lwkt_port_t,
 176                                 int (*pportfn)(lwkt_port_t, lwkt_msg_t));
 177
 178 void lwkt_sendmsg(lwkt_port_t, lwkt_msg_t);
 179 int lwkt_domsg(lwkt_port_t, lwkt_msg_t, int);
 180 int lwkt_forwardmsg(lwkt_port_t, lwkt_msg_t);
 181 void lwkt_abortmsg(lwkt_msg_t);
 182
 183 #endif