How is a FDL structured?

How can I generate a Flash Device Label?

Where is the FDL stored?

How to check the content of a FDL?

The flash device label is a data structure, stored in the flash memory of a device. It is not netX 90 specific but a generic structure used by several Hilscher products.

The structure contains device individual, unique data like serial numbers, etc..
I.e. a unique FDL must be generated for each produced product.

Alternatively, this data can be provided by the host application over a DPM - dual port memory - mailbox service "Device Data Provider Set service".
This service is described in the manual netX Dual-Port Memory Packet-based services (netX 90/4000/4100)

FDL Layout

The structure of the FDL is specified in the document Storage of Device Parameters Application Note and netX 90 - Production guide, chapter "Flash Device Label (*.fdl)".

The following C-headerfile contains a respective structure declaration: Hil_DeviceProductionData.h.
Please refer to the latest release of the cifX/netX Toolkit (NXDRV-TKIT), which contains a set of "Hilscher Definitions" header files, including Hil_DeviceProductionData.h.

/*============================================================*/
/*                                                            */
/*! PRODUCTION Data - Device Label                            */
/*                                                            */
/*============================================================*/
typedef __HIL_PACKED_PRE struct HIL_PRODUCT_DATA_LABEL_Ttag
{

  HIL_PRODUCT_DATA_HEADER_T                 tHeader;
  HIL_PRODUCT_DATA_T                        tProductData;
  HIL_PRODUCT_DATA_FOOTER_T                 tFooter;

} __HIL_PACKED_POST HIL_PRODUCT_DATA_LABEL_T;

/*------------------------------------------------------------*/
/*! PRODUCTION Data Structure                                 */
/*------------------------------------------------------------*/
/* Note: Structures should be aligned */
typedef __HIL_PACKED_PRE struct HIL_PRODUCT_DATA_Ttag
{
  HIL_PRODUCT_DATA_BASIC_DEVICE_DATA_T        tBasicDeviceData;
  HIL_PRODUCT_DATA_MAC_ADDRESSES_COM_T        tMACAddressesCom;
  HIL_PRODUCT_DATA_MAC_ADDRESSES_APP_T        tMACAddressesApp;
  HIL_PRODUCT_DATA_PRODUCT_IDENTIFICATION_T   tProductIdentification;
  HIL_PRODUCT_DATA_OEM_IDENTIFICATION_T       tOEMIdentification;
  HIL_PRODUCT_DATA_LIBSTORAGE_T               tFlashLayout;

} __HIL_PACKED_POST HIL_PRODUCT_DATA_T;

FDL file generation

There are several ways to generate a Flash Device Label.

