GOAL media (goal_media)

The directory goal_media contains:

  • media adapters: generic driver interfaces

  • media interfaces: generic interfaces between media adapters and higher layers


One source and one header files exist for each GOAL media module. Only the sources for the necessary GOAL media modules shall be integrated in the compiler-project of the GOAL system. The registration is described in Chapter: Platform API. The functions are described in detail in the GOAL Reference Manual.
Figure 21 demonstrates the easy exchange of drivers.

 


Figure: media adapter for SPI

Nonvolatile storage


GOAL provides a media adapter and media interface for the nonvolatile storage usable for program downloads and uploads by a bootloader or for the nonvolatile storage of configuration data. The nonvolatile storage media allows:

  • to write data to the nonvolatile memory,

  • to read data from the nonvolatile memory and

  • to erase the nonvolatile memory.

NVS media interface


The media adapter is registered to the media interface by function goal_miNvsReg(). The resource "NVS media interface" must be allocated by function goal_miNvsAlloc(). The media interface is freed by function goal_miNvsFree().
The media interface allows to manage single memory ranges, called regions. Therewith it is possible to assign different memory ranges to various processes and to control the access to the nonvolatile memory process-specific. Each region is identified by an ID, called MI-NVS-REGION-ID, unique. This ID can be specified application-specific. But each ID must only exist once. During registration a unique handle is created for each MI-NVS-REGION-ID. Each region has to be registered to the media interface for nonvolatile storage by higher layers in the state GOAL_FSA_INIT. A region has the following properties:

Table: properties of NVS regions

Property of NVS region

Description

Property of NVS region

Description

offset

start address of the memory region, value range: uint32_t

length

length of the memory region in bytes, value range: uint32_t

strName

name of the file for the nonvolatile storage about the file system for each memory region, strName is a zero-terminated string of the length of GOAL_MI_REGION_NAME_LENGTH in bytes (default: 255 byte)

mode

storage mode:

  • GOAL_MI_NVS_REGION_MODE_COMPLETE:

    • load/save the complete memory region

  • GOAL_MI_NVS_REGION_MODE_STREAM:

    • load/save single data within the memory region, data is addressable about an additional offset

  • GOAL_MI_NVS_REGION_MODE_BUFFERED:

    • load/save to this region is handled through a memory buffer. Writing to the physical medium is decoupled by sequentially writing elements.

access

access right at the region:

  • GOAL_MI_NVS_REGION_ACCESS_READ:

    • region is only readable

  • GOAL_MI_NVS_REGION_ACCESS_WRITE:

    • region is writable and readable

Implementation guidelines

Registration of a memory region

 

  1. Specify a region and define a MI-NVS-REGION-ID:

    #define GOAL_ID_MI_NVS_REGION_CONFIG_DATA 2

     

  2. Create a MA-handle:

    GOAL_MA_NVS_T *pMaNvs;

     

  3. Select the suitable NVS driver and initialize the driver. The driver registers to the media adapter by itself.

  4. Create a MI-handle:

    GOAL_MI_NVS_T *pMiNvsHdl;

     

  5. Register the media interface:

     

  6. Allocate the NVS service:

     

  7. Create a MI-NVS-REGION-handle:

     

  8. Register and configure the memory region: The memory range starts at address 0x0001FFF and has a length of 0x100 byte. The region shall complete. Configurtion data shall be read and written.

 

Write data to nonvolatile memory

  1. Load MI-NVS-REGION-handle of the memory region with the ID GOAL_ID_MI_NVS_REGION_CONFIG_DATA:

     

  2. Erase the nonvolatile memory region:

     

  3. Write data of size bytes to nonvolatile memory region:

 

Read data from nonvolatile memory

 

  1. Load MI-NVS-REGION-handle of the memory region with the ID GOAL_ID_MI_NVS_REGION_CONFIG_DATA:

     

  2. Read data from nonvolatile memory:

NVS media adapter


The selected NVS driver registers itself to the NVS media adapter.

Implementation guidelines

 

These implementation guidelines refer to the case, that no NVS media interface is used.

 

Write data to nonvolatile memory

 

  1. Create a MA-handle:

     

  2. Select the suitable NVS driver and initialize the driver. The driver registers to the media adapter by itself.

  3. Create a NVS description:

     

  4. Erase 0x100 bytes in the nonvolatile memory from start address 0x0001FFF:

     

  5. Write 0x100 bytes from the buffer pData to the nonvolatile memory on start address 0x0001FFF:

 

Read data from nonvolatile memory

 

  1. Create a MA-handle:

     

  2. Select the suitable NVS driver and initialize the driver. The driver registers to the media adapter by itself.

  3. Create a NVS description:

     

  4. Read 0x100 bytes from the start address 0x0001FFFF in the nonvolatile memory and store the data in pData:

LED


GOAL provides a media adapter for the controlling of LEDs. Standardized communication protocols often need status LEDs. The application can also use the LED media adapter to control LEDs application-specific. The media adapter for LEDs allows to handle

  • single LEDS and

  • groups of LEDs


