Working with MRS Data

Introduction

This blog post follows on from Getting started with AARCHMRS Features.json using Python. It introduces the broader set of data available through the Machine Readable Specification (MRS), including features, instructions, and registers.

What is the MRS?

The Arm Architecture Machine Readable Specification (MRS) provides a structured JSON representation of the Arm Architecture Reference Manual for A-profile. The MRS makes architectural information available in a format that software can process directly. This is instead of requiring tools to extract information from human-readable documentation.

The MRS consists of three main JSON files:

1. Features.json
2. Instructions.json
3. Registers.json

Features.json describes architectural features and the relationships between them. The file also defines constraints that link features to architecture versions, other features, and register fields. For example, a constraint can specify that support for one architectural feature requires support for another.

Instructions.json provides a machine-readable representation of the instruction set. It contains instruction definitions, assembly syntax, architectural conditions, encoding information, and links to associated operations.

Registers.json provides a machine-readable representation of architectural registers. It describes information such as register availability, field layouts, access mechanisms, mappings, and other register metadata.

Together, these files provide programmatic access to architecture information in a consistent structure. Software can use this structure as a foundation for automating architecture-related tasks.

What can we do with MRS Data?

Some of the examples discussed in this post come from PAT2, a Python-based parser and analysis tool for Tarmac trace logs and target configuration files. PAT2 imports MRS data and uses the structured architectural information as part of its analysis.

PAT2 is publicly available here.

Example 1 : Feature checker

This is an example from PAT2. The program reads in the value of ID Registers, and from this, uses Features.json to determine which mandatory and optional features it supports. Below is an example of the output for an Arm processor.

Example 2 : Instruction encoding parser

This example shows how Instructions.json can identify an instruction from a machine encoding. Given an instruction encoding and instruction set, the parser compares the fixed encoding bits with the the definitions in Instructions.json.  It then identifies a matching instruction definition.

The parser can then return information associated about the instruction, such as its name, assembly syntax, and encoded fields. This example demonstrates how machine-readable instruction definitions support deterministic instruction lookup.

Here is an example of inputting 0xDAC103E5 for AArch64:

Example 3: Register IMPDEF finder

This example uses Registers.json to find architectural registers that include IMPLEMENTATION DEFINED content and identify which bits are affected. A standalone Python script reads the structured register data directly. The script reports whether the implementation-defined content covers an entire register or only specific bit ranges.

Please note that this is a screenshot of a small portion of the output.

Further reading

For an introduction to working with Features.json using Python, see Getting started with AARCHMRS Features.json using Python.

For more detail on how MRS data is structured, how to parse it, and the use cases discussed in this post, see the Working with MRS data white paper linked below.

Working with MRS data white paper