docs/adding-boards.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[adding-boards]]
   5 Adding new embedded boards to OpenADK
   6 -------------------------------------
   7
   8 This section covers how support for new embedded boards
   9 can be integrated into OpenADK.
  10
  11 First step is to create a board description file in
  12 target/<arch>/systems with the short name of your embedded board.
  13
  14 For example you would create following file for Raspberry PI 2 support:
  15 target/arm/systems/raspberry-pi2
  16 ---------------------
  17 config ADK_TARGET_SYSTEM_RASPBERRY_PI2
  18         bool "Raspberry PI 2"
  19         depends on ADK_TARGET_LITTLE_ENDIAN
  20         select ADK_TARGET_CPU_ARM_CORTEX_A7
  21         select ADK_TARGET_CPU_WITH_NEON
  22         select ADK_TARGET_BOARD_BCM28XX
  23         select ADK_TARGET_WITH_VGA
  24         select ADK_TARGET_WITH_SERIAL
  25         select ADK_TARGET_WITH_CPU_FREQ
  26         select ADK_TARGET_WITH_USB
  27         select ADK_TARGET_WITH_INPUT
  28         select ADK_TARGET_WITH_SD
  29         select ADK_TARGET_WITH_I2C
  30         select ADK_TARGET_WITH_SPI
  31         select ADK_TARGET_WITH_SMP
  32         select ADK_PACKAGE_BCM28XX_BOOTLOADER
  33         select ADK_TARGET_WITH_ROOT_RW
  34         select ADK_TARGET_KERNEL_ZIMAGE
  35         help
  36           Raspberry PI 2
  37 ------------------------
  38
  39 You need to select as a minimum a CPU type and Kernel format.
  40 If a bootloader is required you also need to select it.
  41 (ADK_PACKAGE_BCM28XX_BOOTLOADER) If the bootloader does not exist as a package
  42 in OpenADK, you need to port it first.
  43
  44 The hardware capabilities are optional. (f.e. ADK_TARGET_WITH_SD), but
  45 required when you configure the driver configuration later.
  46
  47 For architectures with a choice for endianess you should depend on either
  48 ADK_TARGET_LITTLE_ENDIAN or ADK_TARGET_BIG_ENDIAN.
  49
  50 If the CPU type like in this example ADK_TARGET_CPU_ARM_CORTEX_A7 is not yet available
  51 you need to add it to target/config/Config.in.cpu. For optimized code generation
  52 you should also add ADK_TARGET_GCC_CPU or ADK_TARGET_GCC_ARCH symbol for your CPU
  53 type. Furthermore you need to decide if your CPU has a MMU, FPU and NPTL support
  54 in the C library.
  55
  56 After the creation of the file you can go into the menu based system and
  57 select your embedded board.
  58
  59 The second step is to create a Kernel configuration file fragment, which contains
  60 only the basic support for your board to get serial console access.
  61
  62 For example the snippet for Raspberry PI 2, the file name must match the embedded board
  63 name:
  64 target/arm/kernel/raspberry-pi2
  65 ------------------------
  66 CONFIG_ARM=y
  67 CONFIG_ARCH_BCM2709=y
  68 CONFIG_BCM2709_DT=y
  69 CONFIG_PHYS_OFFSET=0
  70 CONFIG_HAVE_ARM_ARCH_TIMER=y
  71 CONFIG_FIQ=y
  72 CONFIG_ATAGS=y
  73 CONFIG_KUSER_HELPERS=y
  74 CONFIG_ARM_ERRATA_643719=y
  75 CONFIG_BCM2708_NOL2CACHE=y
  76 CONFIG_RASPBERRYPI_FIRMWARE=y
  77 CONFIG_BRCM_CHAR_DRIVERS=y
  78 CONFIG_BCM2708_VCHIQ=y
  79 CONFIG_BCM2708_VCMEM=y
  80 CONFIG_MAILBOX=y
  81 CONFIG_BCM2835_MBOX=y
  82 CONFIG_OF=y
  83 CONFIG_OF_OVERLAY=y
  84 CONFIG_CMDLINE_FROM_BOOTLOADER=y
  85 ------------------------
  86
  87 If the mainstream kernel from kernel.org does not contain support for your board
  88 you need to get a working kernel tree and create a patch.
  89 For example for Raspberry PI 2 we basically use following method to create a patch:
  90 ------------------------
  91 git clone https://github.com/raspberrypi/linux.git linux-rpi
  92 wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.18.9.tar.xz
  93 tar xvf linux-3.18.9.tar.xz
  94 find linux-3.18.9 linux-rpi -type l -delete
  95 rm -rf linux-rpi/.git
  96 diff -Nur linux-3.18.9 linux-rpi > target/arm/bcm28xx/patches/3.18.9/0001-bcm28xx-github.patch
  97 ------------------------
  98
  99 Normally you use target/<arch>/<target system>/patches/<kernelversion>/0001-<target-system>.patch.
 100 In case of Raspberry PI 2 we have a single patch for Raspberry PI and Raspberry PI 2 and use
 101 the extra board name bcm28xx to describe the family of devices.
 102
 103 After that you can build the toolchain, kernel and base system and write the resulting
 104 firmware from firmware/<target system>/ to your device or boot via netboot and NFS.
 105
 106 If you have some special notes for your embedded board, please add some advise to
 107 target/<arch>/Makefile. You can add information for the different rootfilesystem types.
 108
 109 If your system boots up fine to a shell, you can add the driver configuration.
 110 For example if you add SD card driver support to Raspberry PI 2 you
 111 would add following to target/linux/config/Config.in.block
 112 ------------------------
 113 config ADK_LINUX_KERNEL_MMC_BCM2835
 114         bool "SD card support for BCM2835 boards"
 115         select ADK_LINUX_KERNEL_SCSI
 116         select ADK_LINUX_KERNEL_MMC
 117         select ADK_LINUX_KERNEL_MMC_BLOCK
 118         select ADK_LINUX_KERNEL_BLK_DEV
 119         select ADK_LINUX_KERNEL_BLK_DEV_SD
 120         select ADK_LINUX_KERNEL_MMC_SDHCI
 121         select ADK_LINUX_KERNEL_MMC_SDHCI_PLTFM
 122         select ADK_LINUX_KERNEL_MMC_BCM2835_DMA
 123         depends on ADK_TARGET_BOARD_BCM28XX
 124         default y if ADK_TARGET_BOARD_BCM28XX
 125         default n
 126 ------------------------
 127
 128 We use the symbol prefix ADK_LINUX_KERNEL instead of CONFIG. Otherwise the symbols are
 129 matching the kernel symbol names.
 130
 131 Get again into the menu based system, enable the driver you added and recompile.
 132 If your driver is available as a kernel module use tristate.