141 lines
5.3 KiB
Plaintext
141 lines
5.3 KiB
Plaintext
/*
|
|
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
|
|
|
|
This file is part of ChibiOS/RT.
|
|
|
|
ChibiOS/RT is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 3 of the License, or
|
|
(at your option) any later version.
|
|
|
|
ChibiOS/RT is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
---
|
|
|
|
A special exception to the GPL can be applied should you wish to distribute
|
|
a combined work that includes ChibiOS/RT, without being obliged to provide
|
|
the source code for any proprietary components. See the file exception.txt
|
|
for full details of how and when the exception can be applied.
|
|
*/
|
|
|
|
/**
|
|
* @page article_stop_os How to cleanly stop the OS
|
|
* Stopping the OS should not be normally required but there are scenarios
|
|
* where one might want the complete control over the system again.
|
|
* As example entering into a bootload mode, or invoking some flashing
|
|
* algorithm locked in ROM.<br>
|
|
* ChibiOS/RT does not have a shutdown API and there is a reason for this,
|
|
* stopping the kernel would not be enough, a well defined operations sequence
|
|
* is required.<br>
|
|
* The shutdown operation should always be implemented into the @p main()
|
|
* function because in that context the stack pointer is guaranteed to be
|
|
* in the area allocated by the startup code. Stopping from a thread would
|
|
* leave the stack pointer "somewhere".<br>
|
|
* The shutdown sequence should include the following steps, some steps
|
|
* are optional and depend on the application:
|
|
* - Safely stop critical threads. As example a thread that uses a File System
|
|
* should flush all the modified buffers to the persistent storage before
|
|
* terminating.<br>
|
|
* The system should be designed to request the thread termination using
|
|
* @p chThdTerminate() and then wait its termination using @p chThdWait().
|
|
* This phase can be skipped for non-critical threads.
|
|
* - Invoke the xxxStop() method on all the active device drivers, this
|
|
* disables the interrupt sources used by the various peripherals. This
|
|
* is required in order to not have interrupts after the shutdown that
|
|
* may invoke OS primitives.
|
|
* - Invoke chSysDisable().
|
|
* - Stop the system timer whose service routine invokes
|
|
* @p chSysTimerHandlerI().
|
|
* - Disable any other interrupt source that may invoke OS APIs. In general
|
|
* all the interrupt sources that have handlers declared by using the
|
|
* @p CH_IRQ_HANDLER() macro.
|
|
* - Perform any application related de-initialization.
|
|
* - Invoke chSysEnable().
|
|
* .
|
|
* Now the OS is stopped and you can safely assume there are nothing going on
|
|
* under the hood. From here you can also restart the OS after finishing your
|
|
* critical operations using the following sequence:
|
|
* - Invoke chSysDisable().
|
|
* - Restart the system timer.
|
|
* - Reinitialize the OS by invoking @p chSysInit().
|
|
* - Restart your device drivers using the @p xxxStart() methods.
|
|
* - Restart all your threads.
|
|
* .
|
|
* <h2>Example</h2>
|
|
* This is an example of an hypothetical application that have to shutdown
|
|
* the OS when a certain event is generated.
|
|
* @code
|
|
#include "ch.h"
|
|
#include "hal.h"
|
|
|
|
/* A shutdown flag.*/
|
|
bool_t shutdown_required;
|
|
|
|
/* Critical thread.*/
|
|
static void my_thread(void *p) {
|
|
|
|
while (!chThdShouldTerminate()) {
|
|
/* Normal thread activity code.*/
|
|
}
|
|
/* Thread de-initialization before terminating, here you put the critical
|
|
thread finalization code.*/
|
|
return 0;
|
|
}
|
|
|
|
/* Main program, it is entered with interrupts disabled.*/
|
|
void main(void) {
|
|
|
|
/* HAL initialization, you need to do this just once.*/
|
|
halInit();
|
|
|
|
/* Main loop, the main() function never exits.*/
|
|
while (TRUE) {
|
|
Thread *tp;
|
|
|
|
shutdown_required = FALSE;
|
|
|
|
/* ChibiOS/RT initialization. This function becomes an OS thread.*/
|
|
chSysInit();
|
|
|
|
/* Starting a device driver, SD2 in this case.*/
|
|
sdStart(&SD2, NULL);
|
|
|
|
/* Starting our critical thread.*/
|
|
tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(256),
|
|
NORMALPRIO, my_thread, &SD2);
|
|
|
|
/* Main thread activity into a loop.*/
|
|
while (!shutdown_required) {
|
|
/* Main activity, OS active until a shutdown becomes necessary.*/
|
|
}
|
|
|
|
/* Starting the shutdown sequence.*/
|
|
chThdTerminate(tp); /* Requesting termination. */
|
|
chThdWait(tp); /* Waiting for the actual termination. */
|
|
sdStop(&SD2); /* Stopping serial port 2. */
|
|
chSysDisable();
|
|
stop_system_timer();
|
|
stop_any_other_interrupt();
|
|
chSysEnable();
|
|
|
|
/* Now the main function is again a normal function, no more a
|
|
OS thread.*/
|
|
do_funny_stuff();
|
|
|
|
/* Restarting the OS but you could also stop the system or trigger a
|
|
reset instead.*/
|
|
chSysDisable();
|
|
}
|
|
}
|
|
* @endcode
|
|
* As you can see it is possible to jump in and out of the "OS mode" quite
|
|
* easily. Note that this is just an example, the real code could be very
|
|
* different depending on your requirements.
|
|
*/
|