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 |
---|---|
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:
|
access | access right at the region:
|
Implementation guidelines
Registration of a memory region
Specify a region and define a MI-NVS-REGION-ID:
#define GOAL_ID_MI_NVS_REGION_CONFIG_DATA 2
Create a MA-handle:
GOAL_MA_NVS_T *pMaNvs;
Select the suitable NVS driver and initialize the driver. The driver registers to the media adapter by itself.
Create a MI-handle:
GOAL_MI_NVS_T *pMiNvsHdl;
Register the media interface:
Allocate the NVS service:
Create a MI-NVS-REGION-handle:
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
Load MI-NVS-REGION-handle of the memory region with the ID GOAL_ID_MI_NVS_REGION_CONFIG_DATA:
Erase the nonvolatile memory region:
Write data of size bytes to nonvolatile memory region:
Read data from nonvolatile memory
Load MI-NVS-REGION-handle of the memory region with the ID GOAL_ID_MI_NVS_REGION_CONFIG_DATA:
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
Create a MA-handle:
Select the suitable NVS driver and initialize the driver. The driver registers to the media adapter by itself.
Create a NVS description:
Erase 0x100 bytes in the nonvolatile memory from start address 0x0001FFF:
Write 0x100 bytes from the buffer pData to the nonvolatile memory on start address 0x0001FFF:
Read data from nonvolatile memory
Create a MA-handle:
Select the suitable NVS driver and initialize the driver. The driver registers to the media adapter by itself.
Create a NVS description:
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 |
---|---|
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
Define a MA-ID for a single LED:
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.
Open a media adapter instance and get the MA-SPI handle:
Switch on the LED:
Get the current state of the LED:
Close the media adapter instance:
Switch on/off and get the state of a LED group
A group of 32 LEDs shall be controlled.
Define a MA-ID for a group of LEDs:
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.
Open a media adapter instance and get the MA-SPI handle:
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:
Get the current state of all LEDs in the LED group:
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 | Description |
---|---|
type | type of the SPI communication:
|
mode | combination of clock polarity and phase as SPI mode:
|
bitrate | SPI baudrate in Hz |
unitsize | size of transferred data must be a multiple of unitsize:
|
bitorder | bit order of the transferred data via the SPI bus:
|
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 | 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 |