AM261x MCU+ SDK: Functions

| AM261x MCU+ SDK 26.00.00 |

Files | Data Structures | Functions | Typedefs | Enumerations | Macros
Functions
APIs for TSN GPTP

## Introduction

## Files
file | gptpbasetypes.h
| File contains base datatypes used, as per IEEE 802.1AS Standard Documentation.
file | gptpmasterclock.h
| file contains gptp master clock related functions.

## Data Structures
struct | PortIdentity
| The portIdentity identifies a port of a time-aware system. More...
struct | ClockQuality
| The clock quality represents quality of clock. More...
struct | UInteger48
| 48bit variable, lsb is 32 bits More...
struct | UInteger48m32
| 48bit variable, msb is 32 bits More...
struct | UInteger112
| UInteger112 (802.1AS, 10.3.2 systemIdentity) More...
struct | UInteger224
| UInteger224 (802.1AS, 10.3.4 time-synchronization spanning tree priority vectors ) More...
struct | ScaledNs
| The ScaledNs type represents signed values of time and time interval in units of 2e-16 ns. More...
struct | UScaledNs
| The ScaledNs type represents unsigned values of time and time interval in units of 2^-16 ns. More...
struct | TimeInterval
struct | Timestamp
| The Timestamp type represents a positive time with respect to the epoch. More...
struct | ExtendedTimestamp
| The ExtendTimestamp type represents a positive time with respect to the epoch. The fractionalNanoseconds member is the fractional portion of the timestamp in units of 2^16 ns. More...

## Functions
int | gptpmasterclock_init (const char *shmem_name)
| initialize to get gptp clock from tsn_gptp daemon. if previously initialized, it will simply return 0. More...
int | gptpmasterclock_close (void)
| close gptpmasterclcock More...
int | gptpmasterclock_gm_domainIndex (void)
| return the domainIndex which is currently used as systeme wide gptp clock. More...
int64_t | gptpmasterclock_getts64 (void)
| get 64-bit nsec unit ts of system wide gptp clock More...
int | gptpmasterclock_wait_until_ts64 (int64_t tts, int64_t vclose, int64_t toofar)
| Wait until tts comes. More...
uint64_t | gptpmasterclock_expand_timestamp (uint32_t timestamp)
| expand 32-bit nsec time to 64 bit with aligning to gptp clock. More...
uint64_t | gptpmasterclock_expand_timestamp_ts64 (uint32_t timestamp, int64_t ts64)
| expand 32-bit nsec time to 64 bit with aligning to gptp clock at the time `ts64`. More...
int | gptpmasterclock_gmchange_ind (void)
| get GM change indicator, the number is incremented whenever GM is changed More...
int | gptpmasterclock_get_max_domains (void)
| get maximum number of domains More...
int | gptpmasterclock_get_domain_ts64 (int64_t *ts64, int domainIndex)
| get a synchronized clock value on specific domain More...
void | gptpmasterclock_dump_offset (void)
| print phase offset for all domains More...

## Typedefs
typedef uint8_t | ClockIdentity[CLOCK_IDENTITY_LENGTH]
typedef uint8_t | Nibble
| Primitive data types specifications for IEEE 802.1AS. All non-primitive data types are derived from the primitive types, signed integers are represented as two's complement form. More...
typedef uint8_t | Octet
typedef uint8_t | Octet2[2]
typedef uint8_t | Octet3[3]
typedef uint8_t | Octet4[4]
typedef uint8_t | Enumeration2
typedef uint8_t | Enumeration4
typedef uint8_t | Enumeration8
typedef uint16_t | Enumeration16
typedef uint32_t | Enumeration24
typedef uint8_t | UInteger4

## Enumerations
enum | TimeSource { ATOMIC_CLOCK = 0x10, GPS = 0x20, TERRESTRIAL_RADIO = 0x30, PTP = 0x40, NTP = 0x50, HAND_SET = 0x60, OTHER = 0x90, INTERNAL_OSCILLATOR = 0xA0 }
| the type of source of time used by a ClockMaster(802.1AS, 8.6.2.7 timeSource) More...
enum | PTPPortState { DisabledPort = 3, MasterPort = 6, PassivePort = 7, SlavePort = 9 }
| value of the port state (802.1AS 14.8.3 portState) More...
enum | gmsync_status_t { GMSYNC_UNSYNC =0, GMSYNC_SYNC, GMSYNC_SYNC_STABLE }

## Macros
#define | MAX_PATH_TRACE_N 179
| Macro to define maximum path trace. More...
#define | CLOCK_IDENTITY_LENGTH 8
| Macro which defines Clock Identity Length. More...
#define | SCALEDNS_FACTOR 0x10000
#define | VALUE_DISABLED 0u
#define | VALUE_ENABLED 1u

## Macro Definition Documentation

## ◆ MAX_PATH_TRACE_N

#define MAX_PATH_TRACE_N 179

Macro to define maximum path trace.

Note
  The maximum possible number is 179 based on specification we can set the maximum here and restrict the frame using MAX_PTP_PACKET instead
  #define MAX_PATH_TRACE_N 179

See also
  10.3.8.23 pathTrace

## ◆ CLOCK_IDENTITY_LENGTH

#define CLOCK_IDENTITY_LENGTH 8

Macro which defines Clock Identity Length.

## ◆ SCALEDNS_FACTOR

#define SCALEDNS_FACTOR 0x10000

## ◆ VALUE_DISABLED

#define VALUE_DISABLED 0u

## ◆ VALUE_ENABLED

#define VALUE_ENABLED 1u

## Typedef Documentation

## ◆ ClockIdentity

typedef uint8_t ClockIdentity[CLOCK_IDENTITY_LENGTH]

## ◆ Nibble

