'''E. [wiki:GraspSw Controller Address Space and Clocking Instructions]'''

[[TracNav(GraspContents)]]

This is a very low level API, used only by someone writing a newer
controller socket level command.  All controller socket level
commands are implemented in C code (downloaded as the stage2.srec
to the controller) which modifies registers or address space, and/or
writes instructions to the clocking engine.

Our FPGA [wiki:V2P20Phase0HWSWInterface Memory Map] includes [wiki:V2P20GPIO General Purpose I/O (GPIOs)] that
allow access to:

 * Board ID Register Bits
 * Board I2C Register Bits
 * ADC SPI Configuration Register Interface
 * Clocking Engine Register Interface

== Board ID Bits ==

The first generation of STARGRASP controller fpga boards contain a 2 bits in a GPIO register which indicate which slot of a 4 slot chassis the board is in, and 3 more bits which are programmable as a "chassis ID" to differentiate the chassis when used in a mosaic camera or on a network with multiple development systems e.g. in a lab.

The current generation of STARGRASP uses more flexible I2C parts so that we can ID each board and store more information than just the chassis number.

== Board I2C Bits ==

(More info needed on all of the things accessible by I2C here.)

== ADC SPI Configuration Register ==

(More information on the ADC needed here.)

== Clocking Engine ==

The "Clocking Engine" is an fpga-hardware pattern generator which we developed specifically for controlling clock lines to read a detector.  It consists of one 3-bit pattern generator we call "PG3" and two 4-bit pattern generators we call "PG4s".  Each bit in the PG can control one detector clock line signal.

Todo: Incorporate the wiki pages above into GraspContents.

Related info:

 * [wiki:GraspSwControllerCmdClvset Controller command "clvset"] passes bit patterns and ADC configuration to controller
 * [wiki:ClockMath Clocking Engine Math Module]
 * [wiki:VIDSEQ_bit_packing Clocking Engine pattern generator bit packing]
 * Clocking engine block diagram attached below.

[[Image(clocking_engine.gif)]]

=== Polled Readout Mode ===

The basic order of operations for embedded C code to perform a readout
in '''polled mode''' is:

1. Write CONTROL REGS to set up any data processing that will be required.  For example, will 4 16-bit ADC samples need to be averaged into one value during the readout?

2. Write CONTROL REGS with the buffer locations and sizes where 16-bit video pixels will go.  An even number of pixels must be requested, on a 32-bit aligned address within the "OCM" memory space.  OCM is a few kilobytes of fast, shared memory which the clocking engine HDL hardware and the PowerPC can both access.

3. Check STATUS REGS and wait until there is room for instructions in the clocking engine's input register.

4. Fill FIFO INPUT with 16-bit instructions words which:

 * Set DAC voltages
 * Insert delay times
 * Wait for and synchronize with other clocking engines
 * Control digital I/O lines (OTA CCD cell selects.)
 * Produce Parallel clocking patterns to shift charge
 * Shift the Serial register and general video samples

These instructions are executed serially, in the order written. The FIFO INPUT must not be written when the STATUS REGS indicate that the FIFO is full.

5. Check STATUS REGS to see if enough video samples have been produced to fill one of the requested OCM buffers.  If not, go to step 3.

6. Copy pixel data out of OCM into DRAM or transfer it directly over the Ethernet link to the Pixel server.  If requested, the embedded C code may also perform pedestal subtraction or other "software math engine" functions.  Go to step 2.

=== Error Conditions ===

'''Stalled''' conditions occur when the FIFO INPUT is not filled with a new instruction in time for seamless back-to-back execution with the previous instruction.  Detector readouts will still complete, but the readout timing may be irregular.

'''Overrun''' conditions occur when 16-bit video samples are produced as a result of a SERIAL instruction but no (more) OCM memory locations have been defined.  When they have nowhere to go, they are dropped and the readout function will report missing pixels.

=== Interrupt Driven Mode ===

To reduce the errors above, a new mode of operation triggered by interrupts rather than polling improves the reliability of the system.  Interrupts can be used in place of the polling checks in steps 3. and 5. above.

Step 3 checked for available space in FIFO INPUT for new instructions that drive clocking.  This FIFO is 512 instructions deep, so one possible implementation would have hardware assert an interrupt whenever the FIFO was at least half empty.  In this case, the interrupt routine could safely write up to 256 new instructions whenever the interrupt triggers.  Making the FIFO INPUT interrupt driven is less of a priority because a '''Stalled''' condition only causes a warning and is rare because the FIFO is relatively deep.

Step 5 checks to see if one of the two requested OCM buffers has been completely written and can be memcpy()'d to DRAM and re-used.  An interrupt which triggers whenever one of these buffers is ready (i.e., one which is asserted as long as BUFRDY bit in STATUS REGS is high) would allow faster response time for the memory copy than the polling method, thus avoiding the '''overrun''' errors which occur sporadically in polled mode especially when the stage2 embedded C code is off servicing the network (e.g. logging, DHCP, or answering an asynchronous request for something from a pixel server.)
These type of operations would get interrupted rather than needing to complete before the next polling cycle.

In addition to making the current readout modes more reliable in the face of random, unpredictable network events, interrupts should also allow a higher level of performance (faster pixel rates) from the STARGRASP because the interrupt routine requires less overhead than polling constantly.