Skip to content

Code development

Jump to bottom
Peter Wittich edited this page Feb 19, 2024 · 19 revisions

Downloads

The following assumes you are using a unix-based platform (Linux, MacOS, or WSL on Windows). That means you have access to make, git, etc, and is intended for development on a personal machine. The Cornell LNX machines (such as lnx4189) already have the appropriate tools installed.

Download the following:

If you want to use an IDE here are two possible options. You don't need an IDE and can of course just use emacs/vim/nano/ed and make from your shell, if you prefer to go old skool.

  • Eclipse CDT. This is the basic Eclipse IDE for C/C++ programming. To make things easier it is suggested to grab it from this specialized version for microcontrollers. Install the binary from 'downloads' on this page. This includes not just the Eclipse and CDT but also specializations for working with ARM microcontrollers.
  • An alternative is Visual Studio Code. This more modern IDE is good but takes some tweaking to get it to work with makefile projects. You need to generate a compile_commands.json file to make cross-references work properly, and also need to define custom rules to invoke make. Alternatively, an expansive config file (at the bottom of this page) can also help.

Source code management with git/GitHub

The code for the MCU must be developed on a branch that is not the master branch. The master branch is protected -- you can only submit pull requests to the master branch, not push directly to master.

The pull requests undergo a continuous integration build as described in the top level README file and then the PR must be reviewed by someone before being merged.

Best practice is to rebase the branch to the master before submitting a pull request.

Getting the code

The code can be pulled from the repo as follows.

git clone [email protected]:apollo-lhc/cm_mcu.git

At this point all the usual git commands are available. You'll want to make your own branch to develop there. Easiest thing is to make the branch on github (e.g. with the branch my-branch-name) and then switch to the branch in your local repo via

git checkout my-branch-name

on your local machine.

Building the code

You need to make sure the downloaded compiler is in your path. Then, in your shell, you need to set up one environment variable to point the build at your FreeRTOS code

export FREERTOS_ROOT=/base/of/install/FreeRTOS/Source

The last two parts of the above directory path are internal to the FreeRTOS source code tree.

To build the code you just type

make

Possible flags to consider are DEBUG=1 for a debug build and VERBOSE=1 to see how the compile commands are invoked. All other regular make options should work too. You need to specify REV1=1 if you are building for a REV1 CM.

make -j DEBUG=1 VERBOSE=1

for a debug build with full screen printout.

Setting up the Eclipse project

  1. After downloading the code, start eclipse and import the code via File>New>Makefile Project with existing code.
  2. Set the build to use the ARM compiler by opening the project preferences, navigate to C/C++ Build>Settings, and select "Gnu Tools for ARM Embedded". (If you don't have this option you need to install the ARM for embedded extension for Eclipse).
  3. in the project settings (Project>Properties) in C/C++ Build, unclick "use default make command" and change the make command to make DEBUG=1

The build should mostly work now, but some tweaks need to be added to get rid of the red squiggly lines in the IDE.

  1. In the project settings, click on C/C+++ General>Paths and symbols.
  2. Under 'includes' for C language the following include directories.
    • the project root
    • Two FREERTOS directories: ${FREERTOS_ROOT}/include and ${FREERTOS_ROOT}/portable/GCC/ARM_CM4F
  3. Under "#symbols" for C language add the following settings for convenience.
    • PART_TM4C1290NCPDT, not set this to any value
    • FIRMWARE_VERSION, set to \"dummy\"" (yes, include the slashes and two closing quotes, don't ask.)
    • REV1=1 or REV2=1 as relevant
    • DEBUG=1 so you can see exactly what's being compiled.
    • __fp16 = float to take care of an annoying problem where the IDE doesn't understand the 16 bit float storage type in ARM.
    • gcc needs to be defined for the logging function until gcc supports the FILE_NAME macro.

This should be all that's required; if it does not work check the path to the compiler in the "MCU" setting.

if eclipse forgets that your project is a c/c++ project

Follow the instructions from this SO post here to re-add the c/c++ nature:

  • Right-click on the project.
  • Select: New -> Other
  • Under C/C++, select "Convert to a C/C++ project"

creating a compile_commands.json

The python package compiledb can be used for this purpopse. Once installed (e.g. with pip) call it with

compiledb make -w VERBOSE=1

Both the -w flag and the verbose build are required.

Alternative VSCode setup

create this file in the base of the project:

% cat .vscode/c_cpp_properties.json
{
    "configurations": [
        {
            "name": "Mac",
            "includePath": [
                "${workspaceFolder}",
                "${workspaceFolder}/inc",
                "${workspaceFolder}/common",
                "${workspaceFolder}/driverlib",
                "${workspaceFolder}/projects/boot_loader",
                "${workspaceFolder}/projects/cm_mcu",
                "${FREERTOS_ROOT}/include",
                "${FREERTOS_ROOT}/portable/GCC/ARM_CM4F"
            ],
            "defines": [
                "REV2=1",
                "PART_TM4C1290NCPDT",
                "DEBUG=1",
                "FIRMWARE_VERSION=\"test\"",
                "TARGET_IS_TM4C129_RA1=1"
            ],
            "compilerPath": "/Applications/ARM/bin/arm-none-eabi-gcc",
            "cppStandard": "c++14",
            "cStandard":"c11",
            "intelliSenseMode": "gcc-arm"
        }
    ],
    "version": 4
}% 
%

Change the compilerPath to the location of arm-none-eabi-gcc that you downloaded at the start of this setup process.

Creating a release

There is a yml file / github action for creating a release and populating the release page with the appropriate binary. Do not use the release page; instead create a release on the git CLI and push it to the repo. Please only tag the master branch.

% git tag  v0.31.14
% git push --tags

The tag must be in a "semver" format(i.e., vxx.yy.zz) where x,y, and z are two digit decimal numbers. This should also populate the tag with the description based on the commit messages from the last release.

Subtree of sm_cm_config

The repository sm_cm_config is added as a git subtree. Some commands to use subtrees.

# update the local subtree for diffs, e.g.
git remote update
# push local changes to remote "main" branch
git subtree push --prefix sm_cm_config sm_cm_config main  
# pull changes from remote to local
git subtree pull --prefix sm_cm_config sm_cm_config
# diff of local repo compared to main branch of subtree. Locally our branch is "master"
git diff sm_cm_config/main master:sm_cm_config
Clone this wiki locally