[apple/xnu.git] / bsd / sys / kern_control.h

/*
 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */


#ifndef SYS_KERN_CONTROL_H
#define SYS_KERN_CONTROL_H

#include <sys/appleapiopts.h>

#ifdef __APPLE_API_UNSTABLE
/*
 * Define Controller event subclass, and associated events.
 */

/* Subclass of KEV_SYSTEM_CLASS */
#define KEV_CTL_SUBCLASS 	1

#define KEV_CTL_REGISTERED     	1	/* a new controller appears */
#define KEV_CTL_DEREGISTERED   	2	/* a controller disappears */

/* All KEV_CTL_SUBCLASS events share the same header */
struct ctl_event_data {
    u_int32_t 	ctl_id;
    u_int32_t 	ctl_unit;
};


/*
 * Controls destined to the Controller Manager.
 */

#define	CTLIOCGCOUNT	_IOR('N', 1, int)	/* get number of control structures registered */

/*
 * Controller address structure
 * used to establish contact between user client and kernel controller
 * sc_id/sc_unit uniquely identify each controller
 * sc_id is a 32-bit "signature" obtained by developers from Apple Computer
 * sc_unit is a unit number for this sc_id, and is privately used 
 * by the developper to identify several instances to control
 */

struct sockaddr_ctl
{
    u_char	sc_len;		/* sizeof(struct sockaddr_ctl) */
    u_char	sc_family;	/* AF_SYSTEM */
    u_int16_t 	ss_sysaddr; 	/* AF_SYS_CONTROL */
    u_int32_t 	sc_id; 		/* 32-bit "signature" managed by Apple */
    u_int32_t 	sc_unit;	/* Developer private unit number */
    u_int32_t 	sc_reserved[5];
};
#endif /* __APPLE_API_UNSTABLE */

#ifdef KERNEL
#ifdef __APPLE_API_UNSTABLE

/* Reference to a controller object */
typedef void * kern_ctl_ref;

/* Support flags for controllers */
#define CTL_FLAG_PRIVILEGED	0x1	/* user must be root to contact controller */

/* Data flags for controllers */
#define CTL_DATA_NOWAKEUP	0x1	/* don't wake up client yet */


/*
 * Controller registration structure, given at registration time
 */
struct kern_ctl_reg
{
    /* control information */
    u_int32_t	ctl_id;			/* unique id of the controller, provided by DTS */
    u_int32_t	ctl_unit;		/* unit number for the controller, for the specified id */
                                        /* a controller can be registered several times with the same id */
                                        /* but must have a different unit number */
                                        
    /* control settings */
    u_int32_t	ctl_flags;		/* support flags */
    u_int32_t	ctl_sendsize;		/* override send/receive buffer size */
    u_int32_t	ctl_recvsize;		/* 0 = use default values */

    /* Dispatch functions */

    int 	(*ctl_connect)
                    (kern_ctl_ref ctlref, void *userdata);
                                        /* Make contact, called when user client calls connect */
                                        /* the socket with the id/unit of the controller */

    void 	(*ctl_disconnect)
                    (kern_ctl_ref ctlref, void *userdata);
                                        /* Break contact, called when user client */
                                        /* closes the control socket */
                    
    int 	(*ctl_write)		
                    (kern_ctl_ref ctlref, void *userdata, struct mbuf *m);
                                        /* Send data to the controller, called when user client */
                                        /* writes data to the socket */
                                        
    int 	(*ctl_set)		
                    (kern_ctl_ref ctlref, void *userdata, int opt, void *data, size_t len);
                                        /* set controller configuration, called when user client */
                                        /* calls setsockopt() for the socket */
                                        /* opt is the option number */
                                        /* data points to the data, already copied in kernel space */
                                        /* len is the lenght of the data buffer */

    int 	(*ctl_get)
                    (kern_ctl_ref ctlref, void *userdata, int opt, void *data, size_t *len);
                                        /* get controller configuration, called when user client */
                                        /* calls getsockopt() for the socket */
                                        /* opt is the option number */
                                        /* data points to the data buffer of max lenght len */
                                        /* the controller can directly copy data in the buffer space */
                                        /* and does not need to worry about copying out the data */
                                        /* as long as it respects the max buffer lenght */
                                        /* on input, len contains the maximum buffer length */
                                        /* on output, len contains the actual buffer lenght */
                                        /* if data is NULL on input, then, by convention, the controller */
                                        /* should return in len the lenght of the data it would like */
                                        /* to return in the subsequent call for that option */

