Digi Digi/FS Forth ModNET50 Module w/16MB SDRAM, 2MB Flash User manual

LxNETES

User's Manual

P.O: Box 1103

Kueferstrasse 8

Tel. +49 (7667) 908-0

[email protected]

• D-79200 Breisach, Germany

• D-79206 Breisach, Germany

• Fax +49 (7667) 908-200

• http://www.fsforth.de

LxNETES

2

FS Forth-Systeme GmbH

Postfach 1103, 79200 Breisach, Germany

Release of Document: October 31, 2003

Filename: LxNETES.doc

Author: M. Pietrek / N. James

Program Version: 2.3

form or by any means without the prior written consent of FS Forth-Systeme

GmbH.

LxNETES

3

Table of Contents

1. Documentation History ...................................................................................6

2. Preface...........................................................................................................7

3. Features.........................................................................................................8

4. Requirements.................................................................................................9

4.1. Free Space..........................................................................................9

4.2. Applications..........................................................................................9

4.3. Serial Port Nomenclature.....................................................................9

4.4. LxNETES CD.....................................................................................10

4.4.1. doc..........................................................................................10

4.4.2. images....................................................................................10

4.4.3. images_digi ............................................................................10

4.4.4. images_unc20........................................................................10

4.4.5. images_unc20_rescue............................................................11

4.4.6. software..................................................................................11

5. Installation....................................................................................................12

5.1. Minimal Installation.............................................................................13

5.2. Full Installation...................................................................................14

5.3. Configuring The Network On The Host...............................................14

5.4. Environment Variables.......................................................................15

6. Getting Started.............................................................................................17

6.1. DHCP.................................................................................................17

6.2. Testing the System............................................................................18

6.3. Demonstration Of The Standard System............................................19

7. Building A Project.........................................................................................21

7.1. Directory Structure.............................................................................22

7.2. Kernel ................................................................................................23

7.3. Applications........................................................................................23

7.4. RootFS...............................................................................................23

7.5. JFFS2................................................................................................24

7.6. CVS...................................................................................................24

LxNETES

4

7.7. Rescue Kernel................................................................................... 24

8. Updating Flash............................................................................................. 26

8.1. On A Running System....................................................................... 26

8.2. On A Corrupted System..................................................................... 28

9. Modifying The Default Kernel Configuration................................................. 29

9.1. Default Configuration......................................................................... 29

9.2. Kernel Configuration (xconfig) ........................................................... 30

9.3. RootFS.............................................................................................. 31

9.3.7. CRAMFS................................................................................ 31

9.3.8. NFSROOT ............................................................................. 32

9.3.9. JFFS2.................................................................................... 33

9.4. Using Flash instead of Serial EEPROM............................................. 33

10.Adding Applications To Your Project............................................................ 34

11.The Kernel Boot Process............................................................................. 36

11.1.Overview ........................................................................................... 36

11.2.Phases.............................................................................................. 36

12.User Boot Process....................................................................................... 37

13.Debugging Applications ............................................................................... 38

13.1.Common Setup ................................................................................. 38

13.2.gdbserver .......................................................................................... 38

13.3.Using Abatron’s BDI2000 ................................................................. 40

13.3.10................................................................................. Installation 40

13.3.11................................................................................. Debugging 40

14.Building The Toolchain................................................................................. 43

15.Applications ................................................................................................. 45

15.1.busybox............................................................................................. 45

15.2.eraseall.............................................................................................. 45

15.3.telnetd ............................................................................................... 46

15.4.inetd .................................................................................................. 46

15.5.thttpd................................................................................................. 46

15.6.ftp server ........................................................................................... 46

LxNETES

5

15.7.ftp client .............................................................................................46

15.8.eeprom...............................................................................................47

15.9.update_flash ......................................................................................48

15.10.dbgapp.............................................................................................49

15.11.hello_c..............................................................................................49

15.12.hello_cc............................................................................................49

15.13.Watchdog.........................................................................................49

15.14.Date and Time..................................................................................50

15.15.LCD Demo .......................................................................................50

15.16.PPP..................................................................................................50

