2 * Copyright (c) 2004-2007 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.4 2007/03/21 20:06:36 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>
63 * SYSIDs are 64 bit entities and come in two varieties. Physical SYSIDs
64 * are used to efficiently route messages across the mesh, while Logical
65 * SYSIDs are persistently assigned identifiers representing specific devices
66 * or specific media or named filesystems. That is, the logical SYSID
67 * assigned to a filesystem or ANVIL partition can be stored in that
68 * filesystem's superblock and allows the filesystem to migrate or
69 * be multi-homed (have multiple physical SYSIDs representing the same
72 * Physical SYSIDs can be ever-changing, and any given logical SYSID could
73 * in fact have multiple physical SYSIDs associated with it. The mesh is
74 * self-healing and the combination of the logical and physical sysid
75 * basically validates the message at the target and determines whether
76 * the physical SYSID must be recalculated (looked up again) or not.
78 typedef u_int64_t sysid_t;
80 /***************************************************************************
82 ***************************************************************************
84 * These structures implement the programming interface for end-points and
91 struct syslink_transport;
93 struct syslink_generic_args;
95 typedef int (*syslink_func_t)(struct syslink_generic_args *);
98 * Flags for the syslink system call. Low 8 bits used to specify
99 * the number of bits to reserve for connections into the route node
100 * (e.g. '3' would allow up to 8 connections, though its actually 7
101 * since the one address is needed for the route node itself).
103 #define SYSLINKF_PHYSBITS 0x000000FF
104 #define SYSLINKF_CREAT 0x00000100
105 #define SYSLINKF_EXCL 0x00000200
108 * A syslink structure represents an end-point for communications. System
109 * structures such as vnodes are typically associated with end-points and
110 * usually embed a syslink structure. There is typically one master
111 * structure (sl_remote_id == 0) and any number of slave structures at
112 * remote locations (sl_remote_id on slaves point to master).
114 * A ref counter is integrated into the structure and used by SYSLINK to
115 * keep track of sysid references sent to remote targets. This counter
116 * may also be used by the governing structure (e.g. vnode) so long as
117 * the SYSLINK API is used to manipulate it.
119 * An operations vector implements the ABI for the numerous functions
120 * associated with the system structure. E.G. VOPs for vnodes. The
121 * ops structure also references the transport and protocol layers. Using
122 * vnodes as an example, the ops structure would be replicated from a
123 * template on a per-mount basis.
128 int sl_refs; /* track references */
129 struct syslink_ops *sl_ops; /* operations vector */
133 * The syslink_ops structure is typically embedded as part of a larger system
134 * structure. It conatins a reference to the transport layer (if any),
135 * protocol, and a structural offset range specifying the function vectors
136 * in the larger system structure.
138 * For example, vnode operations (VOPs) embed this structure in the vop_ops
141 * The syslink_ops structure may be replaced as necessary. The VFS subsystem
142 * typically replicates syslink_ops on a per-mount basis and stores a pointer
143 * to the mount point in the larger system structure (vop_ops).
146 struct syslink_proto *proto;
147 void *transport; /* FUTURE USE (transport layer) */
153 * The syslink_desc structure describes a function vector in the protocol.
154 * This structure may be extended by the protocol to contain additional
157 struct syslink_desc {
158 int sd_offset; /* offset into ops structure */
159 const char *sd_name; /* name for debugging */
163 * The syslink_proto structure describes a protocol. The structure contains
164 * templates for the various ops structures required to implement the
167 struct syslink_proto {
168 const char *sp_name; /* identifying name */
170 int sp_opssize; /* structure embedding syslink_ops */
171 struct syslink_ops *sp_call_encode; /* encode call */
172 struct syslink_ops *sp_call_decode; /* decode call */
173 struct syslink_ops *sp_reply_encode; /* encode reply */
174 struct syslink_ops *sp_reply_decode; /* decode reply */
175 struct syslink_ops *sp_ops; /* direct ABI calls */
178 #define SPF_ALLOCATED 0x00000001
181 * The syslink_generic_args structure contains the base data required in
182 * the arguments structure passed to any given ops function. This structure
183 * is typically extended with the actual call arguments.
185 struct syslink_generic_args {
186 struct syslink_desc *a_desc; /* ABI method description */
187 struct syslink *a_syslink; /* original syslink */
188 /* extend arguments */
191 typedef struct syslink *syslink_t;
192 typedef struct syslink_ops *syslink_ops_t;
193 typedef struct syslink_desc *syslink_desc_t;
194 typedef struct syslink_proto *syslink_proto_t;
195 typedef struct syslink_generic_args *syslink_generic_args_t;
197 #if !defined(_KERNEL)
198 int syslink(int, int, sysid_t);