Skip to content

Commit 3a9b530

Browse files
mprsemprse
committed
Add documentation for FPGA-Test-Shield SPI tests (new HAL API)
1 parent fdda087 commit 3a9b530

File tree

2 files changed

+119
-0
lines changed

2 files changed

+119
-0
lines changed

‎TESTS/mbed_hal_fpga_ci_test_shield/spi/README.MD

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
FPGA-Test-Shield: SPI master/slave tests
2+
=============
3+
4+
Overview
5+
----------------
6+
These tests verify various SPI transmission settings like:
7+
- transmission formats (clock polarity and phase, bit ordering, various symbol sizes),
8+
- transmission frequencies (required range, range specified in capabilities),
9+
- synchronous/asynchronous mode,
10+
- master/slave mode,
11+
- full-duplex/half-duplex mode,
12+
- chip select handled by hardware/handled manually (master mode only),
13+
- buffers cases (TX len == RX len, TX len < RX len, TX len > RX len, TX undefined, RX undefined),
14+
- SPI `init()/free()` called using all pins on the form factor,
15+
16+
Additional checks:
17+
- actual `sclk` frequency,
18+
- time between `cs` assertion and first `sclk` edge and last `sclk` edge and `cs` de-assertion,
19+
- `sclk` state on `cs` assertion and de-assertion.
20+
21+
SPI pins which are used in the tests are determined automatically using the pin-map extension.
22+
23+
Detailed information about the defined behavior of the new SPI HAL API can be found here:
24+
https://github.com/ARMmbed/mbed-os/blob/feature-hal-spec-spi/docs/design-documents/hal/0000-spi-overhaul.md#defined-behaviours
25+
26+
Test Setup
27+
----------------
28+
29+
1. **Pre-requirements**
30+
- Mbed board with SPI support,
31+
- FPGA-Test-Shield with the last firmware version.
32+
33+
34+
2. **Running the test**
35+
- Plug the FPGA-Test-Shield to the Device Under Test,
36+
- Connect Device Under Test to the host PC using USB cable,
37+
- Set jumper on the FPGA-Test-Shield to select USB power,
38+
- Connect the power to the FPGA-Test-Shield using USB cable,
39+
- Add `FPGA_CI_TEST_SHIELD` component to the Device Under Test in `targets.json` configuration file,
40+
- Check out `feature-hal-spec-spi` mbed-os branch,
41+
- Run the tests:
42+
- spi master: `mbed test -t GCC_ARM -m K64F -n tests-mbed_hal_fpga_ci_test_shield-spi_master -v`
43+
- spi slave: `mbed test -t GCC_ARM -m K64F -n tests-mbed_hal_fpga_ci_test_shield-spi_slave -v`
44+
45+
**Note:**
46+
- Half Duplex test case is disabled by default. This is because it needs an additional configuration. On different targets, a different line may be used as a data line in Half-Duplex mode. For example in the case of `NUCLEO_F429ZI` in Half-Duplex mode, `mosi` is used as the data line in master mode and `miso` is used as the data line in slave mode. To run the Half-Duplex test case please specify which line should be used as the data line (`HD_DATA_LINE = MOSI or MISO`) and un-comment the Half-Duplex test case.
47+
48+
Transmission Test Scenario
49+
----------------
50+
51+
The most common test case for testing SPI transmission is `basic test`, which uses the following SPI settings:
52+
- Symbol size: 8 bits,
53+
- Clock polarity/phase: Clock idle low/sampling on the first edge,
54+
- Bit order: MSB first,
55+
- SS handling: external (manual),
56+
- Duplex: Full duplex,
57+
- Frequency: 1 MHz,
58+
- RX, TX buffers defined,
59+
- RX buffer length is equal to TX buffer length.
60+
61+
Other transmission test cases differ from the `basic test` always only by one setting (e.g. `symbol size testing (16)` test case has the same scenario, but 16-bit symbols are transmitted). Each transmission test case is executed using synchronous and asynchronous(if supported) API. Note that asynchronous API does not support Half-Duplex mode and rx/tx buffers must have the same size.
62+
63+
Each platform provides its own SPI capabilities:
64+
https://github.com/ARMmbed/mbed-os/blob/feature-hal-spec-spi/docs/design-documents/hal/0000-spi-overhaul.md#the-new-api
65+
66+
Transmission test steps:
67+
- The test configuration is validated against the capabilities. If according to capabilities the specified configuration is not supported by the Device Under Test (e.g. `symbol size testing (16)` cannot be executed if 16-bit symbols are not supported by the Device Under Test), then the test case is skipped.
68+
- Init the SPI peripheral, set format, set frequency (only in case of spi master),
69+
- Transfer 5 times 300 symbols between the Device Under Test and the FPGA-Test-Shield.
70+
- After each transfer verify if:
71+
- checksum on the FPGA-Test-Shield side is correct and if correct data have been received from the FPGA-Test-Shield,
72+
- transmitted symbol count on the Device Under Test side and the FPGA-Test-Shield side are valid,
73+
- `sclk` state on `cs` assertion and de-assertion is valid,
74+
- the time between `cs` assertion and first `sclk` edge and last `sclk` edge and `cs` de-assertion is valid (this is only checked when `hardware ss handling` is selected in master mode).
75+
- Clean up the environment.
76+
77+
78+
Supported platforms
79+
----------------
80+
81+
SPI support is enabled on the following platforms:
82+
- `K66F`,
83+
- `K64F`,
84+
- `NUCLEO_F429ZI`.
85+
86+
Supported features:
87+
88+
| | K64F Master | K64F Slave | K66F Master | K66F Slave | NUCLEO_F429ZI Master | NUCLEO_F429ZI Slave |
89+
|----------------------|-----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
90+
| Symbol size [bits] | 8, 16 | 8, 16 | 8, 16 | 8, 16 | 8, 16 | 8, 16 |
91+
| Clock polarity/phase | SPI_MODE_IDLE_LOW_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_LOW_SAMPLE_SECOND_EDGE | SPI_MODE_IDLE_LOW_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_LOW_SAMPLE_SECOND_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_SECOND_EDGE, | SPI_MODE_IDLE_LOW_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_LOW_SAMPLE_SECOND_EDGE | SPI_MODE_IDLE_LOW_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_LOW_SAMPLE_SECOND_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_SECOND_EDGE, | SPI_MODE_IDLE_LOW_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_LOW_SAMPLE_SECOND_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_SECOND_EDGE, | SPI_MODE_IDLE_LOW_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_LOW_SAMPLE_SECOND_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_SECOND_EDGE, |
92+
| Bit order | SPI_BIT_ORDERING_MSB_FIRST, SPI_BIT_ORDERING_LSB_FIRST, | SPI_BIT_ORDERING_MSB_FIRST | SPI_BIT_ORDERING_MSB_FIRST, SPI_BIT_ORDERING_LSB_FIRST, | SPI_BIT_ORDERING_MSB_FIRST | SPI_BIT_ORDERING_MSB_FIRST, SPI_BIT_ORDERING_LSB_FIRST, | SPI_BIT_ORDERING_MSB_FIRST, SPI_BIT_ORDERING_LSB_FIRST, |
93+
| Frequency [Hz] | 200000 - 4000000 | 200000 - 4000000 | 200000 - 4000000 | 200000 - 4000000 | 200000 - 4000000 | 200000 - 2000000 |
94+
| CS handling | internal, external | internal | internal, external | internal | external | external |
95+
| Duplex mode | Full-Duplex | Full-Duplex | Full-Duplex | Full-Duplex | Full-Duplex/Half-Duplex | Full-Duplex/Half-Duplex |
96+
| Asynchronous mode | Yes | Yes | Yes | Yes | Yes | Yes |
97+
| Slave mode | - | Yes | - | Yes | - | Yes |
98+
99+
100+
Known Issues
101+
----------------
102+
103+
- `K64F, K66F`
104+
105+
1. If configured `sclk` idle state is high and manual `cs` handling is selected, then on `cs` assertion, `sclk` state is invalid (low). Because of this issue support for `SPI_MODE_IDLE_HIGH_SAMPLE_FIRST_EDGE, SPI_MODE_IDLE_HIGH_SAMPLE_SECOND_EDGE` in master mode is now disabled. Valid idle `sclk` state is reached after the first transfer.
106+
Screen-shot from logic analyser below:
107+
![could not load image](k66f_sclk_idle.png)
108+
109+
- `NUCLEO_F429ZI`
110+
111+
1. There is no complete SPI interface provided on Arduino form factor - `cs` pin is missing. Because of this, all test cases for spi slave are skipped.
112+
113+
2. Half-Duplex test case fails because invalid `sclk` state is detected on `cs` assertion. It looks like in Half-Duplex mode hardware takes ownership of the `sclk` pin after calling `spi_transfer()`, not after `spi_init()`. Between `spi_init()` and `spi_transfer()` calls `sclk` state is undefined. Adding a pull-down resistor to the clock line solves the problem.
114+
115+
3. According to the requirements delay from the `cs` assert to the first clock edge must be at least half spi clock period. On `NUCLEO_F429ZI` such delays cannot be programmed, thus internal `cs` handling (in master mode) is disabled.
116+
117+
Expected result:
118+
----------------
119+
The test exits without errors.

‎TESTS/mbed_hal_fpga_ci_test_shield/spi/k66f_sclk_idle.png

183 KB
Loading

0 commit comments

Comments
 (0)