2 * Copyright (c) 2004-2006 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
34 * $DragonFly: src/sys/sys/syslink_msg.h,v 1.3 2006/08/08 01:27:14 dillon Exp $
37 * The syslink infrastructure implements an optimized RPC mechanism across a
38 * communications link. Endpoints, defined by a sysid, are typically
39 * associated with system structures but do not have to be.
41 * syslink - Implements a communications end-point and protocol. A
42 * syslink is typically directly embedded in a related
45 * syslink_proto- Specifies a set of RPC functions.
47 * syslink_desc - Specifies a single RPC function within a protocol.
50 #ifndef _SYS_SYSLINK_MSG_H_
51 #define _SYS_SYSLINK_MSG_H_
54 #include <sys/types.h>
56 #ifndef _MACHINE_ATOMIC_H_
57 #include <machine/atomic.h>
60 typedef u_int32_t sl_cookie_t;
61 typedef u_int32_t sl_msgid_t;
62 typedef u_int16_t sl_cid_t; /* command or error */
63 typedef u_int16_t sl_itemid_t; /* item id */
64 typedef u_int16_t sl_reclen_t; /* item length */
66 #define SL_ALIGN 8 /* 8-byte alignment */
67 #define SL_ALIGNMASK (SL_ALIGN - 1)
70 * Stream or FIFO based messaging structures.
72 * The reclen is the actual record length in bytes prior to alignment.
73 * The reclen must be aligned to obtain the actual size of a syslink_msg
74 * or syslink_item structure. Note that the reclen includes structural
75 * headers (i.e. it does not represent just the data payload, it represents
76 * the entire structure).
78 * A message transaction consists of a command message and a reply message.
79 * A message is uniquely identified by (src_sysid, dst_sysid, msgid). Note
80 * that both ends can initiate a unique command using the same msgid at
81 * the same time, there is no confusion between (src,dst,id) and (dst,src,id).
82 * The reply message will have bit 31 set in the msgid. Transactions occur
83 * over reliable links and use a single-link abstraction (even if the
84 * underlying topology is a mesh). Therefore, there is no need to have
85 * timeouts or retries. If a link is lost the transport layer is responsible
86 * for aborting any transactions which have not been replied to.
88 * Multiple transactions may run in parallel between two entities. Only bit
89 * 31 of the msgid is reserved (to indicate a reply). Bits 30-0 may be
90 * specified by the originator. It is often convenient, but not required,
91 * to shift the pointer to the internal representation of the command on the
92 * originator a few bits and use that as the message id, removing the need
93 * to keep track of unique ids.
95 * Both the governing syslink_msg and embedded syslink_items are limited to
96 * 65535 bytes. When pure data is passed in a message it is typically
97 * limited to 32KB. If transport is via a memory-FIFO or might pass through
98 * a memory-FIFO, pad is usually added to prevent a message from wrapping
99 * around the FIFO boundary, allowing the FIFO to be memory mapped. This
100 * is typically negotiated by the transport layer.
102 * In a command initiation the cid is the command. The command format is
103 * not specified over the wire (other then 0x0000 being reserved), but
104 * typically the high 8 bits specify a protocol and the low 8 bits specify
105 * an index into the protocol's function array. Even though most sysid's
106 * implement only a single protocol and overloading is possible, using
107 * unique command id's across all protocols can be thought of as a safety.
109 * The cid field represents an error code in the response.
111 * The source and destination sysid is relative to the originator. The
112 * transport layer checks the high bits of the source sysid matches its
113 * expectations. These bits may be shortcut to a 0. If the message is
114 * transported to a non-local domain the transport layer must replace the
115 * 0 with the correct coordinates within the topology (insofar as it knows
116 * them). Since locality is layered not all high bits have to be replaced.
117 * The transport for a higher layer will continue to adjust segments of 0's
118 * as required to identify the message's source.
120 * PAD messages may be inserted in the stream by the transport layer(s) and
121 * are always stripped on the receiving end. However, they may be visible
122 * to the receiver (e.g. if the transport is a memory mapped FIFO). If
123 * multiple transport hops occur PAD is typically reformulated and it is
124 * up to the transport layer to decide whether it has to strip and
125 * reformulate it, or whether it can just pass it through, or negotiate
126 * a buffer alignment such that no reformulation is required.
128 * A PAD message uses a msgid of 0. As a special case, PAD messages can be
129 * as small as 8 bytes (msgid, cid, and reclen fields only). The sysid
130 * fields, if present, are ignored.
133 sl_msgid_t msgid; /* (32) transaction id for (src,dst) */
134 sl_cid_t cid; /* (16) command or error code */
135 sl_reclen_t reclen; /* (16) */
136 sysid_t src_sysid; /* (64) end-point identifier */
137 sysid_t dst_sysid; /* (64) end-point identifier */
139 /* one or more embedded syslink_item structures */
142 #define SLMSG_ALIGN(bytes) (((bytes) + 7) & ~7)
143 #define SLMSGF_RESPONSE ((sl_msgid_t)0x80000000)
146 * A transaction contains any number of item structures. Each item
147 * structure may represent leaf data or a recursion into an array of
148 * additional item structures. The data type or field id is specified
149 * by the low 14 bits of the 16 bit itemid.
151 * If the RECURSION bit (15) is set in the itemid, the item's data
152 * represents any number of recursively embedded items.
154 * If the REFID bit (14) is set, it indicates that a leaf item is a
155 * sysid with a payload of exactly 8 bytes, and indicates that a recursion
156 * contains at least one leaf item somewhere within it that is a sysid.
158 * The reserved bits are still counted in the 16 bit itemid so, for example,
159 * an identifier of 0x0001 is different from 0x8001. However, it is not
160 * recommended that this sort of field id overloading be done.
162 * Both recursive and non-recursive items may use the aux field to hold
163 * information. Recursive items ONLY have the aux field available since
164 * the data payload is the recursed item array.
166 * SYSID's passed as data (i.e. the REFID bit is set in the itemid) are
167 * ref-counted by the transport layer. XXX (need to flesh this out some
168 * more w/ regard to temporary cache id's verses more persistent objects,
169 * and how to deal with disconnection and reconnection).
171 * NOTE! The transport layer usually validates that the item data structure
172 * is entirely correct before transmitting the message. Additionally,
173 * locally specified sysid's may have to be modified by the transport layer
174 * if the message exits the local domain.
176 struct syslink_item {
181 /* may be extended to include more data */
184 #define SLIF_RECURSION ((sl_cid_t)0x8000)
185 #define SLIF_REFID ((sl_cid_t)0x4000)
187 typedef struct syslink_msg *syslink_msg_t;
188 typedef struct syslink_item *syslink_item_t;