Clarify GPIO read and write macros

This commit is contained in:
George Oikonomou 2015-02-14 01:44:06 +01:00
parent a34a2e5ad8
commit a93a8912c2

View file

@ -117,6 +117,20 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin);
/** \brief Set pins with PIN_MASK of port with PORT_BASE to value.
* \param PORT_BASE GPIO Port register offset
* \param PIN_MASK Pin number mask. Pin 0: 0x01, Pin 1: 0x02 ... Pin 7: 0x80
* \param value The new value to write to the register. Only pins specified
* by PIN_MASK will be set.
*
* \note The outcome of this macro invocation will be to write to the register
* a new value for multiple pins. For that reason, the value argument cannot be
* a simple 0 or 1. Instead, it must be the value corresponding to the pins that
* you wish to set.
*
* Thus, if you only want to set a single pin (e.g. pin 2), do \e not pass 1,
* but you must pass 0x04 instead (1 << 2). This may seem counter-intuitive at
* first glance, but it allows a single invocation of this macro to set
* multiple pins in one go if so desired. For example, you can set pins 3 and 1
* and the same time clear pins 2 and 0. To do so, pass 0x0F as the PIN_MASK
* and then use 0x0A as the value ((1 << 3) | (1 << 1) for pins 3 and 1)
*/
#define GPIO_WRITE_PIN(PORT_BASE, PIN_MASK, value) \
do { REG(((PORT_BASE) | GPIO_DATA) + ((PIN_MASK) << 2)) = (value); } while(0)
@ -124,6 +138,12 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin);
/** \brief Read pins with PIN_MASK of port with PORT_BASE.
* \param PORT_BASE GPIO Port register offset
* \param PIN_MASK Pin number mask. Pin 0: 0x01, Pin 1: 0x02 ... Pin 7: 0x80
* \return The value of the pins specified by PIN_MASK
*
* This macro will \e not return 0 or 1. Instead, it will return the values of
* the pins specified by PIN_MASK ORd together. Thus, if you pass 0xC3
* (0x80 | 0x40 | 0x02 | 0x01) as the PIN_MASK and pins 7 and 0 are high,
* the macro will return 0x81.
*/
#define GPIO_READ_PIN(PORT_BASE, PIN_MASK) \
REG(((PORT_BASE) | GPIO_DATA) + ((PIN_MASK) << 2))
@ -261,7 +281,7 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin);
/**
* \brief Converts a pin number to a pin mask
* \param The pin number in the range [0..7]
* \param PIN The pin number in the range [0..7]
* \return A pin mask which can be used as the PIN_MASK argument of the macros
* in this category
*/
@ -269,7 +289,7 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin);
/**
* \brief Converts a port number to the port base address
* \param The port number in the range 0 - 3. Likely GPIO_X_NUM.
* \param PORT The port number in the range 0 - 3. Likely GPIO_X_NUM.
* \return The base address for the registers corresponding to that port
* number.
*/