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 199