From 0da7d5d0ec626ff70dc6dd4c28b6e3e06496ce48 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 6 May 2010 15:08:13 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1905 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 4 +- docs/src/integrationguide.dox | 95 +++++++++++++++++++++++++++++++++++++++++++ docs/src/portguide.dox | 17 ++++---- docs/src/stop_os.dox | 63 ++++++++++++++++++++++++++++ readme.txt | 7 ++-- 5 files changed, 175 insertions(+), 11 deletions(-) create mode 100644 docs/src/integrationguide.dox create mode 100644 docs/src/stop_os.dox diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 5aff3203e..69066c0cc 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -22,11 +22,14 @@ * ChibiOS/RT Articles and Code Examples: * - @subpage article_eclipse * - @subpage article_eclipse2 + * - @subpage article_integrationguide + * - @subpage article_portguide * - @subpage article_debug * - @subpage article_create_thread * - @subpage article_interrupts * - @subpage article_wakeup * - @subpage article_manage_memory + * - @subpage article_stop_os * - @subpage article_stacks * - @subpage article_roundrobin * - @subpage article_lifecycle @@ -35,7 +38,6 @@ * - @subpage article_saveram * - @subpage article_jitter * - @subpage article_timing - * - @subpage article_portguide * - @subpage article_design * . */ diff --git a/docs/src/integrationguide.dox b/docs/src/integrationguide.dox new file mode 100644 index 000000000..6eec61e75 --- /dev/null +++ b/docs/src/integrationguide.dox @@ -0,0 +1,95 @@ +/* + 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 . +*/ + +/** + * @page article_integrationguide Integration Guide + * All the delivered ChibiOS/RT demos are stand alone applications so if + * you just start your application from an existing demo there isn't any + * integration effort, you are simply using the existing makefiles, the + * default startup files etc, minimal effort.
+ * The matter is very different if you are going to integrate the OS into + * a different runtime framework or want to use a different build system, + * in that case you have the problem to integrate the OS source code into + * your application. + * + *

What this guide does not cover

+ * This guide has a limited scope, the following topics are handled elsewhere: + * - Porting the OS to different architectures or different compilers is + * not covered in this guide, see @ref article_portguide instead. + * - This guide does not describe any specific environment or development + * tool, it is assumed you already know in detail the environment you + * want to work with. + * . + * + *

Article Index

+ * - @ref integrationguide_kernel + * - @ref integrationguide_hal + * . + * @section integrationguide_kernel Integrating the Kernel + * This section covers the scenario where you want to use the ChibiOS/RT + * kernel into an existing application. In order to accomplish this you need + * to import in your project two components: + * - The portable kernel. + * - The port layer for your microcontroller. + * . + * See the @ref architecture for more details. + * You need to add the following files to your build process: + * - All the source files contained under ./os/kernel/src, note that + * you should add all of them even if you don't plan to use some of the + * subsystems. Unused subsystems can be excluded from the kernel + * configuration file @p chconf.h. + * - All the source files contained under + * ./os/@/@. Note that those + * could be both C source files and assembler source files and that some + * architectures have an extra directories layer containing files required + * for a specific platform. + * . + * You also need to add to the compiler options the following paths for + * searching header files: + * - The portable kernel headers ./os/kernel/include. + * - The port layer headers + * ./os/@/@. + * . + * @section integrationguide_hal Integrating the HAL + * If, in addition to the kernel as described in the previous section, you also + * need to integrate the HAL into your application you also need to import + * the following components: + * - HAL portable files. + * - Platform specific files. + * . + * See the @ref architecture for more details. + * You need to add the following files to your build process: + * - All the source files contained under ./os/hal/src, note that + * you should add all of them even if you don't plan to use some of the + * subsystems. Unused drivers can be excluded from the HAL configuration + * file @p halconf.h. + * - All the source files contained under + * ./os/hal/platforms/@. + * - All the source files contained under + * ./boards/@. + * . + * You also need to add to the compiler options the following paths for + * searching header files: + * - The portable HAL headers ./os/hal/src. + * - The platform layer headers + * ./os/hal/platforms/@. + * - The board description headers + * ./boards/@. + * . + */ diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox index d7de77485..3af53c4cf 100644 --- a/docs/src/portguide.dox +++ b/docs/src/portguide.dox @@ -40,17 +40,20 @@ * applies when porting the OS on a custom hardware using a supported * microcontroller. This task can be easily performed with the following * steps: - * -# Create a new directory under the ChibiOS/RT installation directory: - * ./projects/@ - * -# Copy the microcontroller demo code under the newly created directory. - * -# Customize the demo. Usually there are only four files that need to - * be modified: + * -# Create a new directory under ./boards and copy inside the board files + * from another board using the same microcontroller. + * -# Customize the board files: * - @p board.h This file contains the I/O pins setup for the uC, it - * may also contain other board-dependent settings, as example, clock and - * PLL settings. Customize this file depending on your target hardware. + * may also contain other board-dependent settings, as example, the clock + * frequency. Customize this file depending on your target hardware. * - @p board.c This file contains the initialization code, it is possible * you just need to customize @p board.h and not this file. If you have * some hardware specific initialization code then put it here. + * . + * -# Create a new directory under the ChibiOS/RT installation directory: + * ./projects/@ + * -# Copy an existing demo code under the newly created directory. + * -# Customize the demo: * - @p Makefile You may edit this file in order to remove the test related * sources and/or add you application source files. * - @p main.c It contains the demo simple code, clean it and write your diff --git a/docs/src/stop_os.dox b/docs/src/stop_os.dox new file mode 100644 index 000000000..4fb489a57 --- /dev/null +++ b/docs/src/stop_os.dox @@ -0,0 +1,63 @@ +/* + 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 . +*/ + +/** + * @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.
+ * 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.
+ * 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".
+ * 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.
+ * 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. + * . + */ diff --git a/readme.txt b/readme.txt index f8acafaa5..fbaf8d213 100644 --- a/readme.txt +++ b/readme.txt @@ -83,9 +83,10 @@ toolchains because the latest YAGARTO now uses that setting. It is still possible to use arm-elf- toolchains by editing the TRGT variable in the makefiles. -- Various documentation fixes, added an article covering debugging under - ChibiOS/RT, updated the article about interrupt handlers to cover also - fast interrupt sources. +- Various documentation fixes, added new articles covering debugging under + ChibiOS/RT, OS integration, OS stop and restart. Updated the article about + interrupt handlers to cover also fast interrupt sources, updated the article + about the OS porting. - Long overdue test code cleanup and documentation. - Added new test cases, now the coverage is again up to 100% except for the debug module that would require triggering system terminating tests (panics), -- cgit v1.2.3