zephyr/include/gpio.h

/*
 * Copyright (c) 2017 ARM Ltd
 * Copyright (c) 2015-2016 Intel Corporation.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

/**
 * @file
 * @brief Public APIs for GPIO drivers
 */

#ifndef __GPIO_H__
#define __GPIO_H__

#include <misc/__assert.h>
#include <misc/slist.h>

#include <zephyr/types.h>
#include <stddef.h>
#include <device.h>

/**
 * @brief GPIO Driver APIs
 * @defgroup gpio_interface GPIO Driver APIs
 * @ingroup io_interfaces
 * @{
 */
#ifdef __cplusplus
extern "C" {
#endif

/** @cond INTERNAL_HIDDEN */
#define GPIO_ACCESS_BY_PIN 0
#define GPIO_ACCESS_BY_PORT 1
/** @endcond */

/** GPIO pin to be input. */
#define GPIO_DIR_IN		(0 << 0)

/** GPIO pin to be output. */
#define GPIO_DIR_OUT		(1 << 0)

/** @cond INTERNAL_HIDDEN */
#define GPIO_DIR_MASK		0x1
/** @endcond */

/** GPIO pin to trigger interrupt. */
#define GPIO_INT		(1 << 1)

/** GPIO pin trigger on level low or falling edge. */
#define GPIO_INT_ACTIVE_LOW	(0 << 2)

/** GPIO pin trigger on level high or rising edge. */
#define GPIO_INT_ACTIVE_HIGH	(1 << 2)

/** GPIO pin trigger to be synchronized to clock pulses. */
#define GPIO_INT_CLOCK_SYNC     (1 << 3)

/** Enable GPIO pin debounce. */
#define GPIO_INT_DEBOUNCE       (1 << 4)

/** Do Level trigger. */
#define GPIO_INT_LEVEL		(0 << 5)

/** Do Edge trigger. */
#define GPIO_INT_EDGE		(1 << 5)

/** Interrupt triggers on both rising and falling edge. */
#define GPIO_INT_DOUBLE_EDGE	(1 << 6)

/*
 * GPIO_POL_* define the polarity of the GPIO (1 bit).
 */

/** @cond INTERNAL_HIDDEN */
#define GPIO_POL_POS		7
/** @endcond */

/** GPIO pin polarity is normal. */
#define GPIO_POL_NORMAL		(0 << GPIO_POL_POS)

/** GPIO pin polarity is inverted. */
#define GPIO_POL_INV		(1 << GPIO_POL_POS)

/** @cond INTERNAL_HIDDEN */
#define GPIO_POL_MASK		(1 << GPIO_POL_POS)
/** @endcond */

/*
 * GPIO_PUD_* are related to pull-up/pull-down.
 */

/** @cond INTERNAL_HIDDEN */
#define GPIO_PUD_POS		8
/** @endcond */

/** GPIO pin to have no pull-up or pull-down. */
#define GPIO_PUD_NORMAL		(0 << GPIO_PUD_POS)

/** Enable GPIO pin pull-up. */
#define GPIO_PUD_PULL_UP	(1 << GPIO_PUD_POS)

/** Enable GPIO pin pull-down. */
#define GPIO_PUD_PULL_DOWN	(2 << GPIO_PUD_POS)

/** @cond INTERNAL_HIDDEN */
#define GPIO_PUD_MASK		(3 << GPIO_PUD_POS)
/** @endcond */

/*
 * GPIO_PIN_(EN-/DIS-)ABLE are for pin enable / disable.
 *
 * Individual pins can be enabled or disabled
 * if the controller supports this operation.
 */

/** Enable GPIO pin. */
#define GPIO_PIN_ENABLE		(1 << 10)

/** Disable GPIO pin. */
#define GPIO_PIN_DISABLE	(1 << 11)

/* GPIO_DS_* are for pin drive strength configuration.
 *
 * The drive strength of individual pins can be configured
 * independently for when the pin output is low and high.
 *
 * The GPIO_DS_*_LOW enumerations define the drive strength of a pin
 * when output is low.

 * The GPIO_DS_*_HIGH enumerations define the drive strength of a pin
 * when output is high.
 *
 * The DISCONNECT drive strength indicates that the pin is placed in a
 * high impedance state and not driven, this option is used to
 * configure hardware that supports a open collector drive mode.
 *
 * The interface supports two different drive strengths:
 * DFLT - The lowest drive strength supported by the HW
 * ALT - The highest drive strength supported by the HW
 *
 * On hardware that supports only one standard drive strength, both
 * DFLT and ALT have the same behavior.
 *
 * On hardware that does not support a disconnect mode, DISCONNECT
 * will behave the same as DFLT.
 */

/** @cond INTERNAL_HIDDEN */
#define GPIO_DS_LOW_POS 12
#define GPIO_DS_LOW_MASK (0x3 << GPIO_DS_LOW_POS)
/** @endcond */

/** Default drive strength standard when GPIO pin output is low.
 */
#define GPIO_DS_DFLT_LOW (0x0 << GPIO_DS_LOW_POS)

/** Alternative drive strength when GPIO pin output is low.
 * For hardware that does not support configurable drive strength
 * use the default drive strength.
 */
#define GPIO_DS_ALT_LOW (0x1 << GPIO_DS_LOW_POS)

/** Disconnect pin when GPIO pin output is low.
 * For hardware that does not support disconnect use the default
 * drive strength.
 */
#define GPIO_DS_DISCONNECT_LOW (0x3 << GPIO_DS_LOW_POS)

/** @cond INTERNAL_HIDDEN */
#define GPIO_DS_HIGH_POS 14
#define GPIO_DS_HIGH_MASK (0x3 << GPIO_DS_HIGH_POS)
/** @endcond */

/** Default drive strength when GPIO pin output is high.
 */
#define GPIO_DS_DFLT_HIGH (0x0 << GPIO_DS_HIGH_POS)

/** Alternative drive strength when GPIO pin output is high.
 * For hardware that does not support configurable drive strengths
 * use the default drive strength.
 */
#define GPIO_DS_ALT_HIGH (0x1 << GPIO_DS_HIGH_POS)

/** Disconnect pin when GPIO pin output is high.
 * For hardware that does not support disconnect use the default
 * drive strength.
 */
#define GPIO_DS_DISCONNECT_HIGH (0x3 << GPIO_DS_HIGH_POS)

struct gpio_callback;

/**
 * @typedef gpio_callback_handler_t
 * @brief Define the application callback handler function signature
 *
 * @param "struct device *port" Device struct for the GPIO device.
 * @param "struct gpio_callback *cb" Original struct gpio_callback
 *        owning this handler
 * @param "u32_t pins" Mask of pins that triggers the callback handler
 *
 * Note: cb pointer can be used to retrieve private data through
 * CONTAINER_OF() if original struct gpio_callback is stored in
 * another private structure.
 */
typedef void (*gpio_callback_handler_t)(struct device *port,
					struct gpio_callback *cb,
					u32_t pins);

/**
 * @brief GPIO callback structure
 *
 * Used to register a callback in the driver instance callback list.
 * As many callbacks as needed can be added as long as each of them
 * are unique pointers of struct gpio_callback.
 * Beware such structure should not be allocated on stack.
 *
 * Note: To help setting it, see gpio_init_callback() below
 */
struct gpio_callback {
	/** This is meant to be used in the driver and the user should not
	 * mess with it (see drivers/gpio/gpio_utils.h)
	 */
	sys_snode_t node;

	/** Actual callback function being called when relevant. */
	gpio_callback_handler_t handler;

	/** A mask of pins the callback is interested in, if 0 the callback
	 * will never be called. Such pin_mask can be modified whenever
	 * necessary by the owner, and thus will affect the handler being
	 * called or not. The selected pins must be configured to trigger
	 * an interrupt.
	 */
	u32_t pin_mask;
};

/**
 * @cond INTERNAL_HIDDEN
 *
 * GPIO driver API definition.
 *
 * (Internal use only.)
 */
typedef int (*gpio_config_t)(struct device *port, int access_op,
			     u32_t pin, int flags);
typedef int (*gpio_write_t)(struct device *port, int access_op,
			    u32_t pin, u32_t value);
typedef int (*gpio_read_t)(struct device *port, int access_op,
			   u32_t pin, u32_t *value);
typedef int (*gpio_manage_callback_t)(struct device *port,
				      struct gpio_callback *callback,
				      bool set);
typedef int (*gpio_enable_callback_t)(struct device *port,
				      int access_op,
				      u32_t pin);
typedef int (*gpio_disable_callback_t)(struct device *port,
				       int access_op,
				       u32_t pin);
typedef u32_t (*gpio_api_get_pending_int)(struct device *dev);

struct gpio_driver_api {
	gpio_config_t config;
	gpio_write_t write;
	gpio_read_t read;
	gpio_manage_callback_t manage_callback;
	gpio_enable_callback_t enable_callback;
	gpio_disable_callback_t disable_callback;
	gpio_api_get_pending_int get_pending_int;
};
/**
 * @endcond
 */

/**
 * @brief Configure a single pin.
 * @param port Pointer to device structure for the driver instance.
 * @param pin Pin number to configure.
 * @param flags Flags for pin configuration. IN/OUT, interrupt ...
 * @return 0 if successful, negative errno code on failure.
 */
static inline int gpio_pin_configure(struct device *port, u32_t pin,
				     int flags)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->config(port, GPIO_ACCESS_BY_PIN, pin, flags);
}

