| <!-- Copyright (c) 2010-2026 Arm Limited or its affiliates. All rights reserved. --> | |
| <!-- This document is Non-confidential and licensed under the BSD 3-clause license. --> | |
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <meta charset="utf-8" /> | |
| <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| <meta http-equiv="x-ua-compatible" content="ie=edge"> | |
| <!--FAVICON.ico--> | |
| <meta name="msapplication-TileColor" content="#2b5797"> | |
| <meta name="msapplication-TileImage" content="../img/mstile-144x144.png"> | |
| <link rel="icon" href="../img/favicon.ico"> | |
| <title>ARM Machine Readable Schema - 2.9.6</title> | |
| <!--CSS--> | |
| <link rel="stylesheet" type="text/css" href="../css/bootstrap.min.css"> | |
| <link rel="stylesheet" type="text/css" href="../css/schema.css"> | |
| <link rel="stylesheet" type="text/css" href="../css/hljs-github.css"> | |
| </head> | |
| <body> | |
| <div class="container"> | |
| <div class="row heading"> | |
| <div class="col-md-6 pull-left"><a href="../index.html"><img src="../img/arm.svg" class="logo" /></a></div> | |
| <div class="col-md-6 pull-left"><h1>AARCHMRS Schema <small>2.9.6</small></h1></div> | |
| </div> | |
| </div> | |
| <div class="container"> | |
| <div class="row static-markdown"> | |
| <h1 id="registers">Registers</h1> | |
| <p>The <a class="schema_link" href="../Register_schema.html" title="Register">Register</a> schema defines the layout of Arm Architecture registers. | |
| Below is a guide that represents the general concepts in a register.</p> | |
| <div class="toc"><span class="toctitle">Table of Contents</span><ul> | |
| <li><a href="#a-named-field">A named field</a><ul> | |
| <li><a href="#values">Values</a></li> | |
| <li><a href="#resets">Resets</a></li> | |
| </ul> | |
| </li> | |
| <li><a href="#a-constant-field">A constant field</a></li> | |
| <li><a href="#a-conditional-field">A conditional field</a></li> | |
| <li><a href="#a-dynamic-field">A dynamic field</a></li> | |
| <li><a href="#an-implementation-defined-field">An implementation defined field</a></li> | |
| <li><a href="#an-array-of-fields">An array of fields</a></li> | |
| <li><a href="#a-reserved-field">A reserved field</a></li> | |
| <li><a href="#before-and-after-descriptions">Before and After descriptions</a></li> | |
| </ul> | |
| </div> | |
| <p>A register defines a named layout of fields. For example:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Register", | |
| "state": "AArch64", | |
| "name": "REG0", | |
| "title": "Register 0", | |
| "purpose": "To describe a simple register in the user guide.", | |
| "fieldsets": [ | |
| { | |
| "_type": "Fieldset", | |
| "width": 32, | |
| "values": [ | |
| { | |
| "_type": "Fields.Reserved", | |
| "value": "RES0", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 1, | |
| "width": 31 | |
| } | |
| ] | |
| }, | |
| { | |
| "_type": "Fields.Field", | |
| "name": "F0", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 1 | |
| } | |
| ], | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 0.", | |
| "value": "'0'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 1.", | |
| "value": "'1'" | |
| } | |
| ] | |
| } | |
| } | |
| ] | |
| } | |
| ] | |
| } | |
| </code></pre> | |
| <p>This example shows a 32-bit register called <code>REG0</code> in the <code>AArch64</code> | |
| state, which has two fields:</p> | |
| <ul> | |
| <li><code>RES0</code> located at bits <code>31:1</code>, <em>where <code>RES0</code> is an | |
| architecturally reserved field type which can return any value which | |
| must be read by software as <code>0</code>. You can read more about this | |
| concept in the Arm architecture.</em></li> | |
| <li><code>F0</code> located at bit <code>0</code>.</li> | |
| </ul> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>Field bit positions are always represented with the most | |
| significant bit first, followed by the least significant bit. | |
| For example: <code>MSB:LSB</code>, or <code>31:1</code>.</p> | |
| </div> | |
| <p>Registers are uniquely qualified by the combination of the <code>state</code> | |
| and <code>name</code>, which is denoted by joining the two with <code>-</code>. For | |
| example: <code>AArch64-REG0</code>. Therefore, a register in the external | |
| state which shares the name <code>REG0</code>, <code>ext-REG0</code>, is distinct from | |
| <code>AArch64-REG0</code> in MRS.</p> | |
| <p>See the <a class="schema_link" href="../Register_schema.html" title="Register">Register</a> schema definition for a full | |
| list of properties and their usage.</p> | |
| <h1 id="fieldsets">Fieldsets</h1> | |
| <p>A fieldset in MRS describes an arrangement of bits in a register. | |
| Fieldsets are children of registers, and a register can contain many | |
| Fieldsets.</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Register", | |
| "state": "AArch64", | |
| "name": "REG0", | |
| "purpose": "To describe a register containing fieldsets.", | |
| "fieldsets": [ | |
| { | |
| "_type": "Fieldset", | |
| "width": 64, | |
| "condition": "IsFeatureImplemented(FEAT_A)", | |
| "values": [ | |
| { | |
| "_type": "Fields.Reserved", | |
| "value": "RES0", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 4, | |
| "width": 60 | |
| } | |
| ] | |
| }, | |
| { | |
| "_type": "Fields.Field", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "A description of the F1 field." | |
| }, | |
| "name": "F1", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The first defined value.", | |
| "value": "'0000'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The second defined value.", | |
| "value": "'0011'" | |
| } | |
| ] | |
| } | |
| } | |
| ] | |
| }, | |
| { | |
| "_type": "Fieldset", | |
| "condition": null, | |
| "values": [ | |
| { | |
| "_type": "Fields.Reserved", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 64 | |
| } | |
| ], | |
| "value": "RES1" | |
| } | |
| ], | |
| "width": 64 | |
| } | |
| ] | |
| } | |
| </code></pre> | |
| <p>In this example, two fieldsets are contained within a <code>fieldsets</code> | |
| array, defining two distinct layouts of the same register. Where:</p> | |
| <ul> | |
| <li>the first fieldset is only valid if <code>FEAT_A</code> is implemented.</li> | |
| <li>the second fieldset represents the otherwise case (i.e. when <code>FEAT_A</code> is not implemented).</li> | |
| </ul> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>Conditions can be defined for both <code>Register</code> and <code>Fieldset</code> | |
| models, in addition to other models in MRS. If the condition | |
| for a register is not met, and there is no <code>null</code> condition | |
| specified, the register is absent. However, if defining | |
| conditional fieldsets, you must also specify a <code>null</code> condition | |
| fieldset.</p> | |
| </div> | |
| <p>The sum of the widths of the fields in a fieldset must equal the | |
| width of the fieldset.</p> | |
| <h1 id="fields">Fields</h1> | |
| <h2 id="a-named-field">A named field</h2> | |
| <p>A field in MRS gives the meaning of a specified range of bits | |
| within a fieldset. Fields are children of the <code>values</code> property | |
| of fieldsets. The following example demonstrates a simple field:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.Field", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "A description of the F1 field." | |
| }, | |
| "name": "F1", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The first defined value.", | |
| "value": "'0000'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The second defined value.", | |
| "value": "'0011'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The third defined value.", | |
| "value": "'0100'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The fourth defined value.", | |
| "value": "'1110'" | |
| } | |
| ] | |
| } | |
| } | |
| </code></pre> | |
| <p>Where:</p> | |
| <ul> | |
| <li>the <code>name</code> property is the unique name of bits 3:0, and must | |
| be unique within the fieldset.</li> | |
| <li>the <code>description</code> describes the field, written in | |
| <a href="../aml.html">Arm Markdown Language (AML)</a>.</li> | |
| <li>the <code>values</code> are architecturally defined bit-patterns with defined meanings | |
| (which are also defined in <a href="../aml.html">AML</a>).</li> | |
| </ul> | |
| <p>The above example should produce an output of the form:</p> | |
| <blockquote> | |
| <p><strong>F1, bits[3:0]</strong></p> | |
| <p>A description of the F1 field.</p> | |
| <ul> | |
| <li><code>'0000'</code>: The first defined value.</li> | |
| <li><code>'0011'</code>: The second defined value.</li> | |
| <li><code>'0100'</code>: The third defined value.</li> | |
| <li><code>'1110'</code>: The fourth defined value</li> | |
| </ul> | |
| </blockquote> | |
| <p>While different <a class="schema_link" href="../Fields/" title="Fields">Fields</a> schemas have different required | |
| properties, all fields must have a specified <code>rangeset</code>. | |
| The rangeset encodes the size of the field in bits, and specifies | |
| the location of this field in the containing Fieldset.</p> | |
| <p>See the <a class="schema_link" href="../Fields/" title="Fields">Fields</a> schema definition for a | |
| full list of properties and their usage, including optional | |
| properties and default implied values.</p> | |
| <h3 id="values">Values</h3> | |
| <p>An architecture defines bit-patterns which are expressed as values, and which can have an architectural | |
| meaning associated to them. Values defined in a field must fit the | |
| range of the field, for example the field <code>F1</code> is 4-bits (<code>3:0</code>), | |
| therefore it can only contain values within this range.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>The above output shows the short form of values, The | |
| <a class="schema_link" href="../Fields/Field_schema.html" title="Fields.Field">Fields.Field</a><code>.values</code> property is fully defined as a <a class="schema_link" href="../Valuesets/Values_schema.html" title="Valuesets.Values">Valuesets.Values</a> | |
| (a set of <a class="schema_link" href="../Values/" title="Values">Values</a> types), you can see the full canonical | |
| usage in the next example.</p> | |
| </div> | |
| <p>You can define conditional values using a <a class="schema_link" href="../Values/ConditionalValue_schema.html" title="Values.ConditionalValue">Values.ConditionalValue</a> | |
| model. In the example below, the conditional values only have | |
| meaning when <code>FEAT_A</code> is implemented. When <code>FEAT_A</code> is not | |
| implemented these values do not exist.</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.Field", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "An example field with conditional fields." | |
| }, | |
| "name": "FS", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The first defined value.", | |
| "value": "'0001'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The second defined value.", | |
| "value": "'0010'" | |
| }, | |
| { | |
| "_type": "Values.ConditionalValue", | |
| "condition": "IsFeatureImplemented(FEAT_A)", | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The third defined value, conditioned on FEAT_A.", | |
| "value": "'1110'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The third defined value, conditioned on FEAT_A.", | |
| "value": "'1111'" | |
| } | |
| ] | |
| } | |
| } | |
| ] | |
| } | |
| } | |
| </code></pre> | |
| <blockquote> | |
| <p><strong>F1, bits[3:0]</strong></p> | |
| <p>An example field with conditional fields.</p> | |
| <ul> | |
| <li><code>'0000'</code>: The first defined value.</li> | |
| <li><code>'0011'</code>: The second defined value.</li> | |
| <li><strong>when <code>FEAT_A</code> is implemented</strong>, <code>'0100'</code>: | |
| The third defined value, conditioned on FEAT_A.</li> | |
| <li><strong>when <code>FEAT_A</code> is implemented</strong>, <code>'1110'</code>: | |
| The fourth defined value, conditioned on FEAT_A.</li> | |
| </ul> | |
| </blockquote> | |
| <p>See the <a class="schema_link" href="../Values/ConditionalValue_schema.html" title="Values.ConditionalValue">Values.ConditionalValue</a> for more | |
| information</p> | |
| <h3 id="resets">Resets</h3> | |
| <p>A field may have an architecturally defined reset value, to which it is set when | |
| the CPU is booted or reset. This is specified using the <code>reset</code> property in fields. | |
| For example:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.Field", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "An example field with conditional fields." | |
| }, | |
| "name": "FS", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The value that is set during reset.", | |
| "value": "'0000'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Another value set during runtime.", | |
| "value": "'0011'" | |
| } | |
| ] | |
| }, | |
| "resets": { | |
| "_type": "FieldResets", | |
| "domains": { | |
| "warm": { | |
| "_type": "Values.Value", | |
| "meaning": null, | |
| "value": "'0000'" | |
| } | |
| } | |
| } | |
| } | |
| </code></pre> | |
| <p>Where:</p> | |
| <ul> | |
| <li><code>domain</code> is under which domain does a reset apply, most commonly | |
| a <code>warm</code> or <code>cold</code> domain is defined which generally relates | |
| a cold (power cycle) reset, vs a warm (during runtime) reset. | |
| These domains and their meaning are defined by the | |
| architecture and not by MRS.</li> | |
| <li>The value in the example is defined to be <code>'0000'</code>. Reset values may or may not be one of the architecturally | |
| defined values that are valid for this field, but must be within the range of the field (4-bits in this | |
| case)</li> | |
| </ul> | |
| <p>The <code>resets</code> property of a field is used to contain a <a class="schema_link" href="../FieldResets_schema.html" title="FieldResets">FieldResets</a> | |
| model, which defines the reset value for the field. You must | |
| usually specify reset behavior for each field, even if the reset | |
| behavior of the field is the default.</p> | |
| <p>As shown in the <a class="schema_link" href="../Fields/Field_schema.html" title="Fields.Field">Fields.Field</a> and <a class="schema_link" href="../Values/ConditionalValue_schema.html" title="Values.ConditionalValue">Values.ConditionalValue</a> | |
| examples above, the <code>resets</code> property of the field specifies which | |
| domain the reset is defined for (warm), and the value of the | |
| field following a reset of that specified domain | |
| (architecturally unknown).</p> | |
| <h2 id="a-constant-field">A constant field</h2> | |
| <p>A <a class="schema_link" href="../Fields/ConstantField_schema.html" title="Fields.ConstantField">Fields.ConstantField</a> model | |
| in MRS defines a <strong>named read-only field</strong> which holds one constant | |
| value in an implementation. Here is an example:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.ConstantField", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "An 8-bit value set by an implementation, to define the version" | |
| }, | |
| "name": "Version", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 8 | |
| } | |
| ], | |
| "value": { | |
| "_type": "Values.ImplementationDefined" | |
| } | |
| } | |
| </code></pre> | |
| <p>In the example above, | |
| <a class="schema_link" href="../Values/ImplementationDefined_schema.html" title="Values.ImplementationDefined">Values.ImplementationDefined</a> allows | |
| the implementation to specify any constant value.</p> | |
| <p>In some cases, an architecture can create constraints, this is | |
| done using the constraint property on <a class="schema_link" href="../Values/ImplementationDefined_schema.html" title="Values.ImplementationDefined">Values.ImplementationDefined</a>:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.ConstantField", | |
| "description": "An 8-bit value set by an implementation, defined by the architecture.", | |
| "name": "Version", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 8 | |
| } | |
| ], | |
| "value": { | |
| "_type": "Values.ImplementationDefined", | |
| "constraints": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "vMercury architecture.", | |
| "value": "'00000000'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "vVenus architecture.", | |
| "value": "'00000001'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "vEarth architecture.", | |
| "value": "'00000010'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "vMars architecture.", | |
| "value": "'00000011'" | |
| } | |
| ] | |
| } | |
| } | |
| } | |
| </code></pre> | |
| <p>Alternatively, architecture may define a constant field with a | |
| known value:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.ConstantField", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "An 8-bit value set by the architecture." | |
| }, | |
| "name": "Constant", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 8 | |
| } | |
| ], | |
| "value": { | |
| "_type": "Values.Value", | |
| "meaning": "vEarth architecture.", | |
| "value": "'00000010'" | |
| } | |
| } | |
| </code></pre> | |
| <h2 id="a-conditional-field">A conditional field</h2> | |
| <p>A <a class="schema_link" href="../Fields/ConditionalField_schema.html" title="Fields.ConditionalField">Fields.ConditionalField</a> | |
| model allows you to define different layouts on a specific range of bits.</p> | |
| <p>You can use <a class="schema_link" href="../Fields/ConditionalField_schema.html" title="Fields.ConditionalField">Fields.ConditionalField</a>, for example, in cases where | |
| a field is added by a feature and is reserved otherwise, or in | |
| cases where a field might be different depending on the properties | |
| of the implementation. For example:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.ConditionalField", | |
| "fields": [ | |
| { | |
| "condition": "IsFeatureImplemented(FEAT_A)", | |
| "field": { | |
| "_type": "Fields.Field", | |
| "name": "F1", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "F1 when FEAT_A is implemented" | |
| }, | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "values": {} | |
| } | |
| }, | |
| { | |
| "condition": null, | |
| "field": { | |
| "_type": "Fields.Field", | |
| "name": "F2", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "F2 otherwise" | |
| }, | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "values": {} | |
| } | |
| } | |
| ], | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 50, | |
| "width": 4 | |
| } | |
| ], | |
| "reservedtype": "RES0" | |
| } | |
| </code></pre> | |
| <p>Where:</p> | |
| <ul> | |
| <li>the <code>fields</code> array specifies an object with two properties:<ul> | |
| <li><code>condition</code>: The condition under which this field applies. | |
| A <code>null</code> condition is the way to specify an otherwise clause.</li> | |
| <li><code>field</code>: A <code>Fields.*</code> type.</li> | |
| </ul> | |
| </li> | |
| <li>The <code>reservedtype</code> property is a shorthand for the otherwise clause, equivalent to defining a | |
| <a class="schema_link" href="../Fields/ConditionalField_schema.html" title="Fields.ConditionalField">Fields.ConditionalField</a> with a null condition and containing a field with the specified reserved type. | |
| This can be used to shorthand the otherwise clause. In our example | |
| this property is ignored because the otherwise clause is specified | |
| explicitly in the <code>fields</code> array.</li> | |
| <li>The <code>rangeset</code> defined in <code>fields</code> is relative to the <code>rangeset</code> | |
| defined in the <a class="schema_link" href="../Fields/ConditionalField_schema.html" title="Fields.ConditionalField">Fields.ConditionalField</a>, so <code>F1</code> when resolved is at | |
| <code>53:50</code>.</li> | |
| </ul> | |
| <h2 id="a-dynamic-field">A dynamic field</h2> | |
| <p>A <a class="schema_link" href="../Fields/Dynamic_schema.html" title="Fields.Dynamic">Fields.Dynamic</a> model allows you to define different layouts of | |
| multiple fields <em>(unlike <a class="schema_link" href="../Fields/ConditionalField_schema.html" title="Fields.ConditionalField">Fields.ConditionalField</a> which allows you to | |
| specify one varying field)</em>. Similar to the <code>fields</code> array in | |
| <a class="schema_link" href="../Fields/ConditionalField_schema.html" title="Fields.ConditionalField">Fields.ConditionalField</a>, the fieldset that exists at any given | |
| instant is determined by a condition, and you can specify | |
| different properties for each fieldset and the fields it contains.</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Register", | |
| "state": "AArch64", | |
| "name": "REG0", | |
| "purpose": "To describe a register containing a dynamic field.", | |
| "fieldsets": [ | |
| { | |
| "_type": "Fieldset", | |
| "width": 32, | |
| "condition": null, | |
| "values": [ | |
| { | |
| "_type": "Fields.Dynamic", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "A Dynamic field called F_DYNAMIC with layout D1 and D2" | |
| }, | |
| "name": "F_DYNAMIC", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 1, | |
| "width": 31 | |
| } | |
| ], | |
| "instances": [ | |
| { | |
| "_type": "Fieldset", | |
| "name": "D1", | |
| "values": [ | |
| { | |
| "_type": "Fields.Reserved", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 2, | |
| "width": 29 | |
| } | |
| ], | |
| "value": "RES0" | |
| }, | |
| { | |
| "_type": "Fields.Field", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 2 | |
| } | |
| ], | |
| "name": "F1", | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 0.", | |
| "value": "'00'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 1.", | |
| "value": "'01'" | |
| } | |
| ] | |
| } | |
| } | |
| ], | |
| "width": 31 | |
| }, | |
| { | |
| "_type": "Fieldset", | |
| "name": "D2", | |
| "condition": "IsFeatureImplemented(FEAT_A)", | |
| "values": [ | |
| { | |
| "_type": "Fields.Reserved", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 4, | |
| "width": 27 | |
| } | |
| ], | |
| "value": "RES0" | |
| }, | |
| { | |
| "_type": "Fields.Field", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "name": "F5", | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 0.", | |
| "value": "'0000'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 1.", | |
| "value": "'0001'" | |
| } | |
| ] | |
| } | |
| } | |
| ], | |
| "width": 31 | |
| } | |
| ] | |
| }, | |
| { | |
| "_type": "Fields.Reserved", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 1 | |
| } | |
| ], | |
| "value": "RES0" | |
| } | |
| ] | |
| } | |
| ] | |
| } | |
| </code></pre> | |
| <p>Here you see a dynamic field called <code>F_DYNAMIC</code> with two layouts | |
| <code>D1</code> and <code>D2</code>. <code>D2</code> only exists when <code>FEAT_A</code> is implemented and | |
| the fields <code>D1.F1</code> and <code>D2.F1</code> are completely different fields.</p> | |
| <p>In some cases a layout may apply, given a value of another field. | |
| For example <code>D1</code> may apply if a value of <code>FOTHER == '00000'</code>. To | |
| specify this behavior we use a <a href="../Values/Link_schema.html"><code>Values.Link</code></a> within the <code>FOTHER</code> field.</p> | |
| <h2 id="an-implementation-defined-field">An implementation defined field</h2> | |
| <p>A <a class="schema_link" href="../Fields/ImplementationDefined_schema.html" title="Fields.ImplementationDefined">Fields.ImplementationDefined</a> | |
| model in MRS allocates space in a fieldset for | |
| implementation-specific fields. Use an implementation defined field | |
| to specify bits in a register that an implementation can use as | |
| required.</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.ImplementationDefined", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 8, | |
| "width": 4 | |
| } | |
| ] | |
| } | |
| </code></pre> | |
| <p>The allocated space for implementation defined fields can be | |
| divided into as many distinct fields as the implementation | |
| requires.</p> | |
| <h2 id="an-array-of-fields">An array of fields</h2> | |
| <p>A <a class="schema_link" href="../Fields/Array_schema.html" title="Fields.Array">Fields.Array</a> model defines a fixed | |
| number of fields as an array. This is a shorthand method of | |
| creating multiple similar fields, which are generated from a single | |
| <a class="schema_link" href="../Fields/Array_schema.html" title="Fields.Array">Fields.Array</a> model.</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.Array", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": "Array of F<n> fields, where n = 0 to 15." | |
| }, | |
| "index_variable": "n", | |
| "indexes": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 16 | |
| } | |
| ], | |
| "name": "F<n>", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 32 | |
| } | |
| ], | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 0.", | |
| "value": "'00'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 1.", | |
| "value": "'01'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "Value 3.", | |
| "value": "'11'" | |
| } | |
| ] | |
| } | |
| } | |
| </code></pre> | |
| <p>In the example above, the <code>index_variable</code>, <code>indexes</code>, | |
| <code>name</code>, and <code>rangeset</code> properties determine how the array of | |
| fields is generated. For each individual field within the array, | |
| the rangeset is expressed in terms of the index value. | |
| For example:</p> | |
| <ul> | |
| <li>a <code>rangeset</code> of <code>15:0</code> and <code>indexes</code> of <code>15:0</code> means that | |
| index value <code>n</code> corresponds to bit <code>n</code>, and each field is 1-bit | |
| long.</li> | |
| <li>a <code>rangeset</code> of <code>17, 0</code> and <code>indexes</code> of <code>1:0</code> means that index | |
| value <code>n</code> corresponds to bit <code>17n</code>. Therefore, when the array is expanded | |
| you will have two fields <code>F17</code> at bit <code>17</code> and <code>F0</code> at bit <code>0</code>, | |
| and each field is 1 bit long.</li> | |
| <li>a <code>rangeset</code> of <code>31:0</code> for <code>indexes</code> of <code>15:0</code>, as above, means | |
| that index value <code>n</code> corresponds to bits <code>2n+1:2n</code>, and each field | |
| is 2 bits long.</li> | |
| </ul> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>In the example above, the <a class="schema_link" href="../Fields/Array_schema.html" title="Fields.Array">Fields.Array</a> model automatically | |
| generates 16 fields, named <code>F(0-15)</code>. This means that no other | |
| fields within the same fieldset are permitted to share the | |
| name of a field that would be generated from the <a class="schema_link" href="../Fields/Array_schema.html" title="Fields.Array">Fields.Array</a> | |
| model.</p> | |
| </div> | |
| <h2 id="a-reserved-field">A reserved field</h2> | |
| <p>A <a class="schema_link" href="../Fields/Reserved_schema.html" title="Fields.Reserved">Fields.Reserved</a> model specifies a | |
| range of bits that are reserved by Arm for future use.</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.Reserved", | |
| "value": "RES0", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 56, | |
| "width": 8 | |
| } | |
| ] | |
| } | |
| </code></pre> | |
| <p>The above example defines a <code>RES0</code> field at bits <code>63:56</code>.</p> | |
| <h1 id="descriptions">Descriptions</h1> | |
| <p>A <a class="schema_link" href="../Description_schema.html" title="Description">Description</a> model in MRS allows you to add descriptive | |
| text within another model, such as a register, fieldset, or | |
| field, etc. A simple description, where text is only required before | |
| the content, can be implemented in a short-hand form as a | |
| property of a model:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.Field", | |
| "description": { | |
| "_type": "Description", | |
| "after": null, | |
| "before": [ | |
| "The first paragraph of the F1 field description.", | |
| "The second paragraph of the F1 field description.", | |
| [ | |
| "The third paragraph.", | |
| "This line is also part of the third paragraph." | |
| ] | |
| ] | |
| }, | |
| "name": "F1", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "values": {} | |
| } | |
| </code></pre> | |
| <p>An array notation is used to provide multiline support in JSON, where:</p> | |
| <ul> | |
| <li>First level of array represents a break between lines using two | |
| <code>\n\n</code>, this is due to AARCHMRS using AML, and in markdown | |
| two <code>\n\n</code> denote a split in paragraph.</li> | |
| <li>Second level of array represent one <code>\n</code> break. This is useful when | |
| defining concepts like lists (which require <code>\n</code>), or reduce the | |
| very long lines when writing large paragraphs.</li> | |
| </ul> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>You could have used <code>\n</code> inside one long string explicitly and | |
| it will result in the same output</p> | |
| </div> | |
| <h2 id="before-and-after-descriptions">Before and After descriptions</h2> | |
| <p>In some cases you need to define some text that appears before | |
| values, and other text that appears after them. For example if you | |
| wanted to represent the following:</p> | |
| <blockquote> | |
| <p><strong>F1, bits[3:0]</strong></p> | |
| <p>My F1 fields with two values</p> | |
| <ul> | |
| <li><code>'0000'</code>: The first defined value.</li> | |
| <li><code>'0011'</code>: The second defined value.</li> | |
| </ul> | |
| <p><u>My favourite value is '0000'</u></p> | |
| </blockquote> | |
| <p>Here saying "My favourite value is '0000'" before the value | |
| is defined may lead to confusion. Because of this, a description | |
| object can be stored as a dictionary, with <code>before</code> and <code>after</code> | |
| keys.</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Fields.Field", | |
| "description": { | |
| "_type": "Description", | |
| "before": "My F1 fields with two values", | |
| "after": "My favourite value is '0000'" | |
| }, | |
| "name": "F1", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 4 | |
| } | |
| ], | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The first defined value.", | |
| "value": "'0000'" | |
| }, | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The second defined value.", | |
| "value": "'0011'" | |
| } | |
| ] | |
| } | |
| } | |
| </code></pre> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>You can use the array notation for multiline support within | |
| <code>before</code> and <code>after</code> values</p> | |
| </div> | |
| <h1 id="mapset">Mapset</h1> | |
| <p>A mapset array in MRS captures architectural mappings between | |
| registers or register blocks, as a property of a <a class="schema_link" href="../Register_schema.html" title="Register">Register</a> | |
| model. This information automatically generates text in the | |
| Configuration section of the System register page, that states | |
| which mappings a register has, if any.</p> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>When specifying a bi-directional mapping between registers, | |
| you must specify the mapsets in both registers. The | |
| appropriate mapping information is then automatically | |
| rendered as text in the Configuration of both mapped | |
| registers. Specifying a mapset in only one register | |
| represents a uni-directional mapping.</p> | |
| </div> | |
| <p>A register can be mapped to multiple registers, such as | |
| equivalent AArch64, AArch32, and External registers which are | |
| all mapped to each other. However, as mappings can only be | |
| uni-directional or bi-directional, each pairwise mapping must | |
| be individually specified, if more than two registers are | |
| mapped to each other. For example, you must define mapsets | |
| in both <code>AArch64-REG0</code> and <code>ext-REG0</code> to capture an | |
| architectural mapping between them in MRS, even if both specify | |
| bi-directional mappings to a <code>AArch32-REG0</code> register.</p> | |
| <p>Below is an example of a mapset specified in <code>AArch64-REG0</code>:</p> | |
| <pre class="includes"><code class="language-json">{ | |
| "_type": "Register", | |
| "state": "AArch64", | |
| "name": "REG0", | |
| "title": "Register 0", | |
| "purpose": "To describe a simple register in the user guide.", | |
| "fieldsets": [ | |
| { | |
| "_type": "Fieldset", | |
| "width": 32, | |
| "values": [ | |
| { | |
| "_type": "Fields.Field", | |
| "name": "F0", | |
| "rangeset": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 32 | |
| } | |
| ], | |
| "values": { | |
| "_type": "Valuesets.Values", | |
| "values": [ | |
| { | |
| "_type": "Values.Value", | |
| "meaning": "The only known value.", | |
| "value": "'00000000000000000000000000000000'" | |
| } | |
| ] | |
| } | |
| } | |
| ] | |
| } | |
| ], | |
| "mapset": [ | |
| { | |
| "_type": "Mapping.RegisterMapping", | |
| "condition": null, | |
| "instance": null, | |
| "mapping_type": "Architectural", | |
| "maps": [ | |
| { | |
| "_type": "AST.SquareOp", | |
| "arguments": [ | |
| { | |
| "_type": "AST.Slice", | |
| "left": { | |
| "_type": "AST.Integer", | |
| "value": 31 | |
| }, | |
| "right": { | |
| "_type": "AST.Integer", | |
| "value": 0 | |
| } | |
| } | |
| ], | |
| "var": { | |
| "_type": "Types.RegisterType", | |
| "value": { | |
| "instance": null, | |
| "name": "REG0", | |
| "slices": null, | |
| "state": "ext" | |
| } | |
| } | |
| } | |
| ], | |
| "slices": [ | |
| { | |
| "_type": "Range", | |
| "start": 0, | |
| "width": 32 | |
| } | |
| ] | |
| } | |
| ] | |
| } | |
| </code></pre> | |
| <div class="admonition note"> | |
| <p class="admonition-title">Note</p> | |
| <p>In <code>ext-REG0</code> you would need a corresponding mapset mapping back | |
| to <code>AArch64-REG0</code></p> | |
| </div> | |
| <p>You can define a <a class="schema_link" href="../Mapping/RegisterMapping_schema.html" title="Mapping.RegisterMapping">Mapping.RegisterMapping</a> or | |
| <code>Mapping.RegisterBlockMapping</code> model within a <code>mapset</code> array. | |
| See the <a class="schema_link" href="../Mapping/RegisterMapping_schema.html" title="Mapping.RegisterMapping">Mapping.RegisterMapping</a> and <a class="schema_link" href="../Mapping/RegisterBlockMapping_schema.html" title="Mapping.RegisterBlockMapping">Mapping.RegisterBlockMapping</a> | |
| schema definitions for a full list of properties and their usage.</p> | |
| <h1 id="register-blocks">Register Blocks</h1> | |
| <p>A <a class="schema_link" href="../RegisterBlock_schema.html" title="RegisterBlock">RegisterBlock</a> encapsulates an array of <a class="schema_link" href="../Register_schema.html" title="Register">Register</a> or <a class="schema_link" href="../RegisterBlock_schema.html" title="RegisterBlock">RegisterBlock</a> object | |
| that occupy a contiguous range of the address map, and share a common set of | |
| accessors. The accessors define the access behaviors for each of the Registers and | |
| RegisterBlocks present in the blocks property.</p> | |
| <p>For examples of the RegisterBlock and a full list of properties and their | |
| usage, refer to the <a class="schema_link" href="../RegisterBlock_schema.html" title="RegisterBlock">RegisterBlock</a> schema definition.</p> | |
| </div> | |
| </div> | |
| <div class="container"> | |
| <div class="footer text-right"> | |
| Copyright © 2025 ARM Limited or its affiliates. All rights reserved. | |
| </div> | |
| </div> | |
| <script src="../js/highlight/highlight.js"></script> | |
| <script src="../js/highlight/languages/json.min.js"></script> | |
| <script src="../js/highlight/languages/django.min.js"></script> <!-- JINJA2 --> | |
| <script src="../js/highlight/languages/yaml.min.js"></script> | |
| <script src="../js/highlight/languages/isa.js"></script> | |
| <script type="text/javascript"> | |
| window.onload = function() { | |
| hljs.configure({ | |
| cssSelector: ".schema-json code, .includes code, pre code", | |
| noHighlightRe: /^(no-?highlight|nohl)$/i, | |
| }); | |
| hljs.highlightAll() | |
| }; | |
| </script> | |
| </body> | |
| </html> |