This section describes MX Foundation embedded programming to include:

Real-time Linux

Flex devices have a CPU, on-board memory, and run an embedded Linux RTOS. The Flex device also include an FPGA that is responsible of all the supported databus and I/O frame encoding, decoding, time stamping, errors injections, detection and other protocols critical state machines. The embedded CPU is responsible of all the supported databus I/O engines communications with the FPGA in addition to the Ethernet, USB and PCI-Express communication stacks. This CPU-RTOS-FPGA device architecture allows to handle many combinations of databus and I/O protocols and communication with a host computer using either PCI-Express, USB or Ethernet. The Flex devices can be viewed as a real-time embedded computer with CPU, RTOS and FPGA running specialized databus, I/O and communications software and hardware engines.

Typical usage

The Flex devices are typically used by connecting it to a host computer using USB, Ethernet or PCI-Express link and running a supplied or user-developed application on the host computer with the MX Foundation API. In such usage scenarios, there is no embedded programming necessary. The Flex devices comes out of the box with the firmware needed to control the device and uses all the supported databus and I/O capabilities.

Specialized usages

The embedded CPU with Linux RTOS is also available to the user for running specialized embedded applications. A user-developed embedded application can run on the Flex device and communicate with the host computer or run on the Flex device without connection to a host computer (auto-run mode). For example, a simulator may need to send data using specialized UDP communication and handle custom messages processing. Such tasks can be user developed as embedded specialized software that run on the Flex device Linux RTOS. Other usages examples are bridging data between two different protocols, specialized trigger action, specialized message filtering, using the Flex as standalone unit for recording data in embedded flash-memory and so on.

Embedded Programming

MX Foundation 4 API has been compiled to run with embedded Linux which allows a user application to also run embedded and used MX Foundation 4 the same way of it would on a computer.

With FlexMulti/FlexMobile devices, additional services are available:

telnet server: With a telnet connection, you will be able to interact with Linux. Telnet connection uses the same user/password as MX Foundation 4 server.
tftp client: A tftp client is available, but you will need a tftp server on the host computer. With tftp, you will be able to download files to the device and upload files from the device.

gdbserver (FlexMulti): GDB server is also available to help debug the embedded application. To start gdbserver, use the following commands:

gdbserver host:5555 path_to_my_app

On the host, start the GDB client with the following script. Edit it to match your specific settings:

#!/bin/sh

export PYTHONHOME=/usr/

export EXEC=path_to_my_ELDK_root/ELDK_5_3_85xx_v2/powerpc-e500v2/sysroots/i686-eldk-linux/usr/bin/ppce500v2-linux-gnuspe/powerpc-linux-gnuspe-gdb

$EXEC -iex "set directories path_to_directory" \
      -iex "file path_to_my_file" \
      -iex "set sysroot path_to_my_ELDK_root/ELDK_5_3_85xx_v2/powerpc-e500v2/sysroots/ppce500v2-linux-gnuspe/" \
      -iex "target remote device_ip_address:5555"

With FlexMAX devices, this additional service is available:

SSH server: With a SSH connection, you will be able to interact with Linux. SSH connection uses the same user/password as MX Foundation 4 server. You will also be able to download files to the device and upload files from the device.

Development

The recommended way to develop an MX Foundation embedded application is to develop it first as a host application. Once the host application is developed, debugged, tested, and works as expected then it should be tested in an embedded environment. This process can be iterative for complex applications. The same MX Foundation functionalities are available in the embedded environment as in the host environment. The mxfDeviceFileUpload() function is available to upload an application from the host to the device. Once an embedded application is running, most of the host functions are unavailable until the embedded application is finished and the host library is reloaded. When running embedded, the output of printf will be directed to the debug com port (115200 bps, 8 bit data, no parity, 1 stop bit, no flow control). For FlexMulti devices, a USB UART cable can be used to connect to the computer.The use of the serial port is not mandatory, it is only there to facilitate the development.

Remember that the application will need to be compiled with Linux to run on the device. If the host OS is not Linux, some precautions will need to be taken. For example, if standard socket programming is used, some functionalities differ between Windows and Linux sockets. Also, OS specific functions (like synchronization object) will need to have their equivalent defined for Linux compilation.

To communicate with the embedded application, the use of a communication queue is recommended. A small set of functions can be used to configure and use a communication queue. The communication queue is a functionality that is available on the host application when an embedded application is running to allow exchange of information between the two. For example, to implement a command/ack scenario between the host and embedded part of the application, the host can use one communication queue to send the command and the embedded can use another communication queue to send the ack. The number of communication queues available is defined by KMXF_DEVICE_EMBEDDED_COMM_QUEUE_NUM initialization attribute.

