Changeset 61e27e80 in mainline

Timestamp:

2018-01-17T12:29:19Z (7 years ago)

Author:

Salmelu <salmelu@…>

Branches:

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

Children:

1af4c00

Parents:

5dab9ef0

Message:

xhci: streams: documentation comments

File:

• uspace/drv/bus/usb/xhci/streams.c (modified) (12 diffs)

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

@@ -39 +39 @@
 #include "streams.h"
 
+/** Finds stream data with given stream ID if it exists.
+ * Note that streams with ID 0, 65534 and 65535 are reserved.
+ * Splits the ID into primary and secondary context ID and searches the structures.
+ * @param[in] ep Affected endpoint.
+ * @param[in] stream_id Id of the stream.
+ */
 xhci_stream_data_t *xhci_get_stream_ctx_data(xhci_endpoint_t *ep, uint32_t stream_id)
 {
@@ -70 +76 @@
 }
 
+/** Initializes primary stream data structures in endpoint.
+ * @param[in] xhci_ep Used XHCI bulk endpoint.
+ * @param[in] count Amount of primary streams.
+ */
 static int initialize_primary_structures(xhci_endpoint_t *xhci_ep, unsigned count)
 {
@@ -91 +101 @@
 }
 
+/**
+ *
+ */
 static void clear_primary_structures(xhci_endpoint_t *xhci_ep)
 {
@@ -125 +138 @@
 }
 
-/** Initialize primary stream structure with given index.
- * @param[in] hc Host controller of the endpoint.
- * @param[in] xhci_epi XHCI bulk endpoint to use.
+/** Initialize a single primary stream structure with given index.
+ * @param[in] hc Host controller of the endpoint.
+ * @param[in] xhci_ep XHCI bulk endpoint to use.
  * @param[in] index index of the initialized stream structure.
  */
@@ -137 +150 @@
         int err = EOK;
 
-        /* Init and register TRB ring for every primary stream */
+        /* Init and register TRB ring for the primary stream */
         if ((err = xhci_trb_ring_init(&data->ring))) {
                 return err;
@@ -182 +195 @@
 {
         if (count == 0) {
+                /* The primary stream context can still point to a single ring, not a secondary. */
                 return initialize_primary_stream(hc, xhci_ep, idx);
         }
@@ -209 +223 @@
         XHCI_STREAM_SCT_SET(*ctx, fnzb32(count) + 1);
 
+        /* Initialize all the rings. */
         int err = EOK;
         size_t index;
@@ -251 +266 @@
 }
 
+/** Verifies if all the common preconditions are satisfied.
+ * @param[in] hc Host controller of the endpoint.
+ * @param[in] dev Used device.
+ * @param[in] xhci_ep Associated XHCI bulk endpoint.
+ * @param[in] count Amount of primary streams requested.
+ */
 static int verify_stream_conditions(xhci_hc_t *hc, xhci_device_t *dev,
         xhci_endpoint_t *xhci_ep, unsigned count)
@@ -270 +291 @@
         }
 
-        uint8_t max_psa_size = 2 << XHCI_REG_RD(hc->cap_regs, XHCI_CAP_MAX_PSA_SIZE);
+        /* The maximum amount of primary streams is 2 ^ (MaxPSA + 1) (See table 26 of XHCI specification) */
+        uint8_t max_psa_size = 1 << (XHCI_REG_RD(hc->cap_regs, XHCI_CAP_MAX_PSA_SIZE) + 1);
         if (count > max_psa_size) {
                 usb_log_error("Host controller only supports %u primary streams.", max_psa_size);
@@ -290 +312 @@
 }
 
-/** Initialize primary streams
+/** Initialize, setup and register primary streams.
+ * @param[in] hc Host controller of the endpoint.
+ * @param[in] dev Used device.
+ * @param[in] xhci_ep Associated XHCI bulk endpoint.
+ * @param[in] count Amount of primary streams requested.
  */
 int xhci_endpoint_request_primary_streams(xhci_hc_t *hc, xhci_device_t *dev,
@@ -313 +339 @@
 
         xhci_ep_ctx_t ep_ctx;
+        /* Allowed values are 1-15, where 2 ^ pstreams is the actual amount of streams. */
         const size_t pstreams = fnzb32(count) - 1;
         setup_stream_context(xhci_ep, &ep_ctx, pstreams, 1);
@@ -320 +347 @@
 }
 
-/** Initialize secondary streams
- * sizes - the size of each secondary stream context (an array)
- * count - the amount of primary stream contexts
+/** Initialize, setup and register secondary streams.
+ * @param[in] hc Host controller of the endpoint.
+ * @param[in] dev Used device.
+ * @param[in] xhci_ep Associated XHCI bulk endpoint.
+ * @param[in] sizes Amount of secondary streams in each primary stream.
+                                        This array should have exactly count elements.
+                                        If the size is 0, then a primary ring is created with that index.
+ * @param[in] count Amount of primary streams requested.
  */
 int xhci_endpoint_request_secondary_streams(xhci_hc_t *hc, xhci_device_t *dev,