FPrime reference application for support on ATMEL SAMV family μC’s

Minimal SAMV71 Base Application

This serves as a basic application which can provides application level control of low level peripherals.

Features

• Barebones initialization and startup code for the SAMV71.
• Integration with FreeRTOS for real-time task management.
• Example application showcasing basic peripheral usage.
• Support for open-source toolchains and workflows (e.g., GCC, OpenOCD, and GDB).
• No dependency on Microchip or IAR IDEs.

Getting Started

1. Clone the repository and its submodules:

   git clone https://github.com/your-username/FreeSAM.git
   cd FreeSAM
   git
       

2. Set up your environment: This leverages a docker file

   ./run.sh build docker
       

3. Build the project:

   ./run.sh build app
       

4. Upload and reset the board to run the application:

   ./run.sh exec base
       

Project Structure

• Base/ : Base application source files.
• deps/ : Dependencies provided as submodules
• build/ : Build output directory.
• run.sh : Primary entry point for this project
• README.org : This documentation.

Proving the concept

This section will document the process of bringing up the initial application which targets the SAM V71 Xplained Ultra Evaluation Kit.

The goal: Bring up an application running FPrime on the SAMV71 that demonstrates some basic threading capabilities, com port and peripheral support.

Getting started

Initially I installed the suggested Microchip IDE’s MPLAB, Harmony ect on wine. The next step was running a demo project I found two that specifically reference FreeRTOS support:

This com port event recorder came from the MPLab discover page/github page and seemed appropriate with the following summary:

The application functionality is divided into three threads:

Sensor Thread – Read and display temperature periodically via Two-Wire Interface High Speed (TWIHS) (I²C) EEPROM Thread – Write the temperature values to EEPROM and display it on the COM (serial) port terminal when requested by the user. User Input Thread – Read the character entered on the COM (serial) port terminal.

It did make reference of the use of some particular hardware extension that we don’t have access to but it is still probably worth going through since we can easily adapt that for the hardware on hand.

FreeRTOS also comes with multiple implementations of a simple blinky demo with IDE support for Atmel studio, Keil, and IAR.

After some time trying to configure the board using the previously installed microchip IDE’s I moved over to trying to use Keil’s editor. This also proved troublesome but moreso because it required either windows or wine support, the former would be antithetical to my disposition and the later seemed difficult.

While researching alternatives I came to a deeper understanding of Keil’s toolchain support and integration with Open-CMSIS-Pack. Simply put Open-CMSIS-Pack is an NXP driven project which provides a set of specs, standards and tools for configuring and maintaining the HAL for a wide variety of devices.

This seems like a good long term/production grade solution but for now I’ll try to get the existing IDEs to work since our config is not likely to vary much in the near term.

It is worth noting that Keil seems to leverage this as it’s software packs are referred to as “csolutions” which is an Open-CMSIS-Pack concept.

After some further research I found a repo describing how to run keil using wine in docker. It leverages a separate project which essentially sets up wine/winetricks with a set of sane configurations and manages the wine info really well.

This honestly makes the experience of using wine actually kind of good. I’ll have to re-install harmony, mplab, and keil and see if that solves my previous issues.

Running Blinky Demo with Keil’s µVision

After adding docker-wine as a submodule to this project I added some commands to the run.sh script to support interacting with the docker image. I may end up created a derived docker image later but for now this seems like a pragematic approach.

