README: mcdecoder

The mcdecoder (Machine Code Decoder) is a set of tools to implement a machine code decoder. It includes tools to:

Generate a decoder for a user-defined machine code specification
Emulate a decoder for a binary data and show decoded result
Check the integrity of a machine code specification
etc.

Currently, the mcdecoder only generates decoders in C language.

Quickstart

Define your machine code specification

arm.yaml

                             machine:
   byteorder: little
 instructions:
   - name: add_immediate_a1
     format: xxxx:cond|00|1|0100|x:S|xxxx:Rn|xxxx:Rd|xxxx xxxx xxxx:imm12

                          

Generate a decoder
```
mcdecoder generate arm.yaml
```

Use the decoder from a C client

                          const uint8_t kMachineCodes[] = { 0x04, 0xB0, 0x8D, 0xE2, };
DecodeRequest request;
DecodeResult result;
bool succeeded;

request.codes = &kMachineCodes[0];
succeeded = DecodeInstruction(&request, &result);

                        

For more details, follow Installation steps below and go on to Quickstart tutorial.

Who is mcdecoder for

Developers of a CPU emulator
- To implement the decoder part of an emulator
Developers of a static analyzer for machine codes
- To implement the decoder part of an analyzer
Learners of the basics about machine codes
- Hands-on approach to learn: write and test actual machine codes

Implementing and maintaining a decoder are tough and cumbersome. The mcdecoder soothes these pains by generating a decoder. The mcdecoder was originally developed for athrill, a CPU emulator. It is now independent from athrill.

Requirements

Python 3.10 (with pip)

Installation

                      python3.10 -m pip install mcdecoder

                    

License

The mcdecoder uses MIT License. See LICENSE for more details.

More details about usage

See documents for mcdecoder users.

For developers of mcdecoder

See documents for mcdecoder developers.