Introduction
What is FreeMASTER?
FreeMASTER is a PC-based application developed by NXP for NXP customers. It is a versatile tool usable as a real-time monitor, visualization tool, and a graphical control panel of embedded applications based on the NXP processing units.
This document describes the embedded-side software driver which implements an interface between the application and the host PC. The interface covers the following communication:
Serial UART communication either over plain RS232 interface or more typically over a USB-to-Serial either external or built in a debugger probe.
USB direct connection to target microcontroller
CAN bus
TCP/IP network wired or WiFi
Segger J-Link RTT
JTAG debug port communication
The driver also supports so-called “packet-driven BDM” interface which enables a protocol-based communication over a debugging port. The BDM stands for Background Debugging Module and its physical implementation is different on each platform. Some platforms leverage a semi-standard JTAG interface, other platforms provide a custom implementation called BDM. Regardless of the name, this debugging interface enables non-intrusive access to the memory space while the target CPU is running. For basic memory read and write operations, there is no communication driver required on the target when communicating with the host PC. Use this driver to get more advanced FreeMASTER protocol features over the BDM interface. The driver must be configured for the packet-driven BDM mode, in which the host PC uses the debugging interface to write serial command frames directly to the target memory buffer. The same method is then used to read response frames from that memory buffer.
Similar to “packet-driven BDM”, the FreeMASTER also supports a communication over [J-Link RTT]((https://www.segger.com/products/debug-probes/j-link/technology/about-real-time-transfer/) interface defined by SEGGER Microcontroller GmbH for ARM CortexM-based microcontrollers. This method also uses JTAG physical interface and enables high-speed real time communication to run over the same channel as used for application debugging.
Driver version 3
This document describes version 3 of the FreeMASTER Communication Driver. This version features the implementation of the new Serial Protocol, which significantly extends the features and security of its predecessor. The new protocol internal number is v4 and its specification is available in the documentation accompanying the driver code.
Driver V3 is deployed to modern 32-bit and 64-bit MCU platforms first, so the portfolio of supported platforms is smaller than for the previous V2 versions. It is recommended to keep using the V2 driver for legacy platforms, such as S08, S12, ColdFire, or Power Architecture. Reach out to FreeMASTER community or to the local NXP representative with requests for more information or to port the V3 driver to legacy MCU devices.
Thanks to a layered approach, the new driver simplifies the porting of the driver to new UART, CAN or networking communication interfaces significantly. Users are encouraged to port the driver to more NXP MCU platforms and contribute the code back to NXP for integration into future releases. Existing code and low-level driver layers may be used as an example when porting to new targets.
Note: Using the FreeMASTER tool and FreeMASTER Communication Driver is only allowed in systems based on NXP microcontroller or microprocessor unit. Use with non-NXP MCU platforms is not permitted by the license terms.
Target platforms
The driver implementation uses the following abstraction mechanisms which simplify driver porting and supporting new communication modules:
General CPU Platform (see source code in the
src/platformsdirectory). The code in this layer is only specific to native data type sizes and CPU architectures (for example; alignment-aware memory copy routines). This driver version brings two generic implementations of 32-bit platforms supporting both little-endian and big-endian architectures. There are also implementations customized for the 56F800E family of digital signal controllers and S12Z MCUs.Transport Communication Layer - The Serial, CAN, Networking, PD-BDM, and other methods of transport logic are implemented as a driver layer called FMSTR_TRANSPORT with a uniform API. A support of the Network transport also extends single-client modes of operation which are native for Serial, USB and CAN by a concept of multiple client sessions.
Low-level Communication Driver - Each type of transport further defines a low-level API used to access the physical communication module. For example, the Serial transport defines a character-oriented API implemented by different serial communication modules like UART, LPUART, USART, and also USB-CDC. Similarly, the CAN transport defines a message-oriented API implemented by the FlexCAN or MCAN modules. Moreover, there are multiple different implementations for the same kind of communication peripherals. The difference between the implementation is in the way the low-level hardware registers are accessed. The mcuxsdk folder contains implementations which use MCUXpresso SDK drivers. These drivers should be used in applications based on the NXP MCUXpresso SDK. The “ampsdk” drivers target automotive-specific MCUs and their respective SDKs. The “dreg” implementations use a plain C-language access to hardware register addresses which makes it a universal and the most portable solution. In this case, users are encouraged to add more drivers for other communication modules or other respective SDKs and contribute the code back to NXP for integration.
The low-level drivers defined for the Networking transport enable datagram-oriented UDP and stream TCP communication. This implementation is demonstrated using the lwIP software stack but shall be portable to other TCP/IP stacks. It may sound surprisingly, but also the Segger J-Link RTT communication driver is linked to the Networking transport (RTT is stream oriented communication handled similarly to TCP).
Replacing existing drivers
For all supported platforms, the driver described in this document replaces the V2 implementation and also older driver implementations that were available separately for individual platforms (PC Master SCI drivers).
Clocks, pins, and peripheral initialization
The FreeMASTER communication driver is only responsible for runtime processing of the communication and must be integrated with an user application code to function properly. The user application code is responsible for general initialization of clock sources, pin multiplexers, and peripheral registers related to the communication speed. Such initialization should be done before calling the FMSTR_Init function.
It is recommended to develop the user application using one of the Software Development Kits (SDKs) available from third parties or directly from NXP, such as MCUXpresso SDK, MCUXpresso IDE, and related tools. This approach simplifies the general configuration process significantly.
MCUXpresso SDK
The MCUXpresso SDK is a software package provided by NXP which contains the device initialization code, linker files, and software drivers with example applications for the NXP family of MCUs. The MCUXpresso Config Tools may be used to generate the clock-setup and pin-multiplexer setup code suitable for the selected processor.
The MCUXpresso SDK also contains this FreeMASTER communication driver as a “middleware” component which may be downloaded along with the example applications from https://mcuxpresso.nxp.com/en/welcome.
MCUXpresso SDK on GitHub
The FreeMASTER communication driver is also released as one of the middleware components of the MCUXpresso SDK on the GitHub. This release enables direct integration of the FreeMASTER source code Git repository into a target applications.
Example applications
There are several example applications available for each supported MCU platform.
fmstr_uart demonstrates a plain serial transmission, typically connecting to a computer’s physical or virtual COM port. The typical transmission speed is 115200 bps.
fmstr_can demonstrates CAN bus communication. This requires a suitable CAN interface connected to the computer and interconnected with the target MCU using a properly terminated CAN bus. The typical transmission speed is 500 kbps. A FreeMASTER-over-CAN communication plug-in must be used.
fmstr_usb_cdc uses an on-chip USB controller to implement a CDC communication class. It is connected directly to a computer’s USB port and creates a virtual COM port device. The typical transmission speed is above 1 Mbps.
fmstr_net demonstrates the Network communication over UDP or TCP protocol. Existing examples use lwIP stack to implement the communication, but in general, it shall be possible to use any other TCP/IP stack to achieve the same functionality.
fmstr_wifi is the fmstr_net application modified to use a WiFi network interface instead of a wired Ethernet connection.
fmstr_rtt demonstrates the communication over SEGGER J-Link RTT interface. Both fmstr_net and fmstr_rtt examples require the FreeMASTER TCP/UDP communication plug-in to be used on the PC host side.
fmstr_eonce uses the real-time data unit on the JTAG EOnCE module of the 56F800E family to implement pseudo-serial communication over the JTAG port. The typical transmission speed is around 10 kbps. This communication requires FreeMASTER JTAG/EOnCE communication plug-in.
fmstr_pdbdm uses JTAG or BDM debugging interface to access the target RAM directly while the CPU is running. Note that such approach can be used with any MCU application, even without any special driver code. The computer reads from and writes into the RAM directly without CPU intervention. The Packet-Driven BDM (PD-BDM) communication uses the same memory access to exchange command and response frames. With PD-BDM, the FreeMASTER tool is able to go beyond basic memory read/write operations and accesses also advanced features like Recorder, TSA, or Pipes. The typical transmission speed is around 10 kbps. A PD-BDM communication plug-in must be used in FreeMASTER and configured properly for the selected debugging interface. Note that this communication cannot be used while a debugging interface is used by a debugger session.
fmstr_any is a special example application which demonstrates how the NXP MCUXpresso Config Tools can be used to configure pins, clocks, peripherals, interrupts, and even the FreeMASTER “middleware” driver features in a graphical and user friendly way. The user can switch between the Serial, CAN, and other ways of communication and generate the required initialization code automatically.
Description
This section shows how to add the FreeMASTER Communication Driver into application and how to configure the connection to the FreeMASTER visualization tool.
Features
The FreeMASTER driver implements the FreeMASTER protocol V4 and provides the following features which may be accessed using the FreeMASTER visualization tool:
Read/write access to any memory location on the target.
Optional password protection of the read, read/write, and read/write/flash access levels.
Atomic bit manipulation on the target memory (bit-wise write access).
Optimal size-aligned access to memory which is also suitable to access the peripheral register space.
Oscilloscope access—real-time access to target variables. The sample rate may be limited by the communication speed.
Recorder— access to the fast transient recorder running on the board as a part of the FreeMASTER driver. The sample rate is only limited by the MCU CPU speed. The length of the data recorded depends on the amount of available memory.
Multiple instances of Oscilloscopes and Recorders without the limitation of maximum number of variables.
Application commands—high-level message delivery from the PC to the application.
TSA tables—describing the data types, variables, files, or hyperlinks exported by the target application. The TSA newly supports also non-memory mapped resources like external EEPROM or SD Card files.
Pipes—enabling the buffered stream-oriented data exchange for a general-purpose terminal-like communication, diagnostic data streaming, or other data exchange.
The FreeMASTER driver features:
Full FreeMASTER protocol V4 implementation with a new V4 style of CRC used.
Layered approach supporting Serial, CAN, Network, PD-BDM, and other transports.
Layered low-level Serial transport driver architecture enabling to select UART, LPUART, USART, and other physical implementations of serial interfaces, including USB-CDC.
Layered low-level CAN transport driver architecture enabling to select FlexCAN, msCAN, MCAN, and other physical implementations of the CAN interface.
Layered low-level Networking transport enabling to select TCP, UDP or J-Link RTT communication.
TSA support to write-protect memory regions or individual variables and to deny the access to the unsafe memory.
The pipe callback handlers are invoked whenever new data is available for reading from the pipe.
Two Serial Single-Wire modes of operation are enabled. The “external” mode has the RX and TX shorted on-board. The “true” single-wire mode interconnects internally when the MCU or UART modules support it.
The following sections briefly describe all FreeMASTER features implemented by the driver. See the PC-based FreeMASTER User Manual for more details on how to use the features to monitor, tune, or control an embedded application.
Board Detection
The FreeMASTER protocol V4 defines the standard set of configuration values which the host PC tool reads to identify the target and to access other target resources properly. The configuration includes the following parameters:
Version of the driver and the version of the protocol implemented.
MTU as the Maximum size of the Transmission Unit (for example; communication buffer size).
Application name, description, and version strings.
Application build date and time as a string.
Target processor byte ordering (little/big endian).
Protection level that requires password authentication.
Number of the Recorder and Oscilloscope instances.
RAM Base Address for optimized memory access commands.
Memory Read
This basic feature enables the host PC to read any data memory location by specifying the address and size of the required memory area. The device response frame must be shorter than the MTU to fit into the outgoing communication buffer. To read a device memory of any size, the host uses the information retrieved during the Board Detection and splits the large-block request to multiple partial requests.
The driver uses size-aligned operations to read the target memory (for example; uses proper read-word instruction when an address is aligned to 4 bytes).
Memory Write
Similarly to the Memory Read operation, the Memory Write feature enables to write to any RAM memory location on the target device. A single write command frame must be shorter than the MTU to fit into the target communication buffer. Larger requests must be split into smaller ones.
The driver uses size-aligned operations to write to the target memory (for example; uses proper write-word instruction when an address is aligned to 4 bytes).
Masked Memory Write
To implement the write access to a single bit or a group of bits of target variables, the Masked Memory Write feature is available in the FreeMASTER protocol and it is supported by the driver using the Read-Modify-Write approach.
Be careful when writing to bit fields of volatile variables that are also modified in an application interrupt. The interrupt may be serviced in the middle of a read-modify-write operation and it may cause data corruption.
Oscilloscope
The protocol and driver enables any number of variables to be read at once with a single request from the host. This feature is called Oscilloscope and the FreeMASTER tool uses it to display a real-time graph of variable values.
The driver can be configured to support any number of Oscilloscope instances and enable simultaneously running graphs to be displayed on the host computer screen.
Recorder
The protocol enables the host to select target variables whose values are then periodically recorded into a dedicated on-board memory buffer. After such data sampling stops (either on a host request or by evaluating a threshold-crossing condition), the data buffer is downloaded to the host and displayed as a graph. The data sampling rate is not limited by the speed of the communication line, so it enables displaying the variable transitions in a very high resolution.
The driver can be configured to support multiple Recorder instances and enable multiple recorder graphs to be displayed on the host screen. Having multiple recorders also enables setting the recording point differently for each instance. For example; one instance may be recording data in a general timer interrupt while another instance may record at a specific control algorithm time in the PWM interrupt.
TSA
With the TSA feature, data types and variables can be described directly in the application source code. Such information is later provided to the FreeMASTER tool which may use it instead of reading symbol data from the application ELF executable file.
The information is encoded as so-called TSA tables which become direct part of the application code. The TSA tables contain descriptors of variables that shall be visible to the host tool. The descriptors can describe the memory areas by specifying the address and size of the memory block or more conveniently using the C variable names directly. Different set of TSA descriptors can be used to encode information about the structure types, unions, enumerations, or arrays.
The driver also supports special types of TSA table entries to describe user resources like external EEPROM and SD Card files, memory-mapped files, virtual directories, web URL hyperlinks, and constant enumerations.
TSA Safety
When the TSA is enabled in the application, the TSA Safety can be enabled and validate the memory accesses directly by the embedded-side driver. When the TSA Safety is turned on, any memory request received from the host is validated and accepted only if it belongs to a TSA-described object. The TSA entries can be declared as Read-Write or Read-Only so that the driver can actively deny the write access to the Read-Only objects.
Application commands
The Application Commands are high-level messages that can be delivered from the PC Host to the embedded application for further processing. The embedded application can either poll the status, or be called back when a new Application Command arrives to be processed. After the embedded application acknowledges that the command is handled, the host receives the Result Code and reads the other return data from memory. Both the Application Commands and the Result Codes are specific to a given application and it is user’s responsibility to define them. The FreeMASTER protocol and the FreeMASTER driver only implement the delivery channel and a set of API calls to enable the Application Command processing in general.
Pipes
The Pipes enable buffered and stream-oriented data exchange between the PC Host and the target application. Any pipe can be written to and read from at both ends (either on the PC or the MCU). The data transmission is acknowledged using the special FreeMASTER protocol commands. It is guaranteed that the data bytes are delivered from the writer to the reader in a proper order and without losses.
Serial single-wire operation
The MCU Serial Communication Driver natively supports normal dual-wire operation. Because the protocol is half-duplex only, the driver can also operate in two single-wire modes:
“External” single-wire operation where the Receiver and Transmitter pins are shorted on the board. This mode is supported by default in the MCU driver because the Receiver and Transmitter units are enabled or disabled whenever needed. It is also easy to extend this operation for the RS485 communication.
“True” single-wire mode which uses only a single pin and the direction switching is made by the UART module. This mode of operation must be enabled by defining the FMSTR_SERIAL_SINGLEWIRE configuration option.
Multi-session support
With networking interface it is possible for multiple clients to access the target MCU simultaneously. Reading and writing of target memory is processed atomically so there is no risk of data corruption. The state-full resources such as Recorders or Oscilloscopes are locked to a client session upon first use and access is denied to other clients until lock is released..
Driver files
The driver source files can be found in a top-level src folder, further divided into the sub-folders:
src/platforms platform-specific folder—one folder exists for each supported processor platform (for example; 32-bit Little Endian platform). Each such folder contains a platform header file with data types and a code which implements the potentially platform-specific operations, such as aligned memory access.
src/common folder—contains the common driver source files shared by the driver for all supported platforms. All the .c files must be added to the project, compiled, and linked together with the application.
freemaster.h - master driver header file, which declares the common data types, macros, and prototypes of the FreeMASTER driver API functions.
freemaster_cfg.h.example - this file can serve as an example of the FreeMASTER driver configuration file. Save this file into a project source code folder and rename it to freemaster_cfg.h. The FreeMASTER driver code includes this file to get the project-specific configuration options and to optimize the compilation of the driver.
freemaster_defcfg.h - defines the default values for each FreeMASTER configuration option if the option is not set in the freemaster_cfg.h file.
freemaster_protocol.h - defines the FreeMASTER protocol constants used internally by the driver.
freemaster_protocol.c - implements the FreeMASTER protocol decoder and handles the basic Get Configuration Value, Memory Read, and Memory Write commands.
freemaster_rec.c - handles the Recorder-specific commands and implements the Recorder sampling and triggering routines. When the Recorder is disabled by the FreeMASTER driver configuration file, this file only compiles to empty API functions.
freemaster_scope.c - handles the Oscilloscope-specific commands. If the Oscilloscope is disabled by the FreeMASTER driver configuration file, this file compiles as void.
freemaster_pipes.c - implements the Pipes functionality when the Pipes feature is enabled.
freemaster_appcmd.c - handles the communication commands used to deliver and execute the Application Commands within the context of the embedded application. When the Application Commands are disabled by the FreeMASTER driver configuration file, this file only compiles to empty API functions.
freemaster_tsa.c - handles the commands specific to the TSA feature. This feature enables the FreeMASTER host tool to obtain the TSA memory descriptors declared in the embedded application. If the TSA is disabled by the FreeMASTER driver configuration file, this file compiles as void.
freemaster_tsa.h - contains the declaration of the macros used to define the TSA memory descriptors. This file is indirectly included into the user application code (via freemaster.h).
freemaster_sha.c - implements the SHA-1 hash code used in the password authentication algorithm.
freemaster_private.h - contains the declarations of functions and data types used internally in the driver. It also contains the C pre-processor statements to perform the compile-time verification of the user configuration provided in the freemaster_cfg.h file.
freemaster_serial.c - implements the serial protocol logic including the CRC, FIFO queuing, and other communication-related operations. This code calls the functions of the low-level communication driver indirectly via a character-oriented API exported by the specific low-level driver.
freemaster_serial.h - defines the low-level character-oriented Serial API.
freemaster_can.c - implements the CAN protocol logic including the CAN message preparation, signalling using the first data byte in the CAN frame, and other communication-related operations. This code calls the functions of the low-level communication driver indirectly via a message-oriented API exported by the specific low-level driver.
freemaster_can.h - defines the low-level message-oriented CAN API.
freemaster_net.c - implements the Network protocol transport logic including multiple session management code.
freemaster_net.h - definitions related to the Network transport.
freemaster_pdbdm.c - implements the packet-driven BDM communication buffer and other communication-related operations.
freemaster_utils.c - aligned memory copy routines, circular buffer management and other utility functions
freemaster_utils.h - definitions related to utility code.
src/drivers/[sdk]/serial - contains the code related to the serial communication implemented using one of the supported SDK frameworks.
freemaster_serial_XXX.c and .h - implement low-level access to the communication peripheral registers. Different files exist for the UART, LPUART, USART, and other kinds of Serial communication modules.
src/drivers/[sdk]/can - contains the code related to the serial communication implemented using one of the supported SDK frameworks.
freemaster_XXX.c and .h - implement low-level access to the communication peripheral registers. Different files exist for the FlexCAN, msCAN, MCAN, and other kinds of CAN communication modules.
src/drivers/[sdk]/network - contains low-level code adapting the FreeMASTER Network transport to an underlying TCP/IP or RTT stack.
freemaster_net_lwip_tcp.c and _udp.c - default networking implementation of TCP and UDP transports using lwIP stack.
freemaster_net_segger_rtt.c - implementation of network transport using Segger J-Link RTT interface
Driver configuration
The driver is configured using a single header file (freemaster_cfg.h). Create this file and save it together with other project source files before compiling the driver code. All FreeMASTER driver source files include the freemaster_cfg.h file and use the macros defined here for the conditional and parameterized compilation. The C compiler must locate the configuration file when compiling the driver files. Typically, it can be achieved by putting this file into a folder where the other project-specific included files are stored.
As a starting point to create the configuration file, get the freemaster_cfg.h.example file, rename it to freemaster_cfg.h, and save it into the project area.
Note: It is NOT recommended to leave the freemaster_cfg.h file in the FreeMASTER driver source code folder. The configuration file must be placed at a project-specific location, so that it does not affect the other applications that use the same driver.
Configurable items
This section describes the configuration options which can be defined in freemaster_cfg.h.
Interrupt modes
#define FMSTR_LONG_INTR [0|1]
#define FMSTR_SHORT_INTR [0|1]
#define FMSTR_POLL_DRIVEN [0|1]
Value Type
boolean (0 or 1)
Description
Exactly one of the three macros must be defined to non-zero. The others must be defined to zero or left undefined. The non-zero-defined constant selects the interrupt mode of the driver. See Driver interrupt modes.
FMSTR_LONG_INTR— long interrupt modeFMSTR_SHORT_INTR— short interrupt modeFMSTR_POLL_DRIVEN— poll-driven mode
Note: Some options may not be supported by all communication interfaces. For example, the FMSTR_SHORT_INTR option is not supported by the USB_CDC interface.
Protocol transport
#define FMSTR_TRANSPORT [identifier]
Value Type
Driver identifiers are structure instance names defined in FreeMASTER source code. Specify one of existing instances to make use of the protocol transport.
Description
Use one of the pre-defined constants, as implemented by the FreeMASTER code. The current driver supports the following transports:
FMSTR_SERIAL - serial communication protocol
FMSTR_CAN - using CAN communication
FMSTR_PDBDM - using packet-driven BDM communication
FMSTR_NET - network communication using TCP or UDP protocol
Serial transport
This section describes configuration parameters used when serial transport is used:
#define FMSTR_TRANSPORT FMSTR_SERIAL
FMSTR_SERIAL_DRV
Select what low-level driver interface will be used when implementing the Serial communication.
#define FMSTR_SERIAL_DRV [identifier]
Value Type
Driver identifiers are structure instance names defined in FreeMASTER drivers code. Specify one of existing serial driver instances.
Description
When using MCUXpresso SDK, use one of the following constants (see /drivers/mcuxsdk/serial implementation):
FMSTR_SERIAL_MCUX_UART - UART driver
FMSTR_SERIAL_MCUX_LPUART - LPUART driver
FMSTR_SERIAL_MCUX_USART - USART driver
FMSTR_SERIAL_MCUX_MINIUSART - miniUSART driver
FMSTR_SERIAL_MCUX_QSCI - DSC QSCI driver
FMSTR_SERIAL_MCUX_USB - USB/CDC class driver (also see code in the /support/mcuxsdk_usb folder)
FMSTR_SERIAL_56F800E_EONCE - DSC JTAG EOnCE driver
Other SDKs or BSPs may define custom low-level driver interface structure which may be used as FMSTR_SERIAL_DRV. For example:
FMSTR_SERIAL_DREG_UART - demonstrates the low-level interface implemented without the MCUXpresso SDK and using direct access to peripheral registers.
FMSTR_SERIAL_BASE
#define FMSTR_SERIAL_BASE [address|symbol]
Value Type
Optional address value (numeric or symbolic)
Description
Specify the base address of the UART, LPUART, USART, or other serial peripheral module to be used for the communication.
This value is not defined by default. User application should call FMSTR_SetSerialBaseAddress() to select the peripheral module.
FMSTR_COMM_BUFFER_SIZE
#define FMSTR_COMM_BUFFER_SIZE [number]
Value Type
0 or a value in range 32…255
Description
Specify the size of the communication buffer to be allocated by the driver.
Default value, which suits all driver features, is used when this option is defined as 0.
FMSTR_COMM_RQUEUE_SIZE
#define FMSTR_COMM_RQUEUE_SIZE [number]
Value Type
Value in range 0…255
Description
Specify the size of the FIFO receiver queue used to quickly receive and store characters in the FMSTR_SHORT_INTR interrupt mode.
The default value is 32 B.
FMSTR_SERIAL_SINGLEWIRE
#define FMSTR_SERIAL_SINGLEWIRE [0|1]
Value Type
Boolean 0 or 1.
Description
Set to non-zero to enable the “True” single-wire mode which uses a single MCU pin to communicate. The low-level driver enables the pin direction switching when the MCU peripheral supports it.
CAN Bus transport
This section describes configuration parameters used when CAN transport is used:
#define FMSTR_TRANSPORT FMSTR_CAN
FMSTR_CAN_DRV
Select what low-level driver interface will be used when implementing the CAN communication.
#define FMSTR_CAN_DRV [identifier]
Value Type
Driver identifiers are structure instance names defined in FreeMASTER drivers code. Specify one of existing CAN driver instances.
Description
When using MCUXpresso SDK, use one of the following constants (see /drivers/mcuxsdk/can implementation):
FMSTR_CAN_MCUX_FLEXCAN - FlexCAN driver
FMSTR_CAN_MCUX_MCAN - MCAN driver
FMSTR_CAN_MCUX_MSCAN - msCAN driver
FMSTR_CAN_MCUX_DSCFLEXCAN - DSC FlexCAN driver
FMSTR_CAN_MCUX_DSCMSCAN - DSC msCAN driver
Other SDKs or BSPs may define the custom low-level driver interface structure which may be used as FMSTR_CAN_DRV.
FMSTR_CAN_BASE
#define FMSTR_CAN_BASE [address|symbol]
Value Type
Optional address value (numeric or symbolic)
Description
Specify the base address of the FlexCAN, msCAN, or other CAN peripheral module to be used for the communication.
This value is not defined by default. User application should call FMSTR_SetCanBaseAddress() to select the peripheral module.
FMSTR_CAN_CMDID
#define FMSTR_CAN_CMDID [number]
Value Type
CAN identifier (11-bit or 29-bit number)
Description
CAN message identifier used for FreeMASTER commands (direction from PC Host tool to target application). When declaring 29-bit identifier, combine the numeric value with FMSTR_CAN_EXTID bit. Default value is 0x7AA.
FMSTR_CAN_RSPID
#define FMSTR_CAN_RSPID [number]
Value Type
CAN identifier (11-bit or 29-bit number)
Description
CAN message identifier used for responding messages (direction from target application to PC Host tool). When declaring 29-bit identifier, combine the numeric value with FMSTR_CAN_EXTID bit. Note that both CMDID and RSPID values may be the same. Default value is 0x7AA.
FMSTR_FLEXCAN_TXMB
#define FMSTR_FLEXCAN_TXMB [number]
Value Type
Number in range of 0..N where N is number of CAN message-buffers supported by HW module.
Description
Only used when the FlexCAN low-level driver is used. Define the FlexCAN message buffer for CAN frame transmission. Default value is 0.
FMSTR_FLEXCAN_RXMB
#define FMSTR_FLEXCAN_RXMB [number]
Value Type
Number in range of 0..N where N is number of CAN message-buffers supported by HW module.
Description
Only used when the FlexCAN low-level driver is used. Define the FlexCAN message buffer for CAN frame reception. Note that the FreeMASTER driver may also operate with a common message buffer used by both TX and RX directions. Default value is 1.
Network transport
This section describes configuration parameters used when Network transport is used:
#define FMSTR_TRANSPORT FMSTR_NET
FMSTR_NET_DRV
Select network interface implementation.
#define FMSTR_NET_DRV [identifier]
Value Type
Identifiers are structure instance names defined in FreeMASTER drivers code. Specify one of existing NET driver instances.
Description
When using MCUXpresso SDK, use one of the following constants (see /drivers/mcuxsdk/network implementation):
FMSTR_NET_LWIP_TCP - TCP communication using lwIP stack
FMSTR_NET_LWIP_UDP - UDP communication using lwIP stack
FMSTR_NET_SEGGER_RTT - Communication using SEGGER J-Link RTT interface
Other SDKs or BSPs may define the custom networking interface which may be used as FMSTR_CAN_DRV.
Add another row below:
FMSTR_NET_PORT
#define FMSTR_NET_PORT [number]
Value Type
TCP or UDP port number (short integer)
Description
Specifies the server port number used by TCP or UDP protocols.
FMSTR_NET_BLOCKING_TIMEOUT
#define FMSTR_NET_BLOCKING_TIMEOUT [number]
Value Type
Timeout as number of milliseconds
Description
This value specifies a timeout in milliseconds for which the network socket operations may block the execution inside FMSTR_Poll. This may be set high (e.g. 250) when a dedicated RTOS task is used to handle FreeMASTER protocol polling. Set to a lower value when the polling task is also responsible for other operations. Set to 0 to attempt to use non-blocking socket operations.
FMSTR_NET_AUTODISCOVERY
#define FMSTR_NET_AUTODISCOVERY [0|1]
Value Type
Boolean 0 or 1.
Description
This option enables the FreeMASTER driver to use a separate UDP socket to broadcast auto-discovery messages to network. This helps the FreeMASTER tool to discover the target device address, port and protocol options.
Debugging options
FMSTR_DISABLE
#define FMSTR_DISABLE [0|1]
Value Type
boolean (0 or 1)
Description
Define as non-zero to disable all FreeMASTER features, exclude the driver code from build, and compile all its API functions empty. This may be useful to remove FreeMASTER without modifying any application source code. Default value is 0 (false).
FMSTR_DEBUG_TX
#define FMSTR_DEBUG_TX [0|1]
Value Type
Boolean 0 or 1.
Description
Define as non-zero to enable the driver to periodically transmit test frames out on the selected communication interface (SCI or CAN). With the debug transmission enabled, it is simpler to detect problems in the baudrate or other communication configuration settings.
The test frames are transmitted until the first valid command frame is received from the PC Host tool. The test frame is a valid error status frame, as defined by the protocol format. On the serial line, the test frame consists of three printable characters (+©W) which are easy to capture using the serial terminal tools.
This feature requires the FMSTR_Poll() function to be called periodically. Default value is 0 (false).
FMSTR_APPLICATION_STR
#define FMSTR_APPLICATION_STR
Value Type
String.
Description
Name of the application visible in FreeMASTER host application.
Memory access
FMSTR_USE_READMEM
#define FMSTR_USE_READMEM [0|1]
Value Type
Boolean 0 or 1.
Description
Define as non-zero to implement the Memory Read command and enable FreeMASTER to
have read access to memory and variables. The access can be further restricted
by using a TSA feature.
Default value is 1 (true).
FMSTR_USE_WRITEMEM
#define FMSTR_USE_WRITEMEM [0|1]
Value Type
Boolean 0 or 1.
Description
Define as non-zero to implement the Memory Write command.
The default value is 1 (true).
Oscilloscope options
FMSTR_USE_SCOPE
#define FMSTR_USE_SCOPE [number]
Value Type
Integer number.
Description
Number of Oscilloscope instances to be supported. Set to 0 to disable the Oscilloscope feature.
Default value is 0.
FMSTR_MAX_SCOPE_VARS
#define FMSTR_MAX_SCOPE_VARS [number]
Value Type
Integer number larger than 2.
Description
Number of variables to be supported by each Oscilloscope instance.
Default value is 8.
Recorder options
FMSTR_USE_RECORDER
#define FMSTR_USE_RECORDER [number]
Value Type
Integer number.
Description
Number of Recorder instances to be supported. Set to 0 to disable the Recorder feature.
Default value is 0.
FMSTR_REC_BUFF_SIZE
#define FMSTR_REC_BUFF_SIZE [number]
Value Type
Integer number larger than 2.
Description
Defines the size of the memory buffer used by the Recorder instance #0.
Default: not defined, user shall call `FMSTR_RecorderCreate()`` API function to specify this parameter in run time.
FMSTR_REC_TIMEBASE
#define FMSTR_REC_TIMEBASE [time specification]
Value Type
Number (nanoseconds time).
Description
Defines the base sampling rate in nanoseconds (sampling speed) Recorder instance #0.
Use one of the following macros:
FMSTR_REC_BASE_SECONDS(x)FMSTR_REC_BASE_MILLISEC(x)FMSTR_REC_BASE_MICROSEC(x)FMSTR_REC_BASE_NANOSEC(x)
Default: not defined, user shall call `FMSTR_RecorderCreate()`` API function to specify this parameter in run time.
FMSTR_REC_FLOAT_TRIG
#define FMSTR_REC_FLOAT_TRIG [0|1]
Value Type
Boolean 0 or 1.
Description
Define as non-zero to implement the floating-point triggering. Be aware that floating-point triggering may grow the code size by linking the floating-point standard library.
Default value is 0 (false).
Application Commands options
FMSTR_USE_APPCMD
#define FMSTR_USE_APPCMD [0|1]
Value Type
Boolean 0 or 1.
Description
Define as non-zero to implement the Application Commands feature.
Default value is 0 (false).
FMSTR_APPCMD_BUFF_SIZE
#define FMSTR_APPCMD_BUFF_SIZE [size]
Value Type
Numeric buffer size in range 1..255
Description
The size of the Application Command data buffer allocated by the driver. The buffer stores the (optional) parameters of the Application Command which waits to be processed.
FMSTR_MAX_APPCMD_CALLS
#define FMSTR_MAX_APPCMD_CALLS [number]
Value Type
Number in range 0..255
Description
The number of different Application Commands that can be assigned a callback handler function using FMSTR_RegisterAppCmdCall().
Default value is 0.
TSA options
FMSTR_USE_TSA
#define FMSTR_USE_TSA [0|1]
Value Type
Boolean 0 or 1.
Description
Enable the FreeMASTER TSA feature to be used. With this option enabled, the TSA tables defined
in the applications are made available to the FreeMASTER host tool.
Default value is 0 (false).
FMSTR_USE_TSA_SAFETY
#define FMSTR_USE_TSA_SAFETY [0|1]
Value Type
Boolean 0 or 1.
Description
Enable the memory access validation in the FreeMASTER driver. With this option, the host tool is not able to access the memory which is not described by at least one TSA descriptor. Also a write access is denied for objects defined as read-only in TSA tables.
Default value is 0 (false).
FMSTR_USE_TSA_INROM
#define FMSTR_USE_TSA_INROM [0|1]
Value Type
Boolean 0 or 1.
Description
Declare all TSA descriptors as const, which enables the linker to put the data into the flash memory. The actual result depends on linker settings or the linker commands used in the project.
Default value is 0 (false).
FMSTR_USE_TSA_DYNAMIC
#define FMSTR_USE_TSA_DYNAMIC [0|1]
Value Type
Boolean 0 or 1.
Description
Enable runtime-defined TSA entries to be added to the TSA table by the FMSTR_SetUpTsaBuff() and FMSTR_TsaAddVar() functions.
Default value is 0 (false).
Pipes options
FMSTR_USE_PIPES
#define FMSTR_USE_PIPES [0|1]
Value Type
Boolean 0 or 1.
Description
Enable the FreeMASTER Pipes feature to be used.
Default value is 0 (false).
FMSTR_MAX_PIPES_COUNT
#define FMSTR_MAX_PIPES_COUNT [number]
Value Type
Number in range 1..63.
Description
The number of simultaneous pipe connections to support.
The default value is 1.
Driver interrupt modes
To implement the communication, the FreeMASTER driver handles the Serial or CAN module’s receive and transmit requests. Use the freemaster_cfg.h configuration file to select whether the driver processes the communication automatically in the interrupt service routine handler or if it only polls the status of the module (typically during the application idle time).
This section describes each of the interrupt mode in more details.
Completely Interrupt-Driven operation
Activated using:
#define FMSTR_LONG_INTR 1
In this mode, both the communication and the FreeMASTER protocol decoding is done in the FMSTR_SerialIsr, FMSTR_CanIsr, or other interrupt service routine. Because the protocol execution may be a lengthy task (especially with the TSA-Safety enabled) it is recommended to use this mode only if the interrupt prioritization scheme is possible in the application and the FreeMASTER interrupt is assigned to a lower (the lowest) priority.
In this mode, the application code must register its own interrupt handler for all interrupt vectors related to the selected communication interface and call the FMSTR_SerialIsr or FMSTR_CanIsr functions from that handler.
Mixed Interrupt and Polling Modes
Activated using:
#define FMSTR_SHORT_INTR 1
In this mode, the communication processing time is split between the interrupt routine and the main application loop or task. The raw communication is handled by the FMSTR_SerialIsr, FMSTR_CanIsr, or other interrupt service routine, while the protocol decoding and execution is handled by the FMSTR_Poll routine. Call FMSTR_Poll during the idle time in the application main loop.
The interrupt processing in this mode is relatively fast and deterministic. Upon a serial-receive event, the received character is only placed into a FIFO-like queue and it is not further processed. Upon a CAN receive event, the received frame is stored into a receive buffer. When transmitting, the characters are fetched from the prepared transmit buffer.
In this mode, the application code must register its own interrupt handler for all interrupt vectors related to the selected communication interface and call the FMSTR_SerialIsr or FMSTR_CanIsr functions from that handler.
When the serial interface is used as the serial communication interface, ensure that the FMSTR_Poll function is called at least once per N character time periods. N is the length of the FreeMASTER FIFO queue (FMSTR_COMM_RQUEUE_SIZE) and the character time is the time needed to transmit or receive a single byte over the SCI line.
Completely Poll-driven
#define FMSTR_POLL_DRIVEN 1
In this mode, both the communication and the FreeMASTER protocol decoding are done in the FMSTR_Poll routine. No interrupts are needed and the FMSTR_SerialIsr, FMSTR_CanIsr, and similar handlers compile to an empty code.
When using this mode, ensure that the FMSTR_Poll function is called by the application at least once per the serial “character time” which is the time needed to transmit or receive a single character.
In the latter two modes (FMSTR_SHORT_INTR and FMSTR_POLL_DRIVEN), the protocol handling takes place in the FMSTR_Poll routine. An application interrupt can occur in the middle of the Read Memory or Write Memory commands’ execution and corrupt the variable being accessed by the FreeMASTER driver. In these two modes, some issues or glitches may occur when using FreeMASTER to visualize or monitor volatile variables modified in interrupt servicing code.
The same issue may appear even in the full interrupt mode (FMSTR_LONG_INTR), if volatile variables are modified in the interrupt code with a priority higher than the priority of the communication interrupt.
Data types
Simple portability was one of the main requirements when writing the FreeMASTER driver. This is why the driver code uses the privately-declared data types and the vast majority of the platform-dependent code is separated in the platform-dependent source files. The data types used in the driver API are all defined in the platform-specific header file.
To prevent name conflicts with the symbols used in the application, all data types, macros, and functions have the FMSTR_ prefix. The only global variables used in the driver are the transport and low-level API structures exported from the driver-implementation layer to upper layers. Other than that, all private variables are declared as static and named using the fmstr_ prefix.
Communication interface initialization
The FreeMASTER driver does not perform neither the initialization nor the configuration of the peripheral module that it uses to communicate. It is the application startup code responsibility to configure the communication module before the FreeMASTER driver is initialized by the FMSTR_Init call.
When the Serial communication module is used as the FreeMASTER communication interface, configure the UART receive and transmit pins, the serial communication baud rate, parity (no-parity), the character length (eight bits), and the number of stop bits (one) before initializing the FreeMASTER driver. For either the long or the short interrupt modes of the driver (see Driver interrupt modes), configure the interrupt controller and register an application-specific interrupt handler for all interrupt sources related to the selected serial peripheral module. Call the FMSTR_SerialIsr function from the application handler.
When a CAN module is used as the FreeMASTER communication interface, configure the CAN receive and transmit pins and the CAN module bit rate before initializing the FreeMASTER driver. For either the long or the short interrupt modes of the driver (see Driver interrupt modes), configure the interrupt controller and register an application-specific interrupt handler for all interrupt sources related to the selected CAN peripheral module. Call the FMSTR_CanIsr function from the application handler.
Note: It is not necessary to enable or unmask the serial nor the CAN interrupts before initializing the FreeMASTER driver. The driver enables or disables the interrupts and communication lines, as required during runtime.
FreeMASTER Recorder calls
When using the FreeMASTER Recorder in the application (FMSTR_USE_RECORDER > 0), call the FMSTR_RecorderCreate function early after FMSTR_Init to set up each recorder instance to be used in the application. Then call the FMSTR_Recorder function periodically in the code where the data recording should occur. A typical place to call the Recorder routine is at the timer or PWM interrupts, but it can be anywhere else. The example applications provided together with the driver code call the FMSTR_Recorder in the main application loop.
In applications where FMSTR_Recorder is called periodically with a constant period, specify the period in the Recorder configuration structure before calling FMSTR_RecorderCreate. This setting enables the PC Host FreeMASTER tool to display the X-axis of the Recorder graph properly scaled for the time domain.
Driver usage
Start using or evaluating FreeMASTER by opening some of the example applications available in the driver setup package.
Follow these steps to enable the basic FreeMASTER connectivity in the application:
Make sure that all *.c files of the FreeMASTER driver from the src/common/platforms/[your_platform] folder are a part of the project. See Driver files for more details.
Configure the FreeMASTER driver by creating or editing the freemaster_cfg.h file and by saving it into the application project directory. See Driver configuration for more details.
Include the freemaster.h file into any application source file that makes the FreeMASTER API calls.
Initialize the Serial or CAN modules. Set the baud rate, parity, and other parameters of the communication. Do not enable the communication interrupts in the interrupt mask registers.
For the FMSTR_LONG_INTR and FMSTR_SHORT_INTR modes, install the application-specific interrupt routine and call the FMSTR_SerialIsr or FMSTR_CanIsr functions from this handler.
Call the FMSTR_Init function early on in the application initialization code.
Call the FMSTR_RecorderCreate functions for each Recorder instance to enable the Recorder feature.
In the main application loop, call the FMSTR_Poll API function periodically when the application is idle.
For the FMSTR_SHORT_INTR and FMSTR_LONG_INTR modes, enable the interrupts globally so that the interrupts can be handled by the CPU.
Communication troubleshooting
The most common problem that causes communication issues is a wrong baud rate setting or a wrong pin multiplexer setting of the target MCU. When a communication between the PC Host running FreeMASTER and the target MCU cannot be established, try enabling the FMSTR_DEBUG_TX option in the freemaster_cfg.h file and call the FMSTR_Poll function periodically in the main application task loop.
With this feature enabled, the FreeMASTER driver periodically transmits a test frame through the Serial or CAN lines. Use a logic analyzer or an oscilloscope to monitor the signals at the communication pins of the CPU device to examine whether the bit rate and signal polarity are configured properly.
Driver API
This section describes the driver Application Programmers’ Interface (API) needed to initialize and use the FreeMASTER serial communication driver.
Control API
There are three key functions to initialize and use the driver.
FMSTR_Init
Prototype
FMSTR_BOOL FMSTR_Init(void);
Declaration: freemaster.h
Implementation: freemaster_protocol.c
Description
This function initializes the internal variables of the FreeMASTER driver and enables the communication interface. This function does not change the configuration of the selected communication module. The hardware module must be initialized before the FMSTR_Init function is called.
A call to this function must occur before calling any other FreeMASTER driver API functions.
FMSTR_Poll
Prototype
void FMSTR_Poll(void);
Declaration: freemaster.h
Implementation: freemaster_protocol.c
Description
In the poll-driven or short interrupt modes, this function handles the protocol decoding and execution (see Driver interrupt modes). In the poll-driven mode, this function also handles the communication interface with the PC. Typically, the FMSTR_Poll function is called during the “idle” time in the main application task loop.
To prevent the receive data overflow (loss) on a serial interface, make sure that the FMSTR_Poll function is called at least once per the time calculated as:
N * Tchar
where:
N is equal to the length of the receive FIFO queue (configured by the FMSTR_COMM_RQUEUE_SIZE macro). N is 1 for the poll-driven mode.
Tchar is the character time, which is the time needed to transmit or receive a single byte over the SCI line.
Note: In the long interrupt mode, this function typically compiles as an empty function and can still be called. It is worthwhile to call this function regardless of the interrupt mode used in the application. This approach enables a convenient switching between the different interrupt modes only by changing the configuration macros in the freemaster_cfg.h file.
FMSTR_SerialIsr / FMSTR_CanIsr
Prototype
void FMSTR_SerialIsr(void);
void FMSTR_CanIsr(void);
Declaration: freemaster.h
Implementation: hw-specific low-level driver C file
Description
This function contains the interrupt-processing code of the FreeMASTER driver. In long or short interrupt modes (see Driver interrupt modes), this function must be called from the application interrupt service routine registered for the communication interrupt vector. On platforms where the communication module uses multiple interrupt vectors, the application should register a handler for all vectors and call this function at each interrupt.
Note: In a poll-driven mode, this function is compiled as an empty function and does not have to be used.
Recorder API
FMSTR_RecorderCreate
Prototype
FMSTR_BOOL FMSTR_RecorderCreate(FMSTR_INDEX recIndex, FMSTR_REC_BUFF* buffCfg);
Declaration: freemaster.h
Implementation: freemaster_rec.c
Description
This function registers a recorder instance and enables it to be used by the PC Host tool. Call this function for all recorder instances from 0 to the maximum number defined by the FMSTR_USE_RECORDER configuration option (minus one). An exception to this requirement is the recorder of instance 0 which may be automatically configured by FMSTR_Init when the freemaster_cfg.h configuration file defines the FMSTR_REC_BUFF_SIZE and FMSTR_REC_TIMEBASE options.
For more information, see Configurable items.
FMSTR_Recorder
Prototype
void FMSTR_Recorder(FMSTR_INDEX recIndex);
Declaration: freemaster.h
Implementation: freemaster_rec.c
Description
This function takes a sample of the variables being recorded using the FreeMASTER Recorder instance recIndex. If the selected Recorder is not active when the FMSTR_Recorder function is being called, the function returns immediately. When the Recorder is active, the values of the variables being recorded are copied into the recorder buffer and the trigger conditions are evaluated.
If a trigger condition is satisfied, the Recorder enters the post-trigger mode, where it counts down the follow-up samples (number of FMSTR_Recorder function calls) and de-activates the Recorder when the required post-trigger samples are finished.
The FMSTR_Recorder function is typically called in the timer or PWM interrupt service routines. This function can also be called in the application main loop (for testing purposes).
FMSTR_RecorderTrigger
Prototype
void FMSTR_RecorderTrigger(FMSTR_INDEX recIndex);
Declaration: freemaster.h
Implementation: freemaster_rec.c
Description
This function forces the Recorder trigger condition to happen, which causes the Recorder to be automatically deactivated after the post-trigger samples are sampled. Use this function in the application code for programmatic control over the Recorder triggering. This can be useful when a more complex triggering conditions need to be used.
Fast Recorder API
The Fast Recorder feature is not available in the FreeMASTER driver version 3. This feature was heavily dependent on the target platform and it was only available for the 56F8xxxx DSCs.
TSA Tables
When the TSA is enabled in the FreeMASTER driver configuration file (by setting the FMSTR_USE_TSA macro to a non-zero value), it defines the so-called TSA tables in the application. This section describes the macros that must to be used to define the TSA tables.
There can be any number of TSA tables spread across the application source files. There must be always exactly one TSA Table List defined, which informs the FreeMASTER driver about the active TSA tables.
When there is at least one TSA table and one TSA Table List defined in the application, the TSA information automatically appears in the FreeMASTER symbols list. The symbols can then be used to create FreeMASTER variables for visualization or control.
TSA table definition
The TSA table describes the static or global variables together with their address, size, type, and access-protection information. If the TSA-described variables are of a structure type, the TSA table may also describe this type and provide an access to the individual structure members of the variable.
The TSA table definition begins with the FMSTR_TSA_TABLE_BEGIN macro with a table_id identifying the table. The table_id shall be a valid C-langiage symbol.
FMSTR_TSA_TABLE_BEGIN(table_id)
After this opening macro, the TSA descriptors are placed using these macros:
/* Adding variable descriptors */
FMSTR_TSA_RW_VAR(name, type) /* read/write variable entry */
FMSTR_TSA_RO_VAR(name, type) /* read-only variable entry */
/* Description of complex data types */
FMSTR_TSA_STRUCT(struct_name) /* structure or union type entry */
FMSTR_TSA_MEMBER(struct_name, member_name, type) /* structure member entry */
/* Memory blocks */
FMSTR_TSA_RW_MEM(name, type, address, size) /* read/write memory block */
FMSTR_TSA_RO_MEM(name, type, address, size) /* read-only memory block */
The table is closed using the FMSTR_TSA_TABLE_END macro:
FMSTR_TSA_TABLE_END()
TSA descriptor parameters
The TSA descriptor macros accept these parameters:
name — variable name. The variable must be defined before the TSA descriptor references it.
type — variable or member type. Only one of the pre-defined type constants may be used (see below).
struct_name — structure type name. The type must be defined (typedef) before the TSA descriptor references it.
member_name — structure member name.
Note: The structure member descriptors (FMSTR_TSA_MEMBER) must immediately follow the parent structure descriptor (FMSTR_TSA_STRUCT) in the table.
Note: To write-protect the variables in the FreeMASTER driver (FMSTR_TSA_RO_VAR), enable the TSA-Safety feature in the configuration file.
TSA variable types
The table lists type identifiers which can be used in TSA descriptors:
Constant |
Description |
|---|---|
FMSTR_TSA_UINTn |
Unsigned integer type of size n bits (n=8,16,32,64) |
FMSTR_TSA_SINTn |
Signed integer type of size n bits (n=8,16,32,64) |
FMSTR_TSA_FRACn |
Fractional number of size n bits (n=16,32,64). |
FMSTR_TSA_FRAC_Q(m,n) |
Signed fractional number in general Q form (m+n+1 total bits) |
FMSTR_TSA_FRAC_UQ(m,n) |
Unsigned fractional number in general UQ form (m+n total bits) |
FMSTR_TSA_FLOAT |
4-byte standard IEEE floating-point type |
FMSTR_TSA_DOUBLE |
8-byte standard IEEE floating-point type |
FMSTR_TSA_POINTER |
Generic pointer type defined (platform-specific 16 or 32 bit) |
FMSTR_TSA_USERTYPE(name) |
Structure or union type declared with FMSTR_TSA_STRUCT record |
TSA table list
There shall be exactly one TSA Table List in the application. The list contains one entry for each TSA table defined anywhere in the application.
The TSA Table List begins with the FMSTR_TSA_TABLE_LIST_BEGIN macro and continues with the TSA table entries for each table.
FMSTR_TSA_TABLE_LIST_BEGIN()
FMSTR_TSA_TABLE(table_id)
FMSTR_TSA_TABLE(table_id2)
FMSTR_TSA_TABLE(table_id3)
...
The list is closed with the FMSTR_TSA_TABLE_LIST_END macro:
FMSTR_TSA_TABLE_LIST_END()
TSA Active Content entries
FreeMASTER v2.0 and higher supports TSA Active Content, enabling the TSA tables to describe the memory-mapped files, virtual directories, and URL hyperlinks. FreeMASTER can access such objects similarly to accessing the files and folders on the local hard drive.
With this set of TSA entries, the FreeMASTER pages can be embedded directly into the target MCU flash and accessed by FreeMASTER directly over the communication line. The HTML-coded pages rendered inside the FreeMASTER window can access the TSA Active Content resources using a special URL referencing the fmstr: protocol.
This example provides an overview of the supported TSA Active Content entries:
FMSTR_TSA_TABLE_BEGIN(files_and_links)
/* Directory entry applies to all subsequent MEMFILE entries */
FMSTR_TSA_DIRECTORY("/text_files") /* entering a new virtual directory */
/* The readme.txt file will be accessible at the fmstr://text_files/readme.txt URL */
FMSTR_TSA_MEMFILE("readme.txt", readme_txt, sizeof(readme_txt)) /* memory-mapped file */
/* Files can also be specified with a full path so the DIRECTORY entry does not apply */
FMSTR_TSA_MEMFILE("/index.htm", index, sizeof(index)) /* memory-mapped file */
FMSTR_TSA_MEMFILE("/prj/demo.pmp", demo_pmp, sizeof(demo_pmp)) /* memory-mapped file */
/* Hyperlinks can point to a local MEMFILE object or to the Internet */
FMSTR_TSA_HREF("Board's Built-in Welcome Page", "/index.htm")
FMSTR_TSA_HREF("FreeMASTER Home Page", "http://www.nxp.com/freemaster")
/* Project file links simplify opening the projects from any URLs */
FMSTR_TSA_PROJECT("Demonstration Project (embedded)", "/prj/demo.pmp")
FMSTR_TSA_PROJECT("Full Project (online)", "http://mycompany.com/prj/demo.pmp")
FMSTR_TSA_TABLE_END()
TSA API
FMSTR_SetUpTsaBuff
Prototype
FMSTR_BOOL FMSTR_SetUpTsaBuff(FMSTR_ADDR buffAddr, FMSTR_SIZE buffSize);
Declaration: freemaster.h
Implementation: freemaster_tsa.c
Arguments
buffAddr [in] - address of the memory buffer for the dynamic TSA table
buffSize [in] - size of the memory buffer which determines the maximum number of TSA entries to be added in the runtime
Description
This function must be used to assign the RAM memory buffer to the TSA subsystem when FMSTR_USE_TSA_DYNAMIC is enabled. The memory buffer is then used to store the TSA entries added dynamically to the runtime TSA table using the FMSTR_TsaAddVar function call. The runtime TSA table is processed by the FreeMASTER PC Host tool along with all static tables as soon as the communication port is open.
The size of the memory buffer determines the number of TSA entries that can be added dynamically. Depending on the MCU platform, one TSA entry takes either 8 or 16 bytes.
FMSTR_TsaAddVar
Prototype
FMSTR_BOOL FMSTR_TsaAddVar(FMSTR_TSATBL_STRPTR tsaName, FMSTR_TSATBL_STRPTR tsaType,
FMSTR_TSATBL_VOIDPTR varAddr, FMSTR_SIZE32 varSize,
FMSTR_SIZE flags);
Declaration: freemaster.h
Implementation: freemaster_tsa.c
Arguments
tsaName [in] - name of the object
tsaType [in] - name of the object type
varAddr [in] - address of the object
varSize [in] - size of the object
flags [in] - access flags; a combination of these values:
FMSTR_TSA_INFO_RO_VAR — read-only memory-mapped object (typically a variable)
FMSTR_TSA_INFO_RW_VAR — read/write memory-mapped object
FMSTR_TSA_INFO_NON_VAR — other entry, describing structure types, structure members, enumerations, and other types
Description
This function can be called only when the dynamic TSA table is enabled by the FMSTR_USE_TSA_DYNAMIC configuration option and when the FMSTR_SetUpTsaBuff function call is made to assign the dynamic TSA table memory. This function adds an entry into the dynamic TSA table. It can be used to register a read-only or read/write memory object or describe an item of the user-defined type.
See TSA table definition for more details about the TSA table entries.
Application Commands API
FMSTR_GetAppCmd
Prototype
FMSTR_APPCMD_CODE FMSTR_GetAppCmd(void);
Declaration: freemaster.h
Implementation: freemaster_appcmd.c
Description
This function can be used to detect if there is an Application Command waiting to be processed by the application. If no command is pending, this function returns the FMSTR_APPCMDRESULT_NOCMD constant. Otherwise, this function returns the code of the Application Command that must be processed. Use the FMSTR_AppCmdAck call to acknowledge the Application Command after it is processed and to return the appropriate result code to the host.
The FMSTR_GetAppCmd function does not report the commands for which a callback handler function exists. If the FMSTR_GetAppCmd function is called when a callback-registered command is pending (and before it is actually processed by the callback function), this function returns FMSTR_APPCMDRESULT_NOCMD.
FMSTR_GetAppCmdData
Prototype
FMSTR_APPCMD_PDATA FMSTR_GetAppCmdData(FMSTR_SIZE* dataLen);
Declaration: freemaster.h
Implementation: freemaster_appcmd.c
Arguments
dataLen [out] - pointer to the variable that receives the length of the data available in the buffer. It can be NULL when this information is not needed.
Description
This function can be used to retrieve the Application Command data when the application determines that an Application Command is pending (see FMSTR_GetAppCmd).
There is just a single buffer to hold the Application Command data (the buffer length is FMSTR_APPCMD_BUFF_SIZE bytes). If the data are to be used in the application after the command is processed by the FMSTR_AppCmdAck call, copy the data out to a private buffer.
FMSTR_AppCmdAck
Prototype
void FMSTR_AppCmdAck(FMSTR_APPCMD_RESULT resultCode);
Declaration: freemaster.h
Implementation: freemaster_appcmd.c
Arguments
resultCode [in] - the result code which is to be returned to FreeMASTER
Description
This function is used when the Application Command processing finishes in the application. The resultCode passed to this function is returned back to the host and the driver is re-initialized to expect the next Application Command.
After this function is called and before the next Application Command arrives, the return value of the FMSTR_GetAppCmd function is FMSTR_APPCMDRESULT_NOCMD.
FMSTR_AppCmdSetResponseData
Prototype
void FMSTR_AppCmdSetResponseData(FMSTR_ADDR resultDataAddr, FMSTR_SIZE resultDataLen);
Declaration: freemaster.h
Implementation: freemaster_appcmd.c
Arguments
resultDataAddr [in] - pointer to the data buffer that is to be copied to the Application Command data buffer
resultDataLen [in] - length of the data to be copied. It must not exceed the FMSTR_APPCMD_BUFF_SIZE value.
Description
This function can be used before the Application Command processing finishes, when there are data to be returned back to the PC.
The response data buffer is copied into the Application Command data buffer, from where it is accessed when the host requires it. Do not use FMSTR_GetAppCmdData and the data buffer after FMSTR_AppCmdSetResponseData is called.
Note: The current version of FreeMASTER does not support the Application Command response data.
FMSTR_RegisterAppCmdCall
Prototype
FMSTR_BOOL FMSTR_RegisterAppCmdCall(FMSTR_APPCMD_CODE appCmdCode, FMSTR_PAPPCMDFUNC callbackFunc);
Declaration: freemaster.h
Implementation: freemaster_appcmd.c
Arguments
appCmdCode [in] - the Application Command code for which the callback is to be registered
callbackFunc [in] - pointer to the callback function that is to be registered. Use NULL to unregister a callback registered previously with this Application Command.
Return value
This function returns a non-zero value when the callback function was successfully registered or unregistered. It can return zero when trying to register a callback function for more than FMSTR_MAX_APPCMD_CALLS different Application Commands.
Description
This function can be used to register the given function as a callback handler for the Application Command. The Application Command is identified using single-byte code. The callback function is invoked automatically by the FreeMASTER driver when the protocol decoder obtains a request to get the application command result code.
The prototype of the callback function is
FMSTR_APPCMD_RESULT HandlerFunction(FMSTR_APPCMD_CODE nAppcmd,
FMSTR_APPCMD_PDATA pData, FMSTR_SIZE nDataLen);
Where:
nAppcmd -Application Command code
pData —points to the Application Command data received (if any)
nDataLen —information about the Application Command data length
The return value of the callback function is used as the Application Command Result Code and returned to FreeMASTER.
Note: The FMSTR_MAX_APPCMD_CALLS configuration macro defines how many different Application Commands may be handled by a callback function. When FMSTR_MAX_APPCMD_CALLS is undefined or defined as zero, the FMSTR_RegisterAppCmdCall function always fails.
Pipes API
FMSTR_PipeOpen
Prototype
FMSTR_HPIPE FMSTR_PipeOpen(FMSTR_PIPE_PORT pipePort, FMSTR_PPIPEFUNC pipeCallback,
FMSTR_ADDR pipeRxBuff, FMSTR_PIPE_SIZE pipeRxSize,
FMSTR_ADDR pipeTxBuff, FMSTR_PIPE_SIZE pipeTxSize,
FMSTR_U8 type, const FMSTR_CHAR *name);
Declaration: freemaster.h
Implementation: freemaster_pipes.c
Arguments
pipePort [in] - port number that identifies the pipe for the client
pipeCallback [in] - pointer to the callback function that is called whenever a pipe data status changes
pipeRxBuff [in] - address of the receive memory buffer
pipeRxSize [in] - size of the receive memory buffer
pipeTxBuff [in] - address of the transmit memory buffer
pipeTxSize [in] - size of the transmit memory buffer
type [in] - a combination of FMSTR_PIPE_MODE_xxx and FMSTR_PIPE_SIZE_xxx constants describing primary pipe data format and usage. This type helps FreeMASTER decide how to access the pipe by default. Optional, use 0 when undetermined.
name [in] - user name of the pipe port. This name is visible to the FreeMASTER user when creating the graphical pipe interface.
Description
This function initializes a new pipe and makes it ready to accept or send the data to the PC Host client. The receive memory buffer is used to store the received data before they are read out by the FMSTR_PipeRead call. When this buffer gets full, the PC Host client denies the data transmission into this pipe until there is enough free space again. The transmit memory buffer is used to store the data transmitted by the application to the PC Host client using the FMSTR_PipeWrite call. The transmit buffer can get full when the PC Host is disconnected or when it is slow in receiving and reading out the pipe data.
The function returns the pipe handle which must be stored and used in the subsequent calls to manage the pipe object.
The callback function (if specified) is called whenever new data are received through the pipe and available for reading. This callback is also called when the data waiting in the transmit buffer are successfully pushed to the PC Host and the transmit buffer free space increases. The prototype of the callback function provided by the user application must be as follows. The PipeHandler name is only a placeholder and must be defined by the application.
void PipeHandler(FMSTR_HPIPE pipeHandle);
FMSTR_PipeClose
Prototype
void FMSTR_PipeClose(FMSTR_HPIPE pipeHandle);
Declaration: freemaster.h
Implementation: freemaster_pipes.c
Arguments
pipeHandle [in] - pipe handle returned from the FMSTR_PipeOpen function call
Description
This function de-initializes the pipe object. No data can be received or sent on the pipe after this call.
FMSTR_PipeWrite
Prototype
FMSTR_PIPE_SIZE FMSTR_PipeWrite(FMSTR_HPIPE pipeHandle, FMSTR_ADDR pipeData,
FMSTR_PIPE_SIZE pipeDataLen, FMSTR_PIPE_SIZE writeGranularity);
Declaration: freemaster.h
Implementation: freemaster_pipes.c
Arguments
pipeHandle [in] - pipe handle returned from the FMSTR_PipeOpen function call
pipeData [in] - address of the data to be written
pipeDataLen [in] - length of the data to be written
writeGranularity [in] - size of the minimum unit of data which is to be written
Description
This function puts the user-specified data into the pipe’s transmit memory buffer and schedules it for transmission. This function returns the number of bytes that were successfully written into the buffer. This number may be smaller than the number of the requested bytes if there is not enough free space in the transmit buffer.
The writeGranularity argument can be used to split the data into smaller chunks, each of the size given by the writeGranularity value. The FMSTR_PipeWrite function writes as many data chunks as possible into the transmit buffer and does not attempt to write an incomplete chunk. This feature can prove to be useful to avoid the intermediate caching when writing an array of integer values or other multi-byte data items. When making the nGranularity value equal to the nLength value, all data are considered as one chunk which is either written successfully as a whole or not at all. The nGranularity value of 0 or 1 disables the data-chunk approach.
FMSTR_PipeRead
Prototype
FMSTR_PIPE_SIZE FMSTR_PipeRead(FMSTR_HPIPE pipeHandle, FMSTR_ADDR pipeData,
FMSTR_PIPE_SIZE pipeDataLen, FMSTR_PIPE_SIZE readGranularity);
Declaration: freemaster.h
Implementation: freemaster_pipes.c
Arguments
pipeHandle [in] - pipe handle returned from the FMSTR_PipeOpen function call
pipeData [in] - address of the data buffer to be filled with the received data
pipeDataLen [in] - length of the data to be read
readGranularity [in] - size of the minimum unit of data which is to be read
Description
This function copies the data received from the pipe from its receive buffer to the user buffer for further processing. The function returns the number of bytes that were successfully copied to the buffer. This number may be smaller than the number of the requested bytes if there is not enough data bytes available in the receive buffer.
The readGranularity argument can be used to copy the data in larger chunks in the same way as described in the FMSTR_PipeWrite function.
API data types
This section describes the data types used in the FreeMASTER driver. The information provided here can be useful when modifying or porting the FreeMASTER Communication Driver to new NXP platforms.
Note: The licensing conditions prohibit use of FreeMASTER and the FreeMASTER Communication Driver with non-NXP MPU or MCU products.
Public common types
The table below describes the public data types used in the FreeMASTER driver API calls. The data types are declared in the freemaster.h header file.
Type name |
Description |
|---|---|
FMSTR_ADDR |
Data type used to hold the memory address. On most platforms, this is normally a C-pointer, but it may also be a pure integer type. |
FMSTR_SIZE |
Data type used to hold the memory block size. |
FMSTR_BOOL |
Data type used as a general boolean type. |
FMSTR_APPCMD_CODE |
Data type used to hold the Application Command code. |
FMSTR_APPCMD_DATA |
Data type used to create the Application Command data buffer. |
FMSTR_APPCMD_RESULT |
Data type used to hold the Application Command result code. |
FMSTR_PAPPCMDFUNC |
Pointer to the Application Command handler function. |
Public TSA types
The table describes the TSA-specific public data types. These types are declared in the freemaster_tsa.h header file, which is included in the user application indirectly by the freemaster.h file.
FMSTR_TSA_TINDEX |
Data type used to hold a descriptor index in the TSA table or a table index in the list of TSA tables. |
FMSTR_TSA_TSIZE |
Data type used to hold a memory block size, as used in the TSA descriptors. |
Public Pipes types
The table describes the data types used by the FreeMASTER Pipes API:
FMSTR_HPIPE |
Pipe handle that identifies the open-pipe object. |
FMSTR_PIPE_PORT |
Integer type required to hold at least 7 bits of data. |
FMSTR_PIPE_SIZE |
Integer type required to hold at least 16 bits of data. |
FMSTR_PPIPEFUNC |
Pointer to the pipe handler function. |
Internal types
The table describes the data types used internally by the FreeMASTER driver. The data types are declared in the platform-specific header file and they are not available in the application code.
FMSTR_U8 |
The smallest memory entity. |
FMSTR_U16 |
Unsigned 16-bit integer. |
FMSTR_U32 |
Unsigned 32-bit integer. |
FMSTR_S8 |
Signed 8-bit integer. |
FMSTR_S16 |
Signed 16-bit integer. |
FMSTR_S32 |
Signed 32-bit integer. |
FMSTR_FLOAT |
4-byte standard IEEE floating-point type. |
FMSTR_FLAGS |
Data type forming a union with a structure of flag bit-fields. |
FMSTR_SIZE8 |
Data type holding a general size value, at least 8 bits wide. |
FMSTR_INDEX |
General for-loop index. Must be signed, at least 16 bits wide. |
FMSTR_BCHR |
A single character in the communication buffer. |
FMSTR_BPTR |
A pointer to the communication buffer (an array of FMSTR_BCHR). |
Document references
Links
FreeMASTER tool home: www.nxp.com/freemaster
FreeMASTER community area: community.nxp.com/community/freemaster
MCUXpresso SDK home: www.nxp.com/mcuxpresso
MCUXpresso SDK builder: mcuxpresso.nxp.com/en
Documents
Revision history
This Table summarizes the changes done to this document since the initial release.
Revision |
Date |
Description |
|---|---|---|
1.0 |
03/2006 |
Limited initial release |
2.0 |
09/2007 |
Updated for FreeMASTER version. New Freescale document template used. |
2.1 |
12/2007 |
Added description of the new Fast Recorder feature and its API. |
2.2 |
04/2010 |
Added support for MPC56xx platform, Added new API for use CAN interface. |
2.3 |
04/2011 |
Added support for Kxx Kinetis platform and MQX operating system. |
2.4 |
06/2011 |
Serial driver update, adds support for USB CDC interface. |
2.5 |
08/2011 |
Added Packet Driven BDM interface. |
2.7 |
12/2013 |
Added FLEXCAN32 interface, byte access and isr callback configuration option. |
2.8 |
06/2014 |
Removed obsolete license text, see the software package content for up-to-date license. |
2.9 |
03/2015 |
Update for driver version 1.8.2 and 1.9: FreeMASTER Pipes, TSA Active Content, LIN Transport Layer support, |
3.0 |
08/2016 |
Update for driver version 2.0: Added support for MPC56xx, MPC57xx, KEAxx and S32Kxx platforms. |
4.0 |
04/2019 |
Update for driver released as part of FreeMASTER v3.0 and MCUXpresso SDK 2.6. |
4.1 |
04/2020 |
Minor update for FreeMASTER driver included in MCUXpresso SDK 2.8. |
4.2 |
09/2020 |
Added example applications description and information about the MCUXpresso Config Tools. |
4.3 |
10/2024 |
Added description of Network and Segger J-Link RTT interface configuration. Accompanying the MCUXpresso SDK version 24.12.00. |