User Tools

Site Tools


code:fx3_hvci_and_fpga_i_c_commands

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.

On Windows the device is registered with a GUID {36FC9E60-C465-11CF-8056-444553540000} and if you are not planning on using the SUB2r-lib for your development - that would be the GUID to search for to properly connect to the command channel.

Whether you use SUB2r-lib or not you need to install the 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 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 :)

// 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);
}

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

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Reserved0x00-0x9F Think of this as “system address space”

0xA0-0xA7

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Bootloader check0xA0 R/W Check if a bootloader is running, the result is in the command's status code (success/failure interpreted as true/false)
MS OS Descr.0xA1bits 3:0 - see notes R/O174MS OS Platform DescriptorFor details on the structure and valid parameters' values refer to Microsoft's documentation for 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 calibration0xA2 DPC ThresholdW/O Start the dynamic DPC calibration with the given DPC Threshold in range [0..255]
Reserved0xA3
FPGA I²C Bridge0xA4FPGA register offsetFPGA data (write)R/W0 or 17:0 - FPGA dataFPGA 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
Sensor I²C bridge (8-bit configuration registers)0xA5 bit [15] - sensor I²C bus address bits[14:0] - sensor register address mask and data (if writing) - see Notes column for details R/W0 or 1 7:0 - sensor register's data bus - 0 means 0x20 and 1 means 0x6c
register - a 15 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
RAW Mode Select0xA7 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

0xA8-0xA9 - sysinfo

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Sysinfo0xA8data structure version (currently only 1 is supported) bitmask of additional checks to perform:
0 - check memory integrity
1 - check DMA integrity
2-7: reserved
R/OV1: 30 Supported features (byte #5)
0 - USB3
1 - OTG (USB 2.0 host mode)
2 - 512KB RAM
3 - I2S
4 - GPIF (under 32bits)
5 - GPIF32
Configured features (byte #6)
0 - I²C
1 - I2S
2 - UART
3 - SPI
4 - PIB on/off
5 - DLL status
6 - LPP on/off
Get various internal system info on the guts of the RTOS and the firmware running on FX3. Returned bytes:
Version 1 (FX3 #52):
0 - uint32_t: system uptime in ms ticks
4 - uint8_t: Cypress part number
5 - uint8_t: supported features
6 - uint8_t: configured features
7 - uint8_t: USB speed (0, 1, 2, 3 for: disconnected, FS, HS, SS)
8 - uint32_t: memory alloc() count
12 - uint32_t: memory free() count
16 - uint32_t: DMA alloc() count
20 - uint32_t: DMA free() count
24 - uint16_t: PHY error count
26 - uint16_t: LINK error count
28 - uint8_t: status of memory corruption check
29 - uint8_t: status of DMA corruption check
Reserved0xA9

0xAA-0xAF - versioning and reprogramming

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Erase SPI Flash0xAA 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 version0xAB R/O431: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
FPGA version0xAC R/O431: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
FPGA config. status - SPI codes0xAE R/O2 see below for details Retrieve detailed status of the FPGA configuration operation
SPI Flash write enable0xAF W/O Reconfigure the FX3 IOMatrix to disable GPIF and enable SPI to be re-written

FPGA config status - SPI codes

Bit name Description
15 Program SwitchWord OK
14 Verify OK Verification succeeded
13 Program OK Programming completed successfully
12 Erase OK SPI erase was successful
11 Erase SwitchWord OK
10 Check ID OK
9 Initialize OK
8 Config started Config operation has started
7 CRC error
6 Timeout error
5 Program error Error while programming the SPI
4 Erase error Encountered an error while erasing SPI
3 IdCode error
2 Config error Configuration operation errored out
1 Config done Configuration operation is complete
0 Config not busySet to 1 while the config is not busy

0xB0 - FPS control

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
FPS0xB0 R/W4float32 FPSFPS value is in IEEE float32 format, x86 LE and is exchanged in data phase of the USB control request (both IN and OUT)

0xB1 - Bulk color grading

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Bulk color grading0xB17:4 - table
3:0 - starting index
7:4 - version
4:0 - count
R/Wcount x 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)1)
100 - Lightness vs. Lightness (12 bits)
101 - Hue vs. Lightness (12 bits)2)
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)

