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