The used hardware resources for the controlling of LEDs are encapsulated in the LED driver and depends on the platform. Details are described in the suitable GOAL Platform Manual. It is possible to control the LEDs via GPIOs or about a serial bus as IIC.
The media adapter provides the following functionality:

  • open/close a media adapter for a single LED or a group of LEDs,

  • get/set the state of a single LED,

  • get/set the state of a group of LEDs.

The get-functions require, that the current LED state is readable from the platform.
The connection between the LED driver and the LED media adapter is identified by a MA-ID unique. The determination of the MA-ID is described in the suitable GOAL Platform Manual. The most LED drivers uses a MA-ID created by the application. The application has to assign single LEDs and/or groups of LEDs to MA-IDs during the platform initialization in the state GOAL_FSA_INIT.
A group of LEDs can consist of maximal 32 LEDs. The mask and state value have data type uint32_t and are bit-coded. Each LED in the LED group shall use the same bit position in the mask and state value. The interpretation of the bit values of the LED states is platform-specific. Maybe the application has to consider the polarity of the LEDs. The bit values for the mask are defined as follow:

Table: mask bit coding for groups of LEDs

Bit value

Meaning for LED group mask

Bit value

Meaning for LED group mask

0

LED is ignored and remains unchanged

1

LED is changed according to the desired state bit

Implementation guidelines

Switch on/off and get the state of a single LED

 

  1. Define a MA-ID for a single LED:

     

  2. Call the LED driver function to initialize the LED hardware resource and to register the LED driver for a single LED to the LED media adapter in state GOAL_FSA_INIT.

  3. Open a media adapter instance and get the MA-SPI handle:

     

  4. Switch on the LED:

     

  5. Get the current state of the LED:

     

  6. Close the media adapter instance:

Switch on/off and get the state of a LED group


A group of 32 LEDs shall be controlled.

  1. Define a MA-ID for a group of LEDs:

     

  2. Call the LED driver function to initialize the hardware resource for all LEDs and to register the LED driver for a group of LEDs to the LED media adapter in state GOAL_FSA_INIT.

  3. Open a media adapter instance and get the MA-SPI handle:

     

  4. Switch on the LEDs assigned to bit 31-24, do not change the LEDs assigned to bit 23-16, switch off LEDs assigned to bit 15-0:

     

  5. Get the current state of all LEDs in the LED group:

     

  6. Close the media adapter instance:

SPI


GOAL provides a media adapter for the SPI communication. The media adapter provides the following functionality:

  • open/close a media adapter for a SPI-channel

  • get/set a general SPI-configuration

  • read data from the SPI-bus

  • write data to the SPI-bus

  • write and read data to/from the SPI-bus

  • report events to higher layers


GOAL defines the following general SPI configuration settings:

Table: general SPI configuration settings

SPI configuration setting
according to GOAL_MA_SPI_CONF_T

Description

SPI configuration setting
according to GOAL_MA_SPI_CONF_T

Description

type

type of the SPI communication:

  • GOAL_MA_SPI_TYPE_MASTER,

  • GOAL_MA_SPI_TYPE_SLAVE

mode

combination of clock polarity and phase as SPI mode:

  • GOAL_MA_SPI_MODE_0,

  • GOAL_MA_SPI_MODE_1,

  • GOAL_MA_SPI_MODE_2,

  • GOAL_MA_SPI_MODE_3

bitrate

SPI baudrate in Hz

unitsize

size of transferred data must be a multiple of unitsize:

  • GOAL_MA_SPI_UNITWIDTH_8BIT,

  • GOAL_MA_SPI_UNITWIDTH_16BIT,

  • GOAL_MA_SPI_UNITWIDTH_32BIT
    The minimal size must be equal to the data transfer length of the SPI controller at least.

bitorder

bit order of the transferred data via the SPI bus:

  • GOAL_MA_SPI_BITORDER_MSB,

  • GOAL_MA_SPI_BITORDER_LSB


The SPI-configuration can be set by function goal_maSpiConfigSet(). The current SPI-configuration can be read by function goal_maSpiConfigGet(). The support of the SPI configuration settings depends on the SPI driver and the SPI controller. Details are described in the suitable GOAL Platform Manual.
SPI events are handled event-driven about an application-specific callback function. The supported events depend on the SPI driver and the availability on the SPI controller. GOAL provides the following events:

Table: general SPI events

Event number
according to GOAL_MA_SPI_EVENT_T

Description

Event number
according to GOAL_MA_SPI_EVENT_T

Description

GOAL_MA_SPI_EVENT_TRANSFER_COMPLETE

The SPI controller reports, that the data transfer is completed.

GOAL_MA_SPI_EVENT_TRANSFER_ABORTED

The SPI controller reports, that the data transfer is aborted.

GOAL_MA_SPI_EVENT_MODE_FAULT

The SPI controller reports an error during configuration of the platform-specific SPI mode.

GOAL_MA_SPI_EVENT_READ_OVERFLOW

The SP controller reports a read overflow.

GOAL_MA_SPI_EVENT_ERR_PARITY

The SPI controller on the platform repots a parity error.

GOAL_MA_SPI_EVENT_ERR_DATA_CONSISTENCY

