'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
.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
_
Availabilitysystem/io/usb
.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)