Added PowerPC documentation files. Few fixes to the startup file.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1647 35acf78f-673a-0410-8e92-d51de3d6d3f4

6 files changed, 151 insertions, 22 deletions

diff --git a/os/ports/GCC/AVR/port.dox b/os/ports/GCC/AVR/port.dox
index 664714366..508315656 100644
--- a/os/ports/GCC/AVR/port.dox
+++ b/os/ports/GCC/AVR/port.dox
@@ -63,7 +63,7 @@
  *   used by the interrupt handlers.<br>

  *   The default for this value is @p 32, this space is allocated for each

  *   thread so be careful in order to not waste precious RAM space.<br>

- *   The default value is set into <b>./ports/AVR/chcore.h</b>.

+ *   The default value is set into <b>./os/ports/GCC/AVR/chcore.h</b>.

  * .

  * @ingroup AVR

  */

diff --git a/os/ports/GCC/MSP430/port.dox b/os/ports/GCC/MSP430/port.dox
index 4e8dca24c..09cff8a03 100644
--- a/os/ports/GCC/MSP430/port.dox
+++ b/os/ports/GCC/MSP430/port.dox
@@ -69,7 +69,7 @@
  *   used by the interrupt handlers.<br>

  *   The default for this value is @p 32, this space is allocated for each

  *   thread so be careful in order to not waste precious RAM space.<br>

- *   The default value is set into <b>./ports/MSP430/chcore.h</b>.

+ *   The default value is set into <b>./os/ports/GCC/MSP430/chcore.h</b>.

  * .

  * @ingroup MSP430

  */

diff --git a/os/ports/GCC/PPC/chcore.h b/os/ports/GCC/PPC/chcore.h
index dc09c75f5..1351531f5 100644
--- a/os/ports/GCC/PPC/chcore.h
+++ b/os/ports/GCC/PPC/chcore.h
@@ -18,10 +18,10 @@
 */

 

 /**

- * @file    PPCE200Z/chcore.h

- * @brief   PowerPC E200Zx architecture port macros and structures.

+ * @file    PPC/chcore.h

+ * @brief   PowerPC architecture port macros and structures.

  *

- * @addtogroup PPCE200Z_CORE

+ * @addtogroup PPC_CORE

  * @{

  */

 

diff --git a/os/ports/GCC/PPC/chtypes.h b/os/ports/GCC/PPC/chtypes.h
index ed380b457..e6eedbde0 100644
--- a/os/ports/GCC/PPC/chtypes.h
+++ b/os/ports/GCC/PPC/chtypes.h
@@ -18,9 +18,10 @@
 */

 

 /**

- * @file PPCE200Z/chtypes.h

- * @brief PPC E200Zx architecture port system types.

- * @addtogroup PPCE200Z_CORE

+ * @file    PPC/chtypes.h

+ * @brief   PowerPC architecture port system types.

+ *

+ * @addtogroup PPC_CORE

  * @{

  */

 

diff --git a/os/ports/GCC/PPC/crt0.s b/os/ports/GCC/PPC/crt0.s
index ee8d4c2ac..e12a87843 100644
--- a/os/ports/GCC/PPC/crt0.s
+++ b/os/ports/GCC/PPC/crt0.s
@@ -38,8 +38,20 @@ _boot_address:
         li          %r0, 0

         stwu        %r0, -8(%r1)

         /*

-        * Early initialization.

-        */

+         * IVPR initialization.

+         */

+        lis         %r4, __ivpr_base__@h

+        mtIVPR      %r4    

+        /*

+         * Small sections registers initialization.

+         */

+        lis         %r2, __sdata2_start__@h

+        ori         %r2, %r2, __sdata2_start__@l

+        lis         %r13, __sdata_start__@h

+        ori         %r13, %r13, __sdata_start__@l

+        /*

+         * Early initialization.

+         */

         bl          hwinit0

         /*

          * BSS clearing.

@@ -75,18 +87,6 @@ _boot_address:
         b           .dataloop

 .dataend:

         /*

-         * Small sections registers initialization.

-         */

-        lis         %r2, __sdata2_start__@h

-        ori         %r2, %r2, __sdata2_start__@l

-        lis         %r13, __sdata_start__@h

-        ori         %r13, %r13, __sdata_start__@l

-        /*

-         * IVPR initialization.

-         */

-        lis         %r4, __ivpr_base__@h

-        mtIVPR      %r4    

-        /*

          * Late initialization.

          */

         bl          hwinit1

diff --git a/os/ports/GCC/PPC/port.dox b/os/ports/GCC/PPC/port.dox
new file mode 100644
index 000000000..cc09f3f82
--- /dev/null
+++ b/os/ports/GCC/PPC/port.dox
@@ -0,0 +1,128 @@
+/*

+    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/>.

+*/

+

