| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| code:fx3_fpga_api_spec_rex [2024/02/17 16:27] – 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). | |
| |
| FPGA registers' map is specified [[fpga_map_gen3_and_4|here]]. | |
| |
| %%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 ^ |