16.What’s new in LxNETES v2.3?.....................................................................51

16.1.New Features.....................................................................................51

16.2.Minor Enhancements.........................................................................51

17.What’s new in LxNETES v2.2?.....................................................................51

17.1.New Features.....................................................................................51

17.2.Minor Enhancements.........................................................................52

17.3.Bug Fixes...........................................................................................52

17.4.Known Issues.....................................................................................53

18.FAQs............................................................................................................54

EEPROM................................................................................................55

19.Links.............................................................................................................55

20.Abbreviations................................................................................................56

LxNETES

6

1. Documentation History

Date Version Responsible Description

2003-10-31 2.3 Nigel James Beta1 for v2.3

2003-06-13 2.2 Nigel James Released for v2.2

2003-03-21 2.1 Nigel James Released for v2.1

2003-02-27 2.0 Nigel James Beta1 for v2.1

2002-10-25 1.0 Markus Pietrek Released for v2.0

2002-10-11 0.3 Markus Pietrek Beta2 for v2.0

2002-09-24 0.2 Markus Pietrek Beta1 for v2.0

2002-09-09 0.1 Markus Pietrek Initial Version

Note: the numbers in the version column above refer to revision of this document

and not the LxNETES package.

LxNETES

7

2. Preface

The LxNETES package enables users to easily develop application software

under uClinux for the UNC20 and ModNET50 Developer’s Kits from FS Forth-

Systeme GmbH and the Digi Connect 50 from Digi International, Inc.

In general, this document describes LxNETES as it applies to both the UNC20

Developer’s Kit and the ModNET50 Developer’s Kit. In those cases where

something only applies to one of the Developer’s Kits it will be explicitly stated.

This document assumes that the reader has basic knowledge of Linux. In

addition, it is recommended that the reader has experience with compiling a

standard Linux on the host.

LxNETES

8

3. Features

With LxNETES the user has a platform with the following features:

• uCLinux 2.4.20 kernel

• uClibc 0.9.19 for user applications

• C and C++ supported for application development

• pre-built gdb, busybox and other applications

• Ethernet, flash and EEPROM support

• fast booting with reduced serial output possible

• root file system may be NFS, CRAMFS, JFFS2 or extfs2 (for CompactFlash)

• project-oriented workflow - kernel configuration, rootfs setup and

applications are separated from the kernel sources and the tool chain and

library sources, thus making it possible to maintain the project in a revision

control system.

• all building can be done without any root access.

LxNETES

9

4. Requirements

For development, a Linux x86 host with a recent distribution is required. This

documentation is based on a SuSE distribution installation, but it should work

with minor changes on the other distributions, too.

4.1. Free Space

For installation and building, the following free space is required on the partitions:

/usr/local 350 MB

/targets/LxNETES 60 MB

/targets/LxNETES/ewp 560 MB (only with full installation)

4.2. Applications

A full host development toolchain (make, gcc, binutils) is required for building the

project or the toolchain and Tcl/Tk is required for configuring the kernel and

installation of the packages. If a standard Linux 2.4 can be compiled on the

development platform, then all the required applications will have been installed

already.

For the serial console, a terminal client like "minicom" or "seyon" has to be

installed and configured for 38400 baud.

4.3. Serial Port Nomenclature

A word on the serial port nomenclature since this can be confusing!

The NET+ARM family of microcontrollers has 2 serial ports. These physical ports

on the Developer’s Kits are referred to as COM A and COM B. COM A is always

connected to Port A of the NET+ARM; COM B is connected to Port B on the

LxNETES

10

NET+50 microcontroller and Port C on the NS7520 chip (the NS7520 doesn’t

have a Port B).

On the ModNET50 Developer’s Kit both serial ports, COM A and COM B, are

available. The console, /dev/ttyS0, is on COM A and a second console, ttyS1, is

on COM B.

As delivered from the factory, the UNC20 Developer’s Kit only has 1 serial

interface, COM B, and this is used for the console /dev/ttyS0. The other serial

port, COM A, can be implemented in the wire-wrap area. Refer to the UNC20

