include/lib/xlat_tables/xlat_tables_v2.h

   1 /*
   2  * Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.
   3  *
   4  * SPDX-License-Identifier: BSD-3-Clause
   5  */
   6
   7 #ifndef __XLAT_TABLES_V2_H__
   8 #define __XLAT_TABLES_V2_H__
   9
  10 #include <xlat_tables_defs.h>
  11
  12 #ifndef __ASSEMBLY__
  13 #include <stddef.h>
  14 #include <stdint.h>
  15 #include <xlat_mmu_helpers.h>
  16 #include <xlat_tables_v2_helpers.h>
  17
  18 /*
  19  * Default granularity size for an mmap_region_t.
  20  * Useful when no specific granularity is required.
  21  *
  22  * By default, choose the biggest possible block size allowed by the
  23  * architectural state and granule size in order to minimize the number of page
  24  * tables required for the mapping.
  25  */
  26 #define REGION_DEFAULT_GRANULARITY      XLAT_BLOCK_SIZE(MIN_LVL_BLOCK_DESC)
  27
  28 /* Helper macro to define an mmap_region_t. */
  29 #define MAP_REGION(_pa, _va, _sz, _attr)        \
  30         _MAP_REGION_FULL_SPEC(_pa, _va, _sz, _attr, REGION_DEFAULT_GRANULARITY)
  31
  32 /* Helper macro to define an mmap_region_t with an identity mapping. */
  33 #define MAP_REGION_FLAT(_adr, _sz, _attr)                       \
  34         MAP_REGION(_adr, _adr, _sz, _attr)
  35
  36 /*
  37  * Helper macro to define an mmap_region_t to map with the desired granularity
  38  * of translation tables.
  39  *
  40  * The granularity value passed to this macro must be a valid block or page
  41  * size. When using a 4KB translation granule, this might be 4KB, 2MB or 1GB.
  42  * Passing REGION_DEFAULT_GRANULARITY is also allowed and means that the library
  43  * is free to choose the granularity for this region. In this case, it is
  44  * equivalent to the MAP_REGION() macro.
  45  */
  46 #define MAP_REGION2(_pa, _va, _sz, _attr, _gr)                  \
  47         _MAP_REGION_FULL_SPEC(_pa, _va, _sz, _attr, _gr)
  48
  49 /*
  50  * Shifts and masks to access fields of an mmap_attr_t
  51  */
  52 #define MT_TYPE_MASK            U(0x7)
  53 #define MT_TYPE(_attr)          ((_attr) & MT_TYPE_MASK)
  54 /* Access permissions (RO/RW) */
  55 #define MT_PERM_SHIFT           U(3)
  56 /* Security state (SECURE/NS) */
  57 #define MT_SEC_SHIFT            U(4)
  58 /* Access permissions for instruction execution (EXECUTE/EXECUTE_NEVER) */
  59 #define MT_EXECUTE_SHIFT        U(5)
  60 /*
  61  * In the EL1&0 translation regime, mark the region as User (EL0) or
  62  * Privileged (EL1). In the EL3 translation regime this has no effect.
  63  */
  64 #define MT_USER_SHIFT           U(6)
  65 /* All other bits are reserved */
  66
  67 /*
  68  * Memory mapping attributes
  69  */
  70 typedef enum  {
  71         /*
  72          * Memory types supported.
  73          * These are organised so that, going down the list, the memory types
  74          * are getting weaker; conversely going up the list the memory types are
  75          * getting stronger.
  76          */
  77         MT_DEVICE,
  78         MT_NON_CACHEABLE,
  79         MT_MEMORY,
  80         /* Values up to 7 are reserved to add new memory types in the future */
  81
  82         MT_RO           = U(0) << MT_PERM_SHIFT,
  83         MT_RW           = U(1) << MT_PERM_SHIFT,
  84
  85         MT_SECURE       = U(0) << MT_SEC_SHIFT,
  86         MT_NS           = U(1) << MT_SEC_SHIFT,
  87
  88         /*
  89          * Access permissions for instruction execution are only relevant for
  90          * normal read-only memory, i.e. MT_MEMORY | MT_RO. They are ignored
  91          * (and potentially overridden) otherwise:
  92          *  - Device memory is always marked as execute-never.
  93          *  - Read-write normal memory is always marked as execute-never.
  94          */
  95         MT_EXECUTE              = U(0) << MT_EXECUTE_SHIFT,
  96         MT_EXECUTE_NEVER        = U(1) << MT_EXECUTE_SHIFT,
  97
  98         /*
  99          * When mapping a region at EL0 or EL1, this attribute will be used to
 100          * determine if a User mapping (EL0) will be created or a Privileged
 101          * mapping (EL1).
 102          */
 103         MT_USER                         = U(1) << MT_USER_SHIFT,
 104         MT_PRIVILEGED                   = U(0) << MT_USER_SHIFT,
 105 } mmap_attr_t;
 106
 107 /* Compound attributes for most common usages */
 108 #define MT_CODE         (MT_MEMORY | MT_RO | MT_EXECUTE)
 109 #define MT_RO_DATA      (MT_MEMORY | MT_RO | MT_EXECUTE_NEVER)
 110 #define MT_RW_DATA      (MT_MEMORY | MT_RW | MT_EXECUTE_NEVER)
 111
 112 /*
 113  * Structure for specifying a single region of memory.
 114  */
 115 typedef struct mmap_region {
 116         unsigned long long      base_pa;
 117         uintptr_t               base_va;
 118         size_t                  size;
 119         mmap_attr_t             attr;
 120         /* Desired granularity. See the MAP_REGION2() macro for more details. */
 121         size_t                  granularity;
 122 } mmap_region_t;
 123
 124 /*
 125  * Translation regimes supported by this library.
 126  */
 127 typedef enum xlat_regime {
 128         EL1_EL0_REGIME,
 129         EL3_REGIME,
 130 } xlat_regime_t;
 131
 132 /*
 133  * Declare the translation context type.
 134  * Its definition is private.
 135  */
 136 typedef struct xlat_ctx xlat_ctx_t;
 137
 138 /*
 139  * Statically allocate a translation context and associated structures. Also
 140  * initialize them.
 141  *
 142  * _ctx_name:
 143  *   Prefix for the translation context variable.
 144  *   E.g. If _ctx_name is 'foo', the variable will be called 'foo_xlat_ctx'.
 145  *   Useful to distinguish multiple contexts from one another.
 146  *
 147  * _mmap_count:
 148  *   Number of mmap_region_t to allocate.
 149  *   Would typically be MAX_MMAP_REGIONS for the translation context describing
 150  *   the BL image currently executing.
 151  *
 152  * _xlat_tables_count:
 153  *   Number of sub-translation tables to allocate.
 154  *   Would typically be MAX_XLAT_TABLES for the translation context describing
 155  *   the BL image currently executing.
 156  *   Note that this is only for sub-tables ; at the initial lookup level, there
 157  *   is always a single table.
 158  *
 159  * _virt_addr_space_size, _phy_addr_space_size:
 160  *   Size (in bytes) of the virtual (resp. physical) address space.
 161  *   Would typically be PLAT_VIRT_ADDR_SPACE_SIZE
 162  *   (resp. PLAT_PHY_ADDR_SPACE_SIZE) for the translation context describing the
 163  *   BL image currently executing.
 164  */
 165 #define REGISTER_XLAT_CONTEXT(_ctx_name, _mmap_count, _xlat_tables_count,       \
 166                         _virt_addr_space_size, _phy_addr_space_size)            \
 167         _REGISTER_XLAT_CONTEXT_FULL_SPEC(_ctx_name, _mmap_count,        \
 168                                          _xlat_tables_count,            \
 169                                          _virt_addr_space_size,         \
 170                                          _phy_addr_space_size,          \
 171                                          IMAGE_XLAT_DEFAULT_REGIME)
 172
 173 /*
 174  * Same as REGISTER_XLAT_CONTEXT plus the additional parameter _xlat_regime to
 175  * specify the translation regime managed by this xlat_ctx_t instance. The
 176  * values are the one from xlat_regime_t enumeration.
 177  */
 178 #define REGISTER_XLAT_CONTEXT2(_ctx_name, _mmap_count, _xlat_tables_count,      \
 179                         _virt_addr_space_size, _phy_addr_space_size,            \
 180                         _xlat_regime)                                   \
 181         _REGISTER_XLAT_CONTEXT_FULL_SPEC(_ctx_name, _mmap_count,        \
 182                                          _xlat_tables_count,            \
 183                                          _virt_addr_space_size,         \
 184                                          _phy_addr_space_size,          \
 185                                          _xlat_regime)
 186
 187 /******************************************************************************
 188  * Generic translation table APIs.
 189  * Each API comes in 2 variants:
 190  * - one that acts on the current translation context for this BL image
 191  * - another that acts on the given translation context instead. This variant
 192  *   is named after the 1st version, with an additional '_ctx' suffix.
 193  *****************************************************************************/
 194
 195 /*
 196  * Initialize translation tables from the current list of mmap regions. Calling
 197  * this function marks the transition point after which static regions can no
 198  * longer be added.
 199  */
 200 void init_xlat_tables(void);
 201 void init_xlat_tables_ctx(xlat_ctx_t *ctx);
 202
 203 /*
 204  * Add a static region with defined base PA and base VA. This function can only
 205  * be used before initializing the translation tables. The region cannot be
 206  * removed afterwards.
 207  */
 208 void mmap_add_region(unsigned long long base_pa, uintptr_t base_va,
 209                                 size_t size, mmap_attr_t attr);
 210 void mmap_add_region_ctx(xlat_ctx_t *ctx, const mmap_region_t *mm);
 211
 212 /*
 213  * Add an array of static regions with defined base PA and base VA. This
 214  * function can only be used before initializing the translation tables. The
 215  * regions cannot be removed afterwards.
 216  */
 217 void mmap_add(const mmap_region_t *mm);
 218 void mmap_add_ctx(xlat_ctx_t *ctx, const mmap_region_t *mm);
 219
 220
 221 #if PLAT_XLAT_TABLES_DYNAMIC
 222 /*
 223  * Add a dynamic region with defined base PA and base VA. This type of region
 224  * can be added and removed even after the translation tables are initialized.
 225  *
 226  * Returns:
 227  *        0: Success.
 228  *   EINVAL: Invalid values were used as arguments.
 229  *   ERANGE: Memory limits were surpassed.
 230  *   ENOMEM: Not enough space in the mmap array or not enough free xlat tables.
 231  *    EPERM: It overlaps another region in an invalid way.
 232  */
 233 int mmap_add_dynamic_region(unsigned long long base_pa, uintptr_t base_va,
 234                                 size_t size, mmap_attr_t attr);
 235 int mmap_add_dynamic_region_ctx(xlat_ctx_t *ctx, mmap_region_t *mm);
 236
 237 /*
 238  * Remove a region with the specified base VA and size. Only dynamic regions can
 239  * be removed, and they can be removed even if the translation tables are
 240  * initialized.
 241  *
 242  * Returns:
 243  *        0: Success.
 244  *   EINVAL: The specified region wasn't found.
 245  *    EPERM: Trying to remove a static region.
 246  */
 247 int mmap_remove_dynamic_region(uintptr_t base_va, size_t size);
 248 int mmap_remove_dynamic_region_ctx(xlat_ctx_t *ctx,
 249                                 uintptr_t base_va,
 250                                 size_t size);
 251
 252 #endif /* PLAT_XLAT_TABLES_DYNAMIC */
 253
 254 #endif /*__ASSEMBLY__*/
 255 #endif /* __XLAT_TABLES_V2_H__ */