2 * Copyright (c) 2004-2006 The DragonFly Project. All rights reserved.
4 * This code is derived from software contributed to The DragonFly Project
5 * by Matthew Dillon <dillon@backplane.com>
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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
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.
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
34 * $DragonFly: src/sys/sys/syslink.h,v 1.3 2006/08/06 18:56:46 dillon Exp $
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.
43 * syslink - Implements a communications end-point and protocol. A
44 * syslink is typically directly embedded in a related
47 * syslink_proto- Specifies a set of RPC functions.
49 * syslink_desc - Specifies a single RPC function within a protocol.
52 #ifndef _SYS_SYSLINK_H_
53 #define _SYS_SYSLINK_H_
56 #include <sys/types.h>
60 * SYSIDs are 64 bit entities. A SYSID is potentially routed across a
61 * topology, lsb to msb. End points typically reserve lsb bits
62 * while each routing layer reserves additional bits. Locality of reference
63 * is defined as storing a value of 0 in any 'unknown' high bits,
64 * allowing local meshes to be tied together into larger entities
65 * without disrupting a running system.
67 * Because sysid's are the primary means of identification in a potentially
68 * huge mesh of machines, a way is needed to detect stale values. For
69 * this reason, each local node reserves a number of bits starting at bit 0
70 * (the lsb) as a boot counter. Sysids whos ref counts are not entirely
71 * known due to a disconnect must not be recycled after a disconnect for
72 * at least a number of weeks. 10-16 bits are usually reserved for this
73 * purpose. Theoretically this also means that the SYSID routing space
74 * for a disconnected node should not be reassigned to another node.
76 typedef u_int64_t sysid_t;
78 /***************************************************************************
80 ***************************************************************************
82 * These structures implement the programming interface for end-points and
89 struct syslink_transport;
91 struct syslink_generic_args;
93 typedef int (*syslink_func_t)(struct syslink_generic_args *);
96 * Commands for the syslink() system call.
98 * establish - Establish a new system link with the supplied mask and match
99 * values. A descriptor, if supplied, must be a reliable stream
100 * or packet descriptor. If -1 is specified the kernel will
101 * supply a reliable packet descriptor. Returns the descriptor.
103 * The kernel will automatically adjust the mask to fit
104 * available routing space. The caller typically specifies
105 * the low one bits of the mask, e.g. 0xFFFF, to indicate to
106 * the kernel how big a chunk of the sysid space the caller
107 * needs. If the caller supplies too large a chunk the kernel
108 * will adjust the mask on return. The kernel sets the match
109 * bits for the unmasked bits on return.
111 * getsysmask - Retrieve the mask/match values associated with the kernel's
112 * syslink route node that we have connected to.
114 #define SYSLINK_ESTABLISH 0x0001 /* establish a system link */
115 #define SYSLINK_GETSYSMASK 0x0004 /* retrieve kernel node mask/match */
118 * A syslink structure represents an end-point for communications. System
119 * structures such as vnodes are typically associated with end-points and
120 * usually embed a syslink structure. There is typically one master
121 * structure (sl_remote_id == 0) and any number of slave structures at
122 * remote locations (sl_remote_id on slaves point to master).
124 * A ref counter is integrated into the structure and used by SYSLINK to
125 * keep track of sysid references sent to remote targets. This counter
126 * may also be used by the governing structure (e.g. vnode) so long as
127 * the SYSLINK API is used to manipulate it.
129 * An operations vector implements the ABI for the numerous functions
130 * associated with the system structure. E.G. VOPs for vnodes. The
131 * ops structure also references the transport and protocol layers. Using
132 * vnodes as an example, the ops structure would be replicated from a
133 * template on a per-mount basis.
136 sysid_t sl_sysid; /* syslink id of this end-point */
137 sysid_t sl_remote_id; /* syslink id of remote end-point */
138 int sl_refs; /* track references */
139 struct syslink_ops *sl_ops; /* operations vector */
143 * The syslink_ops structure is typically embedded as part of a larger system
144 * structure. It conatins a reference to the transport layer (if any),
145 * protocol, and a structural offset range specifying the function vectors
146 * in the larger system structure.
148 * For example, vnode operations (VOPs) embed this structure in the vop_ops
151 * The syslink_ops structure may be replaced as necessary. The VFS subsystem
152 * typically replicates syslink_ops on a per-mount basis and stores a pointer
153 * to the mount point in the larger system structure (vop_ops).
156 struct syslink_proto *proto;
157 void *transport; /* FUTURE USE (transport layer) */
163 * The syslink_desc structure describes a function vector in the protocol.
164 * This structure may be extended by the protocol to contain additional
167 struct syslink_desc {
168 int sd_offset; /* offset into ops structure */
169 const char *sd_name; /* name for debugging */
173 * The syslink_proto structure describes a protocol. The structure contains
174 * templates for the various ops structures required to implement the
177 struct syslink_proto {
178 const char *sp_name; /* identifying name */
180 int sp_opssize; /* structure embedding syslink_ops */
181 struct syslink_ops *sp_call_encode; /* encode call */
182 struct syslink_ops *sp_call_decode; /* decode call */
183 struct syslink_ops *sp_reply_encode; /* encode reply */
184 struct syslink_ops *sp_reply_decode; /* decode reply */
185 struct syslink_ops *sp_ops; /* direct ABI calls */
188 #define SPF_ALLOCATED 0x00000001
191 * The syslink_generic_args structure contains the base data required in
192 * the arguments structure passed to any given ops function. This structure
193 * is typically extended with the actual call arguments.
195 struct syslink_generic_args {
196 struct syslink_desc *a_desc; /* ABI method description */
197 struct syslink *a_syslink; /* original syslink */
198 /* extend arguments */
201 typedef struct syslink *syslink_t;
202 typedef struct syslink_ops *syslink_ops_t;
203 typedef struct syslink_desc *syslink_desc_t;
204 typedef struct syslink_proto *syslink_proto_t;
205 typedef struct syslink_generic_args *syslink_generic_args_t;
207 #if !defined(_KERNEL)
208 int syslink(int, int, sysid_t *, sysid_t *);