display-dma2d  4.1.0
display-dma2d
ui_drawing_dma2d_configuration.h
Go to the documentation of this file.
1 /*
2  * C
3  *
4  * Copyright 2023 MicroEJ Corp. All rights reserved.
5  * Use of this source code is governed by a BSD-style license that can be found with this software.
6  */
7 
8 #ifndef UI_DRAWING_DMA2D_CONFIGURATION_H
9 #define UI_DRAWING_DMA2D_CONFIGURATION_H
10 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 // --------------------------------------------------------------------------------
28 // Includes
29 // --------------------------------------------------------------------------------
30 
31 #include <stdint.h>
32 
33 // --------------------------------------------------------------------------------
34 // Defines
35 // --------------------------------------------------------------------------------
36 
37 /*
38  * @brief Value to disable the cache management
39  * @see DRAWING_DMA2D_CACHE_MANAGEMENT
40  */
41 #define DRAWING_DMA2D_CACHE_MANAGEMENT_DISABLED (0U)
42 
43 /*
44  * @brief Value to enable the cache management
45  * @see DRAWING_DMA2D_CACHE_MANAGEMENT
46  */
47 #define DRAWING_DMA2D_CACHE_MANAGEMENT_ENABLED (1U)
48 
49 #if !defined (__DCACHE_PRESENT) || (__DCACHE_PRESENT == 0U)
50 
51 /*
52  * @brief This MCU does not have or does not use a cache. Cache management in
53  * ui_drawing_dma2d.c is disabled.
54  */
55 #define DRAWING_DMA2D_CACHE_MANAGEMENT (DRAWING_DMA2D_CACHE_MANAGEMENT_DISABLED)
56 
57 #else // !defined (__DCACHE_PRESENT) || (__DCACHE_PRESENT == 0U)
58 
59 /*
60  * @brief This MCU has a cache. Cache management must be configured.
61  *
62  * To ensure the best SDRAM performance, the SDRAM section must be configured
63  * as cacheable, write-through and shareable. As per the application notes below,
64  * this is required to maintain cache coherency. If the section is not defined as shareable,
65  * cache maintenance has to be performed, which adds overhead to all dma2d transfers:
66  * cache clean before the transfer and cache invalidate after the transfer.
67  */
68 
69 /*
70  * @brief Cache management requirements are detailed in the following documents:
71  * https://www.st.com/resource/en/application_note/an4838-introduction-to-memory-protection-unit-management-on-stm32-mcus-stmicroelectronics.pdf
72  * https://www.st.com/resource/en/application_note/an4839-level-1-cache-on-stm32f7-series-and-stm32h7-series-stmicroelectronics.pdf
73  *
74  * Cache management is not required in the following cases:
75  *
76  * - MCU without cache (e.g Cortex-M4)
77  *
78  * - Memory region containing display buffers is non-cacheable e.g.:
79  * MPU_InitStruct.BaseAddress = 0xC0000000;
80  * MPU_InitStruct.Size = MPU_REGION_SIZE_8MB;
81  * MPU_InitStruct.IsBufferable = MPU_ACCESS_NON_BUFFERABLE;
82  * MPU_InitStruct.IsCacheable = MPU_ACCESS_NOT_CACHEABLE;
83  * MPU_InitStruct.IsShareable = MPU_ACCESS_SHAREABLE;
84  * MPU_InitStruct.DisableExec = MPU_INSTRUCTION_ACCESS_ENABLE;
85  * MPU_InitStruct.Number = MPU_REGION_NUMBER4;
86  * HAL_MPU_ConfigRegion(&MPU_InitStruct);
87  *
88  * - Memory region containing display buffers is cacheable, write-through, no write allocate, shareable e.g.:
89  * MPU_InitStruct.BaseAddress = 0xC0000000;
90  * MPU_InitStruct.Size = MPU_REGION_SIZE_8MB;
91  * MPU_InitStruct.IsBufferable = MPU_ACCESS_NON_BUFFERABLE;
92  * MPU_InitStruct.IsCacheable = MPU_ACCESS_CACHEABLE;
93  * MPU_InitStruct.IsShareable = MPU_ACCESS_SHAREABLE;
94  * MPU_InitStruct.DisableExec = MPU_INSTRUCTION_ACCESS_ENABLE;
95  * MPU_InitStruct.Number = MPU_REGION_NUMBER4;
96  *
97  * As per application note AN4839, in order to maintain cache coherency, the memory region containing
98  * the display buffers and MicroUI images heap have to be configured as write-through and shareable,
99  * otherwise cache maintenance operations have to be performed.
100  */
101 //#define DRAWING_DMA2D_CACHE_MANAGEMENT (DRAWING_DMA2D_CACHE_MANAGEMENT_DISABLED)
102 
103 /*
104  * @brief Cache management is required in the following cases:
105  *
106  * - MCU with cache (e.g. Cortex-M7) and the memory is configured as follows:
107  *
108  * - Memory region containing display buffers configured as write-back e.g.:
109  * MPU_InitStruct.BaseAddress = 0xC0000000;
110  * MPU_InitStruct.Size = MPU_REGION_SIZE_8MB;
111  * MPU_InitStruct.IsBufferable = MPU_ACCESS_BUFFERABLE;
112  * MPU_InitStruct.IsCacheable = MPU_ACCESS_CACHEABLE;
113  * MPU_InitStruct.IsShareable = MPU_ACCESS_NON_SHAREABLE;
114  * MPU_InitStruct.DisableExec = MPU_INSTRUCTION_ACCESS_ENABLE;
115  * MPU_InitStruct.Number = MPU_REGION_NUMBER4;
116  *
117  * - Memory region containing display buffers configured as write-through, non-shareable e.g.:
118  * MPU_InitStruct.BaseAddress = 0xC0000000;
119  * MPU_InitStruct.Size = MPU_REGION_SIZE_8MB;
120  * MPU_InitStruct.IsBufferable = MPU_ACCESS_NON_BUFFERABLE;
121  * MPU_InitStruct.IsCacheable = MPU_ACCESS_CACHEABLE;
122  * MPU_InitStruct.IsShareable = MPU_ACCESS_NON_SHAREABLE;
123  * MPU_InitStruct.DisableExec = MPU_INSTRUCTION_ACCESS_ENABLE;
124  * MPU_InitStruct.Number = MPU_REGION_NUMBER4;
125  *
126  * Enabling cache management will reduce the performance of the UI, as each dma2d transfer requires
127  * cache clean before the transfer and cache invalidate after the transfer to maintain cache coherency.
128  *
129  * Cache invalidation is performed in the DMA2D ISR, so for this reason the dma2d drawing code is placed
130  * in the ITCM section to minimize the impact on performance.
131  */
132 //#define DRAWING_DMA2D_CACHE_MANAGEMENT (DRAWING_DMA2D_CACHE_MANAGEMENT_ENABLED)
133 
134 #endif // !defined (__DCACHE_PRESENT) || (__DCACHE_PRESENT == 0U)
135 
136 // --------------------------------------------------------------------------------
137 // EOF
138 // --------------------------------------------------------------------------------
139 
140 #ifdef __cplusplus
141 }
142 #endif
143 
144 #endif // UI_DRAWING_DMA2D_CONFIGURATION_H
145