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

/*
 * Copyright (c) 2000-2004 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@
 */
/*!
	@header kern_control.h
	This header defines an API to communicate between a kernel
	extension and a process outside of the kernel.
 */

#ifndef KPI_KERN_CONTROL_H
#define KPI_KERN_CONTROL_H


#include <sys/appleapiopts.h>

/*
 * Define Controller event subclass, and associated events.
 * Subclass of KEV_SYSTEM_CLASS
 */

/*!
	@defined KEV_CTL_SUBCLASS
    @discussion The kernel event subclass for kernel control events.
*/
#define KEV_CTL_SUBCLASS        2

/*!
	@defined KEV_CTL_REGISTERED
    @discussion The event code indicating a new controller was
    	registered. The data portion will contain a ctl_event_data.
*/
#define KEV_CTL_REGISTERED      1       /* a new controller appears */

/*!
	@defined KEV_CTL_DEREGISTERED
    @discussion The event code indicating a controller was unregistered.
    	The data portion will contain a ctl_event_data.
*/
#define KEV_CTL_DEREGISTERED    2       /* a controller disappears */

/*!
	@struct ctl_event_data
	@discussion This structure is used for KEV_CTL_SUBCLASS kernel
		events.
	@field ctl_id The kernel control id.
	@field ctl_unit The kernel control unit.
*/
struct ctl_event_data {
    u_int32_t	ctl_id;			/* Kernel Controller ID */
    u_int32_t 	ctl_unit;
};

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

/*!
	@defined CTLIOCGCOUNT
    @discussion The CTLIOCGCOUNT ioctl can be used to determine the
    	number of kernel controllers registered.
*/
#define CTLIOCGCOUNT    _IOR('N', 2, int)		/* get number of control structures registered */

/*!
	@defined CTLIOCGINFO
    @discussion The CTLIOCGINFO ioctl can be used to convert a kernel
    	control name to a kernel control id.
*/
#define CTLIOCGINFO     _IOWR('N', 3, struct ctl_info)	/* get id from name */


/*!
	@defined MAX_KCTL_NAME
    @discussion Kernel control names must be no longer than
    	MAX_KCTL_NAME.
*/
#define MAX_KCTL_NAME	96

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

/*!
	@struct ctl_info
	@discussion This structure is used with the CTLIOCGINFO ioctl to
		translate from a kernel control name to a control id.
	@field ctl_id The kernel control id, filled out upon return.
	@field ctl_name The kernel control name to find.
*/
struct ctl_info {
    u_int32_t	ctl_id; 				/* Kernel Controller ID  */
    char	ctl_name[MAX_KCTL_NAME];		/* Kernel Controller Name (a C string) */
};


/*!
	@struct sockaddr_ctl
	@discussion The controller address structure is used to establish
		contact between a user client and a kernel controller. The
		sc_id/sc_unit uniquely identify each controller. sc_id is a
		unique identifier assigned to the controller. The identifier can
		be assigned by the system at registration time or be a 32-bit
		creator code obtained from Apple Computer. sc_unit is a unit
		number for this sc_id, and is privately used by the kernel
		controller to identify several instances of the controller.
	@field sc_len The length of the structure.
	@field sc_family AF_SYSTEM.
	@field ss_sysaddr AF_SYS_KERNCONTROL.
	@field sc_id Controller unique identifier.
	@field sc_unit Kernel controller private unit number.
	@field sc_reserved Reserved, must be set to zero.
*/
struct sockaddr_ctl {
    u_char		sc_len;		/* depends on size of bundle ID string */
    u_char		sc_family;	/* AF_SYSTEM */
    u_int16_t 	ss_sysaddr;	/* AF_SYS_KERNCONTROL */
    u_int32_t	sc_id; 		/* Controller unique identifier  */
    u_int32_t 	sc_unit;	/* Developer private unit number */
    u_int32_t 	sc_reserved[5];
};

#ifdef KERNEL

#include <sys/kpi_mbuf.h>

