Internal modules and members

__main__

mcdecoder.__main__.main() → int

Entry point for mcdecoder

Returns:

Exit code of mcdecoder

app

mcdecoder.app.run_app(argv: List[str]) → int

Run the application workflow of mcdecoder.

Parse argv and execute a corresponding sub-command.

Parameters:

argv – Command line parameters

Returns:

Exit code of mcdecoder

generator

mcdecoder.generator.generate(mcfile: str, type: str | None = None, template_directory: str | None = None, output_directory: str = '.') → int

Implementation the sub-command ‘generate’.

Generate MC decoder files from MC description file.

If output_directory is not specified, it is defaulted to the current directory. If template_directory is not specified, the default decoder template (c_decoder decoder) is used.

Parameters:

• mcfile – Path to an MC description file

• type – Code type to generate

• template_directory – Path to a directory including template files

• output_directory – Path to an output directory of generated codes

Returns:

Exit code of mcdecoder

exporter

mcdecoder.exporter.export(mcfile: str, output_file: str) → int

Implementation of the sub-command ‘export’.

Export an MC description as another format.

NOTE Currently, mcdecoder supports only CSV format.

Parameters:

• mcfile – Path to an MC description file

• output_file – Path to an file to be exported

Returns:

Exit code of mcdecoder

emulator

mcdecoder.emulator.emulate(mcfile: str, bit_pattern: str, base: Literal[2, 16] = 16, byteorder: Literal['big', 'little'] = 'big') → int

Implementation of the sub-command ‘emulate’.

Emulate a decoder and output the decoding result.

If base is not specified, base 16 is used by default. If byteorder is not specified, big endian is used by default.

Parameters:

• mcfile – Path to an MC description

• bit_pattern – Binary/hex string to be decoded

• base – Base of integer that specifies the expression of bit_pattern

• byteorder – Byte order of bit_pattern

Returns:

Exit code of mcdecoder

checker

mcdecoder.checker.check(mcfile: str, bit_pattern: str, base: Literal[2, 16] = 16) → int

Implementation of the sub-command ‘check’.

Check the integrity of an MC description and output errors.

If base is not specified, base 16 is used by default.

NOTE Currently, mcdecoder does not support little endian bit pattern.

Parameters:

• mcfile – Path to an MC description file

• bit_pattern – Binary data to be input

• base – Base of integer that specifies the expression of binary data

Returns:

Exit code of mcdecoder

core

class mcdecoder.core.AndIdCondition(conditions: List[InstructionDecoderCondition])

Bases: InstructionDecoderCondition

‘and’ condition subclass for InstructionDecoderCondition to combine conditions with AND operator

conditions: List[InstructionDecoderCondition]

Child InstructionDecoderConditions combined with logical AND operation

property type: str

Type of InstructionDecoderCondition. It’s always ‘and’ for AndIdCondition

class mcdecoder.core.BitRangeDescription(start: int, end: int)

Bases: object

Parsed bit range

end: int

LSB of a bit range

start: int

MSB of a bit range

class mcdecoder.core.DecodeContext(mcdecoder: McDecoder, code16x1: int, code16x2: int, code32x1: int)

Bases: object

Context information while decoding. It is used for non-vectorized calculations.

code16x1: int

16-bit code(1 word of 16-bit)

code16x2: int

16-bit code(2 words of 16-bit)

code32x1: int

32-bit code(1 word of 32-bit)

mcdecoder: McDecoder

McDecoder used for decoding

class mcdecoder.core.DecodeContextVectorized(mcdecoder: McDecoder, code16x1_vec: ndarray, code16x2_vec: ndarray, code32x1_vec: ndarray)

Bases: object

Context information while decoding. It is used for vectorized calculations.

NOTE The length of code16x1_vec, code16x2_vec and code32x1_vec must be the same.

code16x1_vec: ndarray

N-vector of 16-bit codes(1 word of 16-bit)

