regmock-rs

A small library for mocking registers of embedded targets on host machines in Rust 🦀. It allows you to do a wide range of tests for embedded code on your host machine- mocking, faking or modelling the hardwares behavior.

⚠️ WARNING ⚠️ This crate is WIP and all APIs are subject to change.

Made for PACs generated with svd2pac.

Features ⚙️

As of now regmock-rs provides the following features:

• 📼 recording of register accesses (type, register, values before and after the access)
• 🤡 mocking of registers on host machines
• 🔁 register arbitrary callbacks for register accesses
• 🤫 non-recorded register access

How it works

regmock-rs provides the read_fn/write_fn (and ldmst_fn) functions that can be registered with PACs generated by svd2pac to trace register accesses.

When generating PACs using svd2pac and --features=tracing, the generated PAC provides interfaces to register functions that get called on register access operations (i.e. read/write and ldmst for the Aurix platform). This gives developers the ability to attach arbitrary behavior to the register accesses that get performed through the PAC, either by implementing these functions themselves or by using a library that provide an implementation of these functions.

regmock-rs is such a library. The provided read/write/ldmst functions together provide a more advanced implementation of functions that can be registered with svd2pac PACs. The Regmock struct provides a way of mocking registers of embedded devices on non-embedded host computers. This enables the execution unit tests of embedded code on developer machines as well as CI pipelines.

Event Logging 📜

This allows regmock-rs to record:

• the order of register accesses
• the access type (normally read/write - but special accesses such as LDMST on Aurix chips can easily be supported using feature flags)
• on which register these accesses happen

In addition to the plain logging of register accesses, regmock-rs also allows to fully mock the actual registers that get accessed. With this, the log is able to record the value before and after the register access.

Non-Recorded Register Access

The silent<T>(f: impl FnOnce()->T)->T can be used to turn off logging and execution of possible callbacks during the execution of the passed function.

    unsafe {
        let _ =  regmock_rs::silent(|| { pac::REGISTER.bitfield().read() });
        let _ = unsafe { pac::REGISTER.bitfield().read() };
        let logs = regmock_rs::get_logs();
        assert_eq!(logs.len(), 1);
    }

Depending on regmock-rs

To integrate regmock-rs into your build you need a PAC crate and regmock-rs. You want to enable the tracing feature for test builds and keep it disabled for embedded builds.

[dependencies]
# you can for sure depend on released crates, but often you'll encounter "just a repo"
# here we enable all peripherals to be available
my-cpus-pac = { git = "<clone url>", rev = "<tag/revision to use>", features = ["all"] }

[dev-dependencies]
regmock-rs = { git = "https://github.com/Infineon/regmock-rs.git", rev = "<tag/revision to use>" }

[dev-dependencies]
# overwrite PAC cate features for test, we sadly need to restate url & revision
git = "<clone url from above>"
rev = "<rev from above>"
features = ["all", "tracing"] # tracing is not part of all

Assertions

As of now there are no assertions built into this library. This means developers are free to choose whatever assertion library they please. See the test-project test cases for an example how to write test and perform assertions.

Documentation

For an up-to-date documentation of the crate, its usage and different components please refer to the cargo generated documentation by running

cargo doc --open

A range of example with different complexity can be found in the examples.