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