/*!
	@typedef kern_ctl_ref
	@discussion A control reference is used to track an attached kernel
		control. Registering a kernel control will create a kernel
		control reference. This reference is required for sending data
		or removing the kernel control. This reference will be passed to
		callbacks for that kernel control.
*/
typedef void * kern_ctl_ref;

/*!
	@defined CTL_FLAG_PRIVILEGED
    @discussion The CTL_FLAG_PRIVILEGED flag is passed in ctl_flags. If
    	this flag is set, only privileged processes may attach to this
    	kernel control.
*/
#define CTL_FLAG_PRIVILEGED	0x1
/*!
	@defined CTL_FLAG_REG_ID_UNIT
    @discussion The CTL_FLAG_REG_ID_UNIT flag is passed to indicate that
    	the ctl_id specified should be used. If this flag is not
    	present, a unique ctl_id will be dynamically assigned to your
    	kernel control. The CTLIOCGINFO ioctl can be used by the client
    	to find the dynamically assigned id based on the control name
    	specified in ctl_name.
*/
#define CTL_FLAG_REG_ID_UNIT	0x2
/*!
	@defined CTL_FLAG_REG_SOCK_STREAM
    @discussion Use the CTL_FLAG_REG_SOCK_STREAM flag when client need to open 
    	socket of type SOCK_STREAM to communicate with the kernel control. 
    	By default kernel control sockets are of type SOCK_DGRAM.
*/
#define CTL_FLAG_REG_SOCK_STREAM	0x4

/* Data flags for controllers */
/*!
	@defined CTL_DATA_NOWAKEUP
    @discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue
    	data and enqueue mbuf functions to indicate that the process
    	should not be woken up yet. This is useful when you want to
    	enqueue data using more than one call but only want to wake up
    	the client after all of the data has been enqueued.
*/
#define CTL_DATA_NOWAKEUP	0x1
/*!
	@defined CTL_DATA_EOR
    @discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue
    	data and enqueue mbuf functions to mark the end of a record.
*/
#define CTL_DATA_EOR		0x2

/*!
	@typedef ctl_connect_func
	@discussion The ctl_connect_func is used to receive
		notification of a client connecting to the kernel control.
	@param kctlref The control ref for the kernel control the client is
		connecting to.
	@param sac The address used to connect to this control. The field sc_unit 
		contains the unit number of the kernel control instance the client is
		connecting to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control 
		was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. 
		If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was 
		registered, sc_unit is the dynamically allocated unit number of 
		the new kernel control instance that is used for this connection.
	@param unitinfo A place for the kernel control to store a pointer to
		per-connection data.
 */
typedef errno_t (*ctl_connect_func)(kern_ctl_ref kctlref, 
									struct sockaddr_ctl *sac,
									void **unitinfo);

/*!
	@typedef ctl_disconnect_func
	@discussion The ctl_disconnect_func is used to receive notification
		that a client has disconnected from the kernel control. This
		usually happens when the socket is closed. If this is the last
		socket attached to your kernel control, you may unregister your
		kernel control from this callback.
	@param kctlref The control ref for the kernel control instance the client has
		disconnected from.
	@param unit The unit number of the kernel control instance the client has
		disconnected from.  
	@param unitinfo The unitinfo value specified by the connect function
		when the client connected.
 */
typedef errno_t (*ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo);

/*!
	@typedef ctl_send_func
	@discussion The ctl_send_func is used to receive data sent from
		the client to the kernel control.
	@param kctlref The control ref of the kernel control.
	@param unit The unit number of the kernel control instance the client has
		connected to.
	@param unitinfo The unitinfo value specified by the connect function
		when the client connected.
	@param m The data sent by the client to the kernel control in an
		mbuf chain.
	@param flags The flags specified by the client when calling
		send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE).
 */
typedef errno_t (*ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo,
								 mbuf_t m, int flags);

/*!
	@typedef ctl_setopt_func
	@discussion The ctl_setopt_func is used to handle set socket option
		calls for the SYSPROTO_CONTROL option level.
	@param kctlref The control ref of the kernel control.
	@param unit The unit number of the kernel control instance.
	@param unitinfo The unitinfo value specified by the connect function
		when the client connected.
	@param opt The socket option.
	@param data A pointer to the socket option data. The data has
		already been copied in to the kernel for you.
	@param len The length of the socket option data.
 */
