Arnaud VALLEY / Mbed 2 deprecated Pinscape_Controller_V2_arnoz

Mirror with some correction

Dependencies:   mbed FastIO FastPWM USBDevice

TSL14xx/TSL14xx.h@101:755f44622abc, 2019-11-29 (annotated)

Committer:
mjr
Date:
Fri Nov 29 05:38:07 2019 +0000
Revision:
101:755f44622abc
Parent:
100:1ff35c07217c
Child:
104:6e06e0f4b476
Use continuous asynchronous frame transfers in image sensors

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mjr 82:4f6209cb5c33 1 /*
mjr 82:4f6209cb5c33 2 * AMS/TAOS TSL14xx series photodiode array interface class.
mjr 82:4f6209cb5c33 3 *
mjr 82:4f6209cb5c33 4 * This provides a high-level interface for the AMS/TAOS TSLxx series
mjr 82:4f6209cb5c33 5 * of photodiode arrays. This class works with most of the sensors
mjr 82:4f6209cb5c33 6 * in this series, which differ only in pixel array sizes. This code
mjr 82:4f6209cb5c33 7 * has been tested with the following sensors from the series:
mjr 82:4f6209cb5c33 8 *
mjr 82:4f6209cb5c33 9 * TSL1410R - 1280 pixels, 400dpi
mjr 82:4f6209cb5c33 10 * TSL1412S - 1536 pixels, 400dpi
mjr 82:4f6209cb5c33 11 * TSL1401CL - 128 pixels, 400dpi
mjr 82:4f6209cb5c33 12 *
mjr 82:4f6209cb5c33 13 * All of these sensors have the same electrical interface, consisting
mjr 82:4f6209cb5c33 14 * of a clock input (CLK), start pulse input (SI), and analog pixel
mjr 82:4f6209cb5c33 15 * output (AO). The sensors are equipped with hold capacitors and
mjr 82:4f6209cb5c33 16 * shift registers that allow simultaneous sampling of all pixels, and
mjr 82:4f6209cb5c33 17 * serial access to the pixel values.
mjr 82:4f6209cb5c33 18 *
mjr 82:4f6209cb5c33 19 * (Note on the plunger sensor class hierarchy: this class is for the
mjr 82:4f6209cb5c33 20 * sensor only, not for the plunger application. This class is meant
mjr 82:4f6209cb5c33 21 * to be reusable in other contexts that just need to read raw pixel
mjr 82:4f6209cb5c33 22 * data from the sensor. Plunger/tslxxSensor.h implements the next
mjr 82:4f6209cb5c33 23 * level up, which is the implementation of the generic plunger sensor
mjr 82:4f6209cb5c33 24 * interface for TSL14xx sensors. That's still an abstract class, since
mjr 82:4f6209cb5c33 25 * it only provides the plunger class specialization for these sensor
mjr 82:4f6209cb5c33 26 * types, without any image analysis component. The final concrete
mjr 82:4f6209cb5c33 27 * classes are in Plunger/edgeSensor.h and Plunger/barCodeSensor.h,
mjr 82:4f6209cb5c33 28 * which add the image processing that analyzes the image data to
mjr 82:4f6209cb5c33 29 * determine the plunger position.)
mjr 82:4f6209cb5c33 30 *
mjr 101:755f44622abc 31 * *** Double buffering ***
mjr 101:755f44622abc 32 *
mjr 82:4f6209cb5c33 33 * Our API is based on a double-buffered asynchronous read. The caller
mjr 82:4f6209cb5c33 34 * can access a completed buffer, containing the pixels from the last image
mjr 82:4f6209cb5c33 35 * frame, while the sensor is transferring data asynchronously (using the
mjr 82:4f6209cb5c33 36 * microcontroller's DMA capability) into the other buffer. Each time a
mjr 82:4f6209cb5c33 37 * new read is started, we swap buffers, making the last completed buffer
mjr 82:4f6209cb5c33 38 * available to the client and handing the other buffer to the DMA
mjr 82:4f6209cb5c33 39 * controller to fill asynchronously.
mjr 101:755f44622abc 40 *
mjr 101:755f44622abc 41 * In a way, there are actually THREE frames in our pipeline at any given
mjr 101:755f44622abc 42 * time:
mjr 101:755f44622abc 43 *
mjr 101:755f44622abc 44 * - a live image integrating light on the photo receptors on the sensor
mjr 101:755f44622abc 45 * - the prior image, held in the sensor's shift register and being
mjr 101:755f44622abc 46 * transferred via DMA into one of our buffers (the "DMA" buffer)
mjr 101:755f44622abc 47 * - the second prior image, in our other buffer (the "stable" buffer),
mjr 101:755f44622abc 48 * available for the client to process
mjr 101:755f44622abc 49 *
mjr 101:755f44622abc 50 * The integration process on the sensor starts when we begin the transfer
mjr 101:755f44622abc 51 * of an image via DMA. That frame's integration period ends when the next
mjr 101:755f44622abc 52 * transfer starts. So the minimum integration time is also the DMA pixel
mjr 101:755f44622abc 53 * transfer time. Longer integration times can be achieved by waiting
mjr 101:755f44622abc 54 * for an additional interval after a DMA transfer finishes, before starting
mjr 101:755f44622abc 55 * the next transfer. We make provision for this added time to allow for
mjr 101:755f44622abc 56 * longer exposure times to optimize image quality.
mjr 101:755f44622abc 57 *
mjr 82:4f6209cb5c33 58 *
mjr 101:755f44622abc 59 * *** Optimizing pixel transfer speed ***
mjr 82:4f6209cb5c33 60 *
mjr 101:755f44622abc 61 * For Pinscape purposes, we want the fastest possible frame rate, as we're
mjr 101:755f44622abc 62 * trying to accurately capture the motion of a fast-moving object (the
mjr 101:755f44622abc 63 * plunger). The TSL14xx sensors can achieve a frame rate up to about
mjr 101:755f44622abc 64 * 1000 frames per second, if everything is clocked at the limits in the
mjr 101:755f44622abc 65 * data sheet. The KL25Z, however, can't achieve that fast a rate. The
mjr 101:755f44622abc 66 * limiting factor is the KL25Z's ADC. We have to take an ADC sample for
mjr 101:755f44622abc 67 * every pixel, and the minimum sampling time for the ADC on the KL25Z is
mjr 101:755f44622abc 68 * about 2us. With the 1280-pixel TSL1410R, that gives us a minimum
mjr 101:755f44622abc 69 * pixel transfer time of about 2.6ms. And it's actually very difficult
mjr 101:755f44622abc 70 * to achieve that speed - my original, naive implementation took more
mjr 101:755f44622abc 71 * like 30ms (!!!) to transfer each frame.
mjr 82:4f6209cb5c33 72 *
mjr 101:755f44622abc 73 * As a rule, I don't like tricky code, because it's hard to understand
mjr 101:755f44622abc 74 * and hard to debug. But in this case it's justified. For good plunger
mjr 101:755f44622abc 75 * tracking, it's critical to achieve a minimum frame rate of around 200
mjr 101:755f44622abc 76 * fps (5ms per frame). I'm pretty sure there's no way to even get close
mjr 101:755f44622abc 77 * to this rate without the complex setup described below.
mjr 101:755f44622abc 78 *
mjr 101:755f44622abc 79 * Here's our approach for fast data transfer:
mjr 82:4f6209cb5c33 80 *
mjr 82:4f6209cb5c33 81 * First, we put the analog input port (the ADC == Analog-to-Digital
mjr 82:4f6209cb5c33 82 * Converter) in "continuous" mode, at the highest clock speed we can
mjr 82:4f6209cb5c33 83 * program with the available clocks and the fastest read cycle
mjr 82:4f6209cb5c33 84 * available in the ADC hardware. (The analog input port is the
mjr 82:4f6209cb5c33 85 * GPIO pin attached to the sensor's AO == Analog Output pin, where
mjr 82:4f6209cb5c33 86 * it outputs each pixel's value, one at a time, as an analog voltage
mjr 82:4f6209cb5c33 87 * level.) In continuous mode, every time the ADC finishes taking a
mjr 82:4f6209cb5c33 88 * sample, it stores the result value in its output register and then
mjr 82:4f6209cb5c33 89 * immediately starts taking a new sample. This means that no MCU
mjr 82:4f6209cb5c33 90 * (or even DMA) action is required to start each new sample. This
mjr 82:4f6209cb5c33 91 * is where most of the speedup comes from, since it takes significant
mjr 82:4f6209cb5c33 92 * time (multiple microseconds) to move data through the peripheral
mjr 82:4f6209cb5c33 93 * registers, and it takes more time (also multiple microseconds) for
mjr 82:4f6209cb5c33 94 * the ADC to spin up for each new sample when in single-sample mode.
mjr 82:4f6209cb5c33 95 * We cut out about 7us this way and get the time per sample down to
mjr 82:4f6209cb5c33 96 * about 2us. This is close to the documented maximum speed for the
mjr 82:4f6209cb5c33 97 * ADC hardware.
mjr 82:4f6209cb5c33 98 *
mjr 82:4f6209cb5c33 99 * Second, we use the DMA controller to read the ADC result register
mjr 82:4f6209cb5c33 100 * and store each sample in a memory array for processing. The ADC
mjr 82:4f6209cb5c33 101 * hardware is designed to work with the DMA controller by signaling
mjr 82:4f6209cb5c33 102 * the DMA controller when a new sample is ready; this allows DMA to
mjr 82:4f6209cb5c33 103 * move each sample immediately when it's available without any CPU
mjr 82:4f6209cb5c33 104 * involvement.
mjr 82:4f6209cb5c33 105 *
mjr 82:4f6209cb5c33 106 * Third - and this is where it really gets tricky - we use two
mjr 82:4f6209cb5c33 107 * additional "linked" DMA channels to generate the clock signal
mjr 82:4f6209cb5c33 108 * to the CCD sensor. The clock signal is how we tell the CCD when
mjr 82:4f6209cb5c33 109 * to place the next pixel voltage on its AO pin, so the clock has
mjr 82:4f6209cb5c33 110 * to be generated in lock step with the ADC sampling cycle. The
mjr 82:4f6209cb5c33 111 * ADC timing isn't perfectly uniform or predictable, so we can't
mjr 82:4f6209cb5c33 112 * just generate the pixel clock with a *real* clock. We have to
mjr 82:4f6209cb5c33 113 * time the signal exactly with the ADC, which means that we have
mjr 82:4f6209cb5c33 114 * to generate it from the ADC "sample is ready" signal. Fortunately,
mjr 82:4f6209cb5c33 115 * there is just such a signal, and in fact we're already using it,
mjr 82:4f6209cb5c33 116 * as described above, to tell the DMA when to move each result from
mjr 82:4f6209cb5c33 117 * the ADC output register to our memory array. So how do we use this
mjr 82:4f6209cb5c33 118 * to generate the CCD clock? The answer lies in the DMA controller's
mjr 82:4f6209cb5c33 119 * channel linking feature. This allows one DMA channel to trigger a
mjr 82:4f6209cb5c33 120 * second DMA channel each time the first channel completes one
mjr 82:4f6209cb5c33 121 * transfer. And we can use DMA to control our clock GPIO pin by
mjr 82:4f6209cb5c33 122 * using the pin's GPIO IPORT register as the DMA destination address.
mjr 82:4f6209cb5c33 123 * Specifically, we can take the clock high by writing our pin's bit
mjr 82:4f6209cb5c33 124 * pattern to the PSOR ("set output") register, and we can take the
mjr 82:4f6209cb5c33 125 * clock low by writing to the PCOR ("clear output") register. We
mjr 82:4f6209cb5c33 126 * use one DMA channel for each of these operations.
mjr 82:4f6209cb5c33 127 *
mjr 82:4f6209cb5c33 128 * Putting it all together, the cascade of linked DMA channels
mjr 82:4f6209cb5c33 129 * works like this:
mjr 82:4f6209cb5c33 130 *
mjr 82:4f6209cb5c33 131 * - We kick off the first ADC sample.
mjr 82:4f6209cb5c33 132 *
mjr 82:4f6209cb5c33 133 * - When the ADC sample completes, the ADC DMA trigger fires,
mjr 82:4f6209cb5c33 134 * which triggers channel 1, the "Clock Up" channel. This
mjr 82:4f6209cb5c33 135 * performs one transfer of the clock GPIO bit to the clock
mjr 82:4f6209cb5c33 136 * PSOR register, taking the clock high, which causes the CCD
mjr 82:4f6209cb5c33 137 * to move the next pixel onto AO.
mjr 82:4f6209cb5c33 138 *
mjr 82:4f6209cb5c33 139 * - After the Clock Up channel does its transfer, it triggers
mjr 82:4f6209cb5c33 140 * its link to channel 2, the ADC transfer channel. This
mjr 82:4f6209cb5c33 141 * channel moves the ADC output register value to our memory
mjr 82:4f6209cb5c33 142 * array.
mjr 82:4f6209cb5c33 143 *
mjr 82:4f6209cb5c33 144 * - After the ADC channel does its transfer, it triggers channel
mjr 82:4f6209cb5c33 145 * 3, the "Clock Down" channel. This performs one transfer of
mjr 82:4f6209cb5c33 146 * the clock GPIO bit to the clock PCOR register, taking the
mjr 82:4f6209cb5c33 147 * clock low.
mjr 82:4f6209cb5c33 148 *
mjr 82:4f6209cb5c33 149 * Note that the order of the channels - Clock Up, ADC, Clock Down -
mjr 82:4f6209cb5c33 150 * is important. It ensures that we don't toggle the clock line
mjr 82:4f6209cb5c33 151 * too quickly. The CCD has a minimum pulse duration of 50ns for
mjr 82:4f6209cb5c33 152 * the clock signal. The DMA controller is so fast that it might
mjr 82:4f6209cb5c33 153 * toggle the clock faster than this limit if we did the Up and
mjr 82:4f6209cb5c33 154 * Down transfers back-to-back.
mjr 82:4f6209cb5c33 155 *
mjr 82:4f6209cb5c33 156 * Note also that it's important for Clock Up to be the very first
mjr 82:4f6209cb5c33 157 * operation after the DMA trigger. The ADC is in continuous mode,
mjr 82:4f6209cb5c33 158 * meaning that it starts taking a new sample immediately upon
mjr 82:4f6209cb5c33 159 * finishing the previous one. So when the ADC DMA signal fires,
mjr 82:4f6209cb5c33 160 * the new sample is already starting. We therefore have to get
mjr 82:4f6209cb5c33 161 * the next pixel onto the sampling pin immediately, or as close
mjr 82:4f6209cb5c33 162 * to immediately as possible. The sensor's "analog output
mjr 82:4f6209cb5c33 163 * settling time" is 120ns - this is the time for a new pixel
mjr 82:4f6209cb5c33 164 * voltage to stabilize on AO after a clock rising edge. So
mjr 82:4f6209cb5c33 165 * assuming that the ADC raises the DMA signal immediately on
mjr 82:4f6209cb5c33 166 * sample completion, and the DMA controller responds within a
mjr 82:4f6209cb5c33 167 * couple of MCU clock cycles, we should have the new pixel voltage
mjr 82:4f6209cb5c33 168 * stable on the sampling pin by about 200ns after the new ADC
mjr 82:4f6209cb5c33 169 * sample cycle starts. The sampling cycle with our current
mjr 82:4f6209cb5c33 170 * parameters is about 2us, so the voltage level is stable for
mjr 82:4f6209cb5c33 171 * 90% of the cycle.
mjr 82:4f6209cb5c33 172 *
mjr 82:4f6209cb5c33 173 * Also, note that it's okay that the ADC sample transfer doesn't
mjr 82:4f6209cb5c33 174 * happen until after the Clock Up DMA transfer. The ADC output
mjr 82:4f6209cb5c33 175 * register holds the last result until the next sample completes,
mjr 82:4f6209cb5c33 176 * so we have about 2us to grab it. The first Clock Up DMA
mjr 82:4f6209cb5c33 177 * transfer only takes a couple of clocks - order of 100ns - so
mjr 82:4f6209cb5c33 178 * we get to it with time to spare.
mjr 82:4f6209cb5c33 179 *
mjr 82:4f6209cb5c33 180 * (Note that it would nicer to handle the clock with a single DMA
mjr 82:4f6209cb5c33 181 * channel, since DMA channels are a limited resource. We could
mjr 82:4f6209cb5c33 182 * conceivably consolidate the clock generator one DMA channel by
mjr 82:4f6209cb5c33 183 * switching the DMA destination to the PTOR "toggle" register, and
mjr 82:4f6209cb5c33 184 * writing *two* times per trigger - once to toggle the clock up,
mjr 82:4f6209cb5c33 185 * and a second time to toggle it down. But I haven't found a way
mjr 82:4f6209cb5c33 186 * to make this work. The obstacle is that the DMA controller can
mjr 82:4f6209cb5c33 187 * only do one transfer per trigger in the fully autonomous mode
mjr 82:4f6209cb5c33 188 * we're using, and to make this toggle scheme work, we'd have to do
mjr 82:4f6209cb5c33 189 * two writes per trigger. Maybe even three or four: I think we'd
mjr 82:4f6209cb5c33 190 * have to throw in one or two no-op writes (of all zeroes) between
mjr 82:4f6209cb5c33 191 * the two toggles, to pad the timing to ensure that the clock pulse
mjr 82:4f6209cb5c33 192 * width is over the sensor's 50ns minimum. But it's the same issue
mjr 82:4f6209cb5c33 193 * whether it's two writes or four. The DMA controller does have a
mjr 82:4f6209cb5c33 194 * "continuous" mode that does an entire transfer on a single trigger,
mjr 82:4f6209cb5c33 195 * but it can't reset itself after such a transfer; CPU intervention
mjr 82:4f6209cb5c33 196 * is required to do that, which means we'd have to service an
mjr 82:4f6209cb5c33 197 * interrupt on every ADC cycle to set up the next clock write.
mjr 82:4f6209cb5c33 198 * Given the 2us cycle time, an interrupt would create a ton of CPU
mjr 82:4f6209cb5c33 199 * load, and I don't think the CPU is fast enough to reliably complete
mjr 82:4f6209cb5c33 200 * the work we'd have to do on each 2us cycle. Fortunately, at
mjr 82:4f6209cb5c33 201 * the moment we can afford to dedicate three channels to this
mjr 82:4f6209cb5c33 202 * module. We only have one other module using the DMA at all
mjr 82:4f6209cb5c33 203 * (the TLC5940 PWM controller interface), and it only needs one
mjr 82:4f6209cb5c33 204 * channel. So the KL25Z's complement of four DMA channels is just
mjr 82:4f6209cb5c33 205 * enough for all of our needs for the moment.)
mjr 101:755f44622abc 206 *
mjr 101:755f44622abc 207 * Note that some of the sensors in this series (TSL1410R, TSL1412S)
mjr 101:755f44622abc 208 * have a "parallel" readout mode that lets them physically deliver
mjr 101:755f44622abc 209 * two pixels at once the MCU, via separate physical connections. This
mjr 101:755f44622abc 210 * could provide a 2X speedup on an MCU equipped with two independent
mjr 101:755f44622abc 211 * ADC samplers. Unfortunately, the KL25Z is not so equipped; even
mjr 101:755f44622abc 212 * though it might appear at first glance to support multiple ADC
mjr 101:755f44622abc 213 * "channels", all of the channels internally multiplex into a single
mjr 101:755f44622abc 214 * converter unit, so the hardware can ultimately perform only one
mjr 101:755f44622abc 215 * conversion at a time. Paradoxically, using the sensor's parallel
mjr 101:755f44622abc 216 * mode is actually *slower* with a KL25Z than using its serial mode,
mjr 101:755f44622abc 217 * because we can only maintain the higher throughput of the KL25Z ADC's
mjr 101:755f44622abc 218 * continuous sampling mode by reading all samples thorugh a single
mjr 101:755f44622abc 219 * channel. Switching channels on alternating samples involves a
mjr 101:755f44622abc 220 * bunch of setup overhead within the ADC hardware that adds lots of
mjr 101:755f44622abc 221 * clocks compared to single-channel continuous mode.
mjr 82:4f6209cb5c33 222 */
mjr 82:4f6209cb5c33 223
mjr 82:4f6209cb5c33 224 #include "mbed.h"
mjr 82:4f6209cb5c33 225 #include "config.h"
mjr 82:4f6209cb5c33 226 #include "AltAnalogIn.h"
mjr 82:4f6209cb5c33 227 #include "SimpleDMA.h"
mjr 82:4f6209cb5c33 228 #include "DMAChannels.h"
mjr 82:4f6209cb5c33 229
mjr 82:4f6209cb5c33 230 #ifndef TSL14XX_H
mjr 82:4f6209cb5c33 231 #define TSL14XX_H
mjr 82:4f6209cb5c33 232
mjr 82:4f6209cb5c33 233
mjr 82:4f6209cb5c33 234 // To allow DMA access to the clock pin, we need to point the DMA
mjr 82:4f6209cb5c33 235 // controller to the IOPORT registers that control the pin. PORT_BASE()
mjr 82:4f6209cb5c33 236 // gives us the address of the register group for the 32 GPIO pins with
mjr 82:4f6209cb5c33 237 // the same letter name as our target pin (e.g., PTA0 through PTA31),
mjr 82:4f6209cb5c33 238 // and PINMASK gives us the bit pattern to write to those registers to
mjr 82:4f6209cb5c33 239 // access our single GPIO pin. Each register group has three special
mjr 82:4f6209cb5c33 240 // registers that update the pin in particular ways: PSOR ("set output
mjr 82:4f6209cb5c33 241 // register") turns pins on, PCOR ("clear output register") turns pins
mjr 82:4f6209cb5c33 242 // off, and PTOR ("toggle output register") toggle pins to the opposite
mjr 82:4f6209cb5c33 243 // of their current values. These registers have special semantics:
mjr 82:4f6209cb5c33 244 // writing a bit as 0 has no effect on the corresponding pin, while
mjr 82:4f6209cb5c33 245 // writing a bit as 1 performs the register's action on the pin. This
mjr 82:4f6209cb5c33 246 // allows a single GPIO pin to be set, cleared, or toggled with a
mjr 82:4f6209cb5c33 247 // 32-bit write to one of these registers, without affecting any of the
mjr 82:4f6209cb5c33 248 // other pins addressed by the register. (It also allows changing any
mjr 82:4f6209cb5c33 249 // group of pins with a single write, although we don't use that
mjr 82:4f6209cb5c33 250 // feature here.)
mjr 82:4f6209cb5c33 251 //
mjr 82:4f6209cb5c33 252 // - To turn a pin ON: PORT_BASE(pin)->PSOR = PINMASK(pin)
mjr 82:4f6209cb5c33 253 // - To turn a pin OFF: PORT_BASE(pin)->PCOR = PINMASK(pin)
mjr 82:4f6209cb5c33 254 // - To toggle a pin: PORT_BASE(pin)->PTOR = PINMASK(pin)
mjr 82:4f6209cb5c33 255 //
mjr 82:4f6209cb5c33 256 #define GPIO_PORT(pin) (((unsigned int)(pin)) >> PORT_SHIFT)
mjr 82:4f6209cb5c33 257 #define GPIO_PORT_BASE(pin) ((GPIO_Type *)(PTA_BASE + GPIO_PORT(pin) * 0x40))
mjr 82:4f6209cb5c33 258 #define GPIO_PINMASK(pin) gpio_set(pin)
mjr 82:4f6209cb5c33 259
mjr 82:4f6209cb5c33 260 IF_DIAG(
mjr 82:4f6209cb5c33 261 extern uint64_t mainLoopIterCheckpt[];
mjr 82:4f6209cb5c33 262 extern Timer mainLoopTimer;)
mjr 82:4f6209cb5c33 263
mjr 82:4f6209cb5c33 264 class TSL14xx
mjr 82:4f6209cb5c33 265 {
mjr 82:4f6209cb5c33 266 public:
mjr 82:4f6209cb5c33 267 // Set up the interface.
mjr 82:4f6209cb5c33 268 //
mjr 82:4f6209cb5c33 269 // nPixSensor = native number of pixels on sensor
mjr 82:4f6209cb5c33 270 // siPin = SI pin (GPIO, digital out)
mjr 82:4f6209cb5c33 271 // clockPin = CLK pin (GPIO, digital out)
mjr 82:4f6209cb5c33 272 // aoPin = AO pin (GPIO, analog in - must be ADC-capable)
mjr 82:4f6209cb5c33 273 TSL14xx(int nPixSensor, PinName siPin, PinName clockPin, PinName aoPin)
mjr 100:1ff35c07217c 274 : adc_dma(DMAch_TSL_ADC),
mjr 100:1ff35c07217c 275 clkUp_dma(DMAch_TSL_CLKUP),
mjr 100:1ff35c07217c 276 clkDn_dma(DMAch_TSL_CLKDN),
mjr 82:4f6209cb5c33 277 si(siPin),
mjr 82:4f6209cb5c33 278 clock(clockPin),
mjr 100:1ff35c07217c 279 ao(aoPin, true, 0), // continuous sampling, fast sampling mode
mjr 82:4f6209cb5c33 280 nPixSensor(nPixSensor)
mjr 82:4f6209cb5c33 281 {
mjr 100:1ff35c07217c 282 // Calibrate the ADC for best accuracy
mjr 100:1ff35c07217c 283 ao.calibrate();
mjr 100:1ff35c07217c 284
mjr 82:4f6209cb5c33 285 // start the sample timer with an arbitrary zero point of 'now'
mjr 82:4f6209cb5c33 286 t.start();
mjr 82:4f6209cb5c33 287
mjr 101:755f44622abc 288 // start with no minimum integration time
mjr 101:755f44622abc 289 tIntMin = 0;
mjr 101:755f44622abc 290
mjr 82:4f6209cb5c33 291 // allocate our double pixel buffers
mjr 82:4f6209cb5c33 292 pix1 = new uint8_t[nPixSensor*2];
mjr 82:4f6209cb5c33 293 pix2 = pix1 + nPixSensor;
mjr 82:4f6209cb5c33 294
mjr 82:4f6209cb5c33 295 // put the first DMA transfer into the first buffer (pix1)
mjr 82:4f6209cb5c33 296 pixDMA = 0;
mjr 101:755f44622abc 297
mjr 101:755f44622abc 298 // DMA owns both buffers until the first transfer completes
mjr 101:755f44622abc 299 clientOwnsStablePix = true;
mjr 82:4f6209cb5c33 300
mjr 82:4f6209cb5c33 301 // remember the clock pin port base and pin mask for fast access
mjr 82:4f6209cb5c33 302 clockPort = GPIO_PORT_BASE(clockPin);
mjr 82:4f6209cb5c33 303 clockMask = GPIO_PINMASK(clockPin);
mjr 82:4f6209cb5c33 304
mjr 82:4f6209cb5c33 305 // clear out power-on random data by clocking through all pixels twice
mjr 82:4f6209cb5c33 306 clear();
mjr 82:4f6209cb5c33 307 clear();
mjr 82:4f6209cb5c33 308
mjr 82:4f6209cb5c33 309 // Set up the Clock Up DMA channel. This channel takes the
mjr 82:4f6209cb5c33 310 // clock high by writing the clock bit to the PSOR (set output)
mjr 82:4f6209cb5c33 311 // register for the clock pin.
mjr 82:4f6209cb5c33 312 clkUp_dma.source(&clockMask, false, 32);
mjr 82:4f6209cb5c33 313 clkUp_dma.destination(&clockPort->PSOR, false, 32);
mjr 82:4f6209cb5c33 314
mjr 82:4f6209cb5c33 315 // Set up the Clock Down DMA channel. This channel takes the
mjr 82:4f6209cb5c33 316 // clock low by writing the clock bit to the PCOR (clear output)
mjr 82:4f6209cb5c33 317 // register for the clock pin.
mjr 82:4f6209cb5c33 318 clkDn_dma.source(&clockMask, false, 32);
mjr 82:4f6209cb5c33 319 clkDn_dma.destination(&clockPort->PCOR, false, 32);
mjr 82:4f6209cb5c33 320
mjr 82:4f6209cb5c33 321 // Set up the ADC transfer DMA channel. This channel transfers
mjr 82:4f6209cb5c33 322 // the current analog sampling result from the ADC output register
mjr 82:4f6209cb5c33 323 // to our pixel array.
mjr 82:4f6209cb5c33 324 ao.initDMA(&adc_dma);
mjr 82:4f6209cb5c33 325
mjr 82:4f6209cb5c33 326 // Set up our chain of linked DMA channel:
mjr 82:4f6209cb5c33 327 //
mjr 82:4f6209cb5c33 328 // ADC sample completion triggers Clock Up
mjr 82:4f6209cb5c33 329 // ...which triggers the ADC transfer
mjr 82:4f6209cb5c33 330 // ...which triggers Clock Down
mjr 82:4f6209cb5c33 331 //
mjr 82:4f6209cb5c33 332 // We operate the ADC in "continuous mode", meaning that it starts
mjr 82:4f6209cb5c33 333 // a new sample immediately after the last one completes. This is
mjr 82:4f6209cb5c33 334 // what keeps the cycle going after the Clock Down, since the Clock
mjr 82:4f6209cb5c33 335 // Down transfer itself doesn't trigger another DMA operation.
mjr 82:4f6209cb5c33 336 clkUp_dma.trigger(Trigger_ADC0);
mjr 82:4f6209cb5c33 337 clkUp_dma.link(adc_dma);
mjr 82:4f6209cb5c33 338 adc_dma.link(clkDn_dma, false);
mjr 82:4f6209cb5c33 339
mjr 82:4f6209cb5c33 340 // Set the trigger on the downstream links to NONE - these are
mjr 82:4f6209cb5c33 341 // triggered by their upstream links, so they don't need separate
mjr 82:4f6209cb5c33 342 // peripheral or software triggers.
mjr 82:4f6209cb5c33 343 adc_dma.trigger(Trigger_NONE);
mjr 82:4f6209cb5c33 344 clkDn_dma.trigger(Trigger_NONE);
mjr 82:4f6209cb5c33 345
mjr 82:4f6209cb5c33 346 // Register an interrupt callback so that we're notified when
mjr 82:4f6209cb5c33 347 // the last transfer completes.
mjr 82:4f6209cb5c33 348 clkDn_dma.attach(this, &TSL14xx::transferDone);
mjr 82:4f6209cb5c33 349
mjr 82:4f6209cb5c33 350 // clear the timing statistics
mjr 82:4f6209cb5c33 351 totalTime = 0.0;
mjr 82:4f6209cb5c33 352 nRuns = 0;
mjr 101:755f44622abc 353
mjr 101:755f44622abc 354 // start the first transfer
mjr 101:755f44622abc 355 startTransfer();
mjr 82:4f6209cb5c33 356 }
mjr 82:4f6209cb5c33 357
mjr 82:4f6209cb5c33 358 // Get the stable pixel array. This is the image array from the
mjr 82:4f6209cb5c33 359 // previous capture. It remains valid until the next startCapture()
mjr 82:4f6209cb5c33 360 // call, at which point this buffer will be reused for the new capture.
mjr 82:4f6209cb5c33 361 void getPix(uint8_t * &pix, uint32_t &t)
mjr 82:4f6209cb5c33 362 {
mjr 82:4f6209cb5c33 363 // return the pixel array that ISN'T assigned to the DMA
mjr 82:4f6209cb5c33 364 if (pixDMA)
mjr 82:4f6209cb5c33 365 {
mjr 82:4f6209cb5c33 366 // DMA owns pix2, so the stable array is pix1
mjr 82:4f6209cb5c33 367 pix = pix1;
mjr 82:4f6209cb5c33 368 t = t1;
mjr 82:4f6209cb5c33 369 }
mjr 82:4f6209cb5c33 370 else
mjr 82:4f6209cb5c33 371 {
mjr 82:4f6209cb5c33 372 // DMA owns pix1, so the stable array is pix2
mjr 82:4f6209cb5c33 373 pix = pix2;
mjr 82:4f6209cb5c33 374 t = t2;
mjr 82:4f6209cb5c33 375 }
mjr 82:4f6209cb5c33 376 }
mjr 82:4f6209cb5c33 377
mjr 86:e30a1f60f783 378 // Wait for the current DMA transfer to finish, and retrieve its
mjr 86:e30a1f60f783 379 // pixel array buffer. This provides access to the latest image
mjr 86:e30a1f60f783 380 // without starting a new transfer. These pixels are valid throughout
mjr 86:e30a1f60f783 381 // the next transfer (started via startCapture()) and remain valid
mjr 86:e30a1f60f783 382 // until the next transfer after that.
mjr 86:e30a1f60f783 383 void waitPix(uint8_t * &pix, uint32_t &t)
mjr 86:e30a1f60f783 384 {
mjr 101:755f44622abc 385 // wait for stable buffer ownership to transfer to the client
mjr 86:e30a1f60f783 386 wait();
mjr 86:e30a1f60f783 387
mjr 86:e30a1f60f783 388 // Return the pixel array that IS assigned to DMA, since this
mjr 86:e30a1f60f783 389 // is the latest buffer filled. This buffer is stable, even
mjr 86:e30a1f60f783 390 // though it's assigned to DMA, because the last transfer is
mjr 86:e30a1f60f783 391 // already finished and thus DMA is no longer accessing the
mjr 86:e30a1f60f783 392 // buffer.
mjr 86:e30a1f60f783 393 if (pixDMA)
mjr 86:e30a1f60f783 394 {
mjr 86:e30a1f60f783 395 // DMA owns pix2
mjr 86:e30a1f60f783 396 pix = pix2;
mjr 86:e30a1f60f783 397 t = t2;
mjr 86:e30a1f60f783 398 }
mjr 86:e30a1f60f783 399 else
mjr 86:e30a1f60f783 400 {
mjr 86:e30a1f60f783 401 // DMA owns pix1
mjr 86:e30a1f60f783 402 pix = pix1;
mjr 86:e30a1f60f783 403 t = t1;
mjr 86:e30a1f60f783 404 }
mjr 86:e30a1f60f783 405 }
mjr 86:e30a1f60f783 406
mjr 101:755f44622abc 407 // Set the requested minimum integration time. If this is less than the
mjr 101:755f44622abc 408 // sensor's physical minimum time, the physical minimum applies.
mjr 101:755f44622abc 409 virtual void setMinIntTime(uint32_t us)
mjr 82:4f6209cb5c33 410 {
mjr 101:755f44622abc 411 tIntMin = us;
mjr 101:755f44622abc 412 }
mjr 101:755f44622abc 413
mjr 101:755f44622abc 414 // Wait for the stable buffer ownership to transfer to the client
mjr 101:755f44622abc 415 void wait() { while (!clientOwnsStablePix) ; }
mjr 101:755f44622abc 416
mjr 101:755f44622abc 417 // Is a buffer available?
mjr 101:755f44622abc 418 bool ready() const { return clientOwnsStablePix; }
mjr 101:755f44622abc 419
mjr 101:755f44622abc 420 // Release the client DMA buffer. The client must call this when it's
mjr 101:755f44622abc 421 // done with the current image frame to release the frame back to the
mjr 101:755f44622abc 422 // DMA subsystem, so that it can hand us the next frame.
mjr 101:755f44622abc 423 void releasePix() { clientOwnsStablePix = false; }
mjr 82:4f6209cb5c33 424
mjr 101:755f44622abc 425 // get the timing statistics - sum of scan time for all scans so far
mjr 101:755f44622abc 426 // in microseconds, and total number of scans so far
mjr 101:755f44622abc 427 void getTimingStats(uint64_t &totalTime, uint32_t &nRuns) const
mjr 101:755f44622abc 428 {
mjr 101:755f44622abc 429 totalTime = this->totalTime;
mjr 101:755f44622abc 430 nRuns = this->nRuns;
mjr 101:755f44622abc 431 }
mjr 101:755f44622abc 432
mjr 101:755f44622abc 433 // get the average scan time in microseconds
mjr 101:755f44622abc 434 uint32_t getAvgScanTime() const
mjr 101:755f44622abc 435 {
mjr 101:755f44622abc 436 return uint32_t(totalTime / nRuns);
mjr 101:755f44622abc 437 }
mjr 101:755f44622abc 438
mjr 101:755f44622abc 439 private:
mjr 101:755f44622abc 440 // Start a new transfer. We call this at the end of each integration
mjr 101:755f44622abc 441 // cycle, in interrupt mode. This can be called directly by the interrupt
mjr 101:755f44622abc 442 // handler invoked when the DMA transfer completes, or by a timeout. In
mjr 101:755f44622abc 443 // either case, we're in interrupt mode.
mjr 101:755f44622abc 444 void startTransfer()
mjr 101:755f44622abc 445 {
mjr 101:755f44622abc 446 // If we own the stable buffer, swap buffers: hand ownership of the
mjr 101:755f44622abc 447 // old DMA buffer to the client, and take control of the old client
mjr 101:755f44622abc 448 // buffer (which the client must be done with if we own it) as our
mjr 101:755f44622abc 449 // new DMA buffer.
mjr 101:755f44622abc 450 //
mjr 101:755f44622abc 451 // If the client owns the stable buffer, we can't swap buffers,
mjr 101:755f44622abc 452 // because the client is still working on the stable one. So we
mjr 101:755f44622abc 453 // must start the new transfer using the existing DMA buffer.
mjr 101:755f44622abc 454 if (!clientOwnsStablePix)
mjr 82:4f6209cb5c33 455 {
mjr 101:755f44622abc 456 // swap buffers
mjr 101:755f44622abc 457 pixDMA ^= 1;
mjr 101:755f44622abc 458
mjr 101:755f44622abc 459 // release the prior DMA buffer to the client
mjr 101:755f44622abc 460 clientOwnsStablePix = true;
mjr 82:4f6209cb5c33 461 }
mjr 82:4f6209cb5c33 462
mjr 82:4f6209cb5c33 463 // Set up the active pixel array as the destination buffer for
mjr 82:4f6209cb5c33 464 // the ADC DMA channel.
mjr 82:4f6209cb5c33 465 adc_dma.destination(pixDMA ? pix2 : pix1, true);
mjr 82:4f6209cb5c33 466
mjr 82:4f6209cb5c33 467 // start the DMA transfers
mjr 82:4f6209cb5c33 468 clkDn_dma.start(nPixSensor*4, true);
mjr 82:4f6209cb5c33 469 adc_dma.start(nPixSensor, true);
mjr 82:4f6209cb5c33 470 clkUp_dma.start(nPixSensor*4, true);
mjr 82:4f6209cb5c33 471
mjr 82:4f6209cb5c33 472 // note the start time of this transfer
mjr 82:4f6209cb5c33 473 t0 = t.read_us();
mjr 82:4f6209cb5c33 474
mjr 82:4f6209cb5c33 475 // start the next integration cycle by pulsing SI and one clock
mjr 82:4f6209cb5c33 476 si = 1;
mjr 82:4f6209cb5c33 477 clock = 1;
mjr 82:4f6209cb5c33 478 si = 0;
mjr 82:4f6209cb5c33 479 clock = 0;
mjr 82:4f6209cb5c33 480
mjr 82:4f6209cb5c33 481 // Set the timestamp for the current active buffer. The SI pulse
mjr 86:e30a1f60f783 482 // we just did performed the HOLD operation, which takes a snapshot
mjr 86:e30a1f60f783 483 // of the photo receptors and stores it in the sensor's shift
mjr 86:e30a1f60f783 484 // register. We noted the start of the current integration cycle
mjr 86:e30a1f60f783 485 // in tInt when we started it during the previous scan. The image
mjr 86:e30a1f60f783 486 // we're about to transfer therefore represents the light collected
mjr 86:e30a1f60f783 487 // between tInt and right now (actually, the SI pulse above, but
mjr 86:e30a1f60f783 488 // close enough). The image covers a time range rather than a
mjr 86:e30a1f60f783 489 // single point in time, but we still have to give it a single
mjr 86:e30a1f60f783 490 // timestamp. Use the midpoint of the integration period.
mjr 82:4f6209cb5c33 491 uint32_t tmid = (t0 + tInt) >> 1;
mjr 82:4f6209cb5c33 492 if (pixDMA)
mjr 82:4f6209cb5c33 493 t2 = tmid;
mjr 82:4f6209cb5c33 494 else
mjr 82:4f6209cb5c33 495 t1 = tmid;
mjr 82:4f6209cb5c33 496
mjr 82:4f6209cb5c33 497 // Start the ADC sampler. The ADC will read samples continuously
mjr 82:4f6209cb5c33 498 // until we tell it to stop. Each sample completion will trigger
mjr 82:4f6209cb5c33 499 // our linked DMA channel, which will store the next sample in our
mjr 82:4f6209cb5c33 500 // pixel array and pulse the CCD serial data clock to load the next
mjr 82:4f6209cb5c33 501 // pixel onto the analog sampler pin. This will all happen without
mjr 82:4f6209cb5c33 502 // any CPU involvement, so we can continue with other work.
mjr 82:4f6209cb5c33 503 ao.start();
mjr 82:4f6209cb5c33 504
mjr 82:4f6209cb5c33 505 // The new integration cycle starts with the 19th clock pulse
mjr 82:4f6209cb5c33 506 // after the SI pulse. We offload all of the transfer work (including
mjr 86:e30a1f60f783 507 // the clock pulse generation) to the DMA controller, which doesn't
mjr 86:e30a1f60f783 508 // notify when that 19th pulse occurs, so we have to approximate.
mjr 86:e30a1f60f783 509 // Based on empirical measurements, each pixel transfer in our DMA
mjr 86:e30a1f60f783 510 // setup takes about 2us, so clocking 19 pixels takes about 38us.
mjr 86:e30a1f60f783 511 // In addition, the ADC takes about 4us extra for the first read.
mjr 86:e30a1f60f783 512 tInt = t.read_us() + 19*2 + 4;
mjr 82:4f6209cb5c33 513 }
mjr 82:4f6209cb5c33 514
mjr 101:755f44622abc 515 // End of transfer notification. This is called as an interrupt
mjr 101:755f44622abc 516 // handler when the DMA transfer completes.
mjr 101:755f44622abc 517 void transferDone()
mjr 82:4f6209cb5c33 518 {
mjr 101:755f44622abc 519 // stop the ADC sampler
mjr 101:755f44622abc 520 ao.stop();
mjr 101:755f44622abc 521
mjr 101:755f44622abc 522 // clock out one extra pixel to leave the analog out pin on
mjr 101:755f44622abc 523 // the sensor in the high-Z state
mjr 101:755f44622abc 524 clock = 1;
mjr 101:755f44622abc 525 clock = 0;
mjr 101:755f44622abc 526
mjr 101:755f44622abc 527 // add this sample to the timing statistics (for diagnostics and
mjr 101:755f44622abc 528 // performance measurement)
mjr 101:755f44622abc 529 uint32_t now = t.read_us();
mjr 101:755f44622abc 530 totalTime += uint32_t(now - t0);
mjr 101:755f44622abc 531 nRuns += 1;
mjr 101:755f44622abc 532
mjr 101:755f44622abc 533 // note the ending time of the transfer
mjr 101:755f44622abc 534 tDone = now;
mjr 101:755f44622abc 535
mjr 101:755f44622abc 536 // Figure the time remaining to reach the minimum requested
mjr 101:755f44622abc 537 // integration time for the next cycle. The sensor is currently
mjr 101:755f44622abc 538 // working on an integration cycle that started at tInt, and that
mjr 101:755f44622abc 539 // cycle will end when we start the next cycle. We therefore want
mjr 101:755f44622abc 540 // to wait to start the next cycle until we've reached the desired
mjr 101:755f44622abc 541 // total integration time.
mjr 101:755f44622abc 542 uint32_t dt = now - tInt;
mjr 101:755f44622abc 543 if (dt < tIntMin)
mjr 101:755f44622abc 544 {
mjr 101:755f44622abc 545 // more time is required - set a timeout for the remaining inteval
mjr 101:755f44622abc 546 integrationTimeout.attach_us(this, &TSL14xx::startTransfer, tIntMin - dt);
mjr 101:755f44622abc 547 }
mjr 101:755f44622abc 548 else
mjr 101:755f44622abc 549 {
mjr 101:755f44622abc 550 // we've already reached the minimum integration time - start
mjr 101:755f44622abc 551 // the next transfer immediately
mjr 101:755f44622abc 552 startTransfer();
mjr 101:755f44622abc 553 }
mjr 82:4f6209cb5c33 554 }
mjr 101:755f44622abc 555
mjr 101:755f44622abc 556 // Clear the sensor shift register. Clocks in all of the pixels from
mjr 101:755f44622abc 557 // the sensor without bothering to read them on the ADC. Pulses SI
mjr 101:755f44622abc 558 // at the beginning of the operation, which starts a new integration
mjr 101:755f44622abc 559 // cycle.
mjr 82:4f6209cb5c33 560 void clear()
mjr 82:4f6209cb5c33 561 {
mjr 82:4f6209cb5c33 562 // get the clock toggle register
mjr 82:4f6209cb5c33 563 volatile uint32_t *ptor = &clockPort->PTOR;
mjr 82:4f6209cb5c33 564
mjr 82:4f6209cb5c33 565 // make sure any DMA run is completed
mjr 82:4f6209cb5c33 566 wait();
mjr 82:4f6209cb5c33 567
mjr 82:4f6209cb5c33 568 // clock in an SI pulse
mjr 82:4f6209cb5c33 569 si = 1;
mjr 82:4f6209cb5c33 570 *ptor = clockMask;
mjr 82:4f6209cb5c33 571 clockPort->PSOR = clockMask;
mjr 82:4f6209cb5c33 572 si = 0;
mjr 82:4f6209cb5c33 573 *ptor = clockMask;
mjr 82:4f6209cb5c33 574
mjr 82:4f6209cb5c33 575 // This starts a new integration period. Or more precisely, the
mjr 82:4f6209cb5c33 576 // 19th clock pulse will start the new integration period. We're
mjr 82:4f6209cb5c33 577 // going to blast the clock signal as fast as we can, at about
mjr 82:4f6209cb5c33 578 // 100ns intervals (50ns up and 50ns down), so the 19th clock
mjr 82:4f6209cb5c33 579 // will be about 2us from now.
mjr 82:4f6209cb5c33 580 tInt = t.read_us() + 2;
mjr 82:4f6209cb5c33 581
mjr 82:4f6209cb5c33 582 // clock out all pixels, plus an extra one to clock past the last
mjr 82:4f6209cb5c33 583 // pixel and reset the last pixel's internal sampling switch in
mjr 82:4f6209cb5c33 584 // the sensor
mjr 82:4f6209cb5c33 585 for (int i = 0 ; i < nPixSensor + 1 ; )
mjr 82:4f6209cb5c33 586 {
mjr 82:4f6209cb5c33 587 // toggle the clock to take it high
mjr 82:4f6209cb5c33 588 *ptor = clockMask;
mjr 82:4f6209cb5c33 589
mjr 82:4f6209cb5c33 590 // increment our loop variable here to pad the timing, to
mjr 82:4f6209cb5c33 591 // keep our pulse width long enough for the sensor
mjr 82:4f6209cb5c33 592 ++i;
mjr 82:4f6209cb5c33 593
mjr 82:4f6209cb5c33 594 // toggle the clock to take it low
mjr 82:4f6209cb5c33 595 *ptor = clockMask;
mjr 82:4f6209cb5c33 596 }
mjr 82:4f6209cb5c33 597 }
mjr 86:e30a1f60f783 598
mjr 82:4f6209cb5c33 599 // DMA controller interfaces
mjr 82:4f6209cb5c33 600 SimpleDMA adc_dma; // DMA channel for reading the analog input
mjr 82:4f6209cb5c33 601 SimpleDMA clkUp_dma; // "Clock Up" channel
mjr 82:4f6209cb5c33 602 SimpleDMA clkDn_dma; // "Clock Down" channel
mjr 82:4f6209cb5c33 603
mjr 82:4f6209cb5c33 604 // Sensor interface pins
mjr 82:4f6209cb5c33 605 DigitalOut si; // GPIO pin for sensor SI (serial data)
mjr 82:4f6209cb5c33 606 DigitalOut clock; // GPIO pin for sensor SCLK (serial clock)
mjr 82:4f6209cb5c33 607 GPIO_Type *clockPort; // IOPORT base address for clock pin - cached for DMA writes
mjr 82:4f6209cb5c33 608 uint32_t clockMask; // IOPORT register bit mask for clock pin
mjr 100:1ff35c07217c 609 AltAnalogIn_8bit ao; // GPIO pin for sensor AO (analog output)
mjr 82:4f6209cb5c33 610
mjr 82:4f6209cb5c33 611 // number of pixels in the physical sensor array
mjr 82:4f6209cb5c33 612 int nPixSensor; // number of pixels in physical sensor array
mjr 82:4f6209cb5c33 613
mjr 82:4f6209cb5c33 614 // pixel buffers - we keep two buffers so that we can transfer the
mjr 82:4f6209cb5c33 615 // current sensor data into one buffer via DMA while we concurrently
mjr 82:4f6209cb5c33 616 // process the last buffer
mjr 82:4f6209cb5c33 617 uint8_t *pix1; // pixel array 1
mjr 82:4f6209cb5c33 618 uint8_t *pix2; // pixel array 2
mjr 82:4f6209cb5c33 619
mjr 82:4f6209cb5c33 620 // Timestamps of pix1 and pix2 arrays, in microseconds, in terms of the
mjr 100:1ff35c07217c 621 // sample timer (this->t).
mjr 82:4f6209cb5c33 622 uint32_t t1;
mjr 82:4f6209cb5c33 623 uint32_t t2;
mjr 82:4f6209cb5c33 624
mjr 82:4f6209cb5c33 625 // DMA target buffer. This is the buffer for the next DMA transfer.
mjr 82:4f6209cb5c33 626 // 0 means pix1, 1 means pix2. The other buffer contains the stable
mjr 82:4f6209cb5c33 627 // data from the last transfer.
mjr 82:4f6209cb5c33 628 uint8_t pixDMA;
mjr 82:4f6209cb5c33 629
mjr 101:755f44622abc 630 // Stable buffer ownership. At any given time, the DMA subsystem owns
mjr 101:755f44622abc 631 // the buffer specified by pixDMA. The other buffer - the "stable" buffer,
mjr 101:755f44622abc 632 // which contains the most recent completed frame, can be owned by EITHER
mjr 101:755f44622abc 633 // the client or by the DMA subsystem. Each time a DMA transfer completes,
mjr 101:755f44622abc 634 // the DMA subsystem looks at the stable buffer owner flag to determine
mjr 101:755f44622abc 635 // what to do:
mjr 101:755f44622abc 636 //
mjr 101:755f44622abc 637 // - If the DMA subsystem owns the stable buffer, it swaps buffers. This
mjr 101:755f44622abc 638 // makes the newly completed DMA buffer the new stable buffer, and makes
mjr 101:755f44622abc 639 // the old stable buffer the new DMA buffer. At this time, the DMA
mjr 101:755f44622abc 640 // subsystem also changes the stable buffer ownership to CLIENT.
mjr 101:755f44622abc 641 //
mjr 101:755f44622abc 642 // - If the CLIENT owns the stable buffer, the DMA subsystem can't swap
mjr 101:755f44622abc 643 // buffers, because the client is still using the stable buffer. It
mjr 101:755f44622abc 644 // simply leaves things as they are.
mjr 101:755f44622abc 645 //
mjr 101:755f44622abc 646 // In either case, the DMA system starts a new transfer at this point.
mjr 101:755f44622abc 647 //
mjr 101:755f44622abc 648 // The client, meanwhile, is free to access the stable buffer when it has
mjr 101:755f44622abc 649 // ownership. If the client *doesn't* have ownership, it must wait for
mjr 101:755f44622abc 650 // the ownership to be transferred, which can only be done by the DMA
mjr 101:755f44622abc 651 // subsystem on completing a transfer.
mjr 101:755f44622abc 652 //
mjr 101:755f44622abc 653 // When the client is done with the stable buffer, it transfers ownership
mjr 101:755f44622abc 654 // back to the DMA subsystem.
mjr 101:755f44622abc 655 //
mjr 101:755f44622abc 656 // Transfers of ownership from DMA to CLIENT are done only by DMA.
mjr 101:755f44622abc 657 // Transfers from CLIENT to DMA are done only by CLIENT. So whoever has
mjr 101:755f44622abc 658 // ownership now is responsible for transferring ownership.
mjr 101:755f44622abc 659 //
mjr 101:755f44622abc 660 volatile bool clientOwnsStablePix;
mjr 101:755f44622abc 661
mjr 101:755f44622abc 662 // End-of-integration timeout handler. This lets us fire an interrupt
mjr 101:755f44622abc 663 // when the current integration cycle is done, so that we can start the
mjr 101:755f44622abc 664 // next cycle.
mjr 101:755f44622abc 665 Timeout integrationTimeout;
mjr 101:755f44622abc 666
mjr 101:755f44622abc 667 // Requested minimum integration time, in micoseconds. The client can use
mjr 101:755f44622abc 668 // this to control the exposure level, by increasing it for a longer
mjr 101:755f44622abc 669 // exposure and thus more light-gathering in low-light conditions. Note
mjr 101:755f44622abc 670 // that the physical limit on the minimum integration time is roughly equal
mjr 101:755f44622abc 671 // to the pixel file transfer time, because the integration cycle is
mjr 101:755f44622abc 672 // initiated and ended by transfer starts. It's thus impossible to make
mjr 101:755f44622abc 673 // the integration time less than the time for one full pixel file
mjr 101:755f44622abc 674 // transfer.
mjr 101:755f44622abc 675 uint32_t tIntMin;
mjr 101:755f44622abc 676
mjr 82:4f6209cb5c33 677 // timing statistics
mjr 82:4f6209cb5c33 678 Timer t; // sample timer
mjr 82:4f6209cb5c33 679 uint32_t t0; // start time (us) of current sample
mjr 82:4f6209cb5c33 680 uint32_t tInt; // start time (us) of current integration period
mjr 86:e30a1f60f783 681 uint32_t tDone; // end time of latest finished transfer
mjr 82:4f6209cb5c33 682 uint64_t totalTime; // total time consumed by all reads so far
mjr 82:4f6209cb5c33 683 uint32_t nRuns; // number of runs so far
mjr 82:4f6209cb5c33 684 };
mjr 82:4f6209cb5c33 685
mjr 82:4f6209cb5c33 686 #endif /* TSL14XX_H */