The SPI controller on the platform supports a data consistency check. The data consistency check is active and reports an error.

GOAL_MA_SPI_EVENT_ERR_OVERFLOW

The SPI controller works in a buffered mode and reports an overflow of the buffers.

GOAL_MA_SPI_EVENT_ERR_OVERRUN

The SPI controller reports an overrun during reception of data.

GOAL_MA_SPI_EVENT_ERR_BUF_OVERRUN

The internal SPI message buffer in the driver overflows.

GOAL_MA_SPI_EVENT_ERR_FRAMING

The SPI controller reports a framing error.

GOAL_MA_SPI_EVENT_MODE_UNDERRUN

The SPI controller reports an underrun, if it works as SPI slave and no transmission data are prepared and a serial transfer was initiated by the SPI master.


The connection between the SPI driver and the SPI media adapter is identified by a MA-ID unique. The determination of the MA-ID is described in the suitable GOAL Platform Manual. The most SPI drivers determine the MA-ID by itself.

Callback functions


Table: Callback functions

Prototype

GOAL_STATUS_T cbMaSpiEvent(struct GOAL_MA_SPI_T *pMaSpiHdl, GOAL_MA_SPI_EVENT_T event, void *pArg)

Description

This callback function is called if an SPI event was occurred in the SPI driver to inform higher layers.

Parameters





pMaSpiHdl

handle of the media adapter

event

number of the occurred event, see Table 11

pArg

specific arguments used by the callback function

Return values

GOAL return status, see Chapter: GOAL status

Category

mandatory

Registration

during runtime about function goal_maSpiOpen()

Implementation guidelines

Read and write data via the SPI-bus

 

  1. Call the SPI driver function to initialize the SI controller and to register the SPI driver to the SPI media adapter in state GOAL_FSA_INIT. During this guideline GOAL_MA_ID_SPI is used to mark the MA-ID. During the registration a unique MA-SPI handle is created.

  2. Implement a callback function to handle SPI events:

     

  3. Open the media adapter, specify the callback function to handle SPI events and get the MA-SPI handle:

     

  4. Write 4 byte stored in pData to the SPI-bus:

     

  5. Read data from the SPI-bus and store the data to pData:

     

  6. Write 4 byte stored in pWriteData to the SPI-bus and read data from SPI-bus and store the read data to pReadData at the same time:

Configure the SPI interface

 

  1. Get the current general SPI configuration of an opened MA:

     

  2. Specify SPI mode 0:

     

  3. Set SPI configuration:

Handle SPI events

 

  1. Call the SPI driver function to initialize the SI controller and to register the SPI driver to the SPI media adapter in state GOAL_FSA_INIT. During this guideline GOAL_MA_ID_SPI is used to mark the MA-ID. During the registration a unique MA-SPI handle is created.

  2. Implement a callback function to handle SPI events:

     

  3. Open the media adapter, specify the callback function to handle SPI events and get the MA-SPI handle:

     

  4. If a SPI event occurs, the callback function cbApplMaSpiEvent is called.

TLS


GOAL provides a functionality for encryption and authentication of TCP packets on the base of the Transport Layer Security (TLS) protocol /TLS_RFC_5246/. The functionality of TLS requires:

  • a TLS library,

  • a GOAL driver for the integration of the TLS library into the GOAL system,

  • a GOAL media adapter for TLS in order to use a generic interface for TLS in GOAL and.

  • a GOAL media interface for TLS to handle TLS connections in a driver independent abstract layer.

GOAL allows to implement various libraries for cryptographic and transport layer security capabilities. The GOAL TLS media adapter makes it possible to exchange the TLS library with less effort. The TLS functionality is embedded into the GOAL core module for the network handling.
The TLS functionality comprises:

  • encryption/decryption of TCP packets and

  • the authentication by a X509-certificate.

 


Figure: integration of TLS


The authentication is realized by a X509-certificate. The application can specify an own private key and an own X509-certificate by function goal_miTlsOpen(). The private key must have a length between 1024 bit and 2048 bit. If no X509-certificate is specified a default certificate is taken. The default certificate is port-specific.
The GOAL TLS media adapter allows:

  • to open/close a GOAL TLS channel and

  • to get information from the X509-certificate about the certification authority, the organization providing the web-server and the validity period

The encryption and decryption are made by the TLS library internally.

  • example:

    • …\goal\appl\00410_goal\tls*

Configuration


The following compiler-defines are available to configure TLS:

  • GOAL_CONFIG_TLS:

    • 0: TLS is disabled (default)

    • 1: TLS is enabled

mbed TLS library


GOAL supports the open source library mbed TLS. The following sources must be added to the compiler-project:

Table: mbed TLS libary

source

location

source

location

mbed TLS library

…\goal\ext\mbedtls*

GOAL driver for the mbed TLS library

…\goal\plat\drv\tls\mbedtls

GOAL example certificates and key

…\goal\plat\drv\tls\generic

 

The GOAL driver for the mbed TLS library provides the following function for the registration to the GOAL TLS media adapter:

Table: goal_tlsMbedtlsInit

Prototype