typedef errno_t (*ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo,
								   int opt, void *data, size_t len);

/*!
	@typedef ctl_getopt_func
	@discussion The ctl_getopt_func is used to handle client get socket
		option requests for the SYSPROTO_CONTROL option level. A buffer
		is allocated for storage and passed to your function. The length
		of that buffer is also passed. Upon return, you should set *len
		to length of the buffer used. In some cases, data may be NULL.
		When this happens, *len should be set to the length you would
		have returned had data not been NULL. If the buffer is too small,
		return an error.
	@param kctlref The control ref of the kernel control.
	@param unit The unit number of the kernel control instance.
	@param unitinfo The unitinfo value specified by the connect function
		when the client connected.
	@param opt The socket option.
	@param data A buffer to copy the results in to. May be NULL, see
		discussion.
	@param len A pointer to the length of the buffer. This should be set
		to the length of the buffer used before returning.
 */
typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo,
								   int opt, void *data, size_t *len);

/*!
	@struct kern_ctl_reg
	@discussion This structure defines the properties of a kernel
		control being registered.
	@field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero).
		This string should not be empty.
	@field ctl_id The control ID may be dynamically assigned or it can be a
		32-bit creator code assigned by DTS. 
		For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set. 
		For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag.
		The  value of the dynamically assigned control ID is set to this field 
		when the registration succeeds.
	@field ctl_unit A separate unit number to register multiple units that 
		share the same control ID with DTS assigned creator code when 
		the CTL_FLAG_REG_ID_UNIT flag is set.
		This field is ignored for a dynamically assigned control ID.
	@field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT.
	@field ctl_sendsize Override the default send size. If set to zero,
		the default send size will be used, and this default value 
		is set to this field to be retrieved by the caller. 
	@field ctl_recvsize Override the default receive size. If set to
		zero, the default receive size will be used, and this default value 
		is set to this field to be retrieved by the caller. 
	@field ctl_connect Specify the  function to be called whenever a client
		connects to the kernel control. This field must be specified.
	@field ctl_disconnect Specify a function to be called whenever a
		client disconnects from the kernel control.
	@field ctl_send Specify a function to handle data send from the
		client to the kernel control.
	@field ctl_setopt Specify a function to handle set socket option
		operations for the kernel control.
	@field ctl_getopt Specify a function to handle get socket option
		operations for the kernel control.
*/
struct kern_ctl_reg
{
	/* control information */
	char		ctl_name[MAX_KCTL_NAME];
	u_int32_t	ctl_id;
	u_int32_t	ctl_unit;

    /* control settings */
    u_int32_t	ctl_flags;
    u_int32_t	ctl_sendsize;
    u_int32_t	ctl_recvsize;

    /* Dispatch functions */
    ctl_connect_func	ctl_connect;
    ctl_disconnect_func	ctl_disconnect;
    ctl_send_func		ctl_send;
    ctl_setopt_func		ctl_setopt;
    ctl_getopt_func		ctl_getopt;
};

/*!
	@function ctl_register
	@discussion Register a kernel control. This will enable clients to
		connect to the kernel control using a PF_SYSTEM socket.
	@param userkctl A structure defining the kernel control to be
		attached. The ctl_connect callback must be specified, the other callbacks 
		are optional. If ctl_connect is set to zero, ctl_register fails with 
		the error code EINVAL.
	@param kctlref Upon successful return, the kctlref will contain a
		reference to the attached kernel control. This reference is used
		to unregister the kernel control. This reference will also be
		passed in to the callbacks each time they are called.
	@result 0 - Kernel control was registered.
		EINVAL - The registration structure was not valid.
		ENOMEM - There was insufficient memory.
		EEXIST - A controller with that id/unit is already registered.
 */
errno_t
ctl_register(struct kern_ctl_reg *userkctl, kern_ctl_ref *kctlref);	

