This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's General Purpose Input/Output (GPIO) pin functionality, for manual pin state reading and writing.

The following peripheral is used by this module:

PORT (GPIO Management)

The following devices can use this module:

Atmel | SMART SAM D20/D21
Atmel | SMART SAM R21
Atmel | SMART SAM D09/D10/D11
Atmel | SMART SAM L21/L22
Atmel | SMART SAM DA1
Atmel | SMART SAM C20/C21
Atmel | SMART SAM HA1
Atmel | SMART SAM R30
Atmel | SMART SAM R34
Atmel | SMART SAM R35

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The device GPIO (PORT) module provides an interface between the user application logic and external hardware peripherals, when general pin state manipulation is required. This driver provides an easy-to-use interface to the physical pin input samplers and output drivers, so that pins can be read from or written to for general purpose external hardware control.

Driver Feature Macro Definition

Driver Feature Macro	Supported devices
FEATURE_PORT_INPUT_EVENT	SAM L21/L22/C20/C21/R30/R34/R35

Note: The specific features are only available in the driver when the selected device supports those features.

Physical and Logical GPIO Pins

SAM devices use two naming conventions for the I/O pins in the device; one physical and one logical. Each physical pin on a device package is assigned both a physical port and pin identifier (e.g. "PORTA.0") as well as a monotonically incrementing logical GPIO number (e.g. "GPIO0"). While the former is used to map physical pins to their physical internal device module counterparts, for simplicity the design of this driver uses the logical GPIO numbers instead.

Physical Connection

The diagram below shows how this module is interconnected within the device.

Special Considerations

The SAM port pin input sampler can be disabled when the pin is configured in pure output mode to save power; reading the pin state of a pin configured in output-only mode will read the logical output state that was last set.

Extra Information

For extra information, see Extra Information for PORT Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for PORT Driver.

API Overview

Modules
	Quick Start Guide(s)
	In this section you can find a list of all Quick Start guides related to the SAM Port (PORT) Driver.

Data Structures
struct	port_config
	Port pin configuration structure. More...

struct	port_input_event_config
	Port input event configuration structure. More...

Enumerations
enum	port_input_event { PORT_INPUT_EVENT_0 = 0, PORT_INPUT_EVENT_1 = 1, PORT_INPUT_EVENT_2 = 2, PORT_INPUT_EVENT_3 = 3 }
	Port input event. More...

enum	port_input_event_action { PORT_INPUT_EVENT_ACTION_OUT = 0, PORT_INPUT_EVENT_ACTION_SET, PORT_INPUT_EVENT_ACTION_CLR, PORT_INPUT_EVENT_ACTION_TGL }
	Port input event action. More...

enum	port_pin_dir { PORT_PIN_DIR_INPUT = SYSTEM_PINMUX_PIN_DIR_INPUT, PORT_PIN_DIR_OUTPUT = SYSTEM_PINMUX_PIN_DIR_OUTPUT, PORT_PIN_DIR_OUTPUT_WTH_READBACK = SYSTEM_PINMUX_PIN_DIR_OUTPUT_WITH_READBACK }
	Port pin direction configuration enum. More...

enum	port_pin_pull { PORT_PIN_PULL_NONE = SYSTEM_PINMUX_PIN_PULL_NONE, PORT_PIN_PULL_UP = SYSTEM_PINMUX_PIN_PULL_UP, PORT_PIN_PULL_DOWN = SYSTEM_PINMUX_PIN_PULL_DOWN }
	Port pin input pull configuration enum. More...

Driver Feature Definition
Define port features set according to different device family.
#define	FEATURE_PORT_INPUT_EVENT
	Event input control feature support for PORT group. More...

PORT Alias Macros
#define	PORTA PORT->Group[0]
	Convenience definition for GPIO module group A on the device (if available). More...

#define	PORTB PORT->Group[1]
	Convenience definition for GPIO module group B on the device (if available). More...

#define	PORTC PORT->Group[2]
	Convenience definition for GPIO module group C on the device (if available). More...

#define	PORTD PORT->Group[3]
	Convenience definition for GPIO module group D on the device (if available). More...

