Sun SPOT API
Green Release  


com.sun.squawk
Class VM

java.lang.Object
  extended by com.sun.squawk.VM
All Implemented Interfaces:
com.sun.squawk.pragma.GlobalStaticFields

public class VM
extends Object
implements com.sun.squawk.pragma.GlobalStaticFields

This is a Squawk VM specific class that is used to communicate between executing Java software and the low level core VM that is expressed in machine code. There are two parts to this. There are a set of native methods that are used to invoke very low level operations like manipulating memory at a very low level or performing I/O. In the other direction there are a number of methods that the low level core may call. These are used to implement high level operations that are better done in Java than in machine code.

A special version of this class exists for the romizer. The romizer version only implements the methods used to manipulate memory.

Version:
1.0
Author:
Nik Shaylor, Doug Simon

Nested Class Summary
static class VM.StackTraceElement
          Represents the method and bytecode index of the execution point in a frame on a thread's call stack.
 
Field Summary
static String LONG_COPYRIGHT
          Long Form Legal Notice of Sun Microsystems copyright.
static String SHORT_COPYRIGHT
          Short Form Legal Notice of Sun Microsystems copyright.
static int STREAM_STDERR
          The identifier denoting the standard error output stream.
static int STREAM_STDOUT
          The identifier denoting the standard output stream.
 
Constructor Summary
VM()
           
 
Method Summary
static void addServerConnectionHandler(ServerConnectionHandler sch)
          Adds a new ServerConnectionHandler to the list of active handlers.
static void allowUserGC(boolean value)
          Enable or disable Runtime.gc()
static long branchCount()
          Enables a dynamically loaded class to call this.
static void collectGarbage(boolean forceFullGC)
          Switch to the service stack and call 'GC.collectGarbage()'
static void diagnostic(String message)
          Prints the message on the serial port even after the USB has been enumerated
static void diagnostic(String message, int val)
          Prints the message on the serial port even after the USB has been enumerated
static long doubleToLongBits(double value)
          Converts a double into bits.
static void eliminateFinalizer(Object obj)
          Eliminates a finalizer.