code16x2_vec: ndarray

N-vector of 16-bit codes(2 words of 16-bit)

code32x1_vec: ndarray

N-vector of 32-bit codes(1 word of 32-bit)

mcdecoder: McDecoder

McDecoder used for decoding

class mcdecoder.core.EqualityIdCondition(subject: InstructionDecoderConditionObject, operator: str, object: InstructionDecoderConditionObject)

Bases: InstructionDecoderCondition

Equality condition subclass for InstructionDecoderCondition to test a field value’s equality with a value.

Supported operators are ==, !=, >, >=, < and <=.

object: InstructionDecoderConditionObject

Objective InstructionDecoderConditionObject to test with

operator: str

Operator to test

subject: InstructionDecoderConditionObject

Subjective InstructionDecoderConditionObject to be tested

property type: str

Type of InstructionDecoderCondition. It’s always ‘equality’ for EqualityIdCondition

class mcdecoder.core.EqualityInstructionConditionDescription(subject: InstructionConditionObjectDescription, operator: str, object: InstructionConditionObjectDescription)

Bases: InstructionConditionDescription

Parsed equality condition of an instruction such as ‘==’, ‘in’, etc.

object: InstructionConditionObjectDescription

Objective InstructionConditionObjectDescription to test with

operator: str

Operator to test

subject: InstructionConditionObjectDescription

Subjective InstructionConditionObjectDescription to be tested

class mcdecoder.core.FieldIdConditionObject(field: str, element_index: int | None)

Bases: InstructionDecoderConditionObject

Field object/subject subclass for InstructionDecoderConditionObject

element_index: int | None

Bit element index of a field to be tested

field: str

Name of a field to be tested

property type: str

Type of InstructionDecoderConditionObject. It’s always ‘field’ for FieldIdConditionObject

class mcdecoder.core.FieldInstructionConditionObjectDescription(field: str, element_index: int | None)

Bases: InstructionConditionObjectDescription

Field object/subject in an instruction condition

element_index: int | None

Bit element index of a field to be tested

field: str

Name of a field to be tested

class mcdecoder.core.FunctionIdConditionObject(function: str, argument: FieldIdConditionObject)

Bases: InstructionDecoderConditionObject

Uses the result of a function call as an object/subject. It is a subclass for InstructionDecoderConditionObject

argument: FieldIdConditionObject

Argument FieldIdConditionObject

function: str

Name of a function to be called

property type: str

Type of InstructionDecoderConditionObject. It’s always ‘function’ for FunctionIdConditionObject

class mcdecoder.core.FunctionInstructionConditionObjectDescription(function: str, argument: FieldInstructionConditionObjectDescription)

Bases: InstructionConditionObjectDescription

Uses the result of a function call as an object/subject in an instruction condition

argument: FieldInstructionConditionObjectDescription

Argument FieldInstructionConditionObjectDescription

function: str

Name of a function to be called

class mcdecoder.core.ImmediateIdConditionObject(value: int)

Bases: InstructionDecoderConditionObject

Immediate value object/subject subclass for InstructionDecoderConditionObject

property type: str

Type of InstructionDecoderConditionObject. It’s always ‘immediate’ for ImmediateIdConditionObject

value: int

Value to be tested

class mcdecoder.core.ImmediateInstructionConditionObjectDescription(value: int)

Bases: InstructionConditionObjectDescription

Immediate value object/subject in an instruction condition

value: int

Value to be tested

class mcdecoder.core.InIdCondition(subject: InstructionDecoderConditionObject, values: List[int])

Bases: InstructionDecoderCondition

‘in’ condition subclass for InstructionDecoderCondition to test an instruction field is in a value set

subject: InstructionDecoderConditionObject

Subjective InstructionDecoderConditionObject to be tested

property type: str

Type of InstructionDecoderCondition. It’s always ‘in’ for InIdCondition

values: List[int]

Value set a field must be in

