-/*
- * 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 */
+#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);
+#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;
+#endif /* KERNEL_PRIVATE */
projects / apple / xnu.git / blobdiff