Download 5 JSCP Monitor

JSCP
™
™
Software Co-Processor for Java
Architecture & User’s Guide
Using Java in Embedded Systems
VERSION 1.1.4a
SEPTEMBER 1999
Copyright
© 1997-1999 NSIcom. All the rights reserved.
Trademarks
JSCP, c2ROM, f2ROM, Event-Driven System and JSCP Monitor are trademarks of
NSIcom.
Java and all the Java-based trademarks are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and other countries.
All the other product and company names mentioned herein may be the trademarks of their
respective owners.
The software described in this book is furnished under a license agreement and may be used
only in accordance with the terms of the agreement.
Contact NSIcom
NSIcom, Ltd.
1C Yoni Netanyahu
Or-Yehuda 60376
ISRAEL
Tel:
Fax:
Web:
E-mail:
+972-3-533-1976
+972-3-533-2371
http://www.nsicom.com
[email protected] for general information
[email protected] for technical support
SOFTWARE CO-PROCESSOR
FOR
J AV A
TABLE OF CONTENTS
1
PREFACE .............................................................................................................................................1
Audience ........................................................................................................................................................ 1
Compatibility ................................................................................................................................................. 1
Related Publications ...................................................................................................................................... 1
Document Conventions ................................................................................................................................. 2
Formatting ................................................................................................................................................ 2
Terminology............................................................................................................................................. 2
Development Environment ...................................................................................................................... 2
NSIcom Customer Support ............................................................................................................................ 2
2
INTRODUCTION ................................................................................................................................3
2.1
2.2
3
THE JAVA PLATFORM .........................................................................................................................3
THE EMBEDDED SYSTEM CHALLENGE ...............................................................................................4
OVERVIEW OF JSCP ARCHITECTURE .......................................................................................5
3.1
3.2
3.3
MAIN FEATURES ................................................................................................................................5
JSCP ENCAPSULATION FUNCTION .....................................................................................................6
JSCP MULTITHREADING ....................................................................................................................8
Non-Contiguous Dynamic C Stacks for each Java Thread ....................................................................... 8
Centralized Memory Resource Management ........................................................................................... 8
Time-Sliced Scheduling, with Support for Priority Inversion Avoidance ................................................ 8
Proprietary Polling Scheduler .................................................................................................................. 9
Non-Interruptible Java Thread Scheduling............................................................................................... 9
Support of Non-Standard Devices ............................................................................................................ 9
Monitoring and Control of JSCP Activities ............................................................................................. 9
3.4 GARBAGE COLLECTION ....................................................................................................................10
3.5 JSCP MEMORY MANAGEMENT SUBSYSTEM ....................................................................................11
3.5.1
Heaps and Stacks ................................................................................................................12
3.5.2
Minimum Impact on Existing RTOS Tasks ..........................................................................13
3.5.3
Robust Clean-up ..................................................................................................................13
3.5.4
Memory Usage States (Memory Colors) .............................................................................13
3.6 DYNAMIC LINKING OF NATIVE CODE...............................................................................................15
3.7 EVENT DRIVEN SUBSYSTEMS (EDS) ................................................................................................16
3.7.1
Typical EDS Architecture ....................................................................................................16
3.7.2
Characteristics and Limitations of EDS ..............................................................................17
3.7.3
Real-Time Applications and the EDS ..................................................................................18
Networking over Ethernet ...................................................................................................................... 18
Mouse Support for GUI Applications .................................................................................................... 19
3.7.4
Support for Multi-Processor Devices ..................................................................................19
3.8 ABSTRACT WINDOWING TOOLKIT (AWT) .......................................................................................20
4
SPECIFIC FEATURES FOR EMBEDDED SYSTEMS .................................................................21
4.1
4.2
4.3
4.4
4.5
4.6
SCOPE ..............................................................................................................................................21
EMBEDDING JAVA APPLICATIONS ....................................................................................................21
JSCP MONITOR THREAD ..................................................................................................................22
INTERNAL SUPPORT FOR 64-BIT OPERATIONS ..................................................................................22
POWER-SAVE MODE ........................................................................................................................23
JSCP ON WINDOWS NT....................................................................................................................23
© 1997-1999 NSIcom
i
SOFTWARE CO-PROCESSOR
FOR
J AV A
TABLE OF CONTENTS (C ONT ’ D )
5
JSCP MONITOR ................................................................................................................................25
5.1 JSCP MONITOR OVERVIEW..............................................................................................................25
5.2 START-UP AND PRELIMINARY CONFIGURATION ...............................................................................26
5.3 JSCP MONITOR DISPLAY ELEMENTS ...............................................................................................26
5.3.1
Menu Bar .............................................................................................................................27
5.3.2
Thread Monitoring Table ....................................................................................................28
5.3.3
CPU and Memory Usage ....................................................................................................29
5.3.4
Function Buttons .................................................................................................................29
5.4 USING THE JSCP MONITOR ..............................................................................................................30
5.4.1
Control of Threads ..............................................................................................................30
5.4.2
Displaying JSCP Settings ....................................................................................................30
5.4.3
JSCP Performance Statistics ...............................................................................................30
5.4.4
Restarting the JSCP ............................................................................................................30
5.4.5
Entering The Monitor Mode ................................................................................................31
6
JSCP UTILITY PROGRAMS ...........................................................................................................33
6.1
6.2
SCOPE ..............................................................................................................................................33
C2ROM ......................................................................................ERROR! BOOKMARK NOT DEFINED.
Application Considerations .................................................................................................................... 33
6.3
F2ROM ......................................................................................ERROR! BOOKMARK NOT DEFINED.
Application Considerations .................................................................................................................... 34
6.4
J2CLINKS .........................................................................................................................................35
Application Considerations .................................................................................................................... 35
7
INSTALLING THE JSCP .................................................................................................................37
7.1 SCOPE ..............................................................................................................................................37
7.2 JSCP COMPONENTS .........................................................................................................................37
7.2.1
JSCP Build and Run-time Environment ..............................................................................37
7.2.2
JSCP Monitor ......................................................................................................................38
7.2.3
JSCP Utilities ......................................................................................................................38
7.2.4
JSCP Documentation ..........................................................................................................38
7.3 SYSTEM REQUIREMENTS ..................................................................................................................38
7.4 SOFTWARE INSTALLATION ...............................................................................................................38
8
INTEGRATING THE JSCP WITH THE RTOS ............................................................................39
8.1
8.2
8.3
9
GENERAL .........................................................................................................................................39
CREATING AN OS TASK FOR THE JSCP ............................................................................................40
JSCP CONFIGURATION .....................................................................................................................41
JSCP API .............................................................................................................................................43
9.1 USING THE JSCP API’S ....................................................................................................................43
9.2 CONFIGURATION AND INITIALIZATION FUNCTIONS ..........................................................................43
9.2.1
jsPtargetConfig ...................................................................................................................43
9.2.2
jsPtargetJprop .....................................................................................................................45
9.2.3
jsPtargetMainClass .............................................................................................................46
9.2.4
jsPtargetStart ......................................................................................................................46
9.2.5
jsPtargetInit .........................................................................................................................47
9.2.6
jsPtargetStop .......................................................................................................................47
9.2.7
jsPsetDateTime....................................................................................................................47
9.2.8
gcPsetOptions......................................................................................................................48
ii
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
TABLE OF CONTENTS (C ONT ’ D )
9.3 EMBEDDING CLASSES, FILES, AND NATIVE LINKS ...........................................................................49
9.3.1
jsPaddRomClasses ..............................................................................................................49
9.3.2
jsPaddRomFiles ..................................................................................................................49
9.3.3
jsPaddRomZIP ....................................................................................................................50
9.3.4
jsPaddOptionalClasses .......................................................................................................50
9.3.5
jsPaddRomLinks ..................................................................................................................51
9.4 STARTING OPTIONAL SUBSYSTEMS ..................................................................................................52
9.4.1
jsPstartReflect .....................................................................................................................52
9.4.2
jsPstartBigNum ...................................................................................................................52
9.4.3
jsPstartNet ...........................................................................................................................52
9.4.4
JsPstartSUN_NET ...............................................................................................................53
9.4.5
jsPstartMTR ........................................................................................................................53
9.4.6
jsPstartFIO ..........................................................................................................................53
9.4.7
jsPstartAWT ........................................................................................................................53
9.5 MISCELLANEOUS API ......................................................................................................................54
9.5.1
jsPmallocSpl ........................................................................................................................54
9.5.2
jsPfreeSpl ............................................................................................................................54
9.5.3
btPsetPowerSave .................................................................................................................54
9.5.4
jsPstdOut .............................................................................................................................55
9.5.5
jsPspit ..................................................................................................................................55
9.6 EDS API ..........................................................................................................................................56
9.6.1
EDS Call-back Functions ....................................................................................................56
9.6.2
btPedsNew ...........................................................................................................................57
9.6.3
btPedsDel ............................................................................................................................58
9.6.4
btPedsOptions .....................................................................................................................58
9.6.5
btPedsPollCallBack ............................................................................................................59
9.6.6
btPedsFlushCallBack ..........................................................................................................59
9.6.7
btPedsAbortCallBack ..........................................................................................................60
9.6.8
btPedsWait ..........................................................................................................................60
10
TECHNICAL SUPPORT...................................................................................................................61
11
GLOSSARY ......................................................................................................................................... A
© 1997-1999 NSIcom
iii
SOFTWARE CO-PROCESSOR
FOR
J AV A
LIST OF FIGURES
FIGURE 1: JAVA APPLICATION ON AN RTOS (THE GENERIC MODEL) ..............................................................6
FIGURE 2: JAVA APPLICATIONS ENCAPSULATED WITHIN THE JSCP ................................................................6
FIGURE 3: GENERIC JVM CONTIGUOUS MEMORY ALLOCATION ....................................................................12
FIGURE 4: JSCP NON-CONTIGUOUS MEMORY ALLOCATIONS........................................................................13
FIGURE 5. TYPICAL EDS ARCHITECTURE .......................................................................................................17
FIGURE 6: JSCP MONITOR WINDOW ..............................................................................................................26
FIGURE 7: JSCP-RTOS CONTROL FLOW ........................................................................................................39
iv
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
1
FOR
J AV A
PREFACE
Welcome to the Software Co-Processor for Java™ (JSCP™) from NSIcom, Ltd. JSCP is an
enhanced Java Virtual Machine optimized for the constraints imposed by embedded devices.
Using the JSCP and its accompanying tools, embedded system developers can utilize the
advantages of Java world together with the native applications.
Audience
This manual is intended for software professionals interested in the following topics:

Implementation of a Java-enabled embedded environment. This manual shows you how
to integrate the JSCP with your real-time operating system.
Development of Java applications for the embedded environment. This manual shows you
how to include your Java applications within the JSCP. You can also learn how to load
and run Java applications from a network.

Development of native methods and their implementation within the JSCP.
Compatibility
The JSCP is an implementation of the Java Virtual Machine (JVM). The Java class libraries,
which define the Java Application Programming Interface (API), are also included.
The Java development tools (e.g., as contained in the JDK from Sun Microsystems, Inc.) are
not part of this product. Please refer to The Java Platform and System Requirements sections for
a complete list of prerequisites.
This version of the JSCP is compatible with:

Java Development Kit 1.1 from Sun Microsystems, Inc.

Your platform (RTOS and hardware), as discussed with your NSIcom representative.
For details, see the JSCP Readme.doc, included in this package.
Related Publications

JSCP README file, included in this package.
Campione, Mary, and Kathy Walrath. 1998. The Java Tutorial: Object-Oriented Programming for the
Internet. Addison-Wesley, 1996. Reprint.
The
documentation page on Sun Microsystems Inc. Java web site,
http://java.sun.com/docs/. The page contains links to many useful documents,
including the on-line version of The Java Tutorial, as well as documentation for the Java
Development Kit (JDK).
The documentation accompanying your operating system.

The documentation covering the hardware used in your embedded device.
© 1997-1999 NSIcom
1
SOFTWARE CO-PROCESSOR
FOR
J AV A
Document Conventions
The following conventions are used in this manual:
Formatting

