Build and Load
From Ubicom Developer
Table of content
Update Build Environment
Ubicom BSP contains the ubcom32toolchain directory with all the utilities required to build the firmware.
Update your PC
To be able to configure and build the distribution, your host PC needs to be updated with the latest packages. Please refer to FAQs section for information about errors you encounter during the build process.
Make sure that following packages are installed on your system (as well as development versions of them): binutils, glibc, gcc, gdb, ncurses, zlib, sharutils, ctags
For example on PC with Debian based distributions (Ubuntu, Knoppix) you would do the following:
sudo apt-get update sudo apt-get install build-essential \ sharutils exuberant-ctags zlib1g zlib1g-dev libncurses5 libncurses5-dev \ libgcc1 gcc gcc++ gdb expect bison flex makedepend libglib2.0-dev
Update Ubicom high-speed programming dongle
You will use the Ubicom dongle to program boards with the firmware you build. You might have dongles with old firmware. Use the web UI of the dongles to upgrade them. Firmware for upgrading the dongle can be found in the ubicom-dist-1.0/ultra/tools/bin/dongle directory.
Setup terminal environments
most of the Linux distributions use export to set environment variables vs others that use setenv to do the same. Please refer to your distributions documentation on how to set environment variables.
This is an example of how to set the necessary environment variables using export:
export UBICOM_DIST=/home/username/ubicom-dist-1.0/ export PATH=$PATH:$UBICOM_DIST/toolchain/bin export LD_LIBRARY_PATH=$UBICOM_DIST/toolchain/lib:$LD_LIBRARY_PATH
This is an example of how to set the necessary environment variables using setenv:
setenv UBICOM_DIST /home/username/ubicom-dist-1.0/
setenv PATH {$PATH}:{$UBICOM_DIST}/toolchain/bin
setenv LD_LIBRARY_PATH {$UBICOM_DIST}/toolchain/lib:{LD_LIBRARY_PATH}
uClinux vs OpenWrt
The Ubicom Linux distribution includes a uClinux and router specific OpenWrt distribution. uClinux is the distribution of choice for Media and other embedded products. OpenWrt on the other hand is the distribution of choice for building a router. Configuring / building / loading uClinux vs OpenWrt is slightly different. Please refer to Configuration and Loading uClinux for uClinux and refer to Configuration and Loading OpenWrt for OpenWrt.
Configuration and Loading uClinux
Configuring uClinux
STEP 1: Start the configuration environment
To start the configuration process through the menuconfig system type make menuconfig in the root directory of the distribution.
Type "make menuconfig" in the root directory of the distribution.
You should see the top level configuration screen as show below:
1 Distro (uClinux) ---> 2 [ ] Run distro menuconfig 3 [ ] Enable U-Boot --- ******** Ultra settings ********** 4 Board (IP7160Eval.brd) ---> 5 LPJ (ultra7k.lpj) ---> 6 [ ] Regenerate ultra configs 7 [ ] Enable Profiler --- 8 Reset to defaults 9 Load an Alternate Configuration File 10 Save Configuration to an Alternate File
STEP 2: Select distro
Select "uClinux" under "Distro" and select "Run distro menuconfig".
STEP 3: Enable U-Boot
U-Boot is a universal bootloader and probably the most popular boot loader for embedded Linux devices. The Ubicom distribution has the ability to use U-Boot as the boot loader for the system.
Select "Enable U-Boot" by checking the box.
STEP 4: Select board file
The Ubicom distribution uses .brd board files to enable certain H/W features in the chip and place certain functionality on a certain port / set of pins of the chip. Please refer to XXXX for details on board files and how to customize them for your custom board.
The following boards are available:
- IP7160Eval.brd
- Select this option to build for the "UBICOM IP7160 RGW EVAL REV 1.1" board.
- IP7160Eval_Rev12.brd
- Select this option to build for the "UBICOM IP7160 RGW EVAL REV 1.2" board.
- IP7160Eval_WANonSW.brd
- Select this option to build for the "UBICOM IP7160 RGW EVAL REV 1.1" board and which to use port marked WAN as your WAN port.
- IP7160Eval_WANonSW_Rev12.brd
- Select this option to build for the "UBICOM IP7160 RGW EVAL REV 1.2" board and which to use port marked WAN as your WAN port.
- IP7500AVEth.brd
- Select this board to build for the "IP7K Audio Video Board Rev 1.0" board.
- IP7500Media.brd
- Select this board if you have a "IP7K Audio Video Board Rev 1.0" board.
- IP7500MediaEth.brd
- Select this board if you have a "IP7K Media 1.0" board in combination with a CPU module board that has the Ethernet connector populated.
- IP7500Module.brd
- Select this board if you have a "IP7K CPU Module Rev 1.1" board.
In this guide the CPU module is used as an example.
Select the IP7500Module.brd under "Board".
STEP 5: Select LPJ file
The Ubicom distribution uses .lpj project files to enable certain functionality like Ethernet, SPI, I2S, etc. The above mentioned .brd files place these H/W features on a certain port or set of pins. Since the selection under STEP 4 selected IP7500Module.brd is populated with a IP7000 series processor the appropriate .lpj file to select is ultra7k.lpj.
Select ultra7k.lpj under "LPJ"
STEP 6: Saving the top level configuration
Now that the top level configuration is in place, it is time to save these configurations and continue with the configuration of uClinux. Below is what the screen should look like:
1 Distro (uClinux) ---> 2 [*] Run distro menuconfig 3 [*] Enable U-Boot --- ******** Ultra settings ********** 4 Board (IP7500Module.brd) ---> 5 LPJ (ultra7k.lpj) ---> 6 [ ] Regenerate ultra configs 7 [ ] Enable Profiler --- 8 Reset to defaults 9 Load an Alternate Configuration File 10 Save Configuration to an Alternate File
Select "< Exit >" and when prompted "Do you wish to save your new Ubicom Distro configuration" select "< Yes >"
STEP 7: uClinux Distribution Configuration
After the configuration is saved, the main uClinux distribution configuration screen is shown as below:
Vendor/Product Selection --->
Kernel/Library/Defaults Selection --->
---
Load an Alternate Configuration File
Save an Alternate Configuration File
Select "Vendor/Product Selection"
This will bring up the "Vendor/Product Selection" as shown below:
--- Select the Vendor you wish to target
Vendor (Ubicom) --->
--- Select the Product you wish to target
Ubicom Products (AccessPoint) --->
Make sure that "Ubicom" is selected as the "Vendor" and select "Starter" under "Ubicom Products". Select "< Exit >" to return to the main menu.
STEP 8: Kernel/Library/Defaults Selection
The kernel configuration needs to be customized for the specific board the image needs to run on.
Under Kernel/Library/Defaults select "Customize Kernel Settings" as shown below:
--- Kernel is linux-2.6.x
Libc Version (uClibc) --->
[ ] Default all settings (lose changes) (NEW)
[*] Customize Kernel Settings
[ ] Customize Module Settings (NEW)
[ ] Customize Application/Library Settings (NEW)
[ ] Update Default Vendor Settings (NEW)
Select "< Exit >" to return to the Main configuration screen.
Select "< Exit >" again to exit from the main menu. When presented with the question "Do you wish to save your new kernel configuration?" select "< Yes >".
STEP 9: Linux Kernel customization
At this point the Linux Kernel Configuration screen should be shown as below:
Processor type and features --->
Kernel hacking --->
Executable file formats --->
General setup --->
[*] Enable loadable module support --->
[*] Enable the block layer --->
Preemption Model (No Forced Preemption (Server)) --->
[*] Tickless System (Dynamic Ticks)
[ ] High Resolution Timer Support
Memory model (Flat Memory) --->
[ ] 64 bit Memory and IO resources (EXPERIMENTAL)
[*] Networking support --->
Device Drivers --->
File systems --->
Security options --->
<*> Cryptographic API --->
OCF Configuration --->
Library routines --->
---
Load an Alternate Configuration File
Save an Alternate Configuration File
Under "Processor type and features" select "IP7500MODULE" for "Board type" as shown below:
*** Processor type will be selected by Board ***
*** Board ***
Board type (IP7500MODULE) --->
*** Kernel Options ***
[ ] Symmetric multi-processing support
(0) Number of additional physical timer events to create
The last step in the configuration is to save the kernel configuration.
Select < Exit > twice. When presented with the question "Do you wish to save your new kernel configuration?", select "< Yes >" to go back to the command prompt.
Building uClinux
Building uClinux can now be simply done by typing make. This will build all images necessary. Type following command to build the system.
make
There are other possible make targets than the default target. To see the other make targets type make help. Below is an example output of this command.
Basic Targets
<default> - build currently selected Linux distribution and bootloader
NOTE: When you use this, the bootloader is only built once and
will not be rebuilt again unless you use 'make bootloader_clean'.
Alternatively, you can type 'make bootloader' to force bootloader
recompilation. Use 'make ready' to see if *.elf files are ready.
menuconfig - top level Configure
NOTE: This allows you to Change/Update the selected Linux distribution
(uClinux, OpenWrt) and Enable/Disable U-Boot, etc.
info - see your current settings
ready - check if binaries are ready to start loading to board
bootloader - build <ultra>/projects/bootexec and <uboot> if enabled
NOTE: If U-Boot is disabled, only Ultra will be built. Use
'make ready' to see if *.elf files are ready.
bootloader_X - call 'make X' under <ultra>/projects/bootexec and <uboot> if enabled
install_bootloader - load bootloader to board
install - load currently selected Linux distribution to board
install_all - load bootloader and currently selected Linux distribution to board
clean - clean currently selected Linux distribution build files
clean_all - clean bootloader and currently selected Linux distribution build files
distclean - distclean currently selected Linux distribution and global ubicom-distro build files
distclean_all - distclean bootloader, currently selected Linux distribution and global ubicom-distro build files
setup_toolchain - try to symlink/download the toolchain
Advanced Targets
genconfig - force to regenerate ultra configs
NOTE: If configs are never generated, they will already be generated internally
bootexec - build <ultra>/projects/bootexec
bootexec_X - build <ultra>/projects/bootexec target X
uboot - build <uboot>
uboot_X - build in <uboot> target X
install_bootexec - load <ultra>/projects/bootexec binary
install_uboot - load <uboot> binary
Loading the uClinux image
Build sanity check
To sanity check the build and make sure that all image are ready to be loaded onto the board type the command below
make ready
The output tells you if the image are ready and should look like this:
-bash-3.2$ make ready Checking final elf files... /home/username/ubicom-dist-1.0/ultra/projects/bootexec/ultra.elf: ready /home/username/ubicom-dist-1.0/ultra/projects/bootexec/u-boot.elf: ready /home/username/ubicom-dist-1.0/ultra/projects/bootexec/vmlinux.elf: ready
Loading the firmware
Before continuing make sure that the UBICOM_DONGLE environment variable is set to the proper value. Please refer to Ubicom Dongle on how to set this environment variable.
type make install_all to install all images onto the board.
You should see something similar to the below out put.
-bash-3.2$ make install_all
expect /home/username/ubicom-dist/ultra/scripts/prog_board.exp ubicom32 /home/username/ubicom-dist/ultra/projects/bootexec/ultra.elf
spawn ubicom32-elf-gdb --quiet
(gdb) file /home/username/ubicom-dist/ultra/projects/bootexec/ultra.elf
Reading symbols from /home/username/ubicom-dist/ultra/projects/bootexec/ultra.elf...done.
(gdb) target ubicom32 10.10.30.34:5010
0x3ffc0a68 in memcpy (dest=0x40000000, src=0x3ffd0028, n=1)
at /home/username/ubicom-dist/ultra/pkg/ipLibC/src/ubicom32/mem_ubicom32.c:39
39 asm volatile (
(gdb) load
Begin Erase.
0x60000000 length 0x1a048
................................................................................
Begin download
................................................................................
system_main () at /home/username/ubicom-dist/ultra/pkg/ipThread/include/ubicom32/thread.h:44
44 asm volatile (
(gdb) detach
(gdb) expect /home/username/ubicom-dist/ultra/scripts/prog_board.exp ubicom32 /home/username/ubicom-dist/ultra/projects/bootexec/u-boot.elf
spawn ubicom32-elf-gdb --quiet
(gdb) file /home/username/ubicom-dist/ultra/projects/bootexec/u-boot.elf
Reading symbols from /home/username/ubicom-dist/ultra/projects/bootexec/u-boot.elf...done.
(gdb) target ubicom32 10.10.30.34:5010
0x3ffc1038 in ?? ()
(gdb) load
Begin Erase.
0x60020000 length 0x13fa4
................................................................................
Begin download
................................................................................
0x40004890 in ?? ()
(gdb) detach
(gdb) expect /home/username/ubicom-dist/ultra/scripts/prog_board.exp ubicom32 /home/username/ubicom-dist/ultra/projects/bootexec/vmlinux.elf
spawn ubicom32-elf-gdb --quiet
(gdb) file /home/username/ubicom-dist/ultra/projects/bootexec/vmlinux.elf
Reading symbols from /home/username/ubicom-dist/ultra/projects/bootexec/vmlinux.elf...done.
(gdb) target ubicom32 10.10.30.34:5010
0x3ffc06a4 in ?? ()
(gdb) load
Begin Erase.
0x60040000 length 0x4436bc
................................................................................
Begin download
................................................................................
0x40004890 in ?? ()
(gdb) detach
Configuration and Loading OpenWrt
Configuring OpenWrt
STEP 1: Start the configuration environment
To start the configuration process through the menuconfig system type make menuconfig in the root directory of the distribution.
Type "make menuconfig" in the root directory of the distribution.
You should see the top level configuration screen as show below:
1 Distro (OpenWrt) ---> 2 [ ] Run distro menuconfig 3 [ ] Enable U-Boot --- ******** Ultra settings ********** 4 Board (IP7160Eval.brd) ---> 5 LPJ (ultra7k.lpj) ---> 6 [ ] Regenerate ultra configs 7 [ ] Enable Profiler --- 8 Reset to defaults 9 Load an Alternate Configuration File 10 Save Configuration to an Alternate File
STEP 2: Select distro
Select "OpenWrt" under "Distro" and select "Run distro menuconfig".
STEP 3: Enable U-Boot
U-Boot is a universal bootloader and probably the most popular boot loader for embedded Linux devices. The Ubicom distribution has the ability to use U-Boot as the boot loader for the system.
Select "Enable U-Boot" by checking the box.
STEP 4: Select board file
The Ubicom distribution uses .brd board files to enable certain H/W features in the chip and place certain functionality on a certain port / set of pins of the chip. Please refer to XXXX for details on board files and how to customize them for your custom board.
The following boards are available:
- IP7160Eval.brd
- Select this option to build for the "UBICOM IP7160 RGW EVAL REV 1.1" board.
- IP7160Eval_Rev12.brd
- Select this option to build for the "UBICOM IP7160 RGW EVAL REV 1.2" board.
- IP7160Eval_WANonSW.brd
- Select this option to build for the "UBICOM IP7160 RGW EVAL REV 1.1" board and which to use port marked WAN as your WAN port.
- IP7160Eval_WANonSW_Rev12.brd
- Select this option to build for the "UBICOM IP7160 RGW EVAL REV 1.2" board and which to use port marked WAN as your WAN port.
- IP7500AVEth.brd
- Select this board to build for the "IP7K Audio Video Board Rev 1.0" board.
- IP7500Media.brd
- Select this board if you have a "IP7K Audio Video Board Rev 1.0" board.
- IP7500MediaEth.brd
- Select this board if you have a "IP7K Media 1.0" board in combination with a CPU module board that has the Ethernet connector populated.
- IP7500Module.brd
- Select this board if you have a "IP7K CPU Module Rev 1.1" board.
note: OpenWrt only runs on the UBICOM IP7160 RGW EVAL boards. Selecting any other board will result in a build failure!
Select the IP7160Eval_WANonSW_RevXX.brd board under "Board" where XX is either 1.1 or 1.2 depending on the board revision the image needs to be build for.
STEP 5: Select LPJ file
The Ubicom distribution uses .lpj project files to enable certain functionality like Ethernet, SPI, I2S, etc. The above mentioned .brd files place these H/W features on a certain port or set of pins. Since the selection under STEP 4 selected IP7500Module.brd is populated with a IP7000 series processor the appropriate .lpj file to select is ultra7k.lpj.
Select ultra7k.lpj under "LPJ"
STEP 6: Saving the top level configuration
Now that the top level configuration is in place, it is time to save these configurations and continue with the configuration of OpenWrt. Below is what the screen should look like:
1 Distro (OpenWrt) ---> 2 [*] Run distro menuconfig 3 [*] Enable U-Boot --- ******** Ultra settings ********** 4 Board (IP7500Module.brd) ---> 5 LPJ (ultra7k.lpj) ---> 6 [*] Regenerate ultra configs 7 [ ] Enable Profiler --- 8 Reset to defaults 9 Load an Alternate Configuration File 10 Save Configuration to an Alternate File
Select "< Exit >" and when prompted "Do you wish to save your new Ubicom Distro configuration" select "< Yes >"
STEP 7: OpenWrt Distribution Configuration
After the configuration is saved, the main OpenWrt configuration screen is shown as below. No changes are required to this configuration for building the OpenWrt router project.
Target System (Ubicom IPxx [2.6]) --->
Subtarget (IP7160RGW) --->
Target Profile (RouterGateway) --->
Target Images --->
[ ] Select all packages by default (NEW)
[*] Advanced configuration options (for developers) (NEW) --->
[ ] Build the OpenWrt SDK (NEW)
[ ] Image configuration (NEW) --->
Base system --->
Utilities --->
Network --->
Libraries --->
IPv6 --->
Kernel modules --->
Languages --->
Boot Loaders --->
Administration --->
---
Reset to defaults
Load an Alternate Configuration File
Save Configuration to an Alternate File
Select "< Exit >" and when presented with the question "Do you wish to save your new OpenWrt configuration?" select < Yes > to save the OpenWrt configuration.
Building OpenWrt
Building uClinux can now be simply done by typing make. This will build all images necessary. Type following command to build the system.
make
There are other possible make targets than the default target. To see the other make targets type make help. Below is an example output of this command.
Basic Targets
<default> - build currently selected Linux distribution and bootloader
NOTE: When you use this, the bootloader is only built once and
will not be rebuilt again unless you use 'make bootloader_clean'.
Alternatively, you can type 'make bootloader' to force bootloader
recompilation. Use 'make ready' to see if *.elf files are ready.
menuconfig - top level Configure
NOTE: This allows you to Change/Update the selected Linux distribution
(uClinux, OpenWrt) and Enable/Disable U-Boot, etc.
info - see your current settings
ready - check if binaries are ready to start loading to board
bootloader - build <ultra>/projects/bootexec and <uboot> if enabled
NOTE: If U-Boot is disabled, only Ultra will be built. Use
'make ready' to see if *.elf files are ready.
bootloader_X - call 'make X' under <ultra>/projects/bootexec and <uboot> if enabled
install_bootloader - load bootloader to board
install - load currently selected Linux distribution to board
install_all - load bootloader and currently selected Linux distribution to board
clean - clean currently selected Linux distribution build files
clean_all - clean bootloader and currently selected Linux distribution build files
distclean - distclean currently selected Linux distribution and global ubicom-distro build files
distclean_all - distclean bootloader, currently selected Linux distribution and global ubicom-distro build files
setup_toolchain - try to symlink/download the toolchain
Advanced Targets
genconfig - force to regenerate ultra configs
NOTE: If configs are never generated, they will already be generated internally
bootexec - build <ultra>/projects/bootexec
bootexec_X - build <ultra>/projects/bootexec target X
uboot - build <uboot>
uboot_X - build in <uboot> target X
install_bootexec - load <ultra>/projects/bootexec binary
install_uboot - load <uboot> binary
Loading the OpenWrt image
Build sanity check
To sanity check the build and make sure that all image are ready to be loaded onto the board type the command below
make ready
The output tells you if the image are ready and should look like this:
-bash-3.2$ make ready Checking final elf files... /home/username/ubicom-dist-1.0/ultra/projects/bootexec/ultra.elf: ready /home/username/ubicom-dist-1.0/ultra/projects/bootexec/u-boot.elf: ready /home/username/ubicom-dist-1.0/ultra/projects/bootexec/vmlinux.elf: ready
Loading the firmware
Before continuing make sure that the UBICOM_DONGLE environment variable is set to the proper value. Please refer to Ubicom Dongle on how to set this environment variable.
type make install_all to install all images onto the board.
You should see something similar to the below out put.
-bash-3.2$ make install_all
expect /home/username/ubicom-dist/ultra/scripts/prog_board.exp ubicom32 /home/username/ubicom-dist/ultra/projects/bootexec/ultra.elf
spawn ubicom32-elf-gdb --quiet
(gdb) file /home/username/ubicom-dist/ultra/projects/bootexec/ultra.elf
Reading symbols from /home/username/ubicom-dist/ultra/projects/bootexec/ultra.elf...done.
(gdb) target ubicom32 10.10.30.34:5010
0x3ffc0a68 in memcpy (dest=0x40000000, src=0x3ffd0028, n=1)
at /home/username/ubicom-dist/ultra/pkg/ipLibC/src/ubicom32/mem_ubicom32.c:39
39 asm volatile (
(gdb) load
Begin Erase.
0x60000000 length 0x1a048
................................................................................
Begin download
................................................................................
system_main () at /home/username/ubicom-dist/ultra/pkg/ipThread/include/ubicom32/thread.h:44
44 asm volatile (
(gdb) detach
(gdb) expect /home/username/ubicom-dist/ultra/scripts/prog_board.exp ubicom32 /home/username/ubicom-dist/ultra/projects/bootexec/u-boot.elf
spawn ubicom32-elf-gdb --quiet
(gdb) file /home/username/ubicom-dist/ultra/projects/bootexec/u-boot.elf
Reading symbols from /home/username/ubicom-dist/ultra/projects/bootexec/u-boot.elf...done.
(gdb) target ubicom32 10.10.30.34:5010
0x3ffc1038 in ?? ()
(gdb) load
Begin Erase.
0x60020000 length 0x13fa4
................................................................................
Begin download
................................................................................
0x40004890 in ?? ()
(gdb) detach
(gdb) expect /home/username/ubicom-dist/ultra/scripts/prog_board.exp ubicom32 /home/username/ubicom-dist/ultra/projects/bootexec/vmlinux.elf
spawn ubicom32-elf-gdb --quiet
(gdb) file /home/username/ubicom-dist/ultra/projects/bootexec/vmlinux.elf
Reading symbols from /home/username/ubicom-dist/ultra/projects/bootexec/vmlinux.elf...done.
(gdb) target ubicom32 10.10.30.34:5010
0x3ffc06a4 in ?? ()
(gdb) load
Begin Erase.
0x60040000 length 0x4436bc
................................................................................
Begin download
................................................................................
0x40004890 in ?? ()
(gdb) detach
