1 The Nail board

2 What do I do with it?

1 The Nail board

The nail kit is a portable, self-contained, unbrickable ARM Linux development system that weighs about 6 ounces and plugs into a USB port. It requires no other power or data cables, doesn't need an electrical outlet, and avoids the need to clear flat space in a cluttered work environment.

The nail board comes preinstalled with Linux, and the developer CD contains prebuilt images of the bootloader, kernel, and root filesystem, along with an automatic script to reflash it via the built-in JTAG. Every binary on the CD can be reproduced from source code using instructions (and source tarballs) included on the CD. A prebuilt ARM cross compiler is also included to make this easy, or the compiler can be built from the included source code. The instructions are written on the assumption that developers will eventually replace these source tarballs with their own versions.

The nail board is potentially useful to busy kernel developers as a quick way to test an ARM kernel on real hardware, as a development platform for software-controlled "USB gadget" devices, as a prototyping platform for embedded developers looking to deploy on ARM, and as a toy for hobbyists to play with and learn from. It's designed to plug into your laptop and travel with you.

That's what they put on the flyers, anyway.

1.1 What is it

The nail kit is a complete ARM Linux system. It plugs into a USB connection, which provides power and also lets it communicate with the system it's plugged into.

The nail board doesn't have to plug into a laptop: you can plug it into a powered USB hub, or one of those USB cell phone chargers that plugs into a wall outlet, and it will still boot up into Linux and run its programs. (You could even plug a USB network card into its downstream USB connection and use it as a server.) something into the downstream USB connection It requires no other power cords or data cables.

picture of nail board

The Nail board comes preinstalled with Linux. It may be reflashed via a built-in JTAG device accessed through the USB port. This JTAG is capable of bypassing the installed software and reformatting the Nail board's flash with a new bootloader, kernel, and root filesystem, making the Nail board inherently "unbrickable".

screen shot of Linux console

In addition to the built-in serial and JTAG devices, the nail board also provides a generic "USB Gadget", allowing the ARM Linux system running on it to process its own USB packets to provide a software-defined USB device to the host system the Nail board is plugged into. The default USB gadget provided is a USB ethernet device (allowing users to SSH into their nail boards), but example code is also provided to use the USB gadget as a USB flash storage device, or as a second serial port. (XXX: If only one instance of "USB Gadget" hardware is included, can the ARM Linux system running on the Nail board provide one software-defined device at a time?)

1.2 What's in it

The nail board is based around the "Hammer" chip, a small self-contained ARM system that looks like this:

picture of hammer chip

The hammer chip contains:

  • an XXX mhz ARM processor (model#)
  • 16 megabytes Flash memory
  • XXX JTAG, capable of reflashing this memory from "brick" state.
  • 32 megabytes SDRAM

The nail board connects a Hammer chip to the outside world via a USB connection. This adds the following hardware (with Linux kernel CONFIG symbols for relevant drivers):

  • XXX Male (upstream) USB connector
  • XXX Female (downstream) USB connector
  • XXX USB hub
  • XXX serial
  • XXX software-defined USB gadget
  • XXX Blinky LEDs
  • XXX Beepy thing

The links above go to the data sheets for these components, mainly of interest to hardware hackers. [XXX kernel CONFIG symbols]

1.3 What's it running

The preinstalled software on the nail board is a small custom Linux distribution built from

  • XXX Linux-2.6.2X (XXX .config)
  • uClibc XXX (XXX .config)
  • BusyBox XXX (XXX .config)
  • DropBear XXX SSH server

These packages were compiled with gcc 4.XXX and Binutils XXX configured for XXX.

1.4 What else comes with it

The nail board includes a developer CDROM containing documentation, source code, prebuilt binaries for both host and target, some random pictures of kittens that seemed appropriate at the time, and an MP3 of Jonathan Coulton's "Re: Your Brains" [XXX what's actually on it?].

The ISO for the most recent version of this CRDROM is available at [XXX URL]

