Jump User's Manual
Version 1.0 Beta 4

Greg Hewgill <greg@hewgill.com>

Table of Contents

1 Jump
 1.1 What is Jump?
 1.2 Jump Features
 1.3 The Jump Package
 1.4 Requirements
 1.5 Installation
 1.6 Limitations

2 Using Jump
 2.1 Program Requirements
 2.2 Running Jump
 2.3 Options
 2.4 Program-specific Options

3 Technical Information
 3.1 Native code interface
 3.2 Miscellaneous

Appendices
 A Future Enhancements
 B Thanks to...

1 Jump

1.1 What is Jump?

Jump is a program that allows developers to write Java^TM code for the Pilot handheld PDA from Palm. This has nothing to do with the Internet, HTTP, or the World Wide Web, and in particular will not allow you to run or write Java "applets". It does allow you to use a well-designed, easy to learn language to write applications for the Pilot.

Jump works by reading the .class files produced by a Java compiler, creating 68000 assembly language .asm files as output. The .asm files are then assembled by Pila (the Pilot Assembler) to produce a .prc file which can be loaded directly into the Pilot. Jump is essentially the "back end" of a compiler (a Java source-to-bytecode compiler is the "front end").

The .prc files created by Jump are self contained and do not require any Java runtime support to be present on the Pilot.

1.2 Jump Features

There are no features yet. :)

1.3 The Jump Package

The Jump package includes the following files:

1.4 Requirements

Jump requires the following software:

• A correctly installed Java VM. Jump itself is written in Java and needs a VM to run. A good way to get a VM for Windows is to download Microsoft's Java SDK and install it. I believe this is also required in order to run the executable version of Jump (Jump.exe). You might want to get this and install it even if you already have Internet Explorer, because the Java SDK contains the latest VM for Windows.
• A Java compiler. I have tried both Sun's JDK and Microsoft's Java SDK and they both work. Other compilers (Visual Café, Borland JBuilder, etc) will most likely work too.
• The Pilot ASDK. Pila (the Pilot Assembler) is bundled in the ASDK and is required by Jump. Pilrc (the Pilot Resource Compiler) is not strictly required but makes resource creation easier.

In the ASDK, you will also find lots of tools and information that will be indispensable for developing Pilot applications.

1.5 Installation

NOTE: Do not use PKUNZIP! Use WinZip or another 32-bit unzip program. PKUNZIP, being a DOS program, does not handle long file names and will really screw this up.

1. Create a directory, for example c:\jump.
2. Extract the contents of the Jump distribution archive into this directory. Be sure to use the stored directory names so that each sample program ends up in its own directory.
3. Unzip the palmos package (palmos.zip) into this same directory, making sure you use the directory names stored in the palmos.zip file. The end result should be a bunch of .java and .class files in the c:\jump\palmos directory, not in c:\jump or c:\jump\palmos\palmos.
4. Modify your Java CLASSPATH environment variable to include the new c:\jump directory. You can do this with a command such as

   set classpath=c:\jump

   See your Java tools documentation if you need more information about the CLASSPATH variable.
5. Find the classes.zip file that was installed with your Java system, and unzip it into the directory where you found it (be sure to use the stored directory names). Currently Jump does not know how to look inside a zip file for system classes, so this step is necessary for now.
   • Sun JDK: This file can be found in c:\java\lib\classes.zip (or similar path).
   • MS Java SDK: This file can be found in c:\windows\java\classes\classes.zip (or similar path).

Once the files are properly installed, you should run through compiling one of the sample programs to make sure everything works.

1. Select the sample program to try. I'll use Hello for this example.
2. Open a Command Prompt (MS-DOS) window, and change to the Hello subdirectory.
3. Compile the Hello.java program using your Java compiler (javac for the Sun JDK or jvc for MS Java SDK). This should create the Hello.class file. Example:

   javac Hello.java

4. Use Pilrc (from the ASDK) to compile the Hello.rcp file. This should create the *.bin binary resources. Example:

   pilrc Hello.rcp