static int execGraphicsIO(int op, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes an I/O operation on the graphics channel and return the result.
static int execIO(int op, int channel, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes a I/O operation that may block.
static long execIOLong(int op, int channel, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes an I/O operation that returns a long value.
static Address execMessageIO(int op, Object key, Object data, int status)
          Executes a message I/O operation.
static int execSyncIO(int op, int i1)
          Executes a non-blocking I/O operation whose result is guaranteed to be available immediately.
static int execSyncIO(int context, int op, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes a non-blocking I/O operation whose result is guaranteed to be available immediately.
static int execSyncIO(int op, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes a non-blocking I/O operation whose result is guaranteed to be available immediately.
static void fatalVMError()
          Halts the VM because of a fatal condition.
static void finalize(Object o)
           
static int floatToIntBits(float value)
          Converts a float into bits.
static void freeChannel(int channel)
          Frees a channel.
static Address getBootstrapEnd()
          Gets the address at which the object memory containing the bootstrap suite ends.
static int getBootstrapHash()
          Gets the hash of the object memory containing the bootstrap suite in it's canonical (i.e.
static Address getBootstrapStart()
          Gets the address at which the object memory containing the bootstrap suite starts.
static int getChannel(int type)
          Gets a new IO channel.
static Isolate getCurrentIsolate()
          Gets the isolate of the currently executing thread.
static char getFileSeparatorChar()
          The system-dependent default name-separator character.
static long getGUIEvent()
          Gets the next available event on the GUI input channel, blocking until there is one.
static String getManifestProperty(String name)
          Gets the value of an Suite.PROPERTIES_MANIFEST_RESOURCE_NAME property embedded in the suite.
static int getNextHashcode()
          Gets the next available hashcode.
static OutOfMemoryError getOutOfMemoryError()
          Get the sentinal OutOfMemoryException object
static char getPathSeparatorChar()
          The system-dependent path-separator character.
static Address getRomStart()
          Gets the address of the start of the object memory in ROM.
static long getTimeMicros()
          Gets the current time.
static long getTimeMillis()
          Gets the current time.
static float intBitsToFloat(int value)
          Converts bits into a float.
static void invokeMain(String className, String[] args)
          Call the main method of the specified class
static boolean isBigEndian()
          Get the endianess.
static boolean isCurrentIsolateInitialized()
          Determines if the current isolate is set and initialized.
static boolean isHosted()
          Determines if the Squawk system is being run in a hosted environment such as the romizer or mapper application.
static boolean isThreadingInitialized()
          Determines if the threading system is initialized.
static boolean isVerbose()
          Gets the flag indicating if the VM is running in verbose mode.
static boolean isVeryVerbose()
          Gets the flag indicating if the VM is running in very verbose mode.
static double longBitsToDouble(long value)
          Converts bits into a double.
static Mailbox lookupMailbox(String name)
           
static int lookupNative(String name)
          Gets the identifier for a native method.
static double math(int code, double a, double b)
          Performs a math operation.
static void print(boolean b)
          Prints a boolean to the VM output stream.
static void print(char x)
          Prints a character to the VM output stream.
static void print(double x)
          Prints a double to the VM output stream.
static void print(float x)
          Prints a float to the VM output stream.
static void print(int x)
          Prints an integer to the VM output stream.
static void print(long x)
          Prints a long to the VM output stream.
static void print(String x)
          Prints a string to the VM output stream.
static void printAddress(Object val)
          Prints an address to the VM stream.
static void println()
          Prints a new line to the VM output stream.
static void println(boolean x)
          Prints a boolean followed by a new line to the VM output stream.
static void println(char x)
          Prints a character followed by a new line to the VM output stream.
static void println(double x)
          Prints a double followed by a new line to the VM output stream.
static void println(float x)
          Prints a float followed by a new line to the VM output stream.
static void println(int x)
          Prints an integer followed by a new line to the VM output stream.
static void println(long x)
          Prints a long followed by a new line to the VM output stream.
static void println(String x)
          Prints a string followed by a new line to the VM output stream.
static void printObject(Object obj)
          Prints the string representation of an object to the VM stream.
static void printOffset(Offset val)
          Prints an offset to the VM stream.
static void printUWord(UWord val)
          Prints an unsigned word to the VM stream.
static int readSerial(byte[] b, int off, int len)
          Reads characters from the serial line: blocks until one is returned and then returns up to limit.
static boolean registerMailbox(String name, Mailbox mailbox)
          Register named mailbox with the system.
static VM.StackTraceElement[] reifyCurrentStack(int count)
          Returns an array of stack trace elements, each representing one stack frame in the current call stack.
static void setAsDaemonThread(Thread t)
          Mark the specified thread to be a daemon thread (won't prevent VM from exiting)
static int setStream(int stream)
          Sets the stream for the VM.print...
static Object shallowCopy(Object original)
          Perform a shallow copy of the original object, without calling a constructor
static void startTracing()
          Start the VM tracing if tracing support is enabled.
static void stopVM(int code)
          Halt the VM in the normal way.
static void unregisterMailbox(String name, Mailbox mailbox)
          Unregister named mailbox with the system.
static boolean userGCAllowed()
          Tests if Runtime.gc() is allowed.
static boolean usingTypeMap()
          Determines if the VM was built with memory access type checking enabled.
static long waitForDeepSleep(long minimumDeepSleepTime)
          Wait until it's possible that we can go to deep sleep.
static void waitForInterrupt(int irq)
          Waits for an interrupt.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LONG_COPYRIGHT

public static final String LONG_COPYRIGHT
Long Form Legal Notice of Sun Microsystems copyright. Must be embedded in the jar/suite file.

See Also:
Constant Field Values

SHORT_COPYRIGHT

public static final String SHORT_COPYRIGHT
Short Form Legal Notice of Sun Microsystems copyright. Must displayable in Sun applications, for example in version or help command.

See Also:
Constant Field Values

STREAM_STDOUT

public static final int STREAM_STDOUT
The identifier denoting the standard output stream.

See Also:
Constant Field Values

STREAM_STDERR

public static final int STREAM_STDERR
The identifier denoting the standard error output stream.

See Also:
Constant Field Values
Constructor Detail

VM

public VM()
Method Detail

reifyCurrentStack

public static VM.StackTraceElement[] reifyCurrentStack(int count)
Returns an array of stack trace elements, each representing one stack frame in the current call stack. The zeroth element of the array represents the top of the stack, which is the frame of the caller's method. The last element of the array represents the bottom of the stack, which is the first method invocation in the sequence.

Parameters:
count - how many frames from the stack to reify, starting from the frame of the method that called this one. A negative value specifies that all frames are to be reified.
Returns:
the reified call stack

math

public static double math(int code,
                          double a,
                          double b)
Performs a math operation.

Parameters:
code - the opcode
a - the first operand
b - the second operand
Returns:
the result

floatToIntBits

public static int floatToIntBits(float value)
Converts a float into bits.

Parameters:
value - the input
Returns:
the result

doubleToLongBits

public static long doubleToLongBits(double value)
Converts a double into bits.

Parameters:
value - the input
Returns:
the result

intBitsToFloat

public static float intBitsToFloat(int value)
Converts bits into a float.

Parameters:
value - the input
Returns:
the result

longBitsToDouble

public static double longBitsToDouble(long value)
Converts bits into a double.

Parameters:
value - the input
Returns:
the result

isHosted

public static boolean isHosted()
Determines if the Squawk system is being run in a hosted environment such as the romizer or mapper application.

Returns:
true if the Squawk system is being run in a hosted environment

isBigEndian

public static boolean isBigEndian()
Get the endianess.

Returns:
true if the system is big endian

setStream

public static int setStream(int stream)
Sets the stream for the VM.print... methods to one of the STREAM_... constants.

Parameters:
stream - the stream to use for the print... methods
Returns:
the current stream used for VM printing

printUWord

public static void printUWord(UWord val)
Prints an unsigned word to the VM stream. This will be formatted as an unsigned 32 bit or 64 bit value depending on the underlying platform.

Parameters:
val - the word to print

printOffset

public static void printOffset(Offset val)
Prints an offset to the VM stream. This will be formatted as a signed 32 bit or 64 bit value depending on the underlying platform.

Parameters:
val - the offset to print

printAddress

public static void printAddress(Object val)
Prints an address to the VM stream. This will be formatted as an unsigned 32 bit or 64 bit value depending on the underlying platform.

Parameters:
val - the address to print

printObject

public static void printObject(Object obj)
Prints the string representation of an object to the VM stream.

Parameters:
obj - the object whose toString() result is to be printed

print

public static void print(char x)
Prints a character to the VM output stream.

Parameters:
x - the value

print

public static void print(String x)
Prints a string to the VM output stream.

Parameters:
x - the string

print

public static void print(int x)
Prints an integer to the VM output stream.

Parameters:
x - the value

print

public static void print(long x)
Prints a long to the VM output stream.

Parameters:
x - the value

print

public static void print(float x)
Prints a float to the VM output stream.

Parameters:
x - the value

print

public static void print(double x)
Prints a double to the VM output stream.

Parameters:
x - the value

print

public static void print(boolean b)
Prints a boolean to the VM output stream.

Parameters:
b - the value

println

public static void println(char x)
Prints a character followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(String x)
Prints a string followed by a new line to the VM output stream.

Parameters:
x - the string

println

public static void println(int x)
Prints an integer followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(boolean x)
Prints a boolean followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(long x)
Prints a long followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(float x)
Prints a float followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(double x)
Prints a double followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println()
Prints a new line to the VM output stream.


finalize

public static void finalize(Object o)

getRomStart

public static Address getRomStart()
Gets the address of the start of the object memory in ROM.

Returns:
the address of the start of the object memory in ROM

getBootstrapStart

public static Address getBootstrapStart()
Gets the address at which the object memory containing the bootstrap suite starts.

Returns:
the bootstrap object memory start address

getBootstrapEnd

public static Address getBootstrapEnd()
Gets the address at which the object memory containing the bootstrap suite ends.

Returns:
the bootstrap object memory end address

getBootstrapHash

public static int getBootstrapHash()
Gets the hash of the object memory containing the bootstrap suite in it's canonical (i.e. relative to address 0) form.

Returns:
the hash of the bootstrap object memory

getPathSeparatorChar

public static char getPathSeparatorChar()
The system-dependent path-separator character. This character is used to separate filenames in a sequence of files given as a path list. On UNIX systems, this character is ':'; on Windows systems it is ';'.

Returns:
the system-dependent path-separator character

getFileSeparatorChar

public static char getFileSeparatorChar()
The system-dependent default name-separator character. This field is initialized to contain the first character of the value of the system property file.separator. On UNIX systems the value of this field is '/'; on Microsoft Windows systems it is '\'.

See Also:
System.getProperty(java.lang.String)

fatalVMError

public static void fatalVMError()
Halts the VM because of a fatal condition.


branchCount

public static long branchCount()
Enables a dynamically loaded class to call this.

Returns:
the number of instructions the VM has executed or -1 if instruction profiling is disabled

startTracing

public static void startTracing()
Start the VM tracing if tracing support is enabled.


isVerbose

public static boolean isVerbose()
Gets the flag indicating if the VM is running in verbose mode.

Returns:
true if the VM is running in verbose mode

isVeryVerbose

public static boolean isVeryVerbose()
Gets the flag indicating if the VM is running in very verbose mode.

Returns:
true if the VM is running in very verbose mode

getTimeMicros

public static long getTimeMicros()
Gets the current time.

Returns:
the time in microseconds

getTimeMillis

public static long getTimeMillis()
Gets the current time.

Returns:
the time in milliseconds

collectGarbage

public static void collectGarbage(boolean forceFullGC)
                           throws com.sun.squawk.pragma.NotInlinedPragma
Switch to the service stack and call 'GC.collectGarbage()'

Parameters:
forceFullGC - forces a collection of the whole heap
Throws:
com.sun.squawk.pragma.NotInlinedPragma - as the frame of this method will be the inner most frame on the current thread's stack. The inner most frame on any stack does not have it's local variables scanned by the garbage collector. As such, this method must not use any local variables.

stopVM

public static void stopVM(int code)
Halt the VM in the normal way.

Parameters:
code - the exit status code.

shallowCopy

public static Object shallowCopy(Object original)
Perform a shallow copy of the original object, without calling a constructor

Parameters:
original - the iobject to copy
Returns:
a copy of the original object.

getOutOfMemoryError

public static OutOfMemoryError getOutOfMemoryError()
Get the sentinal OutOfMemoryException object

Returns:
the object

execSyncIO

public static int execSyncIO(int op,
                             int i1,
                             int i2,
                             int i3,
                             int i4,
                             int i5,
                             int i6,
                             Object send,
                             Object receive)
Executes a non-blocking I/O operation whose result is guaranteed to be available immediately. This mechanism requires 2 calls to the IO sub-system. The first sets up the globals used to pass the parameters and initiates the operation. The second retrieves the result from the global that the operation stored its result in.

Parameters:
op - the opcode
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - an outgoing array parameter
receive - an incoming array parameter
Returns:
the integer result value

execSyncIO

public static int execSyncIO(int context,
                             int op,
                             int i1,
                             int i2,
                             int i3,
                             int i4,
                             int i5,
                             int i6,
                             Object send,
                             Object receive)
Executes a non-blocking I/O operation whose result is guaranteed to be available immediately. This mechanism requires 2 calls to the IO sub-system. The first sets up the globals used to pass the parameters and initiates the operation. The second retrieves the result from the global that the operation stored its result in.

Parameters:
context - the I/O context
op - the opcode
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - an outgoing array parameter
receive - an incoming array parameter
Returns:
the integer result value

execSyncIO

public static int execSyncIO(int op,
                             int i1)
Executes a non-blocking I/O operation whose result is guaranteed to be available immediately.

Parameters:
op - the opcode
i1 - an integer parameter
Returns:
the integer result value

execIO

public static int execIO(int op,
                         int channel,
                         int i1,
                         int i2,
                         int i3,
                         int i4,
                         int i5,
                         int i6,
                         Object send,
                         Object receive)
                  throws IOException
Executes a I/O operation that may block. This requires at least 2 calls to the IO sub-system: the first to execute the operation and the second to get the status of the operation (success = 0, failure < 0 or blocked > 0). If the status is success, then a third call to the IO sub-system is made to retrieve the result of the operation. If the status indicates that an exception occcurred in the IO sub-system, then an IOException is thrown. If the status indicates that the IO sub-system is blocked, then the status value is used as an event number to block the current thread and put it on a queue of threads waiting for an event.

Parameters:
op - the opcode
channel - the channel number
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - an outgoing array parameter
receive - an incoming array parameter
Returns:
the integer result value
Throws:
IOException

execMessageIO

public static Address execMessageIO(int op,
                                    Object key,
                                    Object data,
                                    int status)
                             throws IOException
Executes a message I/O operation.

Parameters:
op - the opcode
key - the message key
data - the message data or null
Returns:
the Address result or null
Throws:
IOException

execIOLong

public static long execIOLong(int op,
                              int channel,
                              int i1,
                              int i2,
                              int i3,
                              int i4,
                              int i5,
                              int i6,
                              Object send,
                              Object receive)
                       throws IOException
Executes an I/O operation that returns a long value.

Parameters:
op - the opcode
channel - the channel identifier
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - a outgoing reference parameter
receive - an incoming reference parameter (i.e. an array of some type)
Returns:
the long result
Throws:
IOException

execGraphicsIO

public static int execGraphicsIO(int op,
                                 int i1,
                                 int i2,
                                 int i3,
                                 int i4,
                                 int i5,
                                 int i6,
                                 Object send,
                                 Object receive)
Executes an I/O operation on the graphics channel and return the result.

Parameters:
op - the opcode
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - a outgoing reference parameter
receive - an incoming reference parameter (i.e. an array of some type)
Returns:
the event code to wait on or zero

getGUIEvent

public static long getGUIEvent()
Gets the next available event on the GUI input channel, blocking until there is one.

Returns:
the GUI event value

waitForInterrupt

public static void waitForInterrupt(int irq)
                             throws IOException
Waits for an interrupt.

Parameters:
irq - mask for interrupt
Throws:
IOException

waitForDeepSleep

public static long waitForDeepSleep(long minimumDeepSleepTime)
Wait until it's possible that we can go to deep sleep. It's possible if the thread scheduler has nothing to do for at least a certain length of time

Parameters:
minimumDeepSleepTime - the minimum time (in millis) that it's worth deep sleeping
Returns:
the target wake up time (in System clock millis) that we should return from deep sleep

readSerial

public static int readSerial(byte[] b,
                             int off,
                             int len)
                      throws IOException
Reads characters from the serial line: blocks until one is returned and then returns up to limit.

Parameters:
b - byte array in which to write chars read
off - offset in array to write to
len - maximum number of chars to read
Returns:
number of chars read
Throws:
IOException

diagnostic

public static void diagnostic(String message)
Prints the message on the serial port even after the USB has been enumerated

Parameters:
message -

diagnostic

public static void diagnostic(String message,
                              int val)
Prints the message on the serial port even after the USB has been enumerated

Parameters:
message -

invokeMain

public static void invokeMain(String className,
                              String[] args)
                       throws ClassNotFoundException
Call the main method of the specified class

Parameters:
className - the name of the class whose main method is to be run
args - the arguments to be passed to the main method
Throws:
ClassNotFoundException - if the class is not found

setAsDaemonThread

public static void setAsDaemonThread(Thread t)
Mark the specified thread to be a daemon thread (won't prevent VM from exiting)

Parameters:
t - The thread

getChannel

public static int getChannel(int type)
                      throws IOException
Gets a new IO channel.

Parameters:
type - the channel type
Returns:
the identifier for the newly created channel
Throws:
IOException

freeChannel

public static void freeChannel(int channel)
                        throws IOException
Frees a channel.

Parameters:
channel - the identifier of the channel to free
Throws:
IOException

addServerConnectionHandler

public static void addServerConnectionHandler(ServerConnectionHandler sch)
Adds a new ServerConnectionHandler to the list of active handlers.

Parameters:
sch - the ServerConnectionHandler to add
Throws:
IllegalArgumentException - if there is already a handler registered with the same name as sch

allowUserGC

public static void allowUserGC(boolean value)
Enable or disable Runtime.gc()

Parameters:
value - true to enable

userGCAllowed

public static boolean userGCAllowed()
Tests if Runtime.gc() is allowed.

Returns:
true if calls to Runtime.gc() are allowed

usingTypeMap

public static boolean usingTypeMap()
Determines if the VM was built with memory access type checking enabled.

Returns:
true if the VM was built with memory access type checking enabled

getNextHashcode

public static int getNextHashcode()
Gets the next available hashcode.

Returns:
the hashcode

getCurrentIsolate

public static Isolate getCurrentIsolate()
Gets the isolate of the currently executing thread.

Returns:
the isolate

getManifestProperty

public static String getManifestProperty(String name)
Gets the value of an Suite.PROPERTIES_MANIFEST_RESOURCE_NAME property embedded in the suite.

Parameters:
name - the name of the property whose value is to be retrieved
Returns:
the property value

isCurrentIsolateInitialized

public static boolean isCurrentIsolateInitialized()
Determines if the current isolate is set and initialized.

Returns:
true if the current isolate is set and initialized

isThreadingInitialized

public static boolean isThreadingInitialized()
Determines if the threading system is initialized.

Returns:
true if the threading system is initialized.

eliminateFinalizer

public static void eliminateFinalizer(Object obj)
Eliminates a finalizer.

Parameters:
obj - the object of the finalizer

lookupNative

public static int lookupNative(String name)
Gets the identifier for a native method.

Parameters:
name - the fully qualified name of the native method
Returns:
the identifier for the method or -1 if the method does not exist or cannot be dynamically bound to

registerMailbox

public static boolean registerMailbox(String name,
                                      Mailbox mailbox)
Register named mailbox with the system.

Parameters:
name - the public name of the mailboz
mailbox - the mailbox to use with that name.
Returns:
false if the name is already registered to a mailbox.

unregisterMailbox

public static void unregisterMailbox(String name,
                                     Mailbox mailbox)
Unregister named mailbox with the system.

Parameters:
name - the public name of the mailboz
mailbox - the mailbox to use with that name.

lookupMailbox

public static Mailbox lookupMailbox(String name)

Sun SPOT API
Green Release  


Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.