    /* prepare the future */
    u_int32_t	ctl_reserved[4];	/* for future use if needed */
};


/* 
 * FUNCTION :
 * Register the controller to the controller manager
 * For example, can be called from a Kernel Extension Start routine
 * 
 * PARAMETERS :
 * userctl : 	Registration structure containing control information
 *          	and callback functions for the controller. 
 *         	Callbacks are optional and can be null.
 *         	A controller with all callbacks set to null would not be very useful.
 * userdata : 	This parameter is for use by the controller and 
 *         	will be passed to every callback function
 * 
 * RETURN CODE :
 * 0 : 		No error
 *     		ctlref will be filled with a control reference, 
 * 		to use in subsequent call to the controller manager
 * EINVAL : 	Invalid registration structure
 * ENOMEM : 	Not enough memory available to register the controller
 * EEXIST : 	Controller id/unit already registered
 */
 
int
ctl_register(struct kern_ctl_reg *userctl, void *userdata, kern_ctl_ref *ctlref);	

/*
 * FUNCTION :
 * Deregister the controller
 * For example, can be called from a Kernel Extension Stop routine
 * 
 * PARAMETERS :
 * ctlref : 	Reference to the controller previously registered
 *
 * RETURN CODE :
 * 0 : 		No error, 
 * 		The controller manager no longer knows about the controller
 * EINVAL : 	Invalid reference
 */
 
int 
ctl_deregister(kern_ctl_ref ctlref);	

/*
 * FUNCTION :
 * Send data to the application in contact with the controller
 * ctl_enqueuedata will allocate a mbuf, copy data and enqueue it.
 *
 * PARAMETERS :
 * ctlref : 	Reference to the controller previously registered
 * data : 	Data to send
 * len : 	Length of the data (maximum lenght of MCLBYTES)
 * flags : 	Flags used when enqueing
 * 		CTL_DATA_NOWAKEUP = just enqueue, don't wake up client
 *
 * RETURN CODE :
 * 0 : 		No error
 * EINVAL: 	Invalid reference
 * EMSGSIZE: 	The buffer is too large
 * ENOTCONN : 	No user client is connected
 * ENOBUFS : 	Socket buffer is full, or can't get a new mbuf
 *              The controller should re-enqueue later
 */
 
int 
ctl_enqueuedata(kern_ctl_ref ctlref, void *data, size_t len, u_int32_t flags);

/*
 * FUNCTION :
 * Send data to the application in contact with the controller
 *
 * PARAMETERS :
 * ctlref : 	Reference to the controller previously registered
 * m : 		mbuf containing the data to send
 * flags : 	Flags used when enqueing
 * 		CTL_DATA_NOWAKEUP = just enqueue, don't wake up client
 *
 * RETURN CODE :
 * 0 : 		No error
 * EINVAL: 	Invalid reference
 * ENOTCONN : 	No user client is connected
 * ENOBUFS : 	Socket buffer is full, 
 *              The controller should either free the mbuf or re-enqueue later
 */
 
int 
ctl_enqueuembuf(kern_ctl_ref ctlref, struct mbuf *m, u_int32_t flags);

#endif /* __APPLE_API_UNSTABLE */
#endif /* KERNEL */

