Memory Layout Diagrams

Overview

A memory layout diagram describes how the address space of a system is divided into regions, and the .mld file format is the text description from which such a diagram is drawn. Diagrams of this kind are common in hardware and operating system documentation, where a fixed memory map is explained by a column of labelled blocks with the lowest address at the bottom.

The description is kept as a small text file, so it can be held in source control and the picture redrawn whenever the layout changes. The mld command, from the Memory Layout Diagram tool, draws it as an SVG image. It checks the description as it reads it, and reports anything it does not understand; this is described in Errors and warnings, below. The tool is installed with pip install memory-layout, and can also be run as python -m memory_layout. In the RISC OS Build Environment it is available as riscos-mld.

A .mld file has no RISC OS filetype. It is recognised by its .mld extension.

Concepts

File structure

%YAML 1.1

---

# Comments start with a hash.

defaults:

  unit_size: 0x1000

layout:

  0x0000: Low memory

automatic:

  discontinuities: true

Errors and warnings

The tool checks the description as it reads it, and writes what it finds to the error stream, one problem on each line. Each message gives the name of the tool, whether it is an error or a warning, the name of the file, and the problem. There are two kinds of problem.

An error means that no diagram can be drawn. The tool exits with status 1 and writes no output. The errors are:

• a file which cannot be read;
• syntax which the description language does not support, such as an inline list [a, b] or mapping {a: b}, a block string, an anchor, an alias or a tag. The message gives the line number. A value that really does start with one of these characters must be quoted;
• a quoted string which is not closed, or which has text after the closing quote;
• a key which is given twice in the same mapping;
• a document which is not a mapping, or which has no layout, or whose layout has no regions;
• a layout address which is not a number.

A warning means that the tool has understood enough to draw the diagram, but something in it was not as it should be, and it has used the default instead. The tool still writes the diagram and exits with status 0. The warnings are:

• a key which is not known where it is found. The message suggests the known key which is most like it, so that address in the automatic block is reported with a suggestion of addresses;
• a value which is not valid for its field: a colour, a distance, a label position, a junction style, a discontinuity style, an address side, a format name, a yes/no value which is not true or false, or a size or unit which is not a whole number greater than zero;
• a field which has no value, such as a colour which has not been quoted;
• a section or value of the wrong type, such as a defaults block which is not a mapping;
• two layout addresses which are the same address, written differently, such as 16 and 0x10.

The warnings name the field in which the problem was found, such as automatic.addresses.side or layout '0x1000' fill. They do not give a line number, because only the syntax errors are found while the lines are being read.

The --strict option makes every warning an error. The problems are reported as errors, no diagram is written, and the exit status is 1. Use it when a description is checked automatically, so that a mistake is not drawn silently.

$ mld readme.mld

mld: warning: readme.mld: Unknown key 'address' in 'automatic' (did you mean 'addresses'?)

$ mld --strict readme.mld

mld: error: readme.mld: Unknown key 'address' in 'automatic' (did you mean 'addresses'?)

Worked example

This description shows a small application space. The regions are given explicit sizes, one has a label on the left and one has a dotted boundary, the gaps are filled automatically, and the addresses are written in the RISC OS style.

defaults:

  unit_size: 0x1000

  address_format: acorn

  fill: "#C7E3EC"

  outline: "#336DA5"

layout:

  0x8000:

    size: 0x4000

    label: Program code

    labels:

      "el,ic": Read only

  0xC000:

    size: 0x2000

    label: Static data

    junction_high: dotted

  0x10000: Heap

automatic:

  discontinuities: true

  addresses:

    side: right

    start: true

Drawing it with mld produces an SVG image, with the program code at the bottom and the heap above it.

mld appslot.mld --output appslot.svg

Output and limits

The SVG renderer is the supported output. A second renderer writes a Graphviz description, but it cannot place regions close together and its output is much less faithful, so the SVG output is the one to use.

The checks find mistakes in the structure and the values of the description. They cannot know whether the picture is what was intended: a region with the wrong label, or a size which is valid but not the one meant, is still drawn. Look at the picture after changing a description.

Command line