====== Firmware Versioning evolution ======

====== FX3 Version Info ======
The version id is also encoded into the firmware image file name as:
<code><VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber></code>

===== FX3 version info C/C++-struct =====
The FX3 version structure is as follows (little-endian memory layout):

<code cpp firmware-version.h>
struct FwVersion{
    unsigned vendorId    : 3;
    unsigned hwCfgId     : 5;
    unsigned productId   : 8;
#ifdef OLD_VER_FMT
    unsigned releaseType : 5;
    unsigned buildNo     : 11;
#else
    unsigned releaseType : 3;
    unsigned buildNo     : 13;
#endif
};
static_assert(sizeof(FwVersion) == 4);
</code>

Prior to FPGA v. 89 there was no standard-compliant way of representing the version info in a C struct though (which is exactly what prompted the rework in the first place).
==== Bit layout ====
The bits are laid out in 4 sequential bytes as follows (depending on the version):
^  version  ^  3  ^^^^^^^^  2  ^^^^^^^^  1  ^^^^^^^^  0  ^^^^^^^^
^  :::  ^  7  ^  6  ^  5  ^  4  ^  3  ^  2  ^  1  ^  0  ^  7  ^  6  ^  5  ^  4  ^  3  ^  2  ^  1  ^  0  ^  7  ^  6  ^  5  ^  4  ^  3  ^  2  ^  1  ^  0  ^  7  ^  6  ^  5  ^  4  ^  3  ^  2  ^  1  ^  0  ^
|  fx3<102\\ fpga<77  |  buildNo[7:0]  ||||||||  releaseType  |||||  buildNo[10:8]  |||  productId  ||||||||  vendorId  |||  hwCfgId  |||||
|  fx3<103  |  buildNo[10:3]  ||||||||  buildNo[2:0]  |||  releaseType  |||||  productId  ||||||||  hwCfgId  |||||  vendorId  |||
|  fx3>=103\\ fpga>=77  |  buildNo[12:5]  ||||||||  buildNo[4:0]  |||||  releaseType  |||  productId  ||||||||  hwCfgId  |||||  vendorId  |||

Because of the change in bit layout different byte sequences shown below are needed to produce the same result (exact same component values for the sake of simplicity and only as an illustration):
^  version  ^  byte sequence (API return buffer)  |  <code cpp>
.vendorId = 1
.hwCfgId = 1
.productId = 5
.releaseType = 3
.buildNo = 0x67</code>  |
|  fx3>=102\\ fpga<77  |''0x21 0x05 0x18 0x67''|:::|
|  fx3<103  |''0x09 0x05 0xE3 0x0C''|:::|
|  fx3>=103\\ fpga>=77  |''0x09 0x05 0x3B 0x03''|:::|

===== Vendor ID =====
^Code ^Value ^
|1|Cypress|

===== Hardware ID =====
^Code ^Value ^
|1|FX3|

===== Product ID =====
^Code ^Value ^
|1|reserved for Gen 1 camera, a.k.a. "Moon landing"|
|2|reserved for Gen 2 camera, a.k.a. "Piggy"|
|3|Gen 3 camera (Alpha), a.k.a. "Frankie" (from Frankenstein's Monster)|
|4|Gen 3 camera, Production|
|5|Gen 4 camera, a.k.a. "Vitreledonella"|
|6|Gen 5 camera, either "Square One" or "Studio"|

===== Release type =====
^ Code ^ Name ^ Meaning ^
|0|Private build| Private build for debugging and similar purposes |
|1|Alpha| feature-incomplete early development cycle "somewhat stable" build |
|2|Beta| feature-complete, but not very stable build (lots of bugs) |
|3|Evaluation| Tech preview |
|4|Release candidate| feature complete and stable |
|5|Release| general availability |
|6|Backport| backport of a feature from next gen camera |
|7|Emergency bug fix| a critical post-release bugfix |

===== Build number =====
^Code ^Value ^
|#|Increments on each build|


====== FPGA Version Info ======
The version id is also encoded into the firmware image file name as:
<code><VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber></code>


===== Vendor ID =====
A ''3''-bit number that represents a vendor of the main computation unit
^Code ^Value ^
|1|Xilinx (AMD)|
|2|Altera (Intel)|

===== Hardware ID =====
A ''5''-bit number that represents a model from the list in the following table:
^%%VendorId%%^Code ^Value ^
|1|1|Artix-7 100T|
|1|2|Artix-7 200T|
|1|3|Artix %%UltraScale+%% XCAU25P|
|2|1|Cyclone 10 GX|
===== Product ID =====
An ''8''-bit number, unique to each product type from the table below:
^Code ^Value ^
|1|reserved|
|2|reserved|
|3|Gen 3 camera (Alpha), a.k.a. "Frankie"|
|4|Gen 3 camera, Production|
|5|Gen 4 camera, a.k.a. “Vitreledonella”|
|6|Gen 5 camera, prosumer grade "Square One"|
|7|Gen 5 camera, professional grade "Studio"|
===== Release type =====
Lower ''3'' bits of this ''5''-bit value map to a type of build below, the upper ''2'' bits are reserved for future use and must be ''b00''
^Code ^Value ^
|0|Private build|
|1|Alpha|
|2|Beta|
|3|Eval/Tech preview|
|4|Release candidate|
|5|Release|
|6|Backport|
|7|Emergency bug fix|

===== Build number =====
''11'' bits of a build number (the range is ''1..2047'')
^Code ^Value ^
|#|Increments on each build|