ra8_etha_shaper.h File Reference

Per-port ETHA VLAN / shaper / stats / ring / PHY API – HUM Ch 32 (p 1627-1702). More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_etha_regs.h"
#include "ra8_etha_types.h"
#include "ra8_rmac.h"

Include dependency graph for ra8_etha_shaper.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
ra8_err_t	ra8_etha_set_vlan_mode (ra8_etha_port_t port, ra8_etha_vim_t vim, ra8_etha_vem_t vem)
	Configure VLAN tag insertion / extraction for the port.
ra8_err_t	ra8_etha_set_vlan_tag (ra8_etha_port_t port, const ra8_etha_vlan_tag_t *c_tag, const ra8_etha_vlan_tag_t *s_tag_in)
	Programme the C-VLAN and S-VLAN tag values used on TX insertion.
ra8_err_t	ra8_etha_set_rx_tag_filter (ra8_etha_port_t port, uint32_t mask)
	Configure the RX tag filter (multicast group + VLAN-tag filter).
ra8_err_t	ra8_etha_configure_cut_through (ra8_etha_port_t port, uint16_t qd, uint8_t dqd)
	Configure the cut-through TX queue (low-latency forwarding).
ra8_err_t	ra8_etha_configure_cbs (ra8_etha_port_t port, ra8_etha_tc_t tc, uint8_t enable, const ra8_etha_cbs_param_t *param)
	Configure the credit-based shaper (CBS) for one traffic class.
ra8_err_t	ra8_etha_get_cbs_state (ra8_etha_port_t port, ra8_etha_tc_t tc, uint8_t *enabled, uint8_t *gate_open, ra8_etha_cbs_param_t *oper_param)
	Read the operational CBS gate-state vector + per-class oper params.
ra8_err_t	ra8_etha_set_tas_schedule (ra8_etha_port_t port, const ra8_etha_tas_queue_t *queues, uint8_t initial_gate_states, uint32_t cycle_time_ns, uint64_t start_time)
	Programme the time-aware shaper (TAS / 802.1Qbv) gate lists.
ra8_err_t	ra8_etha_tas_ram_reset (ra8_etha_port_t port)
	Reset the TAS RAM and wait for it to report ready.
ra8_err_t	ra8_etha_read_tas_entry (ra8_etha_port_t port, uint8_t address, ra8_etha_tas_entry_t *out)
	Read one TAS RAM entry back out of hardware.
ra8_err_t	ra8_etha_enable_tas (ra8_etha_port_t port, uint8_t enable)
	Enable or disable the TAS scheduler (main switch).
ra8_err_t	ra8_etha_read_stats (ra8_etha_port_t port, ra8_etha_stats_t *out)
	Read the per-port MIB error counters.
ra8_err_t	ra8_etha_clear_stats (ra8_etha_port_t port)
	Clear the per-port MIB error counters in hardware.
ra8_err_t	ra8_etha_descriptor_ring_init (ra8_etha_port_t channel, uint16_t num_tx, uint16_t num_rx, uint16_t buffer_size)
	Configure the per-port descriptor-ring sizing.
ra8_err_t	ra8_etha_get_stats (ra8_etha_port_t channel, ra8_etha_port_stats_t *out_stats)
	Snapshot the per-port software-maintained traffic counters.
ra8_err_t	ra8_etha_account_traffic (ra8_etha_port_t channel, uint32_t tx_ok, uint32_t tx_err, uint32_t rx_ok, uint32_t rx_err, uint32_t rx_drop)
	Increment the per-port TX OK / TX err / RX OK / RX err / drop counters.
ra8_err_t	ra8_etha_open (ra8_etha_port_t channel, const ra8_etha_phy_open_t *phy, ra8_rmac_phy_link_t *out_link)
	Bring an ETHA port + its off-chip PHY up to OPERATION mode.

Detailed Description

Per-port ETHA VLAN / shaper / stats / ring / PHY API – HUM Ch 32 (p 1627-1702).

Tag

[Ring 3 / HAL] {World: NS}

