xref: /titanic_44/usr/src/man/man9f/usb_pipe_bulk_xfer.9f (revision 75d94465dbafa487b716482dc36d5150a4ec9853)
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 "Aug 3, 2006"
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

Solaris DDI specific (Solaris 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(5) for descriptions of the following attributes:

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

attributes(5), 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_open(9F), usb_pipe_reset(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)