xref: /xnu-10063.101.15/bsd/sys/kern_control.h (revision 94d3b452840153a99b38a3a9659680b2a006908e)

/*
 * Copyright (c) 2000-2004, 2012-2016 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * 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. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * 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_OSREFERENCE_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>
#include <sys/_types/_u_char.h>
#include <sys/_types/_u_int16_t.h>
#include <sys/_types/_u_int32_t.h>
#include <sys/_types/_u_int64_t.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 PRIVATE

struct xkctl_reg {
	u_int32_t       xkr_len;
	u_int32_t       xkr_kind;
	u_int32_t       xkr_id;
	u_int32_t       xkr_reg_unit;
	u_int32_t       xkr_flags;
	u_int64_t       xkr_kctlref;
	u_int32_t       xkr_recvbufsize;
	u_int32_t       xkr_sendbufsize;
	u_int32_t       xkr_lastunit;
	u_int32_t       xkr_pcbcount;
	u_int64_t       xkr_connect;
	u_int64_t       xkr_disconnect;
	u_int64_t       xkr_send;
	u_int64_t       xkr_send_list;
	u_int64_t       xkr_setopt;
	u_int64_t       xkr_getopt;
	u_int64_t       xkr_rcvd;
	char            xkr_name[MAX_KCTL_NAME];
};

struct xkctlpcb {
	u_int32_t       xkp_len;
	u_int32_t       xkp_kind;
	u_int64_t       xkp_kctpcb;
	u_int32_t       xkp_unit;
	u_int32_t       xkp_kctlid;
	u_int64_t       xkp_kctlref;
	char            xkp_kctlname[MAX_KCTL_NAME];
};

struct kctlstat {
	u_int64_t       kcs_reg_total __attribute__((aligned(8)));
	u_int64_t       kcs_reg_count __attribute__((aligned(8)));
	u_int64_t       kcs_pcbcount __attribute__((aligned(8)));
	u_int64_t       kcs_gencnt __attribute__((aligned(8)));
	u_int64_t       kcs_connections __attribute__((aligned(8)));
	u_int64_t       kcs_conn_fail __attribute__((aligned(8)));
	u_int64_t       kcs_send_fail __attribute__((aligned(8)));
	u_int64_t       kcs_send_list_fail __attribute__((aligned(8)));
	u_int64_t       kcs_enqueue_fail __attribute__((aligned(8)));
	u_int64_t       kcs_enqueue_fullsock __attribute__((aligned(8)));
	u_int64_t       kcs_bad_kctlref __attribute__((aligned(8)));
	u_int64_t       kcs_tbl_size_too_big __attribute__((aligned(8)));
	u_int64_t       kcs_enqdata_mb_alloc_fail __attribute__((aligned(8)));
	u_int64_t       kcs_enqdata_sbappend_fail __attribute__((aligned(8)));
};

#endif /* PRIVATE */

#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

#ifdef KERNEL_PRIVATE
/*!
 *       @defined CTL_FLAG_REG_EXTENDED
 *   @discussion This flag indicates that this kernel control utilizes the
 *       the extended fields within the kern_ctl_reg structure.
 */
#define CTL_FLAG_REG_EXTENDED   0x8

/*!
 *       @defined CTL_FLAG_REG_CRIT
 *   @discussion This flag indicates that this kernel control utilizes the
 *       the extended fields within the kern_ctl_reg structure.
 */
#define CTL_FLAG_REG_CRIT       0x10

/*!
 *       @defined CTL_FLAG_REG_SETUP
 *   @discussion This flag indicates that this kernel control utilizes the
 *       the setup callback field within the kern_ctl_reg structure.
 */
#define CTL_FLAG_REG_SETUP      0x20
#endif /* KERNEL_PRIVATE */

/* 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_EOR flag can be used for the enqueue
 *       data and enqueue mbuf functions to mark the end of a record.
 */
#define CTL_DATA_EOR            0x2