State Reading/Writing (Physical Group Orientated)
static PortGroup *	port_get_group_from_gpio_pin (const uint8_t gpio_pin)
	Retrieves the PORT module group instance from a given GPIO pin number. More...

static uint32_t	port_group_get_input_level (const PortGroup *const port, const uint32_t mask)
	Retrieves the state of a group of port pins that are configured as inputs. More...

static uint32_t	port_group_get_output_level (const PortGroup *const port, const uint32_t mask)
	Retrieves the state of a group of port pins that are configured as outputs. More...

static void	port_group_set_output_level (PortGroup *const port, const uint32_t mask, const uint32_t level_mask)
	Sets the state of a group of port pins that are configured as outputs. More...

static void	port_group_toggle_output_level (PortGroup *const port, const uint32_t mask)
	Toggles the state of a group of port pins that are configured as an outputs. More...

Configuration and Initialization
static void	port_get_config_defaults (struct port_config *const config)
	Initializes a Port pin/group configuration structure to defaults. More...

void	port_pin_set_config (const uint8_t gpio_pin, const struct port_config *const config)
	Writes a Port pin configuration to the hardware module. More...

void	port_group_set_config (PortGroup const port, const uint32_t mask, const struct port_config const config)
	Writes a Port group configuration group to the hardware module. More...

State Reading/Writing (Logical Pin Orientated)
static bool	port_pin_get_input_level (const uint8_t gpio_pin)
	Retrieves the state of a port pin that is configured as an input. More...

static bool	port_pin_get_output_level (const uint8_t gpio_pin)
	Retrieves the state of a port pin that is configured as an output. More...

static void	port_pin_set_output_level (const uint8_t gpio_pin, const bool level)
	Sets the state of a port pin that is configured as an output. More...

static void	port_pin_toggle_output_level (const uint8_t gpio_pin)
	Toggles the state of a port pin that is configured as an output. More...

Port Input Event
static enum status_code	port_enable_input_event (const uint8_t gpio_pin, const enum port_input_event n)
	Enable the port event input. More...

static enum status_code	port_disable_input_event (const uint8_t gpio_pin, const enum port_input_event n)
	Disable the port event input. More...

static void	port_input_event_get_config_defaults (struct port_input_event_config *const config)
	Retrieve the default configuration for port input event. More...

static enum status_code	port_input_event_set_config (const enum port_input_event n, struct port_input_event_config *const config)
	Configure port input event. More...

#define FEATURE_PORT_INPUT_EVENT

Event input control feature support for PORT group.

#define PORTA PORT->Group[0]

Convenience definition for GPIO module group A on the device (if available).

#define PORTB PORT->Group[1]

Convenience definition for GPIO module group B on the device (if available).

#define PORTC PORT->Group[2]

Convenience definition for GPIO module group C on the device (if available).

#define PORTD PORT->Group[3]

Convenience definition for GPIO module group D on the device (if available).

enum port_input_event

Port input event.

List of port input events.

Enumerator
PORT_INPUT_EVENT_0	Port input event 0.
PORT_INPUT_EVENT_1	Port input event 1.
PORT_INPUT_EVENT_2	Port input event 2.
PORT_INPUT_EVENT_3	Port input event 3.

enum port_input_event_action

Port input event action.

List of port input events action on pin.

Enumerator
PORT_INPUT_EVENT_ACTION_OUT	Event out to pin.
PORT_INPUT_EVENT_ACTION_SET	Set output register of pin on event.
PORT_INPUT_EVENT_ACTION_CLR	Clear output register pin on event.
PORT_INPUT_EVENT_ACTION_TGL	Toggle output register pin on event.

enum port_pin_dir

Port pin direction configuration enum.

Enum for the possible pin direction settings of the port pin configuration structure, to indicate the direction the pin should use.

Enumerator
PORT_PIN_DIR_INPUT	The pin's input buffer should be enabled, so that the pin state can be read.
PORT_PIN_DIR_OUTPUT	The pin's output buffer should be enabled, so that the pin state can be set.
PORT_PIN_DIR_OUTPUT_WTH_READBACK	The pin's output and input buffers should be enabled, so that the pin state can be set and read back.

enum port_pin_pull

Port pin input pull configuration enum.

