Ethernet Agent

The Ethernet Agent is an RDK-B middleware component responsible for managing Ethernet interface configurations, monitoring interface status, and handling WAN failover operations in broadband gateway devices. This component provides comprehensive Ethernet interface management services including interface discovery, configuration management, status monitoring, and integration with WAN management subsystems.

The component serves as the primary interface between the RDK-B middleware stack and the underlying Ethernet hardware abstraction layer (HAL), enabling dynamic configuration of Ethernet interfaces for LAN and WAN operations. It supports advanced features like Ethernet WAN operation mode selection, interface bridging control, and real-time status monitoring with event-driven notifications.

The Ethernet Agent integrates seamlessly with other RDK-B components including the WAN Manager, VLAN Agent, and Component Registry, providing a unified interface for Ethernet interface management across different deployment scenarios. It supports both traditional WAN agent integration and modern WAN manager architectures based on compile-time feature flags.

graph LR
    subgraph "External Systems"
        RemoteMgmt["Remote Management"]
        LocalUI["Local Web UI"]
        CloudMgmt["Cloud Management"]
    end

    subgraph "RDK-B Platform"
        subgraph "Remote Management Agents"
            ProtocolAgents["TR-069/WebPA/TR-369<br/>Protocol Agents"]
        end
        
        subgraph "Ethernet Middleware"
            EthAgent["CcspEthAgent<br/>(Ethernet Agent)"]
        end
        
        subgraph "RDK-B Core Components"
            PSM["PSM<br/>(Parameter Storage)"]
            CR["Component Registry"]
            WanMgr["WAN Manager"]
            VlanAgent["VLAN Agent"]
        end
        
        subgraph "System Layer"
            HAL["Ethernet HAL"]
            Linux["Linux Kernel<br/>(Network Stack)"]
        end
    end

    %% External connections
    RemoteMgmt -->|TR-069/WebPA/TR-369| ProtocolAgents
    LocalUI -->|HTTP/HTTPS| ProtocolAgents
    CloudMgmt -->|WebConfig| ProtocolAgents

    %% Upper layer to Ethernet Agent
    ProtocolAgents -->|R-BUS/DBUS| EthAgent

    %% Ethernet Agent to Other RDK-B Components
    EthAgent -->|Configuration| PSM
    EthAgent -->|Registration| CR
    EthAgent <-->|WAN Events| WanMgr
    EthAgent <-->|VLAN Config| VlanAgent

    %% System Layer interactions
    EthAgent <-->|HAL APIs| HAL
    HAL <-->|Driver Interfaces| Linux

    classDef external fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef ethAgent fill:#e3f2fd,stroke:#1976d2,stroke-width:3px;
    classDef rdkbComponent fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px;
    classDef system fill:#fce4ec,stroke:#c2185b,stroke-width:2px;

    class RemoteMgmt,LocalUI,CloudMgmt external;
    class EthAgent ethAgent;
    class ProtocolAgents,PSM,CR,WanMgr,VlanAgent rdkbComponent;
    class HAL,Linux system;

Key Features & Responsibilities:

Ethernet Interface Management: Provides comprehensive management of Ethernet interfaces including discovery, configuration, and status monitoring for both LAN and WAN operations
TR-181 Data Model Support: Implements Device.Ethernet object hierarchy with support for interface configuration, statistics collection, and WAN mode selection parameters
WAN Failover Integration: Supports Ethernet WAN operation with automatic failover capabilities and integration with WAN Manager for multi-WAN scenarios
Dynamic Interface Configuration: Enables runtime configuration of Ethernet interface parameters including enable/disable, upstream designation, and bridge membership control
Real-time Status Monitoring: Provides continuous monitoring of interface status with event-driven notifications for link state changes and operational mode transitions
HAL Abstraction Layer: Abstracts underlying Ethernet hardware through standardized HAL interfaces enabling platform-independent operation across different hardware implementations

Design

The Ethernet Agent employs a layered architecture design that separates interface abstraction, data model management, and platform integration concerns. The core design follows the RDK-B component pattern with a Service Provider (SSP) layer for process management, a middle layer for TR-181 data model implementation, and a board-specific abstraction layer for HAL integration. This design ensures maintainability while providing flexible deployment options across different hardware platforms.

The component's architecture supports multiple operational modes through compile-time feature flags, enabling integration with either traditional WAN Agent architecture (FEATURE_RDKB_WAN_AGENT) or modern WAN Manager systems (FEATURE_RDKB_WAN_MANAGER). The design emphasizes event-driven communication patterns with other middleware components, utilizing R-BUS for inter-component messaging and HAL callbacks for hardware event processing.

The data persistence strategy leverages the Persistent Storage Manager (PSM) for configuration storage while maintaining runtime state in memory for performance. The component implements a robust error handling and recovery mechanism with comprehensive logging for troubleshooting and system diagnostics. The runtime architecture is event-driven but multi-threaded, with a main control path complemented by dedicated pthreads for responsibilities such as event handling, telemetry/logging, and state management. Interface state coordination is therefore designed to rely on clear thread ownership and synchronization rather than assuming single-threaded execution.

