docs/components/granule-protection-tables-design.rst

6 to initialize the GPTs based on a data structure containing information about
7 the systems memory layout, configure the system registers to enable granule
12 and non-secure. In addition to new security states, corresponding physical
13 address spaces have been added to control memory access for each state. The PAS
14 access allowed to each security state can be seen in the table below.
48 level 0 table controls access to a relatively large region in memory (GPT Block
49 descriptor), and the entire region can belong to a single PAS when a one step
50 mapping is used. Level 0 entry can also link to a level 1 table (GPT Table
54 The Level 1 tables entries with the same PAS can be combined to form a
69 is the smallest unit of memory that can be independently assigned to a PAS.
80 allocates memory for fine-grained locks adjacent to the L0 tables. In the
82 memory using the GPT register configuration and saves important data to a
99 A ``pas_region_t`` structure is a way to represent a physical address space and
100 its attributes that can be used by the GPT library to initialize the tables.
112 validity and create tables to implement it.
115 ``GPT_MAP_REGION_BLOCK`` and ``GPT_MAP_REGION_GRANULE`` be used to populate
116 these structures instead of doing it manually to reduce the risk of future
118 and PAS type as arguments to generate the pas_region_t structure. As the names
125 The GPT initialization APIs require memory to be passed in for the tables to be
138 ``GPT_MAP_REGION_GRANULE`` ownership to be changed using SMC calls. Non-secure
139 granules can be transitioned to either realm or secure space, and realm and
140 secure granules can be transitioned back to non-secure. This library only
141 allows Level 1 entries to be transitioned. The lib may either shatter
142 contiguous blocks or fuse adjacent GPT entries to form a contiguous block
144 propogate to higher block sizes as allowed by RME Architecture. Thus a higher
145 maximum block size may have a higher runtime cost due to software operations
146 that need to be performed for fuse to bigger block sizes. This cost may
147 be offset by better TLB performance due to the higher block size and platforms
148 need to make the trade-off decision based on their particular workload.
153 During Granule Transition access to L1 tables is controlled by a lock to ensure
154 that no more than one CPU is allowed to make changes at any given time.
157 structure. Setting this option to 0 chooses a single spinlock for all GPT L1
164 section is intended to provide additional details and clarifications.
166 To create the GPTs and enable granule protection checks the APIs need to be
171 #. Firmware must call ``gpt_init_l0_tables`` to initialize the level 0 tables to
172    a default state, that is, initializing all of the L0 descriptors to allow all
173    accesses to all memory. The PPS is provided to this function as an argument.
175    are then added to the L1 PAS regions to be initialized in the next step and
177 #. Firmware must call ``gpt_init_pas_l1_tables`` with a pointer to an array of
179    PGS is provided to this function as an argument.
180 #. Firmware must call ``gpt_enable`` to enable granule protection checks by
183    firmware must call ``gpt_runtime_init`` to set up the data structures needed
184    by the GTSI to find the tables and transition granules between PAS types.
185    The base address of bitlocks array and its size are provided to this function
220 corresponding to the size, not the size itself. The decoded hex representations
225 * The L0 table must be aligned to either the table size or 4096 bytes, whichever
233 * The L1 tables must be aligned to their size. The size of each L1 table is the
236 * There must be enough L1 memory supplied to build all requested L1 tables.
245 checked to ensure successful configuration.
254 Substitute values to get this: ((0x100000000 / 0x40000000) * 8)
256 And solve to get 32 bytes. In this case, 4096 is greater than 32, so the L0
257 tables must be aligned to 4096 bytes.
268 structure (8) to get the size of array in bytes.
273 Substitute values to get this: 0x1000000000000 / (1 * 0x20000000 * 8)
275 And solve to get 0x10000 bytes.
286 And solve to get 0x20000 bytes per L1 table.