xref: /illumos-gate/usr/src/common/svc/repcache_protocol.h (revision bbf215553c7233fbab8a0afdf1fac74c44781867)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 
22 /*
23  * Copyright (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved.
24  * Copyright (c) 2016 by Delphix. All rights reserved.
25  */
26 
27 #ifndef	_REPCACHE_PROTOCOL_H
28 #define	_REPCACHE_PROTOCOL_H
29 
30 /*
31  * The Repository Cache Protocol
32  * -----------------------------
33  *
34  * 1. Introduction
35  * ---------------
36  * This header file defines the private protocols between libscf(3lib) and
37  * svc.configd(8).  There are two separate protocols:
38  *
39  * 1.	The 'global' protocol, accessible via an fattach(3C)ed door located
40  *	at REPOSITORY_DOOR_NAME.
41  *
42  * 2.	The 'client' protocol, accessible through a door created using the
43  *	global protocol, which allows access to the repository.
44  *
45  * 1.1 Design restrictions
46  * -----------------------
47  * A basic constraint of the door IPC mechanism is that there is no reliable
48  * delivery.  In particular:
49  *
50  * 1.	If libscf(3lib) recieves an EINTR from door_call(), it doesn't know
51  *      whether or not the server recieved (and is processing) its request.
52  *
53  * 2.	When svc.configd(8) calls door_return(), the client may have already
54  *	received an EINTR, aborting its door_call().  In this case, the
55  *	returned values are dropped on the floor.
56  *
57  * The practical upshot of all of this is simple:
58  *
59  *	Every individual protocol action must be idempotent.
60  *
61  * That is, a client must be able to retry any single request multiple times,
62  * and get the correct results.
63  *
64  * 1.2. Protocol shorthand
65  * -----------------------
66  * We represent by "REQUEST(arg1, arg2) -> result, res1, [desc]" a request code
67  * of REP_PROTOCOL_REQUEST (or REPOSITORY_DOOR_REQUEST), which takes two
68  * additional arguments, arg1 and arg2, and returns a result code, res1, and
69  * a file descriptor desc.
70  *
71  * If an error occurs, the server will usually only send the result code. (a
72  * short return)
73  *
74  * Inside the protocol destription, <foo> indicates the type foo indicates.
75  *
76  * 2. The Global protocol
77  * ----------------------
78  * Everything starting with "REPOSITORY_DOOR" or "repository_door" belongs
79  * to the global protocol.
80  *
81  * 2.1. Global requests
82  * --------------------
83  *
84  * REQUEST_CONNECT(rdr_flags, ...) -> result, [new_door]
85  *	Request a new Client door.  rdr_flags determines attributes of the
86  *	connection:
87  *
88  *	    FLAG_DEBUG
89  *		Sets connection debugging flags to those in rdr_debug.
90  *
91  *	The new door is returned with DOOR_RELEASE set, so if the client does
92  *	not recieve the response, the new door will recieve an unref
93  *	notification.  This makes this request idempotent.
94  *
95  * 2.2. Global reponse codes
96  * -------------------------
97  * GLXXX: This needs to be thought through.
98  *
99  * SUCCESS
100  * FAIL_BAD_REQUEST
101  * FAIL_VERSION_MISMATCH
102  * FAIL_BAD_FLAG
103  * FAIL_BAD_USER
104  * FAIL_NO_RESOURCES
105  *
106  * 3. The Client protocol
107  * ----------------------
108  * Everything starting with "REP_PROTOCOL" or "rep_protocol" belongs to the
109  * client protocol.
110  *
111  * 3.1. Techniques used
112  * --------------------
113  * 3.1.1. Client-controlled identifiers
114  *
115  * An idiom the protocol uses to lower the number of round trips is
116  * client-controlled identifiers.  The basic idea is this:  whenever a
117  * client wants to set up and use a piece of server state, it picks an
118  * integer *which it knows is not in use* to identify it.  The server then
119  * maintains per-client, per-resource id->resource maps.  This has a number
120  * of advantages:
121  *
122  * 1.	Since the client allocates the identifiers, we don't need to do
123  *	a round-trip just to allocate a number.
124  *
125  * 2.	Since it is the client's job to make sure identifiers don't collide,
126  *	idempotency for setup (destroy) are simple:  If the identifier
127  *	already exists (does not exist), we just return success.
128  *
129  * 3.	Since the identifiers are per-client, the design automatically
130  *	precludes clients being able to manipulate other client's state.
131  *
132  * 3.1.2 Sequence numbers
133  *
134  * A standard way of gaining idempotency is introducing sequence numbers.
135  * These are simply integers which get incremented at points in the protocol,
136  * and make sure the client and server are in sync.
137  *
138  * In this protocol, we use sequence numbers for requests (like ITER_READ)
139  * which are repeated, returning different data each time.  Since requests
140  * can also be repeated due to unreliable dispatch, the client increments
141  * the sequence number after every successful request.  This allows the server
142  * to differentiate the two cases. (note that this means that failing
143  * requests have no side effects and are repeatable)
144  *
145  * 3.2. Client abstractions
146  * ------------------------
147  * 3.2.1 Entities
148  *
149  * An "entity" is a typed register which the client can manipulate.
150  * Entities are named in the protocol by client-controlled identifiers.
151  * They have a fixed type for their entire lifetime, and may be in one
152  * of two states:
153  *
154  * valid
155  *	The entity has a valid value, and may be read from.  This state
156  *	is reached by a successful write to the entity by some protocol
157  *	step.
158  *
159  * invalid
160  *	The entity does not contain a valid value.  There are a number
161  *	of ways to reach this state:
162  *
163  *	1.  The entity was just created.
164  *	2.  The underlying object that this entity refers to was destroyed.
165  *	3.  A protocol request which would have modified this entity
166  *	    failed.
167  *
168  * An entity is an element in the tree of repository data.  Every entity
169  * (except for the most distant SCOPE) has exactly one parent.  Entities
170  * can have multiple children of different types, restricted by its base
171  * type.
172  *
173  * The ENTITY_GET call is used to get the root of the tree (the most local
174  * scope)
175  *
176  * 3.2.2. The entity tree
177  * ----------------------
178  * The structure of a scope is as follows:
179  *
180  *	 _______
181  *	| SCOPE |
182  *	|_______|
183  *	    \ .
184  *	     \ .
185  *	      \_________
186  *	      | SERVICE |
187  *	      |_________|
188  *		/.    \ .
189  *	       /.      \ .
190  *	  ____/		\__________
191  *	 | PG |		| INSTANCE |
192  *	 |____|		|__________|
193  *			  /.	 \ .
194  *			 /.	  \ .
195  *		    ____/	   \__________
196  *		   | PG |	   | SNAPSHOT |
197  *		   |____|	   |__________|
198  *					\ .
199  *					 \ .
200  *					  \___________
201  *					  | SNAPLEVEL |
202  *					  |___________|
203  *					     /.
204  *					    /.
205  *				       ____/
206  *				      | PG |
207  *				      |____|
208  *
209  * Where the dots indicate an arbitrary number (including 0) of children.
210  *
211  * For a given scope, the next scope (in the sense of distance) is its
212  * TYPE_SCOPE parent.  The furthest out scope has no parent.
213  *
214  * 3.2.2 Iterators
215  *
216  * GLXXX
217  *
218  * 3.3. Client requests
219  * --------------------
220  *
221  * CLOSE() -> result
222  *	Closes the connection, revoking the door.  After this call completes,
223  *	no further calls will succeed.
224  *
225  * ENTITY_SETUP(entity_id, type) -> result
226  *	Sets up an entity, identified by entity_id, to identify a single
227  *	<type>.  <type> may not be TYPE_NONE.
228  *
229  * ENTITY_NAME(entity_id, name_type) -> result, name
230  *	Returns the name of entity_id.  name_type determines which type of
231  *	name to get.
232  *
233  * ENTITY_PARENT_TYPE(entity_id) -> result, parent_type
234  *	Retrieves the type of entity_id's parent
235  *
236  * ENTITY_GET_CHILD(entity_id, child_id, name) -> result
237  *	Puts entity_id's child (of child_id's type) named 'name' into child_id.
238  *
239  * ENTITY_GET_PARENT(entity_id, out_id) -> result
240  *	Puts entity_id's parent into out_id.
241  *
242  * ENTITY_GET(entity_id, number) -> result
243  *	Makes entity_id point to a particular object.  If any error
244  *	occurs, dest_id will be invalid.
245  *
246  * ENTITY_UPDATE(entity_id, changeid) -> result
247  *	Updates the entity to pick up any new changes.
248  *
249  * ENTITY_CREATE_CHILD(entity_id, type, name, child_id, changeid) -> result
250  *	Attaches the object of type /type/ in child_id as the child of
251  *	entity_id named 'name'.
252  *
253  * ENTITY_CREATE_PG(entity_id, name, type, flags, child_id, changeid) -> result
254  *	Creates a property group child of entity_id named 'name', type 'type'
255  *	and flags 'flags', and puts the resulting object in child_id.
256  *
257  * ENTITY_DELETE(entity_id, changeid) -> result
258  *	Deletes the entity represented by entity_id.
259  *
260  * ENTITY_RESET(entity_id) -> result
261  *	Resets the entity.
262  *
263  * ENTITY_TEARDOWN(entity_id) -> result
264  *	Destroys the entity entity_id.
265  *
266  * ITER_SETUP(iter_id) -> result
267  *	Sets up an iterator id.
268  *
269  * ITER_START(iter_id, entity_id, itertype, flags, pattern) -> result
270  *	Sets up an iterator, identified by iter_id, which will iterate the
271  *	<itertype> children of entity_id whose names match 'pattern',
272  *	with the matching controlled by flags.  Initializing an iterator
273  *	counts as the first sequence number (1).
274  *
275  * ITER_READ(iter_id, sequence, entity_id) -> result
276  *	Retrieves the next element of iterator iter_id.  Sequence starts at 2,
277  *	and is incremented by the client after each successful iteration.
278  *	The result is written to entity_id, which must be of the same type
279  *	as the iterator result.  The iterator must not be iterating values.
280  *
281  * ITER_READ_VALUE(iter_id, sequence) -> result, type, value
282  *	Retrieves the next value for iterator iter_id.  Sequence starts at 2,
283  *	and is incremented by the client after each successful iteration.
284  *	The iterator must be iterating a property's values.
285  *
286  * ITER_RESET(iter_id) -> result
287  *	Throws away any accumulated state.
288  *
289  * ITER_TEARDOWN(iter_id) -> result
290  *	Destroys the iterator iter_id.
291  *
292  * NEXT_SNAPLEVEL(entity_src, entity_dst) -> result
293  *	If entity_src is a snapshot, set entity_dst to the first snaplevel
294  *	in it.  If entity_src is a snaplevel, set entity_dst to the next
295  *	snaplevel, or fail if there isn't one.
296  *
297  * SNAPSHOT_TAKE(entity_id, name, dest_id, flags) -> result
298  *	Takes a snapshot of entity_id, creating snaplevels for the instance and
299  *	its parent service.  If flags is REP_SNAPSHOT_NEW, a new snapshot named
300  *	'name' is created as a child of entity_id, dest_id is pointed to it,
301  *	and the new snaplevels are attached to it.  If flags is
302  *	REP_SNAPSHOT_ATTACH, name must be empty, and the new snaplevels are
303  *	attached to the snapshot dest_id points to.
304  *
305  * SNAPSHOT_TAKE_NAMED(entity_id, instname, svcname, name, dest_id) -> result
306  *	Like SNAPSHOT_TAKE, but always acts as if REP_SNAPSHOT_NEW is
307  *	specified, and instname and svcname override the actual service and
308  *	instance names, respectively, written into the snaplevels.
309  *
310  *	Note that this is only useful for writing snapshots which will later
311  *	be transferred to another instance (svc:/svcname:instname/)
312  *
313  * SNAPSHOT_ATTACH(source_id, dest_id) -> result
314  *	The snaplevels attached to the snapshot referenced by source_id are
315  *	attached to the snapshot dest_id is pointed at.
316  *
317  * PROPERTY_GET_TYPE(entity_id) -> result, value type
318  *	Finds the value type of entity_id, which must be a property.
319  *
320  * PROPERTY_GET_VALUE(entity_id) -> result, type, value
321  *	If the property contains a single value, returns it and its type.
322  *
323  * PROPERTYGRP_SETUP_WAIT(entity_id) -> result, [pipe fd]
324  *	Sets up a notification for changes to the object entity_id currently
325  *	references.  On success, returns one side of a pipe -- when there
326  *	has been a change (or the daemon dies), the other end of the pipe will
327  *	be closed.
328  *
329  *	Only one of these can be set up per client -- attempts to set up more
330  *	than one will cause the previous one to get closed.
331  *
332  * PROPERTYGRP_TX_START(entity_id_tx, entity_id) -> result
333  *	Makes entity_id_tx point to the same property group as entity_id,
334  *	then attempts to set up entity_id_tx as a transaction on that group.
335  *	entity_id and entity_id_tx must be distinct.  On failure, entity_id_tx
336  *	is reset.
337  *
338  * PROPERTYGRP_TX_COMMIT(entity_id, data) -> result
339  *	Gives the actual steps to follow, and attempts to commit them.
340  *
341  * CLIENT_ADD_NOTIFY(type, pattern) -> result
342  *	Adds a new property group name or type pattern to the notify list
343  *	(see CLIENT_WAIT).  If successful, takes effect immediately.
344  *
345  * CLIENT_WAIT(entity_id) -> result, fmri
346  *	Waits for a change to a propertygroup that matches the patterns
347  *	set up using CLIENT_ADD_NOTIFY, and puts the resultant propertygroup
348  *	in entity_id.  Note that if an error occurs, you can loose
349  *	notifications.  Either entity_id is set to a changed propertygroup,
350  *	or fmri is a non-zero-length string identifying a deleted thing.
351  *
352  * BACKUP(name) -> result
353  *	Backs up the persistant repository with a particular name.
354  *
355  * SET_ANNOTATION(operation, file)
356  *	Set up a security audit annotation event.  operation is the name of
357  *	the operation that is being annotated, and file is the file being
358  *	processed.  This will be used to mark operations which comprise
359  *	multiple primitive operations such as svccfg import.
360  *
361  * SWITCH(flag) -> result
362  *	The flag is used to indicate the direction of the switch operation.
363  *	When the flag is set to 'fast', move the main repository from the
364  *	default location (/etc/svc) to the tmpfs locationa (/etc/svc/volatile).
365  *	When it is set to 'perm', the switch is reversed.
366  */
367 
368 #include <door.h>
369 #include <stddef.h>
370 #include <sys/sysmacros.h>
371 
372 #ifdef	__cplusplus
373 extern "C" {
374 #endif
375 
376 /*
377  * svc.configd initial protocol details
378  */
379 #define	REPOSITORY_DOOR_BASEVER	(('R' << 24) | ('e' << 16) | ('p' << 8))
380 #define	REPOSITORY_DOOR_NAME	"/etc/svc/volatile/repository_door"
381 #define	REPOSITORY_DOOR_COOKIE	((void *)REPOSITORY_DOOR_BASEVER)
382 
383 #define	REPOSITORY_BOOT_BACKUP	((const char *)"boot")
384 
385 /*
386  * This value should be incremented any time the protocol changes.  When in
387  * doubt, bump it.
388  */
389 #define	REPOSITORY_DOOR_VERSION			(21 + REPOSITORY_DOOR_BASEVER)
390 
391 /*
392  * flags for rdr_flags
393  */
394 #define	REPOSITORY_DOOR_FLAG_DEBUG		0x00000001	/* rdr_debug */
395 
396 #define	REPOSITORY_DOOR_FLAG_ALL		0x00000001	/* all flags */
397 
398 /*
399  * Request IDs
400  */
401 enum repository_door_requestid {
402 	REPOSITORY_DOOR_REQUEST_CONNECT = (('M' << 8) | 1)
403 };
404 
405 enum repository_door_statusid {
406 	REPOSITORY_DOOR_SUCCESS			= 0,
407 	REPOSITORY_DOOR_FAIL_BAD_REQUEST	= 1,
408 	REPOSITORY_DOOR_FAIL_VERSION_MISMATCH	= 2,
409 	REPOSITORY_DOOR_FAIL_BAD_FLAG		= 3,
410 	REPOSITORY_DOOR_FAIL_NO_RESOURCES	= 4,
411 	REPOSITORY_DOOR_FAIL_PERMISSION_DENIED	= 5
412 };
413 
414 /*
415  * You may only add elements to the end of this structure.
416  */
417 typedef struct repository_door_request {
418 	uint32_t rdr_version;			/* must be first element */
419 	enum repository_door_requestid rdr_request;
420 	uint32_t rdr_flags;
421 	uint32_t rdr_debug;
422 } repository_door_request_t;
423 
424 typedef struct repository_door_response {
425 	enum repository_door_statusid rdr_status;
426 } repository_door_response_t;
427 
428 /*
429  * Client interface.  Used on doors returned by REQUEST_CONNECT
430  */
431 
432 #define	REP_PROTOCOL_NAME_LEN		120	/* maximum name length */
433 #define	REP_PROTOCOL_VALUE_LEN		4096	/* maximum value length */
434 
435 #define	REP_PROTOCOL_FMRI_LEN		(6 * REP_PROTOCOL_NAME_LEN)
436 
437 #define	REP_PROTOCOL_BASE		('C' << 8)
438 
439 /*
440  * Request codes
441  */
442 enum rep_protocol_requestid {
443 	REP_PROTOCOL_CLOSE		= REP_PROTOCOL_BASE,
444 
445 	REP_PROTOCOL_ENTITY_SETUP,
446 	REP_PROTOCOL_ENTITY_NAME,
447 	REP_PROTOCOL_ENTITY_PARENT_TYPE,
448 	REP_PROTOCOL_ENTITY_GET_CHILD,
449 	REP_PROTOCOL_ENTITY_GET_PARENT,
450 	REP_PROTOCOL_ENTITY_GET,
451 	REP_PROTOCOL_ENTITY_UPDATE,
452 	REP_PROTOCOL_ENTITY_CREATE_CHILD,
453 	REP_PROTOCOL_ENTITY_CREATE_PG,
454 	REP_PROTOCOL_ENTITY_DELETE,
455 	REP_PROTOCOL_ENTITY_RESET,
456 	REP_PROTOCOL_ENTITY_TEARDOWN,
457 
458 	REP_PROTOCOL_ITER_SETUP,
459 	REP_PROTOCOL_ITER_START,
460 	REP_PROTOCOL_ITER_READ,
461 	REP_PROTOCOL_ITER_READ_VALUE,
462 	REP_PROTOCOL_ITER_RESET,
463 	REP_PROTOCOL_ITER_TEARDOWN,
464 
465 	REP_PROTOCOL_NEXT_SNAPLEVEL,
466 
467 	REP_PROTOCOL_SNAPSHOT_TAKE,
468 	REP_PROTOCOL_SNAPSHOT_TAKE_NAMED,
469 	REP_PROTOCOL_SNAPSHOT_ATTACH,
470 
471 	REP_PROTOCOL_PROPERTY_GET_TYPE,
472 	REP_PROTOCOL_PROPERTY_GET_VALUE,
473 
474 	REP_PROTOCOL_PROPERTYGRP_SETUP_WAIT,
475 	REP_PROTOCOL_PROPERTYGRP_TX_START,
476 	REP_PROTOCOL_PROPERTYGRP_TX_COMMIT,
477 
478 	REP_PROTOCOL_CLIENT_ADD_NOTIFY,
479 	REP_PROTOCOL_CLIENT_WAIT,
480 
481 	REP_PROTOCOL_BACKUP,
482 
483 	REP_PROTOCOL_SET_AUDIT_ANNOTATION,
484 
485 	REP_PROTOCOL_SWITCH,
486 
487 	REP_PROTOCOL_MAX_REQUEST
488 };
489 
490 /*
491  * Response codes.  These are returned to the client, and the errors are
492  * translated into scf_error_t's by libscf (see proto_error()).
493  */
494 typedef int32_t rep_protocol_responseid_t;
495 enum rep_protocol_responseid {
496 	REP_PROTOCOL_SUCCESS =			0,
497 	/* iterators: No more values. */
498 	REP_PROTOCOL_DONE =			1,
499 
500 	/* Request from client was malformed. */
501 	REP_PROTOCOL_FAIL_BAD_REQUEST =		-1,
502 	/* Prerequisite call has not been made. */
503 	REP_PROTOCOL_FAIL_MISORDERED =		-2,
504 	/* Register for ID has not been created. */
505 	REP_PROTOCOL_FAIL_UNKNOWN_ID =		-3,
506 	/* Out of memory or other resource. */
507 	REP_PROTOCOL_FAIL_NO_RESOURCES =	-4,
508 	/* Type argument is invalid. */
509 	REP_PROTOCOL_FAIL_INVALID_TYPE =	-5,
510 	/* Requested object does not exist. */
511 	REP_PROTOCOL_FAIL_NOT_FOUND =		-6,
512 	/* Register for given ID does not point to an object. */
513 	REP_PROTOCOL_FAIL_NOT_SET =		-7,
514 
515 	/* Requested name is longer than supplied buffer. */
516 	REP_PROTOCOL_FAIL_TRUNCATED =		-8,
517 	/* Operation requires different type. */
518 	REP_PROTOCOL_FAIL_TYPE_MISMATCH =	-9,
519 
520 	/* Changeable object has been changed since last update. */
521 	REP_PROTOCOL_FAIL_NOT_LATEST =		-10,
522 	/* Creation failed because object with given name exists. */
523 	REP_PROTOCOL_FAIL_EXISTS =		-11,
524 	/* Transaction is invalid. */
525 	REP_PROTOCOL_FAIL_BAD_TX =		-12,
526 	/* Operation is not applicable to indicated object. */
527 	REP_PROTOCOL_FAIL_NOT_APPLICABLE =	-13,
528 	/* Two IDs for operation were unexpectedly equal. */
529 	REP_PROTOCOL_FAIL_DUPLICATE_ID =	-14,
530 
531 	/* Permission denied. */
532 	REP_PROTOCOL_FAIL_PERMISSION_DENIED =	-15,
533 	/* Backend does not exist or otherwise refused access. */
534 	REP_PROTOCOL_FAIL_BACKEND_ACCESS =	-16,
535 	/* Backend is read-only. */
536 	REP_PROTOCOL_FAIL_BACKEND_READONLY =	-17,
537 
538 	/* Object has been deleted. */
539 	REP_PROTOCOL_FAIL_DELETED =		-18,
540 
541 	REP_PROTOCOL_FAIL_UNKNOWN =		-0xfd
542 };
543 
544 /*
545  * Types
546  */
547 typedef enum rep_protocol_entity {
548 	REP_PROTOCOL_ENTITY_NONE,
549 	REP_PROTOCOL_ENTITY_SCOPE,
550 	REP_PROTOCOL_ENTITY_SERVICE,
551 	REP_PROTOCOL_ENTITY_INSTANCE,
552 	REP_PROTOCOL_ENTITY_SNAPSHOT,
553 	REP_PROTOCOL_ENTITY_SNAPLEVEL,
554 	REP_PROTOCOL_ENTITY_PROPERTYGRP,
555 	REP_PROTOCOL_ENTITY_CPROPERTYGRP,	/* "composed" property group */
556 	REP_PROTOCOL_ENTITY_PROPERTY,
557 	REP_PROTOCOL_ENTITY_VALUE,
558 
559 	REP_PROTOCOL_ENTITY_MAX
560 } rep_protocol_entity_t;
561 
562 typedef enum rep_protocol_value_type {
563 	REP_PROTOCOL_TYPE_INVALID	= '\0',
564 	REP_PROTOCOL_TYPE_BOOLEAN	= 'b',
565 	REP_PROTOCOL_TYPE_COUNT		= 'c',
566 	REP_PROTOCOL_TYPE_INTEGER	= 'i',
567 	REP_PROTOCOL_TYPE_TIME		= 't',
568 	REP_PROTOCOL_TYPE_STRING	= 's',
569 	REP_PROTOCOL_TYPE_OPAQUE	= 'o',
570 
571 	REP_PROTOCOL_SUBTYPE_USTRING	= REP_PROTOCOL_TYPE_STRING|('u' << 8),
572 	REP_PROTOCOL_SUBTYPE_URI	= REP_PROTOCOL_TYPE_STRING|('U' << 8),
573 	REP_PROTOCOL_SUBTYPE_FMRI	= REP_PROTOCOL_TYPE_STRING|('f' << 8),
574 
575 	REP_PROTOCOL_SUBTYPE_HOST	= REP_PROTOCOL_TYPE_STRING|('h' << 8),
576 	REP_PROTOCOL_SUBTYPE_HOSTNAME	= REP_PROTOCOL_TYPE_STRING|('N' << 8),
577 	REP_PROTOCOL_SUBTYPE_NETADDR	= REP_PROTOCOL_TYPE_STRING|('n' << 8),
578 	REP_PROTOCOL_SUBTYPE_NETADDR_V4	= REP_PROTOCOL_TYPE_STRING|('4' << 8),
579 	REP_PROTOCOL_SUBTYPE_NETADDR_V6	= REP_PROTOCOL_TYPE_STRING|('6' << 8)
580 } rep_protocol_value_type_t;
581 
582 
583 #define	REP_PROTOCOL_BASE_TYPE(t)	((t) & 0x00ff)
584 #define	REP_PROTOCOL_SUBTYPE(t)		(((t) & 0xff00) >> 8)
585 
586 /*
587  * Request structures
588  */
589 typedef struct rep_protocol_request {
590 	enum rep_protocol_requestid rpr_request;
591 } rep_protocol_request_t;
592 
593 struct rep_protocol_iter_request {
594 	enum rep_protocol_requestid rpr_request;
595 	uint32_t rpr_iterid;
596 };
597 
598 struct rep_protocol_iter_start {
599 	enum rep_protocol_requestid rpr_request;	/* ITER_START */
600 	uint32_t rpr_iterid;
601 
602 	uint32_t rpr_entity;
603 	uint32_t rpr_itertype;
604 	uint32_t rpr_flags;
605 	char	rpr_pattern[REP_PROTOCOL_NAME_LEN];
606 };
607 #define	RP_ITER_START_ALL	0x00000001	/* ignore pattern, match all */
608 #define	RP_ITER_START_EXACT	0x00000002	/* exact match with pattern */
609 #define	RP_ITER_START_PGTYPE	0x00000003	/* exact match pg type */
610 #define	RP_ITER_START_FILT_MASK	0x00000003
611 #define	RP_ITER_START_COMPOSED	0x00000004	/* composed */
612 
613 struct rep_protocol_iter_read {
614 	enum rep_protocol_requestid rpr_request;	/* ITER_READ */
615 	uint32_t rpr_iterid;
616 	uint32_t rpr_sequence;		/* client increments upon success */
617 	uint32_t rpr_entityid;		/* entity to write result to */
618 };
619 
620 struct rep_protocol_iter_read_value {
621 	enum rep_protocol_requestid rpr_request;	/* ITER_READ_VALUE */
622 	uint32_t rpr_iterid;
623 	uint32_t rpr_sequence;		/* client increments upon success */
624 };
625 
626 struct rep_protocol_entity_setup {
627 	enum rep_protocol_requestid rpr_request;	/* ENTITY_SETUP */
628 	uint32_t rpr_entityid;
629 	uint32_t rpr_entitytype;
630 };
631 
632 struct rep_protocol_entity_name {
633 	enum rep_protocol_requestid rpr_request;	/* ENTITY_NAME */
634 	uint32_t rpr_entityid;
635 	uint32_t rpr_answertype;
636 };
637 #define	RP_ENTITY_NAME_NAME			0
638 #define	RP_ENTITY_NAME_PGTYPE			1
639 #define	RP_ENTITY_NAME_PGFLAGS			2
640 #define	RP_ENTITY_NAME_SNAPLEVEL_SCOPE		3
641 #define	RP_ENTITY_NAME_SNAPLEVEL_SERVICE	4
642 #define	RP_ENTITY_NAME_SNAPLEVEL_INSTANCE	5
643 #define	RP_ENTITY_NAME_PGREADPROT		6
644 
645 struct rep_protocol_entity_update {
646 	enum rep_protocol_requestid rpr_request;	/* ENTITY_UPDATE */
647 	uint32_t rpr_entityid;
648 	uint32_t rpr_changeid;
649 };
650 
651 struct rep_protocol_entity_parent_type {
652 	enum rep_protocol_requestid rpr_request;	/* ENTITY_PARENT_TYPE */
653 	uint32_t rpr_entityid;
654 };
655 
656 struct rep_protocol_entity_parent {
657 	enum rep_protocol_requestid rpr_request;	/* ENTITY_GET_PARENT */
658 	uint32_t rpr_entityid;
659 	uint32_t rpr_outid;
660 };
661 
662 struct rep_protocol_entity_get {
663 	enum rep_protocol_requestid rpr_request;	/* ENTITY_SET */
664 	uint32_t rpr_entityid;
665 	uint32_t rpr_object;
666 };
667 #define	RP_ENTITY_GET_INVALIDATE	1
668 #define	RP_ENTITY_GET_MOST_LOCAL_SCOPE	2
669 
670 struct rep_protocol_entity_create_child {
671 	enum rep_protocol_requestid rpr_request; /* ENTITY_CREATE_CHILD */
672 	uint32_t rpr_entityid;
673 	uint32_t rpr_childtype;
674 	uint32_t rpr_childid;
675 	uint32_t rpr_changeid;
676 	char	rpr_name[REP_PROTOCOL_NAME_LEN];
677 };
678 
679 struct rep_protocol_entity_create_pg {
680 	enum rep_protocol_requestid rpr_request; /* ENTITY_CREATE_PG */
681 	uint32_t rpr_entityid;
682 	uint32_t rpr_childtype;
683 	uint32_t rpr_childid;
684 	uint32_t rpr_changeid;
685 	char	rpr_name[REP_PROTOCOL_NAME_LEN];
686 	char	rpr_type[REP_PROTOCOL_NAME_LEN];
687 	uint32_t rpr_flags;
688 };
689 
690 struct rep_protocol_entity_get_child {
691 	enum rep_protocol_requestid rpr_request;	/* ENTITY_GET_CHILD */
692 	uint32_t rpr_entityid;
693 	uint32_t rpr_childid;
694 	char	rpr_name[REP_PROTOCOL_NAME_LEN];
695 };
696 
697 struct rep_protocol_entity_delete {
698 	enum rep_protocol_requestid rpr_request; /* ENTITY_DELETE_CHILD */
699 	uint32_t rpr_entityid;
700 	uint32_t rpr_changeid;
701 };
702 
703 struct rep_protocol_entity_reset {
704 	enum rep_protocol_requestid rpr_request;	/* ENTITY_NAME */
705 	uint32_t rpr_entityid;
706 };
707 
708 struct rep_protocol_entity_request {
709 	enum rep_protocol_requestid rpr_request;	/* ENTITY_NAME */
710 	uint32_t rpr_entityid;
711 };
712 
713 struct rep_protocol_entity_teardown {
714 	enum rep_protocol_requestid rpr_request;	/* ENTITY_TEARDOWN */
715 	uint32_t rpr_entityid;
716 };
717 
718 struct rep_protocol_entity_pair {
719 	enum rep_protocol_requestid rpr_request;	/* NEXT_SNAPLEVEL */
720 	uint32_t rpr_entity_src;
721 	uint32_t rpr_entity_dst;
722 };
723 
724 struct rep_protocol_transaction_start {
725 	enum rep_protocol_requestid rpr_request;	/* TX_SETUP */
726 	uint32_t rpr_entityid_tx;		/* property group tx entity */
727 	uint32_t rpr_entityid;			/* property group entity */
728 };
729 
730 struct rep_protocol_transaction_commit {
731 	enum rep_protocol_requestid rpr_request; /* TX_COMMIT */
732 	uint32_t rpr_entityid;
733 	uint32_t rpr_size;			/* size of entire structure */
734 	uint8_t rpr_cmd[1];
735 };
736 
737 #define	REP_PROTOCOL_TRANSACTION_COMMIT_SIZE(sz) \
738 	    (offsetof(struct rep_protocol_transaction_commit, rpr_cmd[sz]))
739 
740 #define	REP_PROTOCOL_TRANSACTION_COMMIT_MIN_SIZE \
741 	    REP_PROTOCOL_TRANSACTION_COMMIT_SIZE(0)
742 
743 enum rep_protocol_transaction_action {
744 	REP_PROTOCOL_TX_ENTRY_INVALID,	/* N/A */
745 	REP_PROTOCOL_TX_ENTRY_NEW,	/* new property */
746 	REP_PROTOCOL_TX_ENTRY_CLEAR,	/* clear old property */
747 	REP_PROTOCOL_TX_ENTRY_REPLACE,	/* change type of old property */
748 	REP_PROTOCOL_TX_ENTRY_DELETE	/* delete property (no values) */
749 };
750 
751 struct rep_protocol_transaction_cmd {
752 	enum	rep_protocol_transaction_action rptc_action;
753 	uint32_t rptc_type;
754 	uint32_t rptc_size;		/* size of entire structure */
755 	uint32_t rptc_name_len;
756 	uint8_t	rptc_data[1];
757 };
758 
759 #define	REP_PROTOCOL_TRANSACTION_CMD_SIZE(sz) \
760 	    (offsetof(struct rep_protocol_transaction_cmd, rptc_data[sz]))
761 
762 #define	REP_PROTOCOL_TRANSACTION_CMD_MIN_SIZE \
763 	    REP_PROTOCOL_TRANSACTION_CMD_SIZE(0)
764 
765 #define	TX_SIZE(x)	P2ROUNDUP((x), sizeof (uint32_t))
766 
767 struct rep_protocol_transaction_request {
768 	enum rep_protocol_requestid rpr_request; /* SETUP, ABORT or TEARDOWN */
769 	uint32_t rpr_txid;
770 };
771 
772 struct rep_protocol_property_request {
773 	enum rep_protocol_requestid rpr_request;
774 	uint32_t rpr_entityid;
775 };
776 
777 struct rep_protocol_propertygrp_request {
778 	enum rep_protocol_requestid rpr_request;
779 	uint32_t rpr_entityid;
780 };
781 
782 struct rep_protocol_notify_request {
783 	enum rep_protocol_requestid rpr_request;
784 	uint32_t rpr_type;
785 	char	rpr_pattern[REP_PROTOCOL_NAME_LEN];
786 };
787 #define	REP_PROTOCOL_NOTIFY_PGNAME 1
788 #define	REP_PROTOCOL_NOTIFY_PGTYPE 2
789 
790 struct rep_protocol_wait_request {
791 	enum rep_protocol_requestid rpr_request;
792 	uint32_t rpr_entityid;
793 };
794 
795 struct rep_protocol_snapshot_take {
796 	enum rep_protocol_requestid rpr_request;	/* SNAPSHOT_TAKE */
797 	uint32_t rpr_entityid_src;
798 	uint32_t rpr_entityid_dest;
799 	int	rpr_flags;
800 	char	rpr_name[REP_PROTOCOL_NAME_LEN];
801 };
802 #define	REP_SNAPSHOT_NEW	0x00000001
803 #define	REP_SNAPSHOT_ATTACH	0x00000002
804 
805 struct rep_protocol_snapshot_take_named {
806 	enum rep_protocol_requestid rpr_request; /* SNAPSHOT_TAKE_NAMED */
807 	uint32_t rpr_entityid_src;
808 	uint32_t rpr_entityid_dest;
809 	char	rpr_svcname[REP_PROTOCOL_NAME_LEN];
810 	char	rpr_instname[REP_PROTOCOL_NAME_LEN];
811 	char	rpr_name[REP_PROTOCOL_NAME_LEN];
812 };
813 
814 struct rep_protocol_snapshot_attach {
815 	enum rep_protocol_requestid rpr_request;	/* SNAPSHOT_ATTACH */
816 	uint32_t rpr_entityid_src;
817 	uint32_t rpr_entityid_dest;
818 };
819 
820 struct rep_protocol_backup_request {
821 	enum rep_protocol_requestid rpr_request;	/* BACKUP */
822 	uint32_t rpr_changeid;
823 	char rpr_name[REP_PROTOCOL_NAME_LEN];
824 };
825 
826 struct rep_protocol_annotation {
827 	enum rep_protocol_requestid rpr_request;	/* SET_ANNOTATION */
828 	char rpr_operation[REP_PROTOCOL_NAME_LEN];
829 	char rpr_file[MAXPATHLEN];
830 };
831 
832 struct rep_protocol_switch_request {
833 	enum rep_protocol_requestid rpr_request;	/* SWITCH */
834 	uint32_t rpr_changeid;
835 	int rpr_flag;
836 };
837 
838 /*
839  * Response structures
840  */
841 typedef struct rep_protocol_response {
842 	rep_protocol_responseid_t rpr_response;
843 } rep_protocol_response_t;
844 
845 struct rep_protocol_integer_response {
846 	rep_protocol_responseid_t rpr_response;
847 	uint32_t rpr_value;
848 };
849 
850 struct rep_protocol_name_response {	/* response to ENTITY_NAME */
851 	rep_protocol_responseid_t rpr_response;
852 	char rpr_name[REP_PROTOCOL_NAME_LEN];
853 };
854 
855 struct rep_protocol_fmri_response {
856 	rep_protocol_responseid_t rpr_response;
857 	char rpr_fmri[REP_PROTOCOL_FMRI_LEN];
858 };
859 
860 struct rep_protocol_value_response {
861 	rep_protocol_responseid_t rpr_response;
862 	rep_protocol_value_type_t rpr_type;
863 	char			rpr_value[2 * REP_PROTOCOL_VALUE_LEN + 1];
864 };
865 
866 #ifdef	__cplusplus
867 }
868 #endif
869 
870 #endif	/* _REPCACHE_PROTOCOL_H */
871