/*!
	@function ctl_deregister
	@discussion Unregister a kernel control. A kernel extension must
		unregister it's kernel control(s) before unloading. If a kernel
		control has clients attached, this call will fail.
	@param kctlref The control reference of the control to unregister.
	@result 0 - Kernel control was unregistered.
		EINVAL - The kernel control reference was invalid.
		EBUSY - The kernel control has clients still attached.
 */
errno_t 
ctl_deregister(kern_ctl_ref kctlref);	

/*!
	@function ctl_enqueuedata
	@discussion Send data from the kernel control to the client.
	@param kctlref The control reference of the kernel control.
	@param unit The unit number of the kernel control instance.
	@param data A pointer to the data to send.
	@param len The length of data to send.
	@param flags Send flags. CTL_DATA_NOWAKEUP is currently the only
		supported flag.
	@result 0 - Data was enqueued to be read by the client.
		EINVAL - Invalid parameters.
		EMSGSIZE - The buffer is too large.
		ENOBUFS - The queue is full or there are no free mbufs.
 */
errno_t 
ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags);

/*!
	@function ctl_enqueuembuf
	@discussion Send data stored in an mbuf chain from the kernel
		control to the client. The caller is responsible for freeing
		the mbuf chain if ctl_enqueuembuf returns an error.
	@param kctlref The control reference of the kernel control.
	@param unit The unit number of the kernel control instance.
	@param m An mbuf chain containing the data to send to the client.
	@param flags Send flags. CTL_DATA_NOWAKEUP is currently the only
		supported flag.
	@result 0 - Data was enqueued to be read by the client.
		EINVAL - Invalid parameters.
		ENOBUFS - The queue is full.
 */
errno_t 
ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags);


/*!
	@function ctl_getenqueuespace
	@discussion Retrieve the amount of space currently available for data to be sent 
		from the kernel control to the client.
	@param kctlref The control reference of the kernel control.
	@param unit The unit number of the kernel control instance.
	@param space The address where to return the current space available 
	@result 0 - Data was enqueued to be read by the client.
		EINVAL - Invalid parameters.
 */
errno_t 
ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space);


#endif /* KERNEL */

#endif /* KPI_KERN_CONTROL_H */
Commit	Line	Data
9bccf70c	1	/*
91447636	2	* Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
9bccf70c A	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
37839358 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	*
37839358 A	12	* This Original Code and all software distributed under the License are
37839358 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,
37839358 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	*/
91447636 A	22	/*!
	23	@header kern_control.h
	24	This header defines an API to communicate between a kernel
	25	extension and a process outside of the kernel.
	26	*/
9bccf70c	27
91447636 A	28	#ifndef KPI_KERN_CONTROL_H
91447636 A	29	#define KPI_KERN_CONTROL_H
9bccf70c	30
9bccf70c A	31
	32	#include <sys/appleapiopts.h>
	33
9bccf70c A	34	/*
9bccf70c A	35	* Define Controller event subclass, and associated events.
91447636	36	* Subclass of KEV_SYSTEM_CLASS
9bccf70c A	37	*/
9bccf70c A	38
91447636 A	39	/*!
	40	@defined KEV_CTL_SUBCLASS
	41	@discussion The kernel event subclass for kernel control events.
	42	*/
	43	#define KEV_CTL_SUBCLASS 2
	44
	45	/*!
	46	@defined KEV_CTL_REGISTERED
	47	@discussion The event code indicating a new controller was
	48	registered. The data portion will contain a ctl_event_data.
	49	*/
	50	#define KEV_CTL_REGISTERED 1 /* a new controller appears */
9bccf70c	51
91447636 A	52	/*!
	53	@defined KEV_CTL_DEREGISTERED
	54	@discussion The event code indicating a controller was unregistered.
	55	The data portion will contain a ctl_event_data.
	56	*/
	57	#define KEV_CTL_DEREGISTERED 2 /* a controller disappears */
