PTP Driver on r_ptp

Table of Contents

• Precision Time Protocol HAL Module Introduction
  • Precision Time Protocol HAL Module Features
  • Precision Time Protocol Hardware Support Details
• Precision Time Protocol HAL Module APIs Overview
• Precision Time Protocol HAL Module Operational Overview
  • Precision Time Protocol HAL Module Important Operational Notes and Limitations
    • Precision Time Protocol HAL Module Operational Notes
    • Precision Time Protocol HAL Module Limitations
• Including the Precision Time Protocol HAL Module in an Application
• Configuring the Precision Time Protocol HAL Module
  • Precision Time Protocol HAL Module Clock Configuration
  • Precision Time Protocol HAL Module Pin Configuration
• Using the Precision Time Protocol HAL Module in an Application

Precision Time Protocol HAL Module Introduction

The PTP HAL Module provides high-level APIs for the time synchronization using the PTP function of the EPTPC peripheral module (EPTPC) on the synergy MCU. A user callback can be created to indicate the occurrence of pulse output timer event or the state change of  Synchronous Frame Processing units(SYNFP0 and SYNFP1), Statistical Time Correction Algorithm(STCA), or Packet Relation Controller unit(PRC-TC).

Precision Time Protocol HAL Module Features

The PTP HAL module configures the PTP for time synchronization functionality.

The PTP HAL allows the user to perform the following operations:

• Set and get local clock counter value.
• Set and get master port ID.
• Set and get PTP message reception configuration.
• Update PTP message information.
• Get offset from master and mean path delay values.
• Collecting gradient differences and extracting the worst ten values by hardware and software.
• Set start time, period, and pulse width of pulse output timer.
• Indicate and auto-clear pulse output event signals to the ELC.
• Enable and disable INFABT status notification.

PTP HAL Module Block Diagram

Precision Time Protocol Hardware Support Details

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

Legend:

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

MCU Group	Ordinary clock	Boundary clock	Transparent clock	E2E delay mechanism	P2P delay mechanism	Pulse output timer operation
S124	N/A	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A	N/A
S3A1	N/A	N/A	N/A	N/A	N/A	N/A
S3A3	N/A	N/A	N/A	N/A	N/A	N/A
S3A6	N/A	N/A	N/A	N/A	N/A	N/A
S3A7	N/A	N/A	N/A	N/A	N/A	N/A
S5D3	N/A	N/A	N/A	N/A	N/A	N/A
S5D5	N/A	N/A	N/A	N/A	N/A	N/A
S5D9	✓	N/A	N/A	✓	✓	✓
S7G2	✓	✓	✓	✓	✓	✓

Precision Time Protocol HAL Module APIs Overview

The PTP HAL module interface defines APIs for key features such as initializing, starting, stopping, getting and setting of synchronous information, setting start time for pulse output timer, setting ELC event indication, and updating PTP message flags. 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.

PTP HAL Module API Summary

PTP API functions

