I/O Port Driver

Table of Contents

• I/O PORT HAL Module Introduction
  • I/O PORT HAL Module Features
  • I/O Port Hardware support details
• I/O PORT HAL Module APIs Overview
• I/O PORT HAL Module Operational Overview
  • I/O PORT HAL Module Important Operational Notes and Limitations
    • I/O PORT HAL Module Operational Notes
    • I/O PORT HAL Module Limitations
• Including the I/O PORT HAL Module in an Application
• Configuring the I/O PORT HAL Module
  • I/O PORT HAL Module Clock Configuration
  • I/O PORT HAL Module Pin Configuration
• Using the I/O PORT HAL Module in an Application

I/O PORT HAL Module Introduction

The I/O Port HAL module implements a high-level API for controlling I/O pins, configuring the board's pins and manipulating I/O pins. The operating state of an I/O pin can be set via the Synergy configurator.  When the Synergy project is built, a pin configuration file is created. When the application runs, the BSP will configure the MCU IO port accordingly, using the same API functions described in this document.

I/O PORT HAL Module Features

The I/O PORT HAL module can perform the following functions:

• Create an event link between two blocks.
• Break that event link between two blocks.
• Generate one of two software events that interrupt the CPU.

I/O PORT HAL Module Block Diagram

I/O Port Hardware support details

The following hardware features are, or are not, supported by SSP for GPIO.

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

MCU Group	Port Direction Setting	Input Data Read function	Output Port Write function	Pin Mode Control	Ethernet Mode Configuration	ELC_PORTn Event Input Read function*	ELC_PORTn Event Output Setting *
S124	✓	✓	✓	✓	N/A	✓	✓
S128	✓	✓	✓	✓	N/A	✓	✓
S1JA	✓	✓	✓	✓	N/A	✓	✓
S3A1	✓	✓	✓	✓	N/A	✓	✓
S3A3	✓	✓	✓	✓	N/A	✓	✓
S3A6	✓	✓	✓	✓	N/A	✓	✓
S3A7	✓	✓	✓	✓	N/A	✓	✓
S5D3	✓	✓	✓	✓	✓	✓	✓
S5D5	✓	✓	✓	✓	✓	✓	✓
S5D9	✓	✓	✓	✓	✓	✓	✓
S7G2	✓	✓	✓	✓	✓	✓	✓

• Note: Event Linking would have to be set up by the user, rather than using the ELC API.

I/O PORT HAL Module APIs Overview

The I/O Port HAL module defines APIs for reading and writing from particular pins and ports. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

I/O PORT HAL Module API Summary

Function Name	Example API Call and Description
init	g_ioport.p_api->init(g_ioport.p_cfg); Initialize configuration of multiple pins.
pinCfg	g_ioport.p_api->pinCfg(IOPORT_PORT_00_PIN_00, IOPORT_CFG_IRQ_ENABLE | IOPORT_CFG_PORT_DIRECTION_INPUT); Configure settings for an individual pin.
pinDirectionSet	g_ioport.p_api->pinDirectionSet(IOPORT_PORT_00_PIN_00, IOPORT_DIRECTION_INPUT); Set the pin direction of a pin.
pinEventInputRead	g_ioport.p_api->pinEventInputRead(IOPORT_PORT_00_PIN_00, &pin_level); Read the event (ELC) input data of the specified pin and return the level.
pinEventOutputWrite	g_ioport.p_api->pinEventOutputWrite(IOPORT_PORT_00_PIN_00, IOPORT_PIN_LEVEL_HIGH); Write pin event (ELC) data.
pinEthernetModeCfg	g_ioport.p_api->pinEthernetModeCfg(IOPORT_ETHERNET_CHANNEL_0, IOPORT_ETHERNET_MODE_MII); Configure the PHY mode of the Ethernet channels.
pinRead	g_ioport.p_api->pinRead(IOPORT_PORT_00_PIN_00, &pin_level); Read level of a pin.
pinWrite	g_ioport.p_api->pinWrite(IOPORT_PORT_00_PIN_00, IOPORT_PIN_LEVEL_HIGH); Write specified level to a pin.
portDirectionSet	g_ioport.p_api->portDirectionSet(IOPORT_PORT_00, direction_values, mask); Set the direction of one or more pins on a port.
portEventInputRead	g_ioport.p_api->portEventInputRead(IOPORT_PORT_00, &pin_levels); Read captured event (ELC) data for a port.
portEventOutputWrite	g_ioport.p_api->portEventOutputWrite(IOPORT_PORT_00, pin_levels, mask); Write event (ELC) output data for a port.
portRead	g_ioport.p_api->portRead(IOPORT_PORT_00, &pin_levels); Read states of pins on the specified port.
portWrite	g_ioport.p_api->portWrite(IOPORT_PORT_00, pin_levels, mask); Write to multiple pins on a port.
versionGet	g_ioport.p_api->versionGet(&version); Retrieve version information using the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	API Call Successful.
SSP_ERR_INVALID_ARGUMENT	The port/pin/mask/direction/level (and so forth) not valid.
SSP_ERR_ASSERTION	Unexpected null pointer.
SSP_ERR_UNSUPPORTED	Feature not supported – for instance Ethernet configuration not supported on the device.

Note

Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

I/O PORT HAL Module Operational Overview

The I/O Port HAL module provides the ability to access the I/O ports of a device at both bit and port level; both port and pin direction can be changed. In addition, a number of configuration APIs are provided to change the functionality of individual pins.

