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.22 2006/05/20 06:32:41 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
  19 #ifdef _KERNEL
  20
  21 #ifndef _SYS_MALLOC_H_
  22 #include <sys/malloc.h>
  23 #endif
  24
  25 #endif
  26
  27 struct lwkt_msg;
  28 struct lwkt_port;
  29 struct thread;
  30
  31 typedef struct lwkt_msg         *lwkt_msg_t;
  32 typedef struct lwkt_port        *lwkt_port_t;
  33
  34 typedef TAILQ_HEAD(lwkt_msg_queue, lwkt_msg) lwkt_msg_queue;
  35
  36 /*
  37  * LWKT command message operator type.  This type holds a message's
  38  * 'command'.  The command format is opaque to the LWKT messaging system,
  39  * meaning that it is specific to whatever convention the API chooses.
  40  * By convention lwkt_cmd_t is passed by value and is expected to
  41  * efficiently fit into a machine register.
  42  */
  43 typedef union lwkt_cmd {
  44     int         cm_op;
  45     int         (*cm_func)(lwkt_msg_t msg);
  46 } lwkt_cmd_t;
  47
  48 /*
  49  * The standard message and port structure for communications between
  50  * threads.  See kern/lwkt_msgport.c for documentation on how messages and
  51  * ports work.
  52  *
  53  * For the most part a message may only be manipulated by whomever currently
  54  * owns it, which generally means the originating port if the message has
  55  * not been sent yet or has been replied, and the target port if the message
  56  * has been sent and/or is undergoing processing.
  57  *
  58  * The one exception to this rule is an abort.  Aborts must be initiated
  59  * by the originator and may 'chase' the target (especially if a message
  60  * is being forwarded), potentially even 'chase' the message all the way
  61  * back to the originator if it races against the target replying the
  62  * message.  The ms_abort_port field is the only field that may be modified
  63  * by the originator or intermediate target (when the abort is chasing
  64  * a forwarding or reply op).  An abort may cause a reply to be delayed
  65  * until the abort catches up to it.
  66  *
  67  * Messages which support an abort will have MSGF_ABORTABLE set, indicating
  68  * that the ms_abort field has been initialized.  An abort will cause a
  69  * message to be requeued to the target port so the target sees the same
  70  * message twice:  once during initial processing of the message, and a
  71  * second time to process the abort request.  lwkt_getport() will detect
  72  * the requeued abort and will copy ms_abort into ms_cmd before returning
  73  * the requeued message the second time.  This makes target processing a
  74  * whole lot less complex.
  75  *
  76  * NOTE! 64-bit-align this structure.
  77  */
  78 typedef struct lwkt_msg {
  79     TAILQ_ENTRY(lwkt_msg) ms_node;      /* link node */
  80     union {
  81         struct lwkt_msg *ms_next;       /* chaining / cache */
  82         union sysunion  *ms_sysunnext;  /* chaining / cache */
  83         struct lwkt_msg *ms_umsg;       /* user message (UVA address) */
  84     } opaque;
  85     lwkt_port_t ms_target_port;         /* current target or relay port */
  86     lwkt_port_t ms_reply_port;          /* async replies returned here */
  87     lwkt_port_t ms_abort_port;          /* abort chasing port */
  88     lwkt_cmd_t  ms_cmd;                 /* message command operator */
  89     lwkt_cmd_t  ms_abort;               /* message abort operator */
  90     int         ms_flags;               /* message flags */
  91 #define ms_copyout_start        ms_msgsize
  92     int         ms_msgsize;             /* size of message */
  93     int         ms_error;               /* positive error code or 0 */
  94     union {
  95         void    *ms_resultp;            /* misc pointer data or result */
  96         int     ms_result;              /* standard 'int'eger result */
  97         long    ms_lresult;             /* long result */
  98         int     ms_fds[2];              /* two int bit results */
  99         __int32_t ms_result32;          /* 32 bit result */
 100         __int64_t ms_result64;          /* 64 bit result */
 101         __off_t ms_offset;              /* off_t result */
 102     } u;
 103 #define ms_copyout_end  ms_pad[0]
 104     int         ms_pad[2];              /* future use */
 105 } lwkt_msg;
 106
 107 #define ms_copyout_size (offsetof(struct lwkt_msg, ms_copyout_end) - offsetof(struct lwkt_msg, ms_copyout_start))
 108
 109 #define MSGF_DONE       0x0001          /* asynch message is complete */
 110 #define MSGF_REPLY1     0x0002          /* asynch message has been returned */
 111 #define MSGF_QUEUED     0x0004          /* message has been queued sanitychk */
 112 #define MSGF_ASYNC      0x0008          /* sync/async hint */
 113 #define MSGF_ABORTED    0x0010          /* indicate pending abort */
 114 #define MSGF_PCATCH     0x0020          /* catch proc signal while waiting */
 115 #define MSGF_REPLY2     0x0040          /* reply processed by rport cpu */
 116 #define MSGF_ABORTABLE  0x0080          /* message supports abort */
 117 #define MSGF_RETRIEVED  0x0100          /* message retrieved on target */
 118
 119 #define MSG_CMD_CDEV    0x00010000
 120 #define MSG_CMD_VFS     0x00020000
 121 #define MSG_CMD_SYSCALL 0x00030000
 122 #define MSG_SUBCMD_MASK 0x0000FFFF
 123
 124 #ifdef _KERNEL
 125 MALLOC_DECLARE(M_LWKTMSG);
 126 #endif
 127
 128 /*
 129  * Notes on port processing requirements:
 130  *
 131  * mp_putport():
 132  *      - may return synchronous error code (error != EASYNC) directly and
 133  *        does not need to check or set MSGF_DONE if so, or set ms_target_port
 134  *      - for asynch procesing should clear MSGF_DONE and set ms_target_port
 135  *        to port prior to initiation of the command.
 136  *
 137  * mp_waitport():
 138  *      - if the passed msg is NULL we wait for, remove, and return the
 139  *        next pending message on the port.
 140  *      - if the passed msg is non-NULL we wait for that particular message,
 141  *        which typically involves waiting until MSGF_DONE is set then
 142  *        pulling the message off the port if MSGF_QUEUED is set and
 143  *        returning it.  If MSGF_PCATCH is set in the message we allow
 144  *        a signal to interrupt and abort the message.
 145  *
 146  * mp_replyport():
 147  *      - reply a message (executed on the originating port to return a
 148  *        message to it).  This can be rather involved if abort is to be
 149  *        supported, see lwkt_default_replyport().  Generally speaking
 150  *        one sets MSGF_DONE.  If MSGF_ASYNC is set the message is queued
 151  *        to the port, else the port's thread is scheduled.
 152  *
 153  * mp_abortport():
 154  *      - abort a message.  The mp_abortport function for the message's
 155  *        ms_target_port is called.  ms_target_port is basically where
 156  *        the message was sent to or last forwarded to.  Aborting a message
 157  *        can be rather involved.  Note that the lwkt_getmsg() code ensures
 158  *        that a message is returned non-abort before it is returned again
 159  *        with its ms_cmd set to ms_abort, even if the abort occurs before
 160  *        the initial retrieval of the message.  The setting of ms_cmd to
 161  *        ms_abort is NOT handled by mp_abortport().  mp_abortport() is
 162  *        basically responsible for requeueing the message to the target
 163  *        port and setting the MSGF_ABORTED flag.
 164  *
 165  */
 166 typedef struct lwkt_port {
 167     lwkt_msg_queue      mp_msgq;
 168     int                 mp_flags;
 169     int                 mp_unused01;
 170     struct thread       *mp_td;
 171     int                 (*mp_putport)(lwkt_port_t, lwkt_msg_t);
 172     void *              (*mp_waitport)(lwkt_port_t, lwkt_msg_t);
 173     void                (*mp_replyport)(lwkt_port_t, lwkt_msg_t);
 174     void                (*mp_abortport)(lwkt_port_t, lwkt_msg_t);
 175 } lwkt_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 void lwkt_initport(lwkt_port_t, struct thread *);
 185 void lwkt_initport_null_rport(lwkt_port_t, struct thread *);
 186 void lwkt_sendmsg(lwkt_port_t, lwkt_msg_t);
 187 int lwkt_domsg(lwkt_port_t, lwkt_msg_t);
 188 int lwkt_forwardmsg(lwkt_port_t, lwkt_msg_t);
 189 void lwkt_abortmsg(lwkt_msg_t);
 190 void *lwkt_getport(lwkt_port_t);
 191
 192 int lwkt_default_putport(lwkt_port_t port, lwkt_msg_t msg);
 193 void *lwkt_default_waitport(lwkt_port_t port, lwkt_msg_t msg);
 194 void lwkt_default_replyport(lwkt_port_t port, lwkt_msg_t msg);
 195 void lwkt_default_abortport(lwkt_port_t port, lwkt_msg_t msg);
 196 void lwkt_null_replyport(lwkt_port_t port, lwkt_msg_t msg);
 197
 198 #endif