+/**

+ * @defgroup PPC PowerPC

+ * @details PowerPC port details. This section describes how the ChibiOS/RT

+ * features are implemented on this architecture.

+ *

+ * @section PPC_STATES Mapping of the System States in the PowerPC port

+ * The ChibiOS/RT logical @ref system_states are mapped as follow in the

+ * PowerPC port:

+ * - <b>Init</b>. This state is represented by the startup code and the

+ *   initialization code before @p chSysInit() is executed. It has not a

+ *   special hardware state associated.

+ * - <b>Normal</b>. This is the state the system has after executing

+ *   @p chSysInit(). Interrupts are enabled.

+ * - <b>Suspended</b>. Interrupts are disabled.

+ * - <b>Disabled</b>. Interrupts are enabled. This state is equivalent to the

+ *   Suspended state because there are no fast interrupts in this architecture.

+ * - <b>Sleep</b>. This state is entered with the execution of the specific

+ *   instruction @p <b>wait</b>.

+ * - <b>S-Locked</b>. Interrupts are disabled.

+ * - <b>I-Locked</b>. This state is equivalent to the SRI state, the

+ *   @p chSysLockI() and @p chSysUnlockI() APIs do nothing (still use them in

+ *   order to formally change state because this may change).

+ * - <b>Serving Regular Interrupt</b>. Normal interrupt service code.

+ * - <b>Serving Fast Interrupt</b>. Not present in this architecture.

+ * - <b>Serving Non-Maskable Interrupt</b>. The PowerPC has several non

+ *   maskable interrupt sources that can be associated to this state.

+ * - <b>Halted</b>. Implemented as an infinite loop with interrupts disabled.

+ * .

+ * @section PPC_NOTES The PowerPC port notes

+ * The PowerPC port is organized as follow:

+ * - The @p main() function is invoked in privileged mode.

+ * - Each thread has a private stack with extra storage for interrupts

+ *   servicing.

+ * - The Book-E Decrementer Timer, mapped on IVOR10, is used for system tick.

+ * - Interrupt nesting is not currently supported.

+ * .

+ * @ingroup ports

+ */

+

+/**

+ * @defgroup PPC_CONF Configuration Options

+ * @brief PowerPC Configuration Options.

+ * @details The PowerPC port allows some architecture-specific configurations

+ * settings that can be specified externally, as example on the compiler

+ * command line:

+ * - @p INT_REQUIRED_STACK, this value represent the amount of stack space used

+ *   by an interrupt handler between the @p extctx and @p intctx

+ *   structures.

+ *   The default for this value is @p 128 bytes, this space is allocated for

+ *   each thread so be careful in order to not waste precious RAM space.<br>

+ *   The default value is set into <b>./os/ports/GCC/PPC/chcore.h</b>.

+ * - @p ENABLE_WFI_IDLE, if set to @p TRUE enables the use of the @p <b>wait</b>

+ *   instruction from within the idle loop. This is defaulted to 0 because

+ *   it can create problems with some debuggers. Setting this option to 1

+ *   reduces the system power requirements.

+ * .

+ * @ingroup PPC

+ */

+

+/**

+ * @defgroup PPC_CORE Core Port Implementation

+ * @brief PowerPC specific port code, structures and macros.

+ *

+ * @ingroup PPC

+ */

+

+/**

+ * @defgroup PPC_STARTUP Startup Support

+ * @brief PPC startup code support.

+ * @details ChibiOS/RT provides its own generic startup file for the PowerPC

+ * port.

+ * Of course it is not mandatory to use it but care should be taken about the

+ * startup phase details.

+ *

+ * <h2>Startup Process</h2>

+ * The startup process, as implemented, is the following:

+ * -# The stacks pointer is initialized into the area defined in the linker

+ *    script.

+ * -# The IVPR register is setup according to the linker script.

+ * -# The R2 and R13 registers are set to pointer to the SDA areas according

+ *    to the EABI specification.

+ * -# An early initialization routine @p hwinit0 is invoked, if the symbol is

+ *    not defined then an empty default routine is executed (weak symbol).

+ * -# DATA and BSS segments are initialized.

+ * -# A late initialization routine @p hwinit1 is invoked, if the symbol not

+ *    defined then an empty default routine is executed (weak symbol).<br>

+ *    This late initialization function is also the proper place for a

+ *    @a bootloader, if your application requires one.

+ * -# The @p main() function is invoked with the parameters @p argc and @p argv

+ *    set to zero.

+ * -# Should the @p main() function return a branch is performed to the weak

+ *    symbol @p main_exit. The default code is an endless empty loop.

+ * .

+ * <h2>Expected linker symbols</h2>

+ * The startup code starts at the symbol @p _boot_address and expects the

+ * following symbols to be defined in the linker script:

+ * - @p __ram_end__ RAM end location +1.

+ * - @p __sdata2_start__ small constants data area

+ * - @p __sdata_start__ small variables data area

+ * - @p __romdata_start__ address of the data segment source read only data.

+ * - @p __data_start__ data segment start location.

+ * - @p __data_end__ data segment end location +1.

+ * - @p __bss_start__ BSS start location.

+ * - @p __bss_end__ BSS end location +1.

+ * - @p __ivpr_base__ IVPR register initialization address.

+ * .

+ * @ingroup PPC

+ * @file PPC/crt0.s Startup code.

+ */