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