usr/src/man/man9s/gld_mac_info.9s

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GLD_MAC_INFO 9S "Jun 7, 2004"
   7 .SH NAME
   8 gld_mac_info \- Generic LAN Driver MAC info data structure
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/gld.h>
  13 .fi
  14
  15 .SH INTERFACE LEVEL
  16 .sp
  17 .LP
  18 Solaris architecture specific (Solaris DDI).
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The Generic LAN Driver (GLD) Media Access Control (MAC) information
  23 (\fBgld_mac_info\fR) structure is the main data interface between the
  24 device-specific driver and GLD. It contains data required by GLD and a pointer
  25 to an optional additional driver-specific information structure.
  26 .sp
  27 .LP
  28 The \fBgld_mac_info\fR structure should be allocated using
  29 \fBgld_mac_alloc()\fR and deallocated using \fBgld_mac_free()\fR. Drivers can
  30 make no assumptions about the length of this structure, which might be
  31 different in different releases of Solaris and/or GLD. Structure members
  32 private to GLD, not documented here, should not be set or read by the
  33 device-specific driver.
  34 .SH STRUCTURE MEMBERS
  35 .sp
  36 .in +2
  37 .nf
  38 caddr_t         gldm_private;              /* Driver private data */
  39 int               (*gldm_reset)();         /* Reset device */
  40 int               (*gldm_start)();         /* Start device */
  41 int               (*gldm_stop)();          /* Stop device */
  42 int               (*gldm_set_mac_addr)();  /* Set device phys addr */
  43 int               (*gldm_set_multicast)(); /* Set/delete */
  44                                             /* multicast address */
  45 int               (*gldm_set_promiscuous)();
  46                                             /* Set/reset promiscuous */
  47                                             /* mode*/
  48 int               (*gldm_send)();          /* Transmit routine */
  49 u_int             (*gldm_intr)();          /* Interrupt handler */
  50 int               (*gldm_get_stats)();     /* Get device statistics */
  51 int               (*gldm_ioctl)();         /* Driver-specific ioctls */
  52 char             *gldm_ident;              /* Driver identity string */
  53 uint32_t          gldm_type;               /* Device type */
  54 uint32_t          gldm_minpkt;             /* Minimum packet size */
  55                                             /* accepted by driver */
  56 uint32_t          gldm_maxpkt;             /* Maximum packet size */
  57                                             /* accepted by driver */
  58 uint32_t          gldm_addrlen;            /* Physical address */
  59                                             /* length */
  60 int32_t           gldm_saplen;             /* SAP length for */
  61                                             /* DL_INFO_ACK */
  62 unsigned char    *gldm_broadcast_addr;     /* Physical broadcast */
  63                                             /* addr */
  64 unsigned char    *gldm_vendor_addr;        /* Factory MAC address */
  65 t_uscalar_t       gldm_ppa;                /* Physical Point of */
  66                                             /* Attachment (PPA) number */
  67 dev_info_t       *gldm_devinfo;            /* Pointer to device's */
  68                                             /* dev_info node */
  69 ddi_iblock_cookie_tgldm_cookie;            /* Device's interrupt */
  70                                             /* block cookie */
  71 int               gldm_margin              /* accepted data beyond */
  72                                             /*gldm_maxpkt */
  73 uint32_t          gldm_capabilities;       /* Device capabilities */
  74 .fi
  75 .in -2
  76 .sp
  77
  78 .sp
  79 .LP
  80 Below is a description of the members of the \fBgld_mac_info\fR structure that
  81 are visible to the device driver.
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBgldm_private\fR\fR
  86 .ad
  87 .RS 16n
  88 This structure member is private to the device-specific driver and is not used
  89 or modified by GLD. Conventionally, this is used as a pointer to private data,
  90 pointing to a driver-defined and driver-allocated per-instance data structure.
  91 .RE
  92
  93 .sp
  94 .LP
  95 The following group of structure members must be set by the driver before
  96 calling \fBgld_register()\fR, and should not thereafter be modified by the
  97 driver; \fBgld_register()\fR can use or cache the values of some of these
  98 structure members, so changes made by the driver after calling
  99 \fBgld_register()\fR might cause unpredicted results.
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBgldm_reset\fR\fR
 104 .ad
 105 .RS 24n
 106 Pointer to driver entry point; see \fBgld\fR(9E).
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBgldm_start\fR\fR
 113 .ad
 114 .RS 24n
 115 Pointer to driver entry point; see \fBgld\fR(9E).
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBgldm_stop\fR\fR
 122 .ad
 123 .RS 24n
 124 Pointer to driver entry point; see \fBgld\fR(9E).
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBgldm_set_mac_addr\fR\fR
 131 .ad
 132 .RS 24n
 133 Pointer to driver entry point; see \fBgld\fR(9E).
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBgldm_set_multicast\fR\fR
 140 .ad
 141 .RS 24n
 142 Pointer to driver entry point; see \fBgld\fR(9E).
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBgldm_set_promiscuous\fR\fR
 149 .ad
 150 .RS 24n
 151 Pointer to driver entry point; see \fBgld\fR(9E).
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBgldm_send\fR\fR
 158 .ad
 159 .RS 24n
 160 Pointer to driver entry point; see \fBgld\fR(9E).
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBgldm_intr\fR\fR
 167 .ad
 168 .RS 24n
 169 Pointer to driver entry point; see \fBgld\fR(9E).
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBgldm_get_stats\fR\fR
 176 .ad
 177 .RS 24n
 178 Pointer to driver entry point; see \fBgld\fR(9E).
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBgldm_ioctl\fR\fR
 185 .ad
 186 .RS 24n
 187 Pointer to driver entry point; can be \fINULL\fR; see \fBgld\fR(9E).
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fBgldm_ident\fR\fR
 194 .ad
 195 .RS 24n
 196 Pointer to a string containing a short description of the device. It is used to
 197 identify the device in system messages.
 198 .RE
 199
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBgldm_type\fR\fR
 204 .ad
 205 .RS 24n
 206 The type of device the driver handles. The values currently supported by GLD
 207 are \fBDL_ETHER\fR (IEEE 802.3 and Ethernet Bus), \fBDL_TPR\fR (IEEE 802.5
 208 Token Passing Ring), and \fBDL_FDDI\fR (ISO 9314-2 Fibre Distributed Data
 209 Interface). This structure member must be correctly set for GLD to function
 210 properly.
 211 .sp
 212 Support for the DL_TPR and DL_FDDI media types is obsolete and may be removed
 213 in a future release of Solaris.
 214 .RE
 215
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fBgldm_minpkt\fR\fR
 220 .ad
 221 .RS 24n
 222 Minimum \fIService\fR \fIData\fR \fIUnit\fR size \(em the minimum packet size,
 223 not including the MAC header, that the device will transmit. This can be zero
 224 if the device-specific driver can handle any required padding.
 225 .RE
 226
 227 .sp
 228 .ne 2
 229 .na
 230 \fB\fBgldm_maxpkt\fR\fR
 231 .ad
 232 .RS 24n
 233 Maximum \fIService\fR \fIData\fR \fIUnit\fR size \(em the maximum size of
 234 packet, not including the MAC header, that can be transmitted by the device.
 235 For Ethernet, this number is 1500.
 236 .RE
 237
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBgldm_addrlen\fR\fR
 242 .ad
 243 .RS 24n
 244 The length in bytes of physical addresses handled by the device. For Ethernet,
 245 Token Ring, and FDDI, the value of this structure member should be 6.
 246 .RE
 247
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fBgldm_saplen\fR\fR
 252 .ad
 253 .RS 24n
 254 The length in bytes of the Service Access Point (SAP) address used by the
 255 driver. For GLD-based drivers, this should always be set to -2, to indicate
 256 that two-byte SAP values are supported and that the SAP appears \fIafter\fR the
 257 physical address in a DLSAP address. See the description under ``Message
 258 DL_INFO_ACK'' in the DLPI specification for more details.
 259 .RE
 260
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fBgldm_broadcast_addr\fR\fR
 265 .ad
 266 .RS 24n
 267 Pointer to an array of bytes of length \fBgldm_addrlen\fR containing the
 268 broadcast address to be used for transmit. The driver must allocate space to
 269 hold the broadcast address, fill it in with the appropriate value, and set
 270 \fBgldm_broadcast_addr\fR to point at it. For Ethernet, Token Ring, and FDDI,
 271 the broadcast address is normally 0xFF-FF-FF-FF-FF-FF.
 272 .RE
 273
 274 .sp
 275 .ne 2
 276 .na
 277 \fB\fBgldm_vendor_addr\fR\fR
 278 .ad
 279 .RS 24n
 280 Pointer to an array of bytes of length \fBgldm_addrlen\fR containing the
 281 vendor-provided network physical address of the device. The driver must
 282 allocate space to hold the address, fill it in with information read from the
 283 device, and set \fBgldm_vendor_addr\fR to point at it.
 284 .RE
 285
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fBgldm_ppa\fR\fR
 290 .ad
 291 .RS 24n
 292 The Physical Point of Attachment (PPA) number for this instance of the device.
 293 Normally this should be set to the instance number, returned from
 294 \fBddi_get_instance\fR(9F).
 295 .RE
 296
 297 .sp
 298 .ne 2
 299 .na
 300 \fB\fBgldm_devinfo\fR\fR
 301 .ad
 302 .RS 24n
 303 Pointer to the \fBdev_info\fR node for this device.
 304 .RE
 305
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fBgldm_cookie\fR\fR
 310 .ad
 311 .RS 24n
 312 The interrupt block cookie returned by \fBddi_get_iblock_cookie\fR(9F),
 313 \fBddi_add_intr\fR(9F), \fBddi_get_soft_iblock_cookie\fR(9F), or
 314 \fBddi_add_softintr\fR(9F). This must correspond to the device's receive
 315 interrupt, from which \fBgld_recv()\fR is called.
 316 .RE
 317
 318 .sp
 319 .ne 2
 320 .na
 321 \fB\fBgldm_margin\fR\fR
 322 .ad
 323 .RS 24n
 324 Drivers set this value to the amount of data in bytes that the device can
 325 transmit beyond \fBgldm_maxpkt\fR. For example, if an Ethernet device can
 326 handle packets whose payload section is no greater than 1522 bytes and the
 327 \fBgldm_maxpkt\fR is set to 1500 (as is typical for Ethernet), then
 328 \fBgldm_margin\fR is set to 22. The registered \fBgldm_margin\fR value is
 329 reported in acknowledgements of the DLIOCMARGININFO ioctl (see \fBdlpi\fR(7P)).
 330 .RE
 331
 332 .sp
 333 .ne 2
 334 .na
 335 \fB\fBgldm_capabilities\fR\fR
 336 .ad
 337 .RS 24n
 338 Bit-field of device capabilities. If the device is capable of reporting media
 339 link state, the GLD_CAP_LINKSTATE bit should be set.
 340 .RE
 341
 342 .SH SEE ALSO
 343 .sp
 344 .LP
 345 \fBgld\fR(7D), \fBdlpi\fR(7P), \fBattach\fR(9E), \fBgld\fR(9E),
 346 \fBddi_add_intr\fR(9F), \fBgld\fR(9F), \fBgld_stats\fR(9S)
 347 .sp
 348 .LP
 349 \fIWriting Device Drivers\fR