9bccf70c	58
91447636 A	59	/*!
	60	@struct ctl_event_data
	61	@discussion This structure is used for KEV_CTL_SUBCLASS kernel
	62	events.
	63	@field ctl_id The kernel control id.
	64	@field ctl_unit The kernel control unit.
	65	*/
9bccf70c	66	struct ctl_event_data {
91447636	67	u_int32_t ctl_id; /* Kernel Controller ID */
9bccf70c A	68	u_int32_t ctl_unit;
	69	};
	70
9bccf70c A	71	/*
	72	* Controls destined to the Controller Manager.
	73	*/
	74
91447636 A	75	/*!
	76	@defined CTLIOCGCOUNT
	77	@discussion The CTLIOCGCOUNT ioctl can be used to determine the
	78	number of kernel controllers registered.
	79	*/
	80	#define CTLIOCGCOUNT _IOR('N', 2, int) /* get number of control structures registered */
	81
	82	/*!
	83	@defined CTLIOCGINFO
	84	@discussion The CTLIOCGINFO ioctl can be used to convert a kernel
	85	control name to a kernel control id.
	86	*/
	87	#define CTLIOCGINFO _IOWR('N', 3, struct ctl_info) /* get id from name */
	88
	89
	90	/*!
	91	@defined MAX_KCTL_NAME
	92	@discussion Kernel control names must be no longer than
	93	MAX_KCTL_NAME.
	94	*/
	95	#define MAX_KCTL_NAME 96
9bccf70c A	96
9bccf70c A	97	/*
91447636	98	* Controls destined to the Controller Manager.
9bccf70c A	99	*/
9bccf70c A	100
91447636 A	101	/*!
	102	@struct ctl_info
	103	@discussion This structure is used with the CTLIOCGINFO ioctl to
	104	translate from a kernel control name to a control id.
	105	@field ctl_id The kernel control id, filled out upon return.
	106	@field ctl_name The kernel control name to find.
	107	*/
	108	struct ctl_info {
	109	u_int32_t ctl_id; /* Kernel Controller ID */
	110	char ctl_name[MAX_KCTL_NAME]; /* Kernel Controller Name (a C string) */
	111	};
	112
	113
	114	/*!
	115	@struct sockaddr_ctl
	116	@discussion The controller address structure is used to establish
	117	contact between a user client and a kernel controller. The
	118	sc_id/sc_unit uniquely identify each controller. sc_id is a
	119	unique identifier assigned to the controller. The identifier can
	120	be assigned by the system at registration time or be a 32-bit
	121	creator code obtained from Apple Computer. sc_unit is a unit
	122	number for this sc_id, and is privately used by the kernel
	123	controller to identify several instances of the controller.
	124	@field sc_len The length of the structure.
	125	@field sc_family AF_SYSTEM.
	126	@field ss_sysaddr AF_SYS_KERNCONTROL.
	127	@field sc_id Controller unique identifier.
	128	@field sc_unit Kernel controller private unit number.
	129	@field sc_reserved Reserved, must be set to zero.
	130	*/
	131	struct sockaddr_ctl {
	132	u_char sc_len; /* depends on size of bundle ID string */
	133	u_char sc_family; /* AF_SYSTEM */
	134	u_int16_t ss_sysaddr; /* AF_SYS_KERNCONTROL */
	135	u_int32_t sc_id; /* Controller unique identifier */
9bccf70c A	136	u_int32_t sc_unit; /* Developer private unit number */
	137	u_int32_t sc_reserved[5];
	138	};
9bccf70c A	139
9bccf70c A	140	#ifdef KERNEL
9bccf70c	141
91447636 A	142	#include <sys/kpi_mbuf.h>
	143
	144	/*!
	145	@typedef kern_ctl_ref
	146	@discussion A control reference is used to track an attached kernel
	147	control. Registering a kernel control will create a kernel
	148	control reference. This reference is required for sending data
	149	or removing the kernel control. This reference will be passed to
	150	callbacks for that kernel control.
	151	*/
