Quickstart

RawProcessor

After completing the Installing of Styx as a dependency of your crate, the simplest quickstart in Rust is probably the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
use styx_emulator::core::executor::DefaultExecutor;
use styx_emulator::cpu::arch::superh::SuperHVariants;
use styx_emulator::plugins::{debug_tools::*, tracing_plugins::ProcessorTracingPlugin};
use styx_emulator::prelude::*;
use styx_emulator::processors::RawProcessor;
use tracing::info;

/// path to yaml description, see [`ParameterizedLoader`] for more
const LOAD_YAML: &str = "load.yaml";

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut proc = ProcessorBuilder::default()
        .with_builder(RawProcessor::new(
            Arch::SuperH,
            SuperHVariants::SH2A,
            ArchEndian::BigEndian,
        ))
        .with_loader(ParameterizedLoader::default())
        .with_executor(DefaultExecutor)
        .add_plugin(ProcessorTracingPlugin)
        .add_plugin(UnmappedMemoryFaultPlugin::new(true))
        .add_plugin(ProtectedMemoryFaultPlugin::new(true))
        .with_target_program(LOAD_YAML)
        .build()?;

    info!("Starting emulator");

    proc.run(Forever)?;

    Ok(())
}

Note that line 20,21,22 are optional plugins, where the ProcessorTracingPlugin provides easy avenues to get output from processors, and the *MemoryFaultPlugins provide an easy ability to stop when a memory releated error occurs in the TargetProgram.

The parameterized loader is a convenient way to layer input data into Styx, and provides an approachable way to use all of the other loaders eg. ELF, binary blob, empty memory, proprietary BFIN loaders etc.

Note that this example is not using a real processor, just a RawProcessor. This means it cannot use any Peripheral’s or EventController’s, and is effectively a more flexible version of Unicorn.

Full Processor

Using a pre-built processor is also easy, you can get away with even less code in many cases:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
use styx_emulator::core::processor::executor::Executor;
use styx_emulator::prelude::*;
use styx_emulator::processors::arm::kinetis21::*;
use tracing::info;

/// path to yaml description, see [`ParameterizedLoader`] for more
const LOAD_YAML: &str = "load.yaml";

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let proc = ProcessorBuilder::default()
        .with_backend(Backend::Pcode)
        .with_loader(ParameterizedLoader::default())
        .with_executor(Executor::default())
        .with_plugin(ProcessorTracingPlugin)
        .with_target_program(LOAD_YAML)
        .build::<Kinetis21Builder>()?;

    info!("Starting emulator");

    proc.start()?;

    Ok(())
}

Python Processor

And a similar use via the python API:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
builder = ProcessorBuilder()
builder.target_program = str(target_program_path())
builder.ipc_port = 16001
builder.loader = RawLoader()
builder.executor = DefaultExecutor()
builder.add_plugin(ProcessorTracingPlugin())
proc = builder.build(Target.Stm32f107)

proc.add_hook(CodeHook(0x690C, 0x690D, log_signal))

proc.start()