aboutsummaryrefslogtreecommitdiff
path: root/share/man/man9/usbdi.9
blob: 449058c4ee933f5d8c5050a393e2232f29be1d83 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
.\"
.\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	$FreeBSD$
.Dd June 24, 2009
.Dt USBDI 9
.Os
.Sh NAME
.Nm usb_fifo_alloc_buffer ,
.Nm usb_fifo_attach ,
.Nm usb_fifo_detach ,
.Nm usb_fifo_free_buffer ,
.Nm usb_fifo_get_data ,
.Nm usb_fifo_get_data_buffer ,
.Nm usb_fifo_get_data_error ,
.Nm usb_fifo_get_data_linear ,
.Nm usb_fifo_put_bytes_max ,
.Nm usb_fifo_put_data ,
.Nm usb_fifo_put_data_buffer ,
.Nm usb_fifo_put_data_error ,
.Nm usb_fifo_put_data_linear ,
.Nm usb_fifo_reset ,
.Nm usb_fifo_softc ,
.Nm usb_fifo_wakeup ,
.Nm usbd_do_request ,
.Nm usbd_do_request_flags ,
.Nm usbd_errstr ,
.Nm usbd_lookup_id_by_info ,
.Nm usbd_lookup_id_by_uaa ,
.Nm usbd_transfer_clear_stall ,
.Nm usbd_transfer_drain ,
.Nm usbd_transfer_pending ,
.Nm usbd_transfer_poll ,
.Nm usbd_transfer_setup ,
.Nm usbd_transfer_start ,
.Nm usbd_transfer_stop ,
.Nm usbd_transfer_submit ,
.Nm usbd_transfer_unsetup ,
.Nm usbd_xfer_clr_flag ,
.Nm usbd_xfer_frame_data ,
.Nm usbd_xfer_frame_len ,
.Nm usbd_xfer_get_frame ,
.Nm usbd_xfer_get_priv ,
.Nm usbd_xfer_is_stalled ,
.Nm usbd_xfer_max_framelen ,
.Nm usbd_xfer_max_frames ,
.Nm usbd_xfer_max_len ,
.Nm usbd_xfer_set_flag ,
.Nm usbd_xfer_set_frame_data ,
.Nm usbd_xfer_set_frame_len ,
.Nm usbd_xfer_set_frame_offset ,
.Nm usbd_xfer_set_frames ,
.Nm usbd_xfer_set_interval ,
.Nm usbd_xfer_set_priv ,
.Nm usbd_xfer_set_stall ,
.Nm usbd_xfer_set_timeout ,
.Nm usbd_xfer_softc ,
.Nm usbd_xfer_state ,
.Nm usbd_xfer_status
.Nd Universal Serial Bus driver programming interface
.Sh SYNOPSIS
.In dev/usb/usb.h
.In dev/usb/usbdi.h
.In dev/usb/usbdi_util.h
.Sh DESCRIPTION
The Universal Serial Bus (USB) driver programming interface provides
USB peripheral drivers with a host controller independent API for
controlling and communicating with USB peripherals.
The
.Nm usb
module supports both USB Host and USB Device side mode.
.
.Sh USB KERNEL PROGRAMMING
Here is a list of commonly used functions:
.Pp
.
.Ft "usb_error_t"
.Fo "usbd_transfer_setup"
.Fa "udev"
.Fa "ifaces"
.Fa "pxfer"
.Fa "setup_start"
.Fa "n_setup"
.Fa "priv_sc"
.Fa "priv_mtx"
.Fc
.
.Pp
.
.Ft "void"
.Fo "usbd_transfer_unsetup"
.Fa "pxfer"
.Fa "n_setup"
.Fc
.
.Pp
.
.Ft "void"
.Fo "usbd_transfer_start"
.Fa "xfer"
.Fc
.
.Pp
.
.Ft "void"
.Fo "usbd_transfer_stop"
.Fa "xfer"
.Fc
.
.Pp
.
.Ft "void"
.Fo "usbd_transfer_drain"
.Fa "xfer"
.Fc
.
.
.
.Sh USB TRANSFER MANAGEMENT FUNCTIONS
The USB standard defines four types of USB transfers.
.
Control transfers, Bulk transfers, Interrupt transfers and Isochronous
transfers.
.
All the transfer types are managed using the following five functions:
.
.Pp
.
.Fn usbd_transfer_setup
This function will allocate memory for and initialise an array of USB
transfers and all required DMA memory.
.
This function can sleep or block waiting for resources to become
available.
.Fa udev
is a pointer to "struct usb_device".
.Fa ifaces
is an array of interface index numbers to use. See "if_index".
.Fa pxfer
is a pointer to an array of USB transfer pointers that are initialized
to NULL, and then pointed to allocated USB transfers.
.Fa setup_start
is a pointer to an array of USB config structures.
.Fa n_setup
is a number telling the USB system how many USB transfers should be
setup.
.Fa priv_sc
is the private softc pointer, which will be used to initialize
"xfer->priv_sc".
.Fa priv_mtx
is the private mutex protecting the transfer structure and the
softc. This pointer is used to initialize "xfer->priv_mtx".
This function returns
zero upon success. A non-zero return value indicates failure.
.
.Pp
.
.Fn usbd_transfer_unsetup
This function will release the given USB transfers and all allocated
resources associated with these USB transfers. 
.Fa pxfer
is a pointer to an array of USB transfer pointers, that may be NULL,
that should be freed by the USB system.
.Fa n_setup
is a number telling the USB system how many USB transfers should be
unsetup.
.
This function can sleep waiting for USB transfers to complete.
.
This function is NULL safe with regard to the USB transfer structure
pointer.
.
It is not allowed to call this function from the USB transfer
callback.
.
.Pp
.
.Fn usbd_transfer_start
This function will start the USB transfer pointed to by
.Fa xfer,
if not already started.
.
This function is always non-blocking and must be called with the
so-called private USB mutex locked.
.
This function is NULL safe with regard to the USB transfer structure
pointer.
.
.Pp
.
.Fn usbd_transfer_stop
This function will stop the USB transfer pointed to by
.Fa xfer,
if not already stopped.
.
This function is always non-blocking and must be called with the
so-called private USB mutex locked.
.
This function can return before the USB callback has been called.
.
This function is NULL safe with regard to the USB transfer structure
pointer.
.
If the transfer was in progress, the callback will called with
"USB_ST_ERROR" and "error = USB_ERR_CANCELLED".
.
.Pp
.
.Fn usbd_transfer_drain
This function will stop an USB transfer, if not already stopped and
wait for any additional USB hardware operations to complete.
.
Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can
safely be freed after that this function has returned.
.
This function can block the caller and will not return before the USB
callback has been called.
.
This function is NULL safe with regard to the USB transfer structure
pointer.
.
.Sh USB TRANSFER CALLBACK
.
The USB callback has three states.
.
USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the
initial state.
.
After the callback has been called with this state it will always be
called back at a later stage in one of the other two states.
.
The USB callback should not restart the USB transfer in case the error
cause is USB_ERR_CANCELLED.
.
The USB callback is protected from recursion.
.
That means one can start and stop whatever transfer from the callback
of another transfer one desires.
.
Also the transfer that is currently called back.
.
Recursion is handled like this that when the callback that wants to
recurse returns it is called one more time.
.
.
.Pp
.
.Fn usbd_transfer_submit
This function should only be called from within the USB callback and
is used to start the USB hardware.
.
An USB transfer can have multiple frames consisting of one or more USB
packets making up an I/O vector for all USB transfer types.
.
.Bd -literal -offset indent
void
usb_default_callback(struct usb_xfer *xfer, usb_error_t error)
{
	int actlen;

	usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL);

	switch (USB_GET_STATE(xfer)) {
	case USB_ST_SETUP: 
		/*
		 * Setup xfer frame lengths/count and data
		 */
		usbd_transfer_submit(xfer);
		break;

	case USB_ST_TRANSFERRED: 
		/* 
		 * Read	usb frame data, if any.
		 * "actlen" has the total length for all frames
		 * transfered.
		 */
		break;

	default: /* Error */
		/*
		 * Print error message and clear stall 
		 * for example.
		 */
		break;
	}
	/* 
	 * Here it is safe to do something without the private 
	 * USB mutex locked.
	 */
	return;
}
.Ed
.
.Sh USB CONTROL TRANSFERS
An USB control transfer has three parts.
.
First the SETUP packet, then DATA packet(s) and then a STATUS
packet.
.
The SETUP packet is always pointed to by frame 0 and the
length is set by 
.Fn usbd_xfer_frame_len
also if there should not be
sent any SETUP packet! If an USB control transfer has no DATA stage,
then the number of frames should be set to 1.
.
Else the default number of frames is 2.
.
.Bd -literal -offset indent

