Merge branch 'main' into feat/friendly_name_instead_of_ids

README.md

@@ -178,18 +178,48 @@ area level, by specifying the names of the regions whose properties want to be o
 
 The diagram can have one or multiple areas. When multiple areas are declared,
 first area has a special status since all links will start on it and go to the corresponding sections on the other areas
-The following characteristics of a map can be defined
-- `x` and `y`: absolute position 
-- `size_x` and `size_y`: absolute size
-- `address`: range of addresses that must be included in the area
-    - `min`: minimum address to include
-    - `max`: maximum address to include
-- `start`: force area to start in to a given address
-- `end`: force area to end in to a given address.
-- `size`: size range for the sections to show
-  - `max`: maximum size of a memory section to be shown
-  - `min`: minimum size of a memory section to be shown
-- `style`: custom style for the given area, according to [Styles](####Styles) section.
+The areas are declared at root level under `areas`. Then each area must use the key `area`.
+For each area, the following characteristics of an area can be defined:
+- `title`:  **[Optional, none]**
+  - The title of the area, which will appear on top of it
+- `pos`:  **[Optional, (50, 50)]** **[x, y]**
+  - absolute position  of the area's top-left corner in pixels
+- `size`:  **[Optional, (300, 600)]** **[width, height]**
+  - area size in pixels
+- `range`:  **[Optional, (0, no limit)]** **[min, max]**
+  - range of addresses that will be taken into account in this area.
+  // - `start`: **[start, end]** force area to start in to a given address
+- `section-size`: **[Optional, (0, no limit)]** **[min, max]**
+  - size range of the sections that should be shown. Exclude others.
+- `style`:  **[Optional, default: parent style]**
+  - specific style for current area. See [Styles](####Styles) section.
+- `sections`: **[Optional, none]**
+  - specify or modify a section or group of sections property such as `style`, `flags`,...
+    - `names`:
+      - list of one or more sections to modify with the parameters below
+    - `flags`: **[Optional, none]**
+      - flags to append to the specified section/s. See [Flags](#### Section flags) section.
+    - `style`: **[Optional, parent style]**
+      - style properties to or modify to the specified section/s
+
+Below an example of area definition:
+
+```yaml
+areas:
+- area:
+    title: 'Full Memory Map'
+    pos: [30, 50]
+    size: [300, 900]
+    range: [0x0, 0x100000000]
+    section-size: [0x02F00000]
+    style:
+      fill: *pastel_green
+    sections:
+    - names: [ External Device ]
+      flags: grows-up
+      style:
+        hide-size: true
+```
 
 #### Section flags
 
@@ -198,6 +228,7 @@ Section flags allows to flag specified sections with special properties. These p
 Flags are listed under property `flags` and can be specified both at the map files under each section
 
 ```yaml
+# flags can be defined at map.yaml files under each section
 map:
 - address: 0x20000000
   id: stack
@@ -208,6 +239,7 @@ map:
 or at the configuration files, with the possibility to specify multiple sections at the same time:
 
 ```yaml
+# flags can be defined at config.yaml files under each section or group of sections
 areas:
 - area:
   # ...
@@ -234,17 +266,30 @@ There are four different break styles, which can be defined by the 'break-type'
 
 #### Links
 
-A link between same sections or addresses drawn at different areas can be created for making, for instance, _zoom_ in effects.
-For creating links between addresses, add the address value within a list under the `addresses` key.
-Do the same for creating links between sections.
-When specifying a section, both links for start and end of the section will be drawn. 
-If any area doesn't have one of the listed addresses or sections, the link will not be drawn for that section.
+Links establish a connection between same addresses or sections at different areas.
+
+While address links are represented with a finite line between the addresses, section link drawing
+cover the whole region space. These can be used,for instance, to represent a _zoom_ in effects from one overview area
+to other area with more detail.
+
+> When drawing a section link, Linkerscope expects both start and end section addresses to be visible at both intended areas.
+If any of those is not present, the link will not be drawn
+
+Links are defined at root level under the `links` tag. Links must have either `addresses` or `sections` tags or both.
+Additionally, specific styles can be specified under the `style` tag.
+
 
 ```yaml
 links:
-  addresses: [ 0x80045d4, 0x20000910, 0x200004e8]
-  sections: [HAL_RCC_OscConfig, __malloc_av_]
+  style:
+    stroke: 'lightgray'
+    stroke-width: 1
+    fill: 'gray'
+  addresses: [ 0xe8040000 ]
+  sections: [['Bit band region', 'Bit band alias']]
+
 ```
+<img style="display: block; margin-left: auto; margin-right: auto;" src="examples/link_example_map.svg">
 
 #### Other properties
 

examples/link_example_config.yaml

@@ -0,0 +1,79 @@
+size: [750, 650]
+variables:
+  graphite: &graphite '#2A363B'
+  pastel_green: &pastel_green '#99B898'
+  pastel_yellow: &pastel_yellow '#FECEA8'
+  pastel_orange: &pastel_orange '#FF847C'
+  pastel_red: &pastel_red '#E84A5F'
+
+style:
+  text-fill: 'lightgrey'
+  background: *graphite
+  fill: '#99B898'
+  hide-size: true
+  stroke: *graphite
+  stroke-width: 1
+  text-stroke: 'black'
+  text-stroke-width: 0
+  font_type: 'Helvetica'
+
+areas:
+- area:
+    title: 'Full Memory Map'
+    size: [200, 500]
+    range: [0x0, 0x100000000]
+    section-size: [0x02F00000]
+    style:
+      hide-address: true
+      fill: *pastel_green
+    sections:
+    - names: [ External Device, External Ram ]
+      fill: '#FF847C'
+      style:
+        hide-size: true
+        hide-address: true
+
+- area:
+    title: 'Address Link Example'
+    pos: [ 400, 50 ]
+    size: [ 200, 200 ]
+    range: [0xE8040000, 0xE8044000]
+    sections: # Adding the 'regions' sub-level under 'style'
+    - names: [ ROM Table ]
+      style:
+        fill: *pastel_green
+    - names: [ External PPB ]
+      style:
+        fill: *pastel_yellow
+    - names: [ ETM, Peripheral ]
+      style:
+        fill: *pastel_orange
+    - names: [ TPIU ]
+      style:
+        fill: *pastel_red
+
+- area:
+    title: 'Sections Link Example'
+    pos: [ 400, 330 ]
+    size: [ 200, 300 ]
+    range: [0x40000000, 0x43000000]
+    sections: # Adding the 'regions' sub-level under 'style'
+    - names: [ Bit ]
+      style:
+        fill: *pastel_yellow
+    - names: [ Bit band region ]
+      style:
+        fill: *pastel_orange
+    - names: [ Reserved ]
+      flags: grows-down
+
+links:
+  style:
+    stroke: 'lightgray'
+    stroke-width: 1
+    fill: 'gray'
+  addresses: [ 0xe8040000 ]
+  sections: [['Bit band region', 'Bit band alias']]
+
+
+

examples/link_example_map.yaml

@@ -0,0 +1,97 @@
+map:
+- address: 0x20000000
+  size:    0x20000000
+  id: SRAM Area
+  type: area
+- address: 0x40000000
+  size:    0x20000000
+  id: Peripheral
+  type: area
+- address: 0x60000000
+  size:    0x40000000
+  id: External RAM
+  type: area
+- address: 0xA0000000
+  size:    0x40000000
+  id: External Device
+  type: area
+- address: 0xE0000000
+  size:    0x08000000
+  id: Private Periph. Bus - Internal
+  type: area
+- address: 0xE8000000
+  size:    0x08000000
+  id: Private Periph. Bus - External
+  type: area
+- address: 0xF0000000
+  size:    0x08000000
+  id: Vendor Specific
+  type: area
+
+- address: 0xE8040000
+  size:    0x00001000
+  id: TPIU
+  type: section
+- address: 0xE8041000
+  size:    0x00001000
+  id: ETM
+  type: section
+- address: 0xE8042000
+  size:    0x00001000
+  id: External PPB
+  type: section
+- address: 0xE8043000
+  size:    0x00001000
+  id: ROM Table
+  type: section
+
+- address: 0xE0000000
+  size:    0x00010000
+  id: ITM
+  type: section
+- address: 0xE0010000
+  size:    0x00010000
+  id: DWT
+  type: section
+- address: 0xE0020000
+  size:    0x00010000
+  id: FPB
+  type: section
+- address: 0xE0030000
+  size:    0x000B0000
+  id: Reserved
+  type: section
+- address: 0xE00E0000
+  size:    0x00010000
+  id: NVIC
+  type: section
+- address: 0xE00F0000
+  size:    0x00010000
+  id: NVIC
+  type: section
+
+- address: 0x20000000
+  size:    0x00100000
+  id: Bit band region
+  type: section
+- address: 0x20100000
+  size:    0x01F00000
+  id: Bit
+  type: section
+- address: 0x22000000
+  size:    0x01000000
+  id: Bit band alias
+  type: section
+
+- address: 0x40000000
+  size:    0x00100000
+  id: Bit band region
+  type: section
+- address: 0x40100000
+  size:    0x01F00000
+  id: Bit
+  type: section
+- address: 0x42000000
+  size:    0x01000000
+  id: Bit band alias
+  type: section