git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/RISC-V_RV32_SiFive_HiFive1_GCC/freedom-metal/doc/sphinx/devguide/pmps.rst

   1 Physical Memory Protection
   2 ==========================
   3
   4 Physical Memory Protection (PMP) is a part of the RISC-V Privileged Architecture
   5 Specification which discribes the interface for a standard RISC-V memory
   6 protection unit.
   7
   8 The PMP defines a finite number of PMP regions which can be individually configured
   9 to enforce access permissions to a range of addresses in memory. Each PMP region
  10 is configurable with the following options:
  11
  12 .. doxygenstruct:: metal_pmp_config
  13    :project: metal
  14    :members:
  15    :no-link:
  16
  17 Initializing the PMP
  18 --------------------
  19
  20 All PMP-related functions first depend on having a handle to the PMP device:
  21
  22 .. code-block:: C
  23
  24    struct metal_pmp *pmp = metal_pmp_get_device();
  25    if(!pmp) {
  26       /* Failed to get PMP device handle */
  27    }
  28
  29 PMP initialization is optional and has the effect of disabling all PMP regions,
  30 if possible:
  31
  32 .. code-block:: C
  33
  34    metal_pmp_init(pmp);
  35
  36 The number of PMP regions available can be retrieved from the PMP device handle:
  37
  38 .. doxygenstruct:: metal_pmp
  39    :project: metal
  40    :members:
  41    :no-link:
  42
  43 Configuring a PMP Region
  44 ------------------------
  45
  46 Freedom Metal has a set of APIs for configuring a PMP region. The most generic of these
  47 is
  48
  49 .. doxygenfunction:: metal_pmp_set_region
  50    :project: metal
  51
  52 This function allows for the configuration of all PMP region settings.
  53
  54 Additional APIs are provided for granularly changing individual PMP region settings.
  55 For example:
  56
  57 .. doxygenfunction:: metal_pmp_set_address
  58    :project: metal
  59    :no-link:
  60 .. doxygenfunction:: metal_pmp_lock
  61    :project: metal
  62    :no-link:
  63 .. doxygenfunction:: metal_pmp_set_writeable
  64    :project: metal
  65    :no-link:
  66
  67 Additional documentation for this API is provided in :doc:`the PMP API reference </apiref/pmp>`.
  68
  69 The RISC-V specification allows implementation of PMP to hard-wire the configuration
  70 values of PMP regions. In these cases, attempts to configure these PMP regions will
  71 fail.
  72
  73 Handling PMP Access Faults
  74 --------------------------
  75
  76 Attempted memory accesses which the PMP is configured to prevent trigger a
  77 CPU exception. These exceptions can be handled by installing a CPU exception
  78 handler for exception codes related to memory access faults.
  79
  80 Additional documentation about creating and registering exception handlers can
  81 be found in :doc:`the Exception Handlers Developer Guide </devguide/exceptions>`.
  82
  83 Additional Documentation
  84 ------------------------
  85
  86 Additional documentation about the Physical Memory Protection system and fault
  87 handling on RISC-V systems can be found in
  88 `The RISC-V Privileged ISA Specification v1.10 <https://riscv.org/specifications/privileged-isa/>`_.