/**
 * @brief Write the data value to a single pin.
 * @param port Pointer to the device structure for the driver instance.
 * @param pin Pin number where the data is written.
 * @param value Value set on the pin.
 * @return 0 if successful, negative errno code on failure.
 */
static inline int gpio_pin_write(struct device *port, u32_t pin,
				 u32_t value)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->write(port, GPIO_ACCESS_BY_PIN, pin, value);
}

/**
 * @brief Read the data value of a single pin.
 *
 * Read the input state of a pin, returning the value 0 or 1.
 *
 * @param port Pointer to the device structure for the driver instance.
 * @param pin Pin number where data is read.
 * @param value Integer pointer to receive the data values from the pin.
 * @return 0 if successful, negative errno code on failure.
 */
static inline int gpio_pin_read(struct device *port, u32_t pin,
				u32_t *value)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->read(port, GPIO_ACCESS_BY_PIN, pin, value);
}

/**
 * @brief Helper to initialize a struct gpio_callback properly
 * @param callback A valid Application's callback structure pointer.
 * @param handler A valid handler function pointer.
 * @param pin_mask A bit mask of relevant pins for the handler
 */
static inline void gpio_init_callback(struct gpio_callback *callback,
				      gpio_callback_handler_t handler,
				      u32_t pin_mask)
{
	__ASSERT(callback, "Callback pointer should not be NULL");
	__ASSERT(handler, "Callback handler pointer should not be NULL");

	callback->handler = handler;
	callback->pin_mask = pin_mask;
}

