Board Template Page

Kit Information

Kit Overview

Access the console

Demo

Demo archives

Flash the demo

HELP If you need to store the root filesystem on a SD Card, use information contained in StroreRootFSonSD. This is useful for Linux4SAM demos older than 5.6.

ALERT! use SAM-BA 3.2.y onwards. You can download it here: SAM-BA 3.x release page.

Run script to flash the demo

  • download the demo package for the board. They are marked as "Media type: Boot on SPI Flash + rootfs on eMMC" in the table above
  • extract the demo package
  • run your usual terminal emulator and enter the demo directory
  • make sure that the sam-ba application is in your Operating System path so that you can reach it from your demo package directory
  • for Microsoft Windows users: Launch the demo_linux_mediaType.bat file
  • for Linux users: Launch the demo_linux_mediaType.sh file
  • this script runs SAM-BA 3 and the associated QML sam-ba script (demo_linux_mediaType_usb.qml) with proper parameters
  • when you reach the end of the flashing process (this will take a few minutes), the following line is written:
    -I- === Done. ===
  • connect a serial link on DBGU and open the terminal emulator program as explained just above
  • power cycle the board
  • monitor the system while it's booting on the LCD screen or through the serial line

Play with the demo

Build From source code

Setup ARM Cross Compiler

  • Ubuntu:
    In Ubuntu, you can install the ARM Cross Compiler by doing:
    sudo apt-get install gcc-arm-linux-gnueabi
    export CROSS_COMPILE=arm-linux-gnueabi-
       

  • Others:
    For others, you can download the Linaro cross compiler and setup the environment by doing:
    wget -c https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/arm-linux-gnueabi/gcc-linaro-4.9.4-2017.01-x86_64_arm-linux-gnueabi.tar.xz
    tar xf gcc-linaro-4.9.4-2017.01-x86_64_arm-linux-gnueabi.tar.xz
    export CROSS_COMPILE=`pwd`/gcc-linaro-4.9.4-2017.01-x86_64_arm-linux-gnueabi/bin/arm-linux-gnueabi-
       

Build AT91Bootstrap from sources

This section describes how to get source code from the git repository, how to configure with the default configuration, how to customize AT91Bootstrap based on the default configuration and finally to build AT91Bootstrap to produce the binary. take the default configuration to download U-Boot from NandFlash for example.

Get AT91Bootstrap Source Code

You can easily download AT91Bootstrap source code on the at91bootstrap git repository.

To get the source code, you should clone the repository by doing:

$ git clone git://github.com/linux4sam/at91bootstrap.git
Cloning into 'at91bootstrap'...
remote: Reusing existing pack: 2476, done.
remote: Counting objects: 167, done.
remote: Compressing objects: 100% (167/167), done.
remote: Total 2643 (delta 135), reused 0 (delta 0)
Receiving objects: 100% (2643/2643), 2.06 MiB | 270 KiB/s, done.
Resolving deltas: 100% (1809/1809), done.
$ cd at91bootstrap/

Configure AT91Bootstrap

Customize AT91Bootstrap

If the default configuration doesn't meet your need, after configuring with the default configuration, you can customize it by doing:
$ make menuconfig
Now, in the menuconfig dialog, you can easily add or remove some features to/from AT91Bootstrap as the same way as kernel configuration.

Build AT91Bootstrap

Then you can build the AT91Bootstrap binary by doing:
$ make

If the building process is successful, the final .bin image is binaries/at91bootstrap.bin.

Build U-Boot from sources

Getting U-Boot sources

Dedicated page on U-Boot wiki: http://www.denx.de/wiki/U-Boot/SourceCode

You can easily download U-Boot source code from Linux4SAM GitHub U-Boot repository:

  • clone the Linux4sam GitHub U-Boot repository
       $ git clone git://github.com/linux4sam/u-boot-at91.git
       Cloning into 'u-boot-at91'...
       remote: Counting objects: 219350, done.
       remote: Compressing objects: 100% (40142/40142), done.
       remote: Total 219350 (delta 175755), reused 219350 (delta 175755)
       Receiving objects: 100% (219350/219350), 56.01 MiB | 1.24 MiB/s, done.
       Resolving deltas: 100% (175755/175755), done.
       $ cd u-boot-at91
       

  • The source code has been taken from the master branch which is pointing to the latest branch we use. If you want to use the other branch, you can list them and use one of them by doing:
       $ git branch -r
       origin/HEAD -> origin/master
       origin/master
       origin/u-boot-2012.10-at91
       origin/u-boot-2013.07-at91
       origin/u-boot-2014.07-at91
       origin/u-boot-2015.01-at91
       origin/u-boot-2016.03-at91
       origin/u-boot-2017.03-at91
       origin/uboot_5series_1.x
       $ git checkout origin/u-boot-2017.03-at91 -b u-boot-2017.03-at91
       Branch u-boot-2017.03-at91 set up to track remote branch u-boot-2017.03-at91 from origin.
       Switched to a new branch 'u-boot-2017.03-at91'
       

