APPLICATION NOTE
AT03248: SAM Port Driver (PORT)
ASF PROGRAMMERS MANUAL
SAM Port Driver (PORT)
This driver for Atmel® | SMART SAM devices 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 peripherals are 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 D10/D11
The outline of this documentation is as follows:
●
Prerequisites
●
Module Overview
●
Special Considerations
●
Extra Information
●
Examples
●
API Overview
42113D-SAMD20/D21-12/2014
Table of Contents
SAM Port Driver (PORT) .................................................................... 1
Software License ................................................................................ 3
1. Prerequisites ................................................................................. 4
2. Module Overview .......................................................................... 5
2.1.
2.2.
Physical and Logical GPIO Pins .................................................... 5
Physical Connection .................................................................... 5
3. Special Considerations ................................................................. 6
4. Extra Information .......................................................................... 7
5. Examples ...................................................................................... 8
6. API Overview ................................................................................ 9
6.1.
6.2.
6.3.
6.4.
Structure Definitions .................................................................... 9
6.1.1.
Struct port_config ........................................................... 9
Macro Definitions ........................................................................ 9
6.2.1.
PORT Alias Macros ........................................................ 9
Function Definitions ................................................................... 10
6.3.1.
State Reading/Writing (Physical Group Orientated) .............. 10
6.3.2.
Configuration and Initialization ......................................... 11
6.3.3.
State Reading/Writing (Logical Pin Orientated) .................... 13
Enumeration Definitions .............................................................. 14
6.4.1.
Enum port_pin_dir ........................................................ 14
6.4.2.
Enum port_pin_pull ...................................................... 14
7. Extra Information for PORT Driver ............................................. 15
7.1.
7.2.
7.3.
7.4.
Acronyms ................................................................................
Dependencies ...........................................................................
Errata ......................................................................................
Module History .........................................................................
15
15
15
15
8. Examples for PORT Driver ......................................................... 16
8.1.
Quick Start Guide for PORT - Basic .............................................. 16
8.1.1.
Setup .......................................................................... 16
8.1.2.
Use Case .................................................................... 17
Index ................................................................................................. 18
Document Revision History .............................................................. 19
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
2
Software License
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
3. The name of Atmel may not be used to endorse or promote products derived from this software without specific
prior written permission.
4. This software may only be redistributed and used in connection with an Atmel microcontroller product.
THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN
NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
3
1.
Prerequisites
There are no prerequisites for this module.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
4
2.
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.
2.1
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.
2.2
Physical Connection
Figure 2-1: Physical Connection on page 5 shows how this module is interconnected within the device.
Figure 2-1. Physical Connection
Por t Pa d
P e r ip h e r a l M U X
GP IO M o d u le
Ot h e r P e r ip h e r a l M o d u le s
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
5
3.
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.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
6
4.
Extra Information
For extra information, see Extra Information for PORT Driver. This includes:
●
Acronyms
●
Dependencies
●
Errata
●
Module History
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
7
5.
Examples
For a list of examples related to this driver, see Examples for PORT Driver.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
8
6.
API Overview
6.1
Structure Definitions
6.1.1
Struct port_config
Configuration structure for a port pin instance. This structure should be initialized by the port_get_config_defaults()
function before being modified by the user application.
Table 6-1. Members
Type
Name
Description
enum port_pin_dir
direction
Port buffer input/output direction.
enum port_pin_pull
input_pull
Port pull-up/pull-down for input
pins.
bool
powersave
Enable lowest possible powerstate
1
on the pin
Notes:
1
All other configurations will be ignored, the pin will be disabled.
6.2
Macro Definitions
6.2.1
PORT Alias Macros
6.2.1.1
Macro PORTA
#define PORTA PORT->Group[0]
Convenience definition for GPIO module group A on the device (if available).
6.2.1.2
Macro PORTB
#define PORTB PORT->Group[1]
Convenience definition for GPIO module group B on the device (if available).
6.2.1.3
Macro PORTC
#define PORTC PORT->Group[2]
Convenience definition for GPIO module group C on the device (if available).
6.2.1.4
Macro PORTD
#define PORTD PORT->Group[3]
Convenience definition for GPIO module group D on the device (if available).
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
9
6.3
Function Definitions
6.3.1
State Reading/Writing (Physical Group Orientated)
6.3.1.1
Function port_get_group_from_gpio_pin()
Retrieves the PORT module group instance from a given GPIO pin number.
PortGroup * port_get_group_from_gpio_pin(
const uint8_t gpio_pin)
Retrieves the PORT module group instance associated with a given logical GPIO pin number.
Table 6-2. Parameters
Data direction
Parameter name
Description
[in]
gpio_pin
Index of the GPIO pin to convert.
Returns
6.3.1.2
Base address of the associated PORT module.
Function port_group_get_input_level()
Retrieves the state of a group of port pins that are configured as inputs.
uint32_t port_group_get_input_level(
const PortGroup *const port,
const uint32_t mask)
Reads the current logic level of a port module's pins and returns the current levels as a bitmask.
Table 6-3. Parameters
Returns
6.3.1.3
Data direction
Parameter name
Description
[in]
port
Base of the PORT module to read
from.
[in]
mask
Mask of the port pin(s) to read.
Status of the port pin(s) input buffers.
Function port_group_get_output_level()
Retrieves the state of a group of port pins that are configured as outputs.
uint32_t port_group_get_output_level(
const PortGroup *const port,
const uint32_t mask)
Reads the current logical output level of a port module's pins and returns the current levels as a bitmask.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
10
Table 6-4. Parameters
Data direction
Parameter name
Description
[in]
port
Base of the PORT module to read
from.
[in]
mask
Mask of the port pin(s) to read.
Returns
6.3.1.4
Status of the port pin(s) output buffers.
Function port_group_set_output_level()
Sets the state of a group of port pins that are configured as outputs.
void port_group_set_output_level(
PortGroup *const port,
const uint32_t mask,
const uint32_t level_mask)
Sets the current output level of a port module's pins to a given logic level.
Table 6-5. Parameters
6.3.1.5
Data direction
Parameter name
Description
[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.
Function port_group_toggle_output_level()
Toggles the state of a group of port pins that are configured as an outputs.
void port_group_toggle_output_level(
PortGroup *const port,
const uint32_t mask)
Toggles the current output levels of a port module's pins.
Table 6-6. Parameters
Data direction
Parameter name
Description
[out]
port
Base of the PORT module to write
to.
[in]
mask
Mask of the port pin(s) to toggle.
6.3.2
Configuration and Initialization
6.3.2.1
Function port_get_config_defaults()
Initializes a Port pin/group configuration structure to defaults.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
11
void port_get_config_defaults(
struct port_config *const config)
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 pullup enabled
Table 6-7. Parameters
6.3.2.2
Data direction
Parameter name
Description
[out]
config
Configuration structure to initialize
to default values.
Function port_pin_set_config()
Writes a Port pin configuration to the hardware module.
void port_pin_set_config(
const uint8_t gpio_pin,
const struct port_config *const config)
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.
Table 6-8. Parameters
6.3.2.3
Data direction
Parameter name
Description
[in]
gpio_pin
Index of the GPIO pin to configure.
[in]
config
Configuration settings for the pin.
Function port_group_set_config()
Writes a Port group configuration group to the hardware module.
void port_group_set_config(
PortGroup *const port,
const uint32_t mask,
const struct port_config *const config)
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.
Table 6-9. Parameters
Data direction
Parameter name
Description
[out]
port
Base of the PORT module to write
to.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
12
Data direction
Parameter name
Description
[in]
mask
Mask of the port pin(s) to
configure.
[in]
config
Configuration settings for the pin
group.
6.3.3
State Reading/Writing (Logical Pin Orientated)
6.3.3.1
Function port_pin_get_input_level()
Retrieves the state of a port pin that is configured as an input.
bool port_pin_get_input_level(
const uint8_t gpio_pin)
Reads the current logic level of a port pin and returns the current level as a Boolean value.
Table 6-10. Parameters
Data direction
Parameter name
Description
[in]
gpio_pin
Index of the GPIO pin to read.
Returns
6.3.3.2
Status of the port pin's input buffer.
Function port_pin_get_output_level()
Retrieves the state of a port pin that is configured as an output.
bool port_pin_get_output_level(
const uint8_t gpio_pin)
Reads the current logical output level of a port pin and returns the current level as a Boolean value.
Table 6-11. Parameters
Returns
6.3.3.3
Data direction
Parameter name
Description
[in]
gpio_pin
Index of the GPIO pin to read.
Status of the port pin's output buffer.
Function port_pin_set_output_level()
Sets the state of a port pin that is configured as an output.
void port_pin_set_output_level(
const uint8_t gpio_pin,
const bool level)
Sets the current output level of a port pin to a given logic level.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
13
Table 6-12. Parameters
6.3.3.4
Data direction
Parameter name
Description
[in]
gpio_pin
Index of the GPIO pin to write to.
[in]
level
Logical level to set the given pin to.
Function port_pin_toggle_output_level()
Toggles the state of a port pin that is configured as an output.
void port_pin_toggle_output_level(
const uint8_t gpio_pin)
Toggles the current output level of a port pin.
Table 6-13. Parameters
Data direction
Parameter name
Description
[in]
gpio_pin
Index of the GPIO pin to toggle.
6.4
Enumeration Definitions
6.4.1
Enum port_pin_dir
Enum for the possible pin direction settings of the port pin configuration structure, to indicate the direction the pin
should use.
Table 6-14. Members
6.4.2
Enum value
Description
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
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.
Table 6-15. Members
Enum value
Description
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.
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
14
7.
Extra Information for PORT Driver
7.1
Acronyms
Below is a table listing the acronyms used in this module, along with their intended meanings.
7.2
Acronym
Description
GPIO
General Purpose Input/Output
MUX
Multiplexer
Dependencies
This driver has the following dependencies:
●
7.3
System Pin Multiplexer Driver
Errata
There are no errata related to this driver.
7.4
Module History
An overview of the module history is presented in the table below, with details on the enhancements and fixes
made to the module since its first release. The current version of this corresponds to the newest version in the
table.
Changelog
Added support for SAMD21
Initial Release
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
15
8.
Examples for PORT Driver
This is a list of the available Quick Start guides (QSGs) and example applications for SAM Port Driver (PORT).
QSGs are simple examples with step-by-step instructions to configure and use this driver in a selection of use
cases. Note that QSGs can be compiled as a standalone application or be added to the user application.
●
8.1
Quick Start Guide for PORT - Basic
Quick Start Guide for PORT - Basic
In this use case, the PORT module is configured for:
●
One pin in input mode, with pull-up enabled
●
One pin in output mode
This use case sets up the PORT to read the current state of a GPIO pin set as an input, and mirrors the opposite
logical state on a pin configured as an output.
8.1.1
Setup
8.1.1.1
Prerequisites
There are no special setup requirements for this use-case.
8.1.1.2
Code
Copy-paste the following setup code to your user application:
void configure_port_pins(void)
{
struct port_config config_port_pin;
port_get_config_defaults(&config_port_pin);
config_port_pin.direction = PORT_PIN_DIR_INPUT;
config_port_pin.input_pull = PORT_PIN_PULL_UP;
port_pin_set_config(BUTTON_0_PIN, &config_port_pin);
}
config_port_pin.direction = PORT_PIN_DIR_OUTPUT;
port_pin_set_config(LED_0_PIN, &config_port_pin);
Add to user application initialization (typically the start of main()):
configure_port_pins();
8.1.1.3
Workflow
1.
Create a PORT module pin configuration struct, which can be filled out to adjust the configuration of a single
port pin.
struct port_config config_port_pin;
2.
Initialize the pin configuration struct with the module's default values.
port_get_config_defaults(&config_port_pin);
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
16
Note
This should always be performed before using the configuration struct to ensure that all values
are initialized to known default settings.
3.
Adjust the configuration struct to request an input pin.
config_port_pin.direction = PORT_PIN_DIR_INPUT;
config_port_pin.input_pull = PORT_PIN_PULL_UP;
4.
Configure push button pin with the initialized pin configuration struct, to enable the input sampler on the pin.
port_pin_set_config(BUTTON_0_PIN, &config_port_pin);
5.
Adjust the configuration struct to request an output pin.
config_port_pin.direction = PORT_PIN_DIR_OUTPUT;
Note
The existing configuration struct may be re-used, as long as any values that have been altered
from the default settings are taken into account by the user application.
6.
Configure LED pin with the initialized pin configuration struct, to enable the output driver on the pin.
port_pin_set_config(LED_0_PIN, &config_port_pin);
8.1.2
Use Case
8.1.2.1
Code
Copy-paste the following code to your user application:
while (true) {
bool pin_state = port_pin_get_input_level(BUTTON_0_PIN);
}
8.1.2.2
port_pin_set_output_level(LED_0_PIN, !pin_state);
Workflow
1.
Read in the current input sampler state of push button pin, which has been configured as an input in the usecase setup code.
bool pin_state = port_pin_get_input_level(BUTTON_0_PIN);
2.
Write the inverted pin level state to LED pin, which has been configured as an output in the use-case setup
code.
port_pin_set_output_level(LED_0_PIN, !pin_state);
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
17
Index
E
Enumeration Definitions
port_pin_dir, 14
port_pin_pull, 14
F
Function Definitions
port_get_config_defaults, 11
port_get_group_from_gpio_pin, 10
port_group_get_input_level, 10
port_group_get_output_level, 10
port_group_set_config, 12
port_group_set_output_level, 11
port_group_toggle_output_level, 11
port_pin_get_input_level, 13
port_pin_get_output_level, 13
port_pin_set_config, 12
port_pin_set_output_level, 13
port_pin_toggle_output_level, 14
M
Macro Definitions
PORTA, 9
PORTB, 9
PORTC, 9
PORTD, 9
S
Structure Definitions
port_config, 9
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
18
Document Revision History
Doc. Rev.
Date
Comments
D
12/2014
Added support for SAMR21 and
SAMD10/D11.
C
01/2014
Added support for SAMD21.
B
06/2013
Corrected documentation typos.
A
06/2013
Initial release
AT03248: SAM Port Driver (PORT) [APPLICATION NOTE]
42113D-SAMD20/D21-12/2014
19
Atmel Corporation
1600 Technology Drive, San Jose, CA 95110 USA
T: (+1)(408) 441.0311
F: (+1)(408) 436.4200
|
www.atmel.com
© 2014 Atmel Corporation. / Rev.: 42113D-SAMD20/D21-12/2014
®
®
Atmel , Atmel logo and combinations thereof, Enabling Unlimited Possibilities , and others are registered trademarks or trademarks of Atmel Corporation in U.S. and other
countries. Other terms and product names may be trademarks of others.
DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted
by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL
ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF
INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no
representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any
time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used
in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.
SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of
such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications
include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in
military or aerospace applications or environments unless specifically designated by Atmel as military- grade. Atmel products are not designed nor intended for use in automotive applications unless
specifically designated by Atmel as automotive-grade.