diff --git a/docs/en/api-reference/system/mm.rst b/docs/en/api-reference/system/mm.rst index ca90859ae04..8c5d6b7d879 100644 --- a/docs/en/api-reference/system/mm.rst +++ b/docs/en/api-reference/system/mm.rst @@ -65,7 +65,7 @@ Driver Concept Terminology ^^^^^^^^^^^ -The virtual memory pool is made up with one or multiple virtual memory regions, see below figure: +The virtual memory pool consists of one or more virtual memory regions, as shown in the figure below: .. image:: /../_static/diagrams/mmu/mem_pool.png :scale: 80 % @@ -73,7 +73,7 @@ The virtual memory pool is made up with one or multiple virtual memory regions, - A virtual memory pool stands for the whole virtual address range that can be mapped to physical memory. -- A virtual memory region is a range of virtual address with same attributes. +- A virtual memory region is a range of virtual addresses with same attributes. - A virtual memory block is a piece of virtual address range that is dynamically mapped. - A slot is the virtual address range between two virtual memory blocks. - A physical memory block is a piece of physical address range that is to-be-mapped or already mapped to a virtual memory block. @@ -125,15 +125,15 @@ You can call :cpp:func:`esp_mmu_map` to do a dynamical mapping, or :cpp:func:`es By default, physical memory blocks and virtual memory blocks are one-to-one mapped. This means, when calling :cpp:func:`esp_mmu_map`: * If it is the enclosed scenario, this API will return an :c:macro:`ESP_ERR_INVALID_STATE`. The ``out_ptr`` will be assigned to the start virtual memory address of the previously mapped one which encloses the to-be-mapped one. -* If it is the identical scenario, this API will behaves exactly the same as the enclosed scenario. +* If it is the identical scenario, this API will behave exactly the same as the enclosed scenario. * If it is the overlapped scenario, this API will by default return an :c:macro:`ESP_ERR_INVALID_ARG`. This means, ``esp_mmap`` driver by default does not allow mapping a physical memory address to multiple virtual memory addresses. -Specially, you can use :c:macro:`ESP_MMU_MMAP_FLAG_PADDR_SHARED`. This flag stands for one-to-multiple mapping between a physical address and multiple virtual addresses: +Specifically, you can use :c:macro:`ESP_MMU_MMAP_FLAG_PADDR_SHARED`. This flag stands for one-to-multiple mapping between a physical address and multiple virtual addresses: * If it is the overlapped scenario, this API will allocate a new virtual memory block as requested, then map to the given physical memory block. -Mapping at a chosen virtual address +Mapping at a Chosen Virtual Address ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :cpp:func:`esp_mmu_map_virt` maps a physical block the same way as :cpp:func:`esp_mmu_map`, but you can pass the virtual start address as ``vaddr_start``. Passing a value of ``0`` for ``vaddr_start`` will let the driver allocate any suitable free block. With a non-zero ``vaddr_start`` value, the whole range must lie in an unmapped slot for the given capabilities and target, and the address must be valid for the MMU view implied by ``caps``. diff --git a/docs/zh_CN/api-reference/system/mm.rst b/docs/zh_CN/api-reference/system/mm.rst index 0618563a44c..86496933944 100644 --- a/docs/zh_CN/api-reference/system/mm.rst +++ b/docs/zh_CN/api-reference/system/mm.rst @@ -75,9 +75,9 @@ ESP-IDF 还提供了一个存储器同步驱动程序来处理潜在的不同步 - 一个虚拟存储池是指可以映射到物理存储的整个虚拟地址范围。 - 一个虚拟存储区域是指具有相同属性的虚拟地址范围。 - 一个虚拟存储块是指一块动态映射的虚拟地址范围。 -- 一个间隙是指两个虚拟存储块之间的虚拟地址范围。 +- 一个槽位是指两个虚拟存储块之间的虚拟地址范围。 - 一个物理存储块是指一块待映射或已映射到虚拟存储块的物理地址范围。 -- 动态映射是指调用 ``esp_mmap`` 驱动程序 API :cpp:func:`esp_mmu_map` 进行的映射，此 API 会将给定的物理存储块映射到 ``esp_mmap`` 驱动程序分配的虚拟存储块中。 +- 动态映射是指调用 ``esp_mmap`` 驱动程序 API :cpp:func:`esp_mmu_map` 或者 :cpp:func:`esp_mmu_map_virt` 进行的映射。这两个接口可将指定的物理内存块映射到虚拟内存块，虚拟内存地址既可以由系统自动分配，也可指定具体的虚拟起始地址进行申请。 存储块的关系 @@ -120,7 +120,7 @@ ESP-IDF 还提供了一个存储器同步驱动程序来处理潜在的不同步 存储映射 ^^^^^^^^ -可以调用 :cpp:func:`esp_mmu_map` 进行动态映射。该 API 会根据你所选择的虚拟存储的属性分配一定大小的虚拟存储块，然后按照要求将此虚拟存储块映射到物理存储块中。``esp_mmap`` 驱动程序支持映射到一种或多种物理存储，因此，应在映射时指定物理存储目标。 +可调用 :cpp:func:`esp_mmu_map` 进行动态映射，如需指定虚拟起始地址，则可调用 :cpp:func:`esp_mmu_map_virt`。这些 API 会根据所选的虚拟存储能力，分配或放置所需大小的虚拟存储块，然后将其映射到请求的物理存储块。 ``esp_mmap`` 驱动程序支持映射到一种或多种类型的物理存储，因此在映射时应指定物理存储目标。 默认情况下，物理存储块和虚拟存储块是一对一映射。因此，当调用 :cpp:func:`esp_mmu_map` 时，如果存储关系不同，API 的行为也有所不同： @@ -133,6 +133,12 @@ ESP-IDF 还提供了一个存储器同步驱动程序来处理潜在的不同步 * 如果是“重叠”的情形，此 API 将按照要求分配一个新的虚拟存储块，并将其映射到给定的物理存储块中。 +在指定虚拟地址处进行映射 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:cpp:func:`esp_mmu_map_virt` 以与 :cpp:func:`esp_mmu_map` 相同的方式映射物理内存块，但允许通过参数 ``vaddr_start`` 指定映射的虚拟起始地址。若将 ``vaddr_start`` 设为 ``0``，驱动程序将自动分配合适的空闲内存块。若 ``vaddr_start`` 为非零值，则指定的整个地址范围必须位于与给定能力 (capability) 和目标 (target) 相匹配的未映射槽位内，且该地址必须在 ``caps`` 所对应的 MMU 视图范围内有效。 + + 取消存储映射 ^^^^^^^^^^^^ @@ -153,7 +159,7 @@ ESP-IDF 还提供了一个存储器同步驱动程序来处理潜在的不同步 可以通过一种或多种方法来访问支持 MMU 的物理存储。 -SPI flash 可以通过 SPI1（ESP-IDF ``spi_flash`` 驱动 API）或指针进行访问。ESP-IDF ``spi_flash`` 驱动 API 中已经考虑了存储同步，因此在使用时无需额外考虑存储同步。 +SPI flash 可以通过 SPI1（ESP-IDF ``esp_flash`` 驱动程序 API）或指针进行访问。ESP-IDF ``esp_flash`` 驱动程序 API 中已经考虑了存储同步，因此在使用时无需额外考虑存储同步。 .. only:: SOC_SPIRAM_SUPPORTED