Differences

This shows you the differences between two versions of the page.

--- code:fx3_hvci_and_fpga_i_c_commands [2019/11/12 16:36] – [0xA8-0xA9 - sysinfo and debugging] Igor Yefmov
+++ code:fx3_hvci_and_fpga_i_c_commands [2024/02/07 19:07] – [mFT lense access: 0xC0] Igor Yefmov
@@ Line 1: / Line 1: @@
+====== FX3/FPGA API spec ======
+This page describes FX3/FPGA API for Square1 and Studio (gen5) products.
+For gen4 and earlier API see [[code:fx3_fpga_api_spec_rex|FX3/FPGA API spec up to REX]].
 ====== Preface ======
 %%SUB2r%% camera is built on a Cypress FX3 chipset that facilitates the ''Super-Speed USB 3.0+'' communication between the device and a host system. Every component of the camera, be it an FPGA or an image sensor, receives user commands via that Cypress FX3.
@@ Line 4: / Line 9: @@
 On Windows the device is registered with a GUID ''{36FC9E60-C465-11CF-8056-444553540000}'' and if you are not planning on using the ''[[code:sub2r-lib|SUB2r-lib]]'' for your development - that would be the GUID to search for to properly connect to the command channel.
-Whether you use ''[[code:sub2r-lib|SUB2r-lib]]'' or not you need to install the [[manual:fx3_device_windows_10_driver|provided driver]] for the OS to properly configure the device in order to be able to connect to its control endpoints.
+Here's a sample code that shows how to send commands to both the ''[[#FX3 API Reference|FX3 Host]]'' and to ''[[#FPGA I²C bridge (registers' map)]]''. The code lacks error checking (for clarity) and this should go without saying that if you copy-paste it into your code you **must** add error handling :)
-Here's a sample code that shows how to send commands to both the ''[[#FX3 Host Vendor Command Reference|FX3 Host]]'' and to ''[[#FPGA I²C bridge]]''. The code lacks error checking (for clarity) and this should go without saying that if you copy-paste it into your code you **must** add error handling :)
 <code c++>// set a new auto-functions' update interval to 2x the default
 // just issue the command directly to FX3's vendor request interface