Function Name	Example API Call and Description
open	g_ptp.p_api->open(g_ptp.p_ctrl, g_ptp.p_cfg); Open the PTP driver module.
close	g_ptp.p_api->close(g_ptp.p_ctrl); Close the PTP driver module.
configure	g_ptp.p_api->configure(g_ptp.p_ctrl, ip_address, physical_address_msw, physical_address_lsw); Configures the PTP driver module.
setExtPromiscuous	g_ptp.p_api->setExtPromiscuous(g_ptp.p_ctrl, 1, false); Sets or clears the extended promiscuous mode
setLocalClock	g_ptp.p_api->setLocalClock(g_ptp.p_ctrl, &lc_clk); Sets local clock counter
getLocalClock	g_ptp.p_api->getLocalClock(g_ptp.p_ctrl, &lc_clk, 20); Gets local clock counter.
getMasterPortID	g_ptp.p_api->getMasterPortID(g_ptp.p_ctrl, 1, curClkId, &curPortId); Gets master port ID.
setMasterPortID	g_ptp.p_api->setMasterPortID(g_ptp.p_ctrl, 1, curClkId, &curPortId); Sets master port ID.
getSyncInfo	g_ptp.p_api->getSyncInfo(g_ptp.p_ctrl, 1, &master_offset, &path_delay); Get current offsetFromMaster and meanPathDelay.
start	g_ptp.p_api->start(g_ptp.p_ctrl, 100); Starts the time synchronization.
stop	g_ptp.p_api->stop(g_ptp.p_ctrl, 100); Stops the time synchronization.
checkWorst10Values	g_ptp.p_api->checkWorst10Values(g_ptp.p_ctrl, 40000); Checks worst 10 values acquired by hardware and set as gradient limits.
setWorst10Values	g_ptp.p_api->setWorst10Values(g_ptp.p_ctrl, 32); Sets the time interval for collecting worst 10 values.
getWorst10Values	g_ptp.p_api->getWorst10Values(g_ptp.p_ctrl, p_lim, m_lim, 40000); Gets the worst 10 values acquired by software.
setGradientLimit	g_ptp.p_api->setGradientLimit(g_ptp.p_ctrl, p_lim, m_lim); Sets the gradient limits for positive and negative worst 10 values.
updateClockID	g_ptp.p_api->updateClockID(g_ptp.p_ctrl, 1, clock_id); Updates clock identity field.
updateDomainNumber	g_ptp.p_api->updateDomainNumber(g_ptp.p_ctrl, 1, domain_num); Updates domain number field in the message header.
updateAnnounceFlags	g_ptp.p_api->updateAnnounceFlags(g_ptp.p_ctrl, 1, &p_flag); Updates announce message's flag field.
updateAnnounceMsgs	g_ptp.p_api->updateAnnounceMsgs(g_ptp.p_ctrl, 1, &p_message); Updates announce message's message field.
updateSyncAnnounceMsgInterval	g_ptp.p_api->updateSyncAnnounceMsgInterval(g_ptp.p_ctrl, 1, &p_sync_interval, &p_ance_interval); Updates transmission interval and logMessageInterval of Sync and Announce messages.
updateDelayMsgInterval	g_ptp.p_api->updateDelayMsgInterval(g_ptp.p_ctrl, 1, &p_interval, &p_timeout); Updates transmission interval, logMessageInterval and timeout values of Delay message.
getMessageReceptionConfig	g_ptp.p_api->getMessageReceptionConfig(g_ptp.p_ctrl, 1, &p_ptp_message_reception); Gets PTP message reception synchronous configuration.
setMessageReceptionConfig	g_ptp.p_api->setMessageReceptionConfig(g_ptp.p_ctrl, PTP_TEST_CHANNEL, &p_ptp_message_reception); Sets PTP message reception synchronous configuration.
disableTimer	g_ptp.p_api->disableTimer(g_ptp.p_ctrl, PTP_STCA_TIMER_CHANNEL_0));Disables the specified timer event interrupt.
indicateEvent	g_ptp.p_api->indicateEvent(g_ptp.p_ctrl, cyc_ch, PTP_STCA_TIMER_PULSE_EDGE_RISING, true); Sets or clears ELC interrupt indication.
autoClearEvent	g_ptp.p_api->autoClearEvent(g_ptp.p_ctrl, cyc_ch, PTP_STCA_TIMER_PULSE_EDGE_RISING, true); Sets or clears ELC interrupt auto clear mode.
setTimer	g_ptp.p_api->setTimer(g_ptp.p_ctrl, 0U, start_time, 200000, 100000);Sets start time, pulse period and pulse width for the pulse output timer.
setMINTevent	g_ptp.p_api->setMINTevent(g_ptp.p_ctrl, PTP_EVENT_STCA, 0x03, false);Sets EPTPC MINT interrupt event.
enableINFABTnotification	g_ptp.p_api->enableINFABTnotification(g_ptp.p_ctrl, 1); Enables EPTPC INFABT notification of the specified PTP channel.
disableINFABTnotification	g_ptp.p_api->disableINFABTnotification(g_ptp.p_ctrl, 1);  Disables EPTPC INFABT notification of the specified PTP channel.
checkINFABTstatus	g_ptp.p_api->checkINFABTstatus(g_ptp.p_ctrl, &status); Checks the status of INFABT flag of the specified PTP channel.
clearINFABTstatus	g_ptp.p_api->clearINFABTstatus(g_ptp.p_ctrl, 1); Clears INFABT interrupt occurrence flag of the specified PTP channel.
versionGet	g_ptp.p_api->versionGet(&ptp_version); Get the driver version based on compile time macros.

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.

While calling configure API, make sure that IP address and MAC address are assigned to respective index when using ordinary clock 0 and ordinary clock 1.

 checkWorst10Values API should be called only when STCA synchronous mode is set to Mode 2 - Gradient collection by hardware in the configurator. 