The I/O Port HAL module provides the following operations for configuring pins:

• Initializes the driver – performed by calling ioport_api_t::init API:
  • Performs parameter checking and processes error conditions.
  • Handles VBATT domain pin configuration.
  • Writes PFS registers for pins.
• Configures pin – performed by calling ioport_api_t::pinCfg API:
  • Performs parameter checking and processes error conditions (checks pin number pin, VBATT support).
  • Writes PFS register for the pin.
• Reads pin level – performed by calling ioport_api_t::pinRead API:
  • Performs parameter checking and processes error conditions (checks pin number pin).
  • Reads PFS register for the pin.
• Reads all pin levels on a port – performed by calling ioport_api_t::portRead API:
  • Performs parameter checking and processes error conditions (checks port number port).
  • Reads current value of PCNTR register value for the specified port.
• Writes pin level – performed by calling ioport_api_t::pinWrite API:
  • Performs parameter checking and processes error conditions (check pin number pin and written level level).
  • Write to PFS register for the pin.
• Write multiple pin levels on a port – performed by calling ioport_api_t::portWrite API:
  • Performs parameter checking and processes error conditions (checks port number port and pin mask mask).
  • Reads current configuration from the PCNTR register for the specified port.
  • Writes the pin levels to the PCNTR register for the specified port accordingly to the mask, preserving pin levels out of the scope.
• Sets the direction of multiple pins on a port – performed by calling ioport_api_t::portDirectionSet API:
  • Performs parameter checking and processes error conditions (checks port number port and pin mask mask).
  • Reads current configuration from the PCNTR register for the specified port.
  • Writes the pin levels to the PCNTR register for the specified port accordingly to the mask, preserving pin directions out of the scope.
• Writes pin direction – performed by calling ioport_api_t::pinDirectionSet API:
  • Performs parameter checking and processes error conditions (checks pin number pin and written direction direction).
  • Writes to the PFS register for the pin.
• Reads event (ELC) port input – performed by calling ioport_api_t::portEventInputRead API:
  • Performs parameter checking and processes error conditions (checks port number port).
  • Reads current value of the PCNTR register value for the specified port.
• Reads event (ELC) pin input – performed by calling ioport_api_t::pinEventInputRead API:
  • Performs parameter checking and processes error conditions (checks pin number pin).
  • Reads current value of the PCNTR register value for the specified pin's port.
  • Gets the pin level by applying a pin mask to the PCNTR register value.
• Writes event (ELC) port output – performed by calling the ioport_api_t::portEventOutputWrite API:
  • Performs parameter checking and processes error conditions (checks port number port and pin mask mask_value).
  • Reads current configuration from the PCNTR register for the specified port.
  • Writes the pin levels to the PCNTR register for the specified port accordingly to the mask preserving pin levels out of the event scope.
• Writes event (ELC) pin output – performed by calling ioport_api_t::pinEventOutputWrite API:
  • Performs parameter checking and processes error conditions (checks pin number pin and written level ioport_api_t::pinRead).
  • Writes the pin level to the PCNTR register for the specified pin's port accordingly to the mask that is preserving pin levels out of the event scope.
• Configures Ethernet channel PHY mode – performed by calling ioport_api_t::pinEthernetModeCfg API:
  • Performs parameter checking and processes error conditions (checks Ethernet channel channel and mode mode).
  • Updates the Ethernet Control Register (PFENET).

I/O PORT HAL Module Important Operational Notes and Limitations

I/O PORT HAL Module Operational Notes

• A bit mask of 16 bits needs to be applied in order to read and write to a specific pin on a port; ports are numbered from 0 (LSB) to 15 (MSB).
• Configuring the Ethernet port (selection of the RMII or MII output format) using the ioport_api_t::pinEthernetModeCfg API function on MCUs without an Ethernet Port will return an Unsupported Error message. To avoid this, the developer should verify the target MCU has an Ethernet port available. This information is easily found in the target MCU hardware user's manual. Simply verify that an Ethernet peripheral is available on the target MCU before beginning development.

I/O PORT HAL Module Limitations

• Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the I/O PORT HAL Module in an Application

This section describes how to include the I/O PORT HAL Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the I/O Port Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the I/O Port Driver is g_ioport0. This name can be changed in the associated Properties window.)

I/O PORT HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_ioport I/O Port driver on r_ioport	Threads	Highlight HAL/Common and select New> Driver> System> I/O Port Driver on r_ioport

When the I/O Port Driver on r_ioport is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

I/O PORT HAL Module Stack

Configuring the I/O PORT HAL Module

The I/O PORT HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the I/O PORT HAL Module on r_ioport

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter error checking.
Name	g_ioport	Module name.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

I/O PORT HAL Module Clock Configuration

The I/O PORT HAL module does not require a specific clock configuration.

I/O PORT HAL Module Pin Configuration

There are no pins associated directly with the I/O PORT HAL Module that require configuration.

Using the I/O PORT HAL Module in an Application

The typical steps in using the I/O PORT HAL module in an application are:

1. Initialize the driver using the ioport_api_t::init API.
2. Configure the pins using the ioport_api_t::pinCfg API.
3. Read from specified pins and ports using the ioport_api_t::pinRead and ioport_api_t::portRead APIs.
4. Write to specified pins and ports using the ioport_api_t::pinWrite and ioport_api_t::portWrite APIs.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical I/O PORT HAL Module Application