Pocket Computing @ WRL

Software Users Guide

 

   

Compaq Internal Use Only


 

 

This guide describes the environment that is used within WRL to develop both applications and daughter-cards for Itsy prototypes. Local users (those working at WRL) should also read the WRL User Guide Supplement.

More specifically, the Software Users Guide provides the following:

 


User Guide Notes

In the following, commands that should be typed in to an Itsy or the host workstation are enclosed in single quotes.

Also, with the exception of creating and modifying a ramdisk, all programs that are run on a host workstation may be run on either a x86-processor-based workstation or an Alpha-processor-based workstation. Furthermore, to connect to an Itsy prototype using PPP or a terminal emulator such as tip or seyon, any workstation can be used, not just those based on an x86 or Alpha processor.

The x86 binaries that are needed for the development environment on a workstation running Linux are available here for Compaq internal sites, and are included in the 'bin' directory of the distribution for external sites. These binaries should be installed in /usr/local/bin on your x86-based workstation


Overview of an Itsy

A few notes about an Itsy Prototype itself.

First, there are two distinct Itsy prototypes in existence. One is the Itsy v1 and one is the Itsy v2. All v2 cases have "v2" written on them somewhere.

An Itsy v1 prototype has a particular set of buttons. On the side are two, one closer to the screen and one further from it (let's call these side-left and side-right, respectively). There's also a tiny recessed one near the serial connector (reset). On the front, there is one big white button (power), two round smaller ones (front-left and front-right), one square one (square), and four clustered for use in a rocker switch.

An Itsy v2 prototype has a different set of buttons on it. On the side are three: side-left, side-middle, and side-right (where side-left is the one closest to the screen). There's also a tiny recessed one on the front face near the serial connector (reset) but not on the same side as it (the one on the same side as it is the hole for the microphone). On the front, there are also four round white buttons clustered as if for use in a rocker switch (but they are separate buttons in the current design), one other big white button (power), and one thumbwheel encoder (encoder) which can rotate clockwise or counter-clockwise in addition to being pushed in.

Second, an Itsy prototype has a touch-sensitive display, 320 by 200 pixels, each of which can be drawn in one of 15 levels of gray. The touchscreen must be calibrated, as explained below.

Third, the processor can operate in one of three modes: run mode, idle mode, and sleep mode. These modes differ in the amount of power that is consumed in each. When running Linux, an Itsy prototype automatically and undetectably enters idle mode whenever the system appears not to be in use. When the system detects user input, it will automatically and undetectably switch back to run mode. The Itsy prototype also has the ability to automatically drop into sleep mode, but that option is disabled by default. In the default 4.0 Release software environment, if you press and hold the power button for several seconds, the Itsy will be put into low-power sleep mode. Once the Itsy is in sleep mode, normal operation can be resumed by pressing the power button to wake it up -- this change of mode will be detectable by the screen going off (in sleep mode) and on again when it is awoken.

Fourth, the standard Itsy distribution comes with a couple of guest accounts: guest and demo, both of which have no password. The root password should have been communicated to you when you got your Itsy. See the section on Creating/customizing a ramdisk for information on how to add your own passwords.

Fifth, your Itsy prototype was probably shipped to you with a run-time environment already installed. The latest version of the files that comprise this environment are available in the directories Software/kernel and Software/ramdisks (note that the motherboard ramdisk include support for the flash file system as of Release 4.0; see this document for more information on the flash file system). These files are the following.

For instructions on how to download and install these files on your Itsy prototype, see the section To Download a Ramdisk, Parameters File, or Kernel into the Flash Memory, and see the Installing Packages section of the Itsy packages document. There are several packages available.


Development Environment

The operating system, applications, and boot-strap code for an Itsy prototype is stored in its non-volatile memory, that is, in its flash memory. When an Itsy prototype is reset or first turned on, the hardware begins by loading a monitor program into the Itsy's DRAM. Once running, this monitor program can be used to, among other tasks, boot the operating system, download files to the Itsy, or store data into the flash memory. The normal operation mode is for the monitor program to automatically boot Linux. When Linux boots, it allocates some of the DRAM to function as a disk. This disk is referred to as the ramdisk. The ramdisk is used to store the binaries of the operating system and applications as well as any data that either requires or generates. Thus, these programs run off of the ramdisk and not out of flash memory.

As of Release 4.0, changes to information stored on a flash file system will be maintained when an Itsy is reset or turned off, but information stored on a ramdisk will not be. So, for example, if a file is modified and it is stored on the partition /dev/ram, the modifications will not be saved on a reset, but if the file is stored on a partition with the prefix /dev/ftl* (any flash partition), changes will be maintained across a reset. The unix command df can be used to determine the partition on which a file is stored. Persistent changes to information that is not saved across a reset must be done while the Itsy is running the monitor program. To prevent Linux from booting, you can either hold the white "power" push-button down while resetting or turning on the Itsy, or, you can execute the command '/sbin/shutdown -h now' on the Itsy while it is running Linux. (If, however, you execute the shutdown command with the "-r" flag instead of the "-h" flag, Linux will be booted automatically.)

The process of writing non-flash-filesystem data into the flash memory (e.g. new ramdisks, kernel, etc.) is controlled by a program that is run on an x86-based or Alpha-based workstation. This program sends the data to the monitor program that is running on an Itsy over a serial line, and the monitor program writes the data into flash memory. We have written two programs for sending the data to the Itsy and these are boot-itsy and eterm.

Calibration

If the touchscreen appears to be not responding properly, you will have to recalibrate it. Calibration is also necessary if the Itsy has no calibration information stored for the touchscreen, say, because this is the first time you've booted it after installing Release 4.0. In the former case, that is, if the touch screen appears to be not responding correctly, it can be manually recalibrated.

In the latter case, that is, there is no stored calibration information, when the Itsy is booted, you will be given the opportunity to calibrate the touchscreen.

When calibrating the touchscreen, you will be shown a series of screens with a cross on them; press a stylus (such as used on a palmpilot) at the center of the cross for each screen. At the end it will put you in a Screen Calibration program. You can select the "Save" button from this menu to save the calibration data you have just generated, or re-calibrate using the "Calibrate" button. The "Test" button will show you a blank screen; when you press the touchscreen with a stylus the Itsy will draw a cross at the location it thinks you touched. To exit the Test screen, press any button (other than the power button). To exit the Screen Calibration program, use the "Exit" button. This will place you in the main sessions menu. Note that at any time you could press the power button to go to the main session menu.

Running Stand Alone

Once you have set the date and time, and optionally calibrated the touchscreen, you will see the main sessions menu, which can be used to start, stop and monitor applications. By default, the session manager provides some system utilities such as top, bash, and shutdown, as well as some applications such as a primitive voice organizer. Additional applications are available, which you can install on your itsy using Itsy Packages.

Once your Itsy is up and running, you may then use the Itsy as you would use any UNIX workstation that is not connected to a network. That is, you can log in, run any of the available applications. The next section discusses how to connect the Itsy to a workstation and log into the Itsy using that workstation.

There is no touchscreen-based keyboard such as was available in earlier releases. Instead, to interact with a shell, you must use the Unistroke recognizer, by writing letters using unistroke commands directly on the touchscreen. Unistroke is similar, but not identical, to the Graffiti interface used by the PalmPilot. Documentation on the Unistroke command set is included in the scribhelp package.

Connecting to a Workstation

An Itsy prototype may be connected to a workstation in order to reprogram the flash memory or to make it easier to develop or debug applications. Such a connection is made using the serial port on an Itsy and the serial port on the workstation in question. If you have trouble getting your Itsy to talk over the serial port, please read this short note on host-computer connection.

This guide explains how to connect the Itsy using the serial port to either a Windows 95/NT workstation, or a workstation running either Linux or Digital UNIX. This connection can be used to reprogram the flash memory or to interact with the Itsy using the workstation's keyboard.

For workstations running Windows 95/NT, a terminal emulator program such as KEA! version 4.10 can be used. This emulator will allow access to the monitor program or to a Linux shell. More information is available below.

For workstations running Digital UNIX or Linux, the flash memory may be reprogrammed using the boot-itsy and eterm programs. Note that if you want to download new versions to try them out but not install them in the flash memory, the boot-itsy program can be used for this purpose. To interact with the Itsy while it is running Linux, a terminal emulator such as tip or seyon, can be used. (see here for some notes on getting seyon to work with an Itsy). A more flexible method for connecting to an Itsy, however, is to use PPP. PPP allows you, among other things, to rlogin in to the Itsy, and to ftp files from the workstation to the Itsy and vice versa.


PPP

To run PPP, the Itsy prototype (i.e., the Itsy) must be connected to a workstation (i.e., the host) using the serial port, and the PPP configuration files set up. Then, on both the workstation and the Itsy, the ppp daemon must be start up.

Note: if you are using a workstation running Windows 95/NT, PPP connections cannot be established using the serial port. Instead, the KEA! terminal emulator can be used to access a Linux shell. Please see the following section for details.

Starting up PPP

Once the configuration files for PPP are set up (see below), you can start the daemon running by

  1. pressing the button labeled "PPP" in the Network submenu of the main session menu.
  2. then exiting your terminal emulator connection if you are using one (see below), and
  3. finally typing 'pppd' on the workstation host.

You should then be able to ping the Itsy by the name assigned to it in the /etc/hosts file of the workstation. Note that you will only be able to reach the Itsy directly from the workstation host; if you want to log in to the Itsy from another machine, you must first log in to the workstation host and then into the Itsy.

You can enter the 'start-pppd external' directly using the onscreen keyboard, or you can connect to it over the serial port using a terminal emulator such as seyon or tip. Note that, by default, the Itsy is expecting a 38400 connection speed for this terminal emulation.

Setting up PPP

To setup PPP, you should first have the following lines in the /etc/ppp/options file stored on the workstation.

asyncmap 200a0000       # XOFF, XON, and ^] (the default telnet escape)
escape 7e,7f,fe,ff,93   # 7-bit and 8-bit variants of rlogin escapes
                        # 0x93 is XOFF or-ed with top bit (0x80)
mru 296                 # IP header plus 256 more octets
/dev/ttyS1
115200
netmask 255.0.0.0
10.0.0.1:10.0.0.2

where 'S1' is the serial port the Itsy is plugged into (probably S0 or S1), '115200' is the speed you want to run at, '10.0.0.1' is the IP address for the host machine, and '10.0.0.2' is the IP address for the Itsy. You may also need "noauth" in the file, if your host machine is running a recent version of Linux.

You can also add the following lines to the /etc/hosts file on your workstation:

10.0.0.1   Itsy-host
10.0.0.2   Itsy

where '10.0.0.1' is the IP address for the host machine, 'Itsy-host' is the name of the host machine, '10.0.0.2' is the IP address for the Itsy, and 'Itsy' is the name of the Itsy. You should also modify the /etc/hosts file on your Itsy to match whatever you put in the one on the workstation. Note that to make these changes permanent, you must customize your ramdisk.

Then, you must configure both the /etc/ppp/options-external and /etc/sysconfig/network-external files on the Itsy. Note that to make these changes permanent, you must customize your ramdisk. The Itsy /etc/sysconfig/network-external file should have:

NETWORKING=yes
HOSTNAME=Itsy.pa.dec.com
DOMAINNAME=pa.dec.com
GATEWAY=10.0.0.1
GATEWAYDEV=ppp0

where 'Itsy.pa.dec.com' is the full name of your Itsy, 'pa.dec.com' is your domain name, and '10.0.0.1' is the IP address of the local Itsy host.

The options file on the host should be correct, assuming your host can run at 115200. If not, adjust the speed in /etc/ppp/options-external on the host; it will get copied to accordingly.

You will also need to set /etc/resolv.conf .external up properly on the Itsy. It should have one line in it:

domain          pa.dec.com

where 'pa.dec.com' is your domain name (this should match the domain name you have set in the /etc/sysconfig/network file).

Notes

  1. Net 10 (IP addresses starting with the number 10) is reserved for experimental systems. You can use it to connect your Itsy and the host, but you will be unable to connect to your Itsy or route to your Itsy from other machines if you use these IP addresses.
  2. For advanced network users, it is possible to set up a subnet and have the host be a router. This will allow an Itsy running PPP to be reachable from any machine that can reach your host. We do not provide instructions for doing this, because it is highly dependent on your local networking setup.
  3. For people who use have Ricochet modems, you should be able to connect up your Itsy to the Ricochet modem by using 'start-pppd ricochet'. No files should have to change. The Itsy will print out what IP address it is assigned by Ricochet.

Connecting to an Itsy using a Workstation running Windows 95/NT

Background Info

Windows users can use a terminal emulator, such as KEA! version 4.10, in place of boot-itsy, eterm, and PPP. For Itsy users at WRL, see here for info on getting a copy of KEA! Note, however, that the downloading of packages to an Itsy is not presently available if you are using programs such as KEA! Instead, you need to manually copy the relevant tar file for the package to your Itsy and decompress it there.

PPP

Windows systems do not establish PPP connections via the serial port. Instead, the KEA! terminal emulator is used to access a Linux shell. Create a session such as the following:

	Communications port:  serial, configured as:

	Port: COM1 or COM2
	Baud Rate: 38,400
	Data bits: 8
	Stop Bits: 1
	Parity: none
	Check Parity: don't check
	Flow Control: None
	Receive Xoff point: default
	Modem disconnect: Never
	Disconnect on Exit: check

	File Transfer Protocol: Zmodem (default configuration)

	Terminal Mode: VT100 (default configuration)

Once started, you may make the additional change:

  • select the Options|Communications menu, and clear the "Limit Transmit Rate" check box.

Using this one can log onto the Itsy and use the Transfer menu to move files back and forth.

Accessing the Monitor Program

Create a KEA! session for accessing the Itsy monitor as follows:

	Communications port:  serial, configured as:

	Port: COM1 or COM2
	Baud Rate: 38,400
	Data bits: 8
	Stop Bits: 1
	Parity: none
	Check Parity: don't check
	Flow Control: None
	Receive Xoff point: default
	Modem disconnect: Never
	Disconnect on Exit: check

	File Transfer Protocol: Zmodem (default configuration)

	Terminal Mode: VT100 (default configuration

Once started, make the following additional changes:

  • Select the Options|Communications menu, and clear the "Limit Transmit Rate" check box.
  • Select the Options|Terminal|General menu and set "Local Echo".
  • Select the Options|Terminal|Display menu and set "New Line" and "Auto Wrap".
  • Select the Transfer|Options menu and click the "Options..." button. Then, set "Newline As" to "CR LF" and clear the "Limit Transfer Rate" check box.

Once the terminal session has been configured, the standard monitor commands can be used. Here's an example of how to down load your params into flash (the text is bold denotes the information entered by the user):

 Flash memory program p 1 0x00080000
 Please download file preceded by its size (ASCII)
 enter file size in bytes followed by Enter
 Select the Options|Terminal|General menu and turn off local echo
 Select the Transfer|Send menu and transfer the file
 File successfully loaded, start programming flash memory 1.
 Programming of flash memory 1 succeeded.
 Flash memory program>
 Select the Options|Terminal|General menu and turn on local echo

Other files are down loaded in a similar manner. For more information on the monitor commands, see the section to Download a Ramdisk, Parameters File, or Kernel into the Flash Memory.

Please Note

Don't forget to save your session configurations. You may also want to change screen size, colors, and Itsy serial port speed.

Creating/customizing a ramdisk

The ramdisk is the in-memory filesystem that the Itsy uses. Your Itsy comes with a ramdisk already installed, but you'll almost certainly want to change files on it (for the ppp setup, password file, etc). In order to change the files permanently (as opposed to just until the Itsy is rebooted), you'll have to change the ramdisk or use the packages functionality to write the files into a flash file system. Using packages is the preferred method.

To change the ramdisk, you must use an x86-based machine running Linux. Further, you must ensure that your workstation has been booted with a large enough ramdisk size to handle the ramdisk that you will load into memory. You must also ensure that your ramdisk is not bigger than there is room for in flash (currently 2949120 bytes).

There are a few steps involved:

  1. Getting a ramdisk into memory on the workstation so you can play with it. You do this by running 'ldrd <filename>' (as root) where filename is the default ramdisk you're planning on using. We usually keep our ramdisk files in the Linux directory that we're doing source compilations in, but you can keep it somewhere else. The one that we have programmed in to your Itsy is available for downloading (for external sites, it is included with the distribution). By default, ldrd will load the ramdisk into /dev/ram-<username>, and mount it as /mnt/ram-<username>. You can change where it does this. Once you've performed this step once, you should not need to repeat it until your workstation is rebooted.
  2. Once it's loaded, you can 'cd' to it and change any files you like. Make sure it doesn't get too big (the current size that we're set up for is 8192kb).
  3. When it's all set, you need to make a new file version, to download. Run 'mkrd <filename>'. Make sure that you have cd'ed out of the mount directory, and started no programs there, because it needs to unmount the filesystem in order to create the file. When it's done, it will remount it.
  4. Finally, you can burn the new ramdisk into flash.

If you end up having multiple ramdisks, and aren't sure what's different between them, you can use the 'ramdiff' program. It prints out files that differ between two mounted ramdisks. Theoretically, it will tell you:

  • things that are on one ramdisk and not the other
  • things that are on both ramdisks but that differ: in content, where they point to (for symlinks), or type [but not modification time]

The command syntax is:

ramdiff dir1 dir2

and an example of the command is:

ramdiff /mnt/ram-kerr /mnt/ram-efoo

To Download a Ramdisk, Parameters File, or Kernel into the Flash Memory

This is a very brief description on how to use the monitor program for downloading into the Flash Memory (i.e., burning into flash memory) a new ramdisk, parameters file, or kernel. For more information, see the section on the monitor program.

To get the monitor program running on an Itsy prototype, either reset an Itsy with the white 'power' push-button held down the whole time or do a '/sbin/shutdown -h now' from a Linux on the Itsy. After either action, you will be in the main menu of the monitor program.

To access the monitor program that is running on an Itsy, you need to use either the eterm or boot-itsy program, which are run on the workstation host. See the sections below on boot-itsy and eterm for more information.

The following assumes you are using eterm. Once eterm is running, type 'f' (without the quotes!) on the main menu. Notes:

  1. to return to the main menu from a sub-menu type 'm'
  2. to return to Linux type 'q' on the main menu

For:

  • downloading a ramdisk, after typing 'f' on the main menu, do the steps for burning in a ramdisk into the flash memory of the mother board verbatim. Note: hit return after typing in the name of the ramdisk (e.g., ramdisk-itsy)

  • downloading a parameters file, after typing 'f' on the main menu, do the steps for burning a params file verbatim. Note: hit return after typing the name of the params file (e.g., arch/arm/boot/params-itsy)

  • downloading a new kernel, after typing 'f' on the main menu, do the steps for burning a kernel verbatim. Note: hit return after typing the name of the file containing the new kernel (e.g., arch/arm/boot/zImage-itsy).

To download your ramdisk to the flash memory on the Itsy (takes a really long time):

p 1 0x00070000
ctrl-c
s
ramdisk-itsy

To download your params file to the flash memory on an Itsy (takes only a short time):

p 1 0x00060000
ctrl-c
s
arch/arm/boot/params-itsy

To download a new kernel to the flash memory of an Itsy (takes a medium amount of time):

p 1 0x00340000
ctrl-c
s
arch/arm/boot/zImage-itsy

Note that your Itsy has been shipped with a monitor serial port speed of 38400. To change that, run 'eterm -o 38400 -n -d /dev/ttyS1' on the workstation host and go to the session parameters menu by typing 's'. If you then type 'u speed', it will reset the Itsy to run the monitor communications at that speed (we use 115200), until the Itsy is reset. Test it out by exiting the eterm ('ctrl-c' and then 'q') and restarting it eterm using -o speed. If it doesn't respond after a few carriage returns, reset it and try a slower speed. Once you're happy with a speed, you can burn it into the flash memory of the Itsy as a monitor default. To do so, go back to the main menu by typing 'm', then go to the configuration parameters menu by typing 'c', then type 'u speed', then type 'd' to check that it looks right, and then type 'p' to program the speed. Be careful; if you screw up, your Itsy won't talk to you anymore, even after a hard reset of the Itsy.

Compiling programs

Once you have your build environment set up, you should be able to compile programs by using /usr/local/bin/arm-unknown-linuxelf-gcc (or whatever you called it) as your compiler. To place them on the Itsy temporarily, just ftp (or rcp) them over. As of Release 4.0, to place them in flash, the preferred method is to use the packages functionality.

Compiling the kernel

You should have a copy of the kernel source in /usr/local/arm-unknown-linuxelf/src/linux. You may want to keep this version pristine, and make another copy to which you will make your changes. Let ROOT be the path name of the directory that contains the root of the copy that you will change (e.g., /usr/local/arm-unknown-linuxelf/src/linux if you are using the original copy).

People working within Compaq may be able to share our CVS repository to keep the source consistent. In you are interest, please refer to our software web page for whom to contact.

Change to the directory ROOT, and do a 'make mrproper' to ensure the subdirectories are totally clean (if you get the message "rm: include/linux/modules/CVS: is a directory, ignore it). Then, do a 'make config'. Accept all the defaults on the config right now (just keep hitting return until it is done). Then do a 'make dep' to make the dependencies. Finally, do a 'make zImage' will make the kernel (and a new set of parameter files).

When you're recompiling the kernel in general, only the 'make zImage' (and perhaps a 'make modules', to remake the modules that aren't part of the kernel but that reside on the ramdisk) will be necessary.

Note that the compiler and other tools ('arm-unknown-linuxelf-gcc', etc) need to be in your path for the compile to work.

Making a new parameter file

You should not need to change the parameters we have downloaded already for you. The kernel is automatically informed of many parameters (such as the amount of memory available on the Itsy) via the monitor program when it boots.

Boot-Itsy

You probably won't need to run this program unless you are kernel hacking. Its use is to download a kernel file but not burn it into flash. The Itsy must be in monitor mode (not running linux) to run this program. A typical use would be:

boot-itsy -d /dev/ttyS1

where it will assume you're getting the ramdisk from flash, the params file from flash, the device it will use is /dev/ttyS1, and the kernel it will get from the default kernel place (your-home-directory/linux/arch/arm/boot/zImage-Itsy, which is where linux builds it).

Once boot-itsy starts, and you're satisfied with what it says it's loading, you should see the monitor menu. If you're not at the top level ('ITSY MONITOR'), use 'm' to get there. Type 'a', then 'ctrl-d' to start the download process going. The Itsy should boot from that point.

The Itsy monitor

The Itsy monitor source (other than the start.asm file, which has been posted externally) is classified Compaq Confidential and, therefore, should not be distributed outside of the company. External Itsy users under NDA are given access to the binary files only.

Generalities

The latest released revision of the monitor is the Itsy Monitor version 2.3. At WRL, the monitor is also available in the directory:

/wrl/proj/itsy/viredaz/prgm/itsymon

There are several versions of the monitor, depending on which compile-time options are selected. Only the "user" version itsymon and the "test" version itsymon_t should be used with regular Itsy computers. The other versions of the monitor assume special or modified hardware. The "user" version itsymon (160 Kbyte) contains the necessary software to:

  • Initialize the Itsy computer and optionally launch an operating system.
  • Load and execute code (e.g., for operating-system development).
  • Program the flash memories.
  • Reconfigure the monitor.

The "test" version itsymon_t (180 Kbyte) also contains hardware test routines.

Upon reset, the monitor initializes the Itsy computer and launches the operating system (by jumping to the operating-system boot address), unless the main push-button is pressed, in which case the monitor's menu-driven interface is started. If the operating-system boot address is set to 0, the menu-driven interface is always started (see the monitor-system API below).

The characteristics listed below are determined by parameters programmed in flash memory and can be modified from within the monitor:

  • Default clock frequency.
  • UART settings (including bit rate).
  • Operating-system boot (physical) address.
  • Operating-system boot parameters (up to 4 parameters).
  • DRAM type.
  • LCD frame-buffer address.

Additionally, the clock frequency and UART settings can also be modified on a session basis.

If required, the monitor can be re-compiled in big endian mode.

Installing/upgrading the Itsy monitor

There are several ways to program the Itsy monitor in flash memory. The easiest way is to execute the monupgrd program. Two versions exist for the "user" and "test" versions of the monitor, respectively:

This program initializes the monitor's parameters in the following way:

  • The default clock frequency and the UART settings are set to their current values (independently of the values of a previous version of the monitor).
  • The operating-system boot address and parameters are copied from the previous version of the monitor (if any). If an older version of these parameters can not be found, the operating-system boot address is set to 0 and the monitor's menu-driven interface is started on reset, until the operating-system boot address is manually updated.
  • The DRAM type is copied from the previous version of the monitor (if any). If an older version of this parameter can not be found, the user is prompted to enter the correct DRAM type.
  • The LCD frame-buffer address is copied from the previous version of the monitor (if any). If an older version of this parameter can not be found, it is set to 0 and the LCD is disabled when booting an operating system.

Using the monitor, the monupgrd program can be executed by selecting the "automated program load/execute" command (i.e., by entering A), and then downloading the file monupgrd or monupgrd_t, as appropriate. This operation can be executed using any terminal emulator that features the capability of downloading a binary file. With the eterm terminal emulator, this can be done by typing Ctrl-C, then selecting the "send file" command (i.e., by entering F), and then entering the name of the file to be downloaded.

The monitor can be configured to launch Linux by selecting the C menu, entering:

S 0x00060000

to set the operating-system boot address, entering:

A 0x08340000 0xC0800000 3

to set the operating-system boot parameters, and then selecting P to program these values in flash memory. Linux can be subsequently booted by selecting M to return to the main menu, and then selecting Q to quit the monitor (software reset). Note that the default configuation that we ship an Itsy out with has the parameters set by default to be the values mentioned above.

The monitor-system API

There are three basic ways of starting the monitor, that result in three different behaviors:

  • Reset (hardware, software, or watch-dog reset).
  • Exiting sleep-mode.
  • Jumping to (physical) address 0 (reset vector).

These cases can be discriminated using the reset controller status register (RCSR), provided that this register is cleared when the boot sequence is completed.

Reset behavior

If any of the HWR, SWR, or WDR bits in the RCSR are set, the reset behavior is assumed. The Itsy hardware is initialized in the following way:

  • The GPIO pins are configured in a "default safe state":
    • The direction of each GPIO pin is configured according to its use (unused GPIO pins are configured as input).
    • The state of output GPIO pins is set to match the corresponding pull-up or pull-down resistor.
    • Alternate functions, edge-detection, and interrupts are disabled.
    The exact state of the GPIO registers depend on which daughter-card (if any) is used.
  • The LCD controller and all serial engines are disabled.
  • The 4 static memory banks are initialized according to their class ID.
  • The DRAM controller is initialized and the number of actual DRAM banks is detected. A quick DRAM test routine is executed for each bank.

If the operating-system boot address is equal to 0 or the main push-button is pressed, the monitor's menu-driven interface is started. Otherwise the operating system is booted by jumping to the operating-system boot (physical) address, while providing the 4 operating-system boot parameters in registers R0 to R3.

Status messages are sent to the UART engine of serial port 3 (Itsy v1) or serial port 1 (Itsy v2). If the operating system is booted, the latter is disabled prior to jumping to the operating-system boot address.

This behavior allows the operating-system to reboot (e.g., to implement shutdown -r) by executing a software reset.

Sleep-mode wake-up behavior

If only the SMR bit in the RCSR is set (i.e., the HWR, SWR, and WDR bits are cleared), the sleep-mode wake-up behavior is assumed. The Itsy hardware is initialized in the following way:

  • The GPIO pins are left untouched.
  • The LCD controller and all serial engines are disabled.
  • The 4 static memory banks are initialized.
  • The DRAM controller is initialized.

The behavior after exiting sleep mode is defined by the value which was stored in the scratch-pad register (PSPR) register before entering sleep mode. The two least-significant bits of this register define the mode (0 to 3), while the 30 most-significant bits are used to pass an optional pointer:

  • Mode 0: complete system resume

    In this mode, an operating system is resumed after a complete initialization of the hardware. The PSPR register must provide a stack pointer. If the value 0 is passed instead of a stack pointer, the monitor is started:

            31              2 1 0
           +-----------------+---+
    PSPR = |       0         | 0 |  =>  Start monitor (UART messages)
           +-----------------+---+
    
           +-----------------+---+
    PSPR = |  Stack pointer  | 0 |  =>  Resume system (no UART messages)
           +-----------------+---+
    

    The stack pointer corresponds to the last-used location of a descending stack which can be used by the initialization software. The return address must be stored in the location pointed to by the stack pointer:

    DRAM:  |                     | High addresses
           +---------------------+
           |   Return address    | <--- Stack pointer
           +---------------------+
           |                     |
           | Stack to be used by |
           | the initialization  |
           |      software       |
           |                     | Low addresses
    
  • Mode 1: system re-start (aka deep sleep) / custom sleep-exit routine

    This mode implements 2 sub-modes. In the first sub-mode, an operating system is fully re-started after a complete initialization of the hardware. The 30 most-significant bits of the PSPR register must be set to 0:

            31              2 1 0
           +-----------------+---+
    PSPR = |        0        | 1 |
           +-----------------+---+
    

    This sub-mode is useful if the content of the DRAM has not been preserved during sleep mode. If the system start address in the monitor parameters is set to 0, the monitor is started. If this parameter stores a system start address, the system is re-started.

    In the second sub-mode, a custom sleep-exit routine is executed. The 30 most-significant bits of the PSPR register must provide the routine's start address:

            31              2 1 0
           +-----------------+---+
    PSPR = |  Start address  | 1 |
           +-----------------+---+
    

    No initializations are made

  • Mode 2: fast system resume

    In this mode, an operating system is resumed after initializing the hardware based on parameters saved before entering sleep mode. The PSPR register must provide a pointer to a structure containing the values of the memory controller's configuration registers and the return address:

            31              2 1 0
           +-----------------+---+
    PSPR = | Struct. pointer | 2 |
           +-----------------+---+
    
    DRAM:  |                     | High addresses
           +---------------------+
           |    Value of MSC1    |
           +---------------------+
           |    Value of MSC0    |
           +---------------------+
           |   Value of MDCAS2   |
           +---------------------+
           |   Value of MDCAS1   |
           +---------------------+
           |   Value of MDCAS0   |
           +---------------------+
           |   Value of MDCNFG   |
           +---------------------+
           |   Return address    | <--- Struct. pointer
           +---------------------+
           |                     | Low addresses
    

    The rest of the hardware is then initialized.

  • Mode 3: minimal system resume

    In this mode, an operating system is resumed after just initializing the memory controller. The PSPR register must provide a pointer to a similar structure as in mode 2:

            31              2 1 0
           +-----------------+---+
    PSPR = | Struct. pointer | 3 |
           +-----------------+---+
    
    DRAM:  |                     | High addresses
           +---------------------+
           |    Value of MSC1    |
           +---------------------+
           |    Value of MSC0    |
           +---------------------+
           |   Value of MDCAS2   |
           +---------------------+
           |   Value of MDCAS1   |
           +---------------------+
           |   Value of MDCAS0   |
           +---------------------+
           |   Value of MDCNFG   |
           +---------------------+
           |   Return address    | <--- Struct. pointer
           +---------------------+
           |                     | Low addresses
    

    This is the fastest mode, and is the one used by default in the version of Linux shipped with your Itsy (release 5.0 and later). The rest of the hardware is not initialized. Therefore, the PH flag (bit 4) of the PSSR register is not cleared.

Monitor restart behavior

If none of the HWR, SWR, WDR, and SMR bits in the RCSR is set, the monitor restart behavior is assumed. The Itsy hardware is initialized exactly as in the reset case. The monitor's menu-driven interface is then always started.

This behavior allows the OS to start the monitor's menu-driven interface (e.g., to implement shutdown -h) by jumping to address 0 (reset vector).

Terminal emulator: eterm

The eterm utility is a terminal emulator running under Digital UNIX and Linux that allow to connect to a system through a serial interface (RS-232). All standard parameters can be selected as command-line options:

Usage: eterm [-d <Device>] [-b 5|6|7|8] [-s 1|2] [-p n|o|O|e|E] [-o <Speed>]
             [-i <Speed>] [-x n|i|o|b] [-l|-e|-c|-t] [-f|-n]

Arguments:
   -d <Device>    Serial port device (default: "/dev/tty00").
   -b 5|6|7|8     Number of bits per character (default: 8).
   -s 1|2         Number of stop bits sent per character (default: 1).
   -p n|o|O|e|E   Parity: (n)one, (o)dd, (O)dd no check, (e)ven, (E)ven no
                  check (default: none).
   -o <Speed>     Output speed, in bit/s (default: 9600 bit/s).
   -i <Speed>     Input speed, in bit/s (default: same as output speed).
   -x n|i|o|b     Software flow control (XON/XOFF): (n)one, (i)nput stream,
                  (o)utput stream, (b)oth streams (default: output stream).
   -l             Line mode (default).
   -e             Character mode with local echo.
   -c             Character mode without local echo.
   -t             Non-terminal mode (non-interactive mode).
   -f             Forward non-printable characters to output (default).
   -n             Display non-printable characters as their octal code
                  preceded by a back-slash ("\nnn").

Since this terminal emulator does not perform any character interpretation (except for the -n option), but simply forwards the serial-interface input stream to the standard output, the exact terminal type that is emulated depends on where it is executed (e.g., an ANSI terminal is emulated if executed within an xterm window).

The eterm terminal emulator has also the capability of downloading files. When typing Ctrl-C, this program prompts the user as follows:

eterm: (C)ontinue, (Q)uit, send (F)ile, (S)ize + file, (A)SCII char.: [C]

The C command continues with no effects. The Q command quits the terminal emulator. The F command prompts the user for a file name and downloads it. The S command prompts the user for a file name, sends its size as an decimal ASCII string followed by a new-line, and then downloads it. The A command allows a user to send any ASCII character given by its octal, decimal or hexadecimal code.

An older terminal emulator, term, takes the same arguments as eterm but lacks the Ctrl-C menu. Except in very special cases, there are no reasons to use term rather then eterm.

Setting the Workstation's ramdisk size

In order to use ramdisks with an x86-based workstation running Linux, you must ensure that the workstation has been booted with a large enough ramdisk size to handle the ramdisks that you plan to load into memory. By default, the ramdisk size built into the kernel seems to be 4Meg. Nearly all ramdisks we build are larger than that, so this value needs to be overridden. Assuming you use LILO as your boot loader, you would change this by specifying

append="ramdisk_size=16384"

in your /etc/lilo.conf. Our lilo.conf looks like this:

boot=/dev/sda
map=/boot/map
install=/boot/boot.b
prompt
timeout=50
image=/boot/vmlinuz-2.0.31
        label=linux
        root=/dev/sda1
        initrd=/boot/initrd-2.0.31.img
        read-only
        append="ramdisk_size=16384"
image=/boot/vmlinuz-2.0.31
        label=linux.stable
        root=/dev/sda1
        initrd=/boot/initrd-2.0.31.img
        read-only

Note that you will need to run /sbin/lilo (and then reboot once) after changing this file for the change to take effect.

If you forget to set the ramdisk size, you will experience I/O errors and other funny behavior when accessing your ramdisk.

Limits on ramdisk size

With the current memory layout on an Itsy, the compressed ramdisk is burned at memory address 0x00070000 and the kernel at address 0x00340000. This gives you a max of 2949120 bytes for a compressed ramdisk. If you overwrite your kernel, there will be no warning (but the kernel won't boot).

 

Compaq Internal Use Only

The Itsy Project is a joint effort of the Western Research Lab and the Systems Research Center

Last update: October 1998