SPI WinRT IO Transfer Tests (mbed LPC1768 Required)

  • Article

The SPI tests do functional and stress testing of SPI controllers exposed to usermode through the Windows.Devices.Spi WinRT APIs. The scope of testing includes:

  • Verification that an SPI controller with specified friendly name is accessible from usermode.
  • Verification that data is sent and received correctly over a range of SPI modes, clock frequencies, data bit lengths, and transfer lengths.
  • Verification there are no gaps between bytes within a transfer. Some devices such as LED strips and analog to digital converters require an uninterrupted clock signal.
  • Verification that the actual clock speed used is within 15% of the requested value.
  • Verification that when a transfer is attempted with a buffer length that is not a multiple of the stride, the transfer is failed with STATUS_INVALID_PARAMETER and no activity is generated on the bus. The stride is determined by DataBitLength as follows:
   
DataBitLength Stride
4 - 8 1
9 - 16 2
17 - 32 4

Tests run against an externally connected mbed LPC1768. The mbed LPC1768 is a popular microcontroller prototyping platform that can be purchased from a variety of online retailers including Sparkfun, Digikey, and Adafruit. Programming the mbed with the test firmware image is as simple as dragging and dropping the firmware image to the mass storage device. The firmware source code is available on github. Detailed instructions on preparing the mbed and running the tests are provided below.

Test details

   
Specifications
  • Device.BusController.SPI.WinRT.Discretional
Platforms
    Supported Releases
    • Windows 10
    • Windows 10, version 1511
    • Windows 10, version 1607
    • Windows 10, version 1703
    • Windows 10, version 1709
    • Windows 10, version 1803
    • Windows 10, version 1809
    • Windows 10, version 1903
    • Next update to Windows 10
    Expected run time (in minutes) 15
    Category Development
    Timeout (in minutes) 30
    Requires reboot false
    Requires special configuration true
    Type automatic

     

    Additional documentation

    Tests in this feature area might have additional documentation, including prerequisites, setup, and troubleshooting information, that can be found in the following topic(s):

    Running the test

    You will need the following hardware to run the tests:

    First, you must load the test firmware onto the mbed:

    1. Plug in the mbed LPC1768 over USB to your PC. It will show up as a removable drive on your PC.
    2. Open the drive in file explorer
    3. Copy c:\Program Files (x86)\Windows Kits\10\Hardware Lab Kit\Tests\x86\iot\busses-tester-mbed_LPC1768.bin to the drive
    4. Press the button on the mbed to reset the microcontroller

    Next, wire up the mbed to your SPI controller under test. To power the mbed, you can plug it in over USB to your device under test or connect the VIN and GND pins directly to power pins on your device under test. Make the following connections between your device under test and the mbed: (mbed pinout),

    1. Connect mbed pin 13 (P0.15/SCK0) to the SCK pin on your device under test
    2. Connect mbed pin 30 (P0.4/CAP2.0) to the SCK pin on your device under test (this pin is used for precise clock measurement)
    3. Connect mbed pin 11 (P0.18/MOSI0) to the MOSI pin on your device under test
    4. Connect mbed pin 12 (P0.17/MISO0) to the MISO pin on your device under test
    5. Connect mbed pin 14 (P0.16/SSEL0) to the Chip Select pin on your device under test
    6. Connect mbed GND to a GND pin on your device under test

    You can now schedule the tests in HLK studio.

    Troubleshooting

    For generic troubleshooting of HLK test failures, see Troubleshooting Windows HLK Test Failures.

    We recommend running the tests on the command line to gain insight into failures and to quickly iterate on solutions. We also recommend hooking up a logic analyzer such as a salae. It can be difficult or impossible to determine the cause of a failure without the ability to inspect bus traffic.

    Here's how to run the tests on the command line:

    1. Copy %programfiles(x86)%\Windows Kits\10\Testing\Runtimes\TAEF\<arch>\MinTe to c:\data\minte

    2. Copy Windows.Devices.LowLevel.UnitTests.dll from %programfiles(x86)%\Windows Kits\10\Hardware Lab Kit\Tests\<arch>\iot to c:\data on your device.

    3. Telnet or ssh into your device

    4. Change directories to c:\data

    5. Run the tests:

      minte\te windows.devices.lowlevel.unittests.dll /name:SpiHlk*

    Command line test usage:

    minte\te windows.devices.lowlevel.unittests.dll [/name:test_name] [/p:SpiFriendlyName=friendly_name] [/p:ClockFrequency=clock_frequency] [/p:DataBitLength=data_bit_length] [/p:SpiMode=0|1|2|3] [/p:Length=length] [/p:WriteLength=write_length] [/p:ReadLength=read_length] [/p:ExtraClocks=extra_clocks] [/p:Verbose=true]
    • test_name - the name of the test to run which may include wildcards. Examples: /name:SpiHlk*, /name:SpiHlkTests::VerifyClockFrequency#metadataSet0
    • friendly_name - the friendly name of the SPI controller under test. If omitted, the first enumerated controller is used. Examples: /p:SpiFriendlyName=SPI1
    • clock_frequency - force a test to use the specified clock frequency. By default, the clock frequency comes from the test data, which is designed to give coverage over a range of frequencies. This parameter should be omitted under normal circumstances. Example: /p:ClockFrequency=1500000
    • data_bit_length - force a test to use the specified data bit length. Example: /p:DataBitLength=9
    • SpiMode - force a test to use the specified SPI mode. Example: /p:SpiMode=2
    • length - force a test to use the specified buffer length for the transfer. Example: /p:length=128
    • write_length - force a TransferSequential test to use the specified buffer length for the write portion of the transfer. Example: /p:WriteLength=8
    • read_length - force a TransferSequential test to use the specified buffer length for the read portion of the transfer. Example: /p:ReadLength=16
    • extra_clocks - specify an adjustment to the number of clocks per byte that the tests use when computing expected clock active times for performance measurements, gap detection, and clock frequency validation. For example, the BCM2836 SPI controller waits an extra clock cycle after each byte, so to compensate for this behavior the measurements must be adjusted. Example: /p:ExtraClocks=1.5
    • /p:Verbose=true - turn on verbose output. This will cause entire buffers to be dumped to the console when a failure occurs. By default, only the first mismatched byte is displayed.

    Examples:

    List available tests:

    minte\te windows.devices.lowlevel.unittests.dll /list

    Run the IO validation tests:

    minte\te windows.devices.lowlevel.unittests.dll /name:SpiHlkIoTests*

    Run the gap detection tests:

    minte\te windows.devices.lowlevel.unittests.dll /name:SpiHlkGapTests*

    Run the clock frequency validation and stride tests:

    minte\te windows.devices.lowlevel.unittests.dll /name:SpiHlkTests*

    Run a specific test against a specific SPI controller instance:

    minte\te windows.devices.lowlevel.unittests.dll /name:SpiHlkIoTests#2::VerifyTransferSequential#metadataSet9 /p:SpiFriendlyName=SPI1

    A tool that can help with manual troubleshooting is SpiTestTool. SpiTestTool is a simple utility for interacting with SPI from the command line.

    More information

    Parameters

    Parameter name Parameter description
    SpiFriendlyName The friendly name of the SPI controller under test (e.g. SPI0).