# RISC OS disassembly in Python
## Introduction
This repository contains the modules used to disassemble ARM (32bit and 64bit)
and Thumb code for RISC OS Pyromaniac. It uses the Capstone library to do so,
but modifies the output so that the disassembly is in a form which is generally
seen by RISC OS users.
## Installation
The tool for disassembly can be installed manually using this repository
(see 'Usage' below) or through PyPI. To install, use:
pip3 install riscos_disassemble
## Usage
Once installed, the tool can be invoked as `riscos-dumpi`. For example:
riscos-dumpi examples/hello_world,ffc
The following switches are supported:
* `--arm`: Disassembles AArch32 (ARM 32 bit) code (the default)
* `--arm64`: Disassembles AArch64 (ARM 64 bit) code, rather than ARM code.
* `--thumb`: Disassembles Thumb code, rather than ARM code.
* `--colour`: Uses the original primary and secondary ANSI colours.
* `--colour-8bit`: Use the more featureful 8bit colour palette.
* `--debuggerplus`: Specify a list of modifications to the debugger output,
which originated in [DebuggerPlus](https://old-www.moreofthesa.me.uk/progs.utils.html).
* `--help-debuggerplus`: More information on the flags.
* `--function-map`: List the addresses for functions with signatures
* `--match`: Only disassemble functions with the given siganture, which may use wildcards.
The filename can be followed by a hexadecimal address to use as the base
address for the file's disassembly. By default the file will be based at
address 0 unless the file is suffixed by `,ff8` (an absolute file).
If the instruction set is not specified, the tool will try to guess whether
ARM or ARM64 should be decoded from the information in the file header.
### DebuggerPlus
DebuggerPlus is a module by Darren Salt, which provides more options
for disassembly than the standard Debugger module provided by RISC OS.
These options were indicated by flags which could be set at the
command line. The `riscos-dumpi` tool supports a subset of those flags.
Supported flags:
* `ANDEQasDCD`: Use DCD instead of ANDEQ, MOV Rn,Rn (same register) etc.
* `APCS`: Use APCS-R register set.
* `Lower`: Force all register names to lower case.
* `QuoteSWIs`: Put quotes around SWI names.
* `UseDCD`: Use DCD instead of 'Undefined instruction', and `BRK` where `DCD &x6000010` would be used.
* `UseNOP`: Use NOP instead of MOV R0,R0.
* `UseVDU`: Use VDU x instead of SWI OS_WriteI+x.
The flags may be specified on the command line with
`--debuggerplus=<flags>` repeated, or as a comma-separated list.
The flags may also be configured using the environment variable
`RISCOS_DUMPI_DEBUGGERPLUS`.
Flags prefixed by a `-` character will be disabled. This is useful to
disable the configuration in the environment variable, or those default
options. `Lower` is currently selected automatically by default.
## Use as a git text converter
If you have RISC OS binaries (or other ARM binaries) checked in to your Git
repository, it can be useful to be able to display and diff them. This can
be achieved by giving the binary files an attribute to indicate that they
should be converted to text first.
To mark the binary files, create a `.gitattributes` (or update your existing
file) with the attribute `diff=armbinary`. `armbinary` a label I have chosen
but you could use any name you preferred. For example:
examples/*,* diff=armbinary
This indicates that any file containing a comma (`,`) within the `examples`
directory is to be converted through the `armbinary` conversion.
To tell Git how to perform the conversion it is necessary to update the
`.gitconfig` file to know how to perform the conversion.
git config --global diff.armbinary.textconv "riscos-dumpi"
This indicates that when performing a diff (including `log -p` and others),
any files with the diff attribute `armbinary` will be passed to the `riscos-dumpi`
tool. You may prefer to use the colourised version of the disassembly, although
this will make it more difficult to see where changes are in diffs:
git config --global diff.armbinary.textconv "riscos-dumpi --colour-8bit"
For more information on the Git attributes, see:
https://git-scm.com/docs/gitattributes#_performing_text_diffs_of_binary_files
## Requirements
The disassembly code requires the Capstone library to be installed. Capstone
4 is currently recommended, although later versions may function as well.
```
pip install 'capstone<5'
```
## Reuse
To use this in another project you would usually need to import the module
and subclass the `Disassemble` class to add functions necessary to access
memory and registers, and to decode SWI calls. However, if you do not care
about these things, the simplest usage can be found in the example script
`simple_disassemble.py`.
The `riscos-dumpi` tool is provided in the package and can be invoked
with:
riscos-dumpi <options>
Or the tool can be manually invoked with:
python -m riscos_disassemble <options>
This tool has more advanced support for the options than the simple example.
## Examples
Example files are supplied in the `examples` directory to demonstrate the disassembly:
* `hello_world` utility file (suffixed by `,ffc`) is a test from the RISC OS Pyromaniac project, which verifies the behaviour of the SWI `OS_Write0`.
* `osbyte81_version` utility file is another test program, which checks the behaviour of `OS_Byte &81` when reading the operating system version.
* `kerneldebug` utility file tests that the input and output in the kernel works, and has function signatures that are recognised.
* `SystemBell` module file (suffixed by `,ffa`), provides the implementation of the system bell on RISC OS Select.
* `simple_aif` absolute file (suffixed by `,ff8`), is a 32bit AIF file.
* `aarch64_hello_world` absolute file (suffixed by `,ff8`) is an AArch64 RISC OS executable from the [RISC OS 64 Simple Binaries](https://github.com/gerph/riscos64-simple-binaries/) project.
* `aarch64_hello_world_utility` utility file (suffixed by `,ffc`) is an AArch64 RISC OS executable from the [RISC OS 64 Simple Binaries](https://github.com/gerph/riscos64-simple-binaries/) project.
Disassembling the example `hello_world` example is simple:
```
charles@laputa ~/riscos-disassemble-python $ riscos-dumpi examples/hello_world,ffc
00000000 : e28f001c : .... : ADR r0, &00000024 ; -> "Hello world"
00000004 : ef000002 : .... : SWI OS_Write0
00000008 : e28f1020 : ... : ADR r1, &00000030 ; -> [&00000001, &6f203052, &6572206e, &6e727574]
0000000c : e1500001 : ..P. : CMP r0, r1
00000010 : 1a000001 : .... : BNE &0000001c
00000014 : ef000003 : .... : SWI OS_NewLine
00000018 : e1a0f00e : .... : MOV pc, lr
0000001c : e28f000c : .... : ADR r0, &00000030 ; -> [&00000001, &6f203052, &6572206e, &6e727574]
00000020 : ef00002b : +... : SWI OS_GenerateError
00000024 : 6c6c6548 : Hell : STCLVS p5, c6, [r12], #-&120
00000028 : 6f77206f : o wo : SWIVS &77206f
0000002c : 00646c72 : rld. : RSBEQ r6, r4, r2, ROR r12
00000030 : 00000001 : .... : ANDEQ r0, r0, r1
00000034 : 6f203052 : R0 o : SWIVS &203052
00000038 : 6572206e : n re : LDRBVS r2, [r2, #-&6e]!
0000003c : 6e727574 : turn : MRCVS p5, #3, r7, c2, c4, #3
00000040 : 6f726620 : fro : SWIVS &726620
00000044 : 534f206d : m OS : MOVTPL r2, #&f06d ; #61549
00000048 : 6972575f : _Wri : LDMDBVS r2!, {r0, r1, r2, r3, r4, r6, r8, r9, r10, r12, lr} ^
0000004c : 20306574 : te0 : EORSHS r6, r0, r4, ROR r5
00000050 : 20736177 : was : RSBSHS r6, r3, r7, ROR r1
00000054 : 20746f6e : not : RSBSHS r6, r4, lr, ROR #30
00000058 : 72726f63 : corr : RSBSVC r6, r2, #&18c ; #396
0000005c : 6c746365 : ectl : LDCLVS p3, c6, [r4], #-&194
00000060 : 65732079 : y se : LDRBVS r2, [r3, #-&79]!
00000064 : 6f742074 : t to : SWIVS &742074
00000068 : 65687420 : the : STRBVS r7, [r8, #-&420]!
0000006c : 72657420 : ter : RSBVC r7, r5, #32, #8 ; #536870912 = bit 29
00000070 : 616e696d : mina : Undefined instruction
00000074 : 00726f74 : tor. : RSBSEQ r6, r2, r4, ROR pc
```
The bulk of the disassembly is textual data, but this is still decoded as if it is
executable.
Raw data
{
"_id": null,
"home_page": "https://github.com/gerph/riscos-disassemble-python",
"name": "riscos-disassemble",
"maintainer": null,
"docs_url": null,
"requires_python": ">=2.7",
"maintainer_email": null,
"keywords": "disassemble, arm, riscos",
"author": "Charles Ferguson",
"author_email": "gerph@gerph.org",
"download_url": "https://files.pythonhosted.org/packages/70/87/d3e3570ecb90ce39ed086f1ca093dee51945700bc1bcf16bd1ae9dff05c1/riscos-disassemble-0.6.62.tar.gz",
"platform": null,
"description": "# RISC OS disassembly in Python\n\n## Introduction\n\nThis repository contains the modules used to disassemble ARM (32bit and 64bit)\nand Thumb code for RISC OS Pyromaniac. It uses the Capstone library to do so,\nbut modifies the output so that the disassembly is in a form which is generally\nseen by RISC OS users.\n\n\n## Installation\n\nThe tool for disassembly can be installed manually using this repository\n(see 'Usage' below) or through PyPI. To install, use:\n\n pip3 install riscos_disassemble\n\n\n## Usage\n\nOnce installed, the tool can be invoked as `riscos-dumpi`. For example:\n\n riscos-dumpi examples/hello_world,ffc\n\nThe following switches are supported:\n\n* `--arm`: Disassembles AArch32 (ARM 32 bit) code (the default)\n* `--arm64`: Disassembles AArch64 (ARM 64 bit) code, rather than ARM code.\n* `--thumb`: Disassembles Thumb code, rather than ARM code.\n* `--colour`: Uses the original primary and secondary ANSI colours.\n* `--colour-8bit`: Use the more featureful 8bit colour palette.\n* `--debuggerplus`: Specify a list of modifications to the debugger output,\n which originated in [DebuggerPlus](https://old-www.moreofthesa.me.uk/progs.utils.html).\n* `--help-debuggerplus`: More information on the flags.\n* `--function-map`: List the addresses for functions with signatures\n* `--match`: Only disassemble functions with the given siganture, which may use wildcards.\n\nThe filename can be followed by a hexadecimal address to use as the base\naddress for the file's disassembly. By default the file will be based at\naddress 0 unless the file is suffixed by `,ff8` (an absolute file).\n\nIf the instruction set is not specified, the tool will try to guess whether\nARM or ARM64 should be decoded from the information in the file header.\n\n\n### DebuggerPlus\n\nDebuggerPlus is a module by Darren Salt, which provides more options\nfor disassembly than the standard Debugger module provided by RISC OS.\nThese options were indicated by flags which could be set at the\ncommand line. The `riscos-dumpi` tool supports a subset of those flags.\n\nSupported flags:\n\n* `ANDEQasDCD`: Use DCD instead of ANDEQ, MOV Rn,Rn (same register) etc.\n* `APCS`: Use APCS-R register set.\n* `Lower`: Force all register names to lower case.\n* `QuoteSWIs`: Put quotes around SWI names.\n* `UseDCD`: Use DCD instead of 'Undefined instruction', and `BRK` where `DCD &x6000010` would be used.\n* `UseNOP`: Use NOP instead of MOV R0,R0.\n* `UseVDU`: Use VDU x instead of SWI OS_WriteI+x.\n\nThe flags may be specified on the command line with\n`--debuggerplus=<flags>` repeated, or as a comma-separated list.\nThe flags may also be configured using the environment variable\n`RISCOS_DUMPI_DEBUGGERPLUS`.\n\nFlags prefixed by a `-` character will be disabled. This is useful to\ndisable the configuration in the environment variable, or those default\noptions. `Lower` is currently selected automatically by default.\n\n\n## Use as a git text converter\n\nIf you have RISC OS binaries (or other ARM binaries) checked in to your Git\nrepository, it can be useful to be able to display and diff them. This can\nbe achieved by giving the binary files an attribute to indicate that they\nshould be converted to text first.\n\nTo mark the binary files, create a `.gitattributes` (or update your existing\nfile) with the attribute `diff=armbinary`. `armbinary` a label I have chosen\nbut you could use any name you preferred. For example:\n\n examples/*,* diff=armbinary\n\nThis indicates that any file containing a comma (`,`) within the `examples`\ndirectory is to be converted through the `armbinary` conversion.\n\nTo tell Git how to perform the conversion it is necessary to update the\n`.gitconfig` file to know how to perform the conversion.\n\n git config --global diff.armbinary.textconv \"riscos-dumpi\"\n\nThis indicates that when performing a diff (including `log -p` and others),\nany files with the diff attribute `armbinary` will be passed to the `riscos-dumpi`\ntool. You may prefer to use the colourised version of the disassembly, although\nthis will make it more difficult to see where changes are in diffs:\n\n git config --global diff.armbinary.textconv \"riscos-dumpi --colour-8bit\"\n\nFor more information on the Git attributes, see:\nhttps://git-scm.com/docs/gitattributes#_performing_text_diffs_of_binary_files\n\n\n## Requirements\n\nThe disassembly code requires the Capstone library to be installed. Capstone\n4 is currently recommended, although later versions may function as well.\n\n```\npip install 'capstone<5'\n```\n\n\n## Reuse\n\nTo use this in another project you would usually need to import the module\nand subclass the `Disassemble` class to add functions necessary to access\nmemory and registers, and to decode SWI calls. However, if you do not care\nabout these things, the simplest usage can be found in the example script\n`simple_disassemble.py`.\n\nThe `riscos-dumpi` tool is provided in the package and can be invoked\nwith:\n\n riscos-dumpi <options>\n\nOr the tool can be manually invoked with:\n\n python -m riscos_disassemble <options>\n\nThis tool has more advanced support for the options than the simple example.\n\n## Examples\n\nExample files are supplied in the `examples` directory to demonstrate the disassembly:\n\n* `hello_world` utility file (suffixed by `,ffc`) is a test from the RISC OS Pyromaniac project, which verifies the behaviour of the SWI `OS_Write0`.\n* `osbyte81_version` utility file is another test program, which checks the behaviour of `OS_Byte &81` when reading the operating system version.\n* `kerneldebug` utility file tests that the input and output in the kernel works, and has function signatures that are recognised.\n* `SystemBell` module file (suffixed by `,ffa`), provides the implementation of the system bell on RISC OS Select.\n* `simple_aif` absolute file (suffixed by `,ff8`), is a 32bit AIF file.\n* `aarch64_hello_world` absolute file (suffixed by `,ff8`) is an AArch64 RISC OS executable from the [RISC OS 64 Simple Binaries](https://github.com/gerph/riscos64-simple-binaries/) project.\n* `aarch64_hello_world_utility` utility file (suffixed by `,ffc`) is an AArch64 RISC OS executable from the [RISC OS 64 Simple Binaries](https://github.com/gerph/riscos64-simple-binaries/) project.\n\nDisassembling the example `hello_world` example is simple:\n\n```\ncharles@laputa ~/riscos-disassemble-python $ riscos-dumpi examples/hello_world,ffc\n00000000 : e28f001c : .... : ADR r0, &00000024 ; -> \"Hello world\"\n00000004 : ef000002 : .... : SWI OS_Write0\n00000008 : e28f1020 : ... : ADR r1, &00000030 ; -> [&00000001, &6f203052, &6572206e, &6e727574]\n0000000c : e1500001 : ..P. : CMP r0, r1\n00000010 : 1a000001 : .... : BNE &0000001c\n00000014 : ef000003 : .... : SWI OS_NewLine\n00000018 : e1a0f00e : .... : MOV pc, lr\n0000001c : e28f000c : .... : ADR r0, &00000030 ; -> [&00000001, &6f203052, &6572206e, &6e727574]\n00000020 : ef00002b : +... : SWI OS_GenerateError\n00000024 : 6c6c6548 : Hell : STCLVS p5, c6, [r12], #-&120\n00000028 : 6f77206f : o wo : SWIVS &77206f\n0000002c : 00646c72 : rld. : RSBEQ r6, r4, r2, ROR r12\n00000030 : 00000001 : .... : ANDEQ r0, r0, r1\n00000034 : 6f203052 : R0 o : SWIVS &203052\n00000038 : 6572206e : n re : LDRBVS r2, [r2, #-&6e]!\n0000003c : 6e727574 : turn : MRCVS p5, #3, r7, c2, c4, #3\n00000040 : 6f726620 : fro : SWIVS &726620\n00000044 : 534f206d : m OS : MOVTPL r2, #&f06d ; #61549\n00000048 : 6972575f : _Wri : LDMDBVS r2!, {r0, r1, r2, r3, r4, r6, r8, r9, r10, r12, lr} ^\n0000004c : 20306574 : te0 : EORSHS r6, r0, r4, ROR r5\n00000050 : 20736177 : was : RSBSHS r6, r3, r7, ROR r1\n00000054 : 20746f6e : not : RSBSHS r6, r4, lr, ROR #30\n00000058 : 72726f63 : corr : RSBSVC r6, r2, #&18c ; #396\n0000005c : 6c746365 : ectl : LDCLVS p3, c6, [r4], #-&194\n00000060 : 65732079 : y se : LDRBVS r2, [r3, #-&79]!\n00000064 : 6f742074 : t to : SWIVS &742074\n00000068 : 65687420 : the : STRBVS r7, [r8, #-&420]!\n0000006c : 72657420 : ter : RSBVC r7, r5, #32, #8 ; #536870912 = bit 29\n00000070 : 616e696d : mina : Undefined instruction\n00000074 : 00726f74 : tor. : RSBSEQ r6, r2, r4, ROR pc\n```\n\nThe bulk of the disassembly is textual data, but this is still decoded as if it is\nexecutable.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Disassemble ARM 32, ARM 64 and Thumb files like RISC OS",
"version": "0.6.62",
"project_urls": {
"Homepage": "https://github.com/gerph/riscos-disassemble-python"
},
"split_keywords": [
"disassemble",
" arm",
" riscos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7087d3e3570ecb90ce39ed086f1ca093dee51945700bc1bcf16bd1ae9dff05c1",
"md5": "b098f847c3a38f2902e05e8827903e06",
"sha256": "5089d292a677d7c7ea14662664c223ea99437eb8a6078d8d69324394b66a78ec"
},
"downloads": -1,
"filename": "riscos-disassemble-0.6.62.tar.gz",
"has_sig": false,
"md5_digest": "b098f847c3a38f2902e05e8827903e06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7",
"size": 48335,
"upload_time": "2024-10-26T16:59:02",
"upload_time_iso_8601": "2024-10-26T16:59:02.909061Z",
"url": "https://files.pythonhosted.org/packages/70/87/d3e3570ecb90ce39ed086f1ca093dee51945700bc1bcf16bd1ae9dff05c1/riscos-disassemble-0.6.62.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 16:59:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gerph",
"github_project": "riscos-disassemble-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "riscos-disassemble"
}
JSON
