[mirror_ubuntu-hirsute-kernel.git] / Documentation / usb / dwc3.rst

===========
DWC3 driver
===========


TODO
~~~~

Please pick something while reading :)

- Convert interrupt handler to per-ep-thread-irq

  As it turns out some DWC3-commands ~1ms to complete. Currently we spin
  until the command completes which is bad.

  Implementation idea:

  - dwc core implements a demultiplexing irq chip for interrupts per
    endpoint. The interrupt numbers are allocated during probe and belong
    to the device. If MSI provides per-endpoint interrupt this dummy
    interrupt chip can be replaced with "real" interrupts.
  - interrupts are requested / allocated on usb_ep_enable() and removed on
    usb_ep_disable(). Worst case are 32 interrupts, the lower limit is two
    for ep0/1.
  - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout()
    until the command completes.
  - the interrupt handler is split into the following pieces:

    - primary handler of the device
      goes through every event and calls generic_handle_irq() for event
      it. On return from generic_handle_irq() in acknowledges the event
      counter so interrupt goes away (eventually).

    - threaded handler of the device
      none

    - primary handler of the EP-interrupt
      reads the event and tries to process it. Everything that requires
      sleeping is handed over to the Thread. The event is saved in an
      per-endpoint data-structure.
      We probably have to pay attention not to process events once we
      handed something to thread so we don't process event X prio Y
      where X > Y.

    - threaded handler of the EP-interrupt
      handles the remaining EP work which might sleep such as waiting
      for command completion.

  Latency:

   There should be no increase in latency since the interrupt-thread has a
   high priority and will be run before an average task in user land
   (except the user changed priorities).
Commit	Line	Data
d80b5005 MCC	1	===========
	2	DWC3 driver
	3	===========
	4
	5
	6	TODO
	7	~~~~
72246da4	8
72246da4 FB	9	Please pick something while reading :)
72246da4 FB	10
72246da4 FB	11	- Convert interrupt handler to per-ep-thread-irq
	12
	13	As it turns out some DWC3-commands ~1ms to complete. Currently we spin
	14	until the command completes which is bad.
	15
	16	Implementation idea:
d80b5005	17
72246da4 FB	18	- dwc core implements a demultiplexing irq chip for interrupts per
	19	endpoint. The interrupt numbers are allocated during probe and belong
	20	to the device. If MSI provides per-endpoint interrupt this dummy
	21	interrupt chip can be replaced with "real" interrupts.
	22	- interrupts are requested / allocated on usb_ep_enable() and removed on
	23	usb_ep_disable(). Worst case are 32 interrupts, the lower limit is two
	24	for ep0/1.
	25	- dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout()
	26	until the command completes.
	27	- the interrupt handler is split into the following pieces:
d80b5005	28
72246da4 FB	29	- primary handler of the device
	30	goes through every event and calls generic_handle_irq() for event
	31	it. On return from generic_handle_irq() in acknowledges the event
	32	counter so interrupt goes away (eventually).
	33
	34	- threaded handler of the device
	35	none
	36
	37	- primary handler of the EP-interrupt
5edfe7d8	38	reads the event and tries to process it. Everything that requires
72246da4 FB	39	sleeping is handed over to the Thread. The event is saved in an
	40	per-endpoint data-structure.
	41	We probably have to pay attention not to process events once we
	42	handed something to thread so we don't process event X prio Y
	43	where X > Y.
	44
	45	- threaded handler of the EP-interrupt
	46	handles the remaining EP work which might sleep such as waiting
	47	for command completion.
	48
	49	Latency:
d80b5005	50
72246da4 FB	51	There should be no increase in latency since the interrupt-thread has a
	52	high priority and will be run before an average task in user land
	53	(except the user changed priorities).