MbedTester.h

00001 /*
00002  * Copyright (c) 2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef MBED_TESTER_H
00019 #define MBED_TESTER_H
00020 
00021 #include "DynamicPinList.h"
00022 #include "platform/FileHandle.h"
00023 #include "platform/Callback.h"
00024 #include "drivers/DigitalInOut.h"
00025 
00026 /**
00027  * The base class for controlling the FPGA CI Test Shield
00028  *
00029  * This is the primary interface to the FPGA CI Test Shield. It contains
00030  * all the code to communicate with the FPGA. It also provides high level
00031  * helper functions, such as functions to setup pin multiplexing, to
00032  * select the currently active peripheral and to perform software updates.
00033  *
00034  * Subclasses can inherit from this class and provide further functionality,
00035  * such as the ability to test SPI.
00036  *
00037  * @note Synchronization level: Not protected
00038  *
00039  * Example of how to toggle Arduino pin D6 from the FPGA cI Test Shield:
00040  * @code
00041  * #include "mbed.h"
00042  * #include "MbedTester.h"
00043  *
00044  * const PinList *form_factor = pinmap_ff_default_pins();
00045  * const PinList *restricted = pinmap_restricted_pins();
00046  * MbedTester tester(form_factor, restricted);
00047  *
00048  * int main() {
00049  *     // Reset the FPGA CI Test Shield to put it into a known state
00050  *     tester.reset();
00051  *
00052  *     // Select the GPIO peripheral
00053  *     tester.select_peripheral(MbedTester::PeripheralGPIO);
00054  *
00055  *     // Map D6 to LogicalPinGPIO0
00056  *     tester.pin_map_set(D6, MbedTester::LogicalPinGPIO0);
00057  *
00058  *     // Toggle pin D6
00059  *     int toggle = 0;
00060  *     while (1) {
00061  *         tester.gpio_write(MbedTester::LogicalPinGPIO0, toggle, true);
00062  *         wait(0.5);
00063  *         toggle = !toggle;
00064  *     }
00065  * }
00066  * @endcode
00067  */
00068 class MbedTester {
00069 public:
00070 
00071     /*
00072      * This type represents the index of a physical pin on the FPGA.
00073      * This can be any value from 0 to 127. A form factor is used to
00074      * map a PinName to a physical pin index.
00075      */
00076     typedef uint8_t PhysicalIndex;
00077 
00078     /*
00079      * There are 8 logical pins connected to the peripherals inside the FPGA.
00080      * These are logical pins 0 through 7. All peripherals can read from these
00081      * pins and the currently active peripheral can output on these pins.
00082      *
00083      * Each logical pin has a fixed function for a given peripheral which is
00084      * why the same value is defined multiple times. For example logical pin
00085      * 2 is SPI clock (SPISclk) when SPI is the active peripheral and
00086      * UART clear to send (UARTCts) when UART is the active peripheral.
00087      *
00088      * A logic pin can be mapped to any physical pin (PinName type) by calling
00089      * the function MbedTester::pin_map_set.
00090      */
00091     enum LogicalPin {
00092 
00093         LogicalPinGPIO0 = 0,
00094         LogicalPinGPIO1 = 1,
00095         LogicalPinGPIO2 = 2,
00096         LogicalPinGPIO3 = 3,
00097         LogicalPinGPIO4 = 4,
00098         LogicalPinGPIO5 = 5,
00099         LogicalPinGPIO6 = 6,
00100         LogicalPinGPIO7 = 7,
00101 
00102         LogicalPinSPIMosi = 0,
00103         LogicalPinSPIMiso = 1,
00104         LogicalPinSPISclk = 2,
00105         LogicalPinSPISsel = 3,
00106 
00107         LogicalPinIOMetrics0 = 0,
00108         LogicalPinIOMetrics1 = 1,
00109         LogicalPinIOMetrics2 = 2,
00110         LogicalPinIOMetrics3 = 3,
00111         LogicalPinIOMetrics4 = 4,
00112         LogicalPinIOMetrics5 = 5,
00113         LogicalPinIOMetrics6 = 6,
00114         LogicalPinIOMetrics7 = 7,
00115 
00116         LogicalPinUARTTx = 0,
00117         LogicalPinUARTRx = 1,
00118         LogicalPinUARTCts = 2,
00119         LogicalPinUARTRts = 3,
00120 
00121         LogicalPinI2CSda = 0,
00122         LogicalPinI2CScl = 1,
00123 
00124         LogicalPinCount = 8,
00125         LogicalPinBanks = 2,
00126         LogicalPinTotal = LogicalPinCount * LogicalPinBanks
00127     };
00128 
00129     /*
00130      * These are the peripherals internal to the FPGA. A peripheral can be
00131      * selected by calling MbedTester::select_peripheral.
00132      */
00133     enum Peripheral {
00134         PeripheralGPIO = 1,
00135         PeripheralSPI = 2,
00136         PeripheralUART = 4,
00137         PeripheralI2C = 5,
00138         PeripheralSPISlave = 6
00139     };
00140 
00141     /**
00142      * Construct a new MbedTester object
00143      *
00144      * The form factor pins passed into this class must match the
00145      * physical MbedTester shield connected to this board or testing
00146      * will not work correctly. The order of pins in this list must
00147      * match the order of the shield.
00148      *
00149      * The exclude pins list should be used to exclude pins which you either
00150      * don't want to be tested or are not suitable for use as a control
00151      * channel. This list is allowed to contain pins that are not in the
00152      * form factor.
00153      *
00154      * @param form_factor The pins that are available on this form factor
00155      * @param exclude_pins The pins that must not be used
00156      */
00157     MbedTester(const PinList *form_factor, const PinList *exclude_pins);
00158 
00159     /**
00160      * Destroy and cleanup resources associated with this object
00161      */
00162     ~MbedTester();
00163 
00164     /**
00165      * Enable automatic selection and update of control pins
00166      *
00167      * Calling this function configures MbedTester to automatically select
00168      * and update the control pins. The control pins are moved if the
00169      * function MbedTester::pin_map_set is called and maps a pin that is being used
00170      * for control.
00171      *
00172      * @note Automatic selection and update of control pins is the default.
00173      * Unless MbedTester::set_control_pins_manual has been called to manually
00174      * set the control pins this function has no effect.
00175      */
00176     void set_control_pins_auto();
00177 
00178     /**
00179      * Set the control pins to use for communication
00180      *
00181      * Manually set the control pins. Calling this function
00182      * disables automatic control pin selection and updates.
00183      * The function MbedTester::pin_map_set must not be used to map over
00184      * control pins when in this mode.
00185      *
00186      * @param clk Clock pin to use as the control channel
00187      * @param mosi Mosi pin to use as the control channel
00188      * @param miso Miso pin to use as the control channel
00189      * @param aux Auxillary pin to use as the control cannel
00190      */
00191     void set_control_pins_manual(PinName clk, PinName mosi, PinName miso, PinName aux);
00192 
00193     /**
00194      * Read FPGA CI Test Shield firmware
00195      *
00196      * Read the firmware on the FPGA CI Test Shield. An optional progress callback
00197      * can be supplied to display progress while the firmware is being read.
00198      *
00199      * @param dest File to write the firmware to. This file must have been opened as writeable
00200      * @param progress Optional progress callback called when the percent complete changes
00201      * @return true if firmware was successfully read, false otherwise
00202      */
00203     bool firmware_dump(mbed::FileHandle *dest, mbed::Callback<void(uint8_t)> progress = mbed::Callback<void(uint8_t)>());
00204 
00205     /**
00206      * Read FPGA CI Test Shield flash
00207      *
00208      * Read the entire flash contents of the FPGA CI Test Shield. An optional progress callback
00209      * can be supplied to display progress while the firmware is being read.
00210      *
00211      * @param dest File to write the firmware to. This file must have been opened as writeable
00212      * @param progress Optional progress callback called when the percent complete changes
00213      * @return true if firmware was successfully read, false otherwise
00214      */
00215     bool firmware_dump_all(mbed::FileHandle *dest, mbed::Callback<void(uint8_t)> progress = mbed::Callback<void(uint8_t)>());
00216 
00217     /**
00218      * Program new FPGA CI Test Shield firmware
00219      *
00220      * Program firmware from the file given. The binary bitstream must be in the correct format
00221      * and contain a correct CRC or the update will fail. To correctly format a bitstream binary
00222      * the post_process_bitstream.py script in the fpga-ci-test-shield repository should be used.
00223      *
00224      * Note - release binaries for the FPGA CI Test Shield have already been formatted and
00225      *        can be loaded directly with this function
00226      *
00227      * @param src File containing the new firmware to program
00228      * @param progress Optional progress callback called when the percent complete changes
00229      * @return true if firmware was successfully applied, false otherwise
00230      */
00231     bool firmware_update(mbed::FileHandle *src, mbed::Callback<void(uint8_t)> progress = mbed::Callback<void(uint8_t)>());
00232 
00233     /**
00234      * Map a physical pin to the given logical pin
00235      *
00236      * This function will automatically move the control channel
00237      * pins to avoid interfering with the mapped pin.
00238      *
00239      * @param physical Physical pin on the board
00240      * @param logical Logical pin to map to
00241      */
00242     void pin_map_set(PinName physical, LogicalPin logical);
00243 
00244     /**
00245      * Reset all pin mappings
00246      *
00247      * After this call all pins will be unmapped
00248      */
00249     void pin_map_reset();
00250 
00251     /**
00252      * Reset all peripherals
00253      *
00254      * This does not reset the pin mappings
00255      */
00256     void peripherals_reset();
00257 
00258     /**
00259      * Reset everything
00260      *
00261      * This function resets the state of both the FPGA CI Test Shield
00262      * and the MbedTester object itself.
00263      *
00264      * Reset effects on the FPGA CI Test Shield include:
00265      * - All pins are tristated
00266      * - All pin mappings are reset
00267      * - All pullup/pulldown settings are reset
00268      * - All peripherals are reset
00269      *
00270      * Reset effects on the MbedTester object include
00271      * - Control channels tristated and freed
00272      * - Control channel selection set to automatic
00273      * - Most internal state reinitialized
00274      */
00275     void reset();
00276 
00277     /**
00278      * Reprogram the FPGA
00279      *
00280      * This function causes the FPGA to reboot and reload RAM contents.
00281      * This should be used after MbedTester::firmware_update to load the
00282      * new image.
00283      */
00284     void reprogram();
00285 
00286     /**
00287      * Get the running FPGA firmware version
00288      *
00289      * @return The version of firmware running on the FPGA.
00290      *
00291      */
00292     uint32_t version();
00293 
00294     /**
00295      * Select the currently active peripheral
00296      *
00297      * @param peripheral Active peripheral
00298      */
00299     void select_peripheral(Peripheral peripheral);
00300 
00301     /* **GPIO peripheral functions** */
00302 
00303     /**
00304      * Read a gpio pin
00305      *
00306      * @param gpio Logical pin to read from
00307      * @return 1 if the pin is high 0 if the pin is low
00308      */
00309     int gpio_read(LogicalPin gpio);
00310 
00311     /**
00312      * Set value and drive of a gpio pin
00313      *
00314      * @param gpio Logical pin to write to
00315      * @param value 0 to set the pin low or non-zero to set it high
00316      * @param driver 0 to set the pin to Hi-Z or non-zero to drive the pin
00317      */
00318     void gpio_write(LogicalPin gpio, int value, bool drive);
00319 
00320     /* **IO Metrics functions** */
00321 
00322     /**
00323      * Start recording metrics on all logical pins
00324      *
00325      * This function resets all past metrics to 0. To
00326      * preserve these call io_metrics_continue instead.
00327      */
00328     void io_metrics_start();
00329 
00330     /**
00331      * Stop recording metrics on all logical pins
00332      *
00333      * This function should be called before any metrics
00334      * are read to ensure the value does not change while
00335      * they are being read.
00336      */
00337     void io_metrics_stop();
00338 
00339     /**
00340      * Continue recording metrics on all logical pins
00341      *
00342      * Resume recording metrics.
00343      */
00344     void io_metrics_continue();
00345 
00346     /**
00347      * Get the shortest low pulse recorded
00348      *
00349      * @param pin Pin to read the metrics for
00350      * @return The shortest number of 100MHz clock cycles the pin was low
00351      */
00352     uint32_t io_metrics_min_pulse_low(LogicalPin pin);
00353 
00354     /**
00355      * Get the shortest high pulse recorded
00356      *
00357      * @param pin Pin to read the metrics for
00358      * @return The shortest number of 100MHz clock cycles the pin was high
00359      */
00360     uint32_t io_metrics_min_pulse_high(LogicalPin pin);
00361 
00362     /**
00363      * Get the longest low pulse recorded
00364      *
00365      * @param pin Pin to read the metrics for
00366      * @return The longest number of 100MHz clock cycles the pin was low
00367      */
00368     uint32_t io_metrics_max_pulse_low(LogicalPin pin);
00369 
00370     /**
00371      * Get the longest high pulse recorded
00372      *
00373      * @param pin Pin to read the metrics for
00374      * @return The longest number of 100MHz clock cycles the pin was high
00375      */
00376     uint32_t io_metrics_max_pulse_high(LogicalPin pin);
00377 
00378     /**
00379      * Get the number of rising edges
00380      *
00381      * @param pin Pin to read the metrics for
00382      * @return The number of rising edges
00383      */
00384     uint32_t io_metrics_rising_edges(LogicalPin pin);
00385 
00386     /**
00387      * Get the number of falling edges
00388      *
00389      * @param pin Pin to read the metrics for
00390      * @return The number of falling edges
00391      */
00392     uint32_t io_metrics_falling_edges(LogicalPin pin);
00393 
00394     /**
00395      * Reset the IO expander modules
00396      *
00397      */
00398     void pin_pull_reset_all();
00399 
00400     /**
00401      * FPGA Pullup mode
00402      */
00403     enum PullMode {
00404         PullUp,
00405         PullDown,
00406         PullNone
00407     };
00408 
00409     /**
00410      * Configure an Mbed pin for a pulldown resistor, pullup resistor, or tristate mode via PinName
00411      *
00412      * @param pin Mbed pin whose mode is being set
00413      * @param mode (MbedTester::PullUp, MbedTester::PullDown, or MbedTester::PullNone)
00414      * @return 0 on success, nonzero on failure
00415      */
00416     int pin_set_pull(PinName pin, PullMode mode);
00417 
00418     /**
00419      * Configure an Mbed pin for a pulldown resistor, pullup resistor, or tristate mode via pin index
00420      *
00421      * @param index Mbed pin index whose mode is being set
00422      * @param mode (MbedTester::PullUp, MbedTester::PullDown, or MbedTester::PullNone)
00423      * @return 0 on success, nonzero on failure
00424      */
00425     int pin_set_pull_index(int index, PullMode mode);
00426 
00427     /*
00428      * Register of the IO expander
00429      */
00430     enum IOExpanderReg {
00431         RegInput,
00432         RegOutput,
00433         RegConfig
00434     };
00435 
00436     /**
00437      * Read a bit for a specific Mbed pin that is set in the input, output, or configuration registers inside of the IO expander via PinName
00438      *
00439      * @param pin Mbed pin whose register bit is being read
00440      * @param reg_type Pin register to access, options are: MbedTester::RegInput, MbedTester::RegOutput, or MbedTester::RegConfig
00441      * @return The value of the bit read
00442      */
00443     uint8_t io_expander_read(PinName pin, IOExpanderReg reg_type);
00444 
00445     /**
00446      * Read a bit for a specific Mbed pin that is set in the input, output, or configuration registers inside of the IO expander via pin index
00447      *
00448      * @param index Mbed pin index whose register bit is being read
00449      * @param reg_type Pin register to access, options are: MbedTester::RegInput, MbedTester::RegOutput, or MbedTester::RegConfig
00450      * @return The value of the bit read
00451      */
00452     uint8_t io_expander_read_index(int index, IOExpanderReg reg_type);
00453 
00454     /**
00455      * Configure an Mbed pin for a pulldown resistor, pullup resistor, or tristate mode
00456      * (this version of the function uses io_expander_i2c_read_bb and io_expander_i2c_write_bb)
00457      *
00458      * @param pin Mbed pin whose mode is being set
00459      * @param mode (MbedTester::PullUp, MbedTester::PullDown, or MbedTester::PullNone)
00460      * @return 0 on success, nonzero on failure
00461      */
00462     int pin_set_pull_bb(PinName pin, PullMode mode);
00463 
00464     /**
00465      * Read a bit for a specific Mbed pin that is set in the input, output, or configuration registers inside of the IO expander
00466      * (this version of the function uses io_expander_i2c_read_bb)
00467      *
00468      * @param pin Mbed pin whose register bit is being read
00469      * @param reg_type Pin register to access, options are: MbedTester::RegInput, MbedTester::RegOutput, or MbedTester::RegConfig
00470      * @return The value of the bit read
00471      */
00472     uint8_t io_expander_read_bb(PinName pin, IOExpanderReg reg_type);
00473 
00474     /**
00475      * Create an analog voltage via the FPGA sys pwm in order to test Mbed AnalogIn
00476      *
00477      * @param enable Enable the FPGA system PWM (false: of, true: on)
00478      * @param voltage The analog voltage that will be created by the FPGA CI test shield (float: 0.0 to 1.0)
00479      */
00480     void set_analog_out(bool enable, float voltage);
00481 
00482     /**
00483      * Turn the FPGA ADC on and off (power management data will be collected while the ADC is on)
00484      *
00485      * @param val FPGA ADC enable bit (false: off, true: on)
00486      */
00487     void set_sample_adc(bool val);
00488 
00489     /**
00490      * Get the result of the analog to digital conversion computed on the FPGA in the form of a voltage reading. The FPGA ADC operates on 0V-1V, which means this function will only ever return a float ranging from 0.0-1.0.
00491      *
00492      * @return The conversion result in the form of a voltage measurement for AnalogMuxIn, Eg. a return value of 0.7 means the ADC on the FPGA read 0.7 volts on its analog input
00493      */
00494     float get_analog_in();
00495 
00496     /**
00497      * Similar to 'get_analog_in' but returns a voltage reading from ANIN0-3
00498      *
00499      * @param index ANIN pin to read (0-3)
00500      * @return The conversion result in the form of a voltage measurement for ANIN0-3
00501      */
00502     float get_anin_voltage(int index);
00503 
00504     /* **Mid level system access** */
00505 
00506     /*
00507      * These are the pins on the FPGA that are not connected to the Mbed board.
00508      * These can be controlled by using MbedTester::sys_pin_read and MbedTester::sys_pin_write.
00509      * These should not be used directly when using the FPGA CI Test Shield. The higher layer
00510      * APIs should be used instead.
00511      */
00512     enum SystemPin {
00513         Reset,
00514         Reprogram,
00515 
00516         DigitalID0,
00517         DigitalID1,
00518         DigitalID2,
00519 
00520         Led0,
00521         Led1,
00522         Led2,
00523         Led3,
00524 
00525         SPIIO0,
00526         SPIIO1,
00527         SPIIO2,
00528         SPIIO3,
00529         SPIClk,
00530         SPICS,
00531 
00532         I2CReset,
00533         I2CSda0,
00534         I2CSda1,
00535         I2CSda2,
00536         I2CScl0,
00537         I2CScl1,
00538         I2CScl2,
00539 
00540         AnalogMuxEnable,
00541         AnalogMuxPwmOut,
00542         AnalogMuxIn,
00543         AnalogMuxAddr0,
00544         AnalogMuxAddr1,
00545         AnalogMuxAddr2,
00546         AnalogMuxAddr3,
00547         AnalogMuxAddr4,
00548         AnalogMuxAddr5,
00549         AnalogMuxAddr6,
00550         AnalogMuxAddr7,
00551 
00552         AnalogInP0,
00553         AnalogInP1,
00554         AnalogInP2,
00555         AnalogInP3,
00556         AnalogInN0,
00557         AnalogInN1,
00558         AnalogInN2,
00559         AnalogInN3,
00560 
00561         SystemPinCount
00562     };
00563 
00564     /**
00565      * Read from the given system pin
00566      *
00567      * @param pin The pin to read from
00568      * @return true if 1 was read, false if 0
00569      */
00570     bool sys_pin_read(SystemPin pin);
00571 
00572     /**
00573      * Write to the given system pin
00574      *
00575      * @param pin The pin to write to
00576      * @param value The value to output on the pin when driven
00577      * @param true to drive the output, false to set the output high-z
00578      * @return true if 1 was read, false if 0
00579      */
00580     void sys_pin_write(SystemPin pin, int value, bool drive);
00581 
00582     /**
00583      * I2C read on I2C system channels 0, 1, or 2
00584      *
00585      * @param i2c_index The number corresponding to the system i2c bus being used (0, 1, or 2)
00586      * @param dev_addr The I2C address of the device being read from
00587      * @param start_reg The internal device address where the read will start
00588      * @param data Data buffer for data to be read into
00589      * @param length The number of bytes to read
00590      * @return 0 on success (ACK), nonzero on failure (NACK)
00591      */
00592     int io_expander_i2c_read(uint8_t i2c_index, uint8_t dev_addr, uint8_t start_reg, uint8_t *data, int length);
00593 
00594     /**
00595      * I2C write on I2C system channels 0, 1, or 2
00596      *
00597      * @param i2c_index The number corresponding to the system i2c bus being used (0, 1, or 2)
00598      * @param dev_addr The I2C address of the device being written to
00599      * @param data The data to be written
00600      * @param length The number of bytes to be written
00601      * @return 0 on success (ACK), nonzero on failure (NACK)
00602      */
00603     int io_expander_i2c_write(uint8_t i2c_index, uint8_t dev_addr, uint8_t *data, int length);
00604 
00605     /**
00606      * I2C read on I2C system channels 0, 1, or 2
00607      * (bit banged version of function, bit banged over control channel)
00608      *
00609      * @param sda System pin used for sda
00610      * @param scl System pin used for scl
00611      * @param dev_addr The I2C address of the device being read from
00612      * @param start_reg The internal device address where the read will start
00613      * @param data Data buffer for data to be read into
00614      * @param length The number of bytes to read
00615      * @return 0 on success (ACK), nonzero on failure (NACK)
00616      */
00617     int io_expander_i2c_read_bb(SystemPin sda, SystemPin scl, uint8_t dev_addr, uint8_t start_reg, uint8_t *data, int length);
00618 
00619     /**
00620      * I2C write on I2C system channels 0, 1, or 2
00621      * (bit banged version of function, bit banged over control channel)
00622      *
00623      * @param sda System pin used for sda
00624      * @param scl System pin used for scl
00625      * @param dev_addr The I2C address of the device being written to
00626      * @param data The data to be written
00627      * @param length The number of bytes to be written
00628      * @return 0 on success (ACK), nonzero on failure (NACK)
00629      */
00630     int io_expander_i2c_write_bb(SystemPin sda, SystemPin scl, uint8_t dev_addr, uint8_t *data, int length);
00631 
00632     /**
00633      * Set the AnalogMuxAddr pins on the FPGA via PinName
00634      *
00635      * @param pin The Mbed pin that the analog signal will be routed to
00636      * @return 0 on success, nonzero on failure
00637      */
00638     int set_mux_addr(PinName pin);
00639 
00640     /**
00641      * Set the AnalogMuxAddr pins on the FPGA via pin index
00642      *
00643      * @param index The Mbed pin index that the analog signal will be routed to
00644      * @return 0 on success, nonzero on failure
00645      */
00646     int set_mux_addr_index(int index);
00647 
00648     /* **AnalogIn peripheral functions** */
00649 
00650     /**
00651      * Turn on/off the analog muxes
00652      *
00653      * @param val false: off, true: on
00654      */
00655     void set_mux_enable(bool val);
00656 
00657     /**
00658      * Turn on/off pwm output on FPGA to test Mbed AnalogIn
00659      *
00660      * @param val false: off, true: on
00661      */
00662     void set_pwm_enable(bool val);
00663 
00664     /**
00665      * Check if FPGA pwm out is on or off
00666      *
00667      * @return FPGA enable bit (false: off, true: on)
00668      */
00669     bool get_pwm_enable();
00670 
00671     /**
00672      * Set the pwm output period and number of cycles high (duty cycle) on the FPGA
00673      *
00674      * @param period In units of clk cycles
00675      * @param cycles_high In units of clk cycles
00676      */
00677     void set_pwm_period_and_cycles_high(uint32_t period, uint32_t cycles_high);
00678 
00679     /**
00680      * Get the pwm output period of the FPGA
00681      *
00682      * @return FPGA pwm output period in units of clk cycles
00683      */
00684     uint32_t get_pwm_period();
00685 
00686     /**
00687      * Get the number of cycles that are high (duty cycle) from FPGA pwm
00688      *
00689      * @return FPGA pwm output cycles high
00690      */
00691     uint8_t get_pwm_cycles_high();
00692 
00693     /**
00694      * Get the 12-bit analog to digital conversion result from the FPGA
00695      *
00696      * @return 12-bit FPGA ADC result for AnalogMuxIn
00697      */
00698     uint16_t get_analogmuxin_measurement();
00699 
00700     /**
00701      * Similar to 'get_analogmuxin_measurement' but returns the current XADC measurement for ANIN0-3
00702      *
00703      * @param index ANIN pin to read (0-3)
00704      * @return 12-bit FPGA ADC result for ANIN0-3
00705      */
00706     uint16_t get_anin_measurement(int index);
00707 
00708     /**
00709      * Gets (by reference) the sum of all ANIN ADC results for any of the 4 ANIN pins specified by the index,
00710      * number of ADC sample sequences that have completed since the XADC was turned on, and the number of FPGA clk cycles
00711      * that have taken place since the ADC was turned on.
00712      *
00713      * @param index ANIN pin of which to get sum of results (0-3)
00714      * @param sum The sum of all specified ANIN pin's ADC results
00715      * @param samples The number of ADC sample sequences that have completed since the XADC was turned on
00716      * @param cycles The number of FPGA clk cycles that have taken place since the ADC was turned on
00717      */
00718     void get_anin_sum_samples_cycles(int index, uint64_t *sum, uint32_t *samples, uint64_t *cycles);
00719 
00720     /**
00721      * Allows safe reading of FPGA ADC related values while the FPGA ADC is on
00722      * If snapshot is set then the ADC values will be safely latched in the FPGA and safe to read.
00723      * The RTL will set snapshot to 0 after 1 clk cycle.
00724      */
00725     void set_snapshot();
00726 
00727     /**
00728      * Set the current system pin mode to disabled
00729      *
00730      * This releases any pin mappings that were set by the previous pin mode.
00731      */
00732     void sys_pin_mode_disabled();
00733 
00734     /**
00735      * Set the current system pin mode to serial flash
00736      *
00737      * Remap physical pins to the serial flash the FPGA boots from.
00738      * This is used for firmware updates.
00739      *
00740      * @param mosi The physical pin index to connect to serial flash mosi
00741      * @param miso The physical pin index to connect to serial flash miso
00742      * @param clk The physical pin index to connect to serial flash clk
00743      * @param ssel The physical pin index to connect to serial flash cs
00744      */
00745     void sys_pin_mode_spi_serial_flash(PhysicalIndex mosi, PhysicalIndex miso, PhysicalIndex clk, PhysicalIndex ssel);
00746 
00747     /**
00748      * Set the current system pin mode to io expander I2C bus
00749      *
00750      * Remap physical pins to the io expander I2C bus. The IO expanders
00751      * are used for setting pullups and pulldowns.
00752      *
00753      * @param index The index of the I2C bus to connect to
00754      * @param sda_in Physical pin index for the FPGA to output the state of SDA on
00755      * @param sda_val Physical pin index for the FPGA to read SDA from. When in this mode the Mbed board
00756      *                must always drive this pin. Driving a 0 causes the FPGA to pull the SDA on the I2C bus low. Setting
00757      *                a 1 causes the FPGA to let SDA on the I2C bus float (and get pulled to 1).
00758      * @param scl_in Physical pin index for the FPGA to output the state of SCL on
00759      * @param scl_val Physical pin index for the FPGA to read SCL from. When in this mode the Mbed board
00760      *                must always drive this pin. Driving a 0 causes the FPGA to pull the SCL on the I2C bus low. Setting
00761      *                a 1 causes the FPGA to let SDA on the SCL bus float (and get pulled to 1).
00762      */
00763     void sys_pin_mode_i2c_io_expander(int index, PhysicalIndex sda_in, PhysicalIndex sda_val, PhysicalIndex scl_in, PhysicalIndex scl_val);
00764 
00765     /**
00766      * Map a physical pin index to the given logical pin
00767      *
00768      * This function will automatically move the control channel
00769      * pins to avoid interfering with the mapped pin. The physical
00770      * pin index does not need to be part of the form factor.
00771      *
00772      * @param physical_index Index of the physical pin on the board
00773      * @param logical Logical pin to map to
00774      */
00775     void pin_map_index(PhysicalIndex physical_index, LogicalPin logical);
00776 
00777 
00778     /* **Low level memory access** */
00779 
00780     /**
00781      * Write to tester memory
00782      *
00783      * @addr addr Address to write to
00784      * @param data Data to write
00785      * @param size Number of bytes to write
00786      */
00787     void write(uint32_t addr, const uint8_t *data, uint32_t size);
00788 
00789     /**
00790      * Read from tester memory
00791      *
00792      * @addr addr Address to read from
00793      * @param data Buffer to fill with data
00794      * @param size Number of bytes to read
00795      */
00796     void read(uint32_t addr, uint8_t *data, uint32_t size);
00797 
00798     /* **Self tests** */
00799 
00800     /**
00801      * Run all self tests
00802      *
00803      * @return true if all self tests pass, false otherwise
00804      */
00805     bool self_test_all();
00806 
00807     /**
00808      * Test that all allowed control channels can be used
00809      *
00810      * Check that all pairs of clk and mosi which aren't in
00811      * the restricted list can be used.
00812      *
00813      * @note CLK and MOSI lines are paired, where CLK is always
00814      * on an even index and MOSI is always on an oddd index:
00815      * clk_index_N = N * 2
00816      * mosi_index_N = N * 2 + 1
00817      *
00818      * @note This functions sets the control pin management mode
00819      * to automatic when it completes.
00820      *
00821      * @return true if all control channel pairs (clk and mosi) of this
00822      *         configuration can be used, false otherwise
00823      */
00824     bool self_test_control_channels();
00825 
00826     /**
00827      * Test that all allowed control miso lines can be used
00828      *
00829      * Check that every pin of this form factor aside from the
00830      * pins in the restricted list can be used as miso.
00831      *
00832      * @note This functions sets the control pin management mode
00833      * to automatic when it completes.
00834      *
00835      * @return true if all control channel miso lines of this
00836      *         configuration can be used, false otherwise
00837      */
00838     bool self_test_control_miso();
00839 
00840     /**
00841      * Test that the current control channel works
00842      *
00843      * @return true if communication is successful, false otherwise
00844      */
00845     bool self_test_control_current();
00846 
00847 private:
00848 
00849     /*
00850      * Find suitable control pins
00851      *
00852      * This function finds the appropriate set of pins and test to ensure that communication with
00853      * the FPGA can be performed over them. Before calling this function MbedTester pins must be
00854      * freed by calling MbedTester::_free_control_pins.
00855      *
00856      * @param clk_out Clock pin to find and set
00857      * @param mosi_out Mosi pin to find and set
00858      * @param miso_out Miso pin to find and set
00859      * @param aux_out Aux pin to find and set
00860      * @return true if all pins were found, false otherwise
00861      */
00862     bool _find_control_indexes(PhysicalIndex &clk_out, PhysicalIndex &mosi_out, PhysicalIndex &miso_out, PhysicalIndex &aux_out);
00863 
00864     /*
00865      * Allocate control pins
00866      *
00867      * The pin indexes must already have been found
00868      */
00869     void _setup_control_pins();
00870 
00871     /*
00872      * Free control pins
00873      *
00874      * This function is safe to call even if the pins have been freed
00875      */
00876     void _free_control_pins();
00877 
00878     /*
00879      * Update the control channel if needed
00880      *
00881      * Open a control channel using allowed pins:
00882      * - Pin must be in the form factor
00883      * - Pin must not be in the exclude list
00884      * - Pin must not be mapped already
00885      */
00886     void _update_control_pins();
00887 
00888     /*
00889      * Check if this control channel needs to be updated
00890      *
00891      * @return true if the control channel needs to be updated, false otherwise
00892      */
00893     bool _update_needed();
00894 
00895     /*
00896      * Reset the state of the MbedTester class
00897      *
00898      * This does not effect the state of the FPGA in any way.
00899      */
00900     void _reset();
00901 
00902     PhysicalIndex _mapping[LogicalPinCount * (LogicalPinBanks + 1)];
00903     DynamicPinList _form_factor;
00904     DynamicPinList _exclude_pins;
00905     bool _control_auto;
00906     bool _control_valid;
00907     PhysicalIndex _clk_index;
00908     PhysicalIndex _mosi_index;
00909     PhysicalIndex _miso_index;
00910     PhysicalIndex _aux_index;
00911     mbed::DigitalInOut *_clk;
00912     mbed::DigitalInOut *_mosi;
00913     mbed::DigitalInOut *_miso;
00914     mbed::DigitalInOut *_aux;
00915     /*
00916      * Used to reset IO expander chips only once the first time
00917      * any IO expander is accessed as well as during an io_exp_test
00918      */
00919     int _init_io_exp_rst_flag;
00920 };
00921 
00922 #endif