4.7.6.1. Enet LLD NETCONF User’s Guide

4.7.6.1.1. Pre-requisites

Reader are expected to have basic knowledge of the following IETF Standards - Network Configuration Protocol - NETCONF (RFC 6241)

  • Using the NETCONF Protocol over Secure Shell (RFC 6242)

  • Using the NETCONF Protocol over Transport Layer Security with Mutual X.509 Authentication (RFC 7589)

  • The YANG 1.1 Data Modeling Language (RFC 7950)

4.7.6.1.2. Introduction

This guide is intended to enhance user’s understanding of the NETCONF Server module, which is included in the TSN stack package. It also provide guidance to user on how to seamlessly integrate NETCONF into their own applications.

4.7.6.1.3. TSN Stack

As part of TSN stack package, it is implemented to work along side other TSN module. NETCONF manages the device configurations with the help of Universal Configuration (UNICONF) daemon, which is a YANG-based configuration library used by all TSN modules.

For more details about other TSN module, please see TSN source modules.

4.7.6.1.3.1. Stack Initialization

Same with other TSN stack modules, TSN Stack needs to be initialized before NETCONF server task can be started.

For details, please refer to TSN Stack Initialization.

4.7.6.1.3.2. NETCONF source modules

NETCONF implementation and example is provided by the following source modules:

  • tsn_netconf: Implementation of the RFC 6241 AS Network Configuration Protocol (NETCONF).

  • enet_tsn_netconf_example: Example application for showing how to use NETCONF with gPTP TSN module.

4.7.6.1.3.3. NETCONF Logging

As part of TSN stack package, NETCONF uses the same logging mechanism as other TSN stack modules.

By default, log level is initialized as follows in tsninit.c, :

TSNAPP_LOGLEVEL “4,ubase:45,cbase:45,uconf:45,gptp:55,lldp:45,avtp:45,nconf:45”
initPara.ub_log_initstr = TSNAPP_LOGLEVEL;

In the above example, nconf:45 signifies the following:

  • nconf : prefix shown in logs for NETCONF related modules. For example :

    INF:nconf:nconf_msghdlr_main_loop:Started

  • 4 (INFO): Log level for printing to the console.

  • 5 (INFOV): Log level for storing in internal memory (which can be dumped to a file).

For more details regarding TSN stack logging, please refer to TSN Logging.

4.7.6.1.4. Integration

4.7.6.1.4.1. Source integration

NETCONF needs both the TSN stack and a TCP/IP stack which is provided by LWIP in TI FreeRTOS. It is advisable to read the following integration guide to have some background about the information discussed below.

To integrate the NETCONF stack into your application, both TSN Stack and LWIP needs to be initialized without conflicting each other.

The initialization routines found at <enet>/examples/enet_tsn/enet_tsn_netconf_example/ncapp_main.c can be used as reference for the following information.

  • After the usual board initialization routines, to support persistent configuration, and the <get-schema> NETCONF RPC protocol operation, filesystem needs to be supported and initialized. For this we can use the existing MMCSD module available in pdk. To initialized MMCSD, please see EnetApp_initMMCSD(), which can be called as follows:

    /* Initialize MMCSD Driver */
status = EnetApp_initMMCSD();
EnetAppUtils_assert(status == ENET_SOK);
EnetAppUtils_print("%s: EnetApp_initMMCSD() done\n", __func__);

  • After the above, LWIP stack needs to be initialized first by calling EnetApp_initLwIP(). This initializes the LWIP’s TCP/IP stack as well as calling the necessary callbacks to initialize and open UDMA LLD and Enet LLD:

    /* Initialize LwIP stack - w/c will open Enet and UDMA LLD */
EnetApp_initLwIP();
EnetAppUtils_print("%s: EnetApp_initLwIP() done\n", __func__);

  • After LWIP initialization, TSN Stack should be initialize by calling EnetApp_initTsnByCfg(). This should be perform prior to calling any TSN module APIs:

    if (EnetApp_initTsnByCfg(&appTsnCfg) < 0)
{
    EnetAppAbort("Failed to tsn_app_init!\n");
}

