Synergy Software Package User's Manual
PTPEDMAC Driver on r_ptpedmac

Table of Contents

PTPEDMAC HAL Module Introduction

The PTPEDMAC HAL Module provides high-level APIs for message transmission using a DMA controller for EPTPC peripheral in synergy MCU. A user callback can be created to indicate the occurrence of frame receive complete event, frame transmit complete event, or error event.

PTPEDMAC HAL Module Features

The PTPEDMAC HAL module configures PTPEDMAC for data transmission and reception of PTP messages.

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

  • Link the PTP host interface to transmit and receive PTP messages.
  • Check the communication status.
  • Read PTP messages.
PTPEDMAC_BD.png
PTPEDMAC HAL Module Block Diagram

PTPEDMAC Hardware Support Details

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

Legend:

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

 

MCU Group Linking PTP host Interface Read PTP message
S124 N/A N/A
S128 N/A N/A
S1JA N/A N/A
S3A1 N/A N/A
S3A3 N/A N/A
S3A6 N/A N/A
S3A7 N/A N/A
S5D3 N/A N/A
S5D5 N/A N/A
S5D9 ✓ ✓
S7G2 ✓ ✓

PTPEDMAC HAL Module APIs Overview

The PTPEDMAC module interface defines APIs for key features such as opening, closing, reading, linking host interface. 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.

PTPEDMAC HAL Module API Summary

PTPEDMAC API functions

Function Name Example API Call and Description
open g_ptpedmac.p_api->open(g_ptpedmac.p_ctrl, g_ptpedmac.p_cfg);
Open the PTPEDMAC driver module for reception of PTP messages.
close g_ptpedmac.p_api->close(g_ptpedmac.p_ctrl);
Close the PTPEMAC module.
linkProcess g_ptpedmac.p_api->linkProcess(g_ptpedmac.p_ctrl);
Sets host interface to transfer PTP messages
linkCheck g_ptpedmac.p_api->linkCheck(g_ptpedmac.p_ctrl);
Checks host interface communication status
read g_ptpedmac.p_api->read(g_ptpedmac.p_ctrl, &read_ch, P_BUF, &num_recvd);
Receives PTP message.
versionGet g_ptpedmac.p_api ->versionGet (&ptpedmac_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.
PTPEDMAC open API should be called after PTP open API call is successful.

PTPEDMAC HAL Module Status Return Values

Name Description
SSP_SUCCESS API Call Successful.
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_NOT_ENABLED PTP host interface is not enabled.
SSP_ERR_TIMEOUT Timeout error.
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.

PTPEDMAC HAL Module Operational Overview

The PTPEDMAC HAL module provides DMA controller for message transmission and reception for the on-chip Ethernet PTP Controller (EPTPC) on a Synergy microcontroller, as configured by the user. It provides convenient API functions to simplify development.

PTPEDMAC HAL Module Important Operational Notes and Limitations

PTPEDMAC HAL Module Operational Notes

The PTPEDMAC controls data transmission and reception based on EPTPC configuration.

The PTPEDMAC transfers data according to the information written in the descriptor. A descriptor includes the buffer size, address, and transmit or receive status.

The user callback must be registered to indicate PTPEDMAC communication status. If the user callback is registered then the PTPEDMAC driver will invoke the callback (ptpedmac_cfg_t::p_callback) with argument ptpedmac_callback_args_t, indicating the event ptpedmac_event_t.

PTPEDMAC supports the following interrupts:

1. Frame receive complete event - this event occurs when PTP message frame is received successfully

  1. Frame transmit complete event - this event occurs when the PTP message frame is transmitted successfully
  2. Error event - this event occurs when an error occurs during the transfer of PTP message

PTPEDMAC HAL Module Limitations

PTPEDMAC write functionality is not supported as EPTPC hardware automatically handles analysis and transmission of PTP messages for time synchronization. 

Including the PTPEDMAC HAL Module in an Application

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

PTPEDMAC HAL driver is used as a lower-level module for PTP driver and is not available to add as a separate stack. PTPEDMAC is added as a lower-level module for PTP driver automatically. 

PTPEDMAC_MS.png
PTPEDMAC HAL Module Stack

When the PTPEDMAC Driver on r_ptpedmac 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.

Configuring the PTPEDMAC HAL Module

The PTPEDMAC 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 PTPEDMAC HAL Module on r_ptpedmac

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Selects if code for parameter checking is to be included in the build.
Number of RX descriptors Range: 1 to 8
Default: 1 		Number of receive buffer descriptors selection.
PTPEDMAC buffer size Range: 64 to 1536
Default: 1536 		Buffer size.
Name g_ptpedmac0 Module name.
Callback Default: NULL PINT interrupt callback selection.
PINT interrupt priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)
Default: Priority 12 		Select the PINT interrupt priority.

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.

PTPEDMAC HAL Module Clock Configuration

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

PTPEDMAC HAL Module Pin Configuration

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

Using the PTPEDMAC HAL Module in an Application

Note
PTPEDMAC APIs are to be used along with PTP APIs for message transmission and reception.
User shall call ptpedmac_api_t::open API only after ptp_api_t::open API call is successful.

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

  1. Initialize the PTP HAL module using ptp_api_t::open API.
  2. Initialize the PTPEDMAC module using ptpedmac_api_t::open API.
  3. Configure the PTP module with IP and MAC address using ptp_api_t::configure API.
  4. Link PTPEDMAC to receive and transfer  PTP message transfer using the ptpedmac_api_t::linkProcess API.
  5. Start time synchronization using the ptp_api_t::start API.
  6. Receive PTP message using ptpedmac_api_t::read API through ptpedmac_cfg_t::p_callback.

 

PTPEDMAC_TA.png
Flow Diagram of a PTPEDMAC HAL Module Application