class mcdecoder.core.InInstructionConditionDescription(subject: InstructionConditionObjectDescription, values: List[int])

Bases: InstructionConditionDescription

Parsed ‘in’ condition of an instruction

subject: InstructionConditionObjectDescription

Subjective InstructionConditionObjectDescription to be tested

values: List[int]

Values to test with

class mcdecoder.core.InRangeIdCondition(subject: InstructionDecoderConditionObject, value_start: int, value_end: int)

Bases: InstructionDecoderCondition

‘in_range’ condition subclass for InstructionDecoderCondition to test an instruction field is in a value range(inclusive)

subject: InstructionDecoderConditionObject

Subjective InstructionDecoderConditionObject to be tested

property type: str

Type of InstructionDecoderCondition. It’s always ‘in_range’ for InRangeIdCondition

value_end: int

End of a value range a field must be in

value_start: int

Start of a value range a field must be in

class mcdecoder.core.InRangeInstructionConditionDescription(subject: InstructionConditionObjectDescription, value_start: int, value_end: int)

Bases: InstructionConditionDescription

Parsed ‘in_range’ condition of an instruction

subject: InstructionConditionObjectDescription

Subjective InstructionConditionObjectDescription to be tested

value_end: int

End of a value range a field must be in

value_start: int

Start of a value range a field must be in

class mcdecoder.core.InstructionConditionDescription

Bases: object

Parsed condition of an instruction

class mcdecoder.core.InstructionConditionObjectDescription

Bases: object

Parsed object/subject in an instruction condition

class mcdecoder.core.InstructionDecodeResult(decoder: InstructionDecoder, fields: List[InstructionFieldDecodeResult])

Bases: object

Decoding result of an instruction

decoder: InstructionDecoder

Corresponding InstructionDecoder

property field_results: List[InstructionFieldDecodeResult]

Child InstructionFieldDecodeResults

Deprecated since version 0.1a6: This will be removed in 1.0. Use fields instead

fields: List[InstructionFieldDecodeResult]

Child InstructionFieldDecodeResults

class mcdecoder.core.InstructionDecoder(name: str, encoding_element_bit_length: int, length_of_encoding_elements: int, fixed_bit_mask: int, fixed_bits: int, type_bit_length: int, match_condition: InstructionDecoderCondition | None, unmatch_condition: InstructionDecoderCondition | None, fields: List[InstructionFieldDecoder], extras: Any | None, _encoding: str)

Bases: object

Decoder for an instruction

encoding_element_bit_length: int

Bit length of an encoding element

extras: Any | None

User-defined data for an instruction

property field_decoders: List[InstructionFieldDecoder]

Child InstructionFieldDecoders

Deprecated since version 0.1a6: This will be removed in 1.0. Use fields instead

fields: List[InstructionFieldDecoder]

Child InstructionFieldDecoders

fixed_bit_mask: int

Mask of fixed bit positions of an instruction

fixed_bits: int

Fixed bits of an instruction

property fixed_bits_mask: int

Mask of fixed bit positions of an instruction

Deprecated since version 0.1a6: This will be removed in 1.0. Use fixed_bit_mask instead

length_of_encoding_elements: int

Length of encoding elements

match_condition: InstructionDecoderCondition | None

Condition an instruction must satisfy

name: str

Name of an instruction

type_bit_length: int

Bit length of a data type used for an instruction

property type_bit_size: int

Bit length of a data type used for an instruction

Deprecated since version 0.1a6: This will be removed in 1.0. Use type_bit_length instead

unmatch_condition: InstructionDecoderCondition | None

Condition an instruction must not satisfy

class mcdecoder.core.InstructionDecoderCondition

Bases: object

Condition of instruction encoding when an instruction applys.

Each subclass must have a string attribute ‘type’ to express the type of a subclass.

abstract property type: str

Type of InstructionDecoderCondition

class mcdecoder.core.InstructionDecoderConditionObject

Bases: object

