sys/sys/syslink_msg.h

   1 /*
   2  * Copyright (c) 2004-2006 The DragonFly Project.  All rights reserved.
   3  *
   4  * This code is derived from software contributed to The DragonFly Project
   5  * by Matthew Dillon <dillon@backplane.com>
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  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
  16  *    distribution.
  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.
  20  *
  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
  32  * SUCH DAMAGE.
  33  *
  34  * $DragonFly: src/sys/sys/syslink_msg.h,v 1.3 2006/08/08 01:27:14 dillon Exp $
  35  */
  36 /*
  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.
  40  *
  41  * syslink      - Implements a communications end-point and protocol.  A
  42  *                syslink is typically directly embedded in a related
  43  *                structure.
  44  *
  45  * syslink_proto- Specifies a set of RPC functions.
  46  *
  47  * syslink_desc - Specifies a single RPC function within a protocol.
  48  */
  49
  50 #ifndef _SYS_SYSLINK_MSG_H_
  51 #define _SYS_SYSLINK_MSG_H_
  52
  53 #ifndef _SYS_TYPES_H_
  54 #include <sys/types.h>
  55 #endif
  56 #ifndef _MACHINE_ATOMIC_H_
  57 #include <machine/atomic.h>
  58 #endif
  59
  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 */
  65
  66 #define SL_ALIGN        8               /* 8-byte alignment */
  67 #define SL_ALIGNMASK    (SL_ALIGN - 1)
  68
  69 /*
  70  * Stream or FIFO based messaging structures.
  71  *
  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).
  77  *
  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.
  87  *
  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.
  94  *
  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.
 101  *
 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.
 108  *
 109  * The cid field represents an error code in the response.
 110  *
 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.
 119  *
 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.
 127  *
 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.
 131  */
 132 struct syslink_msg {
 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 */
 138         /* 8-byte aligned */
 139         /* one or more embedded syslink_item structures */
 140 };
 141
 142 #define SLMSG_ALIGN(bytes)      (((bytes) + 7) & ~7)
 143 #define SLMSGF_RESPONSE ((sl_msgid_t)0x80000000)
 144
 145 /*
 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.
 150  *
 151  * If the RECURSION bit (15) is set in the itemid, the item's data
 152  * represents any number of recursively embedded items.
 153  *
 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.
 157  *
 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.
 161  *
 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.
 165  *
 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).
 170  *
 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.
 175  */
 176 struct syslink_item {
 177         sl_itemid_t     itemid;
 178         sl_reclen_t     reclen;
 179         int32_t         auxdata;
 180         /* 8-byte aligned */
 181         /* may be extended to include more data */
 182 };
 183
 184 #define SLIF_RECURSION  ((sl_cid_t)0x8000)
 185 #define SLIF_REFID      ((sl_cid_t)0x4000)
 186
 187 typedef struct syslink_msg      *syslink_msg_t;
 188 typedef struct syslink_item     *syslink_item_t;
 189
 190 #endif
 191