riscos-dump 0.2.0
Display hexadecimal file dumps like RISC OS
License: MIT
Requires Python: >=2.7
Keywords: hexdump, arm, riscos

# RISC OS hex dump in Python

## Introduction

The modules in this repository provide a means by which a simple hexadecimal dump
may be provided for data, in the same style as that used by the RISC OS `*Dump`
or `*Memory` commands. The code was originally written for these commands (and the
tracing code) in RISC OS Pyromaniac. It has been extracted to a separate module
as it may be more generally useful.


## Installation

The tool for dumping can be installed manually using this repository
(see 'Usage' below) or through PyPI. To install, use:

    pip3 install riscos_dump


## Usage

Once installed, the tool can be invoked as `riscos-dump`. For example:

    riscos-dump examples/hello_world,ffc

There are two optional parameters:

* `<fileoffset>`: A hexadecimal offset into the file to start from
* `<baseaddr>`: Base address to display content from (defaults to 0 unless this is an Absolute file)

The following switches are supported:

* `--row-size`: Number of bytes listed within a row
* `--words`: Display as words, rather than bytes


## Package contents

The package `riscos_dump` contains all the classes used by the tool.

The `dump.py` module provides the implementation of the hexadecimal dumping.
Two classes are provided - `DumpBase` and `Dump`. The `DumpBase` class provides
the basics of decoding and deciding how the data supplied should be presented.
The `Dump` class is derived from `DumpBase` and provides a presentation for a
terminal.

A class `FileDataSource` is provided, which allows indexed access to the content
of a seekable file through a file handle.  This allows the data supplied to the
`DumpBase`/`Dump` objects to be loaded dynamically from disc.

The file `dumper.py` provides a very simple example of the usage of the Dump
objects. For more information on the usage, examine the `dump.py` module.

The file `wxdump.py` uses the `dump.py` module to construct WxPython grids and
frames containing a scrollable window of data. These are limited in their
flexibility at present, but may be extended through subclassing to provide more
functionality.

Two frame implementations exist - `DumpFrame`, which can be supplied data to
display; and `DumpFileFrame`, which will read the data from a file. Both can be
supplied a dictionary of parameters to set on the `DumpBase` object.

## Example code

The file `simple_dump.py` is a very simple dump tool which just displays a
hexadecimal dump from a file.

The file `wxdumper.py` is a simple application which displays the contents of
a file within a window. It is merely an example to show how the `wxdump.py`
classes can be used.

## 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`.

For example, displaying the content of the `hello_word` binary as bytes:

```
charles@laputa ~/riscos-dump-python $ riscos-dump examples/hello_world,ffc
Offset   :   0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F  : Text
       0 :  1C 00 8F E2 02 00 00 EF 20 10 8F E2 01 00 50 E1  : ........ .....P.
      10 :  01 00 00 1A 03 00 00 EF 0E F0 A0 E1 0C 00 8F E2  : ................
      20 :  2B 00 00 EF 48 65 6C 6C 6F 20 77 6F 72 6C 64 00  : +...Hello world.
      30 :  01 00 00 00 52 30 20 6F 6E 20 72 65 74 75 72 6E  : ....R0 on return
      40 :  20 66 72 6F 6D 20 4F 53 5F 57 72 69 74 65 30 20  :  from OS_Write0 
      50 :  77 61 73 20 6E 6F 74 20 63 6F 72 72 65 63 74 6C  : was not correctl
      60 :  79 20 73 65 74 20 74 6F 20 74 68 65 20 74 65 72  : y set to the ter
      70 :  6D 69 6E 61 74 6F 72 00                          : minator.
```

Similarly, to display as words (32bit values):

```
charles@laputa ~/riscos-dump-python $ riscos-dump --words examples/hello_world,ffc
Offset   :         0        4        8        C  : Text
       0 :  E28F001C EF000002 E28F1020 E1500001  : ........ .....P.
      10 :  1A000001 EF000003 E1A0F00E E28F000C  : ................
      20 :  EF00002B 6C6C6548 6F77206F 00646C72  : +...Hello world.
      30 :  00000001 6F203052 6572206E 6E727574  : ....R0 on return
      40 :  6F726620 534F206D 6972575F 20306574  :  from OS_Write0 
      50 :  20736177 20746F6E 72726F63 6C746365  : was not correctl
      60 :  65732079 6F742074 65687420 72657420  : y set to the ter
      70 :  616E696D 00726F74                    : minator.
```