Enum for the possible pin pull settings of the port pin configuration structure, to indicate the type of logic level pull the pin should use.

Enumerator
PORT_PIN_PULL_NONE	No logical pull should be applied to the pin.
PORT_PIN_PULL_UP	Pin should be pulled up when idle.
PORT_PIN_PULL_DOWN	Pin should be pulled down when idle.

static enum status_code port_disable_input_event	(	const uint8_t	gpio_pin,
		const enum port_input_event	n
	)

inlinestatic

Disable the port event input.

Disable the port event input with the given pin and event.

Parameters

[in]	gpio_pin	Index of the GPIO pin
[in]	gpio_pin	Port input event

Return values

STATUS_ERR_INVALID_ARG	Invalid parameter
STATUS_OK	Successfully

References Assert, port_get_group_from_gpio_pin(), PORT_INPUT_EVENT_0, PORT_INPUT_EVENT_1, PORT_INPUT_EVENT_2, PORT_INPUT_EVENT_3, STATUS_ERR_INVALID_ARG, and STATUS_OK.

static enum status_code port_enable_input_event	(	const uint8_t	gpio_pin,
		const enum port_input_event	n
	)

inlinestatic

Enable the port event input.

Enable the port event input with the given pin and event.

Parameters

[in]	gpio_pin	Index of the GPIO pin
[in]	n	Port input event

Return values

STATUS_ERR_INVALID_ARG	Invalid parameter
STATUS_OK	Successfully

References Assert, port_get_group_from_gpio_pin(), PORT_INPUT_EVENT_0, PORT_INPUT_EVENT_1, PORT_INPUT_EVENT_2, PORT_INPUT_EVENT_3, STATUS_ERR_INVALID_ARG, and STATUS_OK.

static void port_get_config_defaults ( struct port_config *const config )

inlinestatic

Initializes a Port pin/group configuration structure to defaults.

Initializes a given Port pin/group configuration structure to a set of known default values. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

Input mode with internal pull-up enabled

Parameters

[out] config Configuration structure to initialize to default values

References Assert, port_config::direction, port_config::input_pull, PORT_PIN_DIR_INPUT, PORT_PIN_PULL_UP, and port_config::powersave.

Referenced by app_resources_uninit(), config_led(), config_port_pins(), configure_port_pins(), HAL_RadioIOInit(), HAL_ResetPinMakeInput(), HAL_ResetPinMakeOutput(), init_buttons(), init_chip_pins(), ksz8851snl_interface_init(), main(), nm_bsp_deinit(), nm_bus_deinit(), oled1_init(), port_input_event_set_config(), run_faultn_test(), run_faultx_test(), setup_extint_callback_mode_test(), setup_extint_polled_mode_test(), spi_attach_slave(), ssd1306_interface_init(), test_backup_mode(), and usb_dual_enable().

static PortGroup* port_get_group_from_gpio_pin ( const uint8_t gpio_pin )

inlinestatic

Retrieves the PORT module group instance from a given GPIO pin number.

Retrieves the PORT module group instance associated with a given logical GPIO pin number.

Parameters

[in] gpio_pin Index of the GPIO pin to convert

Returns: Base address of the associated PORT module.

References system_pinmux_get_group_from_gpio_pin().

Referenced by port_disable_input_event(), port_enable_input_event(), port_input_event_set_config(), port_pin_get_input_level(), port_pin_get_output_level(), port_pin_set_output_level(), and port_pin_toggle_output_level().

static uint32_t port_group_get_input_level	(	const PortGroup *const	port,
		const uint32_t	mask
	)

inlinestatic

Retrieves the state of a group of port pins that are configured as inputs.

Reads the current logic level of a port module's pins and returns the current levels as a bitmask.

Parameters

[in]	port	Base of the PORT module to read from
[in]	mask	Mask of the port pin(s) to read

Returns: Status of the port pin(s) input buffers.

References Assert.

static uint32_t port_group_get_output_level	(	const PortGroup *const	port,
		const uint32_t	mask
	)

inlinestatic

Retrieves the state of a group of port pins that are configured as outputs.

Reads the current logical output level of a port module's pins and returns the current levels as a bitmask.

