Changeset eb928c4 in mainline for uspace/drv/bus/usb/xhci/hc.c

Timestamp:

2018-01-08T00:07:00Z (6 years ago)

Author:

Ondřej Hlavatý <aearsis@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

1102eca

Parents:

ecbad17

git-author:

Ondřej Hlavatý <aearsis@…> (2018-01-08 00:05:39)

git-committer:

Ondřej Hlavatý <aearsis@…> (2018-01-08 00:07:00)

Message:

xhci: documentation & cleanup

Also, a simple refactoring to remove functions that only wraps another
functions unused anywhere else.

File:

• uspace/drv/bus/usb/xhci/hc.c (modified) (20 diffs)

uspace/drv/bus/usb/xhci/hc.c

@@ -66 +66 @@
 /**
  * Walk the list of extended capabilities.
+ *
+ * The most interesting thing hidden in extended capabilities is the mapping of
+ * ports to protocol versions and speeds.
  */
 static int hc_parse_ec(xhci_hc_t *hc)
@@ -145 +148 @@
 }
 
+/**
+ * Initialize MMIO spaces of xHC.
+ */
 int hc_init_mmio(xhci_hc_t *hc, const hw_res_list_parsed_t *hw_res)
 {
@@ -195 +201 @@
 }
 
+/**
+ * Initialize structures kept in allocated memory.
+ */
 int hc_init_memory(xhci_hc_t *hc, ddf_dev_t *device)
 {
@@ -338 +347 @@
 }
 
+/**
+ * Claim xHC from BIOS. Implements handoff as per Section 4.22.1 of xHCI spec.
+ */
 int hc_claim(xhci_hc_t *hc, ddf_dev_t *dev)
 {
@@ -344 +356 @@
                 return EOK;
 
-        /* Section 4.22.1 */
         /* TODO: Test this with USB3-aware BIOS */
         usb_log_debug2("LEGSUP: bios: %x, os: %x", hc->legsup->sem_bios, hc->legsup->sem_os);
@@ -363 +374 @@
 }
 
+/**
+ * Ask the xHC to reset its state. Implements sequence 
+ */
 static int hc_reset(xhci_hc_t *hc)
 {
@@ -454 +468 @@
 }
 
-int hc_schedule(usb_transfer_batch_t *batch)
-{
-        assert(batch);
-        xhci_hc_t *hc = bus_to_hc(endpoint_get_bus(batch->ep));
-
-        if (!batch->target.address) {
-                usb_log_error("Attempted to schedule transfer to address 0.");
-                return EINVAL;
-        }
-
-        return xhci_transfer_schedule(hc, batch);
-}
-
 typedef int (*event_handler) (xhci_hc_t *, xhci_trb_t *trb);
 
@@ -484 +485 @@
 }
 
+/**
+ * Dequeue from event ring and handle dequeued events.
+ *
+ * As there can be events, that blocks on waiting for subsequent events,
+ * we solve this problem by first copying the event TRBs from the event ring,
+ * then asserting EHB and only after, handling the events.
+ *
+ * Whenever the event handling blocks, it switches fibril, and incoming
+ * IPC notification will create new event handling fibril for us.
+ */
 static void hc_run_event_ring(xhci_hc_t *hc, xhci_event_ring_t *event_ring, xhci_interrupter_regs_t *intr)
 {
@@ -541 +552 @@
 }
 
+/**
+ * Handle an interrupt request from xHC. Resolve all situations that trigger an
+ * interrupt separately.
+ *
+ * Note that all RW1C bits in USBSTS register are cleared at the time of
+ * handling the interrupt in irq_code. This method is the top-half.
+ *
+ * @param status contents of USBSTS register at the time of the interrupt.
+ */
 void hc_interrupt(bus_t *bus, uint32_t status)
 {
@@ -573 +593 @@
 }
 
+/**
+ * Tear down all in-memory structures.
+ */
 void hc_fini(xhci_hc_t *hc)
 {
@@ -585 +608 @@
 }
 
+/**
+ * Ring a xHC Doorbell. Implements section 4.7.
+ */
 int hc_ring_doorbell(xhci_hc_t *hc, unsigned doorbell, unsigned target)
 {
@@ -594 +620 @@
 }
 
+/**
+ * Issue an Enable Slot command, returning the obtained Slot ID.
+ *
+ * @param slot_id Pointer where to store the obtained Slot ID.
+ */
 int hc_enable_slot(xhci_hc_t *hc, uint32_t *slot_id)
 {
@@ -615 +646 @@
 }
 
+/**
+ * Issue a Disable Slot command for a slot occupied by device.
+ *
+ * Frees the device context 
+ */
 int hc_disable_slot(xhci_hc_t *hc, xhci_device_t *dev)
 {
@@ -634 +670 @@
 }
 
+/**
+ * Prepare an empty Endpoint Input Context inside a dma buffer.
+ */
 static int create_configure_ep_input_ctx(dma_buffer_t *dma_buf)
 {
@@ -649 +688 @@
 }
 
+/**
+ * Initialize a device, assigning it an address. Implements section 4.3.4.
+ *
+ * @param dev Device to assing an address (unconfigured yet)
+ * @param ep0 EP0 of device TODO remove, can be fetched from dev
+ */
 int hc_address_device(xhci_hc_t *hc, xhci_device_t *dev, xhci_endpoint_t *ep0)
 {
@@ -713 +758 @@
 }
 
+/**
+ * Issue a Configure Device command for a device in slot.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ */
 int hc_configure_device(xhci_hc_t *hc, uint32_t slot_id)
 {
@@ -726 +776 @@
 }
 
+/**
+ * Issue a Deconfigure Device command for a device in slot.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ */
 int hc_deconfigure_device(xhci_hc_t *hc, uint32_t slot_id)
 {
@@ -732 +787 @@
 }
 
+/**
+ * Instruct xHC to add an endpoint with supplied endpoint context.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ * @param ep_idx Endpoint index (number + direction) in question
+ * @param ep_ctx Endpoint context of the endpoint
+ */
 int hc_add_endpoint(xhci_hc_t *hc, uint32_t slot_id, uint8_t ep_idx, xhci_ep_ctx_t *ep_ctx)
 {
@@ -748 +810 @@
 }
 
+/**
+ * Instruct xHC to drop an endpoint.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ * @param ep_idx Endpoint index (number + direction) in question
+ */
 int hc_drop_endpoint(xhci_hc_t *hc, uint32_t slot_id, uint8_t ep_idx)
 {
@@ -763 +831 @@
 }
 
+/**
+ * Instruct xHC to update information about an endpoint, using supplied
+ * endpoint context.
+ *
+ * @param slot_id Slot ID assigned to the device.
+ * @param ep_idx Endpoint index (number + direction) in question
+ * @param ep_ctx Endpoint context of the endpoint
+ */
 int hc_update_endpoint(xhci_hc_t *hc, uint32_t slot_id, uint8_t ep_idx, xhci_ep_ctx_t *ep_ctx)
 {