Object or subject of InstructionDecoderCondition.

Each subclass must have a string attribute ‘type’ to express the type of a subclass.

abstract property type: str

Type of InstructionDecoderConditionObject

class mcdecoder.core.InstructionDescription(*args, **kwargs)

Bases: dict

Describes an instruction

extras: Any | None

Container of user-defined data for an instruction

field_extras: Dict[str, Any] | None

Container of user-defined data for each field

format: str

Encoding format of an instruction

match_condition: str | None

Condition an instruction must satisfy

name: str

Name of an instruction

unmatch_condition: str | None

Condition an instruction must not satisfy

class mcdecoder.core.InstructionEncodingDescription(elements: List[InstructionEncodingElementDescription])

Bases: object

Parsed encoding format of an instruction

elements: List[InstructionEncodingElementDescription]

Child InstructionEncodingElementDescriptions

class mcdecoder.core.InstructionEncodingElementDescription(fields: List[InstructionFieldEncodingDescription])

Bases: object

Parsed encoding element of an instruction

fields: List[InstructionFieldEncodingDescription]

Child InstructionFieldEncodingDescriptions

class mcdecoder.core.InstructionFieldDecodeResult(decoder: InstructionFieldDecoder, value: int)

Bases: object

Decoding result of an instruction field

decoder: InstructionFieldDecoder

Corresponding InstructionFieldDecoder

value: int

Decoded value for a field

class mcdecoder.core.InstructionFieldDecoder(name: str, type_bit_length: int, subfields: List[InstructionSubfieldDecoder], extras: Any | None, _msb: int)

Bases: object

Decoder for an instruction field

extras: Any | None

User-defined data for a field

name: str

Name of a field

property subfield_decoders: List[InstructionSubfieldDecoder]

Child InstructionSubfieldDecoders

Deprecated since version 0.1a6: This will be removed in 1.0. Use subfields instead

subfields: List[InstructionSubfieldDecoder]

Child InstructionSubfieldDecoders

type_bit_length: int

Bit length of a data type used for a field

property type_bit_size: int

Bit length of a data type used for a field

Deprecated since version 0.1a6: This will be removed in 1.0. Use type_bit_length instead

class mcdecoder.core.InstructionFieldEncodingDescription(name: str | None, bits_format: str, bit_ranges: List[BitRangeDescription])

Bases: object

Parsed encoding format of an instruction field

bit_ranges: List[BitRangeDescription]

Bit ranges of a field that the encoding format corresponds to

bits_format: str

Encoding format of a field

name: str | None

Name of a field

class mcdecoder.core.InstructionSubfieldDecoder(index: int, mask: int, msb_in_instruction: int, lsb_in_instruction: int, lsb_in_field: int)

Bases: object

Decoder for an instruction subfield

property end_bit_in_field: int

LSB of a subfield in a field

Deprecated since version 0.1a6: This will be removed in 1.0. Use lsb_in_field instead

property end_bit_in_instruction: int

LSB of a subfield in an instruction

Deprecated since version 0.1a6: This will be removed in 1.0. Use lsb_in_instruction instead

index: int

Index number of a subfield in a field: 0th to (n-1)th

lsb_in_field: int

LSB of a subfield in a field

lsb_in_instruction: int

LSB of a subfield in an instruction

mask: int

Mask of a subfield in an instruction

msb_in_instruction: int

MSB of a subfield in an instruction

property start_bit_in_instruction: int

MSB of a subfield in an instruction

Deprecated since version 0.1a6: This will be removed in 1.0. Use msb_in_instruction instead

exception mcdecoder.core.LoadError(message)

Bases: Exception

Raised when an error occurs while loading

message: str

explanation of the error

class mcdecoder.core.LogicalInstructionConditionDescription(operator: Literal['and', 'or'], conditions: List[InstructionConditionDescription])

Bases: InstructionConditionDescription

Parsed logical condition of an instruction, ‘and’ or ‘or’

