diff options
Diffstat (limited to 'usr/src/man/man9s')
| -rw-r--r-- | usr/src/man/man9s/mac_callbacks.9s | 123 | ||||
| -rw-r--r-- | usr/src/man/man9s/mac_register.9s | 78 | ||||
| -rw-r--r-- | usr/src/man/man9s/usb_ep_ss_comp_descr.9s | 46 | ||||
| -rw-r--r-- | usr/src/man/man9s/usb_ep_xdescr.9s | 29 | ||||
| -rw-r--r-- | usr/src/man/man9s/usba_device.9s | 84 | ||||
| -rw-r--r-- | usr/src/man/man9s/usba_hcdi_ops.9s | 83 | ||||
| -rw-r--r-- | usr/src/man/man9s/usba_hcdi_register_args.9s | 31 | ||||
| -rw-r--r-- | usr/src/man/man9s/usba_pipe_handle_data.9s | 58 |
8 files changed, 303 insertions, 229 deletions
diff --git a/usr/src/man/man9s/mac_callbacks.9s b/usr/src/man/man9s/mac_callbacks.9s index a12d5ba230..9ab382d65e 100644 --- a/usr/src/man/man9s/mac_callbacks.9s +++ b/usr/src/man/man9s/mac_callbacks.9s @@ -30,7 +30,8 @@ structure is used by GLDv3 networking device drivers implementing the interface. .Pp The structure is normally allocated statically by drivers as a single -global entry. A pointer to it is passed as the +global entry. +A pointer to it is passed as the .Sy m_callbacks member of the .Sy mac_register_t @@ -81,10 +82,11 @@ mac_prop_info_t mc_propinfo; /* Get property information */ 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 +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 +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 @@ -132,36 +134,38 @@ structure members have been set. 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 +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 +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 +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 +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 +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 +filters. +For more information on the requirements of the function, see .Xr mc_multicst 9E . .Pp The @@ -172,99 +176,114 @@ For more information on the requirements of the function, see .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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +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 +member. +For more information on the requirements of the function, see .Xr mc_propinfo 9E . .Pp .Ss Required Members @@ -280,7 +299,7 @@ will fail. .It .Sy mc_stop .It -. Sy mc_setpromisc +.Sy mc_setpromisc .It .Sy mc_multicst .It @@ -294,8 +313,8 @@ implement the .Sy mc_unicst and .Sy mc_tx -functions. However, the ring capabilities are still private and evolving -at this time. +functions. +However, the ring capabilities are still private and evolving at this time. .Pp Generally, a device that implements one of .Sy mc_getprop , diff --git a/usr/src/man/man9s/mac_register.9s b/usr/src/man/man9s/mac_register.9s index 469a11693c..6f648e3348 100644 --- a/usr/src/man/man9s/mac_register.9s +++ b/usr/src/man/man9s/mac_register.9s @@ -32,11 +32,12 @@ 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 +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 +function. +Once .Xr mac_register 9F has been called, the structure can be freed through a call to .Xr mac_free 9F . @@ -67,8 +68,8 @@ Device drivers should not modify this field. 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: +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. @@ -79,69 +80,74 @@ The 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. +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 +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. +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. +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. +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 +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. +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). +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 +member. +For all devices of type .Sy MAC_PLUGIN_IDENT_ETHER , this should be set to .Dv NULL . @@ -165,7 +171,8 @@ and 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 +strings where each entry is the name of a distinct property. +See .Xr mac 9E for more information on private properties. .Pp @@ -173,10 +180,11 @@ 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 +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 , diff --git a/usr/src/man/man9s/usb_ep_ss_comp_descr.9s b/usr/src/man/man9s/usb_ep_ss_comp_descr.9s index b94b7f576b..ba3f4e06b0 100644 --- a/usr/src/man/man9s/usb_ep_ss_comp_descr.9s +++ b/usr/src/man/man9s/usb_ep_ss_comp_descr.9s @@ -26,10 +26,12 @@ illumos DDI Specific The .Sy usb_ep_ss_comp_descr_t structure defines additional endpoint attributes for USB 3.0 and newer -devices. This structure is considered a +devices. +This structure is considered a .Em companion descriptor . -On its own, it does not uniquely define an endpoint. A standard USB -descriptor is still required. See +On its own, it does not uniquely define an endpoint. +A standard USB descriptor is still required. +See .Xr usb_ep_descr 9S for the definition of the standard descriptor. .Pp @@ -37,7 +39,8 @@ If available, the SuperSpeed companion descriptor can be accessed by getting the endpoint data through a call to .Xr usb_lookup_ep_data 9F . These descriptors are required to open pipes for USB 3.0 and newer -devices. They can be assembled into the proper format for +devices. +They can be assembled into the proper format for .Xr usb_pipe_xopen 9F by calling .Xr usb_ep_xdescr_fill 9F . @@ -67,15 +70,16 @@ whose value is 0x30. The .Sy bMaxBurst member indicates the maximum number of packets that the endpoint can -send in one 'burst'. Valid values range from 0 to 15 and the values are -one less than the number of packets. A value of 0 indicates that 1 -packet can be sent in a burst. A value of 15 indicates that 16 packets -can be sent in a burst. +send in one 'burst'. +Valid values range from 0 to 15 and the values are one less than the number of +packets. +A value of 0 indicates that 1 packet can be sent in a burst. +A value of 15 indicates that 16 packets can be sent in a burst. .Pp The .Sy bmAttributes -member indicates different attributes of the endpoint. This member is -reserved and should be zero for +member indicates different attributes of the endpoint. +This member is reserved and should be zero for .Sy control and .Sy interrupt @@ -86,11 +90,14 @@ For a endpoint, the .Sy bmAttributes member is used to indicate the maximum number of streams that the device -supports. The first five bits (4:0) are used, the remaining 3 bits are -reserved and should be zero. Values range from 0 to 16. A value of zero -indicates that streams are not supported. Otherwise, it indicates that -the device supports 2 raised to the value number of streams. A value of -3, indicates 2^3 streams are supported. +supports. +The first five bits (4:0) are used, the remaining 3 bits are reserved and should +be zero. +Values range from 0 to 16. +A value of zero indicates that streams are not supported. +Otherwise, it indicates that the device supports 2 raised to the value number of +streams. +A value of 3, indicates 2^3 streams are supported. .Pp For an .Sy isochronous @@ -99,14 +106,15 @@ endpoint, the member is used to indicate the value of the .Sy Mult property, a value used to calculate the maximum number of packets the -device and receive in a service interval. The first two bits (1:0) are -used to determine the mult. The remaining 6 bits (7:2) are reserved and -should be set to zero. +device and receive in a service interval. +The first two bits (1:0) are used to determine the mult. +The remaining 6 bits (7:2) are reserved and should be set to zero. .Pp The .Sy wBytesPerInterval member is used to indicate the total number of bytes that can be -transferred in one service interval. Note, this is only valid for +transferred in one service interval. +Note, this is only valid for .Sy Isochronous and .Sy Interrupt IN diff --git a/usr/src/man/man9s/usb_ep_xdescr.9s b/usr/src/man/man9s/usb_ep_xdescr.9s index bb7a86120e..44ce12793e 100644 --- a/usr/src/man/man9s/usb_ep_xdescr.9s +++ b/usr/src/man/man9s/usb_ep_xdescr.9s @@ -32,9 +32,11 @@ Starting with the .Em USB 3.0 specification, .Em USB 3.0 -endpoints have an endpoint SuperSpeed companion descriptor. See +endpoints have an endpoint SuperSpeed companion descriptor. +See .Xr usb_ep_ss_comp_descr 9S -for a description of the descriptor. In the +for a description of the descriptor. +In the .Em USB 3.1 specification, certain endpoints will have additional companion descriptors. @@ -54,7 +56,8 @@ After looking up endpoint data, through the .Xr usb_lookup_ep_data 9F , device drivers should call the .Xr usb_ep_xdescr_fill 9F -function. After that, the +function. +After that, the .Sy usb_ep_xdescr_t structure will be filled in. .Sh STRUCTURE MEMBERS @@ -70,32 +73,34 @@ usb_ep_ss_comp_descr_t uex_ep_ss; .Pp The .Sy uex_version -member is used to describe the current version of this structure. This -member will be set to the value passed in by the device driver to +member is used to describe the current version of this structure. +This member will be set to the value passed in by the device driver to .Xr usb_ep_xdescr_fil 9F . Device drivers should ignore this field and should not modify the value placed there or modify it. .Pp The .Sy uex_flags -member is an enumeration that defines a number of flags. Each flag -indicates whether or not a given member is present or valid. Before -accessing any member other than +member is an enumeration that defines a number of flags. +Each flag indicates whether or not a given member is present or valid. +Before accessing any member other than .Sy uex_ep , the device driver should check the flag here, otherwise its contents may -be undefined. Currently the following flags are defined: +be undefined. +Currently the following flags are defined: .Bl -tag -width Sy -offset indent .It Sy USB_EP_XFLAGS_SS_COMP Indicates that a SuperSpeed endpoint companion descriptor is present and -has been filled in. The member +has been filled in. +The member .Sy uex_ep_ss is valid. .El .Pp The .Sy uex_ep -member contains a traditional USB endpoint descriptor. Its contents are -defined in +member contains a traditional USB endpoint descriptor. +Its contents are defined in .Xr usb_ep_descr 9S . There is no flag for this member in .Sy uex_flags , diff --git a/usr/src/man/man9s/usba_device.9s b/usr/src/man/man9s/usba_device.9s index cb1fa5453f..036e50feed 100644 --- a/usr/src/man/man9s/usba_device.9s +++ b/usr/src/man/man9s/usba_device.9s @@ -24,30 +24,33 @@ .Sy Volatile - illumos USB HCD private .Pp -This is a private data structure that is not part of the stable DDI. It -may be removed or changed at any time. +This is a private data structure that is not part of the stable DDI. +It may be removed or changed at any time. .Sh DESCRIPTION The .Sy usba_device_t structure is used by the illumos USB Architecture (USBA) to represent a -physical USB device. While a given USB device may be a composite device, -a USB device that implements two or more classes, there will still only -be a single device structure. A USB device is always plugged into a -port on some hub, excepting the root hub, and has an address on the USB -fabric. +physical USB device. +While a given USB device may be a composite device, a USB device that implements +two or more classes, there will still only be a single device structure. +A USB device is always plugged into a port on some hub, excepting the root hub, +and has an address on the USB fabric. .Pp Many of the USB HCD driver operations pass a .Sy usba_device_t -to the HCD driver. The +to the HCD driver. +The .Sy usba_device_t should be used by an HCD driver in a .Em read-only -fashion. A subset of the structure's fields that are useful for HCD -drivers to read are listed below. +fashion. +A subset of the structure's fields that are useful for HCD drivers to read are +listed below. .Pp In addition, there are two optional HCD entry points that interact with this structure and give the change for a driver to store per-device -state. If the driver implements the +state. +If the driver implements the .Xr usba_hcdi_device_init 9E and .Xr usba_hcdi_device_fini 9E @@ -77,9 +80,11 @@ The .Sy usb_dip member is a pointer to the device's .Sy dev_info_t -structure. This generally is used if the HCD driver wants to get naming -information for diagnostic purposes. When duplicating requests for -isochronous and interrupt requests, HCD drivers should use the +structure. +This generally is used if the HCD driver wants to get naming information for +diagnostic purposes. +When duplicating requests for isochronous and interrupt requests, HCD drivers +should use the .Sy dev_info_t from the .Xr usba_pipe_handle_data_t 9S . @@ -88,7 +93,8 @@ The .Sy usb_hubdi member can be used to determine whether or not the .Sy usba_device_t -in question is a hub or not. HCD drivers should compare this member to +in question is a hub or not. +HCD drivers should compare this member to .Dv NULL . If the member is not .Dv NULL , @@ -100,7 +106,8 @@ member indicates the address of the USB device on the broader USB bus. Note, that the actual address assigned to the device may be different, especially if the HCD driver implements the optional .Xr usba_hcdi_device_address 9E -entry point. See the section +entry point. +See the section .Sy USB addressing in .Xr usba_hcdi 9E @@ -108,13 +115,14 @@ for more information. .Pp The .Sy usb_dev_descr -member points to the device descriptor for a given device. This -structure is documented in +member points to the device descriptor for a given device. +This structure is documented in .Xr usb_dev_descr 9S . This member may be .Dv NULL as it may not have been populated during device -attachment. This member may be +attachment. +This member may be .Dv NULL . HCD drivers should always check for .Dv NULL @@ -123,7 +131,8 @@ before dereferencing it. The .Sy usb_mfg_str member may contain a pointer to a character string with the name of the -manufacturer as retrieved from the device. This member may be +manufacturer as retrieved from the device. +This member may be .Dv NULL . HCD drivers should always check for .Dv NULL @@ -132,7 +141,8 @@ before dereferencing it. The .Sy usb_product_str member may contain a pointer to a character string with the name of the -product as retrieved from the device. This member may be +product as retrieved from the device. +This member may be .Dv NULL . HCD drivers should always check for .Dv NULL @@ -141,43 +151,47 @@ before dereferencing it. The .Sy usb_serialno_str member may contain a pointer to a character string with the serial -number of the device as retrieved from the device. This member may be +number of the device as retrieved from the device. +This member may be .Dv NULL . HCD drivers should always check for .Dv NULL before dereferencing it. .Pp The -.Sy usb_port_status_t +.Sy usb_port_status contains a -.Xr usb_port_status_t -entry, which describes the current negotiated speed of the device. See +.Xr usb_port_status_t 9T +entry, which describes the current negotiated speed of the device. +See .Xr usb_port_status_t 9T for more information on the values and types. .Pp The .Sy usb_port -member contains the port on a hub that the device is plugged into. Ports -are always numbered starting at 1. +member contains the port on a hub that the device is plugged into. +Ports are always numbered starting at 1. .Pp The .Sy usb_hs_hub_usba_dev -member is set when there is a parent high-speed hub. This is most -notable for low- and full- speed devices which require split -transaction support. This points to the +member is set when there is a parent high-speed hub. +This is most notable for low- and full- speed devices which require split +transaction support. +This points to the .Sy usb_device_t -structure that is the closest high-speed parent hub. This member should +structure that is the closest high-speed parent hub. +This member should always be set to .Dv NULL -for super-speed devices. A device operating a super-speed can never be -plugged into a high-speed hub. +for super-speed devices. +A device operating a super-speed can never be plugged into a high-speed hub. .Pp The .Sy usb_parent_hub member points to the .Sy usba_device_t -structure that the device in question is plugged into. If the device -represents the root hub, then this field will be +structure that the device in question is plugged into. +If the device represents the root hub, then this field will be .Dv NULL . .Sh SEE ALSO .Xr usba_hcdi 9E , diff --git a/usr/src/man/man9s/usba_hcdi_ops.9s b/usr/src/man/man9s/usba_hcdi_ops.9s index c1b8df0423..87e2ac3a8b 100644 --- a/usr/src/man/man9s/usba_hcdi_ops.9s +++ b/usr/src/man/man9s/usba_hcdi_ops.9s @@ -24,13 +24,14 @@ .Sy Volatile - illumos USB HCD private .Pp -This is a private data structure that is not part of the stable DDI. It -may be removed or changed at any time. +This is a private data structure that is not part of the stable DDI. +It may be removed or changed at any time. .Sh DESCRIPTION The .Sy usba_hcdi_ops structure is usbed HCD drivers to register operations vectors and -callbacks from the USBA HCD interface. See +callbacks from the USBA HCD interface. +See .Xr usba_hcdi 9E for more information on USB HCD device drivers. .Pp @@ -100,8 +101,8 @@ int (*usba_hcdi_hub_update)(usba_device_t *, uint8_t, uint8_t); .Pp The .Sy usba_hcdi_ops_version -member is used to indicate the revision of the operations vector. HCD -drivers should generally set this to +member is used to indicate the revision of the operations vector. +HCD drivers should generally set this to .Dv HCDI_OPS_VERSION . .Pp The @@ -113,7 +114,8 @@ structure of the HCD driver that was received in .Pp The .Sy usba_hcdi_pm_support -member is vestigial. If may be set to +member is vestigial. +If may be set to .Dv NULL or to a function which only returns .Sy USB_FAILURE . @@ -122,7 +124,8 @@ The .Sy usba_hcdi_pipe_open member should be set to a function which takes care of the all of the controller-specific actions of opening up an endpoint on a device and -associating it with the pipe. See +associating it with the pipe. +See .Xr usba_hcdi_pipe_open 9E for more information. .Pp @@ -130,8 +133,10 @@ The .Sy usba_hcdi_pipe_close member should be set to a function which takes care of releasing all of the controller-specific resources and actions taken when the pipe was -opened. This function also has the responsibility to clean up any -outstanding polling on the endpoint. See +opened. +This function also has the responsibility to clean up any outstanding polling on +the endpoint. +See .Xr usba_hcdi_pipe_close 9E for more information. .Pp @@ -139,7 +144,8 @@ The .Sy usba_hcdi_pipe_reset member should be set to a function that takes care of resetting a pipe. A pipe reset not only performs controller-specific functionality, but it -also cleans up any outstanding requests and terminates polling. See +also cleans up any outstanding requests and terminates polling. +See .Xr usba_hcdi_pipe_reset 9E for more information. .Pp @@ -151,7 +157,8 @@ toggle, if the controller exposes this functionality to the host. The .Sy usba_hcdi_pipe_ctrl_xfer member should be set to a function that handles control transfers for any -device, including the root hub. See +device, including the root hub. +See .Xr usba_hcdi_pipe_ctrl_xfer 9E for more information. .Pp @@ -171,38 +178,42 @@ for more information. The .Sy usba_hcdi_pipe_intr_xfer member should be set to a function which performs interrupt transfers. -These may be both periodic and one-shot transfers. In addition, this may -need to handle requests for the root hub. See +These may be both periodic and one-shot transfers. +In addition, this may need to handle requests for the root hub. +See .Xr usba_hcdi_pipe_intr_xfer 9E for more information. .Pp The .Sy usba_hcdi_pipe_stop_intr_polling member should be set to a function which is used to terminate interrupt -polling and return the original interrupt request. See +polling and return the original interrupt request. +See .Xr usba_hcdi_pipe_stop_intr_polling 9E for more information. .Pp The .Sy usba_hcdi_pipe_isoc_xfer member should be set to a function which performs isochronous transfers. -These may be both periodic and one-shot transfers. See +These may be both periodic and one-shot transfers. +See .Xr usba_hcdi_pipe_isoc_xfer 9E for more information. .Pp The .Sy usba_hcdi_pipe_stop_isoc_polling member should be set to a function which is used to terminate isochronous -polling and return the original isochronous request. See +polling and return the original isochronous request. +See .Xr usba_hcdi_pipe_stop_isoc_polling 9E for more information. .Pp The .Sy usba_hcdi_get_current_frame_number member should be set to a function which returns the current virtual -frame number. While this entry point is required, at this time, nothing -uses this functionality in illumos, so having a dummy function which -just returns +frame number. +While this entry point is required, at this time, nothing uses this +functionality in illumos, so having a dummy function which just returns .Sy USB_FAILURE is acceptable. .Pp @@ -219,9 +230,10 @@ The and .Sy usba_hcdi_console_input_exit members are used to facilitate a USB device acting as the system console -and reading input from it. Support for this is optional in an HCD -driver. HCD drivers which do not support this functionality should have -functions which return +and reading input from it. +Support for this is optional in an HCD driver. +HCD drivers which do not support this functionality should have functions which +return .Sy USB_FAILURE . .Pp The @@ -232,9 +244,10 @@ The and .Sy usba_hcdi_console_output_exit members are used to facilitate a USB device acting as the system console -and outputting data to it. Support for this is optional in an HCD -driver. HCD drivers which do not support this functionality should have -functions which return +and outputting data to it. +Support for this is optional in an HCD driver. +HCD drivers which do not support this functionality should have functions which +return .Sy USB_FAILURE . .Pp The @@ -242,8 +255,8 @@ The member is an .Em optional entry point that will be called every time a new device is initialized -and detected by the system. If an HCD does not need this functionality, -the member should be set to +and detected by the system. +If an HCD does not need this functionality, the member should be set to .Dv NULL . See .Xr usba_hcdi_device_init 9E @@ -256,8 +269,8 @@ member is an entry point that will be called every time a device is removed from the system, whether through it being unplugged or a .Xr cfgadm 1M -action. If an HCD does not need this functionality, -the member should be set to +action. +If an HCD does not need this functionality, the member should be set to .Dv NULL . See .Xr usba_hcdi_device_fini 9E @@ -268,8 +281,8 @@ The member is an .Em optional entry point that will be called every time a USB device needs to be -addressed. If an HCD driver does not need this functionality, the member -should be set to +addressed. +If an HCD driver does not need this functionality, the member should be set to .Dv NULL . See .Xr usba_hcdi_device_address 9E @@ -280,10 +293,10 @@ The member is an .Em optional entry point that will be called every time a device descriptor is read -that turns out to be a hub. This gives HCD drivers a chance to perform -any needed controller-specific functionality before the device is -used. If an HCD driver does not need this functionality, the member -should be set to +that turns out to be a hub. +This gives HCD drivers a chance to perform any needed controller-specific +functionality before the device is used. +If an HCD driver does not need this functionality, the member should be set to .Dv NULL . See .Xr usba_hcdi_hub_update 9E diff --git a/usr/src/man/man9s/usba_hcdi_register_args.9s b/usr/src/man/man9s/usba_hcdi_register_args.9s index bdb564d07d..068e826103 100644 --- a/usr/src/man/man9s/usba_hcdi_register_args.9s +++ b/usr/src/man/man9s/usba_hcdi_register_args.9s @@ -24,8 +24,8 @@ .Sy Volatile - illumos USB HCD private .Pp -This is a private data structure that is not part of the stable DDI. It -may be removed or changed at any time. +This is a private data structure that is not part of the stable DDI. +It may be removed or changed at any time. .Sh DESCRIPTION The .Sy usba_hcdi_register_args_t @@ -34,9 +34,9 @@ framework. .Pp The structure is used with the .Xr usba_hcdi_register 9F -function. Device drivers may statically allocate this structure on the -stack. It does not need to be allocated on the heap or used beyond the -call to +function. +Device drivers may statically allocate this structure on the stack. +It does not need to be allocated on the heap or used beyond the call to .Xr usba_hcdi_register 9F . .Pp For more information on the HCD device driver initialization process, @@ -59,8 +59,8 @@ The function should be set to the value of the pre-processor macro .Sy HCDI_REGISTER_VERSION . This ensures that if future revisions to this structure are made, -existing drivers should continue to function. Note, that this structure -is +existing drivers should continue to function. +Note, that this structure is .Sy Volatile . Support for older versions or drastic changes may occur at any time and this should not be relied on nor construed as a guarantee against such @@ -75,7 +75,8 @@ of the device driver instance that is registering with the USBA. The .Sy usba_hcdi_register_ops member is a structure of entry points for the USBA framework to call -into the USB framework. It should be allocated with a call to +into the USB framework. +It should be allocated with a call to .Xr usba_alloc_hcdi_ops 9F and released with a call to .Xr usba_free_hcdi_ops 9F , @@ -89,17 +90,17 @@ information on how they should be filled in. .Pp The .Sy usba_hcdi_register_dma_attr -member should be a pointer to a set of DMA attributes. These DMA -attributes will be used by a subset of client device drivers to perform -allocations, in particular scsa2usb. In general, try to make sure that -these DMA attributes are valid for more transforms, though these will -generally be used for bulk transfers. +member should be a pointer to a set of DMA attributes. +These DMA attributes will be used by a subset of client device drivers to +perform allocations, in particular scsa2usb. +In general, try to make sure that these DMA attributes are valid for more +transforms, though these will generally be used for bulk transfers. .Pp The .Sy usba_hcdi_register_iblock_cookie members should be filed in with the general interrupt priority of the -device driver after it has allocated interrupts. Device drivers may -obtain the priority by calling +device driver after it has allocated interrupts. +Device drivers may obtain the priority by calling .Xr ddi_intr_get_pri 9F and then casting the obtained interrupt priority to the .Sy ddi_iblock_cookie_t . diff --git a/usr/src/man/man9s/usba_pipe_handle_data.9s b/usr/src/man/man9s/usba_pipe_handle_data.9s index aed8e36fb6..57d98441fd 100644 --- a/usr/src/man/man9s/usba_pipe_handle_data.9s +++ b/usr/src/man/man9s/usba_pipe_handle_data.9s @@ -15,7 +15,7 @@ .Dt USBA_PIPE_HANDLE_DATA 9S .Os .Sh NAME -.Nm usba_pipe_handle_data +.Nm usba_pipe_handle_data , .Nm usba_pipe_handle_data_t .Nd USBA Pipe Handle Data Structure .Sh SYNOPSIS @@ -24,24 +24,26 @@ .Sy Volatile - illumos USB HCD private .Pp -This is a private data structure that is not part of the stable DDI. It -may be removed or changed at any time. +This is a private data structure that is not part of the stable DDI. +It may be removed or changed at any time. .Sh DESCRIPTION The .Sy usba_pipe_handle_data structure is the USB architecture's (USBA) way of representing a pipe. -Every pipe is a part of a USB device. Pipe's may be shared between -client drivers or be exclusive to one. For more background on pipe's -see the +Every pipe is a part of a USB device. +Pipe's may be shared between client drivers or be exclusive to one. +For more background on pipe's see the .Sy USB Endpoint Background section of .Xr usba_hcdi 9E . .Pp This structure is provided to HCD driver's when performing requests of -various kinds. The majority of the structures listed here are +various kinds. +The majority of the structures listed here are .Em read-only ; however, HCD drivers are allowed to update a single member, listed -below. All of the writable members are protected by a lock, the member +below. +All of the writable members are protected by a lock, the member .Sy p_mutex . See the .Sy Locking @@ -50,13 +52,13 @@ section in for more information on lock ordering and when HCD drivers should enter this lock. .Pp -A pipe handle has an explicit life cycle wih a device driver. The driver -first sees the pipe handle when its +A pipe handle has an explicit life cycle wih a device driver. +The driver first sees the pipe handle when its .Xr usba_hcdi_pipe_open 9E -entry point is called. At that time, the HCD driver has the change to -store private data on the handle. This pipe handle will be used in -subsequent requests until the handle is closed, through a call to the -HCD driver's +entry point is called. +At that time, the HCD driver has the change to store private data on the handle. +This pipe handle will be used in subsequent requests until the handle is closed, +through a call to the HCD driver's .Xr usba_hcdi_pipe_close 9E entry point. .Sh STRUCTURE MEMBERS @@ -77,19 +79,21 @@ The .Sy p_usba_device member points to the .Xr usba_device 9S -structure that this pipe belongs to. This member should always be set -for an endpoint handed to an HCD driver. +structure that this pipe belongs to. +This member should always be set for an endpoint handed to an HCD driver. .Pp The .Sy p_ep member is filled in with the endpoint descriptor that represents this -device. The endpoint structure is documented in +device. +The endpoint structure is documented in .Xr usb_ep_descr 9S . .Pp The .Sy p_xep member is filled in with the endpoint descriptor and any additional -endpoint descriptors that may exist. The structure is documented in +endpoint descriptors that may exist. +The structure is documented in .Xr usb_ep_xdescr 9S . The endpoint descriptor is the same in both .Sy p_ep @@ -98,11 +102,12 @@ and .Pp The .Sy p_hcd_private -member is reserved for use with HCD drivers. An HCD driver may set -this member during +member is reserved for use with HCD drivers. +An HCD driver may set this member during .Xr usba_hcdi_pipe_open 9E . If set, it can reference this member throughout the life time of the -pipe. The driver should ensure to clean it up when its +pipe. +The driver should ensure to clean it up when its .Xr usba_hcdi_pipe_close 9E entry point is called. .Pp @@ -114,8 +119,8 @@ The mutex should be entered whenever the value is being manipulated. .Pp The .Sy p_req_count -member indicates the number of outstanding requests on the pipe. When -performing +member indicates the number of outstanding requests on the pipe. +When performing .Em periodic interrupt or isochronous transfers, it is the responsibility of the HCD driver to increment the value of @@ -131,9 +136,10 @@ member. .Pp The HCD driver should take special care to ensure that the value of .Sy p_req_count -is always greater than one. There should always be an outstanding -request that an HCD driver has for the pipe, especially if it is a -periodic endpoint. It should only manipulate this member while it owns +is always greater than one. +There should always be an outstanding request that an HCD driver has for the +pipe, especially if it is a periodic endpoint. +It should only manipulate this member while it owns .Sy p_mutex . .Sh SEE ALSO .Xr usba_hcdi_pipe_close 9E , |