GOAL_STATUS_T goal_tlsMbedtlsInit(GOAL_MA_TLS_T **ppTlsHdl, unsigned int maId)

Description

This function registers the GOAL driver for the mbed TLS library, i.e. the driver functions for initialization, opening a TLS channel and getting information from X509v3-certificate are made known in the GOAL TLS media adapter.

Parameters



ppTlsHdl

handle for the TLS instance

maId

MA-ID for the TLS instance

Return values

GOAL return status, see Chapter: GOAL status

Calling

in state GOAL_FSA_INIT_GOAL, stage GOAL_STAGE_TARGET_PRE
(normally during the board initialization, see goal_target_board.c/goal_targetBoardInit() )


The application has to specify a MA-ID. There is no driver-specific rule for the construction of the MA-ID.
The execution of the algorithm for encryption/decryption needs some time and is processed in an own task to allow, that the algorithm can be interrupted by functions with higher priority. This method requires an operating system.
Further the application has to specify a MI-ID. This can be the same as the MA-ID This allows to switch between differnt TLS drivers more easily. The opening function of the GOAL TLS media is executed by function goal_miTlsOpen(). The application has to call the function goal_miTlsOpen() in the state GOAL_FSA_INIT_SETUP to initialize and to open the channels.
The function for getting information from the X509-certificate the GOAL TLS driver function is mapped to the function goal_miTlsReadInfo(). The function goal_miTlsReadInfo() is called by the application in the state GOAL_FSA_OPERATION.

Implementation guidelines

Initialize TLS


This example uses the mbed TLS library.

  1. Define both a MA-ID and a MI_ID.

     

  2. Integrate the initialization of the GOAL TLS media adapter in the stage GOAL_STAGE_MODULES in application-specific function appl_setup(). Here a certificate structure may be given to the media adapter. If no is given, the media adapter uses a default certificate.

     

  3. Create a GOAL net channel for the output of the GOAL TLS media adapter.

     

  4. Configure the GOAL net channel as non-blocking.

     

  5. Get the handle for the TLS session determined by the MI-ID and open the TLS channel.

     

  6. Connect the GOAL net channel (TLS) to the GOAL net channel and specify a callback function to handle packets from the TCP client.

     

  7. Create a callback function to handle packets from the TCP client, see Chapter: Callback functions: cbNetFunc().

Use a TLS channel

  1. TCP/IP packets are transmitted and received encrypted. Only valid TCP/IP packages pass the TLS module.

  2. Information from the certificate can be required.

CMFS


CMFS is a media interface working on top of the NVS media interface. It requires 2 serparate NVS regions for storing CM variables. Despite the plain CM implementation, which stores the whole CM variable store as a binary blob in flash, CMFS only writes modifications to the NVS region. Thereby the NVS region is sequientially written, thus a time consuming erase of the NVS region is not required. However if the NVS region is nearly fully written, the current state of variables is transferred to the secondary NVS region, where all continuing write operations take place.
This CMFS has some advantages over the plan CM implementation:

  • NVS write operations can be performed much faster

  • Data loss during reset while NVS is written can be omitted


To achive this, more NVS storage space needs to be reserved.

When CMFS is enabled, the NVS region with ID GOAL_ID_MI_NVS_REGION_CMCONFIG is not required anymore.

Integration of CMFS


Following except from goal_target_board.c shows integration of CMFS.


In order to utilize CMFS, the following configuration option must be enabled.

  • GOAL_CONFIG_MEDIA_MI_CMFS:

    • 0: CMFS is not utilized (default)

    • 1: CMFS is utilized

This configuration option and the required files are added when the following feature is enabled in the Makefile, when using the GOAL build system:

Ethernet Frame Handler

Introduction

 

GOAL provides a Media Interface and Adapter for Ethernet based data exchange and protocols like HTTP or EtherCAT over Ethernet, see Figure 11.
The Ethernet Frame Handler in the Media Interface receives all Ethernet frames through the generic Ethernet Media Adapter and the Ethernet driver. The frame processing load can be reduced by activating the MAC address filtering by the compiler-define GOAL_CONFIG_MAC_ADDR_FILTER. Then only all broadcast/multicast and the own unicast Ethernet frames pass the MAC filter and are received. This is only a software filter, which drop packets not directed to the device.
The Ethernet Frame Handler identifies received Ethernet frames on base of the

  • MAC address

  • the Ether Type


The values for the Ether Type are standardized in IEEE 802.3. GOAL supports the following Ether Types:

  • 0800h: IP Internet Protocol, version 4 (IPv4)

  • 0806h: Address Resolution Protocol (ARP)

  • 8100h: VLAN Tag


Other Ether Types are registeres by additional software components, such as the PNIO communication stack,
The Ethernet Frame Handler accepts all Ethernet frames if the Ether Type is set to GOAL_ETH_ETHERTYPE_ANY.
The kind of the identification is configured by function goal_miEthProtoAdd() or goal_miEthProtoAddPos().


Figure: Media Interface Ethernet and Media Adapter as part of the GOAL system

 