-void setUUInterval(){
+void setAUInterval(){
     S2R::I2C fx3;
     fx3.open(0);
-    fx3.vrCmd(0xDF, S2R::FX3::write, 6000, 0);
+    fx3.vrCmd(S2R::FX3::af_au_period, S2R::FX3::write, 6000, 0);
 }
@@ Line 44: / Line 47: @@
 ----
-====== FX3 Host Vendor Command Reference ======
+====== FX3 API Reference ======
 The following tables provide information on how to access the camera's functionality for ''FX3 Host Vendor Command Interface''. The address space is split into smaller chunks, grouped by common functionality:
 ===== 0x00-0x9F =====
@@ Line 51: / Line 53: @@
 |Reserved|''0x00''-''0x9F''| | | | | |Think of this as "system address space"|
-===== 0xA0-0xA7 =====
+===== Global controls =====
 ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
 |Bootloader check|''0xA0''| | |R/W| | |Check if a bootloader is running, the result is in the command's status code (success/failure interpreted as ''true''/''false'')|
-|Reserved|''0xA1''| | | | | | |
+|MS OS Descr.|''0xA1''|bits [\(3:0\)] - see notes | |R/O|\(174\)|MS OS Platform Descriptor|For details on the structure and valid parameters' values refer to Microsoft's documentation for [[https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/microsoft-os-2-0-descriptors-specification|Microsoft OS 2.0 Descriptors Specification]]\\ The \(4\) LSB of the ''wIndex'' field are the descriptor's index. Valid values are:\\ \(7\) - MS OS 2.0 descriptor\\ \(8\) - MS OS 2.0 set alternative enumeration (currently not supported)|
-|Run DPC calibration|''0xA2''| |DPC Threshold|W/O| | |Start the dynamic DPC calibration with the given DPC Threshold in range [0..255]|
+|:!: Run DPC calibration|''0xA2''| |DPC Threshold|W/O| | |Start the dynamic DPC calibration with the given DPC Threshold in range [\(0..4095\)]|
-|Reconfig FGPA|''0xA3''| | |W/O| | |Writing anything into this register causes the FPGA to reconfigure itself from SPI Flash|
+|Reserved|''0xA3''| | | | | | |
-|FPGA I²C Bridge|''0xA4''|FPGA register offset|FPGA data (write)|R/W|''0'' or ''1''|''7:0'' - FPGA data|FPGA write returns 0 byte buffer, FPGA read returns 1 byte buffer. Read/write is requested via control endpoint's direction attribute being set to ''DIR_FROM_DEVICE''/''DIR_TO_DEVICE''.\\ For details on individual commands refer to [[#FPGA I²C bridge|FPGA I²C bridge]]|
+===== I²C access =====
-|Sensor I²C bridge (8-bit configuration registers)|''0xA5''| Sensor register | ''mask'' and ''data'' (if writing) - see Notes column for details |R/W|''0'' or ''1''| ''7:0'' - sensor register's data | ''mask'' - an 8-bit MSB that specifies which bits to affect during a write operation - only the bits that are set in ''mask'' will be affected by bits in ''data''. Setting ''mask'' to ''0'' ultimately turns a write operation into a read one as no bits are getting modified\\ ''data'' - an 8-bit LSB that specifies the new data to write into sensor's register. The write only affects the bits that are set in ''mask''\\ Read operation returns an 8-bit register's value\\ Read/write is requested via control endpoint's direction attribute being set to ''DIR_FROM_DEVICE''/''DIR_TO_DEVICE''.\\ For details on each sensor's register's function refer to the sensor's specification |
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
-|Reserved for future I²C bridge |''0xA6''| | | | | | |
+|:!: FPGA I²C Bridge|''0xA4''|FPGA register offset|FPGA data (write)|R/W|\(0\) or \(1\)|[\(7:0\)] - FPGA data|FPGA write returns 0 byte buffer, FPGA read returns 1 byte buffer. Read/write is requested via control endpoint's direction attribute being set to ''DIR_FROM_DEVICE''/''DIR_TO_DEVICE''.\\ For details on individual commands refer to [[#FPGA I²C bridge (registers' map)|FPGA I²C bridge]]|
-|RAW Mode Select|''0xA7''| | |R/W| 1 |''7:1'' - Reserved\\ ''0'' - RAW Mode  |Select RAW Mode ('1') or Processed Video ('0')\\ **N.B.** This has been moved here from ''0xA5'' in FX3 version 46|
+|:!: Sensor I²C bridge (\(8\)-bit configuration registers)|''0xA5''| [\(15:0\)] - sensor ''register'' address | ''mask'' and ''data'' (if writing) - see Notes column for details |R/W|\(0\) or \(1\)| [\(7:0\)] - sensor register's data | ''register'' - a \(16\) bit register address\\ ''mask'' - an \(8\)-bit MSB that specifies which bits to affect during a write operation - only the bits that are set in ''mask'' will be affected by bits in ''data''. Setting ''mask'' to \(0\) ultimately turns a write operation into a read one as no bits are getting modified\\ ''data'' - an \(8\)-bit LSB that specifies the new data to write into sensor's register. The write only affects the bits that are set in ''mask''\\ Read operation returns an \(8\)-bit register's value\\ Read/write is requested via control endpoint's direction attribute being set to ''DIR_FROM_DEVICE''/''DIR_TO_DEVICE''.\\ For details on each sensor's register's function refer to the sensor's specification |
+|:!: Generic I²C access|''0xA6''|[\(15:8\)] \(8\)-bit I²C bus address\\ [\(7:6\)] [[#Generic I²C command selector|command selector]]\\ [\(5:3\)] [[#Generic I²C width selector|data width selector]]\\ [''2:0''] [[#Generic I²C width selector|address width selector]]|[\(7:0\)] - number of data elements to read/write|R/W| | |single/bulk read/write to/from an arbitrary device on I²C bus, supports \(8\), \(16\), \(32\) bit addressing and same for data OR poll for status or get result of a bulk I2C operation, see [[#Generic I²C access details|next section]] for details|
-===== 0xA8-0xA9 - sysinfo and debugging =====
+==== Generic I²C access details ====
+This versatile API allows single/bulk access to an arbitrary device on I²C and supports 8, 16, 32-bit addressing and data. Single (non-bulk) access is always an immediate, non-cached execution while bulk access is always cached. For bulk operations the result is queried/polled until it is acquired or has failed.
+=== Generic I²C command selector ===
+^Code ^Name ^Description ^
+|  \(0\)  | read |This command issues an immediate read on I²C if a single address is requested or batches up the reads for a background task otherwise. Use `status` to know when it is ok to retrieve data via a call to `get results`|
+|  \(1\)  | write |same as `read`, but for I²C writes|
+|  \(2\)  | status |Call this repeatedly while the return code is `still in progress` (code \(0x80\)), until it returns either a `success` (code \(0\)) or any of the `fail` codes, at which point call the `results`|
+|  \(3\)  | results |Once the `read` operation completes successfully, this call will retrieve the read data|
+=== Status codes ===
+^Code ^Description ^
+|  ''0x00''  |operation completed with no errors|
+|  ''0x01''  |I²C subsystem is not initialized|
+|  ''0x02''  |invalid I²C bus address - must be an \(8\)-bit kind, so last bit has to be a \(0\)|
+|  ''0x03''  |I²C operation failed|
+|  ''0x10''  |too many elements to process|
+|  ''0x11''  |invalid (reserved) width value for address|
+|  ''0x12''  |invalid (reserved) width value for data|
+|  ''0x13''  |mismatch between number of elements specified in request (in ''wValue'''s LSB) and buffer (based on ''wLength'' and address+data width)|
+|  ''0x20''  |cache buffer overflow (did you forget to poll for successful completion before issuing a new command? Or is there another application trying to utilize this same API in parallel?)|
+=== Generic I²C width selector ===
+^Value ^Width (bits) ^
+|  \(0\)  | \(8\)  |
+|  \(1\)  | \(16\)  |
+|  \(2\)  | \(32\)  |
+===== Video mode select =====
 ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
-|Sysinfo|''0xA8''|data structure version (currently only ''1'' is supported) | bitmask of additional checks to perform:\\ ''2''-''7'': reserved\\ ''1'' - check DMA integrity\\ ''0'' - check memory integrity |R/O|TBD| |get various internal system info on the guts of the RTOS and the firmware running on FX3. Returned bytes: \\ **Version 1**: \\ 0 - part number|
+|:!: Video Mode Select|''0xA7''| | |R/W| 1 |\(7:2\) - Reserved\\ \(1\) - HDR mode\\ \(0\) - RAW mode  |\(1\) - chose between HDR(\(1\)) or linear (\(0\)) sensor mode\\ \(0\) - select RAW mode (\(1\)) or Processed Video (\(0\)) for video pipeline\\ **N.B.** "Raw mode" has been moved here from ''0xA5'' in FX3 version \(46\)|
-|Reserved|''0xA9''| | | | | | |
-===== 0xAA-0xAF - versioning and reprogramming =====
+===== Sysinfo =====
 ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
-|Erase SPI Flash|''0xAA''| | |W/O| | |Any write to this location invalidates the FX3 SPI Flash and causes the FX3 to reset itself to a bootloader mode for reprogramming|
+|:!: Sysinfo|''0xA8''|data structure version:\\ <del>\(1\) - deprecated</del>\\ \(2\) - supported version | bitmask of additional checks to perform:\\ :!: \(0\) - reinit FPGA and/or sensor if needed\\ \(1\)-\(7\): reserved |R/O|\(54\)| <code>struct SysInfoV2</code> |Get various internal system info on the guts of the RTOS and the firmware running on FX3, as well as overall configuration and health check results. Returned bytes:\\ **Version 2**: [[SysInfoV2]] |
-|FX3 version|''0xAB''| | |R/O|''4''|''31:29'' Vendor ID\\ ''28:24'' HW_CFG_ID\\ ''23:16'' Product ID\\ ''15:11'' Release type\\ ''10:0'' Build number|Get detailed version information of the FX3, for more details refer to [[#FX3 Version Info]]|
+|Reserved|''0xA9''| | | | | | |
-|FPGA version|''0xAC''| | |R/O|''4''|''31:29'' Vendor ID\\ ''28:24'' HW_CFG_ID\\ ''23:16'' Product ID\\ ''15:11'' Release type\\ ''10:0'' Build number|Get detailed version information of the FPGA, for more details refer to [[#FPGA Version Info]]|
-|FPGA config. ctrl.|''0xAD''| | |W/O| | |Any write to this location will put the FPGA into configuration mode|
+===== Versioning and reprogramming =====
-|FPGA config. status - SPI codes|''0xAE''| | |R/O|''2''| see [[#FPGA config status - SPI codes|below]] for details |Retrieve detailed status of the FPGA configuration operation|
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Notes ^
-|SPI Flash write enable|''0xAF''| | |W/O| | |Reconfigure the FX3 IOMatrix to disable GPIF and enable SPI|
+|Erase SPI Flash|''0xAA''| | |W/O| |Any write to this location invalidates the FX3 SPI Flash and causes the FX3 to reset itself to a bootloader mode for reprogramming|
+|FX3 version|''0xAB''| | |R/O|  \(4\)  |Get detailed version information of the FX3, for more details refer to [[#FX3 Version Info]]|
+|:!: FPGA version|''0xAC''| | |R/O|  \(4\)  |Get detailed version information of the FPGA, for more details refer to [[#FPGA Version Info]]|
+|:!: FPGA config. ctrl.|''0xAD''| | |W/O| |Any write to this location will put the FPGA into configuration mode|
+|:!: FPGA config. status - SPI codes|''0xAE''| | |R/O|  \(2\)  |Retrieve detailed status of the FPGA configuration operation. See [[#FPGA config status - SPI codes|below]] for details|
+|SPI Flash write enable|''0xAF''| | |W/O| |Reconfigure the FX3 IOMatrix to disable GPIF and enable SPI to be re-written|
 ==== FPGA config status - SPI codes ====
-^ Bit name ^ Description ^
+^  Bit position^ Bit name ^ Description ^
-|''15'' Program %%SwitchWord%% OK| |
+|  \(15\) | Program %%SwitchWord%% OK| |
-|''14'' Verify OK| Verification succeeded |
+|  \(14\) | Verify OK| Verification succeeded |
-|''13'' Program OK| Programming completed successfully |
+|  \(13\) | Program OK| Programming completed successfully |
-|''12'' Erase OK| SPI erase was successful |
+|  \(12\) | Erase OK| SPI erase was successful |
-|''11'' Erase %%SwitchWord%% OK| |
+|  \(11\) | Erase %%SwitchWord%% OK| |
-|''10'' Check ID OK| |
+|  \(10\) | Check ID OK| |
-|''9'' Initialize OK| |
+|  \(9\) | Initialize OK| |
-|''8'' Config started| Config operation has started |
+|  \(8\) | Config started| Config operation has started |
-|''7'' CRC error| |
+|  \(7\) | CRC error| |
-|''6'' Timeout error| |
+|  \(6\) | Timeout error| |
-|''5'' Program error| Error while programming the SPI |
+|  \(5\) | Program error| Error while programming the SPI |
-|''4'' Erase error| Encountered an error while erasing SPI |
+|  \(4\) | Erase error| Encountered an error while erasing SPI |
-|''3'' %%IdCode%% error| |
+|  \(3\) | %%IdCode%% error| |
-|''2'' Config error| Configuration operation errored out |
+|  \(2\) | Config error| Configuration operation errored out |
-|''1'' Config done| Configuration operation is complete |
+|  \(1\) | Config done| Configuration operation is complete |
-|''0'' Config not busy|Set to ''1'' while the config is not busy|
+|  \(0\) | Config not busy|Set to \(1\) while the config is not busy|
-===== 0xB0-0xCF =====
+===== FPS control =====
 ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
-|Reserved|''0xB0''-''0xCF''| | | | | | |
+|:!: FPS|''0xB0''| | |R/W|\(4\)|float32 FPS|FPS value is in IEEE float32 format, x86 LE|
-===== 0xD0-0xD7 - Auto exposure configuration =====
+===== Bulk color grading =====
 ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
-|AE Setpoint|''0xD0''| |AE Setpoint|R/W|''0'' or ''1'' |''7:0'' AE Setpoint|Target Auto Exposure Luminance Setpoint [0..255]\\ Default: ''105''\\ This controls the "average luminance" of the whole frame that we are trying to achieve. The higher the value the brighter the result is going to be|
+|:!: Bulk color grading|''0xB1''|[\(15:8\)] - table\\ [\(7:0\)] - starting index|[\(15:8\)] - version\\ [\(7:0\)] - count|R/W|\(count * 2\)| |Currently only version \(1\) is supported.\\ The //table// is a value from this list:\\ ''000'' - Hue vs. Hue (\(14\) bits)\\ ''001'' - Hue vs. Saturation (\(12\) bits)\\ ''010'' - Lightness vs. Saturation (\(12\) bits)\\ ''011'' - Saturation vs. Saturation (\(12\) bits)((scheduled for later))\\ ''100'' - Lightness vs. Lightness (\(12\) bits)\\  ''101'' - Hue vs. Lightness (\(12\) bits)((scheduled for later))\\ ''110-111'' - reserved\\ //Starting index// is a \(0\)-based offset of the first written/read color grading value\\ //Version// is currently \(1\)\\ //Count// - how many entries to write/read\\ The buffer is exchanged in data phase of the USB control request (both IN/OUT)|
-|AE Hysteresis|''0xD1''| |AE Hysteresis|R/W|''0'' or ''2'' |''15:0'' AE Hysteresis|Auto Exposure Hysteresis Value [[numberFormats#ufix_8.8|UFIX 8.8]]\\ Default ''3.0''\\ This controls how far can we diverge from the set target luminance before we begin the correction. In other words the higher this value the further we allow the luminance to drift away from the target before correcting it|
-|AE Error Tolerance|''0xD2''| |AE Err Tol|R/W|''0'' or ''2'' |''15:0'' AE Err Tol|Auto Exposure Error Tolerance Value [[numberFormats#ufix_8.8|UFIX 8.8]]\\ Default ''1.0''\\ Specifies the "close enough" tolerance at which point the correction can be stopped. Normally this value is (at least somewhat) lower than the AE Hysteresis|
-|AE Exposure Scaling|''0xD3''| |AE Exp Scale|R/W|''0'' or ''2'' |''15:0'' AE Exp Scale|Auto Exposure Exposure Scaling Value [[numberFormats#ufix_8.8|UFIX 8.8]]\\ Default ''100.0''\\ Controls the speed (stepping) at which the correction is happening. Higher values will result in large brightness jumps and a value too high may cause an oscillation while a value that is too low will cause the correction process to be too slow and seamingly unresponsive|
-|AE C Gain Divisor|''0xD4''| |AE C Gain Divisor|R/W|''0'' or ''2'' |''15:0'' AE C Gain Divisor|Auto Exposure C Gain Divisor Value [[numberFormats#ufix_8.8|UFIX 8.8]]\\ Default ''4.0''\\ Value between 0 and 255 that is inversely proportional to the rate at which the C gain is adjusted in response to exposure errors.  (i.e. the larger the value, the slower C gain will adjust)|
-|Reserved|''0xD5''-''0xD7''| | | | | | |
-===== 0xD8-0xDE - Auto white balance configuration =====
+===== Color correction matrix (a.k.a. CCM or CMX) =====
+See [[isp:ccm|Color correction matrix]] article in this Wiki's ISP section for more details.
 ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
-|AWB Setpoint|''0xD8''| |AWB Setpoint|R/W|''0'' or ''2'' |''15:0'' AWB Setpoint|Auto White Balance G Gain Setpoint [0..2047]\\ Default ''1024''\\ The pinned value for Green Gain that is used as the basis for the rest of the white balance adjustments. Only change this value if you need to make your picture brighter and you have exhausted both the Exposure and the Global Gain options|
+|:!: Color correction matrix|''0xB2''| ''0'' | ''0x0303'' |R/W|32|packed C-array <code>float[3][3]</code>|That data buffer could also be defined as <code>float[9]</code> or as <code>byte*</code> for the same exact memory layout on LE systems|
-|AWB Hysteresis|''0xD9''| |AWB Hysteresis|R/W|''0'' or ''2'' |''15:0'' AWB Hysteresis|Auto White Balance Hysteresis Value [[numberFormats#ufix_8.8|UFIX 8.8]]\\ Default ''3.0''\\ How far can the error drift before we start adjusting it|
-|AWB Error Tolerance|''0xDA''| |AWB Err Tol|R/W|''0'' or ''2'' |''15:0'' AWB Err Tol|Auto White Balance Error Tolerance Value [[numberFormats#ufix_8.8|UFIX 8.8]]\\ Default ''1.0''\\ A.k.a. "good enough" approximation - controls when we stop the correction process, having achieved a "close enough" result. Generally this setting is at least somewhat lower than the AWB Hysteresis value|
-|AWB Adjustment Scaling|''0xDB''| |AWB Adj Scale|R/W|''0'' or ''2'' |''15:0'' AWB Adj Scale|Auto White Balance Adjustment Scaling Value [[numberFormats#ufix_8.8|UFIX 8.8]]\\ Default ''4.0''\\ Value between ''0'' and ''255'' that is inversely proportional to the rate at which the R and B gains are adjusted in response to white balance errors.  (i.e. the larger the value, the slower R and B gains will adjust)|
-|Reserved|''0xDC''-''0xDE''| | | | | | |
-===== 0xDF - Auto-functions' timing =====
+===== 0xB3-0xB7 =====
 ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
-|Auto Update Period|''0xDF''| |Auto Update Period|R/W|''0'' or ''2'' |''15:0'' Auto Update Period|Auto Update Period [0..65535])\\ Default ''3000''\\ Determines how long we wait before trying to apply a new update for both exposure and white balance (when auto functions are enabled).  This is an asynchronous update rate (i.e. not an absolute time, but larger values should mean slower updates)|
+|Reserved|''0xB3''| | | |
+|Reserved|''0xB4''| | | |
+|Reserved|''0xB5''| | | |
+|Reserved|''0xB6''| | | |
+|Reserved|''0xB7''| | | |
-===== 0xE0-0xFF =====
+===== FPGA stats =====
 ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
-|FX3 reset|''0xE0''| | |R/W| | |Cypress vendor command to soft reset FX3|
+|:!: FPGA stats|''0xB8''|statistics type|\(0\)|R/O|see notes|see notes|Read out various stats from FPGA, see [[#FPGA stats' details|table below]] for details|
-|Reserved|''0xE1''-''0xFF''| | | | | | |
+==== FPGA stats' details ===
+^Name ^Value ^Return type ^Notes ^
+| :!: Sensor FPS | ''0x01'' | float | IEEE float32 format, x86 LE number derived from FPGA's video pipeline observed time between first pixel output of two consecutive video frames |
+===== 0xB9 =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|Reserved|''0xB9''| | | |
+===== SDI control =====
+^  Name  ^  Offset  ^  wIndex  ^  wValue  ^  Access type  ^  Byte length  ^  Return buffer bits  ^  Notes  ^
+|:!: SDI control|  ''0xBA''  |  \(0\)  |  \(1\)  |  R/W  |  \(1\)  |\(0\) - SDI on/off | SDI control, for now only on/off with the default video mode of 1080p@60fps 10bit YUV ''4:2:0'' packed |
+===== 0xBB-0xBF =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|Reserved|''0xBB''| | | |
+|Reserved|''0xBC''| | | |
+|Reserved|''0xBD''| | | |
+|Reserved|''0xBE''| | | |
+|Reserved|''0xBF''| | | |
+===== SPI flash management =====
+The SPI flash memory (either \(128\)MB or \(256\)MB) is partitioned into \(65\)KB sectors, each comprised of \(256\) pages. Each page is \(256\) bytes long.
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|SPI command byte|''0xC0''|[\(7:0\)] command byte|\(0\)|R/W| |execute SPI command with no address|
+|SPI command with 24-bit address|''0xC1''|[\(15:8\)] bits [\(23:16\)] of the address\\ [\(7:0\)] command byte|[\(15:0\)] LSW of the address|R/W| |execute SPI command with a \(24\)-bit address|
+|SPI flash write page|''0xC2''|[\(15:0\)] page address| |W/O|\(256\)| |write a page of SPI flash (same command as Cypress' examples). The flash page size is fixed to \(256\) bytes|
+|SPI flash read page|''0xC3''|[\(15:0\)] page address| |R/O|\(256\)|page's content|read a page of SPI flash (same command as Cypress' examples). The flash page size is fixed to \(256\) bytes|
+|SPI flash sector erase/poll|''0xC4''|[\(7:0\)] - sector|\(0\) - poll\\ \(1\) - erase |R/W| | |either erase a SPI flash sector, or poll SPI busy status (same command as Cypress' examples)\\ \\ sector's byte address is computed by multiplying //wIndex// by \(65536\)\\ \\ For Erase SPI flash sector function:\\  - //wValue// = ''0x0001''\\  - //wIndex// = SPI flash sector address\\  - //wLength// = ''0x0000''\\ No data phase associated with this command\\ \\ For Check SPI busy status function:\\  - //wValue// = ''0x0000''\\  - //wIndex// = ''0x0000''\\  - //wLength// = ''0x0001''\\ Data phase indicates flash busy status:\\  - ''0x00'' means SPI flash has finished write/erase operation\\  - non-zero value means that SPI flash is still busy processing previous write/erase command.|
+|SPI flash cmd 24|''0xC5''|[\(7:0\)] command byte\\ [\(15:8\)] address's bits [\(23:16\)]|[\(15:0\)] address's bits [\(15:0\)]|R/W| | |Run an arbitrary SPI flash command byte|
+|Reserved|''0xC6''| | | | | | |
+|Reserved|''0xC7''| | | | | | |
+===== 0xC8-0xCF =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|Reserved|''0xC8''| | | | | | |
+|Reserved|''0xC9''| | | | | | |
+|Reserved|''0xCA''| | | | | | |
+|Reserved|''0xCB''| | | | | | |
+|Reserved|''0xCC''| | | | | | |
+|Reserved|''0xCD''| | | | | | |
+|Reserved|''0xCE''| | | | | | |
+|Reserved|''0xCF''| | | | | | |
+===== Auto exposure configuration =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|:!: AE Setpoint|''0xD0''| |AE Setpoint|R/W|\(0\) or \(2\) |[\(11:0\)] value|Target Auto Exposure Luminance Setpoint \([0..4095]\)\\ Default: \(2500\)\\ This controls the "average luminance" of the whole frame that we are trying to achieve. The higher the value the brighter the result is going to be|
+|Reserved|''0xD1''| | | | | | |
+|Reserved|''0xD2''| | | | | | |
+|Reserved|''0xD3''| | | | | | |
+|Reserved|''0xD4''| | | | | | |
+|Reserved|''0xD5''| | | | | | |
+|Reserved|''0xD6''| | | | | | |
+|Reserved|''0xD7''| | | | | | |
+===== Auto white balance configuration =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|:!: AWB Setpoint|''0xD8''| |AWB Setpoint|R/W|\(0\) or \(2\) |[\(11:0\)] value|Auto White Balance G Gain Setpoint \([0..4095]\)\\ Default \(2048\)\\ The pinned value for Green Gain that is used as the basis for the rest of the white balance adjustments. Only change this value if you need to make your picture brighter and you have exhausted both the Exposure and the Global Gain options|
+|Reserved|''0xDC''| | | | | | |
+|Reserved|''0xDD''| | | | | | |
+|Reserved|''0xDE''| | | | | | |
+===== Auto-functions' timing =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|Auto Update Period|''0xDF''| |Auto Update Period|R/W|\(0\) or \(2\) |[\(15:0\)] value|Auto Update Period \([0..65535]\))\\ Default \(17\)\\ Determines how long we wait before trying to apply a new update for both exposure and white balance (when auto functions are enabled), as well as other up-keep operations, like pushing data over I²C bus.\\ This is an asynchronous update rate.\\ That value is approximately in milliseconds|
+===== FX3 reset =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|FX3 reset|''0xE0''| | |W/O| | |Cypress vendor command to soft reset FX3|
+===== Camera peripherals =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Notes ^
+| LED | ''0xE1'' | See [[#LED function selector]] | \(0\) |  R/W  | \(24\) bits per RGB triplet | Mode selector values are described in [[#LED function selector]] |
+| Fan control and monitoring | ''0xE2'' | See [[#Fan control and monitoring function selector]] | depends on selected function |  R/W  | \(1\) or \(2\) | This API is available in gen4 v.114 and gen5 v.1\\ \\ For function selector values refer to [[#Fan control and monitoring function selector]] |
+| Temperature sensor(s)|''0xE3''| See [[#Temperature sensor monitoring function selector]] | depends on selected function |  R/O  | \(1\) | This API is available in gen4 v.114 and gen5 v.1\\ \\ For function selector values refer to [[#Temperature sensor monitoring function selector]] below |
+|Reserved|''0xE4''| | | |
+|Reserved|''0xE5''| | | |
+|Reserved|''0xE6''| | | |
+|Reserved|''0xE7''| | | |
+|Reserved|''0xE8''| | | |
+====== LED function selector ======
+^Function ^Value ^Byte length^ Notes ^
+| Unified LED color | \(0\) | \(3\) | For both gen4 and gen5 this allows to get/set the single \(24\)-bit RGB triplet for LED pixel(s) color. When reading from multi-pixel setup the value of the first pixel is returned |
+| Left-side LED color | \(1\) | \(3\) | Gen5 has two sides for pixels, this allows to get/set the color of the left group. When reading the value of the first pixel in a group is returned |
+| Right-side LED color | \(2\) | \(3\) | Gen5 has two sides for pixels, this allows to get/set the color of the right group. When reading the value of the first pixel in a group is returned |
+| \(8\)-pixel LED mode | \(3\) | \(24\) | Gen5 comes with a total of 8 LED pixels, individually controllable with this API. The command always operates (gets/sets) the full array of \(8\) \(3\)-byte RGB pixels |
+====== Fan control and monitoring function selector ======
+^Function ^Value ^Type ^Byte length^ Notes ^
+| FPGA-controlled fan on/off | \(0\) | <code>boolean</code> | \(1\) | Gen4 (including the REX model) is equipped with a fan that is controlled by FPGA |
+| EMC2101's fan speed | \(1\) | <code>uint8_t</code> | fan speed | The speed's value is in range \([0..100]\%\) though keep in mind that at very low speeds the fan may stop spinning |
+| EMC2101's fan RPM reading | \(2\) | <code>uint16_t</code> | RPM, R/O access | This reading is based on internal tachometer's clock ticks' count |
+====== Temperature sensor monitoring function selector ======
+^Function ^Constant ^Value ^Byte length^ Notes ^
+| EMC2101's internal temperature sensor | ''0'' | ''int8_t'' | ''1'' | A signed temperature reading in °C |
+===== 0xE9-0xEF =====
+|Reserved|''0xE9''| | | |
+|Reserved|''0xEA''| | | |
+|Reserved|''0xEB''| | | |
+|Reserved|''0xEC''| | | |
+|Reserved|''0xED''| | | |
+|Reserved|''0xEE''| | | |
+|Reserved|''0xEF''| | | |
+===== 0xF0-0xF9 =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|Reserved|''0xF0''| | | |
+|Reserved|''0xF1''| | | |
+|Reserved|''0xF2''| | | |
+|Reserved|''0xF3''| | | |
+|Reserved|''0xF4''| | | |
+|Reserved|''0xF5''| | | |
+|Reserved|''0xF6''| | | |
+|Reserved|''0xF7''| | | |
+|Reserved|''0xF8''| | | |
+|Reserved|''0xF9''| | | |
+===== [Debug] Get raw descriptor =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|Get raw descriptor|''0xFA''|[[#Get raw descriptor commands|command]]|[[#Get raw descriptor structure types|struct to get]]|R/O|varies by command (see below)|struct's byte buffer|This APi is mostly used for debugging purposes and provides "direct" access to USB descriptors|
+==== Get raw descriptor commands ====
+^Cmd (wIndex) ^Meaning ^
+|\(0\)|get a \(2\)-byte descriptive text label's length (not including the C-style null-terminator)|
+|\(1\)|get descriptive text label (up to \(4096\) bytes **without** a C-style null-terminator)|
+|\(2\)|get a \(2\)-byte size of the structure in bytes|
+|\(3\)|get structure's byte buffer|
+==== Get raw descriptor structure types ====
+As of FX3 version ''58'' the following internal structures are supported:
+^wValue ^ Details ^
+|\(0\)|reserved (unused)|
+|\(1\)|USB device descriptor HS|
+|\(2\)|USB device descriptor SS|
+|\(3\)|USB Device Qualifier descriptor|
+|\(4\)|USB BOS (Binary Object Store) descriptor|
+|\(5\)|MS OS Platform Capability descriptor version 2.0|
+|\(6\)|Full-Speed (2.0) USB Configuration descriptor|
+|\(7\)|High-Speed (2.0) USB Configuration descriptor|
+|\(8\)|Super-Speed (3.0) USB Configuration descriptor|
+===== OS runtime info =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|:!: OS runtime info|''0xFB''|see below|see below|R/O|see below|see below|Query for OS internal info. A type of query is specified in ''wValue'' field and, along with other fields, is described in the table below|
+^wValue ^wIndex ^Description ^
+|  :!: \(0\)  | | get number of user trheads |
+|  :!: \(1\)  | \(0\)-based thread's index |get info on the thread, see [[OsThreadInfo_v60|struct OsThreadInfo]] for details|
+===== 0xFC-0xFF - Reserved for debug APIs =====
+^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^
+|Reserved|''0xFC''| | | | | | |
+|Reserved|''0xFD''| | | | | | |
+|Reserved|''0xFE''| | | | | | |
+|Reserved|''0xFF''| | | | | | |
-====== FPGA I²C bridge ======
+====== FPGA I²C bridge (registers' map) ======
 The following tables provide information on how to access the camera's functionality for an FPGA I²C bridge.
-Here's a sample code (skipping all error checking) that sets the LED to bright-yellow color:
+Here's a sample code (skipping all error checking) that sets the LED to bright-yellow color FIXME:
 <code c++>S2R::FX3 dev; // auto-open device #0
 using S2R::FX3;
@@ Line 139: / Line 332: @@
 The address space is broken down into smaller chunks, grouped by common functionality:
-===== 0x00-0x07 - FPGA general access =====
+===== FPGA basic status and controls =====
-^Name ^Offset ^Access ^Bit mapping ^Notes ^
+^Name ^Offset ^Bytes ^Access ^Bit mapping ^Notes ^
-|FPGA Version #0|''0x00''|R/O|''7:5'' Vendor ID\\ ''4:0'' HW_CFG_ID| |
+|:!: FPGA Version|''0x00''|  4  |R/O| see [[#Firmware Version Info]] | |
-|FPGA Version #1|''0x01''|R/O|''7:0'' Product ID| |
+|:!: FPGA status|''0x01''|  1  |R/O|''7:2'' reserved| |
-|FPGA Version #2|''0x02''|R/O|''7:3'' Release type\\ ''2:0'' Build number MSB|Build number is split into 2 MSB and 8 LSB for a combined total width of 10 bits|
+|:::|:::|:::|:::|:!: ''1'' DPC calibration done| ''1'' indicates that DPC calibration is completed |
-|FPGA Version #3|''0x03''|R/O|''7:0'' Build number LSB|:::|
+|:::|:::|:::|:::|:!: ''0'' SFP+| ''1'' indicates there is an active device in SFP+ cage |
-|FPGA config status #0|''0x04''|R/O|see [[#FPGA config status - SPI codes|SPI codes]] for details|LSB (bits ''7''-''0'') of the FPGA config status|
+|:!: FPGA control|''0x02''|  1  |R/W|''7:2'' reserved| |
-|FPGA config status #1|''0x05''|R/O|see [[#FPGA config status - SPI codes|SPI codes]] for details|MSB (bits ''15''-''8'') of the FPGA config status|
+|:::|:::|:::|:::|:!: ''1'' enable DPC| enable DPC correction |
-|FPGA control|''0x06''|R/W| |Global control of the FPGA's functionality|
+|:::|:::|:::|:::|:!: ''0'' FPGA config enable|if set to ''1'', the GPIF becomes read only and waits for an FPGA update bitstream|
-|:::|:::|:::|''7'' FPGA config enable|If bit ''7'' is set, the GPIF becomes read only and waits for an update bitstream|
+|:!: FPGA config status|''0x03''|  2  |R/O|see [[#FPGA config status - SPI codes|SPI codes]] for details| |
-|:::|:::|:::|''6'' Reserved| |
+|:!: FPGA core temperature|''0x04''|  1  | R/O | ''7:0'' - temperature in Farenheits | Reading of the FPGA's internal temperature sensor in degrees of Farenheits |
-|:::|:::|:::|''5'' RAW Mode|Setting bit ''5'' and clearing bit ''0x06::2'' will enable RAW mode output (4K Only)|
+|:!: LED RED|''0x05''|  2  |R/W| |LED's red intensity in range \([0..65535]\)|
-|:::|:::|:::|''4'' Video Format|Bit ''4'' selects between NV12 ('1') and YUY2 ('0') output formats |
+|:!: LED GREEN|''0x06''|  2  |R/W| |LED's green intensity in range \([0..65535]\)|
-|:::|:::|:::|''3'' DPC enable|Setting bit ''3'' along with bit ''0x06::0'' will perform a DPC correction|
+|:!: LED BLUE|''0x07''|  2  |R/W| |LED's blue intensity in range \([0..65535]\)|
-|:::|:::|:::|''2'' HSUB enable|Bit ''2'' is to enable/disable [[isp:Horizontal Subsampling]]|
-|:::|:::|:::|''1'' Audio enable|Bit ''1'' is to enable/disable on-board microphones|
+===== AWB =====
-|:::|:::|:::|''0'' Video enable|Bit ''0'' enables/disables video streaming|
+Info for performing Auto White-Balance adjustments on the image
-|FPGA core temperature|''0x07''| R/O | ''7:0'' - temperature in Farenheits | Reading of the FPGA's internal temperature sensor in degrees of Farenheits |
+^Name ^Offset ^Bytes ^Access ^Notes ^
+|:!: AWB Red adjustment|''0x08''|  2  |R/W|a signed 16-bit value of an adjustment to apply to every pixel in Red channel. Default is \(0\)|
+|:!: AWB Green adjustment|''0x09''|  2  |R/W|a signed 16-bit value of an adjustment to apply to every pixel in Green channel. Default is \(0\)|
+|:!: AWB Blue adjustment|''0x0A''|  2  |R/W|a signed 16-bit value of an adjustment to apply to every pixel in Blue channel. Default is \(0\)|
+|Reserved| ''0x0B'' | | | |
+|:!: AWB Red total| ''0x0C'' |  4  | R/O | |
+|:!: AWB Green total| ''0x0D'' |  4  | R/O | |
+|:!: AWB Blue total| ''0x0E'' |  4  | R/O | |
+|:!: AWB count total| ''0x0F'' |  4  | R/O | A count of pixels that were used to calculate the \(R/G/B\) totals |
+===== Basic UVC controls =====
+^Name ^Offset ^Bytes ^Access ^Range ^Range description ^Neutral value ^
+|:!: Brightness|''0x10''|  2  |R/W|\([-1024..1023]\) |\(-1024\) makes the image very dark\\ \(1023\) makes the image very bright |\(0\) |
+|:!: Contrast|''0x11''|  2  |R/W|\([1..2047]\)  |\(1\) turns image into grayscale\\ \(2047\) makes all pixels either black or white |\(1023\) |
+|:!: Saturation|''0x12''|  2  |R/W|\([0..900]\) |\([0\%..900\%]\) or grayscale to 9x |\(100\) |
+|:!: Sharpness|''0x13''|  1  |R/W|\([0..255]\) | |\(0\) |
+|:!: Gamma|''0x14''|  1  |R/W|\([0..15]\) | |\(0\) |
+|:!: Hue|''0x15''|  2  |R/W|\([-8192..8191]\) |\([-180°..180°)\) |\(0\) |
+|Reserved|''0x16-0x1F''| | | | |
-===== 0x08-0x0D - LED =====
-^Name ^Offset ^Access ^Bit mapping ^Notes ^
-|LED_RED_L|''0x08''|R/W|''7:0'' Red LED|LSB of LED's red intensity in range [0..255]|
-|LED_RED_H|''0x09''|R/W|Reserved| |
-|LED_GREEN_L|''0x0A''|R/W|''7:0'' Green LED|LSB of LED's green intensity in range [0..255]|
-|LED_GREEN_H|''0x0B''|R/W|Reserved| |
-|LED_BLUE_L|''0x0C''|R/W|''7:0'' Blue LED|LSB of LED's blue intensity in range [0..255]|
-|LED_BLUE_H|''0x0D''|R/W|Reserved| |
-===== 0x0E-0x0F - Noise Reduction =====
+===== General image stats and adjustments =====
-==== pre-68 (SUB2r-lib will continue supporting this until end of August 2019) ====
+^  Defective pixel cancellation  ^^^^^
-^Name ^Offset ^Access ^Bit mapping ^Notes ^
+^Name ^Offset ^Bytes ^Access ^Notes ^
-|NR Control|''0x0E''|R/W|''7:1'' Reserved| |
+|:!: DPC Threshold|''0x20''|  2  |R/W| A write into this register triggers the start of DPC calibration |
-|:::|:::|:::|''0'' NR Enable| '1' => NR enabled, '0' => NR disabled|
+|:!: DPC count|''0x21'' |  2  |R/O|Once the DPC calibration is done the 16-bit value is stored in here|
-|NR Threshold|''0x0F''|R/W|''7:0'' NR Threshold|Noise level threshold in range [0..255]|
+| |||||
+^  General image stats  ^^^^^
+|:!: flags|''0x22''|  1  |R/O| ''7:2'' reserved\\ :!: ''1'' - indicates whether a red overexposure is detected\\ :!: ''0'' - set if there is a general overexposure detected |
+|:!: FPS|''0x23''|  2  |R/O|16-bit unsigned value representing number of 10μs units between frame start signals from the image sensor, e.g. a value of \(1000\) means it took 10ms between 2 frame start signals, which corresponds to 100FPS|
+|:!: Y average|''0x24''|  2  |R/O|Average "brightness" value|
+| |||||
+^  Color Correction Matrix (a.k.a. CCM or CMX)  ^^^^^
+|  See [[isp:ccm|Color correction matrix]] article in this Wiki's ISP section for more details. The 16-bit (MSB-LSB) value is defined as 7+9 bits, where MSB[7:1] are the integer part and MSB[0]LSB[7:0] is the fractional part (effectively that value is 512 times larger than the original fractional part)  |||||
+|:!: CCM_00|''0x25''|  2  |R/W|\(CCM_{00}\)|
+|:!: CCM_01|''0x26''|  2  |R/W|\(CCM_{01}\)|
+|:!: CCM_02|''0x27''|  2  |R/W|\(CCM_{02}\)|
+|:!: CCM_10|''0x28''|  2  |R/W|\(CCM_{10}\)|
+|:!: CCM_11|''0x29''|  2  |R/W|\(CCM_{11}\)|
+|:!: CCM_12|''0x2A''|  2  |R/W|\(CCM_{12}\)|
+|:!: CCM_20|''0x2B''|  2  |R/W|\(CCM_{20}\)|
+|:!: CCM_21|''0x2C''|  2  |R/W|\(CCM_{21}\)|
+|:!: CCM_22|''0x2D''|  2  |R/W|\(CCM_{22}\)|
-==== starting with version 68 ====
+===== Color grading =====
-^Name ^Offset ^Access ^Bit mapping ^Notes ^
-|Chroma NR Control|''0x0E''|R/W|''7'' Reserved, must be ''0''\\ ''6:0'' value| Chroma (color or an \(H\) component of the \(H/S/L\) pixel data) noise reduction in range \([0\%..100\%]\) mapped into \([0..127]\). Setting this to ''0'' effectively turns the chroma denoising off |
-|Luma NR Control|''0x0F''|R/W|''7'' Reserved, must be ''0''\\ ''6:0'' value| Luma (brightness or an \(L\) component of the \(H/S/L\) pixel data) noise reduction in range \([0\%..100\%]\) mapped into \([0..127]\). Setting this to ''0'' effectively turns the luma denoising off |
-===== 0x10-0x1F - Basic UVC controls =====
 ^Name ^Offset ^Access ^Bit mapping ^Notes ^
-|Brightness_L|''0x10''|R/W|''7:0'' LSB|16 bits of brightness are split into 8 bits of LSB and MSB |
+|:!: switch|''0x2E''|W|''15:10'' reserved |Controls what information is being read/written by accessing the register ''0x002F''|
-|Brightness_H|''0x11''|R/W|''7:0'' MSB|:::|
+|:::|:::|:::|''9:7'' table switch|''000'' - Hue vs. Hue (''14'' bits)\\ ''001'' - Hue vs. Saturation (''12 bits'')\\ ''010'' - Lightness vs. Saturation (''12'' bits)\\ ''011'' - Saturation vs. Saturation (''12'' bits)\\ ''100'' - Lightness vs. Lightness (''12'' bits)\\  ''101'' - Hue vs. Lightness (''12'' bits)\\ ''110-111'' - reserved|
-|Contrast_L|''0x12''|R/W|''7:0'' LSB|16 bits of contrast are split into 8 bits of LSB and MSB |
+|:::|:::|:::|''6:1'' index LSB| index into a page in the table |
-|Contrast_H|''0x13''|R/W|''7:0'' MSB|:::|
+|:::|:::|:::|''0'' access mode| ''0'': "normal mode", in which all the subsequent accesses to the register ''0x002F'' are governed by the values in ''0x002E''\\ ''1'': "bulk access", where after a read or write access to register ''0x002F'' the "Index" value will auto-increment by one so that the next read/wrie will access the subsequent table slot|
-|Saturation_L|''0x14''|R/W|''7:0'' LSB|16 bits of saturation are split into 8 bits of LSB and MSB |
+|:!: Value|''0x2F''|R/W|''15:0'' value| 16 bits of either signed or unsigned integer value\\  - for a "Hue vs. Hue" table the 14 bits signed value is in range ''[-8192..+8192]'' which maps linearly into a Hue angle range ''-180°..+180°''\\  - for a "Hue vs. Saturation" table (as well as for similar tables %%LvS%% and %%SvS%%) the 12 bit unsigned value in range ''[0..+1280]'' maps linearly into a Saturation range ''[0%..1000%]'' where ''100%'' is the neutral position and ''0%'' produces a greyscale image\\  - (until FPGA v.72) for a "Lightness vs. Lightness" table (as well as for similar table %%HvL%%) the 12 bit unsigned value in range ''[0..+4095]'' maps linearly into a Lightness absolute range ''[0..255]'' where ''0'' is pitch black and ''255'' is the maximum possible pixel luminosity value\\  - (starting with FPGA v.73) for a "Lightness vs. Lightness" table (as well as for similar table %%HvL%%) the 13 bit signed value in range ''[-4096..+4095]'' maps linearly into a Lightness *relative* (adjustment) range ''[-256..255]'' where ''0'' is no adjustment to pixel luminosity value|
-|Saturation_H|''0x15''|R/W|''7:0'' MSB|:::|
-|Sharpness_L|''0x16''|R/W|''7:0'' LSB|16 bits of sharpness are split into 8 bits of LSB and MSB |
-|Sharpness_H|''0x17''|R/W|''7:0'' MSB|:::|
-|Gamma_L|''0x18''|R/W|''7:0'' LSB|16 bits of gamma are split into 8 bits of LSB and MSB |
-|Gamma_H|''0x19''|R/W|''7:0'' MSB|:::|
-|Hue_L|''0x1A''|R/W|''7:0'' LSB|16 bits of hue are split into 8 bits of LSB and MSB |
-|Hue_H|''0x1B''|R/W|''7:0'' MSB|:::|
-|Reserved|''0x1C''-''0x1F''| | |
-===== 0x20-0x27 - Defective pixel cancellation =====
+===== Media setup =====
+==== Media output and transform blocks ====
 ^Name ^Offset ^Access ^Bit mapping ^Notes ^
-|DPC Threshold LSB|''0x20''|R/W|''7:0'' LSB| 16 bit of DPC (defective pixel cancellation) Threshold are split into 8 bits of LSB and MSB|
+|:!: Media output modules|''0x30''|R/W|''7'' - res\\ ''6'' - res (headphones)\\ ''5'' - res (UAC)\\ ''4'' - res\\ :!: ''3'' - HDMI video\\ :!: ''2'' - SDI video\\ :!: ''1'' - SFP+ video\\ :!: ''0'' - UVC|Enable/disable state of individual media output modules for video and audio streams|
-|DPC Threshold MSB|''0x21''|R/W|''7:0'' MSB|:::|
+|:!: Video transform blocks|''0x31''|R/W|:!: ''7'' - sharpness\\ ''6'' - res\\ ''5'' - res\\ ''4'' - res\\ ''3'' - res\\ ''2'' - res\\ :!: ''1'' - CCM\\ :!: ''0'' - (UVC Gamma)|Enable/disable individual transformation blocks in video pipeline|
-|DPC count LSB|''0x22''|R/O|''7:0'' LSB|Once the DPC calibration is done the 16-bit value is stored in these 2 registers|
-|DPC count MSB|''0x23''|R/O|''7:0'' MSB|:::|
-|Reserved|''0x24''-''0x27''| | |
-===== 0x28-0x2F - General image statistics =====
+==== Video output formats ====
 ^Name ^Offset ^Access ^Bit mapping ^Notes ^
-|Y average|''0x28''|R/O|''7:0'' value|
+|:!: Video output format|''0x32''|R/W|:!: ''7:4'' - UVC\\ :!: ''3:0'' - FPS code for SDI, SFP+, SDI|Bit depth for all video formats is set in register ''0x49''\\ UVC video formats:\\ :!:''0'' - "RAW" greyscale pre-debayer pixels\\ :!:''1'' - 4:4:4 RGB\\ :!:''2'' - (res) packed YCbCr 4:4:4\\ :!:''3'' - packed YCbCr 4:2:2\\ :!:''4'' - (res) packed YCbCr 4:2:0\\ :!:''5'' - (res) planar YCbCr 4:4:4\\ :!:''6'' - (res) planar YCbCr 4:2:2\\ :!:''7'' - planar YCbCr 4:2:0\\ :!:''8-15'' - (res) MJPEG, MPEG-x/H.26x, etc\\ \\ SDI/HDMI and SFP+ video output formats/FPS are always in unison. See [[code:fx3_hvci_and_fpga_i_c_commands#sdi_fps|SDI FPS]] table below for codes. SDI output is always in a packed (not planar) YUV 4:2:2 format|
-|<del>U average</del>|<del>''0x29''</del>|<del>R/O</del>| |
+|:!: Video output pixel bit depth|''0x33''|R/W|:!: ''7:6'' - HDMI\\ :!: ''5:4'' - SDI\\ :!: ''3:2'' - SFP+\\ :!: ''1:0'' - UVC|Pixel bit depths \(d_p\) is calculated from a 2-bit value \(N\) as: \[d_p = (N+4)*2\] Not all values are valid, for example SDI and SFP+ both do not support ''8''-bit output and UVC **only** supports ''8''-bit color depth, at least for now|
-|<del>V average</del>|<del>''0x2A''</del>|<del>R/O</del>| |
-|R average|''0x29''|R/O|''7:0'' value|an average RGB value|
-|G average|''0x2A''|R/O|''7:0'' value|:::|
-|B average|''0x2B''|R/O|''7:0'' value|:::|
-|Reserved|''0x2C''-''0x2F''| | |
-===== 0x30-0x3F - GPIO =====
+==== Image sensor config ====
 ^Name ^Offset ^Access ^Bit mapping ^Notes ^
-|CAM_GPIO_L|''0x30''|R/W|reserved| |
+|:!: Image sensor configuration|''0x34''|R/W|''7:2'' - res\\ :!: ''1:0'' - de-mosaicing strategy|**De-mosaicing strategy** directs the use of a specific implementation of color reconstruction:\\ ''3'', ''2'' - reserved\\ ''1'' - use "branching 5x5", for example the one [[http://www.siliconimaging.com/RGB%20Bayer.htm|described here]]\\ ''0'' - use "branchless 5x5", like the one [[https://www.ipol.im/pub/art/2011/g_mhcd/article.pdf|described in here]]|
-|CAM_GPIO_H|''0x31''|R/W|reserved| |
+|Reserved|''0x35-0x39''| | | |
-|CAM_GPIO_DIR_L|''0x32''|R/W|reserved| |
-|CAM_GPIO_DIR_H|''0x33''|R/W|reserved| |
-|CAM_GPIO_OE_L|''0x34''|R/W|reserved| |
-|CAM_GPIO_OE_H|''0x35''|R/W|reserved| |
-|Reserved|''0x36''-''0x3F''| | |
-===== 0x40-0x7F - On-board compression =====
+==== Audio setup ====
 ^Name ^Offset ^Access ^Bit mapping ^Notes ^
-|Reserved|''0x40''-''0x7F''| | | Compression doesn't fit into the current Xilinx Artix-7 100T FPGA |
+|:!: Audio transform blocks|''0x3A''|R/W|''7:0'' - res|Enable/disable individual transformation blocks in audio pipeline|
+|Reserved|''0x3B-0x3F''| | | |
-===== 0x80-0xBF - Green Screen enhancer =====
+==== FOURCC formats (for UVC) ====
+A combination of data in ''0x0033[1:0]'' (pixel bit depth) and ''0x32[7:4]'' (video format) used for UVC is mapped into standard FOURCC codes as summarized in the following table:
+^''0x0033[1:0]''\''0x0032[7:4]'' ^''0'' (RAW) ^''1'' (RGB) ^''2'' (packed YUV 4:4:4((ordering is UYV))) ^''3'' (packed YUV 4:2:2((macropixel byte ordering: Y0U0Y1V0))) ^''7'' (planar YUV 4:2:0((chroma plane is a interleaved set of U/V samples))) ^
+^''0'' (8 bit) |:!: BA81/BYR1/GREY/Y8/Y800 (8bpp)|:!: BI_RGB/RGB (24bpp) |:!: Y444/IYU2 (24bpp) |:!: YUY2/YUYV (16 bpp)|:!: NV12 (12bpp)|
+^''1'' (10 bit) |:!: Y10((need to register with MS)) (16bpp((not 10)))|:!: BI_BITFIELDS (48bpp) |:!: Y410 (32bpp((includes 2 bit alpha at [31:30]))) |:!: Y210 (32bpp)\\ YUVP?/Y42T (24bpp?)|:!: P010 (32bpp) |
+^''2'' (12 bit) |:!: BYR2 (16pbb((not 12)))|:!: BI_BITFIELDS (48bpp) |:!: Y412((need to register with MS)) (40bpp((or 36?))) |:!: Y212((need to register with MS)) (32bpp((or 24?))) |:!: P012((need to register with MS)) (32bpp((or 24, or 18?))) |
+^''3'' (14 bit) |:!: Y16((yes, 16, not 14)) (16bpp((not 14)))|:!: BI_BITFIELDS (48bpp) |:!: Y414((need to register with MS)) (48bpp((or 42?))) |:!: Y214((need to register with MS)) (32bpp((or 28?))) |:!: P014((need to register with MS)) (32bpp((or 21?))) |
+==== SDI FPS ====
+Below is the table that lists codes for supported SDI FPS settings set in ''0x0032[3:0]'':
+^  FPS  ^  code  ^
+|  23.98  |  0x01  |
+|  24  |  0x02  |
+|  25  |  0x04  |
+|  29.97  |  0x05  |
+|  30  |  0x06  |
+|  50  |  0x08  |
+|  59.94  |  0x09  |
+|  60  |  0x0A  |
+|  120  |  0x0C  |
+==== SDI pixel clock frequency ====
+^  Frame geometry  ^  MHz  ^  FPS  ^
+|  1920x1080  |  74.18  |  23.98  |
+|  :::   |  :::   |  29.97  |
+|  :::   |  74.25  |  24  |
+|  :::   |  :::   |  25  |
+|  :::   |  :::   |  30  |
+|  :::   |  148.35  |  59.94  |
+|  :::   |  148.5  |  50  |
+|  :::   |  :::   |  60  |
+|  :::   |  297  |  120  |
+|  3840x2160  |  296.70  |  23.98  |
+|  :::   |  :::   |  29.97  |
+|  :::   |  297   |  24  |
+|  :::   |  :::   |  25  |
+|  :::   |  :::   |  30  |
+|  :::   |  593.41  |  59.94  |
+|  :::   |  594  |  50  |
+|  :::   |  :::   |  60  |
+|  :::   |  1188  |  120  |
+|  7680x4320  |  1188  |  24  |
+|  :::   |  :::   |  30  |
+===== Green Screen enhancer =====
 //"Green screen", a.k.a. "Chroma Key" on-board optimization is designed to replace a range of colors with a single solid one//
-==== 0x80-0x8F - band #0 ====
+==== band #0 ====
 If enabled these setting take precedence over other 3 bands
-^Name ^Offset ^Access ^Bit mapping ^Notes ^
+^Name ^Offset ^Bytes ^Access ^Notes ^
-|CK control|''0x80''|R/W|''7:1'' reserved\\ ''0'' enable|enable/disable Chroma Key control|
+|:!: CK control|''0x80''|  1  |R/W|''7:1'' reserved\\ ''0'' enable/disable Chroma Key control|
-|CK status|''0x81''| |reserved| |
+|:!: CK saturation min|''0x81''|  1  |R/W|[0..255] to specify the minimum saturation threshold|
-|CK saturation min|''0x82''|R/W|''7:0'' sat. min|[0..255] to specify the minimum saturation threshold|
+|:!: CK saturation max|''0x82''|  1  |R/W|[0..255] to specify the maximum saturation threshold|
-|CK saturation max|''0x83''|R/W|''7:0'' sat. max|[0..255] to specify the maximum saturation threshold|
+|:!: CK luma min|''0x83''|  1  |R/W|[0..255] to specify the minimum brightness threshold|
-|CK luma min|''0x84''|R/W|''7:0'' luma min|[0..255] to specify the minimum brightness threshold|
+|:!: CK luma max|''0x84''|  1  |R/W|[0..255] to specify the maximum brightness threshold|
-|CK luma max|''0x85''|R/W|''7:0'' luma max|[0..255] to specify the maximum brightness threshold|
+|:!: CK hue|''0x85''|  2  |R/W|14 bits of a signed hue value, its [-8K..+8K] range is mapped into [-180°..+180°]|
-|CK hue LSB|''0x86''|R/W|''7:0'' hue LSB|14 bits of a signed hue value are split into 8 LSB and 6 MSB, its [-8K..+8K] range is mapped into [-180°..+180°]|
+|:!: CK tolerance|''0x86''|  2  |R/W|13 bits of an unsigned hue tolerance value, valid range is [0..8K], which is mapped into [0°..180°].\\ That value specifies how far to stretch the ''CK hue'' value both ways (symmetrically). If the ''CK tolerance'' is above 90° the covered color space is over 50% of values|
-|CK hue MSB|''0x87''|R/W|''7:6'' reserved\\ ''5:0'' hue MSB|:::|
+|:!: CK red|''0x87''|  2  |R/W| |
-|CK tolerance LSB|''0x88''|R/W|''7:0'' tolerance LSB|13 bits of an unsigned hue tolerance value are split into 8 LSB and 5 MSB, valid range is [0..8K], which is mapped into [0°..180°].\\ That value specifies how far to stretch the ''CK hue'' value both ways (symmetrically). If the ''CK tolerance'' is above 90° the covered color space is over 50% of values|
+|:!: CK green|''0x88''|  2  |R/W| |
-|CK tolerance MSB|''0x89''|R/W|''7:5'' reserved\\ ''4:0'' tolerance MSB|:::|
+|:!: CK blue|''0x89''|  2  |R/W| |
-|CK red LSB|''0x8A''|R/W|''7:0'' red LSB| |
+|Reserved|''0x8A-0x8F''| | | |
-|CK red MSB|''0x8B''|R/W|reserved| |
-|CK green LSB|''0x8C''|R/W|''7:0'' green LSB| |
-|CK green MSB|''0x8D''|R/W|reserved| |
-|CK blue LSB|''0x8E''|R/W|''7:0'' blue LSB| |
-|CK blue MSB|''0x8F''|R/W|reserved| |
-==== 0x90-0x9F - band #1 ====
+==== band #1 ====
 Color substitution (if enabled) takes place after the first band had a chance to process the pixels
-The layout of the settings is identical to that of band #0 just shifted down by a paragraph and occupying address block ''0x90-0x9F''
+The layout of the settings is identical to that of band #0 just shifted down by a paragraph and occupying address block ''0x0090-0x009F''
-==== 0xA0-0xAF - band #2 ====
+==== band #2 ====
 Color substitution (if enabled) takes place after the first and second bands had a chance to process the pixels
-The layout of the settings is identical to that of band #0 just shifted down by 2 paragraphs and occupying address block ''0xA0-0xAF''
+The layout of the settings is identical to that of band #0 just shifted down by 2 paragraphs and occupying address block ''0x00A0-0x00AF''
-==== 0xB0-0xBF - band #3 ====
+==== band #3 ====
 Color substitution (if enabled) takes place after other bands had a chance to process the pixels
 The layout of the settings is identical to that of band #0 just shifted down by 3 paragraphs and occupying address block ''0xB0-0xBF''
-===== 0xC0-0xCF - Color grading =====
-^Name ^Offset ^Access ^Bit mapping ^Notes ^
+==== mFT lense access ====
-|switch|''0xC0''|W| |Controls what information is being read/written by accessing the next set of registers (''0xC2..0xC3'')|
-|:::|:::|:::|''7:5'' table switch|''000'' - Hue vs. Hue (''14'' bits)\\ ''001'' - Hue vs. Saturation (''12 bits'')\\ ''010'' - Lightness vs. Saturation (''12'' bits)\\ ''011'' - Saturation vs. Saturation (''12'' bits)((scheduled for later))\\ ''100'' - Lightness vs. Lightness (''12'' bits)\\  ''101'' - Hue vs. Lightness (''12'' bits)((scheduled for later))\\ ''110-111'' - reserved|
-|:::|:::|:::|''4:1'' index MSB|Reserved for 4 MSB of the 12-bit index into tables|
-|:::|:::|:::|''0'' access mode| the only valid value right now is ''0'', which is "normal mode", in which all the subsequent access to the registers in this API block are governed by the values in ''0xC0'' and ''0xC1''\\ ''1'' would be used for "bulk access" where after a read or write access to register ''0xC2'' the "Index" value will auto-increment by one so that the next pair will access the subsequent table slot|
-|Index LSB|''0xC1''|W|''7:0'' index LSB| 8 LSB bits of the 12-bit index into a table (we only use 6 bits today and the rest are ignored)|
-|Value L|''0xC2''|R/W|''7:0'' LSB| 16 bits split into 8 LSB and 8 MSB\\  - for a "Hue vs. Hue" table the 14 bits signed value is in range ''[-8192..+8192]'' which maps linearly into a Hue angle range ''-180°..+180°''\\  - for a "Hue vs. Saturation" table (as well as for similar tables %%LvS%% and %%SvS%%) the 12 bit unsigned value in range ''[0..+1280]'' maps linearly into a Saturation range ''[0%..1000%]'' where ''100%'' is the neutral position and ''0%'' produces a greyscale image\\  - for a "Lightness vs. Lightness" table (as well as for similar table %%HvL%%) the 12 bit unsigned value in range ''[0..+4095]'' maps linearly into a Lightness range ''[0..255]'' where ''0'' is pitch black and ''255'' is the maximum possible pixel luminosity value|
-|Value H|''0xC3''|R/W|''7:0'' MSB|:::|
-|Reserved|''0xC4''-''0xCF''| | |
+^Name ^Offset ^Bytes ^Access ^Notes ^
+|:!: mFT control register|''0xC0''|  1  |R/W|''7:2'' returned data count\\ ''1'': (R/O) command completion flag \\ ''0'': (W/O) setting this to ''1'' sends the command to mFT|
+|:!: mFT command setup|''0xC1''|  1  |W/O|See below for the 32-bit command structure|
+|:!: mFT returned data|''0xC2''|  1  |R/O|Once the command completion flag is set in control register returned data can be retrieved through this register|
-===== 0xD0-0xFF - Reserved =====
+FPGA "register" ''0xC1'' serves as a service point to access mFT protocol and allows FX3 to communicate with the mFT by forwarding requests and replies between the two.
-This is where future API will land. Stay tuned ;-)
-====== FX3 Version Info ======
+Micro Four Thirds System (mFT) defines a communication protocol in which the "body" (host) issues 4 bytes of data (command type, command code, and two 1-byte parameters) and gets a response of variable number of bytes, depending on the command (including a 0-length data response). See the mFT spec for each individual command's request/response.
+FPGA acts as a two-way command repeater and in such capacity it expects a 4 byte command supplied to it as part of an I²C "write" operation and responds with the appropriate return data buffer to a subsequent "read" I²C operation on the same address.
+The 4 bytes of the command are laid out as follows:
+<code>struct MftCmd{
+  uint8_t cmd_type;
+  uint8_t cmd_code;
+  uint8_t param1, param2;
+};
+</code>
+or in a more visual format (taking into consideration the little-endian memory layout typical of the architectures we use):
+|  MSW  ||  LSW  ||
+|  MSB  |  LSB  |  MSB  |  LSB  |
+|  param2  |  param1  |  cmd_code  |  cmd_type  |
+which is the equivalent of this code:
+<code>MftCmd cmd{1, 2, 3, 4};
+static_assert(std::bit_cast<uint32_t>(cmd) == 0x04030201);
+</code>
+====== Firmware Version Info ======
+This applies to both FX3 and FPGA firmware version info data structures.
+===== Bit layout =====
+The bits are laid out in 4 sequential bytes as follows:
+^  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  ^
+|  buildNo[12:5]  ||||||||  buildNo[4:0]  |||||  releaseType  |||  productId  ||||||||  hwCfgId  |||||  vendorId  |||
+===== Firmware 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;
+    unsigned releaseType : 3;
+    unsigned buildNo     : 13;
+};
+static_assert(sizeof(FwVersion) == 4);
+</code>
+===== FX3 Version Info =====
 The version id is also encoded into the firmware image file name as:
 <code><VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber></code>
-===== Vendor ID =====
-^Code ^Value ^
-|1|Cypress|
-===== Hardware ID =====
+|Code |Value |
-^Code ^Value ^
+^  Vendor ID  ^^
-|1|FX3|
+|1|Cypress|
+^  Hardware ID  ^^
-===== Product ID =====
+|1|FX3 Gen1|
-^Code ^Value ^
+^  Product ID  ^^
 |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"|
-===== Release type =====
+|6|Gen 5 camera, either "Square One" or "Studio"|
-^ Code ^ Name ^ Meaning ^
+^  Release type  ^^
-|0|Private build| Private build for debugging and similar purposes |
+|0|Private build: Private build for debugging and similar purposes |
-|1|Alpha| feature-incomplete early development cycle "somewhat stable" build |
+|1|Alpha: feature-incomplete early development cycle "somewhat stable" build |
-|2|Beta| feature-complete, but not very stable build (lots of bugs) |
+|2|Beta: feature-complete, but not very stable build (lots of bugs) |
-|3|Evaluation| Tech preview |
+|3|Evaluation: Tech preview |
-|4|Release candidate| feature complete and stable |
+|4|Release candidate: feature complete and stable |
-|5|Release| general availability |
+|5|Release: general availability |
-|6|Backport| backport of a feature from next gen camera |
+|6|Backport: backport of a feature from next gen camera |
-|7|Emergency bug fix| a critical post-release bugfix |
+|7|Emergency bug fix: a critical post-release bugfix |
+^  Build number  ^^
-===== Build number =====
-^Code ^Value ^
 |#|Increments on each build|
-====== FPGA Version Info ======
+===== 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 =====
-^Code ^Value ^
-|1|Xilinx|
-===== Hardware ID =====
+|Code |Value |
-^Code ^Value ^
+^  Vendor ID that represents a vendor of the main computation unit  ^^
-|1|Artix 100T|
+|1|Xilinx (AMD)|
-|2|Artix 200T|
+|2|Altera (Intel)|
+^  Hardware ID for %%VendorId%% 1 (Xylinx)  ^^
-===== Product ID =====
+|1|Artix-7 100T|
-^Code ^Value ^
+|2|Artix-7 200T|
+|3|Artix %%UltraScale+%% XCAU25P|
+^  Hardware ID for %%VendorId%% 2 (Altera)  ^^
+|1|Cyclone 10 GX|
+^  Product ID  ^^
 |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”|
-===== Release type =====
+|6|Gen 5 camera, prosumer grade "Square One"|
-^Code ^Value ^
+|7|Gen 5 camera, professional grade "Studio"|
+^  Release type  ^^
 |0|Private build|
 |1|Alpha|
@@ Line 343: / Line 622: @@
 |6|Backport|
 |7|Emergency bug fix|
+^  Build number  ^^
-===== Build number =====
+|#|''11'' bits of a build number (the range is ''1..2047''). Increments on each build|
-^Code ^Value ^
-|#|Increments on each build|