Objective

This document is intended for users who have some familiarity with the linux environment. It covers the first steps a user would take when introduced to the LinkGear linux box. More details can be found in the LinkGear FAQ.

Getting Started

The LinkGear has no graphics controller or video output. To begin doing anything with the LinkGear, a terminal login is necessary. There are two ways to login to the LinkGear: using a RS-232 serial console or a secure shell, ssh, via the network. The default system console is the serial port ttySC1. This is the DB9 connector on the rear panel marked CONSOLE. Connecting via the serial console has the advantage of viewing all the kernel messages during boot. Ssh can also be used to login from another computer, which requires the network to be setup and an ssh server running on the LinkGear. And of course, knowing the IP address of the LinkGear is a prerequisite for an ssh login.

Serial Console Login

First, connect the LinkGear to a host machine with a 9-pin, null-modem serial cable. The standard serial device on a linux host machine is /dev/ttyS0. If the host machine does not have a serial port, a USB-to-RS232 serial port adapter is useful. This device will appear as /dev/ttyUSB0 on a linux host machine. A terminal emulation program, minicom for example, can be used as a terminal on the host machine. To learn how to setup minicom, please see Appendix A

Next, apply power to the LinkGear. The bootloader welcome screen like this one will appear on your serial console,

After Linux has loaded, a login prompt will appear. To login, type root. There is no default password. A bash shell should appear.

[top]

Secure Shell Login

1. Connect the LinkGear eth1 port (see default network configuration) to a host computer using a straight CAT5 cable and apply power to the LinkGear. The front panel link LED (top) should illuminate for the connected port.
2. The default boot configuration should start a DHCP server on eth1. This server should assign the host computer an IP address.
3. Now login from the host machine.
   
   host>ssh root@192.168.0.1
4. There is no default password. Enter any non-empty text string as password. A bash shell should appear.

[top]

Root File Systems

The LinkGear has a 128MB, internal flash block device which has pre-installed, a small root file system. To fit a glibc-based file system on such a small footprint, documentation¹, all build tools, most locale information², and even the rpm package manager itself, have been removed³.

The LinkGear ships with two pre-built file systems, the minimum filesystem mentioned above and a full development file system. The development file system is packaged as a compressed tar file and includes the missing components listed above and many other packages. This larger file system can be mounted either as an NFS root file system, or on a USB storage device. Mounting the root development file system is necessary to perform the following tasks:

• adding, erasing updating or querying rpm packages on the internal flash block device file system
• compiling applications, libraries or source rpms
• to add or delete Glibc locale information
• Using tar and other utilities not available on the minimum file system
• Viewing man pages and info files

Notes:

1. Documentation was omitted using the --excludedocs rpm installation option
2. Only the english-US and Posix Glibc locales are installed
3. The rpm database of installed packages in /var/lib/rpm is, of course, included to manage future package installations and removals

[top]

Installing Applications

Applications can be installed using the RPM package manager. The factory-installed file system includes an RPM database of the installed RPMs.

The internal flash block device is limited in size. For this reason, the rpm package manager executable is not installed. In order to add, query, erase or otherwise invoke the package manager, the internal flash block device will need to be mounted from an alternate root file system. This root file system will have more storage capacity and include the package manager. The alternate root file system can be mounted either via the network with NFS, or on a USB storage device. For more details please see the installing RPMs FAQ.

[top]

Cross or Native Development Environment?

Applications can be developed in either a cross or native environment. In a cross development environment, a cross compiler and tools on a development host are used to build an executable image for a target device of a different architecture. In the case of LinkGear development, the target is the sh architecture and the development system is most probably an i386 architecture. In a native environment, the host and target machines are identical; the native compilation tools can be used. Certain executable images are better suited to be built in a cross environment, while others may have to be built in a native environment.

Many applications cannot support cross-compilation. For larger software projects, cross-compilation should be attempted first due to the much shorter compilation times. However, it requires a certain amount of work to set up the environment and often Makefile and configuration scripts do not support cross-compilation. Choosing the development environment is based on the nature of the application. Here are the general guidelines:

