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