graph TD
    subgraph EthAgentContainer ["Ethernet Agent Process (CcspEthAgent)"]
        subgraph SSP ["Service Provider Layer"]
            SSPMain[SSP Main Process]
            MsgBusIntf[R-BUS Interface]
            ServiceReg[Service Registration]
        end
        
        subgraph MiddleLayer ["Middle Layer (TR-181 DML)"]
            EthDML[Ethernet DML Handler]
            InterfaceDML[Interface DML Handler]
            StatsModule[Statistics Module]
            R-BUSHandler[R-BUS Event Handler]
        end
        
        subgraph BoardAPI ["Board API Layer"]
            EthManager[Ethernet Manager]
            HALInterface[HAL Interface Module]
            ConfigMgr[Configuration Manager]
        end
    end

    subgraph ExternalDeps ["External Dependencies"]
        HAL[Ethernet HAL]
        PSMStore[PSM Storage]
        WanMgrSvc[WAN Manager Service]
    end

    SSPMain --> MsgBusIntf
    MsgBusIntf --> ServiceReg
    ServiceReg --> EthDML
    
    EthDML --> InterfaceDML
    EthDML --> StatsModule
    InterfaceDML --> R-BUSHandler
    
    R-BUSHandler --> EthManager
    EthManager --> HALInterface
    HALInterface --> ConfigMgr
    
    HALInterface -->|HAL API Calls| HAL
    ConfigMgr -->|PSM Get/Set| PSMStore
    R-BUSHandler -->|R-BUS Events| WanMgrSvc

    classDef ssp fill:#e3f2fd,stroke:#1976d2,stroke-width:2px;
    classDef middle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;
    classDef board fill:#fff8e1,stroke:#f57c00,stroke-width:2px;
    classDef external fill:#e8f5e8,stroke:#388e3c,stroke-width:2px;
    
    class SSPMain,MsgBusIntf,ServiceReg ssp;
    class EthDML,InterfaceDML,StatsModule,R-BUSHandler middle;
    class EthManager,HALInterface,ConfigMgr board;
    class HAL,PSMStore,WanMgrSvc external;

Prerequisites and Dependencies

Build-Time Flags and Configuration:

Configure Option	Build Flag	Purpose	Default
`--enable-wanfailover`	`FEATURE_WAN_FAIL_OVER`	Enable WAN failover capabilities and R-BUS integration	Disabled
`--enable-core_net_lib_feature_support`	`CORE_NET_LIB_FEATURE_SUPPORT` (Makefile), `CORE_NET_LIB` (code guard)	Enable linking against `-lnet` library. Sets `CORE_NET_LIB_FEATURE_SUPPORT` in Makefile for linking; code uses `#ifdef CORE_NET_LIB` which must be separately defined via CFLAGS	Disabled
`--enable-dropearly`	`DROP_ROOT_EARLY`	Enable non-root execution by dropping root privileges early in process lifecycle	Disabled
`--enable-notify`	`ENABLE_SD_NOTIFY`	Define systemd notification flag (note: currently defined but not used in codebase)	Disabled
`--enable-unitTestDockerSupport`	`UNIT_TEST_DOCKER_SUPPORT`	Enable Docker-based unit testing support with static function visibility	Disabled

RDK-B Platform and Integration Requirements

RDK-B Components: Component Registry, Persistent Storage Manager (PSM), WAN Manager (if FEATURE_RDKB_WAN_MANAGER enabled), VLAN Agent (if FEATURE_RDKB_WAN_AGENT enabled)
HAL Dependencies: ccsp_hal_ethsw.h interface with minimum HAL specification compliance for Ethernet switching operations; platform-specific statistics support (ETH_STATS_ENABLED) may be available on some platforms
Systemd Services: ccsp-cr.service must be active, psm.service for configuration persistence, dbus.service for inter-process communication
Hardware Requirements: Ethernet switching hardware with HAL support, minimum 1 Ethernet interface, WAN-capable Ethernet port for WAN failover features
Message Bus: R-BUS component registration with Device.Ethernet namespace reservation for TR-181 support and inter-component communication
TR-181 Data Model: Device.Ethernet object hierarchy support, Device.DeviceInfo parameters for AutoWAN feature discovery
Configuration Files: TR181-EthAgent.xml for data model definitions (dynamically modified based on DISTRO features), PSM database initialization for default interface configurations
Startup Order: Component Registry → PSM → Ethernet Agent → WAN Manager (if enabled), HAL initialization must complete before Ethernet Agent startup

Threading Model

The Ethernet Agent uses a multi-threaded design with dedicated execution contexts for core control flow, asynchronous event handling, and background activities such as telemetry/logging. The agent spawns multiple pthreads including a state machine thread (CcspEthManager_StateMachineThread), event handler threads (SysEventHandlerThrd, CosaDmlEthEventHandlerThread), monitoring threads (ThreadMonitorPhyAndNotify, CcspHalExtSw_AssociatedDeviceMonitorThread), message update threads (ThreadUpdateInformMsg, ThreadBootInformMsg), and configuration threads (ThreadConfigEthWan, CosaDmlEthWanChangeHandling). Work is distributed across these threads, so the implementation treats interface state, configuration data, and published status as shared resources requiring proper synchronization.