Example1: SETUP + STATUS
 usbd_xfer_set_frames(xfer, 1);
 usbd_xfer_set_frame_len(xfer, 0, 8);
 usbd_transfer_submit(xfer);

Example2: SETUP + DATA + STATUS
 usbd_xfer_set_frames(xfer, 2);
 usbd_xfer_set_frame_len(xfer, 0, 8);
 usbd_xfer_set_frame_len(xfer, 1, 1);
 usbd_transfer_submit(xfer);

Example3: SETUP + DATA + STATUS - split
1st callback:
 usbd_xfer_set_frames(xfer, 1);
 usbd_xfer_set_frame_len(xfer, 0, 8);
 usbd_transfer_submit(xfer);

2nd callback:
 /* IMPORTANT: frbuffers[0] must still point at the setup packet! */
 usbd_xfer_set_frames(xfer, 2);
 usbd_xfer_set_frame_len(xfer, 0, 0);
 usbd_xfer_set_frame_len(xfer, 1, 1);
 usbd_transfer_submit(xfer);

Example4: SETUP + STATUS - split
1st callback:
 usbd_xfer_set_frames(xfer, 1);
 usbd_xfer_set_frame_len(xfer, 0, 8);
 usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS);
 usbd_transfer_submit(xfer);

2nd callback:
 usbd_xfer_set_frames(xfer, 1);
 usbd_xfer_set_frame_len(xfer, 0, 0);
 usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS);
 usbd_transfer_submit(xfer);

