| blob | 6f648e334893fbdef4a2fd8bc4f4ee9cbd7a7fa9 |
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 10, 2016
15 .Dt MAC_REGISTER 9S
16 .Os
17 .Sh NAME
18 .Nm mac_register ,
19 .Nm mac_register_t
20 .Nd networking device driver registration structure
21 .Sh SYNOPSIS
22 .In sys/mac_provider.h
23 .In sys/mac_ether.h
24 .Sh INTERFACE LEVEL
25 illumos DDI specific
26 .Sh DESCRIPTION
27 The
28 .Sy mac_register
29 structure is used by GLDv3 networking device drivers implementing the
30 .Xr mac 9E
31 interface.
32 .Pp
33 The structure is allocated by a call to
34 .Xr mac_alloc 9F
35 after which the various structure members should be set.
36 Once they have been set, the structure can be used by a GLDv3 device driver to
37 register with the MAC framework by calling the
38 .Xr mac_register 9F
39 function.
40 Once
41 .Xr mac_register 9F
42 has been called, the structure can be freed through a call to
43 .Xr mac_free 9F .
44 .Sh STRUCTURE MEMBERS
45 .Bd -literal -offset indent
46 uint_t m_version;
47 const char *m_type_ident;
48 void *m_driver;
49 dev_info_t *m_dip;
50 uint_t m_instance;
51 uint8_t *m_src_addr;
52 uint8_t *m_dst_addr;
53 mac_callbacks_t *m_callbacks;
54 uint_t m_min_sdu;
55 uint_t m_max_sdu;
56 void *m_pdata;
57 size_t m_pdata_size;
58 char **m_priv_props;
59 uint32_t m_margin;
60 .Ed
61 .Pp
62 The
63 .Sy m_version
64 member is set during a call to
65 .Xr mac_alloc 9F .
66 Device drivers should not modify this field.
67 .Pp
68 The
69 .Sy m_type_ident
70 member identifies the kind of networking device that this driver
71 represents.
72 The following constants should be used to identify the device type:
73 .Bl -tag -width Dv
74 .It Sy MAC_PLUGIN_IDENT_ETHER
75 The device driver implements IEEE 802.3 Ethernet.
76 .El
77 .Pp
78 The
79 .Sy m_driver
80 value is a private value that the device driver may set and will be
81 provided as an argument in many of the
82 .Xr mac 9E
83 callbacks.
84 Most often this is set to the driver's soft state for a specific instance.
85 .Pp
86 The
87 .Sy m_dip
88 member should point to the device driver's
89 .Sy dev_info
90 structure for that specific instance.
91 This structure is provided during the driver's
92 .Xr attach 9E
93 entry point.
94 .Pp
95 The
96 .Sy m_instance
97 member should be set to zero.
98 The GLDv3 framework will determine the appropriate instance.
99 .Pp
100 The
101 .Sy m_src_addr
102 member should be set to a byte array that describes the source MAC
103 address of the device.
104 This is usually the default MAC address as programmed by the device manufacturer
105 in that instance of the device.
106 .Pp
107 The
108 .Sy m_dst_addr
109 member is an optional property and should be set to
110 .Dv NULL
111 by most device drivers.
112 If set, this address will be the destination for outgoing frames.
113 .Pp
114 The
115 .Sy m_callbacks
116 member contains the GLDv3 entry points implemented by the device driver.
117 See
118 .Xr mac_callbacks 9S
119 for a full explanation of the structure, its members, and their
120 responsibilities.
121 See
122 .Xr mac 9E
123 for a broader picture of how the entry points are used.
124 .Pp
125 The
126 .Sy m_min_sdu
127 property is the minimum service data unit.
128 It represents the minimum size packet that the device can transmit, ignoring its
129 own headers.
130 Thus for an Ethernet device, this value would exclude the Ethernet header and
131 any VLAN headers.
132 If this is set to zero, then that means that either the MAC protocol does not
133 require a minimum size or that the device driver and hardware will ensure that
134 any minimum size is taken care of.
135 .Pp
136 The
137 .Sy m_max_sdu
138 property is the maximum service data unit.
139 It represents the maximum size packet that the device can transmit, ignoring its
140 own headers.
141 For an Ethernet based device, this would exclude the size of the Ethernet
142 header and a VLAN headers.
143 This value is often called the maximum transmission unit (MTU).
144 .Pp
145 The
146 .Sy m_pdata
147 member is used for data specific to the type specified in the
148 .Sy m_type_ident
149 member.
150 For all devices of type
151 .Sy MAC_PLUGIN_IDENT_ETHER ,
152 this should be set to
153 .Dv NULL .
154 .Pp
155 The
156 .Sy m_pdata_size
157 member indicates the size of the member
158 .Sy m_pdata .
159 For all devices of type
160 .Sy MAC_PLUGIN_IDENT_ETHER ,
161 this should be set to 0.
162 .Pp
163 The
164 .Sy m_priv_props
165 member is an optional member that lists device-specific properties.
166 These properties will be queried through functions like
167 .Xr mc_getprop 9E ,
168 .Xr mc_propinfo 9E ,
169 and
170 .Xr mc_setprop 9E .
171 If the driver does not have any private properties, it should be set to
172 .Dv NULL .
173 Otherwise, it should be set to a NULL-terminated array of character
174 strings where each entry is the name of a distinct property.
175 See
176 .Xr mac 9E
177 for more information on private properties.
178 .Pp
179 The
180 .Sy m_margin
181 property
182 indicates the amount of additional bytes of information that may be
183 included beyond the basic MAC header.
184 For example, with an Ethernet device, if the hardware supports a VLAN tag, then
185 this property would be set to the size of a VLAN tag, indicating that it
186 supported the additional bytes in a single packet beyond the Ethernet header and
187 the
188 .Sy m_max_sdu .
189 .Sh SEE ALSO
190 .Xr attach 9E ,
191 .Xr mac 9E ,
192 .Xr mac_alloc 9F ,
193 .Xr mac_free 9F ,
194 .Xr mac_register 9F ,
195 .Xr mac_callbacks 9S