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

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