Since the goal is to run the application in an embedded environment, some precautions must be taken when developing the application. Resources in an embedded environment are more scarce. For instance, FlexMulti 629 has 256 MB of DDR2 memory. The memory is shared between embedded Linux services and applications, but also with the filesystem. Embedded Linux uses ramfs for its filesystem so that every file is in fact stored in RAM. This lowers the amount of memory available for the embedded application. Typically, around 150 MB is available for the embedded application. Files created by the application will be lost after a reset or power-off of the device.

Embedded applications can optionally use these two libraries in addition to the standard c library:

libm: mathematical library (math.h)
libpthread: for multithreaded application

ar429_comm_queues.c
ar429_embedded_comm_queues.c
mil1553_embedded_update_host.c
mil1553_embedded_update_embedded.c

Embedded Linux Development Kit

The embedded application must be compiled using a cross-compiler package that will generate code compatible with the CPU of the Flex device. This package is included with the MX Foundation Linux SDK.

Note: A Linux environment is needed to compile the embedded code. For Windows/OSX user, a virtual machine with Linux as a guest operating system is recommended. The MXF installation folder should be shared between the host and guest OS.

Compilation

The makefile of examples in /make/linux_embedded should be used as reference to create the makefile to compile embedded application.

Auto-run

The FlexMulti, FlexMobile and FlexMAX devices can be set in auto-run mode which will automatically start the application that is burned into its NOR flash at power-up. The same steps described in Development section should be used to build the application that will be started. A client/server architecture should be used when developing the embedded application. The embedded application should act as a server, meaning that it should not close, because it is the main way to communicate with the application.

Programmation

The standalone application needs MX Foundation library and firmware to run. These files will automatically be packaged with the standalone application by the mxfStandAloneFileGenerate() function. The mxfStandAloneFileGenerate() function generates the package to burn in the device's NOR flash memory, which is in the same folder as the standalone application executable.

You can now burn the package in the NOR flash memory of the FlexMulti, FlexMobile or FlexMAX device by using the mxfDeviceFirmwareUpload() function or using the deviceprog utility (bin/utilities).

With deviceprog utility, from terminal, run deviceprog with path to .ctrom file generated by mxfStandAloneFileGenerate() function as a parameter and follow the instructions to the flash standalone device (Server Address is standalone device IP address). You can change the default IP address and netmask at this step. Be sure to set the IP address and netmask according to your desired network configuration if DHCP is not used.

Non-volatile Storage

FlexMulti devices have non-volatile memory (NAND flash). The non-volatile memory is useful to make the device a standalone data recorder with the help of the Non-Volatile Storage group of functions. These functions allow an application to create files and assign an acquisition channel to a file so that incoming data is automatically written to the file. Acquisition filtering is also available. Functions to read the content of a file and navigate through it are also available.

ar429_embedded_recorder.c

MX Embedded

The MX Embedded service lets the user download and attach an embedded code within the MX Foundation firmware residing on the MAX Technologies device. MX Embedded application is different from MX Foundation embedded application. Both are compiled using the cross-compiler package, but MX Embedded application has access only to a specific group of functions that can be called from the function handlers. This embedded code can have many function handlers that are called on to receive or transmit events. For example, it is possible to make these user defined handlings:

RX message filtering
RX message triggering
RX/TX message bridging
TX message data updating
Timer handling

MX Embedded application is useful when the application must react quickly (low latency) to an event, for more complex filtering or triggering or to bridge data between two different protocols. MX Foundation embedded application can also use a MX Embedded application.

Host

The host part is the MX Foundation API with the MX Embedded service functions. MX Foundation lets the user have complete control over supported hardware devices, including devices-channel-attributes, operating modes, RX/TX messages queuing, TX scheduling, routing and data processing. The MX Embedded service allows:

Download compiled code
Download data section
Send commands
Enabling specific channel event handling
Writing/reading user shared space
Reading from RX queues
Writing into TX queues

The control of the embedded code is made by sending commands and/or using the shared memory space.

Initialization attributes are used to define the number of TX/RX embedded queues and shared memory space size.

Function overview

