man/man9e/usba_hcdi_pipe_ctrl_xfer.9e

.\"
.\" 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 Dec 22, 2016
.Dt USBA_HCDI_PIPE_CTRL_XFER 9E
.Os
.Sh NAME
.Nm usba_hcdi_pipe_ctrl_xfer
.Nd perform a USB control transfer
.Sh SYNOPSIS
.In sys/usb/usba/hcdi.h
.Ft int
.Fo prefix_hcdi_pipe_ctrl_xfer
.Fa "usba_pipe_handle_data_t *ph"
.Fa "usb_ctrl_req_t *ucrp"
.Fa "usb_flags_t usb_flags"
.Fc
.Sh INTERFACE LEVEL
.Sy Volatile -
illumos USB HCD private function
.Pp
This is a private function that is not part of the stable DDI. It may be
removed or changed at any time.
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa ph
A pointer to a USB pipe handle as defined in
.Xr usba_pipe_handle_data 9S .
.It Fa ucrp
A pointer to a USB control transfer request. The structure's members are
documented in
.Xr usb_ctrl_req 9S .
.It Fa usb_flags
Flags which describe how allocations should be performed. Valid flags
are:
.Bl -tag -width Sy
.It Sy USB_FLAGS_NOSLEEP
Do not block waiting for memory. If memory is not available the allocation
will fail.
.It Sy USB_FLAGS_SLEEP
Perform a blocking allocation. If memory is not available, the function
will wait until memory is made available.
.Pp
Note, the request may still fail even if
.Sy USB_FLAGS_SLEEP
is specified.
.El
.El
.Sh DESCRIPTION
The
.Fn usba_hcdi_pipe_ctrl_xfer
entry point is used to initiate an
.Em asynchronous
USB Control transfer on the pipe
.Fa ph .
The specific USB control transfer is provided in
.Fa ucrp .
For more background on transfer types, see
.Xr usba_hcdi 9E .
.Pp
The host controller driver should first check the USB address of the
pipe handle. It may correspond to the root hub. If it does, rather than
initiating an I/O transfer, the driver may need to emulate it using
available information.
.Pp
Control endpoints are always bi-directional. A given endpoint may
perform transfer data from the OS to the device, or from the device to
the OS. The driver will need to look at the control transfer request and
transform that into the appropriate format for the controller.
.Pp
Control transfers are made up of three parts. A setup stage, an optional
data stage, and a status stage. Depending on the controller, the driver
may need to transform the transfer request into a format that matches
this. Refer to the device's controller specification for more
information on whether this is required or not.
.Pp
The device driver should a request based on the information present in
the control request
.Fa ucrp .
If there is a non-zero length for the transfer, indicated by the
.Sy ctrl_wLength
member of
.Fa ucrp
being greater than zero, then the controller needs to allocate a
separate memory buffer for the request. The corresponding data will be
found in an
.Xr mblk 9S
structure as the
.Sy ctrl_data
member of
.Fa ucrp .
.Pp
If this transfer needs to be sent to a device through the controller and
is not being handled directly by the driver, then the driver should
allocate a separate region of memory (generally memory suitable for a
DMA transfer) for the transfer. If sending data to the device, the data
in the message block should be copied prior to the transfer. Otherwise,
once the transfer completes, data should be transferred into the message
block and the write pointer incremented.
.Pp
If the driver needs to allocate memory for this transfer, it should
honor the values set in
.Fa usb_flags
to indicate whether or not it should block for memory, whether DMA
memory or normal kernel memory.
.Pp
If the driver successfully schedules the I/O or it can handle the I/O
itself because it's a synthetic root hub request, then it should return
.Sy USB_SUCCESS .
If the driver returns successfully, it must call
.Xr usba_hcdi_cb 9F
with
.Fa ucrp
either before or after it returns. The only times that a driver would
call the callback before the function returns are for requests to the
root hub that it handles inline and does not need to send off
asynchronous activity to the controller.
.Pp
For asynchronous requests, the controller is also responsible for
timing out the request if it does not complete. If the timeout in the
request as indicated in the
.Sy ctrl_timeout
member is set to zero, then the driver should use the USBA default
timeout of
.Sy HCDI_DEFAULT_TIMEOUT .
All timeout values are in
.Em seconds .
.Ss Callback Handling
When the control transfer completes the driver should consider the
following items to determine what actions it should take on the callback:
.Bl -bullet
.It
If the transfer timed out, it should remove the transfer from the
outstanding list, queue the next transfer, and return the transfer back
to the OS with the error code
.Sy USB_CR_TIMEOUT
with
.Xr usba_hcdi_cb 9F .
.It
If the transfer failed, it should find the appropriate error and call
.Xr usba_hcdi_cb 9F
with that error.
.It
If the transfer succeeded, but less data was transferred than expected,
consult the
.Sy ctrl_attributes
member of the
.Fa ucrp .
If the
.Sy USB_ATTRS_SHORT_XFER_OK
flag is not present, then the driver should call
.Xr usba_hcdi_cb 9F
with the error
.Sy USB_CR_DATA_UNDERRUN .
.It
If the transfer was going to the host, then the driver should copy the
data into the transfer's message block and update the
.Sy b_wptr
member of the
.Xr mblk 9S .
.It
If everything was successful, call
.Xr usba_hcdi_cb 9F
with the code
.Sy USB_CR_OK .
.El
.Sh RETURN VALUES
Upon successful completion, the
.Fn usba_hcdi_pipe_ctrl_xfer
function should return
.Sy USB_SUCCESS .
Otherwise, it should return the appropriate USB error. If uncertain, use
.Sy USB_FAILURE .
.Sh SEE ALSO
.Xr usba_hcdi 9E ,
.Xr usba_hcdi_cb 9F ,
.Xr mblk 9S ,
.Xr usb_ctrl_req 9S ,
.Xr usba_pipe_handle_data 9S