Cross-compiling U-Boot

Before compiling the U-Boot, you need setup cross compile toolchain in the section.

Build Kernel from sources

Getting Kernel sources

To get the source code, you have to clone the repository:

$ git clone git://github.com/linux4sam/linux-at91.git
Cloning into 'linux-at91'...
remote: Counting objects: 4524288, done.
remote: Compressing objects: 100% (721/721), done.
remote: Total 4524288 (delta 385), reused 1 (delta 1), pack-reused 4523564
Receiving objects: 100% (4524288/4524288), 1.22 GiB | 1.35 MiB/s, done.
Resolving deltas: 100% (3777338/3777338), done.
Checking connectivity... done.
Checking out files: 100% (49565/49565), done.

The source code has been taken from the master branch which is pointing on the latest branch we use.

Pointing hand Note that you can also add this Linux4SAM repository as a remote GIT repository to your usu

$ git remote add linux4sam git://github.com/linux4sam/linux-at91.git
$ git remote update linux4sam
Fetching linux4sam
From git://github.com/linux4sam/linux-at91
 * [new branch]                linux-2.6.39-at91 -> linux4sam/linux-2.6.39-at91
 * [new branch]                linux-3.10-at91 -> linux4sam/linux-3.10-at91
 * [new branch]                linux-3.15-at91 -> linux4sam/linux-3.15-at91
 * [new branch]                linux-3.18-at91 -> linux4sam/linux-3.18-at91
 * [new branch]                linux-3.4.9-at91 -> linux4sam/linux-3.4.9-at91
 * [new branch]                linux-3.6.9-at91 -> linux4sam/linux-3.6.9-at91
 * [new branch]                linux-4.1-at91 -> linux4sam/linux-4.1-at91
 * [new branch]                linux-4.4-at91 -> linux4sam/linux-4.4-at91
 * [new branch]                linux-4.9-at91 -> linux4sam/linux-4.9-at91
 * [new branch]                master     -> linux4sam/master

If you want to use an other branch, you can list them and use one of them by doing this:

$ git branch -r
  origin/HEAD -> origin/master
  origin/linux-2.6.39-at91
  origin/linux-3.10-at91
  origin/linux-3.15-at91
  origin/linux-3.18-at91
  origin/linux-3.4.9-at91
  origin/linux-3.6.9-at91
  origin/linux-4.1-at91
  origin/linux-4.4-at91
  origin/linux-4.9-at91
  origin/master
$ git checkout origin/linux-4.9-at91 -b linux-4.9-at91
Branch linux-4.9-at91 set up to track remote branch linux-4.9-at91 from origin.
Switched to a new branch 'linux-4.9-at91'

Configure and Build the Linux kernel

Now you have to configure the Linux kernel according to your hardware. We have two default configuration at91 SoC in arch/arm/configs
arch/arm/configs/at91_dt_defconfig
arch/arm/configs/sama5_defconfig

  • at91_dt_defconfig: for at91sam ARM926 series chips
  • sama5_defconfig: for SAMA5 series chips

At this step, you can modify default configuration using the menuconfig

$ make ARCH=arm menuconfig

And build the Linux kernel image, before you build you need set up the cross compile toolchain, check this section.

$ make ARCH=arm

[..]

  Kernel: arch/arm/boot/Image is ready
  Kernel: arch/arm/boot/zImage is ready

Now you have an usable compressed kernel image zImage.

If you need an uImage you can run this additional step:

make ARCH=arm uImage LOADADDR=0x20008000

[..]

  Kernel: arch/arm/boot/zImage is ready
  UIMAGE  arch/arm/boot/uImage
Image Name:   Linux-4.1.0-linux4sam_5.3+
Created:      Fri Sep  9 17:02:45 2016
Image Type:   ARM Linux Kernel Image (uncompressed)
Data Size:    3441072 Bytes = 3360.42 kB = 3.28 MB
Load Address: 20008000
Entry Point:  20008000
  Image arch/arm/boot/uImage is ready

make ARCH=arm dtbs