mxfEmbeddedCodeDownload(): Download the user code
mxfEmbeddedDataDownload(): Download a data section
mxfEmbeddedCommandSend(): Send a user command
mxfEmbeddedSharedBufferRead(): Read the shared buffer memory
mxfEmbeddedSharedBufferWrite(): Write the shared buffer memory
mxfEmbeddedHandlerEnableSet(): Enable and disable a specified channel handler
mxfEmbeddedRxBufferAlloc(): Allocate a receive buffer area for MX Embedded queue reception
mxfEmbeddedRxBufferGet(): Return the buffer handle referenced by the device handle and queue index pair
mxfEmbeddedRxBufferFree(): Deallocates the memory previously allocated by mxfEmbeddedRxBufferAlloc()
mxfEmbeddedRxBufferStatusGet(): Returns the status of the MX Embedded RX buffer
mxfEmbeddedRxBufferClear(): Clear the pending data to read from the MX Embedded RX buffer
mxfEmbeddedRxBufferRead(): Read the RX Queue
mxfEmbeddedRxBufferInfoGet(): Return the device handle and queue index pair from a MX Embedded RX buffer handle
mxfEmbeddedTxBufferAlloc(): Allocate a transmit buffer area for MX Embedded queue transmission
mxfEmbeddedTxBufferGet(): Return the buffer handle referenced by the device handle and queue index pair
mxfEmbeddedTxBufferFree(): Deallocates the memory previously allocated by mxfEmbeddedTxBufferAlloc()
mxfEmbeddedTxBufferStatusGet(): Returns the status of the MX Embedded TX buffer
mxfEmbeddedTxBufferClear(): Clear the pending data to read from the MX Embedded TX buffer
mxfEmbeddedTxBufferWrite(): Write the TX Queue
mxfEmbeddedTxBufferInfoGet(): Return the device handle and queue index pair from a MX Embedded TX buffer handle

Examples

ar429_embedded_discrete.c
ar429_embedded_timer.c

Embedded

The embedded part consists of function handler templates. Each function must be implemented by the user. This part doesn't have access to MX Foundation functions. It uses a special embedded API. This API allows:

TX message data update
Aperiodic transmission
Writing/reading user shared space
Timer configuration
printf function for debugging purpose
Writing into RX queues
Reading TX queues
etc.

Handler overview

mxfEmbeddedCommandHandler(): Called when the mxfEmbeddedCommandSend() function is called. The command ID and command parameters buffer (size and pointer) are passed by function parameters. This handler has a lower priority than the other handlers and can be interrupted.
mxfEmbeddedDataDownloadHandler(): Called when the mxfEmbeddedDataDownload() function is called. The data buffer size and pointer are passed by function parameters.
mxfEmbeddedRxIntHandler(): Called when a data is received by any enabled channel. It is called before the acquisition receive and sampling receive handling. This handler gives three action possibilities: acquisition received filtering or triggering and sampling filtering. This handler can be enabled/disabled on a channel basis using the mxfEmbeddedHandlerEnableSet() host function.
mxfEmbeddedTxPeriodicUpdateMsgIntHandler(): Called after a data is transmitted by any enabled channel. It is called before the TX periodic update message buffer handling. This handler allows updating the message for the next transmission. This handler can be enabled/disabled on a channel basis using the mxfEmbeddedHandlerEnableSet() host function.
mxfEmbeddedTimerHandler(): Called periodically at each timer period. This handler can be enabled/disabled by the mxfEmbeddedTimerHandlerEnableSet() embedded function.

Compiler

Follow these steps to install the cross-compiler package. Once the toolchain is installed, it will be used to compile the MX Embedded application.

Here are the steps to compile an MX Embedded application:

If you already have the embedded source code, copy it to the examples/_my_subfolder_/src/embedded folder, otherwise copy the provided embedded code template (examples/embedded/src/embedded_side/embedded_side_template.c) to another filename and implement each template functions handler needed.
Copy any embedded batch file example (examples/_my_subfolder_/make/linux_embedded/build_xxx) to another filename.
Edit the batch file and change the embedded file name on the second line (export MX_FILE=filename) for your embedded code filename.
Run the batch file to start the compilation.

cd /path_to_mx_foundation_install/examples/_my_subfolder_/make/linux_embedded
./build_my_embedded_code
If no compilation error occurs, the compiled binary file will be created in bin/examples/embedded/embedded-side of your MX Embedded installation folder.
The embedded code is now ready to be downloaded and controlled by the MX Foundation host application.

Library

The C library (libc.a) and the Math library (libm.a) are included in the toolchain installation.

The C library contains many functions. Only a few of these functions may be used in a MX Embedded code:

Standard Utility functions (stdlib.h): abs and atoi only
Character type functions (ctype.h): all
Input and Output functions (stdio.h): printf only
Strings and memory functions (string.h): all

The usage of any other functions is not recommended.

The Math library allows using many mathematical functions. The prototypes are found in math.h.

Debugger Monitor

The embedded monitor tool displays the “printf” formatted output generated by the embedded code. The executable is located in “mx_foundation/bin/utilities” directory.

Examples

ar429_embedded_side_discrete.c
ar429_embedded_side_timer.c