'\" 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]
.TH usb_pipe_bulk_xfer 9F "3 Aug 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_pipe_bulk_xfer \- USB bulk transfer function
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>



\fBint\fR \fBusb_pipe_bulk_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, 
     \fBusb_bulk_req_t *\fR\fIrequest\fR, \fBusb_flags_t\fR \fIflags\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIpipe_handle\fR\fR
.ad
.RS 15n
.rt  
Bulk pipe handle on which request is made.
.RE

.sp
.ne 2
.mk
.na
\fB\fIrequest\fR\fR
.ad
.RS 15n
.rt  
Pointer to bulk transfer request.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 15n
.rt  
USB_FLAGS_SLEEP is the only flag recognized. Wait for request to complete.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBusb_pipe_bulk_xfer()\fR 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.
.sp
.LP
Requests for bulk transfers must have mblks attached to store data. Allocate an
mblk for data when a request is allocated via \fBusb_alloc_bulk_req\fR(9F) by
passing a non-negative value for the \fIlen\fR argument.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 25n
.rt  
Transfer was successful.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 25n
.rt  
Request is \fBNULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_CONTEXT\fR
.ad
.RS 25n
.rt  
Called from interrupt context with the USB_FLAGS_SLEEP flag set.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_REQUEST\fR
.ad
.RS 25n
.rt  
The request has been freed or otherwise invalidated.
.sp
A set of conflicting attributes were specified. See \fBusb_bulk_request\fR(9S).
.sp
The normal and/or exception callback was NULL and USB_FLAGS_SLEEP was not set.
.sp
Data space is not provided to a non-zero length bulk request:
.sp
.in +2
.nf
(bulk_data == NULL and bulk_len != 0)
.fi
.in -2

.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_PIPE\fR
.ad
.RS 25n
.rt  
Pipe handle is NULL or invalid.
.sp
Pipe is closing or closed.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_PIPE_ERROR\fR
.ad
.RS 25n
.rt  
Pipe handle refers to a pipe which is in the USB_PIPE_STATE_ERROR state.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_NO_RESOURCES\fR
.ad
.RS 25n
.rt  
Memory, descriptors or other resources are unavailable.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_HC_HARDWARE_ERROR\fR
.ad
.RS 25n
.rt  
Host controller is in error state.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_FAILURE\fR
.ad
.RS 25n
.rt  
An asynchronous transfer failed or an internal error occurred.
.sp
A bulk request requested too much data:
.sp
.in +2
.nf
(length > usb_get_max_bulk_xfer size())
.fi
.in -2

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

.sp
.LP
Additional status information may be available in the bulk_completion_reason
and bulk_cb_flags fields of the request. Please see
\fBusb_completion_reason\fR(9S) and \fBusb_callback_flags\fR(9S) for more
information.
.SH CONTEXT
.sp
.LP
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.
.SH EXAMPLES
.sp
.in +2
.nf
   /* 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));
    }
                
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
ArchitecturePCI-based systems
_
Interface stabilityCommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBusb_alloc_request\fR(9F), \fBusb_get_cfg\fR(9F),
\fBusb_get_status\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F),
\fBusb_pipe_get_state\fR(9F), \fBusb_pipe_intr_xfer\fR(9F),
\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_pipe_open\fR(9F),
\fBusb_pipe_reset\fR(9F), \fBusb_bulk_request\fR(9S),
\fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S),
\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S),
\fBusb_isoc_request\fR(9S)