<commit_before>Tutorial: Driver Cosimulation
=============================

Cocotb was designed to provide a common platform for hardware and software
developers to interact.  By integrating systems early, ideally at the
block level, it's possible to find bugs earlier in the design process.

For any given component that has a software interface there is typically a
software abstraction layer or driver which communicates with the hardware. In
this tutorial we will call unmodified production software from our testbench
and re-use the code written to configure the entity.



Difficulties with Driver Co-simulation
--------------------------------------

Co-simulating *un-modified* production software against a block-level
testbench is not trivial - there are a couple of significant obstacles to
overcome:


Calling the HAL from a test
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Typically the software component (often referred to as a Hardware Abstraction
Layer or HAL) is written in C.  We need to call this software from our test<commit_msg>Issue #125: Add instruction on running the example!<commit_after>Tutorial: Driver Cosimulation
=============================

Cocotb was designed to provide a common platform for hardware and software
developers to interact.  By integrating systems early, ideally at the
block level, it's possible to find bugs earlier in the design process.

For any given component that has a software interface there is typically a
software abstraction layer or driver which communicates with the hardware. In
this tutorial we will call unmodified production software from our testbench
and re-use the code written to configure the entity.

For the impatient this tutorial is provided as an example with Cocotb. You can
run this example from a fresh checkout::

    cd examples/endian_swapper/tests
    make MODULE=test_endian_swapper_hal

.. note:: `SWIG`_ is required to compile the example




Difficulties with Driver Co-simulation
--------------------------------------

Co-simulating *un-modified* production software against a block-level
testbench is not trivial - there are a couple of significant obstacles to
overcome:


Calling the HAL from a test
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Typically the software component (often referred to as a Hardware Abstraction
Layer or HAL) is written in C.  We need to call this software from our test
{'fraction_non_alphanumeric': 0.10532994923857868, 'fraction_numerical': 0.0012690355329949238, 'mean_word_length': 4.130151843817788, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5513933', 'n_tokens_mistral': 565, 'n_tokens_neox': 527, 'n_words': 315}