lora-car/libopencm3/lib/lm4f/gpio.c

599 lines
20 KiB
C
Raw Normal View History

/*
* This file is part of the libopencm3 project.
*
* Copyright (C) 2011 Gareth McMullin <gareth@blacksphere.co.nz>
* Copyright (C) 2013 Alexandru Gagniuc <mr.nuke.me@gmail.com>
*
* This library is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
/** @defgroup gpio_file GPIO
*
*
* @ingroup LM4Fxx
*
* @version 1.0.0
*
* @author @htmlonly &copy; @endhtmlonly 2011
* Gareth McMullin <gareth@blacksphere.co.nz>
* @author @htmlonly &copy; @endhtmlonly 2013
* Alexandru Gagniuc <mr.nuke.me@gmail.com>
*
* @date 16 March 2013
*
* LGPL License Terms @ref lgpl_license
*
* @brief <b>libopencm3 LM4F General Purpose I/O</b>
*
* The LM4F GPIO API provides functionality for accessing the GPIO pins of the
* LM4F.
*
* @attention @code An important aspect to consider is that libopencm3 uses the
* AHB aperture for accessing the GPIO registers on the LM4F. The AHB must be
* explicitly enabled with a call to gpio_enable_ahb_aperture() before accessing
* any GPIO functionality.
* @endcode
*
* Please see the individual GPIO modules for more details. To use the GPIO, the
* gpio.h header needs to be included:
* @code{.c}
* #include <libopencm3/lm4f/gpio.h>
* @endcode
*/
/**@{*/
#include <libopencm3/lm4f/gpio.h>
#include <libopencm3/lm4f/systemcontrol.h>
/* Value we need to write to unlock the GPIO commit register */
#define GPIO_LOCK_UNLOCK_CODE 0x4C4F434B
/** @defgroup gpio_config GPIO pin configuration
* @ingroup gpio_file
*
* \brief <b>Enabling and configuring GPIO pins</b>
*
* @section gpio_api_enable Enabling GPIO ports
* @attention
* Before accessing GPIO functionality through this API, the AHB aperture for
* GPIO ports must be enabled via a call to @ref gpio_enable_ahb_aperture().
* Failing to do so will cause a hard fault.
*
* @note
* Once the AHB aperture is enabled, GPIO registers can no longer be accessed
* via the APB aperture. The two apertures are mutually exclusive.
*
* Enabling the AHB aperture only needs to be done once. However, in order to
* access a certain GPIO port, its clock must also be enabled. Enabling the
* GPIO clock needs to be done for every port that will be used.
*
* For example, to enable GPIOA and GPIOD:
* @code{.c}
* // Make sure we can access the GPIO via the AHB aperture
* gpio_enable_ahb_aperture();
* ...
* // Enable GPIO ports A and D
* periph_clock_enable(RCC_GPIOA);
* periph_clock_enable(RCC_GPIOD);
* @endcode
*
* On reset all ports are configured as digital floating inputs (no pull-up or
* pull-down), except for special function pins.
*
*
* @section gpio_api_in Configuring pins as inputs
*
* Configuring GPIO pins as inputs is done with @ref gpio_mode_setup(), with
* @ref GPIO_MODE_INPUT for the mode parameter. The direction of the pull-up
* must be specified with the same call
*
* For example, PA2, PA3, and PA4 as inputs, with pull-up on PA4:
* @code{.c}
* gpio_mode_setup(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO2 | GPIO3);
* gpio_mode_setup(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_PULLUP, GPIO4);
* @endcode
*
*
* @section gpio_api_out Configuring pins as outputs
*
* Output pins have more configuration options than input pins. LM4F pins can be
* configured as either push-pull, or open drain. The drive strength of each pin
* can be adjusted between 2mA, 4mA, or 8mA. Slew-rate control is available when
* the pins are configured to drive 8mA. These extra options can be specified
* with @ref gpio_set_output_config().
* The default is push-pull configuration with 2mA drive capability.
*
* @note
* @ref gpio_set_output_config() controls different capabilities than the
* similar sounding gpio_set_output_options() from the STM GPIO API. They are
* intentionally named differently to prevent confusion between the two. They
* are API incompatible.
*
* For example, to set PA2 to output push-pull with a drive strength of 8mA:
* @code{.c}
* gpio_mode_setup(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO2);
* gpio_set_output_config(GPIOA, GPIO_OTYPE_PP, GPIO_DRIVE_8MA, GPIO2);
* @endcode
*
*
* @section gpio_api_analog Configuring pins as analog function
*
* Configuring GPIO pins to their analog function is done with
* @ref gpio_mode_setup(), with @ref GPIO_MODE_ANALOG for the mode parameter.
*
* Suppose PD4 and PD5 are the USB pins. To enable their analog functionality
* (USB D+ and D- in this case), use:
* @code
* // Mux USB pins to their analog function
* gpio_mode_setup(GPIOD, GPIO_MODE_ANALOG, GPIO_PUPD_NONE, GPIO4 | GPIO5);
* @endcode
*
* @section gpio_api_alf_func Configuring pins as alternate functions
*
* Most pins have alternate functions associated with them. When a pin is set to
* an alternate function, it is multiplexed to one of the dedicated hardware
* peripheral in the chip. The alternate function mapping can be found in the
* part's datasheet, and usually varies between arts of the same family.
*
* Multiplexing a pin, or group of pins to an alternate function is done with
* @ref gpio_set_af(). Because AF0 is not used on the LM4F, passing 0 as the
* alt_func_num parameter will disable the alternate function of the given pins.
*
* @code
* // Mux PB0 and PB1 to AF1 (UART1 TX/RX in this case)
* gpio_set_af(GPIOB, 1, GPIO0 | GPIO1);
* @endcode
*
* @section gpio_api_sfpins Changing configuration of special function pins
*
* On the LM4F, the NMI and JTAG/SWD default to their alternate function. These
* pins cannot normally be committed to GPIO usage. To enable these special
* function pins to be used as GPIO, they must be unlocked. This may be achieved
* via @ref gpio_unlock_commit. Once a special function pin is unlocked, its
* settings may be altered in the usual way.
*
* For example, to unlock the PF0 pin (NMI on the LM4F120):
* @code
* // PF0 is an NMI pin, and needs to be unlocked
* gpio_unlock_commit(GPIOF, GPIO0);
* // Now the pin can be configured
* gpio_mode_setup(RGB_PORT, GPIO_MODE_INPUT, GPIO_PUPD_PULLUP, btnpins);
* @endcode
*/
/**@{*/
/**
* \brief Enable access to GPIO registers via the AHB aperture
*
* All GPIO registers are accessed in libopencm3 via the AHB aperture. It
* provides faster control over the older APB aperture. This aperture must be
* enabled before calling any other gpio_*() function.
*
*/
void gpio_enable_ahb_aperture(void)
{
SYSCTL_GPIOHBCTL = 0xffffffff;
}
/**
* \brief Configure a group of pins
*
* Sets the Pin direction, analog/digital mode, and pull-up configuration of
* or a set of GPIO pins on a given GPIO port.
*
* @param[in] gpioport GPIO block register address base @ref gpio_reg_base
* @param[in] mode Pin mode (@ref gpio_mode) \n
* - GPIO_MODE_OUTPUT -- Configure pin as output \n
* - GPIO_MODE_INPUT -- Configure pin as input \n
* - GPIO_MODE_ANALOG -- Configure pin as analog function
* @param[in] pullup Pin pullup/pulldown configuration (@ref gpio_pullup) \n
* - GPIO_PUPD_NONE -- Do not pull the pin high or low \n
* - GPIO_PUPD_PULLUP -- Pull the pin high \n
* - GPIO_PUPD_PULLDOWN -- Pull the pin low
* @param[in] gpios @ref gpio_pin_id. Any combination of pins may be specified
* by OR'ing then together
*/
void gpio_mode_setup(uint32_t gpioport, enum gpio_mode mode,
enum gpio_pullup pullup, uint8_t gpios)
{
switch (mode) {
case GPIO_MODE_OUTPUT:
GPIO_DIR(gpioport) |= gpios;
GPIO_DEN(gpioport) |= gpios;
GPIO_AMSEL(gpioport) &= ~gpios;
break;
case GPIO_MODE_INPUT:
GPIO_DIR(gpioport) &= ~gpios;
GPIO_DEN(gpioport) |= gpios;
GPIO_AMSEL(gpioport) &= ~gpios;
break;
case GPIO_MODE_ANALOG:
GPIO_DEN(gpioport) &= ~gpios;
GPIO_AMSEL(gpioport) |= gpios;
break;
default:
/* Don't do anything */
break;
}
/*
* Setting a bit in the GPIO_PDR register clears the corresponding bit
* in the GPIO_PUR register, and vice-versa.
*/
switch (pullup) {
case GPIO_PUPD_PULLUP:
GPIO_PUR(gpioport) |= gpios;
break;
case GPIO_PUPD_PULLDOWN:
GPIO_PDR(gpioport) |= gpios;
break;
case GPIO_PUPD_NONE: /* Fall through */
default:
GPIO_PUR(gpioport) &= ~gpios;
GPIO_PDR(gpioport) &= ~gpios;
break;
}
}
/**
* \brief Configure output parameters of a group of pins
*
* Sets the output configuration and drive strength, of or a set of GPIO pins
* for a set of GPIO pins in output mode.
*
* @param[in] gpioport GPIO block register address base @ref gpio_reg_base
* @param[in] otype Output driver configuration (@ref gpio_output_type) \n
* - GPIO_OTYPE_PP -- Configure pin driver as push-pull \n
* - GPIO_OTYPE_OD -- Configure pin driver as open drain
* @param[in] drive Pin drive strength (@ref gpio_drive_strength) \n
* - GPIO_DRIVE_2MA -- 2mA drive \n
* - GPIO_DRIVE_4MA -- 4mA drive \n
* - GPIO_DRIVE_8MA -- 8mA drive \n
* - GPIO_DRIVE_8MA_SLEW_CTL -- 8mA drive with slew rate
* control
* @param[in] gpios @ref gpio_pin_id. Any combination of pins may be specified
* by OR'ing then together
*/
void gpio_set_output_config(uint32_t gpioport, enum gpio_output_type otype,
enum gpio_drive_strength drive, uint8_t gpios)
{
if (otype == GPIO_OTYPE_OD) {
GPIO_ODR(gpioport) |= gpios;
} else {
GPIO_ODR(gpioport) &= ~gpios;
}
/*
* Setting a bit in the GPIO_DRxR register clears the corresponding bit
* in the other GPIO_DRyR registers, and vice-versa.
*/
switch (drive) {
case GPIO_DRIVE_8MA_SLEW_CTL:
GPIO_DR8R(gpioport) |= gpios;
GPIO_SLR(gpioport) |= gpios;
break;
case GPIO_DRIVE_8MA:
GPIO_DR8R(gpioport) |= gpios;
GPIO_SLR(gpioport) &= ~gpios;
break;
case GPIO_DRIVE_4MA:
GPIO_DR4R(gpioport) |= gpios;
break;
case GPIO_DRIVE_2MA: /* Fall through */
default:
GPIO_DR2R(gpioport) |= gpios;
break;
}
}
#define PCTL_AF(pin, af) ((af) << ((pin) << 2))
#define PCTL_MASK(pin) PCTL_AF((pin), 0xf)
/**
* \brief Multiplex group of pins to the given alternate function
*
* Mux the pin or group of pins to the given alternate function. Note that a
* number of pins may be set but only with a single AF number. This is useful
* when one or more of a peripheral's pins are assigned to the same alternate
* function.
*
* Because AF0 is not used on the LM4F, passing 0 as the alt_func_num parameter
* will disable the alternate function of the given pins.
*
* @param[in] gpioport GPIO block register address base @ref gpio_reg_base
* @param[in] alt_func_num Pin alternate function number or 0 to disable the
* alternate function multiplexing.
* @param[in] gpios @ref gpio_pin_id. Any combination of pins may be specified
* by OR'ing then together
*/
void gpio_set_af(uint32_t gpioport, uint8_t alt_func_num, uint8_t gpios)
{
uint32_t pctl32;
uint8_t pin_mask;
int i;
/* Did we mean to disable the alternate function? */
if (alt_func_num == 0) {
GPIO_AFSEL(gpioport) &= ~gpios;
return;
}
/* Enable the alternate function */
GPIO_AFSEL(gpioport) |= gpios;
/* Alternate functions are digital */
GPIO_DEN(gpioport) |= gpios;
/* Now take care of the actual multiplexing */
pctl32 = GPIO_PCTL(gpioport);
for (i = 0; i < 8; i++) {
pin_mask = (1 << i);
if (!(gpios & pin_mask)) {
continue;
}
pctl32 &= ~PCTL_MASK(i);
pctl32 |= PCTL_AF(i, (alt_func_num & 0xf));
}
GPIO_PCTL(gpioport) = pctl32;
}
/**
* \brief Unlock the commit control of a special function pin
*
* Unlocks the commit control of the given pin or group of pins. If a pin is a
* JTAG/SWD or NMI, the pin may then be reconfigured as a GPIO pin. If the pin
* is not locked by default, this has no effect.
*
* @param[in] gpioport GPIO block register address base @ref gpio_reg_base
* @param[in] gpios @ref gpio_pin_id. Any combination of pins may be specified
* by OR'ing then together.
*/
void gpio_unlock_commit(uint32_t gpioport, uint8_t gpios)
{
/* Unlock the GPIO_CR register */
GPIO_LOCK(gpioport) = GPIO_LOCK_UNLOCK_CODE;
/* Enable committing changes */
GPIO_CR(gpioport) |= gpios;
/* Lock the GPIO_CR register */
GPIO_LOCK(gpioport) = ~GPIO_LOCK_UNLOCK_CODE;
}
/**@}*/
/** @defgroup gpio_control GPIO pin control
* @ingroup gpio_file
*
* \brief <b>Controlling GPIO pins</b>
*
* Each I/O port has 8 individually configurable bits. When reading and writing
* data to the GPIO ports, address bits [9:2] mask the pins to be read or
* written. This mechanism makes all GPIO port reads and writes on the LM4F
* atomic operations. The GPIO API takes full advantage of this fact to preserve
* the atomicity of these operations.
*
* Setting or clearing a group of bits can be accomplished with @ref gpio_set()
* and @ref gpio_clear() respectively. These operation use the masking mechanism
* described above to only affect the specified pins.
*
* Sometimes it is more appropriate to read or set the level of a group of pins
* on a port, in one atomic operation. Reading the status can be accomplished
* with @ref gpio_read(). The result is equivalent to reading all the pins, then
* masking only the desired pins; however, the masking is done in hardware, and
* does not require an extra hardware operation.
*
* Writing a group of pins can be accomplished with @ref gpio_write(). The mask
* ('gpios' parameter) is applied in hardware, and the masked pins are not
* affected, regardless of the value of the respective bits written to the GPIO
* port.
*
* Two extra functions are provided, @ref gpio_port_read() and
* @ref gpio_port_write(). They are functionally identical to
* @ref gpio_read (port, GPIO_ALL) and @ref gpio_write (port, GPIO_ALL, val)
* respectively. Hence, they are also atomic.
*
* GPIO pins may be toggled with @ref gpio_toggle(). This function does not
* translate to an atomic operation.
*
* @note
* The @ref gpio_toggle() operation is the only GPIO port operation which is not
* atomic. It involves a read-modify-write cycle.
*
* Suppose PA0, PA1, PA2, and PA3 are to be modified without affecting the other
* pins on port A. This is common when controlling, for example, a 4-bit bus:
* @code{.c}
* // Pins 4,5,6, and 7 are unaffected, regardless of the bits in val
* gpio_write(GPIOA, GPIO0 | GPIO1 | GPIO2 | GPIO3, val);
* // Wait a bit then send the other 4 bits
* wait_a_bit();
* gpio_write(GPIOA, GPIO0 | GPIO1 | GPIO2 | GPIO3, val >> 4);
* @endcode
*
* Suppose a LED is connected to PD4, and we want to flash the LED for a brief
* period of time:
* @code
* gpio_set(GPIOD, GPIO4);
* wait_a_bit();
* gpio_set(GPIOD, GPIO4);
* @endcode
*/
/**@{*/
/**
* \brief Toggle a Group of Pins
*
* Toggle one or more pins of the given GPIO port.
*
* @param[in] gpioport GPIO block register address base @ref gpio_reg_base
* @param[in] gpios Pin identifiers. @ref gpio_pin_id
*/
void gpio_toggle(uint32_t gpioport, uint8_t gpios)
{
/* The mask makes sure we only toggle the GPIOs we want to */
GPIO_DATA(gpioport)[gpios] ^= GPIO_ALL;
}
/**@}*/
/** @defgroup gpio_irq GPIO Interrupt control
* @ingroup gpio_file
*
* \brief <b>Configuring interrupts from GPIO pins</b>
*
* GPIO pins can trigger interrupts on either edges or levels. The type of
* trigger can be configured with @ref gpio_configure_int_trigger(). To have an
* event on the given pin generate an interrupt, its interrupt source must be
* unmasked. This can be achieved with @ref gpio_enable_interrupts(). Interrupts
* which are no longer needed can be disabled through
* @ref gpio_disable_interrupts().
*
* In order for the interrupt to generate an IRQ and a call to the interrupt
* service routine, the interrupt for the GPIO port must be routed through the
* NVIC with @ref nvic_enable_irq(). For this last step, the nvic.h header is
* needed:
* @code{.c}
* #include <libopencm3/lm4f/nvic.h>
* @endcode
*
* Enabling an interrupt is as simple as configuring the desired trigger,
* unmasking the desired interrupt, and routing the desired GPIO port's
* interrupt through the NVIC.
* @code{.c}
* // Trigger interrupt on each rising edge
* gpio_configure_trigger(GPIOF, GPIO_TRIG_EDGE_RISE, GPIO0 | GPIO4);
* // Unmask the interrupt on those pins
* gpio_enable_interrupts(GPIOF, GPIO0 | GPIO4);
* // Enable the interrupt in the NVIC as well
* nvic_enable_irq(NVIC_GPIOF_IRQ);
* @endcode
*
* After interrupts are properly enabled and routed through the NVIC, when an
* event occurs, the appropriate IRQ flag is set by hardware, and execution
* jumps to the GPIO ISR. The ISR should query the IRQ flags to determine which
* event caused the interrupt. For this, use @ref gpio_is_interrupt_source(),
* with the desired GPIO flag. After one or more interrupt sources are
* serviced, the IRQ flags must be cleared by the ISR. This can be done with
* @ref gpio_clear_interrupt_flag().
*
* A typical GPIO ISR may look like the following:
* @code{.c}
* void gpiof_isr(void)
* {
* uint8_t serviced_irqs = 0;
*
* // Process individual IRQs
* if (gpio_is_interrupt_source(GPIOF, GPIO0)) {
* process_gpio0_event();
* serviced_irq |= GPIO0;
* }
* if (gpio_is_interrupt_source(GPIOF, GPIO4)) {
* process_gpio4_event();
* serviced_irq |= GPIO4;
* }
*
* // Clear the interrupt flag for the processed IRQs
* gpio_clear_interrupt_flag(GPIOF, serviced_irqs);
* }
* @endcode
*/
/**@{*/
/**
* \brief Configure the interrupt trigger on the given GPIO pins
*
* Sets the Pin direction, analog/digital mode, and pull-up configuration of
* or a set of GPIO pins on a given GPIO port.
*
* @param[in] gpioport GPIO block register address base @ref gpio_reg_base
* @param[in] trigger Trigger configuration (@ref gpio_trigger) \n
* - GPIO_TRIG_LVL_LOW -- Trigger on low level \n
* - GPIO_TRIG_LVL_HIGH -- Trigger on high level \n
* - GPIO_TRIG_EDGE_FALL -- Trigger on falling edges \n
* - GPIO_TRIG_EDGE_RISE -- Trigger on rising edges \n
* - GPIO_TRIG_EDGE_BOTH -- Trigger on all edges
* @param[in] gpios @ref gpio_pin_id. Any combination of pins may be specified
* by OR'ing then together
*/
void gpio_configure_trigger(uint32_t gpioport, enum gpio_trigger trigger,
uint8_t gpios)
{
switch (trigger) {
case GPIO_TRIG_LVL_LOW:
GPIO_IS(gpioport) |= gpios;
GPIO_IEV(gpioport) &= ~gpios;
break;
case GPIO_TRIG_LVL_HIGH:
GPIO_IS(gpioport) |= gpios;
GPIO_IEV(gpioport) |= gpios;
break;
case GPIO_TRIG_EDGE_FALL:
GPIO_IS(gpioport) &= ~gpios;
GPIO_IBE(gpioport) &= ~gpios;
GPIO_IEV(gpioport) &= ~gpios;
break;
case GPIO_TRIG_EDGE_RISE:
GPIO_IS(gpioport) &= ~gpios;
GPIO_IBE(gpioport) &= ~gpios;
GPIO_IEV(gpioport) |= gpios;
break;
case GPIO_TRIG_EDGE_BOTH:
GPIO_IS(gpioport) &= ~gpios;
GPIO_IBE(gpioport) |= gpios;
break;
default:
/* Don't do anything */
break;
}
}
/**
* \brief Enable interrupts on specified GPIO pins
*
* Enable interrupts on the specified GPIO pins
*
* Note that the NVIC must be enabled and properly configured for the interrupt
* to be routed to the CPU.
*
* @param[in] gpioport GPIO block register address base @ref gpio_reg_base
* @param[in] gpios @ref gpio_pin_id. Pins whose interrupts to enable. Any
* combination of pins may be specified by OR'ing them
* together.
*/
void gpio_enable_interrupts(uint32_t gpioport, uint8_t gpios)
{
GPIO_IM(gpioport) |= gpios;
}
/**
* \brief Disable interrupts on specified GPIO pins
*
* Disable interrupts on the specified GPIO pins
*
* Note that the NVIC must be enabled and properly configured for the interrupt
* to be routed to the CPU.
*
* @param[in] gpioport GPIO block register address base @ref gpio_reg_base
* @param[in] gpios @ref gpio_pin_id. Pins whose interrupts to disable. Any
* combination of pins may be specified by OR'ing them
* together.
*/
void gpio_disable_interrupts(uint32_t gpioport, uint8_t gpios)
{
GPIO_IM(gpioport) |= gpios;
}
/**@}*/
/**@}*/