VLAN tag insertion / extraction, RX tag filter, cut-through queue, credit-based shaper (CBS / 802.1Qav), time-aware shaper (TAS / 802.1Qbv), per-port MIB counters, descriptor ring sizing, software traffic accounting, and the one-shot PHY bring-up helper. Split out of the umbrella ra8_etha.h to keep that header under the per-file line budget; this is a pure move of the original declarations (the tests-side Ethernet header parser that once lived here moved to tests/fixtures/inc/eth_frame_fixture.h under issue #238). The data types these functions take live in ra8_etha_types.h, the register enums in ra8_etha_regs.h, and the PHY link type in ra8_rmac.h.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file ra8_etha_shaper.h.

Function Documentation

ra8_etha_account_traffic()

ra8_err_t ra8_etha_account_traffic ( ra8_etha_port_t channel, uint32_t tx_ok, uint32_t tx_err, uint32_t rx_ok, uint32_t rx_err, uint32_t rx_drop )

nodiscard

Increment the per-port TX OK / TX err / RX OK / RX err / drop counters.

Parameters

[in]	channel	Port identifier.
[in]	tx_ok	Frames to add to tx_ok.
[in]	tx_err	Frames to add to tx_err.
[in]	rx_ok	Frames to add to rx_ok.
[in]	rx_err	Frames to add to rx_err.
[in]	rx_drop	Frames to add to rx_drop.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Counters updated (or saturated).
k_ra8_err_invalid_arg	channel out of range.

Precondition

Port previously brought up via ra8_etha_init.

Caller serialises against concurrent ra8_etha_get_stats.

Postcondition

Each counter += the matching argument, saturating at UINT32_MAX.

Note

IRQ-context safe; performs no allocation, no locks.

See also

ra8_etha_get_stats

Since

0.1.0

Definition at line 158 of file ra8_etha_stats.c.

References internal_port_ok(), internal_sat_add_u32(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_log_error, ra8_etha_port_stats_t::rx_drop, ra8_etha_port_stats_t::rx_err, ra8_etha_port_stats_t::rx_ok, s_etha_slots, s_tag, ra8_etha_port_stats_t::tx_err, and ra8_etha_port_stats_t::tx_ok.

Referenced by internal_eth_loopback_run_once().

ra8_etha_clear_stats()

ra8_err_t ra8_etha_clear_stats ( ra8_etha_port_t port )

nodiscard

Clear the per-port MIB error counters in hardware.

Parameters

[in]

port

Port identifier.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	All five counters zeroed.
k_ra8_err_invalid_arg	port out of range.

Precondition

Port previously brought up via ra8_etha_init.

Caller has snapshotted via ra8_etha_read_stats first if deltas matter.

Postcondition

EAUSMFSECN = EATFECN = EAFSECN = EADQOECN = EADQSECN = 0.

No state outside the five counter registers is touched.

Note

Provided so applications can reset the MIB at any time.

See also

ra8_etha_read_stats

Since

0.1.0

Definition at line 767 of file ra8_etha.c.

References r_etha_regs_t::EADQOECN, r_etha_regs_t::EADQSECN, r_etha_regs_t::EAFSECN, r_etha_regs_t::EATFECN, r_etha_regs_t::EAUSMFSECN, internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_etha(), ra8_log_error, and s_tag.

ra8_etha_configure_cbs()

ra8_err_t ra8_etha_configure_cbs ( ra8_etha_port_t port, ra8_etha_tc_t tc, uint8_t enable, const ra8_etha_cbs_param_t * param )

nodiscard

Configure the credit-based shaper (CBS) for one traffic class.

Parameters

[in]	port	Port identifier.
[in]	tc	Traffic class (0..7).
[in]	enable	Non-zero -> set EACAEC.CEtc and EACC.CCtc.
[in]	param	Pointer to CBS parameters (increment + upper-limit).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	CBS programmed.
k_ra8_err_null_ptr	param is nullptr (when enable != 0).
k_ra8_err_invalid_arg	port, tc, or values out of range.

Precondition

Port is in CONFIG mode.

param->increment fits in 20 bits, upper_lim in 31 bits.

Postcondition

EACAIVC[tc] = increment; EACAULC[tc] = upper_lim.

EACAEC.CEtc = enable!=0; EACC.CCtc = enable!=0.

Note

CBS is the AVB credit shaper (802.1Qav).

See also

ra8_etha_get_cbs_state

Since

0.1.0

Definition at line 680 of file ra8_etha.c.

References r_etha_regs_t::EACAEC, r_etha_regs_t::EACAIVC, r_etha_regs_t::EACAULC, r_etha_regs_t::EACC, ra8_etha_cbs_param_t::increment, internal_port_ok(), internal_tc_ok(), k_ra8_err_invalid_arg, k_ra8_etha_mask_civ, k_ra8_etha_mask_cul, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_etha(), ra8_log_error, s_tag, and ra8_etha_cbs_param_t::upper_lim.

Referenced by tsn_program_cbs().

ra8_etha_configure_cut_through()

ra8_err_t ra8_etha_configure_cut_through ( ra8_etha_port_t port, uint16_t qd, uint8_t dqd )

nodiscard

Configure the cut-through TX queue (low-latency forwarding).

Parameters

[in]	port	Port identifier.
[in]	qd	16-bit cut-through queue depth in bytes (CTQD).
[in]	dqd	4-bit cut-through descriptor queue depth (CTDQD).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	EACTQC + EACTDQDC updated.
k_ra8_err_invalid_arg	port out of range.

Precondition

Port is in CONFIG mode.

dqd <= 15.

Postcondition

EACTQC.CTQD = qd; EACTDQDC.CTDQD = dqd.

Cut-through path may begin forwarding short frames sooner.

Note

CTDQD = 0 effectively disables the cut-through path.

Since

0.1.0

Definition at line 666 of file ra8_etha.c.

References r_etha_regs_t::EACTDQDC, r_etha_regs_t::EACTQC, internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_etha_mask_ctdqd, k_ra8_etha_mask_ctqd, k_ra8_ok, ra8_etha(), ra8_log_error, and s_tag.

ra8_etha_descriptor_ring_init()

ra8_err_t ra8_etha_descriptor_ring_init ( ra8_etha_port_t channel, uint16_t num_tx, uint16_t num_rx, uint16_t buffer_size )

nodiscard

Configure the per-port descriptor-ring sizing.

Parameters

[in]	channel	Port identifier (0..1, mapped to ra8_etha_port_t).
[in]	num_tx	Number of TX descriptors (1..4096).
[in]	num_rx	Number of RX descriptors (1..4096).
[in]	buffer_size	Bytes per descriptor buffer (>= 64, <= 16383).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Ring config captured.
k_ra8_err_invalid_arg	Any argument out of range.

Precondition

Port previously brought up via ra8_etha_init.

Caller has reserved descriptor storage matching num_tx + num_rx.

Postcondition

Per-port stats reflect ring_tx / ring_rx / ring_buf.

Per-class TX queue depths are clamped to num_tx.

Note

Per-port; safe to call concurrently for distinct ports.

See also

ra8_etha_get_stats

Since

0.1.0

Definition at line 115 of file ra8_etha_stats.c.

References r_etha_regs_t::EATDQDC, internal_port_ok(), internal_ring_args_ok(), k_ra8_err_invalid_arg, k_ra8_etha_mask_dqd, k_ra8_etha_tc_count, k_ra8_ok, ra8_etha(), ra8_log_error, s_etha_slots, and s_tag.

Referenced by internal_eth_loopback_run_once().

ra8_etha_enable_tas()

ra8_err_t ra8_etha_enable_tas ( ra8_etha_port_t port, uint8_t enable )

nodiscard

Enable or disable the TAS scheduler (main switch).

Parameters

[in]	port	Port identifier.
[in]	enable	Non-zero -> set EATASC.TASE; zero -> clear.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	EATASC.TASE updated.
k_ra8_err_invalid_arg	port out of range.

Precondition

Port previously brought up via ra8_etha_init.

TAS schedule programmed via ra8_etha_set_tas_schedule.

Postcondition

EATASC.TASE = enable!=0.

Other EATASC bits unchanged.

Note

When disabled, all gates are forced open.

See also

ra8_etha_set_tas_schedule

Since

0.1.0

Definition at line 389 of file ra8_etha_tas.c.

References r_etha_regs_t::EATASC, internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_etha_eatasc_tase_pos, k_ra8_ok, ra8_etha(), ra8_log_error, and s_tag.

Referenced by tsn_program_tas().

ra8_etha_get_cbs_state()

ra8_err_t ra8_etha_get_cbs_state ( ra8_etha_port_t port, ra8_etha_tc_t tc, uint8_t * enabled, uint8_t * gate_open, ra8_etha_cbs_param_t * oper_param )

nodiscard

Read the operational CBS gate-state vector + per-class oper params.

Parameters

[in]	port	Port identifier.
[in]	tc	Traffic class (0..7).
[out]	enabled	Non-zero if oper-enable mirror bit is set.
[out]	gate_open	Non-zero if EACGSM gate-state bit is asserted.
[out]	oper_param	Live oper-side increment + upper-limit values.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	any out pointer is nullptr.
k_ra8_err_invalid_arg	port or tc out of range.

Precondition

Port previously brought up via ra8_etha_init.

All output pointers are writable.

Postcondition

*enabled reflects EACOEM.CEtc.

*gate_open reflects EACGSM.CGStc.

Note

The oper-side mirror lags the admin-side until next CBS update.

See also

ra8_etha_configure_cbs

Since

0.1.0

Definition at line 718 of file ra8_etha.c.

References r_etha_regs_t::EACGSM, r_etha_regs_t::EACOEM, r_etha_regs_t::EACOIVM, r_etha_regs_t::EACOULM, ra8_etha_cbs_param_t::increment, internal_port_ok(), internal_tc_ok(), k_ra8_err_invalid_arg, k_ra8_etha_mask_civ, k_ra8_etha_mask_cul, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_etha(), ra8_log_error, s_tag, and ra8_etha_cbs_param_t::upper_lim.

Referenced by tsn_program_cbs().

ra8_etha_get_stats()

ra8_err_t ra8_etha_get_stats ( ra8_etha_port_t channel, ra8_etha_port_stats_t * out_stats )

nodiscard

Snapshot the per-port software-maintained traffic counters.

Parameters

[in]	channel	Port identifier.
[out]	out_stats	Destination for the snapshot.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	out_stats is nullptr.
k_ra8_err_invalid_arg	channel out of range.

Precondition

Port previously brought up via ra8_etha_init.

out_stats is a writable pointer.

Postcondition

out_stats is populated with the live per-port counters.

Note

Used by threadx_netx_tcp_echo for liveness.

See also

ra8_etha_descriptor_ring_init

Since

0.1.0

Definition at line 147 of file ra8_etha_stats.c.

References internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_error, s_etha_slots, and s_tag.

Referenced by internal_eth_loopback_run_once().

ra8_etha_open()

ra8_err_t ra8_etha_open ( ra8_etha_port_t channel, const ra8_etha_phy_open_t * phy, ra8_rmac_phy_link_t * out_link )

nodiscard

Bring an ETHA port + its off-chip PHY up to OPERATION mode.

One-shot helper that wraps the per-port bring-up sequence the threadx_netx_tcp_echo app needs. Steps:

1. EAMC = OPERATION
2. ra8_rmac_phy_reset(channel, phy->phy_addr)
3. ra8_rmac_phy_set_advertise(channel, ..., phy->advertise)
4. ::ra8_rmac_phy_auto_neg_start(channel, ...)
5. ra8_rmac_phy_auto_neg_wait(channel, ..., phy->timeout_ms, out_link)

Parameters

[in]	channel	Port identifier.
[in]	phy	PHY bring-up parameters (must not be nullptr).
[out]	out_link	Resolved link state on success.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Port + PHY up; out_link populated.
k_ra8_err_null_ptr	phy or out_link is nullptr.
k_ra8_err_invalid_arg	channel out of range or phy fields bad.
k_ra8_err_hw_timeout	PHY reset / auto-neg never completed.

Precondition

Port previously brought up via ra8_etha_init.

RMAC port previously brought up via ra8_rmac_init.

Off-chip PHY visible on the MDIO bus at phy->phy_addr.

Postcondition

EAMC = OPERATION.

Auto-neg complete; *out_link reflects negotiated capability.

See also

ra8_etha_descriptor_ring_init

ra8_rmac_phy_auto_neg_wait

Since

0.1.0

Definition at line 215 of file ra8_etha_stats.c.

References ra8_etha_phy_open_t::advertise, internal_etha_to_operation(), internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_etha_phy_open_t::phy_addr, RA8_CHECK_NULL_PTR, ra8_log_error, ra8_rmac_phy_auto_neg_start(), ra8_rmac_phy_auto_neg_wait(), ra8_rmac_phy_reset(), ra8_rmac_phy_set_advertise(), s_tag, and ra8_etha_phy_open_t::timeout_ms.

ra8_etha_read_stats()

ra8_err_t ra8_etha_read_stats ( ra8_etha_port_t port, ra8_etha_stats_t * out )

nodiscard

Read the per-port MIB error counters.

Parameters

[in]	port	Port identifier.
[out]	out	Snapshot of all five counter registers.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	out is nullptr.
k_ra8_err_invalid_arg	port out of range.

Precondition

Port previously brought up via ra8_etha_init.

out is a writable pointer.

Postcondition

out is populated with the live counter values.

Counters in hardware are NOT cleared; use ra8_etha_clear_stats.

Note

Each counter is 16 bits and saturates rather than wrapping.

See also

ra8_etha_clear_stats

Since

0.1.0

Definition at line 745 of file ra8_etha.c.

References r_etha_regs_t::EADQOECN, r_etha_regs_t::EADQSECN, r_etha_regs_t::EAFSECN, r_etha_regs_t::EATFECN, r_etha_regs_t::EAUSMFSECN, ra8_etha_stats_t::frame_size_err, internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_etha_mask_mfs, k_ra8_ok, ra8_etha_stats_t::queue_overflow_err, ra8_etha_stats_t::queue_security_err, RA8_CHECK_NULL_PTR, ra8_etha(), ra8_log_error, s_tag, ra8_etha_stats_t::switch_min_frame_err, and ra8_etha_stats_t::tag_filter_err.

ra8_etha_read_tas_entry()

ra8_err_t ra8_etha_read_tas_entry ( ra8_etha_port_t port, uint8_t address, ra8_etha_tas_entry_t * out )

nodiscard

Read one TAS RAM entry back out of hardware.

The TAS entry read flow of HUM Figure 32.15 (Ch 32.4.2.13 "TAS Entry i Read Flow" p 1678): write the address to EATASGR.TASGAR, poll until EATASGRR.GR clears, then take TASGSR and TASGTR[27:0].

This is the read-back that lets a caller assert something real. Without it, the only available evidence that a schedule was programmed is that the programming calls returned k_ra8_ok – which they also did while the driver was writing gate states into the entry-address register.

Parameters

[in]	port	Port identifier.
[in]	address	TAS RAM entry address (0..k_ra8_etha_tas_addr_max).
[out]	out	Entry read back from that address.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	*out holds the entry at address.
k_ra8_err_null_ptr	out is nullptr.
k_ra8_err_invalid_arg	port out of range.
k_ra8_err_hw_timeout	EATASGRR.GR never cleared within budget.

Precondition

Port previously brought up via ra8_etha_init.

Port is not in RESET or DISABLE mode.

Postcondition

On success *out reflects TAS RAM contents at address.

Hardware state is unchanged apart from EATASGR.

Note

Not thread-safe; serialise per port.

See also

ra8_etha_set_tas_schedule

Since

0.1.0

Definition at line 361 of file ra8_etha_tas.c.

References r_etha_regs_t::EATASGR, r_etha_regs_t::EATASGRR, ra8_etha_tas_entry_t::gate_open, ra8_etha_tas_entry_t::gate_time_ns, internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_etha_eatasgrr_gr_pos, k_ra8_etha_eatasgrr_tasgsr_pos, k_ra8_etha_mask_tas_gal, k_ra8_etha_mask_tas_gtl, k_ra8_etha_tas_learn_spins, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_etha(), ra8_hw_wait_flag_clear32(), ra8_log_error, and s_tag.

Referenced by tsn_tas_entry_matches().

ra8_etha_set_rx_tag_filter()

ra8_err_t ra8_etha_set_rx_tag_filter ( ra8_etha_port_t port, uint32_t mask )

nodiscard

Configure the RX tag filter (multicast group + VLAN-tag filter).

Parameters

[in]	port	Port identifier.
[in]	mask	Bit mask written verbatim to EARTFC. Bit positions follow HUM Ch 32 EARTFC: NT, RT, CST, CSRT, CT, CRT, SCT, SCRT, UT.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	EARTFC = mask.
k_ra8_err_invalid_arg	port out of range.

Precondition

Port is in CONFIG mode.

Caller has used the EARTFC bit names (NT/RT/CST/...) when building mask.

Postcondition

EARTFC = mask & 0x1FF.

Frames matching the active filter survive; others are dropped.

Note

This is the multicast group filter for tagged traffic.

Since

0.1.0

Definition at line 655 of file ra8_etha.c.

References r_etha_regs_t::EARTFC, internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_etha_local_9bit_mask, k_ra8_ok, ra8_etha(), ra8_log_error, and s_tag.

ra8_etha_set_tas_schedule()

ra8_err_t ra8_etha_set_tas_schedule ( ra8_etha_port_t port, const ra8_etha_tas_queue_t * queues, uint8_t initial_gate_states, uint32_t cycle_time_ns, uint64_t start_time )

nodiscard

Programme the time-aware shaper (TAS / 802.1Qbv) gate lists.

Implements the TAS setting flow of HUM Figure 32.11 (Ch 32.4.2.9 "TAS Setting Flow" p 1675-1676) exactly:

1. read EATASC and abort when TASCI says a configuration change is impossible;
2. take the base TAS RAM address from EATASC.TASCA[23:16];
3. write each queue's entry count to EATASENCi;
4. write the cycle start time to EATASCSTC0/1 and the cycle time to EATASCTC;
5. learn every entry in turn – EATASGL0 takes the entry ADDRESS, EATASGL1 takes {TASGSL gate state, TASGTL gate time}, then EATASGLR.GL is polled until hardware clears it;
6. commit by setting EATASC.TASE, with TASCC set only when TAS was already enabled (a live schedule change).

queues is indexed by descriptor queue because the TAS RAM is partitioned per queue rather than holding one interleaved list: the entry blocks are laid out in queue order from EATASC.TASCA upward, and an entry's single GS bit belongs to the queue whose block holds it.

Parameters

[in]	port	Port identifier.
[in]	queues	Per-queue gate lists; k_ra8_etha_tc_count elements.
[in]	initial_gate_states	EATASIGSC bitmap – bit q is queue q's gate state at schedule start (HUM Ch 32.3.5.2 p 1647).
[in]	cycle_time_ns	Total cycle time, written verbatim to EATASCTC.
[in]	start_time	Absolute cycle-start time on the gPTP time base; low word to EATASCSTC0, high word to EATASCSTC1.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	TAS programmed and committed.
k_ra8_err_null_ptr	queues is nullptr, or a queue declares a non-zero count with a nullptr entry list.
k_ra8_err_invalid_arg	port out of range, the total entry count exceeds k_ra8_etha_tas_entries_max, or a gate time does not fit TASGTL[27:0].
k_ra8_err_busy	EATASC.TASCI is set; the port cannot accept a configuration change right now.
k_ra8_err_hw_timeout	EATASGLR.GL never cleared after a learn.

Precondition

Port is in CONFIG or OPERATION mode – the flow is unusable in RESET and DISABLE, per the note on Figure 32.11.

The TAS RAM has been reset at least once via ra8_etha_tas_ram_reset.

Postcondition

On success every declared entry is resident in the TAS RAM and EATASC.TASE is set.

On any error return no commit is issued, so a previously active schedule keeps running.

Note

Not thread-safe; serialise per port.

Warning

Gate times are in NANOSECONDS, not bus clocks: HUM Table 32.6 (p 1691) defines TAS.GT that way.

Example:

static const ra8_etha_tas_entry_t ptp_window[2] = {
  {.gate_time_ns = 125000U, .gate_open = true},
  {.gate_time_ns = 875000U, .gate_open = false},
};
ra8_etha_tas_queue_t queues[k_ra8_etha_tc_count] = {};
queues[k_ra8_etha_tc_7].entries = ptp_window;
queues[k_ra8_etha_tc_7].count   = 2U;
(void)ra8_etha_set_tas_schedule(k_ra8_etha_port_0, queues, 0x80U, 1000000U, 0U);

State Machine

See also

ra8_etha_tas_ram_reset

ra8_etha_read_tas_entry

Since

0.1.0

Definition at line 313 of file ra8_etha_tas.c.

References r_etha_regs_t::EATASC, internal_port_ok(), internal_tas_learn_all(), internal_tas_program_timing(), internal_tas_validate(), k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_etha_eatasc_tasca_pos, k_ra8_etha_eatasc_tascc_pos, k_ra8_etha_eatasc_tasci_pos, k_ra8_etha_eatasc_tase_pos, k_ra8_etha_mask_tas_gal, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_etha(), ra8_log_error, and s_tag.

Referenced by tsn_program_tas().

ra8_etha_set_vlan_mode()

ra8_err_t ra8_etha_set_vlan_mode ( ra8_etha_port_t port, ra8_etha_vim_t vim, ra8_etha_vem_t vem )

nodiscard

Configure VLAN tag insertion / extraction for the port.

Parameters

[in]	port	Port identifier.
[in]	vim	Insertion mode (ra8_etha_vim_t).
[in]	vem	Extraction mode (ra8_etha_vem_t).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	EAVCC updated.
k_ra8_err_invalid_arg	port out of range.

Precondition

Port is in CONFIG mode.

vem fits in 3 bits.

Postcondition

EAVCC.VIM = vim and EAVCC.VEM = vem.

Subsequent TX frames are tagged or stripped per the new mode.

Note

Tag values to insert come from::ra8_etha_set_vlan_tag.

See also

ra8_etha_set_vlan_tag

Since

0.1.0

Definition at line 609 of file ra8_etha.c.

References r_etha_regs_t::EAVCC, internal_port_ok(), k_etha_vem_mask, k_ra8_err_invalid_arg, k_ra8_etha_eavcc_vem_pos, k_ra8_ok, ra8_etha(), ra8_log_error, and s_tag.

ra8_etha_set_vlan_tag()

ra8_err_t ra8_etha_set_vlan_tag ( ra8_etha_port_t port, const ra8_etha_vlan_tag_t * c_tag, const ra8_etha_vlan_tag_t * s_tag_in )

nodiscard

Programme the C-VLAN and S-VLAN tag values used on TX insertion.

Parameters

[in]	port	Port identifier.
[in]	c_tag	C-VLAN tag (inner). Pointer to descriptor.
[in]	s_tag_in	S-VLAN tag (outer). Pointer to descriptor.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	EAVTC packed and written.
k_ra8_err_null_ptr	c_tag or s_tag is nullptr.
k_ra8_err_invalid_arg	port out of range or vid/pcp out of range.

Precondition

Port is in CONFIG mode.

c_tag->vid <= 0xFFF and c_tag->pcp <= 7 (same for s_tag).

Postcondition

EAVTC has both tags packed: CTV/CTP/CTD then STV/STP/STD.

No partial write on validation failure.

Note

Only effective when EAVCC.VIM =k_ra8_etha_vim_enabled.

See also

ra8_etha_set_vlan_mode

Since

0.1.0

Definition at line 623 of file ra8_etha.c.

References ra8_etha_vlan_tag_t::dei, r_etha_regs_t::EAVTC, internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_etha_eavtc_ctd_pos, k_ra8_etha_eavtc_ctp_pos, k_ra8_etha_eavtc_ctv_pos, k_ra8_etha_eavtc_std_pos, k_ra8_etha_eavtc_stp_pos, k_ra8_etha_eavtc_stv_pos, k_ra8_etha_mask_vlan_dei, k_ra8_etha_mask_vlan_pcp, k_ra8_etha_mask_vlan_vid, k_ra8_ok, ra8_etha_vlan_tag_t::pcp, RA8_CHECK_NULL_PTR, ra8_etha(), ra8_log_error, s_tag, and ra8_etha_vlan_tag_t::vid.

ra8_etha_tas_ram_reset()

ra8_err_t ra8_etha_tas_ram_reset ( ra8_etha_port_t port )

nodiscard

Reset the TAS RAM and wait for it to report ready.

The TAS RAM reset flow of HUM Figure 32.8 (Ch 32.4.2.6 "TAS RAM Reset Flow" p 1667): write 1 to EATASRIRM.TASRIOG, then poll until EATASRIRM.TASRR reads 1. Hardware clears TASRIOG itself when the initialisation completes. Entries learned before a reset do not survive it, so this runs once during bring-up, ahead of any schedule.

Parameters

[in]

port

Port identifier.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	TAS RAM initialised; EATASRIRM.TASRR reads 1.
k_ra8_err_invalid_arg	port out of range.
k_ra8_err_hw_timeout	TASRR never asserted within budget.

Precondition

Port previously brought up via ra8_etha_init.

Port is not in RESET or DISABLE mode; the flow is unusable there.

Postcondition

On success the TAS RAM holds no entries and TASRR reads 1.

On timeout no schedule is committed.

Note

Not thread-safe; serialise per port.

See also

ra8_etha_set_tas_schedule

Since

0.1.0

Definition at line 244 of file ra8_etha_tas.c.

References r_etha_regs_t::EATASRIRM, internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_etha_eatasrirm_tasriog_pos, k_ra8_etha_eatasrirm_tasrr_pos, k_ra8_etha_tas_ram_spins, k_ra8_ok, ra8_etha(), ra8_hw_wait_flag_set32(), ra8_log_error, and s_tag.

Referenced by tsn_program_tas().