From efb7c86c45b774dc0b142b089d8bd2229ae57a33 Mon Sep 17 00:00:00 2001 From: Bertrand SIMONNET Date: Mon, 2 May 2016 16:24:12 -0700 Subject: Document the HAL. Documents and explain the HAL to facilitate its implementation. Bug: 28522721 Change-Id: Ie65610b5f6f0e61a92ea6558deb2f54eb93f3e90 --- hal/hardware/peripheral_io.h | 219 +++++++++++++++++++++++++++++++++++++------ 1 file 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 -- cgit v1.2.3