te
 Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
 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]
 USB_PIPE_BULK_XFER 9F "Sep 16, 2016"
 NAME
usb_pipe_bulk_xfer - USB bulk transfer function

 SYNOPSIS
#include <sys/usb/usba.h>



int usb_pipe_bulk_xfer(usb_pipe_handle_t pipe_handle,
 usb_bulk_req_t *request, usb_flags_t flags);




 INTERFACE LEVEL
illumos DDI specific (illumos DDI)

 PARAMETERS
pipe_handle


Bulk pipe handle on which request is made.



request


Pointer to bulk transfer request.



flags


USB_FLAGS_SLEEP is the only flag recognized. Wait for request to complete.




 DESCRIPTION
The usb_pipe_bulk_xfer() function requests the USBA framework to perform
a transfer through a USB bulk pipe. The request is passed to the host
controller driver (HCD), which performs the necessary transactions to complete
the request. Requests are synchronous when USB_FLAGS_SLEEP has been specified
in flags. Calls for synchronous requests will not return until their
transaction has completed. Asynchronous requests (made without specifying the
USB_FLAGS_SLEEP flag) notify the caller of their completion via a callback
function.


Requests for bulk transfers must have mblks attached to store data. Allocate an
mblk for data when a request is allocated via usb_alloc_bulk_req(9F) by
passing a non-negative value for the len argument.

 RETURN VALUES
USB_SUCCESS


Transfer was successful.



USB_INVALID_ARGS


Request is NULL.



USB_INVALID_CONTEXT


Called from interrupt context with the USB_FLAGS_SLEEP flag set.



USB_INVALID_REQUEST


The request has been freed or otherwise invalidated.
A set of conflicting attributes were specified. See usb_bulk_request(9S).
The normal and/or exception callback was NULL and USB_FLAGS_SLEEP was not set.
Data space is not provided to a non-zero length bulk request:

(bulk_data == NULL and bulk_len != 0)






USB_INVALID_PIPE


Pipe handle is NULL or invalid.
Pipe is closing or closed.



USB_PIPE_ERROR


Pipe handle refers to a pipe which is in the USB_PIPE_STATE_ERROR state.



USB_NO_RESOURCES


Memory, descriptors or other resources are unavailable.



USB_HC_HARDWARE_ERROR


Host controller is in error state.



USB_FAILURE


An asynchronous transfer failed or an internal error occurred.
A bulk request requested too much data:

(length > usb_get_max_bulk_xfer size())



The pipe is in a unsuitable state (error, busy, not ready).





Additional status information may be available in the bulk_completion_reason
and bulk_cb_flags fields of the request. Please see
usb_completion_reason(9S) and usb_callback_flags(9S) for more
information.

 CONTEXT
May be called from kernel or user context without regard to arguments. May be
called from interrupt context only when the USB_FLAGS_SLEEP flag is clear.

 EXAMPLES
 /* Allocate, initialize and issue a synchronous bulk request. */

 usb_bulk_req_t bulk_req;
 mblk_t *mblk;

 bulk_req = usb_alloc_bulk_req(dip, bp->b_bcount, USB_FLAGS_SLEEP);

 bulk_req->bulk_attributes = USB_ATTRS_AUTOCLEARING;
 mblk = bulk_req->bulk_data;
 bcopy(buffer, mblk->b_wptr, bp->b_bcount);
 mblk->b_wptr += bp->b_bcount;

 if ((rval = usb_pipe_bulk_xfer(pipe, bulk_req, USB_FLAGS_SLEEP))
 != USB_SUCCESS) {
 cmn_err (CE_WARN, "%s%d: Error writing bulk data.",
 ddi_driver_name(dip), ddi_get_instance(dip));
 }





 ATTRIBUTES
See attributes(7) for descriptions of the following attributes:






ATTRIBUTE TYPE ATTRIBUTE VALUE
Architecture PCI-based systems
Interface stability Committed



 SEE ALSO
 attributes (7),  usb_alloc_request (9F),  usb_get_cfg (9F),  usb_get_status (9F),  usb_pipe_ctrl_xfer (9F),  usb_pipe_get_state (9F),  usb_pipe_intr_xfer (9F),  usb_pipe_isoc_xfer (9F),  usb_pipe_reset (9F),  usb_pipe_xopen (9F),  usb_bulk_request (9S),  usb_callback_flags (9S),  usb_completion_reason (9S),  usb_ctrl_request (9S),  usb_intr_request (9S),  usb_isoc_request (9S)