Changeset 95a62dc in mainline

Timestamp:

2017-12-27T20:52:25Z (6 years ago)

Author:

Petr Manek <petr.manek@…>

Branches:

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

Children:

67d58e8

Parents:

2e2af3a

git-author:

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

git-committer:

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

Message:

xhci: add [some] docstrings in bus.c

File:

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

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

@@ -50 +50 @@
 
 
+/** Initial descriptor used for control endpoint 0 before more configuration is retrieved. */
 static const usb_endpoint_desc_t ep0_initial_desc = {
         .endpoint_no = 0,
@@ -60 +61 @@
 static endpoint_t *endpoint_create(device_t *, const usb_endpoint_desc_t *);
 
+/** Assign address and control endpoint to a new XHCI device.
+ * @param[in] bus XHCI bus, in which the address is assigned.
+ * @param[in] dev New device to address and configure.
+ *
+ * @return Error code.
+ */
 static int address_device(xhci_bus_t *bus, xhci_device_t *dev)
 {
@@ -106 +113 @@
 }
 
+/** Retrieve and set maximum packet size for endpoint zero of a XHCI device.
+ * @param[in] hc Host controller, which manages the device.
+ * @param[in] dev Device with operational endpoint zero.
+ *
+ * @return Error code.
+ */
 static int setup_ep0_packet_size(xhci_hc_t *hc, xhci_device_t *dev)
 {
@@ -131 +144 @@
 }
 
+/** Respond to a new device on the XHCI bus. Address it, negotiate packet size
+ * and retrieve USB descriptors.
+ * @param[in] bus XHCI bus, where the new device emerged.
+ * @param[in] dev XHCI device, which has appeared on the bus.
+ *
+ * @return Error code.
+ */
 int xhci_bus_enumerate_device(xhci_bus_t *bus, device_t *dev)
 {
@@ -182 +202 @@
 static int endpoint_unregister(endpoint_t *);
 
+/** Remove device from XHCI bus. Transition it to the offline state, abort all
+ * ongoing transfers and unregister all of its endpoints.
+ * @param[in] bus XHCI bus, from which the device is removed.
+ * @param[in] dev XHCI device, which is removed from the bus.
+ *
+ * @return Error code.
+ */
 int xhci_bus_remove_device(xhci_bus_t *bus, device_t *dev)
 {
@@ -244 +271 @@
         return (xhci_bus_t *) bus_base;
 }
+
+// TODO: Fill in docstrings for XHCI bus callbacks once generic bus callbacks get their docstrings.
 
 static int device_enumerate(device_t *dev)
@@ -479 +508 @@
 }
 
+/** Structure binding XHCI static callbacks to generic bus callbacks. */
 static const bus_ops_t xhci_bus_ops = {
+// TODO: Is it good idea to use this macro? It blurrs the fact that the callbacks and static functions are called the same.
 #define BIND_OP(op) .op = op,
         BIND_OP(reserve_default_address)
@@ -507 +538 @@
 };
 
+/** Initialize XHCI bus.
+ * @param[in] bus Allocated XHCI bus to initialize.
+ * @param[in] hc Associated host controller, which manages the bus.
+ *
+ * @return Error code.
+ */
 int xhci_bus_init(xhci_bus_t *bus, xhci_hc_t *hc)
 {
@@ -523 +560 @@
 }
 
+/** Finalize XHCI bus.
+ * @param[in] bus XHCI bus to finalize.
+ */
 void xhci_bus_fini(xhci_bus_t *bus)
 {
-
+        // FIXME: Deallocate bus->devices_by_slot?
+        // FIXME: Should there be some bus_fini() to call?
+        // FIXME: Something else we forgot?
 }