0xB2 - Color correction matrix (a.k.a. CCM or CMX)

See 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
Color correction matrix0xB2 R/W32packed C-array int16_t[4][4]That data buffer could also be defined as int16_t[16] or as byte* for the same exact memory layout on LE systems

0xB3-0xBF

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Reserved0xB3
Reserved0xB4
Reserved0xB5
Reserved0xB6
Reserved0xB7
Reserved0xB8
Reserved0xB9
Reserved0xBA
Reserved0xBB
Reserved0xBC
Reserved0xBD
Reserved0xBE
Reserved0xBF

0xC0-0xC1

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Reserved0xC0
Reserved0xC1

0xC2-0xC4 - SPI flash management

The SPI flash memory (either 128MB or 256MB) is partitioned into 65KB 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 flash write page0xC216:0 page address W/O256 write a page of SPI flash (same command as Cypress' examples). The flash page size is fixed to 256 bytes
SPI flash read page0xC316:0 page address R/O256page's contentread a page of SPI flash (same command as Cypress' examples). The flash page size is fixed to 256 bytes
SPI flash sector erase/poll0xC47:0 - sector0 - 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.

0xC5-0xCB

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Reserved0xC5
Reserved0xC6
Reserved0xC7
Reserved0xC8
Reserved0xC9
Reserved0xCA
Reserved0xCB

0xCC - FPGA temperature sensor

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
FPGA core temperature0xCC R/O FPGA temperature read from the on-board sensor (not implemented yet)

0xCD-0xCF

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Reserved0xCD
Reserved0xCE
Reserved0xCF

0xD0-0xD7 - Auto exposure configuration

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
AE Setpoint0xD0 AE SetpointR/W0 or 1 7:0 AE SetpointTarget 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
deprecated AE Hysteresis0xD1 AE HysteresisR/W0 or 2 15:0 AE HysteresisAuto Exposure Hysteresis Value 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
deprecated AE Error Tolerance0xD2 AE Err TolR/W0 or 2 15:0 AE Err TolAuto Exposure Error Tolerance Value 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
deprecated AE Exposure Scaling0xD3 AE Exp ScaleR/W0 or 2 15:0 AE Exp ScaleAuto Exposure Exposure Scaling Value 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
deprecated AE C Gain Divisor0xD4 AE C Gain DivisorR/W0 or 2 15:0 AE C Gain DivisorAuto Exposure C Gain Divisor Value 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)
Reserved0xD5
Reserved0xD6
Reserved0xD7

0xD8-0xDE - Auto white balance configuration

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
AWB Setpoint0xD8 AWB SetpointR/W0 or 2 15:0 AWB SetpointAuto 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
deprecated AWB Hysteresis0xD9 AWB HysteresisR/W0 or 2 15:0 AWB HysteresisAuto White Balance Hysteresis Value UFIX 8.8
Default 3.0
How far can the error drift before we start adjusting it
deprecated AWB Error Tolerance0xDA AWB Err TolR/W0 or 2 15:0 AWB Err TolAuto White Balance Error Tolerance Value 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
deprecated AWB Adjustment Scaling0xDB AWB Adj ScaleR/W0 or 2 15:0 AWB Adj ScaleAuto White Balance Adjustment Scaling Value 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)
Reserved0xDC
Reserved0xDD
Reserved0xDE

0xDF - Auto-functions' timing

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Auto Update Period0xDF Auto Update PeriodR/W0 or 2 15:0 Auto Update PeriodAuto 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

0xE0 - FX3 reset

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
FX3 reset0xE0 W/O Cypress vendor command to soft reset FX3

0xE1-0xEF

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Reserved0xE1
Reserved0xE2
Reserved0xE3
Reserved0xE4
Reserved0xE5
Reserved0xE6
Reserved0xE7
Reserved0xE8
Reserved0xE9
Reserved0xEA
Reserved0xEB
Reserved0xEC
Reserved0xED
Reserved0xEE
Reserved0xEF

0xF0-0xF9

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Reserved0xF0
Reserved0xF1
Reserved0xF2
Reserved0xF3
Reserved0xF4
Reserved0xF5
Reserved0xF6
Reserved0xF7
Reserved0xF8
Reserved0xF9

