Jump2 User's Manual

Version 2.0 Alpha 8

24-Nov-2000
Ralf Kleberhoff ( kleberhoff@aol.com )

Watch the newsgroup pilot.programmer.jump on the server news.massena.com.

The current version can be found at http://sourceforge.net/projects/jump


LICENSE

Jump2 is distributed under the GNU GENERAL PUBLIC LICENSE (version 2),

Copyright (C) 1996/97 by Greg Hewgill
Copyright (C) 2000 by Ralf Kleberhoff

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.


WARNING

Jump2 is still in an Alpha state of development. Don't expect a stable development environment. Jump2 might notwork as expected. Don't blame me if something goes wrong - you have been warned...


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 JavaTM code for the Pilot handheld PDA from 3Com. 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, only bugs :)

1.3 The Jump Package

The Jump package includes the following files (I only mention the important ones):

jump.jar the Java classes that make up the Jump program
define.asm constants used by the native (68K assembly) routines
kernel.asm 68K assembly routines always included into Jump's output
native-java.asm some methods declared "native" in the Java class library, implemented in 68K assembly for Jump.
native-opcodes.asm assembly routines implementing some complex JVM opcodes
native-palmos.asm assembly routines (native methods of class palmos.Palm) interfacing Jump to the PalmOS operating system
native-Character.asm assembly routines overriding some methods of the java.lang.Character class with more compact ones.

The Jump package also includes the following directories (again, I only mention the important ones):

NewSource the Java source files that make up the Jump program
javadocs the auto-generated documentation of the Jump source files
doc a few HTML pages describing Jump (includes this page)
jar the jarfile of the Jump program plus a batch-file
examples some example programs for Jump
tools the PalmOS API generator

1.4 Requirements

Jump requires the following software:

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

1.5 Installation

  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. Modify your Java CLASSPATH environment variable to include the jar file the new c:\jump directory plus the directory where you have your program. You can do this with a command such as
    set classpath=c:\jump\jar\jump.jar;.

    See your Java tools documentation if you need more information about the CLASSPATH variable.

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

Select the sample program to try. I'll use Hello for this example.

  1. Open a Command Prompt (MS-DOS) window, and change to the Hello subdirectory.
  2. 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
  3. Use Pilrc (from the ASDK) to compile the Hello.rcp file. This should create the *.bin binary resources. Example:
    pilrc Hello.rcp
  4. Run Jump to post-compile the Hello.class file into a Hello.asm file. Example:
    java Jump Hello
  5. Run Pila (from the ASDK) to assemble the Hello.asm file (together with the *.bin resource files) into the Palm binary Hello.prc. Example:
    Pila Hello.asm

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

If you want to write your own program, you need to write the following files (replace <project> with the name of your project):

  1. Write the Java program sources.
  2. Write a <project>.rcp resource description file for Pilrc.
  3. Write a <project>.res file listing the binary resource files that you got from Pilrc.

1.6 Limitations

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

The following features are now implemented (maybe, they work...)

There are also some other features not yet implemented:

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.

And, remember that this is an Alpha version, so expect some problems...


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 an .asm file from a .class file, run the Jump program with the name of your main class (the one containing the PilotMain method) on the command line. For example,

java Jump Hello

Assuming all goes well, Jump will create a Hello.asm file (and not yet automatically run Pila to create a Hello.prc file, you have to do this yourself).

2.3 Options

