Mercurial > ecos

comparison packages/hal/cortexm/kinetis/var/current/doc/kinetis.sgml @ 3177:58eda6fed5a5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
New files -- Kinetis variant documentation. [Bug 1001580]
author vae
date Fri, 18 May 2012 21:27:23 +0000
parents
children 9b3d0f81044b
comparison
equal deleted inserted replaced
3176:7c9ce2220671 3177:58eda6fed5a5
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
73 approximate settings, then the user can manually do the fine tuning.
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/&lt;version&gt;/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_&lt;NVM&gt;_&lt;SRAM&gt;_&lt;STARTUP&gt;[_&lt;PLF&gt;].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>
201 </refsect3>
202 <refsect3 id="kinetis-var-memory-plf-spec"><title>Platform Specific Memory Layouts</title>
203 <para>
204 Platforms, if needed, can provide their own layouts in addition to the variant ones. Typically
205 they will cover systems with external memory. The <link linkend="kinetis-var-startup">
206 startup type</link> implicitly determines whether variant and platform defined
207 layout shall be used.
208 </para>
209 </refsect3>
210 <refsect3 id="kinetis-var-memory-sram"><title>On-chip SRAM</title>
211 <para>
212 Kinetis on chip SRAM memory consists of two equal banks that occupy consecutive locations anchored
213 below and above <literal>0x20000000</literal>. This fact is reflected in memory layout scripts.
214 There are linker scripts that treat SRAM as a single section (<filename>unisram</filename>) or as
215 2 separate sections (<filename>sram2s</filename>).
216 </para>
217 </refsect3>
218 <refsect3 id="kinetis-var-memory-flash"><title>On-chip FLASH</title>
219 <para>
220 Kinetis on-chip flash contains a special area <literal>[0x400-0x40F]</literal>
221 that holds the flash security configuration. In order to preserve this area from
222 accidental writing and at the same time provide regular access,
223 a custom linker section <literal>.flash_conf</literal> is created. In addition, in order
224 to utilize the FLASH pool below <literal>0x400</literal> the <emphasis>USER_SECTION</emphasis>
225 <literal>.kinetis_misc</literal> is defined. This section typically contains
226 code parts from <filename>kinetis_misc.c</filename>.
227 </para>
228 </refsect3>
229 <refsect3 id="kinetis-var-memory-cache"><title>Cache</title>
230 <para>
231 Kinetis members with operating frequencies of 120 MHz and 150 MHz are equipped with cache memory.
232 Due to the Harvard architecture, there are two unified cache memories connected to code
233 - <emphasis>PC</emphasis> and system - <emphasis>PS</emphasis> buses respectively. One of the
234 issues with caching is operation with bus masters such as DMA, Ethernet controller, etc.
235 In order to keep shared data such
236 as buffers and transfer descriptors synchronous, a part of cached data may have to be flushed
237 and/or invalidated. In some cases, an alternative can be the usage of non-cacheable memory
238 regions. <literal>CYGHWR_HAL_NON_CACHABLE</literal> provides for the configuration of non-cacheable
239 memory. If some bus masters have provision for non-cacheable memory, such configuration options
240 can be parented by <literal>CYGHWR_HAL_NON_CACHABLE</literal>.
241 </para>
242 </refsect3>
243 <refsect2 id="kinetis-var-startup"><title>Startup types</title>
244 <para>
245 There are <emphasis>two levels</emphasis> of startup type:
246 </para>
247 <variablelist>
248 <varlistentry>
249 <term>Variant <literal>CYG_HAL_STARTUP_VAR</literal></term>
250 <listitem><para>This is always present and provides startup
251 types for systems without external memory.
252 </para></listitem></varlistentry>
253 <varlistentry>
254 <term>Platform <literal>CYG_HAL_STARTUP_PLF</literal></term>
255 <listitem><para>This is optional and is
256 provided by a platform package. Typically it provides startup types for systems
257 that employ external memory.
258 </para></listitem></varlistentry>
259 </variablelist>
260 <para>
261 </para>
262 <para>
263 When present, the platform startup overloads the variant startup and has precedence over it.
264 User can activate the variant startup by setting platform startup to
265 <literal>ByVariant</literal>.
266 </para>
267 <refsect3 id="kinetis-var-startup-byvariant"><title>Startup types provided variant</title>
268 <para>
269 The following startup types are provided for Kinetis at the variant level:
270 </para>
271 <variablelist>
272 <varlistentry>
273 <term><literal>ROM</literal></term>
274 <listitem><para>Normal startup for stand-alone operation. eCos image has to be flashed
275 in internal flash;
276 </para></listitem></varlistentry>
277 <varlistentry>
278 <term><literal>SRAM</literal></term>
279 <listitem><para>Image is loaded in internal SRAM by means of JTAG/SWD and executed
280 under debugger control.
281 </para></listitem></varlistentry>
282 </variablelist>
283 <note><para>(IMPORTANT) Never, ever attempt to flash Kinetis with an image for SRAM startup.
284 SRAM startup images do not contain a <literal>.flash_conf</literal> section so random contents
285 may be written to the flash protection area and lock your Kinetis device. This lock-out can be permanent.
286 </para></note>
287 </refsect3>
288 </refsect2>
289 <refsect2 id="kinetis-interrupt-priority-scheme"><title>Interrupt priority scheme</title>
290 <para>
291 In case of multiple simultaneous interrupts, interrupt service request resolution is based
292 on a relative comparison of interrupt priorities, rather than on individual interrupt priority values.
293 <emphasis>Interrupt priority scheme</emphasis> gives a consolidated overview and control
294 of priorities of all interrupt sources. Interrupt priorities can be provided by either variant
295 <literal>CYGHWR_HAL_DEVS_IRQ_PRIO_SCHEME_VAR</literal>
296 or platform <literal>CYGHWR_HAL_DEVS_IRQ_PRIO_SCHEME</literal>.
297 </para>
298 </refsect2>
299 </refsect1>
300
301 </refentry>
302
303 <!--</part>-->