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 NotesIn 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 ItsyA 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 EnvironmentThe 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. CalibrationIf 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 AloneOnce 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 WorkstationAn 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. PPPTo 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 PPPOnce the configuration files for PPP are set up (see below), you can start the daemon running by
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 PPPTo 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
Connecting to an Itsy using a Workstation running Windows 95/NTBackground 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:
Once started, you may make the additional change:
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:
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 ramdiskThe 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:
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:
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 MemoryThis 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:
For:
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 programsOnce 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 kernelYou 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 fileYou 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-ItsyYou 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 monitorThe 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. GeneralitiesThe latest released revision of the monitor is the Itsy Monitor version 2.3.
At WRL, the monitor is also available in the directory:
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:
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:
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 monitorThere 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:
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:
to set the operating-system boot address, entering:
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 APIThere are three basic ways of starting the monitor, that result in three different behaviors:
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 behaviorIf 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:
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 behaviorIf 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 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:
Monitor restart behaviorIf 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: etermThe 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:
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:
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 sizeIn 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 sizeWith 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