FMI Driver

Table of Contents

• FMI HAL Module Introduction
  • FMI HAL Module Features
• FMI HAL Module APIs Overview
• FMI HAL Module Operational Overview
  • FMI HAL Module Important Operational Notes and Limitations
    • FMI HAL Module Operational Notes
    • FMI HAL Module Limitations
• Including the FMI HAL Module in an Application
• Configuring the FMI HAL Module
  • FMI HAL Module Clock Configuration
  • FMI HAL Module Pin Configuration
• Using the FMI HAL Module in an Application

FMI HAL Module Introduction

The FMI HAL module provides a high-level API for applications that read records from the Factory MCU Information Flash Table and uses the Flash Interface on the Synergy MCU.

FMI HAL Module Features

The FMI HAL module reads the FMIFRT (Factory MCU Information Flash Root Table) on a Synergy microcontroller, looking up the address of the start of the table in flash. The module sets the caller's pointer to the Product Information record from the table. This information may be used to determine the capabilities of features specific to this MCU package. Information available from the FMI HAL module includes:

• Product information (that is, product name, package, pin count and temperature range)
• Product features (version major, version minor and variant data)
• Event information such as interrupts and events

FMI HAL Module Block Diagram

FMI HAL Module APIs Overview

The FMI HAL module defines an API for accessing the FMIFRT. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

FMI HAL Module API Summary

Function Name	Example API Call and Description
init	g_fmi.p_api->init(); Initialize the FMI base pointer.
productInfoGet	g_fmi.p_api->productInfoGet(&g_pp_product_info); Get product information record address into g_pp_product_info pointer.
uniqueIdGet	g_fmi.p_api->uniqueIdGet(&g_p_unique_id); Copy the unique ID into the g_p_unique_id pointer.
productFeatureGet	g_fmi.p_api->productFeatureGet(&g_ssp_feature, &g_feature_info); Get feature information and store it in g_feature_info pointer.
eventInfoGet	g_fmi.p_api->eventInfoGet(&g_ssp_feature,SSP_SIGNAL_GPT_COUNTER_OVERFLOW, &g_event_info); Get event information and store it in g_event_info pointer.
versionGet	g_fmi.p_api->versionGet(&g_p_version); Get the driver version based on compile time macros.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	API Call Successful.
SSP_ERR_INVALID_FMI_DATA	The FMI data table provided is not valid
SSP_ERR_IP_CHANNEL_NOT_PRESENT	Requested channel does not exist on this MCU
SSP_ERR_IP_UNIT_NOT_PRESENT	Requested unit does not exist on this MCU
SSP_ERR_INTERNAL	Requested feature is in a format not supported at this time
SSP_ERR_IRQ_BSP_DISABLED	Event information could not be found
SSP_ERR_ASSERTION	Caller's pointer is null
SSP_ERR_INVALID_FACTORY_FLASH	Factory flash is not valid

Note

Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

FMI HAL Module Operational Overview

The FMI HAL module retrieves the product information record address and populates the  fmi_product_info_t structure using the fmi_api_t::productInfoGet API.

The FMI HAL module copies unique ID and populates the fmi_unique_id_t structure using the fmi_api_t::uniqueIdGet API.

The FMI HAL module gets feature information and populates the fmi_feature_info_t structure using the fmi_api_t::productFeatureGet API.

The FMI HAL module fetches event information and populates the fmi_event_info_t structure using the fmi_api_t::eventInfoGet API.

The FMI HAL module gets code version and API version in ssp_version_t structure using the fmi_api_t::versionGet API.

For details, refer the FMI HAL module source code and SSP user manual.

FMI HAL Module Important Operational Notes and Limitations

FMI HAL Module Operational Notes

• The fmi_product_info_t::unique_id is deprecated. It does not contain a unique ID if the factory MCU information is linked in by the application code. Use fmi_api_t::uniqueIdGet for the unique ID.

FMI HAL Module Limitations

• For limitations of FMI HAL Interface and its implementation, see the latest SSP release notes.
• The FMI Driver has been tested on the S7G2 (WS2) Synergy microcontroller family using the FMIFRT peripheral register. It is the only Synergy MCU that is currently programmed with data in the Factory MCU Information Table.

Including the FMI HAL Module in an Application

This section describes how to include the FMI HAL Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the FMI Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the FMI Driver is g_fmi0. This name can be changed in the associated Properties window.)

FMI HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_fmi FMI Driver on r_fmi	Threads> HAL/Common	New Stack> Driver> System> FMI Driver on r_fmi

When the FMI Driver on r_fmi is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

FMI HAL Module Stack

Configuring the FMI HAL Module

The FMI HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the FMI HAL Module on r_fmi

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Controls whether to include code for API parameter checking.
SSP MCU Information Symbol Name	g_fmi_data	This symbol maps to the base address where the factory flash table information will be found. It should not be modified.
Part Number Mask	0xFE00	Each bit represents one character in the Synergy part number, where the MSB is the first character in the part number ('R'). Set bits to ensure the part number in the MCU factory flash matches the part number in the SSP MCU Information. The default mask checks everything except operating temperature, software ID, and quality ID.
Name	g_fmi	Module instance name.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Family. Other MCUs may have different default values and available configuration settings.

FMI HAL Module Clock Configuration

No specific clock configurations are required for the FMI HAL Module.

FMI HAL Module Pin Configuration

No specific pin configurations are required for the FMI HAL Module.

Using the FMI HAL Module in an Application

The typical steps in using the FMI HAL Module in an application are:

1. Initialize the FMI using the fmi_api_t::init API, it is automatically initialized after Reset.
2. Use the fmi_api_t::productInfoGet API to get product information.
3. Use the fmi_api_t::uniqueIdGet API to get unique ID.
4. Use the fmi_api_t::productFeatureGet API to get feature information.
5. Use the fmi_api_t::eventInfoGet API to get event information.
6. Use the fmi_api_t::versionGet API to get driver version information.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical FMI HAL Module Application