Developer’s Kit User Manual on how to do this.

Summary: there is a fixed link between COM A/B and the pins of the UNC20 or

ModNET50 module. The console, /dev/ttyS0, can be assigned to either COM A

or COM B. Refer to section 9.2 “Kernel Configuration (xconfig)” on how to do

this.

4.4. LxNETES CD

The CD contains all the software and documentation needed for LxNETES.

4.4.1. doc

This User’s Manual as a PDF file and additional HOWTOs.

4.4.2. images

All pre-built images for the ModNET50, for example "linux.bin" and

"jffs2.img".

4.4.3. images_digi

All pre-built images for the Digi Connect 50, for example "linux.bin" and

"jffs2.img".

4.4.4. images_unc20

All pre-built images for the UNC20, for example "linux.bin" and

"jffs2.img".

LxNETES

11

4.4.5. images_unc20_rescue

A rescue image, “linux.bin”.

4.4.6. software

All software related specifically to the LxNETES. This can be installed by calling

"install.tcl" from the root directory of the CD.

LxNETES

12

5. Installation

The installation script provided on the CD will install the LxNETES kernel,

toolchain and sources in /usr/local/LxNETES-2.3 and the project

directories in /targets/LxNETES.

We recommend that you install as the default user, since then it will not be

necessary to do any builds as root. However, you have to be root to create a

sub-directory in "/usr/local" or to create the non-existing "/targets"

directory. So create these directories as superuser, change the owner to the

default user, and then do the installation as default user.

$su

Password:

# mkdir /usr/local/LxNETES-2.3 /targets

# chown username:group /usr/local/LxNETES-2.3 /targets

# exit

Since there will be many compilations done in "/targets" and its sub-

directories, it is recommended to have it as a partition of its own so as to reduce

fragmentation of the root file system.

Insert the LxNETES CD into the CD ROM drive and enter

mount /cdrom

cd /cdrom

./install.tcl

The script will ask you whether you'd like to have a full or minimal installation.

After selecting the type it calculates the estimated disk consumption for the

installation and then asks to continue. If yes, it copies and unpacks the files to

your hard disk.

LxNETES

13

***** LxNETES Installer *****

Do you want a full installation with toolchain sources (y/n)? n

Do you want to install the ModNET50 template project (y/n)? y

Do you want to install the UNC20 template project (y/n)? y

Do you want to install the DIGI Connect 50 template project (y/n)? y

Estimated disk usage:

/usr/local : 350 MB

/targets/LxNETES : 60 MB

/targets/LxNETES/ewp : 560 MB

You need to have write access to the directories

Proceed installation (y/n)? y

gunzip -c software/LxNETES_distribution.tgz|(cd /usr/local; tar xf -)

Don't forget to set LXNETES_NFSROOT if you want to use NFS as a rootfs

Have fun

Note that a check is made whether /targets/LxNETES/project* already exists and

you have the option of overwriting or aborting the installation. Therefore, when

upgrading, you should save any work already done in the project directory.

5.1. Minimal Installation

A minimal installation is recommended if the developer doesn't want to build the

toolchain, the libraries and the standard applications himself. This should be the

normal case. After the installation, the following new directories will have been

added:

/usr/local/LxNETES-2.3/arm-elf Toolchain with compiler, libraries and

include files for the target

/usr/local/LxNETES-2.3/apps The pre-built target applications

/usr/local/LxNETES-2.3/linux The kernel sources

/usr/local/LxNETES-2.3/bin Non-toolchain host applications needed

to create the project images such as

mkfs.jffs2

LxNETES

14

/targets/LxNETES/project The default project for the ModNET50

/targets/LxNETES/project_unc20 The default project for the UNC20

/targets/LxNETES/project_digi The default project for the Digi Connect

50

5.2. Full Installation

A full installation is necessary if the toolchain or the applications have to be

rebuilt, either because there are older or newer system libraries installed than on

SuSE 7.2 or the host platform is not an x86. This will create, in addition to the

minimal installation, the following directories:

/targets/LxNETES/ewp Contains unpatched kernel sources, the

standard toolchain, libraries and

