Changeset 2e2af3a in mainline for uspace/drv/bus/usb/xhci/endpoint.c

Timestamp:

2017-12-27T20:43:24Z (6 years ago)

Author:

Petr Manek <petr.manek@…>

Branches:

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

Children:

95a62dc

Parents:

f4b83cc

git-author:

Petr Manek <petr.manek@…> (2017-12-27 19:50:18)

git-committer:

Petr Manek <petr.manek@…> (2017-12-27 20:43:24)

Message:

xhci: add docstrings in endpoint.c

File:

• uspace/drv/bus/usb/xhci/endpoint.c (modified) (21 diffs)

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

@@ -45 +45 @@
 #include "endpoint.h"
 
+/** Initialize new XHCI endpoint.
+ * @param[in] xhci_ep Allocated XHCI endpoint to initialize.
+ * @param[in] dev Device, to which the endpoint belongs.
+ * @param[in] desc USB endpoint descriptor carrying configuration data.
+ *
+ * @return Error code.
+ */
 int xhci_endpoint_init(xhci_endpoint_t *xhci_ep, device_t *dev, const usb_endpoint_desc_t *desc)
 {
@@ -75 +82 @@
 }
 
+/** Finalize XHCI endpoint.
+ * @param[in] xhci_ep XHCI endpoint to finalize.
+ */
 void xhci_endpoint_fini(xhci_endpoint_t *xhci_ep)
 {
@@ -82 +92 @@
 }
 
+/** Determine the type of a XHCI endpoint.
+ * @param[in] ep XHCI endpoint to query.
+ *
+ * @return EP_TYPE_[CONTROL|ISOCH|BULK|INTERRUPT]_[IN|OUT]
+ */
 static int xhci_endpoint_type(xhci_endpoint_t *ep)
 {
@@ -106 +121 @@
 }
 
+/** Test whether an XHCI endpoint uses streams.
+ * @param[in] xhci_ep XHCI endpoint to query.
+ *
+ * @return True if the endpoint uses streams.
+ */
 static bool endpoint_using_streams(xhci_endpoint_t *xhci_ep)
 {
@@ -111 +131 @@
 }
 
