SPI upgrade - per-peripheral mutex and GPIO-based SSEL #9469

kjbracey · 2019-01-23T12:20:13Z

Description

This commit takes some of the work done on the SPI class from #8445, and refines it, to provide the per-peripheral mutex functionality.

This also implements GPIO-based SSEL, which exposes a new select()/deselect() API for users to group transfers, and should work on every platform (unlike the HAL-based SSEL). This requires users to use a new constructor to avoid backwards compatibility issues.

To activate the per-peripheral mutex, the HAL must define SPI_COUNT and provide spi_get_peripheral_name(). (In #8445 this is a reworked spi_get_module, but the name is changed here to avoid a collision with existing HALs - this commit is designed to work without wider HAL changes).

Fixes: #9149

Pull request type

[ ] Fix
[ ] Refactor
[ ] Target update
[X] Functionality change
[ ] Docs update
[ ] Test update
[ ] Breaking change

Reviewers

@jarlamsa, @c1728p9, @ithinuel

kjbracey · 2019-01-23T12:20:39Z

First draft - just for discussion and @jarlamsa to try out at the minute, really.

ciarmcom · 2019-01-23T14:00:43Z

@kjbracey-arm, thank you for your changes.
@c1728p9 @ithinuel @jarlamsa @ARMmbed/mbed-os-core @ARMmbed/mbed-os-hal @ARMmbed/mbed-os-maintainers please review.

jarlamsa · 2019-01-24T11:59:01Z

[Error] SPI.cpp@239,37: 'struct SingletonPtr<mbed::CircularBuffer<mbed::Transaction<mbed::SPI>, 2ul> >' has no member named 'reset'
[Error] SPI.cpp@271,41: 'struct SingletonPtr<mbed::CircularBuffer<mbed::Transaction<mbed::SPI>, 2ul> >' has no member named 'full'
[Error] SPI.cpp@275,41: 'struct SingletonPtr<mbed::CircularBuffer<mbed::Transaction<mbed::SPI>, 2ul> >' has no member named 'push'
[Error] SPI.cpp@323,41: 'struct SingletonPtr<mbed::CircularBuffer<mbed::Transaction<mbed::SPI>, 2ul> >' has no member named 'pop'

You probably wanted to use the member access through pointer operator with the access to the transaction_buffer.

jarlamsa · 2019-01-30T07:55:48Z

drivers/SPI.cpp

@@ -167,7 +236,7 @@ void SPI::abort_transfer()
 void SPI::clear_transfer_buffer()
 {
 #if TRANSACTION_QUEUE_SIZE_SPI
-    _transaction_buffer.reset();
+    _peripheral->transaction_buffer.reset();


transaction_buffer->reset

jarlamsa · 2019-01-30T07:56:07Z

drivers/SPI.cpp

@@ -199,12 +268,12 @@ int SPI::queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, i
    t.callback = callback;
    t.width = bit_width;
    Transaction<SPI> transaction(this, t);
-    if (_transaction_buffer.full()) {
+    if (_peripheral->transaction_buffer.full()) {


transaction_buffer->full

jarlamsa · 2019-01-30T07:56:59Z

drivers/SPI.cpp

        return -1; // the buffer is full
    } else {
        core_util_critical_section_enter();
-        _transaction_buffer.push(transaction);
-        if (!spi_active(&_spi)) {
+        _peripheral->transaction_buffer.push(transaction);


transaction_buffer->push

jarlamsa · 2019-01-30T07:57:12Z

drivers/SPI.cpp

@@ -250,7 +320,7 @@ void SPI::start_transaction(transaction_t *data)
 void SPI::dequeue_transaction()
 {
    Transaction<SPI> t;
-    if (_transaction_buffer.pop(t)) {
+    if (_peripheral->transaction_buffer.pop(t)) {


transaction_buffer->pop

jarlamsa · 2019-01-30T08:00:00Z

Otherwise seems to be working without issues on NUCLEO_F429ZI when made changes to stm_spi_api.c and TARGET_STM32F4/TARGET_STM32F429xI/TARGET_NUCLEO_F429ZI/PeripheralNames.h

Do we bring the HAL-changes in with this PR or in a separate PR?

ithinuel · 2019-01-30T14:50:24Z

Won't this change collide with the work done on branch feature-hal-spec-spi ?

Wouldn't it be better to keep the status quo until the feature gets actually merged into master ?
(I am asking this with in mind the maintenance cost induced by changes on master when time comes to rebase the feature branch.)

kjbracey · 2019-01-30T14:56:30Z

Yes, it collides, and the feature branch will need to be rebased and aligned with this :/

The problem is that this feature is required for 5.12, but your feature branch isn't due to land for 5.12.

The system-wide mutex is a blocker for @jarlamsa's project - SD card accesses break the radio driver.

cmonr · 2019-01-30T22:51:17Z

@bulislaw @ARMmbed/mbed-os-maintainers Fyi ^^^

deepikabhavnani · 2019-01-30T22:55:01Z

First draft - just for discussion and @jarlamsa to try out at the minute, really.

Will like to see at least some test code to verify the changes in this PR

kjbracey · 2019-01-31T08:21:24Z

I'm not sure what the current SPI test infrastructure consists of. I see #7976 in progress for specific testing, but that's part of the pending feature branch, and it's testing the HAL, not class SPI.

For the new select/deselect functionality, bringing it into use by SD drivers and 802.15.4 radio drivers would get that exercised by their test suites. (I've asked @jarlamsa to look at that - would simplify their code and offset code size increase here).

kjbracey · 2019-02-01T10:54:44Z

@ithinuel - new commit reworks the peripheral blocks to make them allocated on-demand from the heap. This optimises RAM usage for the typical "SPI peripherals in use much fewer than those available in hardware" case.

I think that's the least worst option, having considered the "static array of spi peripheral count" and "put 1 peripheral object inside each SPI object" options. The last would have been cunning, and optimal for the typical "1 device per peripheral" case, but I couldn't figure out how to hand over correctly and safely when an SPI object was deleted.

Does eliminate the need for SPI_COUNT from the HAL, but increases ROM size. Ends up pulling in mutex deletion code in a simple test image, which the static version avoids. Can't see a cunning way around that. (It comes via SPI's virtual destructor).

kjbracey · 2019-02-01T10:55:36Z

Requires fix in #9580.

0xc0170 · 2019-03-01T10:59:10Z

CI restarted

mbed-ci · 2019-03-01T11:58:48Z

Test run: FAILED

Summary: 1 of 9 test jobs failed
Build number : 3
Build artifacts

Failed test jobs:

jenkins-ci/mbed-os-ci_build-ARMC5

0xc0170 · 2019-03-01T12:12:07Z

Some targets report [DEBUG] Errors: Error: L6218E: Undefined symbol spi_get_peripheral_name (referred from BUILD/tests/NRF52_DK/ARM/drivers/SPI.o). . Not certain why only ARMC5 failed.

This commit takes some of the work done on the SPI class from ARMmbed#8445, and refines it, to provide the per-peripheral mutex functionality. This also implements GPIO-based SSEL, which exposes a new select()/deselect() API for users to group transfers, and should work on every platform (unlike the HAL-based SSEL). This requires users to use a new constructor to avoid backwards compatibility issues. To activate the per-peripheral mutex, the HAL must define SPI_COUNT and provide spi_get_peripheral_name(). (In ARMmbed#8445 this is a reworked spi_get_module, but the name is changed here to avoid a collision with existing HALs - this commit is designed to work without wider HAL changes). Fixes: ARMmbed#9149

SPIFBlockDevice was using SingletonPtr without an include, and only getting it via SPI.h. Spotted while changing SPI to not use SingletonPtr - now abandoned, but still this shouldn't have been relying on it.

Avoid collision with some HALs that already define SPI_COUNT.

kjbracey · 2019-03-01T12:38:41Z

Some HALs had their own existing SPI_COUNT definition. Moved our new one to DEVICE_SPI_COUNT to avoid collision.

Rebased.

0xc0170 · 2019-03-01T12:42:02Z

CI restarted

ithinuel

Aside from the two "style" comment, LGTM

ithinuel · 2019-03-01T13:24:59Z

drivers/SPI.cpp

+void SPI::select()
+{
+    lock();
+    if (_select_count++ == 0) {


This is just a matter of coding style, but for clarity, could this increment be done after the if ?

I think I did that quite deliberately because a couple of days before writing it I saw some existing code containing this:

core_util_atomic_incr_u32(foo, 1); if (foo == 1) {

which is not thread-safe, and needs to be

if (core_util_atomic_incr_u32(foo, 1) == 1) {

I think if people can't get comfortable with the increment/decrement pattern, it just encourages that sort of mistake. (Although breaking it up doesn't hurt in this case, as we are in a lock).

ithinuel · 2019-03-01T13:25:41Z

drivers/SPI.cpp

+
+void SPI::deselect()
+{
+    if (--_select_count == 0) {


Like in the previous commend, could this decrement be done before the if to avoid any confusion ?

mbed-ci · 2019-03-01T14:48:34Z

Test run: FAILED

Summary: 1 of 14 test jobs failed
Build number : 4
Build artifacts

Failed test jobs:

jenkins-ci/mbed-os-ci_tools-test

0xc0170 · 2019-03-01T15:56:52Z

@ithinuel Happy with this PR?

stevew817 · 2019-04-25T12:26:22Z

@0xc0170 This broke SPI for Silicon Labs targets, as we currently don't allow instantiating NC pins and the new constructor does exactly that.

How was this PR tested?

kjbracey · 2019-04-25T12:44:29Z

Expected behaviour is that targets should permit gpio_init with NC, but are free to assert or crash if any real read/write operations are made on the NC pin.

This isn't explicitly documented, as far as I can see, but is implied by the existence of gpio_is_connected:

/* Checks if gpio object is connected (pin was not initialized with NC)
 * @param pin The pin to be set as GPIO
 * @return 0 if port is initialized with NC
 **/
int gpio_is_connected(const gpio_t *obj);

The PR would have been tested on whichever devices we have present and operational in CI - but as I believe we don't have any sort of universal SPI test rigs it would have been exercised in devices using 802.15.4 radio modules and the like, and I guess Silicon Labs targets would not have been represented.

The Silicon Labs targets should be updated to permit NC GPIO initialisation - I would suggest removing the assert from gpio_init, and instead having MBED_ASSERT(gpio_is_connected(obj)) in other calls.

stevew817 · 2019-04-25T13:35:21Z

@kjbracey-arm The other issue is targets using asynchronous SPI. the irq_handler is called from IRQ context, and this PR changed the transaction buffer to be a singletonPtr, see https://github.com/ARMmbed/mbed-os/pull/9469/files#diff-ade6379acb4d9069bc0cc21788bb6883R359

Inside the IRQ handler, dequeue_transaction can be called, which in turn tries to dequeue from the transaction buffer. This will cause failure, since the transaction buffer now needs to lock a mutex to get to the singletonPtr. That evidently won't work from IRQ context...

kjbracey · 2019-04-25T13:49:52Z

SingletonPtr's mutex lock only occurs on first use, so AFAICT there would only be an issue if the very first asynchronous transaction was started directly from an interrupt handler. Are you doing that?

I guess we could prime the transaction buffer in the constructor to help that case - a call to its get() in _do_construct.

stevew817 · 2019-04-25T13:59:13Z

Priming would be helpful.
Starting an asynch transaction on a timer is not really an exotic use case?

kjbracey · 2019-04-25T14:07:13Z

The fact that async calls can be initiated from interrupt does illustrate a (pre-existing) design problem - the mutex locks for the peripheral are being bypassed, which means it won't work correctly in any sort of environment where there are multiple users sharing one SPI peripheral.

We do need to pin down exactly what the rules about async use are - I believe the guys working on the SPI HAL upgrade feature branch have been looking at this.

Still, for the current environment where asynch is historically lockless, it would make sense to prime it so it continues to work in that scenario. I'll make a patch for that. Will cost a bit of ROM space pulling in the init code for unused asynch, but not a lot.

0xc0170 · 2019-04-29T15:46:36Z

Thanks @stevew817 for getting back to us with these issues

kjbracey force-pushed the spi_muxing branch 2 times, most recently from 0fae068 to ae6feea Compare January 23, 2019 12:45

kjbracey changed the title ~~SPI upgrade - per-bus mutex and GPIO-based SSEL~~ SPI upgrade - per-peripheral mutex and GPIO-based SSEL Jan 23, 2019

kjbracey force-pushed the spi_muxing branch from ae6feea to db7de64 Compare January 23, 2019 13:19

ciarmcom requested review from c1728p9, ithinuel, jarlamsa and a team January 23, 2019 14:00

ciarmcom added the needs: review label Jan 23, 2019

jarlamsa suggested changes Jan 30, 2019

View reviewed changes

kjbracey force-pushed the spi_muxing branch 2 times, most recently from 9fd003e to c60000f Compare January 31, 2019 11:19

cmonr added needs: work and removed needs: review labels Jan 31, 2019

kjbracey force-pushed the spi_muxing branch from c60000f to a655fb9 Compare February 1, 2019 10:54

kjbracey added the needs: preceding PR label Feb 1, 2019

kjbracey removed the needs: preceding PR label Feb 5, 2019

kjbracey added 4 commits March 1, 2019 14:33

SPIFBlockDevice.h: include SingletonPtr.h

c368021

SPIFBlockDevice was using SingletonPtr without an include, and only getting it via SPI.h. Spotted while changing SPI to not use SingletonPtr - now abandoned, but still this shouldn't have been relying on it.

Cope with HALs not defining SPIName

df7e336

Rename SPI_COUNT to DEVICE_SPI_COUNT

b12be6b

Avoid collision with some HALs that already define SPI_COUNT.

kjbracey force-pushed the spi_muxing branch from f0eb6f5 to b12be6b Compare March 1, 2019 12:37

0xc0170 added needs: CI and removed needs: work labels Mar 1, 2019

ithinuel suggested changes Mar 1, 2019

View reviewed changes

0xc0170 added ready for merge and removed needs: CI labels Mar 1, 2019

0xc0170 merged commit 7c9a718 into ARMmbed:master Mar 1, 2019

0xc0170 removed the ready for merge label Mar 1, 2019

cmonr mentioned this pull request Mar 1, 2019

ARM Toolchain update to ARM Compiler 6.11(ARMC6) #9888

Merged

kjbracey mentioned this pull request Apr 26, 2019

gpio_api.h: Clarify desired behaviour for NC #10489

Merged

0xc0170 mentioned this pull request Jun 8, 2021

Unable to work with two physical I2C buses #14735

Closed

multiplemonomials mentioned this pull request Feb 29, 2024

Every Mbed target should be required to implement spi_get_peripheral_name() mbed-ce/mbed-os#255

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SPI upgrade - per-peripheral mutex and GPIO-based SSEL #9469

SPI upgrade - per-peripheral mutex and GPIO-based SSEL #9469

kjbracey commented Jan 23, 2019 •

edited

Loading

kjbracey commented Jan 23, 2019

ciarmcom commented Jan 23, 2019

jarlamsa commented Jan 24, 2019 •

edited

Loading

jarlamsa Jan 30, 2019

jarlamsa Jan 30, 2019

jarlamsa Jan 30, 2019

jarlamsa Jan 30, 2019

jarlamsa commented Jan 30, 2019

ithinuel commented Jan 30, 2019 •

edited

Loading

kjbracey commented Jan 30, 2019

cmonr commented Jan 30, 2019

deepikabhavnani commented Jan 30, 2019

kjbracey commented Jan 31, 2019 •

edited

Loading

kjbracey commented Feb 1, 2019

kjbracey commented Feb 1, 2019

0xc0170 commented Mar 1, 2019

mbed-ci commented Mar 1, 2019

0xc0170 commented Mar 1, 2019

kjbracey commented Mar 1, 2019

0xc0170 commented Mar 1, 2019

ithinuel left a comment

ithinuel Mar 1, 2019

kjbracey Mar 1, 2019

ithinuel Mar 1, 2019

mbed-ci commented Mar 1, 2019

0xc0170 commented Mar 1, 2019

stevew817 commented Apr 25, 2019

kjbracey commented Apr 25, 2019 •

edited

Loading

stevew817 commented Apr 25, 2019

kjbracey commented Apr 25, 2019

stevew817 commented Apr 25, 2019

kjbracey commented Apr 25, 2019 •

edited

Loading

0xc0170 commented Apr 29, 2019

SPI upgrade - per-peripheral mutex and GPIO-based SSEL #9469

SPI upgrade - per-peripheral mutex and GPIO-based SSEL #9469

Conversation

kjbracey commented Jan 23, 2019 • edited Loading

Description

Pull request type

Reviewers

kjbracey commented Jan 23, 2019

ciarmcom commented Jan 23, 2019

jarlamsa commented Jan 24, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jarlamsa commented Jan 30, 2019

ithinuel commented Jan 30, 2019 • edited Loading

kjbracey commented Jan 30, 2019

cmonr commented Jan 30, 2019

deepikabhavnani commented Jan 30, 2019

kjbracey commented Jan 31, 2019 • edited Loading

kjbracey commented Feb 1, 2019

kjbracey commented Feb 1, 2019

0xc0170 commented Mar 1, 2019

mbed-ci commented Mar 1, 2019

0xc0170 commented Mar 1, 2019

kjbracey commented Mar 1, 2019

0xc0170 commented Mar 1, 2019

ithinuel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbed-ci commented Mar 1, 2019

0xc0170 commented Mar 1, 2019

stevew817 commented Apr 25, 2019

kjbracey commented Apr 25, 2019 • edited Loading

stevew817 commented Apr 25, 2019

kjbracey commented Apr 25, 2019

stevew817 commented Apr 25, 2019

kjbracey commented Apr 25, 2019 • edited Loading

0xc0170 commented Apr 29, 2019

kjbracey commented Jan 23, 2019 •

edited

Loading

jarlamsa commented Jan 24, 2019 •

edited

Loading

ithinuel commented Jan 30, 2019 •

edited

Loading

kjbracey commented Jan 31, 2019 •

edited

Loading

kjbracey commented Apr 25, 2019 •

edited

Loading

kjbracey commented Apr 25, 2019 •

edited

Loading