| blob | a12d5ba230994094cfa2750ed2d666ab0b93270d |
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2016 Joyent, Inc.
13 .\"
14 .Dd May 12, 2016
15 .Dt MAC_CALLBACKS 9S
16 .Os
17 .Sh NAME
18 .Nm mac_callbacks ,
19 .Nm mac_callbacks_t
20 .Nd networking device driver entry points structure
21 .Sh SYNOPSIS
22 .In sys/mac_provider.h
23 .Sh INTERFACE LEVEL
24 illumos DDI specific
25 .Sh DESCRIPTION
26 The
27 .Sy mac_callbacks
28 structure is used by GLDv3 networking device drivers implementing the
29 .Xr mac 9E
30 interface.
31 .Pp
32 The structure is normally allocated statically by drivers as a single
33 global entry. A pointer to it is passed as the
34 .Sy m_callbacks
35 member of the
36 .Sy mac_register_t
37 structure.
38 .Sh TYPES
39 The following types define the function pointers in use in the
40 .Sy mac_register_t .
41 .Bd -literal -offset indent
42 typedef int (*mac_getstat_t)(void *, uint_t, uint64_t *);
43 typedef int (*mac_start_t)(void *);
44 typedef void (*mac_stop_t)(void *);
45 typedef int (*mac_setpromisc_t)(void *, boolean_t);
46 typedef int (*mac_multicst_t)(void *, boolean_t, const uint8_t *);
47 typedef int (*mac_unicst_t)(void *, const uint8_t *);
48 typedef void (*mac_ioctl_t)(void *, queue_t *, mblk_t *);
49 typedef void (*mac_resources_t)(void *);
50 typedef mblk_t *(*mac_tx_t)(void *, mblk_t *);
51 typedef boolean_t (*mac_getcapab_t)(void *, mac_capab_t, void *);
52 typedef int (*mac_open_t)(void *);
53 typedef void (*mac_close_t)(void *);
54 typedef int (*mac_set_prop_t)(void *, const char *, mac_prop_id_t,
55 uint_t, const void *);
56 typedef int (*mac_get_prop_t)(void *, const char *, mac_prop_id_t,
57 uint_t, void *);
58 typedef void (*mac_prop_info_t)(void *, const char *, mac_prop_id_t,
59 mac_prop_info_handle_t);
60 .Ed
61 .Sh STRUCTURE MEMBERS
62 .Bd -literal -offset indent
63 uint_t mc_callbacks; /* Denotes which callbacks are set */
64 mac_getstat_t mc_getstat; /* Get the value of a statistic */
65 mac_start_t mc_start; /* Start the device */
66 mac_stop_t mc_stop; /* Stop the device */
67 mac_setpromisc_t mc_setpromisc; /* Enable or disable promiscuous mode */
68 mac_multicst_t mc_multicst; /* Enable or disable a multicast addr */
69 mac_unicst_t mc_unicst; /* Set the unicast MAC address */
70 mac_tx_t mc_tx; /* Transmit a packet */
71 void *mc_reserved; /* Reserved, do not use */
72 mac_ioctl_t mc_ioctl; /* Process an unknown ioctl */
73 mac_getcapab_t mc_getcapab; /* Get capability information */
74 mac_open_t mc_open; /* Open the device */
75 mac_close_t mc_close; /* Close the device */
76 mac_set_prop_t mc_setprop; /* Set a device property */
77 mac_get_prop_t mc_getprop; /* Get a device property */
78 mac_prop_info_t mc_propinfo; /* Get property information */
79 .Ed
80 .Pp
81 The
82 .Sy mc_callbacks
83 member is used to denote which of a series of optional callbacks are
84 present. This method allows additional members to be added to the
85 .Sy mac_callbacks_t
86 structure while maintaining ABI compatibility with existing modules. If
87 a member is not mentioned below, then it is a part of the base version
88 of the structure and device drivers do not need to set anything to
89 indicate that it is present.
90 The
91 .Sy mc_callbacks
92 member should be set to the bitwise inclusive OR of the following
93 pre-processor values:
94 .Bl -tag -width Dv -offset indent
95 .It Sy MC_IOCTL
96 Indicates that the
97 .Sy mc_ioctl
98 structure member has been set.
99 .It Sy MC_GETCAPAB
100 Indicates that the
101 .Sy mc_getcapab
102 structure member has been set.
103 .It Sy MC_OPEN
104 Indicates that the
105 .Sy mc_open
106 structure member has been set.
107 .It Sy MC_CLOSE
108 Indicates that the
109 .Sy mc_close
110 structure member has been set.
111 .It Sy MC_SETPROP
112 Indicates that the
113 .Sy mc_setprop
114 structure member has been set.
115 .It Sy MC_GETPROP
116 Indicates that the
117 .Sy mc_getprop
118 structure member has been set.
119 .It Sy MC_PROPINFO
120 Indicates that the
121 .Sy mc_propinfo
122 structure member has been set.
123 .It Sy MC_PROPERTIES
124 Indicates that the
125 .Sy mc_getprop ,
126 .Sy mc_propinfo ,
127 and
128 .Sy mc_setprop
129 structure members have been set.
130 .El
131 .Pp
132 The
133 .Sy mc_getstat
134 function defines an entry point used to receive statistics about the
135 device. A list of statistics that it is required to support is available
136 in
137 .Xr mac 9E .
138 For more information on the requirements of the function, see
139 .Xr mc_getstat 9E .
140 .Pp
141 The
142 .Sy mc_start
143 member defines an entry point that is used to start the device. For more
144 information on the requirements of the function, see
145 .Xr mc_start 9E .
146 .Pp
147 The
148 .Sy mc_stop
149 member defines an entry point that is used to stop the device. It is the
150 opposite of the
151 .Sy mc_start
152 member. For more information on the requirements of the function, see
153 .Xr mc_stop 9E .
154 .Pp
155 The
156 .Sy mc_setpromisc
157 member is used to enable and disable promiscuous mode on the device. For
158 more information on the requirements of the function, see
159 .Xr mc_setpromisc 9E .
160 .Pp
161 The
162 .Sy mc_multicst
163 member is used to enable or disable multicast addresses in the device's
164 filters. For more information on the requirements of the function, see
165 .Xr mc_multicst 9E .
166 .Pp
167 The
168 .Sy mc_unicst
169 member is used to set the primary unicast MAC address of the device.
170 For more information on the requirements of the function, see
171 .Xr mc_unicst 9E .
172 .Pp
173 The
174 .Sy mc_tx
175 member is used to transmit a single message on the wire. For more
176 information on the requirements of the function, see
177 .Xr mc_tx 9E .
178 .Pp
179 The
180 .Sy mc_ioctl
181 member is used to process device specific ioctls. The GLDv3 does not
182 define any ioctls that devices should handle; however, there may be
183 private ioctls for this device. This entry point is optional. For it to
184 be considered, the
185 .Sy MC_IOCTL
186 value must be present in the
187 .Sy mc_callbacks
188 member. For more information on the requirements of the function, see
189 .Xr mc_ioctl 9E .
190 .Pp
191 The
192 .Sy mc_getcapab
193 member is used to determine device capabilities. Each capability has its
194 own data and semantics associated with it. A list of capabilities is
195 provided in
196 .Xr mac 9E .
197 This entry point is optional. For it to be used, the
198 .Sy MC_GETCAPAB
199 value must be present in the
200 .Sy mc_callbacks
201 member. For more information on the requirements of the function, see
202 .Xr mc_getcapab 9E .
203 .Pp
204 The
205 .Sy mc_open
206 member is used to provide specific actions to take when the device is
207 opened. Note that most device drivers will not have a need to implement
208 this. It is not required for this function to be implemented for this
209 device to be used with
210 .Xr dlpi 7P .
211 This entry point is optional. For it to be used, the
212 .Sy MC_OPEN
213 value must be present in the
214 .Sy mc_callbacks
215 member. For more information on the requirements of the function, see
216 .Xr mc_open 9E .
217 .Pp
218 The
219 .Sy mc_close
220 member is used to provide specific actions to take when the device is
221 closed. Note that most device drivers will not have a need to implement
222 this. It is not required for this function to be implemented for this
223 device to be used with
224 .Xr dlpi 7P .
225 This entry point is optional. For it to be used, the
226 .Sy MC_CLOSE
227 value must be present in the
228 .Sy mc_callbacks
229 member. For more information on the requirements of the function, see
230 .Xr mc_close 9E .
231 .Pp
232 The
233 .Sy mc_getprop
234 member is used to get the current value of a property from the device. A
235 list of properties, their sizes, and their interpretation is available
236 in
237 .Xr mac 9E .
238 This entry point is optional. For it to be used, the
239 .Sy MC_GETPROP
240 value must be present in the
241 .Sy mc_callbacks
242 member. For more information on the requirements of the function, see
243 .Xr mc_getprop 9E .
244 .Pp
245 The
246 .Sy mc_setprop
247 member is used to set the value of a device property. A list of
248 properties, their sizes, and their interpretation is available in
249 .Xr mac 9E .
250 This entry point is optional. For it to be used, the
251 .Sy MC_SETPROP
252 value must be present in the
253 .Sy mc_callbacks
254 member. For more information on the requirements of the function, see
255 .Xr mc_setprop 9E .
256 .Pp
257 The
258 .Sy mc_propinfo
259 member is used to obtain metadata about a property such as its default
260 value, whether or not it is writable, and more. A list of properties,
261 their sizes, and their interpretation is available in
262 .Xr mac 9E .
263 This entry point is optional. For it to be used, the
264 .Sy MC_PROPINFO
265 value must be present in the
266 .Sy mc_callbacks
267 member. For more information on the requirements of the function, see
268 .Xr mc_propinfo 9E .
269 .Pp
270 .Ss Required Members
271 Many members in the structure are optional; however, the following
272 members must be set or a call to
273 .Xr mac_register 9F
274 will fail.
275 .Bl -bullet -offset indent
276 .It
277 .Sy mc_getstat
278 .It
279 .Sy mc_start
280 .It
281 .Sy mc_stop
282 .It
283 . Sy mc_setpromisc
284 .It
285 .Sy mc_multicst
286 .It
287 .Sy mc_tx
288 .It
289 .Sy mc_unicst
290 .El
291 .Pp
292 Note, that devices which implement the GLDv3 ring capabilities must not
293 implement the
294 .Sy mc_unicst
295 and
296 .Sy mc_tx
297 functions. However, the ring capabilities are still private and evolving
298 at this time.
299 .Pp
300 Generally, a device that implements one of
301 .Sy mc_getprop ,
302 .Sy mc_setprop ,
303 or
304 .Sy mc_propinfo
305 will want to implement all three endpoints to ensure that the property
306 is fully integrated into user land utilities such as
307 .Xr dladm 1M .
308 .Sh SEE ALSO
309 .Xr dladm 1M ,
310 .Xr dlpi 7P ,
311 .Xr mac 9E ,
312 .Xr mc_close 9E ,
313 .Xr mc_getcapab 9E ,
314 .Xr mc_getprop 9E ,
315 .Xr mc_getstat 9E ,
316 .Xr mc_ioctl 9E ,
317 .Xr mc_multicst 9E ,
318 .Xr mc_open 9E ,
319 .Xr mc_propinfo 9E ,
320 .Xr mc_setpromisc 9E ,
321 .Xr mc_setprop 9E ,
322 .Xr mc_start 9E ,
323 .Xr mc_stop 9E ,
324 .Xr mc_tx 9E ,
325 .Xr mc_unicst 9E ,
326 .Xr mac_register 9S