+/** Determine maximum size of XHCI endpoint's Primary Stream Context Array.
+ * @param[in] xhci_ep XHCI endpoint to query.
+ *
+ * @return Number of items in the Primary Stream Context Array.
+ */
 static size_t primary_stream_ctx_array_max_size(xhci_endpoint_t *xhci_ep)
 {
@@ -130 +155 @@
 // }
 
+/** Initialize primary streams of XHCI bulk endpoint.
+ * @param[in] hc Host controller of the endpoint.
+ * @param[in] xhci_epi XHCI bulk endpoint to use.
+ * @param[in] count Number of primary streams to initialize.
+ */
 static void initialize_primary_streams(xhci_hc_t *hc, xhci_endpoint_t *xhci_ep, unsigned count) {
         for (size_t index = 0; index < count; ++index) {
@@ -136 +166 @@
 
                 /* Init and register TRB ring for every primary stream */
-                xhci_trb_ring_init(ring);
+                xhci_trb_ring_init(ring); // FIXME: Not checking error code?
                 XHCI_STREAM_DEQ_PTR_SET(*ctx, ring->dequeue);
 
@@ -144 +174 @@
 }
 
+/** Configure XHCI bulk endpoint's stream context.
+ * @param[in] xhci_ep Associated XHCI bulk endpoint.
+ * @param[in] ctx Endpoint context to configure.
+ * @param[in] pstreams The value of MaxPStreams.
+ */
 static void setup_stream_context(xhci_endpoint_t *xhci_ep, xhci_ep_ctx_t *ctx, unsigned pstreams) {
         XHCI_EP_TYPE_SET(*ctx, xhci_endpoint_type(xhci_ep));
@@ -156 +191 @@
 }
 
+/** TODO document this
+ */
 int xhci_endpoint_request_streams(xhci_hc_t *hc, xhci_device_t *dev, xhci_endpoint_t *xhci_ep, unsigned count) {
         if (xhci_ep->base.transfer_type != USB_TRANSFER_BULK
@@ -210 +247 @@
 }
 
+/** TODO document this
+ */
 static int xhci_isoch_alloc_transfers(xhci_endpoint_t *xhci_ep) {
         int i = 0;
@@ -234 +273 @@
 }
 
+/** Allocate transfer data structures for XHCI endpoint.
+ * @param[in] xhci_ep XHCI endpoint to allocate data structures for.
+ *
+ * @return Error code.
+ */
 int xhci_endpoint_alloc_transfer_ds(xhci_endpoint_t *xhci_ep)
 {
@@ -256 +300 @@
 }
 
+/** Free transfer data structures for XHCI endpoint.
+ * @param[in] xhci_ep XHCI endpoint to free data structures for.
+ */
 void xhci_endpoint_free_transfer_ds(xhci_endpoint_t *xhci_ep)
 {
@@ -311 +358 @@
 }
 
+/** Configure endpoint context of a control endpoint.
+ * @param[in] ep XHCI control endpoint.
+ * @param[in] ctx Endpoint context to configure.
+ */
 static void setup_control_ep_ctx(xhci_endpoint_t *ep, xhci_ep_ctx_t *ctx)
 {
@@ -322 +373 @@
 }
 
+/** Configure endpoint context of a bulk endpoint.
+ * @param[in] ep XHCI bulk endpoint.
+ * @param[in] ctx Endpoint context to configure.
+ */
 static void setup_bulk_ep_ctx(xhci_endpoint_t *ep, xhci_ep_ctx_t *ctx)
 {
@@ -334 +389 @@
 }
 
+/** Configure endpoint context of a isochronous endpoint.
+ * @param[in] ep XHCI isochronous endpoint.
+ * @param[in] ctx Endpoint context to configure.
+ */
 static void setup_isoch_ep_ctx(xhci_endpoint_t *ep, xhci_ep_ctx_t *ctx)
 {
@@ -348 +407 @@
 }
 
+/** Configure endpoint context of a interrupt endpoint.
+ * @param[in] ep XHCI interrupt endpoint.
+ * @param[in] ctx Endpoint context to configure.
+ */
 static void setup_interrupt_ep_ctx(xhci_endpoint_t *ep, xhci_ep_ctx_t *ctx)
 {
@@ -360 +423 @@
 }
 
+/** Type of endpoint context configuration function. */
 typedef void (*setup_ep_ctx_helper)(xhci_endpoint_t *, xhci_ep_ctx_t *);
 
+/** Static array, which maps USB endpoint types to their respective endpoint context configuration functions. */
 static const setup_ep_ctx_helper setup_ep_ctx_helpers[] = {
         [USB_TRANSFER_CONTROL] = setup_control_ep_ctx,
@@ -369 +434 @@
 };
 
+/** Configure endpoint context of XHCI endpoint.
+ * @param[in] ep Associated XHCI endpoint.
+ * @param[in] ep_ctx Endpoint context to configure.
+ */
 void xhci_setup_endpoint_context(xhci_endpoint_t *ep, xhci_ep_ctx_t *ep_ctx)
 {
@@ -381 +450 @@
 }
 
+/** Add a new XHCI endpoint to a device. The device must be online unless
+ * the added endpoint is number 0.
+ * @param[in] dev XHCI device, to which to add the endpoint
+ * @param[in] ep XHCI endpoint to add.
+ *
+ * @return Error code.
+ */
 int xhci_device_add_endpoint(xhci_device_t *dev, xhci_endpoint_t *ep)
 {
@@ -404 +480 @@
 }
 
+/** Remove XHCI endpoint from a device.
+ * @param[in] ep XHCI endpoint to remove.
+ */
 void xhci_device_remove_endpoint(xhci_endpoint_t *ep)
 {
@@ -416 +495 @@
 }
 
+/** Retrieve XHCI endpoint from a device by the endpoint number.
+ * @param[in] dev XHCI device to query.
+ * @param[in] ep Endpoint number identifying the endpoint to retrieve.
+ *
+ * @return XHCI endpoint with the specified number or NULL if no such endpoint exists.
+ */
 xhci_endpoint_t *xhci_device_get_endpoint(xhci_device_t *dev, usb_endpoint_t ep)
 {