Board Porting
This topic covers porting of the Devicescape™ Wireless Infrastructure Platform for one of the supported reference boards to a board based on the same CPU, or a very similar one (that is, one of the same family). It does not cover the work required to port the platform to a totally new CPU type.
Since most of the CPUs supported by the platform are highly integrated, system-on-a-chip type CPUs, most of the peripherals also remain the same. The exception here is the Intel IA-32/x86 family which have many external peripheral solutions. Luckily, many of these are already supported by Linux, and an embedded device based on this family can make use of this wide range of drivers very easily.
The following topics are covered here:
What Needs to be Changed?
There are a number of things in the system that might to need be changed to support a new board:
The exact list of changes depends on the CPU. The following sections describe the tasks required to port boards based on the three "embedded" CPU types that the platform supports:
- Intel's IXP4xx family (big-endian XScale)
- Atheros' AR531x/AR231x family (big-endian MIPS)
- Broadcom's BCM4712 (little-endian MIPS).
IA-32/x86 board ports are not covered since most conform to the standard PC architecture, the only changes required being the selection of drivers for the peripheral controllers being used.
Intel IXP4xx Boards
Kernel Changes
Most of the required changes to support a new IXP4xx-based board are in the kernel code. This section describes these changes, and uses the example of adding support for the Linksys WRV54G, which is known as the Gemtek GTWX5715 in the Linux kernel (this is the name of the board that is inside the Linksys WRV54G systems).
1. arch/arm/config.in
Add the new board to the options for IXP425-based boards:
mainmenu_option next_comment
comment 'IXP425 Implementation Options'
choice 'IXP425 Board Type' \
"IXDP425 CONFIG_ARCH_IXDP425 \
GTWX5715/WRV54G CONFIG_MACH_GTWX5715 \
Montejade CONFIG_MACH_MONTEJADE \
IXCDP1100 CONFIG_ARCH_IXCDP1100 \
PrPMC1100 CONFIG_ARCH_PRPMC1100 \
COYOTE CONFIG_ARCH_ADI_COYOTE \
SE4000 CONFIG_ARCH_SE4000 \
SG560 CONFIG_MACH_SG560 \
SG565 CONFIG_MACH_SG565 \
SG580 CONFIG_MACH_SG580 \
SG710 CONFIG_MACH_ESS710 \
SE5100 CONFIG_MACH_SE5100" IXDP425
2. arch/arm/tools/mach-types
Add an entry for the new board. If you wish to do this properly, the new board should be registered with the ARM-Linux project according to the instructions in Documentation/arm/README which reads:
Machine Registration
The legacy registration process for adding a new machine (also referred to as "architecture") was accomplished via email. The new process is not email based. Instead, a Web form is provided for you to submit the information about the new board. The information made available in the Web page instantly, and also in the downloadable version of the mach-types file. The machine registry page is:
http://www.arm.linux.org.uk/developer/machines/
At the top of this page there is a link to the form for submitting a new board. You will need to register with the site first (that is, "create an account"). Then, follow the link to the new machine submission page. This will automatically take you to the login/registration page if you are not already logged in. To register the machine, you need only provide your name and email; your password will immediately be sent to the email address you use here. To log in after that, simply give your email address and the password.
Following is an example of the machine registration Web page which shows the kind of information you will need to provide.
Although the board we are using for this example has already been registered, the version of the mach-types file that is included with the platform release does not include it, and we are using a different name for it, so we will add a line with the correct board ID number:
gtwx5715 MACH_GTWX5715 GTWX5715 641
You can view the current ARM board registry at http://www.arm.linux.org.uk/developer/machines/ and download the current mach-types file from http://www.arm.linux.org.uk/developer/machines/?action=download.
3. arch/arm/boot/compressed/head-xscale.S
Add a conditional section at the end of the file to set the new board ID up correctly in case the bootloader does not (you can avoid this step if you are sure that your bootloader will pass the correct board ID to the kernel).
#ifdef CONFIG_MACH_GTWX5715
mov r7, #MACH_TYPE_GTWX5715 & 0xff
orr r7, r7, #MACH_TYPE_GTWX5715 & 0xff00
4. arch/arm/kernel/bios32.c
Add a line to define the external PCI data structure:
extern struct hw_pci gtwx5715_pci;
Add a section at the end of the block of IXP425 boards (inside the #ifdef CONFIG_ARCH_IXP425/#endif block) to select this PCI datastructure in the event that the board is a GTWX5715:
if (machine_is_gtwx5715()) {
5. arch/arm/mach-ixp425/Makefile
Add the targets for the board-specific PCI library. If your board's PCI configuration (PCI clock, reset and IRQ GPIO pin assignments) all match an existing board, then you can simply reference that board's source file. If not, then you will need to reference a file with your board's name (as we do here for the GTWX5715 board). We will add this new source file in step 8 below.
obj-$(CONFIG_MACH_GTWX5715) += gtwx5715-pci.o
6. arch/arm/mach-ixp425/arch.c
Add a new conditionally compiled section at the end of the file describing the board:
#ifdef CONFIG_MACH_GTWX5715
MACHINE_START(GTWX5715, "Gemtek GTWX5715/Linksys WRV54G Home Gateway")
MAINTAINER("Devicescape Software, Inc.")
BOOT_MEM(PHYS_OFFSET, IXP425_PERIPHERAL_BASE_PHYS,
IXP425_PERIPHERAL_BASE_VIRT)
7. arch/arm/mach-ixp425/gtwx5715-pci.c
Create this file using one of the existing files, e.g. montejade-pci.c or ixdp425-pci.c, as an example, and the hardware description for your new board. In particular, you will need the GPIO pin assignments for PCI clock, reset and IRQ lines. Here is the file for the GTWX5715 board (taken directly from one of the Linksys GPL releases):
/**************************************************************************
* oarch/arm/mach-ixp425/gtwx5715-pci.c
* This program is free software; you can redistribute it
* and/or modify it under the terms of the GNU General
* Public License as published by the Free Software
* Foundation; either version 2 of the License, or (at
* your option) any later version.
* This copyright notice should not be removed
#include <asm/mach/pci.h>
#include <asm/arch/irqs.h>
#include <asm/arch/pci.h>
#include <asm/arch/ixp425-gpio.h>
#include <asm/arch/ixp425-pci.h>
#define IXP425_PCI_INTA_IRQ IRQ_IXP425_INTC_GPIO11
#define IXP425_PCI_INTB_IRQ IRQ_IXP425_INTC_GPIO10
void __init gtwx5715_pci_init(void *sysdata)
* Insert code here to reset PCI bus
ixp425_pci_init(sysdata);
static int __init gtwx5715_map_irq(struct pci_dev *dev, u8 slot, u8 pin)
return IRQ_GTWX5715_PCI_INTA;
return IRQ_GTWX5715_PCI_INTB;
struct hw_pci gtwx5715_pci __initdata = {
map_irq: gtwx5715_map_irq,
/**************************************************************************
8. include/asm-arm/arch-ixp425/irqs.h
Add definitions for the board-specific interrupt line numbers returned in the IRQ mapping function in the previous step:
#define IRQ_GTWX5715_PCI_INTA IRQ_IXP425_GPIO11
#define IRQ_GTWX5715_PCI_INTB IRQ_IXP425_GPIO10
Once you have completed all of those steps, you can change the kernel configuration to select your newly added board and try building it.
When you are happy with the kernel configuration, copy the .config file to:
arch/arm/def-configs/<BoardName>
as the default configuration file for the new board.
Hints & Tips
On some IXP4xx based boards, such as the ADI Engineering Coyote, the console is connected to UART2 instead of UART1. In cases like these, you must change the kernel's command line (CONFIG_CMDLINE) to specify the console as ttyS1 instead of ttyS0.
Atheros AR531x/AR231x Boards
Kernel Changes
Since the Atheros AR5312 and AR2313 based boards are generally very similar, in a large part due to the high level of integration of peripherals into the CPU itself, the changes required to move to a new board are very minimal. This section describes these changes, and uses the example of adding support for the D-Link DWL-2210AP, a commercially available board based on the AR2313 part.
1. arch/mips/config-shared.in
Add the name of your new board type to the choice section for AR531X boards:
comment 'Board selection'
"UNKNOWN CONFIG_APUNKNOWN \
Below that choice section, add a new conditional block to select the correct flash bus width for the board. In general AR5312 boards have a 16 bit flash bus (CONFIG_MTD_PHYSMAP_BUSWIDTH = 2), and AR2313 boards have an 8 bit flash bus (CONFIG_MTD_PHYSMAP_BUSWIDTH = 1), but check the hardware design if you are unsure. In the case of the D-Link DWL-2210AP, the bus width is 8 bits:
if [ "$CONFIG_DWL2210" = "y" ]; then
define_int CONFIG_MTD_PHYSMAP_BUSWIDTH 1
2. include/asm-mips/bootinfo.h
Add a new machine type for the board to the section of machine types for Atheros-based boards:
#define MACH_ATHEROS_DWL2210 7 /* DWL-2210AP */
Make sure that the number you assign is not already taken (recommendation: use the last number in the list plus 1).
3. arch/mips/ar531x/ar531xprom.c
Add a new conditionally compiled section setting the mips_machtype variable appropriately for the new board:
mips_machtype = MACH_ATHEROS_DWL2210;
Once you have completed all of those steps, you can change the kernel configuration to select your newly added board and try building it.
When you are happy with the kernel configuration, copy the .config file to:
arch/mips/<DeconfigsBoardName>
as the default configuration file for the new board.
Hints & Tips
Booting Without a Bootloader
It is possible with the MIPS boards to boot them without a bootloader. While this is less useful during development (especially while porting a kernel to the board), for a production system it has a number of advantages:
- The space taken up by the bootloader in flash is saved (the additional code needed in the kernel to make it initialize the CPU and self-extract is much smaller than the bootloader).
- The boot time is reduced
The changes needed to support this are as follows:
- CONFIG_BOOTLOADER
Make sure that the CONFIG_BOOTLOADER option in the kernel configuration file is not set. When this is set, the CPU initialization code is not included in the kernel image.
- Flash Partitioning
Since the normal kernel uses Redboot's flash partition table to define the flash partitions, when booting without it we need to define a flash mapping manually. The following changes need to be made to convert from Redboot partitions to manually specified partitions:
- Make sure CONFIG_MTD_REDBOOT_PARTS is not set (if manually editing the file, you can then delete all the CONFIG_MTD_REDBOOT_PARTS_* settings as well)
- Make sure CONFIG_MTD_AR531X is selected, and CONFIG_MTD_AR531X_SIZE is set correctly to the size of the flash (in bytes).
- Update drivers/mtd/maps/ar531x-flash.c to define the partitions that are required for your board. Take into account both the overall size of the flash device and the erase block size when choosing the partition sizes.
Broadcom BCM94712 Boards
Kernel
In most cases there will never be any need to change the kernel source itself. Most, if not all changes necessary can be made using the existing kernel configuration options.
Bootloader: CFE
The supported bootloader for Broadcom based boards is CFE. You should contact Broadcom to obtain the sources for this bootloader and information about porting it to your new hardware platform.