The Ethernet frames can be divided in frames with low and high priority. The priority is also specified by function goal_miEthProtoAdd() or goal_miEthProtoAddPos(). The type of identification and the priority determine the handling of received frames, see Figure 12.

 


Figure: RX Ethernet frame handling

 

During the interrupt-controlled receipt the callback function specified by function goal_miEthProtoAdd() or goal_miEthProtoAddPos() is called immediately. For the loop-controlled handling the received message is stored internal and the callback function is called in the GOAL loop. The Ethernet Frame handler registers the function goal_miEthLoop() for this purpose.
Ethernet Frame HandlerEthernet controllers provide possibilities to analyze the Ethernet communication by counting of events represented as statistics, see Chapter: Statistics.
The generic Ethernet Frame Handler can be controlled via the command line interface, see Chapter Command line interface.

Configuration

Compiler-defines


The following compiler-defines are available to configure the generic Ethernet Frame Handler:

Table: Compiler-defines

Define

Value

Purpose

GOAL_CONFIG_ETHERNET

0/1

generic Ethernet Frame Handler is disabled (default)/ enabled

GOAL_CONFIG_MEDIA_MI_ETH

0/1

enable new API of the Media Interface Ethernet

GOAL_TARGET_ETH_PORT_COUNT

any

number of external ports (default: platform-specific)

GOAL_CONFIG_MAC_ADDR_FILTER

0/1

MAC address filtering disabled (default)/ enabled

GOAL_ETH_NAMES

0/1

names for Ethernet commands are not available (default)/ available

GOAL_CONFIG_ETH_STATS

0/1

support of Ethernet statistics is disabled (default)/ enabled

GOAL_CONFIG_ETH_STATS_NAMES

0/1

short description of Ethernet statistic is not available (default)/ is available

GOAL GOAL_CONFIG_TDMA

0/1

time division multiple access disabled (default)/ enabled

CM-variables


The following CM-variables are available to configure the Configuration Manager:

Table: ETH_CM_VAR_MAC

CM-Module-ID

GOAL_ID_ETH

CM-variable-ID

0

CM-variable name

ETH_CM_VAR_MAC

Description

MAC address

CM data type

GOAL_CM_GENERIC

Size

6 bytes

Default value

from NVS or 0


Table: ETH_CM_VAR_LINK

CM-Module-ID

GOAL_ID_ETH

CM-variable-ID

1

CM-variable name

ETH_CM_VAR_LINK

Description

mask for the link state of the Ethernet port

CM data type

GOAL_CM_UINT32

Size

4 bytes

Default vaue

from NVS or 0

Explanation

There are four Linkstates: default (0x00), unknown (0x01), down (0x02) and up (0x03). Per Port two bits are used, beginning at the LSB.

Examples

1 Port Device - Port 0 has the state “up”. ETH_CM_VAR_LINK = 0x03
2 Port Device - Port 0 hat state “up”, Port 1 hat state “down”. ETH_CM_VAR_LINK = 0x0B

 

Table: ETH_CM_VAR_SPEED

CM-Module-ID

GOAL_ID_ETH

CM-variable-ID

2

CM-variable name

ETH_CM_VAR_SPEED

Description

mask for the speed of the Ethernet port

CM data type

GOAL_CM_UINT32

Size

4 bytes

Default value

from NVS or 0

Explanation

There are five speeds in MBit/s: default (0x00), unknown (0x01), 10 (0x02), 100 (0x0x03) and 1000 (0x04). Per Port three bits are used, beginning at the LSB.

Examples

1 Port Device - Port 0 uses 100 MBit/s. ETH_CM_VAR_SPEED= 0x03
2 Port Device - Port 0 uses 100 MBit/s, Port 1 uses 10 MBit/s. ETH_CM_VAR_SPEED= 0x0B


Table: ETH_CM_VAR_DUPLEX

CM-Module-ID

GOAL_ID_ETH

CM-variable-ID

3

CM-variable name

ETH_CM_VAR_DUPLEX

Description

mask for duplex property of the Ethernet port

CM data type

GOAL_CM_UINT32

Size

4 bytes

Default value

from NVS or 0

Explanation

There are four Duplex states: default (0x00), unknown (0x01), Halfduplex (0x02) and Fullduplex (0x03). Per Port two bits are used, beginning at the LSB.

Examples

1 Port Device - Port 0 acts Fullduplex. ETH_CM_VAR_SPEED= 0x03
2 Port Device - Port 0 acts Fullduplex, Port 1 is unknown. ETH_CM_VAR_SPEED= 0x07


Table: ETH_CM_VAR_PORTCNT

CM-Module-ID

GOAL_ID_ETH

CM-variable-ID

4

CM-variable name

ETH_CM_VAR_PORTCNT

Description

number of Ethernet ports

CM data type

GOAL_CM_UINT32

Size

4 bytes

Default value

from NVS or 0

 

The generic Ethernet Frame Handler uses GOAL queues internally. The size of these queues can be optimized for the current platform. The configuration is described in Chapter: Internal queue usage.

Callback functions


The Ethernet frame handler supports callback functions

  • for the receipt of Ethernet frames and

  • to inform the application about the changed state of the Ethernet port.


