RA Flexible Software Package Documentation
Release v5.7.0
|
|
Functions | |
fsp_err_t | R_PTP_Open (ptp_ctrl_t *const p_ctrl, ptp_cfg_t const *const p_cfg) |
fsp_err_t | R_PTP_MacAddrSet (ptp_ctrl_t *const p_ctrl, uint8_t const *const p_mac_addr) |
fsp_err_t | R_PTP_IpAddrSet (ptp_ctrl_t *const p_ctrl, uint32_t ip_addr) |
fsp_err_t | R_PTP_LocalClockIdSet (ptp_ctrl_t *const p_ctrl, uint8_t const *const p_clock_id) |
fsp_err_t | R_PTP_MasterClockIdSet (ptp_ctrl_t *const p_ctrl, uint8_t const *const p_clock_id, uint16_t port_id) |
fsp_err_t | R_PTP_MessageFlagsSet (ptp_ctrl_t *const p_ctrl, ptp_message_type_t message_type, ptp_message_flags_t flags) |
fsp_err_t | R_PTP_CurrentUtcOffsetSet (ptp_ctrl_t *const p_ctrl, uint16_t offset) |
fsp_err_t | R_PTP_PortStateSet (ptp_ctrl_t *const p_ctrl, uint32_t state) |
fsp_err_t | R_PTP_MessageSend (ptp_ctrl_t *const p_ctrl, ptp_message_t const *const p_message, uint8_t const *const p_tlv_data, uint16_t tlv_data_size) |
fsp_err_t | R_PTP_LocalClockValueSet (ptp_ctrl_t *const p_ctrl, ptp_time_t const *const p_time) |
fsp_err_t | R_PTP_LocalClockValueGet (ptp_ctrl_t *const p_ctrl, ptp_time_t *const p_time) |
fsp_err_t | R_PTP_PulseTimerCommonConfig (ptp_ctrl_t *const p_ctrl, ptp_pulse_timer_common_cfg_t *const p_timer_cfg) |
fsp_err_t | R_PTP_PulseTimerEnable (ptp_ctrl_t *const p_ctrl, uint32_t channel, ptp_pulse_timer_cfg_t *const p_timer_cfg) |
fsp_err_t | R_PTP_PulseTimerDisable (ptp_ctrl_t *const p_ctrl, uint32_t channel) |
fsp_err_t | R_PTP_Close (ptp_ctrl_t *const p_ctrl) |
fsp_err_t | R_PTP_BestMasterClock (ptp_message_t const *const p_announce1, ptp_message_t const *const p_announce2, int8_t *const p_comparison) |
Driver for the PTP peripheral on RA MCUs. This module implements the PTP Interface.
PTP allows for multiple devices on a network to synchronize their clocks with very high precision. The PTP peripheral generates and processes PTP messages automatically. In slave mode, it also corrects the local time in order to adjust for any offset from the master clock time.
Configuration | Options | Default | Description |
---|---|---|---|
Parameter Checking |
| Default (BSP) | If selected code for parameter checking is included in the build. |
Configuration | Options | Default | Description |
---|---|---|---|
Clock Properties | |||
Priority 1 | Value must in the range [0,255]. | 128 | Priority1 field advertised in generated announce packets. |
Class | Value must in the range [0,255]. | 248 | Class field advertised in generated announce packets. |
Accuracy | Value must in the range [0,255]. | 0xFE | Accuracy field advertised in generated announce packets. |
Variance | Value must in the range [0,65535]. | 0xFFFF | Variance field advertised in generated announce packets. |
Priority 2 | Value must in the range [0,255]. | 128 | Priority2 field advertised in generated announce packets. |
Time Source | Value must in the range [0,255]. | 160 | Time Source field advertised in generated announce packets. |
Ethernet | |||
Multicast Filter MAC address | Must be a valid MAC address | 01:1B:19:00:00:00 | In Multicast Filtered mode, only multicast addresses that match this address are received by the ETHERC EDMAC. |
Primary Destination MAC address | Must be a valid MAC address | 01:1B:19:00:00:00 | The destination MAC address for primary PTP messages. |
PDelay Destination MAC address | Must be a valid MAC address | 01:80:C2:00:00:0E | The destination MAC address for PDelay messages. |
IP | |||
Primary Destination IP address | Must be a valid IP address | 224.0.1.129 | The destination IPv4 address for primary messages. |
PDelay Destination IP address | Must be a valid IP address | 224.0.0.107 | The destination IPv4 address for PDelay messages. |
Event Message TOS | Value must in the range [0,255]. | 0 | The IP packet TOS for event messages. |
General Message TOS | Value must in the range [0,255]. | 0 | The IP packet TOS for general messages. |
Primary Message TTL | Value must in the range [0,255]. | 1 | The IP packet TTL for primary messages. |
PDelay Message TTL | Value must in the range [0,255]. | 1 | The IP packet TTL for p_delay messages. |
Event Port | Value must in the range [0,65535]. | 319 | The UDP port for event messages. |
General Port | Value must in the range [0,65535]. | 320 | The UDP port for general messages. |
Synchronization Detection | |||
Threshold (Nanoseconds) | Value must be greater than 0. | 1000000 | The minimum offsetFromMaster value required in order to synchronize with the master clock. |
Count | Value must in the range [0,15]. | 5 | The number of times the calculated offsetFromMaster value must be less than the threshold in order to synchronize with the master clock. |
Synchronization Lost Detection | |||
Threshold (Nanoseconds) | Value must be greater than 0. | 10000000 | The minimum offsetFromMaster value required in order to lose synchronization with the master clock. |
Count | Value must in the range [0,15]. | 5 | The number of times the calculated offsetFromMaster value must be greater than the threshold in order to lose synchronization with the master. |
Interrupts | |||
Callback | Name must be a valid C symbol | ptp0_user_callback | Called when a STCA/SYNFP event occurs, a PTP message is received, or if a Pulse Timer event occurs. |
MINT Interrupt priority | MCU Specific Options | Select the EPTPC MINT interrupt priority. | |
Pulse Timer Interrupt priority | MCU Specific Options | Select the EPTPC IPLS priority. | |
Name | Name must be a valid C symbol | g_ptp0 | Module name. |
Ethernet PHY Interface Type |
| RMII | The interface type used to communicate with the Ethernet PHY. |
Frame Filter |
| Unicast | Selects how packets are filtered based on their destination MAC address. Packets that pass the filter are transferred to the ETHERC EDMAC. |
Frame Format |
| Ethernet II | The format of the frames that encapsulate the PTP messages. |
Clock Domain | Value must in the range [0,255]. | 0 | The PTP clock will only respond to clocks in its domain. |
Clock Domain Filter |
| Enable | Filter out PTP messages from other clock domains. |
Buffer Size | Value must in the range [64,1536]. | 1536 | The maximum Ethernet packet size that can be transmitted or received by the application from the EDMAC. |
Number of transmit buffers | Value must in the range [1,16]. | 4 | The number of transmit buffers in the packet queue. |
Number of receive buffers | Value must in the range [1,16]. | 4 | The number of receive buffers in the packet queue. |
Announce message interval. | MCU Specific Options | The period of time between generated announce messages. | |
Sync message interval. | MCU Specific Options | The period of time between generated sync messages. | |
Delay_req message interval. | MCU Specific Options | The period of time between generated delay_req messages. | |
Message timeout | Value must be greater than 0. | 4000 | The time in milliseconds needed to generate timeout events after not receiving a sync or delay_resp message. |
Clock Source |
| PCLKA / 6 | The STCA clock source must be 20Mhz, 25Mhz, 50Mhz, or 100Mhz. When REF50CK0 is selected, the STCA frequency is 25Mhz. |
Clock Correction Mode |
| Clock Correction Mode 1 | Clock correction mode 1 corrects the local clock using the current offsetFromMaster value. Clock correction mode 2 calculates a clock gradient in order to continuously correct the local clock. |
Gradient Worst10 Interval | Value must in the range [0,255]. | 32 | The number of sync messages to use when calculating the worst10 gradient values (Only applies to clock correction mode 2). |
The STCA input clock can be the following clock sources:
The STCA input clock is restricted to the following frequencies:
When REF50CK0 is selected, the input clock frequency is 25 Mhz.
The PTP module requires the Ethernet (r_ether) instance in order to initialize the Ethernet PHY. This means that the ETHERC pins must be configured.
The current PTP port state determines which messages need to be generated and processed by the PTP peripheral. It is the application's responsibility to determine what the current state of the PTP port should be.
The following messages can be generated by the PTP peripheral:
The following messages can be processed by the PTP peripheral:
The application must receive the following messages in order to determine the current state of its PTP port:
The following messages can only be sent manually:
The PTP API defines the following states:
State | Generated Messages | Processed Messages | Received Messages |
---|---|---|---|
Disabled | N/A | N/A | N/A |
Passive | N/A | N/A | Announce, Signaling, Management |
E2E/P2P Slave | Delay_req/(PDelay_req, PDelay_resp) | Sync, Follow_up, Delay_resp/(PDelay_req, PDelay_resp) | Announce, Signaling, Management |
E2E/P2P Master | Announce, Sync, Delay_resp/(PDelay_req, PDelay_resp) | delay_req/(PDelay_req, PDelay_resp) | Announce, Signaling, Management |
Pulse Timers are configurable timers used to generate interrupts and ELC events. Each pulse timer has a configurable start time, pulse, and period. At the start of each timer period, a rising edge occurs. After the pulse time has elapsed, a falling edge occurs. ELC events and IRQs can be generated on rising and/or falling edges for each Pulse Timer. There are two types of interrupts generated by each Pulse Timer; MINT and IPLS.
Pulse timers may be configured to generate the following ELC events:
MINT IRQs are only generated on the rising edge of a Pulse Timer channel. The callback will provide the channel number of the pulse timer that caused the interrupt.
Each Pulse Timer channel can be configured as a source for generating IPLS IRQs. All of the pulse timers that are selected as IPLS sources are OR'd together and rising and falling edge IRQs can be generated from the resulting signal. Below is an example of a resulting signal from two IPLS sources. Unlike MINT interrupts, IPLS interrupts do not provide any information about which Pulse Timer caused the IRQ because the IRQs from all the Pulse Timers are OR'd together.
The PTP driver can filter Ethernet frames that are received by Ethernet (r_ether). There are four different filtering modes:
Developers should be aware of the following limitations when using the PTP:
This is a basic example of minimal use of PTP in slave mode.
This is a basic example of minimal use of PTP in master mode.
This is a basic example of how to send PTP messages.
Data Structures | |
struct | ptp_instance_ctrl_t |
struct ptp_instance_ctrl_t |
PTP instance control block.
Data Fields | ||
---|---|---|
uint32_t | open | Marks if the instance has been opened. |
uint32_t | tx_buffer_write_index | Index into the descriptor list to write the next packet. |
uint32_t | tx_buffer_complete_index | Index into the descriptor list of the last transmitted packet. |
uint32_t | rx_buffer_index | Index into the descriptor of the last received packet. |
uint32_t | tslatr | Keep track of whether tslatr was set. |
ptp_cfg_t const * | p_cfg | Pointer to the configuration structure. |
This function initializes PTP. Implements ptp_api_t::open.
This function performs the following tasks:
FSP_SUCCESS | The instance has been successfully configured. |
FSP_ERR_ALREADY_OPEN | Instance was already initialized. |
FSP_ERR_NOT_OPEN | The EDMAC instance was not opened correctly. |
FSP_ERR_ASSERTION | An invalid argument was given in the configuration structure. |
fsp_err_t R_PTP_MacAddrSet | ( | ptp_ctrl_t *const | p_ctrl, |
uint8_t const *const | p_mac_addr | ||
) |
This function sets the MAC address for the PTP instance. Implements ptp_api_t::macAddrSet.
FSP_SUCCESS | The MAC address has been set. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL |
FSP_ERR_INVALID_MODE | The instance is not in the correct state. |
fsp_err_t R_PTP_IpAddrSet | ( | ptp_ctrl_t *const | p_ctrl, |
uint32_t | ip_addr | ||
) |
This function sets the IP address for the PTP instance. Implements ptp_api_t::ipAddrSet.
FSP_SUCCESS | The IP address has been set. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL. |
FSP_ERR_INVALID_MODE | The configured ptp_synfp_cfg_t::frame_format is not configured to use IP packets, or the instance is not in the correct state. |
fsp_err_t R_PTP_LocalClockIdSet | ( | ptp_ctrl_t *const | p_ctrl, |
uint8_t const *const | p_clock_id | ||
) |
This function sets the local clock ID for the PTP instance. Implements ptp_api_t::localClockIdSet.
FSP_SUCCESS | The local clock ID has been set. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL |
FSP_ERR_INVALID_MODE | The instance is not in the correct state. |
fsp_err_t R_PTP_MasterClockIdSet | ( | ptp_ctrl_t *const | p_ctrl, |
uint8_t const *const | p_clock_id, | ||
uint16_t | port_id | ||
) |
This function sets the master clock ID and port ID that the local clock will synchronize with. Implements ptp_api_t::masterClockIdSet.
FSP_SUCCESS | The master clock ID and port ID have been set. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL |
fsp_err_t R_PTP_MessageFlagsSet | ( | ptp_ctrl_t *const | p_ctrl, |
ptp_message_type_t | message_type, | ||
ptp_message_flags_t | flags | ||
) |
This function sets the flags field for the given message type. Implements ptp_api_t::messageFlagsSet.
FSP_SUCCESS | The master clock ID and port ID have been set. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL or invalid. |
fsp_err_t R_PTP_CurrentUtcOffsetSet | ( | ptp_ctrl_t *const | p_ctrl, |
uint16_t | offset | ||
) |
This function sets the currentUtcOffset value in announce messages. ptp_api_t::currentUtcOffsetSet.
FSP_SUCCESS | The currentUtcOffset has been updated. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL or invalid. |
fsp_err_t R_PTP_PortStateSet | ( | ptp_ctrl_t *const | p_ctrl, |
uint32_t | state | ||
) |
This function changes the current state of the PTP instance. Implements ptp_api_t::portStateSet.
FSP_SUCCESS | The instance will transition to the new state. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL |
fsp_err_t R_PTP_MessageSend | ( | ptp_ctrl_t *const | p_ctrl, |
ptp_message_t const *const | p_message, | ||
uint8_t const *const | p_tlv_data, | ||
uint16_t | tlv_data_size | ||
) |
This function sends a PTP message. ptp_api_t::messageSend.
FSP_SUCCESS | The packet has been written to the transmit descriptor. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL or invalid. |
FSP_ERR_ETHER_ERROR_TRANSMIT_BUFFER_FULL | There is no space for the packet in the transmit queue. |
fsp_err_t R_PTP_LocalClockValueSet | ( | ptp_ctrl_t *const | p_ctrl, |
ptp_time_t const *const | p_time | ||
) |
This function sets the local clock value. Implements ptp_api_t::localClockValueSet.
FSP_SUCCESS | The local clock value has been set. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL or invalid. |
fsp_err_t R_PTP_LocalClockValueGet | ( | ptp_ctrl_t *const | p_ctrl, |
ptp_time_t *const | p_time | ||
) |
This function gets the local clock value. Implements ptp_api_t::localClockValueGet.
FSP_SUCCESS | The local clock value has been written in p_time. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL |
fsp_err_t R_PTP_PulseTimerCommonConfig | ( | ptp_ctrl_t *const | p_ctrl, |
ptp_pulse_timer_common_cfg_t *const | p_timer_cfg | ||
) |
This function configures IPLS IRQ settings that are common to all pulse timer channels. Implements ptp_api_t::pulseTimerCommonConfig.
FSP_SUCCESS | The pulse timer has been enabled. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL or invalid. |
fsp_err_t R_PTP_PulseTimerEnable | ( | ptp_ctrl_t *const | p_ctrl, |
uint32_t | channel, | ||
ptp_pulse_timer_cfg_t *const | p_timer_cfg | ||
) |
This function enables a pulse timer channel. Implements ptp_api_t::pulseTimerEnable.
FSP_SUCCESS | The pulse timer has been enabled. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL or invalid. |
FSP_ERR_INVALID_ARGUMENT | The start time must be set to a value that is later than current time. |
fsp_err_t R_PTP_PulseTimerDisable | ( | ptp_ctrl_t *const | p_ctrl, |
uint32_t | channel | ||
) |
This function disables a pulse timer channel. Implements ptp_api_t::pulseTimerDisable.
FSP_SUCCESS | The pulse timer has been disabled. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL or invalid. |
fsp_err_t R_PTP_Close | ( | ptp_ctrl_t *const | p_ctrl | ) |
Disable the PTP instance. Implements ptp_api_t::close.
FSP_SUCCESS | The pulse timer has been disabled. |
FSP_ERR_NOT_OPEN | The instance has not been opened. |
FSP_ERR_ASSERTION | An argument was NULL or invalid. |
fsp_err_t R_PTP_BestMasterClock | ( | ptp_message_t const *const | p_announce1, |
ptp_message_t const *const | p_announce2, | ||
int8_t *const | p_comparison | ||
) |
This function compares two clocks to determine which one is the better master clock.
p_comparison:
FSP_SUCCESS | The valid result has been written to p_use_announce_clock. |
FSP_ERR_ASSERTION | An argument was NULL. |