Cross Environment
The application build procedure is complex and the build environment supports cross-compilation. This is the case for the Linux kernel and Xfree86 (although the LinkGear has no graphic support). It is quicker to cross-compile. To setup the cross environment, please refer to the LinkGear FAQ for more information.

Native Environment
The application build process is simple, the build time is short or the application does not support cross-compilation. For example, the configure script does not distinguish between the cross and host environments or requires a test program which cannot run on the host machine.

All applications can be developed in the native environment. The GNU toolchain does not fit on the internal flash block device. Instead, applications can be built natively by mounting the root file system on an alternate device. A USB storage device, which is fairly easy to set up, provides a file system exceeding the 128MB limitation of the internal flash block device. Please refer to the native environment section in the LinkGear FAQ to setup a root file system on a USB device.

A second choice is to use an NFS root file system on a host, making the LinkGear a diskless device. However, this will require the user to setup DHCP, TFTP and NFS servers. Please refer to mounting an NFS root file system in the LinkGear FAQ.

[top]

Building the Kernel

To understand how to build the linux kernel for the LinkGear, please read this FAQ. It is faster to build the kernel in a cross-development environment on a host machine. Once successfully built, the kernel can be installed in one of two ways:

• NFS mount a target root filesystem - The LinkGear filesystem is mounted on the host machine over the network via NFS. The kernel image and modules can be copied directly to the target. By default the NFS daemon is not started at boot time. This LinkGear FAQ explains how to mount the target file system on host machine.
• Build a kernel RPM. The kernel can be built as an RPM package. Once successfully built, this RPM can be copied to an NFS or USB file system. Once this file system is booted, the kernel rpm package can be installed, see above).

Note: Every time a new kernel is copied to the target, the following command must be executed on the LinkGear:

[top]

Appendix A: Setting up Minicom

Most GNU/Linux distributions have minicom as an available package. If you don't have minicom software, you can go to http://alioth.debian.org/projects/minicom. To start minicom in a host shell terminal type,

Minicom may need to run as root in order to setup the serial port. Configure the serial port to 38,400 baud, no parity and 8 data bits. Type <CRTL>-A Z to enter the setup screen.

Type O and select Serial port setup

Type A to set the serial device. This will depend on which host serial port will be used. A typical value is /dev/ttyS0 for the standard serial device or /dev/ttyUSB0 for a USB serial device.
Type E to choose braud rate, data bits, parity and stop bits
Type F to disable hardware flow control.

To save the configuration, hit ESC to quit, choose Save setup as dfl, then Exit.
Exit minicom and restart. When minicom is restarted, the output from the LinkGear should appear in the terminal.

[top]

Appendix B: Default Network Configuration

The default, factory settings for the ethernet ports are listed here.

Note 1: DHCP configuration is incomplete. For instance, site-specific information, such as nameservers, should be added to the /etc/dhcpd.conf file.

The network configurations can be changed by editing the network scripts files /etc/sysconfig/network-scripts/ifcfg-eth*,/etc/dhcpd.conf, and others. For more information on the ifcfg-* scripts and other sysconfig files, please see the file /usr/share/doc/initscripts-<ver>/sysconfig.txt. This file only exists on the development file system.

If it is necessary to disable the dhcp server, run

or, to disable permanently,

Appendix C: On-line Reference

For further information on running Linux on the LinkGear, please refer to the LinkGear Linux FAQ. Also, the following web sites contain a more information on SH and Linux related topics.

Renesas Super-H Linux Information:
linuxsh on Sourceforge
Linux-SH Wiki¹ - The source for sh on linux.

Note 1: The Linux-SH Wiki includes many other sh-related information not necessarily applicable to the LinkGear-100. For instance, the LinkGear-100 has it's own boot loader, a modified linux loader (lilo) and the installed file system is based on gcc-3.4.3 and glibc-2.3.3. Using packages from Fedora cores, Debian, Gentoo or other distributions may not work properly. However, the creation or modification of alternative distributions for the LinkGear by others is strongly encouraged. All source packages built for the LinkGear are available, of course.

The Linux Kernel:
www.linuxhq.com
www.kernel.org
www.tldp.org/LDP/tlk/tlk.html -- Excellent source for kernel documentation

Linux Documentation:
www.linux.org
www.tldp.org

[top]