On 14/05/13(Tue) 16:09, Marcus Glocker wrote: > On Fri, May 10, 2013 at 09:44:53AM +0200, Martin Pieuchot wrote: > > > So this is is one more step in my effort to merge the various code paths > > to submit an USB transfer. > > > > This diff gets rid of the two badly named functions: usbd_bulk_transfer() > > & usbd_intr_transfer() and makes use of the usbd_setup_xfer(9) + > > usbd_transfer(9) combination. These functions were badly named because > > they are identical wrappers to submit a synchronous transfer. There are > > however two small functional differences with this diff: > > > > - previously a custom name for the wait channel was given to tlseep(9) > > while sleeping for I/O. Now it will be "usbsyn" for all USB > > synchronous transfers. > > > > - previously the priority given to tlseep(9) was PZERO. Now it will be > > PRIBIO like for all USB synchronous transfers. But this shouldn't make > > a difference in practice, because the only priority between the two, > > PVFS, is unused. > > > > This diff also includes a new manual for the above mentioned functions. > > I'd like to document as much functions of our USB stack as possible to > > make sure driver porter/writer understand how it works.
Updated diff with two minors tweaks to make sure that: - no information is leaked to userland when USBD_SHORT_XFER_OK is set for ugen(4) reads - do not bother checking for the actual transfered length for reads in urio(4), USBD_SHORT_XFER_OK being not set, an error is returned if actlen < len. Plus includes some tweaks for the manpage by jmc@ Index: sys/dev/usb/ugen.c =================================================================== RCS file: /cvs/src/sys/dev/usb/ugen.c,v retrieving revision 1.72 diff -u -p -r1.72 ugen.c --- sys/dev/usb/ugen.c 17 May 2013 09:09:11 -0000 1.72 +++ sys/dev/usb/ugen.c 17 May 2013 17:49:09 -0000 @@ -478,7 +478,7 @@ ugen_do_read(struct ugen_softc *sc, int struct usbd_xfer *xfer; usbd_status err; int s; - int error = 0; + int flags, error = 0; u_char buffer[UGEN_CHUNK]; DPRINTFN(5, ("%s: ugenread: %d\n", sc->sc_dev.dv_xname, endpt)); @@ -546,14 +546,16 @@ ugen_do_read(struct ugen_softc *sc, int xfer = usbd_alloc_xfer(sc->sc_udev); if (xfer == 0) return (ENOMEM); + flags = USBD_SYNCHRONOUS; + if (sce->state & UGEN_SHORT_OK) + flags |= USBD_SHORT_XFER_OK; + if (sce->timeout == 0) + flags |= USBD_CATCH; while ((n = min(UGEN_BBSIZE, uio->uio_resid)) != 0) { DPRINTFN(1, ("ugenread: start transfer %d bytes\n",n)); - tn = n; - err = usbd_bulk_transfer( - xfer, sce->pipeh, - sce->state & UGEN_SHORT_OK ? - USBD_SHORT_XFER_OK : 0, - sce->timeout, buf, &tn, "ugenrb"); + usbd_setup_xfer(xfer, sce->pipeh, 0, buf, n, + flags, sce->timeout, NULL); + err = usbd_transfer(xfer); if (err) { if (err == USBD_INTERRUPTED) error = EINTR; @@ -563,6 +565,7 @@ ugen_do_read(struct ugen_softc *sc, int error = EIO; break; } + usbd_get_xfer_status(xfer, NULL, NULL, &tn, NULL); DPRINTFN(1, ("ugenread: got %d bytes\n", tn)); error = uiomove(buf, tn, uio); if (error || tn < n) @@ -640,7 +643,7 @@ ugen_do_write(struct ugen_softc *sc, int { struct ugen_endpoint *sce = &sc->sc_endpoints[endpt][OUT]; u_int32_t n; - int error = 0; + int flags, error = 0; char buf[UGEN_BBSIZE]; struct usbd_xfer *xfer; usbd_status err; @@ -663,6 +666,9 @@ ugen_do_write(struct ugen_softc *sc, int return (EIO); } #endif + flags = USBD_SYNCHRONOUS; + if (sce->timeout == 0) + flags |= USBD_CATCH; switch (sce->edesc->bmAttributes & UE_XFERTYPE) { case UE_BULK: @@ -674,8 +680,9 @@ ugen_do_write(struct ugen_softc *sc, int if (error) break; DPRINTFN(1, ("ugenwrite: transfer %d bytes\n", n)); - err = usbd_bulk_transfer(xfer, sce->pipeh, 0, - sce->timeout, buf, &n,"ugenwb"); + usbd_setup_xfer(xfer, sce->pipeh, 0, buf, n, + flags, sce->timeout, NULL); + err = usbd_transfer(xfer); if (err) { if (err == USBD_INTERRUPTED) error = EINTR; @@ -698,8 +705,9 @@ ugen_do_write(struct ugen_softc *sc, int if (error) break; DPRINTFN(1, ("ugenwrite: transfer %d bytes\n", n)); - err = usbd_intr_transfer(xfer, sce->pipeh, 0, - sce->timeout, buf, &n, "ugenwi"); + usbd_setup_xfer(xfer, sce->pipeh, 0, buf, n, + flags, sce->timeout, NULL); + err = usbd_transfer(xfer); if (err) { if (err == USBD_INTERRUPTED) error = EINTR; Index: sys/dev/usb/uhidev.c =================================================================== RCS file: /cvs/src/sys/dev/usb/uhidev.c,v retrieving revision 1.44 diff -u -p -r1.44 uhidev.c --- sys/dev/usb/uhidev.c 7 May 2013 08:44:38 -0000 1.44 +++ sys/dev/usb/uhidev.c 17 May 2013 17:28:46 -0000 @@ -645,8 +645,9 @@ uhidev_write(struct uhidev_softc *sc, vo DPRINTF(("\n")); } #endif - return usbd_intr_transfer(sc->sc_owxfer, sc->sc_opipe, 0, - USBD_NO_TIMEOUT, data, &len, "uhidevwi"); + usbd_setup_xfer(sc->sc_owxfer, sc->sc_opipe, 0, data, len, + USBD_SYNCHRONOUS | USBD_CATCH, 0, NULL); + return usbd_transfer(sc->sc_owxfer); } int Index: sys/dev/usb/ulpt.c =================================================================== RCS file: /cvs/src/sys/dev/usb/ulpt.c,v retrieving revision 1.43 diff -u -p -r1.43 ulpt.c --- sys/dev/usb/ulpt.c 15 Apr 2013 09:23:02 -0000 1.43 +++ sys/dev/usb/ulpt.c 17 May 2013 17:28:46 -0000 @@ -636,8 +636,9 @@ ulpt_do_write(struct ulpt_softc *sc, str if (error) break; DPRINTFN(1, ("ulptwrite: transfer %d bytes\n", n)); - err = usbd_bulk_transfer(xfer, sc->sc_out_pipe, USBD_NO_COPY, - USBD_NO_TIMEOUT, bufp, &n, "ulptwr"); + usbd_setup_xfer(xfer, sc->sc_out_pipe, 0, bufp, n, + USBD_NO_COPY | USBD_SYNCHRONOUS | USBD_CATCH, 0, NULL); + err = usbd_transfer(xfer); if (err) { DPRINTF(("ulptwrite: error=%d\n", err)); error = EIO; @@ -704,8 +705,9 @@ ulpt_ucode_loader_hp(struct ulpt_softc * while (remain > 0) { len = min(remain, ULPT_BSIZE); memcpy(bufp, &ucode[offset], len); - error = usbd_bulk_transfer(xfer, sc->sc_out_pipe, USBD_NO_COPY, - USBD_NO_TIMEOUT, bufp, &len, "ulptwr"); + usbd_setup_xfer(xfer, sc->sc_out_pipe, 0, bufp, len, + USBD_NO_COPY | USBD_SYNCHRONOUS, 0, NULL); + error = usbd_transfer(xfer); if (error != USBD_NORMAL_COMPLETION) { printf("%s: ucode upload error=%s!\n", sc->sc_dev.dv_xname, usbd_errstr(error)); Index: sys/dev/usb/umsm.c =================================================================== RCS file: /cvs/src/sys/dev/usb/umsm.c,v retrieving revision 1.90 diff -u -p -r1.90 umsm.c --- sys/dev/usb/umsm.c 15 Apr 2013 09:23:02 -0000 1.90 +++ sys/dev/usb/umsm.c 17 May 2013 17:28:46 -0000 @@ -767,8 +767,9 @@ umsm_umass_changemode(struct umsm_softc else { n = UMASS_BBB_CBW_SIZE; memcpy(bufp, &cbw, UMASS_BBB_CBW_SIZE); - err = usbd_bulk_transfer(xfer, cmdpipe, USBD_NO_COPY, - USBD_NO_TIMEOUT, bufp, &n, "umsm"); + usbd_setup_xfer(xfer, cmdpipe, 0, bufp, n, + USBD_NO_COPY | USBD_SYNCHRONOUS, 0, NULL); + err = usbd_transfer(xfer); if (err) DPRINTF(("%s: send error:%s", __func__, usbd_errstr(err))); Index: sys/dev/usb/urio.c =================================================================== RCS file: /cvs/src/sys/dev/usb/urio.c,v retrieving revision 1.42 diff -u -p -r1.42 urio.c --- sys/dev/usb/urio.c 17 May 2013 09:14:08 -0000 1.42 +++ sys/dev/usb/urio.c 17 May 2013 17:39:13 -0000 @@ -304,7 +304,7 @@ urioread(dev_t dev, struct uio *uio, int struct usbd_xfer *xfer; usbd_status err; void *bufp; - u_int32_t n, tn; + u_int32_t n; int error = 0; sc = urio_cd.cd_devs[URIOUNIT(dev)]; @@ -327,9 +327,9 @@ urioread(dev_t dev, struct uio *uio, int while ((n = min(URIO_BSIZE, uio->uio_resid)) != 0) { DPRINTFN(1, ("urioread: start transfer %d bytes\n", n)); - tn = n; - err = usbd_bulk_transfer(xfer, sc->sc_in_pipe, USBD_NO_COPY, - URIO_RW_TIMEOUT, bufp, &tn, "uriors"); + usbd_setup_xfer(xfer, sc->sc_in_pipe, 0, bufp, n, + USBD_NO_COPY | USBD_SYNCHRONOUS, URIO_RW_TIMEOUT, NULL); + err = usbd_transfer(xfer); if (err) { if (err == USBD_INTERRUPTED) error = EINTR; @@ -340,10 +340,10 @@ urioread(dev_t dev, struct uio *uio, int break; } - DPRINTFN(1, ("urioread: got %d bytes\n", tn)); + DPRINTFN(1, ("urioread: got %d bytes\n", n)); - error = uiomove(bufp, tn, uio); - if (error || tn < n) + error = uiomove(bufp, n, uio); + if (error) break; } usbd_free_xfer(xfer); @@ -390,8 +390,9 @@ uriowrite(dev_t dev, struct uio *uio, in DPRINTFN(1, ("uriowrite: transfer %d bytes\n", n)); - err = usbd_bulk_transfer(xfer, sc->sc_out_pipe, USBD_NO_COPY, - URIO_RW_TIMEOUT, bufp, &n, "uriowr"); + usbd_setup_xfer(xfer, sc->sc_out_pipe, 0, bufp, n, + USBD_NO_COPY | USBD_SYNCHRONOUS, URIO_RW_TIMEOUT, NULL); + err = usbd_transfer(xfer); DPRINTFN(2, ("uriowrite: err=%d\n", err)); if (err) { if (err == USBD_INTERRUPTED) Index: sys/dev/usb/usbdi.c =================================================================== RCS file: /cvs/src/sys/dev/usb/usbdi.c,v retrieving revision 1.55 diff -u -p -r1.55 usbdi.c --- sys/dev/usb/usbdi.c 26 Apr 2013 14:19:25 -0000 1.55 +++ sys/dev/usb/usbdi.c 17 May 2013 17:28:46 -0000 @@ -293,7 +293,7 @@ usbd_transfer(struct usbd_xfer *xfer) struct usb_dma *dmap = &xfer->dmabuf; usbd_status err; u_int size; - int s; + int flags, s; if (usbd_is_dying(pipe->device)) return (USBD_IOERROR); @@ -351,7 +351,8 @@ usbd_transfer(struct usbd_xfer *xfer) while (!xfer->done) { if (pipe->device->bus->use_polling) panic("usbd_transfer: not done"); - tsleep(xfer, PRIBIO, "usbsyn", 0); + flags = PRIBIO | (xfer->flags & USBD_CATCH ? PCATCH : 0); + tsleep(xfer, flags, "usbsyn", 0); } splx(s); return (xfer->status); Index: sys/dev/usb/usbdi.h =================================================================== RCS file: /cvs/src/sys/dev/usb/usbdi.h,v retrieving revision 1.53 diff -u -p -r1.53 usbdi.h --- sys/dev/usb/usbdi.h 26 Apr 2013 14:19:25 -0000 1.53 +++ sys/dev/usb/usbdi.h 17 May 2013 17:28:46 -0000 @@ -76,6 +76,7 @@ typedef void (*usbd_callback)(struct usb #define USBD_SYNCHRONOUS 0x02 /* wait for completion */ /* in usb.h #define USBD_SHORT_XFER_OK 0x04*/ /* allow short reads */ #define USBD_FORCE_SHORT_XFER 0x08 /* force last short packet on write */ +#define USBD_CATCH 0x10 /* catch signals while sleeping */ #define USBD_NO_TIMEOUT 0 #define USBD_DEFAULT_TIMEOUT 5000 /* ms = 5 s */ Index: sys/dev/usb/usbdi_util.c =================================================================== RCS file: /cvs/src/sys/dev/usb/usbdi_util.c,v retrieving revision 1.31 diff -u -p -r1.31 usbdi_util.c --- sys/dev/usb/usbdi_util.c 15 Apr 2013 09:23:02 -0000 1.31 +++ sys/dev/usb/usbdi_util.c 17 May 2013 17:28:46 -0000 @@ -396,90 +396,6 @@ usbd_get_config(struct usbd_device *dev, return (usbd_do_request(dev, &req, conf)); } -void usbd_bulk_transfer_cb(struct usbd_xfer *xfer, void *priv, - usbd_status status); -void -usbd_bulk_transfer_cb(struct usbd_xfer *xfer, void *priv, - usbd_status status) -{ - wakeup(xfer); -} - -usbd_status -usbd_bulk_transfer(struct usbd_xfer *xfer, struct usbd_pipe *pipe, - u_int16_t flags, u_int32_t timeout, void *buf, u_int32_t *size, char *lbl) -{ - usbd_status err; - int s, error, pri; - - usbd_setup_xfer(xfer, pipe, 0, buf, *size, flags, timeout, - usbd_bulk_transfer_cb); - DPRINTFN(1, ("usbd_bulk_transfer: start transfer %d bytes\n", *size)); - s = splusb(); /* don't want callback until tsleep() */ - err = usbd_transfer(xfer); - if (err != USBD_IN_PROGRESS) { - splx(s); - return (err); - } - pri = timeout == 0 ? (PZERO | PCATCH) : PZERO; - error = tsleep((caddr_t)xfer, pri, lbl, 0); - splx(s); - if (error) { - DPRINTF(("usbd_bulk_transfer: tsleep=%d\n", error)); - usbd_abort_pipe(pipe); - return (USBD_INTERRUPTED); - } - usbd_get_xfer_status(xfer, NULL, NULL, size, &err); - DPRINTFN(1,("usbd_bulk_transfer: transferred %d\n", *size)); - if (err) { - DPRINTF(("usbd_bulk_transfer: error=%d\n", err)); - usbd_clear_endpoint_stall(pipe); - } - return (err); -} - -void usbd_intr_transfer_cb(struct usbd_xfer *xfer, void *priv, - usbd_status status); -void -usbd_intr_transfer_cb(struct usbd_xfer *xfer, void *priv, - usbd_status status) -{ - wakeup(xfer); -} - -usbd_status -usbd_intr_transfer(struct usbd_xfer *xfer, struct usbd_pipe *pipe, - u_int16_t flags, u_int32_t timeout, void *buf, u_int32_t *size, char *lbl) -{ - usbd_status err; - int s, error, pri; - - usbd_setup_xfer(xfer, pipe, 0, buf, *size, flags, timeout, - usbd_intr_transfer_cb); - DPRINTFN(1, ("usbd_intr_transfer: start transfer %d bytes\n", *size)); - s = splusb(); /* don't want callback until tsleep() */ - err = usbd_transfer(xfer); - if (err != USBD_IN_PROGRESS) { - splx(s); - return (err); - } - pri = timeout == 0 ? (PZERO | PCATCH) : PZERO; - error = tsleep(xfer, pri, lbl, 0); - splx(s); - if (error) { - DPRINTF(("usbd_intr_transfer: tsleep=%d\n", error)); - usbd_abort_pipe(pipe); - return (USBD_INTERRUPTED); - } - usbd_get_xfer_status(xfer, NULL, NULL, size, &err); - DPRINTFN(1,("usbd_intr_transfer: transferred %d\n", *size)); - if (err) { - DPRINTF(("usbd_intr_transfer: error=%d\n", err)); - usbd_clear_endpoint_stall(pipe); - } - return (err); -} - void usb_detach_wait(struct device *dv) { Index: sys/dev/usb/usbdi_util.h =================================================================== RCS file: /cvs/src/sys/dev/usb/usbdi_util.h,v retrieving revision 1.21 diff -u -p -r1.21 usbdi_util.h --- sys/dev/usb/usbdi_util.h 15 Apr 2013 09:23:02 -0000 1.21 +++ sys/dev/usb/usbdi_util.h 17 May 2013 17:28:46 -0000 @@ -69,13 +69,5 @@ usbd_status usbd_set_config_no(struct us usbd_status usbd_set_config_index(struct usbd_device *dev, int index, int msg); -usbd_status usbd_bulk_transfer(struct usbd_xfer *xfer, - struct usbd_pipe *pipe, u_int16_t flags, u_int32_t timeout, - void *buf, u_int32_t *size, char *lbl); - -usbd_status usbd_intr_transfer(struct usbd_xfer *xfer, - struct usbd_pipe *pipe, u_int16_t flags, u_int32_t timeout, - void *buf, u_int32_t *size, char *lbl); - void usb_detach_wait(struct device *); void usb_detach_wakeup(struct device *); Index: sys/dev/usb/uscanner.c =================================================================== RCS file: /cvs/src/sys/dev/usb/uscanner.c,v retrieving revision 1.48 diff -u -p -r1.48 uscanner.c --- sys/dev/usb/uscanner.c 15 Apr 2013 09:23:02 -0000 1.48 +++ sys/dev/usb/uscanner.c 17 May 2013 17:28:46 -0000 @@ -464,11 +464,12 @@ uscanner_do_read(struct uscanner_softc * DPRINTFN(1, ("uscannerread: start transfer %d bytes\n",n)); tn = n; - err = usbd_bulk_transfer( + usbd_setup_xfer( sc->sc_bulkin_xfer, sc->sc_bulkin_pipe, - USBD_SHORT_XFER_OK, USBD_NO_TIMEOUT, - sc->sc_bulkin_buffer, &tn, - "uscnrb"); + 0, sc->sc_bulkin_buffer, tn, + USBD_SHORT_XFER_OK | USBD_SYNCHRONOUS | USBD_CATCH, 0, + NULL); + err = usbd_transfer(sc->sc_bulkin_xfer); if (err) { if (err == USBD_INTERRUPTED) error = EINTR; @@ -520,11 +521,11 @@ uscanner_do_write(struct uscanner_softc if (error) break; DPRINTFN(1, ("uscanner_do_write: transfer %d bytes\n", n)); - err = usbd_bulk_transfer( + usbd_setup_xfer( sc->sc_bulkout_xfer, sc->sc_bulkout_pipe, - 0, USBD_NO_TIMEOUT, - sc->sc_bulkout_buffer, &n, - "uscnwb"); + 0, sc->sc_bulkout_buffer, n, + USBD_SYNCHRONOUS | USBD_CATCH, 0, NULL); + err = usbd_transfer(sc->sc_bulkout_xfer); if (err) { if (err == USBD_INTERRUPTED) error = EINTR; Index: share/man/man9/Makefile =================================================================== RCS file: /cvs/src/share/man/man9/Makefile,v retrieving revision 1.177 diff -u -p -r1.177 Makefile --- share/man/man9/Makefile 24 Apr 2013 17:29:02 -0000 1.177 +++ share/man/man9/Makefile 17 May 2013 17:28:46 -0000 @@ -25,7 +25,9 @@ MAN= altq.9 aml_evalnode.9 atomic.9 audi route.9 rwlock.9 sensor_attach.9 \ shutdownhook_establish.9 tsleep.9 spl.9 startuphook_establish.9 \ socreate.9 sosplice.9 style.9 syscall.9 systrace.9 sysctl_int.9 \ - tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 vfs_busy.9 \ + tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 \ + usbd_transfer.9 \ + vfs.9 vfs_busy.9 \ vfs_cache.9 vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \ vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vnode.9 vnsubr.9 \ VOP_GETATTR.9 VOP_LOOKUP.9 vput.9 vrecycle.9 vref.9 vrele.9 \ @@ -331,6 +333,7 @@ MLINKS+=timeout.9 timeout_add.9 timeout. MLINKS+=tsleep.9 wakeup.9 tsleep.9 msleep.9 MLINKS+=tvtohz.9 tstohz.9 MLINKS+=uiomove.9 uio.9 +MLINKS+=usbd_transfer.9 usbd_setup_xfer.9 MLINKS+=uvm.9 uvm_init.9 uvm.9 uvm_init_limits.9 uvm.9 uvm_setpagesize.9 \ uvm.9 uvm_swap_init.9 uvm.9 uvm_map.9 uvm.9 uvm_map_pageable.9 \ uvm.9 uvm_map_pageable_all.9 uvm.9 uvm_map_checkprot.9 \ Index: share/man/man9/usbd_transfer.9 =================================================================== RCS file: share/man/man9/usbd_transfer.9 diff -N share/man/man9/usbd_transfer.9 --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ share/man/man9/usbd_transfer.9 17 May 2013 17:29:13 -0000 @@ -0,0 +1,105 @@ +.\" $OpenBSD$ +.\" +.\" Copyright (c) 2013 Martin Pieuchot +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate$ +.Dt USBD_TRANSFER 9 +.Os +.Sh NAME +.Nm usbd_setup_xfer , usbd_transfer +.Nd submit USB data transfers +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.Ft void +.Fn usbd_setup_xfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ + "void *priv" "void *buffer" "uint32_t length" "uint16_t flags" \ + "uint32_t timeout" "usbd_callback callback" +.Ft usbd_status +.Fn usbd_transfer "struct usbd_xfer *xfer" +.Sh DESCRIPTION +These functions provide a controller independent mechanism to perform USB +data transfers. +.Pp +The function +.Fn usbd_setup_xfer +is used to initialize the structure pointed to by +.Fa xfer , +describing an individual transfer to submit. +It takes the following arguments: +.Bl -tag -width callback +.It Fa xfer +A pointer to an existing structure describing a transfer. +.It Fa pipe +A pointer to a pipe associated with the endpoint for the transfer. +.It Fa priv +A pointer to a private cookie untouched by the USB stack for reuse in the +.Fa callback . +.It Fa buffer +A pointer to the data buffer. +.It Fa length +The total length of the data to read or write. +.It Fa flags +The characteristics of the transfer: +.Bl -tag -width xxx -offset indent +.It Dv USBD_NO_COPY +Do not copy data between +.Fa buffer +and the DMA buffer. +.It Dv USBD_SYNCHRONOUS +Causes +.Fn usbd_transfer +to sleep until the I/O transfer is complete or the +.Fa timeout +expires. +.It Dv USBD_SHORT_XFER_OK +Do not report short reads, when the length of the data read is lower than +.Fa length , +as errors. +.It Dv USBD_FORCE_SHORT_XFER +Submit a supplementary zero length packet at the end of the data if +.Fa length +is a multiple of the endpoint's wMaxPacketSize. +.It Dv USBD_CATCH +Used in conjunction with the +.Dv USBD_SYNCHRONOUS +flag to pass the +.Dv PCATCH +flag to +.Xr tsleep 9 +in order to check for signals before and after sleeping. +.El +.It Fa timeout +Timeout of the transfer in milliseconds. +.It Fa callback +A routine invoked upon completion of the transfer whether successful or not. +.El +.Pp +The function +.Fn usbd_transfer +is used to submit the USB transfer described by +.Fa xfer +to the corresponding +.Xr usb 4 +host controller to perform I/O with devices. +.Sh CODE REFERENCES +These functions are implemented in the file +.Pa sys/dev/usb/usbdi.c . +.Sh SEE ALSO +.Xr ehci 4 , +.Xr ohci 4 , +.Xr uhci 4 , +.Xr usb 4 , +.Xr tsleep 9