1.. _samples_boards_stm32_ccm:
2
3STM32 CCM example
4#################
5
6Overview
7********
8
9Show usage of the Core Coupled Memory (CCM) that is available
10on several STM32 devices. The very important difference with
11normal RAM is that CCM can not be used for DMA.
12
13By prefixing a variable with __ccm_data_section, __ccm_bss_section,
14or __ccm_noinit_section those variables are placed in the CCM.
15
16The __ccm_data_section prefix should be used for variables that
17are initialized. Like the normal data section the initial
18values take up space in the FLASH image.
19
20The __ccm_bss_section prefix should be used for variables that
21should be initialized to 0. Like the normal bss section they
22do not take up FLASH space.
23
24The __ccm_noinit_section prefix should be used for variables
25that don't need to have a defined initial value (for example
26buffers that will receive data). Compared to bss or data the
27kernel does not need to initialize the noinit section making
28the startup slightly faster.
29
30To add CCM support to a board, add the following line to the
31board's DTS file ``chosen`` section:
32
33.. code-block:: console
34
35   zephyr,ccm = &ccm0;
36
37For example the olimex STM32 E407 DTS file looks like this:
38
39.. literalinclude:: ../../../../boards/arm/olimex_stm32_e407/olimex_stm32_e407.dts
40   :linenos:
41
42Building and Running
43********************
44
45.. zephyr-app-commands::
46   :app: samples/boards/stm32/ccm
47   :goals: build flash
48
49The first time the example is run after power on, the output will
50look like this:
51
52.. code-block:: console
53
54   ***** BOOTING ZEPHYR OS v1.10.99 - BUILD: Jan 14 2018 09:32:46 *****
55
56   CCM (Core Coupled Memory) usage example
57
58   The total used CCM area   : [0x10000000, 0x10000021)
59   Zero initialized BSS area : [0x10000000, 0x10000007)
60   Uninitialized NOINIT area : [0x10000008, 0x10000013)
61   Initialised DATA area     : [0x10000014, 0x10000021)
62   Start of DATA in FLASH    : 0x08003940
63
64   Checking initial variable values: ... PASSED
65
66   Initial variable values:
67   ccm_data_var_8  addr: 0x10000014 value: 0x12
68   ccm_data_var_16 addr: 0x10000016 value: 0x3456
69   ccm_data_var_32 addr: 0x10000018 value: 0x789abcde
70   ccm_data_array  addr: 0x1000001c size: 5 value:
71           0x11 0x22 0x33 0x44 0x55
72   ccm_bss_array addr: 0x10000000 size: 7 value:
73           0x00 0x00 0x00 0x00 0x00 0x00 0x00
74   ccm_noinit_array addr: 0x10000008 size: 11 value:
75           0xa9 0x99 0xba 0x90 0xe1 0x2a 0xba 0x93 0x4c 0xfe 0x4b
76
77   Variable values after writing:
78   ccm_data_var_8  addr: 0x10000014 value: 0xed
79   ccm_data_var_16 addr: 0x10000016 value: 0xcba9
80   ccm_data_var_32 addr: 0x10000018 value: 0x87654321
81   ccm_data_array  addr: 0x1000001c size: 5 value:
82           0xaa 0xaa 0xaa 0xaa 0xaa
83   ccm_bss_array addr: 0x10000000 size: 7 value:
84           0xbb 0xbb 0xbb 0xbb 0xbb 0xbb 0xbb
85   ccm_noinit_array addr: 0x10000008 size: 11 value:
86           0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc
87
88   Example end
89
90
91First, each CCM section is listed with its address and size. Next, some usage
92examples are shown. Note that the ``noinit`` section holds variables with
93uninitialized data. After writing to the variables, they all should hold the
94values shown above.
95
96When the board is reset (without power-cycling), the output looks like this:
97
98.. code-block:: console
99
100   ***** BOOTING ZEPHYR OS v1.10.99 - BUILD: Jan 14 2018 09:32:46 *****
101
102   CCM (Core Coupled Memory) usage example
103
104   The total used CCM area   : [0x10000000, 0x10000021)
105   Zero initialized BSS area : [0x10000000, 0x10000007)
106   Uninitialized NOINIT area : [0x10000008, 0x10000013)
107   Initialised DATA area     : [0x10000014, 0x10000021)
108   Start of DATA in FLASH    : 0x08003940
109
110   Checking initial variable values: ... PASSED
111
112   Initial variable values:
113   ccm_data_var_8  addr: 0x10000014 value: 0x12
114   ccm_data_var_16 addr: 0x10000016 value: 0x3456
115   ccm_data_var_32 addr: 0x10000018 value: 0x789abcde
116   ccm_data_array  addr: 0x1000001c size: 5 value:
117           0x11 0x22 0x33 0x44 0x55
118   ccm_bss_array addr: 0x10000000 size: 7 value:
119           0x00 0x00 0x00 0x00 0x00 0x00 0x00
120   ccm_noinit_array addr: 0x10000008 size: 11 value:
121           0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc
122
123   Variable values after writing:
124   ccm_data_var_8  addr: 0x10000014 value: 0xed
125   ccm_data_var_16 addr: 0x10000016 value: 0xcba9
126   ccm_data_var_32 addr: 0x10000018 value: 0x87654321
127   ccm_data_array  addr: 0x1000001c size: 5 value:
128           0xaa 0xaa 0xaa 0xaa 0xaa
129   ccm_bss_array addr: 0x10000000 size: 7 value:
130           0xbb 0xbb 0xbb 0xbb 0xbb 0xbb 0xbb
131   ccm_noinit_array addr: 0x10000008 size: 11 value:
132           0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc 0xcc
133
134   Example end
135
136
137The difference with the first run is that the ccm_noinit section still has the
138values from the last write. It is important to notice that this is not guaranteed,
139it still should be considered uninitialized leftover data.
140