The names of the callback functions are application-specific.

Table: cbEthFrameReceivedFunc()

Prototype

GOAL_STATUS_T cbEthFrameReceivedFunc(GOAL_BUFFER_T **ppBuf)

Description

This callback function is used to deal with the received Ethernet frame.

Parameters

ppBuf

pointer at the buffer containing the received Ethernet frame

Return values

GOAL return status, see Chapter: GOAL status

Category

mandatory, if the Ethernet Frame Handler is used

Registration

during runtime via function goal_miEthProtoAdd()

 

Table: cbEthPortChangedFunc()

Prototype

void cbEthPortChangedFunc(GOAL_ETH_PORT_T id, uint32_t maskChg, struct GOAL_ETH_PORT_STATE_T *pState)

Description

This callback function is called to inform the application about the changed state of the Ethernet port.

Parameters





id

number of the Ethernet port

maskChg

mask for the changed state bits

pState

new state of the Ethernet port

Return values

None

Category

Optional

Registration

during runtime via function goal_miEthPortStateCbReg()

Ethernet interface


GOAL makes a general interface available to configure the Ethernet interface and to get state information about the Ethernet interface, e.g. the switch or PHY. There are two possibilities to access to the configuration setting or the state information:

  • via special functions of the Ethernet Frame Handler or

  • via the Ethernet command and the function goal_miEthCmd().

The implementation and the support of the Ethernet commands depend on the platform. The platform-specific details are described in the GOAL Platform Manual.
GOAL provides the following commands for the configuration of the Ethernet interface:

Table: GOAL_ETH_CMD_AUTONEG_PROGRESS

Ethernet command

GOAL_ETH_CMD_AUTONEG_PROGRESS

Description

get the state of the auto-negotiation process:

  • GOAL_ETH_AUTONEG_INPROGRESS,

  • GOAL_ETH_AUTONEG_FAIL_ALL,

  • GOAL_ETH_AUTONEG_FAIL_DUPLEX,

  • GOAL_ETH_AUTONEG_DONE,

  • GOAL_ETH_AUTONEG_SKIPPED

Special set function

Special get function

goal_miEthAutonegProgressGet()

 

Table: GOAL_ETH_CMD_AUTONEG

Ethernet command

GOAL_ETH_CMD_AUTONEG

Description

set or get the behavior for the auto-negotiation:

  • GOAL_ETH_AUTONEG_ON,

  • GOAL_ETH_AUTONEG_OFF

Special set function

goal_miEthAutonegSet()

Special get function

goal_miEthAutonegGet()

 

Table: GOAL_ETH_CMD_AUTONEG_RESTART

Ethernet command

GOAL_ETH_CMD_AUTONEG_RESTART

Description

restart the auto-negotiation process

Special set function

Special get function

 

Table: GOAL_ETH_CMD_DUPLEX

Ethernet command

GOAL_ETH_CMD_DUPLEX

Description

set or get the transfer mode:

  • GOAL_ETH_DUPLEX_HALF,

  • GOAL_ETH_DUPLEX_FULL

Special set function

goal_miEthLinkDuplexSet()

Special get function

goal_miEthLinkDuplexGet()

 

Table: GOAL_ETH_CMD_HW_FAULT

Ethernet command

GOAL_ETH_CMD_HW_FAULT

Description

get an indicator for the last hardware fault

Special set function

Special get function

 

Table: GOAL_ETH_CMD_SPEED

Ethernet command

GOAL_ETH_CMD_SPEED

Description

set or get the rate of transfer: GOAL_ETH_SPEED_10, GOAL_ETH_SPEED_100 or GOAL_ETH_SPEED_1000 Mbit/s

Special set function

goal_miEthLinkSpeedSet()

Special get function

goal_miEthLinkSpeedGet()

 

Table: GOAL_ETH_CMD_SPEED_MAX

Ethernet command

GOAL_ETH_CMD_SPEED_MAX

Description

get the maximal allowed rate of transfer:

  • GOAL_ETH_SPEED_10 Mbit/s,

  • GOAL_ETH_SPEED_100 Mbit/s,

  • GOAL_ETH_SPEED_1000 Mbit/s

Special set function

Special get function

 

Table: GOAL_ETH_CMD_LINK_STATE

Ethernet command

GOAL_ETH_CMD_LINK_STATE

Description

get the current state of the Ethernet connection:

  • GOAL_ETH_STATE_UP,

  • GOAL_ETH_STATE_DOWN

Special set function

Special get function

goal_miEthLinkStateGet()

 

Table: GOAL_ETH_CMD_PORT_STATE

Ethernet command

GOAL_ETH_CMD_PORT_STATE

Description

switch on/off the Ethernet port or get the current state of the Ethernet port:

  • GOAL_ETH_STATE_UP,

  • GOAL_ETH_STATE_DOWN

Special set function

goal_miEthPortStateSet()

Special get function

goal_miEthPortStateGet()

 

Table: GOAL_ETH_CMD_LINK_CAPABILITIES

Ethernet command

GOAL_ETH_CMD_LINK_CAPABILITIES

Description

