You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/porting/target/spi.md
+52-55
Original file line number
Diff line number
Diff line change
@@ -2,14 +2,14 @@
2
2
3
3
The **Serial Peripheral Interface** allows you to send or receive a data stream over a synchronous serial interface made of 3 to 4 lines.
4
4
5
-
- MISO: Master In Slave Out.
6
-
- MOSI: Master Out Slave In.
5
+
- MISO: Master in, slave out.
6
+
- MOSI: Master out, slave in.
7
7
- MCLK: Clock.
8
-
- SS: Slave Select.
8
+
- SS: Slave select.
9
9
10
10
A typical use case of this interface is with SDCard, memory blocks and DACs or ADCs.
11
11
12
-
This highly configurable interface has a wide range of elements you can adjust:
12
+
This highly configurable interface has elements you can adjust:
13
13
14
14
- Frame length.
15
15
- Clocks polarity and phase.
@@ -18,94 +18,91 @@ This highly configurable interface has a wide range of elements you can adjust:
18
18
19
19
### Assumptions
20
20
21
-
#### Defined Behaviours
21
+
#### Defined behaviors
22
22
23
23
-`spi_get_module()` returns the `SPIName` unique identifier to the peripheral associated to this SPI channel.
24
-
-`spi_get_capabilities()` fills the given `spi_capabilities_t` instance
25
-
-`spi_get_capabilities()` should consider the `ssel` pin when evaluation the `support_slave_mode` capability.
26
-
If the given `ssel` pin cannot be managed by hardware in slave mode, `support_slave_mode` should be false.
27
-
- At least a symbol width of 8bit must be supported.
28
-
- The supported frequency range must include the range [0.2..2] MHz.
24
+
-`spi_get_capabilities()` fills the given `spi_capabilities_t` instance.
25
+
-`spi_get_capabilities()` should consider the `ssel` pin when evaluating the `support_slave_mode` capability.
26
+
- If the given `ssel` pin cannot be managed by hardware in slave mode, `support_slave_mode` should be false.
27
+
- At least a symbol width of 8 bit must be supported.
28
+
- The supported frequency range must include the range 0.2-2 MHz.
29
29
- The shortest part of the duty cycle must not be shorter than 50% of the expected period.
30
30
-`spi_init()` initializes the pins leaving the configuration registers unchanged.
31
31
-`spi_init()` if `is_slave` is false:
32
-
- if`ssel` is `NC` the hal implementation ignores this pin.
33
-
- if`ssel` is not `NC` then the hal implementation owns the pin and its management.
34
-
- When managed by the hal implementation, `ssel` is always considered active low.
32
+
- If`ssel` is `NC`, the HAL implementation ignores this pin.
33
+
- If`ssel` is not `NC`, then the HAL implementation owns the pin and its management.
34
+
- When managed by the HAL implementation, `ssel` is always considered active low.
35
35
- When the hardware supports the half-duplex (3-wire) mode, if `miso` (exclusive) or `mosi` is missing in any function that expects pins, the bus is assumed to be half-duplex.
36
36
-`spi_free()` resets the pins to their default state.
37
37
-`spi_free()` disables the peripheral clock.
38
-
-`spi_format()` sets:
39
-
- the number of bits per symbol
40
-
- the mode :
41
-
.0 Clock idle state is *low*, data are sampled when the clock becomes *active* (polarity = 0, phase = 0)
42
-
.1 Clock idle state is *low*, data are sampled when the clock becomes *inactive* (polarity = 0, phase = 1)
43
-
.2 Clock idle state is *high*, data are sampled when the clock becomes *active* (polarity = 1, phase = 0)
44
-
.3 Clock idle state is *high*, data are sampled when the clock becomes *inactive* (polarity = 1, phase = 1)
45
-
- the bit ordering (lsb/msb first).
38
+
-`spi_format()` sets:
39
+
- The number of bits per symbol.
40
+
- The mode:
41
+
.0 Clock idle state is *low*, data are sampled when the clock becomes *active* (polarity = 0, phase = 0).
42
+
.1 Clock idle state is *low*, data are sampled when the clock becomes *inactive* (polarity = 0, phase = 1).
43
+
.2 Clock idle state is *high*, data are sampled when the clock becomes *active* (polarity = 1, phase = 0).
44
+
.3 Clock idle state is *high*, data are sampled when the clock becomes *inactive* (polarity = 1, phase = 1).
45
+
- The bit ordering (lsb/msb first).
46
46
-`spi_format()` updates the configuration of the peripheral except the baud rate generator.
47
47
-`spi_frequency()` sets the frequency to use during the transfer.
48
-
-`spi_frequency()` returns the actual frequency that will be used.
48
+
-`spi_frequency()` returns the actual frequency that is used.
49
49
-`spi_frequency()` updates the baud rate generator leaving other configurations unchanged.
50
50
-`spi_init()`, `spi_frequency()` and `spi_format()` must be called at least once each before initiating any transfer.
51
-
-`spi_transfer()` :
52
-
- writes `tx_len` symbols to the bus.
53
-
- reads `rx_len` symbols from the bus.
54
-
- if `rx` is NULL then inputs are discarded.
55
-
- if `tx` is NULL then `fill_symbol` is used instead.
56
-
- returns the number of symbol clocked on the bus during this transfer.
57
-
- expects symbols types to be the closest stdint type bigger or equal to its size following the platform's endianness.
58
-
e.g.:
59
-
- 7bits => uint8_t
60
-
- 15bits => uint16_t
61
-
- 16bits => uint16_t
62
-
- 17bits => uint32_t
63
-
- In Full-duplex mode :
64
-
- if `rx_len` > `tx_len` then it sends `(rx_len-tx_len)` additional `fill_symbol` to the bus.
65
-
- In Half-duplex mode :
66
-
- as master, `spi_transfer()` sends `tx_len` symbols and then reads `rx_len` symbols.
67
-
- as slave, `spi_transfer()` receives `rx_len` symbols and then sends `tx_len` symbols.
51
+
-`spi_transfer()`:
52
+
- Writes `tx_len` symbols to the bus.
53
+
- Reads `rx_len` symbols from the bus.
54
+
- If `rx` is NULL, then inputs are discarded.
55
+
- If `tx` is NULL, then `fill_symbol` is used instead.
56
+
- Returns the number of symbol clocked on the bus during this transfer.
57
+
- Expects symbols types to be the closest stdint type bigger or equal to its size following the platform's endianness. For example:
58
+
- 7bits => uint8_t.
59
+
- 15bits => uint16_t.
60
+
- 16bits => uint16_t.
61
+
- 17bits => uint32_t.
62
+
- In full-duplex mode:
63
+
- If `rx_len` > `tx_len` then it sends `(rx_len-tx_len)` additional `fill_symbol` to the bus.
64
+
- In half-duplex mode:
65
+
- As master, `spi_transfer()` sends `tx_len` symbols and then reads `rx_len` symbols.
66
+
- As slave, `spi_transfer()` receives `rx_len` symbols and then sends `tx_len` symbols.
68
67
-`spi_transter_async()` schedules a transfer to be process the same way `spi_transfer()` would have but asynchronously.
69
68
-`spi_transter_async()` returns immediately with a boolean indicating whether the transfer was successfully scheduled or not.
70
69
- The callback given to `spi_transfer_async()` is invoked when the transfer completes (with a success or an error).
71
70
-`spi_transfer_async()` saves the handler and the `ctx` pointer.
72
71
- The `ctx` is passed to the callback on transfer completion.
73
-
- Unless if the transfer is aborted, the callback is invoked on completion. The completion maybe when all symbols have been transmitted
74
-
or when in slave mode the master de-asserts the chip select.
75
-
- The `spi_transfer_async()` function may use the `DMAUsage` hint to select the appropriate async algorithm.
76
-
- The `spi_async_event_t` must be filled with the number of symbol clocked on the bus during this transfer and a boolean value indicated if an error has occurred.
77
-
-`spi_transfer_async_abort()` aborts an on-going async transfer.
72
+
- Unless the transfer is aborted, the callback is invoked on completion. The completion may be when all symbols have been transmitted
73
+
or when, in slave mode, the master deasserts the chip select.
74
+
- The `spi_transfer_async()` function may use the `DMAUsage` hint to select the appropriate asynchronous algorithm.
75
+
- The `spi_async_event_t` must be filled with the number of symbols clocked on the bus during this transfer and a boolean value indicated if an error has occurred.
76
+
-`spi_transfer_async_abort()` aborts an ongoing asynchronous transfer.
78
77
79
-
#### Undefined Behaviours
78
+
#### Undefined behaviors
80
79
81
80
- Calling `spi_init()` multiple times on the same `spi_t` without `spi_free()`'ing it first.
82
-
- Calling any method other than `spi_init()` on a non-initialized or freed `spi_t`.
81
+
- Calling any method other than `spi_init()` on an uninitialized or freed `spi_t`.
83
82
- Passing both `miso` and `mosi` as `NC` to `spi_get_module` or `spi_init`.
84
83
- Passing `miso` or `mosi` as `NC` on target that does not support half-duplex mode.
85
84
- Passing `mclk` as `NC` to `spi_get_module` or `spi_init`.
86
85
- Passing an invalid pointer as `cap` to `spi_get_capabilities`.
87
86
- Passing pins that cannot be on the same peripheral.
88
87
- Passing an invalid pointer as `obj` to any method.
89
-
- Giving a`ssel` pin to `spi_init()` when using in master mode.
90
-
SS must be managed by hardware in slave mode and must **NOT** be managed by hardware in master mode.
88
+
- Giving an`ssel` pin to `spi_init()` when using in master mode.
89
+
- SS must be managed by hardware in slave mode and must **NOT** be managed by hardware in master mode.
91
90
- Setting a frequency outside of the range given by `spi_get_capabilities()`.
92
91
- Setting a frequency in slave mode.
93
92
- Setting `bits` in `spi_format` to a value out of the range given by `spi_get_capabilities()`.
94
93
- Passing an invalid pointer as `fill_symbol` to `spi_transfer` and `spi_transfer_async` while they would be required by the transfer (`rx_len != tx_len` or `tx==NULL`).
95
94
- Passing an invalid pointer as `handler` to `spi_transfer_async`.
96
-
- Calling `spi_transfer_async_abort()` while no async transfer is being processed (no transfer or a synchronous transfer).
95
+
- Calling `spi_transfer_async_abort()` while no asynchronous transfer is being processed (no transfer or a synchronous transfer).
97
96
- In half-duplex mode, any mechanism (if any is present) to detect or prevent collision is implementation defined.
98
97
99
98
#### Other requirements
100
99
101
100
A target must also define these elements:
102
101
103
102
-`#define SPI_COUNT (xxxxxU)`.
104
-
The number of SPI peripheral available on the device. A good place for that macro is `PeripheralNames.h` next to the `SPIName` enumeration.
103
+
-The number of SPI peripherals available on the device. A good place for that macro is `PeripheralNames.h` next to the `SPIName` enumeration.
105
104
106
-
#### Notes
107
-
108
-
You can find more details about the design choices on the [HAL RFC #0](https://github.com/ARMmbed/mbed-os/blob/feature-hal-spec-spi/docs/design-documents/hal/0000-spi-overhaul.md).
105
+
<spanclass="notes">**Note:**You can find more details about the design choices in the [SPI design document](https://github.com/ARMmbed/mbed-os/blob/feature-hal-spec-spi/docs/design-documents/hal/0000-spi-overhaul.md).</span>
109
106
110
107
### Dependencies
111
108
@@ -115,7 +112,7 @@ Hardware SPI capabilities.
115
112
116
113
You can find the API and specification for the SPI API in the following class reference:
0 commit comments