NetX Port Ether

Table of Contents

• NetX Port Ether Module Introduction
  • NetX Port Ether Module Features
• NetX Port Ether Module APIs Overview
• NetX Port Ether Module Operational Overview
  • NetX Port Ether Module Important Operational Notes and Limitations
    • NetX Port Ether Module Operational Notes
    • NetX Port Ether Module Limitations
• Including the NetX Port Ether Module in an Application
• Configuring the NetX Port Ether Module
• Using the NetX Port Ether Module in an Application

NetX Port Ether Module Introduction

The Azure RTOS NetX Port Ether module (sf_el_nx) for NetX and NetX Duo is integrated into the SSP. Its function is to interface the NetX and NetX Duo software with the Synergy hardware. This module includes the MAC driver, the PHY driver, additional glue logic and utility functions.

Note

Unless otherwise stated, there is no difference in how this module works between NetX or NetX Duo projects.

NetX Port Ether Module Features

• High-level interface for NetX and NetX Duo for the Synergy Platform
• Channel Selection
• PHY Reset support
• Static MAC Address configuration
• Dynamic MAC Address configuration
• Callbacks are provided for unknown packet reception
• Selectable Ethernet Interrupt Priority
• Link status monitoring support
• Configurable Number of Receive/Transmit Buffer Descriptors
• Supports the use of an external PHY chip

NetX Port Ether Module Block Diagram

NetX Port Ether Module APIs Overview

The NetX Port Ether module has a narrow API, used internally by NetX and by the module itself. It includes the Ethernet driver entry point (nx_ether_driver_eth0, nx_ether_driver_eth1), the Ethernet interrupt handler and other functions used internally by the module but externally visible.

NetX Port Ether Module Operational Overview

The NetX Port Ether module is a high-performance real-time implementation of the NetX Ethernet driver for the Renesas Synergy software and Synergy Ethernet IP.

Note

NetX assumes the existence of ThreadX and depends on its thread execution, suspension, periodic timers and mutual exclusion facilities.

Each IP instance in NetX has a primary interface which is identified by its device driver specified in the nx_ip_create service. The network driver is responsible for handling various NetX requests, including packet transmission, packet reception, and requests for status and control.

For a multi-home system, the IP instance can be configured for multiple interfaces, each with an associated network driver that performs these tasks for the respective interface. The network driver must also handle asynchronous events occurring on the media. Asynchronous events from the media include packet reception, packet transmission completion, and status changes. NetX provides the network driver with several access functions to handle various events. These functions are designed to be called from the interrupt service routine portion of the network driver. For IP networks, the network driver should forward all ARP packets received to the nx_arp_packet_deferred_receive internal function. All RARP packets should be forwarded to nx_rarp_packet_deferred_receive internal function. There are two options for IP packets:

If fast dispatch of IP packets is required, incoming IP packets are forwarded to nx_ip_packet_receive for immediate processing; this greatly improves NetX performance in handling IP packets. Otherwise, IP packets are forwarded to nx_ip_packet_deferred_receive. This service places the IP packet in the deferred processing queue where it is then handled by the internal IP thread, which results in the least amount of ISR processing time.

The network driver can also defer interrupt processing to run out of the context of the IP thread. In this mode, the ISR shall save the necessary information, call the internal function nx_ip_driver_deferred_processing, and acknowledge the interrupt controller. This service notifies IP thread to schedule a callback to the network driver to complete the process of the event that causes the interrupt.

Key Configuration Property Settings:

Multi-Channel

Multi-Channel determines which interface the ethernet driver is applied to. It may need to be modified from the default value of zero. See Section 5 "Configuring the NetX Port Ether".

Channel 0/1 Phy Reset Pin

PHY reset is supported through I/O port pins. This property depends on the value of the Channel property above. 

Note

For different Synergy Kits different I/O PINs are being utilized, for this purpose it may need to be modified from the default value. 

Static MAC Address Configuration

