sys/sys/msgport.h

   1 /*
   2  * SYS/MSGPORT.H
   3  *
   4  *      Implements LWKT messages and ports.
   5  */
   6
   7 #ifndef _SYS_MSGPORT_H_
   8 #define _SYS_MSGPORT_H_
   9
  10 #ifndef _SYS_QUEUE_H_
  11 #include <sys/queue.h>          /* TAILQ_* macros */
  12 #endif
  13 #ifndef _SYS_SPINLOCK_H_
  14 #include <sys/spinlock.h>
  15 #endif
  16 #include <machine/stdint.h>
  17
  18 struct lwkt_msg;
  19 struct lwkt_port;
  20 struct lwkt_serialize;
  21 struct thread;
  22
  23 typedef struct lwkt_msg         *lwkt_msg_t;
  24 typedef struct lwkt_port        *lwkt_port_t;
  25
  26 typedef TAILQ_HEAD(lwkt_msg_queue, lwkt_msg) lwkt_msg_queue;
  27
  28 /*
  29  * The standard message and port structure for communications between
  30  * threads.  See kern/lwkt_msgport.c for documentation on how messages and
  31  * ports work.
  32  *
  33  * A message may only be manipulated by whomever currently owns it,
  34  * which generally means the originating port if the message has
  35  * not been sent yet or has been replied, and the target port if the message
  36  * has been sent and/or is undergoing processing.
  37  *
  38  * NOTE! 64-bit-align this structure.
  39  */
  40 typedef struct lwkt_msg {
  41     TAILQ_ENTRY(lwkt_msg) ms_node;      /* link node */
  42     lwkt_port_t ms_target_port;         /* current target or relay port */
  43     lwkt_port_t ms_reply_port;          /* async replies returned here */
  44     void        (*ms_abortfn)(struct lwkt_msg *);
  45     int         ms_flags;               /* message flags */
  46     int         ms_error;               /* positive error code or 0 */
  47     union {
  48         void    *ms_resultp;            /* misc pointer data or result */
  49         int     ms_result;              /* standard 'int'eger result */
  50         long    ms_lresult;             /* long result */
  51         int     ms_fds[2];              /* two int bit results */
  52         __int32_t ms_result32;          /* 32 bit result */
  53         __int64_t ms_result64;          /* 64 bit result */
  54         __off_t ms_offset;              /* off_t result */
  55     } u;
  56     void        (*ms_receiptfn)(struct lwkt_msg *, lwkt_port_t);
  57 } lwkt_msg;
  58
  59 /*
  60  * Message state flags are manipulated by the current owner only.
  61  *
  62  * DONE         Indicates completion of the reply.  This flag is also set
  63  *              for unsent messages.
  64  *
  65  * REPLY        Indicates message is being replied but may or may not
  66  *              have been queued or returned yet.  This bit is left set
  67  *              when a message is retrieved from a reply port so the caller
  68  *              can distinguish between requests and replies.
  69  *
  70  * QUEUED       Indicates message is queued on reply or target port, or
  71  *              some other port.
  72  *
  73  * SYNC         Indicates that the originator is blocked directly on the
  74  *              message and that the message should be signaled on
  75  *              completion instead of queued.
  76  *
  77  * INTRANSIT    Indicates that the message state is indeterminant (e.g.
  78  *              being passed through an IPI).
  79  *
  80  * ABORTABLE    Static flag indicates that ms_abortfn is valid.
  81  *
  82  * High 16 bits are available to message handlers.
  83  */
  84 #define MSGF_DONE       0x0001          /* message is complete */
  85 #define MSGF_REPLY      0x0002          /* asynch message has been returned */
  86 #define MSGF_QUEUED     0x0004          /* message has been queued sanitychk */
  87 #define MSGF_SYNC       0x0008          /* synchronous message operation */
  88 #define MSGF_INTRANSIT  0x0010          /* in-transit (IPI) */
  89 #define MSGF_WAITING    0x0020          /* MSGF_SYNC being waited upon */
  90 #define MSGF_DROPABLE   0x0040          /* message supports drop */
  91 #define MSGF_ABORTABLE  0x0080          /* message supports abort */
  92 #define MSGF_PRIORITY   0x0100          /* priority message */
  93 #define MSGF_RECEIPT    0x0200          /* need receipt after put done */
  94
  95 #define MSGF_USER0      0x00010000
  96 #define MSGF_USER1      0x00020000
  97 #define MSGF_USER2      0x00040000
  98 #define MSGF_USER3      0x00080000
  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 /*
 106  * Notes on port processing requirements:
 107  *
 108  * mp_putport():
 109  *      - may return synchronous error code (error != EASYNC) directly and
 110  *        does not need to check or set MSGF_DONE if so, or set ms_target_port
 111  *      - for asynch procesing should clear MSGF_DONE and set ms_target_port
 112  *        to port prior to initiation of the command.
 113  *
 114  * mp_waitmsg():
 115  *      - wait for a particular message to be returned.
 116  *
 117  * mp_waitport():
 118  *      - wait for a new message on the specified port.
 119  *
 120  * mp_replyport():
 121  *      - reply a message (executed on the originating port to return a
 122  *        message to it).  This can be rather involved if abort is to be
 123  *        supported, see lwkt_default_replyport().  Generally speaking
 124  *        one sets MSGF_DONE and MSGF_REPLY.  If MSGF_SYNC is set the message
 125  *        is not queued to the port and the reply code wakes up the waiter
 126  *        directly.
 127  *
 128  * mp_dropmsg():
 129  *      - drop a specific message from the specified port.  Currently only
 130  *        threads' embedded ports (thread ports or spin ports) support this
 131  *        function and must be used in the port's owner thread.
 132  *        (returns 0 on success, ENOENT on error).
 133  *
 134  * The use of mpu_td and mp_u.spin is specific to the port callback function
 135  * set.  Default ports are tied to specific threads and use cpu locality
 136  * of reference and mpu_td (and not mp_u.spin at all).  Descriptor ports
 137  * assume access via descriptors, signal interruption, etc.  Such ports use
 138  * mp_u.spin (and not mpu_td at all) and may be accessed by multiple threads.
 139  *
 140  * Threads' embedded ports always have mpu_td back pointing to themselves.
 141  */
 142 typedef struct lwkt_port {
 143     lwkt_msg_queue      mp_msgq;
 144     lwkt_msg_queue      mp_msgq_prio;
 145     int                 mp_flags;
 146     int                 mp_cpuid;
 147     union {
 148         struct spinlock spin;
 149         struct lwkt_serialize *serialize;
 150         void            *data;
 151     } mp_u;
 152     struct thread       *mpu_td;
 153     void *              (*mp_getport)(lwkt_port_t);
 154     int                 (*mp_putport)(lwkt_port_t, lwkt_msg_t);
 155     int                 (*mp_waitmsg)(lwkt_msg_t, int flags);
 156     void *              (*mp_waitport)(lwkt_port_t, int flags);
 157     void                (*mp_replyport)(lwkt_port_t, lwkt_msg_t);
 158     int                 (*mp_dropmsg)(lwkt_port_t, lwkt_msg_t);
 159     int                 (*mp_putport_oncpu)(lwkt_port_t, lwkt_msg_t);
 160 } lwkt_port;
 161
 162 #ifdef _KERNEL
 163
 164 #include <sys/types.h>  /* for boolean_t */
 165
 166 #define mpu_spin        mp_u.spin
 167 #define mpu_serialize   mp_u.serialize
 168 #define mpu_data        mp_u.data
 169
 170 /*
 171  * Port state flags.
 172  *
 173  * WAITING      The owner of the port is descheduled waiting for a message
 174  *              to be replied.  In case this a spin port there can actually
 175  *              be more than one thread waiting on the port.
 176  */
 177 #define MSGPORTF_WAITING        0x0001
 178
 179 /*
 180  * These functions are good for userland as well as the kernel.  The
 181  * messaging function support for userland is provided by the kernel's
 182  * kern/lwkt_msgport.c.  The port functions are provided by userland.
 183  */
 184
 185 void lwkt_initport_thread(lwkt_port_t, struct thread *);
 186 void lwkt_initport_spin(lwkt_port_t, struct thread *, boolean_t);
 187 void lwkt_initport_serialize(lwkt_port_t, struct lwkt_serialize *);
 188 void lwkt_initport_panic(lwkt_port_t);
 189 void lwkt_initport_replyonly_null(lwkt_port_t);
 190 void lwkt_initport_replyonly(lwkt_port_t,
 191                                 void (*rportfn)(lwkt_port_t, lwkt_msg_t));
 192 void lwkt_initport_putonly(lwkt_port_t,
 193                                 int (*pportfn)(lwkt_port_t, lwkt_msg_t));
 194
 195 void lwkt_sendmsg(lwkt_port_t, lwkt_msg_t);
 196 void lwkt_sendmsg_oncpu(lwkt_port_t, lwkt_msg_t);
 197 void lwkt_sendmsg_prepare(lwkt_port_t, lwkt_msg_t);
 198 void lwkt_sendmsg_start(lwkt_port_t, lwkt_msg_t);
 199 void lwkt_sendmsg_start_oncpu(lwkt_port_t, lwkt_msg_t);
 200 int lwkt_domsg(lwkt_port_t, lwkt_msg_t, int);
 201 int lwkt_forwardmsg(lwkt_port_t, lwkt_msg_t);
 202 void lwkt_abortmsg(lwkt_msg_t);
 203
 204 #endif /* _KERNEL */
 205
 206 #endif