pw_bloat: Helper macros to generate memoryregions and utilization

This patch introduces helper preprocessor macros to generate the
snippets of code neded in the linker script to provide memoryregions
and utilization datasources.

Added examples to the documentation.

Change-Id: I2123b1f8819eba14d6f47db5dc307baae24f006f
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/107341
Reviewed-by: Armando Montanez <amontanez@google.com>
Commit-Queue: Alex Deymo <deymo@google.com>

2 files changed, 112 insertions, 20 deletions

diff --git a/pw_bloat/bloat_macros.ld b/pw_bloat/bloat_macros.ld
new file mode 100644
index 000000000..c2f754b57
--- /dev/null
+++ b/pw_bloat/bloat_macros.ld
@@ -0,0 +1,73 @@
+/*
+ * Copyright 2022 The Pigweed Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+/* Helper macros to define the symbols requires by pw_bloat to detect the
+ * utilization and memory regions of your program.
+ *
+ * Include this file into your pw_linker_script() as follows:
+ *
+ *   pw_linker_script("my_linker_script") {
+ *     includes = [ "$dir_pw_bloat/bloat_macros.ld" ]
+ *     linker_script = "my_project_linker_script.ld"
+ *   }
+ */
+
+/* Default alignment used when declaring new sections. In most cases the free
+ * space should be measured down to a multiple of 4 bytes, but this can be
+ * changed in needed. */
+#ifndef PW_BLOAT_SECTION_ALIGN
+#define PW_BLOAT_SECTION_ALIGN 4
+#endif
+
+/* Declares an unused_space section. Instantiate this macro from within the
+ * SECTIONS of your linker script, after every other section, for example:
+ *   PW_BLOAT_UNUSED_SPACE_SECTION(FLASH)
+ *   PW_BLOAT_UNUSED_SPACE_SECTION(RAM)
+ */
+#define PW_BLOAT_UNUSED_SPACE_SECTION(memory_region)                  \
+  .memory_region.unused_space(NOLOAD) : ALIGN(PW_BLOAT_SECTION_ALIGN) \
+  {                                                                   \
+    . = ABSOLUTE(ORIGIN(memory_region) + LENGTH(memory_region));      \
+  } > memory_region
+
+/* Declares a memory region in pw_bloat mapped to the same name. Example:
+ *   PW_BLOAT_MEMORY_REGION(FLASH)
+ */
+#define PW_BLOAT_MEMORY_REGION(memory_region) \
+  PW_BLOAT_MEMORY_REGION_MAP(memory_region, memory_region)
+
+/* Declares a memory region in pw_bloat mapped to a different name. Can be used
+ * multiple times to map multiple aliased memory regions to the same name.
+ *   PW_BLOAT_MEMORY_REGION_MAP(RAM, ITCM)
+ *   PW_BLOAT_MEMORY_REGION_MAP(RAM, DTCM)
+ */
+#define PW_BLOAT_MEMORY_REGION_MAP(name, memory_region) \
+  PW_BLOAT_MEMORY_REGION_MAP_N(name, memory_region, __COUNTER__)
+
+/* Alternative version of PW_BLOAT_MEMORY_REGION_MAP to also specify the index
+ * value. This index value is irrelevant for pw_bloat tools as long as it
+ * doesn't repeat for the same name. Use this macro if you need to specify the
+ * index value for other tools.
+ * Note: this uses two macros to expand __COUNTER__ in
+ *       PW_BLOAT_MEMORY_REGION_MAP. */
+#define PW_BLOAT_MEMORY_REGION_MAP_N(name, memory_region, index) \
+  _PW_BLOAT_MEMORY_REGION_MAP_N(name, memory_region, index)
+
+#define _PW_BLOAT_MEMORY_REGION_MAP_N(name, memory_region, index) \
+  pw_bloat_config_memory_region_##name##_start_##index =          \
+      ORIGIN(memory_region);                                      \
+  pw_bloat_config_memory_region_##name##_end_##index =            \
+      ORIGIN(memory_region) + LENGTH(memory_region);
diff --git a/pw_bloat/docs.rst b/pw_bloat/docs.rst
index 01c706601..c8d0ac00c 100644
--- a/pw_bloat/docs.rst
+++ b/pw_bloat/docs.rst
@@ -329,13 +329,10 @@ Could be modified as follows enable ``Free Space`` reporting:
       . = ALIGN(4);
     } >RAM AT> FLASH
 