NOTE I did run into a few snags along the way, namely when trying to script the installation of keil based of of the [[https://github.com/au5ton/KeilForDocker/issues][KeilForDocker] I found that after switching from the default wineuser user to the hosts’s user with the --as-me flag I got this output:

ERROR: User's home '/home/reggiemarr' is currently owned by UNKNOWN:UNKNOWN
Use option --force-owner to enable user reggiemarr to take ownership

After applying that flag I found that µVision’s pack installer was unable to reach the internet. I was able to use a workaround; Namely downloading the pack files manually and then copying them to a mounted folder so that µVision would be able to import them however at that time I hadn’t known that the source of the error was the --force-owner flag so I spent some time debugging that. After removing the flag I was able to install the IDE using the following steps:

1. Pull in the docker image and download the latest evaluation version of MDK (v5.41 at time of writing). This can be done using the ./run.sh build keil-cfg command and the output should resemble something like this:

   fprime-atmel-sam-reference on  main [!⇡]
   ❯ ./run.sh build keil-cfg
   bash /home/reggiemarr/Projects/fprime-atmel-sam-reference/deps/docker-wine/docker-wine --as-me --volume=/home/reggiemarr/Projects/fprime-atmel-sam-reference:/home/reggiemarr/fprime-atmel-sam-reference   wget https://armkeil.blob.core.windows.net/eval/MDK541.EXE -P /home/reggiemarr/.wine/drive_c/users/reggiemarr/Downloads
   INFO: pulseaudio not installed so running without sound
   latest: Pulling from scottyhardy/docker-wine
   d9802f032d67: Pull complete
   db00ac4c6a92: Pull complete
   efbd506b993d: Pull complete
   8c509df97d50: Pull complete
   df1b72a1c833: Pull complete
   5172b388b864: Pull complete
   df0dc114d187: Pull complete
   7c006199b1e6: Pull complete
   e948126fe326: Pull complete
   d1326b32f3a0: Pull complete
   382718e0361d: Pull complete
   40f4aa84602e: Pull complete
   0cbeb812dc7c: Pull complete
   Digest: sha256:10ace77b523a8a7860bfc1a6d83d132101321f8a1648a58a5ee5c090ba5462f6
   Status: Downloaded newer image for scottyhardy/docker-wine:latest
   docker.io/scottyhardy/docker-wine:latest
   INFO: Creating Docker volume container 'winehome'...
   winehome
   --2024-12-07 13:50:32--  https://armkeil.blob.core.windows.net/eval/MDK541.EXE
   Resolving armkeil.blob.core.windows.net (armkeil.blob.core.windows.net)... 20.209.15.139
   Connecting to armkeil.blob.core.windows.net (armkeil.blob.core.windows.net)|20.209.15.139|:443... connected.
   HTTP request sent, awaiting response... 200 OK
   Length: 900844464 (859M) [application/x-msdownload]
   Saving to: ‘/home/reggiemarr/.wine/drive_c/users/reggiemarr/Downloads/MDK541.EXE’
   
   MDK541.EXE                    100%[==============================================>] 859.11M  3.03MB/s    in 5m 44s
   
   2024-12-07 13:56:17 (2.50 MB/s) - ‘/home/reggiemarr/.wine/drive_c/users/reggiemarr/Downloads/MDK541.EXE’ saved [900844464/900844464]
       

2. If successful the script will then try to execute MDK so that we can install the Keil developer pack (which includes our target IDE, µVision). This requires some manual intervention in the following:

   

   

   Note that we are using this for evaluation purposes only, not product ready development.

   

   This indicates successful completion of the install.

   NOTE that in the KeilForDocker project they noted that sometimes the last step would fail which would require the need to patch the TOOLS.ini file with something like this: RTEPATH="C:\Keil_v5\ARM\PACK" (the path may be different and should be indicated when initially installing MDK).

3. After successfully installing the IDE we now need to run it with this command: ./run.sh exec keil-cfg. A successful install should mean that µVision opens and from there we should be able to click on the “Pack installer icon” indicated in the bottom right corner here:

   Following that a dialog screen will appear, it will attempt to pull the latest CSMIS Packs, after which the screen should be similar to this (note the ONLINE indication at the bottom right corner):

   

1. We can now leverage µVision to run the FreeRTOS SamV71 demo with the following steps:

   Building and executing the demo application - Keil

   1. Open the project file FreeRTOS/Demo/CORTEX_M7_SAMV71_Xplained_IAR_Keil/RTOSDemo.uvprojx from within the Keil uVision IDE.
   2. Open main.c, and set mainCREATE_SIMPLE_BLINKY_DEMO_ONLY to generate either the simply blinky demo, or the full test and demo application, as required.
   3. Ensure the target hardware is connected to the host computer using a suitable debugger interface - the demo was developed and debugged using a J-Link.
   4. Select ‘Build Target’ from the IDE’s ‘Project’ menu, the RTOSDemo project should build without any errors or warnings.
   5. After the build completes, select ‘Start/Stop Debug Session’ from the IDE’s ‘Debug’ menu to program the Cortex-M7 microcontroller, start a debug session, and have the debugger break on entry into the main() function.

   Since the FreeRTOS repo is a submodule to this subproject and the run.sh script mounts the project onto the docker-wine container we can open it at Z:\home\reggiemarr\fprime-atmel-sam-reference\deps\FreeRTOS\FreeRTOS\Demo\CORTEX_M7_SAMV71_Xplained_IAR_Keil/RTOSDemo.uvoptx. Previous to this I had already installed the neccessary packs however you can do so now through the “Pack Installer” or the “Select Software Packs” icons.

   We can then apply the following diff:

   modified   FreeRTOS/Demo/CORTEX_M7_SAMV71_Xplained_IAR_Keil/main.c
   @@ -58,7 +58,7 @@
   
   /* Set mainCREATE_SIMPLE_BLINKY_DEMO_ONLY to one to run the simple blinky demo,
   * or 0 to run the more comprehensive test and demo application. */
   -#define mainCREATE_SIMPLE_BLINKY_DEMO_ONLY    0
   +#define mainCREATE_SIMPLE_BLINKY_DEMO_ONLY    1
   
   /*-----------------------------------------------------------*/
       

   And then, prior to building, we need to set the target compiler (the default seems to be to select one that µVision doesn’t include by default). So configure the target settings as such:

   

   Note we’re missing the device specific pack which can be downloaded with these

Microchip SAMV71 Series Device Support (4.10.230) wget https://packs.download.microchip.com/Microchip.SAMV71_DFP.4.10.230.atpack

Atmel SAMV71 Series Device Support (3.0.214) wget http://packs.download.atmel.com/Atmel.SAMV71_DFP.3.0.214.atpack

Setting up OpenOCD for SAMV71 Xplained Ultra

Prerequisites

• OpenOCD installed (Ubuntu/Debian: sudo apt-get install openocd)
• USB connection to board
• Board powered on

Device Detection

Verify the board is detected:

lsusb | grep Atmel

Should show: 03eb:2111 Atmel Corp. Xplained Pro board debugger and programmer

USB Permissions Setup

Required for Linux systems to allow OpenOCD to access the debugger

1. Create udev rules file:

sudo nano /etc/udev/rules.d/99-atmel-boards.rules

1. Add rules:

ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2111", MODE="0666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", MODE="0666"

1. Apply rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

1. Reconnect board

OpenOCD Configuration

1. Create config file (e.g., samv71.cfg):

source [find interface/cmsis-dap.cfg]
source [find board/atmel_samv71_xplained_ultra.cfg]

Testing Connection

Run OpenOCD with debug output:

openocd -d3 -f samv71.cfg

Notes

• EDBG (Embedded Debugger) is used via CMSIS-DAP interface
• Default configuration files are in /usr/share/openocd/scripts/
• Successful connection will show debugger initialization messages

FreeRTOS config

Feature	ACUBESAT (1st)	LLM Generated (2nd)	ASF (3rd)
Stack Size (minimal)	128	1000	256
Heap Size	40960	40980	47104
Task Name Length	16	25	8
Static Allocation	No	Yes	Not Defined
Timer Support	No	No	Yes
Queue Registry Size	0	5	0
Runtime Stats	No	Yes	Optional
Task Selection	Optimized	Optimized	Not Optimized
Interrupt Priority Setup	Basic	Basic	Detailed

ACUBESAT Configuration

The first configuration represents a minimalist approach focused on space applications. It prioritizes memory efficiency with smaller stack sizes and disabled features like timers and static allocation. The configuration maintains essential RTOS functionality while minimizing overhead, which is crucial for space-grade applications where resources are constrained and reliability is paramount.

LLM Generated Configuration

This configuration takes a more debug-oriented approach, with larger stack sizes and enabled runtime statistics. It includes additional features like queue registry and static allocation support. The configuration appears to be optimized for development and testing phases, where monitoring and debugging capabilities are prioritized over memory efficiency.

ASF Configuration

The Atmel Software Framework configuration provides the most structured and comprehensive setup. It includes detailed interrupt priority management, timer support, and extensive configuration options. The configuration is well-documented and IDE-friendly, making it suitable for complex commercial applications. It strikes a balance between feature availability and resource usage, while providing better development support through its organized structure and documentation.