[..]
  DTC     arch/arm/boot/dts/at91-kizbox2.dtb
  DTC     arch/arm/boot/dts/at91-sama5d2_ptc.dtb
  DTC     arch/arm/boot/dts/at91-sama5d27_som1_ek.dtb
  DTC     arch/arm/boot/dts/at91-sama5d27_som1_ek_pda4.dtb
  DTC     arch/arm/boot/dts/at91-sama5d27_som1_ek_pda7.dtb
  DTC     arch/arm/boot/dts/at91-sama5d27_som1_ek_pda7b.dtb
  DTC     arch/arm/boot/dts/at91-sama5d2_xplained.dtb
  DTC     arch/arm/boot/dts/at91-sama5d2_xplained_pda4.dtb
  DTC     arch/arm/boot/dts/at91-sama5d2_xplained_pda7.dtb
  DTC     arch/arm/boot/dts/at91-sama5d2_xplained_pda7b.dtb
  DTC     arch/arm/boot/dts/at91-sama5d3_xplained.dtb
  DTC     arch/arm/boot/dts/at91-sama5d3_xplained_pda4.dtb
  DTC     arch/arm/boot/dts/at91-sama5d3_xplained_pda7.dtb
  DTC     arch/arm/boot/dts/at91-sama5d3_xplained_pda7b.dtb
  DTC     arch/arm/boot/dts/sama5d31ek.dtb
  DTC     arch/arm/boot/dts/sama5d33ek.dtb
  DTC     arch/arm/boot/dts/sama5d34ek.dtb
  DTC     arch/arm/boot/dts/sama5d35ek.dtb
  DTC     arch/arm/boot/dts/sama5d36ek.dtb
  DTC     arch/arm/boot/dts/sama5d36ek_cmp.dtb
  DTC     arch/arm/boot/dts/at91-sama5d4_ma5d4evk.dtb
  DTC     arch/arm/boot/dts/at91-sama5d4_xplained.dtb
  DTC     arch/arm/boot/dts/at91-sama5d4_xplained_pda4.dtb
  DTC     arch/arm/boot/dts/at91-sama5d4_xplained_hdmi.dtb
  DTC     arch/arm/boot/dts/at91-sama5d4_xplained_pda7.dtb
  DTC     arch/arm/boot/dts/at91-sama5d4ek.dtb
  DTC     arch/arm/boot/dts/at91-sama5d4_xplained_pda7b.dtb
  DTC     arch/arm/boot/dts/at91-sama5d4ek_isi.dtb
  DTC     arch/arm/boot/dts/at91-vinco.dtb
[..]

If the building process is successful, the final images can be found under arch/arm/boot/ directory.

Build Yocto/Poky rootfs from sources

Note that building an entire distribution is a long process. It also requires a big amount of free disk space.

The support for Atmel AT91 SoC family is included in a particular Yocto layer: meta-atmel. The source for this layer are hosted on Linux4SAM GitHub account: https://github.com/linux4sam/meta-atmel

Building environment

A step-by-step comprehensive installation is explained in the Yocto Project Quick Start. The following lines have to be considered as an add-on that is AT91 specific or that can facilitate your setup.

Prerequisite

Here are the reference pages for setting up a Yocto building environment: What You Need and How You Get It.

Step by step build procedure

Note here is a copy of the README procedure available directly in the meta-atmel layer. This file in the meta-atmel layer repository must be considered as the reference and the following copy can be out-of-sync.

This layer provides support for Microchip microprocessors (aka AT91)
====================================================================

For more information about the Microchip MPU product line see:
http://www.microchip.com/design-centers/32-bit-mpus
Linux & Open Source on Microchip microprocessors:
http://www.linux4sam.org


Supported SoCs / MACHINE names
==============================
Note that most of the machine names below, have a SD Card variant that can be
built by adding an "-sd" suffix to the machine name.
- SAMA5D2 product family / sama5d2-xplained, sama5d27-som1-ek-sd, sama5d2-ptc-ek
- SAMA5D4 product family / sama5d4ek, sama5d4-xplained
- SAMA5D3 product family / sama5d3xek, sama5d3-xplained
- AT91SAM9x5 product family (AT91SAM9G15, AT91SAM9G25, AT91SAM9X25, AT91SAM9G35 and AT91SAM9X35) / at91sam9x5ek
- AT91SAM9RL / at91sam9rlek
- AT91SAM9G45 / at91sam9m10g45ek


Sources
=======
- meta-atmel
URI: git://github.com/linux4sam/meta-atmel.git
URI: https://github.com/linux4sam/meta-atmel.git
Branch: rocko


