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