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 (c) 2017, Joyent, Inc.
13 .\"
14 .Dd September 22, 2017
15 .Dt MAC_REGISTER 9F
16 .Os
17 .Sh NAME
18 .Nm mac_register ,
19 .Nm mac_unregister
20 .Nd register and unregister a device driver from the MAC framework
21 .Sh SYNOPSIS
22 .In sys/mac_provider.h
23 .Ft int
24 .Fo mac_register
25 .Fa "mac_register_t *mregp"
26 .Fa "mac_handle_t *mhp"
27 .Fc
28 .Ft int
29 .Fo mac_unregister
30 .Fa "mac_handle_t mh"
31 .Fc
32 .Sh INTERFACE LEVEL
33 illumos DDI specific
34 .Sh PARAMETERS
35 .Bl -tag -width Fa
36 .It Fa mregp
37 A pointer to a
38 .Xr mac_register 9S
39 structure allocated by calling
40 .Xr mac_alloc 9F
41 and filled in by the device driver.
42 .It Fa mhp
43 A pointer to a driver-backed handle to the MAC framework.
44 .It Fa mh
45 The driver-backed handle to the MAC framework.
46 .El
47 .Sh DESCRIPTION
48 The
49 .Fn mac_register
50 function is used to register an instance of a device driver with the
51 .Xr mac 9E
52 framework.
53 Upon successfully calling the
54 .Fn mac_register
55 function, the device will start having its
56 .Xr mac_callbacks 9S
57 entry points called.
58 The device driver should call this function during it's
59 .Xr attach 9E
60 entry point after the device has been configured and is set up.
61 For a more detailed explanation of the exact steps that the device driver
62 should take and where in the sequence of a driver's
63 .Xr attach 9E
64 entry point this function should be called, see the
65 .Sx Registering with MAC
66 section of
67 .Xr mac 9E .
68 .Pp
69 The driver should provide a pointer to a
70 .Ft mac_handle_t
71 structure as the second argument to the
72 .Fn mac_register
73 function.
74 This handle will be used when the device driver needs to interact with the
75 framework in various ways throughout its life.
76 It is also where the driver gets the
77 .Fa mh
78 argument for calling the
79 .Fn mac_unregister
80 function.
81 It is recommended that the device driver keep the handle around in its soft
82 state structure for a given instance.
83 .Pp
84 If the call to the
85 .Fn mac_register
86 function fails, the device driver should unwind its
87 .Xr attach 9E
88 entry point, tear down everything that it initialized, and ultimately
89 return an error from its
90 .Xr attach 9E
91 entry point.
92 .Pp
93 If the
94 .Xr attach 9E
95 routine fails for some reason after the call to the
96 .Fn mac_register
97 function has succeeded, then the driver should call the
98 .Fn mac_unregister
99 function as part of unwinding all of its state.
100 .Pp
101 When a driver is in its
102 .Xr detach 9E
103 entry point, it should call the
104 .Fn mac_unregister
105 function immediately after draining any of its transmit and receive
106 resources that might have been given to the rest of the operating system
107 through DMA binding.
108 See the
109 .Sx MBLKS AND DMA
110 section of
111 .Xr mac 9E
112 for more information.
113 This should be done before the driver does any tearing down.
114 The call to the
115 .Fn mac_unregister
116 function may fail.
117 This may happen because the networking stack is still using the device.
118 In such a case, the driver should fail the call to
119 .Xr detach 9E
120 and return
121 .Sy DDI_FAILURE .
122 .Sh CONTEXT
123 The
124 .Fn mac_register
125 function is generally only called from a driver's
126 .Xr attach 9E
127 entry point.
128 The
129 .Fn mac_unregister
130 function is generally only called from a driver's
131 .Xr attach 9E
132 and
133 .Xr detach 9E
134 entry point.
135 However, both functions may be called from either
136 .Sy user
137 or
138 .Sy kernel
139 context.
140 .Sh RETURN VALUES
141 Upon successful completion, the
142 .Fn mac_register
143 and
144 .Fn mac_unregister
145 functions both return
146 .Sy 0 .
147 Otherwise, they return an error number.
148 .Sh EXAMPLES
149 The following example shows how a device driver might call the
150 .Fn mac_register
151 function.
152 .Bd -literal
153 #include <sys/mac_provider.h>
154 #include <sys/mac_ether.h>
155
156 /*
157 * The call to mac_register(9F) generally comes from the context of
158 * attach(9E). This function encapsulates setting up and initializing
159 * the mac_register_t structure and should be assumed to be called from
160 * attach.
161 *
162 * The exact set of callbacks and private properties will vary based
163 * upon the driver.
164 */
165
166 static char *example_priv_props[] = {
167 "_rx_intr_throttle",
168 "_tx_intr_throttle",
169 NULL
170 };
171
172 static mac_callbacks_t example_m_callbacks = {
173 .mc_callbacsk = MC_GETCAPAB | MC_SETPROP | MC_GETPROP | MC_PROPINFO |
174 MC_IOCTL,
175 .mc_start = example_m_start,
176 .mc_stop = example_m_stop,
177 .mc_setpromisc = example_m_setpromisc,
178 .mc_multicst = example_m_multicst,
179 .mc_unicst = example_m_unicst,
180 .mc_tx = example_m_tx,
181 .mc_ioctl = example_m_ioctl,
182 .mc_getcapab = example_m_getcapab,
183 .mc_getprop = example_m_getprop,
184 .mc_setprop = example_m_setprop,
185 .mc_propinfo = example_m_propinfo
186 };
187
188 static boolean_t
189 example_register_mac(example_t *ep)
190 {
191 int status;
192 mac_register_t *mac;
193
194 mac = mac_alloc(MAC_VERSION);
195 if (mac == NULL)
196 return (B_FALSE);
197
198 mac->m_type_ident = MAC_PLUGIN_IDENT_ETHER;
199 mac->m_driver = ep;
200 mac->m_dip = ep->ep_dev_info;
201 mac->m_src_addr = ep->ep_mac_addr;
202 mac->m_callbacks = &example_m_callbacks;
203 mac->m_min_sdu = 0;
204 mac->m_max_sdu = ep->ep_sdu;
205 mac->m_margin = VLAN_TAGSZ;
206 mac->m_priv_props = exmple_priv_props;
207
208 status = mac_register(mac, &ep->ep_mac_hdl);
209 mac_free(mac);
210
211 return (status == 0);
212 }
213 .Ed
214 .Sh ERRORS
215 The
216 .Fn mac_register
217 function may fail if:
218 .Bl -tag -width Er
219 .It EEXIST
220 A driver with the same name and instance already exists.
221 .It EINVAL
222 There was something invalid with the device's registration information.
223 Some of the following reasons may apply, this list is not exhaustive:
224 .Bl -bullet
225 .It
226 The
227 .Xr mac_init_ops 9F
228 function was not called.
229 .It
230 The specified mac plugin does not exist.
231 .It
232 An invalid minor number was used.
233 .It
234 The default unicast source address was incorrect.
235 .It
236 The plugin specific private data was incorrect or missing.
237 .It
238 Plugin specific data was provided when none is required.
239 .It
240 Required callback functions are not specified.
241 .It
242 The system was unable to properly create minor nodes.
243 .El
244 .It ENOSPC
245 The
246 .Xr mac 9E
247 framework was unable to allocate a minor number for the device as they
248 have all been exhausted.
249 .El
250 .Pp
251 The
252 .Fn mac_unregister
253 function will fail if:
254 .Bl -tag -width Er
255 .It Er EBUSY
256 The device is still in use.
257 .It Er ENOTEMPTY
258 The flow table is not empty.
259 .El
260 .Pp
261 Note the set of errors for both the
262 .Fn mac_regster
263 and
264 .Fn mac_unregister
265 functions are not set in stone and may be expanded in future revisions.
266 In general, all errors should be handled by the device driver in similar
267 ways for these functions.
268 .Sh SEE ALSO
269 .Xr attach 9E ,
270 .Xr detach 9E ,
271 .Xr mac 9E ,
272 .Xr mac_alloc 9F ,
273 .Xr mac_init_ops 9F ,
274 .Xr mac_callbacks 9S ,
275 .Xr mac_register 9S