Jump accepts options anywhere on the command line. The following options are recognized (MOST OPTIONS AREN'T IMPLEMENTED IN Jump2 Alpha5:

Option     Description
-v Verbose progress and status output.
-b Insert a Debuffer-compatible breakpoint into the lead-in code.

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:

TABLE INVALID FOR JUMP2, HAVE A LOOK AT THE SAMPLE FILES INSTEAD.

Property   Default   Description
javac javac Name of command line Java compiler. Use jvc for MS Java SDK.
options   Option flags (above) as they would be specified on the command line.
pila pila Name of Pila assembler. May include a pathname if pila is not in your path.

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:

TABLE INVALID FOR JUMP2, HAVE A LOOK AT THE SAMPLE FILES INSTEAD.

Option   Default   Description
appid test Four-letter PalmOS application ID.
appname classname Name of application as it will appear in the Pilot applications list.

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 normally begin with "native-" and end with ".asm".

You name the files in the 'xxx.jump' project-specific properties file, under the key 'natives' as space-separated list; just use the filename without the path, they are searched for via CLASSPATH.

To create your own native methods, declare a method in a class as native (not strictly necessary in Jump2, but as a matter of style, you should do it). 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. Include the name of this file in the project-properties file 'xxx.jump' under the key 'natives'.

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.

CHANGE FROM 1.0

Each method implementation must begin with a specially formatted comment line, exactly naming the method implemented here. Naming scheme is the JVM-internal scheme based on type signatures. Have a look at the example native-java.asm.

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

NativeTest.java

  package dummy;
  class NativeTest {
    public native static int add(int x, int y);
  }

native-test.asm

  ;; native-method dummy/NativeTest.add(II)I
          link    a6,#0
          move.l  8(a6),d0
          add.l   12(a6),d0
          unlk    a6
          rts

NativeTest.jump

  natives=native-test.asm

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. Arguments are popped from the stack by the caller. Return values are passed in d0 (or d0 and d1 for long or double values) or a0.

Note that in Jump2 it is possible to install a native implementation not only for methods declared native, but for all methods. A native implementation takes precedence over the Java version.

There are more keywords in native files than just "native-method". They are written as a block of comment lines before the assembly instructions, beginning with a "native-method" or "jvm-opcode" line, each line starting with a double semi-colon:

;; kernel-routines Only to be used in the kernel.asm file, means that the whole file is included.
;; native-method method-name The following subroutine implements the given method.
;; jvm-opcode opcode-name The following subroutine implements the given JVM opcode.
;; uses-class classname [as symbol] The native code declared in the preceding comment-line depends on the given class. If a symbol is given, all occurrences of this symbol in the native code are replaced by the class-index of the given class.
;; uses-instance classname The native code declared in the preceding comment-line possibly creates instances of the given class. The exact class must be given, not a subclass, a superclass or an interface.
;; needs-exact-layout classname The native code declared in the preceding comment-line directly accesses fields of the given class, treating it like a C-language structure. This means that Jump will reproduce a struct-like layout of all fields and will not eliminate unneeded fields.
;; uses-method method [as symbol] The native code declared in the preceding comment-line calls the given method. The method meant is exctly the one specified, and not an overriding implementation in a subclass. If a symbol is given, all occurrences of this symbol in the native code are replaced by the assembly label of the method.
;; uses-field field [as symbol] The native code declared in the preceding comment-line uses the given field. If a symbol is given for a static field, all occurrences of this symbol are replaced by the assembly label of the field. If a symbol is given for a normal (instance) field, all occurrences of the symbol are replaced by the decimal representation of the offset of the field.

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.

I'll probably change the GC to use a different algorithm, thus avoiding the problems with POSE described below.

On using POSE:

If you run Jump-generated programs under POSE, you should switch off some debug options, especially "MemMgr Data Structure" and "Free Chunk Access". The garbage collector sometimes reads from memory that once was allocated, but may have been freed in the meantime. This is not a bug, but a feature of this special type of garbage collector.

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.

There is a tool MkApi that generates the implementation. If you NEED additional PalmOS traps, MkApi might help you. But it's your responsibility to deal with the results ;-).


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!

The current state of development can be found in the Jump2 Development Notes.

B Thanks to...

(from Ralf to ...):

Greg Hewgill ( greg@hewgill.com ), the original developer of Jump. Thanks for inventing it and making it free software. And thank you for Copilot, the PalmOS emulator now known as POSE. It's indispensible for any Palm programmer.

Eric Sessoms ( sessoms@pagesz.net ), the author of Debuffer, a FORTH-based, programmable debugger interacting with POSE. Debuffer helped me a lot in finding errors. Its programmability allows for powerful debugging and data inspection macros. I had to learn the basics of FORTH first, but it was worth the pain!

Keith Rollin ( krollin@palm.com ) was very helpful in answering questions on technical details of PalmOS.

George Magiros ( george@stonehenge.ohr.gatech.edu ) contributed opcode implementations for the float and double data types.

Darrin Massena ( Pilot Software Development ) not only developed Pila, the Pilot Assembler, but also hosts the pilot.programmer.* newsgroups on his news.massena.com server.

Wes Cherry ( wesc@ricochet.net ) developed PilRC, the least painful way (as far as I know) of creating Palm resources.

Noli Sicad ( nsicad@yahoo.com ) did a lot of testing and contributed example software.

Both Rob Nielsen ( rnielsen@wn.com.au ) and Peter Carroll ( kedge@se77en.com ) did a lot of testing and are actively working on Waba compatibility classes for Jump.

...and to all the volunteers ready to experiment with an unstable tool.

(and from Greg for Jump version 1.0 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 Pilot Page) 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.


Jump is Copyright © 1996,1997 by Greg Hewgill
and Copyright © 2000 by Ralf Kleberhoff
Email: kleberhoff@aol.com

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