Add Critical Section HAL API specification #5346

ghost · 2017-10-19T10:31:07Z

Description

As discussed in NRF51_DK: core_util_are_interrupts_enabled wrong behavior when inside critical section #5198 there is a need for a HAL API specification for platform-specific Critical Section behaviors.

Specifically, the purpose of this pull request is to:

Provide a reliable method of detecting if the current program is running within a critical section.

The current method of checking if the program is in a critical section is to call core_util_interrupts_enabled(), under most circumstances this works as by default entering a critical section disables interrupts. Some platforms do not disable all interrupts when entering a critical section, causing this to fail.

This PR provides a method core_util_in_critical_section() which specifically checks the state of the program.
Move platform-specific implementations for critical sections from the User Facing API into the HAL.

Added the platform specific HAL functions hal_critical_section_enter and hal_critical_section_exit which are called from the platform independent API core_util_critical_section_enter and core_util_critical_section_exit.

Added a weak default implementation for HAL API. The default implementation
matches the previous behavior stored in the User facing API:
- The first call to enter a Critical Section stores the state of interrupts
  before disabling and each successive call re-disables interrupts.
- The last call (non-nested) will restore the IRQ state that was set on the
  enter to the critical section. Nested calls are ignored.

Porting Guide

Implement the API declared in mbed-os/hal/critical_section_api.h. If the platform you are porting requires custom critical section behavior that is incompatible with the default (disabling all interrupts).

The functions defined in the header hal_critical_section_enter and hal_critical_section_exit are called on the first entry to, and the last exit from the critical section respectively, any nested calls to enter critical sections do not call the HAL API functions.

You must define the state changes that need to happen when entering a critical section. You should store this state in the critical section translation unit before setting to a state that is safe for the critical section. When hal_critical_section_exit is called the saved state should be restored.

Status

IN DEVELOPMENT

TODO:

Porting Guide
Test Plan
Ported All Boards:
- NRF51

bulislaw · 2017-10-20T21:38:13Z

hal/critical_section_api.h

+  *                     critical section or a nested call. The first call should
+  *                     store the state prior to entering the critical section.
+  */
+void hal_critical_section_enter(const bool in_nested_critical_section);


Do we need the parameter? Mbed core is keeping count anyway we may as well call it once? What do you think? I would prefer to have complicated drivers and simple HAL implementation @0xc0170 @c1728p9

Yeah, that makes more sense. I did it that way because the original implementation let you call enter multiple times and it would re-disable interrupts. But, that doesn't make much sense as it will assert if they've been re-enabled during the critical section.

adbridge · 2017-10-24T10:39:49Z

@bulislaw are you happy with this now ?

bulislaw · 2017-10-24T14:14:56Z

hal/critical_section_api.h

+
+/** Mark the start of a critical section
+  *
+  * This function is called directly by core_util_critical_section_enter on


That's a bit sparse, can we add some info about multiple calls - as far as I understand that this function will be only called once (no need to handle enter-...-enter-exit). The same for exit. Are there any other assumptions or limitations we should mention?

bulislaw · 2017-10-24T14:15:51Z

hal/mbed_critical_section_api.c

+
+MBED_WEAK void hal_critical_section_exit()
+{
+// FIXME


Why is that fix me? if we don't know lets get rid of that.

It was in the original code, it was added here: Don't call __disable_irq for uVisor. It seems like it still needs resolving at some point so I didn't remove it.

bulislaw · 2017-10-24T14:17:07Z

platform/mbed_critical.c


-        interrupt_enable_counter--;
+    critical_section_reentrancy_counter--;


Shall we assert at underflowing?

I suppose there's no harm in adding an assert, but it shouldn't underflow because it returns early if the counter is already 0.

bulislaw · 2017-10-24T14:17:57Z

Ah and also can we unify the name of mbed_critical_section_api.c to match the header.

ghost · 2017-10-24T14:53:59Z

Ah and also can we unify the name of mbed_critical_section_api.c to match the header.

That seems reasonable. But, all of the current HAL files follow that naming scheme and I don't see the distinction from them e.g
mbed_flash_api.c - flash_api.h
mbed_lp_ticker_api.c - lp_ticker_api.h

bulislaw · 2017-10-24T15:57:27Z

Ah ok fair enough.

bulislaw · 2017-10-25T14:39:16Z

There are some issues with doxy can you please fix them.

0xc0170 · 2017-10-25T16:23:27Z

targets/TARGET_NORDIC/TARGET_NRF5/critical_section_api.c

+
+void hal_critical_section_enter(void)
+{
+  sd_nvic_critical_region_enter(&_sd_state);


4 spaces indentation

0xc0170 · 2017-10-25T16:26:29Z

hal/critical_section_api.h

+  * function so it can be restored when exiting the critical section.
+  *
+  */
+void hal_critical_section_enter(void);