conditions: List[InstructionConditionDescription]

Conditions combined with an logical operator

operator: Literal['and', 'or']

Operator of a logical condition

class mcdecoder.core.MachineDecoder(byteorder: Literal['big', 'little'], extras: Any | None)

Bases: object

Decoder for a machine

byteorder: Literal['big', 'little']

Byte order of a machine

extras: Any | None

User-defined data for a machine

class mcdecoder.core.MachineDescription(*args, **kwargs)

Bases: dict

Describes a machine

byteorder: Literal['big', 'little']

Byte order of a machine

extras: Any | None

Container of user-defined data for a machine

class mcdecoder.core.McDecoder(namespace: str | None, namespace_prefix: str, machine: MachineDecoder, instructions: List[InstructionDecoder], decision_trees: List[McdDecisionTree], extras: Any | None)

Bases: object

Decoder itself. The root model element of MC decoder model

decision_trees: List[McdDecisionTree]

Child McdDecisionTrees

extras: Any | None

User-defined data not related to a machine, an instruction and a field

property instruction_decoders: List[InstructionDecoder]

Child InstructionDecoders

Deprecated since version 0.1a6: This will be removed in 1.0. Use instructions instead

instructions: List[InstructionDecoder]

Child InstructionDecoders

machine: MachineDecoder

Child MachineDecoder

property machine_decoder: MachineDecoder

Child MachineDecoder

Deprecated since version 0.1a6: This will be removed in 1.0. Use machine instead

namespace: str | None

Namespace of generated codes

namespace_prefix: str

Namespace prefix of generated codes

class mcdecoder.core.McDecoderDescription(*args, **kwargs)

Bases: dict

Decoder information that isn’t related to a machine, an instruction and a field

namespace: str | None

Namespace for the symbols of a generated decoder

process_instruction_hook: str | None

Hook function to process model for an instruction decoder

class mcdecoder.core.McDescription(*args, **kwargs)

Bases: dict

Describes a machine code specification. The root element of MC description model

decoder: McDecoderDescription | None

Child McDecoderDescription

extras: Any | None

User-defined data not related to a machine, an instruction and a field

instructions: List[InstructionDescription]

Child InstructionDescriptions

machine: MachineDescription

Child MachineDescription

class mcdecoder.core.McdDecisionNode(index: int, mask: int, fixed_bit_nodes: Dict[int, McdDecisionNode], arbitrary_bit_node: McdDecisionNode | None, instructions: List[InstructionDecoder])

Bases: object

Node of a McdDecisionTree.

It has two types of child nodes:

• Fixed bit node: A node related to fixed bits. It is decided by a threshold value.

• Arbitrary bit node: A node related to arbitrary bits. It isn’t decided by a threshold value and pass through to the node.

property all_nodes: Iterable[McdDecisionNode]

This node and its descendants.

The nodes are ordered in the way of depth-first search.

arbitrary_bit_node: McdDecisionNode | None

Arbitrary bit McdDecisionNode

fixed_bit_nodes: Dict[int, McdDecisionNode]

Dictionary of a threshold value and its fixed bit McdDecisionNode

index: int

Index number of a node in a tree

instructions: List[InstructionDecoder]

Instructions decided by a node

mask: int

Mask of threshold bit positions

class mcdecoder.core.McdDecisionTree(encoding_element_bit_length: int, length_of_encoding_elements: int, root_node: McdDecisionNode)

Bases: object

Decision tree to find a matched instruction for a code

encoding_element_bit_length: int

Bit length of an encoding element

length_of_encoding_elements: int

Length of encoding elements

root_node: McdDecisionNode

Root node of a decision tree

class mcdecoder.core.OrIdCondition(conditions: List[InstructionDecoderCondition])

Bases: InstructionDecoderCondition

‘or’ condition subclass for InstructionDecoderCondition to combine conditions with OR operator

conditions: List[InstructionDecoderCondition]