#endif /* SYS_KERN_CONTROL_H */
Commit	Line	Data
9bccf70c A	1	/*
	2	* Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
de355530 A	6	* The contents of this file constitute Original Code as defined in and
	7	* are subject to the Apple Public Source License Version 1.1 (the
	8	* "License"). You may not use this file except in compliance with the
	9	* License. Please obtain a copy of the License at
	10	* http://www.apple.com/publicsource and read it before using this file.
9bccf70c	11	*
de355530 A	12	* This Original Code and all software distributed under the License are
de355530 A	13	* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
9bccf70c A	14	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
9bccf70c A	15	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
de355530 A	16	* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	17	* License for the specific language governing rights and limitations
	18	* under the License.
9bccf70c A	19	*
	20	* @APPLE_LICENSE_HEADER_END@
	21	*/
	22
	23
	24	#ifndef SYS_KERN_CONTROL_H
	25	#define SYS_KERN_CONTROL_H
	26
	27	#include <sys/appleapiopts.h>
	28
	29	#ifdef __APPLE_API_UNSTABLE
	30	/*
	31	* Define Controller event subclass, and associated events.
	32	*/
	33
	34	/* Subclass of KEV_SYSTEM_CLASS */
	35	#define KEV_CTL_SUBCLASS 1
	36
	37	#define KEV_CTL_REGISTERED 1 /* a new controller appears */
	38	#define KEV_CTL_DEREGISTERED 2 /* a controller disappears */
	39
	40	/* All KEV_CTL_SUBCLASS events share the same header */
	41	struct ctl_event_data {
	42	u_int32_t ctl_id;
	43	u_int32_t ctl_unit;
	44	};
	45
	46
	47	/*
	48	* Controls destined to the Controller Manager.
	49	*/
	50
	51	#define CTLIOCGCOUNT _IOR('N', 1, int) /* get number of control structures registered */
	52
	53	/*
	54	* Controller address structure
	55	* used to establish contact between user client and kernel controller
	56	* sc_id/sc_unit uniquely identify each controller
	57	* sc_id is a 32-bit "signature" obtained by developers from Apple Computer
	58	* sc_unit is a unit number for this sc_id, and is privately used
	59	* by the developper to identify several instances to control
	60	*/
	61
	62	struct sockaddr_ctl
	63	{
	64	u_char sc_len; /* sizeof(struct sockaddr_ctl) */
	65	u_char sc_family; /* AF_SYSTEM */
	66	u_int16_t ss_sysaddr; /* AF_SYS_CONTROL */
	67	u_int32_t sc_id; /* 32-bit "signature" managed by Apple */
	68	u_int32_t sc_unit; /* Developer private unit number */
	69	u_int32_t sc_reserved[5];
	70	};
	71	#endif /* __APPLE_API_UNSTABLE */
	72
	73	#ifdef KERNEL
	74	#ifdef __APPLE_API_UNSTABLE
	75
	76	/* Reference to a controller object */
	77	typedef void * kern_ctl_ref;
	78
	79	/* Support flags for controllers */
	80	#define CTL_FLAG_PRIVILEGED 0x1 /* user must be root to contact controller */
	81
	82	/* Data flags for controllers */
