diff options
Diffstat (limited to 'usr/src/man/man9e')
| -rw-r--r-- | usr/src/man/man9e/Makefile | 10 | ||||
| -rw-r--r-- | usr/src/man/man9e/chpoll.9e | 22 | ||||
| -rw-r--r-- | usr/src/man/man9e/mac_capab_led.9e | 228 | ||||
| -rw-r--r-- | usr/src/man/man9e/mac_capab_transceiver.9e | 407 |
4 files changed, 663 insertions, 4 deletions
diff --git a/usr/src/man/man9e/Makefile b/usr/src/man/man9e/Makefile index 2d32bfbe34..8036f34cda 100644 --- a/usr/src/man/man9e/Makefile +++ b/usr/src/man/man9e/Makefile @@ -42,6 +42,8 @@ MANFILES= Intro.9e \ ks_snapshot.9e \ ks_update.9e \ mac.9e \ + mac_capab_transceiver.9e \ + mac_capab_led.9e \ mc_getcapab.9e \ mc_getprop.9e \ mc_getstat.9e \ @@ -111,6 +113,9 @@ MANLINKS= _info.9e \ MAC.9e \ mc_close.9e \ mc_stop.9e \ + mcl_set.9e \ + mct_info.9e \ + mct_read.9e \ intro.9e \ tran_destroy_pkt.9e \ tran_pkt_constructor.9e \ @@ -148,6 +153,11 @@ gldm_stop.9e := LINKSRC = gld.9e mc_close.9e := LINKSRC = mc_open.9e mc_stop.9e := LINKSRC = mc_start.9e +mcl_set.9e := LINKSRC = mac_capab_led.9e + +mct_info.9e := LINKSRC = mac_capab_transceiver.9e +mct_read.9e := LINKSRC = mac_capab_transceiver.9e + tran_setcap.9e := LINKSRC = tran_getcap.9e tran_destroy_pkt.9e := LINKSRC = tran_init_pkt.9e diff --git a/usr/src/man/man9e/chpoll.9e b/usr/src/man/man9e/chpoll.9e index 7b4b3edf0b..1e8aac5e81 100644 --- a/usr/src/man/man9e/chpoll.9e +++ b/usr/src/man/man9e/chpoll.9e @@ -1,10 +1,11 @@ '\" te .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 1989 AT&T +.\" Copyright 2017 Joyent, Inc .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH CHPOLL 9E "May 7, 2008" +.TH CHPOLL 9E "Jan 18, 2017" .SH NAME chpoll \- poll entry point for a non-STREAMS character driver .SH SYNOPSIS @@ -182,13 +183,26 @@ if (specified_events_are_satisfied_now) { *reventsp = satisfied_events & events; } else { *reventsp = 0; - if (!anyyet) - *phpp = &my_local_pollhead_structure; } +if ((*reventsp == 0 && !anyyet) || (events & POLLET)) + *phpp = &my_local_pollhead_structure; return (0); .fi .in -2 +Note: Prior to the integration of \fBepoll\fR(5), which included +edge-triggering via the \fBPOLLET\fR flag, standard chpoll mechanisms would +only provide a pollhead in \fBphpp\fR if there were no matching events. +Edge-triggered polling requires that \fBpollwakeup()\fR always be called for a +resource, so if \fBPOLLET\fR is set in the \fBevents\fR of interest, the chpoll +method must yield a pollhead and prepare to issue \fBpollwakeup()\fR calls on +it. + +Drivers which are not wired up to make \fBpollwakeup()\fR calls on a pollhead +when their status changes should emit one from their \fBchpoll\fR routine. +This will exclude the resource from caching by pollers, since it cannot alert +them to new events without \fBpollwakeup()\fR notification. + .RE .RS +4 .TP @@ -252,7 +266,7 @@ associated with the \fBpollhead\fR is about to be deallocated by the number. .SH SEE ALSO .LP -\fBpoll\fR(2), \fBnochpoll\fR(9F), \fBpollwakeup\fR(9F) +\fBpoll\fR(2), \fBepoll\fR(5), \fBnochpoll\fR(9F), \fBpollwakeup\fR(9F) .sp .LP \fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/mac_capab_led.9e b/usr/src/man/man9e/mac_capab_led.9e new file mode 100644 index 0000000000..cf6b3713d3 --- /dev/null +++ b/usr/src/man/man9e/mac_capab_led.9e @@ -0,0 +1,228 @@ +.\" +.\" 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 (c) 2017, Joyent, Inc. +.\" +.Dd Feb 21, 2017 +.Dt MAC_CAPAB_LED 9E +.Os +.Sh NAME +.Nm mac_capab_led , +.Nm mcl_set +.Nd MAC LED capability +.Sh SYNOPSIS +.In sys/mac_provider.h +.Vt typedef struct mac_capab_led mac_capab_led_t; +.Vt typedef enum mac_led_mode mac_led_mode_t; +.Ft int +.Fo mcl_set +.Fa "void *driver" +.Fa "mac_led_mode_t mode" +.Fa "uint_t flags" +.Fc +.Sh INTERFACE LEVEL +.Sy Evolving - +This interface is still evolving. +API and ABI stability is not guaranteed. +.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 mode +A value that indicates how the driver should drive the LEDs. +See the +.Sx LED MODES +section for a list of supported modes. +.It Fa flags +Reserved for future use. +.El +.Sh DESCRIPTION +The +.Sy MAC_CAPAB_LED +capability allows GLDv3 device drivers to expose an interface for +controlling the LEDs on the device. +This allows the system to control the LEDs to assist system +administrators in finding and identifying specific physical devices in +the system. +.Pp +Implementing this capability is optional. +For more information on how to handle capabilities and how to indicate +that a capability is not supported, see +.Xr mc_getcapab 9E . +.Pp +This capability should be implemented if the device in question provides +a way to manipulate its LEDs. +Generally the LEDs on a device default to indicating link status and +activity. +However, they can often be turned off or set to a specific pattern for +identification purposes. +.Ss LED MODES +The system has a notion of different LED modes. +Each LED mode suggests a different way that a device driver should drive +the indicator LEDs on the device. +While we generally want all such LED modes to be as uniform +as possible, there is a limit to such similarities due to the +capabilities of NICs. +Each mode is a member of the +.Vt mac_led_mode_t +enumeration. +The currently defined modes are: +.Bl -tag -width Dv -offset indent +.It Dv MAC_LED_DEFAULT +This mode indicates that the device's default behavior should be used. +This is usually some form of link status and activity. +It is device specific and usually is the default behavior after a device +is powered on. +.It Dv MAC_LED_OFF +This mode indicates that the device's LEDs should be turned off and not +emit any light. +.It Dv MAC_LED_ON +This mode indicates that the device's LEDs should be turned on and +remain solid. +.It Dv MAC_LED_IDENT +This mode indicates that the driver should emit some form of +identification pattern. +We suggest that devices indicate some form of solid blinking light that +is on and off at alternating units of time, for example, every 200 +milliseconds. +If it is possible to use an alternate color from the normal link up and +activity lighting, that is recommended. +.El +.Ss MAC Capability Structure +When the device driver's +.Xr mc_getcapab 9E +function entry point is called with the capability set to +.Dv MAC_CAPAB_LED , +then the value of the capability structure is the following structure: +.Bd -literal -offset indent +typedef struct mac_capab_led { + uint_t mcl_flags; + mac_led_mode_t mcl_modes; + int (*mcl_set)(void *driver, mac_led_mode_t mode, + uint_t flags); +} mac_capab_led_t; +.Ed +.Pp +If the driver supports the +.Dv MAC_CAPAB_LED +capability, it should fill in this structure, based on the following +rules: +.Bl -tag -width Vt +.It Fa mcl_flags +The +.Fa mcl_flags +member is used to negotiate extensions with the driver. +MAC will set the value of +.Fa mcl_flags +to include all of the currently known extensions. +The driver should intersect this list with the set that they actually +support. +At this time, no such features are defined and the driver should set the +member to +.Sy 0 . +.It Fa mcl_modes +The +.Fa mcl_modes +member represents the support modes of the device driver. +The device driver should set +.Vt mcl_modes +to the bitwise-inclusive-OR of the LED modes listed in +.Sx LED MODES . +.Pp +If the driver does not support anything other than the default behavior +of +.Dv MAC_LED_DEFAULT , +then the device driver should not indicate that it supports this +capability. +.It Fa mcl_set +The +.Fa mcl_set +entry point will be called by the MAC framework when it needs the device +driver to change how it is driving its LEDs. +Each call will ask the driver to change the display mode to the +specified mode. +The driver does not have to multiplex requests for multiple modes or +keep track of what has been requested, that is taken care of by the +system itself. +.Pp +The driver should first validate that +.Fa mode +is a mode that it supports. +While the device reports the set of supported modes as a +bitwise-inclusive-OR, the driver should only receive a single value in +.Fa mode . +The value of the +.Fa flags +argument is reserved for future use. +Drivers must check that the value of flags is zero and if not, return +.Er EINVAL . +.Pp +When this entry point is first called on a driver, it should snapshot +its device registers such that it knows how to restore the default +behavior. +Because each method of programming the LEDs is different, it +is up to the driver itself to take care of this, the broader framework +cannot take care of it. +.Pp +If for some reason the driver is asked to program the same mode that it +is already driving, then it need not do anything and should simply +return success. +.Pp +Once the driver successfully changes the LED driving mode, it should +return +.Sy 0 . +Otherwise, it should return the appropriate error number. +For a full list of error numbers, see +.Xr Intro 2 . +Common values are: +.Bl -tag -width Er -offset width +.It Er EINVAL +.Fa flag +contains an unknown value. +.It Er ENOTSUP +.Fa mode +is unsupported. +.Fa flags +contains an unsupported or unknown value. +.It Er EIO +An I/O error occurred while trying to program the device's registers. +This could be because a command timed out or an FM-aware driver +encountered an error. +.El +.Pp +The broader framework will guarantee that only a single call to the +.Fa mcl_set +function is ongoing at any time. +If other parts of the driver refer to the data used by the +.Fa mcl_set +function, then the driver must ensure that it is performing sufficient +locking of its data. +.El +.Sh CONTEXT +The +.Ft mcl_set +entry point will only be called from +.Sy user +or +.Sy kernel +context. +It will never be called from interrupt context. +.Sh SEE ALSO +.Xr Intro 2 , +.Xr mac 9E , +.Xr mc_getcapab 9E , +.Xr mac_register 9F diff --git a/usr/src/man/man9e/mac_capab_transceiver.9e b/usr/src/man/man9e/mac_capab_transceiver.9e new file mode 100644 index 0000000000..7626fe5fed --- /dev/null +++ b/usr/src/man/man9e/mac_capab_transceiver.9e @@ -0,0 +1,407 @@ +.\" +.\" 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 (c) 2017, Joyent, Inc. +.\" +.Dd Mar 24, 2017 +.Dt MAC_CAPAB_TRANSCEIVER 9E +.Os +.Sh NAME +.Nm mac_capab_transciever , +.Nm mct_info , +.Nm mct_read +.Nd MAC capability for networking transceivers +.Sh SYNOPSIS +.In sys/mac_provider.h +.Vt typedef struct mac_capab_transceiver mac_capab_transceiver_t; +.Ft int +.Fo "mct_info" +.Fa "void *driver" +.Fa "uint_t id" +.Fa "mac_transceiver_info_t *infop" +.Fc +.Ft int +.Fo mct_read +.Fa "void *driver" +.Fa "uint_t id" +.Fa "uint_t page" +.Fa "void *buf" +.Fa "size_t nbytes" +.Fa "off_t offset" +.Fa "size_t *nread" +.Fc +.Sh INTERFACE LEVEL +.Sy Volatile - +This interface is still evolving in illumos. +API and ABI stability is +not guaranteed. +.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 id +An integer value indicating which transceiver is being inquired about. +.It Fa infop +An opaque structure which is used to set information about the +transceiver. +.It Fa page +A value that indicates which page from the i2c bus is being requested. +.It Fa buf +A pointer to which data should be written to when reading from the +device. +.It Fa nbytes +A value indicating the number of bytes being asked to read into +.Fa buf . +.It Fa offset +A value indicating the offset into the page to start reading data. +.It Fa nread +A value to be updated by the driver with the number of successfully read +bytes. +.El +.Sh DESCRIPTION +The +.Sy MAC_CAPAB_TRANSCEIVER +capability allows for GLDv3 networking device drivers to provide +information to the system about their transceiver. +Implementing this capability is optional. +For more information on how to handle capabilities and how to indicate +that a capability is not supported, see +.Xr mc_getcapab 9E . +.Pp +This capability should be implemented if the device in question supports +a Small Form Factor (SFF) transceiver. +These are more commonly known by names such as SFP, SFP+, SFP28, QSFP+, +and QSFP28. +This interface does not apply to traditional copper Ethernet phys. +These transceivers provide standardized information over the i2c bus at +specific pages. +.Ss Supported Standards +.Bl -tag -width Sy +.It Sy INF-8074 +The +.Sy INF-8084 +standard was the original multiple source agreement (MSA) for SFP +devices. +It proposed the original series of management pages at i2c page 0xa0. +This page contained up to 512 bytes, however, only the first +96 bytes are standardized. +Bytes 97 to 127 are reserved for the vendor. +The remaining bytes are reserved by the specification. +The management page was subsequently adopted by SFP+ devices. +.It Sy SFF-8472 +The +.Sy SFF-8472 +standard extended the original SFP MSA. +This standard added a second i2c page at 0xa2, while maintaining the +original page at 0xa0. +The page at 0xa0 is now explicitly 256 bytes. +The page at 0xa2 is also 256 bytes. +This standard was also adopted for all SFP28 parts, which are commonly +used in transceivers for 25 Gb/s Ethernet. +.It Sy SFF-8436 +The +.Sy SFF-8436 +standard was developed for QSFP+ transceivers, which involve the +bonding of 4 SFP+ links. +QSFP+ is commonly used in the transceivers for 40 Gb/s Ethernet. +This standard uses i2c page 0xa0 for read-only identification purposes. +The lower half of the page is used for control, while the upper 128 +bytes is similar to the +.Sy INF-8084 +and +.Sy SFF-8472 +standards. +.It Sy SFF-8636 +The +.Sy SFF-8636 +standard is a common management standard which is shared between both +SAS and QSFP+ 28 Gb/s transceivers. +The latter transceiver is commonly found in 100 Gb/s Ethernet. +The transceiver's memory map is similar to that found in the +.Sy SFF-8436 +specification. +The identification information is found in the upper 128 +bytes of page 0xa0, while the lower part of the page is used for +control, among other purposes. +.El +.Pp +The following table summarizes the above information. +.Bl -column "Sy SFF-8636" "1 Gb/s, 10 Gb/s, 25 Gb/s" "256 bytes" "0xa0, 0xa2" -offset indent +.Em "Standard" Ta Em Speeds Ta Em Size Ta Em i2c pages +.It INF-8074 Ta 1 Gb/s, 10 Gb/s Ta 128 bytes Ta 0xa0 +.It SFF-8472 Ta 1 Gb/s, 10 Gb/s, 25 GB/s Ta 512 bytes Ta 0xa0, 0xa2 +.It SFF-8436 Ta 40 Gb/s Ta 256 bytes Ta 0xa0 +.It SFF-8636 Ta 100 Gb/s Ta 256 bytes Ta 0xa0 +.El +.Ss MAC Capability Structure +When the device driver's +.Xr mc_getcapab 9E +function entry point is called with the capability requested set to +.Sy MAC_CAPAB_TRANSCEIVER , +then the value of the capability structure is the following structure: +.Bd -literal -offset indent +typedef struct mac_capab_transceiver { + uint_t mct_flags; + uint_t mct_ntransceiveres; + int (*mct_info)(void *driver, uint_t id, + mac_transceiver_info_t *infop), + int (*mct_read)(void *driver, uint_t id, uint_t page, + void *buf, size_t nbytes, off_t offset, + size_t *nread) +} mac_capab_transceiver_t; +.Ed +.Pp +If the device driver supports the +.Sy MAC_CAPAB_TRANSCEIVER +capability, it should fill in this structure, based on the following +rules: +.Bl -tag -width Sy +.It Sy mct_flags +The +.Vt mct_flags +member is used to negotiate extensions with the driver. +MAC will set the value of +.Vt mct_flags +to include all of the currently known extensions. +The driver should intersect this list with the set that they actually +support. +At this time, no such features are defined and the driver should set the +member to +.Sy 0 . +.It Sy mct_ntransceivers +The value of +.Sy mct_ntransceivers +indicates that the number of transceivers present in the device. +For most devices, it is expected that this value will be set to one. +However, some devices do support multiple transceivers and PHYs that +show up behind a single logical MAC. +.Pp +It is expected that this value will not change across the lifetime of +the device being attached. +It is important to remember that this represents the total possible +number of transceivers in the device, not how many are currently present +and powered on. +.Pp +The number of transceivers will influence the +.Fa id +argument used in the +.Fn mct_info +and +.Fn mct_read +entry points. +The transceiver IDs will start at zero and go to the value of +.Fa mct_ntransceivers - 1 . +It is up to the driver to keep the mapping between actual transceivers +and the transceiver identifiers consistent. +.It Sy mct_info +The +.Fn mct_info +entry point is used to set basic information about the transceiver. +This entry point is +.Em required . +If the device driver cannot implement this entry point, then it should +not indicate that it supports the capability. +.Pp +The +.Fn mct_info +entry point should fill in information about the transceiver with an +identifier of +.Fa id . +See the description above of +.Sy mct_ntransceivers +for more information on how the IDs are determined. +.Pp +The driver should then proceed to fill in basic information by calling +the functions described in the section +.Sx Information Functions . +After successfully calling all of the functions, the driver should +return +.Sy 0 . +Othewrise, it should return the appropriate error number. +For a full list of error numbers, see +.Xr Intro 2 . +Common values are: +.Bl -tag -width Er -offset width +.It Er EINVAL +The transceiver identifier +.Fa id +was invalid. +.It Er ENOTSUP +This instance of the devices does not support a transceiver. +For example, a device which sometimes has copper PHYs and therefore this +instance does not have any PHYs. +.It Er EIO +An error occurred while trying to read device registers. +For example, an FM-aware device had an error. +.El +.It Sy mct_read +The +.Fn mct_read +function is used to read information from a transceiver's i2c bus. +The +.Fn mct_read +entry point is an +.Em optional +entry point. +.Pp +The transceiver should first check the value of +.Fa id , +which indicates which transceiver information is being requested. +See the description above of +.Sy mct_ntransceivers +for more information on how the IDs are determined. +.Pp +The driver should try to read up to +.Fa nbytes +of data from the i2c bus at page +.Fa page . +The driver should start reading at offset +.Fa offset . +Finally, it should update the value in +.Fa nread +with the number of bytes written to the buffer +.Fa buf . +.Pp +If for some reason the driver cannot read all of the requested bytes, +that is acceptable. +Instead it should perform a short read. +This may occur because the transceiver does not allow reads at a +requested region or the region is shorter than is common for most +devices. +.Pp +Upon successful completion, the driver should ensure that +.Fa nread +has been updated and then return +.Sy 0 . +Otherwise, the driver should return the appropriate error number. +For +a full list of error numbers, see +.Xr Intro 2 . +Common values are: +.Bl -tag -width Er -offset width +.It Er EINVAL +The value of +.Fa id +represented an invalid transceiver identifier. +The transceiver i2c page +.Fa page +is not valid for this type of device. +The value of +.Fa offset +is beyond the range supported for this +.Fa page . +.It Er EIO +An error occurred while trying to read the device i2c pages. +.El +.El +.Ss Transceiver Information Functions +The +.Fn mct_info +entry point is the primary required entry point for a device driver +which supports this capability. +The information structure is opaque to the device driver. +Instead, a series of informational functions is +available to the device driver to call on the transceiver. +The device drivers should try to call and fill in as many of these as +possible. +There are two different properties that a driver can set: +.Bl -enum -offset indent +.It +Whether the transceiver is present. +.It +Whether the transceiver is usable. +.El +.Pp +To set whether or not the transceiver is present, the driver should call +.Xr mac_transceiver_info_set_present 9F . +This is used to indicate whether the transceiver is plugged in or not. +If the transceiver is a part of the NIC, then this function should +always be called with the value set to +.Dv B_TRUE . +.Pp +Finally, the driver has the ability to provide information about whether +or not the transceiver is usable or not. +A transceiver may be present, but not usable, if the hardware and +firmware support a limited number of transceivers. +To set this information, the driver should call +.Xr mac_transceiver_info_set_usable 9F . +If the transceiver is not present, then the driver should not call this +function. +.Ss Opaque Transceivers +Some devices abstract the nature of the transceiver and do not allow +direct access to the transceiver. +In this case, if the device driver still has access to enough +information to know if the transceiver is at least present, then it +should still implement the +.Fn mct_info +entry point. +.Ss Locking and Data Access +Calls to get information about the transceivers may come at the same +time as general I/O requests to the device to send or receive data. +The driver should make sure that reading data from the i2c bus of the +transceiver does not interfere with the device's functionality in this +regard. +Different locks should be used. +.Pp +On some devices, reading from the transceiver's i2c bus might cause a +disruption of service to the device. +For example, on some devices a phy reset may be required or come about +as a side effect of trying to read the device. +If any kind of disruption would be caused, then the driver +must not implement the +.Ft mct_read +entry point. +.Sh CONTEXT +The various callback functions will be called from +.Sy kernel +context. +These functions will never be called from +.Sy interrupt +context. +.Sh SEE ALSO +.Xr Intro 2 , +.Xr mac 9E , +.Xr mc_getcapab 9E , +.Xr mac_register 9F , +.Xr mac_transceiver_info_set_present 9F , +.Xr mac_transceiver_info_set_usable 9F , +.Xr mac_register 9S , +.Rs +.%N INF-8074i +.%T SFP (Small Formfactor Pluggable) Interface +.%Q SFF Committee +.%O Revision 1.0 +.%D May 12, 2001 +.Re +.Rs +.%N SFF-8472 +.%T Diagnostic Monitoring Interface for Optical Transceivers +.%O Revision 12.2 +.%D November 21, 2014 +.Re +.Rs +.%N SFF-8436 +.%T QSFP+ 10 Gbs 4X PLUGGABLE TRANSCEIVER +.%O Revision 4.8 +.%D October 31, 2013 +.Re +.Rs +.%N SFF-8636 +.%T Management Interface for Cabled Environments +.%O Revision 2.7 +.%D January 26, 2016 +.Re |