usb_pipe_bulk_xfer(9f)

1usb_pipe_bulk_xfer(9F)   Kernel Functions for Drivers   usb_pipe_bulk_xfer(9F)
2
3
4

NAME

6       usb_pipe_bulk_xfer - USB bulk transfer function
7

SYNOPSIS

9       #include <sys/usb/usba.h>
10
11
12
13       int usb_pipe_bulk_xfer(usb_pipe_handle_t pipe_handle,
14            usb_bulk_req_t *request, usb_flags_t flags);
15
16

INTERFACE LEVEL

18       Solaris DDI specific (Solaris DDI)
19

PARAMETERS

21       pipe_handle    Bulk pipe handle on which request is made.
22
23
24       request        Pointer to bulk transfer request.
25
26
27       flags          USB_FLAGS_SLEEP  is  the  only flag recognized. Wait for
28                      request to complete.
29
30

DESCRIPTION

32       The usb_pipe_bulk_xfer() function requests the USBA framework  to  per‐
33       form  a  transfer through a USB bulk pipe. The request is passed to the
34       host controller driver (HCD), which performs the necessary transactions
35       to  complete the request. Requests are synchronous when USB_FLAGS_SLEEP
36       has been specified in flags. Calls for synchronous  requests  will  not
37       return  until  their  transaction  has completed. Asynchronous requests
38       (made without specifying the USB_FLAGS_SLEEP flag) notify the caller of
39       their completion via a callback function.
40
41
42       Requests  for  bulk  transfers  must have mblks attached to store data.
43       Allocate  an  mblk  for  data  when  a   request   is   allocated   via
44       usb_alloc_bulk_req(9F)  by  passing  a  non-negative  value for the len
45       argument.
46

RETURN VALUES

48       USB_SUCCESS              Transfer was successful.
49
50
51       USB_INVALID_ARGS         Request is NULL.
52
53
54       USB_INVALID_CONTEXT      Called  from  interrupt   context   with   the
55                                USB_FLAGS_SLEEP flag set.
56
57
58       USB_INVALID_REQUEST      The request has been freed or otherwise inval‐
59                                idated.
60
61                                A set of conflicting  attributes  were  speci‐
62                                fied. See usb_bulk_request(9S).
63
64                                The  normal and/or exception callback was NULL
65                                and USB_FLAGS_SLEEP was not set.
66
67                                Data space  is  not  provided  to  a  non-zero
68                                length bulk request:
69
70                                  (bulk_data == NULL and bulk_len != 0)
71
72
73
74       USB_INVALID_PIPE         Pipe handle is NULL or invalid.
75
76                                Pipe is closing or closed.
77
78
79       USB_PIPE_ERROR           Pipe  handle  refers to a pipe which is in the
80                                USB_PIPE_STATE_ERROR state.
81
82
83       USB_NO_RESOURCES         Memory, descriptors  or  other  resources  are
84                                unavailable.
85
86
87       USB_HC_HARDWARE_ERROR    Host controller is in error state.
88
89
90       USB_FAILURE              An asynchronous transfer failed or an internal
91                                error occurred.
92
93                                A bulk request requested too much data:
94
95                                  (length > usb_get_max_bulk_xfer size())
96
97                                The pipe is  in  a  unsuitable  state  (error,
98                                busy, not ready).
99
100
101
102       Additional  status  information  may  be  available in the bulk_comple‐
103       tion_reason  and  bulk_cb_flags  fields  of  the  request.  Please  see
104       usb_completion_reason(9S)  and usb_callback_flags(9S) for more informa‐
105       tion.
106

CONTEXT

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

EXAMPLES

113            /* Allocate, initialize and issue a synchronous bulk request. */
114
115             usb_bulk_req_t bulk_req;
116             mblk_t *mblk;
117
118             bulk_req = usb_alloc_bulk_req(dip, bp->b_bcount, USB_FLAGS_SLEEP);
119
120             bulk_req->bulk_attributes   = USB_ATTRS_AUTOCLEARING;
121             mblk = bulk_req->bulk_data;
122             bcopy(buffer, mblk->b_wptr, bp->b_bcount);
123             mblk->b_wptr += bp->b_bcount;
124
125             if ((rval = usb_pipe_bulk_xfer(pipe, bulk_req, USB_FLAGS_SLEEP))
126                 != USB_SUCCESS) {
127                     cmn_err (CE_WARN, "%s%d: Error writing bulk data.",
128                         ddi_driver_name(dip), ddi_get_instance(dip));
129             }
130
131
132

ATTRIBUTES

134       See attributes(5) for descriptions of the following attributes:
135
136
137
138
139       ┌─────────────────────────────┬─────────────────────────────┐
140       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
141       ├─────────────────────────────┼─────────────────────────────┤
142       │Architecture                 │PCI-based systems            │
143       ├─────────────────────────────┼─────────────────────────────┤
144       │Interface stability          │Committed                    │
145       ├─────────────────────────────┼─────────────────────────────┤
146       │Availability                 │SUNWusb                      │
147       └─────────────────────────────┴─────────────────────────────┘
148