Dependencies
============
This Layer depends on :
- meta-openembedded
URI: git://git.openembedded.org/meta-openembedded
URI: http://cgit.openembedded.org/meta-openembedded/
Branch: rocko

Optionally:
- meta-qt5
URI: git://code.qt.io/yocto/meta-qt5.git
URI: http://code.qt.io/cgit/yocto/meta-qt5.git/
Tag: v5.9.4


Build procedure
===============

0/ Create a directory
mkdir my_dir
cd my_dir

1/ Clone yocto/poky git repository with the proper branch ready
git clone git://git.yoctoproject.org/poky -b rocko

2/ Clone meta-openembedded git repository with the proper branch ready
git clone git://git.openembedded.org/meta-openembedded -b rocko

3/ Clone meta-qt5 git repository with the proper branch ready
git clone git://code.qt.io/yocto/meta-qt5.git
cd meta-qt5
git checkout v5.9.4
cd ..

4/ Clone meta-atmel layer with the proper branch ready
git clone git://github.com/linux4sam/meta-atmel.git -b rocko

5/ Enter the poky directory to configure the build system and start the build process
cd poky

6/ Initialize build directory
source oe-init-build-env build-atmel

7/ Add meta-atmel layer to bblayer configuration file
vim conf/bblayers.conf

# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../../..')}"

BBLAYERS ?= " \
  ${BSPDIR}/poky/meta \
  ${BSPDIR}/poky/meta-poky \
  ${BSPDIR}/poky/meta-yocto-bsp \
  ${BSPDIR}/meta-atmel \
  ${BSPDIR}/meta-openembedded/meta-oe \
  ${BSPDIR}/meta-openembedded/meta-networking \
  ${BSPDIR}/meta-openembedded/meta-python \
  ${BSPDIR}/meta-openembedded/meta-multimedia \
  ${BSPDIR}/meta-qt5 \
  "

BBLAYERS_NON_REMOVABLE ?= " \
  ${BSPDIR}/poky/meta \
  ${BSPDIR}/poky/meta-poky \
  "

8/ Edit local.conf to specify the machine, location of source archived, package type (rpm, deb or ipk)
Pick one MACHINE name from the "Supported SoCs / MACHINE names" chapter above
and edit the "local.conf" file. Here is an example:

vim conf/local.conf
[...]
MACHINE ??= "sama5d3-xplained"
[...]
DL_DIR ?= "your_download_directory_path"
[...]
PACKAGE_CLASSES ?= "package_ipk"
[...]
USER_CLASSES ?= "buildstats image-mklibs"

To get better performance, use the "poky-atmel" distribution by also adding that
line:
DISTRO = "poky-atmel"

9/ Build core minimal image
bitbake core-image-minimal

10/ We found that additional local.conf changes are needed for our QT demo
image. You can add these two lines at the end of the file:
vim conf/local.conf
[...]
LICENSE_FLAGS_WHITELIST += "commercial"
SYSVINIT_ENABLED_GETTYS = ""

11/ Build Atmel demo images
bitbake atmel-qt5-demo-image


Typical bitbake output
======================
Build Configuration:
BB_VERSION        = "1.36.0"
BUILD_SYS         = "x86_64-linux"
NATIVELSBSTRING   = "universal"
TARGET_SYS        = "arm-poky-linux-gnueabi"
MACHINE           = "sama5d2-xplained"
DISTRO            = "poky-atmel"
DISTRO_VERSION    = "2.4.2"
TUNE_FEATURES     = "arm armv7a vfp thumb neon callconvention-hard cortexa5"
TARGET_FPU        = "hard"
meta
meta-poky
meta-yocto-bsp    = "rocko:cca8bde9d700d68c5f36d7d4c47c048526aedfc0"
meta-atmel        = "rocko:0353a4afb1f404aa0830b19dcde4f057070a4ce3"
meta-oe
meta-networking
meta-python
meta-multimedia   = "rocko:dacfa2b1920e285531bec55cd2f08743390aaf57"
meta-qt5          = "HEAD:e721e84659869e4a04838d95d7cdbab9d48f5c3d"


Contributing
============
To contribute to this layer you should submit the patches for review to:
the github pull-request facility directly or the forum. Anyway, don't forget to
Cc the maintainers.

AT91 Forum:
http://www.at91.com/discussions/

for some useful guidelines to be followed when submitting patches:
http://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded

Maintainers:
Nicolas Ferre 
Patrice Vilchez 

When creating patches insert the [meta-atmel] tag in the subject, for example
use something like:
git format-patch -s --subject-prefix='meta-atmel][PATCH' 

Using SAM-BA to flash components to board

SPI + eMMC Flash demo - Memory map