9bccf70c A	152	typedef void * kern_ctl_ref;
9bccf70c A	153
91447636 A	154	/*!
	155	@defined CTL_FLAG_PRIVILEGED
	156	@discussion The CTL_FLAG_PRIVILEGED flag is passed in ctl_flags. If
	157	this flag is set, only privileged processes may attach to this
	158	kernel control.
	159	*/
	160	#define CTL_FLAG_PRIVILEGED 0x1
	161	/*!
	162	@defined CTL_FLAG_REG_ID_UNIT
	163	@discussion The CTL_FLAG_REG_ID_UNIT flag is passed to indicate that
	164	the ctl_id specified should be used. If this flag is not
	165	present, a unique ctl_id will be dynamically assigned to your
	166	kernel control. The CTLIOCGINFO ioctl can be used by the client
	167	to find the dynamically assigned id based on the control name
	168	specified in ctl_name.
	169	*/
	170	#define CTL_FLAG_REG_ID_UNIT 0x2
	171	/*!
	172	@defined CTL_FLAG_REG_SOCK_STREAM
	173	@discussion Use the CTL_FLAG_REG_SOCK_STREAM flag when client need to open
	174	socket of type SOCK_STREAM to communicate with the kernel control.
	175	By default kernel control sockets are of type SOCK_DGRAM.
	176	*/
	177	#define CTL_FLAG_REG_SOCK_STREAM 0x4
9bccf70c A	178
9bccf70c A	179	/* Data flags for controllers */
91447636 A	180	/*!
	181	@defined CTL_DATA_NOWAKEUP
	182	@discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue
	183	data and enqueue mbuf functions to indicate that the process
	184	should not be woken up yet. This is useful when you want to
	185	enqueue data using more than one call but only want to wake up
	186	the client after all of the data has been enqueued.
	187	*/
	188	#define CTL_DATA_NOWAKEUP 0x1
	189	/*!
	190	@defined CTL_DATA_EOR
	191	@discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue
	192	data and enqueue mbuf functions to mark the end of a record.
	193	*/
	194	#define CTL_DATA_EOR 0x2
9bccf70c	195
91447636 A	196	/*!
	197	@typedef ctl_connect_func
	198	@discussion The ctl_connect_func is used to receive
	199	notification of a client connecting to the kernel control.
	200	@param kctlref The control ref for the kernel control the client is
	201	connecting to.
	202	@param sac The address used to connect to this control. The field sc_unit
	203	contains the unit number of the kernel control instance the client is
	204	connecting to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control
	205	was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure.
	206	If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was
	207	registered, sc_unit is the dynamically allocated unit number of
	208	the new kernel control instance that is used for this connection.
	209	@param unitinfo A place for the kernel control to store a pointer to
	210	per-connection data.
	211	*/
	212	typedef errno_t (*ctl_connect_func)(kern_ctl_ref kctlref,
	213	struct sockaddr_ctl *sac,
	214	void **unitinfo);