#ifdef KERNEL_PRIVATE
/*!
 *       @defined CTL_DATA_CRIT
 *       @discussion This flag indicates the data is critical to the client
 *               and that it needs to be forced into the socket buffer
 *               by resizing it if needed.
 */
#define CTL_DATA_CRIT   0x4
#endif /* KERNEL_PRIVATE */

__BEGIN_DECLS

/*!
 *       @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 placeholder for a pointer to the optional user-defined
 *               private data associated with this kernel control instance.  This
 *               opaque info will be provided to the user when the rest of the
 *               callback routines are executed.  For example, it can be used
 *               to pass a pointer to an instance-specific data structure in
 *               order for the user to keep track of the states related to this
 *               kernel control instance.
 */
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 user-defined private data initialized by the
 *               ctl_connect_func callback.
 */
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 user-defined private data initialized by the
 *               ctl_connect_func callback.
 *       @param m The data sent by the client to the kernel control in an
 *               mbuf chain. Your function is responsible for releasing the
 *               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 user-defined private data initialized by the
 *               ctl_connect_func callback.
 *       @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 user-defined private data initialized by the
 *               ctl_connect_func callback.
 *       @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);

#ifdef KERNEL_PRIVATE
/*!
 *       @typedef ctl_rcvd_func
 *       @discussion The ctl_rcvd_func is called when the client reads data from
 *               the kernel control socket. The kernel control can use this callback
 *               in combination with ctl_getenqueuespace() to avoid overflowing
 *               the socket's receive buffer. When ctl_getenqueuespace() returns
 *               0 or ctl_enqueuedata()/ctl_enqueuembuf() return ENOBUFS, the
 *               kernel control can wait until this callback is called before
 *               trying to enqueue the data again.
 *       @param kctlref The control ref of the kernel control.
 *       @param unit The unit number of the kernel control instance.
 *       @param unitinfo The user-defined private data initialized by the
 *               ctl_connect_func callback.
 *       @param flags The recv flags. See the recv(2) man page.
 */
typedef void (*ctl_rcvd_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo,
    int flags);

/*!
 *       @typedef ctl_send_list_func
 *       @discussion The ctl_send_list_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 user-defined private data initialized by the
 *               ctl_connect_func callback.
 *       @param m The data sent by the client to the kernel control in an
 *               mbuf packet chain. Your function is responsible for releasing
 *               mbuf packet chain.
 *       @param flags The flags specified by the client when calling
 *               send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE).
 */
typedef errno_t (*ctl_send_list_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo,
    mbuf_t m, int flags);

/*!
 *       @typedef ctl_bind_func
 *       @discussion The ctl_bind_func is an optional function that allows the client
 *               to set up their unitinfo prior to connecting.
 *       @param kctlref The control ref for the kernel control the client is
 *               binding 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
 *               binding 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 placeholder for a pointer to the optional user-defined
 *               private data associated with this kernel control instance.  This
 *               opaque info will be provided to the user when the rest of the
 *               callback routines are executed.  For example, it can be used
 *               to pass a pointer to an instance-specific data structure in
 *               order for the user to keep track of the states related to this
 *               kernel control instance.
 */
typedef errno_t (*ctl_bind_func)(kern_ctl_ref kctlref,
    struct sockaddr_ctl *sac,
    void **unitinfo);

/*!
 *       @typedef ctl_setup_func
 *       @discussion The ctl_setup_func is an optional function that allows the client
 *               to pick a unit number in the case that the caller hasn't specified one
 *       @param unit A placeholder for a pointer to the unit number that is selected with
 *               this kernel control instance
 *       @param unitinfo A placeholder for a pointer to the optional user-defined
 *               private data associated with this kernel control instance.  This
 *               opaque info will be provided to the user when the rest of the
 *               callback routines are executed.  For example, it can be used
 *               to pass a pointer to an instance-specific data structure in
 *               order for the user to keep track of the states related to this
 *               kernel control instance.
 */
