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 +Linux Kernel configuration+ you have the choice between
  32 dfferent kernel versions. Depending on your target devices, their might
  33 be some external git repositories available, if the support for the device
  34 is not upstream.
  35 There you can choose any needed addon drivers or any supported runtime
  36 and debugging features.
  37
  38 The kernel expands itself on boot, if compressed, and then initialize the
  39 hardware. The additional kernel modules are loaded later by an init script.
  40 The kernel will automatically mount the virtual filesystem /dev as devtmpfs
  41 and then will execute +/sbin/init+ in userspace.
  42
  43 init system
  44 ~~~~~~~~~~~
  45
  46 The _init_ program is the first userspace program started by the kernel (it
  47 carries the PID number 1), and is responsible for starting the userspace
  48 services and programs (for example: web server, graphical applications, other
  49 network servers, etc.).
  50
  51 In OpenADK you can choose between different init implementations. *Busybox*
  52 init is the best tested one and the default. Amongst many programs, Busybox
  53 has an implementation of a basic +init+ program, which is sufficient for most
  54 embedded systems. The Busybox +init+ program will read the +/etc/inittab+ file
  55 at boot to know what to do. The syntax of this file can be found in
  56 http://git.busybox.net/busybox/tree/examples/inittab (note that Busybox
  57 +inittab+ syntax is special: do not use a random +inittab+ documentation from
  58 the Internet to learn about Busybox +inittab+). The default +inittab+ in
  59 OpenADK is generated while producing the +base-files+ package.  The main job
  60 the default inittab does is to start the +/etc/init.d/rcS+ shell script, and
  61 start one or more +getty+ programs (which provides a login prompt).
  62
  63 /dev management
  64 ~~~~~~~~~~~~~~~
  65
  66 On a Linux system, the +/dev+ directory contains special files, called
  67 _device files_, that allow userspace applications to access the
  68 hardware devices managed by the Linux kernel. Without these _device
  69 files_, your userspace applications would not be able to use the
  70 hardware devices, even if they are properly recognized by the Linux
  71 kernel.
  72
  73 In OpenADK you can choose between different types of device managements.
  74 OpenADK defaults to *static device nodes using devtmpfs*. That is the simplest
  75 way available. Most users might like to change it to *dynamic device nodes
  76 using devtmpfs and mdev*. This method relies on the _devtmpfs_ virtual
  77 filesystem in the kernel, which is enabled by default for all OpenADK generated
  78 kernels, and adds the +mdev+ userspace utility on top of it. +mdev+ is a
  79 program part of Busybox that the kernel will call every time a device is added
  80 or removed. Thanks to the +/etc/mdev.conf+ configuration file, +mdev+ can be
  81 configured to for example, set specific permissions or ownership on a device
  82 file, call a script or application whenever a device appears or disappear, etc.
  83 Basically, it allows _userspace_ to react on device addition and removal
  84 events. +mdev+ is also important if you have devices that require a firmware,
  85 as it will be responsible for pushing the firmware contents to the kernel.
  86 +mdev+ is a lightweight implementation (with fewer features) of +udev+. For
  87 more details about +mdev+ and the syntax of its configuration file, see
  88 http://git.busybox.net/busybox/tree/docs/mdev.txt.
  89
  90 initscripts
  91 ~~~~~~~~~~~
  92
  93 The /etc/init.d/rcS script will execute all shell scripts in /etc/init.d in
  94 order with the parameter +autostart+. The order is identified by the +#INIT+
  95 comment in the script. All scripts are sourcing the +/etc/rc.conf+ file to
  96 determine if a service should be started on boot and which flags if any are
  97 used for the service. By default all services are disabled. If the variable
  98 for a service is set to "DAEMON" and mksh is installed, the service starts
  99 asynchronously in the background. Most scripts provided by OpenADK via
 100 +package/<pkgname>/files/<pkgname>.init+ are like:
 101
 102 ---------------------
 103 #!/bin/sh
 104 #PKG foo
 105 #INIT 60
 106
 107 . /etc/rc.conf
 108
 109 case $1 in
 110 autostop) ;;
 111 autostart)
 112         test x"${foo:-NO}" = x"NO" && exit 0
 113         test x"$foo" = x"DAEMON" && test -x /bin/mksh && exec mksh -T- $0 start
 114         exec sh $0 start
 115         ;;
 116 start)
 117         /usr/sbin/foo $foo_flags
 118         ;;
 119 stop)
 120         kill $(pgrep -f /usr/sbin/foo )
 121         ;;
 122 restart)
 123         sh $0 stop
 124         sh $0 start
 125         ;;
 126 *)
 127         echo "usage: $0 (start|stop|restart)"
 128         exit 1
 129 esac
 130 exit $?
 131 ---------------------
 132
 133 cfgfs - configuration file system
 134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 135
 136 The cfgfs application for the OpenADK system uses a special small partition on
 137 the block device of your embedded system (f.e. flash, sd card, compact flash
 138 or hard disk). Only changes made to /etc on your embedded system are saved in a
 139 compressed form (using LZO1 compression algorithm) in this partition. There is
 140 no Linux filesystem on this partition. The embedded system initialization
 141 process will setup /etc correctly on boot up, when cfgfs application is found.
 142 After making any changes to /etc, which should survive a reboot of the embedded
 143 system must be written to the cfgfs partition via “cfgfs commit”. Trying to
 144 reboot, shutdown or halt an embedded system with unsaved changes will generate
 145 an error, which can be circumvented. Updates to /etc via a package
 146 manager (f.e. ipkg) will be reported.
 147
 148 ---------------------
 149 cfgfs
 150 Configuration Filesystem Utility (cfgfs)
 151 Syntax:
 152         /sbin/cfgfs commit [-f]
 153         /sbin/cfgfs erase
 154         /sbin/cfgfs setup [-N]
 155         /sbin/cfgfs status [-rq]
 156         /sbin/cfgfs { dump | restore } [<filename>]
 157 ---------------------
 158
 159 network configuration
 160 ~~~~~~~~~~~~~~~~~~~~~
 161
 162 On bootup +/etc/network/interfaces+ is used to find out which network configuration
 163 should be used. The default is to use DHCP (via busybox +udhcpc+) on the first found
 164 ethernet device to configure the network. See network configuration for detailed syntax
 165 of +/etc/network/interfaces+. It is similar to Debian network configuration and uses
 166 +ifupdown+ from +busybox+.
 167
 168 See Appendix xref:network-configuration[]
 169
 170 getting a shell on the system
 171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 172
 173 There are two methods available to get a shell on your embedded system created with
 174 OpenADK. You can either login locally via serial console or graphical console or you
 175 can login remotely via secure shell.
 176
 177 In both cases the default user is +root+ and the default password is
 178 +linux123+. *You should always change the default password!!* You can do this
 179 either via +passwd+ on the system or you can preconfigure a password via +make
 180 menuconfig+ under +Runtime configuration+.
 181
 182 The default shell used in OpenADK is +mksh+ from http://www.mirbsd.org/mksh.htm.
 183 You can change the shell in +make menuconfig+ under +Runtime configuration+. Be
 184 aware of the fact that the bootup process might use some +mksh+ features to
 185 speedup the system start. When you change the shell for system +/bin/sh+ the
 186 slower startup is used as a fallback.
 187
 188 analyzing logs
 189 ~~~~~~~~~~~~~~
 190
 191 Since embedded systems usually avoid writing continously on non-volatile storage
 192 (to avoid waer-out of the storage device) there are no logfiles under /var/log and
 193 /var itself is mapped onto a RAM based filesystem.
 194
 195 Instead the syslog daemon logs into a ciruclar memory
 196 buffer. The size of the memory buffer is by default 32KiB and can be changed in the
 197 busybox configuration.
 198
 199 To access the content of the buffer the +logread+ utility is used to dump the buffer.
 200 To get a continous output of the logbuffer -f has to be added as option.
 201
 202 ---------------------
 203 Usage: logread [-fF]
 204
 205 -f Output data as log grows
 206 -F Same as -f, but dump buffer first
 207 ---------------------