5. Run Jump to compile the Hello class into a Pilot executable. This should create Hello.prc. Example:

   Jump Hello

If everything goes well, you should now have a Hello.prc file that is ready to load onto your Pilot (or Copilot). If there is a problem, check the following items:

• If the Java compiler complains about the palmos package, make sure that the CLASSPATH environment variable contains only the Jump installation directory (ie. c:\jump, not c:\jump\palmos).
• If Jump says "Unable to start the application. The Java Virtual Machine cannot be found", then you do not have the latest Microsoft Java VM installed. You can either get the latest MS Java SDK, or you can unzip the Jump.zip file to get the Jump class files. Then run the Jump class using your Java SDK's applet viewer (this is java.exe for the Sun JDK).
• If Jump complains about the inability to find the system classes, make sure you have unzipped the classes.zip file into a tree of .class files.
• If Jump complains about native functions, make sure that the native-*.asm files are present and are in the same directory as Jump.properties.
• If Pila is not in your path, edit Jump.properties to tell Jump where Pila can be found (see section 2.3).

1.6 Limitations

The following major Java language features are not yet implemented by Jump:

• long (64-bit integer), float (32-bit IEEE), and double (64-bit IEEE) data types
• Interface method calls
• Multidimensional arrays (these almost work now)
• Class initialization functions
• Object finalize() function
• Threads (probably won't ever be implemented)

There are also some other features not yet implemented:

• Null pointers are not properly detected where they should be
• ClassCastException is not thrown when it should be
• The following opcodes:
  • dup_x2
  • dup2_x1
  • dup2_x2
  • goto_w
  • jsr_w
• 32-bit multiply and divide - currently Jump uses 16-bit multiply and divide instructions which can cause various unexpected arithmetic results
• The following long (64-bit integer) arithmetic operations:
  • addition
  • subtraction
  • multiplication
  • division
  • remainder
  • negation
  • shift right
  • unsigned shift right
  • comparison
• The following PalmOS API functions:

  Function	Reason
  DmFindSortPosition	no callback functions
  DmInsertionSort	no callback functions
  DmQuickSort	no callback functions
  ErrThrow	use Java throw instead
  EvtGetPenBtnList	returns pointer to array
  FindDrawHeader	FindParamsPtr
  FindGetLineBounds	FindParamsPtr
  FindSaveMatch	FindParamsPtr
  FplXxx	PalmOS floating point library
  FrmSetEventHandler	no callback functions
  GetCharAttr	returns pointer to array
  GetCharCaselessValue	returns pointer to array
  GetCharSortValue	returns pointer to array
  GrfMatch
  GrfMatchGlyph
  LstSetDrawFunction	no callback functions
  LstSetListChoices	array of char pointers
  PsrXxx	no callback functions
  SlkSendPacket	arrays of structures
  SlkSetSocketListener	no callback functions
  StrCat	modifies string data
  StrChr	returns address
  StrCopy	modifies string data
  StrItoA	modifies string data
  StrItoH	modifies string data
  StrStr	returns address
  StrToLower	modifies string data
  SysInsertionSort	no callback functions
  SysQSort	no callback functions
  TblSetCustomDrawProcedure	no callback functions
  TblSetLoadDataProcedure	no callback functions
  TblSetSaveDataProcedure	no callback functions
  WinGetPattern	CustomPatternType
  WinGetWindowPointer	returns pointer to structure
  WinSetPattern	CustomPatternType

• Not all of the PalmOS API constants have equivalents in the Java palmos package.

Some of the PalmOS API functions require the address of a callback routine to be passed to the API function. Examples of these functions are the sorting functions, FrmSetEventHandler, custom list and table draw functions, SlkSetSocketListener, and some others. These functions are not supported by the current version of Jump.

2 Using Jump

2.1 Program Requirements

The only requirement that Jump makes of your source code is that you have a function PilotMain in your main class declared like this:

    public static int PilotMain(int cmd, int cmdPBP, int launchFlags)

This is the function that is called when your application starts. For a normal application launch, cmd will be 0. This function should normally return 0.

Resources are expected to be found in a file called classname.res where classname is the name of the main class passed to Jump. This file is copied verbatim into the classname.asm file.

2.2 Running Jump

To create a .prc file from a .class file, run the Jump.exe program with the name of your main class (the one containing the PilotMain method) on the command line. For example,

Jump Hello

Assuming all goes well, Jump will create a Hello.asm file and automatically run Pila to create a Hello.prc file.

2.3 Options

Jump accepts options anywhere on the command line. The following options are recognized:

You may also create a file called Jump.properties in the current directory. This text file contains lines of the form "name=value". Valid property names are shown in the following table:

Here is an example of a Jump.properties file (the double backslashes are not a typo, they are required wherever you would normally use a single backslash):

javac=jvc
options=-c -o
pila=e:\\asdk\\bin\\pila

2.3 Program-specific Options

There are two program-specific options that Jump recognizes. These are specified in a file called classname.jump in the current directory. The valid options are:

Here is an example of a classname.jump file:

appname=Hello World
appid=Helo

3 Technical Information

3.1 Native Code Interface

Jump supports the Java native keyword for calling methods implemented in 68K assembly language. This is used by Jump to implement various native parts of the java.lang package, and also to implement the PalmOS API function stubs. The implementations of native methods are loaded from files that begin with "native-" and end with ".asm". There can be as many of these files as you like; they are all searched for native methods.

To create your own native methods, declare a method in a class as native. This indicates to the Java compiler and Jump that the implementation of the method is not in Java, but is an external method. Create a native-*.asm file to hold the implementation of the method, and write the assembler code for the method in this file.

You may put more than one native method implementation in a native .asm file. Each method implementation must be separated by at least one blank line, and method implementations cannot contain any blank lines.

Here is a simple example of a native method declaration and implementation:

  class NativeTest {
    public native static int Add(int x, int y);
  }

  NativeTest__Add:
          link    a6,#0
          move.l  8(a6),d0
          add.l   12(a6),d0
          unlk    a6
          rts

Note that arguments to Java methods are pushed from left to right. This is different from the way arguments are passed to PalmOS API functions.

3.2 Miscellaneous notes

On the garbage collector:

It's sort of an inverse mark and sweep. Sweep and mark, if you will. :) Each allocated block is kept in a linked list. Each time the garbage collector is run, it traverses through the list and attempts to find a pointer to the current block in one of three places: (1) the current stack, (2) the static data area, or (3) other objects on the heap. If it finds something that looks like a pointer, it assumes it is and continues to the next block. Otherwise, it deletes the block. There is an important optimization though - when a pointer to a block is located, the address of the pointer is stored in the block itself. On the next pass through, the garbage collector first checks to see whether the stored pointer location still points to the block. If so, it keeps the block. Otherwise, it performs another search for a pointer.

On calling PalmOS API functions:

For calls that return a pointer to a string, the stub creates a temporary Java byte[] array whose data pointer is initialized with the return value of the function, then calls the String constructor that takes a byte[] and creates a Java String. The end result is that the String class makes a copy of the data in the Java memory space.

For calls like DateToAscii that take a pointer to a buffer as a parameter, the stub generator makes the parameter a Java StringBuffer. Then it passes the address of the array data to the API function, which fills it in. After the API function return, the stub tweaks the length field of the StringBuffer so that the characters show up properly.

Appendices

A Future Enhancements

Here is a list of features that I would like to put into Jump. If you have any features you would like to see in Jump, please let me know!

• A portable (Java) assembler and resource compiler, so Jump can be run on non-Windows platforms.

B Thanks to...

Darrin Massena (Pilot Software Development) for Pila, the Pilot Assembler. Darrin is also leading the effort to put together the Alternative SDK, a suite of tools for Pilot development that is independent of the Macintosh.

Sam Neth (nethSoft) for convincing me that rewriting Jump itself in Java really was a good idea (I originally wrote it in C++).

Thomas Werthmann-Auzinger for the prodding that was required to get me to actually release the source.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.