Document the HAL.
Documents and explain the HAL to facilitate its implementation.
Bug: 28522721
Change-Id: Ie65610b5f6f0e61a92ea6558deb2f54eb93f3e90
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 @@
* 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);
- int (*register_pin_group)(const char* name, char** pins, size_t nr_pins);
- 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 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);
+
+ /**
+ * 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_io_module_t peripheral_io_module_t;
struct peripheral_io_module_t {
- struct hw_module_t common;
+ 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);
+ /**
+ * 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
