Crate regmock_rs

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.

Modules

• matchers
  Collection of matchers that can be run against iterators that yield RegisterAccess.
• utils
  Collection of data structures and functions that power regmock_rs.

Macros

• given
  Macro for matching LogMatcher against iterators of RegisterAccess in a “more prose like” manner.
• require_reg
  Macro for constructing register specific LogMatcher structs in a “more prose like” manner.
• require_seq
  Macro for constructing a LogSequenceMatcher struct in a “more prose like” manner. Works together well with e.g. the crate::utils::access_gen::read_value and crate::utils::access_gen::write_value helpers (and cousins).

Enums

• MockError
  Errors generated when handling the thread_local locked Regmock object.

Functions

• callbacks
  Enable/disable the execution of callbacks in the thread_local MOCK object.
• init_regmock
  Initialize the thread_local regmock object.
• logging
  Enable/disable logging of register accesses in the thread_local MOCK object.
• logs
  Get the utils::RegmockLog form the thread_local MOCK object.
• read_fn
  Perform a read from the mocked registers. Register this function as the READ_FN in the pacgen PAC.
• silent
  Disable logging and execution of callbacks during the closure f.
• wait_until_polled
  Block until specific register is being polled or timeout occurs.
• with_mock
  Execute function against thread_local Regmock object.
• write_fn
  Perform a write from the mocked registers. Register this function as the WRITE_FN in the pacgen PAC.