paul@3 | 1 | {{infobox|This is currently a work in progress. The objective is to make a reliable set of instructions that can be used to provide a directly bootable Emdebian system. See the [[#Further Work|"Further Work"]] section for areas of improvement.}}
|
paul@3 | 2 |
|
paul@3 | 3 | [http://www.emdebian.org/ Emdebian] is a project that provides cross-compilation toolchains, tools for cross-building packages, and tools for making root filesystems for deployment on devices, particularly embedded devices with "foreign" architectures. Such tools permit the time-consuming and resource-intensive work of preparing a system image to be done on "normal" personal computers and workstations, with the finished result then being deployed on the target device.
|
paul@3 | 4 |
|
paul@3 | 5 | Where Emdebian differs from other projects and toolchains is in its relationship to Debian. It is able to draw upon the extensive selection of Debian packages that are already available, up-to-date, and maintained for a selection of architectures. This means that it should be possible to benefit from the considerable effort invested in Debian packaging by the community and be able to obtain usable packages for specific technologies without being obliged to take on the work of tracking upstream development, dependency relationships, fixing portability issues, and performing packaging work just to be able to use some particular piece of software.
|
paul@3 | 6 |
|
paul@3 | 7 | == The Workflow ==
|
paul@3 | 8 |
|
paul@3 | 9 | Making an installable Emdebian system involves the following steps:
|
paul@3 | 10 |
|
paul@3 | 11 | # Obtain the necessary tools.
|
paul@3 | 12 | # Obtain a kernel image.
|
paul@3 | 13 | # Choose a suitable configuration.
|
paul@3 | 14 | # Prepare a root filesystem.
|
paul@3 | 15 | # Configure the installation.
|
paul@3 | 16 | # Format the boot medium.
|
paul@3 | 17 | # Complete the installation.
|
paul@3 | 18 | # Boot into the new system.
|
paul@3 | 19 |
|
paul@3 | 20 | === Obtaining the Tools ===
|
paul@3 | 21 |
|
paul@3 | 22 | To prepare a root filesystem, the [http://wiki.debian.org/Multistrap multistrap] tool is needed. On Debian-based systems, this tool should be available from the usual package repository, and can thus be installed as follows:
|
paul@3 | 23 |
|
paul@3 | 24 | apt-get install multistrap
|
paul@3 | 25 |
|
paul@3 | 26 | Since multistrap is under active development, it may be the case that a later version of the tool is required. If this proves to be the case when following these instructions, you may need to enable the appropriate "backports" repository (using <code>/etc/apt/sources.list</code> and/or <code>/etc/apt/sources.d</code>), update the packaging system...
|
paul@3 | 27 |
|
paul@3 | 28 | apt-get update
|
paul@3 | 29 |
|
paul@12 | 30 | ...and then try to install such a newer version. If no readily available newer version exists in a usable repository, you may need to backport the package from a later Debian release. Such an activity is currently outside the scope of this document.
|
paul@3 | 31 |
|
paul@3 | 32 | ==== Downloads ====
|
paul@3 | 33 |
|
paul@3 | 34 | The scripts and files related to this activity are provided in the following archive:
|
paul@3 | 35 |
|
paul@3 | 36 | [[File:Qi-emdebian.tar.gz]]
|
paul@3 | 37 |
|
paul@3 | 38 | A [http://hgweb.boddie.org.uk/qi-emdebian repository] also provides the scripts and files in their different versions.
|
paul@3 | 39 |
|
paul@3 | 40 | === Obtaining a Kernel Image ===
|
paul@3 | 41 |
|
paul@3 | 42 | It can be easier to obtain an existing kernel image prepared by the [[Building Software Image|OpenWrt-based toolchain]], typically called <code>openwrt-xburst-qi_lb60-uImage.bin</code> and found in the [http://downloads.qi-hardware.com/software/images/NanoNote/Ben/ software image release folders].
|
paul@3 | 43 |
|
paul@3 | 44 | With the existing available kernels, there should be no need for any kernel modules to get started. However, the intention is to provide a more reliable way of obtaining the kernel and any additional modules using either the appropriate Debian packages or through other methods.
|
paul@3 | 45 |
|
paul@3 | 46 | === Choosing a Configuration ===
|
paul@3 | 47 |
|
paul@12 | 48 | The multistrap package and documentation provide several example configurations. However, a specific configuration for the NanoNote should look like this for the Debian Jessie release:
|
paul@3 | 49 |
|
paul@3 | 50 | <pre>
|
paul@3 | 51 | [General]
|
paul@3 | 52 | arch=mipsel
|
paul@3 | 53 | cleanup=true
|
paul@3 | 54 | noauth=false
|
paul@12 | 55 | bootstrap=Debian
|
paul@12 | 56 | aptsources=Debian
|
paul@3 | 57 |
|
paul@3 | 58 | [Debian]
|
paul@12 | 59 | packages=udev busybox-static
|
paul@3 | 60 | source=http://ftp.debian.org/debian
|
paul@3 | 61 | keyring=debian-archive-keyring
|
paul@12 | 62 | suite=jessie
|
paul@3 | 63 | </pre>
|
paul@3 | 64 |
|
paul@13 | 65 | This minimal configuration installs a base system from Debian packages. (Previously, qi-emdebian used special Emdebian Grip packages which were meant to be smaller than conventional Debian packages, but the Emdebian project considered the effort of producing such packages for an arguably marginal benefit to be a costly distraction from other work.) In addition, the <code>udev</code> and <code>busybox-static</code> packages are added; this latter package is essential for the initial configuration of the system. Various other packages may be needed in practice, and so example files for various distributions are provided in the [http://hgweb.boddie.org.uk/qi-emdebian/file/tip/conf qi-emdebian distribution] for guidance.
|
paul@5 | 66 |
|
paul@3 | 67 | === Preparing a Root Filesystem ===
|
paul@3 | 68 |
|
paul@12 | 69 | With a suitable configuration file called, for example, <code>multistrap-jessie-mipsel.conf</code> a root filesystem can be constructed in a location such as <code>rootfs</code> as follows. Note that you must be <code>root</code> or use <code>sudo</code> for this to work properly. Multistrap may ask for elevated privileges.
|
paul@3 | 70 |
|
paul@12 | 71 | multistrap -f multistrap-jessie-mipsel.conf -d rootfs
|
paul@3 | 72 |
|
paul@8 | 73 | If this operation fails with errors related to repository public keys, you may need to install a newer version of multistrap as described above. A selection of configuration files can be found in the <code>conf</code> directory in the qi-emdebian distribution.
|
paul@3 | 74 |
|
paul@3 | 75 | === Configuring the Installation ===
|
paul@3 | 76 |
|
paul@3 | 77 | On its own, multistrap does not provide all the files required for a running system. Moreover, a filesystem prepared by the tool will not be configured, and any attempt to boot into such a filesystem will probably fail. Thus, additional configuration must be performed.
|
paul@3 | 78 |
|
paul@3 | 79 | ==== Conventional Configuration Files ====
|
paul@3 | 80 |
|
paul@3 | 81 | A number of configuration files, missing from the root filesystem, must be defined for the installation:
|
paul@3 | 82 |
|
paul@3 | 83 | * <code>/etc/fstab</code>
|
paul@5 | 84 | * <code>/etc/hostname</code>
|
paul@3 | 85 | * <code>/etc/network/interfaces</code>
|
paul@5 | 86 | * <code>/etc/resolv.conf</code>
|
paul@3 | 87 |
|
paul@5 | 88 | Such files can be placed in a directory called, for example, <code>files</code> while retaining the necessary filesystem structure, so that <code>fstab</code> would reside at <code>files/etc/fstab</code>, and so on. This reflects their typical locations in a real system.
|
paul@3 | 89 |
|
paul@5 | 90 | ==== Pre-Initialisation Files ====
|
paul@5 | 91 |
|
paul@5 | 92 | Two additional files called <code>preinit</code> and <code>preinit-config</code> are required that "glue" the kernel to the Debian system on the first boot of the system. These files must reside in the current directory when running the script below. The <code>preinit</code> file is a convention apparently employed by the OpenWrt distribution used on the NanoNote, and where kernels from other origins are to be used, it is important that the appropriate conventions for invoking the system <code>init</code> program are followed. Thus, if you switch to a different kernel from another project, you may need to change the <code>qi-emdebian-postsetup</code> script to install these files into other locations, potentially giving them different names.
|
paul@3 | 93 |
|
paul@3 | 94 | ==== Running the Script ====
|
paul@3 | 95 |
|
paul@3 | 96 | With the missing files now defined, a script written to automate the remaining configuration activity can be run as follows. Again, it may help to be <code>root</code> or to use <code>sudo</code> to be able to copy the necessary files into the root filesystem:
|
paul@3 | 97 |
|
paul@5 | 98 | qi-emdebian-postsetup rootfs openwrt-xburst-qi_lb60-uImage.bin files
|
paul@3 | 99 |
|
paul@5 | 100 | Here, <code>rootfs</code> is the root filesystem created above, <code>openwrt-xburst-qi_lb60-uImage.bin</code> is the kernel image obtained above, and <code>files</code> is the directory containing the missing configuration files.
|
paul@3 | 101 |
|
paul@3 | 102 | === Formatting the Boot Medium ===
|
paul@3 | 103 |
|
paul@3 | 104 | Currently, only booting from a microSD card is described in these instructions. Eventually, installation to NAND may also be covered.
|
paul@3 | 105 |
|
paul@3 | 106 | The microSD card should first be made available to the computer performing this work. On a Linux-based system, it should then appear as a device like <code>/dev/sdb</code>. You should check and '''make absolutely sure''' that you know which device has been assigned to the microSD card, perhaps using the <code>dmesg</code> command to see what is reported when plugging in the card. For example:
|
paul@3 | 107 |
|
paul@3 | 108 | <pre>
|
paul@3 | 109 | [25942.832101] sd 20:0:0:0: [sdb] Attached SCSI removable disk
|
paul@3 | 110 | [25942.832148] sd 20:0:0:0: Attached scsi generic sg2 type 0
|
paul@3 | 111 | </pre>
|
paul@3 | 112 |
|
paul@3 | 113 | With this information, you can now partition the card using <code>fdisk</code>. First, as <code>root</code> or using <code>sudo</code>, run the following to look for existing partitions:
|
paul@3 | 114 |
|
paul@3 | 115 | fdisk -l /dev/sdb
|
paul@3 | 116 |
|
paul@5 | 117 | If the microSD card already has partitions, you should check to see if they have been mounted by the system:
|
paul@5 | 118 |
|
paul@5 | 119 | mount
|
paul@5 | 120 |
|
paul@5 | 121 | If so, you must first unmount the corresponding devices as follows (as <code>root</code> or using <code>sudo</code>):
|
paul@5 | 122 |
|
paul@5 | 123 | umount /dev/sdb1
|
paul@5 | 124 |
|
paul@5 | 125 | To preserve existing partitions, you can copy them from the card to your system as follows (as <code>root</code> or using <code>sudo</code>):
|
paul@5 | 126 |
|
paul@5 | 127 | dd if=/dev/sdb1 of=sdb1.backup
|
paul@5 | 128 |
|
paul@5 | 129 | To add a new partition, run <code>fdisk</code>, use the <code>n</code> command to make a primary partition, and then the <code>w</code> command to write the partition table. Since <code>fdisk</code> will probably suggest a reasonable start of a partition, perhaps the biggest concern is the size of the partition. Choosing <code>+1024M</code> to indicate a partition of 1024MB or 1GB is not unreasonable for modern microSD cards and current Emdebian installations.
|
paul@5 | 130 |
|
paul@5 | 131 | It is also possible to accept the partition size suggested by <code>fdisk</code> and assign all the space on the card to a partition as well. This may not be sensible, however, since it may make some operations slower and hinder alternative uses for the space (like the creation of other partitions for purposes like backups).
|
paul@3 | 132 |
|
paul@7 | 133 | ==== Swap Partition ====
|
paul@7 | 134 |
|
paul@7 | 135 | Debian programs can use a lot of memory - more than the 32MB of program memory that the NanoNote has available - and so it becomes necessary to allocate additional swap memory so that all running programs can fit in memory. Making a swap partition is largely the same process as that described above for the root partition, but it is likely that you will want to choose a much smaller size. 128M is likely to be enough for the NanoNote: anything larger is probably entertaining a misplaced belief that the computer is powerful to efficiently run the kinds of programs needing such larger amounts of memory.
|
paul@7 | 136 |
|
paul@7 | 137 | If you create a swap partition, be sure to edit the <code>files/etc/fstab</code> file and to remove the comment marker for the line describing the <code>swap</code> partition.
|
paul@7 | 138 |
|
paul@3 | 139 | === Completing the Installation ===
|
paul@3 | 140 |
|
paul@3 | 141 | With a partition in place (<code>/dev/sdb1</code> in this case), you can now run the following helper script (as <code>root</code> or using <code>sudo</code>):
|
paul@3 | 142 |
|
paul@3 | 143 | qi-emdebian-install rootfs /dev/sdb1 --mkfs
|
paul@3 | 144 |
|
paul@10 | 145 | This will make a filesystem in the partition and copy the root filesystem to the card. You should then eject the card as follows (adjusting for the appropriate device name):
|
paul@10 | 146 |
|
paul@10 | 147 | eject sdb
|
paul@3 | 148 |
|
paul@3 | 149 | === Booting into the New System ===
|
paul@3 | 150 |
|
paul@3 | 151 | To boot into the newly prepared system, insert the microSD card into the NanoNote's card slot, then hold down the M key while pressing the power button. The device should now report that it is loading <code>"/boot/uImage" from mmc device</code>. With the conventional OpenWrt-based kernel, the boot splash-screen (or bootsplash) will take up most of the display, but messages will appear at the bottom of the screen.
|
paul@3 | 152 |
|
paul@3 | 153 | If everything goes according to plan, a few minutes will be required for the configuration of the system to be done by the device - this is an issue with installing and booting Debian for the first time - but eventually, a message at the bottom of the screen should read something like...
|
paul@3 | 154 |
|
paul@7 | 155 | nanonote login:
|
paul@3 | 156 |
|
paul@3 | 157 | This indicates that the system is now ready to allow you to log in. You should be able to do so as <code>root</code> without providing a password. It is then your responsibility to set a password using the <code>passwd</code> command.
|
paul@3 | 158 |
|
paul@7 | 159 | === Further Configuration ===
|
paul@7 | 160 |
|
paul@7 | 161 | To set the clock to a UTC time, run the following command:
|
paul@7 | 162 |
|
paul@12 | 163 | date -u -s '2015-06-17 13:08:00'
|
paul@7 | 164 |
|
paul@7 | 165 | To set the time zone, run the following:
|
paul@7 | 166 |
|
paul@7 | 167 | dpkg-reconfigure tzdata
|
paul@7 | 168 |
|
paul@7 | 169 | It may be easier to run this command via a secure shell (ssh) connection to the NanoNote from a computer with a larger screen.
|
paul@7 | 170 |
|
paul@7 | 171 | To set up a default locale or to change the locales and their settings, install the appropriate package and reconfigure it:
|
paul@7 | 172 |
|
paul@7 | 173 | apt-get install locales
|
paul@7 | 174 | dpkg-reconfigure locales
|
paul@7 | 175 |
|
paul@3 | 176 | == Further Work ==
|
paul@3 | 177 |
|
paul@3 | 178 | Things to be added include...
|
paul@3 | 179 |
|
paul@3 | 180 | * A selection of sample configuration files plus other files like hostname, group, and so on
|
paul@3 | 181 | * Network configuration
|
paul@3 | 182 | * A proper way of getting a kernel and modules (perhaps using Debian-centric methods)
|
paul@3 | 183 | * Information about essential packages already provided by the existing [[OpenWrt Software Image|software image]]
|
paul@3 | 184 | * Package fixes, such as the use of integer-only libraries for Vorbis decoding, for example
|
paul@3 | 185 |
|
paul@3 | 186 | The initial configuration process should be improved to give nicer visual feedback. Currently, the screen is cleared and the configuration activity is reported to the console. It might be convenient to allow interactivity using the usual curses-based textual user interface that Debian uses when configuring packages.
|
paul@3 | 187 |
|
paul@3 | 188 | === Initial Root Filesystems ===
|
paul@3 | 189 |
|
paul@12 | 190 | Use of a separate [http://www.kernel.org/doc/Documentation/initrd.txt initial root filesystem] has been suggested. [http://www.mobileread.com/forums/showthread.php?t=99021 Installing a "normal" Debian ARMEL Linux on the Kindle] provides one recipe for making such a filesystem. There is also a Debian package - [http://packages.debian.org/jessie/initramfs-tools initramfs-tools] - which might be of interest, although it seems to be limited to copying files around for the same architecture. There is also [http://wiki.debian.org/InitrdReplacementOptions a comparison] between initramfs-tools and [http://packages.debian.org/sid/yaird yaird]. Another related tool is [http://packages.debian.org/jessie/debirf debirf].
|
paul@3 | 191 |
|
paul@3 | 192 | === Related Documents ===
|
paul@3 | 193 |
|
paul@3 | 194 | A document somewhat similar to this one, but employing debootstrap is [http://foxg20old.acmesystems.it/doku.php?id=debian:how_to_cross_compile_a_kernel_and_create_the_debian_root_file_store How to Cross Compile a Kernel and Create the Debian Root File Store]. Another similar document describing an initial root filesystem is [http://whiteboard.ping.se/Android/Debian How to run Debian or Ubuntu GNU/Linux on your Android]. And [http://cblfs.cross-lfs.org/index.php/Creating_an_Initramfs Creating an Initramfs] also provides some useful hints.
|
paul@3 | 195 |
|
paul@3 | 196 | [[Category:Ben NanoNote]]
|