Parameters

[in]	port	Base of the PORT module to read from
[in]	mask	Mask of the port pin(s) to read

Returns: Status of the port pin(s) output buffers.

References Assert.

void port_group_set_config	(	PortGroup *const	port,
		const uint32_t	mask,
		const struct port_config *const	config
	)

Writes a Port group configuration group to the hardware module.

Writes out a given configuration of a Port group configuration to the hardware module.

Note: If the pin direction is set as an output, the pull-up/pull-down input configuration setting is ignored.

Parameters

[out]	port	Base of the PORT module to write to
[in]	mask	Mask of the port pin(s) to configure
[in]	config	Configuration settings for the pin group

References Assert, system_pinmux_config::direction, port_config::direction, system_pinmux_config::input_pull, port_config::input_pull, system_pinmux_config::mux_position, system_pinmux_config::powersave, port_config::powersave, system_pinmux_get_config_defaults(), SYSTEM_PINMUX_GPIO, and system_pinmux_group_set_config().

static void port_group_set_output_level	(	PortGroup *const	port,
		const uint32_t	mask,
		const uint32_t	level_mask
	)

inlinestatic

Sets the state of a group of port pins that are configured as outputs.

Sets the current output level of a port module's pins to a given logic level.

Parameters

[out]	port	Base of the PORT module to write to
[in]	mask	Mask of the port pin(s) to change
[in]	level_mask	Mask of the port level(s) to set

References Assert.

static void port_group_toggle_output_level	(	PortGroup *const	port,
		const uint32_t	mask
	)

inlinestatic

Toggles the state of a group of port pins that are configured as an outputs.

Toggles the current output levels of a port module's pins.

Parameters

[out]	port	Base of the PORT module to write to
[in]	mask	Mask of the port pin(s) to toggle

References Assert.

static void port_input_event_get_config_defaults ( struct port_input_event_config *const config )

inlinestatic

Retrieve the default configuration for port input event.

Fills a configuration structure with the default configuration for port input event:

Event output to pin
Event action to be executed on PIN 0

Parameters

[out] config Configuration structure to fill with default values

References port_input_event_config::action, Assert, port_input_event_config::gpio_pin, and PORT_INPUT_EVENT_ACTION_OUT.

static enum status_code port_input_event_set_config	(	const enum port_input_event	n,
		struct port_input_event_config *const	config
	)

inlinestatic

Configure port input event.

Configures port input event with the given configuration settings.

Parameters

[in] config Port input even configuration structure containing the new config

Return values

STATUS_ERR_INVALID_ARG	Invalid parameter
STATUS_OK	Successfully

References port_input_event_config::action, Assert, port_config::direction, port_input_event_config::gpio_pin, port_get_config_defaults(), port_get_group_from_gpio_pin(), PORT_INPUT_EVENT_0, PORT_INPUT_EVENT_1, PORT_INPUT_EVENT_2, PORT_INPUT_EVENT_3, PORT_PIN_DIR_OUTPUT, port_pin_set_config(), STATUS_ERR_INVALID_ARG, and STATUS_OK.

static bool port_pin_get_input_level ( const uint8_t gpio_pin )

inlinestatic

Retrieves the state of a port pin that is configured as an input.

Reads the current logic level of a port pin and returns the current level as a Boolean value.

Parameters

[in] gpio_pin Index of the GPIO pin to read

Returns: Status of the port pin's input buffer.

References port_get_group_from_gpio_pin().

Referenced by btn_init(), button_pressed(), eic_callback_to_clear_halt(), extint_detection_callback(), get_button(), HAL_DIO0PinValue(), HAL_DIO1PinValue(), HAL_DIO2PinValue(), main(), oled1_get_button_state(), oled1_get_led_state(), sd_mmc_is_write_protected(), sd_mmc_select_slot(), and update_led_state().

static bool port_pin_get_output_level ( const uint8_t gpio_pin )

inlinestatic

Retrieves the state of a port pin that is configured as an output.

Reads the current logical output level of a port pin and returns the current level as a Boolean value.

Parameters

[in] gpio_pin Index of the GPIO pin to read

Returns: Status of the port pin's output buffer.