demo_spi_emmc_map_lnx4sam5x.png

Install SAM-BA software in your PC

In addition to the official SAM-BA pages on http://www.microchip.com, we maintain information about SAM-BA in the SoftwareTools page.

ALERT! use SAM-BA 3.2.y onwards. You can download it here: SAM-BA 3.x release page.

Launch SAM-BA tools

  • According to this section make sure that the chip can execute the SAM-BA Monitor.

Programming components into SPI flash

Program AT91Bootstrap binary

Run SAM-BA with USB connection (equivalent to serial) and erase the beginning of the SPI flash and then write AT91Bootstrap binary:

# sam-ba -p serial -b sama5d2-xplained -a serialflash -c erase::0x3000 -c writeboot:at91bootstrap-sama5d2_xplained.bin
Opening serial port 'ttyACM0'
Connection opened.
Detected memory size is 4194304 bytes.
Page size is 256 bytes.
Buffer is 93952 bytes (367 pages) at address 0x002290c0.
Supported erase block sizes: 4KB, 32KB, 64KB
Executing command 'erase::0x3000'
Erased 4096 bytes at address 0x00000000 (33.33%)
Erased 4096 bytes at address 0x00001000 (66.67%)
Erased 4096 bytes at address 0x00002000 (100.00%)
Executing command 'writeboot:at91bootstrap-sama5d2_xplained.bin'
Appending 56 bytes of padding to fill the last written page
Wrote 10752 bytes at address 0x00000000 (100.00%)
Connection closed.

HELP Note that you can run several commands on the same SAM-BA invocation.

Program U-Boot binary

Run SAM-BA with USB connection (equivalent to serial) and erase the U-Boot section in the SPI flash memory map and then write U-Boot binary:

# sam-ba -p serial -b sama5d2-xplained -a serialflash -c erase:0x8000:0x70000 -c write:u-boot-sama5d2-xplained.bin:0x8000
Opening serial port 'ttyACM0'
Connection opened.
Detected memory size is 4194304 bytes.
Page size is 256 bytes.
Buffer is 93952 bytes (367 pages) at address 0x002290c0.
Supported erase block sizes: 4KB, 32KB, 64KB
Executing command 'erase:0x8000:0x70000'
Erased 32768 bytes at address 0x00008000 (7.14%)
Erased 65536 bytes at address 0x00010000 (21.43%)
Erased 65536 bytes at address 0x00020000 (35.71%)
Erased 65536 bytes at address 0x00030000 (50.00%)
Erased 65536 bytes at address 0x00040000 (64.29%)
Erased 65536 bytes at address 0x00050000 (78.57%)
Erased 65536 bytes at address 0x00060000 (92.86%)
Erased 32768 bytes at address 0x00070000 (100.00%)
Executing command 'write:u-boot-sama5d2-xplained.bin:0x8000'
Appending 118 bytes of padding to fill the last written page
Wrote 93952 bytes at address 0x00008000 (23.30%)
Wrote 93952 bytes at address 0x0001ef00 (46.60%)
Wrote 93952 bytes at address 0x00035e00 (69.90%)
Wrote 93952 bytes at address 0x0004cd00 (93.21%)
Wrote 27392 bytes at address 0x00063c00 (100.00%)
Connection closed.

Programming components into eMMC flash

Program rootfs file

With SAM-BA you can directly program SD/MMC images to the on-board eMMC. These images are named *.img or *.wic for the ones generated by Yocto Project.

# sam-ba -p serial -b sama5d2-xplained -a sdmmc -c write:atmel-qt5-demo-image-sama5d2-xplained.wic
Opening serial port 'ttyACM0'
Connection opened.
Detected memory size is 3925868544 bytes.
Page size is 512 bytes.
Buffer is 88576 bytes (173 pages) at address 0x0022a5a0.
Executing command 'write:atmel-qt5-demo-image-sama5d2-xplained.wic'
Wrote 88576 bytes at address 0x00000000 (0.02%)
Wrote 88576 bytes at address 0x00015a00 (0.04%)
Wrote 88576 bytes at address 0x0002b400 (0.05%)
Wrote 88576 bytes at address 0x00040e00 (0.07%)
Wrote 88576 bytes at address 0x00056800 (0.09%)
[..]
Wrote 88576 bytes at address 0x1d4e8600 (99.98%)
Wrote 88576 bytes at address 0x1d4fe000 (100.00%)
Wrote 4608 bytes at address 0x1d513a00 (100.00%)
Connection closed.

HELP Note that programming a rootfs of several hundreds of MiB will take a few minutes to complete.