README

This README file contains information on building the meta-hilscher-netx4000
BSP layer, and booting / creating bootable images.


Table of Contents
=================

1. Description
2. Yocto BSP Layer - Hilscher netX4000 SoC
  2.1 Included drivers
  2.2 How to use it
      2.2.1 Enabling verified boot
  2.3 Creating own machines
  2.4 Creating bootable images
      2.4.1 SD/MMC card
      2.4.2 USB stick


1. Description
==============
This is the general hardware specific BSP overlay for the Hilscher netX4000
relaxed and full SoC.

The core BSP part of meta-hilscher-netx4000 was made and tested with Yocto/Poky
distribution / layer.


2. Yocto BSP Layer - Hilscher netX4000 SoC
==========================================

This layer depends on:

URI: git://git.yoctoproject.org/poky
branch: master
revision: HEAD

Pre-Requisites for all boards:
 * UART0 to interface with bootloader / kernel

Preferred boot media for evaluation:
 * SD/MMC card


2.1 Included drivers
====================

mainline drivers:
 * UART/RS232 - ARM PL011
 * SPI - ARM PL022
   * Limitations:
     * DMA only working in transfer modes larger than 8 bits
     * GPIO's must be used as chip select signals
 * GMAC - Synopsis DWC_ETH_QOS
 * DMAC (8ch) - NPFAXI + platform patches
 * USB 2.0 Host - ehci, ohci + platform initialization patches

non-mainline drivers:
 * SDIO (including DMA support)
 * SQI - 4-bit SPI unit
 * GPIO
 * USB 2.0 Device
 * I2C
 * RTC
 * ADC/IIO
   * Limitations:
     * requires access to R7 peripherals which are usually denied by firewall.
       Special initialization code needed on R7
     * no sequencer support (just basic manual sampling)
 * ECC (1 bit correction / 2 bit detection) for L1/L2 cache - EDAC modules
 * ECC (1 bit correction / 2 bit detection) for DDR memory - EDAC modules
 * LCD (framebuffer driver)
 * CAN (kernel 4.9+)
 * PCIe root-complex


2.2 How to use it
=================

1. Setup yocto build environment

    source poky/oe-init-build-env build

2. Add meta-hilscher-netx4000 layer to conf/bblayers.conf

3. Setup machine in conf/local.conf
    * MACHINE = "nxhx4000-jtag-plus-rev4"

4. Build any default image "bitbake <image>"
    * core-image-minimal
    * core-image-minimal-dev
    * core-image-sato

5. optional configuration
    Check "http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html"
    for options.


2.2.1 Enabling verified boot
============================
See yocto reference manual for enabling veified boot in u-boot


2.3 Creating own machines
=========================

see http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#platdev-newmachine

Example machine:
 * machine configuration:
   meta-hilscher-netx4000/conf/nxhx4000-jtag-plus-rev4.conf
 * hardware description (device tree):
   meta-hilscher-netx4000/recipes-bsp/netx-device-tree/files/nxhx4000-jtag-plus_rev4.dts


2.4 Creating bootable images
============================


2.4.1 SD/MMC card
=================

The netX4000 base machine configuration (netx4000.inc) includes
IMAGE_FSTYPES:append = " wic wic.bmap " and WKS_FILE:prepend = " sdimg-bootpart.wks " lines.

These are responsible for automatically building an SD card image file.

To use it, change into the machine related deploy directory and copy the image
file to SD card.

EXAMPLE: (host command line)
  cd tmp/deploy/images/nxhx4000-jtag-plus-rev4
  dd if=core-image-minimal-nxhx4000-jtag-plus-rev4.wic of=/dev/sdb bs=4M && sync

Alternatively you can use bmaptool as described in the yocto manual:
  https://www.yoctoproject.org/docs/2.7/dev-manual/dev-manual.html#flashing-images-using-bmaptool

NOTE:
 * /dev/sdb is the device file of SD card and must be adapted to your conditions!
 * Perhaps sudo permissions are required


2.4.2 USB stick
================
NOTE: Building USB sticks requires bootloader to either be
      started from a serial flash connected to the netX chip or
      from an SD/MMC card.

Pre-Requisites:
 * Make sure that IMAGE_FSTYPES (local.conf or machine-configuration)
   contains "tar.bz2"

Format USB stick to ext4 and extract tarball.

EXAMPLE: (host command line)
  mkfs.ext4 /dev/sdb1
  mount /dev/sdb1 /mnt
  tar xf core-image-minimal-nxhx4000-jtag-plus-rev2.tar.bz2 -C /mnt
  sync && umount /dev/sdb*

NOTE:
 * /dev/sdb is the device file of USB stick and must be adapted to your conditions!
 * Perhaps sudo permissions are required