diff options
Diffstat (limited to 'usr/src')
31 files changed, 5773 insertions, 5 deletions
diff --git a/usr/src/man/man9e/Makefile b/usr/src/man/man9e/Makefile index ad777c67dc..24551bf655 100644 --- a/usr/src/man/man9e/Makefile +++ b/usr/src/man/man9e/Makefile @@ -40,6 +40,19 @@ MANFILES= Intro.9e \ ioctl.9e \ ks_snapshot.9e \ ks_update.9e \ + mac.9e \ + mc_getcapab.9e \ + mc_getprop.9e \ + mc_getstat.9e \ + mc_ioctl.9e \ + mc_multicst.9e \ + mc_open.9e \ + mc_propinfo.9e \ + mc_setpromisc.9e \ + mc_setprop.9e \ + mc_start.9e \ + mc_tx.9e \ + mc_unicst.9e \ mmap.9e \ open.9e \ power.9e \ @@ -70,6 +83,8 @@ MANFILES= Intro.9e \ MANLINKS= _info.9e \ _init.9e \ + gldv3.9e \ + GLDv3.9e \ gldm_get_stats.9e \ gldm_intr.9e \ gldm_ioctl.9e \ @@ -80,6 +95,9 @@ MANLINKS= _info.9e \ gldm_set_promiscuous.9e \ gldm_start.9e \ gldm_stop.9e \ + MAC.9e \ + mc_close.9e \ + mc_stop.9e \ intro.9e \ tran_destroy_pkt.9e \ tran_pkt_constructor.9e \ @@ -93,6 +111,10 @@ intro.9e := LINKSRC = Intro.9e _info.9e := LINKSRC = _fini.9e _init.9e := LINKSRC = _fini.9e +MAC.9e := LINKSRC = mac.9e +gldv3.9e := LINKSRC = mac.9e +GLDv3.9e := LINKSRC = mac.9e + gldm_get_stats.9e := LINKSRC = gld.9e gldm_intr.9e := LINKSRC = gld.9e gldm_ioctl.9e := LINKSRC = gld.9e @@ -104,6 +126,9 @@ gldm_set_promiscuous.9e := LINKSRC = gld.9e gldm_start.9e := LINKSRC = gld.9e gldm_stop.9e := LINKSRC = gld.9e +mc_close.9e := LINKSRC = mc_open.9e +mc_stop.9e := LINKSRC = mc_start.9e + tran_setcap.9e := LINKSRC = tran_getcap.9e tran_destroy_pkt.9e := LINKSRC = tran_init_pkt.9e diff --git a/usr/src/man/man9e/mac.9e b/usr/src/man/man9e/mac.9e new file mode 100644 index 0000000000..18e12be957 --- /dev/null +++ b/usr/src/man/man9e/mac.9e @@ -0,0 +1,1825 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 11, 2016 +.Dt MAC 9E +.Os +.Sh NAME +.Nm mac , +.Nm GLDv3 +.Nd MAC networking device driver overview +.Sh SYNOPSIS +.In sys/mac_provider.h +.In sys/mac_ether.h +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh DESCRIPTION +The +.Sy MAC +framework provides a means for implementing high-performance networking +device drivers. It is the successor to the GLD interfaces and is +sometimes referred to as the GLDv3. The remainder of this manual +introduces the aspects of writing devices drivers that leverage the MAC +framework. While both the GLDv3 and MAC framework refer to the same thing, in +this manual page we use the term the +.Em MAC framework +to refer to the device driver interface. +.Pp +MAC device drivers are character devices. They define the standard +.Xr _init 9E , +.Xr _fini 9E , +and +.Xr _info 9E +entry points to initialize the module, as well as +.Xr dev_ops 9S +and +.Xr cb_ops 9S +structures. +.Pp +The main interface with MAC is through a series of callbacks defined in +a +.Xr mac_callbacks 9S +structure. These callbacks control all the aspects of the device. They +range from sending data, getting and setting of +properties, controlling mac address filters, and also managing +promiscuous mode. +.Pp +The MAC framework takes care of many aspects of the device driver's +management. A device that uses the MAC framework does not have to worry +about creating device nodes or implementing +.Xr open 9E +or +.Xr close 9E +routines. In addition, all of the work to interact with +.Xr dlpi 7P +is taken care of automatically and transparently. +.Ss Initializing MAC Support +For a device to be used in the framework, it must register with the +framework and take specific actions during +.Xr _init 9E , +.Xr attach 9E , +.Xr detach 9E , +and +.Xr _fini 9E . +.Pp +All device drivers have to define a +.Xr dev_ops 9S +structure which is pointed to by a +.Xr modldrv 9S +structure and the corresponding NULL-terminated +.Xr modlinkage 9S +structure. The +.Xr dev_ops 9S +structure should have a +.Xr cb_ops 9S +structure defined for it; however, it does not need to implement any of +the standard +.Xr cb_ops 9S +entry points. +.Pp +Normally, in a driver's +.Xr _init 9E +entry point, it passes its +.Sy modlinkage +structure directly to +.Xr mod_install 9F . +To properly register with MAC, the driver must call +.Xr mac_init_ops 9F +before it calls +.Xr mod_install 9F . +If for some reason the +.Xr mod_install 9F +function fails, then the driver must be removed by a call to +.Xr mac_fini_ops 9F . +.Pp +Conversely, in the driver's +.Xr _fini 9F +routine, it should call +.Xr mac_fini_ops 9F +after it successfully calls +.Xr mod_remove 9F . +For an example of how to use the +.Xr mac_init_ops 9F +and +.Xr mac_fini_ops 9F +functions, see the examples section in +.Xr mac_init_ops 9F . +.Ss Registering with MAC +Every instance of a device should register separately with MAC. +To register with MAC, a driver must allocate a +.Xr mac_register 9S +structure, fill it in, and then call +.Xr mac_register 9F . +The +.Sy mac_register_t +structure contains information about the device and all of the required +function pointers that will be used as callbacks by the framework. +.Pp +These steps should all be taken during a device's +.Xr attach 9E +entry point. It is recommended that the driver perform this sequence of +steps after the device has finished its initialization of the chipset +and interrupts, though interrupts should not be enabled at that point. +After it calls +.Xr mac_register 9F +it will start receiving callbacks from the MAC framework. +.Pp +To allocate the registration structure, the driver should call +.Xr mac_alloc 9F . +Device drivers should generally always pass the symbol +.Sy MAC_VERSION +as the argument to +.Xr mac_alloc 9F . +Upon successful completion, the driver will receive a +.Sy mac_register_t +structure which it should fill in. The structure and its members are +documented in +.Xr mac_register 9S . +.Pp +The +.Xr mac_callbacks 9S +structure is not allocated as a part of the +.Xr mac_register 9S +structure. In general, device drivers declare this statically. See the +.Sx MAC Callbacks +section for more information on how to fill it out. +.Pp +Once the structure has been filled in, the driver should call +.Xr mac_register 9F +to register itself with MAC. The handle that it uses to register with +should be part of the driver's soft state. It will be used in various +other support functions and callbacks. +.Pp +If the call is successful, then the device driver +should enable interrupts and finish any other initialization required. +If the call to +.Xr mac_register 9F +failed, then it should unwind its initialization and should return +.Sy DDI_FAILURE +from its +.Xr attach 9E +routine. +.Ss MAC Callbacks +The MAC framework interacts with a device driver through a series of +callbacks. These callbacks are described in their individual manual +pages and the collection of callbacks is indicated in the +.Xr mac_callbacks 9S +manual page. This section does not focus on the specific functions, but +rather on interactions between them and the rest of the device driver +framework. +.Pp +A device driver should make no assumptions about when the various +callbacks will be called and whether or not they will be called +simultaneously. For example, a device driver may be asked to +transmit data through a call to its +.Xr mc_tx 9F +entry point while it is being asked to get a device property through a +call to its +.Xr mc_getprop 9F +entry point. As such, while some calls may be serialized to the device, +such as setting properties, the device driver should always presume that +all of its data needs to be protected with locks. While the device is +holding locks, it is safe for it call the following MAC routines: +.Bl -bullet -offset indent -compact +.It +.Xr mac_hcksum_get 9F +.It +.Xr mac_hcksum_set 9F +.It +.Xr mac_lso_get 9F +.It +.Xr mac_maxsdu_update 9F +.It +.Xr mac_prop_info_set_default_link_flowctrl 9F +.It +.Xr mac_prop_info_set_default_str 9F +.It +.Xr mac_prop_info_set_default_uint8 9F +.It +.Xr mac_prop_info_set_default_uint32 9F +.It +.Xr mac_prop_info_set_default_uint64 9F +.It +.Xr mac_prop_info_set_perm 9F +.It +.Xr mac_prop_info_set_range_uint32 9F +.El +.Pp +Any other MAC related routines should not be called with locks held, +such as +.Xr mac_link_update 9F +or +.Xr mac_rx 9F . +Other routines in the DDI may be called while locks are held; however, +device driver writers should be careful about calling blocking routines +while locks are held or in interrupt context, though it is generally +legal to do so. +.Ss Receiving Data +A device driver will often receive data through the means of an +interrupt. When that interrupt occurs, the device driver will receive +one or more frames with optional metadata. Often each frame has a +corresponding descriptor which has information about whether or not +there were errors or whether or not the device successfully checksummed +the packet. +.Pp +During a single interrupt, a device driver should process a fixed number +of frames. For each frame the device driver should: +.Bl -enum -offset indent +.It +First check whether or not the frame has errors. If errors were +detected, then the frame should not be sent to the operating system. It +is recommended that devices keep kstats (see +.Xr kstat_create 9S +for more information) and bump the counter whenever such an error is +detected. If the device distinguishes between the types of errors, then +separate kstats for each class of error are recommended. See the +.Sx STATISTICS +section for more information on the various error cases that should be +considered. +.It +Once the frame has been determined to be valid, the device driver should +transform the frame into a +.Xr mblk 9S . +See the section +.Sx MBLKS AND DMA +for more information on how to transform and prepare a message block. +.It +If the device supports hardware checksumming (see the +.Sx CAPABILITIES +section for more information on checksumming), then the device driver +should set the corresponding checksumming information with a call to +.Xr mac_hcksum_set 9F . +.It +It should then append this new message block to the +.Em end +of the message block chain, linking it to the +.Sy b_next +pointer. It is vitally important that all the frames be chained in the +order that they were received. If the device driver mistakenly reorders +frames, then it may cause performance impacts in the TCP stack and +potentially impact application correctness. +.El +.Pp +Once all the frames have been processed and assembled, the device driver +should deliver them to the rest of the operating system by calling +.Xr mac_rx 9F . +The device driver should try to give as many mblk_t structures to the +system at once. It +.Em should not +call +.Xr mac_rx 9F +once for every assembled mblk_t. +.Pp +The device driver must not hold any locks across the call to +.Xr mac_rx 9F . +When this function is called, received data will be pushed through the +networking stack and some replies may be generated and given to the +driver to send out. +.Pp +It is not the device driver's responsibility to determine whether or not +the system can keep up with a driver's delivery rate of frames. The rest +of the networking stack will handle issues related to keeping up +appropriately and ensure that kernel memory is not exhausted by packets +that are not being processed. +.Pp +Finally, the device driver should make sure that any other housekeeping +activities required for the ring are taken care of such that more data +can be received. +.Ss Transmitting Data and Back Pressure +A device driver will be asked to transmit a message block chain by +having it's +.Xr mc_tx 9E +entry point called. While the driver is processing the message blocks, +it may run out of resources. For example, a transmit descriptor ring may +become full. At that point, the device driver should return the +remaining unprocessed frames. The act of returning frames indicates that +the device has asserted flow control. +Once this has been done, no additional calls will be made to the +driver's transmit entry point and the back pressure will be propagated +throughout the rest of the networking stack. +.Pp +At some point in the future when resources have become available again, +for example after an interrupt indicating that some portion of the +transmit ring has been sent, then the device driver must notify the +system that it can continue transmission. To do this, the +driver should call +.Xr mac_tx_update 9F . +After that point, the driver will receive calls to its +.Xr mc_tx 9E +entry point again. As mentioned in the section on callbacks, the device +driver should avoid holding any particular locks across the call to +.Xr mac_tx_update 9F . +.Ss Interrupt Coalescing +For devices operating at higher data rates, interrupt coalescing is an +important part of a well functioning device and may impact the +performance of the device. Not all devices support interrupt +coalescing. If interrupt coalescing is supported on the device, it is +recommended that device driver writers provide private properties for +their device to control the interrupt coalescing rate. This will make it +much easier to perform experiments and observe the impact of different +interrupt rates on the rest of the system. +.Ss MAC Address Filter Management +The MAC framework will attempt to use as many MAC address filters as a +device has. To program a multicast address filter, the driver's +.Xr mc_multicst 9E +entry point will be called. If the device driver runs out of filters, it +should not take any special action and just return the appropriate error +as documented in the corresponding manual pages for the entry points. +The framework will ensure that the device is placed in promiscuous mode +if it needs to. +.Ss Link Updates +It is the responsibility of the device driver to keep track of the +data link's state. Many devices provide a means of receiving an +interrupt when the state of the link changes. When such a change +happens, the driver should update its internal data structures and then +call +.Xr mac_link_update 9F +to inform the MAC layer that this has occurred. If the device driver +does not properly inform the system about link changes, then various +features like link aggregations and other mechanisms that leverage the +link state will not work correctly. +.Ss Link Speed and Auto-negotiation +Many networking devices support more than one possible speed that they +can operate at. The selection of a speed is often performed through +.Em auto-negotiation , +though some devices allow the user to control what speeds are advertised +and used. +.Pp +Logically, there are two different sets of things that the device driver +needs to keep track of while it's operating: +.Bl -enum +.It +The supported speeds in hardware. +.It +The enabled speeds from the user. +.El +.Pp +By default, when a link first comes up, the device driver should +generally configure the link to support the common set of speeds and +perform auto-negotiation. +.Pp +A user can control what speeds a device advertises via auto-negotiation +and whether or not it performs auto-negotiation at all by using a series +of properties that have +.Sy _EN_ +in the name. These are read/write properties and there is one for each +speed supported in the operating system. For a full list of them, see +the +.Sx PROPERTIES +section. +.Pp +In addition to these properties, there is a corresponding set of +properties with +.Sy _ADV_ +in the name. These are similar to the +.Sy _EN_ +family of properties, but they are read-only and indicate what the +device has actually negotiated. While they are generally similar to the +.Sy _EN_ +family of properties, they may change depending on power settings. See +the +.Sy Ethernet Link Properties +section in +.Xr dladm 1M +for more information. +.Pp +It's worth discussing how these different values get used throughout the +different entry points. The first entry point to consider is the +.Xr mc_propinfo 9E +entry point. For a given speed, the driver should consult whether or not +the hardware supports this speed. If it does, it should fill in the +default value that the hardware takes and whether or not the property is +writable. The properties should also be updated to indicate whether or +not it is writable. This holds for both the +.Sy _EN_ +and +.Sy _ADV_ +family of properties. +.Pp +The next entry point is +.Xr mc_getprop 9E . +Here, the device should first consult whether the given speed is +supported. If it is not, then the driver should return +.Er ENOTSUP . +If it does, then it should return the current value of the property. +.Pp +The last property endpoint is the +.Xr mc_setprop 9E +entry point. Here, the same logic applies. Before the driver considers +whether or not the property is writable, it should first check whether +or not it's a supported property. If it's not, then it should return +.Er ENOTSUP . +Otherwise, it should proceed to check whether the property is writable, +and if it is and a valid value, then it should update the property and +restart the link's negotiation. +.Pp +Finally, there is the +.Xr mc_getstat 9E +entry point. Several of the statistics that are queried relate to +auto-negotiation and hardware capabilities. When a statistic relates to +the hardware supporting a given speed, the +.Sy _EN_ +properties should be ignored. The only thing that should be consulted is +what the hardware itself supports. Otherwise, the statistics should look +at what is currently being advertised by the device. +.Ss Unregistering from MAC +During a driver's +.Xr detach 9E +routine, it should unregister the device instance from MAC by calling +.Xr mac_unregister 9F +on the handle that it originally called it on. If the call to +.Xr mac_unregister 9F +failed, then the device is likely still in use and the driver should +fail the call to +.Xr detach 9E . +.Ss Interacting with Devices +Administrators always interact with devices through the +.Xr dladm 1M +command line interface. The state of devices such as whether the link is +considered +.Sy up +or +.Sy down , +various link properties such as the +.Sy MTU , +.Sy auto-negotiation +state, +and +.Sy flow control +state, +are all exposed. It is also the preferred way that these properties are +set and configured. +.Pp +While device tunables may be presented in a +.Xr driver.conf 4 +file, it is recommended instead to expose such things through +.Xr dladm 1M +private properties, whether explicitly documented or not. +.Sh CAPABILITIES +Capabilities in the MAC Framework are optional features that a device +supports which indicate various hardware features that the device +supports. The two current capabilities that the system supports are +related to being able to hardware perform large send offloads (LSO), +often also known as TCP segmentation and the ability for hardware to +calculate and verify the checksums present in IPv4, IPV6, and protocol +headers such as TCP and UDP. +.Pp +The MAC framework will query a device for support of a capability +through the +.Xr mc_getcapab 9E +function. Each capability has its own constant and may have +corresponding data that goes along with it and a specific structure that +the device is required to fill in. Note, the set of capabilities changes +over time and there are also private capabilities in the system. Several +of the capabilities are used in the implementation of the MAC framework. +Others, like +.Sy MAC_CAPAB_RIGNS , +represent feature that have not been stabilized and thus both API and +binary compatibility for them is not guaranteed. It is important that +the device driver handles unknown capabilities correctly. For more +information, see +.Xr mc_getcapab 9E . +.Pp +The following capabilities are +stable and defined in the system: +.Ss MAC_CAPAB_HCKSUM +The +.Sy MAC_CAPAB_HCKSUM +capability indicates to the system that the device driver supports some +amount of checksumming. The specific data for this capability is a +pointer to a +.Sy uint32_t . +To indicate no support for any kind of checksumming, the driver should +either set this value to zero or simply return that it doesn't support +the capability. +.Pp +Note, the values that the driver declares in this capability indicate +what it can do when it transmits data. If the driver can only +verify checksums when receiving data, then it should not indicate that +it supports this capability. The following set of flags may be combined +through a bitwise inclusive OR: +.Bl -tag -width Ds +.It Sy HCKSUM_INET_PARTIAL +This indicates that the hardware can calculate a partial checksum for +both IPv4 and IPv6; however, it requires the pseudo-header checksum be +calculated for it. The pseudo-header checksum will be available for the +mblk_t when calling +.Xr mac_hcksum_get 9F . +Note this does not imply that the hardware is capable of calculating the +IPv4 header checksum. That should be indicated with the +.Sy HCKSUM_IPHDRCKSUM flag. +.It Sy HCKSUM_INET_FULL_V4 +This indicates that the hardware will fully calculate the L4 checksum +for outgoing IPv4 packets and does not require a pseudo-header checksum. +Note this does not imply that the hardware is capable of calculating the +IPv4 header checksum. That should be indicated with the +.Sy HCKSUM_IPHDRCKSUM . +.It Sy HCKSUM_INET_FULL_V6 +This indicates that the hardware will fully calculate the L4 checksum +for outgoing IPv6 packets and does not require a pseudo-header checksum. +.It Sy HCKSUM_IPHDRCKSUM +This indicates that the hardware supports calculating the checksum for +the IPv4 header itself. +.El +.Pp +When in a driver's transmit function, the driver will be processing a +single frame. It should call +.Xr mac_hcksum_get 9F +to see what checksum flags are set on it. Note that the flags that are +set on it are different from the ones described above and are documented +in its manual page. These flags indicate how the driver is expected to +program the hardware and what checksumming is required. Not all frames +will require hardware checksumming or will ask the hardware to checksum +it. +.Pp +If a driver supports offloading the receive checksum and verification, +it should check to see what the hardware indicated was verified. The +driver should then call +.Xr mac_hcksum_set 9F . +The flags used are different from the ones above and are discussed in +detail in the +.Xr mac_hcksum_set 9F +manual page. If there is no checksum information available or the driver +does not support checksumming, then it should simply not call +.Xr mac_hcksum_set 9F . +.Pp +Note that the checksum flags should be set on the first +mblk_t that makes up a given message. In other words, if multiple +mblk_t structures are linked together by the +.Sy b_cont +member to describe a single frame, then it should only be called on the +first mblk_t of that set. However, each distinct message should have the +checksum bits set on it, if applicable. In other words, each mblk_t that +is linked together by the +.Sy b_next +pointer may have checksum flags set. +.Pp +It is recommended that device drivers provide a private property or +.Xr driver.conf 4 +property to control whether or not checksumming is enabled for both rx +and tx; however, the default disposition is recommended to be enabled +for both. This way if hardware bugs are found in the checksumming +implementation, they can be disabled without requiring software updates. +The transmit property should be checked when determining how to reply to +.Xr mc_getcapab 9E +and the receive property should be checked in the context of the receive +function. +.Ss MAC_CAPAB_LSO +The +.Sy MAC_CAPAB_LSO +capability indicates that the driver supports various forms of large +send offload (LSO). The private data is a pointer to a +.Sy mac_capab_lso_t +structure. At the moment, LSO support is limited to TCP inside of IPv4. +This structure has the following members which are used to indicate +various types of LSO support. +.Bd -literal -offset indent +t_uscalar_t lso_flags; +lso_basic_tcp_ivr4_t lso_basic_tcp_ipv4; +.Ed +.Pp +The +.Sy lso_flags +member is used to indicate which members are valid and should be +considered. Each flag represents a different form of LSO. The member +should be set to the bitwise inclusive OR of the following values: +.Bl -tag -width Dv -offset indent +.It Sy LSO_TX_BASIC_TCP_IPV4 +This indicates hardware support for performing TCP segmentation +offloading over IPv4. When this flag is set, the +.Sy lso_basic_tcp_ipv4 +member must be filled in. +.El +.Pp +The +.Sy lso_basic_tcp_ipv4 +member is a structure with the following members: +.Bd -literal -offset indent +t_uscalar_t lso_max +.Ed +.Bd -filled -offset indent +The +.Sy lso_max +member should be set to the maximum size of the TCP data +payload that can be offloaded to the hardware. +.Ed +.Pp +Like with checksumming, it is recommended that driver writers provide a +means for disabling the support of LSO even if it is enabled by default. +This deals with the case where issues that pop up for LSO may be worked +around without requiring additional driver work. +.Sh PROPERTIES +Properties in the MAC framework represent aspects of a link. These +include things like the link's current state and MTU. Many of the +properties in the system are focused around auto-negotiation and +controlling what link speeds are advertised. Information about +properties is covered by three different device entry points. The +.Xr mc_propinfo 9E +entry point obtains metadata about the property. The +.Xr mc_getprop 9E +entry point obtains the property. The +.Xr mc_setprop 9E +entry point updates the property to a new value. +.Pp +Many of the properties listed below are read-only. Each property +indicates whether it's read-only or it's read/write. However, driver +writers may not implement the ability to set all writeable properties. +Many of these depend on the card itself. In particular, all properties +that relate to auto-negotiation and are read/write may not be updated +if the hardware in question does not support toggling what link speeds +are auto-negotiated. While copper Ethernet often does not have this +restriction, it often exists with various fiber standards and phys. +.Pp +The following properties are the subset of MAC framework properties that +driver writers should be aware of and handle. While other properties +exist in the system, driver writers should always return an error when a +property not listed below is encountered. See +.Xr mc_getprop 9E +and +.Xr mc_setprop 9E +for more information on how to handle them. +.Bl -hang -width Ds +.It Sy MAC_PROP_DUPLEX +.Bd -filled -compact +Type: +.Sy link_duplex_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_DUPLEX +property is used to indicate whether or not the link is duplex. A duplex +link may have traffic flowing in both directions at the same time. The +.Sy link_duplex_t +is an enumeration which may be set to any of the following values: +.Bl -tag -width Ds +.It Sy LINK_DUPLEX_UNKNOWN +The current state of the link is unknown. This may be because the link +has not negotiated to a specific speed or it is down. +.It Sy LINK_DUPLEX_HALF +The link is running at half duplex. Communication may travel in only one +direction on the link at a given time. +.It Sy LINK_DUPLEX_FULL +The link is running at full duplex. Communication may travel in both +directions on the link simultaneously. +.El +.It Sy MAC_PROP_SPEED +.Bd -filled -compact +Type: +.Sy uint64_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_SPEED +property stores the current link speed in bits per second. A link +that is running at 100 MBit/s would store the value 100000000ULL. A link +that is running at 40 Gbit/s would store the value 40000000000ULL. +.It Sy MAC_PROP_STATUS +.Bd -filled -compact +Type: +.Sy link_state_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_STATUS +property is used to indicate the current state of the link. It indicates +whether the link is up or down. The +.Sy link_state_t +is an enumeration which may be set to any of the following values: +.Bl -tag -width Ds +.It Sy LINK_STATE_UNKNOWN +The current state of the link is unknown. This may be because the +driver's +.Xr mc_start 9E +endpoint has not been called so it has not attempted to start the link. +.It Sy LINK_STATE_DOWN +The link is down. This may be because of a negotiation problem, a cable +problem, or some other device specific issue. +.It Sy LINK_STATE_UP +The link is up. If auto-negotiation is in use, it should have completed. +Traffic should be able to flow over the link, barring other issues. +.El +.It Sy MAC_PROP_AUTONEG +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_AUTONEG +property indicates whether or not the device is currently configured to +perform auto-negotiation. A value of +.Sy 0 +indicates that auto-negotiation is disabled. A +.Sy non-zero +value indicates that auto-negotiation is enabled. Devices should +generally default to enabling auto-negotiation. +.Pp +When getting this property, the device driver should return the current +state. When setting this property, if the device supports operating in +the requested mode, then the device driver should reset the link to +negotiate to the new speed after updating any internal registers. +.It Sy MAC_PROP_MTU +.Bd -filled -compact +Type: +.Sy uint32_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_MTU +property determines the maximum transmission unit (MTU). This indicates +the maximum size packet that the device can transmit, ignoring its own +headers. For an Ethernet device, this would exclude the size of the +Ethernet header and any VLAN headers that would be placed. It is up to +the driver to ensure that any MTU values that it accepts when adding in +its margin and header sizes does not exceed its maximum frame size. +.Pp +By default, drivers for Ethernet should initialize this value and the +MTU to +.Sy 1500 . +When getting this property, the driver should return its current +recorded MTU. When setting this property, the driver should first +validate that it is within the device's valid range and then it must +call +.Xr mac_maxsdu_update 9F . +Note that the call may fail. If the call completes successfully, the +driver should update the hardware with the new value of the MTU and +perform any other work needed to handle it. +.Pp +If the device does not support changing the MTU after the device's +.Xr mc_start 9E +entry point has been called, then driver writers should return +.Er EBUSY . +.It Sy MAC_PROP_FLOWCTRL +.Bd -filled -compact +Type: +.Sy link_flowctrl_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_FLOWCTRL +property manages the configuration of pause frames as part of Ethernet +flow control. Note, this only describes what this device will advertise. +What is actually enabled may be different and is subject to the rules of +auto-negotiation. The +.Sy link_flowctrl_t +is an enumeration that may be set to one of the following values: +.Bl -tag -width Ds +.It Sy LINK_FLOWCTRL_NONE +Flow control is disabled. No pause frames should be generated or +honored. +.It Sy LINK_FLOWCTRL_RX +The device can receive pause frames; however, it should not generate +them. +.It Sy LINK_FLOWCTRL_TX +The device can generate pause frames; however, it does not support +receiving them. +.It Sy LINK_FLOWCTRL_BI +The device supports both sending and receiving pause frames. +.El +.Pp +When getting this property, the device driver should return the way that +it has configured the device, not what the device has actually +negotiated. When setting the property, it should update the hardware and +allow the link to potentially perform auto-negotiation again. +.El +.Pp +The remaining properties are all about various auto-negotiation link +speeds. They fall into two different buckets: properties with +.Sy _ADV_ +in the name and properties with +.Sy _EN_ +in the name. For any given supported speed, there is one of each. The +.Sy _EN_ +set of properties are read/write properties that control what should be +advertised by the device. When these are retrieved, they should return +the current value of the property. When they are set, they should change +how the hardware advertises the specific speed and trigger any kind of +link reset and auto-negotiation, if enabled, to occur. +.Pp +The +.Sy _ADV_ +set of properties are read-only properties. They are meant to reflect +what has actually been negotiated. These may be different from the +.Sy _EN_ +family of properties, especially when different power management +settings are at play. +.Pp +See the +.Sx Link Speed and Auto-negotiation +section for more information. +.Pp +The properties are ordered in increasing link speed: +.Bl -hang -width Ds +.It Sy MAC_PROP_ADV_10HDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_10HDX_CAP +property describes whether or not 10 Mbit/s half-duplex support is +advertised. +.It Sy MAC_PROP_EN_10HDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_10HDX_CAP +property describes whether or not 10 Mbit/s half-duplex support is +enabled. +.It Sy MAC_PROP_ADV_10FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_10FDX_CAP +property describes whether or not 10 Mbit/s full-duplex support is +advertised. +.It Sy MAC_PROP_EN_10FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_10FDX_CAP +property describes whether or not 10 Mbit/s full-duplex support is +enabled. +.It Sy MAC_PROP_ADV_100HDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_100HDX_CAP +property describes whether or not 100 Mbit/s half-duplex support is +advertised. +.It Sy MAC_PROP_EN_100HDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_100HDX_CAP +property describes whether or not 100 Mbit/s half-duplex support is +enabled. +.It Sy MAC_PROP_ADV_100FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_100FDX_CAP +property describes whether or not 100 Mbit/s full-duplex support is +advertised. +.It Sy MAC_PROP_EN_100FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_100FDX_CAP +property describes whether or not 100 Mbit/s full-duplex support is +enabled. +.It Sy MAC_PROP_ADV_100T4_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_100T4_CAP +property describes whether or not 100 Mbit/s Ethernet using the +100BASE-T4 standard is +advertised. +.It Sy MAC_PROP_EN_100T4_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_ADV_100T4_CAP +property describes whether or not 100 Mbit/s Ethernet using the +100BASE-T4 standard is +enabled. +.It Sy MAC_PROP_ADV_1000HDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_1000HDX_CAP +property describes whether or not 1 Gbit/s half-duplex support is +advertised. +.It Sy MAC_PROP_EN_1000HDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_1000HDX_CAP +property describes whether or not 1 Gbit/s half-duplex support is +enabled. +.It Sy MAC_PROP_ADV_1000FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_1000FDX_CAP +property describes whether or not 1 Gbit/s full-duplex support is +advertised. +.It Sy MAC_PROP_EN_1000FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_1000FDX_CAP +property describes whether or not 1 Gbit/s full-duplex support is +enabled. +.It Sy MAC_PROP_ADV_2500FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_2500FDX_CAP +property describes whether or not 2.5 Gbit/s full-duplex support is +advertised. +.It Sy MAC_PROP_EN_2500FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_2500FDX_CAP +property describes whether or not 2.5 Gbit/s full-duplex support is +enabled. +.It Sy MAC_PROP_ADV_5000FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_5000FDX_CAP +property describes whether or not 5.0 Gbit/s full-duplex support is +advertised. +.It Sy MAC_PROP_EN_5000FDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_5000FDX_CAP +property describes whether or not 5.0 Gbit/s full-duplex support is +enabled. +.It Sy MAC_PROP_ADV_10GFDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_10GFDX_CAP +property describes whether or not 10 Gbit/s full-duplex support is +advertised. +.It Sy MAC_PROP_EN_10GFDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_10GFDX_CAP +property describes whether or not 10 Gbit/s full-duplex support is +enabled. +.It Sy MAC_PROP_ADV_40GFDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_40GFDX_CAP +property describes whether or not 40 Gbit/s full-duplex support is +advertised. +.It Sy MAC_PROP_EN_40GFDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_40GFDX_CAP +property describes whether or not 40 Gbit/s full-duplex support is +enabled. +.It Sy MAC_PROP_ADV_100GFDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read-Only +.Ed +.Pp +The +.Sy MAC_PROP_ADV_100GFDX_CAP +property describes whether or not 100 Gbit/s full-duplex support is +advertised. +.It Sy MAC_PROP_EN_100GFDX_CAP +.Bd -filled -compact +Type: +.Sy uint8_t | +Permissions: +.Sy Read/Write +.Ed +.Pp +The +.Sy MAC_PROP_EN_100GFDX_CAP +property describes whether or not 100 Gbit/s full-duplex support is +enabled. +.El +.Ss Private Properties +In addition to the defined properties above, drivers are allowed to +define private properties. These private properties are device-specific +properties. All private properties share the same constant, +.Sy MAC_PROP_PRIVATE . +Properties are distinguished by a name, which is a character string. The +list of such private properties is defined when registering with mac in +the +.Sy m_priv_props +member of the +.Xr mac_register 9S +structure. +.Pp +The driver may define whatever semantics it wants for these private +properties. They will not be listed when running +.Xr dladm 1M , +unless explicitly requested by name. All such properties should start +with a leading underscore character and then consist of alphanumeric +ASCII characters and additional underscores or hyphens. +.Pp +Properties of type +.Sy MAC_PROP_PRIVATE +may show up in all three property related entry points: +.Xr mc_propinfo 9E , +.Xr mc_getprop 9E , +and +.Xr mc_setprop 9E . +Device drivers should tell the different properties apart by using the +.Xr strcmp 9F +function to compare it to the set of properties that it knows about. +When encountering properties that it doesn't know, it should treat them +like all other unknown properties. +.Sh STATISTICS +The MAC framework defines a couple different sets of statistics which +are based on various standards for devices to implement. Statistics are +retrieved through the +.Xr mc_getstat 9E +entry point. There are both statistics that are required for all devices +and then there is a separate set of Ethernet specific statistics. Not +all devices will support every statistic. In many cases, several device +registers will need to be combined to create the proper stat. +.Pp +In general, if the device is not keeping track of these statistics, then +it is recommended that the driver store these values as a +.Sy uint64_t +to ensure that overflow does not occur. +.Pp +If a device does not support a specific statistic, then it is fine to +return that it is not supported. The same should be used for +unrecognized statistics. See +.Xr mc_getstat 9E +for more information on the proper way to handle these. +.Ss General Device Statistics +The following statistics are based on MIB-II statistics from both RFC +1213 and RFC 1573. +.Bl -tag -width Ds +.It Sy MAC_STAT_IFSPEED +The device's current speed in bits per second. +.It Sy MAC_STAT_MULTIRCV +The total number of received multicast packets. +.It Sy MAC_STAT_BRDCSTRCV +The total number of received broadcast packets. +.It Sy MAC_STAT_MULTIXMT +The total number of transmitted multicast packets. +.It Sy MAC_STAT_BRDCSTXMT +The total number of received broadcast packets. +.It Sy MAC_STAT_NORCVBUF +The total number of packets discarded by the hardware due to a lack of +receive buffers. +.It Sy MAC_STAT_IERRORS +The total number of errors detected on input. +.It Sy MAC_STAT_UNKNOWNS +The total number of received packets that were discarded because they +were of an unknown protocol. +.It Sy MAC_STAT_NOXMTBUF +The total number of outgoing packets dropped due to a lack of transmit +buffers. +.It Sy MAC_STAT_OERRORS +The total number of outgoing packets that resulted in errors. +.It Sy MAC_STAT_COLLISIONS +Total number of collisions encountered by the transmitter. +.It Sy MAC_STAT_RBYTES +The total number of +.Sy bytes +received by the device, regardless of packet type. +.It Sy MAC_STAT_IPACKETS +The total number of +.Sy packets +received by the device, regardless of packet type. +.It Sy MAC_STAT_OBYTES +The total number of +.Sy bytes +transmitted by the device, regardless of packet type. +.It Sy MAC_STAT_OPACKETS +The total number of +.Sy packets +sent by the device, regardless of packet type. +.It Sy MAC_STAT_UNDERFLOWS +The total number of packets that were smaller than the minimum sized +packet for the device and were therefore dropped. +.It Sy MAC_STAT_OVERFLOWS +The total number of packets that were larger than the maximum sized +packet for the device and were therefore dropped. +.El +.Ss Ethernet Specific Statistics +The following statistics are specific to Ethernet devices. They refer to +values from RFC 1643 and include various MII/GMII specific stats. Many +of these are also defined in IEEE 802.3. +.Bl -tag -width Ds +.It Sy ETHER_STAT_ADV_CAP_1000FDX +Indicates that the device is advertising support for 1 Gbit/s +full-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_1000HDX +Indicates that the device is advertising support for 1 Gbit/s +half-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_100FDX +Indicates that the device is advertising support for 100 Mbit/s +full-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_100GFDX +Indicates that the device is advertising support for 100 Gbit/s +full-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_100HDX +Indicates that the device is advertising support for 100 Mbit/s +half-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_100T4 +Indicates that the device is advertising support for 100 Mbit/s +100BASE-T4 operation. +.It Sy ETHER_STAT_ADV_CAP_10FDX +Indicates that the device is advertising support for 10 Mbit/s +full-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_10GFDX +Indicates that the device is advertising support for 10 Gbit/s +full-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_10HDX +Indicates that the device is advertising support for 10 Mbit/s +half-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_2500FDX +Indicates that the device is advertising support for 2.5 Gbit/s +full-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_40GFDX +Indicates that the device is advertising support for 40 Gbit/s +full-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_5000FDX +Indicates that the device is advertising support for 5.0 Gbit/s +full-duplex operation. +.It Sy ETHER_STAT_ADV_CAP_ASMPAUSE +Indicates that the device is advertising support for receiving pause +frames. +.It Sy ETHER_STAT_ADV_CAP_AUTONEG +Indicates that the device is advertising support for auto-negotiation. +.It Sy ETHER_STAT_ADV_CAP_PAUSE +Indicates that the device is advertising support for generating pause +frames. +.It Sy ETHER_STAT_ADV_REMFAULT +Indicates that the device is advertising support for detecting faults in +the remote link peer. +.It Sy ETHER_STAT_ALIGN_ERRORS +Indicates the number of times an alignment error was generated by the +Ethernet device. This is a count of packets that were not an integral +number of octets and failed the FCS check. +.It Sy ETHER_STAT_CAP_1000FDX +Indicates the device supports 1 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_CAP_1000HDX +Indicates the device supports 1 Gbit/s half-duplex operation. +.It Sy ETHER_STAT_CAP_100FDX +Indicates the device supports 100 Mbit/s full-duplex operation. +.It Sy ETHER_STAT_CAP_100GFDX +Indicates the device supports 100 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_CAP_100HDX +Indicates the device supports 100 Mbit/s half-duplex operation. +.It Sy ETHER_STAT_CAP_100T4 +Indicates the device supports 100 Mbit/s 100BASE-T4 operation. +.It Sy ETHER_STAT_CAP_10FDX +Indicates the device supports 10 Mbit/s full-duplex operation. +.It Sy ETHER_STAT_CAP_10GFDX +Indicates the device supports 10 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_CAP_10HDX +Indicates the device supports 10 Mbit/s half-duplex operation. +.It Sy ETHER_STAT_CAP_2500FDX +Indicates the device supports 2.5 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_CAP_40GFDX +Indicates the device supports 40 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_CAP_5000FDX +Indicates the device supports 5.0 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_CAP_ASMPAUSE +Indicates that the device supports the ability to receive pause frames. +.It Sy ETHER_STAT_CAP_AUTONEG +Indicates that the device supports the ability to perform link +auto-negotiation. +.It Sy ETHER_STAT_CAP_PAUSE +Indicates that the device supports the ability to transmit pause frames. +.It Sy ETHER_STAT_CAP_REMFAULT +Indicates that the device supports the ability of detecting a remote +fault in a link peer. +.It Sy ETHER_STAT_CARRIER_ERRORS +Indicates the number of times that the Ethernet carrier sense condition +was lost or not asserted. +.It Sy ETHER_STAT_DEFER_XMTS +Indicates the number of frames for which the device was unable to +transmit the frame due to being busy and had to try again. +.It Sy ETHER_STAT_EX_COLLISIONS +Indicates the number of frames that failed to send due to an excessive +number of collisions. +.It Sy ETHER_STAT_FCS_ERRORS +Indicates the number of times that a frame check sequence failed. +.It Sy ETHER_STAT_FIRST_COLLISIONS +Indicates the number of times that a frame was eventually transmitted +successfully, but only after a single collision. +.It Sy ETHER_STAT_JABBER_ERRORS +Indicates the number of frames that were received that were both larger +than the maximum packet size and failed the frame check sequence. +.It Sy ETHER_STAT_LINK_ASMPAUSE +Indicates whether the link is currently configured to accept pause +frames. +.It Sy ETHER_STAT_LINK_AUTONEG +Indicates whether the current link state is a result of +auto-negotiation. +.It Sy ETHER_STAT_LINK_DUPLEX +Indicates the current duplex state of the link. The values used here +should be the same as documented for +.Sy MAC_PROP_DUPLEX . +.It Sy ETHER_STAT_LINK_PAUSE +Indicates whether the link is currently configured to generate pause +frames. +.It Sy ETHER_STAT_LP_CAP_1000FDX +Indicates the remote device supports 1 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_LP_CAP_1000HDX +Indicates the remote device supports 1 Gbit/s half-duplex operation. +.It Sy ETHER_STAT_LP_CAP_100FDX +Indicates the remote device supports 100 Mbit/s full-duplex operation. +.It Sy ETHER_STAT_LP_CAP_100GFDX +Indicates the remote device supports 100 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_LP_CAP_100HDX +Indicates the remote device supports 100 Mbit/s half-duplex operation. +.It Sy ETHER_STAT_LP_CAP_100T4 +Indicates the remote device supports 100 Mbit/s 100BASE-T4 operation. +.It Sy ETHER_STAT_LP_CAP_10FDX +Indicates the remote device supports 10 Mbit/s full-duplex operation. +.It Sy ETHER_STAT_LP_CAP_10GFDX +Indicates the remote device supports 10 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_LP_CAP_10HDX +Indicates the remote device supports 10 Mbit/s half-duplex operation. +.It Sy ETHER_STAT_LP_CAP_2500FDX +Indicates the remote device supports 2.5 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_LP_CAP_40GFDX +Indicates the remote device supports 40 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_LP_CAP_5000FDX +Indicates the remote device supports 5.0 Gbit/s full-duplex operation. +.It Sy ETHER_STAT_LP_CAP_ASMPAUSE +Indicates that the remote device supports the ability to receive pause +frames. +.It Sy ETHER_STAT_LP_CAP_AUTONEG +Indicates that the remote device supports the ability to perform link +auto-negotiation. +.It Sy ETHER_STAT_LP_CAP_PAUSE +Indicates that the remote device supports the ability to transmit pause +frames. +.It Sy ETHER_STAT_LP_CAP_REMFAULT +Indicates that the remote device supports the ability of detecting a +remote fault in a link peer. +.It Sy ETHER_STAT_MACRCV_ERRORS +Indicates the number of times that the internal MAC layer encountered an +error when attempting to receive and process a frame. +.It Sy ETHER_STAT_MACXMT_ERRORS +Indicates the number of times that the internal MAC layer encountered an +error when attempting to process and transmit a frame. +.It Sy ETHER_STAT_MULTI_COLLISIONS +Indicates the number of times that a frame was eventually transmitted +successfully, but only after more than one collision. +.It Sy ETHER_STAT_SQE_ERRORS +Indicates the number of times that an SQE error occurred. The specific +conditions for this error are documented in IEEE 802.3. +.It Sy ETHER_STAT_TOOLONG_ERRORS +Indicates the number of frames that were received that were longer than +the maximum frame size supported by the device. +.It Sy ETHER_STAT_TOOSHORT_ERRORS +Indicates the number of frames that were received that were shorter than +the minimum frame size supported by the device. +.It Sy ETHER_STAT_TX_LATE_COLLISIONS +Indicates the number of times a collision was detected late on the +device. +.It Sy ETHER_STAT_XCVR_ADDR +Indicates the address of the MII/GMII receiver address. +.It Sy ETHER_STAT_XCVR_ID +Indicates the id of the MII/GMII receiver address. +.It Sy ETHER_STAT_XCVR_INUSE +Indicates what kind of receiver is in use. The following values may be +used: +.Bl -tag -width Ds +.It Sy XCVR_UNDEFINED +The receiver type is undefined by the hardware. +.It Sy XCVR_NONE +There is no receiver in use by the hardware. +.It Sy XCVR_10 +The receiver supports 10BASE-T operation. +.It Sy XCVR_100T4 +The receiver supports 100BASE-T4 operation. +.It Sy XCVR_100X +The receiver supports 100BASE-TX operation. +.It Sy XCVR_100T2 +The receiver supports 100BASE-T2 operation. +.It Sy XCVR_1000X +The receiver supports 1000BASE-X operation. This is used for all fiber +receivers. +.It Sy XCVR_1000T +The receiver supports 1000BASE-T operation. This is used for all copper +receivers. +.El +.El +.Ss Device Specific kstats +In addition to the defined statistics above, if the device driver +maintains additional statistics or the device provides additional +statistics, it should create its own kstats through the +.Xr kstat_create 9F +function to allow operators to observe them. +.Sh TX STALL DETECTION, DEVICE RESETS, AND FAULT MANAGEMENT +Device drivers are the first line of defense for dealing with broken +devices and bugs in their firmware. While most devices will rarely fail, +it is important that when designing and implementing the device driver +that particular attention is paid in the design with respect to RAS +(Reliability, Availability, and Serviceability). While everything +described in this section is optional, it is highly recommended that +all new device drivers follow these guidelines. +.Pp +The Fault Management Architecture (FMA) provides facilities for +detecting and reporting various classes of defects and faults. +Specifically for networking device drivers, issues that should be +detected and reported include: +.Bl -bullet -offset indent +.It +Device internal uncorrectable errors +.It +Device internal correctable errors +.It +PCI and PCI Express transport errors +.It +Device temperature alarms +.It +Device transmission stalls +.It +Device communication timeouts +.It +High invalid interrupts +.El +.Pp +All such errors fall into three primary categories: +.Bl -enum -offset indent +.It +Errors detected by the Fault Management Architecture +.It +Errors detected by the device and indicated to the device driver +.It +Errors detected by the device driver +.El +.Ss Fault Management Setup and Teardown +Drivers should initialize support for the fault management framework by +calling +.Xr ddi_fm_init 9F +from their +.Xr attach 9E +routine. By registering with the fault management framework, a device +driver is given the chance to detect and notice transport errors as well +as report other errors that exist. While a device driver does not need to +indicate that it is capable of all such capabilities described in +.Xr ddi_fm_init 9F , +we suggest that device drivers at least register the +.Sy DDI_FM_EREPORT_CAPABILITY +so as to allow the driver to report issues that it detects. +.Pp +If the driver registers with the fault management framework during its +.Xr attach 9E +entry point, it must call +.Xr ddi_fm_fini 9E +during its +.Xr detach 9E +entry point. +.Ss Transport Errors +Many modern networking devices leverage PCI or PCI Express. As such, +there are two primary ways that device drivers access data: they either +memory map device registers and use routines like +.Xr ddi_get8 9F +and +.Xr ddi_put8 9F +or they use direct memory access (DMA). New device drivers should always +enable checking of the transport layer by marking their support in the +.Xr ddi_device_acc_attr_t 9S +structure and using routines like +.Xr ddi_fm_acc_err_get 9F +and +.Xr ddi_fm_dma_err_get 9F +to detect if errors have occurred. +.Ss Device Indicated Errors +Many devices have capabilities to announce to a device driver that a +fatal correctable error or uncorrectable error has occurred. Other +devices have the ability to indicate that various physical issues have +occurred such as a fan failing or a temperature sensor having fired. +.Pp +Drivers should wire themselves to receive notifications when these +events occur. The means and capabilities will vary from device to +device. For example, some devices will generate information about these +notifications through special interrupts. Other devices may have a +register that software can poll. In the cases where polling is required, +driver writers should try not to poll too frequently and should +generally only poll when the device is actively being used, e.g. between +calls to the +.Xr mc_start 9E +and +.Xr mc_stop 9E +entry points. +.Ss Driver Transmit Stall Detection +One of the primary responsibilities of a hardened device driver is to +perform transmit stall detection. The core idea behind tx stall +detection is that the driver should record when it's getting activity +related to when data has been successfully transmitted. Most devices +should be transmitting data on a regular basis as long as the link is +up. If it is not, then this may indicate that the device is stuck and +needs to be reset. At this time, the MAC framework does not provide any +resources for performing these checks; however, polling on each +individual transmit ring for the last completion time while something is +actively being transmitted through the use of routines such as +.Xr timeout 9F +may be a reasonable starting point. +.Ss Driver Command Timeout Detection +Each device is programmed in different ways. Some devices are programmed +through asynchronous commands while others are programmed by writing +directly to memory mapped registers. If a device receives asynchronous +replies to commands, then the device driver should set reasonable +timeouts for all such commands and plan on detecting them. If a timeout +occurs, the driver should presume that there is an issue with the +hardware and proceed to abort the command or reset the device. +.Pp +Many devices do not have such a communication mechanism. However, +whenever there is some activity where the device driver must wait, then +it should be prepared for the fact that the device may never get back to +it and react appropriately by performing some kind of device reset. +.Ss Reacting to Errors +When any of the above categories of errors has been triggered, the +behavior that the device driver should take depends on the kind of +error. If a fatal error, for example, a transport error, a transmit +stall was detected, or the device indicated an uncorrectable error was +detected, then it is +important that the driver take the following steps: +.Bl -enum -offset indent +.It +Set a flag in the device driver's state that indicates that it has hit +an error condition. When this error condition flag is asserted, +transmitted packets should be accepted and dropped and actions that would +require writing to the device state should fail with an error. This flag +should remain until the device has been successfully restarted. +.It +If the error was not a transport error that was indicated by the fault +management architecture, e.g. a transport error that was detected, then +the device driver should post an +.Sy ereport +indicating what has occurred with the +.Xr ddi_fm_ereport_post 9F +function. +.It +The device driver should indicate that the device's service was lost +with a call to +.Xr ddi_fm_service_impact 9F +using the symbol +.Sy DDI_SERVICE_LOST . +.It +At this point the device driver should issue a device reset through some +device-specific means. +.It +When the device reset has been completed, then the device driver should +restore all of the programmed state to the device. This includes things +like the current MTU, advertised auto-negotiation speeds, MAC address +filters, and more. +.It +Finally, when service has been restored, the device driver should call +.Xr ddi_fm_service_impact 9F +using the symbol +.Sy DDI_SERVICE_RESTORED . +.El +.Pp +When a non-fatal error occurs, then the device driver should submit an +ereport and should optionally mark the device degraded using +.Xr ddi_fm_service_impact 9F +with the +.Sy DDI_SERVICE_DEGRADED +value depending on the nature of the problem that has occurred. +.Pp +Device drivers should never make the decision to remove a device from +service based on errors that have occurred nor should they panic the +system. Rather, the device driver should always try to notify the +operating system with various ereports and allow its policy decisions to +occur. The decision to retire a device lies in the hands of the fault +management architecture. It knows more about the operator's intent and +the surrounding system's state than the device driver itself does and it +will make the call to offline and retire the device if it is required. +.Ss Device Resets +When resetting a device, a device driver must exercise caution. If a +device driver has not been written to plan for a device reset, then it +may not correctly restore the device's state after such a reset. Such +state should be stored in the instance's private state data as the MAC +framework does not know about device resets and will not inform the +device again about the expected, programmed state. +.Pp +One wrinkle with device resets is that many networking cards show up as +multiple PCI functions on a single device, for example, each port may +show up as a separate function and thus have a separate instance of the +device driver attached. When resetting a function, device driver writers +should carefully read the device programming manuals and verify whether +or not a reset impacts only the stalled function or if it impacts all +function across the device. +.Pp +If the only way to reset a given function is through the device, then +this may require more coordination and work on the part of the device +driver to ensure that all the other instances are correctly restored. +In cases where this occurs, some devices offer ways of injecting +interrupts onto those other functions to notify them that this is +occurring. +.Sh MBLKS AND DMA +The networking stack manages framed data through the use of the +.Xr mblk 9S +structure. The mblk allows for a single message to be made up of +individual blocks. Each part is linked together through its +.Sy b_cont +member. However, it also allows for multiple messages to be chained +together through the use of the +.Sy b_next +member. While the networking stack works with these structures, device +drivers generally work with DMA regions. There are two different +strategies that device drivers use for handling these two different +cases: copying and binding. +.Ss Copying Data +The first way that device drivers handle interfacing between the two is +by having two separate regions of memory. One part is memory which has +been allocated for DMA through a call to +.Xr ddi_dma_alloc 9F +and the other is memory associated with the memory block. +.Pp +In this case, a driver will use +.Xr bcopy 9F +to copy memory between the two distinct regions. When transmitting a +packet, it will copy the memory from the mblk_t to the DMA region. When +receiving memory, it will allocate a mblk_t through the +.Xr allocb 9F +routine, copy the memory across with +.Xr bcopy 9F , +and then increment the mblk_t's +.Sy w_ptr +structure. +.Pp +If, when receiving, memory is not available for a new message block, +then the frame should be skipped and effectively dropped. A kstat should +be bumped when such an occasion occurs. +.Ss Binding Data +An alternative approach to copying data is to use DMA binding. When +using DMA binding, the OS takes care of mapping between DMA memory and +normal device memory. The exact process is a bit different between +transmit and receive. +.Pp +When transmitting a device driver has an mblk_t and needs to call the +.Xr ddi_dma_addr_bind_handle 9F +function to bind it to an already existing DMA handle. At that point, it +will receive various DMA cookies that it can use to obtain the addresses +to program the device with for transmitting data. Once the transmit is +done, the driver must then make sure to call +.Xr freemsg 9F +to release the data. It must not call +.Xr freemsg 9F +before it receives an interrupt from the device indicating that the data +has been transmitted, otherwise it risks sending arbitrary kernel +memory. +.Pp +When receiving data, the device can perform a similar operation. First, +it must bind the DMA memory into the kernel's virtual memory address +space through a call to the +.Xr ddi_dma_addr_bind_handle 9F +function if it has not already. Once it has, it must then call +.Xr desballoc 9F +to try and create a new mblk_t which leverages the associated memory. It +can then pass that mblk_t up to the stack. +.Ss Considerations +When deciding which of these options to use, there are many different +considerations that must be made. The answer as to whether to bind +memory or to copy data is not always simpler. +.Pp +The first thing to remember is that DMA resources may be finite on a +given platform. Consider the case of receiving data. A device driver +that binds one of its receive descriptors may not get it back for quite +some time as it may be used by the kernel until an application actually +consumes it. Device drivers that try to bind memory for receive, often +work with the constraint that they must be able to replace that DMA +memory with another DMA descriptor. If they were not replaced, then +eventually the device would not be able to receive additional data into +the ring. +.Pp +On the other hand, particularly for larger frames, copying every packet +from one buffer to another can be a source of additional latency and +memory waste in the system. For larger copies, the cost of copying may +dwarf any potential cost of performing DMA binding. +.Pp +For device driver authors that are unsure of what to do, they should +first employ the copying method to simplify the act of writing the +device driver. The copying method is simpler and also allows the device +driver author not to worry about allocated DMA memory that is still +outstanding when it is asked to unload. +.Pp +If device driver writers are worried about the cost, it is recommended +to make the decision as to whether or not to copy or bind DMA data +a separate private property for both transmitting and receiving. That +private property should indicate the size of the received frame at which +to switch from one format to the other. This way, data can be gathered +to determine what the impact of each method is on a given platform. +.Sh SEE ALSO +.Xr dladm 1M , +.Xr driver.conf 4 , +.Xr ieee802.3 5 , +.Xr dlpi 7P , +.Xr _fini 9E , +.Xr _info 9E , +.Xr _init 9E , +.Xr attach 9E , +.Xr close 9E , +.Xr detach 9E , +.Xr mc_close 9E , +.Xr mc_getcapab 9E , +.Xr mc_getprop 9E , +.Xr mc_getstat 9E , +.Xr mc_multicst 9E , +.Xr mc_open 9E , +.Xr mc_propinfo 9E , +.Xr mc_setpromisc 9E , +.Xr mc_setprop 9E , +.Xr mc_start 9E , +.Xr mc_stop 9E , +.Xr mc_tx 9E , +.Xr mc_unicst 9E , +.Xr open 9E , +.Xr allocb 9F , +.Xr bcopy 9F , +.Xr ddi_dma_addr_bind_handle 9F , +.Xr ddi_dma_alloc 9F , +.Xr ddi_fm_acc_err_get 9F , +.Xr ddi_fm_dma_err_get 9F , +.Xr ddi_fm_ereport_post 9F , +.Xr ddi_fm_fini 9F , +.Xr ddi_fm_init 9F , +.Xr ddi_fm_service_impact 9F , +.Xr ddi_get8 9F , +.Xr ddi_put8 9F , +.Xr desballoc 9F , +.Xr freemsg 9F , +.Xr kstat_create 9F , +.Xr mac_alloc 9F , +.Xr mac_fini_ops 9F , +.Xr mac_hcksum_get 9F , +.Xr mac_hcksum_set 9F , +.Xr mac_init_ops 9F , +.Xr mac_link_update 9F , +.Xr mac_lso_get 9F , +.Xr mac_maxsdu_update 9F , +.Xr mac_prop_info_set_default_link_flowctrl 9F , +.Xr mac_prop_info_set_default_str 9F , +.Xr mac_prop_info_set_default_uint32 9F , +.Xr mac_prop_info_set_default_uint64 9F , +.Xr mac_prop_info_set_default_uint8 9F , +.Xr mac_prop_info_set_perm 9F , +.Xr mac_prop_info_set_range_uint32 9F , +.Xr mac_register 9F , +.Xr mac_rx 9F , +.Xr mac_unregister 9F , +.Xr mc_getprop 9F , +.Xr mc_tx 9F , +.Xr mod_install 9F , +.Xr mod_remove 9F , +.Xr strcmp 9F , +.Xr timeout 9F , +.Xr cb_ops 9S , +.Xr ddi_device_acc_attr_t 9S , +.Xr dev_ops 9S , +.Xr kstat_create 9S , +.Xr mac_callbacks 9S , +.Xr mac_register 9S , +.Xr mblk 9S , +.Xr modldrv 9S , +.Xr modlinkage 9S +.Rs +.%A McCloghrie, K. +.%A Rose, M. +.%T RFC 1213 Management Information Base for Network Management of +.%T TCP/IP-based internets: MIB-II +.%D March 1991 +.Re +.Rs +.%A McCloghrie, K. +.%A Kastenholz, F. +.%T RFC 1573 Evolution of the Interfaces Group of MIB-II +.%D January 1994 +.Re +.Rs +.%A Kastenholz, F. +.%T RFC 1643 Definitions of Managed Objects for the Ethernet-like +.%T Interface Types +.Re diff --git a/usr/src/man/man9e/mc_getcapab.9e b/usr/src/man/man9e/mc_getcapab.9e new file mode 100644 index 0000000000..b890163c53 --- /dev/null +++ b/usr/src/man/man9e/mc_getcapab.9e @@ -0,0 +1,184 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 02, 2016 +.Dt MC_GETCAPAB 9E +.Os +.Sh NAME +.Nm mc_getcapab +.Nd get device capabilities +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft boolean_t +.Fo prefix_m_getcapab +.Fa "void *driver" +.Fa "mac_capab_t capab" +.Fa "void *cap_data" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa capab +A value which indicates the capability being asked about. For a full +list of capabilities, see the +.Sx CAPABILITIES +section of +.Xr mac 9E . +.It Fa cap_data +Capability specific data that may need to be filled in. The type of data +used is listed in the +.Sx CAPABILITIES +section of +.Xr mac 9E . +.El +.Sh DESCRIPTION +The +.Fn mc_getcapab +entry point is called to determine whether or not a device supports a +specific capability. The capability in question is specified in +.Fa capab +and the list of possible capabilities is listed in the +.Sx CAPABILITIES +section of +.Xr mac 9E . +.Pp +Capabilities are generally only queried once for a given device. An +instance of a device cannot change whether or not it supports a given +capability after it has been queried by the system. +.Pp +Each capability has its own specific kind of data that a device driver +needs to fill in as part of declaring that it supports a given +capability. That data is present in +.Fa cap_data . +The device driver should cast +.Fa cap_data +to the appropriate structure and fill it in. The structures to use for a +given capability are all listed in the +.Sx CAPABILITIES +section of +.Xr mac 9E . +.Pp +The return value is used to indicate whether or not a device driver +supports the given capability. If it does, then the device driver should +return +.Sy B_TRUE +after filling in +.Fa cap_data . +Otherwise, whenever it encounters an unsupported or unknown capability, +it should return +.Sy B_FALSE . +Many device drivers employ +.Sy switch +statements and return +.Sy B_FALSE +from their default case statement. The system will present unknown +capabilities to device drivers and they must properly return +.Sy B_FALSE . +.Pp +The driver has access to its soft state by casting the +.Fa driver +argument to the specific structure. The device driver is responsible for +any necessary locking. +.Pp +Many capabilities are related to features of hardware. However, all +hardware and firmware has the possibility of having bugs. It is +recommended that any capability that is supported have some form of +tunable, whether in the form of a +.Sy MAC_PROP_PRIVATE +driver-specific property and/or a +.Xr driver.conf 5 +property to disable it. This way when problems are discovered in the +field, they can be worked around without requiring initial changes to +the device driver. +.Sh CONTEXT +This function is generally only called from +.Sy kernel +context. +.Sh RETURN VALUES +If the device driver supports the specified capability +.Fa capab , +then it should return +.Sy B_TRUE . +Otherwise, it should return +.Sy B_FALSE . +.Sh EXAMPLES +The following example shows how a driver might structure its +.Fn mc_getcapab +entry point. +.Bd -literal +#include <sys/types.h> +#include <sys/mac_provider.h> + +/* + * Note, this example merely shows the structure of the function. For + * the purpose of this example, we assume that we have a device which + * has members that indicate whether the various capabilities have been + * enabled and that they are read-only after the driver has had its + * mc_start(9F) entry point called. + */ + +#define EXAMPLE_LSO_MAX 65535 + +static boolean_t +example_m_getcapab(void *arg, mac_capab_t cap, void *cap_data) +{ + example_t *ep = arg; + + switch (cap) { + case MAC_CAPAB_HCKSUM: { + uint32_t *txflags = cap_data; + + /* + * The actual flags used here should be replaced with + * what the device actually supports. If the device + * doesn't support checksums, then this case statement + * shouldn't exist. + */ + *txflags = 0; + if (ep->ep_tx_hcksum_enable == B_TRUE) + *txflags = HCKSUM_IPHDRCKSUM; + break; + } + + case MAC_CAPAB_LSO: { + mac_capab_lso_t *lso = cap_data; + + if (ep->ep_lso_enable == B_TRUE) { + lso->lso_flags = LSO_TX_BASIC_TCP_IPV4; + lso->lso_basic_tcp_ipv4.lso_max = EXAMPLE_LSO_MAX; + } else { + return (B_FALSE); + } + break; + } + + default: + return (B_FALSE); + } + + return (B_TRUE); +} +.Ed +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9e/mc_getprop.9e b/usr/src/man/man9e/mc_getprop.9e new file mode 100644 index 0000000000..c9a9f1786f --- /dev/null +++ b/usr/src/man/man9e/mc_getprop.9e @@ -0,0 +1,231 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 02, 2016 +.Dt MC_GETPROP 9E +.Os +.Sh NAME +.Nm mc_getprop +.Nd get device properties +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo prefix_m_getprop +.Fa "void *driver" +.Fa "const char *pr_name" +.Fa "mac_prop_id_t pr_num" +.Fa "uint_t pr_valsize" +.Fa "void *pr_val" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa pr_name +A null-terminated string that contains the name of the property. +.It Fa pr_num +A constant that is used to identify the property. +.It Fa pr_valsize +A value that indicates the size in bytes of +.Fa pr_val . +.It Fa pr_val +A pointer to a +.Fa pr_valsize +byte buffer that can store the property. +.El +.Sh DESCRIPTION +The +.Fn mc_getprop +entry point is used to obtain the value of a given device's property and +place it into +.Fa pr_val . +.Pp +When the +.Fn mc_getprop +entry point is called, the driver needs to first identify the property. +The set of possible properties and their meaning is listed in the +.Sx PROPERTIES +section of +.Xr mac 9E . +It should identify the property based on the value of +.Fa pr_num . +Most drivers will use a +.Sy switch +statement and for any property that it supports it should then check if +the value in +.Fa pr_valsize +is sufficient for the property, comparing it to the minimum size +listed for the property in +.Xr mac 9E . +If it is not, then it should return an error. Otherwise, it should copy +the property's value into +.Fa pr_val . +When an unknown or unsupported +property is encountered, generally the +.Sy default +case of the switch statement, the device driver should return an error. +.Pp +The special property +.Sy MAC_PROP_PRIVATE +indicates that this is a device driver specific private property. The +device driver must then look at the value of the +.Fa pr_name +argument and use +.Xr strcmp 9F +on it, comparing it to each of its private (bounded-size) properties to +identify which one it is. +.Pp +The device +driver can access its device soft state by casting the +.Fa device +pointer to the appropriate structure. As this may be called while other +operations are ongoing, the device driver should employ the appropriate +locking while reading the properties. +.Sh CONTEXT +The +.Fn mc_getprop +function is generally called from +.Sy kernel +context. +.Sh RETURN VALUES +Upon successful completion, the device driver should have copied the +value of the property into +.Fa pr_val +and return +.Sy 0 . +Otherwise, a positive error should be returned to indicate failure. +.Sh EXAMPLES +The following example shows how a device driver might structure its +.Fn mc_getprop +entry point. +.Bd -literal +#include <sys/mac_provider.h> + +/* + * Note, this example merely shows the structure of this function. + * Different devices will manage their state in different ways. Like other + * examples, this assumes that the device has state in a structure called + * example_t and that there is a lock which keeps track of that state. + */ +static char *example_priv_props[] = { + "_rx_intr_throttle", + "_tx_intr_throttle", + NULL +}; + +static int +example_m_getprop_private(example_t *ep, const char *pr_name, uint_t pr_valsize, + void *pr_val) +{ + uint32_t val; + + ASSERT(MUTEX_HELD(&ep->ep_lock)); + if (strcmp(pr_name, example_priv_props[0] == 0) { + val = ep->ep_rx_itr; + } else if (strcmp(pr_name, exampe_priv_props[1] == 0) { + val = ep->ep_tx_itr; + } else { + return (ENOTSUP); + } + + /* + * Due to issues in the GLDv3, these must be returned as string + * properties. + */ + if (snprintf(pr_val, pr_valsize, "%d", val) >= pr_valsize) + return (EOVERFLOW); + + return (0); +} + +static int +example_m_getprop(void *arg, const char *pr_name, mac_prop_id_t pr_num, + uint_t pr_valsize, void *pr_val) +{ + int ret = 0; + uint64_t speed; + example_t *ep = arg; + + mutex_enter(&ep->ep_lock); + + /* + * This only handles a subset of the properties that exist on the + * system. A proper driver will need to handle more. See mac(9E) for a + * full property list. + */ + switch (pr_num) { + case MAC_PROP_DUPLEX: + if (pr_valsize < sizeof (link_duplex_t)) { + ret = EOVERFLOW; + break; + } + bcopy(ep->ep_link_duplex, pr_val, sizeof (link_duplex_t)); + case MAC_PROP_SPEED: + if (pr_valsize < sizeof (uint64_t)) { + ret = EOVERFLOW; + break; + } + /* + * The link speed is stored in Mbits/s in this driver and is + * expected in bits/s. + */ + speed = ep->ep_link_speed * 1000000ULL; + bcopy(&speed, pr_val, sizeof (speed)); + break; + case MAC_PROP_MTU: + if (pr_valsize < sizeof (uint32_t)) { + ret = EOVERFLOW; + break; + } + bcopy(&ep->ep_mtu, pr_val, sizeof (speed)); + break; + case MAC_PROP_PRIVATE: + ret = example_m_getprop_private(ep, pr_name, pr_valsize, + pr_val); + break; + default: + ret = ENOTSUP; + break; + } + + mutex_exit(&ep->ep_lock); + + return (ret); +} +.Ed +.Sh ERRORS +The device driver may return one of the following errors. While this list +is not intended to be exhaustive, it is recommended to use one of these +if possible. +.Bl -tag -width Er +.It Er ENOTSUP +This error should be used whenever an unknown or unsupported property is +encountered. +.It Er EOVERFLOW +This error should be used when +.Fa pr_valsize +is smaller than the required size for a given value. +.El +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr strcmp 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9e/mc_getstat.9e b/usr/src/man/man9e/mc_getstat.9e new file mode 100644 index 0000000000..a2733606c1 --- /dev/null +++ b/usr/src/man/man9e/mc_getstat.9e @@ -0,0 +1,156 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MC_GETSTAT 9E +.Os +.Sh NAME +.Nm mc_getstat +.Nd get device statistics information +.Sh SYNOPSIS +.In sys/mac_provider.h +.In sys/mac_ether.h +.Ft int +.Fo prefix_m_getstat +.Fa "void *driver" +.Fa "uint_t stat" +.Fa "uint64_t *stat_value" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa stat +The numeric identifier of a statistic. +.It Fa stat_value +A pointer to a 64-bit unsigned value in which the device driver should +place the statistic. +.El +.Sh DESCRIPTION +The +.Fn mc_getstat +entry point is used to get statistics from the device driver. Statistics +are stored as monotonic values. They should only ever increase over the +lifetime of a device, resetting only as part of the instance of a +device attaching and detaching. When hardware has values that may +overflow, it is up to the device driver to store them as a 64-bit +quantity that does not overflow in its soft state. +.Pp +Most device drivers will use a +.Sy switch +statement, switching on the value of the statistic +.Fa stat . +The full list of supported statistics is available in the +.Sx STATISTICS +section of +.Xr mac 9E . +.Pp +If a device driver recognizes the value of +.Fa stat , +then it should store the current 64-bit unsigned integer into +.Fa stat_value . +If the device driver does not support the statistic or does not +recognize the requested statistic, then it should not set anything in +.Fa stat_value +and instead return +.Er ENOTSUP . +.Pp +The device driver can obtain access to its soft state through the +.Fa driver +member. It should be cast to the appropriate structure. The device +driver should employ any necessary locking to access the statistic +members of its soft state to ensure that the data is properly +serialized. +.Sh RETURN VALUES +Upon successful completion, the device driver should fill in +.Fa stat_value +and return +.Sy 0 . +Otherwise it should return a non-zero error number to indicate an error +occurred. +.Sh EXAMPLES +The following example shows how a driver might structure its +.Fn mc_getstat +entry point. +.Bd -literal +#include <sys/mac_provider.h> +#include <sys/mac_ether.h> + +/* + * Note, this example merely shows the structure of the function. For + * the purpose of this example, we assume that we have a device which + * has members that indicate its stats and that it has a lock which is + * used to serialize access to this data. + */ + +static int +example_m_getstat(void *arg, uint_t stat, uint64_t *val) +{ + example_t *ep = arg; + + mutex_enter(&ep->ep_lock); + switch (stat) { + case MAC_STAT_RBYTES: + *val = ep->ep_stats.eps_rbytes; + break; + case MAC_STAT_OBYTES: + *val = ep->ep_stats.eps_obytes; + break; + case MAC_STAT_IPACKETS: + *val = ep->ep_stats.eps_ipackets; + break; + case MAC_STAT_OPACKETS: + *val = ep->ep_stats.eps_opackets; + break; + + /* + * Note, there are many more stats that should be checked and + * filled in if supported. You should use one case statement for + * each stat. + */ + + default: + mutex_exit(&ep->ep_lock); + return (ENOTSUP); + } + mutex_exit(&ep->ep_lock); + + return (0); +} +.Ed +.Sh ERRORS +The device driver may return one of the following errors. While this list +is not intended to be exhaustive, it is recommended to use one of these +if possible. +.Bl -tag -width Er +.It Er ENOTSUP +The specified statistic is unknown, unsupported, or unimplemented. +.It Er EIO +A transport or DMA FM related error occurred while trying to sync data +from the device. +.It Er ECANCELLED +The device is not currently in a state where it can currently service +the request. +.El +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9e/mc_ioctl.9e b/usr/src/man/man9e/mc_ioctl.9e new file mode 100644 index 0000000000..65f93e1be0 --- /dev/null +++ b/usr/src/man/man9e/mc_ioctl.9e @@ -0,0 +1,126 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MC_IOCTL 9E +.Os +.Sh NAME +.Nm mc_ioctl +.Nd device specific I/O control operation +.Sh SYNOPSIS +.In sys/types.h +.In sys/stream.h +.In sys/stropts.h +.In sys/ddi.h +.In sys/sunddi.h +.Ft void +.Fo prefix_m_ioctl +.Fa "void *driver" +.Fa "queue_t *wq" +.Fa "mblk_t *mp" +.Fc +.Sh INTERFACE LEVEL +illumos DDI Specific +.Sh PARAMETERS +.Bl -tag -width Ds +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa wq +A pointer to a STREAMS write-side queue that the ioctl request was +received upon. +.It Fa mp +A pointer to a message block structure that contains the I/O control +request. +.El +.Sh DESCRIPTION +The +.Fn mc_ioctl +entry point is an optional GLDv3 entry point. It provides a means +for device-specific I/O control operations to be initiated. In general, +this entry point is not recommended for most devices and is +unimplemented. +.Pp +The I/O control interface is not like a traditional character or block +device's +.Xr ioctl 9E +entry point, rather it is a STREAMS-based I/O control operation. The +data pointer of the +.Fa mp +argument is a +.Xr iocblk 9S +structure. After handling the message, the driver will need to reply to +the message, which is usually done by using the +.Xr miocack 9F +and +.Xr miocnak 9F +functions to prepare +.Fa mp . +.Pp +The device driver can access its soft state by casting the value pointed +to in +.Fa driver . +The driver should be careful and ensure that it performs any necessary +locking to access members of that structure while processing the I/O +control operation. +.Sh RETURN VALUES +Return information is not conveyed by the return value of this function, rather +it is encoded in the +.Xr iocblk 9S +structure in the +.Fa mp +argument. +.Sh EXAMPLES +The following example shows how a device driver might structure its +.Fn mc_ioctl +entry point. +.Bd -literal +#include <sys/types.h> +#include <sys/stream.h> +#include <sys/stropts.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +/* + * Note, this example merely shows the structure of this function. It does not + * actively handle any device-specific ioctls and instead returns failure for + * every one. This is the most common case. Note, miocnak(9F) takes care of + * calling putnext(9F) for us. + */ +static void +example_m_ioctl(void *arg, queue_t *wq, mblk_t *mp) +{ + miocnak(wq, mp, 0, EINVAL); +} +.Ed +.Sh SEE ALSO +.Xr ioctl 9E , +.Xr mac 9E , +.Xr put 9E , +.Xr mac_register 9F , +.Xr miocack 9F , +.Xr miocnak 9F , +.Xr putnext 9F , +.Xr iocblk 9S , +.Xr mac_register 9S +.Rs +.%T Writing Device Drivers +.Re +.Rs +.%T STREAMS Programming Guide +.Re diff --git a/usr/src/man/man9e/mc_multicst.9e b/usr/src/man/man9e/mc_multicst.9e new file mode 100644 index 0000000000..daf47bf675 --- /dev/null +++ b/usr/src/man/man9e/mc_multicst.9e @@ -0,0 +1,229 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MC_MULTICST 9E +.Os +.Sh NAME +.Nm mc_multicst +.Nd add or remove multicast address from device filter +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo prefix_m_multicst +.Fa "void *driver" +.Fa "boolean_t add" +.Fa "const uint8_t *mac" +.Fc +.Sh INTERFACE LEVEL +illumos DDI Specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa add +A boolean value that indicates whether the device driver should add the +specified address to its filter list or remove it. +.It Fa mac +A pointer to an array of bytes that contains the new multicast address being +added or removed. It is guaranteed to be at least a number of bytes long equal +to the length of the MAC plugin's address length. For Ethernet devices that +length is six bytes, +.Sy ETHERADDRL . +.El +.Sh DESCRIPTION +The +.Fn mc_multicst +entry point is used to program a device driver's multicast filters. For +more background on filter management, see the +.Sx MAC Address Filter Management +section in +.Xr mac 9E . +.Pp +The device driver can optionally sanity check +.Fa mac +by making sure that it's both a valid multicast address and by checking +whether or not it's already programmed the address. Based on the value of +.Fa add , +the driver should either add the specified address, +.Fa mac , +or remove it from its filter tables. The device driver is not +responsible for any form of reference counting on these requests: that +is maintained by the broader framework. +.Pp +The device driver can access its own device soft state by casting the +.Fa device +pointer. The device driver should employ the appropriate locking while +updating and manipulating its filter tables and its own records. It is +recommended that device drivers always maintain a copy of the addresses +programmed into the device's filter tables so that they can more easily +recover from various device resets and errors, or handle requests to +suspend and resume the device that may result in the device registers +being cleared. +.Sh RETURN VALUES +Upon successful completion, the device driver should return +.Sy 0 . +Otherwise, the driver should return a positive error number to indicate +why the request failed. +.Sh EXAMPLES +The following example shows how a device driver might structure its +.Fn mc_multicst +entry point. +.Bd -literal +#include <sys/mac_provider.h> + +/* + * Note, this example merely shows the structure of this function. + * Different devices will have different ways to manage the set of + * multicast MAC addresses that they can program into their filters and + * they have different ways of keeping track of them. Like other + * examples, this assumes that there is a lock which protects this data. + * In this case we assume we have an array of structures that is used to + * track each multicast entry and a count of valid entries. + */ + +#define EXAMPLE_NMULTICAST_ADDRS 100 + +static int +example_multicast_add(example_t *ep, const uint8_t *mac_addr) +{ + int i, ret; + + mutex_enter(&ep->ep_lock); + for (i = 0; i < ep->ep_nmcast_addrs; i++) { + if (bcmp(ep->ep_nmcast_addrs[i].ema_addr, mac_addr, + ETHERADDRL) == 0) { + /* + * The address is alread in our list, so we can + * return and say we're done. + */ + mutex_exit(&ep->ep_lock); + return (0); + } + } + + /* + * We need to add this multicast address to a filter, make sure + * we have enough space to do so. + */ + if (ep->ep_nmcast_addrs >= EXAMPLE_NMULTICAST_ADDRS) { + mutex_exit(&ep->ep_lock); + return (ENOSPC); + } + + /* + * Program the device before we add it to our list. Assume zero + * means success. + */ + ret = example_program_add_mcast_filter(ep, mac_addr); + if (ret == 0) { + bcopy(mac_addr, + ep->ep_nmcast_addrs[ep->ep_nmcast_addrs].ema_addr, + ETHERADDRL); + ep->ep_nmcast_addrs++; + } + + mutex_exit(&ep->ep_lock); + + return (ret); +} + +static int +example_multicast_remove(example_t *ep, const uint8_t *mac_addr) +{ + int i, ret; + boolean_t found = B_FALSE; + + mutex_enter(&ep->ep_lock); + for (i = 0; i < ep->ep_nmcast_addrs; i++) { + if (bcmp(ep->ep_mcast_addrs[i].ema_addr, mac_addr, + ETHERADDRL) == 0) { + found = B_TRUE; + break; + } + } + + if (found == B_FALSE) { + mutex_exit(&ep->ep_lock); + return (ENOENT); + } + + /* + * Assume that a return value of zero indicates that the removal + * was successful. Note that i still has the index of this + * entry. + */ + ret = example_program_rem_mcast_filter(ep, mac_addr); + if (ret == 0) { + int last = ep->ep_nmcast_addrs - 1; + if (i != last) { + bcopy(ep->ep_mcast_addrs[last].ema_addr, + ep->ep_mcast_addrs[i].ema_addr, + ETHERADDRL); + } + bzero(ep->ep_mcast_addrs[last].ema_addr, + ETHERADDRL); + VERIFY(ep->ep_nmcast_addrs > 0); + ep->ep_nmcast_addrs--; + } + + mutex_exit(&ep->ep_lock); + return (ret); +} + +static int +example_m_multicst(void *arg, boolean_t add, const uint8_t *mac_addr) +{ + example_t *ep = arg; + + /* + * We sanity check that we've been given a multicast address. + */ + if ((mac_addr[0] & 0x01) == 0) + return (EINVAL); + + if (add) + return (example_multicast_add(ep, mac_addr); + else + return (example_multicast_remove(ep, mac_addr)); +} +.Ed +.Sh ERRORS +The device driver may return one of the following errors. While this list +is not intended to be exhaustive, it is recommended to use one of these +if possible. +.Bl -tag -width Er +.It Er EINVAL +The address +.Fa mac +is not a valid unicast address. +.It Er EIO +The driver encountered a device or transport error while trying to +update the device's state. +.It Er ENOENT +The device driver was asked to remove a multicast address that it does +not have. +.It Er ENOSPC +The driver was asked to add a multicast address; however, it has no more +filter slots available to program the entry. +.El +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9e/mc_open.9e b/usr/src/man/man9e/mc_open.9e new file mode 100644 index 0000000000..7a16ff84ed --- /dev/null +++ b/usr/src/man/man9e/mc_open.9e @@ -0,0 +1,69 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd Aug 18, 2016 +.Dt MC_OPEN 9E +.Os +.Sh NAME +.Nm mc_open , +.Nm mc_close +.Nd optional device open and close entry points +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo prefix_m_open +.Fa "void *driver" +.Fc +.Ft void +.Fo prefix_m_close +.Fa "void *driver" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.El +.Sh DESCRIPTION +The +.Fn mc_open +and +.Fn mc_close +entry points are called when the file system node corresponding to the +device is opened. Standard device drivers do not need to implement this +function and should not define the callback. +.Pp +The GLDv3 guarantees that calls to the +.Fn mc_open +and +.Fn mc_close +entry points are serialized. Only one such call will be issued to the +device driver at any time. +.Sh RETURN VALUES +Upon successful completion, the device driver should return +.Sy 0 +for its +.Fn mc_open +entry point. Otherwise, it should return a non-zero error number to +indicate an error occurred. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9e/mc_propinfo.9e b/usr/src/man/man9e/mc_propinfo.9e new file mode 100644 index 0000000000..cbc43e8774 --- /dev/null +++ b/usr/src/man/man9e/mc_propinfo.9e @@ -0,0 +1,259 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MC_PROPINFO 9E +.Os +.Sh NAME +.Nm mc_propinfo +.Nd get information about a property +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo prefix_m_propinfo +.Fa "void *driver" +.Fa "const char *pr_name" +.Fa "mac_prop_id_t pr_num" +.Fa "mac_prop_info_handle_t hdl" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Ds +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa pr_name +A null-terminated string that contains the name of the property. +.It Ft pr_num +The value indicates the property that the device is working with. +.It Fa hdl +A handle to use with the +.Xr mac_prop_info 9F +family of routines to indicate the property's metadata. +.El +.Sh DESCRIPTION +The +.Fn mc_propinfo +entry point is an optional entry point for networking device drivers +that is used to obtain metadata about a property, including its +permissions, default value, and information about valid possible values. +If the device driver does not implement either of the +.Xr mc_getprop 9E +or +.Xr mc_setprop 9E +entry points then it does not need to implement the +.Xr mc_propinfo 9E +entry point. However, it is highly recommended that these interfaces be +implemented in order to give users and administrators of the system +access to the properties of the device. +.Pp +When the +.Fn mc_propinfo +entry point is called, the driver needs to first identify the property. +The set of possible properties and their meaning is listed in the +.Sx PROPERTIES +section of +.Xr mac 9E . +It should identify the property based on the value of +.Fa pr_num . +Most drivers will use a +.Sy switch +statement and for any property that it supports it should call the +appropriate +.Xr mac_prop_info 9F +functions to set values and then return. When an unknown or unsupported +property is encountered, generally the +.Sy default +case of the switch statement, the device driver should simply do nothing +and return. +.Pp +The special property +.Sy MAC_PROP_PRIVATE +indicates that this is a device driver specific private property. The +device driver must then look at the value of the +.Fa pr_name +argument and use +.Xr strcmp 9F +on it, comparing it to each of its private properties to identify which +one it is. +.Pp +For each property the driver has three different sets of information +that it can fill in. The driver should try to fill in all of these that +make sense, if possible. +.Bl -enum +.It +First, the driver should fill in the permissions of the property with +the +.Xr mac_prop_info_set_perm 9F +function. These permissions indicate what the device driver supports for +a given property. For each non-private property, see the property list +in +.Xr mac 9E +to see what the maximum property permissions are. As discussed in +.Xr mac 9E , +a device driver may have more limited permissions than the default. For +example, on some SFP-based devices, it may not be possible to change any +of the auto-negotiation properties. +.It +The driver should then fill in any default value that it has for a +property. This is the value that the device driver sets by default if no +other tuning has been performed. There are different functions depending +on the type of the default value to call. They are all listed in +.Xr mac_prop_info 9F . +.It +Finally, a driver may optionally set one or more value ranges. These are +used for integer properties such as +.Sy MAC_PROP_MTU . +The driver may call +.Xr mac_prop_info_set_range_uint32 9F +to set a series of one or more inclusive ranges that describe valid +values for the property. For example, a device that supports jumbo +frames up to 9600 bytes would call +.Xr mac_prop_info_set_range_uint32 9F +to convey that it supports MTUs in the range of 1500-9600 bytes. +.El +.Pp +If the device driver needs to access its private data, it will be +available in the +.Fa driver +argument which it should cast to the appropriate structure. From there, +the device driver may need to lock the structure to ensure that access +to it is properly serialized. +.Sh RETURN VALUES +The +.Fn mc_propinfo +entry point does not have a return value. Drivers should simply ignore +and immediately return when encountering unsupported and unknown +properties. +.Sh EXAMPLES +The following example shows how a device driver might structure its +.Fn mc_propinfo +entry point. +.Bd -literal +#include <sys/mac_provider.h> + +/* + * Note, this example merely shows the structure of this function. + * Different devices will manage their state in different ways. Like other + * examples, this assumes that the device has state in a structure called + * example_t and that there is a lock which keeps track of that state. + */ + +static void +example_m_propinfo(void *arg, const char *pr_name, mac_prop_id_t pr_num, + mac_prop_info_handle_t prh) +{ + uint8_t value; + uint_t perm; + + example_t *ep = arg; + + mutex_enter(&ep->ep_lock); + + switch (pr_num) { + /* + * We try to fill in as much information for each property as makes + * sense. In some cases, you may only be able to set the permissions. + */ + case MAC_PROP_DUPLEX: + case MAC_PROP_SPEED: + mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ); + break; + + /* + * The MTU is a good example of a property that has a property range. + * The range represents the valid values the MTU can take. + */ + case MAC_PROP_MTU: + mac_prop_info_set_perm(prh, MAC_PROP_PERM_RW); + mac_prop_info_set_range(prh, ep->ep_min_mtu, ep->ep_max_mtu); + break; + + /* + * The ADV properties represent things that the device supports and + * can't be changed by the user. These are good examples of properties + * that have a default value and are read-only. + */ + case MAC_PROP_ADV_100FDX_CAP: + mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ); + value = (ep->ep_link_sup_speeds & EXAMPLE_100FDX) ? 1 : 0; + mac_prop_info_set_default_uint8(prh, value); + break; + case MAC_PROP_ADV_1000FDX_CAP: + mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ); + value = (ep->ep_link_sup_speeds & EXAMPLE_1000FDX) ? 1 : 0; + mac_prop_info_set_default_uint8(prh, value); + break; + case MAC_PROP_ADV_10GFDX_CAP: + mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ); + value = (ep->ep_link_sup_speeds & EXAMPLE_10GDX) ? 1 : 0; + mac_prop_info_set_default_uint8(prh, value); + break; + + /* + * The EN properties represent the speeds advertised by the driver. On + * baseT (copper) PHYs, we allow them to be set, otherwise we don't. + * This driver always advertises it if supported, hence why all of these + * default to advertised if the link supports its. + */ + case MAC_PROP_EN_100FDX_CAP: + perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ? + MAC_PROP_PERM_RW : MAC_PROP_PERM_READ; + mac_prop_info_set_perm(prh, perm); + value = (ep->ep_link_sup_speeds & EXAMPLE_100FDX) ? 1 : 0; + mac_prop_info_set_default_uint8(prh, value); + break; + case MAC_PROP_EN_1000FDX_CAP: + perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ? + MAC_PROP_PERM_RW : MAC_PROP_PERM_READ; + mac_prop_info_set_perm(prh, perm); + value = (ep->ep_link_sup_speeds & EXAMPLE_1000FDX) ? 1 : 0; + mac_prop_info_set_default_uint8(prh, value); + break; + case MAC_PROP_EN_10GFDX_CAP: + perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ? + MAC_PROP_PERM_RW : MAC_PROP_PERM_READ; + mac_prop_info_set_perm(prh, perm); + value = (ep->ep_link_sup_speeds & EXAMPLE_10GFDX) ? 1 : 0; + mac_prop_info_set_default_uint8(prh, value); + break; + + /* + * If this device has private properties, then it should compare pr_name + * with the device's private properties and then fill in property + * information if it recognizes the name. + */ + case MAC_PROP_PRIVATE: + break; + + /* + * For unknown properties, there's not much to do. Simply don't call any + * of the mac_prop_info(9F) related functions. + */ + default: + break; + } + mutex_exit(&ep->ep_lock); +} +.Ed +.Sh SEE ALSO +.Xr mac 9E , +.Xr mc_getprop 9E , +.Xr mc_propinfo 9E , +.Xr mac_prop_info 9F diff --git a/usr/src/man/man9e/mc_setpromisc.9e b/usr/src/man/man9e/mc_setpromisc.9e new file mode 100644 index 0000000000..4c3d4f9113 --- /dev/null +++ b/usr/src/man/man9e/mc_setpromisc.9e @@ -0,0 +1,85 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MC_SETPROMISC 9E +.Os +.Sh NAME +.Nm mc_setpromisc +.Nd modify device promiscuous mode entry point +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo prefix_m_setpromisc +.Fa "void *driver" +.Fa "boolean_t enable" +.Fc +.Sh INTERFACE LEVEL +illumos DDI Specific +.Sh PARAMETERS +.Bl -tag -width Ds +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa enable +A boolean that indicates the desired state of the device's promiscuous +mode. If set to +.Sy B_TRUE , +promiscuous mode should be enabled on the device. If set to +.Sy B_FALSE , +then promiscuous mode should be disabled on the device. +.El +.Sh DESCRIPTION +The +.Fn mc_setpromisc +entry point is called when the GLDv3 wants to change the device's +promiscuous mode. When this entry point is called, the device should +manipulate both its unicast and multicast promiscuous mode. +.Pp +When +.Fa enable +is true, then it should make sure that both unicast and multicast +promiscuous mode are enabled. When it's set to false, then they should +be disabled. In general, devices should always start with promiscuous +mode disabled until the framework indicates that it should be enabled. +.Pp +The device driver's private state is available by casting the +.Fa driver +argument to the function. Note, this entry point may be called in +parallel with others and therefore the device driver should employ any +necessary locking on that structure. +.Sh RETURN VALUES +Upon successful completion, the device driver's +.Fn mc_setpromisc +entry point should return +.Sy 0 +after having set the device's state. Otherwise, it should return a +non-zero positive error number to indicate the error that occurred. +.Sh ERRORS +The device driver may return one of the following errors. While this list +is not intended to be exhaustive, it is recommended to use one of these +if possible. +.Bl -tag -width Er +.It Er EIO +The driver encountered a device or transport error while trying to +update the device's state. +.El +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9e/mc_setprop.9e b/usr/src/man/man9e/mc_setprop.9e new file mode 100644 index 0000000000..c978ef6974 --- /dev/null +++ b/usr/src/man/man9e/mc_setprop.9e @@ -0,0 +1,241 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 02, 2016 +.Dt MC_SETPROP 9E +.Os +.Sh NAME +.Nm mc_setprop +.Nd set device properties +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo prefix_m_setprop +.Fa "void *driver" +.Fa "const char *pr_name" +.Fa "mac_prop_id_t pr_num" +.Fa "uint_t pr_valsize" +.Fa "const void *pr_val" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa pr_name +A null-terminated string that contains the name of the property. +.It Fa pr_num +A constant that is used to identify the property. +.It Fa pr_valsize +A value that indicates the size in bytes of +.Fa pr_val . +.It Fa pr_val +A pointer to a +.Fa pr_valsize +byte buffer that contains the new value of the property. +.El +.Sh DESCRIPTION +The +.Fn mc_setprop +entry point is used to set the value of a given device's property from +the copy stored in +.Fa pr_val . +.Pp +When the +.Fn mc_setprop +entry point is called, the driver needs to first identify the property. +The set of possible properties and their meaning is listed in the +.Sx PROPERTIES +section of +.Xr mac 9E . +It should identify the property based on the value of +.Fa pr_num . +Most drivers will use a +.Sy switch +statement and for any property that it supports it should then check if +the value in +.Fa pr_valsize +is sufficient for the property, comparing it to the minimum size +listed for the property in +.Xr mac 9E . +If it is not, then it should return an error. Otherwise, it should +update the property based on the value in +.Fa pr_val . +When an unknown or unsupported property is encountered, generally the +.Sy default +case of the switch statement, the device driver should return an error. +.Pp +The special property +.Sy MAC_PROP_PRIVATE +indicates that this is a device driver specific private property. The +device driver must then look at the value of the +.Fa pr_name +argument and use +.Xr strcmp 9F +on it, comparing it to each of its private properties to identify which +one it is. +.Pp +Not all properties are supposed to be writable. Some devices may opt to +not allow a property that is designated as read/write to be set. When +such a property is encountered, the driver should return the appropriate +error. +.Pp +The device +driver can access its device soft state by casting the +.Fa device +pointer to the appropriate structure. As this may be called while other +operations are ongoing, the device driver should employ the appropriate +locking while writing the properties. +.Sh RETURN VALUES +Upon successful completion, the device driver should have copied the +value of the property into +.Fa pr_val +and return +.Sy 0 . +Otherwise, a positive error should be returned to indicate failure. +.Sh EXAMPLES +The following examples shows how a device driver might structure its +.Fn mc_setporp +entry point. +.Bd -literal +#include <sys/mac_provider.h> + +/* + * Note, this example merely shows the structure of this function. + * Different devices will manage their state in different ways. Like other + * examples, this assumes that the device has state in a structure called + * example_t and that there is a lock which keeps track of that state. + * + * For the purpose of this example, we assume that this device supports 100 Mb, + * 1 GB, and 10 Gb full duplex speeds. + */ + +static int +exmple_m_setprop(void *arg, const char *pr_name, mac_prop_id_t pr_num, + uint_t pr_valsize, const void *pr_val) +{ + uint32_t new_mtu; + int ret = 0; + example_t *ep = arg; + + mutex_enter(&ep->ep_lock); + switch (pr_num) { + /* + * These represent properties that can never be changed, regardless of + * the type of PHY on the device (copper, fiber, etc.) + */ + case MAC_PROP_DUPLEX: + case MAC_PROP_SPEED: + case MAC_PROP_STATUS: + case MAC_PROP_ADV_100FDX_CAP: + case MAC_PROP_ADV_1000FDX_CAP: + case MAC_PROP_ADV_10GFDX_CAP: + ret = ENOTSUP; + break; + + /* + * These EN properties are used to control the advertised speeds of the + * device. For this example, we assume that this device does not have a + * copper phy, at which point auto-negotiation and the speeds in + * question cannot be changed. These are called out separately as they + * should be controllable for copper based devices or it may need to be + * conditional depending on the type of phy present. + */ + case MAC_PROP_EN_100FDX_CAP: + case MAC_PROP_EN_1000FDX_CAP: + case MAC_PROP_EN_10GFDX_CAP: + case MAC_PROP_AUTONEG: + ret = ENOTSUP; + break; + + case MAC_PROP_MTU: + if (pr_valsize < sizeof (uint32_t)) { + ret = EOVERFLOW; + break; + } + bcopy(&new_mtu, pr_val, sizeof (uint32_t)); + + if (new_mtu < ep->ep_min_mtu || + new_mtu > ep->ep_max_mtu) { + ret = EINVAL; + break; + } + + /* + * We first ask MAC to update the MTU before we do anything. + * This may fail. It returns zero on success. The + * example_update_mtu function does device specific updates to + * ensure that the MTU on the device is updated and any internal + * data structures are up to date. + */ + ret = mac_maxdsu_update(&ep->ep_mac_hdl, new_mtu); + if (ret == 0) { + example_update_mtu(ep, new_mtu); + } + break; + + /* + * Devices may have their own private properties. If they do, they + * should not return ENOTSUP, but instead see if it's a property they + * recognize and handle it similar to those above. If it doesn't + * recognize the name, then it should return ENOTSUP. + */ + case MAC_PROP_PRIVATE: + ret = ENOTSUP; + break; + + default: + ret = ENOTSUP; + break; + } + mutex_exit(&ep->ep_lock); + + return (ret); +} +.Ed +.Sh ERRORS +The device driver may return one of the following errors. While this list +is not intended to be exhaustive, it is recommended to use one of these +if possible. +.Bl -tag -width Er +.It Er EINVAL +The contents of +.Fa pr_val +are outside the valid range for the property. +.It Er ENOTSUP +This error should be used whenever an unknown or unsupported property is +encountered. It should also be used when the property is not writable. +.It Er EOVERFLOW +This error should be used when +.Fa pr_valsize +is smaller than the required size for a given value. +.It Er EBUSY +This error should be used when a property can't be set because the +device has started. Note that device driver writers are encouraged to design +device drivers such that this error is not possible. +.It Er ECANCELLED +The device is in a state that does not allow it to handle data; for +example, it's suspended. +.El +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr strcmp 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9e/mc_start.9e b/usr/src/man/man9e/mc_start.9e new file mode 100644 index 0000000000..db8a47339c --- /dev/null +++ b/usr/src/man/man9e/mc_start.9e @@ -0,0 +1,86 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MC_START 9E +.Os +.Sh NAME +.Nm mc_start , +.Nm mc_stop +.Nd start and stop device entry points +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo prefix_m_start +.Fa "void *driver" +.Fc +.Ft void +.Fo prefix_m_stop +.Fa "void *driver" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Ds +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.El +.Sh DESCRIPTION +The +.Fn mc_start +entry point for a driver indicates that it should initialize the chip +to be ready to send or receive data. This entry point is guaranteed to +be called before any entry points that are expected to be able to send +and receive data. During this entry point, most devices will allocate +DMA resources, enable the link, and finish performing any necessary +device programming. +.Pp +The +.Fn mc_stop +entry point for a driver indicates that it should tear down any +allocated resources for the driver and, after the function returns, it is +not expected to perform any additional I/O. +.Pp +The driver has access to its private data in the +.Fa driver +argument to either function, which it should cast to the +appropriate structure. The system guarantees that only one of the +.Fn mc_start +and +.Fn mc_stop +functions will be called at any given time for a given instance. +Similarly, these should not be called at the same time as a device's +.Xr attach 9E +or +.Xr detach 9E +routine. However, the driver may have other ongoing routines that it +needs to protect against. The device driver should always apply the +appropriate locking techniques needed to ensure that access to the data +in its soft state is protected. +.Sh RETURN VALUES +Upon successful completion, device drivers should return +.Sy 0 +for the +.Fn mc_start +entry point. Otherwise, they should return a non-zero positive error +number to indicate the error that occurred. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9e/mc_tx.9e b/usr/src/man/man9e/mc_tx.9e new file mode 100644 index 0000000000..d50ad25fee --- /dev/null +++ b/usr/src/man/man9e/mc_tx.9e @@ -0,0 +1,169 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 02, 2016 +.Dt MC_TX 9E +.Os +.Sh NAME +.Nm mc_tx +.Nd transmit a message block chain +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft "mblk_t *" +.Fo prefix_m_tx +.Fa "void *driver" +.Fa "mblk_t *mp_chain" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa mp_chain +A series of +.Xr mblk 9S +structures that may have multiple independent packets linked together on +their +.Sy b_next +member. +.El +.Sh DESCRIPTION +The +.Fn mc_tx +entry point is called when the system requires a device driver to +transmit data. The device driver will receive a chain of messge blocks. +The +.Fa mp_chain +argument represents the first frame. The frame may be spread out +across one or more +.Xr mblk 9S +structures that are linked together by the +.Sy b_cont +member. There may be multiple frames, linked together by the +.Sy b_next +pointer of the +.Xr mblk 9S . +.Pp +For each frame, the driver should allocate the required resources and +prepare it for being transmitted on the wire. The driver may opt to copy +those resources to a DMA buffer or it may bind them. For more +information on these options, see the +.Sx MBLKS AND DMA +section of +.Xr mac 9E . +.Pp +As it processes each frame in the chain, if the device driver has +advertised either of the +.Sy MAC_CAPAB_HCKSUM +or +.Sy MAC_CAPAB_LSO +flags, it must check whether either apply for the given frame using the +.Xr mac_hcksum_get 9F +and +.Xr mac_lso_get 9F +functions respectively. If either is enabled for the given frame, the +hardware must arrange for that to be taken care of. +.Pp +For each frame that the device driver processes it is responsible for +doing one of three things with it: +.Bl -enum +.It +Transmit the frame. +.It +Drop the frame by calling +.Xr freemsg 9F +on the individual mblk_t. +.It +Return the frames to indicate that resources are not available. +.El +.Pp +The device driver is in charge of the memory associated with +.Fa mp_chain . +If the device driver does not return the message blocks to the GLDv3, +then it must call +.Xr freemsg 9F +on the frames. If it does not, the memory associated with them +will be leaked. When a frame is being transmitted, if the device driver +performed DMA binding, it should not free the message block until after +it is guaranteed that the frame has been transmitted. If the message +block was copied to a DMA buffer, then it is allowed to call +.Xr freemsg 9F +at any point. +.Pp +In general, the device driver should not drop frames without +transmitting them unless it has no other choice. Times when this happens +may include the device driver being in a state where it can't transmit, +an error was found in the frame while trying to establish the checksum +or LSO state, or some other kind of error that represents an issue with +the passed frame. +.Pp +The device driver should not free the chain when it does not have enough +resources. For example, if entries in a device's descriptor ring fill +up, then it should not drop those frames and instead should return all +of the frames that were not transmitted. This indicates to the stack +that the device is full and that flow control should be asserted. Back +pressure will be applied to the rest of the stack, allowing most systems +to behave better. +.Pp +Once a device driver has returned unprocessed frames from its +.Fn mc_tx +entry point, then the device driver will not receive any additional +calls to its +.Fn mc_tx +entry point until it calls +.Xr mac_tx_update 9F +to indicate that resources are available again. Note that because it is +the device driver that is calling this function to indicate resources +are available, it is very important that it only return frames in cases +where the device driver itself will be notified that resources are +available again. For example, when it receives an interrupt indicating +that the data that it transmitted has been completed so it can use +entries in its descriptor ring or other data structures again. +.Pp +The device driver can obtain access to its soft state through the +.Fa driver +member. It should cast it to the appropriate structure. The device +driver should employ any necessary locking to access the transmit +related data structures. Note that the device driver should expect that +it may have its transmit endpoints called into from other threads while +it's servicing device interrupts related to them. +.Sh CONTEXT +The +.Fn mc_tx +entry point may be called from +.Sy kernel +or +.Sy interrupt +context. +.Sh RETURN VALUES +Upon successful completion, the device driver should return +.Dv NULL . +Otherwise, it should return all unprocessed message blocks and ensure +that it calls +.Xr mac_tx_update 9F +some time in the future. +.Sh SEE ALSO +.Xr mac 9E , +.Xr freemsg 9F , +.Xr mac_lso_get 9F , +.Xr mac_register 9F , +.Xr mac_tx_update 9F , +.Xr mac_register 9S , +.Xr mblk 9S diff --git a/usr/src/man/man9e/mc_unicst.9e b/usr/src/man/man9e/mc_unicst.9e new file mode 100644 index 0000000000..c9df221f71 --- /dev/null +++ b/usr/src/man/man9e/mc_unicst.9e @@ -0,0 +1,105 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MC_UNICST 9E +.Os +.Sh NAME +.Nm mc_unicst +.Nd set device unicast address +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo prefix_m_unicst +.Fa "void *driver" +.Fa "const uint8_t *mac" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa driver +A pointer to the driver's private data that was passed in via the +.Sy m_pdata +member of the +.Xr mac_register 9S +structure to the +.Xr mac_register 9F +function. +.It Fa mac +A pointer to an array of bytes that contains the new unicast address of +the device. It is guaranteed to be at least a number of bytes long equal +to the length of the MAC plugin's address length. For Ethernet devices that +length is six bytes, +.Sy ETHERADDRL . +.El +.Sh DESCRIPTION +The +.Fn mc_unicst +entry point is used by the GLDv3 to indicate that the device driver +should update the primary MAC address of the device. In the basic mode +of operation, this entry point is required and the device has a single +primary MAC address. If multiple MAC addresses are required, the +device will be placed into promiscuous mode. This call should overwrite +the existing MAC address that is programmed into the device. +.Pp +As noted in the +.Sx PARAMETERS +section, the +.Fa mac +array is guaranteed to be at least as many bytes as is required to +specify an address; however, it should be assumed to be no longer than +that value. +.Pp +The device driver can optionally assert that the address is in the +valid form for a unicast address and then program the device. The device +driver can access its device soft state by casting the +.Fa device +pointer to the appropriate structure. As this may be called while other +operations are ongoing, the device driver should employ the appropriate +locking while updating the data. +.Pp +It is recommended that device drivers always maintain a copy of the +current unicast address in its soft state so that way it can recover +from various device reset and errors or handle requests to suspend and +resume the device that may result in device registers being cleared. +.Pp +Some devices support multiple MAC address filters. The +.Fn mc_unicst +entry point only supports a single MAC address. In this case, devices +should only use a single MAC address and replace that MAC address. +Support for using more than a single MAC address filter will be provided +by future interfaces. +.Sh RETURN VALUES +Upon successful completion, the device driver should have updated its +unicast filter and return +.Sy 0 . +Otherwise, the MAC address should remain unchanged and the driver should +return an appropriate error number. +.Sh ERRORS +The device driver may return one of the following errors. While this list +is not intended to be exhaustive, it is recommended to use one of these +if possible. +.Bl -tag -width Er +.It Er EINVAL +The address +.Fa mac +is not a valid unicast address. +.It Er EIO +The driver encountered a device or transport error while trying to +update the device's state. +.El +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile index 81d5754873..b72191c28d 100644 --- a/usr/src/man/man9f/Makefile +++ b/usr/src/man/man9f/Makefile @@ -321,6 +321,16 @@ MANFILES= ASSERT.9f \ ldi_strategy.9f \ linkb.9f \ list_create.9f \ + mac_alloc.9f \ + mac_hcksum_get.9f \ + mac_init_ops.9f \ + mac_link_update.9f \ + mac_lso_get.9f \ + mac_maxsdu_update.9f \ + mac_prop_info.9f \ + mac_register.9f \ + mac_rx.9f \ + mac_tx_update.9f \ makecom.9f \ makedevice.9f \ max.9f \ @@ -956,6 +966,17 @@ MANLINKS= SIZEOF_PTR.9f \ list_remove_head.9f \ list_remove_tail.9f \ list_tail.9f \ + mac_free.9f \ + mac_hcksum_set.9f \ + mac_fini_ops.9f \ + mac_prop_info_set_default_link_flowctrl.9f \ + mac_prop_info_set_default_str.9f \ + mac_prop_info_set_default_uint8.9f \ + mac_prop_info_set_default_uint32.9f \ + mac_prop_info_set_default_uint64.9f \ + mac_prop_info_set_perm.9f \ + mac_prop_info_set_range_uint32.9f \ + mac_unregister.9f \ makecom_g0.9f \ makecom_g0_s.9f \ makecom_g1.9f \ @@ -1750,6 +1771,18 @@ list_remove_head.9f := LINKSRC = list_create.9f list_remove_tail.9f := LINKSRC = list_create.9f list_tail.9f := LINKSRC = list_create.9f +mac_free.9f := LINKSRC = mac_alloc.9f +mac_hcksum_set.9f := LINKSRC = mac_hcksum_get.9f +mac_fini_ops.9f := LINKSRC = mac_init_ops.9f +mac_prop_info_set_default_link_flowctrl.9f := LINKSRC = mac_prop_info.9f +mac_prop_info_set_default_str.9f := LINKSRC = mac_prop_info.9f +mac_prop_info_set_default_uint8.9f := LINKSRC = mac_prop_info.9f +mac_prop_info_set_default_uint32.9f := LINKSRC = mac_prop_info.9f +mac_prop_info_set_default_uint64.9f := LINKSRC = mac_prop_info.9f +mac_prop_info_set_perm.9f := LINKSRC = mac_prop_info.9f +mac_prop_info_set_range_uint32.9f := LINKSRC = mac_prop_info.9f +mac_unregister.9f := LINKSRC = mac_register.9f + makecom_g0.9f := LINKSRC = makecom.9f makecom_g0_s.9f := LINKSRC = makecom.9f makecom_g1.9f := LINKSRC = makecom.9f diff --git a/usr/src/man/man9f/mac_alloc.9f b/usr/src/man/man9f/mac_alloc.9f new file mode 100644 index 0000000000..c3c6892b19 --- /dev/null +++ b/usr/src/man/man9f/mac_alloc.9f @@ -0,0 +1,98 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MAC_ALLOC 9F +.Os +.Sh NAME +.Nm mac_alloc , +.Nm mac_free +.Nd allocate and free mac registration structures +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft "mac_register_t *" +.Fo mac_alloc +.Fa "uint_t mac_version" +.Fc +.Ft void +.Fo mac_free +.Fa "mac_register_t *mregp" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa mac_version +An integer corresponding to the version of the MAC interface that the +device driver was built against. +.It Fa mregp +A pointer to an allocated mac_register_t structure that was obtained +from calling the +.Fn mac_alloc +function. +.El +.Sh DESCRIPTION +The +.Fn mac_alloc +and +.Fn mac_free +routines are used to allocate and free the structures used to register a +device driver with +.Xr mac 9E . +The device driver should call +.Fn mac_alloc +with the value of +.Dv MAC_VERSION +to indicate the current version of the MAC framework that it supports. +The device driver will be returned an instance of a +.Xr mac_register 9S +structure which it can then use to call +.Xr mac_register 9F . +For more information on the order of events, see the +.Sx Initializing MAC Support +section of +.Xr mac 9E . +.Pp +When the driver is done with the +.Xr mac_register 9S +structure, it must call the +.Xr mac_free +function to release any associated memory. +.Sh CONTEXT +The +.Fn mac_alloc +and +.Fn mac_free +routines are generally called from the context of a device driver's +.Xr attach 9E +entry point; however, they may be called from both +.Sy user +and +.Sy kernel +context. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mac_register +function will return a pointer to an allocated +.Sy mac_register_t +structure that can be filled in by the driver. Otherwise, +.Dv NULL +is returned to indicate that the structure could not be allocated. The +most common cause for this is that the value of +.Fa mac_version +is not supported by the kernel. +.Sh SEE ALSO +.Xr attach 9E , +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mac_register 9S diff --git a/usr/src/man/man9f/mac_hcksum_get.9f b/usr/src/man/man9f/mac_hcksum_get.9f new file mode 100644 index 0000000000..b186890fd1 --- /dev/null +++ b/usr/src/man/man9f/mac_hcksum_get.9f @@ -0,0 +1,201 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 01, 2016 +.Dt MAC_HCKSUM_GET 9F +.Os +.Sh NAME +.Nm mac_hcksum_get , +.Nm mac_hcksum_set +.Nd get and set checksum information on message blocks +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo mac_hcksum_get +.Fa "mblk_t *mp" +.Fa "uint32_t *start" +.Fa "uint32_t *stuff" +.Fa "uint32_t *end" +.Fa "uint32_t *value" +.Fa "uint32_t *flags" +.Fc +.Ft void +.Fo mac_hcksum_set +.Fa "mblk_t *mp" +.Fa "uint32_t start" +.Fa "uint32_t stuff" +.Fa "uint32_t end" +.Fa "uint32_t value" +.Fa "uint32_t flags" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa mp +A pointer to a +.Xr mblk 9S +structure that contains a frame. +.It Fa start +The value or a pointer to it that contains the offset from the L3 +header, generally IP, of the first byte that's covered by the checksum. +.It Fa stuff +The value or a pointer to it that contains the offset from the L3 header +of where the L4 checksum is. For example, if using IPv4 and TCP, this +would contain the offset from the start of the IPv4 header to the first +byte of the TCP checksum. +.It Fa end +The value or a pointer to it that contains the offset from the L3 +header, generally IP, of the last byte that's covered by the checksum. +.It Fa value +The value or a pointer to it that contains the actual value of the +checksum. +.It Fa flags +A series of one or more flags that have bitwise inclusive ORed together. +The set of flags have different meanings depending on whether +.Fa mp +is being transmitted or received. +.El +.Sh DESCRIPTION +The +.Fn mac_hcksum_get +and +.Fn mac_hcksum_set +functions are provided to device drivers to get and set checksum related +information. When a device driver indicates that it supports the +.Sy MAC_CAPAB_HCKSUM +capability as part of its +.Xr mc_getcapab 9E +entry point, then it is responsible for calling these functions +appropriately during the transmit and receive paths. +.Pp +While both functions operate on an +.Sy mblk_t , +this function should only be called on the first +.Sy mblk_t +that begins a given individual frame in a chain. In other words, it only +works on entries where it is the first of many possible entries linked +together by the +.Sy b_cont +member. The first +.Sy mblk_t +received from any +.Xr mac 9E +API or pointed to by a +.Sy b_next +pointer should be used. +.Ss Receiving Data +When a device driver is receiving data, it is its responsibility to +.Em set +checksum information when it has indicated that it supports the +.Sy MAC_CAPAB_HCKSUM +capability. Device drivers will call the +.Fn mac_hcksum_set +function to indicate what checksum information has occurred. +.Pp +The proper values to set depend on the flags passed in. The following +flags are supported when receiving data, note that they may have +different meanings from when transmitting data. The driver should set +the +.Fa flags +argument to the bitwise inclusive OR of the following values: +.Bl -tag -width Sy +.It Sy HCK_IPV4_HDRCKSUM_OK +This flag indicates that the hardware has verified the IPv4 header is +correct and that the networking stack does not need to verify it. +.It Sy HCK_PARTIALCKSUM +This flag indicates that the hardware has computed a partial checksum. +When this flag is set, the driver is responsible for passing in the +partial checksum in the +.Fa value +argument as well as the start and ending bytes of the checksum in the +.Fa start +and +.Fa end +arguments. +.It Sy HCK_FULLCKSUM +This flag indicates that the hardware has calculated the full L4 header +checksum; however, it wants the system to verify it. The checksum should +be passed in the +.Fa value +argument. +.It Sy HCK_FULLCKSUM_OK +This flag indicates that the hardware has calculated the full L4 header +checksum and verified that it is correct. The networking stack does not +need to verify it. +.El +.Pp +The +.Sy HCK_PARTIALCKSUM , +.Sy HCK_FULLCKSUM , +and +.Sy HCK_FULLCKSUM_OK +flags are all mutually exclusive. A device driver should only set one of +the three flags. +.Pp +If one of the arguments is not required based on the specified value of +.Fa flags , +then the device driver should set any remaining arguments to +.Sy 0 . +.Ss Transmitting Data +When a device driver is transmitting data and it has advertised that it +supports the +.Sy MAC_CAPAB_HCKSUM +capability, then it must call the +.Fn mac_hcksum_get +function to determine what hardware checksumming options are required to +be performed by the hardware. While the device driver may need the other +fields, it must check the +.Fa flags +argument to determine what it is being requested to do. The following +values may be set in +.Fa flags : +.Bl -tag -width Sy +.It Sy HCK_IPV4_HDRCKSUM +The device driver must compute the IPv4 header checksum. No other fields +have been filled in. +.It Sy HCK_PARTIALCKSUM +The device driver needs to compute the partial ones' complement of the +checksum. The system has filled in the +.Fa start , +.Fa stuff , +and +.Fa end +arguments to assist the device driver. +.It Sy HCK_FULLCKSUM +The device driver should compute the full L4 checksum. No other fields +have been filled in for the device driver. +.El +.Pp +The flags that the device driver will get will depend on what the device +driver has advertised that it supports in response to the +.Xr mc_getcapab 9E +query for the +.Sy MAC_CAPAB_HCKSUM +capability. +.Pp +The +.Sy HCK_PARTIALCKSUM +and +.Sy HCK_FULLCKSUM +flags are mutually exclusive. +.Sh CONTEXT +The +.Fn mac_hcksum_get +and +.Fn mac_hcksum_set +functions may be called from any context. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_getcapab 9E , +.Xr mblk 9S diff --git a/usr/src/man/man9f/mac_init_ops.9f b/usr/src/man/man9f/mac_init_ops.9f new file mode 100644 index 0000000000..a744cddbf8 --- /dev/null +++ b/usr/src/man/man9f/mac_init_ops.9f @@ -0,0 +1,195 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MAC_INIT_OPS 9F +.Os +.Sh NAME +.Nm mac_init_ops , +.Nm mac_fini_ops +.Nd initialize and finalize driver support for the MAC framework +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo mac_init_ops +.Fa "struct dev_ops *ops" +.Fa "const char *name" +.Fc +.Ft void +.Fo mac_fini_ops +.Fa "struct dev_ops *ops" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Ds +.It Fa ops +A pointer to the driver's +.Xr dev_ops 9S +structure. +.It Fa name +A pointer to a null-terminated string of ASCII characters that contains +the name of the driver. +.El +.Sh DESCRIPTION +The +.Fn mac_init_ops +and +.Fn mac_fini_ops +functions are used to initialize and finalize support for a device +driver that implements the +.Xr mac 9E +networking device framework. +.Pp +The +.Fn mac_init_ops +function should be called during the driver's +.Xr _init 9E +entry point. As described in more detail in the +.Sx Initializing MAC Support +section of +.Xr mac 9E , +this must be called before the driver calls +.Xr mod_install 9F . +If this is not done, then the call to +.Xr mac_register 9F +will fail. +.Pp +When in the driver's +.Xr _fini 9E +entry point, after the call to +.Xr mod_remove 9F +has succeeded, then the driver must call the +.Fn mac_fini_ops +function to finalize support and finish releasing any resources. If the +call to +.Xr mod_remove 9F +fails, then the device driver should not call +.Fn mac_fini_ops +and should fail the call to +.Xr _fini 9F . +.Pp +In addition, if the call to +.Xr mod_install 9F +in the driver's +.Xr _init 9E +entry point fails, then the driver should also call +.Xr mac_fini_ops 9F . +See the example below for how this should be structured. +.Sh CONTEXT +The +.Fn mac_init_ops +function should only ever be called from the context of a driver's +.Xr _init 9E +entry point. +.Pp +The +.Fn mac_fini_ops +function should only ever be called from the context of a driver's +.Xr _init 9E +or +.Xr _fini 9E +entry point. +.Sh RETURN VALUES +The +.Fn mac_init_ops +and +.Fn mac_fini_ops +functions will always succeed. They do not have any kind of return +value. +.Sh EXAMPLES +The following example shows how a driver would call +.Xr mac_init_ops 9F +and +.Xr mac_fini_ops 9F +correctly in the +.Xr _init 9E +and +.Xr _fini 9E +entry points of a driver. +.Bd -literal +#include <sys/modctl.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +#include <sys/mac_provider.h> + +/* + * When using this, replace mydrv with the name of the actual device + * driver. In addition, the mydrv_ prefix that is used should be + * replaced with the name of the device driver + */ +#define MYDRV_NAME "mydrv" + +/* + * The following dev_ops structure would need to be filled in by a + * proper device driver. + */ +static struct dev_ops mydrv_dev_ops; + +static struct modldrv mydrv_modldrv = { + &mod_driverops, + MYDRV_NAME, + &mydrv_dev_ops +}; + +static struct modlinkage mydrv_modlinkage = { + MODREV_1, + &mydrv_modldrv, + NULL +}; + +int +_init(void) +{ + int ret; + + /* Perform other needed initialization */ + + mac_init_ops(&mydrv_devops, MYDRV_NAME); + + ret = mod_install(&mydrv_modlinkage); + if (ret != DDI_SUCCESS) { + mac_fini_ops(&mydrv_devops); + /* Perform other needed finalization */ + } + + return (ret); +} + +int +_info(struct modinfo *modinfop) +{ + return (mod_info(&mydrv_modlinkage, modinfo)); +} + +int +_fini(void) +{ + int ret; + + ret = mod_remove(&mydrv_modlinkage); + if (ret == DDI_SUCCESS) { + mac_fini_ops(&mydrv_devops); + /* Perform other needed finalization */ + } + + return (ret); +} +.Ed +.Sh SEE ALSO +.Xr _fini 9E , +.Xr _init 9E , +.Xr mac 9E , +.Xr mod_install 9F , +.Xr mod_remove 9F , +.Xr dev_ops 9S diff --git a/usr/src/man/man9f/mac_link_update.9f b/usr/src/man/man9f/mac_link_update.9f new file mode 100644 index 0000000000..a7a460dab0 --- /dev/null +++ b/usr/src/man/man9f/mac_link_update.9f @@ -0,0 +1,74 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MAC_LINK_UPDATE 9F +.Os +.Sh NAME +.Nm mac_link_update +.Nd inform the MAC layer about a link state change +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo mac_link_update +.Fa "mac_handle_t mh" +.Fa "link_state_t link" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa mh +The MAC handle obtained from a call to +.Xr mac_register 9F . +.It Fa link +The current state of the link. For valid link states see the discussion +of +.Sy MAC_PROP_STATUS +in the +.Sx PROPERTIES +section of +.Xr mac 9E . +.El +.Sh DESCRIPTION +The +.Fn mac_link_update +function is used by device drivers to inform the MAC layer that the +state of a link has changed. As discussed in the +.Sx Link Updates +section of +.Xr mac 9E , +the driver should call this whenever it detects that the state of the +link has changed. If the state has not changed, then the driver should +not call this function. In addition, if the device driver is powering +off the link or is transitioning to a state where it can no longer +determine the link status, then it should make sure to call this +function with the value of +.Fa link +set to +.Sy LINK_STATE_UNKNOWN . +.Pp +Device drivers should ensure that they're not holding any of their +specific locks when calling this function. +.Sh CONTEXT +The +.Fn mac_link_update +function may be called from +.Sy user , +.Sy kernel , +or +.Sy interrupt +context. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F diff --git a/usr/src/man/man9f/mac_lso_get.9f b/usr/src/man/man9f/mac_lso_get.9f new file mode 100644 index 0000000000..b8a28c770c --- /dev/null +++ b/usr/src/man/man9f/mac_lso_get.9f @@ -0,0 +1,94 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 02, 2016 +.Dt MAC_LSO_GET 9F +.Os +.Sh NAME +.Nm mac_lso_get +.Nd get LSO information on message blocks +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo mac_lso_get +.Fa "mblk_t *mp" +.Fa "uint32_t *mss" +.Fa "uint32_t *flags" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa mp +A pointer to a +.Xr mblk 9S +structure that contains an outgoing frame. +.It Fa mss +A pointer to a value that will be filled in with the maximum segment +size (MSS). +.It Fa flags +A pointer to a value that will be filled in with various flags that +indicate the behavior to perform. +.El +.Sh DESCRIPTION +The +.Fn mac_lso_get +function is used by device drivers that have indicated that they support +the +.Sy MAC_CAPAB_LSO +capability to determine whether large send offload (also known as large +segmentation offload or LSO) is required for this frame or not. If so, +the driver should take the appropriate actions to program the hardware +to perform LSO. +.Pp +The +.Fn mac_lso_get +function should only be called on the first +.Sy mblk_t +that begins a given individual frame in a chain. In other words, it only +works on entries where it is the first of many possible entries linked +together by the +.Sy b_cont +member. The first +.Sy mblk_t +received from any +.Xr mac 9E +API or pointed to by a +.Sy b_next +pointer should be used. +.Pp +A device driver should first look at the +.Fa flags +argument to determine what to do. +.Fa flags +may be a bitwise inclusive OR of the following: +.Bl -tag -width Sy +.It Sy HW_LSO +This flag indicates that hardware needs to perform segmentation +offload. The maximum segment size that the driver should use is +available through the +.Fa mss +argument. +.El +.Sh CONTEXT +The +.Fn mac_lso_get +function may be called from +.Sy user , +.Sy kernel , +or +.Sy interrupt +context. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mblk 9S diff --git a/usr/src/man/man9f/mac_maxsdu_update.9f b/usr/src/man/man9f/mac_maxsdu_update.9f new file mode 100644 index 0000000000..297d30ef41 --- /dev/null +++ b/usr/src/man/man9f/mac_maxsdu_update.9f @@ -0,0 +1,87 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 02, 2016 +.Dt MAC_MAXSDU_UPDATE 9F +.Os +.Sh NAME +.Nm mac_maxsdu_update +.Nd indicate that a device's maximum data size has changed +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo mac_maxsdu_update +.Fa "mac_handle_t mh" +.Fa "uint_t sdu" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa mh +The MAC handle obtained from a call to +.Xr mac_register 9F . +.It Fa sdu +An integer representing the maximum size data payload. +.El +.Sh DESCRIPTION +The +.Fn mac_maxsdu_update +function is used to inform the MAC layer that the device represented by +the handle +.Fa mh +has changed the largest size frame that it can transmit, also known as +its Send Data Unit (SDU). This should be called when the device's MTU +has been requested to be changed when a driver's +.Xr mac_setprop 9E +entry point has been called with the property +.Sy MAC_PROP_MTU +or some other device-related event occurring. +.Pp +The +.Fa sdu +represents the size of the largest payload ignoring the size of its own +headers or any margin. For example, for an Ethernet-based device, this +size should not include the Ethernet header or any VLAN tags. +.Pp +Through VNICs and other virtual data links, many different devices may +be using a single physical device and have their own MTUs. The system +takes care of those concerns and will not ask a device driver to update +the MTU without verifying this. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mac_maxsdu_update +function returns +.Sy 0 . +Otherwise, a non-negative error is returned. +.Sh EXAMPLES +For an example of how a device driver should use the +.Fn mac_maxsdu_update +function, see the +.Sx EXAMPLES +section in +.Xr mac_setprop 9E . +.Sh ERRORS +The +.Fn max_maxsdu_update +function may fail if: +.Bl -tag -width Er +.It Er EINVAL +The specified +.Fa sdu +is lower than the minimum SDU of the device. +.El +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_setprop 9E , +.Xr mac_register 9F diff --git a/usr/src/man/man9f/mac_prop_info.9f b/usr/src/man/man9f/mac_prop_info.9f new file mode 100644 index 0000000000..4e3ea44477 --- /dev/null +++ b/usr/src/man/man9f/mac_prop_info.9f @@ -0,0 +1,210 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MAC_PROP_INFO 9F +.Os +.Sh NAME +.Nm mac_prop_info , +.Nm mac_prop_info_set_default_link_flowctrl , +.Nm mac_prop_info_set_default_str , +.Nm mac_prop_info_set_default_uint8 , +.Nm mac_prop_info_set_default_uint32 , +.Nm mac_prop_info_set_default_uint64 , +.Nm mac_prop_info_set_perm , +.Nm mac_prop_info_set_range_uint32 +.Nd mac property information functions +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo mac_prop_info_set_default_link_flowctrl +.Fa "mac_prop_info_handle_t hdl" +.Fa "link_flowctrl_t fctl" +.Fc +.Ft void +.Fo mac_prop_info_set_default_str +.Fa "mac_prop_info_handle_t hdl" +.Fa "const char *str" +.Fc +.Ft void +.Fo mac_prop_info_set_default_uint8 +.Fa "mac_prop_info_handle_t hdl" +.Fa "uint8_t u8" +.Fc +.Ft void +.Fo mac_prop_info_set_default_uint16 +.Fa "mac_prop_info_handle_t hdl" +.Fa "uint16_t u16" +.Fc +.Ft void +.Fo mac_prop_info_set_default_uint32 +.Fa "mac_prop_info_handle_t hdl" +.Fa "uint32_t u32" +.Fc +.Ft void +.Fo mac_prop_info_set_perm +.Fa "mac_prop_info_handle_t hdl" +.Fa "uint8_t perm" +.Fc +.Ft void +.Fo mac_prop_info_set_range_uint32 +.Fa "mac_prop_info_handle_t hdl" +.Fa "uint32_t low" +.Fa "uint32_t high" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Ds +.It Ft hdl +A pointer to the MAC property information handle. +.It Ft fctl +A valid link flow control entry. Valid values are documented in the +.Sy MAC_PROP_FLOWCTRL +property description in the +.Sx PROPERTIES +section of +.Xr mac 9E . +.It Ft str +A null-terminated ASCII character string that describes that contains a +value of a property. +.It Ft u8 +An 8-bit unsigned value. +.It Ft u16 +An 16-bit unsigned value. +.It Ft u32 +An 32-bit unsigned value. +.It Ft perm +An 8-bit unsigned value which is the bitwise inclusive OR of the +following values: +.Bl -tag -width Ds +.It Sy MAC_PROP_PERM_READ +This flag indicates that a property is +.Sy readable . +.It Sy MAC_PROP_PERM_WRITE +This flag indicates that a property is +.Sy writable . +.It Sy MAC_PROP_PERM_RW +This flag indicates that a property is both +.Sy readable +and +.Sy writeable . +This is equivalent to specifying both +.Sy MAC_PROP_PERM_READ +and +.Sy MAC_PROP_PERM_WRITE . +.El +.It Ft low +A 32-bit unsigned value that represents the lowest possible value of an +integer property, generally inclusive. +.It Ft high +A 32-bit unsigned value that represents the highest possible value an +integer property, generally inclusive. +.El +.Sh DESCRIPTION +The +.Sy mac_prop_info +family of functions are used to fill in metadata about a given property +as part of a driver's +.Xr mc_propinfo 9E +entry point. These functions can be used to fill in information about +the default value that the device assigns to a property and the +permissions that a privileged user has to update the property. +.Pp +The +.Fn mac_prop_info_set_perm +function is used to set the permissions of a property. These permissions +indicate whether or not the property can be read or modified from the +device driver's perspective. The permissions for a given property should +generally not change for a given device and they do not need to take +into account user privileges. For the most case, properties will only +take one of two values: +.Sy MAC_PROP_PERM_READ +or +.Sy MAC_PROP_PERM_RW . +Usually it does not make sense for a property to just have +.Sy MAC_PROP_PERM_WRITE . +.Pp +Subsequent calls to the +.Fn mac_prop_info_set_perm +function will override the values stored in previous calls. +.Pp +The +.Fn mac_prop_info_set_range_uint32 +function is used to indicate a range of possible integer values that a +device may take. This range is generally inclusive, meaning the property +may be set to any value in the range of +.Fa low +to +.Fa high . +Each time the +.Fn mac_prop_info_set_range_uint32 +function is called, a new property range is added, allowing for multiple +disjoint ranges to be specified for a given property. +.Pp +The remaining functions, +.Fn mac_prop_info_set_default_link_flowctrl , +.Fn mac_prop_info_set_default_str , +.Fn mac_prop_info_set_uint8 , +.Fn mac_prop_info_set_uint16 , +.Fn mac_prop_info_set_uint32 , +and +.Fn mac_prop_info_set_range_uint32 +update the default value of a given property. The default value is the +initial value that the property takes after the device driver has called +.Xr mac_register 9F . +If these functions are called multiple times, then the default value +will be replaced with each call. +.Pp +The different functions each support a different type of default value +and some are used for specific properties. The +.Fn mac_prop_info_set_default_link_flowctrl +function works with properties that describe flow control properties. +The various values of a +.Ft link_flowctrl_t +are documented in +.Xr mac 9E . +.Pp +The +.Fn mac_prop_info_set_default_str +function sets the default value for properties that use strings. The +device driver should ensure that it uses alphanumeric ASCII characters +only in the string to guarantee portability. +.Pp +The +.Fn mac_prop_info_set_default_uint8 , +.Fn mac_prop_info_set_default_uint16 , +and +.Fn mac_prop_info_set_default_uint32 +functions set the default value for values whose properties are 8-, 16-, +and 32-bit unsigned values respectively. +.Sh CONTEXT +These functions are generally called on a handle passed into the +.Xr mc_propinfo 9E +entry point, though they function in both +.Sy user +and +.Sy kernel +context. +.Sh RETURN VALUES +All of the functions documented here do not return a value. It is not +the driver's responsibility to ensure that there is sufficient space for +permissions, ranges, or default values in the +.Ft mac_prop_info_handle_t +structures: the surrounding driver framework will transparently take +care of that and ensure that errors are correctly propagated. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mc_getprop 9E , +.Xr mc_propinfo 9E , +.Xr mc_setprop 9E diff --git a/usr/src/man/man9f/mac_register.9f b/usr/src/man/man9f/mac_register.9f new file mode 100644 index 0000000000..05fe8fc60b --- /dev/null +++ b/usr/src/man/man9f/mac_register.9f @@ -0,0 +1,267 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 31, 2016 +.Dt MAC_REGISTER 9F +.Os +.Sh NAME +.Nm mac_register , +.Nm mac_unregister +.Nd register and unregister a device driver from the MAC framework +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft int +.Fo mac_register +.Fa "mac_register_t *mregp" +.Fa "mac_handle_t *mhp" +.Fc +.Ft int +.Fo mac_unregister +.Fa "mac_handle_t mh" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa mregp +A pointer to a +.Xr mac_register 9S +structure allocated by calling +.Xr mac_alloc 9F +and filled in by the device driver. +.It Fa mhp +A pointer to a driver-backed handle to the MAC framework. +.It Fa mh +The driver-backed handle to the MAC framework. +.El +.Sh DESCRIPTION +The +.Fn mac_register +function is used to register an instance of a device driver with the +.Xr mac 9E +framework. Upon successfully calling the +.Fn mac_register +function, the device will start having its +.Xr mac_callbacks 9S +entry points called. The device driver should call this function +during it's +.Xr attach 9E +entry point after the device has been configured and is set up. For a +more detailed explanation of the exact steps that the device driver +should take and where in the sequence of a driver's +.Xr attach 9E +entry point this function should be called, see the +.Sx Registering with MAC +section of +.Xr mac 9E . +.Pp +The driver should provide a pointer to a +.Ft mac_handle_t +structure as the second argument to the +.Fn mac_register +function. This handle will be used when the device driver needs to +interact with the framework in various ways throughout its life. It is +also where the driver gets the +.Fa mh +argument for calling the +.Fn mac_unregister +function. It is recommended that the device driver keep the handle +around in its soft state structure for a given instance. +.Pp +If the call to the +.Fn mac_register +function fails, the device driver should unwind its +.Xr attach 9E +entry point, tear down everything that it initialized, and ultimately +return an error from its +.Xr attach 9E +entry point. +.Pp +If the +.Xr attach 9E +routine fails for some reason after the call to the +.Fn mac_register +function has succeeded, then the driver should call the +.Fn mac_unregister +function as part of unwinding all of its state. +.Pp +When a driver is in its +.Xr detach 9E +entry point, it should call the +.Fn mac_unregister +function immediately after draining any of its transmit and receive +resources that might have been given to the rest of the operating system +through DMA binding. See the +.Sx MBLKS AND DMA +section of +.Xr mac 9E +for more information. This should be done before the driver does any +tearing down. The call to the +.Fn mac_unregister +function may fail. This may happen because the networking stack is still +using the device. In such a case, the driver should fail the call to +.Xr detach 9E +and return +.Sy DDI_FAILURE . +.Sh CONTEXT +The +.Fn mac_register +function is generally only called from a driver's +.Xr attach 9E +entry point. The +.Fn mac_unregister +function is generally only called from a driver's +.Xr attach 9E +and +.Xr detach 9E +entry point. However, both functions may be called from either +.Sy user +or +.Sy kernel +context. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mac_register +and +.Fn mac_unregister +functions both return +.Sy 0 . +Otherwise, they return an error number. +.Sh EXAMPLES +The following example shows how a device driver might call the +.Fn mac_register +function. +.Bd -literal +#include <sys/mac_provider.h> +#include <sys/mac_ether.h> + +/* + * The call to mac_register(9F) generally comes from the context of + * attach(9E). This function encapsulates setting up and initializing + * the mac_register_t structure and should be assumed to be called from + * attach. + * + * The exact set of callbacks and private properties will vary based + * upon the driver. + */ + +static char *example_priv_props[] = { + "_rx_intr_throttle", + "_tx_intr_throttle", + NULL +}; + +static mac_callbacks_t example_m_callbacks = { + .mc_callbacsk = MC_GETCAPAB | MC_SETPROP | MC_GETPROP | MC_PROPINFO | + MC_IOCTL, + .mc_start = example_m_start, + .mc_stop = example_m_stop, + .mc_setpromisc = example_m_setpromisc, + .mc_multicst = example_m_multicst, + .mc_unicst = example_m_unicst, + .mc_tx = example_m_tx, + .mc_ioctl = example_m_ioctl, + .mc_getcapab = example_m_getcapab, + .mc_getprop = example_m_getprop, + .mc_setprop = example_m_setprop, + .mc_propinfo = example_m_propinfo +}; + +static boolean_t +example_register_mac(example_t *ep) +{ + int status; + mac_register_t *mac; + + mac = mac_alloc(MAC_VERSION); + if (mac == NULL) + return (B_FALSE); + + mac->m_type_indent = MAC_PLUGIN_IDENT_ETHER; + mac->m_driver = ep; + mac->m_dip = ep->ep_dev_info; + mac->m_src_addr = ep->ep_mac_addr; + mac->m_callbacks = &example_m_callbacks; + mac->m_min_sdu = 0; + mac->m_max_sdu = ep->ep_sdu; + mac->m_margin = VLAN_TAGSZ; + mac->m_priv_props = exmple_priv_props; + + status = mac_register(mac, &ep->ep_mac_hdl); + mac_free(mac); + + return (status == 0); +} +.Ed +.Sh ERRORS +The +.Fn mac_register +function may fail if: +.Bl -tag -width Er +.It EEXIST +A driver with the same name and instance already exists. +.It EINVAL +There was something invalid with the device's registration information. +Some of the following reasons may apply, this list is not exhaustive: +.Bl -bullet +.It +The +.Xr mac_init_ops 9F +function was not called. +.It +The specified mac plugin does not exist. +.It +An invalid minor number was used. +.It +The default unicast source address was incorrect. +.It +The plugin specific private data was incorrect or missing. +.It +Plugin specific data was provided when none is required. +.It +Required callback functions are not specified. +.It +The system was unable to properly create minor nodes. +.El +.It ENOSPC +The +.Xr mac 9E +framework was unable to allocate a minor number for the device as they +have all been exhausted. +.El +.Pp +The +.Fn mac_unregister +function will fail if: +.Bl -tag -width Er +.It Er EBUSY +The device is still in use. +.It Er ENOTEMPTY +The flow table is not empty. +.El +.Pp +Note the set of errors for both the +.Fn mac_regster +and +.Fn mac_unregister +functions are not set in stone and may be expanded in future revisions. +In general, all errors should be handled by the device driver in similar +ways for these functions. +.Sh SEE ALSO +.Xr attach 9E , +.Xr detach 9E , +.Xr mac 9E , +.Xr mac_alloc 9F , +.Xr mac_init_ops 9F , +.Xr mac_callbacks 9S , +.Xr mac_register 9S diff --git a/usr/src/man/man9f/mac_rx.9f b/usr/src/man/man9f/mac_rx.9f new file mode 100644 index 0000000000..74ce834a9a --- /dev/null +++ b/usr/src/man/man9f/mac_rx.9f @@ -0,0 +1,81 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 02, 2016 +.Dt MAC_RX 9F +.Os +.Sh NAME +.Nm mac_rx +.Nd deliver frames from a driver to the system +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo mac_rx +.Fa "mac_handle_t mh" +.Fa "mac_resource_handle_t mrh" +.Fa "mblk_t *mp_chain" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa mh +The MAC handle obtained from a call to +.Xr mac_register 9F . +.It Fa mrh +A reserved parameter that should be passed as +.Dv NULL . +.It Fa mp_chain +A series of one or more +.Xr mblk 9S +structures chained together by their +.Sy b_next +member. +.El +.Sh DESCRIPTION +The +.Fn mac_rx +function is used by device drivers to deliver frames that a device +driver has received to the rest of the operating system. This will +generally be called at the end of a device driver's interrupt handler +after it is has converted all of the incoming data into a chain of +.Xr mblk 9S +structures. For a full description of the process that the device driver +should take as part of receiving data, see the +.Sx Receiving Data +section of +.Xr mac 9E . +.Pp +Device drivers should ensure that they are not holding any of their own +locks when they call the +.Fn mac_rx +function. +.Pp +Device drivers should not call the +.Fn mac_rx +function after each individual mblk_t is assembled. Rather, the device +driver should batch up as many frames as it is willing to process in a +given interrupt or otherwise. +.Sh CONTEXT +The +.Fn mac_rx +function can be called from +.Sy user , +.Sy kernel , +or +.Sy interrupt +context. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_register 9F , +.Xr mblk 9S diff --git a/usr/src/man/man9f/mac_tx_update.9f b/usr/src/man/man9f/mac_tx_update.9f new file mode 100644 index 0000000000..11f6ac475d --- /dev/null +++ b/usr/src/man/man9f/mac_tx_update.9f @@ -0,0 +1,68 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd June 02, 2016 +.Dt MAC_TX_UPDATE 9F +.Os +.Sh NAME +.Nm mac_tx_update +.Nd indicate that a device can transmit again +.Sh SYNOPSIS +.In sys/mac_provider.h +.Ft void +.Fo mac_tx_update +.Fa "mac_handle_t mh" +.Fc +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh PARAMETERS +.Bl -tag -width Fa +.It Fa mh +The MAC handle obtained from a call to +.Xr mac_register 9F . +.El +.Sh DESCRIPTION +The +.Fn mac_tx_update +function is used by device drivers to indicate that the device +represented by the handle +.Fa mh +can transmit data again. It should only be called after the device +driver has returned data from its +.Xr mc_tx 9E +endpoint. For more information on when this should be called, see both +.Xr mc_tx 9E +and the +.Sx Transmitting Data and Back Pressure +section of +.Xr mac 9E . +.Pp +Device drivers should not hold any of their own locks when calling into +this function. See the +.Sx MAC Callbacks +section of +.Xr mac 9E +for more information. +.Sh CONTEXT +The +.Fn mac_tx_update +function may be called from +.Sy user , +.Sy kernel , +or +.Sy interrupt +context. +.Sh SEE ALSO +.Xr mac 9E , +.Xr mac_tx 9E , +.Xr mac_register 9F diff --git a/usr/src/man/man9s/Makefile b/usr/src/man/man9s/Makefile index c24521f325..f281dc3230 100644 --- a/usr/src/man/man9s/Makefile +++ b/usr/src/man/man9s/Makefile @@ -48,6 +48,8 @@ MANFILES= Intro.9s \ kstat_io.9s \ kstat_named.9s \ linkblk.9s \ + mac_callbacks.9s \ + mac_register.9s \ modldrv.9s \ modlinkage.9s \ modlmisc.9s \ @@ -89,15 +91,20 @@ MANFILES= Intro.9s \ usb_request_attributes.9s \ usb_string_descr.9s -MANLINKS= dblk.9s \ - intro.9s \ +MANLINKS= dblk.9s \ + intro.9s \ + mac_callbacks_t.9s \ + mac_register_t.9s \ mblk.9s -intro.9s := LINKSRC = Intro.9s +intro.9s := LINKSRC = Intro.9s -dblk.9s := LINKSRC = datab.9s +dblk.9s := LINKSRC = datab.9s -mblk.9s := LINKSRC = msgb.9s +mac_callbacks_t.9s := LINKSRC = mac_callbacks.9s +mac_register_t.9s := LINKSRC = mac_register.9s + +mblk.9s := LINKSRC = msgb.9s .KEEP_STATE: diff --git a/usr/src/man/man9s/mac_callbacks.9s b/usr/src/man/man9s/mac_callbacks.9s new file mode 100644 index 0000000000..a12d5ba230 --- /dev/null +++ b/usr/src/man/man9s/mac_callbacks.9s @@ -0,0 +1,326 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 12, 2016 +.Dt MAC_CALLBACKS 9S +.Os +.Sh NAME +.Nm mac_callbacks , +.Nm mac_callbacks_t +.Nd networking device driver entry points structure +.Sh SYNOPSIS +.In sys/mac_provider.h +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh DESCRIPTION +The +.Sy mac_callbacks +structure is used by GLDv3 networking device drivers implementing the +.Xr mac 9E +interface. +.Pp +The structure is normally allocated statically by drivers as a single +global entry. A pointer to it is passed as the +.Sy m_callbacks +member of the +.Sy mac_register_t +structure. +.Sh TYPES +The following types define the function pointers in use in the +.Sy mac_register_t . +.Bd -literal -offset indent +typedef int (*mac_getstat_t)(void *, uint_t, uint64_t *); +typedef int (*mac_start_t)(void *); +typedef void (*mac_stop_t)(void *); +typedef int (*mac_setpromisc_t)(void *, boolean_t); +typedef int (*mac_multicst_t)(void *, boolean_t, const uint8_t *); +typedef int (*mac_unicst_t)(void *, const uint8_t *); +typedef void (*mac_ioctl_t)(void *, queue_t *, mblk_t *); +typedef void (*mac_resources_t)(void *); +typedef mblk_t *(*mac_tx_t)(void *, mblk_t *); +typedef boolean_t (*mac_getcapab_t)(void *, mac_capab_t, void *); +typedef int (*mac_open_t)(void *); +typedef void (*mac_close_t)(void *); +typedef int (*mac_set_prop_t)(void *, const char *, mac_prop_id_t, + uint_t, const void *); +typedef int (*mac_get_prop_t)(void *, const char *, mac_prop_id_t, + uint_t, void *); +typedef void (*mac_prop_info_t)(void *, const char *, mac_prop_id_t, + mac_prop_info_handle_t); +.Ed +.Sh STRUCTURE MEMBERS +.Bd -literal -offset indent +uint_t mc_callbacks; /* Denotes which callbacks are set */ +mac_getstat_t mc_getstat; /* Get the value of a statistic */ +mac_start_t mc_start; /* Start the device */ +mac_stop_t mc_stop; /* Stop the device */ +mac_setpromisc_t mc_setpromisc; /* Enable or disable promiscuous mode */ +mac_multicst_t mc_multicst; /* Enable or disable a multicast addr */ +mac_unicst_t mc_unicst; /* Set the unicast MAC address */ +mac_tx_t mc_tx; /* Transmit a packet */ +void *mc_reserved; /* Reserved, do not use */ +mac_ioctl_t mc_ioctl; /* Process an unknown ioctl */ +mac_getcapab_t mc_getcapab; /* Get capability information */ +mac_open_t mc_open; /* Open the device */ +mac_close_t mc_close; /* Close the device */ +mac_set_prop_t mc_setprop; /* Set a device property */ +mac_get_prop_t mc_getprop; /* Get a device property */ +mac_prop_info_t mc_propinfo; /* Get property information */ +.Ed +.Pp +The +.Sy mc_callbacks +member is used to denote which of a series of optional callbacks are +present. This method allows additional members to be added to the +.Sy mac_callbacks_t +structure while maintaining ABI compatibility with existing modules. If +a member is not mentioned below, then it is a part of the base version +of the structure and device drivers do not need to set anything to +indicate that it is present. +The +.Sy mc_callbacks +member should be set to the bitwise inclusive OR of the following +pre-processor values: +.Bl -tag -width Dv -offset indent +.It Sy MC_IOCTL +Indicates that the +.Sy mc_ioctl +structure member has been set. +.It Sy MC_GETCAPAB +Indicates that the +.Sy mc_getcapab +structure member has been set. +.It Sy MC_OPEN +Indicates that the +.Sy mc_open +structure member has been set. +.It Sy MC_CLOSE +Indicates that the +.Sy mc_close +structure member has been set. +.It Sy MC_SETPROP +Indicates that the +.Sy mc_setprop +structure member has been set. +.It Sy MC_GETPROP +Indicates that the +.Sy mc_getprop +structure member has been set. +.It Sy MC_PROPINFO +Indicates that the +.Sy mc_propinfo +structure member has been set. +.It Sy MC_PROPERTIES +Indicates that the +.Sy mc_getprop , +.Sy mc_propinfo , +and +.Sy mc_setprop +structure members have been set. +.El +.Pp +The +.Sy mc_getstat +function defines an entry point used to receive statistics about the +device. A list of statistics that it is required to support is available +in +.Xr mac 9E . +For more information on the requirements of the function, see +.Xr mc_getstat 9E . +.Pp +The +.Sy mc_start +member defines an entry point that is used to start the device. For more +information on the requirements of the function, see +.Xr mc_start 9E . +.Pp +The +.Sy mc_stop +member defines an entry point that is used to stop the device. It is the +opposite of the +.Sy mc_start +member. For more information on the requirements of the function, see +.Xr mc_stop 9E . +.Pp +The +.Sy mc_setpromisc +member is used to enable and disable promiscuous mode on the device. For +more information on the requirements of the function, see +.Xr mc_setpromisc 9E . +.Pp +The +.Sy mc_multicst +member is used to enable or disable multicast addresses in the device's +filters. For more information on the requirements of the function, see +.Xr mc_multicst 9E . +.Pp +The +.Sy mc_unicst +member is used to set the primary unicast MAC address of the device. +For more information on the requirements of the function, see +.Xr mc_unicst 9E . +.Pp +The +.Sy mc_tx +member is used to transmit a single message on the wire. For more +information on the requirements of the function, see +.Xr mc_tx 9E . +.Pp +The +.Sy mc_ioctl +member is used to process device specific ioctls. The GLDv3 does not +define any ioctls that devices should handle; however, there may be +private ioctls for this device. This entry point is optional. For it to +be considered, the +.Sy MC_IOCTL +value must be present in the +.Sy mc_callbacks +member. For more information on the requirements of the function, see +.Xr mc_ioctl 9E . +.Pp +The +.Sy mc_getcapab +member is used to determine device capabilities. Each capability has its +own data and semantics associated with it. A list of capabilities is +provided in +.Xr mac 9E . +This entry point is optional. For it to be used, the +.Sy MC_GETCAPAB +value must be present in the +.Sy mc_callbacks +member. For more information on the requirements of the function, see +.Xr mc_getcapab 9E . +.Pp +The +.Sy mc_open +member is used to provide specific actions to take when the device is +opened. Note that most device drivers will not have a need to implement +this. It is not required for this function to be implemented for this +device to be used with +.Xr dlpi 7P . +This entry point is optional. For it to be used, the +.Sy MC_OPEN +value must be present in the +.Sy mc_callbacks +member. For more information on the requirements of the function, see +.Xr mc_open 9E . +.Pp +The +.Sy mc_close +member is used to provide specific actions to take when the device is +closed. Note that most device drivers will not have a need to implement +this. It is not required for this function to be implemented for this +device to be used with +.Xr dlpi 7P . +This entry point is optional. For it to be used, the +.Sy MC_CLOSE +value must be present in the +.Sy mc_callbacks +member. For more information on the requirements of the function, see +.Xr mc_close 9E . +.Pp +The +.Sy mc_getprop +member is used to get the current value of a property from the device. A +list of properties, their sizes, and their interpretation is available +in +.Xr mac 9E . +This entry point is optional. For it to be used, the +.Sy MC_GETPROP +value must be present in the +.Sy mc_callbacks +member. For more information on the requirements of the function, see +.Xr mc_getprop 9E . +.Pp +The +.Sy mc_setprop +member is used to set the value of a device property. A list of +properties, their sizes, and their interpretation is available in +.Xr mac 9E . +This entry point is optional. For it to be used, the +.Sy MC_SETPROP +value must be present in the +.Sy mc_callbacks +member. For more information on the requirements of the function, see +.Xr mc_setprop 9E . +.Pp +The +.Sy mc_propinfo +member is used to obtain metadata about a property such as its default +value, whether or not it is writable, and more. A list of properties, +their sizes, and their interpretation is available in +.Xr mac 9E . +This entry point is optional. For it to be used, the +.Sy MC_PROPINFO +value must be present in the +.Sy mc_callbacks +member. For more information on the requirements of the function, see +.Xr mc_propinfo 9E . +.Pp +.Ss Required Members +Many members in the structure are optional; however, the following +members must be set or a call to +.Xr mac_register 9F +will fail. +.Bl -bullet -offset indent +.It +.Sy mc_getstat +.It +.Sy mc_start +.It +.Sy mc_stop +.It +. Sy mc_setpromisc +.It +.Sy mc_multicst +.It +.Sy mc_tx +.It +.Sy mc_unicst +.El +.Pp +Note, that devices which implement the GLDv3 ring capabilities must not +implement the +.Sy mc_unicst +and +.Sy mc_tx +functions. However, the ring capabilities are still private and evolving +at this time. +.Pp +Generally, a device that implements one of +.Sy mc_getprop , +.Sy mc_setprop , +or +.Sy mc_propinfo +will want to implement all three endpoints to ensure that the property +is fully integrated into user land utilities such as +.Xr dladm 1M . +.Sh SEE ALSO +.Xr dladm 1M , +.Xr dlpi 7P , +.Xr mac 9E , +.Xr mc_close 9E , +.Xr mc_getcapab 9E , +.Xr mc_getprop 9E , +.Xr mc_getstat 9E , +.Xr mc_ioctl 9E , +.Xr mc_multicst 9E , +.Xr mc_open 9E , +.Xr mc_propinfo 9E , +.Xr mc_setpromisc 9E , +.Xr mc_setprop 9E , +.Xr mc_start 9E , +.Xr mc_stop 9E , +.Xr mc_tx 9E , +.Xr mc_unicst 9E , +.Xr mac_register 9S diff --git a/usr/src/man/man9s/mac_register.9s b/usr/src/man/man9s/mac_register.9s new file mode 100644 index 0000000000..469a11693c --- /dev/null +++ b/usr/src/man/man9s/mac_register.9s @@ -0,0 +1,187 @@ +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright 2016 Joyent, Inc. +.\" +.Dd May 10, 2016 +.Dt MAC_REGISTER 9S +.Os +.Sh NAME +.Nm mac_register , +.Nm mac_register_t +.Nd networking device driver registration structure +.Sh SYNOPSIS +.In sys/mac_provider.h +.In sys/mac_ether.h +.Sh INTERFACE LEVEL +illumos DDI specific +.Sh DESCRIPTION +The +.Sy mac_register +structure is used by GLDv3 networking device drivers implementing the +.Xr mac 9E +interface. +.Pp +The structure is allocated by a call to +.Xr mac_alloc 9F +after which the various structure members should be set. Once they have +been set, the structure can be used by a GLDv3 device driver to register +with the MAC framework by calling the +.Xr mac_register 9F +function. Once +.Xr mac_register 9F +has been called, the structure can be freed through a call to +.Xr mac_free 9F . +.Sh STRUCTURE MEMBERS +.Bd -literal -offset indent +uint_t m_version; +const char *m_type_ident; +void *m_driver; +dev_info_t *m_dip; +uint_t m_instance; +uint8_t *m_src_addr; +uint8_t *m_dst_addr; +mac_callbacks_t *m_callbacks; +uint_t m_min_sdu; +uint_t m_max_sdu; +void *m_pdata; +size_t m_pdata_size; +char **m_priv_props; +uint32_t m_margin; +.Ed +.Pp +The +.Sy m_version +member is set during a call to +.Xr mac_alloc 9F . +Device drivers should not modify this field. +.Pp +The +.Sy m_type_ident +member identifies the kind of networking device that this driver +represents. The following constants should be used to identify the +device type: +.Bl -tag -width Dv +.It Sy MAC_PLUGIN_IDENT_ETHER +The device driver implements IEEE 802.3 Ethernet. +.El +.Pp +The +.Sy m_driver +value is a private value that the device driver may set and will be +provided as an argument in many of the +.Xr mac 9E +callbacks. Most often this is set to the driver's soft state for a +specific instance. +.Pp +The +.Sy m_dip +member should point to the device driver's +.Sy dev_info +structure for that specific instance. This structure is provided during +the driver's +.Xr attach 9E +entry point. +.Pp +The +.Sy m_instance +member should be set to zero. The GLDv3 framework will determine the +appropriate instance. +.Pp +The +.Sy m_src_addr +member should be set to a byte array that describes the source MAC +address of the device. This is usually the default MAC address as +programmed by the device manufacturer in that instance of the device. +.Pp +The +.Sy m_dst_addr +member is an optional property and should be set to +.Dv NULL +by most device drivers. If set, this address will be the destination for +outgoing frames. +.Pp +The +.Sy m_callbacks +member contains the GLDv3 entry points implemented by the device driver. +.Xr mac +See +.Xr mac_callbacks 9S +for a full explanation of the structure, its members, and their +responsibilities. See +.Xr mac 9E +for a broader picture of how the entry points are used. +.Pp +The +.Sy m_min_sdu +property is the minimum service data unit. It represents the minimum +size packet that the device can transmit, ignoring its own headers. Thus +for an Ethernet device, this value would exclude the Ethernet header and +any VLAN headers. If this is set to zero, then that means that either +the MAC protocol does not require a minimum size or that the device +driver and hardware will ensure that any minimum size is taken care of. +.Pp +The +.Sy m_max_sdu +property is the maximum service data unit. It represents the maximum +size packet that the device can transmit, ignoring its own headers. For +an Ethernet based device, this would exclude the size of the Ethernet +header and a VLAN headers. This value is often called the maximum +transmission unit (MTU). +.Pp +The +.Sy m_pdata +member is used for data specific to the type specified in the +.Sy m_type_ident +member. For all devices of type +.Sy MAC_PLUGIN_IDENT_ETHER , +this should be set to +.Dv NULL . +.Pp +The +.Sy m_pdata_size +member indicates the size of the member +.Sy m_pdata . +For all devices of type +.Sy MAC_PLUGIN_IDENT_ETHER , +this should be set to 0. +.Pp +The +.Sy m_priv_props +member is an optional member that lists device-specific properties. +These properties will be queried through functions like +.Xr mc_getprop 9E , +.Xr mc_propinfo 9E , +and +.Xr mc_setprop 9E . +If the driver does not have any private properties, it should be set to +.Dv NULL . +Otherwise, it should be set to a NULL-terminated array of character +strings where each entry is the name of a distinct property. See +.Xr mac 9E +for more information on private properties. +.Pp +The +.Sy m_margin +property +indicates the amount of additional bytes of information that may be +included beyond the basic MAC header. For example, with an Ethernet +device, if the hardware supports a VLAN tag, then this property would be +set to the size of a VLAN tag, indicating that it supported the +additional bytes in a single packet beyond the Ethernet header and the +.Sy m_max_sdu . +.Sh SEE ALSO +.Xr attach 9E , +.Xr mac 9E , +.Xr mac_alloc 9F , +.Xr mac_free 9F , +.Xr mac_register 9F , +.Xr mac_callbacks 9S diff --git a/usr/src/pkg/manifests/system-kernel.man9e.inc b/usr/src/pkg/manifests/system-kernel.man9e.inc index 4381625c0c..a3e8bc6788 100644 --- a/usr/src/pkg/manifests/system-kernel.man9e.inc +++ b/usr/src/pkg/manifests/system-kernel.man9e.inc @@ -36,6 +36,19 @@ file path=usr/share/man/man9e/identify.9e file path=usr/share/man/man9e/ioctl.9e file path=usr/share/man/man9e/ks_snapshot.9e file path=usr/share/man/man9e/ks_update.9e +file path=usr/share/man/man9e/mac.9e +file path=usr/share/man/man9e/mc_getcapab.9e +file path=usr/share/man/man9e/mc_getprop.9e +file path=usr/share/man/man9e/mc_getstat.9e +file path=usr/share/man/man9e/mc_ioctl.9e +file path=usr/share/man/man9e/mc_multicst.9e +file path=usr/share/man/man9e/mc_open.9e +file path=usr/share/man/man9e/mc_propinfo.9e +file path=usr/share/man/man9e/mc_setpromisc.9e +file path=usr/share/man/man9e/mc_setprop.9e +file path=usr/share/man/man9e/mc_start.9e +file path=usr/share/man/man9e/mc_tx.9e +file path=usr/share/man/man9e/mc_unicst.9e file path=usr/share/man/man9e/mmap.9e file path=usr/share/man/man9e/open.9e file path=usr/share/man/man9e/power.9e @@ -63,6 +76,8 @@ file path=usr/share/man/man9e/tran_tgt_free.9e file path=usr/share/man/man9e/tran_tgt_init.9e file path=usr/share/man/man9e/tran_tgt_probe.9e file path=usr/share/man/man9e/write.9e +link path=usr/share/man/man9e/GLDv3.9e target=mac.9e +link path=usr/share/man/man9e/MAC.9e target=mac.9e link path=usr/share/man/man9e/_info.9e target=_fini.9e link path=usr/share/man/man9e/_init.9e target=_fini.9e link path=usr/share/man/man9e/gldm_get_stats.9e target=gld.9e @@ -75,7 +90,10 @@ link path=usr/share/man/man9e/gldm_set_multicast.9e target=gld.9e link path=usr/share/man/man9e/gldm_set_promiscuous.9e target=gld.9e link path=usr/share/man/man9e/gldm_start.9e target=gld.9e link path=usr/share/man/man9e/gldm_stop.9e target=gld.9e +link path=usr/share/man/man9e/gldv3.9e target=mac.9e link path=usr/share/man/man9e/intro.9e target=Intro.9e +link path=usr/share/man/man9e/mc_close.9e target=mc_open.9e +link path=usr/share/man/man9e/mc_stop.9e target=mc_start.9e link path=usr/share/man/man9e/tran_destroy_pkt.9e target=tran_init_pkt.9e link path=usr/share/man/man9e/tran_pkt_constructor.9e target=tran_setup_pkt.9e link path=usr/share/man/man9e/tran_pkt_destructor.9e target=tran_setup_pkt.9e diff --git a/usr/src/pkg/manifests/system-kernel.man9f.inc b/usr/src/pkg/manifests/system-kernel.man9f.inc index 31fd09040d..972e2e58a1 100644 --- a/usr/src/pkg/manifests/system-kernel.man9f.inc +++ b/usr/src/pkg/manifests/system-kernel.man9f.inc @@ -316,6 +316,16 @@ file path=usr/share/man/man9f/ldi_remove_event_handler.9f file path=usr/share/man/man9f/ldi_strategy.9f file path=usr/share/man/man9f/linkb.9f file path=usr/share/man/man9f/list_create.9f +file path=usr/share/man/man9f/mac_alloc.9f +file path=usr/share/man/man9f/mac_hcksum_get.9f +file path=usr/share/man/man9f/mac_init_ops.9f +file path=usr/share/man/man9f/mac_link_update.9f +file path=usr/share/man/man9f/mac_lso_get.9f +file path=usr/share/man/man9f/mac_maxsdu_update.9f +file path=usr/share/man/man9f/mac_prop_info.9f +file path=usr/share/man/man9f/mac_register.9f +file path=usr/share/man/man9f/mac_rx.9f +file path=usr/share/man/man9f/mac_tx_update.9f file path=usr/share/man/man9f/makecom.9f file path=usr/share/man/man9f/makedevice.9f file path=usr/share/man/man9f/max.9f @@ -975,6 +985,24 @@ link path=usr/share/man/man9f/list_remove.9f target=list_create.9f link path=usr/share/man/man9f/list_remove_head.9f target=list_create.9f link path=usr/share/man/man9f/list_remove_tail.9f target=list_create.9f link path=usr/share/man/man9f/list_tail.9f target=list_create.9f +link path=usr/share/man/man9f/mac_fini_ops.9f target=mac_init_ops.9f +link path=usr/share/man/man9f/mac_free.9f target=mac_alloc.9f +link path=usr/share/man/man9f/mac_hcksum_set.9f target=mac_hcksum_get.9f +link path=usr/share/man/man9f/mac_prop_info_set_default_link_flowctrl.9f \ + target=mac_prop_info.9f +link path=usr/share/man/man9f/mac_prop_info_set_default_str.9f \ + target=mac_prop_info.9f +link path=usr/share/man/man9f/mac_prop_info_set_default_uint32.9f \ + target=mac_prop_info.9f +link path=usr/share/man/man9f/mac_prop_info_set_default_uint64.9f \ + target=mac_prop_info.9f +link path=usr/share/man/man9f/mac_prop_info_set_default_uint8.9f \ + target=mac_prop_info.9f +link path=usr/share/man/man9f/mac_prop_info_set_perm.9f \ + target=mac_prop_info.9f +link path=usr/share/man/man9f/mac_prop_info_set_range_uint32.9f \ + target=mac_prop_info.9f +link path=usr/share/man/man9f/mac_unregister.9f target=mac_register.9f link path=usr/share/man/man9f/makecom_g0.9f target=makecom.9f link path=usr/share/man/man9f/makecom_g0_s.9f target=makecom.9f link path=usr/share/man/man9f/makecom_g1.9f target=makecom.9f diff --git a/usr/src/pkg/manifests/system-kernel.man9s.inc b/usr/src/pkg/manifests/system-kernel.man9s.inc index f502ea2647..d782b25b96 100644 --- a/usr/src/pkg/manifests/system-kernel.man9s.inc +++ b/usr/src/pkg/manifests/system-kernel.man9s.inc @@ -44,6 +44,8 @@ file path=usr/share/man/man9s/kstat_intr.9s file path=usr/share/man/man9s/kstat_io.9s file path=usr/share/man/man9s/kstat_named.9s file path=usr/share/man/man9s/linkblk.9s +file path=usr/share/man/man9s/mac_callbacks.9s +file path=usr/share/man/man9s/mac_register.9s file path=usr/share/man/man9s/modldrv.9s file path=usr/share/man/man9s/modlinkage.9s file path=usr/share/man/man9s/modlmisc.9s @@ -71,4 +73,6 @@ file path=usr/share/man/man9s/tuple.9s file path=usr/share/man/man9s/uio.9s link path=usr/share/man/man9s/dblk.9s target=datab.9s link path=usr/share/man/man9s/intro.9s target=Intro.9s +link path=usr/share/man/man9s/mac_callbacks_t.9s target=mac_callbacks.9s +link path=usr/share/man/man9s/mac_register_t.9s target=mac_register.9s link path=usr/share/man/man9s/mblk.9s target=msgb.9s |