Creating Root File System Images for the Reference AP
The Devicescape Wireless Infrastructure Platform provides a reference design for an IEEE 802.11 standards based access point. An easy way to get familiar with the platform is to walk through the process of creating a root file system (RFS) image for the reference design AP and load it onto your target device.
The following topics describe the runtime system architecture of the Devicescape Reference AP and guide you through the steps of creating an RFS for the AP.
If you already understand the device architectures, know the build process, and just want a quick reference to the package list for an AP, see Access Point Package List.
The topics covered here are:
Access Point Target Architecture
The Devicescape Access Point (AP) reference design uses an Atheros radio and driver. The Host Access Point daemon (HostAPd) manages user-space 802.11 functions such as authentication, encryption, initializing network interface, beacon intervals, extended authorization protocol (EAP) keys, and so on.
Each component in the AP reference design architecture is described in detail in the Devicescape Package Reference Guide:
- For information on the reference design Atheros driver, see the "atheros-drv" package topic.
- For information on the DataPath driver, see "ieee80211 package" topic.
- For information on HostAPd (including configuration and external APIs for control, status, and monitoring), see the "hostapd package" topic.
(Other drivers can be used in place of the Atheros driver, but these are not part of the AP reference design. For information on supported Broadcom driver, refer to the Broadcom driver topics in the Package Reference Guide.)
Reference AP Features
At a glance, the Devicescape Reference Access Point (AP) provides the following features and more:
- Access point software (hostapd package)
- BusyBox (lightweight implementation of shell and other common Linux utilities combined into a single executable and optimized for embedded systems)
- Configuration subsystem daemon and plug-in support (device-mgmt-agent, device-mgmt-agent-ap packages)
- Configuration backup, restore, and upgrade support
- Console login support (getty)
- Clustering support for auto-synch of AP configurations and clustering-dependent features such as channel planning, wireless neighborhood reporting, and AP-based user management (clustering and clustering-ap-schema packages)
- DHCP client support (busybox)
- IEEE 802.1d bridging (bridge-utils)
- Filtering (provided by iptables and ebtables packages)
- Factory reset button and LED sample applications and drivers
- GDB server (Remote server for the GNU Debugger on the runtime side via gdbserver)
- JFFS2/cramFS file system support
- Network Time Protocol (NTP) client (ntpclient package)
- Package management (lightweight system for installing, uninstalling and upgrading packages provided by ipkg, the Itsy Package Manager)
- Secure Shell daemon (SSHD) (provided by the dropbear package)
- Telnet (busybox)
- Web pages and controller for Web based Access Point administration (web-ui-ap-admin, web-ui-ap-admin-help, web-ui-framework, and web-ui-services packages)
- Web server (via the mini-httpd package)
- Wireless drivers (ieee80211, rate-control-<Driver>, atheros-drv, and so on)
- Wireless tools (including wireless sniffer, virtual client simulator, WPA testing tool, and arbitrary frame generator as described in the "ieee80211 package" topic in the Devicescape Package Guide)
The following section describes how to build a reference AP. For a complete list of packages needed for the Reference AP, see Access Point Package List.
Pre-Built RFS/Kernel Images and RFS Create Scripts
The Devicescape Wireless Infrastructure Platform installation provides pre-built root file system (RFS) and kernel images for the Devicescape Reference AP. The pre-built images are installed in the following directory:
/opt/devicescape/linux/2.0/<Architecture>-bbdyn-uclibc/boot/
If you simply want to install pre-built reference AP software as a first step, you use these images as a starting point.
For information on how to load the RFS and kernel images and boot the target device, refer to the Getting Started Guide for the platform you are using as the target device. (For example, if your target device is the Atheros based "Monte Jade IXDPG425", refer to Getting Started with Devicescape Linux on the Monte Jade IXDPG425.) If you have already worked through the board setup process, connected to the board via a serial port, and booted the device; you can skip directly to the final "load kernel and boot" sections, Follow that information to load the prebuilt RFS and kernel images, and reboot the device.
The boot directory also includes make-rootfs.sh, which is a script for creating an RFS image for the reference AP. In other words, running make-rootfs.sh will create the same RFS image already provided. You can examine the steps in this script to understand the command line process of creating an RFS.
If you modify any of the standard AP packages (modify packages and rebuild as described in Modifying and Building the Packages), you can run make-rootfs.sh to get an updated AP.
Creating an RFS Image for the Reference AP (with ipkg and mkfs.jffs2 commands)
IPKG, or the Itsy(*) Package Management System, is a lightweight package management system designed specifically for use in Linux devices with limited storage. It is similar to RPMs and DPKGs. In fact, the iPKG file format is based on the Debian package management system (DPKG). IPKG allows for addition, update or removal of packages on a running system. It supports versioning, dependency tracking and conflict management.
You can use ipkg to create root file system (RFS) images from the command line. The following sections describe how to create RFS images from the command line using ipkg.
|
Notes
|
- Pre-built RFS and kernel images are also provided with the platform, as described in "Pre-Built RFS/Kernel Images and RFS Create Scripts" on page 12. Also, the script make-rootfs.sh can be used to create an RFS image for the reference AP. (make-rootfs.sh is located in
/opt/devicescape/linux/2.0/<Architecture>-bbdyn-uclibc/boot/.) You can examine the steps in this script to understand the command line process of creating an RFS for the reference AP.
- The IPKGs are installed in:
/opt/devicescape/linux/2.0/<Architecture>-bbdyn-uclibc/packages/core/IPKG
- The following procedure describes how to create a JFFS file for the target. If your target device is an Atheros AR531X board, you have the option of creating a cramfs image as an alternative to a jffs2 image. For information on creating a cramfs image, see the PDF document "Creating a cramfs Filesystem Image" on the Atheros AR531x in the Wireless Infrastructure Platform Documentation (http://www.devicescape.com/docs/wip/) under "Getting Started Board Guides". The cramfs information is included in the AR531x board guide as section 2.3.2.1 "Creating a cramfs Filesystem Image". Also, a pre-built cramfs image is provided with this board, along with a pre-built jffs2 image. The cramfs flash filesystem is a compressed filesystem format that can be used to store your target's root filesystem on flash memory.
|
To create an RFS image from the command line using ipkg, do the following:
- Create an ipkg configuration file that indicates where to find the ipkgs to put in the rootfs, the target architecture, and the location where the rootfs should be created. For example:
file://opt/devicescape/linux/2.0/armv5bf-bbdyn-uclibc/packages/core/IPKG/
file://opt/devicescape/linux/2.0/armv5bf-bbdyn-uclibc/packages/contributed/IPKG/
- Update the ipkg index.
ipkg -V 0 -f ipkg.conf update
- Install the desired packages.
ipkg -V 0 -f ipkg.conf install \
ds-config-ixdpg425 ds-filesystem \
ds-init ds-init-dropbear ds-init-httpd ds-init-telnetd \
ds-sample-webui ds-setup ds-wireless-ap gdbserver hostapd \
hostapd-atheros-config ieee80211 ieee80211-tools ipkg \
ixp425 uClibc wireless-tools zlib
On the above command line, include all packages needed for the Access Point (AP) reference design. To build the reference AP, include the set of packages for either an enterprise profile for target boards with at least 8 MB flash, or a reduced profile for target boards with only 4 MB flash. Note that, in either case, some packages are board-specific; be sure to select the package for your target board architecture.
Table 1 Access Point Package List
|
Package
|
Description
|
Enterprise
|
Reduced
|
|
<DriverVendor>-drv
|
Wireless driver package. Depending on the target architecture for which you are building, you will choose one of the following:
- atheros-drv - Devicescape proprietary Atheros driver used by the IEEE80211 package, suitable for all mini-PCI configurations
- broadcom-wl-drv
|
yes
|
yes
|
|
bridge-utils
|
Linux bridging utilities
|
yes
|
yes
|
|
busybox
|
BusyBox multicall binary that provides UNIX environment
|
yes
|
yes
|
|
clearsilver
|
Web templating library
|
yes
|
yes
|
|
clicmds
|
Command Line Interface (CLI) commands
|
yes
|
yes
|
|
clustering
|
Clustering, user management, channel planning, sessions, and neighboring AP feature pack.
(See also web-ui-clustering and las packages.)
|
yes
|
|
|
device-mgmt-agent
|
Device management agent
|
yes
|
yes
|
|
device-mgmt-agent-ap
|
Access point plugins for the device management agent (device-mgmt-agent)
|
yes
|
yes
|
|
device-mgmt-agent-lsql-http
|
A CGi program that allows LSQL queries to be performed over HTTP.
|
yes
|
yes
|
|
device-mgmt-agent-ntp
|
Plugins for DMAN to start and configure NTP.
|
yes
|
yes
|
|
device-mgmt-agent-ssh
|
A plugin for DMAN to start and configure SSH.
|
yes
|
yes
|
|
device-mgmt-agent-web-server
|
A plugin for DMAN to start and configure the web server.
|
yes
|
yes
|
|
dropbear
|
Small footprint SSH server and client
|
yes
|
yes
|
|
ds-config-<Board>
|
Board specific files
|
yes
|
yes
|
|
ds-filesystem
|
|
yes
|
yes
|
|
ds-init-wip
|
Initialization scripts for the Devicescape Wireless Infrastructure Platform
|
yes
|
yes
|
|
ds-setup
|
Core system files for the Devicescape Wireless Infrastructure Platform
|
yes
|
yes
|
|
ebtables
|
A filtering tool for a bridging firewall
|
yes
|
yes
|
|
hostapd
|
Access Point daemon
|
yes
|
yes
|
|
ieee80211
|
Devicescape 802.11 stack. This is only needed for Atheros drivers.
|
yes
|
yes
|
|
ieee80211-tools
|
Wireless test and manufacturing tools. This is only needed for Atheros drivers.
|
yes
|
|
|
insert1q
|
A kernel module to insert vlan tags and read priority information.
|
yes
|
yes
|
|
ipkg
|
The Itsy Package Manager, a lightweight package manager for installing, uninstalling, and upgrading packages.
|
yes
|
yes
|
|
iptables
|
Linux IP packet filtering tools
|
yes
|
yes
|
|
ixp425
|
IXP4xx access library and Ethernet driver to support Intel IXP4xx chip package.
|
yes
|
|
|
las
|
C-based local authentication server (LAS) available as an option for use with WPA Enterprise security mode.
|
yes
|
yes
|
|
libghthash
|
Hash table library
|
yes
|
yes
|
|
libi802
|
Utility library
|
yes
|
yes
|
|
liblsqlquery
|
Library for creating LSQL queries
|
yes
|
yes
|
|
libupnp
|
Universal Plug and Play (UPnP)
|
yes
|
yes
|
|
libxml2
|
Large XML library (inc. XPath).
|
yes
|
yes
|
|
mini-httpd
|
Web server
|
yes
|
|
|
mini-httpd-nossl
|
Web server
|
|
yes
|
|
mtd
|
Linux memory technology device utilities (flash management tools)
|
yes
|
yes
|
|
net-snmp
|
Simple Network Management Protocol (SNMP) agent. Supports SNMP v.1 and v.2 management information bases (MIBs). (See also web-ui-snmp package.)
|
yes
|
|
|
ntpclient
|
Network time protocol client. (See also web-ui-ap-admin-ext package.)
|
yes
|
yes
|
|
openssl-libs
|
The open source toolkit for SSL/TLS
|
yes
|
yes
|
|
portal
|
Guest portal on network
|
yes
|
yes
|
|
redboot-config
|
Redboot bootloader configuration package required only for Monte Jade IXDPG425 target boards
|
yes
|
|
|
rate-control-<Driver>
|
Rate control functionality for the driver
|
yes
|
yes
|
|
strip1q
|
Kernel module to strip IEEE 802.1q tags and read priority information for the purpose of implementing Layer 2 quality of service (QoS) for non-VLAN frames.
|
yes
|
yes
|
|
uClibc
|
Small footprint C library
|
yes
|
yes
|
|
web-ui-ap-admin
|
Web pages and controller for access point administration.
Note: The web-ui-ap-admin package provides Web pages for basic features of Reference AP; that is, most of the Web UI pages. Web UI components for optional packages are implemented separately as extensions to make it easy to exclude or include that functionality on the AP (along with the associated Web UIs) during development.
|
yes
|
yes
|
|
web-ui-ap-admin-help
|
Online Help starter package for access point Web based Administration Web UI, generated as a result of building the web-ui-ap-admin package.
Note: The web-ui-ap-admin-help package provides Online Help for basic functionality on the Reference AP. Online Help for Web UI extensions associated with optional components is provided as a part of those extension packages.
|
yes
|
|
|
web-ui-clustering
|
AP Administration Web UI extension for clustering package. Includes Web pages and Help for cluster management, channel allocation, and wireless neighborhood views.
|
yes
|
yes
|
|
web-ui-las
|
AP Administration Web UI extension for las package (Web page and Help)
|
yes
|
yes
|
|
web-ui-ntp
|
Includes AP Administration Web UI extension for ntpclient package (Web page and Help)
|
yes
|
yes
|
|
web-ui-snmp
|
AP Administration Web UI extension for net-snmp package (Web page and Help)
|
yes
|
|
|
zlib
|
Compression library
|
yes
|
yes
|
|
Note
|
For debugging purposes, we suggest also including gdbserver package (remote server for the GNU Debugger on the runtime side) and simple-ftpd or vsftpd package (FTP server).
|
- Create a root file system image, specifying the metafile, erase block size and Root File System (RFS) partition size:
mkfs.jffs2 --devtable=metafile.txt \
--big-endian --root=rfs --output=rootfs.jffs2
This is the root file system image that can be programmed into the flash on the target system.)
The following table shows the options you must specify for the mkfs.jffs2 command.
Table 2 mkfs.jffs2 Command Options
|
Option
|
Description
|
|
--big-endian
|
Use this option to specify that the target CPU byte order is big-endian.
The default is little endian. If you do not specify this option, mkfs.jffs2 assumes that the target is little-endian (for example, BCM9471).
|
|
--output=<Filename>
|
Output the JFFS2 file system to the specified file.
|
|
--devicetable=<Filename>
|
Use the specified file as a device table file. This file determines which device nodes will be on the resulting filesystem.
You can find an example of a device table file under /opt/devicescape/toolchains/<Architecture>-linux/examples on the platform CD-ROM for the architecture you are using.
|
|
--eraseblock=<Size>
|
Use the specified erase block size.
|
|
--pad=<Size>
|
Pad output to the specified size in bytes. The value for this option is the size of your root file system partition. (See the table below.)
Caution: If you have more data than can fit on a filesystem of <Size> bytes, the resulting image will be truncated when the target flash is programmed and the filesystem will be corrupted. Therefore, if your output image is larger than the value you specified for --pad, you must reduce the size of your root file system and re-run the mkfs.jffs2 command.
Reducing the Flash Footprint:
If you are working with a board that has a minimal flash size (for example, 4 MB), incorporate a given file pruning script into the project. To reduce the flash footprint for particular boards (those with only 4 MB flash), you can incorporate into the project the file pruning script provided ( prune-rfsdir.sh) to remove any extra, unnecessary files from the staging area. The script will run when you execute the command to create an RFS image as a pre-processing step. The pruning script is located in: /opt/devicescape/linux/2.0/<Architecture>-bbdyn-uclibc/boot/prune-rfsdir.sh.
|
|
--root=<DirectoryOfRFS>
|
Build file system from the specified directory
|
The following table shows the board-specific settings (RFS partition size, Erase Block size, and Target Endian) you will need to provide to the mkfs.jffs2 command.
Table 3 mkfs.jffs2 Board-Specific Options: RFS Partition Size, Erase Block Size, and Endian
|
Option
|
Setting
|
|
AR531x (Atheros SoC/D-Link DWL-2210AP)
|
- Root File System (RFS) Partition Size: 0x2d0000
- Erase Block Size: 0x10000
- Target Endian: Big
|
|
IXDPG425 (Monte Jade)
|
- Root File System (RFS) Partition Size: 0xe80000
- Erase Block Size: 0x20000
- Target Endian: Big
|
|
Novatec ntnp425c
|
- Root File System (RFS) Partition Size: 0xe40000
- Erase Block Size: 0x20000
- Target Endian: Big
|
|
Allied Telesyn AT-WA7400
|
- Root File System (RFS) Partition Size: 0x6D0000
- Erase Block Size: 0x10000
- Target Endian: Big
|
If you are new to working with the platform and are using this topic to build the Devicescape Reference AP as an example, at this point please refer to What's Next? for some guidance on how to proceed.
What's Next?
If you are new to working with the platform and are using this topic to build the Devicescape Reference AP as an example, a logical next step is to load this RFS image file you just created along with the kernel image (supplied with the platform) onto the target device. The details of this task will vary depending on which target device (board and chipset) you are using; but it is likely you have already been through the process once when you first brought up the board.
For information on how to load the RFS and kernel images and boot the target device, refer to the Getting Started Guide for the platform you are using as the target device. (For example, if your target device is the Atheros based "Monte Jade IXDPG425", refer to Getting Started with Devicescape Linux on the Monte Jade IXDPG425.) If you have already worked through the board setup process, connected to the board via a serial port, and booted the device; you can skip directly to the final "load kernel and boot" sections, Follow that information to load your new RFS and kernel images, and reboot the device.
For information on re-building a kernel image, see Modifying and Building the Packages.
