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.4 2007/03/21 20:06:36 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
 133 /*
 134  * Raw protocol structures
 135  */
 136 struct syslink_msg {
 137         u_int16_t       sm_cmd;         /* protocol command code */
 138         u_int16_t       sm_bytes;       /* unaligned size of message */
 139         u_int32_t       sm_seq;
 140         /* minimum syslink_msg size is 8 bytes (special PAD) */
 141         sysid_t         sm_srcid;       /* origination logical sysid */
 142         sysid_t         sm_dstid;       /* destination logical sysid */
 143         sysid_t         sm_dstpysid;    /* cached physical sysid */
 144 };
 145
 146 struct syslink_elm {
 147         u_int16_t       se_ctl;
 148         u_int16_t       se_bytes;
 149         u_int32_t       se_reserved;
 150         /* extended by data */
 151 };
 152
 153 #define SLMSG_ALIGN(bytes)      (((bytes) + 7) & ~7)
 154 #define SLMSGF_RESPONSE ((sl_msgid_t)0x80000000)
 155
 156 #define SLIF_RECURSION  ((sl_cid_t)0x8000)
 157 #define SLIF_REFID      ((sl_cid_t)0x4000)
 158
 159 typedef struct syslink_msg      *syslink_msg_t;
 160 typedef struct syslink_item     *syslink_item_t;
 161
 162 #endif
 163