1.\" $OpenBSD: usbd_open_pipe.9,v 1.5 2022/03/29 18:15:52 naddy Exp $ 2.\" 3.\" Copyright (c) 2015 Sean Levy <attila@stalphonsos.com> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: March 29 2022 $ 18.Dt USBD_OPEN_PIPE 9 19.Os 20.Sh NAME 21.Nm usbd_open_pipe , usbd_open_pipe_intr 22.Nd create USB pipe 23.Sh SYNOPSIS 24.In dev/usb/usb.h 25.In dev/usb/usbdi.h 26.Ft usbd_status 27.Fn usbd_open_pipe "struct usbd_interface *iface" "uint8_t address" "uint8_t flags" "struct usbd_pipe **pipe" 28.Ft usbd_status 29.Fn usbd_open_pipe_intr "struct usbd_interface *iface" "uint8_t address" "uint8_t flags" "struct usbd_pipe **pipe" "void *priv" "void *buffer" "uint32_t len" "usbd_callback cb" "int ival" 30.Sh DESCRIPTION 31The 32.Fn usbd_open_pipe 33and 34.Fn usbd_open_pipe_intr 35functions create pipes. 36A pipe is a logical connection between the host and an endpoint on a 37USB device. 38USB drivers use pipes to manage transfers to or from a USB 39endpoint. 40.Pp 41The 42.Fn usbd_open_pipe 43function takes the following arguments: 44.Bl -tag -width callback 45.It Fa iface 46The USB interface for which the pipe is to be created. 47.It Fa address 48The address of the endpoint in that interface to which the pipe should be 49connected. 50.It Fa flags 51A bitmask of flags. 52Currently there is only one flag bit defined: 53.Bl -tag -width xxx -offset indent 54.It Dv USBD_EXCLUSIVE_USE 55Do not allow other pipes to use this endpoint while this pipe exists. 56.El 57.It Fa pipe 58A pointer to where the resulting 59.Vt struct usbd_pipe * 60should be stored if the call is successful. 61.El 62.Pp 63The 64.Fn usbd_open_pipe_intr 65function takes the following arguments: 66.Bl -tag -width callback 67.It Fa iface 68The USB interface for which the pipe is to be created. 69.It Fa address 70The endpoint in that interface to which the pipe should be connected. 71.It Fa flags 72A bitmask of flags. 73These flags are not interpreted in the same way as the 74.Fa flags 75passed to 76.Fn usbd_open_pipe . 77Instead, 78.Fn usbd_open_pipe_intr 79implicitly turns on the 80.Dv USBD_EXCLUSIVE_USE 81bit for the pipe, disallowing multiple interrupt pipes for 82the same endpoint. 83The 84.Fa flags 85argument in this case is instead passed directly to 86.Xr usbd_setup_xfer 9 87as its 88.Fa flags 89argument, whose interpretation is documented in 90its man page. 91.It Fa pipe 92A pointer to where the resulting 93.Vt struct usbd_pipe * 94should be stored if the call is successful. 95.It Fa priv 96A pointer to a private cookie untouched by the USB stack for reuse in 97the callback specified by the 98.Fa cb 99argument. 100.It Fa buffer 101A pointer to the data buffer for use by the implicit transfer 102(see below). 103.It Fa len 104The length in bytes of 105.Fa buffer . 106.It Fa cb 107A callback invoked every time the interrupt transfer completes. 108.It Fa ival 109The interval in milliseconds with which the interrupt pipe 110should be polled by the USB stack. 111.El 112.Pp 113Pipes created by 114.Fn usbd_open_pipe_intr 115implicitly have a repeating transfer queued on them which 116is run every 117.Fa ival 118milliseconds. 119This implicit transfer is not automatically removed from the list of 120transfers maintained by the pipe, unlike normal transfers, and will 121continue to be processed every 122.Fa ival 123milliseconds. 124.Sh CONTEXT 125.Fn usbd_open_pipe 126and 127.Fn usbd_open_pipe_intr 128can be called during autoconf or from process context. 129.Sh SEE ALSO 130.Xr usb 4 , 131.Xr usbd_close_pipe 9 , 132.Xr usbd_transfer 9 133