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