diff options
Diffstat (limited to 'docs')
33 files changed, 371 insertions, 158 deletions
diff --git a/docs/adding-boards.txt b/docs/adding-boards.txt new file mode 100644 index 000000000..5f50df702 --- /dev/null +++ b/docs/adding-boards.txt @@ -0,0 +1,132 @@ +// -*- 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" + depends on ADK_TARGET_LITTLE_ENDIAN + select ADK_TARGET_CPU_ARM_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 a 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 depend on either +ADK_TARGET_LITTLE_ENDIAN or ADK_TARGET_BIG_ENDIAN. + +If the CPU type like in this example ADK_TARGET_CPU_ARM_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, the file name must match the embedded board +name: +target/arm/kernel/raspberry-pi2 +------------------------ +CONFIG_ARM=y +CONFIG_ARCH_BCM2709=y +CONFIG_BCM2709_DT=y +CONFIG_PHYS_OFFSET=0 +CONFIG_HAVE_ARM_ARCH_TIMER=y +CONFIG_FIQ=y +CONFIG_ATAGS=y +CONFIG_KUSER_HELPERS=y +CONFIG_ARM_ERRATA_643719=y +CONFIG_BCM2708_NOL2CACHE=y +CONFIG_RASPBERRYPI_FIRMWARE=y +CONFIG_BRCM_CHAR_DRIVERS=y +CONFIG_BCM2708_VCHIQ=y +CONFIG_BCM2708_VCMEM=y +CONFIG_MAILBOX=y +CONFIG_BCM2835_MBOX=y +CONFIG_OF=y +CONFIG_OF_OVERLAY=y +CONFIG_CMDLINE_FROM_BOOTLOADER=y +------------------------ + +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/0001-bcm28xx-github.patch +------------------------ + +Normally you use target/<arch>/<target system>/patches/<kernelversion>/0001-<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_LINUX_KERNEL_MMC_BCM2835 + bool "SD card support for BCM2835 boards" + select ADK_LINUX_KERNEL_SCSI + select ADK_LINUX_KERNEL_MMC + select ADK_LINUX_KERNEL_MMC_BLOCK + select ADK_LINUX_KERNEL_BLK_DEV + select ADK_LINUX_KERNEL_BLK_DEV_SD + select ADK_LINUX_KERNEL_MMC_SDHCI + select ADK_LINUX_KERNEL_MMC_SDHCI_PLTFM + select ADK_LINUX_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_LINUX_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 a kernel module use tristate. diff --git a/docs/adding-packages-auto.txt b/docs/adding-packages-auto.txt index 9af8c6ae9..4bfb2e439 100644 --- a/docs/adding-packages-auto.txt +++ b/docs/adding-packages-auto.txt @@ -18,11 +18,11 @@ package, with an example: 06: PKG_NAME:= libfoo 07: PKG_VERSION:= 1.0 08: PKG_RELEASE:= 1 -09: PKG_MD5SUM:= ba526cd8f4403a5d351a9efaa8608fbc +09: PKG_HASH:= 62333167b79afb0b25a843513288c67b59547acf653e8fbe62ee64e71ebd1587 10: PKG_DESCR:= foo library 11: PKG_SECTION:= libs -12: PKG_BUILDDEP:= openssl -13: PKG_DEPENDS:= libopenssl +12: PKG_BUILDDEP:= curl +13: PKG_DEPENDS:= libcurl 14: PKG_URL:= http://www.libfoo.org/ 15: PKG_SITES:= http://downloads.libfoo.org/ 16: @@ -42,14 +42,14 @@ The Makefile begins with line 4 with the inclusion of the top level rules.mk file. After that the Makefile starts on line 6 to 15 with metadata information: the name of the package (+PKG_NAME+), the version of the package (+PKG_VERSION+), the release number of the package (+PKG_RELEASE+), which is -used in OpenADK to mark any package updates, the md5 hash of the source archive -(+PKG_MD5SUM+), the short one line description for the package (+PKG_DESCR+), +used in OpenADK to mark any package updates, the sha256 hash of the source archive +(+PKG_HASH+), the short one line description for the package (+PKG_DESCR+), the package section for the menu configuration system (+PKG_SECTION+), the package buildtime dependencies (+PKG_BUILDDEP+), the package runtime dependencies (+PKG_DEPENDS+), the package homepage (+PKG_URL+) and finally the internet locations at which the tarball can be downloaded from (+PKG_SITES+). Normally ${PKG_NAME}-${PKG_VERSION}.tar.gz will be downloaded. You can -overwrite the default via the +DISTFILES+ variable. You can add more then one +override the default via the +DISTFILES+ variable. You can add more then one archive name in +DISTFILES+ via space separated. If you have no source archive at all, just use the boolean variable +NO_DISTFILES+ and set it to 1. diff --git a/docs/adding-packages-directory.txt b/docs/adding-packages-directory.txt index 45b7630dd..2f87b7c3e 100644 --- a/docs/adding-packages-directory.txt +++ b/docs/adding-packages-directory.txt @@ -39,19 +39,15 @@ are space separated and can be negated with ! as a prefix. * Target system ** variable used PKG_SYSTEM_DEPENDS -** for allowed values see the output of: find target/*/systems -type f |grep -v toolchain +** for allowed values see the output of: find target/*/systems -type f * Target C library ** variable used PKG_LIBC_DEPENDS -** allowed values are: uclibc-ng uclibc glibc musl +** allowed values are: uclibc-ng glibc musl -* Host system -** variable used PKG_HOST_DEPENDS -** allowed values are: linux darwin cygwin freebsd netbsd openbsd - -* C++ support -** variable used PKG_NEED_CXX -** Comment string: `C++` +* Special support needed (Toolchain with Threads, Realtime or C++ enabled) +** variable used PKG_NEEDS +** allowed values are: threads rt c++ Further formatting details: see xref:writing-rules-mk[the writing rules]. diff --git a/docs/adding-packages-host.txt b/docs/adding-packages-host.txt index bf7ff7158..35cf3ab6c 100644 --- a/docs/adding-packages-host.txt +++ b/docs/adding-packages-host.txt @@ -18,7 +18,7 @@ by another target package to build, with an example: 06: PKG_NAME:= hostfoo 07: PKG_VERSION:= 1.0 08: PKG_RELEASE:= 1 -09: PKG_MD5SUM:= 291ba57c0acd218da0b0916c280dcbae +09: PKG_HASH:= 62333167b79afb0b25a843513288c67b59547acf653e8fbe62ee64e71ebd1587 10: PKG_DESCR:= hostfoo utility 11: PKG_SECTION:= misc 12: PKG_URL:= http://www.foo.org/ @@ -52,7 +52,7 @@ Following mix between host and target package is possible, too: 06: PKG_NAME:= foo 07: PKG_VERSION:= 1.0 08: PKG_RELEASE:= 1 -09: PKG_MD5SUM:= 032a7b7b9f1a6e278ccde73f82cec5c2 +09: PKG_HASH:= 62333167b79afb0b25a843513288c67b59547acf653e8fbe62ee64e71ebd1587 10: PKG_DESCR:= foo tool 11: PKG_SECTION:= lang 12: PKG_BUILDDEP:= foo-host diff --git a/docs/adding-packages-manual.txt b/docs/adding-packages-manual.txt index 8bf6b32a0..768d3cdb6 100644 --- a/docs/adding-packages-manual.txt +++ b/docs/adding-packages-manual.txt @@ -20,11 +20,11 @@ scripts. 06: PKG_NAME:= libfoo 07: PKG_VERSION:= 1.0 08: PKG_RELEASE:= 1 -09: PKG_MD5SUM:= eade38998313c25fd7934719cdf8a2ea +09: PKG_HASH:= 62333167b79afb0b25a843513288c67b59547acf653e8fbe62ee64e71ebd1587 10: PKG_DESCR:= foo library 11: PKG_SECTION:= libs -12: PKG_BUILDDEP:= openssl -13: PKG_DEPENDS:= libopenssl +12: PKG_BUILDDEP:= libressl +13: PKG_DEPENDS:= libressl 14: PKG_URL:= http://www.libfoo.org/ 15: PKG_SITES:= http://download.libfoo.org/ 16: @@ -53,14 +53,14 @@ The Makefile begins with line 4 with the inclusion of the top level rules.mk file. After that the Makefile starts on line 6 to 15 with metadata information: the name of the package (+PKG_NAME+), the version of the package (+PKG_VERSION+), the release number of the package (+PKG_RELEASE+), which is -used in OpenADK to mark any package updates, the md5 hash of the source archive -(+PKG_MD5SUM+), the short one line description for the package (+PKG_DESCR+), +used in OpenADK to mark any package updates, the sha256 hash of the source archive +(+PKG_HASH+), the short one line description for the package (+PKG_DESCR+), the package section for the menu configuration system (+PKG_SECTION+), the package buildtime dependencies (+PKG_BUILDDEP+), the package runtime dependencies (+PKG_DEPENDS+), the package homepage (+PKG_URL+) and finally the internet locations at which the tarball can be downloaded from (+PKG_SITES+). Normally ${PKG_NAME}-${PKG_VERSION}.tar.gz will be downloaded. You can -overwrite the default via the +DISTFILES+ variable. You can add more then one +override the default via the +DISTFILES+ variable. You can add more then one archive name in +DISTFILES+ via space separated. If you have no source archive at all, just use the boolean variable +NO_DISTFILES+ and set it to 1. diff --git a/docs/common-usage.txt b/docs/common-usage.txt index 28d04da41..25cc22454 100644 --- a/docs/common-usage.txt +++ b/docs/common-usage.txt @@ -9,7 +9,7 @@ Understanding when a full rebuild is necessary OpenADK tries to detect what part of the system should be rebuilt when the system configuration is changed through +make menuconfig+. In some cases it -automatically rebuilt packages, but sometimes just a warning is printed to the +automatically rebuilds packages, but sometimes just a warning is printed to the terminal, that a rebuild is necessary to make the changes an effect. If strange things are happening, the autodetection might have not worked correctly, then you should consider to rebuild everything. If you are following development you @@ -37,7 +37,7 @@ some fixes in +build_*/w-<pkgname>-<pkgversion>/+, just do: -------------------- If you are happy with your changes to the package sources, you can automatically -generate a patch, which will be saved in +package/<pkgname>/patches and automatically +generate a patch, which will be saved in +package/<pkgname>/patches+ and automatically applied on the next clean rebuild: -------------------- $ make package=<pkgname> update-patches @@ -67,20 +67,29 @@ Environment variables ~~~~~~~~~~~~~~~~~~~~~ OpenADK also honors some environment variables, when they are passed -to +make+. +to +make+. The most useful and common ones are: +* +ADK_APPLIANCE+, the appliance task you want to build +* +ADK_CUSTOM_TASKS_DIR+, extra directory to fetch tasks from +* +ADK_TARGET_OS+, the operating system of the target system * +ADK_TARGET_ARCH+, the architecture of the target system +* +ADK_TARGET_CPU+, the specific CPU optimization for the target system (f.e. cortex-a53) * +ADK_TARGET_SYSTEM+, the embedded target system name * +ADK_TARGET_LIBC+, the C library for the target system +* +ADK_TARGET_ABI+, the ABI for the target system (f.e. MIPS N64) +* +ADK_TARGET_ENDIAN+, the endianess for the target system (little/big) +* +ADK_TARGET_BINFMT+, the binary format for the target system (f.e. ELF/FLAT/FDPIC) +* +ADK_TARGET_FLOAT+, the float support for the target system (f.e. soft/softfp/hard) +* +ADK_TARGET_FS+, the firmware type or root filesystem for the target system * +ADK_VERBOSE+, verbose build, when set to 1 + An example that creates a configuration file for Raspberry PI with all software packages enabled, but not included in the resulting firmware image: -------------------- - $ make ADK_TARGET_ARCH=arm ADK_TARGET_SYSTEM=raspberry-pi ADK_TARGET_LIBC=musl allmodconfig + $ make ADK_APPLIANCE=new ADK_TARGET_ARCH=arm ADK_TARGET_SYSTEM=raspberry-pi ADK_TARGET_LIBC=musl allmodconfig -------------------- This is often used in the development process of a target system, to verify that all packages are compilable. - diff --git a/docs/configure.txt b/docs/configure.txt index 5dd4690fb..9414302e8 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -38,11 +38,11 @@ target system uses ARM, the regular compilation toolchain on your host runs on x86 and generates code for x86, while the cross-compilation toolchain runs on x86 and generates code for ARM. -You can choose between four C libraries: +You can choose between three C libraries: http://www.uclibc-ng.org[uClibc-ng], -http://www.uclibc.org[uClibc], -http://www.gnu.org/software/libc/libc.html[glibc] and -http://www.musl-libc.org[musl]. +http://www.gnu.org/software/libc/libc.html[glibc], +http://www.musl-libc.org[musl] and +https://sourceware.org/newlib/[newlib]. There are some configuration options provided in +Toolchain settings+. You can enable or disable the building of following components and toolchain diff --git a/docs/contribute.txt b/docs/contribute.txt index 5a8e1fdd8..cdd66bb5a 100644 --- a/docs/contribute.txt +++ b/docs/contribute.txt @@ -7,7 +7,8 @@ Contributing to OpenADK If you want to contribute to OpenADK, you will need a git view of the project. Refer to xref:getting-openadk[] to get it. -Currently a mail to wbx@openadk.org is the central place for contribution. +You can either subscribe to the mailing list dev@openadk.org or +send an email directly to wbx@openadk.org. [[submitting-patches]] Submitting patches @@ -35,10 +36,10 @@ This will generate patch files automatically adding the +Signed-off-by+ line. Once patch files are generated, you can review/edit the commit message before submitting them using your favorite text editor. -Lastly, send/submit your patch set to the OpenADK developer: +Lastly, send/submit your patch set to the OpenADK developers: --------------------- -$ git send-email --to wbx@openadk.org *.patch +$ git send-email --to dev@openadk.org *.patch --------------------- Note that +git+ should be configured to use your mail account. diff --git a/docs/customize-busybox-config.txt b/docs/customize-busybox-config.txt index 070a0ca1e..ad156b21d 100644 --- a/docs/customize-busybox-config.txt +++ b/docs/customize-busybox-config.txt @@ -15,6 +15,6 @@ in +package/busybox/config+ and regenerate your OpenADK configuration. A change in the busybox configuration will rebuild the busybox package. If you choose another implementation of f.e. tar, which is provided by default from busybox, tar in busybox will be deactivated and the package will be -automatically rebuilded, so that your resulting firmware images or archives +automatically rebuilt, so that your resulting firmware images or archives will only contain a single tar program. Obviously just the one you have selected. diff --git a/docs/customize-kernel-config.txt b/docs/customize-kernel-config.txt index f96544dc4..44f04ef2d 100644 --- a/docs/customize-kernel-config.txt +++ b/docs/customize-kernel-config.txt @@ -5,15 +5,21 @@ Customizing the Linux kernel configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Linux kernel configuration can be customized using +make menuconfig+. -OpenADK uses a combination of Linux miniconfig feature and user defined -features to generate a valid Linux configuration for your target. -Some features and drivers are not selectable via +make menuconfig+, either -because your choosen target system does not have support for it or the -option is not implemented, yet. OpenADK uses some kind of abstraction -layer between the real full featured and complicated Linux kernel configuration -and you. It is not perfect and does include a lot of manual work in -+target/linux/config+, but it works in an acceptable way. +The Linux kernel can be configured in the following manners by choosing the +desired "Kernel configuration" option in the OpenADK configuration menu: + +* using +make menuconfig+ in conjunction with an OpenADK minimal configuration +* choosing a Linux kernel in-tree default configuration +* providing an extern kernel configuration file + +Choosing the first option, OpenADK uses a combination of Linux miniconfig +feature and user defined features to generate a valid Linux configuration for +your target. Some features and drivers are not selectable via ++make menuconfig+, either because your choosen target system does not have +support for it or the option is not implemented, yet. OpenADK uses some kind of +abstraction layer between the real full featured and complicated Linux kernel +configuration and you. It is not perfect and does include a lot of manual work +in +target/linux/config+, but it works in an acceptable way. If you just want to view the Linux configuration, which is actually used for your target, you can execute following command: @@ -46,3 +52,21 @@ bootup the system with support for your board, serial console, network card and If you need to enable some new optional drivers or features, which are not available in +make menuconfig+, you need to dig in +target/linux/config+. There is the abstraction layer for the real kernel configuration. + +The defconfig option will choose a kernel in-tree default configuration +specific to your target architecture. You won't be able to do further +customization. + +Choosing the external configuration option, the OpenADK menu will prompt for +the location of a Linux +.config+ file relative to the OpenADK root directory. +You will be able to alter the configuration by +make kernelconfig+. But the +changes will get lost unless you save your changes by executing + +--------------- + $ make savekconfig +--------------- + +after completing the Linux kernel configuration dialog. Despite this is the +most flexible way to configure the kernel, keep in mind that you are fully +responsible to enable all kernel features needed to mount your filesystems +and required by your applications. diff --git a/docs/customize-libc-config.txt b/docs/customize-libc-config.txt index ec6e50ff6..dbf3f25c4 100644 --- a/docs/customize-libc-config.txt +++ b/docs/customize-libc-config.txt @@ -5,8 +5,7 @@ Customizing the libc configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Just like xref:busybox-custom[BusyBox], http://www.uclibc.org/[uClibc] -and http://www.uclibc-ng.org/[uClibc-ng] +Just like xref:busybox-custom[BusyBox] http://www.uclibc-ng.org/[uClibc-ng] offering a lot of configuration options. They allow you to select various functionalities depending on your needs and limitations. OpenADK chooses automatically the best configuration regarding @@ -14,22 +13,21 @@ resulting code size, standard conformance, portability and GNU libc compatibility. If you still have the requirements to change the default, regenerate -a new uClibc/uClibc-ng config from the existing one: +a new uClibc-ng config from the existing one: ---------------- - $ tar xvf dl/uClibc-x.y.z.tar.bz2 - $ cd uClibc-x.y.z && patch -p1 <../toolchain/uClibc/patches-x.y.z/*.patch - $ cp ../target/<arch>/uclibc.config .config + $ tar xvf dl/uClibc-ng-x.y.z.tar.xz + $ cd uClibc-ng-x.y.z + $ cp ../target/<arch>/uclibc-ng.config .config $ make menuconfig ---------------- -Make all required changes. Then copy the newly created uClibc configuration back +Make all required changes. Then copy the newly created uClibc-ng configuration back and rebuild your targetsystem, including the toolchain components: ---------------- - $ cp .config ../target/<arch>/uclibc.config + $ cp .config ../target/<arch>/uclibc-ng.config $ cd .. && make cleandir && make ---------------- -The config is shared by uClibc and uClibc-ng. There are no customization options for GNU libc or musl available. diff --git a/docs/customize-rootfs.txt b/docs/customize-rootfs.txt index 3518d15bb..3d4f0bf7b 100644 --- a/docs/customize-rootfs.txt +++ b/docs/customize-rootfs.txt @@ -21,3 +21,9 @@ You can also point to another directory via: You can start with the example configuration files from +root_*+. The +extra+ directory will never be deleted by any clean target to avoid loss of customized configuration data. + +Another option is to configure a post-build action. This is available +in +Global settings+. It must point to a script relative to the root +of your openadk working copy. It will be invoked as part of the ++-imageinstall+ step with $ADK_TOPDIR as first argument. You can use +it e.g. to modify the +root_*+ filesystem before bundling it. diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index d4975027a..b26ee0577 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -6,6 +6,8 @@ Developer Guidelines include::writing-rules.txt[] +include::adding-boards.txt[] + include::adding-packages.txt[] include::patch-policy.txt[] diff --git a/docs/faq-troubleshooting.txt b/docs/faq-troubleshooting.txt index 84059b2f9..cd2bfc2c6 100644 --- a/docs/faq-troubleshooting.txt +++ b/docs/faq-troubleshooting.txt @@ -53,6 +53,4 @@ Why is there no web based configuration interface available? OpenADK provides a basic root filesystem for your embedded device. If you need a web based configuration interface for your own appliance, -just write one. There are plenty of possibilities. You could use -Lighttpd with PHP or an C++ application server like Tntnet. - +just write one. There are plenty of possibilities. diff --git a/docs/getting.txt b/docs/getting.txt index 0902bb6e0..59dbdb960 100644 --- a/docs/getting.txt +++ b/docs/getting.txt @@ -21,4 +21,4 @@ Or if you prefer HTTP or using Git behind a proxy: $ git clone http://git.openadk.org/openadk.git --------------------- -Or you can get a http://www.openadk.org/snapshots/[snapshot]. +Or you can get a https://snapshots.openadk.org/[snapshot]. diff --git a/docs/how-openadk-works.txt b/docs/how-openadk-works.txt index acafc7587..fa4b98c2c 100644 --- a/docs/how-openadk-works.txt +++ b/docs/how-openadk-works.txt @@ -19,7 +19,7 @@ many different parts. * The +target/+ directory contains the definitions for all the processor architectures that are supported by OpenADK. +target/linux+ contains the meta-data for the Linux kernel configuration abstraction layer and - the kernel patches + the kernel patches. * The +package/+ directory contains the Makefiles and associated files for all user-space tools and libraries that OpenADK can @@ -27,38 +27,35 @@ many different parts. is one sub-directory per package. * The +mk/+ directory contains some globally used Makefiles with - the suffix +.mk+, these are used in all other Makefile via include + the suffix +.mk+, these are used in all other Makefiles via include. * The +adk/+ directory contains the Makefiles and associated files for software related to the generation of the - host tools needed for +make menuconfig+ system + host tools needed for +make menuconfig+ system. * The +scripts/+ directory contains shell scripts for the creation of - meta-data in OpenADK, install scripts and image creation scripts + meta-data in OpenADK, install scripts and image creation scripts. -The main Makefile performs the following steps before the configuration -is done: +The configuration process is separated in following steps: -* Call the +prereq+ target to check if the host system have all required - software installed. It creates the +prereq.mk+ Makefile. +* Makefile is just a wrapper which calls the prerequisite shell script. + +* The prerequisite shell script +scripts/prereq.sh+ checks if the host + system have all required software installed and tries to build GNU make + and bash if it is missing. It creates the +prereq.mk+ Makefile. * Compile and run the OpenADK tools to generate the meta-data for the menu based configuration and creates the +package/Depends.mk+ Makefile to handle the - dependencies + dependencies. -* Starts the menu based configuration system via +make menuconfig+ +* Starts the menu based configuration system via +make menuconfig+. -The main Makefile performs the following steps, once the -configuration is done (it is mainly a wrapper for +mk/build.mk+): +The following steps are performed, once the configuration is done +(mainly implemented in +mk/build.mk+): * Create all the output directories: +host_<gnu_host_name>+, +target_<arch>_<libc>+, +build_<arch>_<libc>+, +pkg_<arch>_<libc>+, etc. -* Call the +scan-pkgs.sh+ script to find any needed optional host software, needed to compile - software the user has configured - -* Call the +create-menu+ script to generate meta-data for available systems and package collections - * Generate the host tools required for different tasks (encrypting passwords, compressing data, extracting archives, creating images, ..) diff --git a/docs/images/menuconfig-configured.png b/docs/images/menuconfig-configured.png Binary files differdeleted file mode 100644 index cad536cc9..000000000 --- a/docs/images/menuconfig-configured.png +++ /dev/null diff --git a/docs/images/menuconfig.png b/docs/images/menuconfig.png Binary files differdeleted file mode 100644 index 5624a2982..000000000 --- a/docs/images/menuconfig.png +++ /dev/null diff --git a/docs/images/openadk-appliance.png b/docs/images/openadk-appliance.png Binary files differnew file mode 100644 index 000000000..3e590b39c --- /dev/null +++ b/docs/images/openadk-appliance.png diff --git a/docs/images/openadk-arch.png b/docs/images/openadk-arch.png Binary files differnew file mode 100644 index 000000000..df00c20c4 --- /dev/null +++ b/docs/images/openadk-arch.png diff --git a/docs/images/openadk-menu.png b/docs/images/openadk-menu.png Binary files differnew file mode 100644 index 000000000..42856a3d2 --- /dev/null +++ b/docs/images/openadk-menu.png diff --git a/docs/images/openadk-system.png b/docs/images/openadk-system.png Binary files differnew file mode 100644 index 000000000..8a2b314b1 --- /dev/null +++ b/docs/images/openadk-system.png diff --git a/docs/images/openadk-target.png b/docs/images/openadk-target.png Binary files differnew file mode 100644 index 000000000..97c04d07e --- /dev/null +++ b/docs/images/openadk-target.png diff --git a/docs/images/openadk-task.png b/docs/images/openadk-task.png Binary files differnew file mode 100644 index 000000000..8a9808853 --- /dev/null +++ b/docs/images/openadk-task.png diff --git a/docs/introduction.txt b/docs/introduction.txt index 1b0c33271..8bab44a38 100644 --- a/docs/introduction.txt +++ b/docs/introduction.txt @@ -16,13 +16,22 @@ OpenADK is useful mainly for people working with embedded systems, but can be used by people playing with emulators or small netbooks needing a fast and small Linux system. +OpenADK can also be used to generate a cross-toolchain for any kind +of architecture and C library combination. It supports uClibc-ng, musl, +GNU libc and newlib. With newlib support you can build bare-metal toolchains +without need for Linux as operating system. + Embedded systems often use processors that are not the regular x86 -processors everyone is used to having in his PC. They can be PowerPC -processors, MIPS processors, ARM processors, etc. +processors everyone is used to having in his PC. + +OpenADK supports 44 different architectures: +AARCH64, Alpha, ARC, ARM, AVR32, Blackfin, C6X, CR16, CRIS, C-SKY, Epiphany, FR-V, FT32, +H8/300, HPPA, IA64, LM32, M32C, M32R, M68K, METAG, Microblaze, MIPS, MIPS64, MN10300, +Moxie, MSP430, NDS32, NIOS2, OR1K, PPC, PPC64, RISCV32, RISCV64, RX, S/390, SH, SPARC, SPARC64, Tile, +V850, X86, X86_64 and Xtensa. OpenADK supports numerous processors and their variants; it also comes -with default configurations for some embedded systems, emulators and netbooks. -(Raspberry PI, Cubox-i, Qemu, Aranym, PCEngines APU, Lemote Yeelong, IBM X40 and more) +with sample configurations for many embedded systems and emulators. OpenADK is not a Linux distribution and there are no releases or binary packages available. If you need something like that, better switch to diff --git a/docs/package-make-target.txt b/docs/package-make-target.txt index 13c498062..3f4643d17 100644 --- a/docs/package-make-target.txt +++ b/docs/package-make-target.txt @@ -47,6 +47,8 @@ Additionally, there are some other useful make targets: | +clean+ | Remove the whole package build directory -| +host-package+ | Build and install the host binaries and libraries +| +hostclean+ | Remove the whole hostpackage build directory + +| +hostpackage+ | Build and install the host binaries and libraries |=================================================== diff --git a/docs/package-reference.txt b/docs/package-reference.txt index 53bccb3bd..29c4208d0 100644 --- a/docs/package-reference.txt +++ b/docs/package-reference.txt @@ -12,7 +12,7 @@ information is: * +PKG_RELEASE+, mandatory, must contain the OpenADK specific release of the package. -* +PKG_MD5SUM+, mandatory, must contain the MD5 hash of the package, will be used +* +PKG_HASH+, mandatory, must contain the SHA256 hash of the package, will be used to check if a download of a package is complete. * +PKG_SECTION+, mandatory, must contain the OpenADK specific section, see package/section.lst. @@ -44,10 +44,18 @@ information is: installed before the configuration of the current package starts. * +PKG_DEPENDS+ optional, lists the runtime dependencies that are required to - run the software package on the target. It conatins a list of package names, + run the software package on the target. It contains a list of package names, which might be different to the package directory name. See what is used in PKG_template, to find out the package name used here. +* +PKG_KDEPENDS+ optional, lists the kernel module dependencies that are required to + run the software package on the target. It contains a list of kernel module names + in lower case as used in +target/linux/config+. (use minus instead of underscores) + +* +PKG_NEEDS+ optional, lists the features that are required to build or + run the software package on the target. It contains a list of keywords. + Supported are +threads+ +mmu+ +intl+ and +c+++ + * +PKG_NOPARALLEL+ optional, may be set to 1, to disable parallel building of the package via make -jn, n=4 is default, but can be changed in +Global Settings+ in the menu based configuration. @@ -61,10 +69,6 @@ information is: +STAGING_TARGET_DIR/scripts+, required for automake/autoconf package +noremove+ do not automatically remove package files from +STAGING_TARGET_DIR+ -* +PKG_NEED_CXX+ optional, package need C++ compiler - -* +PKG_CXX+ optional, package can use either `uClibc++` or `libstdc++` - The recommended way to define these variables is to use the following syntax: @@ -100,7 +104,7 @@ different steps of the configure, build and install process. * +MAKE_ENV+ add additional variables to build step -* +MAKE_FLAGS+ add additinal make flags to build step +* +MAKE_FLAGS+ add additional make flags to build step * +FAKE_FLAGS+ add additional make flags to fake install step @@ -108,15 +112,15 @@ different steps of the configure, build and install process. * +INSTALL_STYLE+ either manual or auto -* +CONFIGURE_PROG+ overwrite default configure programm +* +CONFIGURE_PROG+ override default configure program -* +MAKE_FILE+ overwrite default Makefile +* +MAKE_FILE+ override default Makefile -* +ALL_TARGET+ overwrite default build target +* +ALL_TARGET+ override default build target -* +INSTALL_TARGET+ overwrite default install target +* +INSTALL_TARGET+ override default install target -The variables to add or overwrite preprocessor, compiler and linker flags: +The variables to add or override preprocessor, compiler and linker flags: * +TARGET_CPPFLAGS+ flags for the preprocessor diff --git a/docs/patch-policy.txt b/docs/patch-policy.txt index e948661cf..bb3677d7b 100644 --- a/docs/patch-policy.txt +++ b/docs/patch-policy.txt @@ -75,7 +75,7 @@ Backported from: <some commit id> or --------------- -Fetch from: <some url> +Fetched from: <some url> --------------- It is also sensible to add a few words about any changes to the patch diff --git a/docs/prerequisite.txt b/docs/prerequisite.txt index 8209abb82..32fb77a75 100644 --- a/docs/prerequisite.txt +++ b/docs/prerequisite.txt @@ -5,44 +5,34 @@ System requirements ------------------- -OpenADK is designed to run on Linux systems. But there is basic -support to run on MacOS X Maverick, Windows 7 with Cygwin, OpenBSD, -NetBSD and FreeBSD. Main development happens on Debian/GNU Linux 7 -and MacOS X Maverick. The other host platforms are occasionally -tested. - -OpenADK detects the host system and displays only the software -packages, which are known to be cross-compilable on the used host. -For example OpenJDK7 is only cross-compilable on a Linux host. - +OpenADK is designed to run on Linux systems. +Main development happens on Debian/GNU Linux. OpenADK needs some software to be already installed on the host system; here is the list of the mandatory packages, -package names may vary between host systems. +package names may vary between Linux systems. * Build tools: -** +bash+ ** +binutils+ ** +C compiler (gcc or clang)+ ** `C++ compiler (g++ or clang++)` -** +GNU make+ +** +make+ ** +gzip+ ** +perl+ ** +tar+ -** +wget+ -** +ncurses5 development files+ -** +zlib development files+ +** +git+ +** +strings+ +** +curl or wget+ +** +xz+ +** +ncurses development files+ +** +zlib development files+ ** +libc development files+ There is a check for the required versions of these tools in advance, -though. To re-issue the checks, use +make prereq+. +though. For some packages there are some optional packages required. OpenADK will check for the required tools in advance, when a specific package is choosen. For example Kodi needs Java installed on the host system. OpenADK tries to avoid any optional required host tools and will try to build them when needed. - -For some host systems you can try to use ./scripts/adkprepare.sh to -install all required software. You need to run the script as root, it -will use the package management of your host to install the software. diff --git a/docs/running-openadk.txt b/docs/running-openadk.txt index dcc7cee4e..205b0d292 100644 --- a/docs/running-openadk.txt +++ b/docs/running-openadk.txt @@ -28,14 +28,16 @@ The Linux kernel in OpenADK is intended to be very small in size and will be by default compressed with xz compression algorithm, if available for the target system. You can configure the compression algorithm used for the compression of the Linux kernel and if choosen the initramfs filesystem in -+make menuconfig+. In +Kernel configuration+ you have the choice between -dfferent kernel versions. The latest version will be automatically used. ++make menuconfig+. In +Linux Kernel configuration+ you have the choice between +dfferent kernel versions. Depending on your target devices, their might +be some external git repositories available, if the support for the device +is not upstream. There you can choose any needed addon drivers or any supported runtime and debugging features. The kernel expands itself on boot, if compressed, and then initialize the -hardware. The additional kernel modules are loaded later by a init script. -The kernel will autoamtically mount the virtual filesystem /dev as devtmpfs +hardware. The additional kernel modules are loaded later by an init script. +The kernel will automatically mount the virtual filesystem /dev as devtmpfs and then will execute +/sbin/init+ in userspace. init system @@ -46,10 +48,11 @@ carries the PID number 1), and is responsible for starting the userspace services and programs (for example: web server, graphical applications, other network servers, etc.). -OpenADK uses *Busybox* init. Amongst many programs, Busybox has an -implementation of a basic +init+ program, which is sufficient for most embedded -systems. The Busybox +init+ program will read the +/etc/inittab+ file at boot -to know what to do. The syntax of this file can be found in +In OpenADK you can choose between different init implementations. *Busybox* +init is the best tested one and the default. Amongst many programs, Busybox +has an implementation of a basic +init+ program, which is sufficient for most +embedded systems. The Busybox +init+ program will read the +/etc/inittab+ file +at boot to know what to do. The syntax of this file can be found in http://git.busybox.net/busybox/tree/examples/inittab (note that Busybox +inittab+ syntax is special: do not use a random +inittab+ documentation from the Internet to learn about Busybox +inittab+). The default +inittab+ in @@ -67,19 +70,22 @@ files_, your userspace applications would not be able to use the hardware devices, even if they are properly recognized by the Linux kernel. -OpenADK uses *dynamic device nodes using devtmpfs and mdev*. This method relies -on the _devtmpfs_ virtual filesystem in the kernel, which is enabled by default -for all OpenADK generated kernels, and adds the +mdev+ userspace utility on top -of it. +mdev+ is a program part of Busybox that the kernel will call every time -a device is added or removed. Thanks to the +/etc/mdev.conf+ configuration -file, +mdev+ can be configured to for example, set specific permissions or -ownership on a device file, call a script or application whenever a device -appears or disappear, etc. Basically, it allows _userspace_ to react on device -addition and removal events. +mdev+ is also important if you have devices that -require a firmware, as it will be responsible for pushing the firmware contents -to the kernel. +mdev+ is a lightweight implementation (with fewer features) of -+udev+. For more details about +mdev+ and the syntax of its configuration file, -see http://git.busybox.net/busybox/tree/docs/mdev.txt. +In OpenADK you can choose between different types of device managements. +OpenADK defaults to *static device nodes using devtmpfs*. That is the simplest +way available. Most users might like to change it to *dynamic device nodes +using devtmpfs and mdev*. This method relies on the _devtmpfs_ virtual +filesystem in the kernel, which is enabled by default for all OpenADK generated +kernels, and adds the +mdev+ userspace utility on top of it. +mdev+ is a +program part of Busybox that the kernel will call every time a device is added +or removed. Thanks to the +/etc/mdev.conf+ configuration file, +mdev+ can be +configured to for example, set specific permissions or ownership on a device +file, call a script or application whenever a device appears or disappear, etc. +Basically, it allows _userspace_ to react on device addition and removal +events. +mdev+ is also important if you have devices that require a firmware, +as it will be responsible for pushing the firmware contents to the kernel. ++mdev+ is a lightweight implementation (with fewer features) of +udev+. For +more details about +mdev+ and the syntax of its configuration file, see +http://git.busybox.net/busybox/tree/docs/mdev.txt. initscripts ~~~~~~~~~~~ @@ -141,7 +147,7 @@ manager (f.e. ipkg) will be reported. --------------------- cfgfs -Configuration Filesystem Utility (cfgfs), Version 1.09 +Configuration Filesystem Utility (cfgfs) Syntax: /sbin/cfgfs commit [-f] /sbin/cfgfs erase @@ -173,8 +179,29 @@ In both cases the default user is +root+ and the default password is either via +passwd+ on the system or you can preconfigure a password via +make menuconfig+ under +Runtime configuration+. -The default shell used in OpenADK is +mksh+ from http://www.mirbsd.org/mksh/. +The default shell used in OpenADK is +mksh+ from http://www.mirbsd.org/mksh.htm. You can change the shell in +make menuconfig+ under +Runtime configuration+. Be aware of the fact that the bootup process might use some +mksh+ features to speedup the system start. When you change the shell for system +/bin/sh+ the slower startup is used as a fallback. + +analyzing logs +~~~~~~~~~~~~~~ + +Since embedded systems usually avoid writing continously on non-volatile storage +(to avoid waer-out of the storage device) there are no logfiles under /var/log and +/var itself is mapped onto a RAM based filesystem. + +Instead the syslog daemon logs into a ciruclar memory +buffer. The size of the memory buffer is by default 32KiB and can be changed in the +busybox configuration. + +To access the content of the buffer the +logread+ utility is used to dump the buffer. +To get a continous output of the logbuffer -f has to be added as option. + +--------------------- +Usage: logread [-fF] + +-f Output data as log grows +-F Same as -f, but dump buffer first +--------------------- diff --git a/docs/using.txt b/docs/using.txt index 7cf109609..96642f8e8 100644 --- a/docs/using.txt +++ b/docs/using.txt @@ -18,16 +18,29 @@ assistant: For each menu entry in the configuration tool, you can find associated help that describes the purpose of the entry. -image::menuconfig.png[] +image::openadk-menu.png[] -First of all you need to choose your target architecture, your target -system, your target C library, your target firmware type and your target -package format. After that you can select individual packages and kernel -settings or just use one of the predefined package collections. When you -are ready exit and save. You can always redefine the configuration -using +make menuconfig+. +First of all you need to choose if you want to build a Linux firmware +or a bare-metal toolchain. Linux is choosen as default. -image::menuconfig-configured.png[] +image::openadk-arch.png[] + +After that you should select your target architecture. + +image::openadk-system.png[] + +Now you can select your target system, endianess, cpu and other stuff. + +image::openadk-task.png[] + +If you want to compile some predefined appliance tasks, you can select it in +Tasks+. +You can later simply add your own tasks, which is a collection of options, packages, +kernel modules or features, runtime configuration and more. They can either be placed +inside the +tasks+ directory or in your own custom directory that you pass via ++ADK_CUSTOM_TASKS_DIR+ to make. + +When you are ready exit and save. You can always redefine the +configuration using +make menuconfig+. Once everything is configured, the configuration tool generates a +.config+ file that contains the description of your configuration. It @@ -57,9 +70,11 @@ OpenADK output is stored in several subdirectories: * +firmware/+ where all the images and packages are stored. -* +build_<system>_<arch>_<libc>/+ where all the components except for the cross-compilation toolchain are built. The directory contains one subdirectory for each of these components. +* +build_<system>_<libc>_<arch>_<abi>/+ where all the components except for the + cross-compilation toolchain are built. The directory contains one + subdirectory for each of these components. -* +target_<arch>_<libc>/+ which contains a hierarchy similar to a root filesystem +* +target_<system>_<libc>_<arch>_<abi>/+ which contains a hierarchy similar to a root filesystem hierarchy. This directory contains the installation of the cross-compilation toolchain and all the userspace packages selected for the target. However, this directory is 'not' intended to be @@ -69,7 +84,7 @@ OpenADK output is stored in several subdirectories: libraries and applications for the target that depend on other libraries. -* +root_<system>_<arch>_<libc>/+ which contains the complete root filesystem for +* +root_<system>_<libc>_<arch>_<abi>/+ which contains the complete root filesystem for the target. One exception, it doesn't have the correct permissions (e.g. setuid for the busybox binary) for some files. Therefore, this directory *should not be used on your target*. @@ -85,18 +100,21 @@ OpenADK output is stored in several subdirectories: * +host_<gnu_host_name>/+ contains the installation of tools compiled for the host that are needed for the proper execution of OpenADK -* +toolchain_<gnu_host_name>/+ contains just the cross-compilation toolchain. - Can be used together with +target_<arch>_<libc>/+ for other projects. Toolchain +* +host_build_<gnu_host_name>/+ contains the build directories of tools compiled for the host + that are needed for the proper execution of OpenADK + +* +toolchain_<system>_<libc>_<arch>_<abi>>/+ contains just the cross-compilation toolchain. + Can be used together with +target_<system>_<libc>_<arch>_<abi>/+ for other projects. Toolchain is relocatable. -* +toolchain_build_<arch>_<libc>/+ contains the build directories for the various +* +toolchain_build_<system>_<libc>_<arch>_<abi>/+ contains the build directories for the various components of the cross-compilation toolchain. -* +pkg_<system>_<arch>_<libc>/+ contains stamp files and file lists for the various components. +* +pkg_<system>_<libc>_<arch>_<abi>/+ contains stamp files and file lists for the various components. The command, +make menuconfig+ and +make+, are the basic ones that allow to easily and quickly generate images fitting -your needs, with all the supports and applications you enabled. +your needs, with all the applications you enabled. More details about the "make" command usage are given in xref:make-tips[]. diff --git a/docs/working-with.txt b/docs/working-with.txt index 9e101d28f..2bc155b06 100644 --- a/docs/working-with.txt +++ b/docs/working-with.txt @@ -21,5 +21,6 @@ Hacking OpenADK If OpenADK does not yet fit all your requirements, you may be interested in hacking it to add: -* new packages: refer to the xref:adding-packages[Developer guide] +* new embedded targets: refer to the xref:adding-boards[Adding new boards] +* new packages: refer to the xref:adding-packages[Adding new packages] diff --git a/docs/writing-rules.txt b/docs/writing-rules.txt index e24ff4a5c..60f496eaf 100644 --- a/docs/writing-rules.txt +++ b/docs/writing-rules.txt @@ -21,8 +21,7 @@ An entry has the following pattern: --------------------- config ADK_TARGET_FOO - prompt "foo" - boolean + bool "foo" select BR2_PACKAGE_LIBBAR depends on ADK_PACKAGE_LIBBAZ default n @@ -32,14 +31,14 @@ config ADK_TARGET_FOO http://foo.org/foo/ --------------------- -* The +boolean+, +depends on+, +default+, +select+ and +help+ lines are indented +* The +bool+, +depends on+, +default+, +select+ and +help+ lines are indented with one tab. * The help text itself should be indented with one tab and two spaces. The +Config.in+ files are the input for the configuration tool -used in OpenADK, which is the regular _Kconfig_. For further +used in OpenADK, which is an enhanced version of _Kconfig_. For further details about the _Kconfig_ language, refer to http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[]. |