References port_get_group_from_gpio_pin().

Referenced by iso7816_get_reset_statuts().

void port_pin_set_config	(	const uint8_t	gpio_pin,
		const struct port_config *const	config
	)

Writes a Port pin configuration to the hardware module.

Writes out a given configuration of a Port pin configuration to the hardware module.

Note: If the pin direction is set as an output, the pull-up/pull-down input configuration setting is ignored.

Parameters

[in]	gpio_pin	Index of the GPIO pin to configure
[in]	config	Configuration settings for the pin

References Assert, system_pinmux_config::direction, port_config::direction, system_pinmux_config::input_pull, port_config::input_pull, system_pinmux_config::mux_position, system_pinmux_config::powersave, port_config::powersave, system_pinmux_get_config_defaults(), SYSTEM_PINMUX_GPIO, and system_pinmux_pin_set_config().

Referenced by app_resources_uninit(), config_led(), config_port_pins(), configure_port_pins(), HAL_RadioIOInit(), HAL_ResetPinMakeInput(), HAL_ResetPinMakeOutput(), init_buttons(), init_chip_pins(), ksz8851snl_interface_init(), mac_init(), main(), nm_bsp_deinit(), oled1_init(), port_input_event_set_config(), run_faultn_test(), run_faultx_test(), setup_extint_callback_mode_test(), setup_extint_polled_mode_test(), spi_attach_slave(), ssd1306_interface_init(), test_backup_mode(), and usb_dual_enable().

static void port_pin_set_output_level	(	const uint8_t	gpio_pin,
		const bool	level
	)

inlinestatic

Sets the state of a port pin that is configured as an output.

Sets the current output level of a port pin to a given logic level.

Parameters

[in]	gpio_pin	Index of the GPIO pin to write to
[in]	level	Logical level to set the given pin to

References port_get_group_from_gpio_pin().

Referenced by config_led(), control_cmd_handler(), extint_detection_callback(), HAL_DisableRFCtrl(), HAL_EnableRFCtrl(), HAL_RadioIOInit(), HAL_ResetPinOutputValue(), HAL_TCXOPowerOff(), HAL_TCXOPowerOn(), init_chip_pins(), iso7816_icc_power_off(), iso7816_icc_power_on(), ksz8851snl_hard_reset(), led_toggle_indication(), mac_t_gts_cb(), main(), nm_bsp_deinit(), nm_bsp_reset(), oled1_init(), oled1_set_led_state(), process_data_ind_not_transient(), run_extint_callback_mode_test(), run_extint_polled_mode_test(), run_faultn_test(), run_faultx_test(), setup_extint_callback_mode_test(), setup_extint_polled_mode_test(), socket_cb(), spi_attach_slave(), spi_select_slave(), ssd1306_hard_reset(), ssd1306_init(), ssd1306_write_command(), ssd1306_write_data(), start_application(), test_backup_mode(), test_idle_mode(), test_standby_mode_dynamic_power_sleepwalking(), test_standby_mode_static_power_sleepwalking(), update_led_state(), watchdog_early_warning_callback(), xosc32k_fail_callback(), and xosc32k_ok_callback().

static void port_pin_toggle_output_level ( const uint8_t gpio_pin )

inlinestatic

Toggles the state of a port pin that is configured as an output.

Toggles the current output level of a port pin.

Parameters

[in] gpio_pin Index of the GPIO pin to toggle

References port_get_group_from_gpio_pin().

Referenced by event_counter(), handle_gts_data_tx_end(), mac_process_data_frame(), main(), oled1_toggle_led_state(), process_data_ind_not_transient(), rtc_match_callback(), rtc_overflow_callback(), SysTick_Handler(), tc_callback_to_toggle_led(), tcc_callback_to_toggle_led(), and usart_write_callback().

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Driver Feature Macro Definition

Physical and Logical GPIO Pins

Physical Connection

Special Considerations

Extra Information

Examples

API Overview

Modules

Data Structures

Enumerations

Driver Feature Definition

PORT Alias Macros

State Reading/Writing (Physical Group Orientated)

Configuration and Initialization

State Reading/Writing (Logical Pin Orientated)

Port Input Event