.Ed
.Sh USB TRANSFER CONFIG
To simply the search for endpoints the
.Nm usb
module defines a USB config structure where it is possible to specify
the characteristics of the wanted endpoint.
.Bd -literal -offset indent

struct usb_config { 
	bufsize,
	callback
	direction,
	endpoint,
	frames,
	index flags,
	interval,
	timeout,
	type,
};

.Ed
.
.Pp
.Fa type
field selects the USB pipe type.
.
Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK,
UE_ISOCHRONOUS.
.
The special value UE_BULK_INTR will select BULK and INTERRUPT pipes.
.
This field is mandatory.
.
.Pp
.Fa endpoint
field selects the USB endpoint number.
.
A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching
endpoint.
.
This field is mandatory.
.
.Pp
.Fa direction
field selects the USB endpoint direction.
.
A value of "UE_DIR_ANY" will select the first matching endpoint.
.
Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT".
.
"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which
means that the direction will be swapped in case of
USB_MODE_DEVICE.
.
Note that "UE_DIR_IN" refers to the data transfer direction of the
"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of
the "OUT" tokens.
.
This field is mandatory.
.
.Pp
.Fa interval
field selects the interrupt interval.
.
The value of this field is given in milliseconds and is independent of
device speed.
.
Depending on the endpoint type, this field has different meaning:
.Bl -tag
.It UE_INTERRUPT
"0" use the default interrupt interval based on endpoint descriptor.
"Else" use the given value for polling rate.
.It UE_ISOCHRONOUS
"0" use default. "Else" the value is ignored.
.It UE_BULK
.It UE_CONTROL
"0" no transfer pre-delay. "Else" a delay as given by this field in
milliseconds is inserted before the hardware is started when
"usbd_transfer_submit()" is called.
.Pp
NOTE: The transfer timeout, if any, is started after that the
pre-delay has elapsed!
.El
.
.Pp
.Fa timeout
field, if non-zero, will set the transfer timeout in milliseconds. If
the "timeout" field is zero and the transfer type is ISOCHRONOUS a
timeout of 250ms will be used.
.
.Pp
.Fa frames
field sets the maximum number of frames. If zero is specified it will
yield the following results:
.Bl -tag
.It UE_BULK
xfer->nframes = 1;
.It UE_INTERRUPT
xfer->nframes = 1;
.It UE_CONTROL
xfer->nframes = 2;
.It UE_ISOCHRONOUS
Not allowed. Will cause an error.
.El
.
.Pp
.Fa ep_index
field allows you to give a number, in case more endpoints match the
description, that selects which matching "ep_index" should be used.
.
.Pp
.Fa if_index
field allows you to select which of the interface numbers in the
"ifaces" array parameter passed to "usbd_transfer_setup" that should
be used when setting up the given USB transfer.
.
.Pp
.Fa flags
field has type "struct usb_xfer_flags" and allows one to set initial
flags an USB transfer. Valid flags are:
.Bl -tag
.It force_short_xfer
This flag forces the last transmitted USB packet to be short.  A short
packet has a length of less than "xfer->max_packet_size", which
derives from "wMaxPacketSize". This flag can be changed during
operation.
.It short_xfer_ok
This flag allows the received transfer length, "xfer->actlen" to be
less than "xfer->sumlen" upon completion of a transfer.  This flag can
be changed during operation.
.It short_frames_ok
This flag allows the reception of multiple short USB frames. This flag
only has effect for BULK and INTERRUPT endpoints and if the number of
frames received is greater than 1. This flag can be changed during
operation.
.It pipe_bof
This flag causes a failing USB transfer to remain first in the PIPE
queue except in the case of "xfer->error" equal to
"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue
will be started until either:
.Bl -tag
.It 1
The failing USB transfer is stopped using "usbd_transfer_stop()".
.It 2
The failing USB transfer performs a successful transfer.
.El
The purpose of this flag is to avoid races when multiple transfers are
queued for execution on an USB endpoint, and the first executing
transfer fails leading to the need for clearing of stall for
example.
.
In this case this flag is used to prevent the following USB transfers
from being executed at the same time the clear-stall command is
executed on the USB control endpoint.
.
This flag can be changed during operation.
.Pp
"BOF" is short for "Block On Failure"
.Pp
NOTE: This flag should be set on all BULK and INTERRUPT USB transfers
which use an endpoint that can be shared between userland and kernel.
.
.
.It proxy_buffer
Setting this flag will cause that the total buffer size will be
rounded up to the nearest atomic hardware transfer size.
.
The maximum data length of any USB transfer is always stored in the
"xfer->max_data_length".
.
For control transfers the USB kernel will allocate additional space
for the 8-bytes of SETUP header.
.
These 8-bytes are not counted by the "xfer->max_data_length"
variable.
.
This flag can not be changed during operation.
.
.
.It ext_buffer
Setting this flag will cause that no data buffer will be
allocated.
.
Instead the USB client must supply a data buffer.
.
This flag can not be changed during operation.
.
.
.It manual_status
Setting this flag prevents an USB STATUS stage to be appended to the
end of the USB control transfer.
.
If no control data is transferred this flag must be cleared.
.
Else an error will be returned to the USB callback.
.
This flag is mostly useful for the USB device side.
.
This flag can be changed during operation.
.
.
.It no_pipe_ok
Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This
flag can not be changed during operation.
.
.
.It stall_pipe
.Bl -tag
.It Device Side Mode
Setting this flag will cause STALL pids to be sent to the endpoint
belonging to this transfer before the transfer is started.
.
The transfer is started at the moment the host issues a clear-stall
command on the STALL'ed endpoint.
.
This flag can be changed during operation.
.It Host Side Mode
Setting this flag will cause a clear-stall control request to be
executed on the endpoint before the USB transfer is started.
.El
.Pp
If this flag is changed outside the USB callback function you have to
use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()"
functions! This flag is automatically cleared after that the stall or
clear stall has been executed.
.
.El
.Pp
.Fa bufsize
field sets the total buffer size in bytes.
.
If this field is zero, "wMaxPacketSize" will be used, multiplied by
the "frames" field if the transfer type is ISOCHRONOUS.
.
This is useful for setting up interrupt pipes.
.
This field is mandatory.
.Pp
NOTE: For control transfers "bufsize" includes the length of the
request structure.
.
.Pp
.Fa callback
pointer sets the USB callback. This field is mandatory.
.
.
.Sh USB LINUX COMPAT LAYER
The
.Nm usb
module supports the Linux USB API.
.
.
.Sh SEE ALSO
.Xr libusb 3 ,
.Xr usb 4 ,
.Xr usbconfig 8
.Sh STANDARDS
The
.Nm usb
module complies with the USB 2.0 standard.
.Sh HISTORY
The
.Nm usb
module has been inspired by the NetBSD USB stack initially written by
Lennart Augustsson. The
.Nm usb
module was written by
.An Hans Petter Selasky Aq hselasky@FreeBSD.org .