2 What do I do with it?

The nail board is potentially useful to developers as a quick way to test an ARM kernel on real hardware, as a development platform for software-controlled "USB gadget" devices, as a prototyping platform for embedded developers looking to deploy on ARM, and as a toy for hobbyists to play with and learn from.

It's designed to plug into your laptop and travel with you. It should also fit in a jacket pocket. (It may not fit in a pants pocket, but you really don't want to put it through the wash anyway. Also, despite saying "hammer" on the side of the case, hitting things with your nail board to drive them into wood is not recommended.)

If you do enough development to put an application you like on the thing, you can plug a nail board into some other power source (such as a USB hub or wall outlet adapter) and have it talk to the outside world through the "female" USB connectior at the other end. It really is a self-contained device that can operate standalone, provided it has power. Note that the "hammer" chip inside the nail board is available in other packages capable of working off batteries or , one of which may be a better form factor for actually deploying your software.

2.1 Plugging the Nail board into your laptop.

When you plug the Nail board into an existing "host" system (via the Nail board's "upstream" USB port), it shows up as three devices. The Nail presents itself as a USB hub, attached to which are a serial port, a JTAG, and a software-defined "USB gadget" device.

The USB serial port presented to the host system is connected to a serial device on the ARM Linux system. These serial devices are used to communicate with ARM software running on the Nail board. By default, /dev/console of the preinstalled ARM Linux system is attached to this serial connection (115200 bps, 8N1), and may be used to log in to the nail board. (See Logging in to the Nail board.)

The JTAG is a device is a hardware debugger. It can directly access the hammer's flash memory, bypassing any software currently running on the board. This is often used be used to format and reinstall all the software on the Nail board (even if the existing software has become unresponsive), to simply to upgrade the software on it. (See Unbricking the nail board.) The JTAG can also be used to debug software running on the device, via the GNU debugger (see Debugging the Nail board with gdb.

The USB Gadget is a software defined device. Since the USB packets are sent and received by software running on the nail board, this device can act like any USB device. The preinstalled Linux image uses it to provide an ethernet device. If you see an ethernet device from the nail board, it means the onboard Linux booted and ran successfully.

In the absence of other USB devices, the following commands should show these three devices on a host Linux system that has the appropriate kernel driver modules loaded (usbserial.ko for the first two and usbnet.ko for the third):

ls -l /dev/XXX # console serial device
ls -l /dev/XXX # JTAG device
ifconfig XXX # ethernet gadget device.

2.2 Logging in to the Nail board.

XXX Put text here.

2.3 Unbricking the nail board.

XXX Put text here.

2.4 Debugging the Nail board with gdb.

XXX Put text here.

- What is it
- What's in it?
- What's it running?
- What comes with it?
- What do I do with it?
  - Plugging the nail board into your laptop.
    - Find the serial and jtag devices.
    - If you get ethernet too, Linux is running on the nail board.

  - Using minicom to log in to your nail board.
    - Using the ethernet device to ssh to your nail board.

  - Using JTAG to reflash your nail board.
    Now that you've found the preinstalled Linux system, let's destroy it!
    - Prebuilt bootloader, kernel, root filesystem.
    - Script to reflash the nail board.
      - Yes, this is slow.  Faster closed source library, but eh.
    - Proving you reflashed it (boot message BLAH="hello")

  - Using JTAG to back up your nail board.
    You probably never need to do this, but it's nice to know you can.
    Why loopback mounting jffs2 is a pain in the ass.

  - Compiling your own "hello world" program to run on the Nail board.
    - "hello world"
    - Installing the prebuilt cross compiler toolchain

  - Compiling and installing your own ARM kernel on the Nail board.
    - kernel actually slightly easier, doesn't use libc or stdinc.
    - .config
    - Installing a new kernel.

  - Fiddling with the bootloader
      - Why not just boot the new kernel directly?
      - Installing a new kernel with the bootloader instead of the JTAG.
      - Booting a kernel via tftp
        - Setting up a TFTP server
      - Changing the bootloader's default actions.
      - Rebuilding the bootloader from source.

  - Where did this cross compiler toolchain come from?
    - Building it yourself from source.

  - Building your own root filesystem for the nail board.
    - What's in a root filesystem?
    - Linux From Scratch.
    - Firmware Linux

  - Fun with QEMU

  - Driving the hardware on the nail board
    - Serial console
    - USB Gadget
    - Blinky lights
    - Making it beep

[15:22]  You misunderstand, your device can potentially be _useful_ to Linus and Andrew.
[15:22]  "Here's a little toy you can use to test an arm kernel".
[15:22]  It's portable, self-contained, unbrickable, and here's a script to reflash it trivially.
[15:22]  landley: indeed, just hard to stand out from the crowd with so many other "samples" that linus probably gets
[15:23]  That's why you need lwn and linux devices reviews first.
[15:23]  Don't send an unsolicited sample, it'll stay in a box on his floor.
[15:24]  Get jonathan corbett excited, then tell him you'd like to send one to Linux because you think it'll help arm support for Linux if he has a convenient and portable test system he can take with him on airplanes.
[15:24]  landley: yea, thats what i figured
[15:24]  landley: and since i've never spoken to linus , it would be unsolicited, hehe
[15:25]  prpplague: which is why you need the lwn review.
[15:25]  Does Jonathan do hardware reviews at all?
[15:25]  occasionally.  Not often.
[15:25]  He may delegate.
[15:26]  But keep in mind, he co-authored a book on device drivers.
[15:26]  Hook him with the "look, a usb gadget host"
[15:26]  There are a half-dozen major hurdles to doing embedded development.
[15:26]  You've got to be able to set up a cross compiler toolchain, which stops most people.
[15:26]  You've got to be able to build your own root filesystem.
[15:27]  You've got to be able to configure a kernel for hardware you've never used before.
[15:27]  You've got to be able to _install_ this kernel -- flashing the device is a huge roadblock for a lot of people.
[15:27]  It's intimidating due to brickability.
[15:27]  You need to be able to obtain a device to play with and make sure that all of the above is correct for that specific device.
[15:28]  You've got to set up some way to get feedback from the device; minicom is evil.
[15:28]  And setting up serial ports is rapidly becoming a lost art, even assuming your machine still _has_ a serial port anymore.
[15:29]  And all that's just to get the device to a shell prompt, which isn't inherently all that _interesting_.
[15:31]  prpplague: the point is, a device that just plugs into USB makes about 1/3 of those problems go away.
[15:31]  You have hardware, no problem obtaining a serial port or wiring up the cables right.
[15:32]  (Heck, finding _flat_space_ to set the device up is a bit of a challenge for most geeks.)
[15:32]  The "dangerous evil jtag" can be hidden behind a script.
[15:33]  As for getting software on the device, the approach I'm taking with firmware linux evolved for a reason.
[15:33]  You need binaries, but binaries by themselves aren't enough.
[15:33]  You need the source and build scripts to reproduce them.
[15:34]  Build scripts are better than makefiles because you can read the scripts as a form of documentation.
[15:34]  It does this, this, and this.  In that order.
[15:34]  You can chop bits out, modify them, etc.
[15:34]  (Some of that's personal preference, of course.  But not all.)
[15:35]  You need documentation explaning not just what to do but what the _options_ are.
[15:35]  "Here are the capabilities of the device.  It has the potential to do X, Y, and Z."
[15:36]  And from a software geek's point of view, "plug the device into a USB port" and it's all software from there...
[15:41]  prpplague: on the nail board page, could you give a bullet point list of the hardware in the thing?
[15:42]  Preferably with "hammer module" and sub-bullets, and then "nail board" and sub-bullets for what's on that?
mount -t usbfs usbfs /proc/bus/usb -nodev,noexec,nosuid,devgid=123,devmode=0664