Difference between revisions of "Firmware file format (.gdf)"

From Granite Devices Knowledge Wiki
Jump to: navigation, search
[checked revision][checked revision]
(GDF version 400 - draft)
(Header)
Line 28: Line 28:
 
         /* GDF version 400 format
 
         /* GDF version 400 format
 
         * ----------------------
 
         * ----------------------
 +
        *
 +
        * Note: GDF v400 is not limited to firmware files any more,
 +
        * it can be used as general purpose data container for up to 4GB data chunks.
 
         *
 
         *
 
         * Binary file contents
 
         * Binary file contents
Line 37: Line 40:
 
         * 2 GDF version = 400
 
         * 2 GDF version = 400
 
         * 2 GDF backwards compatible version = 400
 
         * 2 GDF backwards compatible version = 400
        * 4 target device type ID
 
 
         * 4 number of data chunks in file = N
 
         * 4 number of data chunks in file = N
 
         *
 
         *
 
         * repeat N times:
 
         * repeat N times:
 +
        * 4 data chunk descriptive name string length in bytes = L
 +
        * L data chunk descriptive name string in UTF8
 
         * 4 data chunk type
 
         * 4 data chunk type
 
         * 4 data chunk option bits
 
         * 4 data chunk option bits
Line 55: Line 59:
 
         * 2=firmware version string, UTF8
 
         * 2=firmware version string, UTF8
 
         * 3=remarks, UTF8
 
         * 3=remarks, UTF8
 +
        * 4=manufacturer, UTF8
 +
        * 5=copyright, UTF8
 +
        * 6=license, UTF8
 +
        * 7=disclaimer, UTF8
 +
        * 8=circulation, UTF8 (i.e. customer name)
 +
        * 20=unix timestamp, S=4
 +
        * 50=target device type ID and mask, S=8
 +
        *  first 4 bytes are target device ID, i.e. 11000=IONI
 +
        *  second 4 bytes are mask/divider for type comparison, must be >0
 +
        *  file is compatible if following eq is true: floor(readID/divider) == floor(targetID/divider)
 
         * 100=main MCU FW binary, S=any
 
         * 100=main MCU FW binary, S=any
 
         * 101=main MCU FW unique identifier number, S=4
 
         * 101=main MCU FW unique identifier number, S=4
 +
        * 102=main MCU FW required HW feature bits, S=4
 +
        *    helps to determine whether FW works on target
 +
        *    device version when compared to a value readable from the device.
 +
        *    0 means no requirements, works on all target ID devices.
 
         * 200=secondary MCU FW binary, S=any
 
         * 200=secondary MCU FW binary, S=any
 
         *
 
         *
Line 64: Line 82:
 
         * ----------------------
 
         * ----------------------
 
         * bit 0: if 1, GDF loading application must support/understand the chunk type to use this file
 
         * bit 0: if 1, GDF loading application must support/understand the chunk type to use this file
 +
        * bits 1-31: reserved
 
         *
 
         *
 
         */
 
         */

Revision as of 21:08, 9 October 2018

File format byte by byte

All multibyte integers are stored LSB first.

GDF version 300

Header

IDString - 4 bytes, always="GDFW"

BLFileVersion - 2 bytes, value=300

TargetDriveType - 2 bytes, Argon=4000, Ion=11000, Atomi=14000

HostFWbytes - 4 bytes, number of bytes for STM32 CPU

GCFWbytes - 4 bytes, number of bytes for GraniteCore CPU or 0xffffffff if not included

Data

Data of HostFW begins. Amount of bytes is HostFWbytes

Data of GCFW begins. Amount of bytes is GCFWbytes

File checksum

FileCksum - 4 bytes calculated from the current file. Simply sum of all unsigned bytes in file except CKSum itself


GDF version 400 - draft

Header

Version 400 described below:

        /* GDF version 400 format
         * ----------------------
         *
         * Note: GDF v400 is not limited to firmware files any more,
         * it can be used as general purpose data container for up to 4GB data chunks.
         *
         * Binary file contents
         * --------------------
         *
         * bytes  meaning:
         *
         * 4	ASCII string = "GDFW"
         * 2	GDF version = 400
         * 2	GDF backwards compatible version = 400
         * 4	number of data chunks in file = N
         *
         * repeat N times:
         * 4	data chunk descriptive name string length in bytes = L
         * L	data chunk descriptive name string in UTF8
         * 4	data chunk type
         * 4	data chunk option bits
         * 4	data chunk size in bytes=S
         * S	data
         * end of repeat
         *
         * 4	file's CRC-32
         *
         * data chunk types
         * ----------------
         * 0=target device name, UTF8
         * 1=firmware name, UTF8
         * 2=firmware version string, UTF8
         * 3=remarks, UTF8
         * 4=manufacturer, UTF8
         * 5=copyright, UTF8
         * 6=license, UTF8
         * 7=disclaimer, UTF8
         * 8=circulation, UTF8 (i.e. customer name)
         * 20=unix timestamp, S=4
         * 50=target device type ID and mask, S=8
         *   first 4 bytes are target device ID, i.e. 11000=IONI
         *   second 4 bytes are mask/divider for type comparison, must be >0
         *   file is compatible if following eq is true: floor(readID/divider) == floor(targetID/divider)
         * 100=main MCU FW binary, S=any
         * 101=main MCU FW unique identifier number, S=4
         * 102=main MCU FW required HW feature bits, S=4
         *     helps to determine whether FW works on target
         *     device version when compared to a value readable from the device.
         *     0 means no requirements, works on all target ID devices.
         * 200=secondary MCU FW binary, S=any
         *
         * note: firmware may contain many combinations of above chunks. in basic case, it contains just chunk type 100 and nothing else.
         *
         * data chunk option bits
         * ----------------------
         * bit 0: if 1, GDF loading application must support/understand the chunk type to use this file
         * bits 1-31: reserved
         *
         */

For practical reading software implementation, see devicedeployment.c from SimpleMotion library.