0xFA - [Debug] Get raw descriptor

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Get raw descriptor0xFAcommand (see below)struct to returnR/Ovaries by command (see below)struct's byte bufferSee below for details

List of commands supported by this API:

Cmd (wIndex) Meaning
0get a 2-byte descriptive text label's length (not including the C-style null-terminator)
1get descriptive text label (up to 4096 bytes without a C-style null-terminator)
2get a 2-byte size of the structure in bytes
3get structure's byte buffer

As of FX3 version 58 the following internal structures are supported:

Index (wValue) Details
0reserved (unused)
1USB device descriptor 2.0
2USB device descriptor 3.0
3USB Device Qualifier descriptor
4USB BOS (Binary Object Store) descriptor
5Full-Speed (2.0) USB Configuration descriptor
6High-Speed (2.0) USB Configuration descriptor
7Super-Speed (3.0) USB Configuration descriptor
8MS OS Platform Capability descriptor version 2.0

0xFB - Get internal state

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Get internal state0xFBcommand:
0 - reserved
1 - get the struct
version:
0..58 - reserved
59 - FX3 v.59
RO84
CachedGlobalState
see CachedGlobalStatus_v0x01 for the definition

0xFC-0xFF - Reserved for debug APIs

Name Offset wIndex wValue Access type Byte length Return buffer bits Notes
Reserved0xFC
Reserved0xFD
Reserved0xFE
Reserved0xFF

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:

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

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 #00x00R/O7:5 Vendor ID
4:0 HW_CFG_ID
FPGA Version #10x01R/O7:0 Product ID
FPGA Version #20x02R/O7: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 #30x03R/O7:0 Build number LSB
FPGA config status #00x04R/Osee SPI codes for detailsLSB (bits 7-0) of the FPGA config status
FPGA config status #10x05R/Osee SPI codes for detailsMSB (bits 15-8) of the FPGA config status
FPGA control0x06R/W Global control of the FPGA's functionality
7 FPGA config enableIf 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 ModeSetting bit 5 and clearing bit 0x06::2 will enable RAW mode output (4K Only)
4 Video FormatBit 4 selects between NV12 ('1') and YUY2 ('0') output formats
3 DPC enableSetting bit 3 along with bit 0x06::0 will perform a DPC correction
2 HSUB enableBit 2 is to enable/disable Horizontal Subsampling Deprecated
1 Audio enableBit 1 is to enable/disable on-board microphones
0 Video enableBit 0 enables/disables video streaming
FPGA core temperature0x07 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_L0x08R/W7:0 Red LEDLSB of LED's red intensity in range [0..255]
LED_RED_H0x09R/WReserved
LED_GREEN_L0x0AR/W7:0 Green LEDLSB of LED's green intensity in range [0..255]
LED_GREEN_H0x0BR/WReserved
LED_BLUE_L0x0CR/W7:0 Blue LEDLSB of LED's blue intensity in range [0..255]
LED_BLUE_H0x0DR/WReserved

0x0E-0x0F - Noise Reduction

Name Offset Access Bit mapping Notes
Chroma NR Control0x0ER/W7 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 Control0x0FR/W7 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_L0x10R/W7:0 LSB16 bits of brightness are split into 8 bits of LSB and MSB
Brightness_H0x11R/W7:0 MSB
Contrast_L0x12R/W7:0 LSB16 bits of contrast are split into 8 bits of LSB and MSB
Contrast_H0x13R/W7:0 MSB
Saturation_L0x14R/W7:0 LSB16 bits of saturation are split into 8 bits of LSB and MSB
Saturation_H0x15R/W7:0 MSB
Sharpness_L0x16R/W7:0 LSB16 bits of sharpness are split into 8 bits of LSB and MSB
Sharpness_H0x17R/W7:0 MSB
Gamma_L0x18R/W7:0 LSB16 bits of gamma are split into 8 bits of LSB and MSB
Gamma_H0x19R/W7:0 MSB
Hue_L0x1AR/W7:0 LSB16 bits of hue are split into 8 bits of LSB and MSB
Hue_H0x1BR/W7:0 MSB
Reserved0x1C
Reserved0x1D
Reserved0x1E
Reserved0x1F