Threading Architecture: Multi-threaded with event-driven processing across dedicated worker threads for state machine operations, event handling, monitoring, and background tasks
Primary Responsibilities: TR-181 DML operations execute in the main thread, while state-machine transitions, HAL event notifications, status polling, telemetry/logging, and WAN configuration changes execute in dedicated pthread contexts
Event Processing: Asynchronous events from HAL, R-BUS method calls, timers, and internal worker threads are coordinated so that updates are serialized where required before mutating shared component state
Synchronization / Ownership Rules: Shared mutable state must only be accessed under the component's synchronization primitives or via explicit thread ownership and hand-off mechanisms. Threads that do not own a piece of state should communicate changes through the agent's event/dispatch path rather than updating shared structures directly

Component State Flow

Initialization to Active State

The Ethernet Agent follows a structured initialization sequence from system startup to full operational state. The component initializes its service provider layer, registers with the Component Registry, loads interface configurations from persistent storage, establishes HAL connections, and transitions to active monitoring mode.

sequenceDiagram
    participant System as System Startup
    participant EthAgent as Ethernet Agent
    participant CR as Component Registry
    participant PSM as PSM
    participant HAL as Ethernet HAL
    participant WanMgr as WAN Manager

    System->>EthAgent: Start CcspEthAgent Process
    Note over EthAgent: State: Initializing<br/>Load configuration, setup logging
    
    EthAgent->>CR: Register Component & Namespace
    CR-->>EthAgent: Registration Complete
    Note over EthAgent: State: Initializing → LoadingConfig
    
    EthAgent->>PSM: Load Persistent Configuration
    PSM-->>EthAgent: Interface Configs Retrieved
    Note over EthAgent: State: LoadingConfig → InitializingHAL
    
    EthAgent->>HAL: Initialize Ethernet HAL
    HAL-->>EthAgent: HAL Ready & Interface Discovery
    Note over EthAgent: State: InitializingHAL → ConnectingServices
    
    EthAgent->>WanMgr: Establish R-BUS Connection (if WAN Manager enabled)
    WanMgr-->>EthAgent: Connection Established
    Note over EthAgent: State: ConnectingServices → Active
    
    EthAgent->>System: Initialization Complete (Active State)
    
    loop Runtime Operations
        Note over EthAgent: State: Active<br/>Monitor interfaces, process events
        EthAgent->>EthAgent: Process HAL Events & R-BUS Methods
        EthAgent->>HAL: Poll Interface Status
        HAL-->>EthAgent: Status Updates
        EthAgent->>WanMgr: Publish Interface Events
    end
    
    System->>EthAgent: Stop Request
    Note over EthAgent: State: Active → Shutdown
    EthAgent->>PSM: Persist Configuration
    EthAgent->>HAL: Cleanup HAL Resources
    EthAgent->>System: Shutdown Complete

Runtime State Changes and Context Switching

The Ethernet Agent manages several runtime state transitions based on interface events, configuration changes, and WAN operational mode switching. These state changes are triggered by HAL events, TR-181 parameter modifications, and external component requests.

State Change Triggers:

Interface link state changes (up/down) trigger immediate status updates and event notifications to subscribing components
WAN operational mode changes trigger interface reconfiguration and notification to WAN Manager for failover coordination
Configuration parameter updates trigger validation, persistence to PSM, and application of new settings to HAL interfaces
HAL error conditions trigger error state transitions with automatic recovery attempts and comprehensive error logging

Context Switching Scenarios:

WAN Failover Context: Component switches between monitoring primary and backup WAN interfaces based on WAN Manager requests
Bridge Mode Context: Interfaces dynamically added/removed from bridge configurations based on LAN/WAN role assignments
AutoWAN Mode Context: Automatic detection and configuration of optimal WAN interface based on connectivity validation

Call Flow

Initialization Call Flow:

sequenceDiagram
    participant Init as Initialization Process
    participant SSP as SSP Main
    participant DML as Ethernet DML
    participant HAL as Ethernet HAL
    participant PSM as PSM

    Init->>SSP: Start CcspEthAgent
    SSP->>SSP: Initialize Logging & Signal Handlers
    SSP->>DML: Load TR-181 Data Model
    DML->>DML: Register Parameter Handlers
    DML->>PSM: Load Persistent Interface Configs
    PSM-->>DML: Configuration Data
    DML->>HAL: Initialize Ethernet HAL
    HAL-->>DML: Interface Discovery & Status
    DML->>SSP: DML Initialization Complete
    SSP->>Init: Component Ready (Active State)

Interface Configuration Call Flow:

The most critical operational flow involves processing TR-181 parameter changes and applying them to the underlying Ethernet interfaces through the HAL layer.