typedef uint8_t Nibble

Primitive data types specifications for IEEE 802.1AS. All non-primitive data types are derived from the primitive types, signed integers are represented as two's complement form.

    See the following Table

Data Types | Definition
--- | ---
EnumerationN | N-bit enumerated value
UIntegerN | N-bit unsigned integer
Nibble | 4-bit field not interpreted as a number
Octet | 8-bit field not interpreted as a number
OctetN | N-octet fiels not interpreted as a number
Double | Double precision (64-bit) floating-point vlaue

## ◆ Octet

typedef uint8_t Octet

## ◆ Octet2

typedef uint8_t Octet2[2]

## ◆ Octet3

typedef uint8_t Octet3[3]

## ◆ Octet4

typedef uint8_t Octet4[4]

## ◆ Enumeration2

typedef uint8_t Enumeration2

## ◆ Enumeration4

typedef uint8_t Enumeration4

## ◆ Enumeration8

typedef uint8_t Enumeration8

## ◆ Enumeration16

typedef uint16_t Enumeration16

## ◆ Enumeration24

typedef uint32_t Enumeration24

## ◆ UInteger4

typedef uint8_t UInteger4

## Enumeration Type Documentation

## ◆ TimeSource

enum TimeSource

the type of source of time used by a ClockMaster(802.1AS, 8.6.2.7 timeSource)

Enumerator
ATOMIC_CLOCK |
GPS |
TERRESTRIAL_RADIO |
PTP |
NTP |
HAND_SET |
OTHER |
INTERNAL_OSCILLATOR |

## ◆ PTPPortState

enum PTPPortState

value of the port state (802.1AS 14.8.3 portState)

Note
  IEEE1588-2019, initializing=1, faulty=2, disabled=3, listening=4, pre-master=5, master=6, passive=7, uncalibrated=8, slave=9

Enumerator
DisabledPort |
MasterPort |
PassivePort |
SlavePort |

## ◆ gmsync_status_t

enum gmsync_status_t

Enumerator
GMSYNC_UNSYNC |
GMSYNC_SYNC |
GMSYNC_SYNC_STABLE |

## Function Documentation

## ◆ gptpmasterclock_init()

int gptpmasterclock_init | ( | const char * | shmem_name | ) |

initialize to get gptp clock from tsn_gptp daemon. if previously initialized, it will simply return 0.

Parameters

  shmem_name | shared memory node name. set NULL to use the default

Returns
  -1 on error, 0 on Successful initialization.

Note
  argument 'shmem_name' will not be used in platforms that recommends against using shared memory (e.g GHS INTEGRITY). Pass NULL is such case.

## ◆ gptpmasterclock_close()

int gptpmasterclock_close | ( | void |  | ) |

close gptpmasterclcock

Returns
  -1: on error, 0:on successfull

## ◆ gptpmasterclock_gm_domainIndex()

int gptpmasterclock_gm_domainIndex | ( | void |  | ) |

return the domainIndex which is currently used as systeme wide gptp clock.

Returns
  domainIndex, -1: error

## ◆ gptpmasterclock_getts64()

int64_t gptpmasterclock_getts64 | ( | void |  | ) |

get 64-bit nsec unit ts of system wide gptp clock

Returns
  >=0 on success, -1 on error

## ◆ gptpmasterclock_wait_until_ts64()

int gptpmasterclock_wait_until_ts64 | ( | int64_t | tts,
|  | int64_t | vclose,
|  | int64_t | toofar
| ) |  |

Wait until tts comes.

Returns
  -1: error, 1:already passed, 2:in vclose, 3:farther than toofar seconds, 0:returns from nanosleep(has been waited to very close timing)

Parameters

  tts | target time in nano second unit
  vclose | nano second unit; treated as very close, and stop waiting even ttv is still in future
  toofar | nano second unit; treated as too far, and stop waiting

## ◆ gptpmasterclock_expand_timestamp()

uint64_t gptpmasterclock_expand_timestamp | ( | uint32_t | timestamp | ) |

expand 32-bit nsec time to 64 bit with aligning to gptp clock.

Parameters

  timestamp | timestamp which we are going to convert into 32bit to 64 bit.

Returns
  expanded time

Note
  a range of -2.147 to 2.147 secconds can be correctly aligned

## ◆ gptpmasterclock_expand_timestamp_ts64()

uint64_t gptpmasterclock_expand_timestamp_ts64 | ( | uint32_t | timestamp,
|  | int64_t | ts64
| ) |  |

expand 32-bit nsec time to 64 bit with aligning to gptp clock at the time `ts64`.

Parameters

  timestamp | timestamp which we are going to convert into 32bit to 64 bit.
  ts64 | the gptp clock time that the `timestamp` will be aligned to.

Returns
  expanded time

Note
  a range of -2.147 to 2.147 secconds can be correctly aligned

## ◆ gptpmasterclock_gmchange_ind()

int gptpmasterclock_gmchange_ind | ( | void |  | ) |

get GM change indicator, the number is incremented whenever GM is changed

Returns
  GM change indicator value, -1: on error

## ◆ gptpmasterclock_get_max_domains()

int gptpmasterclock_get_max_domains | ( | void |  | ) |

get maximum number of domains

Returns
  returns available number of domains.

## ◆ gptpmasterclock_get_domain_ts64()

int gptpmasterclock_get_domain_ts64 | ( | int64_t * | ts64,
|  | int | domainIndex
| ) |  |

get a synchronized clock value on specific domain

Parameters

  ts64 | pointer to return clock value
  domainIndex | domain index number

Returns
  0 on success, -1 on error.

## ◆ gptpmasterclock_dump_offset()

void gptpmasterclock_dump_offset | ( | void |  | ) |

print phase offset for all domains