get the supported transfer mode and transfer rate
The return value has data type uint32_t and is bit-coded. The bits have the following meaning for bit value 1:

  • bit 0: 10 Mbit/s in half-duplex mode is supported

  • bit 1: 10 Mbit/s in full-duplex mode is supported

  • bit 2: 100 Mbit/s in half-duplex mode is supported

  • bit 3: 100 Mbit/s in full-duplex mode is supported

  • bit 4: 1000 Mbit/s in half-duplex mode is supported

  • bit 5: 1000 Mbit/s in full-duplex mode is supported

Special set function

Special get function

 

Table: GOAL_ETH_CMD_AUTONEG_ADVERTISMENT

Ethernet command

GOAL_ETH_CMD_AUTONEG_ADVERTISMENT

Description

set or get the list for transfer rate and transfer mode for the auto-negotiation process
The value has the data type uint32_t and is bit-coded. The bits have the following meaning for bit value 1:

  • bit 0: 10 Mbit/s in half-duplex mode is used

  • bit 1: 10 Mbit/s in full-duplex mode is used

  • bit 2: 100 Mbit/s in half-duplex mode is used

  • bit 3: 100 Mbit/s in full-duplex mode is used

  • bit 4: 1000 Mbit/s in half-duplex mode is used

  • bit 5: 1000 Mbit/s in full-duplex mode is used

Special set function

Special get function

 

Table: GOAL_ETH_CMD_PORT_ADMIN_STATE

Ethernet command

GOAL_ETH_CMD_PORT_ADMIN_STATE

Description

get the current state of the Ethernet port:

  • GOAL_ETH_STATE_UP,

  • GOAL_ETH_STATE_DOWN

Special set function

Special get function

 

Table: GOAL_ETH_CMD_LED_LINK

Ethernet command

GOAL_ETH_CMD_LED_LINK

Description

set or get the PHY link LED state

Special set function

Special get function

 

Table: GOAL_ETH_CMD_PORT_COUNT

Ethernet command

GOAL_ETH_CMD_PORT_COUNT

Description

get the number of installed Ethernet ports

Special set function

Special get function

VLAN


GOAL makes a general interface available to configure the VLAN capabilities of the underlying switch. The access to the configuration setting or the state information is realized via Ethernet commands and the function goal_miEthCmd(). The implementation and the support of the Ethernet commands depend on the platform.
GOAL provides the following Ethernet commands for the VLAN capabilities:

Table: VLAN capabilities

Ethernet command

Description

Ethernet command

Description

GOAL_ETH_CMD_VLAN_MODE_IN

set or get the input mode of the VLAN processing

GOAL_ETH_CMD_VLAN_MODE_OUT

set or get the output mode of the VLAN processing

GOAL_ETH_CMD_VLAN_DEF

set or get the default VLAN-ID and priority for a port

GOAL_ETH_CMD_VLAN_PORT_ADD

adds a port as a member of the given VLAN-ID

GOAL_ETH_CMD_VLAN_PORT_REM

removes a port as a member from the given VLAN-ID

GOAL_ETH_CMD_VLAN_TABLE_CNT

get the VLAN table entry count

GOAL_ETH_CMD_VLAN_TABLE_GET

shows the entries of the VLAN table

GOAL_ETH_CMD_VLAN_VERIFY

enables/disables the VLAN domain verification for the given port

GOAL_ETH_CMD_VLAN_DISCUNK

enabled/disables the discarding of frames with unknown VLAN-IDs

MAC table


The MAC table subgroup provides an interface to the MAC table settings and allows to access to specific MAC table entries.
GOAL provides the following Ethernet commands for the handling of MAC table settings:

Table: Ethernet commands for the handling of MAC table settings

Ethernet command

Description

Ethernet command

Description

GOAL_ETH_CMD_MACTAB_CONF

enables/disables the given feature of the MAC table:

  • learning: Automatic MAC address learning

  • ageing: MAC address ageing for dynamic entries

  • migration: Allows the migration of MAC addresses between ports

  • discunknown: Discard frames with unknown destination address

  • pervlan: Learn MAC addresses per VLAN allowing the same MAC address in different VLANs

GOAL_ETH_CMD_MACTAB_SET

set an entry in the MAC table

GOAL_ETH_CMD_MACTAB_GET

get an entry from the MAC table

GOAL_ETH_CMD_MACTAB_CLR

clear MAC table

Port settings


Table: Ethernet commands for the handling of Port settings

Ethernet command

Description

Ethernet command

Description

GOAL_ETH_CMD_PORT_FWD_ADD

add port to forward table

GOAL_ETH_CMD_PORT_FWD_DEL

delete port from forward table

GOAL_ETH_CMD_PORT_AUTH

set/get port authorization

GOAL_ETH_CMD_PORT_CTRL_DIR

set/get port controlled directions

GOAL_ETH_CMD_PORT_EAPOL_ENABLE

set/get port EAPOL frame reception mode

QoS settings


Table: Ethernet commands for the handling of QoS settings

Ethernet command

Description

Ethernet command

Description

GOAL_ETH_CMD_QOS_MODE