After the above, UNICONF and NETCONF daemon can already be spawn. However, to be able to load other TSN modules the following initialization needs to be performed.

  • Ethernet device table in combase needs to be initialize, but with a few key difference as shown below:

    for (i = 0; i < gEnetAppCfg.numEthPorts; i++)
{
    snprintf(&gEnetApp_netDevs[i][0], CB_MAX_NETDEVNAME, "tilld%d", i);
    appTsnCfg.netdevs[i] = &gEnetApp_netDevs[i][0];
    ethdevs[i].netdev = gEnetApp_netDevs[i];
    ethdevs[i].macport = gEnetAppCfg.ethPorts[i].macPort;
    if (i == 0)
    {
        /* tilld0 reuses the allocated source mac, other interfaces will allocate
         * the mac by themself */
        memcpy(ethdevs[i].srcmac, &gEnetAppObj.macAddr[0U], ENET_MAC_ADDR_LEN);
    }
}

cb_lld_init_devs_table(ethdevs, i, enetType, instId);

    • Since LWIP initializes Enet LLD, it also acquire a MAC address for the port used during initialization. To re-use this in combase, we need to copy gEnetAppObj.macAddr[0U], which is the MAC address acquired during LWIP initialization, to the Ethernet device table that will be used for combase initialization.

    • This will let cb_lld_init_devs_table skip allocating new MAC address for one of the virtual Ethernet device.

4.7.6.1.5. Starting NETCONF Daemon

Similar to other TSN Stack modules, NETCONF deamon can be started by adding NETCONF_ENABLED`` to the application compile flags and calling EnetApp_startTsn(). EnetApp_startTsn() ensures that UNICONF is spawned and ready before spawning other modules task.

For the following discusion, please see EnetApp_netconfTask() implemented in <enet>/examples/enet_tsn/enet_tsn_netconf_example/netconf_init.c for reference.

4.7.6.1.5.1. NETCONF server options

NETCONF deamon uses the following config options:

typedef struct nconfopt{
    nconf_transopt_t sopt;
    nconf_ucclopt_t ucclopt;
    uint16_t dlogmem;
    char *dlogfile;
    bool ishelp;
} nconfopt_t;

Currently only the ucclopt is used in TI FreeRTOS which contains the UNICONF client options shown below:

typedef struct {
    char *dbname;
    char *schemadir;
    bool ucthread;
} nconf_ucclopt_t;

Where:

  • dbname: Specify the path of database file in the file system. This should be the same database file configured for UNICONF daemon.

  • schemadir: Specify the path where the xmlsafe schema files are located in the file system. This is used during <get-schema> RPC operation, where NETCONF server sends the Yang schema file to the client when requested. Yang Schema supported by UNICONF is provided in <enet>/examples/enet_tsn/schemas.

  • ucthread: Specify whether UNICONF is run on thread mode. This is always True in TI FreeRTOS environment.

4.7.6.1.5.2. NETCONF server init functions

There are three functions needs to be called to initialized NETCONF components before starting NETCONF’s Message Handler main loop.

  • nconf_ucclient_init() - Initializes NETCONF’s Uniconf Client component, which handles communication with UNICONF daemon.

  • nconf_msghdlr_init() - Initializes NETCONF’s Message Handler component, which handles incoming client events.

  • nconf_transport_init() - Initializes NETCONF’s Transport Manager component, which initializes and uses LWIP’s altcp callbacks for accepting and receiving request from TCP/IP NETCONF clients and forwards this request to Message Handler

4.7.6.1.5.3. NETCONF Server Message Handler Main Loop

Once, all initialization suceeded, nconf_msghdlr_main_loop() can be called to start processing NETCONF client messages.

Note

nconf_msghdlr_main_loop() is a blocking function and will not return unless stopped.

4.7.6.1.6. Stoping and Deinitializing NETCONF Server

To unblock and stop Message Handler’s main loop call nconf_msghdlr_stop().

