| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| code:fx3_fpga_api_spec_rex [2023/09/01 14:45] – [0xA0-0xA7] Igor Yefmov | code:fx3_fpga_api_spec_rex [2024/02/18 02:03] (current) – [0xB2 - Color correction matrix (a.k.a. CCM or CMX)] Igor Yefmov |
|---|
| ====== Preface ====== | |
| This page describes FX3/FPGA API as they were up to the REX version of hardware (gen4). | |
| |
| %%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. | |
| |
| 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 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 setAUInterval(){ | |
| S2R::I2C fx3; | |
| fx3.open(0); | |
| fx3.vrCmd(S2R::FX3::af_au_period, S2R::FX3::write, 6000, 0); | |
| } | |
| |
| // run DPC calibration - also just a straight-up vendor request command to FX3 | |
| void runDPC(UCHAR _threshold = 240){ | |
| S2R::I2C fx3; | |
| fx3.open(0); | |
| fx3.vrCmd(S2R::FX3::calibrate_dpc, S2R::FX3::write, _threshold, 0); | |
| } | |
| |
| // increase LED's green brightness by 25% | |
| // utilize the FPGA's I²C bridge | |
| void lightUpTheGreen() | |
| { | |
| using Cmd = S2R::FX3::Fx3Cmd; | |
| using OpType = S2R::FX3::VrCmdOpType; | |
| |
| S2R::FX3 fx3; // `S2R::I2C fx3;` works as well | |
| fx3.open(0); | |
| uint8_t buf[1]{0}; | |
| const uint16_t clrChannel{0x0A}; // LED green | |
| fx3.vrCmd(Cmd::i2c_bridge, OpType::read, 0, clrChannel, buf, 1); | |
| buf[0] += buf[0] / 4; // yes, this can totally overflow | |
| fx3.vrCmd(Cmd::i2c_bridge, OpType::write, buf[0], clrChannel); | |
| } | |
| |
| |
| </code> | |
| |
| ---- | |
| |
| ====== FX3 API Reference ====== | ====== FX3 API Reference ====== |
| |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..255]| |
| |Reserved|''0xA3''| | | | | | | | |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 (registers' map)|FPGA I²C bridge]]| | |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_map_gen3_and_4|FPGA I²C bridge]]| |
| |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 | | |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 | |
| |Reserved for future I²C bridge |''0xA6''| | | | | | | | |Reserved for future I²C bridge |''0xA6''| | | | | | | |
| ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | ^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| | |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''|''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]]| | |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 [[code#fx3_version_info|FX3 Version Info]]| |
| |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 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 [[code#fpga_version_info|FPGA Version Info]]| |
| |FPGA config. ctrl.|''0xAD''| | |W/O| | |Any write to this location will put the FPGA into configuration mode| | |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''| see [[#FPGA config status - SPI codes|below]] for details |Retrieve detailed status of the FPGA configuration operation| | |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| |
| See [[isp:ccm|Color correction matrix]] article in this Wiki's ISP section for more details. | 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 ^ | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ |
| |Color correction matrix FIXME (needs actual implementation in FX3)|''0xB2''| ''0'' | ''0x0303'' |R/W|32|packed C-array ''float[3][3]''|That data buffer could also be defined as ''float[9]'' or as ''byte*'' for the same exact memory layout on LE systems| | |Color correction matrix|''0xB2''| ''0'' | ''0x0303'' |R/W|32|packed C-array ''float[3][3]''|That data buffer could also be defined as ''float[9]'' or as ''byte*'' for the same exact memory layout on LE systems\\ Implemented in v.115| |
| ===== 0xB3-0xB7 ===== | ===== 0xB3-0xB7 ===== |
| ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ |
| |
| |
| |
| ====== 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: | |
| <code c++>S2R::FX3 dev; // auto-open device #0 | |
| using S2R::FX3; | |
| dev.vrCmd(FX3Cmd::i2c_bridge, VrCmdOpType::write, 255, 0x08); // red | |
| dev.vrCmd(FX3Cmd::i2c_bridge, VrCmdOpType::write, 255, 0x0A); // green | |
| dev.vrCmd(FX3Cmd::i2c_bridge, VrCmdOpType::write, 0, 0x0C); // blue | |
| </code> | |
| |
| The address space is broken down into smaller chunks, grouped by common functionality: | |
| ===== 0x00-0x07 - FPGA general access ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |FPGA Version #0|''0x00''|R/O|''7:5'' Vendor ID\\ ''4:0'' HW_CFG_ID| | | |
| |FPGA Version #1|''0x01''|R/O|''7:0'' Product ID| | | |
| |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| | |
| |FPGA Version #3|''0x03''|R/O|''7:0'' Build number LSB|:::| | |
| |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 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| | |
| |FPGA control|''0x06''|R/W| |Global control of the FPGA's functionality| | |
| |:::|:::|:::|''7'' FPGA config enable|If bit ''7'' is set, the GPIF becomes read only and waits for an update bitstream| | |
| |:::|:::|:::|''6'' on-board fan| (FPGA-72+) ''1'' turns the on-board fan on, ''0'' turns it off | | |
| |:::|:::|:::|''5'' RAW Mode|Setting bit ''5'' and clearing bit ''0x06::2'' will enable RAW mode output (4K Only)| | |
| |:::|:::|:::|''4'' Video Format|Bit ''4'' selects between NV12 ('1') and YUY2 ('0') output formats | | |
| |:::|:::|:::|''3'' DPC enable|Setting bit ''3'' along with bit ''0x06::0'' will perform a DPC correction| | |
| |:::|:::|:::|''2'' <del>HSUB enable</del>|<del>Bit ''2'' is to enable/disable Horizontal Subsampling</del> **Deprecated**| | |
| |:::|:::|:::|''1'' Audio enable|Bit ''1'' is to enable/disable on-board microphones| | |
| |:::|:::|:::|''0'' Video enable|Bit ''0'' enables/disables video streaming| | |
| |FPGA core temperature|''0x07''| R/O | ''7:0'' - temperature in Farenheits | Reading of the FPGA's internal temperature sensor in degrees of Farenheits | | |
| |
| ===== 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 ===== | |
| |
| ^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 | | |
| |Brightness_H|''0x11''|R/W|''7:0'' MSB|:::| | |
| |Contrast_L|''0x12''|R/W|''7:0'' LSB|16 bits of contrast are split into 8 bits of LSB and MSB | | |
| |Contrast_H|''0x13''|R/W|''7:0'' MSB|:::| | |
| |Saturation_L|''0x14''|R/W|''7:0'' LSB|16 bits of saturation are split into 8 bits of LSB and MSB | | |
| |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''| | | | |
| |Reserved|''0x1D''| | | | |
| |Reserved|''0x1E''| | | | |
| |Reserved|''0x1F''| | | | |
| |
| ===== 0x20-0x27 - Defective pixel cancellation ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |DPC Threshold LSB|''0x20''|R/W|''7:0'' LSB| 16 bit of DPC Threshold are split into 8 bits of LSB and MSB| | |
| |DPC Threshold MSB|''0x21''|R/W|''7:0'' MSB|:::| | |
| |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|:::| | |
| |Grey threshold|''0x24''|R/W| ''7:0'' |If the full range of incoming \(R,G,B\) triplet is up to that number (inclusive), force both the \(H\) and \(S\) to be ''0'' | | |
| |Reserved|''0x25''| | | | |
| |Reserved|''0x26''| | | | |
| |Reserved|''0x27''| | | | |
| |
| ===== 0x28-0x3F - General image statistics ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |Y average|''0x28''|R/O|''7:0'' value| | |
| |flags|''0x29''|R/O|''7:0'' value|flags for %%OverExposure%% and SFP+ cage device. The following bits are currently defined:\\ ''7:3'' - reserved\\ ''2'' - set to ''1'' if there is an active device in SFP+ cage FIXME((move out of here into a separate register, dedicated to peripherals))\\ ''1'' - indicates whether a red overexposure is detected\\ ''0'' - set if there is a general overexposure detected| | |
| |FPS_L|''0x2B''|R/O|''7:0'' LSB|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| | |
| |FPS_H|''0x2C''|R/O|''7:0'' MSB|:::| | |
| |Reserved|''0x2D''| | | | |
| |AWB Y limit|''0x2E''|R/W|''7:0'' value|Lower bound brightness threshold for pixels to qualify for AWB statistic counter, default value ''100''| | |
| |AWB S limit|''0x2F''|R/W|''7:0'' value|Upper bound saturation threshold for pixels to qualify for AWB statistic counter, default value ''10''| | |
| |Reserved|''0x30''| | | | |
| |AWB Red total counter|''0x33-0x31''|R/O|24-bit value|''0x33'' is MSB, ''0x31'' is LSB| | |
| |Reserved|''0x34''| | | | |
| |AWB Green total counter|''0x37-0x35''|R/O|24-bit value|''0x37'' is MSB, ''0x35'' is LSB| | |
| |Reserved|''0x38''| | | | |
| |AWB Blue total counter|''0x3B-0x39''|R/O|24-bit value|''0x39'' is MSB, ''0x3B'' is LSB| | |
| |AWB total pixel counter|''0x3F-0x3C''|R/O|32-bit value|''0x3F'' is MSB, ''0x3C'' is LSB| | |
| |
| ===== 0x40-0x45 - AWB adjustments ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |AWB Red adjustment|''0x40''|R/W|''7:0'' - value|a signed 8-bit value of an adjustment to apply to every pixel in Red channel. Default is ''0''| | |
| |reserved|''0x41''| | | | | |
| |AWB Green adjustment|''0x42''|R/W|''7:0'' - value|a signed 8-bit value of an adjustment to apply to every pixel in Green channel. Default is ''0''| | |
| |reserved|''0x43''| | | | | |
| |AWB Blue adjustment|''0x44''|R/W|''7:0'' - value|a signed 8-bit value of an adjustment to apply to every pixel in Blue channel. Default is ''0''| | |
| |reserved|''0x45''| | | | | |
| |
| ===== 0x46-0x4F - Media setup ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |Media output modules|''0x46''|R/W|''7'' - res\\ ''6'' - res (headphones)\\ ''5'' - res (UAC)\\ ''4'' - res\\ ''3'' - res\\ ''2'' - SDI video\\ ''1'' - SFP+ video\\ ''0'' - UVC|Enable/disable state of individual media output modules for video and audio streams| | |
| |Video transform blocks|''0x47''|R/W|''7'' - res (sharpness)\\ ''6'' - res\\ ''5'' - res\\ ''4'' - res\\ ''3'' - res\\ ''2'' - HSL pipeline\\ ''1'' - CCM\\ ''0'' - res (UVC Gamma)|Enable/disable individual transformation blocks in video pipeline| | |
| |Video output format|''0x48''|R/W|''7:4'' - UVC\\ ''3:0'' - SDI FPS|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 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| | |
| |Video output pixel bit depth|''0x49''|R/W|''7:6'' - res\\ ''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| | |
| |MIPI configuration|''0x4A''|R/W|''7:4'' - res\\ ''3:2'' - de-mosaicing strategy\\ ''1:0'' - MIPI bit depth|**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]]\\ **MIPI bit depth** controls the data packing format for the pixels coming through MIPI interface. MIPI bit depth \(d_p\) is calculated from a 2-bit value \(N\) as: \[d_p = (N+4)*2\]| | |
| |Reserved|''0x4B''| | | | | |
| |Audio transform blocks|''0x4C''|R/W|''7:0'' - res|Enable/disable individual transformation blocks in audio pipeline| | |
| |Reserved|''0x4D''| | | | | |
| |Reserved|''0x4E''| | | | | |
| |Reserved|''0x4F''| | | | | |
| |
| ==== FOURCC formats (for UVC) ==== | |
| A combination of data in ''0x49[1:0]'' (pixel bit depth) and ''0x48[6:3]'' (video format) used for UVC is mapped into standard FOURCC codes as summarized in the following table: | |
| ^''0x49[1:0]''\''0x48[6:3]'' ^''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 st in ''0x48[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 | | |
| |
| ===== 0x50-0x5F - Reserved ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |Reserved|''0x50''-''0x5F''| | | | | |
| |
| ===== 0x60-0x6F - Reserved ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |Reserved|''0x60''-''0x6F''| | | | | |
| |
| ===== 0x70-0x7F - Reserved ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |Reserved|''0x70''-''0x7F''| | | | | |
| |
| |
| ===== 0x80-0xBF - 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 ==== | |
| If enabled these setting take precedence over other 3 bands | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |CK control|''0x80''|R/W|''7:1'' reserved\\ ''0'' enable|enable/disable Chroma Key control| | |
| |CK status|''0x81''| |reserved| | | |
| |CK saturation min|''0x82''|R/W|''7:0'' sat. min|[0..255] to specify the minimum saturation threshold| | |
| |CK saturation max|''0x83''|R/W|''7:0'' sat. max|[0..255] to specify the maximum saturation threshold| | |
| |CK luma min|''0x84''|R/W|''7:0'' luma min|[0..255] to specify the minimum brightness threshold| | |
| |CK luma max|''0x85''|R/W|''7:0'' luma max|[0..255] to specify the maximum brightness threshold| | |
| |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 hue MSB|''0x87''|R/W|''7:6'' reserved\\ ''5:0'' hue MSB|:::| | |
| |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 tolerance MSB|''0x89''|R/W|''7:5'' reserved\\ ''4:0'' tolerance MSB|:::| | |
| |CK red LSB|''0x8A''|R/W|''7:0'' red LSB| | | |
| |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 ==== | |
| 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'' | |
| |
| ==== 0xA0-0xAF - 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'' | |
| |
| ==== 0xB0-0xBF - 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 ^ | |
| |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'' page|Reserved for a page number in the table, currently is always set to ''0''| | |
| |:::|:::|:::|''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| index into a page in the 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\\ - (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| | |
| |Value H|''0xC3''|R/W|''7:0'' MSB|:::| | |
| |Reserved|''0xC4''-''0xCF''| | | | |
| |
| |
| ===== 0xD0-0xE1 - 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). | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |CCM_00_L|''0xD0''|R/W|''7:0'' LSB|\(CCM_{00}\)| | |
| |CCM_00_H|''0xD1''|R/W|''7:0'' MSB|:::| | |
| |CCM_01_L|''0xD2''|R/W|''7:0'' LSB|\(CCM_{01}\)| | |
| |CCM_01_H|''0xD3''|R/W|''7:0'' MSB|:::| | |
| |CCM_02_L|''0xD4''|R/W|''7:0'' LSB|\(CCM_{02}\)| | |
| |CCM_02_H|''0xD5''|R/W|''7:0'' MSB|:::| | |
| |CCM_10_L|''0xD6''|R/W|''7:0'' LSB|\(CCM_{10}\)| | |
| |CCM_10_H|''0xD7''|R/W|''7:0'' MSB|:::| | |
| |CCM_11_L|''0xD8''|R/W|''7:0'' LSB|\(CCM_{11}\)| | |
| |CCM_11_H|''0xD9''|R/W|''7:0'' MSB|:::| | |
| |CCM_12_L|''0xDA''|R/W|''7:0'' LSB|\(CCM_{12}\)| | |
| |CCM_12_H|''0xDB''|R/W|''7:0'' MSB|:::| | |
| |CCM_20_L|''0xDC''|R/W|''7:0'' LSB|\(CCM_{20}\)| | |
| |CCM_20_H|''0xDD''|R/W|''7:0'' MSB|:::| | |
| |CCM_21_L|''0xDE''|R/W|''7:0'' LSB|\(CCM_{21}\)| | |
| |CCM_21_H|''0xDF''|R/W|''7:0'' MSB|:::| | |
| |CCM_22_L|''0xE0''|R/W|''7:0'' LSB|\(CCM_{22}\)| | |
| |CCM_22_H|''0xE1''|R/W|''7:0'' MSB|:::| | |
| |
| |
| ===== 0xE2-0xEF ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |Reserved|''0xE2''| | | | | |
| |Reserved|''0xE3''| | | | | |
| |Reserved|''0xE4''| | | | | |
| |Reserved|''0xE5''| | | | | |
| |Reserved|''0xE6''| | | | | |
| |Reserved|''0xE7''| | | | | |
| |Reserved|''0xE8''| | | | | |
| |Reserved|''0xE9''| | | | | |
| |Reserved|''0xEA''| | | | | |
| |Reserved|''0xEB''| | | | | |
| |Reserved|''0xEC''| | | | | |
| |Reserved|''0xED''| | | | | |
| |Reserved|''0xEE''| | | | | |
| |Reserved|''0xEF''| | | | | |
| |
| ===== 0xF0-0xFF ===== | |
| ^Name ^Offset ^Access ^Bit mapping ^Notes ^ | |
| |Reserved|''0xF0''| | | | | |
| |Reserved|''0xF1''| | | | | |
| |Reserved|''0xF2''| | | | | |
| |Reserved|''0xF3''| | | | | |
| |Reserved|''0xF4''| | | | | |
| |Reserved|''0xF5''| | | | | |
| |Reserved|''0xF6''| | | | | |
| |Reserved|''0xF7''| | | | | |
| |Reserved|''0xF8''| | | | | |
| |Reserved|''0xF9''| | | | | |
| |Reserved|''0xFA''| | | | | |
| |Reserved|''0xFB''| | | | | |
| |Reserved|''0xFC''| | | | | |
| |Reserved|''0xFD''| | | | | |
| |Reserved|''0xFE''| | | | | |
| |Reserved|''0xFF''| | | | | |
| |
| ====== 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| | |
| |
| |
