Mercurial > ecos
annotate packages/hal/cortexm/kinetis/var/current/doc/kinetis.sgml @ 3189:068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
| author | vae |
|---|---|
| date | Sat, 03 Nov 2012 15:51:54 +0000 |
| parents | 9b3d0f81044b |
| children |
| 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 | |
|
3189
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
81 the requested part name segments. |
| 3177 | 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. | |
|
3189
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
233 Due to the Harvard architecture, there are two cache memories connected to code |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
234 - <emphasis>PC</emphasis> and system - <emphasis>PS</emphasis> buses respectively. |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
235 Although both modules can cache both instructions and data (unified caches), with the provided |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
236 memory they act as instruction (<emphasis>PC</emphasis>) and data (<emphasis>PS</emphasis>) caches. |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
237 </para> |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
238 <para> |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
239 A common caching issue is sharing memory resources with bus masters such as DMA, Ethernet controller, etc. |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
240 In order to keep shared data such as buffers and transfer control descriptors consistent, |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
241 cached data have to be flushed and/or invalidated. An alternative approach, used here is usage of |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
242 non-cachable memory for shared data. <literal>CYGHWR_HAL_NON_CACHABLE</literal> provides for |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
243 the configuration of non-cachable memory. If some bus masters have provision for non-cache able memory, |
|
068fbe2304f1
Separate data and code caches, as well as text indentation suggested by Jifl. Fixes to cache and SDRAM CDL and functions Improved SDRAM controller support due to better manufacturer documentation: Configurable pad control. [Bugzilla 1001606]
vae
parents:
3180
diff
changeset
|
244 such configuration options can be parenthed by <literal>CYGHWR_HAL_NON_CACHABLE</literal>. |
| 3177 | 245 </para> |
| 246 </refsect3> | |
|
3180
9b3d0f81044b
* twr_k40x256/current/cdl/hal_cortexm_kinetis_twr_k40x256.cdl,
jld
parents:
3177
diff
changeset
|
247 </refsect2> |
| 3177 | 248 <refsect2 id="kinetis-var-startup"><title>Startup types</title> |
| 249 <para> | |
| 250 There are <emphasis>two levels</emphasis> of startup type: | |
| 251 </para> | |
| 252 <variablelist> | |
| 253 <varlistentry> | |
| 254 <term>Variant <literal>CYG_HAL_STARTUP_VAR</literal></term> | |
| 255 <listitem><para>This is always present and provides startup | |
| 256 types for systems without external memory. | |
| 257 </para></listitem></varlistentry> | |
| 258 <varlistentry> | |
| 259 <term>Platform <literal>CYG_HAL_STARTUP_PLF</literal></term> | |
| 260 <listitem><para>This is optional and is | |
| 261 provided by a platform package. Typically it provides startup types for systems | |
| 262 that employ external memory. | |
| 263 </para></listitem></varlistentry> | |
| 264 </variablelist> | |
| 265 <para> | |
| 266 </para> | |
| 267 <para> | |
| 268 When present, the platform startup overloads the variant startup and has precedence over it. | |
| 269 User can activate the variant startup by setting platform startup to | |
| 270 <literal>ByVariant</literal>. | |
| 271 </para> | |
| 272 <refsect3 id="kinetis-var-startup-byvariant"><title>Startup types provided variant</title> | |
| 273 <para> | |
| 274 The following startup types are provided for Kinetis at the variant level: | |
| 275 </para> | |
| 276 <variablelist> | |
| 277 <varlistentry> | |
| 278 <term><literal>ROM</literal></term> | |
| 279 <listitem><para>Normal startup for stand-alone operation. eCos image has to be flashed | |
| 280 in internal flash; | |
| 281 </para></listitem></varlistentry> | |
| 282 <varlistentry> | |
| 283 <term><literal>SRAM</literal></term> | |
| 284 <listitem><para>Image is loaded in internal SRAM by means of JTAG/SWD and executed | |
| 285 under debugger control. | |
| 286 </para></listitem></varlistentry> | |
| 287 </variablelist> | |
| 288 <note><para>(IMPORTANT) Never, ever attempt to flash Kinetis with an image for SRAM startup. | |
| 289 SRAM startup images do not contain a <literal>.flash_conf</literal> section so random contents | |
| 290 may be written to the flash protection area and lock your Kinetis device. This lock-out can be permanent. | |
| 291 </para></note> | |
| 292 </refsect3> | |
| 293 </refsect2> | |
| 294 <refsect2 id="kinetis-interrupt-priority-scheme"><title>Interrupt priority scheme</title> | |
| 295 <para> | |
| 296 In case of multiple simultaneous interrupts, interrupt service request resolution is based | |
| 297 on a relative comparison of interrupt priorities, rather than on individual interrupt priority values. | |
| 298 <emphasis>Interrupt priority scheme</emphasis> gives a consolidated overview and control | |
| 299 of priorities of all interrupt sources. Interrupt priorities can be provided by either variant | |
| 300 <literal>CYGHWR_HAL_DEVS_IRQ_PRIO_SCHEME_VAR</literal> | |
| 301 or platform <literal>CYGHWR_HAL_DEVS_IRQ_PRIO_SCHEME</literal>. | |
| 302 </para> | |
| 303 </refsect2> | |
| 304 </refsect1> | |
| 305 | |
| 306 </refentry> | |
| 307 | |
| 308 <!--</part>--> |