litex

LiteX Sim is a contribution from LambdaConcept and provides
a modular SoC simulation environment.

The contribution from LambdaConcept is a major rework/refactoring
of the original simulation environnment PoC that was hacky and not
modular.

LiteX Sim is Copyright (c) 2017 Pierre-Olivier Vauboin <po@lambdaconcept.com>
                           2017 Ramtin Amin <ramtin@lambdaconcept.com>

Original PoC is Copyright (c) 2015-2016 Florent Kermarrec <florent@enjoy-digital.fr>


Verilator user hooks
--------------------

LiteX's Verilator backend can link user C++ sources into the simulation
executable and call optional user hooks at initialization and around each
Verilator eval. This is useful for debug/instrumentation code that needs direct
access to Verilator internals, for example forcing a signal marked with
`/*verilator forceable*/`.

With litex_sim:

```
litex_sim --verilator-extra-source force_hooks.cpp
```

From a custom simulation target:

```
builder.build(
    sim_config               = sim_config,
    verilator_extra_sources  = ["force_hooks.cpp"],
)
```

Example `force_hooks.cpp`:

```
#include <stdint.h>

#include "Vsim.h"
#include "Vsim___024root.h"

extern "C" void litex_sim_user_init(void *vsim)
{
    Vsim *sim = static_cast<Vsim *>(vsim);
    (void)sim;
}

extern "C" void litex_sim_user_pre_eval(void *vsim, uint64_t time_ps)
{
    Vsim *sim = static_cast<Vsim *>(vsim);
    (void)time_ps;

    // Replace this with the generated name from obj_dir/Vsim___024root.h
    // for the signal declared with /*verilator forceable*/.
    sim->rootp->sim__DOT__my_signal__VforceVal = 1;
    sim->rootp->sim__DOT__my_signal__VforceEn  = 1;
}

extern "C" void litex_sim_user_post_eval(void *vsim, uint64_t time_ps)
{
    Vsim *sim = static_cast<Vsim *>(vsim);
    (void)sim;
    (void)time_ps;
}
```

These hooks are Verilator-specific debug hooks. The `rootp` hierarchy and
`__Vforce*` names are generated by Verilator and can change when the generated
design hierarchy changes.