5. HALCoGen tool documentation

Note

A documentation of the tool HALCoGen can be found in this section, the Waf tool wrapper for this project in HALCoGen, information on configuring HALCoGen in the context of the toolchain of this project in HALCoGen and an example on how to use a pre-generated HAL instead of generating it in the compilation step in How to Use Generated Sources from HALCoGen.

This part of the manual summarizes the usage of HALCoGen and references important documents by TI.

5.1. 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.

5.2. 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.

5.2.1. 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 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 2 versions v1.1.0 and upwards.

5.2.2. 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 Listing 5.7.

Listing 5.7 Modified line 144 in CAN4v000.xml

      var i=0
   for(i=1;i <= 64;i++)
         {

5.2.3. Mailbox 42 configuration in CAN1

HALCoGen has a bug that the initialization code of CAN1 mailbox 42 is not generated whatever is configured in HALCoGen. To use this mailbox, the user needs to initialize this mailbox manually (see TI forum post <https://e2e.ti.com/support/microcontrollers/arm-based-microcontrollers-group/arm-based-microcontrollers/f/arm-based-microcontrollers-forum/905953/ccs-tms570lc4357-halcogen-can-message-configuration-bug-can1-message-41-42—can2-message-41-42>).