The first couple of articles in this series focused generally on the hows and whys of building Linux™ distributions on x86 versus PowerPC® platforms. Part 3 gets into actual implementation specifics for the Kuro Box platform.
An important point to note before you start: While you're experimenting with the Kuro Box, it's very helpful to have a connection to the default console. That's where bootloader and kernel debugging messages normally appear, and it's also your best chance to talk directly to the box -- particularly if something goes mildly wrong. Without this direct connection, you have to log in through telnet, over the network interface -- and that interface might not be working properly if your experiments go awry.
The default console is a 57600bps 8N1 asynchronous connection to one of the MPC8241's serial ports. This port is routed directly to connector J1 on the Kuro Box PCB, but it requires level-shifting if you want to talk to it with a regular PC. The fastest way to throw together a suitable hardware interface is to take an off-the-shelf USB to serial converter, pull the level-shifter chip off it, and patch the Kuro Box's serial lines to the appropriate traces on the USB-to-serial PCB. I've written a fairly detailed account of how to carry out this sort of hack, and you'll find a link to it in the Resources section at the end of this article. Here's a picture of a PalmConnect adapter hacked to be a Kuro Box debugging conduit:
Figure 1. Example of USB-serial converter hacked for use with Kuro Box
The previous article (see Resources) described different ways of organizing the boot process: loading the entire operating system into RAMdisk, or running off a secondary storage medium like a hard disk, and various options in between. The Kuro Box actually implements two different startup methods depending on whether this is a "first-time" or a "normal" boot. There is a minimal bootloader in flash, along with the main kernel image, and a failsafe initial RAMdisk image is stored in flash also. This small emergency RAMdisk recovers the unit from a hard drive erasure. If you've already run the installer program and "blessed" the hard disk in your Kuro Box, the only way you can get back to the flash filesystem is either by holding down the red button on the back while powering on, or by partially erasing the hard disk and rebooting. This latter option will obviously delete all of your files, so back up before running this command:
# dd if=/dev/zero of=/dev/hda bs=1k count=1
This works by filling the blocks that would otherwise hold disk partition information, used by the kernel to identify a usable root filesystem, with zeroes, making the disk look blank. Corrupting the hard disk in this way will send the unit a little crazy, too. You'll probably need to pull the power plug to get the unit to reboot once you do this.
Recognizing the emergency flash filesystem
From the outside, you can tell at once if your Kuro box is running off the emergency flash filesystem, because the login prompt (and network information) identifies the unit as KURO-BOX-EM:
Listing 1. The login prompt for the emergency flash filesystem
Kroutoshikou KURO-BOX (IETSUNA) kernel 2.4.17-kuro-box on ppc KURO-BOX-EM login: |
By contrast, the complete version identifies itself as simply KURO-BOX:
Listing 2. The login prompt for the on-disk filesystem
Kroutoshikou KURO-BOX (IETSUNA) kernel 2.4.17_kuro-box on ppc KURO-BOX login: |
Start by looking briefly at the flash-based emergency filesystem. Buffalo Technology doesn't provide much documentation on the Linux distribution it uses, either the small flash-resident version or the larger distribution loaded onto the hard disk. Thus, in order to learn more about what the unit runs and how it starts up, you need to do a little forensic analysis. (This is a useful skill anyway; among other things, you'll see that there is rather a lot of cruft in the Kuro Box filesystem).
By the way, although the Kuro hardware is capable of running diskless, operating entirely out of flash and RAM, you can't use this feature directly because the kernel will hang if it can't detect an attached hard disk.
Once you log into the box as root (the default root password in emergency
mode is kuro, or, for the new Kuro Box HG, kuroadmin), the first place you
should look is in /etc/inittab. The lines of principal interest here are:
Listing 3. /etc/inittab
id:2:initdefault: si::sysinit:/etc/init.d/rcS l2:2:wait:/etc/init.d/rc 2 |
In order, these lines tell you that the box operates at runlevel 2 by
default, that it runs a system-initialization script called rcS, and that
it then runs the scripts in the /etc/rc.d/rc2.d directory. That directory
contains, amongst several inactive files, symbolic links to five working
scripts: apservd, inetd, logoutd, ppc_uartd, and rmnologin.
The apservd (/usr/bin/ap_servd) daemon
is a Kuro-specific daemon described as "AP
Serv," where AP presumably stands for Access Point. The Kuro Box is
descended from a wireless device called the Linkstation, so the name of
this daemon probably derives from that ancestor. This daemon is undocumented,
but appears to be implicated in several functions, including spawning
dhcpc to get an IP address from a DHCP server (if one is available) and
handling device discovery and remote software installs from the Windows®
utility.
The inetd daemon, if you're not familiar with it, is the
network service
"super-daemon." Its configuration file is /etc/inetd.conf, and if you
inspect this file, you will see that the only services scheduled to run in
EM mode are ftp (in.ftpd; not functional) and telnet (in.telnetd).
The ppc_uartd daemon is another Kuro-specific
daemon; it kicks the external hardware
watchdog regularly. If it isn't running, the slave microcontroller will
assume a hardware or software failure and power down the system. The
hardware watchdog is, however, disabled when the unit is running in EM
mode, so it's not clear why the kicker daemon is installed.
The logoutd daemon is non-functional (the underlying software
isn't installed) and
rmnologin is a housekeeping script that simply deletes a temporary flag
file that prevents you from logging in while the system is starting up.
Browsing around in the EM-mode filesystem, you will also find that most of
the usual command-line utilities are present, along with some special
modifications. For example, there is no standard fdisk
command; instead,
there is a special disk-partitioning utility called mfdisk.
The exploration above is primarily for interest's sake. This article won't go into modifying the flash-based filesystem or kernel image just yet, because it's an "unsupported" and hazardous route to take -- meaning that Buffalo doesn't provide a failsafe mechanism of any sort. There is a general consensus on the Revolution support forums that someone ought to port U-Boot to the Kuro hardware. This would allow you to reflash the unit with experimental kernels safely, but as yet nobody has stepped up to the plate and carried this out. Given this state of affairs, if you build an unbootable kernel (or even simply one without the right network or console support), you can lock yourself out of the device permanently -- the only failsafe way to reflash it is by using a hardware debugger attached to the BDM port.
So, now you'll inspect -- and add to -- the default software bundle the unit runs off the hard drive. The goal is to install a set of native development tools (GCC, gas, and others) and as complete as possible a set of kernel drivers for hardware, such as USB serial converters and webcams.
If you haven't already done so, run the Windows installer and set up the hard drive on your Kuro Box. Note that you must disable any firewall software you're running on your Windows machine. If you have problems running the setup program, try it again once or twice; it can be a little flaky. If it simply refuses to work at all, the Resources section contains a link to the manual install process. The usual symptom of a recalcitrant installer is that the setup process will get right through to the end, seemingly without problems, but at the last step you'll get an error dialog saying "Failed to update software."
Once you've installed the standard software bundle, you can poke around
inside it the same way you did with the EM filesystem. Look in particular
at the list of running processes (with ps -ax) and the startup scripts and
configuration files in /etc and its subdirectories.
You'll quickly find that the hard disk load is a superset of the EM
software; it's structured in the same way and incorporates the same
components plus a few extras. Among the additional processes, you'll find
thttpd (a small-footprint Web server), lpd (the print daemon), cron
(used to run tasks at scheduled intervals), atalkd, and
afpd (these provide
AppleTalk® and AppleShare® functionality respectively; they're not necessary unless
your network contains Macintosh® computers running MacOS® 9.x or earlier), and smbd and nmbd
(components of samba, Linux's Windows-compatible file-
and printer-sharing layer).
The root directory for the Web server is /www
-- you'll find all the
Japanese-localized Web pages and Perl scripts in there by default.
Revolution does make an English-translated version of these files
available for download, but there's no need to bother with them for the
purposes of this article; they're just a pretty front-end to configuration
tasks you can do manually with telnet. The primary configuration file for
the Web server is /etc/thttpd.conf -- there's
probably not much you want
to change in there. See the thttpd home page for
further information on
configuring the server, but for now just leave it the way it is (the next
article will assume you're running with a default configuration).
The default directory made directly visible and mountable by Windows and
MacOS machines on your network is /mnt/share. The Windows sharepoint is
set up by Samba's configuration files, which you can find in the
/etc/samba directory. For more information on configuring Samba, refer to
the official Samba home page, specifically the
installation/documentation sessions. Likewise, the AppleShare sharepoint
is set up by netatalk's (specifically, atalkd's) configuration files, which are located in
/etc/atalk. Modern versions of MacOS can mount Samba shares directly, and
other operating systems don't natively look for AppleShare volumes, so I
won't be delving into the mysteries of netatalk.
If you look in /lib/modules/2.4.17_kuro-box you'll find the usual map
files (modules.usbmap et al) that map vendor and product IDs to kernel
drivers. The only one of these maps that is really useful is the USB
device map, since that's the only user-pluggable interface on the Kuro
Box.
If you browse through the kernel drivers provided in the default software
bundle, you'll see that it's far from being a complete set. The Resources section has a link to the kernel drivers provided by
linkstation.yi.org -- you'll need to install these additional drivers for
later installments in this series. To install these drivers, download the
tarball and uncompress it in the /lib/modules/2.4.17_kuro-box directory.
Then, run depmod -qa to update the module dependencies.
Installing the development tools
The final thing you'll need to do is install the development tools you'll
be using later. You can get the toolchain from Revolution, or from the
mirror listed in the Resources section. To install these tools, first
transfer the main file (binary.zip from Revolution,
kurobox-tools.tar.gz
if you got it from me) over to your Kuro Box and unpack it in the root
directory. You'll wind up with several tarballs; simply extract all of
these files and the tools are installed. The tarballs contain embedded
paths relative to /, so you don't need to create any directories by hand.
Once you've extracted everything, you can delete the tarballs.
If you've been following along so far, by now you have a fully configured Kuro Box with a fairly complete set of device driver modules and all the native development tools you're likely to need. You also have pointers to the primary configuration files in the Linux distribution you're using, which should help you customize it if you need to do so. In the next installment of this series, you'll develop a simple, Web-based, back-end application program written in C.
-
Migrating from x86 to PowerPC is the only
developerWorks Power Architecture technology series on the entire Internet
that will help you build your own remote-controlled robot submarine army.
Missed a previous installment? Don't dismay: it's astonishingly easy to
read them all now.
- Need to
hack a serial
port onto your Kuro box? Lewin has posted all of the details to
his site.
- An earlier developerWorks article on lightweight
Linux discusses other items of interest to people working on tiny systems.
Although it's now a little dated, most of the utilities it describes are still
being actively maintained (developerWorks, October 2002).
- Another article gives a higher-level overview of the Kuro Box, and some
of the fun you can have setting it up to play
Zork (developerWorks, December 2004).
- ftp.linkstation.yi.org is a Japanese archive of
support files for the Kuro Box and its sibling products.
- Download this file for Edwards' mirror of the complete set of Kuro Box kernel modules from
linkstation.yi.org.
- Download this file for Edwards' mirror
of the complete set of Kuro Box development tools from Revolution's Web
site.
- The thttpd homepage
has more information about the
"tiny/turbo/throttling HTTP server" used in Kuro Box. While it isn't
the smallest possible HTTP implementation, it provides an excellent
balance between size, performance, and feature set.
- The Samba home page, the UNIX-hosted,
open source, SMB-compatible network client/server package used by Kuro Box
(and many other Linux distributions), has more information about configuring
Samba.
- The netatalk home page
has more information about the
open source AppleShare server/client software used in Kuro Box.
- The Kuro's software distribution is based on BusyBox, version 0.60.5.
- Another popular embedded Web server is distributed by
GoAhead.
You might want to use GoAhead's server if you are
building a deeply embedded application based on a lean operating system
like eCos.
- Have experience you'd be willing to share with Power Architecture zone
readers? Article submissions on all aspects of Power Architecture technology from authors inside and outside
IBM are welcomed. Check out the Power Architecture author
FAQ to learn more.
- Have a question or comment on this story, or
on Power Architecture technology in general?
Post it in the Power Architecture technical forum
or send in a letter to the editors.
- The Power Architecture Community Newsletter includes full-length articles as well as recent news about members of the Power Architecture community and upcoming events of interest.
Learn more
about the Power Architecture Community Newsletter and how to contribute to it. Subscription is free.
- All things Power are chronicled in the developerWorks Power
Architecture editors' blog, which is just one of many developerWorks
blogs.
- Find more articles and resources on Power Architecture
technology and all things
related in the developerWorks Power
Architecture technology content area.
- Download a IBM PowerPC 405 Evaluation Kit to demo a SoC in a simulated
environment, or just to explore the fully licensed version of
Power Architecture technology. This and other fine Power Architecture-related downloads are listed in
the developerWorks Power Architecture technology content area's downloads section.
Lewin A.R.W. Edwards works for a Fortune 50 company as a wireless security/fire safety device design engineer. Prior to that, he spent five years developing x86, ARM and PA-RISC-based networked multimedia appliances at Digi-Frame Inc. He has extensive experience in encryption and security software and is the author of two books on embedded systems development. He can be reached at sysadm@zws.com.
