Mbed OS Reference | MbedTester.h Source File

 /*
  * Copyright (c) 2019, Arm Limited and affiliates.
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 #ifndef MBED_TESTER_H
 #define MBED_TESTER_H
 
 #include "DynamicPinList.h"
 #include "platform/FileHandle.h"
 #include "platform/Callback.h"
 #include "drivers/DigitalInOut.h"
 
 /**
  * The base class for controlling the FPGA CI Test Shield
  *
  * This is the primary interface to the FPGA CI Test Shield. It contains
  * all the code to communicate with the FPGA. It also provides high level
  * helper functions, such as functions to setup pin multiplexing, to
  * select the currently active peripheral and to perform software updates.
  *
  * Subclasses can inherit from this class and provide further functionality,
  * such as the ability to test SPI.
  *
  * @note Synchronization level: Not protected
  *
  * Example of how to toggle Arduino pin D6 from the FPGA cI Test Shield:
  * @code
  * #include "mbed.h"
  * #include "MbedTester.h"
  *
  * const PinList *form_factor = pinmap_ff_default_pins();
  * const PinList *restricted = pinmap_restricted_pins();
  * MbedTester tester(form_factor, restricted);
  *
  * int main() {
  *     // Reset the FPGA CI Test Shield to put it into a known state
  *     tester.reset();
  *
  *     // Select the GPIO peripheral
  *     tester.select_peripheral(MbedTester::PeripheralGPIO);
  *
  *     // Map D6 to LogicalPinGPIO0
  *     tester.pin_map_set(D6, MbedTester::LogicalPinGPIO0);
  *
  *     // Toggle pin D6
  *     int toggle = 0;
  *     while (1) {
  *         tester.gpio_write(MbedTester::LogicalPinGPIO0, toggle, true);
  *         wait(0.5);
  *         toggle = !toggle;
  *     }
  * }
  * @endcode
  */
 class MbedTester {
 public:
 
     /*
      * This type represents the index of a physical pin on the FPGA.
      * This can be any value from 0 to 127. A form factor is used to
      * map a PinName to a physical pin index.
      */
     typedef uint8_t PhysicalIndex;
 
     /*
      * There are 8 logical pins connected to the peripherals inside the FPGA.
      * These are logical pins 0 through 7. All peripherals can read from these
      * pins and the currently active peripheral can output on these pins.
      *
      * Each logical pin has a fixed function for a given peripheral which is
      * why the same value is defined multiple times. For example logical pin
      * 2 is SPI clock (SPISclk) when SPI is the active peripheral and
      * UART clear to send (UARTCts) when UART is the active peripheral.
      *
      * A logic pin can be mapped to any physical pin (PinName type) by calling
      * the function MbedTester::pin_map_set.
      */
     enum LogicalPin {
 
         LogicalPinGPIO0 = 0,
         LogicalPinGPIO1 = 1,
         LogicalPinGPIO2 = 2,
         LogicalPinGPIO3 = 3,
         LogicalPinGPIO4 = 4,
         LogicalPinGPIO5 = 5,
         LogicalPinGPIO6 = 6,
         LogicalPinGPIO7 = 7,
 
         LogicalPinSPIMosi = 0,
         LogicalPinSPIMiso = 1,
         LogicalPinSPISclk = 2,
         LogicalPinSPISsel = 3,
 
         LogicalPinIOMetrics0 = 0,
         LogicalPinIOMetrics1 = 1,
         LogicalPinIOMetrics2 = 2,
         LogicalPinIOMetrics3 = 3,
         LogicalPinIOMetrics4 = 4,
         LogicalPinIOMetrics5 = 5,
         LogicalPinIOMetrics6 = 6,
         LogicalPinIOMetrics7 = 7,
 
         LogicalPinUARTTx = 0,
         LogicalPinUARTRx = 1,
         LogicalPinUARTCts = 2,
         LogicalPinUARTRts = 3,
 
         LogicalPinI2CSda = 0,
         LogicalPinI2CScl = 1,
 
         LogicalPinCount = 8,
         LogicalPinBanks = 2,
         LogicalPinTotal = LogicalPinCount * LogicalPinBanks
     };
 
     /*
      * These are the peripherals internal to the FPGA. A peripheral can be
      * selected by calling MbedTester::select_peripheral.
      */
     enum Peripheral {
         PeripheralGPIO = 1,
         PeripheralSPI = 2,
         PeripheralUART = 4,
         PeripheralI2C = 5,
         PeripheralSPISlave = 6
     };
 
     /**
      * Construct a new MbedTester object
      *
      * The form factor pins passed into this class must match the
      * physical MbedTester shield connected to this board or testing
      * will not work correctly. The order of pins in this list must
      * match the order of the shield.
      *
      * The exclude pins list should be used to exclude pins which you either
      * don't want to be tested or are not suitable for use as a control
      * channel. This list is allowed to contain pins that are not in the
      * form factor.
      *
      * @param form_factor The pins that are available on this form factor
      * @param exclude_pins The pins that must not be used
      */
     MbedTester(const PinList *form_factor, const PinList *exclude_pins);
 
     /**
      * Destroy and cleanup resources associated with this object
      */
     ~MbedTester();
 
     /**
      * Enable automatic selection and update of control pins
      *
      * Calling this function configures MbedTester to automatically select
      * and update the control pins. The control pins are moved if the
      * function MbedTester::pin_map_set is called and maps a pin that is being used
      * for control.
      *
      * @note Automatic selection and update of control pins is the default.
      * Unless MbedTester::set_control_pins_manual has been called to manually
      * set the control pins this function has no effect.
      */
     void set_control_pins_auto();
 
     /**
      * Set the control pins to use for communication
      *
      * Manually set the control pins. Calling this function
      * disables automatic control pin selection and updates.
      * The function MbedTester::pin_map_set must not be used to map over
      * control pins when in this mode.
      *
      * @param clk Clock pin to use as the control channel
      * @param mosi Mosi pin to use as the control channel
      * @param miso Miso pin to use as the control channel
      * @param aux Auxillary pin to use as the control cannel
      */
     void set_control_pins_manual(PinName clk, PinName mosi, PinName miso, PinName aux);
 
     /**
      * Read FPGA CI Test Shield firmware
      *
      * Read the firmware on the FPGA CI Test Shield. An optional progress callback
      * can be supplied to display progress while the firmware is being read.
      *
      * @param dest File to write the firmware to. This file must have been opened as writeable
      * @param progress Optional progress callback called when the percent complete changes
      * @return true if firmware was successfully read, false otherwise
      */
     bool firmware_dump(mbed::FileHandle *dest, mbed::Callback<void(uint8_t)> progress = mbed::Callback<void(uint8_t)>());
 
     /**
      * Read FPGA CI Test Shield flash
      *
      * Read the entire flash contents of the FPGA CI Test Shield. An optional progress callback
      * can be supplied to display progress while the firmware is being read.
      *
      * @param dest File to write the firmware to. This file must have been opened as writeable
      * @param progress Optional progress callback called when the percent complete changes
      * @return true if firmware was successfully read, false otherwise
      */
     bool firmware_dump_all(mbed::FileHandle *dest, mbed::Callback<void(uint8_t)> progress = mbed::Callback<void(uint8_t)>());
 
     /**
      * Program new FPGA CI Test Shield firmware
      *
      * Program firmware from the file given. The binary bitstream must be in the correct format
      * and contain a correct CRC or the update will fail. To correctly format a bitstream binary
      * the post_process_bitstream.py script in the fpga-ci-test-shield repository should be used.
      *
      * Note - release binaries for the FPGA CI Test Shield have already been formatted and
      *        can be loaded directly with this function
      *
      * @param src File containing the new firmware to program
      * @param progress Optional progress callback called when the percent complete changes
      * @return true if firmware was successfully applied, false otherwise
      */
     bool firmware_update(mbed::FileHandle *src, mbed::Callback<void(uint8_t)> progress = mbed::Callback<void(uint8_t)>());
 
     /**
      * Map a physical pin to the given logical pin
      *
      * This function will automatically move the control channel
      * pins to avoid interfering with the mapped pin.
      *
      * @param physical Physical pin on the board
      * @param logical Logical pin to map to
      */
     void pin_map_set(PinName physical, LogicalPin logical);
 
     /**
      * Reset all pin mappings
      *
      * After this call all pins will be unmapped
      */
     void pin_map_reset();
 
     /**
      * Reset all peripherals
      *
      * This does not reset the pin mappings
      */
     void peripherals_reset();
 
     /**
      * Reset everything
      *
      * This function resets the state of both the FPGA CI Test Shield
      * and the MbedTester object itself.
      *
      * Reset effects on the FPGA CI Test Shield include:
      * - All pins are tristated
      * - All pin mappings are reset
      * - All pullup/pulldown settings are reset
      * - All peripherals are reset
      *
      * Reset effects on the MbedTester object include
      * - Control channels tristated and freed
      * - Control channel selection set to automatic
      * - Most internal state reinitialized
      */
     void reset();
 
     /**
      * Reprogram the FPGA
      *
      * This function causes the FPGA to reboot and reload RAM contents.
      * This should be used after MbedTester::firmware_update to load the
      * new image.
      */
     void reprogram();
 
     /**
      * Get the running FPGA firmware version
      *
      * @return The version of firmware running on the FPGA.
      *
      */
     uint32_t version();
 
     /**
      * Select the currently active peripheral
      *
      * @param peripheral Active peripheral
      */
     void select_peripheral(Peripheral peripheral);
 
     /* **GPIO peripheral functions** */
 
     /**
      * Read a gpio pin
      *
      * @param gpio Logical pin to read from
      * @return 1 if the pin is high 0 if the pin is low
      */
     int gpio_read(LogicalPin gpio);
 
     /**
      * Set value and drive of a gpio pin
      *
      * @param gpio Logical pin to write to
      * @param value 0 to set the pin low or non-zero to set it high
      * @param driver 0 to set the pin to Hi-Z or non-zero to drive the pin
      */
     void gpio_write(LogicalPin gpio, int value, bool drive);
 
     /* **IO Metrics functions** */
 
     /**
      * Start recording metrics on all logical pins
      *
      * This function resets all past metrics to 0. To
      * preserve these call io_metrics_continue instead.
      */
     void io_metrics_start();
 
     /**
      * Stop recording metrics on all logical pins
      *
      * This function should be called before any metrics
      * are read to ensure the value does not change while
      * they are being read.
      */
     void io_metrics_stop();
 
     /**
      * Continue recording metrics on all logical pins
      *
      * Resume recording metrics.
      */
     void io_metrics_continue();
 
     /**
      * Get the shortest low pulse recorded
      *
      * @param pin Pin to read the metrics for
      * @return The shortest number of 100MHz clock cycles the pin was low
      */
     uint32_t io_metrics_min_pulse_low(LogicalPin pin);
 
     /**
      * Get the shortest high pulse recorded
      *
      * @param pin Pin to read the metrics for
      * @return The shortest number of 100MHz clock cycles the pin was high
      */
     uint32_t io_metrics_min_pulse_high(LogicalPin pin);
 
     /**
      * Get the longest low pulse recorded
      *
      * @param pin Pin to read the metrics for
      * @return The longest number of 100MHz clock cycles the pin was low
      */
     uint32_t io_metrics_max_pulse_low(LogicalPin pin);
 
     /**
      * Get the longest high pulse recorded
      *
      * @param pin Pin to read the metrics for
      * @return The longest number of 100MHz clock cycles the pin was high
      */
     uint32_t io_metrics_max_pulse_high(LogicalPin pin);
 
     /**
      * Get the number of rising edges
      *
      * @param pin Pin to read the metrics for
      * @return The number of rising edges
      */
     uint32_t io_metrics_rising_edges(LogicalPin pin);
 
     /**
      * Get the number of falling edges
      *
      * @param pin Pin to read the metrics for
      * @return The number of falling edges
      */
     uint32_t io_metrics_falling_edges(LogicalPin pin);
 
     /**
      * Reset the IO expander modules
      *
      */
     void pin_pull_reset_all();
 
     /**
      * FPGA Pullup mode
      */
     enum PullMode {
         PullUp,
         PullDown,
         PullNone
     };
 
     /**
      * Configure an Mbed pin for a pulldown resistor, pullup resistor, or tristate mode via PinName
      *
      * @param pin Mbed pin whose mode is being set
      * @param mode (MbedTester::PullUp, MbedTester::PullDown, or MbedTester::PullNone)
      * @return 0 on success, nonzero on failure
      */
     int pin_set_pull(PinName pin, PullMode mode);
 
     /**
      * Configure an Mbed pin for a pulldown resistor, pullup resistor, or tristate mode via pin index
      *
      * @param index Mbed pin index whose mode is being set
      * @param mode (MbedTester::PullUp, MbedTester::PullDown, or MbedTester::PullNone)
      * @return 0 on success, nonzero on failure
      */
     int pin_set_pull_index(int index, PullMode mode);
 
     /*
      * Register of the IO expander
      */
     enum IOExpanderReg {
         RegInput,
         RegOutput,
         RegConfig
     };
 
     /**
      * 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
      *
      * @param pin Mbed pin whose register bit is being read
      * @param reg_type Pin register to access, options are: MbedTester::RegInput, MbedTester::RegOutput, or MbedTester::RegConfig
      * @return The value of the bit read
      */
     uint8_t io_expander_read(PinName pin, IOExpanderReg reg_type);
 
     /**
      * 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
      *
      * @param index Mbed pin index whose register bit is being read
      * @param reg_type Pin register to access, options are: MbedTester::RegInput, MbedTester::RegOutput, or MbedTester::RegConfig
      * @return The value of the bit read
      */
     uint8_t io_expander_read_index(int index, IOExpanderReg reg_type);
 
     /**
      * Configure an Mbed pin for a pulldown resistor, pullup resistor, or tristate mode
      * (this version of the function uses io_expander_i2c_read_bb and io_expander_i2c_write_bb)
      *
      * @param pin Mbed pin whose mode is being set
      * @param mode (MbedTester::PullUp, MbedTester::PullDown, or MbedTester::PullNone)
      * @return 0 on success, nonzero on failure
      */
     int pin_set_pull_bb(PinName pin, PullMode mode);
 
     /**
      * Read a bit for a specific Mbed pin that is set in the input, output, or configuration registers inside of the IO expander
      * (this version of the function uses io_expander_i2c_read_bb)
      *
      * @param pin Mbed pin whose register bit is being read
      * @param reg_type Pin register to access, options are: MbedTester::RegInput, MbedTester::RegOutput, or MbedTester::RegConfig
      * @return The value of the bit read
      */
     uint8_t io_expander_read_bb(PinName pin, IOExpanderReg reg_type);
 
     /**
      * Create an analog voltage via the FPGA sys pwm in order to test Mbed AnalogIn
      *
      * @param enable Enable the FPGA system PWM (false: of, true: on)
      * @param voltage The analog voltage that will be created by the FPGA CI test shield (float: 0.0 to 1.0)
      */
     void set_analog_out(bool enable, float voltage);
 
     /**
      * Turn the FPGA ADC on and off (power management data will be collected while the ADC is on)
      *
      * @param val FPGA ADC enable bit (false: off, true: on)
      */
     void set_sample_adc(bool val);
 
     /**
      * 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.
      *
      * @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
      */
     float get_analog_in();
 
     /**
      * Similar to 'get_analog_in' but returns a voltage reading from ANIN0-3
      *
      * @param index ANIN pin to read (0-3)
      * @return The conversion result in the form of a voltage measurement for ANIN0-3
      */
     float get_anin_voltage(int index);
 
     /* **Mid level system access** */
 
     /*
      * These are the pins on the FPGA that are not connected to the Mbed board.
      * These can be controlled by using MbedTester::sys_pin_read and MbedTester::sys_pin_write.
      * These should not be used directly when using the FPGA CI Test Shield. The higher layer
      * APIs should be used instead.
      */
     enum SystemPin {
         Reset,
         Reprogram,
 
         DigitalID0,
         DigitalID1,
         DigitalID2,
 
         Led0,
         Led1,
         Led2,
         Led3,
 
         SPIIO0,
         SPIIO1,
         SPIIO2,
         SPIIO3,
         SPIClk,
         SPICS,
 
         I2CReset,
         I2CSda0,
         I2CSda1,
         I2CSda2,
         I2CScl0,
         I2CScl1,
         I2CScl2,
 
         AnalogMuxEnable,
         AnalogMuxPwmOut,
         AnalogMuxIn,
         AnalogMuxAddr0,
         AnalogMuxAddr1,
         AnalogMuxAddr2,
         AnalogMuxAddr3,
         AnalogMuxAddr4,
         AnalogMuxAddr5,
         AnalogMuxAddr6,
         AnalogMuxAddr7,
 
         AnalogInP0,
         AnalogInP1,
         AnalogInP2,
         AnalogInP3,
         AnalogInN0,
         AnalogInN1,
         AnalogInN2,
         AnalogInN3,
 
         SystemPinCount
     };
 
     /**
      * Read from the given system pin
      *
      * @param pin The pin to read from
      * @return true if 1 was read, false if 0
      */
     bool sys_pin_read(SystemPin pin);
 
     /**
      * Write to the given system pin
      *
      * @param pin The pin to write to
      * @param value The value to output on the pin when driven
      * @param true to drive the output, false to set the output high-z
      * @return true if 1 was read, false if 0
      */
     void sys_pin_write(SystemPin pin, int value, bool drive);
 
     /**
      * I2C read on I2C system channels 0, 1, or 2
      *
      * @param i2c_index The number corresponding to the system i2c bus being used (0, 1, or 2)
      * @param dev_addr The I2C address of the device being read from
      * @param start_reg The internal device address where the read will start
      * @param data Data buffer for data to be read into
      * @param length The number of bytes to read
      * @return 0 on success (ACK), nonzero on failure (NACK)
      */
     int io_expander_i2c_read(uint8_t i2c_index, uint8_t dev_addr, uint8_t start_reg, uint8_t *data, int length);
 
     /**
      * I2C write on I2C system channels 0, 1, or 2
      *
      * @param i2c_index The number corresponding to the system i2c bus being used (0, 1, or 2)
      * @param dev_addr The I2C address of the device being written to
      * @param data The data to be written
      * @param length The number of bytes to be written
      * @return 0 on success (ACK), nonzero on failure (NACK)
      */
     int io_expander_i2c_write(uint8_t i2c_index, uint8_t dev_addr, uint8_t *data, int length);
 
     /**
      * I2C read on I2C system channels 0, 1, or 2
      * (bit banged version of function, bit banged over control channel)
      *
      * @param sda System pin used for sda
      * @param scl System pin used for scl
      * @param dev_addr The I2C address of the device being read from
      * @param start_reg The internal device address where the read will start
      * @param data Data buffer for data to be read into
      * @param length The number of bytes to read
      * @return 0 on success (ACK), nonzero on failure (NACK)
      */
     int io_expander_i2c_read_bb(SystemPin sda, SystemPin scl, uint8_t dev_addr, uint8_t start_reg, uint8_t *data, int length);
 
     /**
      * I2C write on I2C system channels 0, 1, or 2
      * (bit banged version of function, bit banged over control channel)
      *
      * @param sda System pin used for sda
      * @param scl System pin used for scl
      * @param dev_addr The I2C address of the device being written to
      * @param data The data to be written
      * @param length The number of bytes to be written
      * @return 0 on success (ACK), nonzero on failure (NACK)
      */
     int io_expander_i2c_write_bb(SystemPin sda, SystemPin scl, uint8_t dev_addr, uint8_t *data, int length);
 
     /**
      * Set the AnalogMuxAddr pins on the FPGA via PinName
      *
      * @param pin The Mbed pin that the analog signal will be routed to
      * @return 0 on success, nonzero on failure
      */
     int set_mux_addr(PinName pin);
 
     /**
      * Set the AnalogMuxAddr pins on the FPGA via pin index
      *
      * @param index The Mbed pin index that the analog signal will be routed to
      * @return 0 on success, nonzero on failure
      */
     int set_mux_addr_index(int index);
 
     /* **AnalogIn peripheral functions** */
 
     /**
      * Turn on/off the analog muxes
      *
      * @param val false: off, true: on
      */
     void set_mux_enable(bool val);
 
     /**
      * Turn on/off pwm output on FPGA to test Mbed AnalogIn
      *
      * @param val false: off, true: on
      */
     void set_pwm_enable(bool val);
 
     /**
      * Check if FPGA pwm out is on or off
      *
      * @return FPGA enable bit (false: off, true: on)
      */
     bool get_pwm_enable();
 
     /**
      * Set the pwm output period and number of cycles high (duty cycle) on the FPGA
      *
      * @param period In units of clk cycles
      * @param cycles_high In units of clk cycles
      */
     void set_pwm_period_and_cycles_high(uint32_t period, uint32_t cycles_high);
 
     /**
      * Get the pwm output period of the FPGA
      *
      * @return FPGA pwm output period in units of clk cycles
      */
     uint32_t get_pwm_period();
 
     /**
      * Get the number of cycles that are high (duty cycle) from FPGA pwm
      *
      * @return FPGA pwm output cycles high
      */
     uint8_t get_pwm_cycles_high();
 
     /**
      * Get the 12-bit analog to digital conversion result from the FPGA
      *
      * @return 12-bit FPGA ADC result for AnalogMuxIn
      */
     uint16_t get_analogmuxin_measurement();
 
     /**
      * Similar to 'get_analogmuxin_measurement' but returns the current XADC measurement for ANIN0-3
      *
      * @param index ANIN pin to read (0-3)
      * @return 12-bit FPGA ADC result for ANIN0-3
      */
     uint16_t get_anin_measurement(int index);
 
     /**
      * Gets (by reference) the sum of all ANIN ADC results for any of the 4 ANIN pins specified by the index,
      * number of ADC sample sequences that have completed since the XADC was turned on, and the number of FPGA clk cycles
      * that have taken place since the ADC was turned on.
      *
      * @param index ANIN pin of which to get sum of results (0-3)
      * @param sum The sum of all specified ANIN pin's ADC results
      * @param samples The number of ADC sample sequences that have completed since the XADC was turned on
      * @param cycles The number of FPGA clk cycles that have taken place since the ADC was turned on
      */
     void get_anin_sum_samples_cycles(int index, uint64_t *sum, uint32_t *samples, uint64_t *cycles);
 
     /**
      * Allows safe reading of FPGA ADC related values while the FPGA ADC is on
      * If snapshot is set then the ADC values will be safely latched in the FPGA and safe to read.
      * The RTL will set snapshot to 0 after 1 clk cycle.
      */
     void set_snapshot();
 
     /**
      * Set the current system pin mode to disabled
      *
      * This releases any pin mappings that were set by the previous pin mode.
      */
     void sys_pin_mode_disabled();
 
     /**
      * Set the current system pin mode to serial flash
      *
      * Remap physical pins to the serial flash the FPGA boots from.
      * This is used for firmware updates.
      *
      * @param mosi The physical pin index to connect to serial flash mosi
      * @param miso The physical pin index to connect to serial flash miso
      * @param clk The physical pin index to connect to serial flash clk
      * @param ssel The physical pin index to connect to serial flash cs
      */
     void sys_pin_mode_spi_serial_flash(PhysicalIndex mosi, PhysicalIndex miso, PhysicalIndex clk, PhysicalIndex ssel);
 
     /**
      * Set the current system pin mode to io expander I2C bus
      *
      * Remap physical pins to the io expander I2C bus. The IO expanders
      * are used for setting pullups and pulldowns.
      *
      * @param index The index of the I2C bus to connect to
      * @param sda_in Physical pin index for the FPGA to output the state of SDA on
      * @param sda_val Physical pin index for the FPGA to read SDA from. When in this mode the Mbed board
      *                must always drive this pin. Driving a 0 causes the FPGA to pull the SDA on the I2C bus low. Setting
      *                a 1 causes the FPGA to let SDA on the I2C bus float (and get pulled to 1).
      * @param scl_in Physical pin index for the FPGA to output the state of SCL on
      * @param scl_val Physical pin index for the FPGA to read SCL from. When in this mode the Mbed board
      *                must always drive this pin. Driving a 0 causes the FPGA to pull the SCL on the I2C bus low. Setting
      *                a 1 causes the FPGA to let SDA on the SCL bus float (and get pulled to 1).
      */
     void sys_pin_mode_i2c_io_expander(int index, PhysicalIndex sda_in, PhysicalIndex sda_val, PhysicalIndex scl_in, PhysicalIndex scl_val);
 
     /**
      * Map a physical pin index to the given logical pin
      *
      * This function will automatically move the control channel
      * pins to avoid interfering with the mapped pin. The physical
      * pin index does not need to be part of the form factor.
      *
      * @param physical_index Index of the physical pin on the board
      * @param logical Logical pin to map to
      */
     void pin_map_index(PhysicalIndex physical_index, LogicalPin logical);
 
 
     /* **Low level memory access** */
 
     /**
      * Write to tester memory
      *
      * @addr addr Address to write to
      * @param data Data to write
      * @param size Number of bytes to write
      */
     void write(uint32_t addr, const uint8_t *data, uint32_t size);
 
     /**
      * Read from tester memory
      *
      * @addr addr Address to read from
      * @param data Buffer to fill with data
      * @param size Number of bytes to read
      */
     void read(uint32_t addr, uint8_t *data, uint32_t size);
 
     /* **Self tests** */
 
     /**
      * Run all self tests
      *
      * @return true if all self tests pass, false otherwise
      */
     bool self_test_all();
 
     /**
      * Test that all allowed control channels can be used
      *
      * Check that all pairs of clk and mosi which aren't in
      * the restricted list can be used.
      *
      * @note CLK and MOSI lines are paired, where CLK is always
      * on an even index and MOSI is always on an oddd index:
      * clk_index_N = N * 2
      * mosi_index_N = N * 2 + 1
      *
      * @note This functions sets the control pin management mode
      * to automatic when it completes.
      *
      * @return true if all control channel pairs (clk and mosi) of this
      *         configuration can be used, false otherwise
      */
     bool self_test_control_channels();
 
     /**
      * Test that all allowed control miso lines can be used
      *
      * Check that every pin of this form factor aside from the
      * pins in the restricted list can be used as miso.
      *
      * @note This functions sets the control pin management mode
      * to automatic when it completes.
      *
      * @return true if all control channel miso lines of this
      *         configuration can be used, false otherwise
      */
     bool self_test_control_miso();
 
     /**
      * Test that the current control channel works
      *
      * @return true if communication is successful, false otherwise
      */
     bool self_test_control_current();
 
 private:
 
     /*
      * Find suitable control pins
      *
      * This function finds the appropriate set of pins and test to ensure that communication with
      * the FPGA can be performed over them. Before calling this function MbedTester pins must be
      * freed by calling MbedTester::_free_control_pins.
      *
      * @param clk_out Clock pin to find and set
      * @param mosi_out Mosi pin to find and set
      * @param miso_out Miso pin to find and set
      * @param aux_out Aux pin to find and set
      * @return true if all pins were found, false otherwise
      */
     bool _find_control_indexes(PhysicalIndex &clk_out, PhysicalIndex &mosi_out, PhysicalIndex &miso_out, PhysicalIndex &aux_out);
 
     /*
      * Allocate control pins
      *
      * The pin indexes must already have been found
      */
     void _setup_control_pins();
 
     /*
      * Free control pins
      *
      * This function is safe to call even if the pins have been freed
      */
     void _free_control_pins();
 
     /*
      * Update the control channel if needed
      *
      * Open a control channel using allowed pins:
      * - Pin must be in the form factor
      * - Pin must not be in the exclude list
      * - Pin must not be mapped already
      */
     void _update_control_pins();
 
     /*
      * Check if this control channel needs to be updated
      *
      * @return true if the control channel needs to be updated, false otherwise
      */
     bool _update_needed();
 
     /*
      * Reset the state of the MbedTester class
      *
      * This does not effect the state of the FPGA in any way.
      */
     void _reset();
 
     PhysicalIndex _mapping[LogicalPinCount * (LogicalPinBanks + 1)];
     DynamicPinList _form_factor;
     DynamicPinList _exclude_pins;
     bool _control_auto;
     bool _control_valid;
     PhysicalIndex _clk_index;
     PhysicalIndex _mosi_index;
     PhysicalIndex _miso_index;
     PhysicalIndex _aux_index;
     mbed::DigitalInOut *_clk;
     mbed::DigitalInOut *_mosi;
     mbed::DigitalInOut *_miso;
     mbed::DigitalInOut *_aux;
     /*
      * Used to reset IO expander chips only once the first time
      * any IO expander is accessed as well as during an io_exp_test
      */
     int _init_io_exp_rst_flag;
 };
 
 #endif
Important Information for this Arm website
