Mercurial > ecos
annotate packages/hal/cortexm/kinetis/var/current/doc/kinetis.sgml @ 3180:9b3d0f81044b
* twr_k40x256/current/cdl/hal_cortexm_kinetis_twr_k40x256.cdl,
twr_k60n512/current/cdl/hal_cortexm_kinetis_twr_k60n512.cdl,
twr_k70f120m/current/cdl/hal_cortexm_kinetis_twr_k70f120m.cdl,
var/current/cdl/hal_cortexm_kinetis.cdl:
Reference per-package documentation.
* var/current/doc/kinetis.sgml: Close <para> and <refsect2> blocks.
| author | jld |
|---|---|
| date | Sat, 19 May 2012 10:36:22 +0000 |
| parents | 58eda6fed5a5 |
| children | 068fbe2304f1 |
| rev | line source |
|---|---|
| 3177 | 1 <!-- DOCTYPE part PUBLIC "-//OASIS//DTD DocBook V3.1//EN" --> |
| 2 | |
| 3 <!-- {{{ Banner --> | |
| 4 | |
| 5 <!-- =============================================================== --> | |
| 6 <!-- --> | |
| 7 <!-- kinetis.sgml --> | |
| 8 <!-- --> | |
| 9 <!-- KINETIS documentation. --> | |
| 10 <!-- --> | |
| 11 <!-- =============================================================== --> | |
| 12 <!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> | |
| 13 <!-- =============================================================== --> | |
| 14 <!-- Copyright (C) 2012 Free Software Foundation, Inc. --> | |
| 15 <!-- This material may be distributed only subject to the terms --> | |
| 16 <!-- and conditions set forth in the Open Publication License, v1.0 --> | |
| 17 <!-- or later (the latest version is presently available at --> | |
| 18 <!-- http://www.opencontent.org/openpub/) --> | |
| 19 <!-- Distribution of the work or derivative of the work in any --> | |
| 20 <!-- standard (paper) book form is prohibited unless prior --> | |
| 21 <!-- permission obtained from the copyright holder --> | |
| 22 <!-- =============================================================== --> | |
| 23 <!-- ####ECOSDOCCOPYRIGHTEND#### --> | |
| 24 <!-- =============================================================== --> | |
| 25 <!-- #####DESCRIPTIONBEGIN#### --> | |
| 26 <!-- --> | |
| 27 <!-- Author(s): Ilija Kocho --> | |
| 28 <!-- Contact(s): ilijak@siva.com.mk --> | |
| 29 <!-- Date: 2012/01/10 --> | |
| 30 <!-- Version: 0.01 --> | |
| 31 <!-- --> | |
| 32 <!-- ####DESCRIPTIONEND#### --> | |
| 33 <!-- =============================================================== --> | |
| 34 | |
| 35 <!-- }}} --> | |
| 36 | |
| 37 <!-- <part id="hal-cortexm-kinetis"><title>Freescale Kinetis Family Support</title> --> | |
| 38 | |
| 39 <refentry id="hal-cortexm-kinetis-var"> | |
| 40 <refmeta> | |
| 41 <refentrytitle>Freescale Kinetis Variant</refentrytitle> | |
| 42 </refmeta> | |
| 43 <refnamediv> | |
| 44 <refname><literal>CYGPKG_HAL_CORTEXM_KINETIS</literal></refname> | |
| 45 <refpurpose>eCos Support for Freescale Kinetis Micro-controllers</refpurpose> | |
| 46 </refnamediv> | |
| 47 | |
| 48 <refsect1 id="hal-cortexm-kinetis-var-description"><title>Description</title> | |
| 49 <para> | |
| 50 Kinetis is a Freescale microcontroller family based on the ARM Cortex-M4 core. The | |
| 51 family consists of subfamilies: K10, K20, K30, K40, K50, K60 and K70 | |
| 52 that gradually add-on performance and features. | |
| 53 </para> | |
| 54 <para> | |
| 55 The Kinetis variant HAL provides generic support for hardware found on some | |
| 56 or all Kinetis members. The variant package <literal>CYGPKG_HAL_CORTEXM_KINETIS</literal> | |
| 57 provides configurable components that aim to support the complete set of options | |
| 58 found in the Kinetis family. | |
| 59 </para> | |
| 60 </refsect1> | |
| 61 <refsect1 id="kinetis-var-sup"><title>What's supported</title> | |
| 62 <para> | |
| 63 The current Kinetis software includes a Kinetis variant HAL, some Platform BSPs, | |
| 64 as well as DMA, UART, Wallclock, Ethernet and SPI support. | |
| 65 </para> | |
| 66 </refsect1> | |
| 67 <refsect1 id="kinetis-var-config"><title>Configuration</title> | |
| 68 <para> Kinetis is a set of families of micro-controllers packed with highly configurable components. | |
| 69 In order to facilitate system configuration for the user, the CDL configuration items are organized as a set of | |
| 70 expert components. Typically, for a given peripheral, the user chooses the required hardware | |
| 71 options and desirable parameters, and the respective CDL configuration options and settings are calculated from these. | |
| 72 If it is not possible to achieve exact values, the configurator attempts to provide | |
|
3180
9b3d0f81044b
* twr_k40x256/current/cdl/hal_cortexm_kinetis_twr_k40x256.cdl,
jld
parents:
3177
diff
changeset
|
73 approximate settings, then the user can manually do the fine tuning.</para> |
| 3177 | 74 <refsect2 id="kinetis-var-cpu-select"><title>Kinetis Part Selection</title> |
| 75 <para> | |
| 76 Within a family and/or across families the chips are further differentiated by their features | |
| 77 such as: optional FPU, amount of memory, etc. The family member options are reflected in the | |
| 78 controller naming scheme (see respective Freescale Kinetis product brief(s) and reference manual(s)). | |
| 79 The Kinetis part builder <literal>CYGHWR_HAL_CORTEXM_KINETIS</literal>, respects this naming scheme and | |
| 80 enables the user to interactively configure eCos for the desired part by selecting | |
| 81 the requested part's name segments. | |
| 82 Based on user input, the CDL computes the part-specific eCos configuration. This includes calculation | |
| 83 of on-chip FLASH and SRAM layout as well as the activation/deactivation of options such as FPU and | |
| 84 Ethernet. | |
| 85 </para> | |
| 86 </refsect2> | |
| 87 <refsect2 id="kinetis-var-clocking"><title>Clocking</title> | |
| 88 <para> | |
| 89 Kinetis is packed with a rich set of clocking options provided by the Multipurpose Clock Generator - MCG. | |
| 90 Dependent on the part, MCG can have outlets for one or two external frequency reference sources | |
| 91 <emphasis>OSC</emphasis> and <emphasis>OSC1</emphasis> and one | |
| 92 or two PLL oscillators <emphasis>PLL</emphasis> and <emphasis>PLL1</emphasis>. | |
| 93 Each of the external frequency reference sources can be either a crystal or external | |
| 94 oscillator and associated with either or both PLL oscillators. <emphasis>OSC</emphasis> can also be a | |
| 95 reference source for the FLL oscillator. | |
| 96 Besides <emphasis>OSC</emphasis> and <emphasis>OSC1</emphasis>, there are additional clock sources | |
| 97 including two RC oscillators and a (battery backed) RTC clock with it's own 32768 Hz crystal oscillator. | |
| 98 MCG gives the user a wide choice of system and peripheral clock source(s) that can be | |
| 99 external clock(s), internal clocks, a PLL or the FLL. An external or on-chip | |
| 100 oscillator can be used as a system clock or as a reference for PLL/FLL oscillator(s). | |
| 101 </para> | |
| 102 <note><para> In the documentation of Kinetis parts with two oscillators, <emphasis>OSC</emphasis> | |
| 103 and <emphasis>PLL</emphasis> are described as <emphasis>OSC0</emphasis> and <emphasis>PLL0</emphasis> respectively. | |
| 104 </para></note> | |
| 105 <para> | |
| 106 Clocking component <literal>CYGHWR_HAL_CORTEXM_KINETIS_CLOCKING</literal> provides some expert | |
| 107 functionality in order to facilitate clock system configuration. Normally, the user sets requirements: | |
| 108 clock source, clock reference, desired core frequency and upper limits for peripheral | |
| 109 clock frequencies. The component automatically calculates MCG and other peripheral register | |
| 110 settings in order to achieve the required clock frequencies. This setting is not always perfect but | |
| 111 fits (exactly or close) for commonly used frequencies. If necessary, the user can fine tune the | |
| 112 clock settings interactively using the eCos Configuration Tool. | |
| 113 The two clock sources are named: | |
| 114 </para> | |
| 115 <variablelist> | |
| 116 <varlistentry> | |
| 117 <term>System clock</term> | |
| 118 <listitem><para>The clock source that provides the clock for the Cortex-M core. | |
| 119 It may also provide the clock for some peripherals. | |
| 120 </para></listitem></varlistentry> | |
| 121 <varlistentry> | |
| 122 <term>Auxiliary clock</term> | |
| 123 <listitem><para>This is optional and may provide a clock for peripherals but not for the Cortex-M core. | |
| 124 </para></listitem></varlistentry> | |
| 125 </variablelist> | |
| 126 <para> | |
| 127 The user can select which source is the system clock. The choices for system clock are: <emphasis>PLL</emphasis>, | |
| 128 <emphasis>FLL</emphasis>, <emphasis>External reference clock</emphasis> and, when available, <emphasis>PLL1</emphasis>. | |
| 129 The auxiliary clock, when available is: <emphasis>PLL</emphasis> if <emphasis>PLL1</emphasis> is selected | |
| 130 for system the clock or <emphasis>PLL1</emphasis> if any other source is selected for the system clock. | |
| 131 </para> | |
| 132 </refsect2> | |
| 133 <refsect2 id="kinetis-var-memory"><title>Memory layouts</title> | |
| 134 <para> | |
| 135 The memory layouts and startup types which don't employ external memory should be applicable to all | |
| 136 Kinetis platforms so they are defined and maintained at the variant level. | |
| 137 This is somewhat different than common eCos practice but has some advantages brought by universal, | |
| 138 single copy linker scripts for single chip configurations. The linker scripts are further enhanced/generalized | |
| 139 by utilization of macros provided by CDL and calculated on the basis of the | |
| 140 <link linkend="kinetis-var-cpu-select">selected Kinetis part</link>. | |
| 141 </para> | |
| 142 <refsect3 id="kinetis-var-memory-ldscript-location"><title>Variant Linker | |
| 143 Script Location</title> | |
| 144 <para> | |
| 145 Variant linker scripts are found at: | |
| 146 <filename class="directory">hal/kinetis/var/<version>/include/pkgconf</filename> | |
| 147 </para> | |
| 148 </refsect3> | |
| 149 <refsect3 id="kinetis-var-memory-ldscript-naming"><title>Linker Script Naming</title> | |
| 150 <para> | |
| 151 Linker script file names are composed of segments | |
| 152 <filename>mlt_kinetis_<NVM>_<SRAM>_<STARTUP>[_<PLF>].ldi</filename> | |
| 153 where <filename>PLF</filename> is an optional extension for platform specific scripts and | |
| 154 other segments have meanings as described in the following table. | |
| 155 </para> | |
| 156 <table frame="all" id="kinetis-var-table-ldscript-naming"><title>Linker script name segments</title> | |
| 157 <tgroup cols="3" align="center"> | |
| 158 <colspec colnum="1" colname="segment" colwidth="1*" > | |
| 159 <colspec colnum="2" colname="desc" colwidth="2*" > | |
| 160 <colspec colnum="3" colname="values" colwidth="1*" > | |
| 161 <thead> | |
| 162 <row> | |
| 163 <entry>Segment</entry> | |
| 164 <entry>Description</entry> | |
| 165 <entry>Values</entry> | |
| 166 </row> | |
| 167 </thead> | |
| 168 <tbody> | |
| 169 <row> | |
| 170 <entry><filename>NVM</filename></entry> | |
| 171 <entry>Kinetis non-volatile memory configuration</entry> | |
| 172 <entry> | |
| 173 <filename>flash</filename>, | |
| 174 <filename>flexnvm</filename> | |
| 175 </entry> | |
| 176 </row> | |
| 177 <row> | |
| 178 <entry><filename>SRAM</filename></entry> | |
| 179 <entry>SRAM memory sectioning</entry> | |
| 180 <entry> | |
| 181 <filename>unisram</filename>, | |
| 182 <filename>sram2s</filename> | |
| 183 </entry> | |
| 184 </row> | |
| 185 <row> | |
| 186 <entry><filename>STARTUP</filename></entry> | |
| 187 <entry>Startup type</entry> | |
| 188 <entry> | |
| 189 <filename>rom</filename>, | |
| 190 <filename>sram</filename> | |
| 191 </entry> | |
| 192 </row> | |
| 193 </tbody> | |
| 194 </tgroup> | |
| 195 </table> | |
| 196 <para> | |
| 197 <note><para>Never attempt to flash Kinetis with an image for SRAM startup. SRAM startup images | |
| 198 do not contain a <literal>.flash_conf</literal> section so random contents may be written in | |
| 199 flash protection area and lock your Kinetis device. This lock-out can be permanent. | |
| 200 </para></note> | |
|
3180
9b3d0f81044b
* twr_k40x256/current/cdl/hal_cortexm_kinetis_twr_k40x256.cdl,
jld
parents:
3177
diff
changeset
|
201 </para> |
| 3177 | 202 </refsect3> |
| 203 <refsect3 id="kinetis-var-memory-plf-spec"><title>Platform Specific Memory Layouts</title> | |
| 204 <para> | |
| 205 Platforms, if needed, can provide their own layouts in addition to the variant ones. Typically | |
| 206 they will cover systems with external memory. The <link linkend="kinetis-var-startup"> | |
| 207 startup type</link> implicitly determines whether variant and platform defined | |
| 208 layout shall be used. | |
| 209 </para> | |
| 210 </refsect3> | |
| 211 <refsect3 id="kinetis-var-memory-sram"><title>On-chip SRAM</title> | |
| 212 <para> | |
| 213 Kinetis on chip SRAM memory consists of two equal banks that occupy consecutive locations anchored | |
| 214 below and above <literal>0x20000000</literal>. This fact is reflected in memory layout scripts. | |
| 215 There are linker scripts that treat SRAM as a single section (<filename>unisram</filename>) or as | |
| 216 2 separate sections (<filename>sram2s</filename>). | |
| 217 </para> | |
| 218 </refsect3> | |
| 219 <refsect3 id="kinetis-var-memory-flash"><title>On-chip FLASH</title> | |
| 220 <para> | |
| 221 Kinetis on-chip flash contains a special area <literal>[0x400-0x40F]</literal> | |
| 222 that holds the flash security configuration. In order to preserve this area from | |
| 223 accidental writing and at the same time provide regular access, | |
| 224 a custom linker section <literal>.flash_conf</literal> is created. In addition, in order | |
| 225 to utilize the FLASH pool below <literal>0x400</literal> the <emphasis>USER_SECTION</emphasis> | |
| 226 <literal>.kinetis_misc</literal> is defined. This section typically contains | |
| 227 code parts from <filename>kinetis_misc.c</filename>. | |
| 228 </para> | |
| 229 </refsect3> | |
| 230 <refsect3 id="kinetis-var-memory-cache"><title>Cache</title> | |
| 231 <para> | |
| 232 Kinetis members with operating frequencies of 120 MHz and 150 MHz are equipped with cache memory. | |
| 233 Due to the Harvard architecture, there are two unified cache memories connected to code | |
| 234 - <emphasis>PC</emphasis> and system - <emphasis>PS</emphasis> buses respectively. One of the | |
| 235 issues with caching is operation with bus masters such as DMA, Ethernet controller, etc. | |
| 236 In order to keep shared data such | |
| 237 as buffers and transfer descriptors synchronous, a part of cached data may have to be flushed | |
| 238 and/or invalidated. In some cases, an alternative can be the usage of non-cacheable memory | |
| 239 regions. <literal>CYGHWR_HAL_NON_CACHABLE</literal> provides for the configuration of non-cacheable | |
| 240 memory. If some bus masters have provision for non-cacheable memory, such configuration options | |
| 241 can be parented by <literal>CYGHWR_HAL_NON_CACHABLE</literal>. | |
| 242 </para> | |
| 243 </refsect3> | |
|
3180
9b3d0f81044b
* twr_k40x256/current/cdl/hal_cortexm_kinetis_twr_k40x256.cdl,
jld
parents:
3177
diff
changeset
|
244 </refsect2> |
| 3177 | 245 <refsect2 id="kinetis-var-startup"><title>Startup types</title> |
| 246 <para> | |
| 247 There are <emphasis>two levels</emphasis> of startup type: | |
| 248 </para> | |
| 249 <variablelist> | |
| 250 <varlistentry> | |
| 251 <term>Variant <literal>CYG_HAL_STARTUP_VAR</literal></term> | |
| 252 <listitem><para>This is always present and provides startup | |
| 253 types for systems without external memory. | |
| 254 </para></listitem></varlistentry> | |
| 255 <varlistentry> | |
| 256 <term>Platform <literal>CYG_HAL_STARTUP_PLF</literal></term> | |
| 257 <listitem><para>This is optional and is | |
| 258 provided by a platform package. Typically it provides startup types for systems | |
| 259 that employ external memory. | |
| 260 </para></listitem></varlistentry> | |
| 261 </variablelist> | |
| 262 <para> | |
| 263 </para> | |
| 264 <para> | |
| 265 When present, the platform startup overloads the variant startup and has precedence over it. | |
| 266 User can activate the variant startup by setting platform startup to | |
| 267 <literal>ByVariant</literal>. | |
| 268 </para> | |
| 269 <refsect3 id="kinetis-var-startup-byvariant"><title>Startup types provided variant</title> | |
| 270 <para> | |
| 271 The following startup types are provided for Kinetis at the variant level: | |
| 272 </para> | |
| 273 <variablelist> | |
| 274 <varlistentry> | |
| 275 <term><literal>ROM</literal></term> | |
| 276 <listitem><para>Normal startup for stand-alone operation. eCos image has to be flashed | |
| 277 in internal flash; | |
| 278 </para></listitem></varlistentry> | |
| 279 <varlistentry> | |
| 280 <term><literal>SRAM</literal></term> | |
| 281 <listitem><para>Image is loaded in internal SRAM by means of JTAG/SWD and executed | |
| 282 under debugger control. | |
| 283 </para></listitem></varlistentry> | |
| 284 </variablelist> | |
| 285 <note><para>(IMPORTANT) Never, ever attempt to flash Kinetis with an image for SRAM startup. | |
| 286 SRAM startup images do not contain a <literal>.flash_conf</literal> section so random contents | |
| 287 may be written to the flash protection area and lock your Kinetis device. This lock-out can be permanent. | |
| 288 </para></note> | |
| 289 </refsect3> | |
| 290 </refsect2> | |
| 291 <refsect2 id="kinetis-interrupt-priority-scheme"><title>Interrupt priority scheme</title> | |
| 292 <para> | |
| 293 In case of multiple simultaneous interrupts, interrupt service request resolution is based | |
| 294 on a relative comparison of interrupt priorities, rather than on individual interrupt priority values. | |
| 295 <emphasis>Interrupt priority scheme</emphasis> gives a consolidated overview and control | |
| 296 of priorities of all interrupt sources. Interrupt priorities can be provided by either variant | |
| 297 <literal>CYGHWR_HAL_DEVS_IRQ_PRIO_SCHEME_VAR</literal> | |
| 298 or platform <literal>CYGHWR_HAL_DEVS_IRQ_PRIO_SCHEME</literal>. | |
| 299 </para> | |
| 300 </refsect2> | |
| 301 </refsect1> | |
| 302 | |
| 303 </refentry> | |
| 304 | |
| 305 <!--</part>--> |