0x20-0x27 - Defective pixel cancellation

Name Offset Access Bit mapping Notes
DPC Threshold LSB0x20R/W7:0 LSB 16 bit of DPC Threshold are split into 8 bits of LSB and MSB
DPC Threshold MSB0x21R/W7:0 MSB
DPC count LSB0x22R/O7:0 LSBOnce the DPC calibration is done the 16-bit value is stored in these 2 registers
DPC count MSB0x23R/O7:0 MSB
Grey threshold0x24R/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
Reserved0x25
Reserved0x26
Reserved0x27

0x28-0x3F - General image statistics

Name Offset Access Bit mapping Notes
Y average0x28R/O7:0 value
flags0x29R/O7:0 valueflags 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 FIXME3)
1 - indicates whether a red overexposure is detected
0 - set if there is a general overexposure detected
Reserved0x2B
Reserved0x2C
Reserved0x2D
AWB Y limit0x2ER/W7:0 valueLower bound brightness threshold for pixels to qualify for AWB statistic counter, default value 100
AWB S limit0x2FR/W7:0 valueUpper bound saturation threshold for pixels to qualify for AWB statistic counter, default value 10
Reserved0x30
AWB Red total counter0x33-0x31R/O24-bit value0x33 is MSB, 0x31 is LSB
Reserved0x34
AWB Green total counter0x37-0x35R/O24-bit value0x37 is MSB, 0x35 is LSB
Reserved0x38
AWB Blue total counter0x3B-0x39R/O24-bit value0x39 is MSB, 0x3B is LSB
AWB total pixel counter0x3F-0x3CR/O32-bit value0x3F is MSB, 0x3C is LSB

0x40-0x45 - AWB adjustments

Name Offset Access Bit mapping Notes
AWB Red adjustment0x40R/W7:0 - valuea signed 8-bit value of an adjustment to apply to every pixel in Red channel. Default is 0
reserved0x41
AWB Green adjustment0x42R/W7:0 - valuea signed 8-bit value of an adjustment to apply to every pixel in Green channel. Default is 0
reserved0x43
AWB Blue adjustment0x44R/W7:0 - valuea signed 8-bit value of an adjustment to apply to every pixel in Blue channel. Default is 0
reserved0x45

0x46-0x4F - Reserved

Name Offset Access Bit mapping Notes
Reserved0x46-0x4F

0x50-0x5F - Reserved

Name Offset Access Bit mapping Notes
Reserved0x50-0x5F

0x60-0x6F - Reserved

Name Offset Access Bit mapping Notes
Reserved0x60-0x6F

0x70-0x7F - Reserved

Name Offset Access Bit mapping Notes
Reserved0x70-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 control0x80R/W7:1 reserved
0 enable
enable/disable Chroma Key control
CK status0x81 reserved
CK saturation min0x82R/W7:0 sat. min[0..255] to specify the minimum saturation threshold
CK saturation max0x83R/W7:0 sat. max[0..255] to specify the maximum saturation threshold
CK luma min0x84R/W7:0 luma min[0..255] to specify the minimum brightness threshold
CK luma max0x85R/W7:0 luma max[0..255] to specify the maximum brightness threshold
CK hue LSB0x86R/W7:0 hue LSB14 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 MSB0x87R/W7:6 reserved
5:0 hue MSB
CK tolerance LSB0x88R/W7:0 tolerance LSB13 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 MSB0x89R/W7:5 reserved
4:0 tolerance MSB
CK red LSB0x8AR/W7:0 red LSB
CK red MSB0x8BR/Wreserved
CK green LSB0x8CR/W7:0 green LSB
CK green MSB0x8DR/Wreserved
CK blue LSB0x8ER/W7:0 blue LSB
CK blue MSB0x8FR/Wreserved

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
switch0xC0W Controls what information is being read/written by accessing the next set of registers (0xC2..0xC3)
7:5 table switch000 - Hue vs. Hue (14 bits)
001 - Hue vs. Saturation (12 bits)
010 - Lightness vs. Saturation (12 bits)
011 - Saturation vs. Saturation (12 bits)4)
100 - Lightness vs. Lightness (12 bits)
101 - Hue vs. Lightness (12 bits)5)
110-111 - reserved
4:1 pageReserved 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 LSB0xC1W7:0 index LSB index into a page in the table (we only use 6 bits today and the rest are ignored)
Value L0xC2R/W7: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 H0xC3R/W7:0 MSB
Reserved0xC4-0xCF