getWorst10Values and setGradientLimit  APIs should be called only when STCA synchronous mode is set to Mode 2 - Gradient collection by software in the configurator. 

linkProcess API should be called after configure API and ensure that there is no delay between the API calls.

While calling setTimer API, user needs to pass half the required pulse output period and pulse high width.

PTP HAL Module Status Return Values

Name	Description
SSP_SUCCESS	API Call Successful.
SSP_ERR_INVALID_CHANNEL	Attempt to use invalid PTP channel
SSP_ERR_NOT_OPEN	Unit is not open.
SSP_ERR_ASSERTION	An input pointer is NULL.
SSP_ERR_IRQ_BSP_DISABLED	A required interrupt does not exist in the vector table.
SSP_ERR_TIMEOUT	Timeout error.
SSP_ERR_INVALID_MODE	Attempt to use unsupported or incorrect mode.
SSP_ERR_IN_USE	Unit is already opened.

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.

Precision Time Protocol HAL Module Operational Overview

The PTP driver on r_ptp HAL module controls the on-chip Precision Time Protocol (PTP) module for the Ethernet Controller (EPTPC) on a Synergy microcontroller, as configured by the user. It directly controls the EPTPC hardware without using any RTOS elements. It provides convenient API functions to simplify development.

Precision Time Protocol HAL Module Important Operational Notes and Limitations

Precision Time Protocol HAL Module Operational Notes

PTP HAL module can be used for the synchronization of clocks.

Clock state

• Master: EPTPC peripheral sends announce and sync message to slave devices which contain local clock time in UNIX Timestamp format
• Slave: EPTPC peripheral receives and corrects the local time in accordance to master clock time.

Clock mode

• Ordinary clock: PTP messages are transmitted and received through one Ethernet port in operation as an ordinary clock. An ordinary clock operates as either master or slave. 
• Boundary clock: PTP messages are transmitted and received through both ports in operation as a boundary clock. One port operates as a slave in synchronization with the master and the other operates as the master that delivers time information synchronized with the master clock. Both ports can also operate as masters.
• Transparent clock: A transparent clock does not act as a master or slave, instead relays PTP messages from the master to the slave.

Delay correction mechanism

• E2E delay correction mechanism: It involves message exchange between master and slave. The slave sends a delay request to the master, which in turn responds with a delay response back to the requested slave.
• P2P delay correction mechanism: This mechanism uses a port-based peer delay message mechanism. Each port on a PTP device sends peer delay request messages to the port it is directly connected to. The connected port then responds with a peer delay response message.

Statistical time correction algorithm (STCA): When configured as a slave, the synchronized state can be identified by the offset from master value staying below a threshold specified in advance or calculated statistically from collected positive and negative gradient values by hardware or software (worst-10 acquisition). 

STCA clock can be used as the clock source for generating pulse signals from pulse output timer m (m = 0 to 5). PCLKA is used as a source clock at a frequency of 20 MHz.

The generated pulse signals can be linked through event link (ELC) to get triggered when a rising or falling edge is detected.

Interrupts and callback: The user callback must be registered to handle pulse output timer event or state change of SYNFP0, SYNFP1, STCA or PRC-TC. If the user callback is registered then the PTP driver will invoke the callback (ptp_cfg_t::p_callback) with argument ptp_callback_args_t, indicating the event ptp_event_t.

PTPEDMAC supports the following interrupts:

1. Rising edge detected on the periodic pulse signal from pulse output timer 
2. Change in state of SYNFP0
3. Change in state of SYNFP1
4. Change in state of STCA
5. Change in state of PRC-TC

Initialization: Ethernet initialization should be done and Ethernet link should be up before calling PTP APIs.

Precision Time Protocol HAL Module Limitations

PTP HAL module limitations:

1. PTP HAL module does not support the setting of inter-port transfer mode for standard ethernet frames.
2. PTP HAL module does not support the setting of multicast frame filter for standard ethernet frames.

EPTPC hardware limitations:

1. PTP message frames are not supported over IPv6 format.

Including the Precision Time Protocol HAL Module in an Application

This section describes how to include the PTP 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.

PTP HAL driver is used as a lower level module for Ethernet and is not available to add as a separate stack. It is available as optional driver under sf_el_nx. PTPEDMAC is added as a lower level module for PTP automatically. An example is illustrated in the following figure where a module must be selected to Add PTP Driver. The following figure shows the selection of the PTP driver to complete the stack for the module.

