LxNETES™ User’s Guide ConnectCore 9P 9360/9750
Digi International Inc. 2005. All Rights Reserved. The Digi logo is a registered trademarks of Digi International, Inc. All other trademarks mentioned in this document are the property of their respective owners. Information in this document is subject to change without notice and does not represent a commitment on the part of Digi International.
Contents • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •• • • • • • • • • • • • Chapter 1 Introduction........................................................................ 9 Overview..................................................................................................................9 Cross-development environment .......................................................................9 Linux kernel sources ..................
Manual Installation ................................................................................................27 Chapter 4 Building the First Project................................................. 29 Building the Default Project ..................................................................................29 Step 1: Run configure ................................................................................29 Example: ...........................................................................
Introduction......................................................................................................44 U-Boot ...................................................................................................................44 ConnectCore 9P 9360/9750 .............................................................................45 Linux boot methods ...............................................................................................46 TFTP/NFS........................................
LCD interface ..................................................................................................62 Touch screen interface .....................................................................................62 CC9P9360/9750.........................................................................................62 Compact flash interface ...................................................................................63 CC9P6360/9750..........................................................
Introduction Introduction C H A P T E R 1 Overview The LxNETES package enables you to easily develop software under Linux 2.6 for Digi International and FS Forth-Systeme embedded modules supported in this release of LxNETES. This document assumes that you have basic knowledge of Linux. In addition, it is recommended that you have experience with compiling a standard Linux kernel on your host PC. If you are new to Linux, the following books are recommended for resources: 1.
Overview Linux kernel sources The LxNETES package contains the complete source code of the Linux kernel. This allows you to configure, modify, and create a custom kernel to your specific embedded system’s needs. Although the kernel sources are the official distribution, some modifications have been made to adapt the sources to the supported platforms. Template project The philosophy of work in LxNETES environment is linked to the idea of ‘projects’.
Introduction Features What’s new in LxNETES 3.2? Linux Kernel Linux Kernel 2.6.12.5 Added touch screen driver for the ConnectCore 9P family Added RTC driver for the ConnectCore 9P family Build process based on autoconf Bootloader New U-Boot boot loader, based on version 1.1.3 Tool chain gcc-3.4.4 cross compiler for NET+ARM, ARM, and XScale processors For existing LxNETES customers: LxNETES 3.2 uses a different uClibc than previous versions of LxNETES which is not backwards compatible.
Features Drivers for the following module components and interfaces: – SDRAM memory – Flash memory – Ethernet – USB Host – Serial – I2C – RTC – GPIO – Watchdog – LCD Framebuffer – Compact Flash Cards – SD Cards – PCI – SPI – Touch Screen – User Buttons if available U-Boot universal bootloader, capable of booting Linux and other operating systems from Ethernet, Flash memory and USB. C and C++ support for application development gcc-3.4.
Introduction Autoconf driven build process All building can be done without root access This LxNETES version can coexist with older installations of LxNETES Conventions used in this manual The following is a list of the typographical conventions used in this manual: Style Style Style # $ [1] Used for file and directory names, programs and command names, command-line options, URL, and new terms. Used in examples to show the contents of files, the output from commands or in the text the C code.
Features # # This is a target session And this is what you must input (in bold) Acronyms and abbreviations CGI CRAMFS DHCP GDB GPIO Compressed ROM File system Dynamic Host Configuration Protocol (RFC 2131) GNU debugger General Purpose Input/Output INITRD Initial Ram Disk IP Internet Protocol JFFS(2) Journaling Flash File System (version 2) JTAG Joint Test Action Group (IEEE 1149.
Requirements Requirements C H A P T E R 2 System Requirements/Prerequisites System requirements Your development system should be a reasonably fast x86-based host PC with an Ethernet interface, a serial port, and a parallel port. Different Linux distributions such as SuSE, Debian, or RedHat can be used for the development. This documentation is based on the Debian Linux distribution; however, other distributions with minor changes in the settings can also be used.
System Requirements/Prerequisites DOS or DOS-emulator (such as dosemu) Optional but recommended components: Qt3 development tools For using LxNETES, a recent Linux distribution based on GNU C Library glibc version 2.3 (a free implementation of the Standard C Library) is needed. To find out which glibc version is installed on your system use the following commands: $ $ ldd --version ls -l /lib/libc*so Please make sure that you use GNU Make version 3.80 or later.
Requirements Applications & Services To use this software, your system has to be configured to build a standard Linux 2.6. If you can build a kernel for your development platform, you can be sure that all the necessary software is installed. Depending on the network services used during the development, additional daemons may have to be installed. TFTP daemon U-Boot is able to write files to the Flash memory of the module.
System Requirements/Prerequisites NFS server Use the network file system (NFS) to simplify application debugging on the target. NFS allows your target to mount its root file system with read/write permissions from the host computer over Ethernet. NFS also allows you to access the file system from the target and from the host computer the same time. The NFS server configuration details are beyond the scope of this User's Manual and are very specific to the various distributions.
Requirements After modifying the exports file, the NFS server has to be restarted with the following command: # /etc/init.d/nfs-kernel-server restart JTAG-Booster The JTAG-Booster software for hardware Flash updates is a DOS application. It must be installed on a native DOS / Windows host or a virtual machine like "dosemu" under Linux. Execute "dosemu" as root to gain full hardware access.
System Requirements/Prerequisites 20 LxNETES User’s Guide
Getting Started Getting Started C H A P T E R 3 Introduction This chapter describes how to configure and test your host PC and development board (target) and how to start up the device for the very first time. Connecting host PC with development board Step 1: Connect serial port Connect the host PC to the development board (target) using a serial null-modem cable. The serial connection is used to interact with the target device.
Introduction To use a terminal client as non-root user, either you need read/write access to /dev/ttyS or the client has to be setuid root. Unless otherwise stated, it is assumed your target is connected to the first serial port (COM 1, ttyS0) of your host. If you use another port, change the “ttyS” to the appropriate number. Minicom To configure minicom, start it as root by entering: # minicom –s Go to “Serial port setup” and change the values to your environment.
Getting Started Figure 3-2: Seyon Settings Step 4: Connect power Connect the included power supply to the development board. After power-on, the LEDs on the board will light up and 2-4 seconds later the system will print boot messages on the console. After 20-25 seconds, the boot loader has unpacked and launched the pre-installed Linux kernel from the built-in Flash memory. You will see output on the terminal client similar to the output below.
Introduction U-Boot 1.1.3 U-Boot code: 20F00000 -> 20F1529C BSS: -> 20F19A80 RAM Configuration: Bank #0: 20000000 32 MB AM29LV128M (16MB) Flash: 16 MB In: serial Out: serial Err: serial Hit any key to stop autoboot: 0 ## Booting image at 20100000 ... Image Name: Linux-2.6.12 Created: 2005-06-17 11:29:13 UTC Image Type: ARM Linux Kernel Image (uncompressed) Data Size: 2478816 Bytes = 2.4 MB Load Address: 20008000 Entry Point: 20008000 Verifying Checksum ... OK OK Starting kernel ... Linux version 2.6.
Getting Started The target network parameters can be changed in U-Boot using the "setenv" command. You can see the IP address of the target by issuing this command: # ifconfig eth0 Link encap:Ethernet HWaddr 12:34:56:78:9A:BC inet addr:192.168.42.10 Bcast:192.168.42.255 Mask:255.255.255.0 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:3453 errors:0 dropped:0 overruns:0 frame:0 TX packets:62 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:1000 RX bytes:399740 (390.
Guided Installation The mount point of the CD drive depends on your distribution. SuSE e.g. uses "/mnt/cdrom" as the default mount point. Check your "/etc/fstab" or ask your Administrator to do this for you. Guided Installation After mounting the CD you are ready to run the installer. Use the following commands to start (depending on your distribution's mount point): $ /media/cdrom/install.sh If the script detects a Perl/Tk installation, a graphical installer will start.
Getting Started Manual Installation Instead of using the installation script you can do the installation manually. Just copy the directory "LxNETES" on the CDROM to a directory on your host PC.
Manual Installation 28 LxNETES User’s Guide
Building the First Project Building the First Project C H A P T E R 4 Building the Default Project Until now you have worked with the pre-loaded, default kernel image on the target. The next step is to rebuild it on your development host PC to familiarize yourself with the build process. Step 1: Run configure Start a new shell and change into your LxNETES installation directory. Create a new directory underneath and change to that directory.
Building the Default Project ConnectCore 9P 9750: cc9p9750dev Please check if the script used the correct platform and detected the right directory to install the kernel and the nfsroot directory. If you used the suggested paths in the setup of the TFTPD and NFS server, the output of configure should contain: checking which directory to install bootfiles to... /tftpboot checking which directory to install nfsroot to...
Application Development Application Development C H A P T E R 5 Writing applications The user applications are stored in subdirectory apps/ of the project folder. The template project includes several demo applications for use as templates to begin developing your own programs. They will automatically build and copy to the folder “/usr/bin/” of the target when building the system.
Writing applications Using C++ A sample C++ application “hello_world” is included in “apps/misc/src/hello_world”. You can use this sample application as a template to develop your own C++ applications. Just use add_app as above and adapt the Makefile.in according to hello_world_cpp/ Makefile.
Application Development Table 6-3: /proc/cpuinfo contents 33
Debugging applications Debugging applications The purpose of a debugger is to allow you to see what is going on his own programs while they execute. For that purpose the GDB debugger is used by means of the gdbserver application that runs on the target side and communicates with the host computer. This communication can happen on the serial port or through Ethernet (the latter is preferred for being much faster). The use of the GDB debugger is out of the scope of this manual.
Application Development In the debug interface type $ $ $ (gdb) set architecture ARCHITECTURE (gdb) set solib-absolute-prefix (gdb) target remote TARGET.IP:2001 The supported architectures can be displayed with the following command: $ (gdb) set architecture Requires an argument. Valid arguments are arm, armv2, armv2a, armv3, armv3m, armv4, armv4t, armv5, armv5t, armv5te, xscale, ep9312, iwmmxt, auto.
Debugging applications Included pre-built applications The sources for the included applications can be found in the software folder on the LxNETES CD. Shell applications: busybox The “busybox” includes all standard shell applications like “cat”, “chmod”, “echo”, “mount”, “sh” and some more. They are linked into one static application to save flash memory, at the cost of a larger RAM footprint for each application, so this is not recommended for daemons.
Application Development Nano-X/microwindows Nano-X makes it possible to write applications using the framebuffer with an API similar to Xlib. There are two demo applications. To use either you must start with the nano-X server. # nano-X & and then the application. # nanox_bar & On targets with small flash, nano-X is disabled by default. You may pass “--enable nano-X” to configure, despite the flash size, but you risk overwriting the rootfs on the target. For further details see http://www.
Useful applications Useful applications mem With this application you can read and write the contents of the SDRAM. All the options of this tool are accessible through a command line.
Kernel Development Kernel Development C H A P T E R 6 Writing kernel modules What is a kernel module? Modules are pieces of code that can be loaded and unloaded into the kernel upon demand. They are useful because they extend the functionality of the kernel without the need to reboot the system. A typical kernel module is the device driver, which allows the kernel to access hardware connected to the system.
Writing kernel modules Add the module to the build environment You have to edit "my_kmodule/Makefile.in" so that the build environment knows what files to build. To include them for the target build, append them to obj-m like "obj-m += my_module.o". The modules must be named like their C-source files. Usable object modules will have the extension ".ko". # Add your kernel modules here obj-m += my_module.o Then you have to add the module to the list of available modules. Edit the configure.
Advanced Topics Advanced Topics C H A P T E R 7 Modifying the default project The following information is the default kernel configuration for LxNETES: serial baudrate 38400 bps Ethernet enabled uses devfs per default The default configuration is made up of 2 layers: Kernel command line parameters: set by U-Boot Kernel configuration: lowest priority The kernel command line parameters can overwrite some configurations.
Modifying the default project Once you have configured the kernel to your system needs, save the configuration and exit. To rebuild the kernel use one of the build commands seen before.
Advanced Topics Building a custom project To create a custom project, that is a project for your custom hardware, first configure the default project. Follow the steps described in "Building the Default Project" up to running configure. Then run: $ $ $ ~/LxNETES-3.2/build$ bin/add_platform –b cc9p9360dev custom checking whether make sets $(MAKE)... yes ... In this example, ConnectCore 9P 9360 dev module (cc9p9360dev)was used as the template project.
Boot process Boot process This chapter describes the boot process of U-Boot and Linux. Introduction A boot loader is a small piece of software that executes soon after powering up a computer. On a desktop PC it resides on the master boot record (MBR) of the hard drive and is executed after the PC BIOS performs various system initializations. The boot loader then passes system information to the kernel and then executes the kernel.
Advanced Topics ConnectCore 9P 9360/9750 On the ConnectCore 9P 9360 and ConnectCore 9P 9750 modules, the SPI boot loader is loaded from the SPI EEPROM which initializes the RAM. Then additional code (~1kB) is loaded into RAM (address 0x0). This code loads U-Boot from NAND flash and executes it. In the next step, U-Boot configures the serial console, the Ethernet interface and the Flash memory and loads the settings stored as environment variables in the nonvolatile memory.
Linux boot methods Linux boot methods Linux is booted by U-Boot in one of the following ways: TFTP/NFS Flash memory USB storage device (e.g. an USB memory stick) The following information describes each boot method. TFTP/NFS With this method, the Linux kernel is downloaded through Ethernet via TFTP protocol from the server's TFTP folder. Use the "tftp" command from the U-Boot command line to copy a kernel image from your TFTP server to the target's RAM. Then use "bootm" to execute it.
Advanced Topics A faster way to do this is to use the "boot_flash" macro. NOR Flash Use the following commands if you have NOR Flash (similar to booting from NAND). # # # setenv bootargs console=... ip=$(ipaddr):$(serverip)::$(netmask):2440:eth0:off root=/dev/mtdblock2 rootfstype=jffs2 cp.b bootm A faster way to do this is to use the "boot_flash" macro. USB It is possible to load a kernel image from a USB storage device.
Linux boot process Update the kenel from the USB stick to the memory and write it to flash memory. # run update_kernel_usb Linux boot process The command “bootm” uncompress the kernel and runs the function start_kernel(). Once the kernel is started, several options are given to the kernel: machine type, command line and ATAG list.
Advanced Topics Uncompressing Linux....................................................................... done, booting the kernel. Linux version 2.6.12.5-fs.1 (jdietsch@onyx.fsforth.de) (gcc version 3.4.
Linux boot process If a wrong command line parameter for "console=" is used, nothing will be displayed after "done, booting the kernel". The system may continue to boot. You may connect to the target by Telnet after telnetd is configured . After finishing the initialization, the filesystems are mounted and the process "/sbin/init" is started with process ID 0. Init runs all applications stated in "/etc/inittab", e.g. "/etc/ init.d/rcS", the various daemons like telnetd and shells on the serial consoles.
Advanced Topics Updating a running system (the easy way) On a running system, that is a system able to start the boot loader, U-Boot contains predefined macros that can update the on-module flash memory. If the boot loader is corrupted, you have to first use a debugger to restore the boot loader which then can be used to restore the remaining images. Power up (or reset) the target. After 2-4 seconds, the boot loader messages appear on the serial port. Hit any key to interrupt the auto-boot process.
Linux boot process Step 1: Download the new image file to RAM The first step is to download the image into RAM. Specify the start address, the end address, and the size of the image in RAM, for example: # mw.l # tftp # Filename .
Advanced Topics For modules with NOR flash, use this command: # cp.b ConnectCore 9P 9360/9750 The following commands are to update the U-Boot loader, Kernel image, and Root file system. U-Boot To update the U-Boot boot loader, type: mw.l 100000 ffffffff 10000 tftp 100000 nand erase 0 40000 nand write.
Updating a corrupted system using a debugger Updating a corrupted system using a debugger ConnectCore 9P 9360/9750 If the Flash memory has become corrupted and the system cannot boot anymore, then the Flash memory must be re-programmed using the JTAG interface and the JTAG-Booster. Connect the JTAG-Boosters 8-pin connector to the development board (JTAG X12). The two black cables point to pin 1. Set DIP-switch S4-1 to "on" and S4-2 to S4-8 to "off". Copy the JTAG tools from the LxNETES-3.
Root File System Types Root File System Types C H A P T E R 8 The following describes the different possibilities which can be used as root file system. The type of rootfs must be passed as an argument to kernel by means of the bootargs environment variable of U-Boot. NFSROOT The rootfs may be in a different computer on the network and not within the target.
# run boot_net This script does three steps (that you can also do manually): Step 1: Set bootargs to be passed to the kernel The environmental variable bootargs must be updated to tell Linux that the rootfs is taken via NFS. To manually do this enter the following commands (it is supposed that the network variables serverip and nfspath have been already set). The values for ip and console have to be filled depending on the platform. # # setenv bootargs nfsroot=$(serverip):$(nfspath) root=nfs ip=...
Root File System Types JFFS2 JFFS is a log-structured journaling flash file system which was designed to be used on Flash devices in embedded systems. It was originally developed for the 2.0 kernel by Axis Communications. JFFS2 is an improved version of JFFS which includes compression and improved read/write access. Find more about JFFS2 at http://sourceware.org/jffs2 NAND chips are not guaranteed to be error free and most chips have bad blocks.
jffs2_get_inode_nodes(): Data CRC failed on node at 0xXX XXXXXX: Read 0xXXXXXXXX, calculated 0xXXXXXXXX The message above is printed if the file system was not cleanly unmounted. The system should not be powered off before all partitions are unmounted. After a clean unmount, the message should disappear. Step 1: Set bootargs to be passed to the kernel The environmental variable bootargs must be updated to tell Linux that the rootfs is taken from Flash and it is stored in JFFS2 file system.
Root File System Types You should use a separate data partition for your data which is frequently updated so your rootfs does not get corrupted.
LxNETES User’s Guide
Interfaces & Devices Interfaces & Devices C H A P T E R 9 The following interfaces and devices are supported in the current LxNETES version: a9m2410 a9m2440 Compact Flash X X Ethernet X X I2C Interface X X LCD X X PCI n/a n/a RTC X X SD card X X Serial X X SPI X Touch screen USB Host cc9c cc9p9360 cc9p9750 ccxp270 X X X only available on the UNCBASCF base board X X X X X X X X X X X X X n/a X n/a n/a X X X X n/a unc90 n/a X X X X X X
USB host interface A USB host driver is included and enabled in the default kernel configuration. To operate multiple USB devices simultaneously, connect a USB hub to the USB host port. A memory stick can be mounted as followed # # lxmount usb ls -l /media/usbdisk I2C interface A driver for the I2C interface is included and enabled in the default kernel configuration. Devices attached to the I2C interface can be accessed via /sys/bus/i2c/device/.
Interfaces & Devices Compact flash interface CC9P6360/9750 A driver for the internal Compact Flash (CF) card interface is included and enabled in the default kernel configuration. A CF card can be mounted as follows # # lxmount cf ls -l /media/cf SD card interface A SD card can be mounted as follows: # # lxmount sd ls -l /media/sd Real time clock (RTC) A driver for the RTC, which is connected to the I2C interface, is included and enabled in the default kernel configuration.
The next step is to store this information into the RTC. Use the application hwclock: # hwclock Fri Jun 3 13:22:44 UTC 2005 0.000000 seconds Now you can reset or power off your target. The small battery on the development board will keep the correct time/date values and are saved when you power up your target again. PCI interface A driver for the PCI interface can be enabled in the kernel configuration. You can use Mini-PCI cards with the Mini-PCI slot on the development board.
Appendix A •••••••••••••••••••••••••••••••••••••••••••••••••••••••• Related documentation http://www.modarm9.com http://www.fsforth.de http://www.kernel.org http://u-boot.sourceforge.net http://www.uclibc.org http://www.abatron.ch http://www.samsung.com http://www.netsilicon.com http://www.atmel.com Linux Device Drivers http://sourceware.org/jffs2 http://sources.redhat.com/jffs2 http://www.gnu.
Related documentation There following folders are on the CD: Readme.txt Briefly describes LxNETES and lists the CD contents. RelNotes.txt Contains the last release information. install.sh A script to install LxNETES on your host computer. For more information see chapter 4 (installation). docs The doc folder contains this User's Manual and additional documentation. images This folder contains pre-built images for your target platform.
ConnectCore 9P 9360 (CC9P9360) File Description u-boot-cc9p9360dev.bin U-Boot boot loader image for the ConnectCore 9P 9360 module on the ConnectCore 9P development board. uImage-cc9p9360dev.bin Linux kernel image for the ConnectCore 9P 9360 module on the ConnectCore 9P development board. rootfs-cc9p9360dev.jffs2 Root file system for the ConnectCore 9P 9360 module. ConnectCore 9P 9750 (CC9P9750) File Description u-boot-cc9p9750dev.
Memory layouts upstream LxNETES is based on various open source projects. The original source code from these projects is stored in this folder. The following source code is included: Linux Buildroot U-Boot This folder contains the source code of U-Boot including all patches which are necessary for the specific target. Memory layouts Flash memory layout The partitioning of the nonvolatile memory is described in this following table.
ConnectCore 9P 9360 / ConnectCore 9P 9750 RAM Start Address 0x00000000 0x00080000 0x00080000 0x00100000 0x00108000 RAM End Address 0x00080000 0x000C0000 Description U-Boot stack TEXT_BASE U-Boot default load address in UBoot for Linux kernel entry point of the decompressed kernel Used by U-Boot Linux 69
Memory layouts 70 LxNETES User’s Guide
Appendix B •••••••••••••••••••••••••••••••••••••••••••••••••••••••• U-Boot command reference This chapter gives an overview of common used U-Boot commands. Detailed information can be found at: http://www.denx.de/wiki/view/DULG/Manual?stickboard=tqm8xxl To get to the U-Boot prompt press any key immediately after you have powered the target on or pressed reset. At the prompt type “help” or “?” to get an overview of the supported commands.
U-Boot command reference # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 72 help ? autoscr base bdinfo boot bootd bootelf bootm bootp bootvx cmp coninfo cp crc32 date echo eeprom fatinfo fatload fatls fsinfo fsload go help icrc32 iloop imd iminfo imls imm imw inm iprobe itest loadb loads loop ls md mm mtest mw nand nboot nfs nm ping printenvrarpbootreset run saveenv setenv sleep tftpbootusb usbboot version - alias for 'help' run scrip
Each of these commands has additional help available, which can be viewed by entering help . All numeric values, which are needed for different commands, are interpreted as HEX values. Entering 30100000 means 0x30100000.To speed up programming, the real size of the image files can be used.
U-Boot command reference fatload usb DEV:PART ADDR image loads image to ADDR from USB storage device DEV with the partiton number PART to ADDR help shows all of the available commands help ITEM shows all of the available commands belonging to a particular item. e.g.
The command “run” allows to execute variables as sequence od commands. Here values of other variables could be used to simplify the scripts. (e.g. $(filesize) ) Example (A9M24x0): The following variables are available: ipaddr = 192.168.42.10 serverip = 192.168.42.
