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  * $DragonFly: src/sys/sys/syslink_msg.h,v 1.11 2007/08/13 17:47:20 dillon Exp $
  35  */
  36 /*
  37  * The syslink infrastructure implements an optimized RPC mechanism across a
  38  * communications link.  Endpoints, defined by a session sysid, are typically
  39  * associated with system structures but do not have to be.
  40  *
  41  * This header file is primarily responsible for the formatting of message
  42  * traffic over a syslink.
  43  */
  44
  45 #ifndef _SYS_SYSLINK_MSG_H_
  46 #define _SYS_SYSLINK_MSG_H_
  47
  48 #ifndef _SYS_TYPES_H_
  49 #include <sys/types.h>
  50 #endif
  51 #ifndef _MACHINE_ATOMIC_H_
  52 #include <machine/atomic.h>
  53 #endif
  54
  55 typedef int32_t         sl_auxdata_t;   /* auxillary data element */
  56 typedef u_int32_t       sl_rlabel_t;    /* reply label routing id */
  57 typedef u_int16_t       sl_proto_t;     /* protocol control field */
  58 typedef u_int16_t       sl_cmd_t;       /* command/status id */
  59 typedef u_int16_t       sl_reclen_t;    /* item length */
  60
  61 #define SL_ALIGN        8               /* 8-byte alignment */
  62 #define SL_ALIGNMASK    (SL_ALIGN - 1)
  63
  64 /*
  65  * SYSLINK_ELM - structured data element.
  66  *
  67  * syslink_msg's have zero or more syslink_elm's arranged as an array.
  68  * Each syslink_elm may represent opaque data or recursively structured
  69  * data.
  70  *
  71  * SE_CMD field - identify RPC command (at the top level) or RPC data element
  72  *                in deeper recursions.
  73  *
  74  *      Please note that while bits have individual meanings, command switches
  75  *      should universally compare all 16 bits against the command.  This
  76  *      guarentees that commands will not be misinterpreted (e.g. reply vs
  77  *      command, or data which has not been endian converted).
  78  *
  79  *      SE_CMDF_REPLY - is usually set in the top level syslink_elm embedded
  80  *      in syslink message replies as a safety in order to prevent a reply
  81  *      from being misinterpreted as a command.
  82  *
  83  *      SE_CMDF_STRUCTURED - indicates that the payload is an array of
  84  *      structured syslink_elm's, otherwise the payload is considered to
  85  *      be opaque.
  86  *
  87  *      SE_CMDF_GLOBAL - indicates that the command is globally defined by the
  88  *      syslink standard and is not protocol-specific.  Note that PADs
  89  *      are not global commands.
  90  *
  91  *      SE_CMDF_UNTRANSLATED - indicates that the syslink_elm structure had
  92  *      to be translated into host endian format but any directly or
  93  *      indirectly represented opaque data has not been.  This bit is used
  94  *      by the protocol layer to properly endian-translate protocol-specific
  95  *      opaque data.
  96  *
  97  *      SE_CMDF_ASIZE* - These 2 bits can encode the size for simple elments.
  98  *      The size is verified prior to delivery so command switches on simple
  99  *      elements need not check se_bytes.  This also makes it easier for
 100  *      the protocol code to do endian conversions.  These bits are not used
 101  *      for this purpose in sm_head.
 102  *
 103  *      SE_CMDF_DMAR
 104  *      SE_CMDF_DMAW - These bits share the same bit positions as the ASIZE
 105  *      bits and are used in sm_head to indicate the presence of an out of
 106  *      band DMA buffer associated with the message.  DMAW indicates that
 107  *      the originator is passing data to the target, DMAR indicates that
 108  *      the target is passing data to the originator.  Both bits may be set.
 109  *
 110  * SE_AUX field - auxillary data field (signed 32 bit integer)
 111  *
 112  *      This field contains protocol and command/element specific data.
 113  *      This typically contains an error code in replies (at least in
 114  *      sm_head).
 115  */
 116 struct syslink_elm {
 117         sl_cmd_t        se_cmd;         /* syslink element command/status id */
 118         sl_reclen_t     se_bytes;       /* unaligned record size */
 119         sl_auxdata_t    se_aux;         /* auxillary data always present */
 120         /* extended by data */
 121 };
 122
 123 #define SE_CMDF_REPLY           0x8000  /* safety feature */
 124 #define SE_CMDF_STRUCTURED      0x4000  /* payload is structured */
 125 #define SE_CMDF_GLOBAL          0x2000  /* non-proto-specific global cmd */
 126 #define SE_CMDF_UNTRANSLATED    0x1000  /* needs endian translation */
 127
 128 #define SE_CMDF_ASIZEMASK       0x0C00  /* auto-size mask */
 129 #define SE_CMDF_ASIZEX          0x0000  /* N bytes of extended data */
 130 #define SE_CMDF_ASIZE_RESERVED  0x0400  /* reserved for future use */
 131 #define SE_CMDF_ASIZE4          0x0800  /* 4 bytes of extended data */
 132 #define SE_CMDF_ASIZE8          0x0C00  /* 8 bytes of extended data */
 133
 134 #define SE_CMDF_DMAR            0x0800  /* (structured only) originator reads */
 135 #define SE_CMDF_DMAW            0x0400  /* (structured only) originator writes*/
 136
 137 #define SE_CMD_MASK             0x03FF
 138
 139 #define SE_CMD_PAD              0x0000  /* always reserved to mean PAD */
 140
 141 /*
 142  * SYSLINK_MSG - Syslink transactional command or response
 143  *
 144  * This structure represents a syslink transactional command or response
 145  * between two end-points identified by the session id.  Either end may
 146  * initiate a command independant of the other.  A transaction consists of
 147  * the sending of a command and the reception of a response.
 148  *
 149  * Multiple transactions in each direction (and both directions at once)
 150  * may occur in parallel.  The command/reply transaction space in one
 151  * direction is independant of the command/reply transaction space in the
 152  * other direction.
 153  *
 154  * SM_PROTO     rppppppx-ppppppx
 155  *
 156  *      r       0 = Command, 1 = Reply
 157  *
 158  *      x       Used to detect endian reversal.  The protocol id is OR'd
 159  *              with 0x0100 on transmission.  If we find bit 0 set to 1 on
 160  *              reception, endian translation must occur.
 161  *
 162  *      -       Reserved, must be 0
 163  *
 164  *      p12     Encoded protocol number.  Protocol 0 indicates PAD (r must
 165  *              be 0 as well).  Protocols 0-63 are reserved and may only be
 166  *              used when officially recognized by the DragonFly project.
 167  *              64-4095 are user defined.
 168  *
 169  * SM_BYTES     bbbbbbbbbbbbbbbb
 170  *
 171  *      b16     This is the size of the whole message, including headers
 172  *              but not including out-of-band DMA.  All messages must
 173  *              be 8-byte aligned.  Unlike syslink_elm structures, sm_bytes
 174  *              must be properly aligned.
 175  *
 176  * SM_RLABEL    llllllllllllllllllllllllllllllll
 177  *
 178  *      l32     This is a 32 bit reply label routing id.  The format of
 179  *              this field is defined by the transport layer.  The field
 180  *              is typically assigned in the command message as it passes
 181  *              through the transport layer and is retained verbatim in
 182  *              the reply message.
 183  *
 184  *              The most typical use of this field is as an aid to direct
 185  *              messages in a multi-threaded environment.  For example,
 186  *              a kernel talking to a filesystem over a syslink might
 187  *              identify the thread originating the command in this field
 188  *              in order to allow the reply to be routed directly back to
 189  *              that thread.
 190  *
 191  *              The field can also be used in crossbar switching meshes
 192  *              to identify both the originator and the target, but it
 193  *              should be noted that the verbatim requirement means the
 194  *              mesh must pick out the proper field based on the 'r'eply
 195  *              bit in sm_proto.
 196  *
 197  * SM_MSGID     m64
 198  *
 199  *      m64     This 64 bit message id combined with the mesh id and the
 200  *              'r'eply bit (and also the direction of the message when
 201  *              operating over a full-duplex syslink) uniquely identifies
 202  *              a syslink message.
 203  *
 204  *              The message id is typically set to the address of the
 205  *              syslink message or control structure used by the originator,
 206  *              or obtained from a 64 bit counter.  This way the originator
 207  *              can guarentee uniqueness without actually having to track
 208  *              message id allocations.
 209  *
 210  * SM_SESSID    s64
 211  *
 212  *      s64     This is a 64 bit session id key whos primary purpose is to
 213  *              validate a link and prevent improperly routed or stale
 214  *              messages from having an adverse effect on the cluster.  The
 215  *              field is typically left 0 for intra-host links.
 216  *
 217  * SM_HEAD      (structure)
 218  *
 219  *      All syslink messages other then PAD messages must contain at least
 220  *      one whole syslink_elm.  Elements are arranged in an array until
 221  *      the syslink message space is exhausted.  Each element may represent
 222  *      opaque data or recursively structured data.  Structured data consists
 223  *      of an array of 0 or more elements embedded in the parent element.
 224  *
 225  *
 226  * ENDIAN TRANSLATION - endian translation occurs when a message is received
 227  * with bit 0 set in sm_proto, indicating that the native endian mode of
 228  * the sender is different from the native endian mode of the receiver.
 229  * Endian translation is NOT specific to little or big endian formatting
 230  * but instead occurs only when the two sides have different native endian
 231  * modes.  All fields are interpreted structurally.  Only little and big
 232  * endian formats are supported (i.e. simple byte reversal).
 233  *
 234  * Translation consists of reversing the byte ordering for each structural
 235  * field.  Any syslink_elm structures are recursively translated as well,
 236  * but opaque data contained within is not.  The SE_CMDF_UNTRANSLATED bit
 237  * in each translated syslink_elm structure is flipped.
 238  *
 239  * Syslink routers and switches may or may not translate a syslink_msg (but
 240  * they must still properly interpret the syslink_msg header as the
 241  * message passes through).  It is possible for a message to be translated
 242  * multiple times while it transits the network so it is important when
 243  * translation occurs that the SE_CMDF_UNTRANSLATED bit in the syslink_elm
 244  * structures gets flipped rather then simply set.
 245  */
 246 struct syslink_msg {
 247         sl_proto_t      sm_proto;       /* protocol id, endian, reply bit */
 248         sl_reclen_t     sm_bytes;       /* unaligned size of message */
 249         sl_rlabel_t     sm_rlabel;      /* reply label routing id */
 250         /* minimum syslink_msg size is 8 bytes (special PAD) */
 251         sysid_t         sm_msgid;       /* message id */
 252         sysid_t         sm_sessid;      /* session id */
 253         struct syslink_elm sm_head;     /* structured data */
 254 };
 255
 256 /*
 257  * Minimum sizes for syslink pads and syslink messages.  Pads can be as
 258  * small as 8 bytes and are 8-byte aligned.  Syslink messages can be as
 259  * small as 16 bytes and are 8-byte aligned.
 260  */
 261 #define SL_MIN_PAD_SIZE         offsetof(struct syslink_msg, sm_msgid)
 262 #define SL_MIN_MSG_SIZE         sizeof(struct syslink_msg)
 263 #define SL_MIN_ELM_SIZE         sizeof(struct syslink_elm)
 264 #define SL_MSG_ALIGN(bytes)     (((bytes) + 7) & ~7)
 265
 266 /*
 267  * sm_proto field       rppppppx-PPPPPPx        encoded
 268  *                      ----ppppppPPPPPP        decoded
 269  *
 270  * Note: SMPROTO_ defines are in encoded form
 271  */
 272 #define SM_PROTO_REPLY          0x8000
 273 #define SM_PROTO_ENDIAN_NORM    0x0100
 274 #define SM_PROTO_ENDIAN_REV     0x0001
 275 #define SM_PROTO_ENCODE(n)      ((((n) << 1) & ~127) | (((n) << 3) & 0x7E00) \
 276                                  | SM_PROTO_ENDIAN_NORM)
 277 #define SM_PROTO_DECODE(n)      ((((n) >> 1) & 63) | (((n) >> 3) & )) 0x0FC0) \
 278                                  | SM_PROTO_ENDIAN_NORM)
 279
 280 /*
 281  * Reserved protocol encodings 0-63
 282  */
 283 #define SMPROTO_PAD             SM_PROTO_ENCODE(0x0000)
 284
 285 /*
 286  * high level protocol encodings
 287  */
 288 #define SMPROTO_BSDVFS          SM_PROTO_ENCODE(0x0040)
 289
 290 /*
 291  * Syslink messages may contain recursive components.  The recursion depth
 292  * allowed is limited to SL_MAXDEPTH.
 293  *
 294  * Syslink messages, NON-inclusive of any DMA buffers, are limited to
 295  * SL_MAXSIZE bytes.  DMA buffer limitations are not defined here but
 296  * the expectation is that they can be fairly large.
 297  */
 298 #define SL_MAXDEPTH     10
 299 #define SL_MAXSIZE      4096
 300
 301 /*
 302  * slmsgalloc() sizes
 303  */
 304 #define SLMSG_SMALL     256
 305 #define SLMSG_BIG       SL_MAXSIZE
 306
 307
 308 union syslink_small_msg {
 309         struct syslink_msg msg;
 310         char buf[SLMSG_SMALL];
 311 };
 312
 313 union syslink_big_msg {
 314         struct syslink_msg msg;
 315         char buf[SLMSG_BIG];
 316 };
 317
 318 typedef struct syslink_msg      *syslink_msg_t;
 319 typedef struct syslink_elm      *syslink_elm_t;
 320
 321 #endif
 322