PTP HAL Module Stack 1

When the PTP Driver on r_ptp 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.

PTP HAL Module Stack 2

Configuring the Precision Time Protocol HAL Module

The PTP 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 PTP HAL Module on r_ptp

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Selects if code for parameter checking is to be included in the build.
Name	g_ptp	Module name.
Clock mode	Ordinary clock 0, Ordinary clock 1, Boundary clock, Transparent clock Default: Ordinary clock 0	PTP clock mode selection.
STCA synchronous mode	Mode 1- No gradient collection, Mode 2- Gradient collection by hardware, Mode 2- Gradient collection by software Default: Mode 2- Gradient collection by hardware	STCA synchronous mode selection.
MINT callback	Default: NULL	PTP MINT interrupt callback selection.
MINT interrupt priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Select the MINT interrupt priority.
Clock state	Slave, Master Default: Slave	PTP clock state selection.
Delay correction mechanism	E2E (End to end), P2P (Peer to peer) Default: End to end delay correction mechanism	Delay correction mechanism selection.
Frame format	Ethernet II, Ethernet 802.3, Ethernet II over UDP4, Ethernet 802.3 over UDP4 Default: Ethernet II	PTP message frame format selection.

Note

While using ordinary clock mode, make sure the Ethernet channel selected for sf_el_nx and r_ptp are the same.

Other MCUs may have different default values and available configuration settings.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group.

Precision Time Protocol HAL Module Clock Configuration

No specific clock configurations are required for the PTP HAL Module.

Precision Time Protocol HAL Module Pin Configuration

No specific pin configurations are required for the PTP HAL Module.

Using the Precision Time Protocol HAL Module in an Application

Note

User shall proceed with time synchronization operations only after Ethernet is initialized, link is up and PTP is configured with IP and MAC address.  

The typical steps in using the PTP HAL module in an application are:

PTP master application:

1. Initialize the PTP HAL module using ptp_api_t::open, ptp_api_t::configure, ptpedmac_api_t::open APIs.

2. Set PTP host interface for PTP message transfer using the ptpedmac_api_t::linkProcess API.

3. Set the local clock value using the ptp_api_t::setLocalClock API.

4. Start time synchronization using the ptp_api_t::start API.

5. Stop synchronization using the ptp_api_t::stop API.

6. Use the ptp_api_t::close call to close the peripheral.

Flow Diagram of a PTP HAL Module Application as master

PTP slave application:

1. Initialize the PTP HAL module using ptp_api_t::open, ptp_api_t::configure, ptpedmac_api_t::open APIs.
2. Set the interval for getting worst 10 values using the ptp_api_t::setWorst10Values API.
3. Set PTP host interface for PTP message transfer using the ptpedmac_api_t::linkProcess API.
4. Wait till PINT interrupt occurs. Receive PTP message using ptpedmac_api_t::read API through ptpedmac_cfg_t::p_callback.
5. Start time synchronization using the ptp_api_t::start API.
6. Get worst 10 value acquired by software or hardware using ptp_api_t::getWorst10Values or ptp_api_t::checkWorst10Values and set as gradient limit.
7. Get local clock counter value using the ptp_api_t::getLocalClock API.
8. Get master offset and path delay using ptp_api_t::getSyncInfo API.
9. Stop time synchronization using the ptp_api_t::stop API.
10. Use the ptp_api_t::close call to close the peripheral.

Flow Diagram of a PTP HAL Module Application as slave

Application for setting pulse output timer:

1. Configure PTP clock state as master and register a callback function for MINT ISR.
2. Initialize the PTP HAL module using ptp_api_t::open, ptp_api_t::configure APIs.
3. Configure PTP module to indicate and auto-clear event using ptp_api_t::indicateEvent, ptp_api_t::autoClearEvent APIs.
4. Set the start time, period, and pulse width for pulse output timer using ptp_api_t::setTimer API
5. Set the local clock value using the ptp_api_t::setLocalClock API.
6. Start time synchronization using the ptp_api_t::start API.
7. Wait till the MINT timer event occurs. Start counting by pulse output timer through ptp_cfg_t::p_callback.
8. Stop synchronization using the ptp_api_t::stop API.
9. Use the ptp_api_t::close call to close the peripheral.

Flow Diagram of a PTP HAL Module Application for setting pulse output timer

Note

As per hardware user manual, time synchronization will not start immediately after starting the PTP module by calling start API. It might take about 3 seconds to get synchronized.