83	#define CTL_DATA_NOWAKEUP 0x1 /* don't wake up client yet */
84
85
86	/*
87	* Controller registration structure, given at registration time
88	*/
89	struct kern_ctl_reg
90	{
91	/* control information */
92	u_int32_t ctl_id; /* unique id of the controller, provided by DTS */
93	u_int32_t ctl_unit; /* unit number for the controller, for the specified id */
94	/* a controller can be registered several times with the same id */
95	/* but must have a different unit number */
96
97	/* control settings */
98	u_int32_t ctl_flags; /* support flags */
99	u_int32_t ctl_sendsize; /* override send/receive buffer size */
100	u_int32_t ctl_recvsize; /* 0 = use default values */
101
102	/* Dispatch functions */
103
104	int (*ctl_connect)
105	(kern_ctl_ref ctlref, void *userdata);
106	/* Make contact, called when user client calls connect */
107	/* the socket with the id/unit of the controller */
108
109	void (*ctl_disconnect)
110	(kern_ctl_ref ctlref, void *userdata);
111	/* Break contact, called when user client */
112	/* closes the control socket */
113
114	int (*ctl_write)
115	(kern_ctl_ref ctlref, void userdata, struct mbuf m);
116	/* Send data to the controller, called when user client */
117	/* writes data to the socket */
118
119	int (*ctl_set)
120	(kern_ctl_ref ctlref, void userdata, int opt, void data, size_t len);
121	/* set controller configuration, called when user client */
122	/* calls setsockopt() for the socket */
123	/* opt is the option number */
124	/* data points to the data, already copied in kernel space */
125	/* len is the lenght of the data buffer */
126
127	int (*ctl_get)
128	(kern_ctl_ref ctlref, void userdata, int opt, void data, size_t *len);
129	/* get controller configuration, called when user client */
130	/* calls getsockopt() for the socket */
131	/* opt is the option number */
132	/* data points to the data buffer of max lenght len */
133	/* the controller can directly copy data in the buffer space */
134	/* and does not need to worry about copying out the data */
135	/* as long as it respects the max buffer lenght */
136	/* on input, len contains the maximum buffer length */
137	/* on output, len contains the actual buffer lenght */
138	/* if data is NULL on input, then, by convention, the controller */
139	/* should return in len the lenght of the data it would like */
140	/* to return in the subsequent call for that option */
141
142	/* prepare the future */
143	u_int32_t ctl_reserved[4]; /* for future use if needed */
144	};
145
146
147	/*
148	* FUNCTION :
149	* Register the controller to the controller manager
150	* For example, can be called from a Kernel Extension Start routine
151	*
152	* PARAMETERS :
153	* userctl : Registration structure containing control information
154	* and callback functions for the controller.
155	* Callbacks are optional and can be null.
156	* A controller with all callbacks set to null would not be very useful.
157	* userdata : This parameter is for use by the controller and
158	* will be passed to every callback function
159	*
160	* RETURN CODE :
161	* 0 : No error
162	* ctlref will be filled with a control reference,
163	* to use in subsequent call to the controller manager
164	* EINVAL : Invalid registration structure
165	* ENOMEM : Not enough memory available to register the controller
166	* EEXIST : Controller id/unit already registered
167	*/
168
169	int
170	ctl_register(struct kern_ctl_reg userctl, void userdata, kern_ctl_ref *ctlref);
171
172	/*
173	* FUNCTION :
174	* Deregister the controller
175	* For example, can be called from a Kernel Extension Stop routine
176	*
177	* PARAMETERS :
178	* ctlref : Reference to the controller previously registered
179	*
180	* RETURN CODE :
181	* 0 : No error,
182	* The controller manager no longer knows about the controller
183	* EINVAL : Invalid reference
184	*/
185
186	int
187	ctl_deregister(kern_ctl_ref ctlref);
188
189	/*
190	* FUNCTION :
191	* Send data to the application in contact with the controller
192	* ctl_enqueuedata will allocate a mbuf, copy data and enqueue it.
193	*
194	* PARAMETERS :
195	* ctlref : Reference to the controller previously registered
196	* data : Data to send
197	* len : Length of the data (maximum lenght of MCLBYTES)
198	* flags : Flags used when enqueing
199	* CTL_DATA_NOWAKEUP = just enqueue, don't wake up client
200	*
201	* RETURN CODE :
202	* 0 : No error
203	* EINVAL: Invalid reference
204	* EMSGSIZE: The buffer is too large
205	* ENOTCONN : No user client is connected
206	* ENOBUFS : Socket buffer is full, or can't get a new mbuf
207	* The controller should re-enqueue later
208	*/
209
210	int
211	ctl_enqueuedata(kern_ctl_ref ctlref, void *data, size_t len, u_int32_t flags);
212
213	/*
214	* FUNCTION :
215	* Send data to the application in contact with the controller
216	*
217	* PARAMETERS :
218	* ctlref : Reference to the controller previously registered
219	* m : mbuf containing the data to send
220	* flags : Flags used when enqueing
221	* CTL_DATA_NOWAKEUP = just enqueue, don't wake up client
222	*
223	* RETURN CODE :
224	* 0 : No error
225	* EINVAL: Invalid reference
226	* ENOTCONN : No user client is connected
227	* ENOBUFS : Socket buffer is full,
228	* The controller should either free the mbuf or re-enqueue later
229	*/
230
231	int
232	ctl_enqueuembuf(kern_ctl_ref ctlref, struct mbuf *m, u_int32_t flags);
233
234	#endif /* __APPLE_API_UNSTABLE */
235	#endif /* KERNEL */
236
237	#endif /* SYS_KERN_CONTROL_H */
238