This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's physical I/O Pins, to alter the direction and input/drive characteristics as well as to configure the pin peripheral multiplexer selection.

The following peripheral is used by this module:

PORT (Port I/O 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 SAM devices contain a number of General Purpose I/O pins, used to interface the user application logic and internal hardware peripherals to an external system. The Pin Multiplexer (PINMUX) driver provides a method of configuring the individual pin peripheral multiplexers to select alternate pin functions.

Driver Feature Macro Definition

Driver Feature Macro	Supported devices
FEATURE_SYSTEM_PINMUX_DRIVE_STRENGTH	SAM L21, SAM C20/C21, SAM 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.

Peripheral Multiplexing

SAM devices contain a peripheral MUX, which is individually controllable for each I/O pin of the device. The peripheral MUX allows you to select the function of a physical package pin - whether it will be controlled as a user controllable GPIO pin, or whether it will be connected internally to one of several peripheral modules (such as an I²C module). When a pin is configured in GPIO mode, other peripherals connected to the same pin will be disabled.

Special Pad Characteristics

There are several special modes that can be selected on one or more I/O pins of the device, which alter the input and output characteristics of the pad.

Drive Strength

The Drive Strength configures the strength of the output driver on the pad. Normally, there is a fixed current limit that each I/O pin can safely drive, however some I/O pads offer a higher drive mode which increases this limit for that I/O pin at the expense of an increased power consumption.

Slew Rate

The Slew Rate configures the slew rate of the output driver, limiting the rate at which the pad output voltage can change with time.

Input Sample Mode

The Input Sample Mode configures the input sampler buffer of the pad. By default, the input buffer is only sampled "on-demand", i.e. when the user application attempts to read from the input buffer. This mode is the most power efficient, but increases the latency of the input sample by two clock cycles of the port clock. To reduce latency, the input sampler can instead be configured to always sample the input buffer on each port clock cycle, at the expense of an increased power consumption.

Physical Connection

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

Special Considerations

The SAM port pin input sampling mode is set in groups of four physical pins; setting the sampling mode of any pin in a sub-group of eight I/O pins will configure the sampling mode of the entire sub-group.

High Drive Strength output driver mode is not available on all device pins - refer to your device specific datasheet.

Extra Information

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

Examples

For a list of examples related to this driver, see Examples for SYSTEM PINMUX 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 System Pin Multiplexer (SYSTEM PINMUX) Driver.

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

Macros
#define	FEATURE_SYSTEM_PINMUX_DRIVE_STRENGTH
	Output Driver Strength Selection feature support. More...

#define	SYSTEM_PINMUX_GPIO (1 << 7)
	Peripheral multiplexer index to select GPIO mode for a pin. More...

Enumerations
enum	system_pinmux_pin_dir { SYSTEM_PINMUX_PIN_DIR_INPUT, SYSTEM_PINMUX_PIN_DIR_OUTPUT, SYSTEM_PINMUX_PIN_DIR_OUTPUT_WITH_READBACK }
	Port pin direction configuration enum. More...

enum	system_pinmux_pin_pull { SYSTEM_PINMUX_PIN_PULL_NONE, SYSTEM_PINMUX_PIN_PULL_UP, SYSTEM_PINMUX_PIN_PULL_DOWN }
	Port pin input pull configuration enum. More...

enum	system_pinmux_pin_sample { SYSTEM_PINMUX_PIN_SAMPLE_CONTINUOUS, SYSTEM_PINMUX_PIN_SAMPLE_ONDEMAND }
	Port pin digital input sampling mode enum. More...

enum	system_pinmux_pin_strength { SYSTEM_PINMUX_PIN_STRENGTH_NORMAL, SYSTEM_PINMUX_PIN_STRENGTH_HIGH }
	Port pin drive output strength enum. More...

Functions
void	system_pinmux_group_set_output_strength (PortGroup *const port, const uint32_t mask, const enum system_pinmux_pin_strength mode)

static void	system_pinmux_pin_set_output_strength (const uint8_t gpio_pin, const enum system_pinmux_pin_strength mode)
	Configures the output driver strength mode for a GPIO pin. More...

Configuration and Initialization
static void	system_pinmux_get_config_defaults (struct system_pinmux_config *const config)
	Initializes a Port pin configuration structure to defaults. More...

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

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

Special Mode Configuration (Physical Group Orientated)
static PortGroup *	system_pinmux_get_group_from_gpio_pin (const uint8_t gpio_pin)
	Retrieves the PORT module group instance from a given GPIO pin number. More...

void	system_pinmux_group_set_input_sample_mode (PortGroup *const port, const uint32_t mask, const enum system_pinmux_pin_sample mode)
	Configures the input sampling mode for a group of pins. More...

Special Mode Configuration (Logical Pin Orientated)
static uint8_t	system_pinmux_pin_get_mux_position (const uint8_t gpio_pin)
	Retrieves the currently selected MUX position of a logical pin. More...

static void	system_pinmux_pin_set_input_sample_mode (const uint8_t gpio_pin, const enum system_pinmux_pin_sample mode)
	Configures the input sampling mode for a GPIO pin. More...

#define FEATURE_SYSTEM_PINMUX_DRIVE_STRENGTH

Output Driver Strength Selection feature support.

#define SYSTEM_PINMUX_GPIO (1 << 7)

Peripheral multiplexer index to select GPIO mode for a pin.

Referenced by _system_pinmux_config(), main(), port_group_set_config(), port_pin_set_config(), system_pinmux_get_config_defaults(), and system_pinmux_pin_get_mux_position().

enum system_pinmux_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
SYSTEM_PINMUX_PIN_DIR_INPUT	The pin's input buffer should be enabled, so that the pin state can be read.
SYSTEM_PINMUX_PIN_DIR_OUTPUT	The pin's output buffer should be enabled, so that the pin state can be set (but not read back)
SYSTEM_PINMUX_PIN_DIR_OUTPUT_WITH_READBACK	The pin's output and input buffers should both be enabled, so that the pin state can be set and read back.

enum system_pinmux_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
SYSTEM_PINMUX_PIN_PULL_NONE	No logical pull should be applied to the pin.
SYSTEM_PINMUX_PIN_PULL_UP	Pin should be pulled up when idle.
SYSTEM_PINMUX_PIN_PULL_DOWN	Pin should be pulled down when idle.

enum system_pinmux_pin_sample

Port pin digital input sampling mode enum.

Enum for the possible input sampling modes for the port pin configuration structure, to indicate the type of sampling a port pin should use.

Enumerator
SYSTEM_PINMUX_PIN_SAMPLE_CONTINUOUS	Pin input buffer should continuously sample the pin state.
SYSTEM_PINMUX_PIN_SAMPLE_ONDEMAND	Pin input buffer should be enabled when the IN register is read.

enum system_pinmux_pin_strength

Port pin drive output strength enum.

Enum for the possible output drive strengths for the port pin configuration structure, to indicate the driver strength the pin should use.

Enumerator
SYSTEM_PINMUX_PIN_STRENGTH_NORMAL	Normal output driver strength.
SYSTEM_PINMUX_PIN_STRENGTH_HIGH	High current output driver strength.

static void system_pinmux_get_config_defaults ( struct system_pinmux_config *const config )

inlinestatic

Initializes a Port pin configuration structure to defaults.

Initializes a given Port pin 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:

Non peripheral (i.e. GPIO) controlled
Input mode with internal pull-up enabled

Parameters

[out] config Configuration structure to initialize to default values

References Assert, system_pinmux_config::direction, system_pinmux_config::input_pull, system_pinmux_config::mux_position, system_pinmux_config::powersave, SYSTEM_PINMUX_GPIO, SYSTEM_PINMUX_PIN_DIR_INPUT, and SYSTEM_PINMUX_PIN_PULL_UP.

Referenced by _i2c_slave_set_config(), _spi_set_config(), configure_ac(), configure_ac_channel(), dac_init(), dbg_init(), extint_chan_set_config(), extint_nmi_set_config(), i2s_clock_unit_set_config(), i2s_serializer_set_config(), main(), port_group_set_config(), port_pin_set_config(), run_ac_init_test(), setup_ac_callback_mode_test(), setup_ac_window_mode_test(), setup_clock_out_pin(), tcc_init(), usart_init(), and usb_init().

static PortGroup* system_pinmux_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 Assert, and NULL.

Referenced by port_get_group_from_gpio_pin(), system_pinmux_pin_get_mux_position(), system_pinmux_pin_set_config(), system_pinmux_pin_set_input_sample_mode(), and system_pinmux_pin_set_output_strength().

void system_pinmux_group_set_config	(	PortGroup *const	port,
		const uint32_t	mask,
		const struct system_pinmux_config *const	config
	)

Writes a Port pin group configuration to the hardware module.

Writes out a given configuration of a Port pin 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

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

References _system_pinmux_config(), Assert, and i.

Referenced by port_group_set_config().

void system_pinmux_group_set_input_sample_mode	(	PortGroup *const	port,
		const uint32_t	mask,
		const enum system_pinmux_pin_sample	mode
	)

Configures the input sampling mode for a group of pins.

Configures the input sampling mode for a group of pins, to control when the physical I/O pin value is sampled and stored inside the microcontroller.

Parameters

[in]	port	Base of the PORT module to configure
[in]	mask	Mask of the port pin(s) to configure
[in]	mode	New pin sampling mode to configure

References Assert, and SYSTEM_PINMUX_PIN_SAMPLE_ONDEMAND.

void system_pinmux_group_set_output_strength	(	PortGroup *const	port,
		const uint32_t	mask,
		const enum system_pinmux_pin_strength	mode
	)

static uint8_t system_pinmux_pin_get_mux_position ( const uint8_t gpio_pin )

inlinestatic

Retrieves the currently selected MUX position of a logical pin.

Retrieves the selected MUX peripheral on a given logical GPIO pin.

Parameters

[in] gpio_pin Index of the GPIO pin to configure

Returns: Currently selected peripheral index on the specified pin.

References port, system_pinmux_get_group_from_gpio_pin(), and SYSTEM_PINMUX_GPIO.

Referenced by _spi_check_config().

void system_pinmux_pin_set_config	(	const uint8_t	gpio_pin,
		const struct system_pinmux_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 _system_pinmux_config(), port, and system_pinmux_get_group_from_gpio_pin().

Referenced by _i2c_slave_set_config(), _spi_set_config(), configure_ac(), configure_ac_channel(), dac_init(), dbg_init(), extint_chan_set_config(), extint_nmi_set_config(), i2s_clock_unit_set_config(), i2s_serializer_set_config(), main(), port_pin_set_config(), run_ac_init_test(), setup_ac_callback_mode_test(), setup_ac_window_mode_test(), setup_clock_out_pin(), tcc_init(), usart_init(), and usb_init().

static void system_pinmux_pin_set_input_sample_mode	(	const uint8_t	gpio_pin,
		const enum system_pinmux_pin_sample	mode
	)

inlinestatic

Configures the input sampling mode for a GPIO pin.

Configures the input sampling mode for a GPIO input, to control when the physical I/O pin value is sampled and stored inside the microcontroller.

Parameters

[in]	gpio_pin	Index of the GPIO pin to configure
[in]	mode	New pin sampling mode to configure

References port, system_pinmux_get_group_from_gpio_pin(), and SYSTEM_PINMUX_PIN_SAMPLE_ONDEMAND.

Referenced by main().

static void system_pinmux_pin_set_output_strength	(	const uint8_t	gpio_pin,
		const enum system_pinmux_pin_strength	mode
	)

inlinestatic

Configures the output driver strength mode for a GPIO pin.

Configures the output drive strength for a GPIO output, to control the amount of current the pad is able to sink/source.

Parameters

[in]	gpio_pin	Index of the GPIO pin to configure
[in]	mode	New output driver strength mode to configure

References port, system_pinmux_get_group_from_gpio_pin(), and SYSTEM_PINMUX_PIN_STRENGTH_HIGH.

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Driver Feature Macro Definition

Physical and Logical GPIO Pins

Peripheral Multiplexing

Special Pad Characteristics

Drive Strength

Slew Rate

Input Sample Mode

Physical Connection

Special Considerations

Extra Information

Examples

API Overview

Modules

Data Structures

Macros

Enumerations

Functions

Configuration and Initialization

Special Mode Configuration (Physical Group Orientated)

Special Mode Configuration (Logical Pin Orientated)