'\" te
.\" Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
.TH usb_pipe_bulk_alloc_streams 9F "05 February 2013" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_pipe_bulk_alloc_streams \- Allocate and set up streams on a USB bulk pipe
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>
.fi

.LP
.nf
\fBint usb_pipe_bulk_alloc_streams\fR(\fBusb_pipe_handle_t *\fR\fIpipe_handle\fR,
\fBuint16_t\fR \fIstream_cnt\fR, \fBusb_flag_t\fR \fIusb_flags\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  
Pointer to a usb bulk pipe handle on which streams are set up.
.RE

.sp
.ne 2
.mk
.na
\fB\fIstream_cnt\fR\fR
.ad
.RS 15n
.rt  
The streams count to allocate.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 15n
.rt  
\fBUSB_FLAGS_SLEEP\fR is the only flag that is recognized. Wait for memory resources if not immediately available.
.RE

.SH DESCRIPTION
.sp
.LP
A standard USB Bulk Pipe represents the ability to move single stream of (FIFO) data between the host and a device via a host memory buffer and a device endpoint. SuperSpeed Streams provide protocol-level support for a multi-stream model and utilize stream pipe communications mode.
.sp
.LP
The \fBusb_pipe_bulk_alloc_streams()\fR function creates and initializes SuperSpeed Streams on a given USB bulk pipe.
.sp
.LP
The USB 3.0 defines that a bulk pipe can support up to 65535 streams. However, host and device may be not able to support all the range. The \fBattributes\fR(5) returns the maximum streams count.
.sp
.LP
All explicit streams allocation is exclusive on a bulk pipe. Attempts to allocate streams on a stream pipe will fail.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fB\fBUSB_SUCCESS\fR\fR
.ad
.RS 23n
.rt  
Streams resource was allocated and streams were set up.
.RE

.sp
.ne 2
.mk
.na
\fB\fBUSB_INVALID_CONTEXT\fR\fR
.ad
.RS 23n
.rt  
Called from interrupt handler with \fBUSB_FLAGS_SLEEP\fR set.
.RE

.sp
.ne 2
.mk
.na
\fB\fBUSB_INVALID_ARGS\fR\fR
.ad
.RS 23n
.rt  
\fBPipe_handle\fR is \fBNULL\fR. The \fIstream_cnt\fR is zero or exceeds the maximum streams count.
.RE

.sp
.ne 2
.mk
.na
\fB\fBUSB_NOT_SUPPORTED\fR\fR
.ad
.RS 23n
.rt  
The host does not support SuperSpeed Streams.
.RE

.sp
.ne 2
.mk
.na
\fB\fBUSB_FAILURE\fR\fR
.ad
.RS 23n
.rt  
Host was not in operational state. Host failed to allocate resources. Streams are already set up.
.RE

.SH CONTEXT
.sp
.LP
The allocation routines can always be called from kernel and user context regardless of arguments. They may be called from interrupt context only if \fBUSB_FLAGS_SLEEP\fR is not specified.
.SH EXAMPLES
.sp
.in +2
.nf
usb_pipe_handle_t *pipe;
           uint16_t stream_cnt;

           /* Open the pipe */
           if (usb_pipe_open(dip, epdescr, &policy, USB_FLAGS_SLEEP,
               pipe) != USB_SUCCESS) {
           }

           /* Decide how many streams can be allocated. */
           if(usb_pipe_bulk_get_max_streams(pipe, &stream_cnt) !=
               USB_SUCCESS) {
           };

           /* Allocate streams resource. */
           if (usb_pipe_bulk_alloc_streams(*pipe, stream_cnt,
               USB_FLAGS_SLEEP) != USB_SUCCESS) {
           }
.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_request_attributes\fR(9S), \fBusb_bulk_request\fR(9S), \fBusb_pipe_bulk_free_streams\fR(9F), \fBusb_pipe_bulk_reset_stream\fR(9F), \fBusb_pipe_open\fR(9F), \fBusb_pipe_close\fR(9F), \fBusb_pipe_reset\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_get_max_bulk_streams\fR(9F), \fBusb_callback_flags\fR(9S)