API additions to formalize common routines in OSAL

[skliper]

During unit testing and for "restart" actions in a real system (either processor or power-cycle restarts) it is necessary to have a method of cleanly shutting down the system.

Currently, support for shutdown operations is left up to the BSP, and it is not consistently handled between the various BSPs or not handled at all in some cases.

OSAL needs to have formal procedures for a normal shutdown since there is often some clean up work to do, including but not limited to:

• Sanely exit all running tasks, or collect resources from tasks that have exited already
• Delete queues, mutexes and semaphores (this is particularly necessary on systems where this is a limited resource and may affect the ability to implement a warm restart)
• Unmount any non-volatile filesystems that may have been mounted
• Delete shared memory segments

This ticket will add some basic API calls to formalize the procedure and provide the hooks necessary to do this cleanup.

The POSIX layer needs this with the highest priority, as it is used extensively for testing where a sane shutdown/restart procedure is important.

[skliper]

Imported from trac issue 33. Created by jphickey on 2015-03-19T16:20:04, last modified: 2015-11-20T16:22:16

[skliper]

Trac comment by jphickey on 2015-03-19 16:28:38:

== The following new OSAL API calls are proposed ==

OS_API_Wait() - provide a standard way for a thread to go to sleep and be woken by external events. This is currently often done by calling "sleep()" in a loop however there are better ways of doing this.

OS_DeleteAllObjects() - provide a single call that can be used during shutdown to clean up all the resources that were allocated by OSAL.

OS_SystemShutdown() - a method for the user application to schedule a clean shutdown. This would cancel all user threads that are still running (leaving only the original "main" thread) and use the DeleteAllObjects() call to clean everything up before exiting. Note that this differs from the OS_ApplicationExit() because the ApplicationExit will exit immediately without cleaning anything up.

[skliper]

Trac comment by jphickey on 2015-03-19 16:51:00:

Branch name is "trac-33-wait-shutdown-api", commit [changeset:797301d] is ready for review

This contains an API definition for the new functions as well as a POSIX and RTEMS implementation for them. VxWorks is not yet modified, pending availability of a test platform. However the lack of a VxWorks implementation at this time does not cause any issues as no VxWorks BSPs are using these functions.

The "pc-linux" BSP is modified to make use of the OS_API_Wait() function for the idle loop, and the unit tests are modified to use the OS_DeleteAllObjects() call for clean up between tests where necessary.

[skliper]

Trac comment by glimes on 2015-05-18 19:56:39:

Recommend accept.

[skliper]

Trac comment by sstrege on 2015-05-19 10:32:37:

Looks good to me

[skliper]

Trac comment by sduran on 2015-06-01 14:57:13:

recommend accept.

[skliper]

Trac comment by sstrege on 2015-06-29 16:47:30:

Since all of the functions in the OSAL are API functions we may want to consider naming the new OS_API_Wait() function OS_Wait()?

[skliper]

Trac comment by jwilmot on 2015-06-30 11:01:39:

Error handling from the shutdown functions need to be considered. A commanded system restart/POR in flight is usually in response to fault management. We want to make sure there are minimal delays in the restart/POR execution and that the system can't fault out of the restart/POR process.

[skliper]

Trac comment by acudmore on 2015-06-30 12:55:33:

For Susie's last comment about renaming OS_API_Wait to OS_Wait.. Would this function ever be used in an application thread? If not, I think it makes sense to not give it a generic name.

For OS_SystemShutdown, would OS_ApplicationShutdown be a better name? Some might think that the SystemShutdown API would shut the system down in the case of Linux-like systems.

[skliper]

Trac comment by glimes on 2015-06-30 14:31:56:

Per CCB meeting 2015-06-30, accepted for inclusion in development,
after a few small updates we discussed in the meeting.

[skliper]

Trac comment by jphickey on 2015-06-30 15:05:33:

Per CCB meeting - This will be updated as follows:

• {{{OS_API_Wait()}}} will be renamed to {{{OS_IdleLoop()}}}
• {{{OS_SystemShutdown()}}} will be renamed to {{{OS_ApplicationShutdown()}}}

[skliper]

Trac comment by jphickey on 2015-07-01 23:20:55:

The "trac-33-wait-shutdown-api" branch has been updated, commit [changeset:ec6125c] addresses the CCB discussion and renames those functions per above.