docs/running-openadk.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 Running OpenADK created Linux firmware
   5 ======================================
   6
   7 Bootloader
   8 ~~~~~~~~~~~
   9
  10 The Bootloader is used to initialize the machine and load the Linux kernel.
  11 A list of popular Bootloaders can be found on http://elinux.org/Bootloader.
  12 OpenADK provides the Bootloader if necessary for a target system.
  13 You can find them in +make menuconfg+ under +Packages/Bootloader+.
  14 Some Bootloaders require the Linux kernel in a special format (SREC, ELF, ..),
  15 compressed or with a special header. This will be automatically done by
  16 OpenADK in +target/<arch>/Makefile+ while creating the firmware archives or
  17 images.
  18
  19 Linux kernel
  20 ~~~~~~~~~~~~
  21
  22 The kernel is a program that constitutes the central core of a computer
  23 operating system. It has complete control over everything that occurs in the
  24 system. The Bootloader can provide some basic runtime configuration
  25 parameters via the kernel commandline feature.
  26
  27 The Linux kernel in OpenADK is intended to be very small in size and will
  28 be by default compressed with xz compression algorithm, if available for
  29 the target system. You can configure the compression algorithm used for the
  30 compression of the Linux kernel and if choosen the initramfs filesystem in
  31 +make menuconfig+. In +Kernel configuration+ you have the choice between
  32 dfferent kernel versions. The latest stable OpenADK version will be automatically used.
  33 There you can choose any needed addon drivers or any supported runtime
  34 and debugging features.
  35
  36 The kernel expands itself on boot, if compressed, and then initialize the
  37 hardware. The additional kernel modules are loaded later by a init script.
  38 The kernel will autoamtically mount the virtual filesystem /dev as devtmpfs
  39 and then will execute +/sbin/init+ in userspace.
  40
  41 init system
  42 ~~~~~~~~~~~
  43
  44 The _init_ program is the first userspace program started by the kernel (it
  45 carries the PID number 1), and is responsible for starting the userspace
  46 services and programs (for example: web server, graphical applications, other
  47 network servers, etc.).
  48
  49 OpenADK uses *Busybox* init. Amongst many programs, Busybox has an
  50 implementation of a basic +init+ program, which is sufficient for most embedded
  51 systems. The Busybox +init+ program will read the +/etc/inittab+ file at boot
  52 to know what to do. The syntax of this file can be found in
  53 http://git.busybox.net/busybox/tree/examples/inittab (note that Busybox
  54 +inittab+ syntax is special: do not use a random +inittab+ documentation from
  55 the Internet to learn about Busybox +inittab+). The default +inittab+ in
  56 OpenADK is generated while producing the +base-files+ package.  The main job
  57 the default inittab does is to start the +/etc/init.d/rcS+ shell script, and
  58 start one or more +getty+ programs (which provides a login prompt).
  59
  60 /dev management
  61 ~~~~~~~~~~~~~~~
  62
  63 On a Linux system, the +/dev+ directory contains special files, called
  64 _device files_, that allow userspace applications to access the
  65 hardware devices managed by the Linux kernel. Without these _device
  66 files_, your userspace applications would not be able to use the
  67 hardware devices, even if they are properly recognized by the Linux
  68 kernel.
  69
  70 OpenADK uses *dynamic device nodes using devtmpfs and mdev*. This method relies
  71 on the _devtmpfs_ virtual filesystem in the kernel, which is enabled by default
  72 for all OpenADK generated kernels, and adds the +mdev+ userspace utility on top
  73 of it. +mdev+ is a program part of Busybox that the kernel will call every time
  74 a device is added or removed. Thanks to the +/etc/mdev.conf+ configuration
  75 file, +mdev+ can be configured to for example, set specific permissions or
  76 ownership on a device file, call a script or application whenever a device
  77 appears or disappear, etc. Basically, it allows _userspace_ to react on device
  78 addition and removal events. +mdev+ is also important if you have devices that
  79 require a firmware, as it will be responsible for pushing the firmware contents
  80 to the kernel. +mdev+ is a lightweight implementation (with fewer features) of
  81 +udev+. For more details about +mdev+ and the syntax of its configuration file,
  82 see http://git.busybox.net/busybox/tree/docs/mdev.txt.
  83
  84 initscripts
  85 ~~~~~~~~~~~
  86
  87 The /etc/init.d/rcS script will execute all shell scripts in /etc/init.d in
  88 order with the parameter +autostart+. The order is identified by the +#INIT+
  89 comment in the script. All scripts are sourcing the +/etc/rc.conf+ file to
  90 determine if a service should be started on boot and which flags if any are
  91 used for the service. By default all services are disabled. If the variable
  92 for a service is set to "DAEMON" and mksh is installed, the service starts
  93 asynchronously in the background. Most scripts provided by OpenADK via
  94 +package/<pkgname>/files/<pkgname>.init+ are like:
  95
  96 ---------------------
  97 #!/bin/sh
  98 #PKG foo
  99 #INIT 60
 100
 101 . /etc/rc.conf
 102
 103 case $1 in
 104 autostop) ;;
 105 autostart)
 106         test x"${foo:-NO}" = x"NO" && exit 0
 107         test x"$foo" = x"DAEMON" && test -x /bin/mksh && exec mksh -T- $0 start
 108         exec sh $0 start
 109         ;;
 110 start)
 111         /usr/sbin/foo $foo_flags
 112         ;;
 113 stop)
 114         kill $(pgrep -f /usr/sbin/foo )
 115         ;;
 116 restart)
 117         sh $0 stop
 118         sh $0 start
 119         ;;
 120 *)
 121         echo "usage: $0 (start|stop|restart)"
 122         exit 1
 123 esac
 124 exit $?
 125 ---------------------
 126
 127 cfgfs - configuration file system
 128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 129
 130 The cfgfs application for the OpenADK system uses a special small partition on
 131 the block device of your embedded system (f.e. flash, sd card, compact flash
 132 or hard disk). Only changes made to /etc on your embedded system are saved in a
 133 compressed form (using LZO1 compression algorithm) in this partition. There is
 134 no Linux filesystem on this partition. The embedded system initialization
 135 process will setup /etc correctly on boot up, when cfgfs application is found.
 136 After making any changes to /etc, which should survive a reboot of the embedded
 137 system must be written to the cfgfs partition via “cfgfs commit”. Trying to
 138 reboot, shutdown or halt an embedded system with unsaved changes will generate
 139 an error, which can be circumvented. Updates to /etc via a package
 140 manager (f.e. ipkg) will be reported.
 141
 142 ---------------------
 143 cfgfs
 144 Configuration Filesystem Utility (cfgfs), Version 1.09
 145 Syntax:
 146         /sbin/cfgfs commit [-f]
 147         /sbin/cfgfs erase
 148         /sbin/cfgfs setup [-N]
 149         /sbin/cfgfs status [-rq]
 150         /sbin/cfgfs { dump | restore } [<filename>]
 151 ---------------------
 152
 153 network configuration
 154 ~~~~~~~~~~~~~~~~~~~~~
 155
 156 On bootup +/etc/network/interfaces+ is used to find out which network configuration
 157 should be used. The default is to use DHCP (via busybox +udhcpc+) on the first found
 158 ethernet device to configure the network. See network configuration for detailed syntax
 159 of +/etc/network/interfaces+. It is similar to Debian network configuration and uses
 160 +ifupdown+ from +busybox+.
 161
 162 See Appendix xref:network-configuration[]
 163
 164 getting a shell on the system
 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 166
 167 There are two methods available to get a shell on your embedded system created with
 168 OpenADK. You can either login locally via serial console or graphical console or you
 169 can login remotely via secure shell.
 170
 171 In both cases the default user is +root+ and the default password is
 172 +linux123+. *You should always change the default password!!* You can do this
 173 either via +passwd+ on the system or you can preconfigure a password via +make
 174 menuconfig+ under +Runtime configuration+.
 175
 176 The default shell used in OpenADK is +mksh+ from http://www.mirbsd.org/mksh/.
 177 You can change the shell in +make menuconfig+ under +Runtime configuration+. Be
 178 aware of the fact that the bootup process might use some +mksh+ features to
 179 speedup the system start. When you change the shell for system +/bin/sh+ the
 180 slower startup is used as a fallback.