Child InstructionDecoderConditions combined with logical OR operation

property type: str

Type of InstructionDecoderCondition. It’s always ‘or’ for OrIdCondition

mcdecoder.core.calc_instruction_bit_size(instruction_encoding: InstructionEncodingDescription) → int

Calculate the bit length of an instruction

Parameters:

instruction_encoding – Calculation target

Returns:

Bit length of an instruction

mcdecoder.core.create_mcdecoder_model(mcfile: str) → McDecoder

Create a model which contains information of MC decoder

Parameters:

mcfile – Path to an MC description file

Returns:

Created McDecoder

Raises:

LoadError – if there’s an invalid or inconsistent information

mcdecoder.core.decode_instruction(context: DecodeContext, instruction_decoder: InstructionDecoder) → InstructionDecodeResult

Decode an instruction

Parameters:

• context – Context information while decoding

• instruction_decoder – InstructionDecoder to decode with

Returns:

InstructionDecodeResult

mcdecoder.core.find_matched_instructions(context: DecodeContext) → List[InstructionDecoder]

Find instructions matched with a given code

Parameters:

context – Context information while decoding

Returns:

Matched InstructionDecoders

mcdecoder.core.find_matched_instructions_vectorized(context: DecodeContextVectorized) → ndarray

Find all the matched instructions to vectorized codes and return matched instructin matrix.

Parameters:

context – Context information while decoding

Returns:

N x M matrix of codes(N) and instructions(M). Each element holds the boolean result whether a code is matched for an instruction.

mcdecoder.core.load_mc_description(mcfile: str) → McDescription

Load an MC description file and validate against the schema

Parameters:

mcfile – Path to an MC description file

Returns:

Loaded McDescription

mcdecoder.core.parse_instruction_encoding(instruction_encoding: str) → InstructionEncodingDescription

Parse a string of the encoding format of an instruction

Parameters:

instruction_encoding – String of the encoding format of an instruction

Returns:

Parsed InstructionEncodingDescription

common

mcdecoder.common.bit_length_of_character(base: Literal[2, 16]) → int

Calculate a bit length that corresponds to one character

Parameters:

base – Base of integer

Returns:

Bit length for one character

mcdecoder.common.convert_to_big_endian(bits: str, base: Literal[2, 16], byteorder: Literal['big', 'little']) → str

Convert the byte order of bits to big endian.

If byteorder is big, no conversion will be taken place.

Parameters:

• bits – Binary/hex string to be converted

• base – Base of integer that specifies the expression of bits

• byteorder – Byte order of bits

Returns:

Converted binary/hex string that is big endian

mcdecoder.common.make_mask(bit_size: int) → int

Make a mask of bit_size bits

Parameters:

bit_size – Bit length of a mask

Returns:

Mask with bit_size bits

mcdecoder.common.make_parent_directories(file: str) → bool

Make parent directories of a file path

Parameters:

file – Path to a file

Returns:

True if succeeded in making parent directories. False otherwise.

mcdecoder.common.pad_trailing_zeros(bits: str, base: Literal[2, 16], expected_bit_size: int) → str

Pad trailing zeros to bits if the length of bits is less than expected_bit_size.

If expected_bit_size is not aligned to a byte alignment, some additional bits are added to a byte alignment.

Parameters:

• bits – Binary/hex string to be converted

• base – Base of integer that specifies the expression of bits

• expected_bit_size – Expected bit size bits should have

Returns:

Padded binary/hex string

mcdecoder.common.string_length_for_byte(base: Literal[2, 16]) → int

Calculate a string length that corresponds to one byte

Parameters:

base – Base of integer

Returns:

String length for one byte

mcdecoder.common.trim_whitespace(s: str) → str

Trim all the whitespaces from a string

Parameters:

s – String which trims whitespace from

Returns:

Whitespace-trimmed string

__version__

mcdecoder.__version__.__version__ = '0.1.1'

Current version of mcdecoder