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 Nov 26, 2017
15.Dt USBA_HCDI_REGISTER_ARGS 9S
16.Os
17.Sh NAME
18.Nm usba_hcdi_register_args ,
19.Nm usba_hcdi_register_args_t
20.Nd USB HCD driver registration
21.Sh SYNOPSIS
22.In sys/usb/usba/hcdi.h
23.Sh INTERFACE LEVEL
24.Sy Volatile -
25illumos USB HCD private
26.Pp
27This is a private data structure that is not part of the stable DDI.
28It may be removed or changed at any time.
29.Sh DESCRIPTION
30The
31.Sy usba_hcdi_register_args_t
32structure is used by USB HCD device drivers to register with the USBA
33framework.
34.Pp
35The structure is used with the
36.Xr usba_hcdi_register 9F
37function.
38Device drivers may statically allocate this structure on the stack.
39It does not need to be allocated on the heap or used beyond the call to
40.Xr usba_hcdi_register 9F .
41.Pp
42For more information on the HCD device driver initialization process,
43see
44.Xr usba_hcdi 9E .
45.Sh STRUCTURE MEMBERS
46The
47.Sy usba_hcdi_register_args_t
48structure has the following members:
49.Bd -literal -offset indent
50uint_t			usba_hcdi_register_version;
51dev_info_t		*usba_hcdi_register_dip;
52usba_hcdi_ops_t		*usba_hcdi_register_ops;
53ddi_dma_attr_t		*usba_hcdi_register_dma_attr;
54ddi_iblock_cookie_t	usba_hcdi_register_iblock_cookie;
55.Ed
56.Pp
57The
58.Sy usba_hcdi_register_version
59function should be set to the value of the pre-processor macro
60.Sy HCDI_REGISTER_VERSION .
61This ensures that if future revisions to this structure are made,
62existing drivers should continue to function.
63Note, that this structure is
64.Sy Volatile .
65Support for older versions or drastic changes may occur at any time and
66this should not be relied on nor construed as a guarantee against such
67changes.
68.Pp
69The
70.Sy usba_hcdi_register_dip
71should be set to the
72.Sy dev_info_t
73of the device driver instance that is registering with the USBA.
74.Pp
75The
76.Sy usba_hcdi_register_ops
77member is a structure of entry points for the USBA framework to call
78into the USB framework.
79It should be allocated with a call to
80.Xr usba_alloc_hcdi_ops 9F
81and released with a call to
82.Xr usba_free_hcdi_ops 9F ,
83after the driver has called
84.Xr usba_hcdi_register 9F .
85.Pp
86Please see
87.Xr usba_hcdi_ops 9S
88for more information on the members of the structure and for more
89information on how they should be filled in.
90.Pp
91The
92.Sy usba_hcdi_register_dma_attr
93member should be a pointer to a set of DMA attributes.
94These DMA attributes will be used by a subset of client device drivers to
95perform allocations, in particular scsa2usb.
96In general, try to make sure that these DMA attributes are valid for more
97transforms, though these will generally be used for bulk transfers.
98.Pp
99The
100.Sy usba_hcdi_register_iblock_cookie
101members should be filed in with the general interrupt priority of the
102device driver after it has allocated interrupts.
103Device drivers may obtain the priority by calling
104.Xr ddi_intr_get_pri 9F
105and then casting the obtained interrupt priority to the
106.Sy ddi_iblock_cookie_t .
107.Sh SEE ALSO
108.Xr usba_hcdi 9E ,
109.Xr ddi_intr_get_pri 9F ,
110.Xr usba_alloc_hcdi_ops 9F ,
111.Xr usba_free_hcdi_ops 9F ,
112.Xr usba_hcdi_register 9F ,
113.Xr usba_hcdi_ops 9S
114