GPIO pin configuration

Enabling and configuring GPIO pins More...

Collaboration diagram for GPIO pin configuration:

Macros
#define	PCTL_AF(pin, af)   ((af) << ((pin) << 2))
#define	PCTL_MASK(pin)   PCTL_AF((pin), 0xf)

Functions
void	gpio_enable_ahb_aperture (void)
	Enable access to GPIO registers via the AHB aperture. More...
void	gpio_mode_setup (uint32_t gpioport, enum gpio_mode mode, enum gpio_pullup pullup, uint8_t gpios)
	Configure a group of pins. More...
void	gpio_set_output_config (uint32_t gpioport, enum gpio_output_type otype, enum gpio_drive_strength drive, uint8_t gpios)
	Configure output parameters of a group of pins. More...
void	gpio_set_af (uint32_t gpioport, uint8_t alt_func_num, uint8_t gpios)
	Multiplex group of pins to the given alternate function. More...
void	gpio_unlock_commit (uint32_t gpioport, uint8_t gpios)
	Unlock the commit control of a special function pin. More...

Detailed Description

Enabling and configuring GPIO pins

Enabling GPIO ports

Attention

Before accessing GPIO functionality through this API, the AHB aperture for GPIO ports must be enabled via a call to 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:

// 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);

On reset all ports are configured as digital floating inputs (no pull-up or pull-down), except for special function pins.

Configuring pins as inputs

Configuring GPIO pins as inputs is done with gpio_mode_setup(), with 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:

gpio_mode_setup(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO2 | GPIO3);
gpio_mode_setup(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_PULLUP, GPIO4);

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 gpio_set_output_config(). The default is push-pull configuration with 2mA drive capability.

Note

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:

gpio_mode_setup(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO2);
gpio_set_output_config(GPIOA, GPIO_OTYPE_PP, GPIO_DRIVE_8MA, GPIO2);

Configuring pins as analog function

Configuring GPIO pins to their analog function is done with gpio_mode_setup(), with 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:

// Mux USB pins to their analog function
gpio_mode_setup(GPIOD, GPIO_MODE_ANALOG, GPIO_PUPD_NONE, GPIO4 | GPIO5);

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 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.

// Mux PB0 and PB1 to AF1 (UART1 TX/RX in this case)
gpio_set_af(GPIOB, 1, GPIO0 | GPIO1);

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 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):

// 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);

Macro Definition Documentation

PCTL_AF

#define PCTL_AF	(		pin,
			af
	)		((af) << ((pin) << 2))

Definition at line 302 of file gpio.c.

PCTL_MASK

#define PCTL_MASK

(

pin

)

PCTL_AF((pin), 0xf)

Definition at line 303 of file gpio.c.

Function Documentation

gpio_enable_ahb_aperture()

void gpio_enable_ahb_aperture

(

void

)

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.

Definition at line 186 of file gpio.c.

References SYSCTL_GPIOHBCTL.

gpio_mode_setup()

void gpio_mode_setup	(	uint32_t	gpioport,
		enum gpio_mode	mode,
		enum gpio_pullup	pullup,
		uint8_t	gpios
	)

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.

Parameters

[in]	gpioport	GPIO block register address base GPIO register base addresses
[in]	mode	Pin mode (gpio_mode) GPIO_MODE_OUTPUT – Configure pin as output GPIO_MODE_INPUT – Configure pin as input GPIO_MODE_ANALOG – Configure pin as analog function
[in]	pullup	Pin pullup/pulldown configuration (gpio_pullup) GPIO_PUPD_NONE – Do not pull the pin high or low GPIO_PUPD_PULLUP – Pull the pin high GPIO_PUPD_PULLDOWN – Pull the pin low
[in]	gpios	GPIO pin identifiers. Any combination of pins may be specified by OR'ing then together

Definition at line 209 of file gpio.c.

References GPIO_AMSEL, GPIO_DEN, GPIO_DIR, GPIO_MODE_ANALOG, GPIO_MODE_INPUT, GPIO_MODE_OUTPUT, GPIO_PDR, GPIO_PUPD_NONE, GPIO_PUPD_PULLDOWN, GPIO_PUPD_PULLUP, and GPIO_PUR.

gpio_set_af()

void gpio_set_af	(	uint32_t	gpioport,
		uint8_t	alt_func_num,
		uint8_t	gpios
	)

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.

Parameters

[in]	gpioport	GPIO block register address base GPIO register base addresses
[in]	alt_func_num	Pin alternate function number or 0 to disable the alternate function multiplexing.
[in]	gpios	GPIO pin identifiers. Any combination of pins may be specified by OR'ing then together

Definition at line 321 of file gpio.c.

References GPIO_AFSEL, GPIO_DEN, GPIO_PCTL, and PCTL_AF.

gpio_set_output_config()

void gpio_set_output_config	(	uint32_t	gpioport,
		enum gpio_output_type	otype,
		enum gpio_drive_strength	drive,
		uint8_t	gpios
	)

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.

Parameters

[in]	gpioport	GPIO block register address base GPIO register base addresses
[in]	otype	Output driver configuration (gpio_output_type) GPIO_OTYPE_PP – Configure pin driver as push-pull GPIO_OTYPE_OD – Configure pin driver as open drain
[in]	drive	Pin drive strength (gpio_drive_strength) GPIO_DRIVE_2MA – 2mA drive GPIO_DRIVE_4MA – 4mA drive GPIO_DRIVE_8MA – 8mA drive GPIO_DRIVE_8MA_SLEW_CTL – 8mA drive with slew rate control
[in]	gpios	GPIO pin identifiers. Any combination of pins may be specified by OR'ing then together

Definition at line 270 of file gpio.c.

References GPIO_DR2R, GPIO_DR4R, GPIO_DR8R, GPIO_DRIVE_2MA, GPIO_DRIVE_4MA, GPIO_DRIVE_8MA, GPIO_DRIVE_8MA_SLEW_CTL, GPIO_ODR, GPIO_OTYPE_OD, and GPIO_SLR.

gpio_unlock_commit()

void gpio_unlock_commit	(	uint32_t	gpioport,
		uint8_t	gpios
	)

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.

Parameters

[in]	gpioport	GPIO block register address base GPIO register base addresses
[in]	gpios	GPIO pin identifiers. Any combination of pins may be specified by OR'ing then together.

Definition at line 365 of file gpio.c.

References GPIO_CR, GPIO_LOCK, and GPIO_LOCK_UNLOCK_CODE.