Hilscher`s netX Studio Development tool features a FDL Wizard to generate template files for various use cases and a FDL Editor to modify the content.
These tools are meant to be used during product development.

Since the FDL contains unique device specific data like serial number and MAC addresses, each produced device requires a unique FDL file.
Two possibilities:

1. patch an existing FDL
   i.e. just replace the serial number and MAC addresses and update the checksum
   
   
2. create a FDL file using a program or script
   - usage of the C-header file Hil_DeviceProductionData.h might be useful
   - Hilscher provides an example Python script for FDL generation.
     This example script is provided "as is", without warranty and support!
     The script might be used as a base for own development.

• DeviceLabelGUI_netX_90_flash.py (prepared for for use case A and B)
• DeviceLabelGUI_netX_90_filesystem.py (prepared for use case C)
• This C-project and it's source code might be useful for own developments: Flash Dump and File Analysis Tool, https://github.com/HilscherNetX/netXFileChecker

FDL storage

The FDL binary is stored at a fixed address in the netX 90 COM-side Flash Memory INTFLASH0. The offset address is 0x2000, the fixed size is 0x1000 Bytes (4KB).
Please refer also to the Video Tutorial "Flash Memory Layout"

FDL content

Basic Device Data

The Basic Device Data is related to the Firmware validation for LFW(Protocol stacks) and APP-FW.
If custom changes are performed to the Basic Device Data, the File Header (*.nxi, *.nai file) might be modified as well in order to meet the firmware validation requirements.

Please note that a user cannot define it's own manufacturer code. These are managed and assigned by Hilscher.
It is possible to use the Hilscher manufacturer code for custom (netX chip based devices) in order to use firmware files (*.nxi) without header modifications.
If a Hilscher manufacturere code (1-255) is used in custom devices, the device number and serial number must be set to 0. Instead the OEM serial and order number can be used.

The Basic Device Data is not used for protocol stack specific purposes. For this case, the OEM Identification data might be used.
Exception: As a fallback solution, e.g. the basic device data serial number might be used for EthernetIP CIP protocol in case the OEM serial number is not valid (e.g. too long).

Basic Device Data Fields

• Manufacturer ID -    0 = Undefined; 1 - 255 = Hilscher GmbH; 256 - x = OEM - All numbers are managed and assigned by Hilscher GmbH
  Relevant for firmware validation, must match the firmware file header
  
  
• Device classification number -    Possible values are defined in the dual port memory definitions (see HIL_HW_DEV_CLASS_*).
  Relevant for firmware validation, must match the firmware file header
  
  
• Device number  - For usManufacturer 1-255 the numbers are managed by Hilscher GmbH. It is used for the order number of a product.
  If a custom device shall use a Hilscher manufacturer code (1-255) the Device number must be set to 0.
  
  
• Serial number -   For usManufacturer 1-255 the serial number of the device is managed by Hilscher GmbH.
  If a custom device shall use a Hilscher manufacturer code (1-255) the Serial number must be set to 0.
  Instead, the OEM serial number field is used to store a custom serial number.
  It must be assured that the OEM serial number meet the protocol dependent requirements, like max. length.
  
  
• Hardware compatibility number -  This number indicates an incompatible hardware change
  Relevant for firmware validation, must match the firmware file header
  
  
• Hardware revision number - Production related hardware revision number
  
  
• Production date -  uint16_t format is 0xYYWW

MAC AddressesCom

Unique MAC addresses for the Communication Firmware. Each device must contain a unique FDL with unique MAC addresses in this section.
Typically up to 4 MAC addresses are required for one single device, depending on the used firmware and features. Please refer to MAC Adresses for Loadable Firmware Protocol Stacks for further details.

MAC AddressesApp

Optional unique MAC addresses for the application side. Typically not required for netX 90 based devices.

Product Identification

USB Vendor and Product IDs. Typically not required for netX 90 based devices.

OEM Identification

Optional usable data for device identification.The single data fields can be enabled/disabled separately.

Note: However some loadable firmwares (LFWs) might require the enabling of several data fields simultaneously.
E.g. PROFINET V5.3 requires fields 0-2 = Serial number, Order number and Hardware revision to be enabled.
Please refer to the respective Protocol Stack API Manual

figure: PROFINET LFW V5.3 API manual excerpt

This data is evaluated by the data provider component in the LFW and forwarded to the protocol stack.
The communication protocol stack might use this data for device identification purposed towards the network master (PLC). E.g. PROFINET I&M data.

Alternatively, this data can be provided by the host application over a DPM - dual port memory - mailbox service "Device Data Provider Set service".
This service is described in the manual netX Dual-Port Memory Packet-based services (netX 90/4000/4100)

OEM Identification Data Fields

• Serial number (char string)
  It must be assured that the OEM serial number meet the protocol dependent requirements, like max. length.
  E.g. for the EthernetIP or EtherCAT Protocols the OEM serial number is convertet from char string to a UINT32 (max serial number = 4294967295)
  In case several numbers are required, the OEM Vendor specific data array might be used.
• Order number (char string)
• Hardware revision (char string)
• Production date/time (char string)
• Vendor specific data (byte array)

Flash Layout

Information about the number and size of flash memories, both internal and external, in the system accessed by Hilscher LFW - Loadable Firmware.

Information about the location and size of specific components (like *.hwc, *.nxi, etc.) in the flash memories. This information is required by Hilscher LFWs.

We recommend to stick to the default settings, as generated by the netXSTUDIO FDL creation tool.

FDL content checker utility

Flash Dump and File Analysis Tool

Beside a windows executable, this utility is available as source code. The sources can be used as a base for a FDL generator tool.