Comparing ASF Projects for Atmel Boards and User Boards

Created on: 27 April 2016

Part 5 of the ASF ARM Tutorial

Comparison between an ASF project made for an Atmel evaluation board and an ASF project made for a user or custom board.

In this part of the Atmel Software Framework tutorial, we look at how the two different ASF project types are structured. It is shown which files need to be edited and where to add code and settings when starting a new ASF project.

By comparing the projects we will answer the following questions:

• What does the red dot or red square next to files in Atmel Studio Solution Explorer mean?
• What are the various folders and files in ASF projects for?
• Which files must be modified in a new ASF project?
• Into which ASF files must which code be placed?

Basic ASF Files and Project Structure

A top level view of the structure of three different ASF projects is shown in the image below. The image shows the project files and folders in Atmel Studio Solution Explorer for the three projects. On the left is the ASF project made for the Atmel SAM4N Xplained Pro board from part 2 of this tutorial series. In the middle is the custom or user board ASF project from part 3 of this tutorial series. On the right is an new empty ASF user board project without any code added.

At the top level, the projects are very similar. The Atmel board project and user board project are identical except for the small red squares on some of the file icons. The red square marks files that have been modified by the user. The same small dot or square is grey on files that have not been modified by the user. If any code is added to main.c in the empty ASF user board project, the square on the main.c file icon will change from grey to red.

The first two projects both have a conf_clock.h file, while the empty user board project does not. The reason for this is that the empty user board project has not had any ASF modules added. The conf_clock.h file is added to the project when the System Clock Control (service) is added to the project using the ASF Wizard.

If you have been following this tutorial series and creating the projects, you may remember that we never added the System Clock Control service ASF module to any of the projects. This module is a dependency of the IOPORT ASF module and the Delay routines ASF module, so it is automatically added to the project if either of these two modules is added.

ASF Project Structure Next Level

Expanding the common and sam folders of our three ASF projects shows more differences between the projects as shown in the below image.

The sam Folder

The folder structure separates microcontroller specific low-level code into the sam folder for Atmel SAM ARM microcontrollers.

sam\boards\

The Atmel board ASF project at the left of the image has a boards folder inside the sam folder which the user board ASF projects do not have. This sam\boards\ folder contains board specific initialization code and hardware definitions for the Atmel board chosen when creating the project.

sam\drivers\

The sam\drivers\ folder contains driver code for drivers that were added by the ASF Wizard. This folder is not present in the empty user board ASF project because no ASF modules were added to the project.

sam\utils\

The sam\utils\ folder contains various utility functions, files and definitions including microcontroller hardware register definitions, linker scripts, macros and files for building the project.

The common Folder

common\boards\

The common\boards\ folder contains a header file used to include the correct header file for the board or microcontroller used. In a user board project it also includes user board initialization code.

common\services\

The common\services\ folder contains ASF code for ASF service modules added by the ASF Wizard. Again this folder is not present in the empty user board ASF project because no ASF modules have been added to the project. Although only ASF service modules were added to the project in the previous parts of this tutorial, these services have driver dependencies. The needed driver(s) are added automatically by the ASF Wizard and the drivers folder created in the sam folder.

common\utils\

This folder contains Atmel part identification macros and interrupt controller utility functions.

ASF Project Structure Configuration and Settings Files

The next level of folders have been expanded for the Atmel board and user board ASF projects to show where the files used for board configuration and settings are found as shown below.

First observe that the Atmel board project does not have a user_board folder found in common\boards\user_board\ in the user board project. Similarly the user board project does not have a sam\boards\ folder containing a folder named after an Atmel evaluation board.

These two folders are equivalents for the two different ASF project types.

init.c

The init.c file contains the initialization code for the board in the board_init() function which is called at the beginning of main(). This init.c file is found in common\boards\user_board\ for a user board ASF project. The same file is found in \sam\boards\<board_name>\ in Atmel board ASF projects.

In Atmel board projects the code in board_init() initializes the hardware for the specific Atmel board chosen when creating the project. In a user board project, this code must be added by the user to initialize the specific hardware on the user board.

Hardware Definition Header File

In Atmel board projects, hardware is defined in the header file in \sam\boards\<board_name>\ which has the name <board_name>.h where board_name is the name of the Atmel evaluation board selected when the project was created. In a user board project this information must be added to user_board.h found in common\boards\user_board\.

Atmel board projects include the external resenator or crystal settings for the board in this file.

conf_board.h

The conf_board.h file found in config\ is used for board specific configuration definitions.

conf_clock.h

This file is only available after adding the System Clock Control service ASF module or by adding an ASF module that depends on the system clock control module.

The system clock source, prescaler and PLL settings are changed in this file.