End of Test (EOT) ================= Generates EOT code for ending the test. Writes to ``tohost`` to indicate a pass or fail. ``tohost`` ----------- The simulators Spike and Whisper use ``tohost`` to indicate the end of the test, defined in the ``io_htif`` sections. Writing to ``tohost`` with ``lsb=1`` will end the test. If ``[msb:lsb+1]`` is non zero and ``lsb=1`` the test is marked as a fail. If ``[msb:lsb+1]`` is zero and ``lsb=1`` (value of ``0x1``) the test is marked as a pass. You can find more information about ``tohost`` in this `Spike discussion `_. Riescue uses ``tohost`` in the ``io_htif`` sections to indicate the end of the test. Other platforms may have different ways to indicate the end of the test. .. important:: This code was written with the assumption that only one hart will execute the end of test code and the test will always write to ``tohost``. Writing to ``tohost`` is a requirement to get ISS to end. Tests currently always write to ``tohost`` when using Riescue. .. note:: There's currently no mechanism to stop other tests from executing. Riescue relies on an EOT write to end the test for all harts. If this is a problem, file an issue on the `Riescue GitHub repository `_ and request a feature. API --------- The EOT code is generated by the :py:class:`riescue.dtest_framework.runtime.eot.Eot` class. It generates a few public routines that can be called by other code. .. code-block:: eot__end_test: eot__passed: eot__failed: eot__halt: ``eot__end_test`` ___________________ This code is called at the end of the test for failures, passes, and halts. It should be ran in the handler privilege mode and returns to ``M`` mode before ending the test. Passing a value of ``1`` into ``gp`` will mark the test as passed, otherwise any other non-zero value will be marked as a fail ``eot__end_test`` is called by the all routines (except for the loader panic): .. mermaid:: graph LR eot[eot__end_test] scheduler__finished -->|gp=1| eot os_end_test -->|gp=1| eot scheduler__panic -->|gp=0| eot trap__panic -->|gp=0| eot end_test --> os_end_test syscall_f0000003 --> os_end_test failed --> test_failed syscall_f0000002 --> test_failed test_failed -->|gp=0| eot classDef mMode fill:#5164e0,stroke:#5164e0,stroke-width:3px,color:#fff classDef handlerMode fill:#fa512e,stroke:#fa512e,stroke-width:3px,color:#000 classDef handlerBlock fill:#FEC3A4,stroke:#FEC3A4,stroke-width:3px,color:#0 classDef testMode fill:#7584e6,stroke:#7584e6,stroke-width:3px,color:#0 classDef testBlock fill:#C0C0E0,stroke:#C0C0E0,stroke-width:3px,color:#0 class eot mMode class scheduler__finished,trap__panic,test_failed,os_end_test,scheduler__panic handlerMode class syscall_f0000002,syscall_f0000003,failed,end_test handlerBlock The exception is a loader panic before the runtime is fully initilaized. Failures in the loader directly call ``eot__failed``. ``eot__passed`` / ``eot__failed`` ___________________________________ This code is called by ``eot__end_test`` depending on the value of ``gp``. If ``gp`` is 1, the test is marked as passed, any other value is marked as failed. .. mermaid:: graph LR loader__panic --> eot__failed eot[eot__end_test] eot -->|gp == 1| eot__passed eot -->|gp != 1| eot__failed classDef mMode fill:#5164e0,stroke:#5164e0,stroke-width:3px,color:#fff classDef handlerMode fill:#fa512e,stroke:#fa512e,stroke-width:3px,color:#000 classDef handlerBlock fill:#FEC3A4,stroke:#FEC3A4,stroke-width:3px,color:#0 classDef testMode fill:#7584e6,stroke:#7584e6,stroke-width:3px,color:#0 classDef testBlock fill:#C0C0E0,stroke:#C0C0E0,stroke-width:3px,color:#0 class eot,loader__panic,eot__passed,eot__failed mMode MP EOT ___________ MP code selects a single hart to write to ``tohost`` and then halts. The first hart to enter ``eot__end_test`` will be the one to write to ``tohost``. All other harts will wait in the ``eot__halt`` routine until the first hart writes to ``tohost``. Overriding EOT Code -------------------- EOT hooks are available for inserting additional code at different points in the EOT code. The availabe hooks are: - ``PRE_PASS``: Called before the test is marked as passed. - ``POST_PASS``: Called after the test is marked as passed. - ``PRE_FAIL``: Called before the test is marked as failed. - ``POST_FAIL``: Called after the test is marked as failed. - ``PRE_HALT``: Called before the test is halted. See the :doc:`../python_api/FeatMgr` class for more information on how to use hooks. Configuration ------------- The ``tohost`` write value can be overridden by setting the ``eot_pass_value`` and ``eot_fail_value`` configuration options. - ``eot_pass_value``: Value to write to tohost on test pass - ``eot_fail_value``: Value to write to tohost on test fail The ``tohost`` address can be configured by changing the ``htif`` section in the CPU configuration file. If no ``htif`` section is provided, it will insert the address at the end of the runtime code (after the ``.section .text`` section). Examples --------- For more information on how to modify the end of test code, see the :doc:`../../user_guides/modifying_end_of_test` user guide.