sequenceDiagram
    participant Client as External Client
    participant DML as Ethernet DML
    participant Manager as Ethernet Manager  
    participant HAL as Ethernet HAL
    participant PSM as PSM
    participant WanMgr as WAN Manager

    Client->>DML: Set TR-181 Parameter (R-BUS)
    Note over DML: Validate parameter value & constraints
    DML->>Manager: Process Configuration Change
    Manager->>HAL: Apply Interface Configuration
    HAL-->>Manager: Configuration Applied/Error
    alt Configuration Success
        Manager->>PSM: Persist Configuration
        PSM-->>Manager: Storage Complete
        Manager->>WanMgr: Notify Interface Change (if WAN interface)
        WanMgr-->>Manager: Acknowledgment
        Manager-->>DML: Success Response
        DML-->>Client: Parameter Set Complete
    else Configuration Error  
        Manager-->>DML: Error Response
        DML-->>Client: Error - Invalid Configuration
    end

TR‑181 Data Models

Supported TR-181 Parameters

The Ethernet Agent implements comprehensive TR-181 parameter support following BBF TR-181 Issue 2 specifications with RDK-Central extensions for enhanced Ethernet interface management and WAN failover capabilities. The implementation covers the Device.Ethernet object hierarchy with custom extensions for AutoWAN feature support and interface bridging control.

Build Configuration Note: The Ethernet Agent's TR-181 data model varies based on compile-time feature flags defined in the build configuration:

Interface Table Implementation (mutually exclusive):

FEATURE_RDKB_WAN_MANAGER: Implements standard TR-181 Device.Ethernet.Interface.{i} table with full parameter support (Enable, Status, Alias, etc.) and Stats sub-object. This is the modern WAN Manager integration mode.

FEATURE_RDKB_WAN_AGENT: Implements RDK-Central custom Device.Ethernet.X_RDKCENTRAL-COM_Interface.{i} table with vendor-specific parameters (X_RDKCENTRAL-COM_Upstream, X_RDKCENTRAL-COM_Status, etc.). This is the legacy WAN Agent integration mode.

Optional AutoWAN Feature (independent flag):

AUTOWAN_ENABLE: When enabled, adds the Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN object with automatic WAN interface selection capabilities. This object can be present in either WAN_MANAGER or WAN_AGENT builds.

Only one interface table implementation is active in a given build. The object hierarchies shown below indicate which build configuration each applies to.

Object Hierarchy

When FEATURE_RDKB_WAN_MANAGER is enabled:

Device.
├── DeviceInfo.
│   └── X_RDKCENTRAL-COM_AutowanFeatureSupport (boolean, R)
└── Ethernet.
    ├── X_RDKCENTRAL-COM_EthHost_Sync (boolean, R/W)
    ├── X_RDKCENTRAL-COM_WAN.
    │   ├── Enabled (boolean, R/W)
    │   └── Port (unsignedInt, R)
    ├── Interface.{i}.                                         [Standard TR-181]
    │   ├── Enable (boolean, R/W)
    │   ├── Status (string, R)
    │   ├── Alias (string, R/W)
    │   ├── Name (string, R)
    │   ├── LastChange (unsignedInt, R)
    │   ├── LowerLayers (string, R/W)
    │   ├── Upstream (boolean, R/W)                            [R/W if FEATURE_RDKB_WAN_UPSTREAM]
    │   ├── MACAddress (string, R)
    │   ├── MaxBitRate (int, R)
    │   ├── CurrentBitRate (unsignedInt, R)
    │   ├── DuplexMode (string, R/W)
    │   ├── X_RDKCENTRAL-COM_AssociatedDevice.{i}.
    │   │   └── MACAddress (string, R/W)
    │   └── Stats.
    │       ├── BytesSent (string, R)                          [64-bit counter as string]
    │       ├── BytesReceived (string, R)                      [64-bit counter as string]
    │       ├── PacketsSent (unsignedInt, R)
    │       ├── PacketsReceived (unsignedInt, R)
    │       ├── ErrorsSent (unsignedInt, R)
    │       ├── ErrorsReceived (unsignedInt, R)
    │       ├── UnicastPacketsSent (unsignedInt, R)
    │       ├── UnicastPacketsReceived (unsignedInt, R)
    │       ├── DiscardPacketsSent (unsignedInt, R)
    │       ├── DiscardPacketsReceived (unsignedInt, R)
    │       ├── MulticastPacketsSent (unsignedInt, R)
    │       ├── MulticastPacketsReceived (unsignedInt, R)
    │       ├── BroadcastPacketsSent (unsignedInt, R)
    │       ├── BroadcastPacketsReceived (unsignedInt, R)
    │       └── UnknownProtoPacketsReceived (unsignedInt, R)
    └── X_RDKCENTRAL-COM_EthernetWAN.                          [Only if AUTOWAN_ENABLE]
        ├── SelectedOperationalMode (string, R/W)
        ├── CurrentOperationalMode (string, R)
        ├── LastKnownOperationalMode (string, R)
        ├── ConfigureWan (boolean, R/W)
        ├── PostCfgWanFinalize (string, R/W)
        └── RequestPhyStatus (string, R/W)

