sys/sys/syslink_msg.h

   1 /*
   2  * Copyright (c) 2004-2007 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 /*
  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.
  38  *
  39  * This header file is primarily responsible for the formatting of message
  40  * traffic over a syslink.
  41  */
  42
  43 #ifndef _SYS_SYSLINK_MSG_H_
  44 #define _SYS_SYSLINK_MSG_H_
  45
  46 #ifndef _SYS_TYPES_H_
  47 #include <sys/types.h>
  48 #endif
  49 #include <machine/atomic.h>
  50
  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 */
  56
  57 #define SL_ALIGN        8               /* 8-byte alignment */
  58 #define SL_ALIGNMASK    (SL_ALIGN - 1)
  59
  60 /*
  61  * SYSLINK_ELM - structured data element.
  62  *
  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
  65  * data.
  66  *
  67  * SE_CMD field - identify RPC command (at the top level) or RPC data element
  68  *                in deeper recursions.
  69  *
  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).
  74  *
  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.
  78  *
  79  *      SE_CMDF_STRUCTURED - indicates that the payload is an array of
  80  *      structured syslink_elm's, otherwise the payload is considered to
  81  *      be opaque.
  82  *
  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.
  86  *
  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
  91  *      opaque data.
  92  *
  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.
  98  *
  99  *      SE_CMDF_DMAR
 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.
 105  *
 106  * SE_AUX field - auxillary data field (signed 32 bit integer)
 107  *
 108  *      This field contains protocol and command/element specific data.
 109  *      This typically contains an error code in replies (at least in
 110  *      sm_head).
 111  */
 112 struct syslink_elm {
 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 */
 117 };
 118
 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 */
 123
 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 */
 129
 130 #define SE_CMDF_DMAR            0x0800  /* (structured only) originator reads */
 131 #define SE_CMDF_DMAW            0x0400  /* (structured only) originator writes*/
 132
 133 #define SE_CMD_MASK             0x03FF
 134
 135 #define SE_CMD_PAD              0x0000  /* always reserved to mean PAD */
 136
 137 /*
 138  * SYSLINK_MSG - Syslink transactional command or response
 139  *
 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.
 144  *
 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
 148  * other direction.
 149  *
 150  * SM_PROTO     rppppppx-ppppppx
 151  *
 152  *      r       0 = Command, 1 = Reply
 153  *
 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.
 157  *
 158  *      -       Reserved, must be 0
 159  *
 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.
 164  *
 165  * SM_BYTES     bbbbbbbbbbbbbbbb
 166  *
 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.
 171  *
 172  * SM_RLABEL    llllllllllllllllllllllllllllllll
 173  *
 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
 178  *              the reply message.
 179  *
 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
 185  *              that thread.
 186  *
 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
 191  *              bit in sm_proto.
 192  *
 193  * SM_MSGID     m64
 194  *
 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
 198  *              a syslink message.
 199  *
 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.
 205  *
 206  * SM_SESSID    s64
 207  *
 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.
 212  *
 213  * SM_HEAD      (structure)
 214  *
 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.
 220  *
 221  *
 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).
 229  *
 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.
 234  *
 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.
 241  */
 242 struct syslink_msg {
 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 */
 250 };
 251
 252 /*
 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.
 256  */
 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)
 261
 262 /*
 263  * sm_proto field       rppppppx-PPPPPPx        encoded
 264  *                      ----ppppppPPPPPP        decoded
 265  *
 266  * Note: SMPROTO_ defines are in encoded form
 267  */
 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)
 275
 276 /*
 277  * Reserved protocol encodings 0-63
 278  */
 279 #define SMPROTO_PAD             SM_PROTO_ENCODE(0x0000)
 280
 281 /*
 282  * high level protocol encodings
 283  */
 284 #define SMPROTO_BSDVFS          SM_PROTO_ENCODE(0x0040)
 285
 286 /*
 287  * Syslink messages may contain recursive components.  The recursion depth
 288  * allowed is limited to SL_MAXDEPTH.
 289  *
 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.
 293  */
 294 #define SL_MAXDEPTH     10
 295 #define SL_MAXSIZE      4096
 296
 297 /*
 298  * slmsgalloc() sizes
 299  */
 300 #define SLMSG_SMALL     256
 301 #define SLMSG_BIG       SL_MAXSIZE
 302
 303
 304 union syslink_small_msg {
 305         struct syslink_msg msg;
 306         char buf[SLMSG_SMALL];
 307 };
 308
 309 union syslink_big_msg {
 310         struct syslink_msg msg;
 311         char buf[SLMSG_BIG];
 312 };
 313
 314 typedef struct syslink_msg      *syslink_msg_t;
 315 typedef struct syslink_elm      *syslink_elm_t;
 316
 317 #endif
 318