changeset 3177:58eda6fed5a5

New files -- Kinetis variant documentation. [Bug 1001580]
author vae
date Fri, 18 May 2012 21:27:23 +0000
parents 7c9ce2220671
children a56d5166ddf6
files packages/hal/cortexm/kinetis/twr_k70f120m/current/ChangeLog packages/hal/cortexm/kinetis/twr_k70f120m/current/doc/twr_k70f120m.sgml packages/hal/cortexm/kinetis/var/current/ChangeLog packages/hal/cortexm/kinetis/var/current/doc/kinetis.sgml packages/hal/cortexm/kinetis/var/current/doc/kinetis_begin.sgml packages/hal/cortexm/kinetis/var/current/doc/kinetis_end.sgml
diffstat 6 files changed, 557 insertions(+), 3 deletions(-) [+]
line wrap: on
line diff
--- a/packages/hal/cortexm/kinetis/twr_k70f120m/current/ChangeLog
+++ b/packages/hal/cortexm/kinetis/twr_k70f120m/current/ChangeLog
@@ -1,3 +1,8 @@
+2012-05-18  Ilija Kocho  <ilijak@siva.com.mk>
+
+	* doc/twr_k70f120m.sgml:
+	New file -- TWR-K70F120M platform documentation. [Bug 1001580]
+
 2012-05-17  Ilija Kocho  <ilijak@siva.com.mk>
 
 	* cdl/hal_cortexm_kinetis_twr_k70f120m.cdl:
new file mode 100644
--- /dev/null
+++ b/packages/hal/cortexm/kinetis/twr_k70f120m/current/doc/twr_k70f120m.sgml
@@ -0,0 +1,165 @@
+<!-- DOCTYPE part  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
+
+<!-- {{{ Banner                                                     -->
+
+<!-- =============================================================== -->
+<!--                                                                 -->
+<!--     twr_k70f120m.sgml                                        -->
+<!--                                                                 -->
+<!--     TWR-K70F120M board documentation.                        -->
+<!--                                                                 -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
+<!-- =============================================================== -->
+<!-- Copyright (C) 2012 Free Software Foundation, Inc. -->
+<!-- This material may be distributed only subject to the terms      -->
+<!-- and conditions set forth in the Open Publication License, v1.0  -->
+<!-- or later (the latest version is presently available at          -->
+<!-- http://www.opencontent.org/openpub/)                            -->
+<!-- Distribution of the work or derivative of the work in any       -->
+<!-- standard (paper) book form is prohibited unless prior           -->
+<!-- permission obtained from the copyright holder                   -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTEND####                                     -->
+<!-- =============================================================== -->
+<!-- #####DESCRIPTIONBEGIN####                                       -->
+<!--                                                                 -->
+<!-- Author(s):   Ilija Kocho                                        -->
+<!-- Contact(s):  ilijak@siva.com.mk                                 -->
+<!-- Date:        2012/01/10                                         -->
+<!-- Version:     0.01                                               -->
+<!--                                                                 -->
+<!-- ####DESCRIPTIONEND####                                          -->
+<!-- =============================================================== -->
+
+<!-- }}} -->
+
+<!--<part id="hal-cortexm-kinetis"><title>Freescale Kinetis Family Support</title>-->
+
+<refentry id="kinetis-twr-k70f120m">
+  <refmeta>
+    <refentrytitle>TWR-K70F120M Development kit</refentrytitle>
+  </refmeta>
+  <refnamediv>
+    <refname>CYGPKG_HAL_CORTEXM_KINETIS_TWR_K70F120M</refname>
+    <refpurpose>eCos Support for Freescale TWR-K70F120M development kit</refpurpose>
+  </refnamediv>
+  
+  <refsect1 id="kinetis-twr-k70f120m-description"><title>Description</title>
+    <para>
+    The Freescale TWR-K70F120M is a development kit for <link linkend="hal-cortexm-kinetis-var">
+    Freescale Kinetis</link> Cortex-M4 based micro-controllers. It covers K70, K60, K10 and K20
+    microcontroller subfamilies. K70FN1M0 is a high end member comprising on-chip 1 MiB FLASH
+    and 128 KiB SRAM memory as well as a 16 KiB unified cache.
+    K70 parts are equipped with a rich set of communication interfaces including Ethernet USB, UARTs
+    CAN, SPI and I2C. They also have a Graphics controller and a DMA controller, as well as FlexBus and SDRAM
+    external memory interfaces. They are mixed signal devices featuring a 16 bit ADC and a 12 bit DAC. 
+    </para>
+  </refsect1>
+  <refsect1 id="kinetis-twr-k70f120m-config"><title>Configuration</title>
+    <refsect2 id="kinetis-twr-k70f120m-config-hardware"><title>Hardware Setup</title>
+      <refsect3 id="kinetis-twr-k70f120m-config-hardware-cpu"><title>TWR-K70F120M setup</title>
+      <para>
+      Factory jumper settings on TWR-K70F120M are fitted for standalone operation of the board.
+      In order to use it with the Ethernet PHY from TWR-SER, some jumpers have to be changed
+      on both TWR-K70F120M and TWR-SER. Jumper settings for TWR-SER are given in
+      <link linkend="kinetis-twr-k60n512-config">TWR-K60N512 Configuration</link> and here are the TWR-K70F120M
+      settings.
+      </para>
+      <table frame="all"><title>TWR-K70F120M Jumper setting</title>
+        <tgroup cols="3" align="center">
+          <colspec colnum="1" colname="jumper" colwidth="1*" >
+          <colspec colnum="2" colname="jumpset" colwidth="1*" >
+          <colspec colnum="3" colname="desc" colwidth="3*" >
+          <thead>
+            <row>
+              <entry>Jumper</entry>
+              <entry>Setting</entry>
+              <entry>Description</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>J19</entry>
+              <entry>OFF</entry>
+              <entry>On board 50MHz oscillator is not powered</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+      </refsect3>
+    </refsect2>
+    <refsect2 id="kinetis-twr-k70f120m-config-ecos"><title>eCos Configuration</title>
+      <refsect3 id="twr-k70f120m-clocking"><title>Clocking</title>
+      <para>
+      The TWR-K70F120M package defines requirements for the platform clocking.
+      </para>
+      </refsect3>  
+      <refsect3 id="twr-k70f120m-memory"><title>Memory</title>
+      <para>
+      The K70 has two 64 KiB SRAM banks giving a total of 128KiB on chip SRAM. In addition, on-board there is
+      128 MiB of external RAM (SDRAM) and 256 MiB of NAND Flash.
+      External RAM is divided in two regions: 
+      </para>
+      <variablelist>
+        <varlistentry>
+          <term>ram</term>
+          <listitem><para> Regular RAM.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>ramnc</term>
+          <listitem><para>Non cached RAM. This region contains <literal>.noncache</literal> section.</para></listitem>
+        </varlistentry>
+      </variablelist>
+      </refsect3>
+    </refsect2>
+    <refsect2 id="kinetis-twr-k70f120m-memory"><title>Memory layouts</title>
+      <para>
+      Additional platform memory layouts follow the <link linkend="kinetis-var-memory">variant</link>
+      ones only by putting all RAM sections except <literal>.sram</literal> in the <literal>ram</literal> region.
+      The linker file names incorporate the segment <filename>_extram_</filename>.
+      </para>
+      <refsect3 id="kinetis-twr-k70f120m-memory-ldscript-location"><title>Linker 
+      Script Location</title>
+      <para>
+      Linker scripts are found at:
+      <filename class="directory">hal/kinetis/twr-k70f120m/&lt;version&gt;/include/pkgconf</filename>
+      </para>
+      </refsect3>
+      <refsect3 id="kinetis-twr-k70f120m-memory-ldscript-naming"><title>Linker Script Naming</title>
+      <para>
+      Linker script file names have following form:
+      <filename>mlt_kinetis_&lt;NVM&gt;_&lt;SRAM&gt;_&lt;STARTUP_extram.ldi</filename>
+      where <filename>PLF</filename> is an optional extension for platform specific scripts and
+      other segments have meaning as described <link linkend="kinetis-var-table-ldscript-naming">here</link>.
+      </para>
+      </refsect3>
+    </refsect2>
+    <refsect2 id="kinetis-twr-k70f120m-startup"><title>Startup types</title>
+      <para>
+      The platform startup <literal>CYG_HAL_STARTUP_PLF</literal> offers the following startups:
+      </para>
+      <variablelist>
+        <varlistentry>
+          <term><literal>ROM (Platform)</literal></term>
+          <listitem><para>Normal startup for stand-alone operation. The eCos image has to be flashed
+            in internal flash. External RAM is used as main memory.
+            </para>
+            <para>
+            Note: This startup has a name like the one in the variant but generates different images 
+            by invoking a different set of linker scripts.
+            </para></listitem></varlistentry>
+        <varlistentry>
+          <term><literal>RAM (Platform)</literal></term>
+          <listitem><para>The image is loaded in external RAM by means of RedBoot.
+            </para></listitem></varlistentry>
+        <varlistentry>
+          <term><literal>ByVariant</literal></term>
+          <listitem><para>Activates the <link linkend="kinetis-var-startup">variant startup types</link>.
+            </para></listitem></varlistentry>
+      </variablelist>
+    </refsect2>
+  </refsect1>
+</refentry>
+
+<!--</part>-->
--- a/packages/hal/cortexm/kinetis/var/current/ChangeLog
+++ b/packages/hal/cortexm/kinetis/var/current/ChangeLog
@@ -1,3 +1,10 @@
+2012-05-18  Ilija Kocho  <ilijak@siva.com.mk>
+
+	* doc/kinetis_begin.sgml:
+	* doc/kinetis_end.sgml:
+	* doc/kinetis.sgml:
+	New files -- Kinetis variant documentation. [Bug 1001580]
+
 2012-05-17  Ilija Kocho  <ilijak@siva.com.mk>
 
 	* cdl/hal_cortexm_kinetis.cdl:
@@ -16,8 +23,8 @@ 2012-05-04  Ilija Kocho  <ilijak@siva.co
 	* include/var_io.h:
 	* src/kinetis_ddram.c:
 	* src/kinetis_misc.c:
-    Add: Clocking support for PLL1 (K70), DDRAM controller
-    Cache, eDMA - 32 chan. [Bugzilla 1001579]
+	Add: Clocking support for PLL1 (K70), DDRAM controller
+	Cache, eDMA - 32 chan. [Bugzilla 1001579]
 
 2012-01-11  Tomas Frydrych <tomas@sleepfive.com>
 
@@ -31,7 +38,7 @@ 2012-01-11  Tomas Frydrych <tomas@sleepf
 2012-01-05  Ilija Kocho  <ilijak@siva.com.mk>
 
 	* cdl/kinetis_irq_scheme.cdl
-    Centralized IRQ priority scheme.
+	Centralized IRQ priority scheme.
 
 	* cdl/hal_cortexm_kinetis.cdl:
 	* cdl/kinetis_flexbus.cdl
new file mode 100644
--- /dev/null
+++ b/packages/hal/cortexm/kinetis/var/current/doc/kinetis.sgml
@@ -0,0 +1,303 @@
+<!-- DOCTYPE part  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
+
+<!-- {{{ Banner                                                     -->
+
+<!-- =============================================================== -->
+<!--                                                                 -->
+<!--     kinetis.sgml                                                -->
+<!--                                                                 -->
+<!--     KINETIS          documentation.                             -->
+<!--                                                                 -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
+<!-- =============================================================== -->
+<!-- Copyright (C) 2012 Free Software Foundation, Inc. -->
+<!-- This material may be distributed only subject to the terms      -->
+<!-- and conditions set forth in the Open Publication License, v1.0  -->
+<!-- or later (the latest version is presently available at          -->
+<!-- http://www.opencontent.org/openpub/)                            -->
+<!-- Distribution of the work or derivative of the work in any       -->
+<!-- standard (paper) book form is prohibited unless prior           -->
+<!-- permission obtained from the copyright holder                   -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTEND####                                     -->
+<!-- =============================================================== -->
+<!-- #####DESCRIPTIONBEGIN####                                       -->
+<!--                                                                 -->
+<!-- Author(s):   Ilija Kocho                                        -->
+<!-- Contact(s):  ilijak@siva.com.mk                                 -->
+<!-- Date:        2012/01/10                                         -->
+<!-- Version:     0.01                                               -->
+<!--                                                                 -->
+<!-- ####DESCRIPTIONEND####                                          -->
+<!-- =============================================================== -->
+
+<!-- }}} -->
+
+<!-- <part id="hal-cortexm-kinetis"><title>Freescale Kinetis Family Support</title> -->
+
+<refentry id="hal-cortexm-kinetis-var">
+  <refmeta>
+    <refentrytitle>Freescale Kinetis Variant</refentrytitle>
+  </refmeta>
+  <refnamediv>
+    <refname><literal>CYGPKG_HAL_CORTEXM_KINETIS</literal></refname>
+    <refpurpose>eCos Support for Freescale Kinetis Micro-controllers</refpurpose>
+  </refnamediv>
+  
+  <refsect1 id="hal-cortexm-kinetis-var-description"><title>Description</title>
+    <para>
+    Kinetis is a Freescale microcontroller family based on the ARM Cortex-M4 core. The
+    family consists of subfamilies: K10, K20, K30, K40, K50, K60 and K70
+    that gradually add-on performance and features.
+    </para>
+    <para>
+    The Kinetis variant HAL provides generic support for hardware found on some
+    or all Kinetis members. The variant package <literal>CYGPKG_HAL_CORTEXM_KINETIS</literal>
+    provides configurable components that aim to support the complete set of options
+    found in the Kinetis family.
+    </para>
+  </refsect1>
+  <refsect1 id="kinetis-var-sup"><title>What's supported</title>
+    <para>
+    The current Kinetis software includes a Kinetis variant HAL, some Platform BSPs,
+    as well as DMA, UART, Wallclock, Ethernet and SPI support.
+    </para>
+  </refsect1>
+  <refsect1 id="kinetis-var-config"><title>Configuration</title>
+    <para>    Kinetis is a set of families of micro-controllers packed with highly configurable components.
+    In order to facilitate system configuration for the user, the CDL configuration items are organized as a set of
+    expert components. Typically, for a given peripheral, the user chooses the required hardware
+    options and desirable parameters, and the respective CDL configuration options and settings are calculated from these.
+    If it is not possible to achieve exact values, the configurator attempts to provide 
+    approximate settings, then the user can manually do the fine tuning.
+    <refsect2 id="kinetis-var-cpu-select"><title>Kinetis Part Selection</title>
+      <para>
+      Within a family and/or across families the chips are further differentiated by their features
+      such as: optional FPU, amount of memory, etc. The family member options are reflected in the
+      controller naming scheme (see respective Freescale Kinetis product brief(s) and reference manual(s)). 
+      The Kinetis part builder <literal>CYGHWR_HAL_CORTEXM_KINETIS</literal>, respects this naming scheme and
+      enables the user to interactively configure eCos for the desired part by selecting
+      the requested part's name segments.
+      Based on user input, the CDL computes the part-specific eCos configuration. This includes calculation
+      of on-chip FLASH and SRAM layout as well as the activation/deactivation of options such as FPU and
+      Ethernet.
+      </para>
+    </refsect2>
+    <refsect2 id="kinetis-var-clocking"><title>Clocking</title>
+      <para>
+      Kinetis is packed with a rich set of clocking options provided by the Multipurpose Clock Generator - MCG.
+      Dependent on the part, MCG can have outlets for one or two external frequency reference sources 
+      <emphasis>OSC</emphasis> and <emphasis>OSC1</emphasis> and one
+      or two PLL oscillators <emphasis>PLL</emphasis> and <emphasis>PLL1</emphasis>.
+      Each of the external frequency reference sources can be either a crystal or external
+      oscillator and associated with either or both PLL oscillators. <emphasis>OSC</emphasis> can also be a
+      reference source for the FLL oscillator.
+      Besides <emphasis>OSC</emphasis> and <emphasis>OSC1</emphasis>, there are additional clock sources
+      including two RC oscillators and a (battery backed) RTC clock with it's own 32768 Hz crystal oscillator.
+      MCG gives the user a wide choice of system and peripheral clock source(s) that can be
+      external clock(s), internal clocks, a PLL or the FLL. An external or on-chip
+      oscillator can be used as a system clock or as a reference for PLL/FLL oscillator(s).
+      </para>
+      <note><para> In the documentation of Kinetis parts with two oscillators, <emphasis>OSC</emphasis>
+      and <emphasis>PLL</emphasis> are described as <emphasis>OSC0</emphasis> and <emphasis>PLL0</emphasis> respectively.
+      </para></note>
+      <para>
+      Clocking component <literal>CYGHWR_HAL_CORTEXM_KINETIS_CLOCKING</literal> provides some expert
+      functionality in order to facilitate clock system configuration. Normally, the user sets requirements:
+      clock source, clock reference, desired core frequency and upper limits for peripheral
+      clock frequencies. The component automatically calculates MCG and other peripheral register
+      settings in order to achieve the required clock frequencies. This setting is not always perfect but
+      fits (exactly or close) for commonly used frequencies. If necessary, the user can fine tune the
+      clock settings interactively using the eCos Configuration Tool.
+      The two clock sources are named:
+      </para>
+      <variablelist>
+        <varlistentry>
+          <term>System clock</term>
+          <listitem><para>The clock source that provides the clock for the Cortex-M core.
+            It may also provide the clock for some peripherals.
+            </para></listitem></varlistentry>
+        <varlistentry>
+          <term>Auxiliary clock</term>
+          <listitem><para>This is optional and may provide a clock for peripherals but not for the Cortex-M core.
+            </para></listitem></varlistentry>
+      </variablelist>
+      <para>
+      The user can select which source is the system clock. The choices for system clock are: <emphasis>PLL</emphasis>,
+      <emphasis>FLL</emphasis>, <emphasis>External reference clock</emphasis> and, when available, <emphasis>PLL1</emphasis>.
+      The auxiliary clock, when available is: <emphasis>PLL</emphasis> if <emphasis>PLL1</emphasis> is selected 
+      for system the clock or <emphasis>PLL1</emphasis> if any other source is selected for the system clock.
+      </para>
+    </refsect2>
+    <refsect2 id="kinetis-var-memory"><title>Memory layouts</title>
+      <para>
+      The memory layouts and startup types which don't employ external memory should be applicable to all
+      Kinetis platforms so they are defined and maintained at the variant level.
+      This is somewhat different than common eCos practice but has some advantages brought by universal,
+      single copy linker scripts for single chip configurations. The linker scripts are further enhanced/generalized
+      by utilization of macros provided by CDL and calculated on the basis of the
+      <link linkend="kinetis-var-cpu-select">selected Kinetis part</link>.
+      </para>
+      <refsect3 id="kinetis-var-memory-ldscript-location"><title>Variant Linker 
+      Script Location</title>
+      <para>
+      Variant linker scripts are found at:
+      <filename class="directory">hal/kinetis/var/&lt;version&gt;/include/pkgconf</filename>
+      </para>
+      </refsect3>
+      <refsect3 id="kinetis-var-memory-ldscript-naming"><title>Linker Script Naming</title>
+      <para>
+      Linker script file names are composed of segments
+      <filename>mlt_kinetis_&lt;NVM&gt;_&lt;SRAM&gt;_&lt;STARTUP&gt;[_&lt;PLF&gt;].ldi</filename>
+      where <filename>PLF</filename> is an optional extension for platform specific scripts and
+      other segments have meanings as described in the following table.
+      </para>
+      <table frame="all" id="kinetis-var-table-ldscript-naming"><title>Linker script name segments</title>
+        <tgroup cols="3" align="center">
+          <colspec colnum="1" colname="segment" colwidth="1*" >
+          <colspec colnum="2" colname="desc" colwidth="2*" >
+          <colspec colnum="3" colname="values" colwidth="1*" >
+          <thead>
+            <row>
+              <entry>Segment</entry>
+              <entry>Description</entry>
+              <entry>Values</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><filename>NVM</filename></entry>
+              <entry>Kinetis non-volatile memory configuration</entry>
+              <entry>
+              <filename>flash</filename>,
+              <filename>flexnvm</filename>
+              </entry>
+            </row>
+            <row>
+              <entry><filename>SRAM</filename></entry>
+              <entry>SRAM memory sectioning</entry>
+              <entry>
+              <filename>unisram</filename>,
+              <filename>sram2s</filename>
+              </entry>
+            </row>
+            <row>
+              <entry><filename>STARTUP</filename></entry>
+              <entry>Startup type</entry>
+              <entry>
+              <filename>rom</filename>,
+              <filename>sram</filename>
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+      <para>
+      <note><para>Never attempt to flash Kinetis with an image for SRAM startup. SRAM startup images
+      do not contain a <literal>.flash_conf</literal> section so random contents may be written in 
+      flash protection area and lock your Kinetis device. This lock-out can be permanent.
+      </para></note>
+      </refsect3>
+      <refsect3 id="kinetis-var-memory-plf-spec"><title>Platform Specific Memory Layouts</title>
+      <para>
+      Platforms, if needed, can provide their own layouts in addition to the variant ones. Typically
+      they will cover systems with external memory. The <link linkend="kinetis-var-startup">
+      startup type</link> implicitly determines whether variant and platform defined
+      layout shall be used.
+      </para>
+      </refsect3>
+      <refsect3 id="kinetis-var-memory-sram"><title>On-chip SRAM</title>
+      <para>
+      Kinetis on chip SRAM memory consists of two equal banks that occupy consecutive locations anchored
+      below and above <literal>0x20000000</literal>. This fact is reflected in memory layout scripts.
+      There are linker scripts that treat SRAM as a single section (<filename>unisram</filename>) or as
+      2 separate sections (<filename>sram2s</filename>).
+      </para>
+      </refsect3>
+      <refsect3 id="kinetis-var-memory-flash"><title>On-chip FLASH</title>
+      <para>
+      Kinetis on-chip flash contains a special area <literal>[0x400-0x40F]</literal> 
+      that holds the flash security configuration. In order to preserve this area from 
+      accidental writing and at the same time provide regular access,
+      a custom linker section <literal>.flash_conf</literal> is created. In addition, in order
+      to utilize the FLASH pool below <literal>0x400</literal> the <emphasis>USER_SECTION</emphasis> 
+      <literal>.kinetis_misc</literal> is defined. This section typically contains 
+      code parts from <filename>kinetis_misc.c</filename>.
+      </para>
+      </refsect3>
+      <refsect3 id="kinetis-var-memory-cache"><title>Cache</title>
+      <para>
+      Kinetis members with operating frequencies of 120 MHz and 150 MHz are equipped with cache memory.
+      Due to the Harvard architecture, there are two unified cache memories connected to code 
+      - <emphasis>PC</emphasis> and system - <emphasis>PS</emphasis> buses respectively. One of the
+      issues with caching is operation with bus masters such as DMA, Ethernet controller, etc.
+      In order to keep shared data such
+      as buffers and transfer descriptors synchronous, a part of cached data may have to be flushed
+      and/or invalidated. In some cases, an alternative can be the usage of non-cacheable memory
+      regions. <literal>CYGHWR_HAL_NON_CACHABLE</literal> provides for the configuration of non-cacheable
+      memory. If some bus masters have provision for non-cacheable memory, such configuration options
+      can be parented by <literal>CYGHWR_HAL_NON_CACHABLE</literal>.
+      </para>
+      </refsect3>
+      <refsect2 id="kinetis-var-startup"><title>Startup types</title>
+        <para>
+        There are <emphasis>two levels</emphasis> of startup type:
+        </para>
+        <variablelist>
+          <varlistentry>
+            <term>Variant <literal>CYG_HAL_STARTUP_VAR</literal></term>
+            <listitem><para>This is always present and provides startup
+              types for systems without external memory.
+              </para></listitem></varlistentry>
+          <varlistentry>
+            <term>Platform <literal>CYG_HAL_STARTUP_PLF</literal></term>
+            <listitem><para>This is optional and is 
+              provided by a platform package. Typically it provides startup types for systems
+              that employ external memory.
+              </para></listitem></varlistentry>
+        </variablelist>
+        <para>
+        </para>
+        <para>
+        When present, the platform startup overloads the variant startup and has precedence over it.
+        User can activate the variant startup by setting platform startup to
+        <literal>ByVariant</literal>.
+        </para>
+        <refsect3 id="kinetis-var-startup-byvariant"><title>Startup types provided variant</title>
+        <para>
+        The following startup types are provided for Kinetis at the variant level:
+        </para>
+        <variablelist>
+          <varlistentry>
+            <term><literal>ROM</literal></term>
+            <listitem><para>Normal startup for stand-alone operation. eCos image has to be flashed
+              in internal flash;
+              </para></listitem></varlistentry>
+          <varlistentry>
+            <term><literal>SRAM</literal></term>
+            <listitem><para>Image is loaded in internal SRAM by means of JTAG/SWD and executed
+              under debugger control.
+              </para></listitem></varlistentry>
+        </variablelist>      
+        <note><para>(IMPORTANT) Never, ever attempt to flash Kinetis with an image for SRAM startup.
+        SRAM startup images do not contain a <literal>.flash_conf</literal> section so random contents
+        may be written to the flash protection area and lock your Kinetis device. This lock-out can be permanent.
+        </para></note>
+        </refsect3>
+      </refsect2>
+      <refsect2 id="kinetis-interrupt-priority-scheme"><title>Interrupt priority scheme</title>
+        <para>
+        In case of multiple simultaneous interrupts, interrupt service request resolution is based
+        on a relative comparison of interrupt priorities, rather than on individual interrupt priority values.
+        <emphasis>Interrupt priority scheme</emphasis> gives a consolidated overview and control
+        of priorities of all interrupt sources. Interrupt priorities can be provided by either variant
+        <literal>CYGHWR_HAL_DEVS_IRQ_PRIO_SCHEME_VAR</literal>
+        or platform <literal>CYGHWR_HAL_DEVS_IRQ_PRIO_SCHEME</literal>.
+        </para>
+      </refsect2>
+    </refsect1>
+    
+  </refentry>
+  
+  <!--</part>-->
new file mode 100644
--- /dev/null
+++ b/packages/hal/cortexm/kinetis/var/current/doc/kinetis_begin.sgml
@@ -0,0 +1,37 @@
+<!-- DOCTYPE part  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
+
+<!-- {{{ Banner                                                     -->
+
+<!-- =============================================================== -->
+<!--                                                                 -->
+<!--     kinetis_begin.sgml                                          -->
+<!--                                                                 -->
+<!--     Kinetis documentation.                                      -->
+<!--                                                                 -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
+<!-- =============================================================== -->
+<!-- Copyright (C) 2012 Free Software Foundation, Inc. -->
+<!-- This material may be distributed only subject to the terms      -->
+<!-- and conditions set forth in the Open Publication License, v1.0  -->
+<!-- or later (the latest version is presently available at          -->
+<!-- http://www.opencontent.org/openpub/)                            -->
+<!-- Distribution of the work or derivative of the work in any       -->
+<!-- standard (paper) book form is prohibited unless prior           -->
+<!-- permission obtained from the copyright holder                   -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTEND####                                     -->
+<!-- =============================================================== -->
+<!-- #####DESCRIPTIONBEGIN####                                       -->
+<!--                                                                 -->
+<!-- Author(s):   Ilija Kocho                                        -->
+<!-- Contact(s):  ilijak@siva.com.mk                                 -->
+<!-- Date:        2012/01/10                                         -->
+<!-- Version:     0.01                                               -->
+<!--                                                                 -->
+<!-- ####DESCRIPTIONEND####                                          -->
+<!-- =============================================================== -->
+
+<!-- }}} -->
+
+<part id="hal-cortexm-kinetis"><title>Freescale Kinetis Family Support</title>
new file mode 100644
--- /dev/null
+++ b/packages/hal/cortexm/kinetis/var/current/doc/kinetis_end.sgml
@@ -0,0 +1,37 @@
+<!-- DOCTYPE part  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
+
+<!-- {{{ Banner                                                     -->
+
+<!-- =============================================================== -->
+<!--                                                                 -->
+<!--     kinetis_end.sgml                                             -->
+<!--                                                                 -->
+<!--     Kinetis documentation.                                      -->
+<!--                                                                 -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
+<!-- =============================================================== -->
+<!-- Copyright (C) 2012 Free Software Foundation, Inc. -->
+<!-- This material may be distributed only subject to the terms      -->
+<!-- and conditions set forth in the Open Publication License, v1.0  -->
+<!-- or later (the latest version is presently available at          -->
+<!-- http://www.opencontent.org/openpub/)                            -->
+<!-- Distribution of the work or derivative of the work in any       -->
+<!-- standard (paper) book form is prohibited unless prior           -->
+<!-- permission obtained from the copyright holder                   -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTEND####                                     -->
+<!-- =============================================================== -->
+<!-- #####DESCRIPTIONBEGIN####                                       -->
+<!--                                                                 -->
+<!-- Author(s):   Ilija Kocho                                        -->
+<!-- Contact(s):  ilijak@siva.com.mk                                 -->
+<!-- Date:        2012/01/10                                         -->
+<!-- Version:     0.01                                               -->
+<!--                                                                 -->
+<!-- ####DESCRIPTIONEND####                                          -->
+<!-- =============================================================== -->
+
+<!-- }}} -->
+
+</part>