9bccf70c	215
91447636 A	216	/*!
	217	@typedef ctl_disconnect_func
	218	@discussion The ctl_disconnect_func is used to receive notification
	219	that a client has disconnected from the kernel control. This
	220	usually happens when the socket is closed. If this is the last
	221	socket attached to your kernel control, you may unregister your
	222	kernel control from this callback.
	223	@param kctlref The control ref for the kernel control instance the client has
	224	disconnected from.
	225	@param unit The unit number of the kernel control instance the client has
	226	disconnected from.
	227	@param unitinfo The unitinfo value specified by the connect function
	228	when the client connected.
9bccf70c	229	*/
91447636 A	230	typedef errno_t (ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void unitinfo);
	231
	232	/*!
	233	@typedef ctl_send_func
	234	@discussion The ctl_send_func is used to receive data sent from
	235	the client to the kernel control.
	236	@param kctlref The control ref of the kernel control.
	237	@param unit The unit number of the kernel control instance the client has
	238	connected to.
	239	@param unitinfo The unitinfo value specified by the connect function
	240	when the client connected.
	241	@param m The data sent by the client to the kernel control in an
	242	mbuf chain.
	243	@param flags The flags specified by the client when calling
	244	send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE).
	245	*/
	246	typedef errno_t (ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void unitinfo,
	247	mbuf_t m, int flags);
	248
	249	/*!
	250	@typedef ctl_setopt_func
	251	@discussion The ctl_setopt_func is used to handle set socket option
	252	calls for the SYSPROTO_CONTROL option level.
	253	@param kctlref The control ref of the kernel control.
	254	@param unit The unit number of the kernel control instance.
	255	@param unitinfo The unitinfo value specified by the connect function
	256	when the client connected.
	257	@param opt The socket option.
	258	@param data A pointer to the socket option data. The data has
	259	already been copied in to the kernel for you.
	260	@param len The length of the socket option data.
	261	*/
	262	typedef errno_t (ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void unitinfo,
	263	int opt, void *data, size_t len);
	264
	265	/*!
	266	@typedef ctl_getopt_func
	267	@discussion The ctl_getopt_func is used to handle client get socket
	268	option requests for the SYSPROTO_CONTROL option level. A buffer
	269	is allocated for storage and passed to your function. The length
	270	of that buffer is also passed. Upon return, you should set *len
	271	to length of the buffer used. In some cases, data may be NULL.
	272	When this happens, *len should be set to the length you would
	273	have returned had data not been NULL. If the buffer is too small,
	274	return an error.
	275	@param kctlref The control ref of the kernel control.
	276	@param unit The unit number of the kernel control instance.
	277	@param unitinfo The unitinfo value specified by the connect function
	278	when the client connected.
	279	@param opt The socket option.
	280	@param data A buffer to copy the results in to. May be NULL, see
	281	discussion.
	282	@param len A pointer to the length of the buffer. This should be set
	283	to the length of the buffer used before returning.
	284	*/
	285	typedef errno_t (ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void unitinfo,
	286	int opt, void data, size_t len);
	287
	288	/*!
	289	@struct kern_ctl_reg
	290	@discussion This structure defines the properties of a kernel
	291	control being registered.
	292	@field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero).
	293	This string should not be empty.
294	@field ctl_id The control ID may be dynamically assigned or it can be a
295	32-bit creator code assigned by DTS.
296	For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set.
297	For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag.
298	The value of the dynamically assigned control ID is set to this field
299	when the registration succeeds.
300	@field ctl_unit A separate unit number to register multiple units that
301	share the same control ID with DTS assigned creator code when
302	the CTL_FLAG_REG_ID_UNIT flag is set.
303	This field is ignored for a dynamically assigned control ID.
304	@field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT.
305	@field ctl_sendsize Override the default send size. If set to zero,
306	the default send size will be used, and this default value
307	is set to this field to be retrieved by the caller.
308	@field ctl_recvsize Override the default receive size. If set to
309	zero, the default receive size will be used, and this default value
310	is set to this field to be retrieved by the caller.
311	@field ctl_connect Specify the function to be called whenever a client
312	connects to the kernel control. This field must be specified.
313	@field ctl_disconnect Specify a function to be called whenever a
314	client disconnects from the kernel control.
315	@field ctl_send Specify a function to handle data send from the
316	client to the kernel control.
317	@field ctl_setopt Specify a function to handle set socket option
318	operations for the kernel control.
319	@field ctl_getopt Specify a function to handle get socket option
320	operations for the kernel control.
321	*/
9bccf70c A	322	struct kern_ctl_reg
9bccf70c A	323	{
91447636 A	324	/* control information */
	325	char ctl_name[MAX_KCTL_NAME];
	326	u_int32_t ctl_id;
	327	u_int32_t ctl_unit;
	328
9bccf70c	329	/* control settings */
91447636 A	330	u_int32_t ctl_flags;
	331	u_int32_t ctl_sendsize;
	332	u_int32_t ctl_recvsize;
9bccf70c A	333
9bccf70c A	334	/* Dispatch functions */
91447636 A	335	ctl_connect_func ctl_connect;
	336	ctl_disconnect_func ctl_disconnect;
	337	ctl_send_func ctl_send;
	338	ctl_setopt_func ctl_setopt;
	339	ctl_getopt_func ctl_getopt;
9bccf70c A	340	};
9bccf70c A	341
91447636 A	342	/*!
	343	@function ctl_register
	344	@discussion Register a kernel control. This will enable clients to
	345	connect to the kernel control using a PF_SYSTEM socket.
	346	@param userkctl A structure defining the kernel control to be
	347	attached. The ctl_connect callback must be specified, the other callbacks
	348	are optional. If ctl_connect is set to zero, ctl_register fails with
	349	the error code EINVAL.
	350	@param kctlref Upon successful return, the kctlref will contain a
	351	reference to the attached kernel control. This reference is used
	352	to unregister the kernel control. This reference will also be
	353	passed in to the callbacks each time they are called.
	354	@result 0 - Kernel control was registered.
	355	EINVAL - The registration structure was not valid.
	356	ENOMEM - There was insufficient memory.
	357	EEXIST - A controller with that id/unit is already registered.
	358	*/
	359	errno_t
	360	ctl_register(struct kern_ctl_reg userkctl, kern_ctl_ref kctlref);
