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.man.txt
+++ new/usr/src/man/man9f/mac_register.9f.man.txt
1 1 MAC_REGISTER(9F) Kernel Functions for Drivers MAC_REGISTER(9F)
2 2
3 3 NAME
4 4 mac_register, mac_unregister - register and unregister a device driver
5 5 from the MAC framework
6 6
7 7 SYNOPSIS
8 8 #include <sys/mac_provider.h>
9 9
10 10 int
11 11 mac_register(mac_register_t *mregp, mac_handle_t *mhp);
12 12
13 13 int
14 14 mac_unregister(mac_handle_t mh);
15 15
16 16 INTERFACE LEVEL
17 17 illumos DDI specific
18 18
19 19 PARAMETERS
20 20 mregp A pointer to a mac_register(9S) structure allocated by
21 21 calling mac_alloc(9F) and filled in by the device driver.
22 22
23 23 mhp A pointer to a driver-backed handle to the MAC framework.
24 24
25 25 mh The driver-backed handle to the MAC framework.
26 26
27 27 DESCRIPTION
28 28 The mac_register() function is used to register an instance of a device
29 29 driver with the mac(9E) framework. Upon successfully calling the
30 30 mac_register() function, the device will start having its
31 31 mac_callbacks(9S) entry points called. The device driver should call
32 32 this function during it's attach(9E) entry point after the device has
33 33 been configured and is set up. For a more detailed explanation of the
34 34 exact steps that the device driver should take and where in the sequence
35 35 of a driver's attach(9E) entry point this function should be called, see
36 36 the Registering with MAC section of mac(9E).
37 37
38 38 The driver should provide a pointer to a mac_handle_t structure as the
39 39 second argument to the mac_register() function. This handle will be used
40 40 when the device driver needs to interact with the framework in various
41 41 ways throughout its life. It is also where the driver gets the mh
42 42 argument for calling the mac_unregister() function. It is recommended
43 43 that the device driver keep the handle around in its soft state structure
44 44 for a given instance.
45 45
46 46 If the call to the mac_register() function fails, the device driver
47 47 should unwind its attach(9E) entry point, tear down everything that it
48 48 initialized, and ultimately return an error from its attach(9E) entry
49 49 point.
50 50
51 51 If the attach(9E) routine fails for some reason after the call to the
52 52 mac_register() function has succeeded, then the driver should call the
53 53 mac_unregister() function as part of unwinding all of its state.
54 54
55 55 When a driver is in its detach(9E) entry point, it should call the
56 56 mac_unregister() function immediately after draining any of its transmit
57 57 and receive resources that might have been given to the rest of the
58 58 operating system through DMA binding. See the MBLKS AND DMA section of
59 59 mac(9E) for more information. This should be done before the driver does
60 60 any tearing down. The call to the mac_unregister() function may fail.
61 61 This may happen because the networking stack is still using the device.
62 62 In such a case, the driver should fail the call to detach(9E) and return
63 63 DDI_FAILURE.
64 64
65 65 CONTEXT
66 66 The mac_register() function is generally only called from a driver's
67 67 attach(9E) entry point. The mac_unregister() function is generally only
68 68 called from a driver's attach(9E) and detach(9E) entry point. However,
69 69 both functions may be called from either user or kernel context.
70 70
71 71 RETURN VALUES
72 72 Upon successful completion, the mac_register() and mac_unregister()
73 73 functions both return 0. Otherwise, they return an error number.
74 74
75 75 EXAMPLES
76 76 The following example shows how a device driver might call the
77 77 mac_register() function.
78 78
79 79 #include <sys/mac_provider.h>
80 80 #include <sys/mac_ether.h>
81 81
82 82 /*
83 83 * The call to mac_register(9F) generally comes from the context of
84 84 * attach(9E). This function encapsulates setting up and initializing
85 85 * the mac_register_t structure and should be assumed to be called from
86 86 * attach.
87 87 *
88 88 * The exact set of callbacks and private properties will vary based
|
↓ open down ↓ |
88 lines elided |
↑ open up ↑ |
89 89 * upon the driver.
90 90 */
91 91
92 92 static char *example_priv_props[] = {
93 93 "_rx_intr_throttle",
94 94 "_tx_intr_throttle",
95 95 NULL
96 96 };
97 97
98 98 static mac_callbacks_t example_m_callbacks = {
99 - .mc_callbacsk = MC_GETCAPAB | MC_SETPROP | MC_GETPROP | MC_PROPINFO |
99 + .mc_callbacks = MC_GETCAPAB | MC_SETPROP | MC_GETPROP | MC_PROPINFO |
100 100 MC_IOCTL,
101 101 .mc_start = example_m_start,
102 102 .mc_stop = example_m_stop,
103 103 .mc_setpromisc = example_m_setpromisc,
104 104 .mc_multicst = example_m_multicst,
105 105 .mc_unicst = example_m_unicst,
106 106 .mc_tx = example_m_tx,
107 107 .mc_ioctl = example_m_ioctl,
108 108 .mc_getcapab = example_m_getcapab,
109 109 .mc_getprop = example_m_getprop,
110 110 .mc_setprop = example_m_setprop,
111 111 .mc_propinfo = example_m_propinfo
112 112 };
113 113
114 114 static boolean_t
115 115 example_register_mac(example_t *ep)
116 116 {
117 117 int status;
118 118 mac_register_t *mac;
119 119
120 120 mac = mac_alloc(MAC_VERSION);
121 121 if (mac == NULL)
|
↓ open down ↓ |
12 lines elided |
↑ open up ↑ |
122 122 return (B_FALSE);
123 123
124 124 mac->m_type_ident = MAC_PLUGIN_IDENT_ETHER;
125 125 mac->m_driver = ep;
126 126 mac->m_dip = ep->ep_dev_info;
127 127 mac->m_src_addr = ep->ep_mac_addr;
128 128 mac->m_callbacks = &example_m_callbacks;
129 129 mac->m_min_sdu = 0;
130 130 mac->m_max_sdu = ep->ep_sdu;
131 131 mac->m_margin = VLAN_TAGSZ;
132 - mac->m_priv_props = exmple_priv_props;
132 + mac->m_priv_props = example_priv_props;
133 133
134 134 status = mac_register(mac, &ep->ep_mac_hdl);
135 135 mac_free(mac);
136 136
137 137 return (status == 0);
138 138 }
139 139
140 140 ERRORS
141 141 The mac_register() function may fail if:
142 142
143 143 EEXIST A driver with the same name and instance already
144 144 exists.
145 145
146 146 EINVAL There was something invalid with the device's
147 147 registration information. Some of the following
148 148 reasons may apply, this list is not exhaustive:
149 149
150 150 o The mac_init_ops(9F) function was not called.
151 151
152 152 o The specified mac plugin does not exist.
153 153
154 154 o An invalid minor number was used.
155 155
156 156 o The default unicast source address was incorrect.
157 157
158 158 o The plugin specific private data was incorrect or
159 159 missing.
160 160
161 161 o Plugin specific data was provided when none is
162 162 required.
163 163
164 164 o Required callback functions are not specified.
165 165
166 166 o The system was unable to properly create minor
167 167 nodes.
168 168
169 169 ENOSPC The mac(9E) framework was unable to allocate a minor
170 170 number for the device as they have all been exhausted.
171 171
172 172 The mac_unregister() function will fail if:
173 173
174 174 EBUSY The device is still in use.
175 175
176 176 ENOTEMPTY The flow table is not empty.
|
↓ open down ↓ |
34 lines elided |
↑ open up ↑ |
177 177
178 178 Note the set of errors for both the mac_regster() and mac_unregister()
179 179 functions are not set in stone and may be expanded in future revisions.
180 180 In general, all errors should be handled by the device driver in similar
181 181 ways for these functions.
182 182
183 183 SEE ALSO
184 184 attach(9E), detach(9E), mac(9E), mac_alloc(9F), mac_init_ops(9F),
185 185 mac_callbacks(9S), mac_register(9S)
186 186
187 -illumos September 22, 2017 illumos
187 +illumos February 15, 2020 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX