Skip to content

Creating a new build config

Jump to bottom
Richard Arthurs edited this page Oct 5, 2018 · 7 revisions

Build configurations

  1. Create platform and build directories

  2. Make a new HALCoGEN project, place it in the new platform directory. Uncheck Create directory for project to do this.

    Simply copy the existing halcogen.dil and halogen.hcg files as a starting point if your new build config is for a chip with an existing build config (such as for a new board revision).

  3. In CCS choose build configurations > Manage

    Create a new build config, probably based off an existing configuration that's reasonably close to the new one. Click OK and switch to it.

  4. Now it's time to set up the build configuration in the project properties.

    • Select the right chip and a default debug connection in the CCS General section
    • Adjust CCS Build/ARM Compiler/Include Options settings to include the appropriate platform directory for the build config
    • In CCS Build/ARM Compiler/Predefined Symbols, remove the old symbol from the build config you based the new one on. Add a new one that's appropriately named: PLATFORM_BOARD_VERSION. This will be used in the hardwaredefs file.

  5. If you have a HALCoGEN file that's reasonably close to what the new board needs, go ahead and make the manual edits and regenerate code. If you're bringing up a new chip, here's the procedure for a clean sheet HALCoGEN file:

    • Screenshot any useful sections from an old HALCoGEN file
    • You will want to concentrate on the following sections, they have lots of details:
      • Driver enable
      • Interrupts (note vPortSWI attached to SVC, which is required by FreeRTOS)
      • VIM General and channels (there are some handlers to fill in, and enable appropriate interrupts)
      • Data formats and transfer groups for SPI and MIBSPI peripherals
      • Pulls/output enables on GIOs (and peripheral pins in GIO mode)

  6. Copy all of the RTOS files from a working config into the source directory of your new platform. Do the same for the includes.

  7. Add a definition for vApplicationStackOverflowHook() in platform/sys_main.c. Copy useful definitions from a working sys_main.c into your fresh one.

  8. Modify sys_link.cmd. This is the linker command file, and is used to reserve regions in the memory map for various purposes. By default, there is the interrupt vector table (which tells the CPU where the ISRs are located), but the RTOS should be allocated some protected space.

Below is a modified memory map section. The KERNEL and KRAM sections have been inserted. The lengths (for KERNEL and KRAM) below are likely fine for all implementations (they've been used by us for years), but take care to adjust the origins, which will change depending on how much RAM and flash your particular chip has.

#define IGNORE_HALCOGEN_MEMORY_MAP
MEMORY
{
    VECTORS (X)  : origin=0x00000000 length=0x00000020
    KERNEL  (RX) : origin=0x00000020 length=0x00008000
    FLASH0  (RX) : origin=0x00008020 length=0x0013FFE0
    STACKS  (RW) : origin=0x08000000 length=0x00001500
    KRAM    (RW) : origin=0x08001500 length=0x00000800
    RAM     (RW) : origin=(0x08001500+0x00000800) length=(0x0002EB00-0x00000800)
}

#ifndef IGNORE_HALCOGEN_MEMORY_MAP
// Default memory map code is here
#endif

Similarly, the SECTIONS part of the linker command file needs to be modified. You can probably just copy and paste this one in.

#define IGNORE_HALCOGEN_SECTIONS_CONFIG

SECTIONS
{
    .intvecs : {} > VECTORS
    /* FreeRTOS Kernel in protected region of Flash */
    .kernelTEXT   : {} > KERNEL
    .cinit        : {} > KERNEL
    .pinit        : {} > KERNEL
    /* Rest of code to user mode flash region */
    .text         : {} > FLASH0
    .const        : {} > FLASH0
    /* FreeRTOS Kernel data in protected region of RAM */
    .kernelBSS    : {} > KRAM
    .kernelHEAP   : {} > RAM
    .bss          : {} > RAM
    .data         : {} > RAM
    .sysmem  	  : {} > RAM // RA: added to get rid of warning. If we run into issues, investigate what this does
}

#ifndef IGNORE_HALCOGEN_SECTIONS_CONFIG
// Default sections code is here
#endif

Note: You will need to place these mods in the user code sections of the linker command file, or they'll be wiped out next time HALCoGEN is used to regenerate code. Use creative #ifdef and #ifndef-ing to disable the HALCoGEN-generated sections to ensure they are replaced with your own. Stubs are shown in the code listings above, but without the user sections split up.

  1. Add a platform_x_hardwaredefs.h file for the new build configuration. Base it off an existing one, and be sure to add a section to enable it in the main obc_hardwaredefs.h file.

  2. Attempt to build. You may need to exclude some directories (such as old platform directories) from the build (right click, "Exclude from build"). If there are any old platforms still enabled, exclude them.

Bonus Tips

  • CCS can get weird when adding new files. It's a good idea to quit CCS and open it back up after you generate code from HALCoGEN the first time, making sure that old platforms are excluded from build. There have been issues where CCS wouldn't pick up the new files until it was restarted.

    You can check if it's working by finding a variable/function that is definitely present in the new and old HAL files, such as gioSetBit(). In the new HAL, find it, right click > "open declaration". When the header/c file opens, hover over its tab and the file path will appear. It's good if the correct platform directory is in the path, but if it's wrong, restart CCS and then double check it.

Other documentation

Clone this wiki locally