9bccf70c	361
91447636 A	362	/*!
	363	@function ctl_deregister
	364	@discussion Unregister a kernel control. A kernel extension must
	365	unregister it's kernel control(s) before unloading. If a kernel
	366	control has clients attached, this call will fail.
	367	@param kctlref The control reference of the control to unregister.
	368	@result 0 - Kernel control was unregistered.
	369	EINVAL - The kernel control reference was invalid.
	370	EBUSY - The kernel control has clients still attached.
9bccf70c	371	*/
91447636 A	372	errno_t
91447636 A	373	ctl_deregister(kern_ctl_ref kctlref);
9bccf70c	374
91447636 A	375	/*!
	376	@function ctl_enqueuedata
	377	@discussion Send data from the kernel control to the client.
	378	@param kctlref The control reference of the kernel control.
	379	@param unit The unit number of the kernel control instance.
	380	@param data A pointer to the data to send.
	381	@param len The length of data to send.
	382	@param flags Send flags. CTL_DATA_NOWAKEUP is currently the only
	383	supported flag.
	384	@result 0 - Data was enqueued to be read by the client.
	385	EINVAL - Invalid parameters.
	386	EMSGSIZE - The buffer is too large.
	387	ENOBUFS - The queue is full or there are no free mbufs.
9bccf70c	388	*/
91447636 A	389	errno_t
91447636 A	390	ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags);
9bccf70c	391
91447636 A	392	/*!
	393	@function ctl_enqueuembuf
	394	@discussion Send data stored in an mbuf chain from the kernel
	395	control to the client. The caller is responsible for freeing
	396	the mbuf chain if ctl_enqueuembuf returns an error.
	397	@param kctlref The control reference of the kernel control.
	398	@param unit The unit number of the kernel control instance.
	399	@param m An mbuf chain containing the data to send to the client.
	400	@param flags Send flags. CTL_DATA_NOWAKEUP is currently the only
	401	supported flag.
	402	@result 0 - Data was enqueued to be read by the client.
	403	EINVAL - Invalid parameters.
	404	ENOBUFS - The queue is full.
9bccf70c	405	*/
91447636 A	406	errno_t
91447636 A	407	ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags);
9bccf70c	408
91447636 A	409
	410	/*!
	411	@function ctl_getenqueuespace
	412	@discussion Retrieve the amount of space currently available for data to be sent
	413	from the kernel control to the client.
	414	@param kctlref The control reference of the kernel control.
	415	@param unit The unit number of the kernel control instance.
	416	@param space The address where to return the current space available
	417	@result 0 - Data was enqueued to be read by the client.
	418	EINVAL - Invalid parameters.
9bccf70c	419	*/
91447636 A	420	errno_t
	421	ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space);
	422
9bccf70c	423
9bccf70c A	424	#endif /* KERNEL */
9bccf70c A	425
91447636	426	#endif /* KPI_KERN_CONTROL_H */
9bccf70c	427