162 device initialization in an attach(9E) entry point. For example, PCI
163 devices should setup the device's registers and program them. In
164 addition, all devices should configure interrupts, before getting ready
165 to call into the USBA. Each instance of a device must be initialized and
166 registered with the USBA.
167
168 To initialize a device driver with the USBA, it must first call
169 usba_alloc_hcdi_ops(9F). This provides a device driver with the
170 usba_hcdi_ops(9S) structure that it must fill out. Please see
171 usba_hcdi_ops(9S) for instructions on how it should be filled out. Once
172 filled out, the driver should call usba_hcdi_register(9F).
173
174 If the call to register fails for whatever reason, the device driver
175 should fail its attach(9E) entry point. After this call successfully
176 completes, the driver should assume that any of the functions it
177 registered with the call to usba_hcdi_register(9F) will be called at this
178 point.
179
180 Binding the Root Hub
181 Once this is set up, the hcdi driver must initialize its root hub by
182 calling Xr usba_hcdi_bind_root_hub 9F . To bind the root hub, the device
183 driver is responsible for providing a device descriptor that represents
184 the hardware.
185 Depending on the hardware, this descriptor may be either static or
186 dynamic.
187
188 This device descriptor should be a packed descriptor that is the same
189 that would be read off of the device. The device descriptor should match
190 a hub of a USB generation equivalent to the maximum speed of the device.
191 For example, a USB 3.0 host controller would use a USB 3.0 hub's device
192 descriptor. Similarly, a USB 2.0 host controller would use a USB 2.0
193 hub's device descriptor.
194
195 The descriptor first starts with a USB configuration descriptor, as
196 defined in usb_cfg_descr(9S). It is then followed by an interface
197 descriptor. The definition for it can be found in usb_if_descr(9S).
198 Next is the endpoint descriptor for the single Interrupt-IN endpoint that
199 all hubs have as defined in usb_ep_descr(9S). Finally, any required
200 companion descriptors should be used. For example, a USB 3.x hub will
201 have a usb_ep_ss_comp_descr(9S) appended to the structure.
202
203 Note, that the structure needs to be packed, as though it were read from
204 a device. The structures types referenced in usb_cfg_descr(9S),
205 usb_if_descr(9S), usb_ep_descr(9S), and usb_ep_ss_comp_descr(9S) are not
206 packed for this purpose. They should not be used as they have gaps added
207 by the compiler for alignment.
208
209 Once assembled, the device driver should call
210 usba_hubdi_bind_root_hub(9F). This will cause an instance of the
211 hubd(7D) driver to be attached and associated with the root controller.
212 As such, driver writers need to ensure that all initialization is done
213 prior to loading the root hub. Once successfully loaded, driver writers
214 should assume that they'll get other calls into the driver's operation
215 vector before the call to usba_hubdi_bind_root_hub(9F.)
216
217 If the call to usba_hubdi_bind_root_hub(9F) failed for whatever reason,
218 the driver should unregister from USBA (see the next section), unwind all
219 of the resources it has allocated, and return DDI_FAILURE.
220
221 Otherwise, at this point it's safe to assume that the instance of the
222 device has initialized successfully and the driver should return
223 DDI_SUCCESS.
224
225 Driver Teardown
226 When a driver's detach(9E) entry point has been called, before anything
227 else is done, the device driver should unbind its instance of the root
228 hub and then unregister from the USBA.
229
230 To unbind the root hub, the instance of the driver should call
231 usba_hubdi_unbind_root_hub(9F). If for some reason that function does
232 not return USB_SUCCESS, then the device driver should fail the call to
233 detach(9E) and return DDI_FAILURE.
234
235 Once the root hub has been unbound, the device driver can continue by
|
162 device initialization in an attach(9E) entry point. For example, PCI
163 devices should setup the device's registers and program them. In
164 addition, all devices should configure interrupts, before getting ready
165 to call into the USBA. Each instance of a device must be initialized and
166 registered with the USBA.
167
168 To initialize a device driver with the USBA, it must first call
169 usba_alloc_hcdi_ops(9F). This provides a device driver with the
170 usba_hcdi_ops(9S) structure that it must fill out. Please see
171 usba_hcdi_ops(9S) for instructions on how it should be filled out. Once
172 filled out, the driver should call usba_hcdi_register(9F).
173
174 If the call to register fails for whatever reason, the device driver
175 should fail its attach(9E) entry point. After this call successfully
176 completes, the driver should assume that any of the functions it
177 registered with the call to usba_hcdi_register(9F) will be called at this
178 point.
179
180 Binding the Root Hub
181 Once this is set up, the hcdi driver must initialize its root hub by
182 calling usba_hubdi_bind_root_hub(9F). To bind the root hub, the device
183 driver is responsible for providing a device descriptor that represents
184 the hardware. Depending on the hardware, this descriptor may be either
185 static or dynamic.
186
187 This device descriptor should be a packed descriptor that is the same
188 that would be read off of the device. The device descriptor should match
189 a hub of a USB generation equivalent to the maximum speed of the device.
190 For example, a USB 3.0 host controller would use a USB 3.0 hub's device
191 descriptor. Similarly, a USB 2.0 host controller would use a USB 2.0
192 hub's device descriptor.
193
194 The descriptor first starts with a USB configuration descriptor, as
195 defined in usb_cfg_descr(9S). It is then followed by an interface
196 descriptor. The definition for it can be found in usb_if_descr(9S).
197 Next is the endpoint descriptor for the single Interrupt-IN endpoint that
198 all hubs have as defined in usb_ep_descr(9S). Finally, any required
199 companion descriptors should be used. For example, a USB 3.x hub will
200 have a usb_ep_ss_comp_descr(9S) appended to the structure.
201
202 Note, that the structure needs to be packed, as though it were read from
203 a device. The structures types referenced in usb_cfg_descr(9S),
204 usb_if_descr(9S), usb_ep_descr(9S), and usb_ep_ss_comp_descr(9S) are not
205 packed for this purpose. They should not be used as they have gaps added
206 by the compiler for alignment.
207
208 Once assembled, the device driver should call
209 usba_hubdi_bind_root_hub(9F). This will cause an instance of the
210 hubd(7D) driver to be attached and associated with the root controller.
211 As such, driver writers need to ensure that all initialization is done
212 prior to loading the root hub. Once successfully loaded, driver writers
213 should assume that they'll get other calls into the driver's operation
214 vector before the call to usba_hubdi_bind_root_hub(9F).
215
216 If the call to usba_hubdi_bind_root_hub(9F) failed for whatever reason,
217 the driver should unregister from USBA (see the next section), unwind all
218 of the resources it has allocated, and return DDI_FAILURE.
219
220 Otherwise, at this point it's safe to assume that the instance of the
221 device has initialized successfully and the driver should return
222 DDI_SUCCESS.
223
224 Driver Teardown
225 When a driver's detach(9E) entry point has been called, before anything
226 else is done, the device driver should unbind its instance of the root
227 hub and then unregister from the USBA.
228
229 To unbind the root hub, the instance of the driver should call
230 usba_hubdi_unbind_root_hub(9F). If for some reason that function does
231 not return USB_SUCCESS, then the device driver should fail the call to
232 detach(9E) and return DDI_FAILURE.
233
234 Once the root hub has been unbound, the device driver can continue by
|