These properties set the device MAC address on the respective channel interface at compile time.  To set the MAC address at run time, see the description of the Dynamic MAC Address Configuration callback property below.

Dynamic MAC Address Configuration

This property defines the user defined callback function which sets MAC address at runtime (network link initialization). The default value is NULL and the MAC address is assigned using the Channel MAC Address High/Low Bits settings.

Unknown Ethernet Packet Receive Callback

This property configures callback for letting user process unsupported/custom EtherType packets.

This call-back can be used in conjugation with nx_ether_custom_packet_send Ethernet API to send and receive custom Ethernet packet types.

Name

This property names the instance of the NetX Port Ether driver. For an IP instance configured with multiple network interfaces, the application must add an instance of the driver and give it a unique name (or compile errors will result).  The default name is g_sf_el_nx. 

Ethernet Interrupt Priority

This property sets the driver interrupt priority. The default value is disabled. The dropdown list indicates valid and invalid priorities depending on the MCU target.

Link Status Monitoring

This property lets user choose link status monitoring method. There two options available: PHY Polling and PHY Interrupt (Uses LINKSTA Pin).

PHY polling utilizes an internal monitoring thread for auto negotiation to notify user when link is lost or established.

PHY Interrupt method requires PHY status pin to be connected to LINKSTA pin of Ethernet controller and utilize Ethernet interrupt to notify user when link is lost or established.

This notification though happens through the callback registered with IP instance.

Number of Receive/Transmit Buffer Descriptors

These properties set the number of buffer descriptors (BDs) for receiving and transmitting packets. When the Receive BDs are initialized, the driver allocates a packet for each BD. Therefore, the number of receive BDs should not deplete the IP instance packet pool from which it allocates packets. 

The NetX Port Ether driver supports packet chaining for both receiving and transmitting packets (where packets are chained in the application layer). If a packet is received on the network that exceeds the size of the IP default packet pool payload, the driver can allocate additional packets and process the incoming packet as a packet chain.  

Parameter Checking

This is low level error checking for each component of the project hardware layer. By default, it is set to Default (BSP) which means this property inherits the same property in the BSP.

NetX Port Ether Module Important Operational Notes and Limitations

NetX Port Ether Module Operational Notes

NetX Source Properties

There are two ways to modify NetX source properties- using the source code property directly in the source element or defining the source code symbol directly. For example, to change the number of physical network interfaces, one can either set the Maximum Physical Interfaces property in the NetX Source or NetX Duo Source element, or one can define the source code symbol NX_MAX_PHYSICAL_INTERFACES directly.  In either case, it is still necessary to include the NetX and NetX Duo Source component, generate the project files and to rebuild the NetX library.

TCP Options Field Parameters

Maximum Segment Size

The Maximum Segment Size (MSS) is the maximum amount of bytes a TCP host can receive without being fragmented by the underlying IP layer. During TCP connection establishment phase, both ends exchanges its own TCP MSS value, so that the sender does not send a TCP data segment that is larger than the receiver's MSS. NetX TCP module will optionally validate its peer's advertised MSS value before establishing a connection. By default NetX does not enable such a check.

The nx_tcp_socket_mss_set() API sets a specified socket's Maximum Segment Size (MSS).  The MSS value must be within the network interface IP Maximum Transfer Unit (MTU), allowing room for IP and TCP headers. This service should be used before a TCP socket starts the connection process. If the service is used after a TCP connection is established, the new value has no effect on the connection. To retrieve the MSS value use the nx_tcp_socket_mss_get() API after the TCP connection is established.

Using the External PHY with the NetX Port Ether Module

The NetX Port Ether Module can be used along with an external PHY chip, other than the on-board Micrel PHY chip (KSZ8081 and KSZ8091) found on Synergy Platform Kits. The following steps need to be performed to use a different external PHY chip:

