.. 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 <https://www.ti.com/lit/ml/spna203/spna203.pdf>`_.
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 <https://software-dl.ti.com/hercules/hercules_docs/latest/hercules/>`_
**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 <https://sir.ext.ti.com/jira/browse/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 <https://e2e.ti.com/support/tools/ccs/f/code-composer-studio-forum/993701/codecomposer-ccs10-2-0-20-2-2lts-cannot-compile-halcogen-04-07-01-generated-sources-anymore>`_.
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 <https://e2e.ti.com/support/microcontrollers/other-microcontrollers-group/other/f/other-microcontrollers-forum/543081/halcogen-not-generating-code-for-can4-mailboxes-32>`_
and an additional
`TI forum post about HALCoGen v04.07.01 <https://e2e.ti.com/support/microcontrollers/other-microcontrollers-group/other/f/other-microcontrollers-forum/998737/halcogen-not-generating-code-for-can4-mailboxes-32-in-halcogen-04-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++)
{