Description

This PR is originated by cmorganBE in #914.

Application may restart the scheduler for each test case when it is running with a test framework. This requirement is useful for simulator port like posix. Some of dynamic analysis tools are difficult to run on an embedded target. valgrind is one of the example. With this feature, application writers can better utilize the test framework and valgrind to help diagnosis memory and thread bugs.

FreeRTOS kernel initialize some of the internal variables at declaration time. Therefore, init function is not required in kernel. To restart the scheduler, kernel state needs to be reset by setting internal variables to its default value before next time starting the scheduler.

In this PR:

Add functions to reset kernel state. These functions are only required for source file with initialized internal variables, including tasks.c, timer.c, croutine.c and heap_x.c.
- void vTaskResetState( void )
- void vTimerResetState( void )
- void vPortHeapResetState( void )
- void vCoRoutineResetState( void )

The change in the PR only re-initialize internal variables. Memory or other resource allocated during the time scheduler is running should still be freed by the port or application.

Test Steps section provides an example usage of these functions.

Test Steps

Testing with the following application on posix port.

#include <stdio.h>

#include "FreeRTOS.h"
#include "task.h"

void prvTestTask( void * pvParameters )
{
    vTaskDelay( pdMS_TO_TICKS( 1000 ) );
    printf( "End scheduler\r\n" );
    vTaskEndScheduler();
}

void main_test( void )
{
    for(;;)
   {
        xTaskCreate( prvTestTask, "Test", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY + 2, NULL );
        vTaskStartScheduler();
        vTaskResetState();   /* Without this function call, there will be exception. */
    }
}

Checklist:

[x] I have tested my changes. No regression in existing tests.
[ ] I have modified and/or added unit-tests to cover the code changes in this Pull Request.

Related Issue

914

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

codecov[bot] commented 7 months ago

Codecov Report

Attention: 19 lines in your changes are missing coverage. Please review.

Comparison is base (e68975f) 93.53% compared to head (f4c7106) 92.97%.

Files	Patch %	Lines
tasks.c	0.00%	15 Missing :warning:
timers.c	0.00%	4 Missing :warning:

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #944 +/- ## ========================================== - Coverage 93.53% 92.97% -0.56% ========================================== Files 6 6 Lines 3200 3219 +19 Branches 889 890 +1 ========================================== Hits 2993 2993 - Misses 92 111 +19 Partials 115 115 ``` | [Flag](https://app.codecov.io/gh/FreeRTOS/FreeRTOS-Kernel/pull/944/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FreeRTOS) | Coverage Δ | | |---|---|---| | [unittests](https://app.codecov.io/gh/FreeRTOS/FreeRTOS-Kernel/pull/944/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FreeRTOS) | `92.97% <0.00%> (-0.56%)` | :arrow_down: | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=FreeRTOS#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

cmorganBE commented 6 months ago

Does it look like this one might be merged in the near future?

@chinglee-iot I'll go back at some point and update my examples repo based on yours and what I've been doing here for thread shutdown. Otherwise the fixes to the posix port and shutdown have been fantastic at improving the usabiilty of FreeRTOS on linux for testing and testing under valgrind.

sonarcloud[bot] commented 6 months ago

Quality Gate passed

Issues
0 New issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

chinglee-iot commented 6 months ago

@cmorganBE This PR is merged. Special thanks to you for creating issues and PRs for this feature and discussing with us about the implementation detail.

FreeRTOS / FreeRTOS-Kernel

Support reset kernel state for restarting scheduler #944