running-openadk.txt 8.6 KB

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