0xD0-0xE1 - Color Correction Matrix (a.k.a. CCM or CMX)

See Color correction matrix article in this Wiki's ISP section for more details.

Name Offset Access Bit mapping Notes
CCM_00_L0xD0R/W7:0 LSB\(CCM_{00}\)
CCM_00_H0xD1R/W7:0 MSB
CCM_01_L0xD2R/W7:0 LSB\(CCM_{01}\)
CCM_01_H0xD3R/W7:0 MSB
CCM_02_L0xD4R/W7:0 LSB\(CCM_{02}\)
CCM_02_H0xD5R/W7:0 MSB
CCM_10_L0xD6R/W7:0 LSB\(CCM_{10}\)
CCM_10_H0xD7R/W7:0 MSB
CCM_11_L0xD8R/W7:0 LSB\(CCM_{11}\)
CCM_11_H0xD9R/W7:0 MSB
CCM_12_L0xDAR/W7:0 LSB\(CCM_{12}\)
CCM_12_H0xDBR/W7:0 MSB
CCM_20_L0xDCR/W7:0 LSB\(CCM_{20}\)
CCM_20_H0xDDR/W7:0 MSB
CCM_21_L0xDER/W7:0 LSB\(CCM_{21}\)
CCM_21_H0xDFR/W7:0 MSB
CCM_22_L0xE0R/W7:0 LSB\(CCM_{22}\)
CCM_22_H0xE1R/W7:0 MSB

0xE2-0xEF

Name Offset Access Bit mapping Notes
Reserved0xE2
Reserved0xE3
Reserved0xE4
Reserved0xE5
Reserved0xE6
Reserved0xE7
Reserved0xE8
Reserved0xE9
Reserved0xEA
Reserved0xEB
Reserved0xEC
Reserved0xED
Reserved0xEE
Reserved0xEF

0xF0-0xFF

Name Offset Access Bit mapping Notes
Reserved0xF0
Reserved0xF1
Reserved0xF2
Reserved0xF3
Reserved0xF4
Reserved0xF5
Reserved0xF6
Reserved0xF7
Reserved0xF8
Reserved0xF9
Reserved0xFA
Reserved0xFB
Reserved0xFC
Reserved0xFD
Reserved0xFE
Reserved0xFF

FX3 Version Info

The version id is also encoded into the firmware image file name as:

<VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber>

Vendor ID

Code Value
1Cypress

Hardware ID

Code Value
1FX3

Product ID

Code Value
1reserved for Gen 1 camera, a.k.a. “Moon landing”
2reserved for Gen 2 camera, a.k.a. “Piggy”
3Gen 3 camera (Alpha), a.k.a. “Frankie” (from Frankenstein's Monster)
4Gen 3 camera, Production

Release type

Code Name Meaning
0Private build Private build for debugging and similar purposes
1Alpha feature-incomplete early development cycle “somewhat stable” build
2Beta feature-complete, but not very stable build (lots of bugs)
3Evaluation Tech preview
4Release candidate feature complete and stable
5Release general availability
6Backport backport of a feature from next gen camera
7Emergency 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:

<VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber>

Vendor ID

Code Value
1Xilinx

Hardware ID

Code Value
1Artix 100T
2Artix 200T

Product ID

Code Value
1reserved
2reserved
3Gen 3 camera (Alpha), a.k.a. “Frankie”
4Gen 3 camera, Production

Release type

Code Value
0Private build
1Alpha
2Beta
3Eval/Tech preview
4Release candidate
5Release
6Backport
7Emergency bug fix

Build number

Code Value
#Increments on each build
1) , 2) , 4) , 5)
scheduled for later
3)
move out of here into a separate register, dedicated to peripherals
/home/adminsub2r/public_html/dokuwiki/data/pages/code/fx3_hvci_and_fpga_i_c_commands.txt · Last modified: 2021/09/03 02:54 by Igor Yefmov