Document the HAL.

Documents and explain the HAL to facilitate its implementation.

Bug: 28522721

Change-Id: Ie65610b5f6f0e61a92ea6558deb2f54eb93f3e90

1 files changed, 192 insertions, 27 deletions

diff --git a/hal/hardware/peripheral_io.h b/hal/hardware/peripheral_io.h
index dd55b8f..1de31ef 100644
--- a/hal/hardware/peripheral_io.h
+++ b/hal/hardware/peripheral_io.h
@@ -34,41 +34,206 @@ __BEGIN_DECLS
  * Possible GPIO direction configuration.
  */
 typedef enum {
-  GPIO_DIRECTION_IN,
-  GPIO_DIRECTION_OUT_LOW,
-  GPIO_DIRECTION_OUT_HIGH
+  GPIO_DIRECTION_IN,      /** Input */
+  GPIO_DIRECTION_OUT_LOW, /** Output, initially low */
+  GPIO_DIRECTION_OUT_HIGH /** Output, initially high */
 } gpio_direction_t;
 
+/**
+ * Callback to enable a given pinmux source on a specific pin.
+ *
+ * Args:
+ *  pin: Name of the pin.
+ *  source: Name of the pinmux source to enable. When NULL, setup the pinmux
+ *          to enable GPIO on this pin.
+ *
+ * Returns:
+ *  0 on success, errno on error.
+ */
 typedef int (*pin_mux_cb)(const char* pin, const char* source);
-typedef int (*pin_mux_directon_cb)(const char* pin, int dir);
 
+/**
+ * Callback to set the direction of a given GPIO.
+ *
+ * Args:
+ *  pin: Name of the pin to configure.
+ *  dir: Direction to set. One of gpio_direction_t.
+ *
+ * Returns:
+ *  0 on success, errno on error.
+ */
+typedef int (*pin_mux_direction_cb)(const char* pin, int dir);
+
+/**
+ * Callbacks used by peripheral manager to configure given pins.
+ */
 typedef struct pin_mux_callbacks {
   pin_mux_cb mux_cb;
-  pin_mux_directon_cb direction_cb;
+  pin_mux_direction_cb direction_cb;
 } pin_mux_callbacks;
 
+/**
+ * Callbacks into peripheral manager.
+ *
+ * Those callbacks must be used in register_devices to declare the available
+ * interfaces to peripheral manager.
+ *
+ * All peripherals are referred to by their friendly name.
+ * The friendly name is a string, used to refer to a given peripheral (ex: gpio
+ * name, spi bus name) that is simple to understand, well documented for the
+ * board and unambiguous.
+ *
+ * Before coming up with a new naming scheme, consider:
+ * - Using an existing naming scheme: if the board provides an arduino pinout, a
+ *   raspberry Pi pinout or a 96 boards pinout, use it.
+ * - Using the names written on the board next to the physical ports if any.
+ * - Using the documented name when widely available.
+ *   Referring to the same pin or peripheral by two different names in the
+ *   documentation and in peripheral manager would be confusing to the user.
+ *
+ * If coming up with a new name, use only simple characters (ideally, A-Z, 0-9,
+ * -, _).
+ */
 typedef struct peripheral_registration_cb_t {
-  // TODO(leecam): Fix up the comments.
-
-  // Pin Mux functions.
+  /**
+   * Register a pin.
+   *
+   * Args:
+   *  name: Friendly name (see definition above) of the pin.
+   *  callbacks: Callbacks used to set up pinmuxes.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*register_pin)(const char* name, int gpio, pin_mux_callbacks callbacks);
+
+  /**
+   * Register a pin group.
+   *
+   * Args:
+   *  name: Name of the group.
+   *  pins: List of pin names that are part of the group.
+   *  nr_pins: Size of |pins|.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*register_pin_group)(const char* name, char** pins, size_t nr_pins);
+
+  /**
+   * Register a pinmux source.
+   *
+   * Args:
+   *  name: Name of the pinmux source.
+   *  groups: List of possible pinmux groups this source can come up on.
+   *  nr_groups: Size of |groups|.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*register_source)(const char* name, char** groups, size_t nr_groups);
-  int (*register_simple_source)(const char* name, const char** pins, size_t nr_pins);
 
-  // Gpio functions.
+  /**
+   * Register a simple source, mapped to a single pin group.
+   *
+   * This convenience function replaces the two calls to register_pin_group and
+   * register_source in most cases.
+   *
+   * Args:
+   *  name: Name of the pinmux source.
+   *  pins: List of pins this source comes up on.
+   *  nr_pins: Size of |pins|.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
+  int (*register_simple_source)(const char* name,
+                                const char** pins,
+                                size_t nr_pins);
+
+  /**
+   * Register a sysfs backed GPIO.
+   *
+   * Args:
+   *  name: Friendly name of the GPIO.
+   *  index: Index of the gpio in sysfs.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*register_gpio_sysfs)(const char* name, uint32_t index);
+
+  /**
+   * Set the pinmux for a given GPIO.
+   *
+   * Args:
+   *  name: Friendly name of the pin.
+   *  source: Name of the pinmux source.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*set_gpio_pin_mux)(const char* name, const char* source);
 
-  // Spi functions.
+  /**
+   * Register a SPI device.
+   *
+   * Args:
+   *  name: Friendly name of the device.
+   *  bus: Bus number.
+   *  cs: Chip select.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*register_spi_dev_bus)(const char* name, uint32_t bus, uint32_t cs);
+
+  /**
+   * Set the pinmux for a given SPI device.
+   *
+   * Args:
+   *  name: Friendly name of the device.
+   *  source: Name of the pinmuxing source.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*set_spi_pin_mux)(const char* name, const char* source);
 
-  // Led functions
+  /**
+   * Register a sysfs-backed LED.
+   *
+   * Args:
+   *  name: Friendly name of the LED.
+   *  sysfs_name: Name of the device in sysfs.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*register_led_sysfs)(const char* name, const char* sysfs_name);
 
-  // I2c functions.
+  /**
+   * Register an I2C bus.
+   *
+   * Args:
+   *  name: Friendly name of the I2C device.
+   *  bus: I2C bus number.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*register_i2c_dev_bus)(const char* name, uint32_t bus);
+
+  /**
+   * Set the pinmux for a given I2C bus.
+   *
+   * Args:
+   *  name: Friendly name of the I2C bus.
+   *  source: Name of the pinmuxing source.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
   int (*set_i2c_pin_mux)(const char* name, const char* source);
 
 } peripheral_registration_cb_t;
@@ -76,20 +241,20 @@ typedef struct peripheral_registration_cb_t {
 typedef struct peripheral_io_module_t peripheral_io_module_t;
 
 struct peripheral_io_module_t {
-    struct hw_module_t common;
-
-    /**
-     * Register all available devices with the peripheral manager.
-     *
-     * Arguments:
-     *    dev: Pointer to the peripheral_io module.
-     *    callbacks: Callbacks into peripheral manager to add specific devices.
-     *
-     * Returns:
-     *    0 on success, errno on error.
-     */
-    int (*register_devices)(const peripheral_io_module_t* dev,
-                            const peripheral_registration_cb_t* callbacks);
+  struct hw_module_t common;
+
+  /**
+   * Register all available devices with the peripheral manager.
+   *
+   * Arguments:
+   *  dev: Pointer to the peripheral_io module.
+   *  callbacks: Callbacks into peripheral manager to register devices.
+   *
+   * Returns:
+   *  0 on success, errno on error.
+   */
+  int (*register_devices)(const peripheral_io_module_t* dev,
+                          const peripheral_registration_cb_t* callbacks);
 };
 
 __END_DECLS