Is it documented anywhere that we are providing default implementation (reference where it can be found) ? I can not spot it, we shall mention it, so during porting, they do not reimplement it all over again

There's a brief mention of it in the porting guide, which is in the PR description but I haven't added to the handbook yet. I can make it a bit clearer and point it to the default implementation.

What do you think about at least having a note here in API docs, that we are providing default implementation that can be overriden?

Sure, I can make that clearer

bulislaw · 2017-10-25T16:48:42Z

Please not that this PR is just the code, the other part will be the PG section.

bulislaw · 2017-10-26T20:54:51Z

Is that reviewed now?

0xc0170 · 2017-10-27T15:06:47Z

/morph build

mbed-ci · 2017-10-27T15:40:10Z

Build : SUCCESS

Build number : 355
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/5346/

Triggering tests

/morph test
/morph uvisor-test

mbed-ci · 2017-10-27T18:31:57Z

Test : FAILURE

Build number : 168
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/5346/168

bulislaw · 2017-10-27T19:10:07Z

ghost · 2017-10-30T15:55:17Z

13:31:31 | NRF51_DK-IAR | NRF51_DK | tests-mbedmicro-rtos-mbed-rtostimer | FAIL | 34.99 | shell |
@scartmell-arm

It appears to be a timeout error on Semaphore::wait. But, I'm not sure why yet. The failure only exists on the IAR compiler, usually the first test run after rebooting the board passes, all subsequent runs fail.

Failure is usually:

[1509128019.44][CONN][RXD] :115::FAIL: Expected 1 Was 0
[1509128019.44][CONN][INF] found KV pair in stream: {{__testcase_finish;Test periodic repeats continuously;0;1}}, queued...
[1509128019.52][CONN][RXD] >>> 'Test periodic repeats continuously': 0 passed, 1 failed with reason 'Assertion Failed'

or sometimes:

