[haiku-commits] haiku: hrev54442 - docs/develop/busses/usb

  • From: Adrien Destugues <pulkomandy@xxxxxxxxx>
  • To: haiku-commits@xxxxxxxxxxxxx
  • Date: Sun, 19 Jul 2020 04:07:52 -0400 (EDT)

hrev54442 adds 1 changeset to branch 'master'
old head: bd514095bbcae303fd10d708eed1fb64d9e0b97c
new head: 25f1ddecf7c81f9fd03fbd9463aa6566b8d01fc4
overview: 
https://git.haiku-os.org/haiku/log/?qt=range&q=25f1ddecf7c8+%5Ebd514095bbca

----------------------------------------------------------------------------

25f1ddecf7c8: XHCI: add some docs after a chat with waddlesplash.
  
  Better than nothing, but quite likely very incomplete.
  
  Change-Id: I9c0399d9da3851689bdddce98647a43e8d1e4ccf
  Reviewed-on: https://review.haiku-os.org/c/haiku/+/1540
  Reviewed-by: Adrien Destugues <pulkomandy@xxxxxxxxx>

                             [ Adrien Destugues <pulkomandy@xxxxxxxxxxxxx> ]

----------------------------------------------------------------------------

Revision:    hrev54442
Commit:      25f1ddecf7c81f9fd03fbd9463aa6566b8d01fc4
URL:         https://git.haiku-os.org/haiku/commit/?id=25f1ddecf7c8
Author:      Adrien Destugues <pulkomandy@xxxxxxxxxxxxx>
Date:        Fri Jun 28 20:30:47 2019 UTC
Committer:   Adrien Destugues <pulkomandy@xxxxxxxxx>
Commit-Date: Sun Jul 19 08:07:48 2020 UTC

----------------------------------------------------------------------------

1 file changed, 47 insertions(+)
docs/develop/busses/usb/xhci.txt | 47 ++++++++++++++++++++++++++++++++++++

----------------------------------------------------------------------------

diff --git a/docs/develop/busses/usb/xhci.txt b/docs/develop/busses/usb/xhci.txt
new file mode 100644
index 0000000000..9c8d79cc51
--- /dev/null
+++ b/docs/develop/busses/usb/xhci.txt
@@ -0,0 +1,47 @@
+anyway, here's the summary of XHCI stuff:
+- XHCI operates in units of "TRBs", which consist of a pointer and two 32-bit
+  fields holding varying types of data based on the TRB type. A "normal" type
+  TRB usually has a pointer to a physical buffer and then in one of the fields,
+  an indicator of how many bytes are stored there
+- XHCI concept of "rings" is not, as you might expect, circular buffers.
+  Instead, it uses "Link TRBs", that is, a TRB in which the pointer field
+  points to the next place the hardware should read TRBs from, and it will do
+  so until hitting another Link TRB, etc. So it is in fact more like a linked
+  list. This allows easier management of the event queue, there is no need for
+  a fixed size ring, managing edge cases when the buffer wraps around, etc.
+
+The way we handle transfers in the XHCI driver is:
+- We allocate a "ring" of a small fixed amount for each endpoint (currently,
+  defined as XHCI_MAX_TRANSFERS*2+1, because we need 2 TRBs on the "ring" for
+  each transfer, and 1 at the end for the link to go back to the beginning)
+-  When the stack calls SubmitTransfer(), we allocate a new run of TRBs to
+  handle this transfer, and populate them with all the data. Then we insert one
+  Link TRB on the endpoint ring pointing to the first in the "transfer ring" we
+  just made, a link TRB at the end of the "transfer ring" pointing back to the
+  "endpoint ring", and then an "Event Status" TRB on the "endpoint ring" which
+  tells the XHCI to send an event back to us to tell us the transfer is done
+- For easier tracking, the driver also keeps a TD (transfer descriptor), which
+  is a sideband structure not sent to the hardware, but used to keep track of
+  the TRBs in a given endpoint ring.
+
+So under normal circumstances (i.e. all transfers submitted are successful), we
+will get back only "Event" TRBs generated by the "Event Data" TRBs from the
+"endpoint ring"s, and these will tell us what transfer they correspond to, we
+will notify it as successful, and all is well.
+
+If a transfer fails, then XHCI will generate an event that does *not*
+correspond to an Event Status TRB 
(src/add-ons/kernel/busses/usb/xhci.cpp#L2372).
+The pointer field in this TRB will point to the TRB that caused XHCI to
+generate the event (i.e. the failed TRB), and so we look through the transfers
+in progress on this endpoint and try to find which one corresponds to that TRB.
+
+However, it seems in your case we are failing to find it, and so we get a
+"TRB xxxx was not found in the endpoint!"
+Most likely this TRB is on the "endpoint ring" itself. However as noted before,
+only 2 TRBs for each transfer are actually on the endpoint ring: the Link TRB
+going to the "transfer ring", and the Event Data TRB telling XHCI to fire an
+interrupt.
+
+Valid Link TRBs should never fail to execute; and to my knowledge Event Data
+TRBs should not either.
+


Other related posts:

  • » [haiku-commits] haiku: hrev54442 - docs/develop/busses/usb - Adrien Destugues