1/*
2 * Copyright (c) 2000-2004, 2012-2025 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/*!
29 * @header kern_control.h
30 * This header defines an API to communicate between a kernel
31 * extension and a process outside of the kernel.
32 */
33
34#ifndef KPI_KERN_CONTROL_H
35#define KPI_KERN_CONTROL_H
36
37
38#include <sys/appleapiopts.h>
39#include <sys/_types/_u_char.h>
40#include <sys/_types/_u_int16_t.h>
41#include <sys/_types/_u_int32_t.h>
42#include <sys/_types/_u_int64_t.h>
43
44/*
45 * Define Controller event subclass, and associated events.
46 * Subclass of KEV_SYSTEM_CLASS
47 */
48
49/*!
50 * @defined KEV_CTL_SUBCLASS
51 * @discussion The kernel event subclass for kernel control events.
52 */
53#define KEV_CTL_SUBCLASS 2
54
55/*!
56 * @defined KEV_CTL_REGISTERED
57 * @discussion The event code indicating a new controller was
58 * registered. The data portion will contain a ctl_event_data.
59 */
60#define KEV_CTL_REGISTERED 1 /* a new controller appears */
61
62/*!
63 * @defined KEV_CTL_DEREGISTERED
64 * @discussion The event code indicating a controller was unregistered.
65 * The data portion will contain a ctl_event_data.
66 */
67#define KEV_CTL_DEREGISTERED 2 /* a controller disappears */
68
69/*!
70 * @struct ctl_event_data
71 * @discussion This structure is used for KEV_CTL_SUBCLASS kernel
72 * events.
73 * @field ctl_id The kernel control id.
74 * @field ctl_unit The kernel control unit.
75 */
76struct ctl_event_data {
77 u_int32_t ctl_id; /* Kernel Controller ID */
78 u_int32_t ctl_unit;
79};
80
81/*
82 * Controls destined to the Controller Manager.
83 */
84
85/*!
86 * @defined CTLIOCGCOUNT
87 * @discussion The CTLIOCGCOUNT ioctl can be used to determine the
88 * number of kernel controllers registered.
89 */
90#define CTLIOCGCOUNT _IOR('N', 2, int) /* get number of control structures registered */
91
92/*!
93 * @defined CTLIOCGINFO
94 * @discussion The CTLIOCGINFO ioctl can be used to convert a kernel
95 * control name to a kernel control id.
96 */
97#define CTLIOCGINFO _IOWR('N', 3, struct ctl_info) /* get id from name */
98
99
100/*!
101 * @defined MAX_KCTL_NAME
102 * @discussion Kernel control names must be no longer than
103 * MAX_KCTL_NAME.
104 */
105#define MAX_KCTL_NAME 96
106
107/*
108 * Controls destined to the Controller Manager.
109 */
110
111/*!
112 * @struct ctl_info
113 * @discussion This structure is used with the CTLIOCGINFO ioctl to
114 * translate from a kernel control name to a control id.
115 * @field ctl_id The kernel control id, filled out upon return.
116 * @field ctl_name The kernel control name to find.
117 */
118struct ctl_info {
119 u_int32_t ctl_id; /* Kernel Controller ID */
120 char ctl_name[MAX_KCTL_NAME]; /* Kernel Controller Name (a C string) */
121};
122
123
124/*!
125 * @struct sockaddr_ctl
126 * @discussion The controller address structure is used to establish
127 * contact between a user client and a kernel controller. The
128 * sc_id/sc_unit uniquely identify each controller. sc_id is a
129 * unique identifier assigned to the controller. The identifier can
130 * be assigned by the system at registration time or be a 32-bit
131 * creator code obtained from Apple Computer. sc_unit is a unit
132 * number for this sc_id, and is privately used by the kernel
133 * controller to identify several instances of the controller.
134 * @field sc_len The length of the structure.
135 * @field sc_family AF_SYSTEM.
136 * @field ss_sysaddr AF_SYS_KERNCONTROL.
137 * @field sc_id Controller unique identifier.
138 * @field sc_unit Kernel controller private unit number.
139 * @field sc_reserved Reserved, must be set to zero.
140 */
141struct sockaddr_ctl {
142 u_char sc_len; /* depends on size of bundle ID string */
143 u_char sc_family; /* AF_SYSTEM */
144 u_int16_t ss_sysaddr; /* AF_SYS_KERNCONTROL */
145 u_int32_t sc_id; /* Controller unique identifier */
146 u_int32_t sc_unit; /* Developer private unit number */
147 u_int32_t sc_reserved[5];
148};
149
150
151
152#endif /* KPI_KERN_CONTROL_H */