After stopping main loop, the following functions need to be called to clean-up and release all resource use by NETCONF module.

  • nconf_msghdlr_deinit() - deinitilizes and clean-up resources used by NETCONF’s Message Handler.

  • nconf_ucclient_cleanup() - deinitilizes and clean-up resources used by NETCONF’s uniconf client.

4.7.6.1.7. NETCONF Client Interoperability

Due to the limitation discussed in Transport Protocol Requirements, there is no out of the box NETCONF clients that support unsecured TCP/IP transport. But there is one client available, netconf-client PyPi, that can be configured to use unsecured TCP/IP Transport.

In the TSN example application directory, a sample GUI based client was provided to show how to configure and use netconf-client PyPi.

<enet>/examples/enet_tsn/enet_tsn_netconf_example/netconf_client.

Please refer to TsnNetconfClient::connect_tcp() method in the tsn_ncclient.py python file for an example on how to use unsecured TCP/IP Transport in netconf-client PyPi.

Note

netconf_client above is NOT part of the TSN NETCONF stack and provided as-is. It was provided to use as reference for netconf-client PyPi usage.

4.7.6.1.7.1. Running the NETCONF Client (GUI application)

4.7.6.1.7.1.1. Prerequisites

Install pip module required by the application:

$ pip3 install netconf-client PySide6 lxml
Where:
netconf-client - A NETCONF client for Python 3.6+.
PySide6 - GUI Python Framework.
lxml - For xml processing.

Depending on OS where you will run the client, PySide might need some additional package to run, below are package needed to run PySide based GUI in Ubuntu-22.04:

$ sudo apt update && sudo apt install -y \
  python3 python3-pip dbus-user-session libglib2.0-0 \
  libgl1 libegl1 libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 \
  libxcb-keysyms1 libxcb-shape0

4.7.6.1.7.1.2. Connecting to DUT’s NETCONF Server

Once all requirement are install, run the client application as follows:

$ ./tsn_ncclient_app.py

A login window should appear as follows:

../../_images/ug_tsn_netconf_client_login_window.png

Note

For now, only the TCP transport is usuable in TI FreeRTOS.

Provide the IP address of the DUT in NETCONF Server Host, and input any arbitrary Username then click Connect.

../../_images/ug_tsn_netconf_client_data_window.png

If connection is successful, a data window, similar to the above, containing all Yang configurations that UNICONF manage should appear.

Note

In the above image, the data appears in the Config and Status tab are results from NETCONF’s <get-config> and <get> operation respectively.

4.7.6.1.7.1.3. Updating DUT’s Configuration via NETCONF

To perform edit-config RPC, click on Edit-Config button located in Config Tab.

../../_images/ug_tsn_netconf_client_edit_config_window.png

A window with a text box should appear, where user can input or load from a file the xml data representation of the Yang config data to be updated. For example:

<?xml version='1.0' encoding='UTF-8'?>
<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <ptp xmlns="urn:ieee:std:1588:yang:ieee1588-ptp-tt">
        <instances>
            <instance>
                <instance-index>0</instance-index>
                <default-ds>
                    <priority1>255</priority1>
                    <priority2>254</priority2>
                </default-ds>
            </instance>
        </instances>
    </ptp>
</data>

This data is taken from a template (Skeleton) XML files available in the following directory, for each Yang modules supported by UNICONF.

<tsn-stack>/tsn_uniconf/yangs/tree_xml/<yang-module>-skelton.xml.

After provide filling-up the text box, click on Send to perform the operation. When <edit-config> operations is successful, a dialog box with successful status should appear as shown above.

Note

NOT all data in UNICONF is editable via NETCONF. Please refer to Configuration vs Status Data section for details.

4.7.6.1.7.1.3.1. Configuration vs Status Data

YANG can model state data, as well as configuration data, based on the “config” statement in its Yang schema. Status Data are read-only (ro) data and are not editable through <edit-config> RPC. For quick checking to know which data are read-only (ro) and which are editable (rw) via <edit-config> RPC, please refer to each module’s .tree file, located in the following location:

<tsn-stack>/tsn_uniconf/yangs/tree_xml/<yang-module>.tree

