Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM System Pin Multiplexer (SYSTEM PINMUX) Driver

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:

The following devices can use this module:

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

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.

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.

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.

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]configConfiguration 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 _adc_configure_ain_pin(), _i2c_slave_set_config(), _spi_set_config(), config_clock_output_and_extwake_pin(), configure_ac_channel(), configure_ccl_lut0(), configure_ccl_lut1(), configure_non_inverting_pga_opamp0(), configure_opamp2(), dac_chan_set_config(), extint_chan_set_config(), extint_nmi_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(), tc_init(), 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_pinIndex 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]portBase of the PORT module to configure
[in]maskMask of the port pin(s) to configure
[in]configConfiguration 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]portBase of the PORT module to configure
[in]maskMask of the port pin(s) to configure
[in]modeNew 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_pinIndex of the GPIO pin to configure
Returns
Currently selected peripheral index on the specified pin.

References 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_pinIndex of the GPIO pin to configure
[in]configConfiguration settings for the pin

References _system_pinmux_config(), and system_pinmux_get_group_from_gpio_pin().

Referenced by _adc_configure_ain_pin(), _i2c_slave_set_config(), _spi_set_config(), config_clock_output_and_extwake_pin(), configure_ac_channel(), configure_ccl_lut0(), configure_ccl_lut1(), configure_non_inverting_pga_opamp0(), configure_opamp2(), dac_chan_set_config(), extint_chan_set_config(), extint_nmi_set_config(), main(), port_pin_set_config(), run_ac_init_test(), setup_ac_callback_mode_test(), setup_ac_window_mode_test(), tc_init(), 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_pinIndex of the GPIO pin to configure
[in]modeNew pin sampling mode to configure

References 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_pinIndex of the GPIO pin to configure
[in]modeNew output driver strength mode to configure

References system_pinmux_get_group_from_gpio_pin(), and SYSTEM_PINMUX_PIN_STRENGTH_HIGH.