1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2016 Joyent, Inc.
13.\"
14.Dd February 15, 2020
15.Dt USBA_HCDI_PIPE_OPEN 9E
16.Os
17.Sh NAME
18.Nm usba_hcdi_pipe_open ,
19.Nm usba_hcdi_pipe_close
20.Nd open and close a USB pipe
21.Sh SYNOPSIS
22.In sys/usb/usba/hcdi.h
23.Ft int
24.Fo prefix_hcdi_pipe_open
25.Fa "usba_pipe_handle_data_t *ph"
26.Fa "usb_flags_t usb_flags"
27.Fc
28.Ft int
29.Fo prefix_hcdi_pipe_close
30.Fa "usba_pipe_handle_data_t *ph"
31.Fa "usb_flags_t usb_flags"
32.Fc
33.Sh INTERFACE LEVEL
34.Sy Volatile -
35illumos USB HCD private function
36.Pp
37This is a private function that is not part of the stable DDI.
38It may be removed or changed at any time.
39.Sh PARAMETERS
40.Bl -tag -width Fa
41.It Fa ph
42A pointer to a USB pipe handle as defined in
43.Xr usba_pipe_handle_data 9S .
44.It Fa usb_flags
45Flags which describe how allocations should be performed.
46Valid flags are:
47.Bl -tag -width Sy
48.It Sy USB_FLAGS_NOSLEEP
49Do not block waiting for memory.
50If memory is not available the allocation will fail.
51.It Sy USB_FLAGS_SLEEP
52Perform a blocking allocation.
53If memory is not available, the function will wait until memory is made
54available.
55.Pp
56Note, the request may still fail even if
57.Sy USB_FLAGS_SLEEP
58is specified.
59.El
60.El
61.Sh DESCRIPTION
62The
63.Fn usba_hcdi_pipe_open
64and
65.Fn usba_hcdi_pipe_close
66entry points are called by the USB framework whenever a client, or the
67framework itself, need to open or close a specific pipe.
68For additional background see
69.Xr usba_hcdi 9E .
70.Pp
71When a pipe is opened, the host controller driver is responsible for
72preparing the specified endpoint for performing transfers.
73This may include allocating bandwidth, programming the controller, and more.
74When the pipe is closed, the host controller driver is responsible for
75cleaning up any resources that were allocated during the open call.
76.Pp
77The pipe handle,
78.Fa ph ,
79identifies the endpoint that it the USBA is trying to open or close
80through its endpoint descriptor in the
81.Sy p_ep
82member.
83The endpoint descriptor is described in
84.Xr usb_ep_descr 9S .
85From the endpoint descriptor the driver can determine the type of
86endpoint, what the address of the endpoint is, and what direction the
87endpoint is in.
88When combined, these uniquely describe the pipe.
89.Pp
90To open a pipe, the driver may need additional companion endpoint
91descriptors.
92If these are available, they will be in the
93.Sy p_xep
94member of the pipe handle.
95See
96.Xr usb_ep_xdescr 9S
97for more information on how to determine which descriptors are present
98and get the information encoded in them.
99.Pp
100Host controller drivers should check the USB address of the
101USB device that
102.Fa ph
103belongs to.
104The driver may be asked to open a pipe to the root hub.
105As the root hub is often synthetic, the driver may need to take a different
106path than normal.
107.Ss Pipe open specifics
108A given endpoint on a device can only be opened once.
109If there's a request to open an already open endpoint, then the request to open
110the pipe should be failed.
111.Pp
112By the time the call to open a pipe returns, the driver should expect
113that any of the pipe transfer or reset entry points will be called on
114the pipe.
115.Pp
116A driver can establish private data on an endpoint.
117During pipe open it may set the
118.Sy p_hcd_private
119member to any value.
120Generally this points to an allocated structure that contains data specific to
121the host controller.
122This value will remain on the pipe handle.
123It is the responsibility of the driver to clear the data when the pipe is
124closed.
125.Ss Pipe close specifics
126When a pipe is closed, the driver must clean up all of the resources
127that it allocated when opening the pipe.
128For non-periodic transfers, the host controller driver may assume that there
129are no outstanding transfers that need to be cleaned up.
130However, the same is not true for periodic pipes.
131.Pp
132For pipes that have outstanding periodic transfers, the host controller
133driver needs to clean them up and quiesce them as though a call to
134either
135.Xr usba_hcdi_pipe_stop_intr_polling 9E
136or
137.Xr usba_hcdi_pipe_stop_isoc_polling 9E
138had been called.
139.Pp
140Just as with opening the pipe, the driver should pay attention to the
141address of the USB device, as it may be the root hub, which may be a
142synthetic pipe.
143.Pp
144When a call to
145.Fn usba_hcdi_pipe_close
146completes, the device should be in a state that the pipe can be opened
147again.
148.Sh RETURN VALUES
149Upon successful completion, the
150.Fn usba_hcdi_pipe_open
151and
152.Fn uba_hcdi_pipe_close
153functions should return
154.Sy USB_SUCCESS .
155Otherwise, it should return the appropriate USB error.
156If uncertain, use
157.Sy USB_FAILURE .
158.Sh SEE ALSO
159.Xr usba_hcdi 9E ,
160.Xr usba_hcdi_pipe_stop_intr_polling 9E ,
161.Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
162.Xr usb_ep_descr 9S ,
163.Xr usb_ep_xdescr 9S ,
164.Xr usba_pipe_handle_data 9S
165