/**
 * @brief Add an application callback.
 * @param port Pointer to the device structure for the driver instance.
 * @param callback A valid Application's callback structure pointer.
 * @return 0 if successful, negative errno code on failure.
 *
 * Note: enables to add as many callback as needed on the same port.
 */
static inline int gpio_add_callback(struct device *port,
				    struct gpio_callback *callback)
{
	const struct gpio_driver_api *api = port->driver_api;

	__ASSERT(callback, "Callback pointer should not be NULL");

	return api->manage_callback(port, callback, true);
}

/**
 * @brief Remove an application callback.
 * @param port Pointer to the device structure for the driver instance.
 * @param callback A valid application's callback structure pointer.
 * @return 0 if successful, negative errno code on failure.
 *
 * Note: enables to remove as many callbacks as added through
 *       gpio_add_callback().
 */
static inline int gpio_remove_callback(struct device *port,
				       struct gpio_callback *callback)
{
	const struct gpio_driver_api *api = port->driver_api;

	__ASSERT(callback, "Callback pointer should not be NULL");

	return api->manage_callback(port, callback, false);
}

/**
 * @brief Enable callback(s) for a single pin.
 * @param port Pointer to the device structure for the driver instance.
 * @param pin Pin number where the callback function is enabled.
 * @return 0 if successful, negative errno code on failure.
 *
 * Note: Depending on the driver implementation, this function will enable
 *       the pin to trigger an interruption. So as a semantic detail, if no
 *       callback is registered, of course none will be called.
 */
static inline int gpio_pin_enable_callback(struct device *port, u32_t pin)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->enable_callback(port, GPIO_ACCESS_BY_PIN, pin);
}

/**
 * @brief Disable callback(s) for a single pin.
 * @param port Pointer to the device structure for the driver instance.
 * @param pin Pin number where the callback function is disabled.
 * @return 0 if successful, negative errno code on failure.
 */
static inline int gpio_pin_disable_callback(struct device *port, u32_t pin)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->disable_callback(port, GPIO_ACCESS_BY_PIN, pin);
}