When FEATURE_RDKB_WAN_AGENT is enabled:

Device.
├── DeviceInfo.
│   └── X_RDKCENTRAL-COM_AutowanFeatureSupport (boolean, R)
└── Ethernet.
    ├── X_RDKCENTRAL-COM_EthHost_Sync (boolean, R/W)
    ├── X_RDKCENTRAL-COM_WAN.
    │   ├── Enabled (boolean, R/W)
    │   └── Port (unsignedInt, R)
    ├── X_RDKCENTRAL-COM_Interface.{i}.                        [RDK-Central Custom]
    │   ├── X_RDKCENTRAL-COM_Upstream (boolean, R/W)
    │   ├── X_RDKCENTRAL-COM_WanValidated (boolean, R/W)
    │   ├── X_RDKCENTRAL-COM_Name (string, R)
    │   ├── X_RDKCENTRAL-COM_Status (string, R)                [Up(1), Down(2)]
    │   └── X_RDKCENTRAL-COM_WanStatus (string, R/W)          [Up(1), Down(2)]
    └── X_RDKCENTRAL-COM_EthernetWAN.                          [Only if AUTOWAN_ENABLE]
        ├── SelectedOperationalMode (string, R/W)
        ├── CurrentOperationalMode (string, R)
        ├── LastKnownOperationalMode (string, R)
        ├── ConfigureWan (boolean, R/W)
        ├── PostCfgWanFinalize (string, R/W)
        └── RequestPhyStatus (string, R/W)

Parameter Definitions

Common Parameters (all build configurations):