[1509369613.09][CONN][RXD] {{__tCMSIS-RTOS error: User Timer Callback Queue overflow (status: 0x3, task ID: 0x0, timer ID: 0x20006240)

fails here:

mbed-os\TESTS\mbedmicro-rtos-mbed\rtostimer\main.cpp:115

slots = sem.wait(TEST_DELAY_MS + 1);
t.stop();
TEST_ASSERT_EQUAL(1, slots);

from here:

\mbed-os\rtos\Semaphore.cpp:46

int32_t Semaphore::wait(uint32_t millisec) {
    osStatus_t stat = osSemaphoreAcquire(_id, millisec);
    switch (stat) {
        ...
        case osErrorTimeout:
            return 0;
        ...
    }
}

0xc0170 · 2017-11-02T10:10:15Z

As it was rebased, let's rerun the tests

/morph build

mbed-ci · 2017-11-02T11:16:30Z

Build : SUCCESS

Build number : 415
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/5346/

Triggering tests

/morph test
/morph uvisor-test

mbed-ci · 2017-11-02T14:25:21Z

Test : FAILURE

Build number : 205
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/5346/205

0xc0170 · 2017-11-16T13:09:00Z

As this was tested more than a week ago, restarting tests

/morph build

@scartmell-arm please look at results if any of these fail.

mbed-ci · 2017-11-16T13:38:36Z

Build : SUCCESS

Build number : 532
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/5346/

Triggering tests

/morph test
/morph uvisor-test
/morph export-build

mbed-ci · 2017-11-16T14:37:12Z

Exporter Build : SUCCESS

Build number : 146
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/5346/

mbed-ci · 2017-11-16T14:41:24Z

Test : SUCCESS

Build number : 341
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/5346/341

- Add function to HAL hal_in_critical_section() - Wrap assert in FEATURE_UVISOR macro

hal_critical_section_enter() is safe to call multiple times, however hal_critical_section_exit() is only called on the last exit from a critical section. This will cause a mismatch in the counter and the interrupt state will never be restored if the critical section is nested. Change this to a bool so that the interrupt save state is tracked for hal_in_critical_section() to work correctly.

cmonr · 2018-01-11T16:46:36Z

/morph build

mbed-ci · 2018-01-11T17:13:36Z

Build : FAILURE

Build number : 843
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/5346/

0xc0170 · 2018-01-12T14:22:27Z

Pipe closed exception

/morph build

mbed-ci · 2018-01-12T14:43:50Z

Build : SUCCESS

Build number : 856
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/5346/

Triggering tests

/morph test
/morph uvisor-test
/morph export-build

mbed-ci · 2018-01-12T17:16:24Z

Exporter Build : FAILURE

Build number : 527
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/5346/

cmonr · 2018-01-12T17:34:24Z

/morph export-build

Another "Pipe closed" exception...

mbed-ci · 2018-01-12T18:19:44Z

Exporter Build : SUCCESS

Build number : 529
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/5346/

mbed-ci · 2018-01-12T21:15:19Z

Test : FAILURE

Build number : 700
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/5346/700

0xc0170 · 2018-01-15T06:53:27Z

/morph test

mbed-ci · 2018-01-15T09:40:14Z

Test : SUCCESS

Build number : 706
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/5346/706

0xc0170 · 2018-01-15T11:06:00Z

Waiting for final approval from @alzix / @orenc17A (last round of review after changes that were requested earlier).

0xc0170 added the needs: review label Oct 19, 2017

bulislaw reviewed Oct 20, 2017

View reviewed changes

maciejbocianski mentioned this pull request Oct 24, 2017

Test set for critical section #5201

Merged

bulislaw reviewed Oct 24, 2017

View reviewed changes

bulislaw approved these changes Oct 25, 2017

View reviewed changes

0xc0170 reviewed Oct 25, 2017

View reviewed changes

0xc0170 approved these changes Oct 27, 2017

View reviewed changes

adbridge added needs: work and removed needs: review labels Oct 31, 2017

0xc0170 added the release-version: 5.7.0-rc1 label Nov 16, 2017

Steven Cartmell added 2 commits January 9, 2018 10:41

Move in_critical_section implementation into the HAL

061795c

- Add function to HAL hal_in_critical_section() - Wrap assert in FEATURE_UVISOR macro

cmonr added needs: CI and removed needs: work labels Jan 11, 2018

cmonr added needs: work and removed needs: CI labels Jan 11, 2018

0xc0170 added needs: CI and removed needs: work labels Jan 12, 2018

0xc0170 added needs: review and removed needs: CI labels Jan 15, 2018

alzix approved these changes Jan 16, 2018

View reviewed changes

orenc17 approved these changes Jan 16, 2018

View reviewed changes

0xc0170 added release-version: 5.8.0-rc1 ready for merge and removed needs: review labels Jan 16, 2018

cmonr merged commit 671c2d7 into ARMmbed:master Jan 16, 2018

cmonr removed the ready for merge label Jan 16, 2018

amq mentioned this pull request Mar 8, 2018

InterruptIn not working with EFM32 and tickless #6205

Closed

ghost deleted the feature-hal-spec-critical-section branch December 5, 2018 16:48


		interrupt_enable_counter--;
		critical_section_reentrancy_counter--;

Add Critical Section HAL API specification #5346

Add Critical Section HAL API specification #5346

Conversation

ghost commented Oct 19, 2017 • edited by theotherjimmy Loading

Description

Porting Guide

Status

TODO:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adbridge commented Oct 24, 2017

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

Choose a reason for hiding this comment

bulislaw commented Oct 24, 2017

ghost commented Oct 24, 2017

bulislaw commented Oct 24, 2017

bulislaw commented Oct 25, 2017 • 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

Choose a reason for hiding this comment

bulislaw commented Oct 25, 2017

bulislaw commented Oct 26, 2017

0xc0170 commented Oct 27, 2017

mbed-ci commented Oct 27, 2017

Triggering tests

mbed-ci commented Oct 27, 2017

bulislaw commented Oct 27, 2017

ghost commented Oct 30, 2017

0xc0170 commented Nov 2, 2017

mbed-ci commented Nov 2, 2017

Triggering tests

mbed-ci commented Nov 2, 2017

0xc0170 commented Nov 16, 2017

mbed-ci commented Nov 16, 2017

Triggering tests

mbed-ci commented Nov 16, 2017

mbed-ci commented Nov 16, 2017

cmonr commented Jan 11, 2018

mbed-ci commented Jan 11, 2018

0xc0170 commented Jan 12, 2018

mbed-ci commented Jan 12, 2018

Triggering tests

mbed-ci commented Jan 12, 2018

cmonr commented Jan 12, 2018

mbed-ci commented Jan 12, 2018

mbed-ci commented Jan 12, 2018

0xc0170 commented Jan 15, 2018

mbed-ci commented Jan 15, 2018

0xc0170 commented Jan 15, 2018

ghost commented Oct 19, 2017 •

edited by theotherjimmy

Loading

bulislaw commented Oct 25, 2017 •

edited

Loading