summaryrefslogtreecommitdiff
path: root/docs/adding-boards.txt
diff options
context:
space:
mode:
Diffstat (limited to 'docs/adding-boards.txt')
-rw-r--r--docs/adding-boards.txt147
1 files changed, 147 insertions, 0 deletions
diff --git a/docs/adding-boards.txt b/docs/adding-boards.txt
new file mode 100644
index 000000000..e5409fdd1
--- /dev/null
+++ b/docs/adding-boards.txt
@@ -0,0 +1,147 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[adding-boards]]
+Adding new embedded boards to OpenADK
+-------------------------------------
+
+This section covers how support for new embedded boards
+can be integrated into OpenADK.
+
+First step is to create a board description file in
+target/<arch>/systems with the short name of your embedded board.
+
+For example you would create following file for Raspberry PI 2 support:
+target/arm/systems/raspberry-pi2
+---------------------
+config ADK_TARGET_SYSTEM_RASPBERRY_PI2
+ bool "Raspberry PI 2"
+ select ADK_arm
+ select ADK_raspberry_pi2
+ select ADK_TARGET_LITTLE_ENDIAN
+ select ADK_CPU_CORTEX_A7
+ select ADK_TARGET_CPU_WITH_NEON
+ select ADK_TARGET_BOARD_BCM28XX
+ select ADK_TARGET_WITH_VGA
+ select ADK_TARGET_WITH_SERIAL
+ select ADK_TARGET_WITH_CPU_FREQ
+ select ADK_TARGET_WITH_USB
+ select ADK_TARGET_WITH_INPUT
+ select ADK_TARGET_WITH_SD
+ select ADK_TARGET_WITH_I2C
+ select ADK_TARGET_WITH_SPI
+ select ADK_TARGET_WITH_SMP
+ select ADK_PACKAGE_BCM28XX_BOOTLOADER
+ select ADK_TARGET_WITH_ROOT_RW
+ select ADK_TARGET_KERNEL_ZIMAGE
+ help
+ Raspberry PI 2
+------------------------
+
+You need to select as a minimum the architecture, target system name, CPU type
+and Kernel format. If a bootloader is required you also need to select it.
+(ADK_PACKAGE_BCM28XX_BOOTLOADER) If the bootloader does not exist as a package
+in OpenADK, you need to port it first.
+
+The hardware capabilities are optional. (f.e. ADK_TARGET_WITH_SD), but
+required when you configure the driver configuration later.
+
+For architectures with a choice for endianess you should select either
+ADK_TARGET_LITTLE_ENDIAN or ADK_TARGET_BIG_ENDIAN.
+
+If the CPU type like in this example ADK_CPU_CORTEX_A7 is not yet available
+you need to add it to target/config/Config.in.cpu. For optimized code generation
+you should also add ADK_TARGET_GCC_CPU or ADK_TARGET_GCC_ARCH symbol for your CPU
+type. Furthermore you need to decide if your CPU has a MMU, FPU and NPTL support
+in the C library.
+
+After the creation of the file you can go into the menu based system and
+select your embedded board.
+
+The second step is to create a Kernel configuration file fragment, which contains
+only the basic support for your board to get serial console access.
+
+For example the snippet for Raspberry PI 2:
+target/arm/kernel/raspberry-pi2
+------------------------
+CONFIG_ARM=y
+CONFIG_ARM_PATCH_PHYS_VIRT=y
+CONFIG_ARCH_MULTI_V7=y
+CONFIG_ARCH_BCM2709=y
+CONFIG_MACH_BCM2709=y
+CONFIG_FIQ=y
+CONFIG_SERIAL_AMBA_PL011=y
+CONFIG_SERIAL_AMBA_PL011_CONSOLE=y
+------------------------
+
+The kernel file must be registered in target/config/Config.in.kernel
+------------------------
+config ADK_TARGET_KERNEL_MINICONFIG
+ string
+ ...
+ default "raspberry-pi2" if ADK_TARGET_SYSTEM_RASPBERRY_PI2
+------------------------
+
+If the mainstream kernel from kernel.org does not contain support for your board
+you need to get a working kernel tree and create a patch.
+For example for Raspberry PI 2 we basically use following method to create a patch:
+------------------------
+git clone https://github.com/raspberrypi/linux.git linux-rpi
+wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.18.9.tar.xz
+tar xvf linux-3.18.9.tar.xz
+find linux-3.18.9 linux-rpi -type l -delete
+rm -rf linux-rpi/.git
+diff -Nur linux-3.18.9 linux-rpi > target/arm/bcm28xx/patches/3.18.9/0000-raspberry-pi.patch
+------------------------
+
+Normally you use target/<arch>/<target system>/patches/<kernelversion>/0000-<target-system>.patch.
+In case of Raspberry PI 2 we have a single patch for Raspberry PI and Raspberry PI 2 and use
+the extra board name bcm28xx to describe the family of devices.
+
+After that you can build the toolchain, kernel and base system and write the resulting
+firmware from firmware/<target system>/ to your device or boot via netboot and NFS.
+
+If you have some special notes for your embedded board, please add some advise to
+target/<arch>/Makefile. You can add information for the different rootfilesystem types.
+
+If your system boots up fine to a shell, you can add the driver configuration.
+For example if you add SD card driver support to Raspberry PI 2 you
+would add following to target/linux/config/Config.in.block
+------------------------
+config ADK_KERNEL_MMC_BCM2835
+ bool "SD card support for BCM2835 boards"
+ select ADK_KERNEL_SCSI
+ select ADK_KERNEL_MMC
+ select ADK_KERNEL_MMC_BLOCK
+ select ADK_KERNEL_BLK_DEV
+ select ADK_KERNEL_BLK_DEV_SD
+ select ADK_KERNEL_MMC_SDHCI
+ select ADK_KERNEL_MMC_SDHCI_PLTFM
+ select ADK_KERNEL_MMC_BCM2835_DMA
+ depends on ADK_TARGET_BOARD_BCM28XX
+ default y if ADK_TARGET_BOARD_BCM28XX
+ default n
+------------------------
+
+We use the symbol prefix ADK_KERNEL instead of CONFIG. Otherwise the symbols are
+matching the kernel symbol names.
+
+Get again into the menu based system, enable the driver you added and recompile.
+If your driver is available as kernel module use tristate and add an entry to
+mk/modules.mk.
+
+An entry might look like this:
+------------------------
+$(eval $(call KMOD_template,SND_BCM2708_SOC_I2S,snd-bcm2708-soc-i2s,\
+ $(MODULES_DIR)/kernel/sound/soc/bcm/snd-soc-bcm2708-i2s \
+,60, kmod-snd-soc))
+------------------------
+
+If the user choose the I2S driver for Raspberry PI 2, create a kmod package
+containing the file kernel/sound/soc/bcm/snd-soc-bcm2708-i2s.ko and generate
+a dependency to kmod-snd-soc when a package management (ipkg/opkg) is used.
+Furthermore a file with load instructions is created in /etc/modules.d/snd-bcm2708-soc-i2s
+on the target.
+
+
+