running-openadk.txt 7.6 KB

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