rearrange definitions, make code more navigable

1 files changed, 50 insertions, 34 deletions

diff --git a/translation_table_descriptors.h b/translation_table_descriptors.h
index 975ab61..6aebe31 100644
--- a/translation_table_descriptors.h
+++ b/translation_table_descriptors.h
@@ -12,6 +12,10 @@
 // looks a bit messy... all for backward compatibility, i guess)
 
 
+////// Here are the definitions for short-format descriptors
+
+//// short-format page table descriptor
+
 typedef struct
 {
   uint32_t Bits_1_0   : 1;  // bits 1:0
@@ -32,6 +36,8 @@ typedef struct
 } short_page_table_descriptor_t;
 
 
+//// short-format section descriptor
+
 typedef struct
 {
   uint32_t PXN        : 1;  // bit  0
@@ -68,39 +74,7 @@ typedef struct
 } short_section_descriptor_t;
 
 
-// How AP[2:0] is used depends on settings in SCTLR.AFE
-
-// Meaning of #define'd names below:
-//   RW  - read-write
-//   RO  - read-only
-//   PL1 - a given permission applies to privilege level PL1
-//   PL2 - a given permission applies to privilege level PL2
-//   ALL - a given permission applies to both privilege levels
-// If only a permission for one privilege level is given in the name,
-// it means the other one has no access.
-
-// When SCTLR.AFE is 0 (access flag not used) and short-format
-// descritor table is used, the following access permission control
-// schema for AP[2:0] is used:
-#define AP_2_0_MODEL_NO_ACCESS         0b000
-#define AP_2_0_MODEL_RW_PL1            0b001
-#define AP_2_0_MODEL_RW_PL1_RO_PL0     0b010
-#define AP_2_0_MODEL_RW_ALL            0b011
-#define AP_2_0_MODEL_RESERVED          0b100
-#define AP_2_0_MODEL_RO_PL1            0b101
-#define AP_2_0_MODEL_RO_ALL_DEPRECATED 0b110 // use 0b111 instead
-#define AP_2_0_MODEL_RO_ALL            0b111 // reserved in VMSAv6
-// TODO: the #define's of RO_ALL and reserved could be done
-// conditionally depending on the VMSA version available (either give
-// the programmer #including this the possibility to #define their
-// VMSA version or assume the VMSA version respective to the ARM
-// version we're compiling against)
-
-// Values for bit18, that determines whether a descriptor describes
-// section or supersection:
-#define DESCRIBES_SECTION      0b0
-#define DESCRIBES_SUPERSECTION 0b1
-
+//// short-format supersection descriptor
 
 typedef struct
 {
@@ -139,6 +113,46 @@ typedef struct
 #define SUPERSECTION_BASE_ADDRESS_31_24 PA_31_24
 } short_supersection_descriptor_t;
 
+
+//// possible access permission field values
+
+// How AP[2:0] is used depends on settings in SCTLR.AFE
+
+// Meaning of #define'd names below:
+//   RW  - read-write
+//   RO  - read-only
+//   PL1 - a given permission applies to privilege level PL1
+//   PL2 - a given permission applies to privilege level PL2
+//   ALL - a given permission applies to both privilege levels
+// If only a permission for one privilege level is given in the name,
+// it means the other one has no access.
+
+// When SCTLR.AFE is 0 (access flag not used) and short-format
+// descritor table is used, the following access permission control
+// schema for AP[2:0] is used:
+#define AP_2_0_MODEL_NO_ACCESS         0b000
+#define AP_2_0_MODEL_RW_PL1            0b001
+#define AP_2_0_MODEL_RW_PL1_RO_PL0     0b010
+#define AP_2_0_MODEL_RW_ALL            0b011
+#define AP_2_0_MODEL_RESERVED          0b100
+#define AP_2_0_MODEL_RO_PL1            0b101
+#define AP_2_0_MODEL_RO_ALL_DEPRECATED 0b110 // use 0b111 instead
+#define AP_2_0_MODEL_RO_ALL            0b111 // reserved in VMSAv6
+// TODO: the #define's of RO_ALL and reserved could be done
+// conditionally depending on the VMSA version available (either give
+// the programmer #including this the possibility to #define their
+// VMSA version or assume the VMSA version respective to the ARM
+// version we're compiling against)
+
+
+//// Values for bit18, that determines whether a descriptor describes
+// section or supersection:
+#define DESCRIBES_SECTION      0b0
+#define DESCRIBES_SUPERSECTION 0b1
+
+
+//// short-format descriptor generic type
+
 typedef union
 {
   uint32_t                        raw;
@@ -149,7 +163,9 @@ typedef union
   // more to come here (e.g. short_supersection_descriptor_t)
 } short_descriptor_t;
 
-// possible values of descriptor_type field:
+
+//// possible values of descriptor_type field:
+
 #define SHORT_DESCRIPTOR_INVALID                     0b00
 #define SHORT_DESCRIPTOR_PAGE_TABLE                  0b01
 #define SHORT_DESCRIPTOR_SECTION_OR_SUPERSECTION     0b10