GOAL media (goal_media)

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:

    goal_miNvsReg(&pMiNvsHdl);

     

  6. Allocate the NVS service:

    goal_miNvsAlloc(pMiNvsHdl);

     

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

    GOAL_MI_NVS_REGION_T *pRegion;

     

  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.

    goal_miNvsRegRegion(&pRegion, pMiNvsHdl, pMaNvsHdl, 0x0001FFF, 0x00000100, "config data",GOAL_ID_MI_NVS_REGION_CONFIG_DATA); /* set mode */ goal_miNvsSetMode(pRegion, GOAL_MI_NVS_REGION_MODE_COMPLETE); /* set access rights */ goal_miNvsSetAccess(pRegion, GOAL_MI_NVS_REGION_ACCESS_WRITE);

 

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:

    GOAL_MI_NVS_REGION_T *pRegion; goal_miNvsRegionGetById(&pRegion, GOAL_ID_MI_NVS_REGION_CONFIG_DATA);

     

  2. Erase the nonvolatile memory region:

    goal_miNvsErase(pRegion);

     

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

    goal_miNvsWrite(pRegion, (uint8_t *)pData,0, size);

 

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:

    GOAL_MI_NVS_REGION_T *pRegion; goal_miNvsRegionGetById(&pRegion, GOAL_ID_MI_NVS_REGION_CONFIG_DATA);

     

  2. Read data from nonvolatile memory:

    goal_miNvsRead(&pRegion, (uint8_t *)pData, 0, size);

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:

    GOAL_MA_NVS_T *pMaNvsHdl;

     

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

  3. Create a NVS description:

    GOAL_MA_NVS_DESC_T desc = { .strName = „config data", .fCompleteAccess = GOAL_TRUE}

     

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

    goal_maNvsErase(pMaNvsHdl, &desc, 0x0001FFF, 0x100);

     

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

    goal_maNvsWrite(pMaNvsHdl, &desc, 0x0001FFF, (uint8_t *)pData, 0x100);

 

Read data from nonvolatile memory

 

  1. Create a MA-handle:

    GOAL_MA_NVS_T *pMaNvsHdl;

     

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

  3. Create a NVS description:

    GOAL_MA_NVS_DESC_T desc = { .strName = „config data", .fCompleteAccess = GOAL_TRUE}

     

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

    goal_maNvsRead(pMaNvsHdl, &desc, 0x0001FFFF, (uint8_t *)pData, 0x100);

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:

    #define GOAL_MA_LED_APPL_SINGLE_LED 1

     

  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:

    GOAL_MA_LED_T *pMaLedHdl; /*MA-LED handle */ goal_maLedOpen(GOAL_MA_LED_APPL_SINGLE_LED, &pMaLedHdl)

     

  4. Switch on the LED:

    GOAL_MA_LED_STATE_T state = GOAL_MA_LED_STATE_ON; goal_maLedSet(pMaLedHdl, &state);

     

  5. Get the current state of the LED:

    goal_maLedGet(pMaLedHdl, &state);

     

  6. Close the media adapter instance:

    goal_maLedClose(pMaLedHdl);

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:

    #define GOAL_MA_LED_APPL_GROUP_LED 2

     

  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:

    GOAL_MA_LED_T *pMaLedHdl; /*MA-LED handle */ goal_maLedOpen(GOAL_MA_LED_APPL_GROUP_LED, &pMaLedHdl);

     

  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:

    uint32_t mask = 0xFF00FFFF; uint32_t state = 0xFF000000; goal_maLedGroupSet(pMaLedHdl, &mask, &state);

     

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

    goal_maLedGroupGet(pMaLedHdl, &state);

     

  6. Close the media adapter instance:

    goal_maLedClose(pMaLedHdl);

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:

    GOAL_STATUS_T cbApplMaSpiEvent(struct GOAL_MA_SPI_T *pMaSpiHdl, GOAL_MA_SPI_EVENT_T event, void *pArg) { }

     

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

    GOAL_MA_SPI_T *pMaSpiHdl; goal_maSpiOpen(GOL_MA_SPI_ID, &pMaSpiHdl, cbApplMaSpiEvent, NULL);

     

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

    goal_maSpiWrite(pMaSpiHdl, (uint8_t *)pData, 4);

     

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

    uint16_t len; /* length of read data in bytes */ goal_maSpiRead(pMaSpiHdl, (uint8_t *)pData, &len);

     

  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:

    uint16_t len; /* length of data to write as input parameter and length of read data as output in bytes */ len = 4; goal_maSpiWriteRead(pMaSpiHdl, pWriteData, pReadData, &len);

Configure the SPI interface

 

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

    GOAL_MA_SPI_CONF_T spiConfig; goal_maSpiConfigGet(pMaSpiHdl, &spiConfig);

     

  2. Specify SPI mode 0:

    spiConfig.mode = GOAL_MA_SPI_MODE_0;

     

  3. Set SPI configuration:

    goal_maSpiConfigSet(pMaSpiHdl, &spiConfig);

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:

    GOAL_STATUS_T cbApplMaSpiEvent(struct GOAL_MA_SPI_T *pMaSpiHdl, GOAL_MA_SPI_EVENT_T event, void *pArg) { if (GOAL_MA_SPI_EVENT_ERR_OVERRUN == event) { } else if (GOAL_MA_SPI_EVENT_ERR_PARITY == event) { } else { /* handle unknown events application-specific */ } }

     

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

    GOAL_MA_SPI_T *pMaSpiHdl; goal_maSpiOpen(GOL_MA_SPI_ID, &pMaSpiHdl, cbApplMaSpiEvent, NULL);

     

  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.

    #define APPL_MA_TLS_ID 1 #define APPL_MI_TLS_ID 1

     

  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.

    GOAL_STATUS_T appl_setup (void) { goal_miTlsOpen(APPL_MA_TLS_ID, APPL_MA_TLS_ID, NULL); }

     

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

    GOAL_NET_CHAN_T pNetChanHdl; GOAL_NET_ADDR_T netChanAddr; GOAL_MEMSET(&netChanAddr, 0, sizeof(GOAL_NET_ADDR_T); addr.localPort = 443; goal_netOpen(&pNetChanHdl, &netChanAddr, GOAL_NET_TCP_LISTENER, NULL);

     

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

    uint32_t optVal = 1; goal_netSetOption(pNetChanHdl, GOAL_NET_OPTION_NONBLOCK, &optVal);

     

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

    GOAL_NET_CHAN_T pTlsChanHdl; GOAL_MI_TLS_T *pMiTls; goal_miTlsGetById(&pMiTls, APPL_MI_TLS_ID); goal_miTlsSessionOpen(pMiTls, &pTlsChanHdl, pNetChanHdl);

     

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

    goal_netOpenTunnel(NULL, pTlsChanHdl, applTlsClearDataCb, NULL, NULL);

     

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

    void applTlsClearDataCb(GOAL_NET_CB_TYPE_T cbType, GOAL_NET_CHAN_T *pChan, struct GOAL_BUFFER_T *pBuf) { }

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.

    uint8_t certInfo[128]; goal_miTlsReadInfo(pTlsHdl, GOAL_CERTINFO_CA_CN, certInfo, 128);

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.

#include <goal_media/goal_mi_cmfs.h> static GOAL_MI_NVS_REGION_LIST_T region_list[] = { { /* CMFS Storage Region 1 */ .posStart = 0x01FC0000, .length = 0x00020000, /* 128k kByte */ .strName = "goal_cmfs_nvs1.bin", .id = GOAL_ID_MI_NVS_REGION_CMFS1, .mode = GOAL_MI_NVS_REGION_MODE_STREAM, .access = GOAL_MI_NVS_REGION_ACCESS_WRITE }, { /* CMFS Storage Region 2 */ .posStart = 0x01FE0000, .length = 0x00020000, /* 128k kByte */ .strName = "goal_cmfs_nvs2.bin", .id = GOAL_ID_MI_NVS_REGION_CMFS2, .mode = GOAL_MI_NVS_REGION_MODE_STREAM, .access = GOAL_MI_NVS_REGION_ACCESS_WRITE } }; /****************************************************************************/ /** Board init * * Low level board initialization. * * * @return GOAL_OK - success * @return GOAL_ERR_BOARD_INIT - error initializing board */ GOAL_STATUS_T goal_targetBoardInit( void ) { GOAL_STATUS_T res = GOAL_OK; /* result */ GOAL_MI_CMFS_T *pMiCmfs = NULL; /* CMFS handle */ GOAL_MI_NVS_T *pMiNvs; /* NVS MI handle */ /* register NVS MI with regions */ if (GOAL_RES_OK(res)) { /* register a new nvs MI */ res = goal_miNvsReg(&pMiNvs, GOAL_ID_MA_NVS_EEPROM_ETHERCAT, eeprom_region_list, ARRAY_ELEMENTS(eeprom_region_list)); } /* register CMFS */ if (GOAL_RES_OK(res)) { res = goal_miCmfsReg(&pMiCmfs, 0); } /* register first region to CMFS */ if (GOAL_RES_OK(res)) { res = goal_miCmfsRegRegion(pMiCmfs, GOAL_ID_MI_NVS_REGION_CMFS1); } /* register second region to CMFS */ if (GOAL_RES_OK(res)) { res = goal_miCmfsRegRegion(pMiCmfs, GOAL_ID_MI_NVS_REGION_CMFS2); } return res; }


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 (0x03) 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= 0x13

Table: ETH_CM_VAR_DUPLEX