For example, in <tsn-stack>/tsn_uniconf/yangs/tree_xml/ieee1588-ptp-tt.tree, we can see the following config leaves:

module: ieee1588-ptp-tt
  +--rw ptp
     +--rw instances
     |  +--rw instance* [instance-index]
     |     +--rw instance-index               uint32
     |     +--rw default-ds
     |     |  +--ro clock-identity?                        clock-identity
     |     |  +--ro number-ports?                          uint16
     |     |  +--rw clock-quality
     |     |  |  +--rw clock-class?                  identityref
     |     |  |  +--rw clock-accuracy?               identityref
     |     |  |  +--rw offset-scaled-log-variance?   uint16
     |     |  +--rw priority1?                             uint8
     |     |  +--rw priority2?                             uint8
     |     |  +--ro domain-number?                         uint8
     ...

In the above snippet, we can tell that clock-identity, number-ports, and domain-number are status data and not editable by <edit-config> RPC.

4.7.6.1.8. RFC 6241 Support

4.7.6.1.8.1. Transport Protocol Requirements

For description and more details regarding each Transport Protocol Requirements please refer to section 2 of RFC 6242.

Requirement

Supported

Connection-Oriented Operation

Yes

Authentication, Integrity, and Confidentiality

No

Mandatory Transport Protocol

No

Currently, the NETCONF server, describe in this integration guide uses an unsecured TCP (plaintext) connection as transport which is a non standard transport.

Message Encoding follows the encoding described in NETCONF over SSH (RFC 6242) and NETCONF over TLS (RFC 7589) but due to lack of necessary libraries in pdk, the required secured transport cannot be supported at this time in TI FreeRTOS.

4.7.6.1.8.2. Protocol Operations Supported

For description and more details regarding each RPC Operations, please refer to section 7 of RFC 6241.

RPC

Supported

get

Yes

get-config

Yes

edit-config

Yes

copy-config

No

delete-config

No

lock

No

unlock

No

close-session

Yes

kill-session

Yes

commit

No

discard-changes

No

cancel-commit

No

validate

No

get-schema

Yes

Note

<get-schema> is from RFC6022 IETF NETCONF Monitoring support.

4.7.6.1.8.3. NETCONF Capabilitities Support

For description and more details regarding each capabilities, please refer to section 8 of RFC 6241.

Capability

Supported

Writable-Running

Yes

Candidate Configuration

No

Cofirmed Commit

No

Rollback-on-Error

No

Validate

No

Distinct Startup

No

URL

No

URL

No

XPath

No

4.7.6.1.9. NETCONF Build Configurations

NETCONF server, there are several build configuration that affects server behavior, please refer to the following file for brief description of each.

<tsn-stack>/tsn_netconf/src/common/nconf_config.h.

To support TI Jacinto use case, the following configuration is updated:

  • NCONF_ENABLE_TCP_PLAINTEXT was enabled in TI Jacinto Support due to lack of TLS libraries in pdk. In this mode the port specified in NCONF_SUB_TRANSPORT_PORT is used by DUT to listen for incomming connection from client.

  • NCONF_GEN_ALLOC_FRAGMENTS and NCONF_MAX_UCCFG_INFO_NUM was increased to support the number of yang configs present in CPSW9G.

4.7.6.1.10. Memory footprint

The memory footprint is extracted from the map file.

The size of the modules in bytes when built in release mode:

Code

RO data

RW data

unibase

5252

1086

5473

combase

11488

3329

96008

uniconf

67538

25347

128848

gptp

73096

14404

114043

netconf

56590

12573

56313

pugixml

51968

4933

28

The size of the modules in bytes when built in debug mode:

Code

RO data

RW data

unibase

5732

1086

5473

combase

12816

3329

96008

uniconf

72996

25344

128848

gptp

77510

13803

114043

netconf

68132

12580

56313

pugixml

86322

4968

28

4.7.6.1.11. Limitations

As mentioned in Transport Protocol Requirements above, the current NETCONF server implementation uses Unsecured TCP/IP (Plaintext) as transport which might limit the NETCONF clients available for interoperability test.