'\" te .\" Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved. .TH mac 9E "21 Apr 2015" "SunOS 5.11" "Driver Entry Points" .SH NAME mac, mc_getstat, mc_start, mc_stop, mc_setpromisc, mc_multicst, mc_unicst, mc_tx, mc_ioctl, mc_getcapab, mc_setprop, mc_getprop, mc_propinfo \- MAC driver entry points .SH SYNOPSIS .LP .nf #include #include int prefix_getstat(void *\fIdriver_handle\fR, uint_t \fIstat\fR, uint64_t *\fIstat_value\fR); .fi .LP .nf int prefix_start(void *\fIdriver_handle\fR); .fi .LP .nf void prefix_stop(void *\fIdriver_handle\fR); .fi .LP .nf int prefix_setpromisc(void *\fIdriver_handle\fR, boolean_t \fIpromisc_mode\fR); .fi .LP .nf int prefix_multicst(void *\fIdriver_handle\fR, boolean_t \fIadd\fR, const uint8_t *\fImcast_addr\fR); .fi .LP .nf int prefix_unicst(void *\fIdriver_handle\fR, const uint8_t *\fIucast_addr\fR); .fi .LP .nf mblk_t *prefix_tx(void *\fIdriver_handle\fR, mblk_t *\fImp_chain\fR); .fi .LP .nf void prefix_ioctl(void *\fIdriver_handle\fR, queue_t *\fIq\fR, mblk_t *\fImp\fR); .fi .LP .nf boolean_t prefix_getcapab(void *\fIdriver_handle\fR, mac_capab_t \fIcap\fR, void *\fIcap_data\fR); .fi .LP .nf int prefix_setprop(void *\fIdriver_handle\fR, const char *\fIprop_name\fR, mac_prop_id_t \fIprop_id\fR, uint_t \fIprop_val_size\fR, const void *\fIprop_val\fR); .fi .LP .nf int prefix_getprop(void *\fIdriver_handle\fR, const char *\fIprop_name\fR, mac_prop_id_t \fIprop_id\fR, uint_t \fIprop_val_size\fR, void *\fIprop_val\fR); .fi .LP .nf void prefix_propinfo(void *\fIdriver_handle\fR, const char *\fIprop_name\fR, mac_prop_id_t \fIprop_id\fR, mac_prop_info_handle_t \fIprop_handle\fR); .fi .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIdriver_handle\fR\fR .ad .RS 17n .rt pointer to the driver-private handle that was specified by the device driver through the \fIm_driver\fR field of the \fBmac_register\fR(9S) structure during registration. .RE .sp .ne 2 .mk .na \fB\fIstat\fR\fR .ad .RS 17n .rt statistic being queried .RE .sp .ne 2 .mk .na \fB\fIstat_val\fR\fR .ad .RS 17n .rt value of statistic being queried .RE .sp .ne 2 .mk .na \fB\fIpromisc_mode\fR\fR .ad .RS 17n .rt promiscuous mode to be set .RE .sp .ne 2 .mk .na \fB\fIadd\fR\fR .ad .RS 17n .rt whether to add or delete the multicast address .RE .sp .ne 2 .mk .na \fB\fImcast_addr\fR\fR .ad .RS 17n .rt value of the multicast address to add or remove .RE .sp .ne 2 .mk .na \fB\fIucast_addr\fR\fR .ad .RS 17n .rt value of the unicast address to set .RE .sp .ne 2 .mk .na \fB\fIq\fR\fR .ad .RS 17n .rt STREAMS queue for ioctl operation .RE .sp .ne 2 .mk .na \fB\fImp\fR\fR .ad .RS 17n .rt message block for ioctl operation .RE .sp .ne 2 .mk .na \fB\fImp_chain\fR\fR .ad .RS 17n .rt chain of message blocks to be sent .RE .sp .ne 2 .mk .na \fB\fIcap\fR\fR .ad .RS 17n .rt capability type, \fBMAC_CAPAB_HCKSUM\fR or \fBMAC_CAPAB_LSO\fR .RE .sp .ne 2 .mk .na \fB\fIcap_data\fR\fR .ad .RS 17n .rt pointer to capability data. The type of data depends on the capability type specified by \fIcap\fR. .RE .sp .ne 2 .mk .na \fB\fIprop_name\fR\fR .ad .RS 17n .rt name of a driver-private property .RE .sp .ne 2 .mk .na \fB\fIprop_id\fR\fR .ad .RS 17n .rt property identifier .RE .sp .ne 2 .mk .na \fB\fIprop_val_size\fR\fR .ad .RS 17n .rt property value size, in bytes .RE .sp .ne 2 .mk .na \fB\fIprop_val\fR\fR .ad .RS 17n .rt pointer to a property value .RE .sp .ne 2 .mk .na \fB\fIprop_flags\fR\fR .ad .RS 17n .rt property query flags .RE .sp .ne 2 .mk .na \fB\fIprop_perm\fR\fR .ad .RS 17n .rt property permissions .RE .SH INTERFACE LEVEL .sp .LP Solaris architecture specific (Solaris DDI) .SH DESCRIPTION .sp .LP The entry points described below are implemented by a MAC device driver and passed to the MAC layer through the \fBmac_register\fR structure as part of the registration process using \fBmac_register\fR(9F). .sp .LP The \fBmc_getstat()\fR entry point returns through the 64 bit unsigned integer pointed to by \fIstat_value\fR the value of the statistic specified by the stat argument. Supported statistics are listed in the \fBStatistics\fR section below. The device driver \fBmc_getstat()\fR entry point should return 0 if the statistics is successfully passed back to the caller, or \fBENOTSUP\fR if the statistic is not supported by the device driver. .sp .LP The \fBmc_start()\fR entry point starts the device driver instance specified by \fIdriver_handle\fR. .sp .LP The \fBmc_stop()\fR entry point stops the device driver instance specified by \fIdriver_handle\fR. The MAC layer will invoke the stop entry point before the device is detached. .sp .LP The \fBmc_setpromisc()\fR entry point is used to change the promiscuous mode of the device driver instance specified by \fIdriver_handle\fR. Promiscuous mode should be turned on if the \fIpromisc_mode\fR is set to \fBB_TRUE\fR and off if the \fIpromisc_mode\fR is set to \fBB_FALSE\fR. .sp .LP The \fBmc_multicst()\fR entry point adds or remove the multicast address pointed to by \fImcast_addr\fR to or from the device instance specified by \fIdriver_handle\fR. .sp .LP The \fBmc_unicst()\fR entry point sets the primary unicast address of the device instance specified by \fIdriver_handle\fR to the value specified by \fIucast_addr\fR. The device must start passing back through \fBmac_rx()\fR the packets with a destination MAC address which matches the new unicast address. .sp .LP The \fBmc_tx()\fR entry point is used to transmit the message block on the device driver instance specified by \fIdriver_instance\fR. If the message block could not be submitted to the hardware for processing, the entry point returns \fINULL\fR. If the hardware resources were exhausted, the entry point returns the message block that could not be sent. In that case, the driver is responsible for invoking the \fBmac_tx_update\fR(9F) entry point when more hardware transmit resources are available to resume transmission. The driver is responsible for freeing the message block once the packet has been consumed by the hardware. .sp .LP The \fBmc_ioctl()\fR entry point is a generic facility which can be used to pass arbitrary ioctl to a driver from STREAMs clients. This facility is intended to be used only for debugging purpose only. The STREAMs \fBM_IOCTL\fR messages can be generated by a user-space application and passed done to the device \fBlibdlpi\fR(3LIB). .sp .LP The \fBmc_getcapab()\fR entry point queries a specific capability from the driver. The cap argument specifies the type of capability being queried, and \fIcap_data\fR is used by the driver to return the capability data to the framework, if any. It the driver does not support the capability specified by the framework, it must return \fBB_FALSE\fR, otherwise the driver must return \fBB_TRUE\fR. The following capabilities are supported: .sp .ne 2 .mk .na \fB\fBMAC_CAPAB_HCKSUM\fR\fR .ad .sp .6 .RS 4n The \fIcap_data\fR argument points to a \fBuint32_t\fR location. The driver must return in \fIcap_data\fR a combination of one of the following flags: .sp .ne 2 .mk .na \fB\fBHCKSUM_INET_PARTIAL\fR\fR .ad .sp .6 .RS 4n Partial 1's complement checksum ability. .RE .sp .ne 2 .mk .na \fB\fBHCKSUM_INET_FULL_V4\fR\fR .ad .sp .6 .RS 4n Full 1's complement checksum ability for IPv4 packets. .RE .sp .ne 2 .mk .na \fB\fBHCKSUM_INET_FULL_V6\fR\fR .ad .sp .6 .RS 4n Full 1's complement checksum ability for IPv6 packets. .RE .sp .ne 2 .mk .na \fB\fBHCKSUM_IPHDRCKSUM\fR\fR .ad .sp .6 .RS 4n IPv4 Header checksum offload capability. .RE These flags indicate the level of hardware checksum offload that the driver is capable of performing for outbound packets. .sp When hardware checksumming is enabled, the driver must use the \fBmac_hcksum_get\fR(9F) function to retrieve the per-packet hardware checksumming metadata. .RE .sp .ne 2 .mk .na \fB\fBMAC_CAPAB_LSO\fR\fR .ad .sp .6 .RS 4n The \fIcap_data\fR argument points to a \fBmac_capab_lso_t\fR structure which describes the LSO capabilities of the driver, and is described in detail in \fBmac_capab_lso\fR(9S). .RE .sp .ne 2 .mk .na \fB\fBMAC_CAPAB_RINGS\fR\fR .ad .sp .6 .RS 4n The \fIcap_data\fR argument points to a \fBmac_capab_rings_t\fR structure that describes the hardware transmit and receive rings (DMA channels) capabilities of the driver. This information allows the framework to schedule the traffic arriving from receive rings, associate MAC addresses with receive rings, group receive rings, and fan out outbound traffic to multiple transmit rings. See \fBmac_capab_rings\fR(9S) for more information. .RE .sp .LP The \fBmc_setprop()\fR and \fBmc_getprop()\fR entry points set and get, respectively, the value of a property for the device driver instance specified by \fIdriver_handle\fR. The property is specified by the \fIprop_id\fR argument, and is one of the properties identifier listed in section \fBProperties\fR below. The value of the property is stored in a buffer at \fIprop_val\fR, and the size of that buffer is specified by \fIprop_val_size\fR. The MAC layer ensures that the buffer is large enough to store the property specified by \fIprop_id\fR. The type of each property is listed in the \fBProperties\fR section below. .sp .LP The \fBmc_propinfo()\fR entry point returns immutable attributes of a property for the device driver instance specified by \fIdriver_handle\fR. The property is specified by the \fIprop_id\fR argument, and is one of the properties identifier listed in section \fBProperties\fR below. The entry point invokes the \fBmac_prop_info_set_perm()\fR, \fBmac_prop_info_set_default()\fR, or \fBmac_prop_info_set_range()\fR functions to associate specific attributes of the property being queried. The opaque property handle passed to the \fBmc_propinfo()\fR entry point must be passed as-is to these routines. .sp .LP In addition to the properties listed in the Properties section below, drivers can also expose driver-private properties. These properties are identified by property names strings. Private property names always start with an underscore (_) character and must be no longer than 256 characters, including a null-terminating character. Driver-private properties supported by a device driver are specified by the \fIm_priv_props\fR field of the \fBmac_register\fR data structure. During a call to \fBmc_setprop()\fR, \fBmc_getprop()\fR, or \fBmc_propinfo()\fR, a private property is specified by a property id of \fBMAC_PROP_PRIVATE\fR, and the driver property name is passed through the \fIprop_name\fR argument. Private property values are always specified by a string. The driver is responsible to encode and parse private properties value strings. .SH RETURN VALUES .sp .LP The \fBmc_getstat()\fR entry point returns 0 on success, or \fBENOTSUP\fR if the specific statistic is not supported by the device driver. .sp .LP The \fBmc_start()\fR, \fBmc_setpromisc()\fR, \fBmc_multicst()\fR, and \fBmc_unicst()\fR entry points return 0 on success and one of the error values specified by \fBIntro\fR(2) on failure. .sp .LP The \fBmc_getcapab()\fR entry point returns \fBB_TRUE\fR if the capability is supported by the device driver, \fBB_FALSE\fR otherwise. .sp .LP The \fBmc_tx()\fR entry point returns NULL if all packets could be posted on the hardware to be sent. The entry point returns a chain of unsent message blocks if the transmit resources were exhausted. .sp .LP The \fBmc_setprop()\fR and \fBmc_getprop()\fR entry points return 0 on success, \fBENOTSUP\fR if the property is not supported by the device driver, or an error value specified by \fBIntro\fR(2) for other failures. .SH CONTEXT .sp .LP The \fBmc_tx()\fR entry point can be called from interrupt context. The other entry points can be called from user or kernel context. .SH STATISTICS .sp .LP The stat argument value of the \fBmc_getstat()\fR entry point is used by the framework to specify the specific statistic being queried. The following statistics are supported by all media types: .sp .LP MIB-II stats (RFC 1213 and RFC 1573): .sp .in +2 .nf MAC_STAT_IFSPEED MAC_STAT_MULTIRCV MAC_STAT_BRDCSTRCV MAC_STAT_MULTIXMT MAC_STAT_BRDCSTXMT MAC_STAT_NORCVBUF MAC_STAT_IERRORS MAC_STAT_UNKNOWNS MAC_STAT_NOXMTBUF MAC_STAT_OERRORS MAC_STAT_COLLISIONS MAC_STAT_RBYTES MAC_STAT_IPACKETS MAC_STAT_OBYTES MAC_STAT_OPACKETS MAC_STAT_UNDERFLOWS MAC_STAT_OVERFLOWS MAC_STAT_IDROPS MAC_STAT_IDROPBYTES MAC_STAT_ODROPS MAC_STAT_ODROPBYTES .fi .in -2 .sp .LP The following statistics are specific to Ethernet device drivers: .sp .LP RFC 1643 stats: .sp .in +2 .nf ETHER_STAT_ALIGN_ERRORS ETHER_STAT_FCS_ERRORS ETHER_STAT_FIRST_COLLISIONS ETHER_STAT_MULTI_COLLISIONS ETHER_STAT_SQE_ERRORS ETHER_STAT_DEFER_XMTS ETHER_STAT_TX_LATE_COLLISIONS ETHER_STAT_EX_COLLISIONS ETHER_STAT_MACXMT_ERRORS ETHER_STAT_CARRIER_ERRORS ETHER_STAT_TOOLONG_ERRORS ETHER_STAT_MACRCV_ERRORS .fi .in -2 .sp .LP MII/GMII stats: .sp .in +2 .nf ETHER_STAT_XCVR_ADDR ETHER_STAT_XCVR_ID ETHER_STAT_XCVR_INUSE ETHER_STAT_CAP_1000FDX ETHER_STAT_CAP_1000HDX ETHER_STAT_CAP_100FDX ETHER_STAT_CAP_100HDX ETHER_STAT_CAP_10FDX ETHER_STAT_CAP_10HDX ETHER_STAT_CAP_ASMPAUSE ETHER_STAT_CAP_PAUSE ETHER_STAT_CAP_AUTONEG ETHER_STAT_ADV_CAP_1000FDX ETHER_STAT_ADV_CAP_1000HDX ETHER_STAT_ADV_CAP_100FDX ETHER_STAT_ADV_CAP_100HDX ETHER_STAT_ADV_CAP_10FDX ETHER_STAT_ADV_CAP_10HDX ETHER_STAT_ADV_CAP_ASMPAUSE ETHER_STAT_ADV_CAP_PAUSE ETHER_STAT_ADV_CAP_AUTONEG ETHER_STAT_LP_CAP_1000FDX ETHER_STAT_LP_CAP_1000HDX ETHER_STAT_LP_CAP_100FDX ETHER_STAT_LP_CAP_100HDX ETHER_STAT_LP_CAP_10FDX ETHER_STAT_LP_CAP_10HDX ETHER_STAT_LP_CAP_ASMPAUSE ETHER_STAT_LP_CAP_PAUSE ETHER_STAT_LP_CAP_AUTONEG ETHER_STAT_LINK_ASMPAUSE ETHER_STAT_LINK_PAUSE ETHER_STAT_LINK_AUTONEG ETHER_STAT_LINK_DUPLEX .fi .in -2 .SH PROPERTIES .sp .sp .TS tab(); cw(2.75i) cw(2.75i) lw(2.75i) lw(2.75i) . PropertyProperty Type \fBMAC_PROP_DUPLEX\fR\fBlink_duplex_t\fR \fBMAC_PROP_SPEED\fR\fBuint64_t\fR \fBMAC_PROP_STATUS\fR\fBlink_state_t\fR \fBMAC_PROP_AUTONEG\fR\fBuint8_t\fR \fBMAC_PROP_MTU\fR\fBuint32_t\fR \fBMAC_PROP_FLOWCTRL\fR\fBlink_flowctrl_t\fR \fBMAC_PROP_ADV_10GFDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_EN_10GFDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_ADV_1000FDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_EN_1000FDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_ADV_1000HDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_EN_1000HDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_ADV_100FDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_EN_100FDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_ADV_100HDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_EN_100HDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_ADV_10FDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_EN_10FDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_ADV_10HDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_EN_10HDX_CAP\fR\fBuint8_t\fR \fBMAC_PROP_PRIVATE\fR\fBchar[]\fR .TE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Availabilitysystem/header _ Interface StabilityCommitted .TE .SH SEE ALSO .sp .LP \fBlibdlpi\fR(3LIB), \fBattributes\fR(5), \fBmac_hcksum_get\fR(9F), \fBmac_prop_info_set_perm\fR(9F), \fBmac_register\fR(9F), \fBmac_tx_update\fR(9F), \fBmac_capab_lso\fR(9S), \fBmac_capab_rings\fR(9S), \fBmac_register\fR(9S)