set/get QoS mapping type

GOAL_ETH_CMD_QOS_PRIO_VLAN

set/get QoS VLAN priority

GOAL_ETH_CMD_QOS_PRIO_IP

set/get QoS IP priority

GOAL_ETH_CMD_QOS_PRIO_TYPE

set/get QoS Ethertype priority

Implementation guidelines

Configure MAC address

With the generic Ethernet frame handler you can set an own MAC address in the application.

  1. Configure the MAC address:

     

  2. Set the MAC address:

 

It is highly recommended to set the MAC address before other function calls. The Ethernet frame handler will set the MAC address temporarily in the platform afterwards.

Open Media Interface and Adapter


The generic Ethernet frame handler in GOAL version 2.20.0 uses a new API, which requires an opened Media Interface, Adapter handle and Ethernet driver. In future the new API will make it possible to use more than one virtual Ethernet interface at a time.
To use the new API, you have to define CONFIG_MAKE_FEAT_MEDIA_MI_ETH = 1 in the file goal/projects/…/gcc/Makefile. Thereby you have to open the Media Interface and Adapter manually.
If you don't use this define, the default Ethernet Media Interface and Adapter will be opened and used.

  1. Open the Media Interface Ethernet with the desired driver to use the Ethernet interface provided by the target. The specific driver is choosen by the Media Adapter ID. Per default it is GOAL_MA_ID_ETH.

    At this time there are only two Media Adapter ID's available: GOAL_MA_ID_ETH for Ethernet and GOAL_MA_ID_EOE for EtherCAT over Ethernet.

  2. Open the TCP/IP stack to enable generic Ethernet frame handling.

    This is necessary to register intern callback functions of the TCP/IP stack, which reacts to received frames like ARP's et cetera.

Send and receive Ethernet frames


Ethernet frames shall be sent from the application directly, see Figure 11 Ethernet channel2:

  1. Create a callback function to handle received Ethernet frames application-specific:

     

  2. Register the callback function for the receipt of IPv4 Ethernet frames with a high priority:

     

  3. If an Ethernet frame was received, the callback function cbEthFrameReceivedFunc() is called and the application can handle the Ethernet frame.

  4. Send an Ethernet frame:

     

Dynamic Heap Memory Allocator

Various embedded platforms feature an OS, like Linux or FreeRTOS. These operating systems have their own memory management where allocating and freeing memory during runtime is common.

The Media Adapter for dynamic heap memory offers a generic interface of the OS it’s memory management unit to GOAL. So, memory can be allocate and free from OS heap. Even at runtime. But because the Dynamic Heap Memory Allocator is only as efficient as the OS, freeing may still result into fragmented memory regions. Thus, GOAL is using static heap prior the dynamic heap.

 

schematic relation of static and dynamic heap on targets with OS

 

And what’s about bare metal platforms where are no OS available? For these targets, GOAL provides an own module for dynamic memory management.

schematic relation of static and dynamic heap on bare metal targets

Comparison of static and dynamic Heap memory

dynamic heap

https://portgmbh.atlassian.net/wiki/spaces/GOALR/pages/236355708

dynamic heap

  • dynamic RAM usage by allocation and freeing memory during runtime

  • fragmentation

  • the dynamic heap is offered by OS (or GOAL) directly

  • fixed RAM usage by limited allocation (only during GOAL_FSA_INIT) and prohibited free

  • no fragmentation

  • the static heap is an allocated dynamic heap memory region with special lock

Implementation guidelines

  • GOAL files:

    • goal_media/goal_ma_heap.[h,c] – Header/Source file for dynamic HEAP Memory allocator

    • plat/drv/mem/heap/ - drivers for accessing OS or GOAL heap management unit

  • example:

    • appl/00410_goal/heap - This module is an application, showing the dynamic HEAP access by running some tests.

There are two APIs for handling dynamic heap memory. First starts function naming by goal_maHeap and is confirm to the media adapter, requiring a driver ID. Second starts function naming by goal_maHeap and simplified the arguments by using GOAL_ID_DEFAULT as driver ID.

The following header has to be include for using the dynamic heap API.

Configuration

The size of the dynamic heap depends on the platform in use.

Targets with OS pretending the heap size by it’s configuration.
Targets without OS are using the GOAL heap management unit, which offers following compiler-defines.

  • GOAL_CONFIG_HEAP_DYNAMIC_SIZE: absolute size of dynamic heap in bytes

  • GOAL_CONFIG_HEAP_DYNAMIC_ADD_SIZE: offset size in bytes, increasing the minimum required heap (equals GOAL_CONFIG_HEAP_SIZE)

Allocate memory from dynamic heap

Code: example for allocate dynamic heap

Callocate memory from dynamic heap

Code: example for callocate dynamic heap

Free dynamic heap

Freeing memory, which was not allocated from dynamic heap before is not secured and may cause invalid behavior.

Code: example for freeing heap

Reallocate dynamic heap memory

Code: example for reallocate memory

Code: reallocate can also be used allocate or free memory

Get dynamic heap statistics

GOAL offers some statistics about the dynamic heap.

Code: getting heap statistics