1. Remove or undefine the macro BSP_BOARD_PHY_KSZ8081 or BSP_BOARD_PHY_KSZ8091 in the board BSP file (Example: For the S7G2_DK board, the BSP file is located in synergy/board/s7g2_dk/bsp_ethernet_phy.h).
2. Implement a new PHY driver for the specific PHY chip..Implement the functions defined in the interface file synergy/ssp/inc/framework/instances/sf_el_nx.h
3. Build and run the application

Note

 The above steps also apply to existing projects using an external PHY.

Additional Information

Refer to the NetX User Guide for the Renesas Synergy™ Platform and NetX Duo User Guide for the Renesas Synergy™ Platform for additionaloperational details.

NetX Port Ether Module Limitations

Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the NetX Port Ether Module in an Application

This section describes how to include the NetX Port Ether Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

The NetX Port Ether Framework is used as a lower level module and is not available to add as a separate stack. An example is illustrated in the following figure where a module must be selected to Add NetX Network Driver. The following figure shows the selection of the NetX Port Ether Framework to complete the stack for the module.

NetX Port Ether Module Stack

NetX Port Ether Module Stack

Configuring the NetX Port Ether Module

The NetX Port Ether Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the NetX Port Ether Module

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter checking.
Channel 0 Phy Reset Pin	IOPORT_PORT_09_PIN_03	Channel 0 Phy reset pin selection.
Channel 0 MAC Address High Bits	0x00002E09	Channel 0 MAC address high bits selection.
Channel 0 MAC Address Low Bits	0x0A0076C7	Channel 0 MAC address low bits selection.
Channel 1 Phy Reset Pin	IOPORT_PORT_07_PIN_06	Channel 1 Phy reset pin selection.
Channel 1 MAC Address High Bits	0x00002E09	Channel 1 MAC address high bits selection.
Channel 1 MAC Address Low Bits	0x0A0076C8	Channel 1 MAC address low bits selection.
Number of Receive Buffer Descriptors	8	Number of receive buffer descriptors selection.
Number of Transmit Buffer Descriptors	32	Number of transmit buffer descriptors selection.
Ethernet Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 lowest - not valid if using ThreadX) Default: Priority 12	Ethernet interrupt priority selection.
Link status monitoring method	PHY Interrupt (Uses LINKSTA Pin), PHY Polling Default: PHY Polling	PHY interrupt requires LINKSTA Pin connection to PHY.
Name	g_sf_el_nx	Module name.
Channel	0	Channel selection.
MAC address change callback	NULL	MAC address change callback selection.
Unknown packet receive callback	NULL	Unknown packet receive callback selection.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Family. Other MCUs may have different default values and available configuration settings.

Using the NetX Port Ether Module in an Application

The NetX Port Ether Module should be used in combination with NetX. Examples illustrating the modules use in an implementation for Auto-IP protocol use follow. Other protocols will follow a similar use flow. The steps performed by the Synergy Software Package (SSP) automatically in a NetX application support are:

1. Initialize the system with nx_system_initialize.
2. Create a packet pool with nx_packet_pool_create.  This creates the IP default packet pool, to be used by the IP instance and the ethernet driver. 
3. Create an IP Instance with nx_ip_create.
4. Enable ARP with nx_arp_enable.
5. Enable Link status change notify call back with nx_ip_link_status_change_notify_set.
6. Set gateway IP address for created IP instance nx_ip_gateway_address_set.
7. Create an AutoIP instance with nx_auto_ip_create.

The following steps are performed directly by the application to set up and run the Auto IP thread task.

1. Check if the network link is enabled with the nx_ip_interface_status_check API.
2. Verify the device does not have an IP address by calling the nx_ip_interface_address_get API.
3. Set the IP addreess notification callback by calling the nx_ip_address_change_notify API.
4. Start the Auto IP instance with the nx_auto_ip_start API.
5. Wait for the IP address change callback to set the flag that the IP instance has an IP address.
6. Stop the AutoIP task by calling the nx_auto_ip_stop API.
7. Verify the IP instance has a non-zero IP address by calling the nx_ip_interface_address_get API again.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical NetX Port Ether Module Application