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