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