MRS natively supports markdown in its descriptive content, with a few useful Arm related addons. It inherits from the John Gruber's Markdown (If you are new to markdown, please read the spec above), but does not overwrite the original spec.
Below is a list of additions we have made to markdown to make life easier for Arm content:
The following group of words are defined by Arm to have special or additional meaning:
IMPLEMENTATION DEFINED
OPTIONAL
RES0
RES1
UNDEFINED
UNKNOWN
CONSTRAINED UNPREDICTABLE
UNPREDICTABLE
When they are used in Arm Markdown Language and rendered in output, they will be
automatically wrapped in an <arm-defined-word/> XHTML element as demonstrated below.
This element should be styled as small-caps in any rendered output.
<arm-defined-word>IMPLEMENTATION DEFINED</arm-defined-word>
0b01100 will be automatically converted into:
<binarynumber>0b01100</binaryNumber>
Hex numbers follow the same principle so the hex number
0xABcdEf123 will be converted to (Note it is coerced to upper-case
for consistency):
<hexnumber>0xABCDEF123</hexnumber>
Notes are usually used to define non architectural components in MRS models and so they need to be supported. For this we use [note] and [/note]. For example:
[note]This is a single line note[/note]
or
[note]
This is multiline
- Item 1
- Item 2
[/note]
Will be converted to an HTML representation of the note
<note><p>This is a single line note</p></note>
<note>
<p>This is multiline</p>
<ul>
<li>Item 1</li>
<li>Item 2</li>
</ul>
</note>
It is important to link to another register in the MRS model, but you don't want to write links all over the place, what if you could use a format that would recognize a register and auto-link it.
Well there is one. If you had:
The register AArch64-REG0_EL1 is also mapped to ext-REG0 but not AArch32-REG0. And register arrays can be written as AArch64-REG0<n>_EL1, and it will link correctly.
Will be auto converted to HTML using register_link tags:
The register <register_link state="AArch64" id="AArch64-reg0_el1.txt">REG0_EL1</register_link> is also mapped to <register_link state="ext" id="ext-reg0_el1.txt">REG0</register_link> but not <register_link state="AArch32" id="AArch32-reg0.txt">REG0</register_link>. And register arrays can be written as
<register_link state="AArch64" id="AArch64-regn_el1.txt">REG0<n>_EL1</register_link>, and
it will link correctly.
Note
In order to uniquely identify the target of a register link, some
context is required. If the register exists within a register block,
it must be referred to as a child of that block, with syntax in the
form of REGBLOCK1.REG0. For more information about register blocks,
refer to RegisterBlocks.
Outside of register blocks, the only supported prefixes are AArch64,
AArch32 and ext. The prefix such as AArch64 are shown to be
removed in the rendered output. Meaning the input AArch64-REG0 is shown
as REG0, but linked using the prefix.
Therefore the final HTML output will render as:
The register REG0_EL1 is also mapped to REG0 but not REG0. And register arrays can be written as REG0
_EL1, and it will link correctly.
Note
The .txt file extension is determined during runtime, and
can be configured by the implementer. For example for
xml rendering of the ArmARM, it is configured to be .xml
If you had AArch64-REG0 WITH SPACE this will recognize REG0
as a register and leave WITH SPACE alone, which can be annoying
so there is a way to be explicit about links by using the r
prefix in markdown linking syntax, for example:
The register r[REG0 WITH SPACES](AArch64-reg0-with-spaces) has spaces.
This will convert it into the following HTML:
The register <register_link state="AArch64" id="AArch64-reg0-with-spaces.txt">REG0 WITH SPACES</register_link> has spaces.
An example register name with a variable:
In some cases you may want to link to create links between different types of content, for
this you can use the x prefixed linking syntax, for example:
When x[FeatureName](linkid) is implemented,
the only permitted value is 0b0001.
Will be converted to the following HTML:
When <xref linkend="linkid">FeatureName</xref> is implemented,
the only permitted value is 0b0001.
Note
The linkend is an ID that can be used to reference different parts of your document, the
AML does not define what an ID should be, and different renders should use this ID to
generate links that are appropriate for their formats, or alternatively ignore
the link and just use the text
Writing tables is required in some cases due to the complexity of the ARM architecture. To do this the following format can be used:
+----------------------------------------------------+
| Hello | World |
+=======+============================================+
| Mars | Mars is the fourth planet from the Sun. |
+-------+--------------------------------------------+
| Earth | Earth is the third planet from the Sun. |
+-------+--------------------------------------------+
Note that the first row is separated from the rest of the table by the row of = symbols, and will
be styled differently (because the separation indicates that it is a header row).