Code appears in a mono-spaced font. For example:
for (count = 0; count < 5; count ++){
References to filenames and their locations appear in a sans serif font. For example:
j-src\config.c
Terminology

The terms task and multitasking are used in relation to the operating system; the
equivalent Java concepts are referred to as thread and multithreading.
The term native function refers to a function written in the C or Assembly language.
The terms native thread and native task refer to an OS task which is not executing any Java
code, but may be executing code on behalf of the JSCP. The term OS task refer to any
code which is not part of the JSCP.
The term user usually refers to the engineer who is integrating the JSCP into the embedded
system, not to the end user of the product.
Development Environment

You can develop applications with the JSCP on a variety of operating systems (e.g.,
Unix), using a variety of tools (e.g., Microsoft Visual J++). For the sake of simplicity, the
examples and instructions in this manual are presented for Sun's JDK on Windows NT.
All the file references are relative to the jscp\ parent directory.
NSIcom Customer Support
We value your comments. If you have any problems, ideas, or suggestions, please contact us
at the addresses listed in this manual under Technical Support.
2
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
2
INTRODUCTION
2.1
The Java Platform
FOR
J AV A
The Java platform is made out of four distinct but interrelated technologies, each of which is
defined by a separate specification from Sun Microsystems, Inc:

The Java programming language.

The Java class file format.

The Java Application Programming Interface.

The Java Virtual Machine (JVM).
This document is concerned only with Java Virtual Machines.
Adding a Java Virtual Machine to your embedded system provides the following advantages:

Portability
Java was designed from the bottom up for cross-platform independence. Java’s motto,
“Write once, run everywhere” is fast becoming a reality. While most languages compile
to machine-dependent object code, Java source code is compiled to bytecode, which is a
set of instructions to a virtual machine. The bytecode can then be run on any hardware
platform where a Java Virtual Machine (JVM) has been installed.

Dynamic
In most embedded systems, the absence of a file system or any secondary storage, limits
the application to the original code burned into the ROM when the device is first
programmed. In contrast, Java’s network support and dynamic linking capabilities allow
easy access and dynamical program execution.

Size
The Java bytecode is significantly smaller than native machine code. In addition, the
highly modular architecture of the Java bytecode allows you to leave out the pieces you
don’t need, thus reducing the memory footprint of your application.

Security
Java has a built-in modifiable security manager, that enables the execution of code from
untrusted sources in a trusted environment.

GUI Support
Java has a well-established windowing and graphics subsystem, called the Advanced
Windowing Toolkit (AWT), which does not depend on any underlying graphic or
windowing library. This allows you to add GUI applications to your device in a very
efficient and standard way.
For more information on Java, visit Sun's Java home page at http://java.sun.com/.
© 1997-1999 NSIcom
3
SOFTWARE CO-PROCESSOR
2.2
FOR
J AV A
The Embedded System Challenge
Despite Java’s robustness and portability to standard desktop operating systems (and many
times, because of Java’s robustness), embedded systems present the programmers with
several challenges. For example:
 Java applications must be able to integrate with an existing RTOS without disturbing its
other applications. For example, Denial-of-Service (DoS) might be only an annoyance
while browsing the Web, but in a mission-critical embedded system, service guarantees
are mandatory.
Typically, the embedded system programmer has full control over all the tasks running
in the device and the resources consumed by each task, and can determine the stack size
of each task; moreover, in many cases, memory is pre-allocated to each task and
recursive calls are avoided. However, with Java applications, this level of control is just
not possible: recursive native function calls are intrinsic within the JVM (e.g.,
ExecuteJava(), LoadClassFromClass() ), memory cannot be pre-allocated, and there is no
explicit memory de-allocation command in the Java language. Therefore, control over
application execution can only be performed in the JVM itself. Though Java security
protects against illegal operations, it cannot protect against DoS.
Embedded systems usually support custom, non-standard external devices. Since Java does
not allow direct access to the system API, those devices need to be recognized and
supported by the JVM itself. A developer needs a way by which to extend the embedded
Java Virtual Machine.
Java is dynamic, which means that there is no linking stage in the process of building a Java
application. Instead, classes are linked at run time as they are referenced. Java classes may
also reference native C code, which means that the virtual machine should be able to
dynamically link native C code at run time. In the Windows environment, for example, this
is achieved by placing the native code in Dynamic Linked Libraries (DLL). Though some
RTOS’s provide support for shared libraries and dynamic linking, most do not.
Embedded systems often lack secondary storage devices and therefore do not have a file
system. All the Java applications require at least a simulated file system for initial class
loading, system properties, etc…
On a desktop computer, a Java application is executed from the command line, in which the
end-user may specify parameters both to the JVM and to the Java application to be run.
Embedded systems usually do not support a command line at the end-user level.
Real-time operating systems typically lack virtual memory management; they also lack reset and
clean-up services. As a result, the option of hitting Control-C and restarting the JVM is not
available to the end user of an embedded Java virtual machine as it is to the desktop user.
Applications running on embedded systems must be able to maximize efficiency in a
typically resource-poor environment (e.g., low storage capacity, no file system, no
runtime linking and loading mechanism).
 Real-time operating systems do not necessarily support thread control, preemption, and
64-bit arithmetic.
 Real-time operating systems support a variety of CPU’s, thus compromising application
portability.
The JSCP offered by NSIcom is an enhanced Java Virtual Machine based on Sun’s JVM. The
JSCP is fully compliant with Sun’s specifications and is optimized for the embedded environment
to address the above challenges. After integrating the JSCP into your embedded system, you have
added a whole new dimension of capabilities to your device, and any third-party application
written in Java will execute on your device unmodified, without recompiling, and in a secure way.
4
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
3
OVERVIEW OF JSCP ARCHITECTURE
3.1
Main Features
FOR
J AV A
The JSCP is a Java Virtual Machine especially designed for embedded devices. It provides a
Java environment that is:

Easy to configure and implement alongside existing non-Java applications.
Simplifies the creation of support for non-standard external devices in Java (bar-code
readers, robotic arms, etc…).
Does not rely on the existence of any file system for performing Java-compatible operations.
Does not rely on an underlying native graphic windowing system for implementing the Java
AWT.
Optimized for efficient, flexible use of device memory.
Tracks memory and CPU usage, and provides reset and clean-up services.
Not dependent on the RTOS for multithreading services and control.
Able to operate in an otherwise non-preemptive environment1.
Provides 64-bit emulation2 where not supported by the hardware or compiler.
Able to load classes dynamically from the network.
Minimally dependent on RTOS and CPU, thus maintaining a high degree of portability. The
JSCP has been ported to all the major RTOS and CPU architectures, and to more than a
few proprietary embedded environments.
1
2
Non-preemptive environment - an environment in which the control over running programs is arbitrary.
64-bit emulation - Java requires 64-bit operations, therefore it requires support for 64-bit arithmetic.
© 1997-1999 NSIcom
5
SOFTWARE CO-PROCESSOR
3.2
FOR
J AV A
JSCP Encapsulation Function
Multithreading is an integral part of any full-featured Java application (it is also a JVM
requirement). While many operating systems provide multithreading services, some do not.
More importantly, embedded systems present some unique challenges that could limit the
effectiveness of native multithreading. This is the result of the commonly-used approach to
JVM implementation, as recommended by Sun (referred to below as the generic JVM
implementation, or just generic JVM), which maps Java threads directly to native tasks.
When using the generic JVM, each Java thread appears to the RTOS as a separate task, as
shown in Figure 1. The RTOS must then provide the scheduling of each Java thread, and
must synchronize among the Java threads and the other RTOS tasks.
Java Thread X
Java Thread Y
RTOS
OS Task A
OS Task B
OS Task C
Existing Embedded Applications
Figure 1: Java Application on an RTOS (the Generic Model)
The JSCP offered by NSIcom uses encapsulation, i.e., all the Java threads are encapsulated
within the JSCP virtual machine. As a result, the JSCP, along with all the Java applications
running within it, appear to the RTOS as a single task. This model is shown in Figure 2.
Java Thread X
OS Task A
RTOS
OS Task B
OS Task C
Java Thread Y
JSCP Kernel
JSCP Task
Java Thread Z
Java Thread U
OS Task D
Existing Embedded Applications
Java Thread V
JSCP
Figure 2: Java Applications Encapsulated Within the JSCP
6
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
The encapsulation function, which is performed by the JSCP kernel, provides a simple and
reliable solution to multithreading. However, although the use of encapsulation to replace
RTOS tasks by a proprietary thread package is by itself an important function, encapsulation
has many additional important and far-reaching consequences. Among these are:

Greater security and reliability for both the Java and the non-Java portions of the
system.

Retention of the essential characteristics of the non-Java part, such as response time,
interrupt latency, and other parameters which are crucial in embedded applications.

When scheduled by the non-Java part, the JSCP is free to manage its own affairs without
disruption.

Better maintainability.

Improved performance.
© 1997-1999 NSIcom
7
SOFTWARE CO-PROCESSOR
3.3
FOR
J AV A
JSCP Multithreading
The JSCP has built-in kernel code that controls the execution of all the Java threads. For this
purpose, the JSCP includes a proprietary package, called Blue Threads, that handles all the Java
thread scheduling, monitoring and control functions.
The Blue Threads package includes the JVM scheduler, SCHD. SCHD does not execute any
Java code; it does however, perform system-related operations on behalf of Java threads.
SCHD is mapped to an RTOS task upon system initialization (this is similar to the generic
JVM, in which the Java Primordial thread is mapped to the RTOS main task). However,
unlike the generic JVM, due to the use of encapsulation the only task the RTOS knows
about is the JVM scheduler, SCHD (there are some configurations that require a few
additional auxiliary native tasks to provide support for JSCP subsystems).
The Blue Threads package has several unique features, explained below.
Non-Contiguous Dynamic C Stacks for each Java Thread
The Blue Threads package enables the C stack associated with each Java thread to grow and
shrink dynamically, as needed for thread execution (see also the Garbage Collection section).
This feature confers significant advantages relative to the generic JVM, which uses the nonencapsulated model. In the non-encapsulated model, it is necessary to pre-define the size of the C
stack assigned to Java threads. This means that all the threads will get the same C stack size,
although they might execute recursive calls to different levels. As a result, the person
installing the JVM in an embedded system must define the C stack size without any real
information on the C stack size the JVM will actually require, considering the wide range of
arbitrary applications to which it will be eventually exposed.
Centralized Memory Resource Management
The Blue Threads package provides for central management of memory resources. Among
other advantages, central management of memory resources enables reliable clean-up of the
resources the JSCP has used, and reliable restarting (resetting) of the JSCP.
This contrasts with the non-encapsulated model, which has no knowledge of the actual utilization
of the memory resources, and therefore makes centralized resource management impractical
and exposes the other non-Java applications to increased risk of interference from the Java
threads. A particularly problematic scenario occurs when the resource manager is trying to
kill a Java thread because it is consuming too many resources: the resource manager may kill
that thread even if it may be locking a critical section (either a JVM-private critical section, or
a section which is critical to the whole system), and thus leave the JVM, or the entire system,
in an unstable state.
These characteristics of the non-encapsulated model make services such as JVM restarting and
clean-up of the resources the JVM has used, very hard to implement.
Time-Sliced Scheduling, with Support for Priority Inversion Avoidance
The JVM scheduler of the Blue Threads package uses time-slice scheduling. The time-slice
duration is user-configurable (commonly-used values are 20 to 60 ms).
8
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
Proprietary Polling Scheduler
RTOS’s usually use interrupt-driven schedulers to ensure “hard real-time” response, whereas
Java is an interpretive language. Java has several inherent features, which contribute to its
robustness, but at the same time may also make Java a “non-hard real-time” platform:
Java uses an asynchronous Garbage Collection thread for de-allocation of unused memory
resources.
All the Java threads are interconnected via a shared GC pool, shared GC hash tables, shared
interlocked class loading, and other internal mechanisms.
On the other hand, Java is a robust language that is well suited to the implementation of
“soft real-time” tasks, and can control the execution of any number of “hard real-time”
native tasks. However, in the non-encapsulated model, a Java thread does not inherit the
real-time properties of the native thread to which it is mapped.
Given the nature of the Java language and the architecture of the JVM, we at NSIcom have
chosen a proprietary polling scheduler that improves the real-time performance of the JSCP.
This proprietary polling scheduler confers the following advantages:
The use of a polling mechanism makes the JSCP more robust and efficient, because code
need not be reentrant. As a result, the JSCP does not use internal interlocks for memory
allocations, nor hash table access.
The polling mechanism is based on the use of Event Driven Subsystems (EDS), which enable the
programmers to avoid the interdependencies associated with interrupts and their use.
Non-Interruptible Java Thread Scheduling
The proprietary polling mechanism used by the Blue Threads package for dispatching external
events and rescheduling Java threads, together with the use of time-slice scheduling, make
the JSCP a very predictive Virtual Machine: a Java thread awaiting an external event is
guaranteed to have the CPU assigned to it no later than one time-slice interval.
Support of Non-Standard Devices
Due to its built-in EDS capability, the JSCP can be easily extended by the user to enable the
handling of events from non-standard devices, such as robotics arm, remote controls, and
many others. Additional details on the EDS capability are given below.
Monitoring and Control of JSCP Activities
The JSCP kernel uses an internal non-Java thread to report the JSCP activity to a remote
monitor application. Using this application, the user can remotely monitor and modify the
JSCP behavior (see the JSCP Monitor application for more information).
The Blue Threads enable the JSCP to run in an idle state, where only the JVM scheduler,
SCHD, and the monitor threads are running. While the JSCP is in this idle state, the enduser can command the JSCP to load a Java application from the network and execute it.
The JVM scheduler, SCHD, keeps track of CPU usage by all the Java threads. Future
releases will allow monitoring and control of additional resources.
© 1997-1999 NSIcom
9
SOFTWARE CO-PROCESSOR
3.4
FOR
J AV A
Garbage Collection
In Java, memory is allocated to an object whenever the object is created, but there is no
explicit way to free an object and release the memory it occupies: a Java object is freed and
the memory it occupies is reclaimed automatically when the object is no longer referenced.
This method is called Garbage Collection (GC). The Garbage Collection code is executed
asynchronously in the context of a system thread under the control of the JSCP scheduler,
SCHD. The basic algorithm used for garbage collection is the Mark & Sweep algorithm
developed by Sun.
The JSCP garbage collection function has been enhanced in the following ways:

The JSCP uses a Memory Management Subsystem to enable the allocation of non-contiguous
dynamic GC heaps, and keeps the handles separated from the objects in two distinct
lists of pages. In comparison, the generic JVM uses a fixed pre-allocated heap to hold
both handles and objects.

The Mark & Sweep algorithm is implemented in the non-contiguous heap.

The asynchronous Garbage Collection (aGC) thread is always initialized. As an option,
the aGC thread can be initialized in the suspended mode (this is performed by means of
one of the user-selectable parameters in the JSCP configuration file). The initialization
mode can also be changed from the monitor application (see the JSCP Monitor).

The behavior and priority of the aGC thread changes dynamically in accordance with the
state of memory contention. The JSCP supports the definition of three threshold levels
for memory contention: Green, Yellow, and Red (see details below).
When the JSCP memory usage increases beyond the Green threshold and crosses the
preset Yellow or Red threshold, the aGC priority increases and the GC algorithm
becomes more aggressive.

The Mark & Sweep algorithm is an atomic operation: this means that after a mark &
sweep operation has begun, it must either be allowed to complete, or it must be rolled
back. To provide better support for time-critical operations, the JSCP provides a bailout option: when this option is used, the aGC thread will yield the CPU to any thread
with a priority higher than the current aGC thread priority.
The aGC thread runs at the lowest priority when the memory color is Green, however
when the memory color becomes Red, the aGC priority is automatically boosted to the
highest level.
10

The aGC function implemented by the JSCP starts to collect free memory in accordance
with internal criteria of memory usage, whereas the generic JVM executes the aGC
thread at predefined time intervals.

The GC heap is compacted simply by copying fragmented pages to a new page, and
then resetting the object pointer in the relevant handle. However, if an object has a
reference from the C code, then the page containing it is pinned down and will not be
compacted.
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
3.5
FOR
J AV A
JSCP Memory Management Subsystem
Java applications (and the JVM itself) are known for requiring substantial amounts of
memory, and using it in a very fragmented way.
For example, by the time the basic Virtual Machine (without the Abstract Windowing Toolkit
(AWT)) is up and running, and before any Java application is started, approximately 2000
Java objects are already allocated in the GC heap, and 1600 C objects are allocated in the
non-GC heap, requiring a total memory of about 450 kB. Add the AWT to your JVM and
you will get ~3000 Java objects and ~5000 C objects.
On the other hand, most embedded systems have limited real memory, and lack virtual
memory altogether. To solve this dichotomy, the JSCP incorporates its own second-level,
paged memory management subsystem.
The JSCP memory management supports the following main features:

All the memory allocations in the JSCP, including Java objects (GC handles and GC objects,
C stacks and C objects) are handled through the memory management subsystem.

The JSCP calls upon the RTOS to allocate memory pages, not objects. The JSCP memory
management then allocates objects in the memory pages acquired from the system.

The JSCP maintains a list of free pages. The action taken when a page is no longer in
use, depends on the user-modifiable memory colors.

The JSCP maintains several distinct heaps: all the memory pages of a particular heap are
linked together. All the heaps except one (the large object heap) have the same memory
page size, therefore pages can be moved from one heap to another.

There is one heap, called the large object heap, that handles objects larger then the page
size; each element in this heap contains exactly one object. The pages in the large object
heap are returned to the system immediately when they are no longer in use.

Each heap can have a different allocation unit. The smallest allocation unit is 16 bytes,
and the overhead per allocation unit is one byte.

Separate lists of pages are used for GC handles and for GC objects, therefore the GC
heap is dynamic in size and non-contiguous. The allocation rules are as follows:
All the GC handles have the same size, therefore there is no overhead for handling the
GC handles.
All the GC objects are allocated in the same heap (list of pages), regardless of their size.
C objects are allocated in different heaps, depending on object’s size.

The user defines the total memory limit in the configuration file at compile time.

The JSCP keeps track of all the pages, and the total amount of memory used by the
virtual machine and by the Java applications. This enables the JSCP to provide clean-up
and restart services.

The JSCP memory management has a public API. The users are encouraged to use this
API, while extending the JSCP with native code.
© 1997-1999 NSIcom
11
SOFTWARE CO-PROCESSOR
FOR
J AV A
3.5.1 Heaps and Stacks
In a generic JVM (see Figure 3), the GC heap is allocated at start-up and cannot be changed
while the JVM is running. Similarly, while each C stack is allocated dynamically, its size is
determined when its thread begins to run; moreover, all the C stacks have the same size,
which does not change until the thread is complete and thus the corresponding stack space
is freed.
The problem with the fixed stack size is that whatever size is selected, it will not be optimal,
because if it is too small, the application will crash. Consequently, the stack size must be set
to the maximum amount the programmer expects the (unknown) applications will require,
resulting in the waste of a scarce resource.
Memory Usage Legend
Wasted
Used
Garbage
Collection
Heap
Malloc’ed Blocks
C Stack
(Thread 1)
C Stack
(Thread 2)
C Stack
(Thread 3)
Figure 3: Generic JVM Contiguous Memory Allocation
The major improvement in memory management offered by the JSCP is the support for
non-contiguous GC heaps and C stacks. This means that the sizes of the GC heap, and the
size of each C stack need no longer be predetermined at start-up, as is typically the case in
any other JVM; rather, it changes dynamically, on the fly, as required by the running
applications. This allows the various applications running under the JSCP to share the
available (and valuable) memory.
Figure 4 illustrates the advantage of non-contiguous allocation.
12
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
Memory Usage Legend
Malloc’ed
Blocks
Wasted
Used
Garbage
Collection
Heap
C Stack
(Thread 2)
C Stack
(Thread 3)
C Stack
(Thread 1)
Figure 4: JSCP Non-Contiguous Memory Allocations
3.5.2 Minimum Impact on Existing RTOS Tasks
As mentioned previously, the JSCP and all the Java applications running under it are
encapsulated into a single task. The JSCP manages all the memory requirements for all the
Java application threads, as well as for the native methods and the virtual machine itself.
By keeping a record of each allocation, the JSCP lets you limit the total JSCP memory usage
by specifying a single external parameter in the JSCP configuration file (see mem_limit in
Configuration Parameters).
3.5.3 Robust Clean-up
Due to the use of encapsulation, in general only the JVM scheduler, SCHD, is mapped to
the system task. Furthermore, the JSCP memory manager keeps a record of each page of
memory allocated. Therefore, when the JSCP is restarted, the JSCP scheduler first instructs
the memory manager to free all the allocated memory prior to restart.
3.5.4 Memory Usage States (Memory Colors)
The JSCP does not pre-allocate memory for the GC heap, nor for any other use. Instead, the
JSCP enables the user to specify (in the configuration file) the limit to be imposed on the
total JSCP memory usage (the maximum amount of RAM that will be used by the JSCP at
run time).
The user can also define memory color thresholds in the configuration file. The memory
color thresholds enable to dynamically control the memory usage at run time, whenever
memory is requested or reclaimed, as follows:
© 1997-1999 NSIcom
13
SOFTWARE CO-PROCESSOR
FOR
J AV A

Green:
The priority of the asynchronous Garbage Collection (aGC) and Finalizer threads is
set to minimum (priority 1).
The GC heap is not compacted.
Unused memory pages are not returned to the system, but are kept in a local free
memory list.

Yellow:
The priority of the aGC and Finalizer threads is set to normal priority, plus one
(priority 6).
The GC heap is not compacted.
Unused memory pages are returned to the system.

Red:
The priority of the aGC and Finalizer threads is set to the highest priority (priority 10).
Memory requests are honored only if the requester is a system thread.
The GC heap will be compacted.
Unused memory pages are returned to the system.
The user can directly specify the memory color thresholds, or can instruct the JSCP to
calculate the optimum memory color thresholds in accordance with the mandatory total
memory utilization limit (this is made by entering 0 for the memory colors in the JSCP
configuration file).
14
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
3.6
FOR
J AV A
Dynamic Linking of Native Code
Java is a complete and comprehensive programming environment. Unlike programming in
C, you cannot simply reference a system function that resides in some library, because there
is no linking stage involved in building a Java application. Instead, linking is performed at
run-time by the virtual machine when a native method is first referenced.
Most of the native code that Java applications may require is already provided by the JSCP.
For example, if your application requires networking, the JSCP includes the tools necessary
to link your Java code to java.net classes, and to link java.net methods to the native TCP/IP
socket library.
Embedded systems often require support for non-standard devices, e.g., remote controls,
robotic arms, bar-code readers, special cameras, etc. To support a non-standard device in
your Java application, it is necessary to extend your virtual machine to recognize the new
device, because the native C code can only be accessed through the virtual machine.
The JSCP provides a mechanism to extend the virtual machine, which does not depend on
the underlying RTOS for DLL or shared library support. This mechanism consists of a
utility program, J2Clinks, that creates link tables, and code within the JSCP that dynamically
links Java classes to native methods using those link tables (for more information, see
J2Clinks below).
When preparing extensions to the virtual machine, observe the following guidelines:

User-defined native methods should never make a blocking system call (such as read()).
If such a call is required, it should be implemented as an Event Driven Subsystem (see
the EDS section below).

User-defined native methods should use the JSCP public API whenever feasible. Using
the JSCP public API is particularly important when using the memory allocation and deallocation functions.
© 1997-1999 NSIcom
15
SOFTWARE CO-PROCESSOR
3.7
FOR
J AV A
Event Driven Subsystems (EDS)
The previous section discussed the need and the ways by which you can extend the
embedded Java Virtual Machine with native code to support special devices.
This section presents the approach and tools used to enable a Java application utilizing an
external device to operate as an event-driven application, that is, to enable the application
the application to respond to events generated asynchronously by an external device. For
this purpose, the events generated by an external device must be dispatched to the Java
application thread awaiting them. The mechanism by which the JSCP performs the event
registration and dispatching is called an Event Driven Subsystem (EDS).
A typical example of an event-driven system is Java networking: in this case, the external
device is the network interface card (NIC), e.g., an Ethernet card:

When a Java application thread is calling the method accept() in class java.net.SocketImpl,
the request is registered with the EDS serving the network, and the thread is put on
hold.

When a remote computer makes a connect() request with the right address and port
number, the EDS serving the network detects this request, notifies the waiting thread
and passes the connection data to it.

An EDS consists of one or more native C modules implementing the code needed to
support a particular external device. An EDS will always have two components:

Front-end, dynamically linked to Java classes (using J2Clinks tables). The front-end uses
the EDS API calls for communicating to the JSCP scheduler and for dispatching the
events generated by the device to the Java application thread.

Back-end, linked to the external hardware device. The back-end is usually implemented
as a separate system task.
The methods used to enable the EDS front-end and back-end to communicate, e.g., system
messages or private queues, can be chosen by the programmers.
The JSCP already implements all the standard Java packages such as java.net, java.io, java.awt,
etc, as Event Driven Subsystems.
3.7.1 Typical EDS Architecture
The typical EDS architecture is shown in Figure 5. The sequence of activities performed by
the typical EDS is as follows:
1. The EDS is activated when a Java thread that requests input from an external device
invokes a native method in the EDS front end (the native method is dynamically
linked to the Java class on the first invocation, using the J2Clinks table).
2. The EDS front end puts the request on its output queue, which is the input queue of
the back end. The EDS back end is implemented as a separate RTOS task.
NOTES
16

The transfer of requests from the EDS front end to the EDS output
queue is made only when required by the particular EDS application.
For instance, the AWT EDS never executes this action.

The queues used by the EDS might be RTOS queues, however, in many
applications is it sufficient to use simple lightweight pseudo-FIFO queues.
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
3. The EDS front end calls btPedsWait() to register the fact it is waiting for an event. At
this point, the thread making the call is put on hold.
4. The JSCP kernel polls the EDS for available events (using EDS call-back methods).
The call-back methods retrieve data from the front-end input queue (which is the
back-end output queue).
5. The JSCP kernel notifies the thread awaiting the event, and passes a pointer to the
event data.
6. The thread resumes execution immediately after the call to btPedsWait(). It then
processes the event, reformats the data as necessary, and returns it to the Java code.
The auxiliary system task is used asynchronously to perform the following steps:
1. Retrieve EDS front-end requests via the queue.
2. Execute the request.
3. Send completed events through the queue to the EDS front end.
JSCP Task
Java
Thread
JSCP
Micro
Kernel
Auxiliary Task
4
3
1
5
EDS
(EDS
Front End)
C
Input
Queue
EDS
(EDS
Back End)
6
Output
Queue
B
2
EDS
A
Figure 5. Typical EDS Architecture
3.7.2 Characteristics and Limitations of EDS

The JSCP does not make any assumptions, nor does it impose any restrictions on the
structure or use of EDS events. The structure, the content, and the way events are
implemented are entirely at the discretion of the programmer of the particular EDS.
Therefore, the usefulness of the EDS can be enhanced by realizing that events in the
context of EDS should be considered in the broadest possible way. In as far as an EDS
is concerned, events are not required to come from an external device; they need not to
be real events at all.

The EDS programmer must provide the C call-back methods to implement the desired
© 1997-1999 NSIcom
17
SOFTWARE CO-PROCESSOR
FOR
J AV A
EDS actions. The call-back methods are used by the JSCP to poll the EDS for events, to
get the next event, and to flush the EDS buffers.

There is only one mandatory call-back method; the other methods are optional.

All the call-backs are invoked by the JSCP in the context of the internal JVM scheduler
thread. The JVM scheduler, SCHD, is part of the JSCP kernel. Using OS terminology,
call-backs are executed in the system mode.

Events are uniquely identified by three values:

The object ID (user-defined).

The event ID (user-defined).

The thread ID of the waiting thread (appended by the JSCP).
The interpretation and the use of each identifier are totally at the discretion of the
programmer. For example, the asynchronous Garbage Collection thread is controlled by
an EDS; internal VM “events”, such as memory page allocation, stack pop-out, and
thread termination, are all the bundled into a single pseudo-event that may be simply
called the “kick me in and let me run” event. In this last case, all the event identifiers are
simply ignored.

The EDS is usually implemented using an auxiliary system task, where the front end
runs within the context of the JSCP, and the back end runs within the context of an
auxiliary system task.

Methods in the EDS front end should never make a system blocking call. System
blocking calls may however be invoked within the EDS back end, because the back end
is implemented as a separate auxiliary system task.

There is no limitation on the number of concurrent EDS’s. Also, any EDS can be
created and deleted at run-time.
The Typical EDS Architecture section presents the EDS architecture and examples of typical
implementations.
3.7.3 Real-Time Applications and the EDS
As mentioned in the The Embedded System Challenge section, “hard real-time” applications pose
real challenges when implemented on a Java platform, mainly because the programmer has
very little control over memory utilization and thread synchronization.
However, when analyzing a real-time application, we often realize that the real-time nature
of an application is actually determined (and required) only in a small segment of the code
comprising the application. To illustrate this point, let us analyze two common applications,
which are generally considered to be classical real-time applications: network access, and
mouse support in a GUI.
Networking over Ethernet
The exchange of information over a network involves several processing layers:

18
The lowest level is the physical layer, which provides the interface to the network,
in this example – to the Ethernet LAN media. This layer processes data flowing at
rates of 10 or 100 megabits per second (Mbps), rates that require real-time
response on the order of nanoseconds.
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
No software can sustain this type of response, and therefore this part of the
application is implemented in hardware on the Ethernet card.

The next layers above the physical layer process packets. Packet processing
requires sub-millisecond response time, therefore protocols in the IP suite of
protocols are implemented in high-priority system tasks.
The TCP layer is also implemented in a system task. The TCP layer operates as a
buffer for the incoming data, and therefore at the next higher layer, the BSD
sockets layer, an application hardly retains any real-time attributes, nor are such
attributes needed.

The Java code reside on top of the BSD layer, hence real-time operation is not an
issue at this level. Therefore, in the JSCP, the glue code connecting the java.net
API to the BSD layers and to other TCP/IP stacks is implemented as an EDS.
Mouse Support for GUI Applications
A GUI application would not normally qualify as a real-time application. However, the
part of a GUI system that moves the mouse cursor around is of a real-time nature (no
user would not like the mouse to freeze when other applications or threads are running).
The JSCP implementation of the Abstract Windowing Toolkit (AWT) does not rely upon,
nor does it use, any services that have to be provided by an underlying windowing
system, because the entire window manager is written in Java. Furthermore, the mouse
cursor is moved and redrawn by the JSCP (this is done even in the Windows NT version
of the JSCP, which is intended mainly for simulation purposes). If mouse movement
events were to travel all the way from the mouse driver to the Java code in the JVM, and
then back through the system to the frame buffer, mouse response would be extremely
poor.
The AWT implementation in the JSCP utilizes an auxiliary system task whose function is
to get mouse and keyboard events. Mouse moves are implemented locally within that
task: only the mouse clicks (which are much less frequent) are passed through the AWT
EDS to the Java window manager.
The two previous examples demonstrate two highly-interruptible, or highly interactive, Java
applications of real-time nature. Nevertheless, in both cases, the application is layered in
such way that the highly-interruptible part of it does not involve Java (or the VM) at all.
The EDS is very flexible, enabling you to establish arbitrary communication links between
your Java classes and the native tasks that implement real-time functions. Doing so you
enjoy all the advantages of Java, including its robustness and the portability, without losing
the real-time nature of your RTOS and your existing or new native code.
3.7.4 Support for Multi-Processor Devices
The use of encapsulation and the EDS architecture implemented in the JSCP enable using
multiple processors. This requirement can be simply met by placing EDS back-ends on
different processors. The preferred arrangement is to place each particular EDS on the
processor on which the driver of the corresponding external device runs.
This is possible even in case the processors have different architectures. For example, this
may be required to run old system application code together with new applications.
© 1997-1999 NSIcom
19
SOFTWARE CO-PROCESSOR
3.8
FOR
J AV A
Abstract Windowing Toolkit (AWT)
The JSCP fully supports the AWT according to Sun’s specifications. The implementation is
based on the Tiny AWT from Sun, and is built as an EDS, so it can handle various AWT
input devices.
The result is an AWT implementation that can be used on virtually any platform, without
degrading performance. Furthermore, the AWT implementation is entirely transparent to the
user. Therefore, you can program your application using the same techniques you would use
on any desktop operating system, and in addition take into consideration the following
points:
The JSCP AWT does not require any underlying native graphics or windowing system:
The window manager in the JSCP AWT is implemented in Java.
Other parts are implemented in native C code within the JSCP.
Your platform must be able to support minimal graphics requirements. Specifically, a dumb
linear frame buffer is required for rendering graphics.
Though this limitation is not inherent in the AWT code, any graphic display less than
about half the size of a VGA would not be sufficient for implementing the full AWT.
The AWT supports two input devices: a keyboard and a pointing device (e.g., mouse). We
have implemented AWT using a remote control that plays both the role of the keyboard
and the mouse.
The AWT is of course an option with the JSCP, because very often embedded systems do
not have any display device. In this case, to avoid wasting memory, the AWT code and
classes are not included in the JSCP image.
20
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
4
SPECIFIC FEATURES FOR EMBEDDED SYSTEMS
4.1
Scope
FOR
J AV A
This Chapter describe additional JSCP features that have been specifically designed to
enhance support for JSCP applications in embedded systems:
4.2
Embedding Java Applications
A Java virtual machine interprets and executes the bytecode that is the output of a Java
compiler. The generic JVM assumes that you have a file system implemented in your device,
and therefore it is designed to load the bytecode from *.class files in order to execute it.
However, in most cases embedded systems do not have a file system of any kind, and
therefore the JSCP provides a mechanism that enables you to embed your Java application
and make it a part of your JSCP (or entire system) image load. This mechanism consists of
two utility programs:
Error! Reference source not found. enables you to embed the Java code, which resides
in *.class files. Using the c2ROM reduces the RAM requirements by
about 40% when the ROMized classes are loaded at run-time.
Error! Reference source not found. enables you to embed any other type of file. For
example, you can use the f2ROM to embed GIF images, resource handles,
ZIP files, JAR files containing classes, etc. You can also embed a whole
directory tree.
ZIP and JAR files, or the directory tree you embed, can be included in the
CLASSPATH used by the virtual machine.
The classes comprising the Java API known as classes.zip are already part of the JSCP image,
therefore you need not mention them in the CLASSPATH parameter, nor load them in any
other way. The JSCP also provides a way to configure which of the packages appearing in
the classes.zip file will be included in the JSCP image (see JSCP Configuration).
If your device does have a native file system, the JSCP will support it. In addition, the
internal embedded file system of the JSCP is still available for you to use, even when the
device has a real file system:

Whenever a file or directory is referenced, the JSCP searches the internal embedded file
system first.

If the entry is not found and a native file system is implemented, the native file system is
searched for the entry.
© 1997-1999 NSIcom
21
SOFTWARE CO-PROCESSOR
4.3
FOR
J AV A
JSCP Monitor Thread
Normally, the generic JVM does not reveal any information on its execution state, and
therefore it acts like a black box executing Java code. As a result, if the user’s application
runs into a deadlock, the end user has no way of knowing that.
In an embedded system, matters are even worse, since the JVM may be running on a remote
machine which does not have any user input or output device: therefore, the Java application
may have crashed without the user knowing it.
To alleviate the problem, the JSCP kernel includes a dedicated Monitor thread, whose
execution is also controlled by the JVM scheduler. The Monitor thread does not execute any
Java code: its sole purpose is to display the JSCP and Java application status, monitor and
control the Java and system threads running within the JSCP virtual machine.
The Monitor thread communicates with a remote JSCP Monitor application, described in
detail in a separate Chapter. The JSCP Monitor application is written entirely in Java, and
therefore can run on any Java-enabled workstation (Solaris, Windows NT, etc.).
The communication between the Monitor thread and the JSCP Monitor uses a proprietary
UDP-based network protocol. The Monitor thread acts as a UDP server, and therefore it
can simultaneously provide information regarding the JSCP activity to more than one
workstation.
The JSCP monitoring tools can provide many services, for example:

Provide continuos snapshot access to execution status, performance measurements,
CPU and memory usage, etc. and therefore can be used to analyze system performance
and in particular the memory usage.

Monitor all the JSCP threads, including monitoring at the Java level. This means that
the JSCP monitoring tools can be used to trace through the Java stack.

Facilitate debugging of Java applications, by providing continuous information about
application interlocks, deadlocks and other information.

Instruct the JVM scheduler to restart (reset) a user application, or the entire JVM.
These characteristics make the JSCP monitoring tools indispensable during both system
development and system testing.
4.4
Internal Support for 64-bit Operations
Although Java (and in particular Java core classes, hence the Java Virtual Machine) requires
support for 64-bit operations, most processors do not support 64-bit operations, and
therefore on such processors it is to use compilers that can compensate by emulating 64-bit
operations in software.
Since most embedded compilers do not include emulation of 64-bit operations, the JSCP
contains a built-in solution, that automatically performs 64-bit emulation when necessary.
Your installation of the JSCP has been set to use the fastest type of 64-bit operations
available on your system. You need not do anything to implement 64-bit support.
22
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
4.5
FOR
J AV A
Power-Save Mode
As mentioned previously, the JSCP kernel controls the execution of all the Java and internal
system threads. This enables the JVM scheduler to detect the situation when the virtual
machine is idle, and all the threads are in some kind of a waiting state.
This capability can be used to enable the implementation of a power-save mode. For this
purpose, the user can specify via the JSCP API a native method, to be called by the JVM
scheduler when the virtual machine is idle. The called method will then switch the hardware
to the power-save mode and block; it should return only when an external event (such as
keyboard hit) is detected by the hardware.
4.6
JSCP on Windows NT
Unlike embedded C applications, Java applications are always developed on a desktop
computer. The reason is that the Java compiler does not run on the embedded device, only
the Java Virtual Machine. The bytecode generated on the desktop computer will, of course,
run on the Java enabled embedded device.
JVM’s, even when fully compatible, may still differ with respect to look&feel, memory usage,
CLASSPATH usage, system properties, etc. The ability to try and test the Java application on
the target JVM running on the desktop computer used for development is therefore very
desirable. For this purpose, NSIcom provides a Windows NT version of the JSCP, along
with the JSCP for the target (embedded) device.
The Windows NT JSCP version is not the generic JVM, nor is it a simulated JSCP: it is a
genuine JSCP, with all the features mentioned above, namely it does not map Java threads to
NT threads, does not use the Win32 GUI, and it uses internal software mouse, not the NT
workstation’s mouse.
Moreover, the user configures the JSCP version for Windows NT in exactly the same way
the JSCP is configured on the target device: the memory limit of the NT version can be set
to the actual memory limit of the target device, the screen size can be set to that of the target
device, file system support can be disabled in the NT version if it does not exist on the target
device, etc. Essentially, the Windows NT version enables you to try and test your Java
application on a flexible development environment before you try it on your embedded
device.
The Windows NT JSCP version also uses and supports the embedding of Java classes,
together with all the JSCP API’s, including the EDS API’s. Hence this version is a very
convenient platform for the development and testing of new event-driven Java applications.
Moreover, since the EDS is such a flexible method for linking Java classes to native code, it
also enables you to simulate non-standard external devices on your Windows NT JSCP
version (examples appear at the end of this book)
NSIcom strongly recommends that you always take advantage of the opportunity to try your
application first on the Windows NT version of the JSCP.
© 1997-1999 NSIcom
23
SOFTWARE CO-PROCESSOR
FOR
J AV A
NOTES
24
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
5
JSCP MONITOR
5.1
JSCP Monitor Overview
FOR
J AV A
The JSCP Monitor is a Java application that runs on a Java-enabled remote workstation, and
allows you to monitor and control the JSCP activities through a network connection.
The JSCP Monitor receives information on the JSCP status by communicating with the JSCP
Monitor Thread, which reports on the activities of all the other threads running on the JSCP.
Using the JSCP Monitor, you can do the following activities:


Monitor JSCP activity. Using the JSCP Monitor, you can display the following
information, updated every one to three seconds:

View threads running on the JSCP. The information includes details on each
thread, including its ID, name, priority, type, and status.

Trace information of any single thread, and read the JSCP settings, such as its
loader port, HTTP server address, and maximum bytecode run in a single slice.

Monitor memory usage (system and GC) for each thread.

Monitor the JSCP usage of the CPU for each thread. The usage information
includes details on the user, system and scheduled components.

Collect performance statistics, e.g., the frequency with which the JVM scheduler
has polled the event-driven subsystems, or the number of times the JSCP has
yielded control to the system.
Control JSCP activity. Using the JSCP Monitor, you can send commands to perform
the following operations:

Suspend, resume, or kill individual Java threads (not including system threads).

Restart the entire JSCP. This releases all the memory to the system and causes
the re-initialization of all the static variables.
© 1997-1999 NSIcom
25
SOFTWARE CO-PROCESSOR
5.2
FOR
J AV A
Start-up and Preliminary Configuration
To start the JSCP Monitor application, run JSCPmtr.exe from a DOS prompt. You will see
the JSCP Monitor window. A typical window is shown in Figure 6.
After the JSCP Monitor starts, configure the communication parameters and the display
options as follows:
1. Open the Options menu and select the Set Address item to open the address entry
box. Type the IP address (or the Hostname) of the host machine for the JSCP in the
box, and then click OK.
2. Select the display refresh mode, using the radio buttons at the bottom left corner of the
window:
Manual
The display is refreshed only after clicking the Refresh button.
Auto
The display is automatically refreshed. The interval between consecutive
refreshes is defined by selecting the Update Speed on the Options
menu: the range is 1 to 3 seconds. The selected refresh interval is
displayed above the thread monitoring table.
After refreshing is enabled, the JSCP Monitor application will display a JSCP is not
responding message in case it does not receive refresh data from the JSCP (this may be
happen if the JSCP is not currently running on the host machine, or if the host running
the JSCP Monitor application cannot communicate with the JSCP host).
5.3
JSCP Monitor Display Elements
A typical JSCP Monitor window is shown in Figure 6.
Figure 6: JSCP Monitor Window
26
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
The main elements of the JSCP Monitor window are:

Menu Bar. Includes three roll-down menus: JSCP, Options, and Help.

Thread Monitoring Table. Displays information on the threads running on the JSCP.

CPU and Memory Usage. Displays information on the CPU and memory usage of the
JSCP, and the total number of threads running.

Function Buttons. Used to access frequently used functions.

Status Bar. Displays progress messages for certain operations.
5.3.1 Menu Bar
The functions of the menus are explained in the following table.
Menu
Function
JSCP
Includes two items:
Properties
Quit
Options
Help
Displays information on the JSCP.
Terminates the JSCP Monitor
Includes the following items:
Set Address
Used to define the IP address of the host
for the JSCP.
JSCP Restart
Restarts the JSCP. You can specify the
main class to be used after restart. If no
main class is specified, the JSCP enters the
monitoring mode.
Update Speed
Set the refresh rate of the JSCP Monitor
Includes the following items:
General Description Provides a description of JSCP operation.
How To
Provides instructions for performing basic
operations.
Monitor Description Describes the JSCP Monitor window fields.
About
© 1997-1999 NSIcom
Provides information about NSIcom
27
SOFTWARE CO-PROCESSOR
FOR
J AV A
5.3.2 Thread Monitoring Table
The thread monitoring table provides information on Java threads, CPU, and memory usage.
Each thread in your currently loaded Java applications appears as a separate line in the thread
monitoring table. To select a thread, click the corresponding row in the table.
The following information is provided for each thread.
Field
Description
ID
Indicates the ID number of the thread, as assigned by the internal
Operating System.
Name
Indicates the thread name
Prio
Indicates the thread priority. The lowest priority is 1, and the highest
priority is 10
CPU
Indicates the thread CPU usage (in milliseconds)
Type
Indicates the thread type:
State
Sys
System thread. These are JSCP threads, i.e., the Monitor
(MTR), Finalizer, or Garbage Collection (GC) threads.
User
User thread (a thread from your Java applications).
Prim
Primordial (main) thread
Indicates the state of the thread.
R
Runnable (the tread is either currently running, or is in
the runnable queue).
S
Suspended.
SM
Suspended by the JSCP Monitor.
WN
Waiting for network. The thread is waiting for an event
from the network.
WM
Waiting for the Monitor. The thread is waiting due to
synchronization with another thread.
WV
Waiting for variable condition. The thread is waiting due
to synchronization with another thread.
* (suffix) Pending suspension
28
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
5.3.3 CPU and Memory Usage
The CPU and memory usage information is provided under thread monitoring table.
Field
Description
GC
Displays garbage collection data: the memory usage in KB, for both Total and
Free memory, and the GC memory
Threads
Indicates the number of threads that are currently running on the JSCP
CPU
Indicates the following CPU usage parameters (listed from left to right):
1. Percentage of time used to process user threads,
2. Percentage of time used to process system threads,
3. Percentage of time of scheduled threads
The background color of the memory usage field changes when memory is low, to represent
the Memory Usage States (Memory Colors). In the event of a memory shortage, the Garbage
Collection thread becomes progressively more aggressive.
Color
Description
Green
Normal memory usage. The GC thread is set to minimum priority. The
GC thread runs only if everything else is idle
Yellow
Memory usage has exceeded the lower limit. The GC thread priority is
set to (normal priority + 1), and runs in the queue with the other threads
Red
Memory usage has exceeded the upper limit (only two pages of memory
left). No new threads will be accepted. The GC thread is set to
maximum priority, and the GC heap is defragmented.
5.3.4 Function Buttons
The function buttons and the Refresh Mode panel are used as shortcuts for basic JSCP
Monitor operations. In addition, the window includes a Close button, which is used to
terminate the JSCP Monitor application.
The group of three buttons located under the thread monitoring table, at the left-hand edge
of the window, are available only when a thread is selected in the thread monitoring table.
Suspend/Resume Each click toggles the thread execution state (alternately suspends
or resumes thread execution).
Kill
Click to kill the currently selected thread.
Detail
Retrieve the trace information of the currently selected thread.
The two buttons located under the thread monitoring table, at the right-hand edge of the
window, are used to display information regarding memory usage:
Memory Usage
Displays information about the memory usage of the JSCP.
JSCP Info
Displays detailed information about the JSCP memory allocation.
The Refresh Mode panel is used to select the display refresh mode (manual or automatic) for
the JSCP Monitor: if the manual refresh mode is selected, then the Refresh button becomes
active, and the JSCP Monitor display is refreshed only when this button is clicked.
© 1997-1999 NSIcom
29
SOFTWARE CO-PROCESSOR
5.4
FOR
J AV A
Using the JSCP Monitor
The JSCP Monitor controls and monitors Java threads running on the JSCP. This section
describes the operations that can be performed using the JSCP Monitor.
5.4.1 Control of Threads
To perform an operation on a specific thread, perform the following steps:
1. Select the desired thread by clicking its row in the thread monitoring table..
2. Click the button that performs the desired operation:

Suspend (and later resume) a thread: click Suspend/Resume.

Kill a thread: click Kill.

Trace a thread: click Detail.
5.4.2 Displaying JSCP Settings
To display information on the JSCP settings in the monitored device, click the JSCP Info
button.
The following information is displayed in the JSCP Info window:
Field
Description
JSCP Loader Port
The port through which the JSCP connects to the CPU
Default HTTP Server
The IP address of the JSCP HTTP server
Thread Bytecode Slice
The maximum number of bytes that the JSCP will run in a single
time slice
5.4.3 JSCP Performance Statistics
You can obtain the following statistics by selecting the JSCP Properties item on the JSCP
menu.
Scheduler Executed
Indicates the number of times the JSCP has polled its entire
list of event-driven subsystems.
Yield to System
Indicates the number of times that the JSCP has yielded
control of the CPU to other devices.
5.4.4 Restarting the JSCP
You can use the JSCP Monitor to restart the JSCP without wasting memory. After restarting,
the JSCP returns all the memory to the system, and re-initializes all the static variables.
To restart the JSCP, take the following steps:
1. Select the JSCP Restart item on the Options menu.
2. Enter the entry point for the Virtual Machine (i.e., the name of the main class).
3. Click the Restart button.
30
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
5.4.5 Entering The Monitor Mode
You can place the JSCP in the Monitor mode: in this mode, nothing runs except the JVM
scheduler, SCHD. The SCHD will run in the idle mode until it gets a thread to run.
To place the JSCP in the Monitor mode, take the following steps:
1. Select the JSCP Restart item on the Options menu.
2. Leave the main class field blank.
3. Click the Restart button.
© 1997-1999 NSIcom
31
SOFTWARE CO-PROCESSOR
FOR
J AV A
NOTES
32
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
6
JSCP UTILITY PROGRAMS
6.1
Scope
FOR
J AV A
NSIcom provides three utility programs that enable the user to embed Java applications. The
scope of these utilities is described in the Embedding Java Applications section.
Each utility program generates C source code or a header file that can then be crosscompiled and linked with JSCP objects and libraries.
The three utilities run only under Windows NT, but generate output suitable for embedding
on any device. The tables generated by the utility programs are made available to the JSCP
through its API’s (see Embedding Classes, Files and Native Links).
6.2
c2ROM
The c2ROM utility provided with the JSCP is used to prepare your compiled Java classes for
integration with the JSCP (within ROM).
The c2ROM utility takes your application classes as input and produces a .h or .c file
containing a table of objects. Each object is the C source representation of the bytecode of a
Java class. The c2ROM modifies the bytecode to enable the JSCP internal class loader to
take advantage of the fact that the classes are “burned into” ROM. This modification saves
30 to 40% of the RAM needed for that class, when the class is loaded at run-time.
The c2ROM command line is:
c2ROM [-help] [-b] [-r] -t var-name -o out-file class-dir
Arguments
-help
Display a concise description of the available command line arguments.
-b
Generate binary output format. This is a special option used for direct
transfer of memory blocks to the device.
-r
Recursively ROMize all the classes in all the sub-directories starting at
the class-dir.
var-name
The C variable name that will hold the ROMized classes. This variable
is designated as a “static” C variable, unless out-file is a .c file.
out-file
The file that will hold the ROMized classes.
class-dir
The directory containing the .class files. All the .class files in the
directory(s) are ROMized.
Application Considerations

The JSCP internal ROM file system of ROMized classes may be extended any number
of times during initialization, by invoking the jsPaddRomClasses() JSCP API for each
var-name.

The names of the ROMized classes are derived from the Java bytecode, not from the file
names of the .class files.
© 1997-1999 NSIcom
33
SOFTWARE CO-PROCESSOR

FOR
J AV A
ROMized classes are automatically made part of the CLASSPATH. Therefore, if you are
using only ROMized classes in your application, you do not need to use the CLASSPATH
variable at all.
For more information, see Embedding Classes, Files and Native Links.
6.3
f2ROM
The f2ROM utility provided with the JSCP complements the services provided by the
c2ROM utility by enabling the user is used to prepare files of any type, other than .class
files, for integration with the JSCP.
The f2ROM may be used to add GIF images, ZIP and/or JAR files, etc. to the internal
ROM file system of the JSCP, for example:

The f2ROM, in conjunction with jsPaddRomFiles(), can be used to add a single file or an
entire directory tree.

The f2ROM, in conjunction with jsPaddRomZIP() can be used to add ZIP or JAR files
containing classes, and will adjust the JSCP CLASSPATH variable accordingly.
The f2ROM command line is:
f2ROM [-help] [-r] -t var-name [-l link-path] [-ext ext] -o out-file dir1 [dir2 ..]
Arguments
-help
Display a concise description of the available command line arguments.
-r
Recursively process files in all the sub-directories starting at the
dir1[dir2].
var-name
The C variable name that will hold the FILEized files. This variable is
designated as a “static” C variable unless out-file is a .c file.
link-path
An optional directory reference prefixing dir1, that will be used when
searching for the FILEized files at run-time.
ext
Restrict the f2ROM to operate only on files with extension .ext.
out-file
The file that will hold the FILEized files.
dir1
The directory containing the files that will be FILEized.
Application Considerations

Java applications access the internal ROM file system using the standard Java API’s
included in the java.io and sun.io packages.

The JSCP internal ROM file system may be extended any number of times during
initialization.

At run-time, the current local directory is assumed to be the one from which you have
executed the f2ROM, or one directory above the link-path, if link-path was specified.
Note that you can use multiple FILEized directories: the JSCP will treat each one as its
current local directory.

The FILEized directories are not checked for duplicate file names. Searching in
FILEized directories is performed in reverse order of jsPaddRomFiles() calls.
For more information, see Embedding Classes, Files and Native Links.
34
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
6.4
FOR
J AV A
J2Clinks
The J2Clinks utility program provided with the JSCP is used to prepare user-written native
modules for integration within the JSCP. This utility is derived from Sun’s utility program
JAVAH.
The input required by the J2Clinks utility is .c files. The J2Clinks utility can be used in a make
utility description file, which can pass a list of .class files to it.
The output generated by the J2Clinks utility is determined by the command line parameters.
The J2Clinks utility can be instructed to generate the following types of files:
file that represents the contents of a .class file.

.h

‘.tmpl

.stb
file, to serve as a template for the native .c module.
file, a link table used by the JSCP at run-time.
The two command line options are explained below:
1. The J2Clinks command line used to create .h files representing .class files is as follows:
J2Clinks [-jni] [-classpath classpath] -d out-dir pkg1.pkg2.class1
[pkg1.pkg2.class2 ..]
2. The J2Clinks command line used to create a link table of native methods is as follows:
J2Clinks [-jni] [-classpath classpath] -lt=var-name -o out-file pkg1.pkg2.class1
[pkg1.pkg2.class2 ..]
Arguments
-jni
Generate output in Java 1.1 JNI format. If this argument is
omitted, the format of the files generated by J2Clinks is the old
NMI format.
classpath
Specifies the CLASSPATH variable used by J2Clinks to satisfy class
references.
out-dir
The directory to which all the .h files are written.
The out-dir option is available only with command line format 1.
var-name
The C variable name that will hold the link table of all the native
methods defined in all the .class files specified in the command
line. This variable is designated as a “static” C variable unless outfile is a .c file.
The var-name option is available only with command line format 2.
out-file
The file that will hold the link table.
The out-file option is available only with command line format 2.
pkg1.pkg2.class1
List of fully qualified class names.
Application Considerations

The CLASSPATH argument is required only to satisfy class references. The J2Clinks
utility will not use it to search for the classes specified in the command parameters.

The var-name and out-file arguments are used when generating a link table. J2Clinks
© 1997-1999 NSIcom
35
SOFTWARE CO-PROCESSOR
FOR
J AV A
generates one link table per run, that includes all the native methods defined in all the
.class files it processes. The actual file name will be out-file.stb.

Link tables should be introduced to the JSCP using jsPaddRomLinks() called from
with a pointer to var-name as the argument.
jsPtargetStart()

36
The out-dir is used when generating .h files representing classes. One .h file is generated
for each .class file. The names of the .h files are derived from the names of the
corresponding classes in accordance with the following rule: pkg1_pkg2_class1.h
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
7
INSTALLING THE JSCP
7.1
Scope
FOR
J AV A
This Chapter provides information on the JSCP kit contents, and presents installation
procedures for the kit.
7.2
JSCP Components
The JSCP kit includes the following items:

JSCP Build and Run-time Environment

JSCP Monitor

JSCP Utilities

JSCP Documentation.
7.2.1 JSCP Build and Run-time Environment
The JSCP kit contains files that enable you to customize the JSCP to the specific needs of
your platform and project. The following files are provided for this purpose:

The makefile in the \1-luna\build\<target> directory. The <target> parameter is platformspecific, and therefore its name can be found in the README file of the kit.

The libjscp library and/or object files.

Configuration and initialization files in source form, as described below:
The class configuration files are located in \1-luna\1jscp\1config:
The conf_cls.c contains the JSCP optional classes and may be customized.
The conf_awt.c contains the configuration code for the AWT classes and fonts, and
AWT-related classes.
The JSCP configuration file. The actual file name and location are target-dependent.
For example, the JSCP configuration file for the pSOS/PPC target is named
pss_main.c and is located in the \1-luna\1jscp\target\psos\ppc directory.
The JSCP initialization file. This is a task initialization file, specific to your operating
system. It contains instructions to initialize the JSCP as a single task. It must be
merged with the file that initializes your other tasks. For more information, see
the INTEGRATING THE JSCP WITH THE RTOS Chapter.
For example, the initialization file for the pSOS/PPC target is named root.c and is
located in the \1-luna\1jscp\target\psos\ppc directory.
Application initialization files. Use these files to add native methods and classes to the
ROM. Application example files are provided in the \1-luna\1jscp\rom_app
directory.
A README file that is platform-specific., and contains additional information for
programmers.
© 1997-1999 NSIcom
37
SOFTWARE CO-PROCESSOR
FOR
J AV A
7.2.2 JSCP Monitor
The JSCP Monitor is an application written in Java that allows you to monitor the JSCP
activities remotely, through a network connection. Refer to the JSCP Monitor Chapter.
7.2.3 JSCP Utilities
The JSCP utilities are add-on application development tools that are used to integrate Java
bytecode, files, and native methods into the JSCP.
The utilities provided in the kit include the c2ROM, f2ROM, and J2Clinks. A detailed
description of these utilities is given in the JSCP Utility Programs Chapter.
7.2.4 JSCP Documentation
The JSCP Documentation contains the JSCP Architecture and User’s Guide – this
document.
7.3
System Requirements
The development environment in which the JSCP kit is used must meet the following
minimum requirements:
Windows NT workstation for developing and running the JSCP utilities.
Set of Java development tools (e.g., the set contained in the Sun JDK, Microsoft Visual J++,
or Symantec Visual Café). The set must include a Java compiler.
C cross-platform compiler.
7.4
Software Installation
The JSCP kit is supplied as a ZIP file. To get and install the JSCP build environment, take
the following steps:
1. Download the ZIP file for your target platform from the FTP site of NSIcom.
(ftp.nsi.co.il). A user name and password will be provided to you by an NSIcom
representative.
2. Unzip the file. If the target platform is NT, you will need to run setup to install the kit.
Every kit includes a README file. Follow the instructions in this file to customize the kit for
your specific environment.
38
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
8
INTEGRATING THE JSCP WITH THE RTOS
8.1
General
FOR
J AV A
The JSCP runs Java applications within your embedded system environment. All the classes
and native methods are linked together with the JSCP to form a single image load.
The entire image appears as a single task to the RTOS, because the JSCP performs all the
internal resource management functions. Figure 7 shows the flow control from the RTOS to
the JSCP, and the related configuration files.
root.c
……
create and start JSCP task
……
JSCP
default config
JVM init
blue threads init
RUN
xxx_conf.c
jsPtargetConfig()
jsPtargetJprop()
The Application
jsPtargetMainClass()
jsPtargetStart()
jsPtargetInit()
jsPtargetStop()
Figure 7: JSCP-RTOS Control Flow
© 1997-1999 NSIcom
39
SOFTWARE CO-PROCESSOR
8.2
FOR
J AV A
Creating an OS Task for the JSCP
To integrate the JSCP code within your operating system, you should create an Operating
System task for the JSCP, using the procedures specified by your RTOS.
After creating the required OS task, you can initialize it just as you would initialize any other
task on your RTOS. The entry point of the JSCP id defined as follow:
extern the JSCP(int argc, char *argv[]);
For example, if you are running the JSCP on pSOS, you might add the following calls to
your root function in root.c:
void root(void)
{
#define STACK_SIZE 16*1024
ULONG
tid = 0;
unsigned long
targs[2];
int
argc = 0;
char
*argv[1];
argv[0] = NULL;
targs[0] = (unsigned long)argc;
targs[1] = (unsigned long)argv;
t_create("the JSCP", 100, 4096, STACK_SIZE, 0, &tid);
t_start(tid, T_USER | T_PREEMPT | T_TSLICE, the JSCP, targs);
/* Now suspend the 'ROOT' task. */
t_suspend(0L);
}
On the Nucleus/PLUS, you might add the following calls to your Application_Initialize
function:
#define STACK_SIZE 16*1024
NU_TASK
the JSCP_task;
/* Create memory for the JSCP stack. */
status = NU_Allocate_Memory (&System_Memory, &pointer,
STACK_SIZE, NU_NO_SUSPEND);
/* Create the JSCP task. */
status = NU_Create_Task(&JVM_task, "JVM-tsk", the JSCP, 0, 0,
pointer, STACK_SIZE, the JSCP_PRIORITY,
0, NU_PREEMPT, NU_START);
40
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
8.3
FOR
J AV A
JSCP Configuration
The JSCP is configured in two distinct but related ways:

In the target make file, specify the optional objects to include or exclude in the final
image.
In some cases, you must use a stub module if you do not need, or if your device does
not support, a particular subsystem. For instance, if your device supports file I/O, you
should use js_fio and xxx_fio, where xxx designates your RTOS. If you do not have file
I/O on the target device, use js_fio_, which contains the stub file I/O functions.

The JSCP kit provides several C files in source form. These files contain the
configuration functions being called by the JSCP at initialization time. Use these
functions to set the configuration parameters, initialize the optional subsystems, and, if
necessary to, add your own native code and EDS subsystems.
See the Configuration and Initialization section for more information.
© 1997-1999 NSIcom
41
SOFTWARE CO-PROCESSOR
FOR
J AV A
NOTES
42
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
9
JSCP API
9.1
Using the JSCP API’s
FOR
J AV A
To use any of the JSCP API’s, it is necessary to include only one header file, residing in the
directory 1include.
Use #include “jscp_api.h” in each of your C modules.
9.2
Configuration and Initialization Functions
All the functions starting with jsPtarget reside in one of the configuration files provided by
NSIcom in source form. All these functions are called by the JSCP at initialization. The user
can modify the contents of the functions in the configuration files, to reflect the capabilities
of the target embedded device and the application requirements.
The initialization functions are called by the JSCP in the following order:
1. jsPtargetStart() and jsPtargetInit() are called once for each initialization of the virtual
machine (they are called after each remote reset).
2. jsPtargetConfig(), jsPtargetJprop() and jsPtargetMainClass() are called only once, as part of
the “cold start” initialization. These functions are designed to provide the options
available in the command line of a desktop Java Virtual Machine.
On platforms which support the JSCP command line (Windows NT, Windows CE) the
command line parameters take precedence over parameters set in these functions.
3. jsPmallocSpl() is used to allocate memory that will live across the JSCP restarts, i.e., will
not be cleared when the JSCP is restarted.
9.2.1 jsPtargetConfig
int jsPtargetConfig(jsTconfig *conf)
Description
This is the first call made by the JSCP after its task is initialized and any command
line parameters (if present) are evaluated. At this point, the JSCP memory
management subsystem is already initialized.
Arguments
conf
Pointer to jsTconfig structure defined in 1include/jscp_prp.h. This structure
contains fields whose values govern the JSCP scheduler behavior, set
memory limits, etc. All the fields are assigned default values prior to
calling this function.
The jsTconfig fields and their default values are listed in the following
table.
© 1997-1999 NSIcom
43
SOFTWARE CO-PROCESSOR
FOR
J AV A
Name
Type
Default
Comment
title
Char *
“\n”
String to be displayed by the JSCP on the
standard output at initialization. Maximum
string length is TBD.
mem_limit
Long
2 MB
Sets the maximum memory that may be
used at run time.
0
For more information, see Memory Usage
States (Memory Colors).
0.5.. MB
mem_green
Long
mem_yellow
0 is replaced by the JSCP with a value
calculated in accordance with the mem_limit.
mem_red
ticks_per_sec
Long
None
Mandatory parameter, specifies the
software clock rate (the clock used by the
function that returns system ticks). The
software clock rate is given in ticks per
second (TPS). Usually, you will use a
system constant (e.g., KC_TICKS2SEC in
pSOS.).
The JSCP scheduler uses this value in all its
time calculations.
ticks_slice
Long
TPS/25
Number of system ticks a Java thread runs
before the JSCP scheduler preempts it.
This value also determines the scheduling
rate.
idle_sleep_
ticks
Long
TPS
Value (in system ticks) used by the JSCP
scheduler in calling the system “sleep”
function when the virtual machine is idle.
do_yield
Short
port dependent
If set, the JSCP scheduler yields the CPU to
the system each time before it schedules a
Java thread (mandatory parameter for
non-preemptive RTOS’s).
port dependent
If set, then this port has AWT support.
0 OR 1
awt_opt
Short
0 OR 1
max_sockets
Short
64
Maximum number of concurrent opened
sockets allowed (should be synchronized
with the BSP values used by the system).
mtr_port
Short
9999
UDP server port number of the Monitor
thread.
do_asyncGC
Short
1
If not set, the asynchronous Garbage
Collection thread is initialized in the
suspended state.
jsCverify_remote
One of the following classes:
jsCverify_none, jsCverify_remote, or
0 OR 1
verify_classes
jsCverify_all
44
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
Name
Type
Default
Comment
cls_dbg_info
Short
0
If set, the debug information of the classes
and the line number tables are loaded at
run time.
1
Value used for debugging Java applications.
Can be retrieved by System.getProperty
0 OR 1
jscp_dbg
Short
0 .. 10
("the JSCP.jscp_dbg")
test_verbose
Value used for debugging Java applications.
Can be retrieved by System.getProperty ("the
Short
0 .. 10
JSCP. testVerbose").
loader_port
Short
7777
The JSCP network class loader server port.
local_host_name
Char *
"Unknown"
The host name of the machine that serves
as a host for the JSCP.
local_host_ip
Char *
"127.0.0.1"
The IP address of the machine that serves
as a host for the JSCP.
http_server_ip
Char *
none
If the JSCP network class loader is to be
used, this parameter must specify your
HTTP server’s IP address.
verbose
Char
0
If set, runtime information about class
loading and resolving will be written to the
standard output.
0
If set to a non-negative value, the
asynchronous GC thread will print
information about its execution.
0
If set, the asynchronous GC thread will
print object trace information.
0 .. 7
verbosegc
Char
-1 .. 7
tracegc
Char
0 OR 1
Return Value
Return 0 if successful, or -1 to prevent the JSCP from continuing the initialization.
9.2.2 jsPtargetJprop
int jsPtargetJprop ( jsTjava_prop *prop)
Description
This is the second call made by the JSCP, as part of the cold-start initialization phase.
Arguments
prop
Points to a structure of type jsTjava_prop. The JSCP puts the values from
prop in the Java property list, therefore they can be retrieved by your Java
application using the System.getProperty() Java method.
In general, you can use the default values for all the fields in prop, except
the last one: D_param. The D_param field accepts a string value of the
form: “Dkey1=val1 -Dkey2=val2 …” It is used in place of the generic VM
command line, for example: java -Dkey1=val1 -Dke2=val2 …
© 1997-1999 NSIcom
45
SOFTWARE CO-PROCESSOR
FOR
J AV A
Return Value
Return 0 if successful, or -1 to prevent the JSCP to continuing the initialization.
9.2.3 jsPtargetMainClass
char *jsPtargetMainClass(int *argc, char **argv[], char *dParams)
Description
This function is used to specify the name of the “main application class”, instead of
the prompt displayed in the command line available on desktop computer.
If the main application class is given in the command line (where available), all the
values set in this function are ignored.
Arguments
argc
the number of values in argv (return value)
argv
array of C strings comprising the parameters that will be passed to the Java
application (return value)
dParams a string of the form: -Dkey1=val1 -Dkey2=val2 ..
Return Value
C string specifying the name of the Java class containing the “main” method (main
class).
Remarks

If the command line specifies the main application class, all the parameters
returned by this method are ignored.

If the command line does not specify the Java main class, dParam values are
used in addition to those specified in D_params of jsPtargetJprop().

If the return value is 0 (no main class is specified) and the command line does
not specify the main class either, the JSCP enters the Monitor mode.
9.2.4 jsPtargetStart
int jsPtargetStart(int restart_count)
Description
is called after all the JSCP mandatory subsystems, including Blue
Threads, are initialized, but before the virtual machine itself is initialized and before
the JSCP scheduler is active. At this point, you should not call any of the
jsPtargetStart()
execute_java_…
is called each time the JSCP is restarted. It is designed to give you a
starting point to add your own ROMized classes, FILEized ZIP and JAR files, or
J2Clinks tables.
isPtargetStart()
You should also initialize any custom-made EDS at this point, and then call the
jsPstartXXX functions to initialize the JSCP optional subsystems.
Arguments
restart_count
46
Restarts the counting from 0.
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
Return Values
Return 0 if successful, or -1 to prevent the JSCP from continuing the initialization.
9.2.5 jsPtargetInit
int jsPtargetInit(void)
Description
is called after all the subsystems are initialized, the JSCP scheduler is
active and the virtual machine is ready to execute Java bytecode. The function is
called just before the main() method of the main application class is executed.
jsPtargetInit()
Currently, only the AWT (when present) should be initialized by calling
jsPinitAWT() from within this function.
Arguments
None.
Return Values
Return 0 if successful, or -1 to prevent the JSCP from continuing the initialization.
9.2.6 jsPtargetStop
int jsPtargetStop(int stop_count)
Description
jsPtargetStop()
jsPtargetStart()
is called just before the virtual machine is going down. For every
call, there will be a call to the jsPtargetStop().
This function is provided to allow the user to perform the clean-up of resources,
and other related tasks.
Arguments
stop_count
Restarts the counting from 0.
Return Values
Returns 0.
9.2.7 jsPsetDateTime
void jsPsetDateTime(unsigned long curret_time)
Description
The JSCP maintains a 64-bit variable containing the time elapsed since 1/1/1970,
in milliseconds. Use this function to initialize this variable to the current date and
time. The function should be called from the jsPtargetStart() routine.
Arguments
current_time
Time elapsed in seconds since 1/1/1970. Usually, this value is
acquired from the system.
Return Values
None.
© 1997-1999 NSIcom
47
SOFTWARE CO-PROCESSOR
FOR
J AV A
9.2.8 gcPsetOptions
unsigned long gcPsetOptions(int action, unsigned long options)
Description
Use this function to set, clear, or add optional actions to be performed by the
Garbage Collection algorithm.
Arguments
action
One of the following symbolic constants:
gcCsetOptions
Set the new options specified in the options.
GcCclrOptions
Clear the options specified in options.
gcCaddOptions
OR the options specified in options with the current
options.
options An ORed value of the following symbolic constants:
gcCdoBailOut
Instruct the GC thread to abort processing if a thread
with higher priority becomes ready for execution.
gcCdoClassGC
Instruct the GC algorithm to free unused classes and
reclaim their memory.
gcCdoCompact
Instruct the GC algorithm to compact fragmented object
pages.
Return Values
This function returns the ORed value of the previous settings.
48
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
9.3
FOR
J AV A
Embedding Classes, Files, and Native Links
Functions in this section are used to add classes, files, or link tables of native methods to
your embedded Java environment.
The first argument of each of these functions is a pointer to a table generated by one of the
utility programs: c2ROM, f2ROM or J2Clinks.
You should invoke the functions presented in this section from within the jsPtargetStart() of
your application. If you have specified a .c file for the -o parameter of the utility command
line, remember to add the matching object file to your project or make file.
Whenever a Java class is referenced, the JSCP conducts the class search in the following
order:
1. The non-optional ROMized core classes (java.lang, java.io, etc…)
2. The ROMized classes added by jsPaddRomClasses()
3. CLASSPATH search in the specified order (see also jsPaddRomZIP()).
9.3.1 jsPaddRomClasses
void jsPaddRomClasses(jsTrom_pkg *pkg)
Description
Expand the JSCP internal ROM file system with a C variable that contains a table
of class file images.
Only .class files should be used with this function, because the tables constructed
by jsPaddRomClasses() are searched only by the class loader.
This function may be repeatedly invoked to add all the necessary classes. Please
note that tables are searched in the reverse order of jsPaddRomClasses() calls.
Arguments
pkg
A pointer to the C variable specified in the -t parameter of the c2ROM
utility program.
Return Values
None.
9.3.2 jsPaddRomFiles
void jsPaddRomFiles(jsTrom_pkg *dirTree)
Description
Expand the JSCP internal ROM file system with a C variable that contains the
image of a file, or an entire directory tree. This function may be repeatedly invoked
to add all the necessary files and directories.
Arguments
dirTree A pointer to the C variable specified in the -t parameter of the f2ROM
utility program.
© 1997-1999 NSIcom
49
SOFTWARE CO-PROCESSOR
FOR
J AV A
Return Values
None.
9.3.3 jsPaddRomZIP
void jsPaddRomZIP(jsTrom_pkg *zFile, int classPathOption,
char *classPath)
Description
Expand the JSCP internal ROM file system with a C variable that contains the
byte stream of a single ZIP or JAR file. This function may be repeatedly invoked
to add all the necessary ZIP or JAR files. The added files may be concatenated to
the CLASSPATH variable of the JSCP.
Arguments
zFile
A pointer to the C variable specified in the -t parameter of the f2ROM
utility program.
classPathOption One of the following constants:
jsCnotClassPath
The file will not be part of the CLASSPATH.
jsCheadClassPath Add this file at the beginning of the CLASSPATH.
jsCtailClassPath
Add this file at the end of the CLASSPATH.
Return Values
None.
9.3.4 jsPaddOptionalClasses
int jsPaddOptionalClasses(void)
Description
You may call the jsPaddOptionalClasses() and jsPaddOptionalClasses2() from
jsPtargetStart(), to add optional packages taken from the classes.zip.
jsPaddOptionalClasses() resides in the 1config/conf_cls.c source file.
jsPaddOptionalClasses2() resides in the 1config/conf_awt.c source file; it adds classes
related to AWT.
The core classes comprising the virtual machine are always embedded in the JSCP
image. See the sources conf_cls.c and conf_awt.c for details on the classes that are
added to the image by these functions. You can change these sources to reflect
your application requirements.
These functions use jsPaddRomClasses() and jsPaddRomZIP().
Arguments
None.
Return Values
Always returns 0.
50
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
9.3.5 jsPaddRomLinks
void jsPaddRomLinks(jsTrom_links *links)
Description
Introduces one link table generated by the J2Clinks utility program to the JSCP.
This function may be repeatedly invoked to add all the necessary link tables. When
a native method is invoked for the first time, tables introduced by this function are
searched in reverse order of introduction.
Arguments
links
A pointer to the C variable specified in the -lt= parameter of J2Clinks.
Return Values
None.
© 1997-1999 NSIcom
51
SOFTWARE CO-PROCESSOR
9.4
FOR
J AV A
Starting Optional Subsystems
This section provides functions that can be used to configure your Java virtual machine
according to the application requirements, and the capabilities of the device on which the
virtual machine runs. For example, you can use functions provided in this section to avoid
having all the AWT classes and code burned in the device’s ROM, if the device does not
have an output display.
If you do not require any of the functions appearing in this section, simply avoid calling the
relevant start and init functions, and omit the object modules from your project (make file).
The inclusion of classes supporting these subsystems is determined in one of the
configuration files: conf_cls.c and conf_awt.c.
The start functions add support for native functions. You should call all the start functions
from the application’s jsPtargetStart() and pass them the start_count parameter.
The init functions initialize the corresponding native subsystem – you should call the init
functions from the application’s jsPtargetInit().
9.4.1 jsPstartReflect
int jsPstartReflect(int start_count)
Java API provided
java.lang.reflect
Object modules:
1jscp/e_sys/reflect_
1jscp/optional/lang/reflect
Remarks
is used by most applications, therefore it is recommended
that you include it with your virtual machine.
Reflect
9.4.2 jsPstartBigNum
int jsPstartBigNum(int start_count)
Java API provided:
java.math
Object modules:
Files in 1jscp/optional/big_nam (as specified in the make file)
Remarks
This function provides arithmetic support for very large numbers,
i.e., numbers that require more than 64 bits. Most applications do
not need java.math support.
9.4.3 jsPstartNet
int jsPstartNet(int start_count)
Java API provided:
java.net
Object modules:
1jscp/net/socket0
1jscp/net/socket1
1jscp/net/jn
1jscp/net/xxx/jnb (xxx =
Remarks
network implementation)
This function adds java.net native functions and starts the network
EDS. Use this function only if you have network support on your
device.
Also use jsPstopNet() in your application’s jsPtargetStop().
52
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
9.4.4 JsPstartSUN_NET
int jsPstartSUN_NET(int start_count)
Java API provided:
sun.net
Object modules:
1jscp/net/sun_net0
Remarks
This function only adds the native functions needed to support
sun.net classes. The function requires java.net and jsPstartNet().
9.4.5 jsPstartMTR
int jsPstartMTR(int start_count)
Java API provided:
None.
Object modules:
1jscp/blue/bt_mtr
Remarks
This function starts and initializes the Monitor thread, which is
part of the JSCP kernel. The function requires jsPstartNet(),
because it uses the UDP protocol to communicate with the JSCP
Monitor application.
9.4.6 jsPstartFIO
int jsPstartFIO(int start_count)
Java API provided:
java.io
Object modules:
1jscp/e_sys/file_io_
Remarks
This function only adds the native functions needed to support the
java.io classes. The actual secondary file system support is provided
by 1jscp/jscp/js_fio.
If no secondary file system is available, you should use the
1jscp/jscp/js_fio_ stub module. Remember that the internal ROM
file system is always available, therefore it is recommended that you
do include jsPstartFIO() in your start functions.
9.4.7 jsPstartAWT
int jsPstartAWT(int start_count, int Xpix, int Ypix)
Java API provided:
java.awt
Object modules:
Many objects in 1awt directory.
Remarks
The AWT classes and fonts are configured in 1config/conf_awt.c.
This function adds native function interfaces and code, and starts
the AWT EDS.
jsPinitAWT() must
be called in your application’s jsPtargetInit().
and Ypix represent the size of your screen, in pixels, however
they are ignored on some devices.
Xpix
© 1997-1999 NSIcom
53
SOFTWARE CO-PROCESSOR
9.5
FOR
J AV A
Miscellaneous API
9.5.1 jsPmallocSpl
void *jsPmallocSpl(unsigned long size)
Description
Allocates memory in a special page that will not be freed when the virtual machine
is reset. Use this function in jsPtargetConfig() to allocate memory that will live
across VM re-initializations.
Arguments
size
number of bytes to allocate.
Return Values
A pointer to the allocated memory, or 0 if the allocation fails.
9.5.2 jsPfreeSpl
int jsPfreeSpl(void *ptr)
Description
Free the memory allocated by jsPmallocSpl().
Arguments
ptr
The pointer returned by jsPmallocSpl().
Return Values
Non-zero if ptr is not found in the special pages, or 0 if it was found and freed.
9.5.3 btPsetPowerSave
int
btPsetPowerSave(int idle_sec, int (*callback)(int idle_for))
Description
Use this function if your device can to run in the power-save mode. The JSCP
kernel will invoke your call-back function when it detects that the virtual machine
is idle.
This function should be called by the application’s jsPtargetStart(). If no call is
made to btPsetPowerSave(), then the kernel uses the system sleep() function to
relinquish the CPU for a while when it is idle.
Arguments
idle_sec
Idle threshold in seconds. callback is invoked only after the virtual
machine is idle for idle_sec seconds.
callback The native method you provide to implement the power-save mode.
idle_for
54
The parameter passed to callback, which is the number of system clock
ticks during which the virtual machine will be idle. The callback should
block for the specified period, and return control to the JSCP only after
that time has elapsed or some external event (such as a keyboard hit) has
occurred, whichever comes first.
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
If the JSCP does not have any thread in the time-out state, the idle_for
value is zero. In this case callback should block until an external event has
occurred.
Return Values
Always returns 0.
9.5.4 jsPstdOut
int jsPstdOut(char *buff, int count)
Description
Writes data to the standard output stream. This function is used mainly for
debugging.
Arguments
buff
Data to be written.
count
Number of bytes in buff. If count > 0, then buff must be terminated by a
NULL character: all the bytes up to the NULL character will then be
written.
Return Values
Number of character actually written.
9.5.5 jsPspit
void jsPspit(int level, const char *fmt, ...)
Description
This function may be used to print formatted output to the standard output
stream. In the future, it will be used to write data to log files, or to redirect output
to the JSCP Monitor application.
Arguments
level
Currently ignored.
fmt
Format control string same as in the C run-time library function printf().
Return Values
None.
© 1997-1999 NSIcom
55
SOFTWARE CO-PROCESSOR
9.6
FOR
J AV A
EDS API
An Event Driven Subsystem is created and initialized by calling btPedsNew(). The
btPedsNew() function returns a handle representing the new EDS. This handle should be
saved and used as the first parameter on all the other API calls concerning the same EDS.
Each subsystem has its own, unique handle. The call to the btPedsNew() is usually made at
jsPtargetStart() time, but the EDS will be active only after the JSCP scheduler is activated (at
jsPtargetInit() time).
Each EDS has its own set of call-back functions. The call-back functions are user-defined
functions used by the JSCP scheduler to perform EDS-related actions. Call-back functions
are executed in the context of the JSCP scheduler, and therefore should be fast and simple:
in particular, the call-back functions should not make recursive or system blocking calls.
In addition, call-back functions may not call the other EDS API’s: in particular, a call-back
function should never call btPedsWait().
9.6.1 EDS Call-back Functions
Call-back functions are invoked by the JSCP scheduler at the intervals specified by the user
in the ticks_slice field of the configuration structure (see jsPtargetConfig()). However, a longer
interval is specified in the API introducing the call-back.
The complete list of call-back functions is given below. Note that eds_get_event() is the only
mandatory call-back function; all the other functions are optional.
int eds_poll(unsigned long current_tick)
eds_poll()
call-back is used by the JSCP scheduler to poll the EDS for events.
If no poll call-back function is specified, the JSCP scheduler assumes that there are
ready events and it calls the eds_get_event() call-back repeatedly for each thread in
the wait queue of the particular EDS.
eds_poll()
available.
should return either the number of ready events, or zero if no event is
The parameter passed to eds_poll() is the current time in system ticks; this value
may be used to compute event time-outs.

void *eds_get_event(long tid, int obj_id, int event_id)
call-back is used by the JSCP scheduler to retrieve a single event
from the EDS. This is the only mandatory call-back function.
eds_get_event()
The parameters passed to eds_get_event() identify a specific event, and the thread
awaiting that event.
The actual values of the parameters passed are the values set by btPedsWait() when
it was called to notified the JSCP scheduler of an expected event.
should return either a pointer to the EDS private data describing the
requested event (if such an event is ready), or zero if the requested event is not
available. The JSCP scheduler transfers this pointer to the thread awaiting the event.
eds_get_event()
Note that the internal data structure of the EDS event is unknown to the JSCP
scheduler, and therefore the EDS programmer is free to design event structures in
accordance with his or her needs. Moreover, the programmer may ignore some or
all of the parameters passed to eds_get_event().
56
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
int eds_flush(long tid, int param)
eds_flush() call-back is
and eds_get_event().
invoked by the JSCP scheduler before it invokes eds_poll()
The parameter values passed to eds_flush() by the JSCP scheduler are (-1, 0).
should flush any buffers; the return value is zero if no flush was done.
A non-zero value indicates that buffers were flushed.
eds_flush()
int eds_1abort(long tid, int obj_id, int event_id, int why, char
*detail)
eds_1abort()
exiting.
call-back is invoked only when a thread with a pending EDS request is
The parameters passed to eds_1abort() identify the pending request in the way
described for eds_get_event(), together with an error code and a detail message, if
available.
The order of call-back invocation in each iteration of the JSCP scheduler is as follows:
1. A single invocation of eds_flush() for each EDS. This however is made only if a flush
call-back exists for the particular EDS, and the flush interval time, as set by
btPedsFlushCallBack(), has elapsed.
2. A single invocation of eds_poll() for each EDS. This however is made only if a poll
call-back exists for the particular EDS, and the poll interval time, as set by
btPedsPollCallBack(), has elapsed.
3. For each EDS: If the poll call-back does not exist, or if it returned a non-zero value, the
JSCP scheduler invokes eds_get_event() for each thread in the EDS wait queue. A thread
enters the EDS wait queue by calling btPedsWait().
9.6.2 btPedsNew
void *btPedsNew(char *name,
void *(*eds_get_event) (long tid, int obj_id, int
event_id))
Description
This function establishes a new EDS. The opaque pointer returned by the
function, is the handle to the EDS just created. This handle must be used in all the
other API calls concerning the same EDS.
Arguments
Name
A string terminated in a NULL character that specifies the name of
the new EDS. The JSCP Monitor application uses only the first 7
characters when reporting the state of Java threads.
eds_get_event
A pointer to the user-provided call-back function that is used to
retrieve a single event from this EDS.
Return Value
Handle to the EDS just created, or zero if the function failed.
© 1997-1999 NSIcom
57
SOFTWARE CO-PROCESSOR
FOR
J AV A
9.6.3 btPedsDel
void btPedsDel(void *edsp)
Description
This function unlinks a single EDS handle from the EDS list, and deletes the EDS
handle. However, the function does not perform any clean-up.
After this function is executed, all the other API’s and call-back functions
concerning this EDS are no longer available. Therefore, any EDS call using a
deleted handle will probably result in a program fault.
Arguments
edsp
The EDS handle returned by btPedsNew().
Return Value
None.
9.6.4 btPedsOptions
int btPedsOptions(void *edsp, int eds_priority, int idle_fade,
unsigned long flags)
Description
This function is used to change the default attributes of an EDS.
Arguments
edsp
The EDS handle returned by btPedsNew().
eds_priority
An integer value in the range 0 to 10. The value is used to boost the
priority of a thread, after it had received an event from this EDS.
Idle_fade
An integer value used to determine when the EDS is idle. An EDS is
considered idle if no events are received for at least 1/idle_fade
second. For instant, if the programmer had set the idle_fade value of
the network EDS to 10, then if no packets are sent or received for
more than 1/10th of a second, the network EDS is considered idle.
The EDS idle status is used only when the JSCP is idle. It is used by
the JSCP scheduler in its polling loop. The power-save mode will be
activated only after all the EDS’s are idle.
flags
An ORed value of the following symbolic constants:
btCyieldAfterFlush
Instructs the JSCP scheduler to yield the CPU after it
has called the flush call-back, and the flush call-back
returned a non-zero value.
This flag should be used when an auxiliary system
task must be used to complete the flush action and
the RTOS is in the non-preemptive mode, or when
immediate system reaction is desired.
btCpollAlways
Instructs the JSCP scheduler to poll this EDS even
when there are no pending requests.
By default, the JSCP scheduler polls an EDS only when
58
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
FOR
J AV A
a request is pending on the EDS wait queue (a request
is posted by a call to the btPedsWait()). This flag is
effective only if you provide an eds_poll call-back.
Return Value
-1 when edsp represents an invalid EDS, otherwise the return value is 0.
9.6.5 btPedsPollCallBack
int btPedsPollCallBack(void *edsp, int poll_rate,
int (*eds_poll) (unsigned long current_tick))
Description
This function sets the EDS poll call-back function.
Arguments
edsp
The EDS handle returned by btPedsNew().
poll_rate
An integer value that specifies the polling rate. For example, the value
poll_rate = 10 instructs the JSCP scheduler to invoke the poll call-back
function every 1/10th of a second. However, the invocation may be
delayed until the next scheduler cycle. The zero value instructs the
JSCP scheduler to use the global scheduling value.
eds_poll
A pointer to the user-provided call-back function used by the JSCP
scheduler to poll the EDS for events.
Return Value
-1 when edsp represents an invalid EDS; otherwise the return value is 0.
9.6.6 btPedsFlushCallBack
int btPedsFlushCallBack(void *edsp, int flush_rate, int
(*eds_flush)(long tid, int param))
Description
This function sets the EDS’s flush call-back function.
Arguments
edsp
The EDS handle returned by btPedsNew().
flush_rate
An integer value that specifies the flushing rate. For example, the
value flush_rate = 10 instructs the JSCP scheduler to invoke the flush
call-back function every 1/10th of a second. However, the invocation
may be delayed until the next scheduler cycle. The zero value
instructs the JSCP scheduler to use the global scheduling value.
eds_flush
A pointer to the user-provided call-back function used by the JSCP
scheduler to flush the EDS buffers.
Return Value
-1 when edsp represents an invalid EDS; otherwise the return value is 0.
© 1997-1999 NSIcom
59
SOFTWARE CO-PROCESSOR
FOR
J AV A
9.6.7 btPedsAbortCallBack
int btPedsAbortCallBack( void *edsp, int (*eds_1abort)(
long tid, int obj_id, int event_id, int why, char
*detail))
Description
This function sets the EDS abort call-back function. The abort call-back is invoked
by the JSCP scheduler when a thread with a pending EDS request is exiting.
Arguments
edsp
The EDS handle returned by btPedsNew().
eds_1abort
A pointer to the user provided call-back function used by the JSCP to
abort a single request.
Return Value
-1 when edsp represents an invalid EDS; otherwise the return value is 0.
9.6.8 btPedsWait
void *btPedsWait(void *edsp, int obj_id, int event)
Description
notifies the JSCP scheduler of an anticipated event and blocks the
calling thread until the event is ready. The function may be invoked only from the
front-end of an EDS.
btPedsWait()
The parameters passed to the JSCP scheduler identify the particular EDS and the
event the calling function is expecting. The event identifiers will be used by the
JSCP scheduler when it invokes eds_get_event() and eds_1abort().
should be invoked immediately after the EDS front end has
registered the requested event with the EDS back-end.
btPedsWait()
Arguments
edsp
The EDS handle returned by btPedsNew().
obj_id
An integer value identifying an object id.
event
An integer value identifying the event expected.
Return Value
blocks the thread until the requested event is ready. When it returns,
the return value is a pointer to the EDS internal data representing the result as it
was delivered to the JSCP scheduler by the eds_get_event() call-back.
btPedsWait()
The private EDS structure is hidden from the JSCP scheduler.
NOTE
The private EDS data and the EDS front-end code
should provide for error handling. The JSCP
scheduler dispatches via btPedsWait() whatever the
call-back provides. A NULL pointer returned by
btPedsWait() designates an internal error.
60
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
10
FOR
J AV A
TECHNICAL SUPPORT
Free technical support is available for the period specified in the terms and conditions of
your purchasing contract. Technical support can be obtained by contacting NSIcom in any
of the ways listed below, however, e-mail is the preferred method:
E-mail
[email protected]
Fax
+972 3 533 2371
Mailing Address
JSCP Support
NSIcom, Ltd.
1C Yoni Netanyahu
Or-Yehuda 60376
ISRAEL
Telephone
+972 3 533 1976
To help us serve you better, please include the following information in any support-related
correspondence:

Your contact information: your name, company name, e-mail address, phone, and fax
The JSCP version number
Java version number
Details of your platform: RTOS name and version and CPU
Details of your development environment: compiler name and version; linker name and
version

Details of the problem, including whether and how the problem can be reproduced.
For non-technical information, visit us at http://www.nsicom.com.
© 1997-1999 NSIcom
61
SOFTWARE CO-PROCESSOR
FOR
J AV A
NOTES
62
© 1997-1999 NSIcom
SOFTWARE CO-PROCESSOR
11
FOR
J AV A
GLOSSARY
6
64-bit operations ............................................... 22
A
Abstract Windowing Toolkit (AWT) ............... 20
B
Blue Threads.......................................................8
features ...........................................................8
C
Contacting NSIcom .......................................... 61
E
EDS .................................................................. 16
architecture ............................................. 16, 18
characteristics and limitations ...................... 17
Embedded Systems
challenges .......................................................4
Encapsulation .....................................................6
Event
parameters .................................................... 18
Event Driven Subsystems ................................. 16
F
f2ROM ....................................................... 21, 34
G
Garbage Collection ........................................... 10
mark & sweep .............................................. 10
H
Heaps ................................................................ 12
I
Installing JSCP ................................................. 38
Introduction to JSCP...........................................5
J
J2Clinks ..................................................... 15, 35
Java
platform ...................................................... 1, 3
JSCP
build and run-time environment ................... 37
components .................................................. 37
configuration ................................................ 41
creating an OS task ...................................... 40
integration with RTOS ................................. 39
© 1997-1999 NSIcom
memory management subsystem..................11
multithreading ............................................... 8
on Windows NT ...........................................23
overview ........................................................ 5
power-save mode .........................................23
utilities ....................................................33, 38
JSCP Kit
development environment ............................38
software installation .....................................38
JSCP Monitor ...................................................25
control of threads..........................................30
CPU and memory usage ...............................29
display ..........................................................26
displaying JSCP settings ..............................30
entering the monitor mode ...........................31
function buttons ............................................29
JSCP performance statistics .........................30
menu bar .......................................................27
preliminary configuration .............................26
restarting the JSCP .......................................30
start-up .........................................................26
thread monitoring table ................................28
JSCP Monitor Thread .......................................22
M
Memory Allocation
contiguous ....................................................12
non-contiguous .............................................12
Memory Colors .....................................13, 29, 44
green .......................................................10, 14
red...........................................................10, 14
yellow .....................................................10, 14
Monitor mode ...................................................31
Multiprocessor Support ....................................19
Multithreading ................................................... 6
N
Native Code
linking ..........................................................15
R
Restarting JSCP ................................................30
c2ROM .......................................................21, 33
S
SCHD ................................................................ 8
Stacks................................................................12
Support .............................................................61
A