Parameter Path	Data Type	Access	Default Value	Description	BBF Compliance
`Device.DeviceInfo.X_RDKCENTRAL-COM_AutowanFeatureSupport`	boolean	R	`false`	Indicates whether the device supports AutoWAN feature for automatic WAN interface selection and failover capabilities	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_EthHost_Sync`	boolean	R/W	`false`	Controls synchronization of Ethernet host device information with connected devices for network topology discovery	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_WAN.Enabled`	boolean	R/W	`false`	Enables Ethernet WAN functionality allowing Ethernet interfaces to operate as WAN connections	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_WAN.Port`	unsignedInt	R	`0`	Indicates the physical port number currently configured for Ethernet WAN operation	RDK-Central Extension

FEATURE_RDKB_WAN_MANAGER Interface Parameters:

Parameter Path	Data Type	Access	Default Value	Description	BBF Compliance
`Device.Ethernet.Interface.{i}.Enable`	boolean	R/W	`true`	Enables or disables the Ethernet interface. When disabled, interface is administratively down	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Status`	string	R	`"Down"`	Current operational status: Up(1), Down(2), Unknown(3), Dormant(4), NotPresent(5), LowerLayerDown(6), Error(7)	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Alias`	string	R/W	`""`	User-assigned name for the interface. Alternative identifier for interface reference	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Name`	string	R	System-assigned	System-assigned interface name (e.g., eth0, eth1). Read-only identifier	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.LastChange`	unsignedInt	R	`0`	Time in seconds since last interface state change. Used for monitoring interface stability	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.LowerLayers`	string	R/W	`""`	Comma-separated list of lower-layer interface references for layered interface stack	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Upstream`	boolean	R/W¹	`false`	Indicates whether interface is designated as upstream (WAN) connection. Controls routing and bridge membership	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.MACAddress`	string	R	System-assigned	Physical MAC address of the Ethernet interface in colon-separated hexadecimal notation	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.MaxBitRate`	int	R	`-1`	Maximum supported bit rate in Mbps. -1 indicates unknown or auto-negotiation	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.CurrentBitRate`	unsignedInt	R	`0`	Current negotiated bit rate in Mbps. Reflects active link speed	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.DuplexMode`	string	R/W	`"Auto"`	Interface duplex mode: Half(1), Full(2), Auto(3). Auto enables automatic negotiation	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.BytesSent`	string	R	`"0"`	Total bytes transmitted. Represented as string to support 64-bit counter values	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.BytesReceived`	string	R	`"0"`	Total bytes received. Represented as string to support 64-bit counter values	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.PacketsSent`	unsignedInt	R	`0`	Total packets transmitted	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.PacketsReceived`	unsignedInt	R	`0`	Total packets received	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.ErrorsSent`	unsignedInt	R	`0`	Total packets transmitted with errors	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.ErrorsReceived`	unsignedInt	R	`0`	Total packets received with errors	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.UnicastPacketsSent`	unsignedInt	R	`0`	Total unicast packets transmitted	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.UnicastPacketsReceived`	unsignedInt	R	`0`	Total unicast packets received	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.DiscardPacketsSent`	unsignedInt	R	`0`	Total outbound packets discarded (e.g., buffer full, policy)	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.DiscardPacketsReceived`	unsignedInt	R	`0`	Total inbound packets discarded (e.g., buffer full, policy)	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.MulticastPacketsSent`	unsignedInt	R	`0`	Total multicast packets transmitted	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.MulticastPacketsReceived`	unsignedInt	R	`0`	Total multicast packets received	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.BroadcastPacketsSent`	unsignedInt	R	`0`	Total broadcast packets transmitted	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.BroadcastPacketsReceived`	unsignedInt	R	`0`	Total broadcast packets received	TR-181 Issue 2
`Device.Ethernet.Interface.{i}.Stats.UnknownProtoPacketsReceived`	unsignedInt	R	`0`	Total packets received with unknown or unsupported protocol	TR-181 Issue 2

¹ Writable only when FEATURE_RDKB_WAN_UPSTREAM is enabled, otherwise read-only

FEATURE_RDKB_WAN_AGENT Interface Parameters:

Parameter Path	Data Type	Access	Default Value	Description	BBF Compliance
`Device.Ethernet.X_RDKCENTRAL-COM_Interface.{i}.X_RDKCENTRAL-COM_Upstream`	boolean	R/W	`false`	Indicates whether interface is designated as upstream (WAN) connection for legacy WAN Agent integration	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_Interface.{i}.X_RDKCENTRAL-COM_WanValidated`	boolean	R/W	`false`	Indicates whether WAN connectivity validation has passed for this interface	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_Interface.{i}.X_RDKCENTRAL-COM_Name`	string	R	System-assigned	System-assigned interface name for legacy WAN Agent mode	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_Interface.{i}.X_RDKCENTRAL-COM_Status`	string	R	`"Down"`	Current operational status for legacy mode: Up(1), Down(2)	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_Interface.{i}.X_RDKCENTRAL-COM_WanStatus`	string	R/W	`"Down"`	WAN operational status for legacy mode: Up(1), Down(2)	RDK-Central Extension

AUTOWAN_ENABLE Parameters (optional feature - only present when AUTOWAN_ENABLE is defined):

Note: The Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN object and its parameters are only available in builds where the AUTOWAN_ENABLE compile-time flag is enabled. This feature is independent of the WAN_MANAGER/WAN_AGENT choice and can be combined with either integration mode.

Parameter Path	Data Type	Access	Default Value	Description	BBF Compliance
`Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN.SelectedOperationalMode`	string	R/W	`""`	User-selected WAN operational mode for automatic interface selection in multi-WAN scenarios	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN.CurrentOperationalMode`	string	R	`""`	Currently active WAN operational mode reflecting actual system configuration	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN.LastKnownOperationalMode`	string	R	`""`	Previously active WAN operational mode before current mode. Used for failback operations	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN.ConfigureWan`	boolean	R/W	`false`	Triggers WAN interface configuration process when set to true. Self-clearing after processing	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN.PostCfgWanFinalize`	string	R/W	`""`	Post-configuration finalization command string for WAN setup completion	RDK-Central Extension
`Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN.RequestPhyStatus`	string	R/W	`""`	Request physical interface status query. Write interface name to trigger status update	RDK-Central Extension

Internal Modules

The Ethernet Agent is structured into distinct functional modules that handle different aspects of Ethernet interface management. Each module has specific responsibilities and interacts through well-defined interfaces to maintain system modularity and testability.

Module/Class	Description	Key Files
SSP Main Process	Service provider layer handling process lifecycle, signal management, and R-BUS integration for component startup and shutdown coordination	`ssp_main.c`, `ssp_messagebus_interface.c`, `ssp_action.c`
Ethernet DML Handler	TR-181 data model implementation providing parameter access, validation, and event handling for Device.Ethernet object hierarchy	`cosa_ethernet_dml.c`, `cosa_ethernet_dml.h`
Interface DML Handler	Specialized handler for Device.Ethernet.Interface table operations including dynamic interface discovery, configuration management, and statistics collection	`cosa_ethernet_interface_dml.c`, `cosa_ethernet_interface_dml.h`
Ethernet Manager	Core business logic module managing interface state, configuration persistence, and coordination between HAL layer and upper middleware components	`cosa_ethernet_manager.c`, `cosa_ethernet_apis.c`
HAL Interface Module	Hardware abstraction layer integration providing platform-independent access to Ethernet hardware capabilities and event handling	`eth_hal_interface.c`, `cosa_ethernet_apis.h`
R-BUS Handler	Event-driven communication module managing R-BUS method registration, event publishing, and inter-component messaging for real-time interface status updates	`cosa_rbus_handler_apis.c`, `cosa_rbus_handler_apis.h`

Component Interactions

The Ethernet Agent integrates with multiple RDK-B middleware components and external systems to provide comprehensive Ethernet interface management. These interactions include TR-181 parameter access, event notifications, HAL hardware integration, and coordination with WAN management systems.

Interaction Matrix

Target Component/Layer	Interaction Purpose	Key APIs/Endpoints
RDK-B Middleware Components
WAN Manager	Interface status events and WAN failover coordination	`Device.Ethernet.X_RDKCENTRAL-COM_WAN.Enabled`, `Device.Ethernet.Interface.{i}.Upstream`
VLAN Agent	Ethernet link configuration and VLAN interface creation	`Device.X_RDKCENTRAL-COM_Ethernet.Link.{i}.*` parameters via R-BUS
PSM	Configuration persistence for interface settings	`dmsb.ethagent.if.{i}.Upstream`, `dmsb.ethagent.if.{i}.AddToLanBridge`
Component Registry	Service registration and namespace management	Component registration with `eRT.com.cisco.spvtg.ccsp.ethagent` identifier
Telemetry Agent	Interface statistics reporting	R-BUS events for statistics data: BytesSent, PacketsReceived, ErrorsReceived
System & HAL Layers
Ethernet HAL	Hardware interface control and status monitoring	`CcspHalEthSwSetPortAdminStatus()`, `CcspHalEthSwGetPortStatus()`, `CcspHalEthSwGetEthPortStats()`
Linux Network Stack	Direct interface manipulation for advanced configurations	`/sys/class/net/{interface}/operstate`, `ioctl()` system calls

Events Published by Ethernet Agent:

Event Name	Event Topic/Path	Trigger Condition	Subscriber Components
Interface Status Change	`Device.Ethernet.Interface.{i}.Status`	Link up/down, operational state changes	WAN Manager, Telemetry Agent, Web UI
WAN Interface Change	`Device.Ethernet.X_RDKCENTRAL-COM_WAN.Enabled`	WAN interface enable/disable, port changes	WAN Manager, VLAN Agent
Interface Statistics Update	`Device.Ethernet.Interface.{i}.Stats.*`	Periodic statistics collection (configurable interval)	Telemetry Agent, SNMP Agent
AutoWAN Mode Change¹	`Device.Ethernet.X_RDKCENTRAL-COM_EthernetWAN.CurrentOperationalMode`	WAN operational mode transitions	WAN Manager, Event logging systems

¹ Only published when AUTOWAN_ENABLE is defined

IPC Flow Patterns

Primary IPC Flow - Interface Configuration:

sequenceDiagram
    participant Client as Management Client
    participant EthAgent as Ethernet Agent
    participant HAL as Ethernet HAL
    participant PSM as PSM

    Client->>EthAgent: Set Device.Ethernet.Interface.1.Enable=true (R-BUS)
    Note over EthAgent: Validate parameter & check dependencies
    EthAgent->>HAL: CcspHalEthSwSetPortAdminStatus(1, true)
    HAL-->>EthAgent: SUCCESS/ERROR status
    alt Configuration Success
        EthAgent->>PSM: Set dmsb.ethagent.if.1.Enable=true
        PSM-->>EthAgent: Storage confirmation
        EthAgent-->>Client: R-BUS method response (SUCCESS)
    else Configuration Error
        Note over EthAgent: Log error & maintain previous state
        EthAgent-->>Client: R-BUS method response (ERROR)
    end

Event Notification Flow - Interface Status Change:

sequenceDiagram
    participant HAL as Ethernet HAL
    participant EthAgent as Ethernet Agent
    participant WanMgr as WAN Manager
    participant Telemetry as Telemetry Agent

    HAL->>EthAgent: Interface callback: Link Down Event
    Note over EthAgent: Update internal state & validate change
    EthAgent->>WanMgr: R-BUS Event: Device.Ethernet.Interface.1.Status=Down
    EthAgent->>Telemetry: R-BUS Event: Interface statistics update
    WanMgr-->>EthAgent: Event acknowledgment (if required)
    Telemetry-->>EthAgent: Event acknowledgment (if required)

Implementation Details

Major HAL APIs Integration

The Ethernet Agent integrates with the Ethernet HAL through the ccsp_hal_ethsw.h interface, providing platform-independent access to Ethernet switching hardware. The HAL integration supports comprehensive interface management including administrative control, status monitoring, and statistics collection.

Core HAL APIs:

HAL API	Purpose	Implementation File
`CcspHalEthSwSetPortAdminStatus()`	Set interface administrative status (enable/disable)	`source/TR-181/board_sbapi/source-arm/cosa_ethernet_apis_arm.c`
`CcspHalEthSwGetPortStatus()`	Retrieve current interface operational status including link state, link rate, and duplex mode	`source/TR-181/board_sbapi/source-arm/cosa_ethernet_apis_arm.c`
`CcspHalEthSwGetEthPortStats()`	Collect comprehensive interface statistics (bytes, packets, errors)	`source/TR-181/board_sbapi/source-arm/cosa_ethernet_apis_arm.c`
`CcspHalEthSwGetPortCfg()`	Get interface configuration including link rate and duplex mode settings	`source/TR-181/board_sbapi/source-arm/cosa_ethernet_apis_arm.c`
`CcspHalEthSwGetPortAdminStatus()`	Get interface administrative status (up/down)	`source/TR-181/board_sbapi/source-arm/cosa_ethernet_apis_arm.c`
`CcspHalEthSw_RegisterLinkEventCallback()`	Register callback for asynchronous interface link status change notifications	`source/TR-181/middle_layer_src/cosa_ethernet_internal.c`
`GWP_RegisterEthWan_Callback()`	Register callbacks for Ethernet WAN link up/down events	`source/TR-181/middle_layer_src/cosa_ethernet_internal.c`
`CcspHalExtSw_getAssociatedDevice()`	Retrieve list of devices associated with Ethernet interfaces	`source/TR-181/board_sbapi/source-arm/cosa_ethernet_apis_arm.c`, `source/TR-181/board_sbapi/eth_hal_interface.c`

Key Implementation Logic

Interface State Management: The core state machine is implemented in cosa_ethernet_manager.c with interface state tracking, configuration validation, and event-driven status updates
- Main state machine thread execution in CcspEthManager_StateMachineThread() function started by CosaEthManager_Start_StateMachine()
- Interface configuration and retrieval logic in CosaDmlEthPortGetEntry() and CosaDmlEthPortSetCfg() functions (source-arm/cosa_ethernet_apis_arm.c)
- State transition handlers in EthInterface_SetParamBoolValue() and EthInterface_Validate() functions (cosa_ethernet_dml.c)
Event Processing: Hardware events from the HAL layer are processed asynchronously through multiple event handler threads and mapped to appropriate TR-181 parameter changes and R-BUS notifications
- Link status callback handling in CosaDmlEthPortLinkStatusCallback() function registered via CcspHalEthSw_RegisterLinkEventCallback()
- WAN link event callbacks EthWanLinkUp_callback() and EthWanLinkDown_callback() registered via GWP_RegisterEthWan_Callback()
- Event handler threads SysEventHandlerThrd() and CosaDmlEthEventHandlerThread() for processing queued events
- Asynchronous R-BUS event publishing in cosa_rbus_handler_apis.c
Error Handling Strategy: Comprehensive error detection and recovery with HAL error code mapping, automatic retry mechanisms, and detailed logging for troubleshooting
- HAL error code mapping in CosaDmlEthPortGetDinfo() and HAL status query functions with ANSC_STATUS/RETURN_OK return codes
- Recovery mechanisms for failed HAL operations with detailed error logging and fallback to previous known good state
- Interface availability checking with getIfAvailability() to handle NotPresent status for missing physical interfaces
Logging & Debugging: Multi-level logging with interface-specific debug categories, HAL API tracing, and runtime configuration for troubleshooting
- Interface state transition logging with COSA_LOG_LEVEL_INFO for normal operations
- HAL API call tracing with entry/exit logging for all HAL function calls
- Debug hooks for runtime troubleshooting including interface dump capabilities and state inspection

Key Configuration Files

Configuration File	Purpose	Override Mechanisms
`config/TR181-EthAgent.xml`	TR-181 data model definitions and function mappings	Compile-time feature flags: FEATURE_RDKB_WAN_MANAGER, AUTOWAN_ENABLE
`CcspEthAgent.cfg`	Component registration and R-BUS configuration; typically provided by the platform image or integration layer, not stored in this repository	Environment variables: CCSP_MSG_BUS_CFG, CCSP_CFG_PATH
`system_defaults`	Default interface configurations and PSM parameter values; typically provided by the platform image, build system, or companion repos, not stored in this repository	Build-time/integration configuration: --enable-wanfailover, --enable-dropearly

Note: In this repository, the documented configuration artifact present is config/TR181-EthAgent.xml. Files such as CcspEthAgent.cfg and system_defaults are deployment/platform integration artifacts and may be supplied by the target image, build environment, or other repositories.

Name		Name	Last commit message	Last commit date
Latest commit History 102 Commits
.github		.github
build_tools_workflows @ 3d000d7		build_tools_workflows @ 3d000d7
config		config
cov_docker_script		cov_docker_script
hal_schema		hal_schema
source		source
.gitmodules		.gitmodules
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
COPYING		COPYING
LICENSE		LICENSE
Makefile.am		Makefile.am
NOTICE		NOTICE
README.md		README.md
autogen.sh		autogen.sh
configure.ac		configure.ac

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Ethernet Agent

Design

Prerequisites and Dependencies

Component State Flow

Call Flow

TR‑181 Data Models

Supported TR-181 Parameters

Object Hierarchy

Parameter Definitions

Internal Modules

Component Interactions

Interaction Matrix

IPC Flow Patterns

Implementation Details

Major HAL APIs Integration

Key Implementation Logic

Key Configuration Files

About

Licenses found

Uh oh!

Releases 16

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Ethernet Agent

Design

Prerequisites and Dependencies

Component State Flow

Call Flow

TR‑181 Data Models

Supported TR-181 Parameters

Object Hierarchy

Parameter Definitions

Internal Modules

Component Interactions

Interaction Matrix

IPC Flow Patterns

Implementation Details

Major HAL APIs Integration

Key Implementation Logic

Key Configuration Files

About

Resources

License

Licenses found

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 16

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages