Print this page
Support route deletion entries in SVP_R_LOG_ACK.
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/lib/varpd/libvarpd/common/libvarpd_provider.h
+++ new/usr/src/lib/varpd/libvarpd/common/libvarpd_provider.h
1 1 /*
2 2 * This file and its contents are supplied under the terms of the
3 3 * Common Development and Distribution License ("CDDL"), version 1.0.
4 4 * You may only use this file in accordance with the terms of version
5 5 * 1.0 of the CDDL.
6 6 *
7 7 * A full copy of the text of the CDDL should have accompanied this
8 8 * source. A copy of the CDDL is also available via the Internet at
9 9 * http://www.illumos.org/license/CDDL.
10 10 */
11 11
12 12 /*
13 13 * Copyright 2018 Joyent, Inc.
14 14 */
15 15
16 16 #ifndef _LIBVARPD_PROVIDER_H
17 17 #define _LIBVARPD_PROVIDER_H
18 18
19 19 /*
20 20 * varpd provider interface for lookup modules
21 21 *
22 22 * This header file defines all the structures and functions that a given lookup
23 23 * module needs to implement and perform its purpose. At this time, all of these
24 24 * interfaces are considered private to illumos and therefore are subject to
25 25 * change. At some point we will move to more broadly stabilize these interfaces
26 26 * and commit to them. Until such time, expect breakage for out of gate
27 27 * consumers.
28 28 *
29 29 * A plugin is a dynamic shared object that is placed inside of varpd's default
30 30 * module.
31 31 *
32 32 * The shared object must define an initializer, such as with #pragma init. This
33 33 * function will be run with the module is dlopened by libvarpd. In that init
34 34 * function, the function must allocate a varpd_plugin_register by calling
35 35 * libvarpd_plugin_alloc() and specifying VARPD_CURRENT_VERSION. If that
36 36 * succeeds, then it should proceed to fill out the registration and then call,
37 37 * libvarpd_plugin_register() with it. Regardless of whether it succeeds or
38 38 * fails, it should call libvarpd_plugin_free(). In the case of failure, there
39 39 * is not much that the module should do, other than log some message to the
40 40 * standard bunyan logger that exists.
41 41 *
42 42 * Once libvarpd_plugin_register() returns, the module should assume that any
43 43 * of the operations it defined in the operation vector may be called and
44 44 * therefore it is recommended that any other required initialization should be
45 45 * performed at that time.
46 46 *
47 47 * At this time, once a plugin is loaded, it will not be unloaded. Therefore,
48 48 * there is no corresponding requirement to unregister, though that may come in
49 49 * a future version.
50 50 *
51 51 * -----------------------------
52 52 * Plugin Types and Destinations
53 53 * -----------------------------
54 54 *
55 55 * There are two different kinds of plugins in this world, there are point to
56 56 * point plugins and there are dynamic plugins. The key difference is in how
57 57 * packets are routed through the system. In a point to point plugin, a single
58 58 * destination is used when the instance is started. In dynamic plugins,
59 59 * destinations are looked up as they are required and an instance of a plugin
60 60 * is required to provide that.
61 61 *
62 62 * These point to point plugins define a type of OVERLAY_TARGET_POINT and the
63 63 * dynamic plugins instead define a type of OVERLAY_TARGET_DYNAMIC.
64 64 *
65 65 * Encapsulation plugins have multiple types of destinations. They may require
66 66 * an Ethernet address (OVERLAY_PLUGIN_D_ETHERNET), IP address
67 67 * (OVERLAY_PLUGIN_D_IP), and a port (OVERLAY_PLUGIN_D_PORT). For example,
68 68 * consider vxlan, it requires an IP and a port; while a hypothetical nvgre,
69 69 * would only require an IP.
70 70 *
71 71 * A plugin is allowed to describe which of these fields that it supports and
72 72 * given which encapsulation plugin it is paired with, it can support a varying
73 73 * degree of properties. For example, consider the example of the direct plugin.
74 74 * It has a notion of a destination port and a destination IP. If it is paired
75 75 * with a plugin that only requires an IP, then it wouldn't need to show a
76 76 * property that's related to a destination port.
77 77 *
78 78 * ------------------
79 79 * Plugin Definitions
80 80 * ------------------
81 81 *
82 82 * A plugin is required to fill in both an operations vector and a series of
83 83 * additional metadata that it passed in to libvarpd_plugin_register(). The
84 84 * following lists all of the routines and their purposes. The full signatures
85 85 * are available in the body of the header file.
86 86 *
87 87 * varpd_plugin_create_f
88 88 *
89 89 * Create a new instance of a plugin. Each instance refers to a different
90 90 * overlay device and thus a different overlay identifier. Each instance
91 91 * has its own property space and is unique. This function gives the chance
92 92 * for the plugin to create and provide any private data that it will
93 93 * require.
94 94 *
95 95 * In addition, the plugin is given the type of destination that is
96 96 * required and it is its job to determine whether or not it supports it.
97 97 *
98 98 * varpd_plugin_destory_f
99 99 *
100 100 * This is the opposite of varpd_plugin_create_f. It is called to allow the
101 101 * plugin to reclaim any resources with the private argument that it passed
102 102 * out as part of the destroy function.
103 103 *
104 104 * varpd_plugin_start_f
105 105 *
106 106 * This routine is called to indicate that an instance should be started.
107 107 * This is a plugin's chance to verify that it has all of its required
108 108 * properties set and to take care of any action that needs to be handled
109 109 * to begin the plugin. After this point it will be legal to have the
110 110 * varpd_plugin_default_f, varpd_plugin_lookup_f, varpd_plugin_arp_f and
111 111 * varpd_plugin_dhcp_f endpoints called.
112 112 *
113 113 * varpd_plugin_stop_f
114 114 *
115 115 * This routine is called to indicate that an instance is stopping, it is
116 116 * the opposite of varpd_plugin_start_f. This is a chance to clean up
117 117 * resources that are a side effect of having started the instance.
118 118 *
119 119 * varpd_plugin_default_f
120 120 *
121 121 * This routine is defined by plugins of type OVERLAY_TARGET_POINT. It is
122 122 * used to answer the question of where should all traffic for this
123 123 * instance be destined. Plugins of type OVERLAY_TARGET_DYNAMIC should
124 124 * leave this entry set to NULL.
125 125 *
126 126 * On success, the default routine should return VARPD_LOOKUP_OK. On
127 127 * failure, it should return the macro VARPD_LOOKUP_DROP.
128 128 *
129 129 * varpd_plugin_lookup_f
130 130 *
131 131 * This routine must be defined by plugins of type OVERLAY_TARGET_DYNAMIC.
132 132 * It is used to lookup the destination for a given request. Each request
133 133 * comes in with its own MAC address this allows a plugin to direct it to
134 134 * any remote location.
135 135 *
136 136 * This is designed as an asynchronous API. Once a lookup is completed it
137 137 * should call libvarpd_plugin_query_reply() and pass as the second
138 138 * argument either VARPD_LOOKUP_OK to indicate that it went alright or it
139 139 * should reply VARPD_LOOKUP_DROP to indicate that the packet should be
140 140 * dropped.
141 141 *
142 142 * In addition, there are several utility routines that can take care of
143 143 * various kinds of traffic automatically. For example, if an ARP, NDP, or
144 144 * DHCP packet comes in, there are utilities such as
145 145 * libvarpd_plugin_proxy_arp(), libvarpd_plugin_proxy_ndp() and
146 146 * libvarpd_plugin_proxy_dhcp(), which allows the system to do the heavy
147 147 * lifting of validating the packet once it finds that it matches certain
148 148 * properties.
149 149 *
150 150 * varpd_plugin_arp_f
151 151 *
152 152 * This is an optional entry for plugins of type OVERLAY_TARGET_DYNAMIC.
153 153 * This is called after a plugin calls libvarpd_plugin_proxy_arp() and is
154 154 * used to ask the plugin to perform an ARP or NDP query. The type of query
155 155 * is passed in in the third argument, the only valid value for which will
156 156 * be VARPD_QTYPE_ETHERNET, to indicate we're doing an Ethernet lookup.
157 157 *
158 158 * The layer three IP address that is being looked up will be included in
159 159 * the struct sockaddr. The sockaddr(3SOCKET)'s sa_family will be set to
160 160 * indicate the type, eg. AF_INET or AF_INET6 and that will indicate the
161 161 * kind of sockaddr that will be used. For more information see
162 162 * sockaddr(3SOCKET). The implementation ensures that enough space for the
163 163 * link layer address will exist.
164 164 *
165 165 * This is an asynchronous lookup. Once the answer has been written, a
166 166 * plugin should call libvarpd_plugin_arp_reply and if it was successful,
167 167 * VARPD_LOOKUP_OK should be passed in and if it failed, VARPD_LOOKUP_DROP
168 168 * should be passed in instead.
169 169 *
170 170 * varpd_plugin_dhcp_f
171 171 *
172 172 * This is an optional entry for plugins of type OVERLAY_TARGET_DYNAMIC.
173 173 * This is called after a plugin calls the libvarpd_plugin_proxy_dhcp() and
174 174 * is used to ask the plugin to determine where is the DHCP server that
175 175 * this packet should actually be sent to. What is happening here is that
176 176 * rather than broadcast the initial DHCP request, we instead unicast it to
177 177 * a specified DHCP server that this operation vector indicates.
178 178 *
179 179 * The plugin is given a type, the same as the ARP plugin which indicates
180 180 * the kind of link layer address, the only valid type is
181 181 * VARPD_QTYPE_ETHERNET, other types should be rejected. Then, like the arp
182 182 * entry point, the dhcp entry point should determine the link layer
183 183 * address of the DHCP server and write that out in the appropriate memory
184 184 * and call libvarpd_plugin_dhcp_reply() when done. Similar to the arp
185 185 * entry point, it should use VARPD_LOOKUP_OK to indicate that it was
186 186 * filled in and VARPD_LOOKUP_DROP to indicate that it was not.
187 187 *
188 188 * varpd_plugin_nprops_f
189 189 *
190 190 * This is used by a plugin to indicate the number of properties that
191 191 * should exist for this instance. Recall from the section that Plugin
192 192 * types and Destinations, that the number of entries here may vary. As
193 193 * such, the plugin should return the number that is appropriate for the
194 194 * instance.
195 195 *
196 196 * This number will be used to obtain information about a property via the
197 197 * propinfo functions. However, the getprop and setprop interfaces will
198 198 * always use names to indicate the property it is getting and setting.
199 199 * This difference is structured this way to deal with property discovery
200 200 * and to make the getprop and setprop interfaces slightly easier for other
201 201 * parts of the broader varpd/dladm infrastructure.
202 202 *
203 203 * varpd_plugin_propinfo_f
204 204 *
205 205 * This interface is used to get information about a property, the property
206 206 * that information is being requested for is being passed in via the
207 207 * second argument. Here, callers should set properties such as the name,
208 208 * the protection, whether or not the property is required, set any default
209 209 * value, if it exist, and if relevant, set the valid range of values.
210 210 *
211 211 * varpd_plugin_getprop_f
212 212 *
213 213 * This is used to get the value of a property, if it is set. The passed in
214 214 * length indicates the length of the buffer that is used for updating
215 215 * properties. If it is not of sufficient size, the function should return
216 216 * an error and not update the buffer. Otherwise, it should update the size
217 217 * pointer with the valid size.
218 218 *
219 219 * varpd_plugin_setprop_f
220 220 *
221 221 * This is used to set the value of a property. An endpoint should validate
222 222 * that the property is valid before updating it. In addition, it should
223 223 * update its state as appropriate.
224 224 *
225 225 * varpd_plugin_save_f
226 226 *
227 227 * This is used to serialize the state of a given instance of a plugin such
228 228 * that if varpd crashes, it can be recovered. The plugin should write all
229 229 * state into the nvlist that it is passed in, it may use any keys and
230 230 * values that it wants. The only consumer of that nvlist will be the
231 231 * plugin itself when the restore endpoint is called.
232 232 *
233 233 * varpd_plugin_restore_f
234 234 *
235 235 * This is called by the server to restore an instance that used to exist,
236 236 * but was lost due to a crash. This is a combination of calling create and
237 237 * setting properties. The plugin should restore any private state that it
238 238 * can find recorded from the nvlist. The only items in the nvlist will be
239 239 * those that were written out during a previous call to
240 240 * varpd_plugin_save_f.
241 241 *
242 242 *
243 243 * Once all of these interfaces are implemented, the plugin should define the
244 244 * following members in the varpd_plugin_register_t.
245 245 *
246 246 * vpr_version
247 247 *
248 248 * This indicates the version of the plugin. Plugins should set this to the
249 249 * macro VARPD_CURRENT_VERSION.
250 250 *
251 251 * vpr_mode
252 252 *
253 253 * This indicates the mode of the plugin. The plugin's mode should be one
254 254 * of OVERLAY_TARGET_POINT and OVERLAY_TARGET_DYNAMIC. For more discussion
255 255 * of these types and the differences, see the section on Plugin Types and
256 256 * Destinations.
257 257 *
258 258 * vpr_name
259 259 *
260 260 * This is the name of the plugin. This is how users will refer to it in
261 261 * the context of running dladm(1M) commands. Note, this name must be
262 262 * unique across the different plugins, as it will cause others with the
263 263 * same name not to be registered.
264 264 *
265 265 * vpr_ops
266 266 *
267 267 * This is the operations vector as described above. Importantly, the
268 268 * member vpo_callbacks must be set to zero, this is being used for future
269 269 * expansion of the structure.
270 270 *
271 271 *
272 272 * --------------------------------------------------
273 273 * Downcalls, Upcalls, and Synchronization Guarantees
274 274 * --------------------------------------------------
275 275 *
276 276 * Every instance of a plugin is independent. Calls into a plugin may be made
277 277 * for different instances in parallel. Any necessary locking is left to the
278 278 * plugin module. Within an instance, various calls may come in parallel.
279 279 *
280 280 * The primary guarantees are that none of the varpd_plugin_save_f,
281 281 * varpd_plugin_lookup_f, varpd_default_f, varpd_plugin_arp_f, and
282 282 * varpd_plugin_dhcp_f will be called until after a call to varpd_plugin_start_f
283 283 * has been called. Similarly, they will not be called after a call to
284 284 * vardp_plugin_stop_f.
285 285 *
286 286 * The functions documented in this header may be called back into from any
287 287 * context, including from the operation vectors.
288 288 */
289 289
290 290 #include <bunyan.h>
291 291 #include <libvarpd.h>
292 292 #include <libnvpair.h>
293 293 #include <sys/socket.h>
294 294 #include <sys/overlay_target.h>
295 295
296 296 #ifdef __cplusplus
297 297 extern "C" {
298 298 #endif
299 299
300 300 #define VARPD_VERSION_ONE 1
301 301 #define VARPD_CURRENT_VERSION VARPD_VERSION_ONE
302 302
303 303 typedef struct __varpd_provier_handle varpd_provider_handle_t;
304 304 typedef struct __varpd_query_handle varpd_query_handle_t;
305 305 typedef struct __varpd_arp_handle varpd_arp_handle_t;
306 306 typedef struct __varpd_dhcp_handle varpd_dhcp_handle_t;
307 307
308 308 typedef int (*varpd_plugin_create_f)(varpd_provider_handle_t *, void **,
309 309 overlay_plugin_dest_t);
310 310 typedef int (*varpd_plugin_start_f)(void *);
311 311 typedef void (*varpd_plugin_stop_f)(void *);
312 312 typedef void (*varpd_plugin_destroy_f)(void *);
313 313
314 314 #define VARPD_LOOKUP_OK (0)
315 315 #define VARPD_LOOKUP_DROP (-1)
316 316 typedef int (*varpd_plugin_default_f)(void *, overlay_target_point_t *);
317 317 typedef void (*varpd_plugin_lookup_f)(void *, varpd_query_handle_t *,
318 318 const overlay_targ_lookup_t *, overlay_target_point_t *,
319 319 overlay_target_route_t *, overlay_target_mac_t *);
320 320
321 321 #define VARPD_QTYPE_ETHERNET 0x0
322 322 typedef void (*varpd_plugin_arp_f)(void *, varpd_arp_handle_t *, int,
323 323 const struct sockaddr *, uint16_t, uint8_t *);
324 324 typedef void (*varpd_plugin_dhcp_f)(void *, varpd_dhcp_handle_t *, int,
325 325 const overlay_targ_lookup_t *, uint8_t *);
326 326
327 327 typedef int (*varpd_plugin_nprops_f)(void *, uint_t *);
328 328 typedef int (*varpd_plugin_propinfo_f)(void *, const uint_t,
329 329 varpd_prop_handle_t *);
330 330 typedef int (*varpd_plugin_getprop_f)(void *, const char *, void *, uint32_t *);
331 331 typedef int (*varpd_plugin_setprop_f)(void *, const char *, const void *,
332 332 const uint32_t);
333 333
334 334 typedef int (*varpd_plugin_save_f)(void *, nvlist_t *);
335 335 typedef int (*varpd_plugin_restore_f)(nvlist_t *, varpd_provider_handle_t *,
336 336 overlay_plugin_dest_t, void **);
337 337
338 338 typedef struct varpd_plugin_ops {
339 339 uint_t vpo_callbacks;
340 340 varpd_plugin_create_f vpo_create;
341 341 varpd_plugin_start_f vpo_start;
342 342 varpd_plugin_stop_f vpo_stop;
343 343 varpd_plugin_destroy_f vpo_destroy;
344 344 varpd_plugin_default_f vpo_default;
345 345 varpd_plugin_lookup_f vpo_lookup;
346 346 varpd_plugin_nprops_f vpo_nprops;
347 347 varpd_plugin_propinfo_f vpo_propinfo;
348 348 varpd_plugin_getprop_f vpo_getprop;
349 349 varpd_plugin_setprop_f vpo_setprop;
350 350 varpd_plugin_save_f vpo_save;
351 351 varpd_plugin_restore_f vpo_restore;
352 352 varpd_plugin_arp_f vpo_arp;
353 353 varpd_plugin_dhcp_f vpo_dhcp;
354 354 } varpd_plugin_ops_t;
355 355
356 356 typedef struct varpd_plugin_register {
357 357 uint_t vpr_version;
358 358 uint_t vpr_mode;
359 359 const char *vpr_name;
360 360 const varpd_plugin_ops_t *vpr_ops;
361 361 } varpd_plugin_register_t;
362 362
363 363 extern varpd_plugin_register_t *libvarpd_plugin_alloc(uint_t, int *);
364 364 extern void libvarpd_plugin_free(varpd_plugin_register_t *);
365 365 extern int libvarpd_plugin_register(varpd_plugin_register_t *);
366 366
367 367 /*
368 368 * Blowing up and logging
369 369 */
370 370 extern void libvarpd_panic(const char *, ...) __NORETURN;
371 371 extern const bunyan_logger_t *libvarpd_plugin_bunyan(varpd_provider_handle_t *);
372 372
373 373 /*
374 374 * Misc. Information APIs
375 375 */
376 376 extern uint64_t libvarpd_plugin_vnetid(varpd_provider_handle_t *);
377 377 extern uint32_t libvarpd_plugin_dcid(varpd_provider_handle_t *);
378 378
379 379 /*
380 380 * Lookup Replying query and proxying
381 381 */
382 382 extern void libvarpd_plugin_query_reply(varpd_query_handle_t *, int);
383 383
384 384 extern void libvarpd_plugin_proxy_arp(varpd_provider_handle_t *,
385 385 varpd_query_handle_t *, const overlay_targ_lookup_t *);
386 386 extern void libvarpd_plugin_proxy_ndp(varpd_provider_handle_t *,
387 387 varpd_query_handle_t *, const overlay_targ_lookup_t *);
388 388 extern void libvarpd_plugin_arp_reply(varpd_arp_handle_t *, int);
389 389
390 390 extern void libvarpd_plugin_proxy_dhcp(varpd_provider_handle_t *,
391 391 varpd_query_handle_t *, const overlay_targ_lookup_t *);
392 392 extern void libvarpd_plugin_dhcp_reply(varpd_dhcp_handle_t *, int);
393 393
394 394
395 395 /*
396 396 * Property information callbacks
397 397 */
398 398 extern void libvarpd_prop_set_name(varpd_prop_handle_t *, const char *);
399 399 extern void libvarpd_prop_set_prot(varpd_prop_handle_t *, overlay_prop_prot_t);
400 400 extern void libvarpd_prop_set_type(varpd_prop_handle_t *, overlay_prop_type_t);
401 401 extern int libvarpd_prop_set_default(varpd_prop_handle_t *, void *, ssize_t);
402 402 extern void libvarpd_prop_set_nodefault(varpd_prop_handle_t *);
403 403 extern void libvarpd_prop_set_range_uint32(varpd_prop_handle_t *, uint32_t,
404 404 uint32_t);
405 405 extern void libvarpd_prop_set_range_str(varpd_prop_handle_t *, const char *);
|
↓ open down ↓ |
405 lines elided |
↑ open up ↑ |
406 406
407 407 /*
408 408 * Various injecting and invalidation routines
409 409 */
410 410 extern void libvarpd_inject_varp(varpd_provider_handle_t *, const uint8_t *,
411 411 const overlay_target_point_t *);
412 412 extern void libvarpd_inject_arp(varpd_provider_handle_t *, const uint16_t,
413 413 const uint8_t *, const struct in_addr *, const uint8_t *);
414 414 extern void libvarpd_fma_degrade(varpd_provider_handle_t *, const char *);
415 415 extern void libvarpd_fma_restore(varpd_provider_handle_t *);
416 +extern void libvarpd_route_flush(varpd_provider_handle_t *, uint8_t *,
417 + uint8_t *, uint8_t, uint8_t, uint16_t vlan_id);
416 418
417 419 #ifdef __cplusplus
418 420 }
419 421 #endif
420 422
421 423 #endif /* _LIBVARPD_PROVIDER_H */
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX