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