typedef errno_t (*ctl_setup_func)(u_int32_t *unit, void **unitinfo);
#endif /* KERNEL_PRIVATE */

/*!
 *       @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;
#ifdef KERNEL_PRIVATE
	ctl_rcvd_func               ctl_rcvd;   /* Only valid if CTL_FLAG_REG_EXTENDED is set */
	ctl_send_list_func          ctl_send_list;/* Only valid if CTL_FLAG_REG_EXTENDED is set */
	ctl_bind_func           ctl_bind;
	ctl_setup_func                  ctl_setup;
#endif /* KERNEL_PRIVATE */
};

/*!
 *       @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 and CTL_DATA_EOR are currently
 *               the only supported flags.
 *       @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 and CTL_DATA_EOR are currently
 *               the only supported flags.
 *       @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);

#ifdef PRIVATE
/*!
 *       @function ctl_enqueuembuf_list
 *       @discussion Send data stored in an mbuf packet chain from the kernel
 *               control to the client. The caller is responsible for freeing
 *               the mbuf chain if ctl_enqueuembuf returns an error.
 *               Not valid if ctl_flags contains CTL_FLAG_REG_SOCK_STREAM.
 *       @param kctlref The control reference of the kernel control.
 *       @param unit The unit number of the kernel control instance.
 *       @param m_list An mbuf chain containing the data to send to the client.
 *       @param flags Send flags. CTL_DATA_NOWAKEUP is
 *               the only supported flags.
 *       @param m_remain A pointer to the list of mbuf packets in the chain that
 *               could not be enqueued.
 *       @result 0 - Data was enqueued to be read by the client.
 *               EINVAL - Invalid parameters.
 *               ENOBUFS - The queue is full.
 */
errno_t
ctl_enqueuembuf_list(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m_list,
    u_int32_t flags, mbuf_t *m_remain);

/*!
 *       @function ctl_getenqueuepacketcount
 *       @discussion Retrieve the number of packets in the socket
 *               receive buffer.
 *       @param kctlref The control reference of the kernel control.
 *       @param unit The unit number of the kernel control instance.
 *       @param pcnt The address where to return the current count.
 *       @result 0 - Success; the packet count is returned to caller.
 *               EINVAL - Invalid parameters.
 */
errno_t
ctl_getenqueuepacketcount(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *pcnt);

#endif /* PRIVATE */

/*!
 *       @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 - Success; the amount of space is returned to caller.
 *               EINVAL - Invalid parameters.
 */
errno_t
ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space);

/*!
 *  @function ctl_getenqueuereadable
 *  @discussion Retrieve the difference between enqueued bytes and
 *       low-water mark for the socket receive buffer.
 *  @param kctlref The control reference of the kernel control.
 *  @param unit The unit number of the kernel control instance.
 *  @param difference The address at which to return the current difference
 *       between the low-water mark for the socket and the number of bytes
 *       enqueued. 0 indicates that the socket is readable by the client
 *       (the number of bytes in the buffer is above the low-water mark).
 *  @result 0 - Success; the difference is returned to caller.
 *  EINVAL - Invalid parameters.
 */
errno_t
ctl_getenqueuereadable(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *difference);

#ifdef KERNEL_PRIVATE

#include <sys/queue.h>
#include <libkern/locks.h>

/*
 * internal structure maintained for each register controller
 */
struct ctl_cb;
struct kctl;
struct socket;
struct socket_info;

void kctl_fill_socketinfo(struct socket *, struct socket_info *);

u_int32_t ctl_id_by_name(const char *name);
errno_t ctl_name_by_id(u_int32_t id, char *out_name, size_t maxsize);

extern const u_int32_t ctl_maxunit;
#endif /* KERNEL_PRIVATE */

__END_DECLS
#endif /* KERNEL */

#endif /* KPI_KERN_CONTROL_H */