/**
 * @brief Configure all the pins the same way in the port.
 *        List out all flags on the detailed description.
 *
 * @param port Pointer to the device structure for the driver instance.
 * @param flags Flags for the port configuration. IN/OUT, interrupt ...
 * @return 0 if successful, negative errno code on failure.
 */
static inline int gpio_port_configure(struct device *port, int flags)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->config(port, GPIO_ACCESS_BY_PORT, 0, flags);
}

/**
 * @brief Write a data value to the port.
 *
 * Write the output state of a port. The state of each pin is
 * represented by one bit in the value.  Pin 0 corresponds to the
 * least significant bit, pin 31 corresponds to the most significant
 * bit.  For ports with less that 32 physical pins the most significant
 * bits which do not correspond to a physical pin are ignored.
 *
 * @param port Pointer to the device structure for the driver instance.
 * @param value Value to set on the port.
 * @return 0 if successful, negative errno code on failure.
 */
static inline int gpio_port_write(struct device *port, u32_t value)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->write(port, GPIO_ACCESS_BY_PORT, 0, value);
}

/**
 * @brief Read data value from the port.
 *
 * Read the input state of a port.  The state of each pin is
 * represented by one bit in the returned value.  Pin 0 corresponds to
 * the least significant bit, pin 31 corresponds to the most
 * significant bit. Unused bits for ports with less that 32 physical
 * pins are returned as 0.
 *
 * @param port Pointer to the device structure for the driver instance.
 * @param value Integer pointer to receive the data value from the port.
 * @return 0 if successful, negative errno code on failure.
 */
static inline int gpio_port_read(struct device *port, u32_t *value)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->read(port, GPIO_ACCESS_BY_PORT, 0, value);
}

/**
 * @brief Enable callback(s) for the port.
 * @param port Pointer to the device structure for the driver instance.
 * @return 0 if successful, negative errno code on failure.
 *
 * Note: Depending on the driver implementation, this function will enable
 *       the port to trigger an interruption on all pins, as long as these
 *       are configured properly. So as a semantic detail, if no callback
 *       is registered, of course none will be called.
 */
static inline int gpio_port_enable_callback(struct device *port)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->enable_callback(port, GPIO_ACCESS_BY_PORT, 0);
}

/**
 * @brief Disable callback(s) for the port.
 * @param port Pointer to the device structure for the driver instance.
 * @return 0 if successful, negative errno code on failure.
 */
static inline int gpio_port_disable_callback(struct device *port)
{
	const struct gpio_driver_api *api = port->driver_api;

	return api->disable_callback(port, GPIO_ACCESS_BY_PORT, 0);
}

/**
 * @brief Function to get pending interrupts
 *
 * The purpose of this function is to return the interrupt
 * status register for the device.
 * This is especially useful when waking up from
 * low power states to check the wake up source.
 *
 * @param dev Pointer to the device structure for the driver instance.
 *
 * @retval status != 0 if at least one gpio interrupt is pending.
 * @retval 0 if no gpio interrupt is pending.
 */
static inline int gpio_get_pending_int(struct device *dev)
{
	struct gpio_driver_api *api;

	api = (struct gpio_driver_api *)dev->driver_api;
	return api->get_pending_int(dev);
}

struct gpio_pin_config {
	char *gpio_controller;
	u32_t gpio_pin;
};

#define GPIO_DECLARE_PIN_CONFIG_IDX(_idx)	\
	struct gpio_pin_config gpio_pin_ ##_idx
#define GPIO_DECLARE_PIN_CONFIG		\
	GPIO_DECLARE_PIN_CONFIG_IDX()

#define GPIO_PIN_IDX(_idx, _controller, _pin)	\
	.gpio_pin_ ##_idx = {			\
		.gpio_controller = (_controller),\
		.gpio_pin = (_pin),		\
	}
#define GPIO_PIN(_controller, _pin)		\
	GPIO_PIN_IDX(, _controller, _pin)

#define GPIO_GET_CONTROLLER_IDX(_idx, _conf)	\
	((_conf)->gpio_pin_ ##_idx.gpio_controller)
#define GPIO_GET_PIN_IDX(_idx, _conf)	\
	((_conf)->gpio_pin_ ##_idx.gpio_pin)

#define GPIO_GET_CONTROLLER(_conf)	GPIO_GET_CONTROLLER_IDX(, _conf)
#define GPIO_GET_PIN(_conf)		GPIO_GET_PIN_IDX(, _conf)

#ifdef __cplusplus
}
#endif

/**
 * @}
 */

#endif /* __GPIO_H__ */