sys/sys/syslink.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.h,v 1.8 2007/04/29 01:29:31 dillon Exp $
  35  */
  36
  37 /*
  38  * The syslink infrastructure implements an optimized RPC mechanism across a
  39  * communications link.  RPC functions are grouped together into larger
  40  * protocols.  Prototypes are typically associated with system structures
  41  * but do not have to be.
  42  *
  43  * syslink      - Implements a communications end-point and protocol.  A
  44  *                syslink is typically directly embedded in a related
  45  *                structure.
  46  */
  47
  48 #ifndef _SYS_SYSLINK_H_
  49 #define _SYS_SYSLINK_H_
  50
  51 #ifndef _SYS_TYPES_H_
  52 #include <sys/types.h>
  53 #endif
  54 #ifndef _SYS_SYSID_H_
  55 #include <sys/sysid.h>
  56 #endif
  57 #ifndef _SYS_TREE_H_
  58 #include <sys/tree.h>
  59 #endif
  60 #ifndef _SYS_SOCKET_H_
  61 #include <sys/socket.h>
  62 #endif
  63
  64 /***************************************************************************
  65  *                              PROTOCOL API/ABI                           *
  66  ***************************************************************************
  67  *
  68  * These structures implement the programming interface for end-points and
  69  * RPC calls.
  70  */
  71
  72 struct syslink;
  73 struct syslink_desc;
  74 struct syslink_generic_args;
  75
  76 typedef int (*syslink_func_t)(struct syslink_generic_args *);
  77
  78 /*
  79  * Commands for the syslink system call.
  80  *
  81  * CREATE:      Create a new syslink route node with the route node sysid
  82  *              and label information specified in the passed info structure.
  83  *              0 on success, -1 on failure or if the route node already
  84  *              exists.
  85  *
  86  *              The info structure must also contain the number of bits of
  87  *              address space you wish this route node to use.
  88  *
  89  * DESTROY:     Destroy the existing syslink route node with the route node
  90  *              sysid specified in the passed info structure.
  91  *              0 on success, -1 on failure.
  92  *
  93  * LOCATE:      Locate the first syslink route node with a sysid greater or
  94  *              equal to the sysid specified in the passed info structure.
  95  *              The info structure will be loaded on success and the linkid
  96  *              field will also be cleared.
  97  *
  98  *              To scan route nodes, start by specifying a sysid 0.  On
  99  *              success, increment the sysid in the info structure and loop.
 100  *
 101  *              You can also use the contents of the info structure to
 102  *              initiate a scan of links within the route node via the FIND
 103  *              command.  The sysid will remain unchanged through the scan
 104  *              and on completion you can increment it and loop up to
 105  *              the next LOCATE.
 106  *
 107  * ADD:         Add a link to the route node specified in the info structure.
 108  *              The route node must exist and must contain sufficient
 109  *              address space to handle the new link.  If associating a file
 110  *              descriptor, 0 is returned on success and -1 on failure.
 111  *              If obtaining a direct syslink file descriptor, the new
 112  *              descriptor is returned on success or -1 on failure.
 113  *
 114  *              On return, the linkid in the info structure is filled in and
 115  *              other adjustments may also have been made.
 116  *
 117  *              The info structure must contain the number of bits of
 118  *              address space required by the link.  If 0 is specified,
 119  *              a direct stream or connected socket is expected.  If
 120  *              non-zero, a switch is assumed (typically a switched UDP
 121  *              socket).  An all 0's address is reserved and an all 1's
 122  *              address implies a broadcast.  All other addresses imply
 123  *              single targets within the switched infrastructure.
 124  *
 125  *              FLAGS SUPPORTED:
 126  *
 127  *              SENDTO          This allows you to directly associate a
 128  *                              UDP socket and subnet with a syslink route
 129  *                              node.  To use this option the info structure
 130  *                              must contain a sockaddr representing the
 131  *                              broadcast address.  The low bits are adjusted
 132  *                              based on the size of the subnet (as
 133  *                              specified with PHYSBITS) to forward messages.
 134  *                              If not specified, write() is used and the
 135  *                              target is responsible for any switch
 136  *                              demultiplexing.
 137  *
 138  *              PACKET          Indicates that messages are packetized.
 139  *                              syslink will aggregate multiple syslink
 140  *                              messages into a single packet if possible,
 141  *                              but will not exceed 16384 bytes per packet
 142  *                              and will not attempt to pad messages to
 143  *                              align them for FIFO debuffering.
 144  *
 145  * REM:         Disassociate a link using the route node and linkid
 146  *              specified in the info structure.
 147  *
 148  *              The syslink route node will close() the related descriptor
 149  *              (or cause an EOF to occur for any direct syslink descriptor).
 150  *
 151  * FIND:        Locate the first linkid greater or equal to the linkid
 152  *              in the passed info structure for the route node sysid
 153  *              specified in the info structure, and fill in the rest of the
 154  *              structure as appropriate.
 155  *
 156  *              To locate the first link for any given route sysid, set
 157  *              linkid to 0.  To scan available links, increment the
 158  *              returned linkid before looping.
 159  */
 160
 161 #define SYSLINK_CMD_CREATE      0x00000001      /* create route node */
 162 #define SYSLINK_CMD_DESTROY     0x00000002      /* destroy route node */
 163 #define SYSLINK_CMD_LOCATE      0x00000003      /* locate first route node */
 164 #define SYSLINK_CMD_ADD         0x00000004      /* add link */
 165 #define SYSLINK_CMD_REM         0x00000005      /* remove link */
 166 #define SYSLINK_CMD_FIND        0x00000006      /* locate link info */
 167
 168 #define SYSLINK_LABEL_SIZE      32
 169 #define SYSLINK_ROUTER_MAXBITS  20
 170
 171 enum syslink_type { SYSLINK_TYPE_ROUTER, SYSLINK_TYPE_MANAGER, SYSLINK_TYPE_SEED, SYSLINK_TYPE_TERMINAL };
 172
 173 /*
 174  * syslink_info structure
 175  *
 176  * This structure contains information about a syslink route node or
 177  * linkage.
 178  */
 179 struct syslink_info {
 180         int version;                    /* info control structure version */
 181         int fd;                         /* file descriptor (CMD_ADD) */
 182         int linkid;                     /* linkid (base physical address) */
 183         int bits;                       /* physical address bits if switched */
 184         int flags;                      /* message control/switch flags */
 185         enum syslink_type type;
 186         sysid_t sysid;                  /* route node sysid */
 187         char label[SYSLINK_LABEL_SIZE]; /* symbolic name */
 188         char reserved[32];
 189         union {
 190                 struct sockaddr sa;     /* required for SLIF_SENDTO */
 191         } u;
 192 };
 193
 194 /*
 195  * SLIF_PACKET - specify when the descriptor represents packetized data,
 196  *               where a single read or write reads or writes whole packets.
 197  *               For example, a UDP socket.  Otherwise a stream is assumed.
 198  *
 199  * SLIF_XSWITCH- specify when the descriptor represents a switched message
 200  *               source where the target has no means of discerning the
 201  *               subnet address the message is being sent to.
 202  *
 203  *               This case occurs when a stream connection is used to
 204  *               represented a switch instead of a single end-to-end
 205  *               connection.  Instead of trying to tag the stream
 206  *               messages with some kind of mac header, we instead require
 207  *               that the originator pre-adjust the syslink_msg header's
 208  *               src and dst fields based on the number of bits being
 209  *               switched.  The target will then renormalize the address
 210  *               fields to merge its own linkid base in.
 211  */
 212 #define SLIF_PACKET     0x0001          /* packetized, else stream */
 213 #define SLIF_XSWITCH    0x0002          /* router must extract/gen IP addrs */
 214 #if defined(_KERNEL) || defined(_KERNEL_STRUCTURES)
 215 #define SLIF_RQUIT      0x0400
 216 #define SLIF_WQUIT      0x0800
 217 #define SLIF_RDONE      0x1000
 218 #define SLIF_WDONE      0x2000
 219 #define SLIF_DESTROYED  0x4000
 220 #define SLIF_ERROR      0x8000
 221 #endif
 222
 223 #define SLIF_USERFLAGS          (SLIF_PACKET|SLIF_XSWITCH)
 224
 225 #if !defined(_KERNEL)
 226 int syslink(int, struct syslink_info *, size_t);
 227 #endif
 228
 229 #endif