2 * Copyright (c) 2004-2007 The DragonFly Project. All rights reserved.
4 * This code is derived from software contributed to The DragonFly Project
5 * by Matthew Dillon <dillon@backplane.com>
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * 1. Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
17 * 3. Neither the name of The DragonFly Project nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific, prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 * INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
31 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 * The syslink infrastructure implements an optimized RPC mechanism across a
36 * communications link. Endpoints, defined by a session sysid, are typically
37 * associated with system structures but do not have to be.
39 * This header file is primarily responsible for the formatting of message
40 * traffic over a syslink.
43 #ifndef _SYS_SYSLINK_MSG_H_
44 #define _SYS_SYSLINK_MSG_H_
47 #include <sys/types.h>
49 #include <machine/atomic.h>
51 typedef int32_t sl_auxdata_t; /* auxillary data element */
52 typedef u_int32_t sl_rlabel_t; /* reply label routing id */
53 typedef u_int16_t sl_proto_t; /* protocol control field */
54 typedef u_int16_t sl_cmd_t; /* command/status id */
55 typedef u_int16_t sl_reclen_t; /* item length */
57 #define SL_ALIGN 8 /* 8-byte alignment */
58 #define SL_ALIGNMASK (SL_ALIGN - 1)
61 * SYSLINK_ELM - structured data element.
63 * syslink_msg's have zero or more syslink_elm's arranged as an array.
64 * Each syslink_elm may represent opaque data or recursively structured
67 * SE_CMD field - identify RPC command (at the top level) or RPC data element
68 * in deeper recursions.
70 * Please note that while bits have individual meanings, command switches
71 * should universally compare all 16 bits against the command. This
72 * guarentees that commands will not be misinterpreted (e.g. reply vs
73 * command, or data which has not been endian converted).
75 * SE_CMDF_REPLY - is usually set in the top level syslink_elm embedded
76 * in syslink message replies as a safety in order to prevent a reply
77 * from being misinterpreted as a command.
79 * SE_CMDF_STRUCTURED - indicates that the payload is an array of
80 * structured syslink_elm's, otherwise the payload is considered to
83 * SE_CMDF_GLOBAL - indicates that the command is globally defined by the
84 * syslink standard and is not protocol-specific. Note that PADs
85 * are not global commands.
87 * SE_CMDF_UNTRANSLATED - indicates that the syslink_elm structure had
88 * to be translated into host endian format but any directly or
89 * indirectly represented opaque data has not been. This bit is used
90 * by the protocol layer to properly endian-translate protocol-specific
93 * SE_CMDF_ASIZE* - These 2 bits can encode the size for simple elments.
94 * The size is verified prior to delivery so command switches on simple
95 * elements need not check se_bytes. This also makes it easier for
96 * the protocol code to do endian conversions. These bits are not used
97 * for this purpose in sm_head.
100 * SE_CMDF_DMAW - These bits share the same bit positions as the ASIZE
101 * bits and are used in sm_head to indicate the presence of an out of
102 * band DMA buffer associated with the message. DMAW indicates that
103 * the originator is passing data to the target, DMAR indicates that
104 * the target is passing data to the originator. Both bits may be set.
106 * SE_AUX field - auxillary data field (signed 32 bit integer)
108 * This field contains protocol and command/element specific data.
109 * This typically contains an error code in replies (at least in
113 sl_cmd_t se_cmd; /* syslink element command/status id */
114 sl_reclen_t se_bytes; /* unaligned record size */
115 sl_auxdata_t se_aux; /* auxillary data always present */
116 /* extended by data */
119 #define SE_CMDF_REPLY 0x8000 /* safety feature */
120 #define SE_CMDF_STRUCTURED 0x4000 /* payload is structured */
121 #define SE_CMDF_GLOBAL 0x2000 /* non-proto-specific global cmd */
122 #define SE_CMDF_UNTRANSLATED 0x1000 /* needs endian translation */
124 #define SE_CMDF_ASIZEMASK 0x0C00 /* auto-size mask */
125 #define SE_CMDF_ASIZEX 0x0000 /* N bytes of extended data */
126 #define SE_CMDF_ASIZE_RESERVED 0x0400 /* reserved for future use */
127 #define SE_CMDF_ASIZE4 0x0800 /* 4 bytes of extended data */
128 #define SE_CMDF_ASIZE8 0x0C00 /* 8 bytes of extended data */
130 #define SE_CMDF_DMAR 0x0800 /* (structured only) originator reads */
131 #define SE_CMDF_DMAW 0x0400 /* (structured only) originator writes*/
133 #define SE_CMD_MASK 0x03FF
135 #define SE_CMD_PAD 0x0000 /* always reserved to mean PAD */
138 * SYSLINK_MSG - Syslink transactional command or response
140 * This structure represents a syslink transactional command or response
141 * between two end-points identified by the session id. Either end may
142 * initiate a command independant of the other. A transaction consists of
143 * the sending of a command and the reception of a response.
145 * Multiple transactions in each direction (and both directions at once)
146 * may occur in parallel. The command/reply transaction space in one
147 * direction is independant of the command/reply transaction space in the
150 * SM_PROTO rppppppx-ppppppx
152 * r 0 = Command, 1 = Reply
154 * x Used to detect endian reversal. The protocol id is OR'd
155 * with 0x0100 on transmission. If we find bit 0 set to 1 on
156 * reception, endian translation must occur.
158 * - Reserved, must be 0
160 * p12 Encoded protocol number. Protocol 0 indicates PAD (r must
161 * be 0 as well). Protocols 0-63 are reserved and may only be
162 * used when officially recognized by the DragonFly project.
163 * 64-4095 are user defined.
165 * SM_BYTES bbbbbbbbbbbbbbbb
167 * b16 This is the size of the whole message, including headers
168 * but not including out-of-band DMA. All messages must
169 * be 8-byte aligned. Unlike syslink_elm structures, sm_bytes
170 * must be properly aligned.
172 * SM_RLABEL llllllllllllllllllllllllllllllll
174 * l32 This is a 32 bit reply label routing id. The format of
175 * this field is defined by the transport layer. The field
176 * is typically assigned in the command message as it passes
177 * through the transport layer and is retained verbatim in
180 * The most typical use of this field is as an aid to direct
181 * messages in a multi-threaded environment. For example,
182 * a kernel talking to a filesystem over a syslink might
183 * identify the thread originating the command in this field
184 * in order to allow the reply to be routed directly back to
187 * The field can also be used in crossbar switching meshes
188 * to identify both the originator and the target, but it
189 * should be noted that the verbatim requirement means the
190 * mesh must pick out the proper field based on the 'r'eply
195 * m64 This 64 bit message id combined with the mesh id and the
196 * 'r'eply bit (and also the direction of the message when
197 * operating over a full-duplex syslink) uniquely identifies
200 * The message id is typically set to the address of the
201 * syslink message or control structure used by the originator,
202 * or obtained from a 64 bit counter. This way the originator
203 * can guarentee uniqueness without actually having to track
204 * message id allocations.
208 * s64 This is a 64 bit session id key whos primary purpose is to
209 * validate a link and prevent improperly routed or stale
210 * messages from having an adverse effect on the cluster. The
211 * field is typically left 0 for intra-host links.
213 * SM_HEAD (structure)
215 * All syslink messages other then PAD messages must contain at least
216 * one whole syslink_elm. Elements are arranged in an array until
217 * the syslink message space is exhausted. Each element may represent
218 * opaque data or recursively structured data. Structured data consists
219 * of an array of 0 or more elements embedded in the parent element.
222 * ENDIAN TRANSLATION - endian translation occurs when a message is received
223 * with bit 0 set in sm_proto, indicating that the native endian mode of
224 * the sender is different from the native endian mode of the receiver.
225 * Endian translation is NOT specific to little or big endian formatting
226 * but instead occurs only when the two sides have different native endian
227 * modes. All fields are interpreted structurally. Only little and big
228 * endian formats are supported (i.e. simple byte reversal).
230 * Translation consists of reversing the byte ordering for each structural
231 * field. Any syslink_elm structures are recursively translated as well,
232 * but opaque data contained within is not. The SE_CMDF_UNTRANSLATED bit
233 * in each translated syslink_elm structure is flipped.
235 * Syslink routers and switches may or may not translate a syslink_msg (but
236 * they must still properly interpret the syslink_msg header as the
237 * message passes through). It is possible for a message to be translated
238 * multiple times while it transits the network so it is important when
239 * translation occurs that the SE_CMDF_UNTRANSLATED bit in the syslink_elm
240 * structures gets flipped rather then simply set.
243 sl_proto_t sm_proto; /* protocol id, endian, reply bit */
244 sl_reclen_t sm_bytes; /* unaligned size of message */
245 sl_rlabel_t sm_rlabel; /* reply label routing id */
246 /* minimum syslink_msg size is 8 bytes (special PAD) */
247 sysid_t sm_msgid; /* message id */
248 sysid_t sm_sessid; /* session id */
249 struct syslink_elm sm_head; /* structured data */
253 * Minimum sizes for syslink pads and syslink messages. Pads can be as
254 * small as 8 bytes and are 8-byte aligned. Syslink messages can be as
255 * small as 16 bytes and are 8-byte aligned.
257 #define SL_MIN_PAD_SIZE offsetof(struct syslink_msg, sm_msgid)
258 #define SL_MIN_MSG_SIZE sizeof(struct syslink_msg)
259 #define SL_MIN_ELM_SIZE sizeof(struct syslink_elm)
260 #define SL_MSG_ALIGN(bytes) (((bytes) + 7) & ~7)
263 * sm_proto field rppppppx-PPPPPPx encoded
264 * ----ppppppPPPPPP decoded
266 * Note: SMPROTO_ defines are in encoded form
268 #define SM_PROTO_REPLY 0x8000
269 #define SM_PROTO_ENDIAN_NORM 0x0100
270 #define SM_PROTO_ENDIAN_REV 0x0001
271 #define SM_PROTO_ENCODE(n) ((((n) << 1) & ~127) | (((n) << 3) & 0x7E00) \
272 | SM_PROTO_ENDIAN_NORM)
273 #define SM_PROTO_DECODE(n) ((((n) >> 1) & 63) | (((n) >> 3) & )) 0x0FC0) \
274 | SM_PROTO_ENDIAN_NORM)
277 * Reserved protocol encodings 0-63
279 #define SMPROTO_PAD SM_PROTO_ENCODE(0x0000)
282 * high level protocol encodings
284 #define SMPROTO_BSDVFS SM_PROTO_ENCODE(0x0040)
287 * Syslink messages may contain recursive components. The recursion depth
288 * allowed is limited to SL_MAXDEPTH.
290 * Syslink messages, NON-inclusive of any DMA buffers, are limited to
291 * SL_MAXSIZE bytes. DMA buffer limitations are not defined here but
292 * the expectation is that they can be fairly large.
294 #define SL_MAXDEPTH 10
295 #define SL_MAXSIZE 4096
300 #define SLMSG_SMALL 256
301 #define SLMSG_BIG SL_MAXSIZE
304 union syslink_small_msg {
305 struct syslink_msg msg;
306 char buf[SLMSG_SMALL];
309 union syslink_big_msg {
310 struct syslink_msg msg;
314 typedef struct syslink_msg *syslink_msg_t;
315 typedef struct syslink_elm *syslink_elm_t;