1 /*
2  * SPDX-FileCopyrightText: 2010-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 
9 #include <esp_types.h>
10 #include "hal/mmu_types.h"
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
16 /**
17  * MMU Hal layer initialisation
18  */
19 void mmu_hal_init(void);
20 
21 /**
22  * Unmap all the MMU table. After this all external memory vaddr are not available
23  */
24 void mmu_hal_unmap_all(void);
25 
26 /**
27  * Helper functions to convert the MMU page numbers into bytes. e.g.:
28  * - When MMU page size is 16KB, page_num = 2 will be converted into 32KB
29  * - When MMU page size is 32KB, page_num = 2 will be converted into 64KB
30  *
31  * @param mmu_id    MMU ID
32  * @param page_num  page numbers
33  *
34  * @return
35  *         length in byte
36  */
37 uint32_t mmu_hal_pages_to_bytes(uint32_t mmu_id, uint32_t page_num);
38 
39 /**
40  * Helper functions to convert bytes into MMU page numbers. e.g.:
41  * - When MMU page size is 16KB, bytes = 64KB will be converted into 4 pages
42  * - When MMU page size is 32KB, bytes = 64KB will be converted into 2 pages
43  *
44  * @param mmu_id    MMU ID
45  * @param bytes     length in byte
46  *
47  * @return
48  *         length in CONFIG_MMU_PAGE_SIZE
49  */
50 uint32_t mmu_hal_bytes_to_pages(uint32_t mmu_id, uint32_t bytes);
51 
52 /**
53  * To map a virtual address block to a physical memory block
54  *
55  * @param mmu_id       MMU ID
56  * @param mem_type     physical memory type, see `mmu_target_t`
57  * @param vaddr        start virtual address to be mapped
58  * @param paddr        start physical address to be mapped
59  * @param len          length to be mapped, in bytes
60  * @param[out] out_len actual mapped length
61  *
62  * @note vaddr and paddr should be aligned with the mmu page size, see CONFIG_MMU_PAGE_SIZE
63  */
64 void mmu_hal_map_region(uint32_t mmu_id, mmu_target_t mem_type, uint32_t vaddr, uint32_t paddr, uint32_t len, uint32_t *out_len);
65 
66 /**
67  * To unmap a virtual address block that is mapped to a physical memory block previously
68  *
69  * @param[in] mmu_id  MMU ID
70  * @param[in] vaddr   start virtual address
71  * @param[in] len     length to be unmapped, in bytes
72  */
73 void mmu_hal_unmap_region(uint32_t mmu_id, uint32_t vaddr, uint32_t len);
74 
75 /**
76  * Convert virtual address to physical address
77  *
78  * @param mmu_id           MMU ID
79  * @param vaddr            virtual address
80  * @param[out] out_paddr   physical address
81  * @param[out] out_target  Indicating the vaddr/paddr is mapped on which target, see `mmu_target_t`
82  *
83  * @return
84  *        - true: virtual address is valid
85  *        - false: virtual address isn't valid
86  */
87 bool mmu_hal_vaddr_to_paddr(uint32_t mmu_id, uint32_t vaddr, uint32_t *out_paddr, mmu_target_t *out_target);
88 
89 /**
90  * Convert physical address to virtual address
91  *
92  * @note This function can only find the first match virtual address.
93  *       However it is possible that a physical address is mapped to multiple virtual addresses.
94  *
95  * @param mmu_id          MMU ID
96  * @param paddr           physical address
97  * @param target          physical memory target, see `mmu_target_t`
98  * @param type            virtual address type, could be instruction or data
99  * @param[out] out_vaddr  virtual address
100  *
101  * @return
102  *        - true: found a matched vaddr
103  *        - false: not found a matched vaddr
104  */
105 bool mmu_hal_paddr_to_vaddr(uint32_t mmu_id, uint32_t paddr, mmu_target_t target, mmu_vaddr_t type, uint32_t *out_vaddr);
106 
107 
108 /**
109  * Check if the vaddr region is valid
110  *
111  * @param mmu_id      MMU ID
112  * @param vaddr_start start of the virtual address
113  * @param len         length, in bytes
114  * @param type        virtual address type, could be instruction type or data type. See `mmu_vaddr_t`
115  *
116  * @return
117  *         True for valid
118  */
119 bool mmu_hal_check_valid_ext_vaddr_region(uint32_t mmu_id, uint32_t vaddr_start, uint32_t len, mmu_vaddr_t type);
120 
121 #ifdef __cplusplus
122 }
123 #endif
124