applications as archives

/targets/LxNETES/ewp/LxNETES All patches and files necessary to

create the minimal installation out of the

standard applications downloaded from

the internet.

5.3. Configuring The Network On The Host

To simplify debugging on the target, we recommend using NFS so that

application directories can be mounted with read/write permissions on the target.

This requires the host to have an NFS server installed.

The configuration details are beyond the scope of this User’s Manual and are

very specific to the various distributions, therefore this Manual only describes the

modifications necessary for hosts running SuSE distributions.

For exporting a directory per NFS, "/etc/exports" must be modified to

specify the directory to be exported and to whom it should be exported.

LxNETES

15

/exports/bootdir 192.168.42.7(rw,all_squash)

In the example above, "/exports/bootdir" is the path of the NFS root

directory which is only exported to the target (specified as an IP address). Refer

to the Linux man pages for exports for a definition of the options.

After saving the file the NFS server needs to be restarted.

# /etc/rc.d/nfsserver restart

See section 9.3.8 NFSROOT on how to configure the target so it uses an NFS

directory as the root file system.

5.4. Environment Variables

There are three environment variables which slightly modify the behavior of the

build flow of the LxNETES. They can be added to the file "~/.profile" or

"~/.bash_profile" for permanent storage.

Note that LXNETES_NFSROOT_project was new in LxNETES v2.2. It has the

same functionality as LXNETES_NFSROOT, which remains for reasons of

compatibility, and takes precedence over LXNETES_NFSROOT. The reason it

was added is to allow an NFSROOT directory for each project, for those users

who are working with more than one project.

LXNETES_NFSROOT_project

If specified, a "make all" or "make install-

nfsroot" will copy the rootfs and the kernel to

the directory specified in this variable. In the

default configuration it should contain the path

/exports/bootdir_proj1

If specified, this variable will override the

LxNETES

16

LXNETES_NFSROOT setting.

LXNETES_NFSROOT

If specified, a "make all" or "make install-

nfsroot" will copy the rootfs and the kernel to

the directory specified in this variable. In the

default configuration it should contain the path

/exports/bootdir

LXNETES_NOPROMPT When building a project, the prompt and the

terminal window title are changed to make it

visible that a modified environment is being

used. If this variable exists and contains the

value yes, this is suppressed.

As an example, if you’re using the bash shell, and are working with 2 targets,

then enter the following 2 lines in your ~/.bashrc file.

export LXNETES_NFSROOT_project_unc20=/exports/unc20boot

export LXNETES_NFSROOT_project_digi=/exports/digiboot

LxNETES

17

6. Getting Started

The Developer’s Kits are delivered with an image pre-installed in Flash on the

module. After the target is plugged in, boot messages are printed on the console

(38400Bd). Then after about 10 to 15s the kernel has been initialized and the

user may enter commands in the shell.

console=/dev/console

init started: BusyBox v0.60.3 (2003.03.14-12:32+0000) multi-call binary

Starting pid 9, console /dev/console: '/etc/init.d/rcS'

Setting hostname ...

Mounting other filesystems ...

Starting pid 23, console /dev/console: '/usr/bin/lcd_demo'

Starting pid 24, console /dev/console: '/sbin/inetd'

Starting pid 25, console /dev/console: '/sbin/thttpd'

Starting pid 26, console /dev/console: '/sbin/agetty'

BusyBox v0.60.3 (2003.03.14-12:32+0000) Built-in shell (msh)

Enter 'help' for a list of built-in commands.

#

6.1. DHCP

Per factory default the target tries to obtain an IP address via a DHCP request. If

a DHCP server cannot be found, the boot process will forever sit in a loop

waiting for a reply from the DHCP server. To break this loop do the following:

on the UNC20 Developer’s Kit hold the Port C4 button down while

resetting the board

on the ModNET50 Developer’s Kit switch SW10 to on before resetting the

target

PortC4/SW10 may only be released after the target has finished booting

and is awaiting commands on the shell

This will allow LxNETES to boot and the Ethernet interface will have taken the

