.. include:: ./../../macros.txt .. include:: ./../../units.txt .. _HALCOGEN_TOOL_DOCUMENTATION: ########################### HALCoGen tool documentation ########################### .. note:: A documentation of the tool |halcogen| can be found in this section, the waf-tool wrapper for this project in :ref:`WAF_TOOL_HALCOGEN`, information on configuring |halcogen| in the context of the toolchain of this project in :ref:`HAL_CONFIGURATION` and an example on how to use a pre-generated HAL instead of generating it in the compilation step in :ref:`HOW_TO_USE_GENERATED_SOURCES_FROM_HALCOGEN`. This part of the manual summarizes the usage of |halcogen| and references important documents by TI. Release notes ============= When using |halcogen| it is mandatory to be aware of the official `release notes SPNA203 `_. Special care **SHALL** be taken when reading the section "Known issues and limitations". It has to be screened for issues affecting the particular implementation of the BMS. Moreover, the most recent revision of the `Hercules Safety MCU Resource Guide `_ **SHALL** be read carefully. Additional known issues ======================= In addition to the known issues described in the release notes we have encountered additional issues. This section captures the issue, together with a reference to correspondence with TI (not necessarily by us) and a description of work-around measures. This section refers to |halcogen| in version ``04.07.01``. Incompatibility of enum-definitions with newer compilers in strict ANSI mode ---------------------------------------------------------------------------- The ARM CGT compilers since version ``20.2.2.LTS`` (shipped with CCS ``10.2.0.00009``) contain a bugfix for the underlying data type of enums described in `EXT_EP-10334 `_. The code that is generated by |halcogen| heavily relies on this behavior when implementing enums. This issue affects compilation of the HAL in strict ANSI mode. In this mode, the underlying data type of enums is *signed char* (as expected by the C standard). These enums, however, are used for comparison with *unsigned integers* in the generated HAL. Details can be found in a `TI forum post `_. The correct fix for this issue would be to extend all relevant generated enums in the HAL with an entry ``dummy=UCHAR_MAX`` as last entry. This tells the compiler to use *unsigned char* as underlying data type for these enums. Since we cannot modify the HAL without loosing the ability to generate it and TI is not planning to provide a fix in |halcogen| as stated in the linked forum post, a second fix as described in the following paragraph is possible. The compilation failure in this case comes from a diagnostic error ``2142`` that is raised to an error in our toolchain. Under the assumption that the generated HAL is correct, these warnings can be disabled as described by TI by removing ``--emit_warnings_as_errors`` and ``--diag_error=2142`` for the compilation of the HAL. This issue is fixed with the latter option in |foxbms| versions ``v1.1.0`` and upwards. Message definitions in CAN4 --------------------------- |halcogen| has a bug that prevents it from generating a complete set of message definitions for the message boxes 33 to 64. This issue is described in a `TI forum post about HALCoGen v04.05.02 `_ and an additional `TI forum post about HALCoGen v04.07.01 `_. TI plans to update the release note of |halcogen| in the third quarter of 2021 with this information. For the workaround, the configuration files of |halcogen| have to be modified. To be precise, the file ``C:\ti\Hercules\HALCoGen\v04.07.01\drivers\TMS570LC4357ZWT\CAN4v000.xml`` (if |halcogen| is installed into the standard directory) has to be opened and the limit of the for-loop in line ``144`` has to be changed from ``32`` to ``64``. The result should look like the content of :numref:`modify-can4-xml`. .. code-block:: javascript :linenos: :lineno-start: 143 :emphasize-lines: 2 :caption: Modified line 144 in ``CAN4v000.xml`` :name: modify-can4-xml var i=0 for(i=1;i <= 64;i++) {