-    /* Represents unused space in the FLASH segment. This MUST be the last
-     * section assigned to the FLASH region.
+    /* Defines a section representing the unused space in the FLASH segment.
+     * This MUST be the last section assigned to the FLASH region.
      */
-    .FLASH.unused_space (NOLOAD) : ALIGN(4)
-    {
-      . = ABSOLUTE(ORIGIN(FLASH) + LENGTH(FLASH));
-    } >FLASH
+    PW_BLOAT_UNUSED_SPACE(FLASH)
 
     /* Zero initialized global/static data. (.bss). */
     .zero_init_ram (NOLOAD) : ALIGN(4)
@@ -346,15 +343,28 @@ Could be modified as follows enable ``Free Space`` reporting:
       . = ALIGN(4);
     } >RAM
 
-    /* Represents unused space in the RAM segment. This MUST be the last section
-     * assigned to the RAM region.
+    /* Defines a section representing the unused space in the RAM segment. This
+     * MUST be the last section assigned to the RAM region.
      */
-    .RAM.unused_space (NOLOAD) : ALIGN(4)
-    {
-      . = ABSOLUTE(ORIGIN(RAM) + LENGTH(RAM));
-    } >RAM
+    PW_BLOAT_UNUSED_SPACE(RAM)
   }
 
+The preprocessor macro ``PW_BLOAT_UNUSED_SPACE`` is defined in
+``pw_bloat/bloat_macros.ld``. To use these macros include this file in your
+``pw_linker_script`` as follows:
+
+.. code-block::
+
+   pw_linker_script("my_linker_script") {
+     includes = [ "$dir_pw_bloat/bloat_macros.ld" ]
+     linker_script = "my_project_linker_script.ld"
+   }
+
+Note that linker scripts are not natively supported by GN and can't be provided
+through ``deps``, the ``bloat_macros.ld`` must be passed in the ``includes``
+list.
+
+
 ``memoryregions`` data source
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Understanding how symbols, sections, and other data sources can be attributed
@@ -369,18 +379,29 @@ files, ``pw_bloat.bloaty_config`` consumes symbols which are defined in the
 linker script with a special format to extract this information from the ELF
 file: ``pw_bloat_config_memory_region_NAME_{start,end}{_N,}``.
 
+These symbols are defined by the preprocessor macros ``PW_BLOAT_MEMORY_REGION``
+and ``PW_BLOAT_MEMORY_REGION_MAP`` with the right address and size for the
+regions. To use these macros include the ``pw_bloat/bloat_macros.ld`` in your
+``pw_linker_script`` as follows:
+
+.. code-block::
+
+   pw_linker_script("my_linker_script") {
+     includes = [ "$dir_pw_bloat/bloat_macros.ld" ]
+     linker_script = "my_project_linker_script.ld"
+   }
+
 These symbols are then used to determine how to map segments to these memory
 regions. Note that segments must be used in order to account for inter-section
 padding which are not attributed against any sections.
 
 As an example, if you have a single view in the single memory region named
-``FLASH``, then you should produce the following two symbols in your linker
-script:
+``FLASH``, then you should include the following macro in your linker script to
+generate the symbols needed for the that region:
 
 .. code-block::
 
-  pw_bloat_config_memory_region_FLASH_start = ORIGIN(FLASH);
-  pw_bloat_config_memory_region_FLASH_end = ORIGIN(FLASH) + LENGTH(FLASH);
+  PW_BLOAT_MEMORY_REGION(FLASH)
 
 As another example, if you have two aliased memory regions (``DCTM`` and
 ``ITCM``) into the same effective memory named you'd like to call ``RAM``, then
@@ -388,7 +409,5 @@ you should produce the following four symbols in your linker script:
 
 .. code-block::
 
-  pw_bloat_config_memory_region_RAM_start_0 = ORIGIN(ITCM);
-  pw_bloat_config_memory_region_RAM_end_0 = ORIGIN(ITCM) + LENGTH(ITCM);
-  pw_bloat_config_memory_region_RAM_start_1 = ORIGIN(DTCM);
-  pw_bloat_config_memory_region_RAM_end_1 = ORIGIN(DTCM) + LENGTH(DTCM);
+  PW_BLOAT_MEMORY_REGION_MAP(RAM, ITCM)
+  PW_BLOAT_MEMORY_REGION_MAP(RAM, DTCM)