default IP address as defined by the kernel command line options (see section

LxNETES

18

9.2). Then you should switch DHCP off by modifying the eeprom contents. Enter

the command “eeprom –d no”. Other options for the eeprom command can be

found in section 15.8. At the same time you can set the default IP address to suit

your network.

6.2. Testing the System

One of the first things you’ll want to do is verify that your system is working ok. If

you have a prompt on the serial console, then you can enter some commands.

Below are some useful commands and their typical output.

#ls

bin etc jffs mnt proc sbin

dev htdocs lib nfs ram usr

# mount

rootfs on / type rootfs (rw)

/dev/root on / type cramfs (ro)

none on /dev type devfs (rw)

proc on /proc type proc (rw)

ramfs on /ram type ramfs (rw)

# eeprom

Current EEPROM contents:

Checksum: 154

Use DHCP: no

MAC Address: 00:04:f3:00:00:eb

IP Address: 192.168.42.7

Subnet Mask: 255.255.255.0

Gateway: 192.168.42.1

DNS: 0.0.0.0

Environment variables:

NFSMOUNT=192.168.42.1:/exports/bootdir

JFFSMOUNT=yes

#

If you don’t have a prompt on the screen, then there could be a problem with

either the serial cable or the configuration of the terminal client (minicom, seyon,

screen). Per factory default, an LED test is enabled. On the UNC20 this is called

bas_test. Pressing a button (other than Reset!!) causes the corresponding LED

to light. The LED is lit for as long as the button is held down. This test can be

disabled by entering “eeprom –x BASTEST” at the prompt (and later re-enabled

by entering “eeprom –a BASTEST=yes”).

LxNETES

19

Note: please allow sufficient time for the system to boot, ca. 15 secs, before

pressing the buttons, otherwise the action could be mistaken for “Invalidate

EEPROM contents” in the case of PortC4 or “Allow debugger to attach” in the

case of PortC0.

On the ModNET50 this test is called eva_test and has a similar functionality

except that there are now 4 buttons and 4 LEDs. Pressing all 4 buttons

simultaneously ends this test.

Caution: as with every Unix system, "halt" or "reboot" should be run before

turning power off if any file system is mounted read-write. Only if all file systems

are mounted read-only may the system be turned off immediately.

6.3. Demonstration Of The Standard System

LxNETES comes with a configuration that should demonstrate the use of

• kernel modules

• EEPROM usage

• JFFS2

• web server and ftp server

The demonstration requires the target to be attached to a network and

configured with a valid IP address. A web browser is required on the host.

Target (shell) Host (web browser)

# eeprom -x "JFFSMOUNT"

# reboot

# ls /htdocs/jffs2

index.html

# mount

/dev/root on / type cramfs (ro)

none on /dev type devfs

proc on /proc type proc

open

"http://192.168.42.7/jffs2/index.html"

Note that no JFFS2 file system is

LxNETES

20

ramfs on /ram type ramfs

installed.

# eeprom -a "JFFSMOUNT=yes"

# reboot

# ls /htdocs/jffs2

doc index.html

# ls /htdocs/jffs2/doc

README.html

# mount

/dev/root on / type cramfs

none on /dev type devfs

proc on /proc type proc

ramfs on /ram type ramfs

/dev/mtdblock/3 on /htdocs/jffs2 type

jffs2

reload

"http://192.168.42.7/jffs2/index.html"

Now with a JFFS2 installed a

document link is visible which points

to a directory "doc/" containing the file

"README.html"

# cat >/htdocs/jffs2/doc/hello.txt

Hello World

# reboot

Reload

"http://192.168.42.7/jffs2/doc/"

"hello.txt" should still be visible and

readable

# eeprom -e ""

# reboot

After a reload the page should not be

visible.

Also included in the webpage is a CGI demonstration which allows any file on

the target to be displayed in the browser. Per default the file “/proc/cpuinfo” is

entered. Changing this to “/proc/version” will display the kernel version, for

example: Linux version 2.4.20-uc0-fs6.

Page is loading ...

Digi Digi/FS Forth ModNET50 Module w/16MB SDRAM, 2MB Flash User manual

Related papers

Other documents