Ptolemy II PtinyOSDirector Control Flow

Below are tables that show the sequence of calls between Java and C when the PtinyOSDirector is used in simulation mode in Viptos. The PtinyOSDirector uses a Java PtinyOSLoader class for each instance of TOSSIM to keep the namespace separate for each TinyOS node in the model. unique_name is used in native method names to maintain separate namespaces. All calls that cross the Java / C (and C / Java) boundary are JNI calls.

A JNI call from TOSSIM to the Java PtinyOSLoader class (_loader) refers to a call from the C code in TOSSIM to the Java PtinyOSLoader class associated with that instance of TOSSIM. The same is true for a JNI call from the Java PtinyOSLoader class to TOSSIM.

A Java call from PtinyOSDirector to the Java PtinyOSLoader class refers to a call from the Java code in PtinyOSDirector to the Java PtinyOSLoader class associated with that instance of PtinyOSDirector. The same is true for a Java call from the Java PtinyOSLoader class to the PtinyOSDirector.

See:

$PTII/ptolemy/domains/ptinyos/kernel/PtinyOSDirector.java (Start here)
$PTII/ptolemy/domains/ptinyos/kernel/PtinyOSLoader.java

and

$TOSROOT/contrib/ptII/ptinyos/tos/platform/ptII/adc_model.c
$TOSROOT/contrib/ptII/ptinyos/tos/platform/ptII/event_queue.c
$TOSROOT/contrib/ptII/ptinyos/tos/platform/ptII/external_comm.c
$TOSROOT/contrib/ptII/ptinyos/tos/platform/ptII/external_comm.h
$TOSROOT/contrib/ptII/ptinyos/tos/platform/ptII/Nido.nc
$TOSROOT/contrib/ptII/ptinyos/tos/platform/ptII/nido.h
$TOSROOT/contrib/ptII/ptinyos/tos/platform/ptII/ptII.c (Start here)
$TOSROOT/contrib/ptII/ptinyos/tos/platform/ptII/rfm_model.c

$TOSROOT/contrib/ptII/ptinyos/beta/TOSSIM-packet/Nido.nc
$TOSROOT/contrib/ptII/ptinyos/beta/TOSSIM-packet/nido.h
$TOSROOT/contrib/ptII/ptinyos/beta/TOSSIM-packet/packet_sim.c

$TOSROOT/contrib/ptII/ptinyos/tos/types/dbg.h

Initialization: Starting the PtinyOSDirector
Java (PtinyOSDirector) Java (PtinyOSLoader) C (TOSSIM)
PtinyOSDirector.preinitialize()

Generates nesC code (.nc), makefile, and Java PtinyOSLoader (.java).
Runs make, using Runtime.exec()
Compiles nesC (.nc) code to a TOSSIM shared object (.so or .dll), and the Java PtinyOSLoader (.java) to a Java PtinyOSLoader class (.class).
- -
PtinyOSDirector.initialize()

Loads Java PtinyOSLoader class into memory using ClassLoader.loadClass()
Creates instance of PtinyOSLoader class (_loader), using Class.newInstance()
Calls Java _loader.load()
- -
- _loader.load() loads the TOSSIM shared object into memory, using Java System.load() -
PtinyOSDirector.initialize(), continued

Calls Java _loader.main()
- -
- _loader.main() calls JNI main_unique_name() native method. -
- - JNI main_unique_name() calls TOSSIM main(), which contains an initialization routine:

Call TOSSIM initializeSockets(), which calls TOSSIM ptII_startThreads(), which calls JNI _loader.startThreads()

- _loader.startThreads() creates Java threads and calls Java Thread.start() on each thread. -
- - TOSSIM main() initialization routine, continued

Create bootup event and call TOSSIM ptII_queue_insert_event(), which calls JNI _loader.enqueueEvent()

- _loader.enqueueEvent() calls Java PtinyOSDirector.enqueueEvent() -
PtinyOSDirector.enqueueEvent()

Calls Java Ptolemy II fireAt() on the executive director (usually a DE Director), or this director if there is no executive director.
- -

*Initialization: Starting the PtinyOSDirector*
Java (PtinyOSDirector)	Java (PtinyOSLoader)	C (TOSSIM)
PtinyOSDirector.preinitialize() Generates nesC code (.nc), makefile, and Java PtinyOSLoader (.java). Runs make, using Runtime.exec() Compiles nesC (.nc) code to a TOSSIM shared object (.so or .dll), and the Java PtinyOSLoader (.java) to a Java PtinyOSLoader class (.class).	-	-
PtinyOSDirector.initialize() Loads Java PtinyOSLoader class into memory using ClassLoader.loadClass() Creates instance of PtinyOSLoader class (_loader), using Class.newInstance() Calls Java _loader.load()	-	-
-	_loader.load() loads the TOSSIM shared object into memory, using Java System.load()	-
PtinyOSDirector.initialize(), continued Calls Java _loader.main()	-	-
-	_loader.main() calls JNI main_unique_name() native method.	-
-	-	JNI main_unique_name() calls TOSSIM main(), which contains an initialization routine: Call TOSSIM initializeSockets(), which calls TOSSIM ptII_startThreads(), which calls JNI _loader.startThreads()
-	_loader.startThreads() creates Java threads and calls Java Thread.start() on each thread.	-
-	-	TOSSIM main() initialization routine, continued Create bootup event and call TOSSIM ptII_queue_insert_event(), which calls JNI _loader.enqueueEvent()
-	_loader.enqueueEvent() calls Java PtinyOSDirector.enqueueEvent()	-
PtinyOSDirector.enqueueEvent() Calls Java Ptolemy II fireAt() on the executive director (usually a DE Director), or this director if there is no executive director.	-	-

Event processing in PtinyOSDirector and TOSSIM
Java (PtinyOSDirector) Java (PtinyOSLoader) C (TOSSIM)
PtinyOSDirector.fire()

Calls Java _loader.processEvent()
- -
- _loader.processEvent() calls JNI processEvent_unique_name() native method. -
- - JNI processEvent_unique_name() calls TOSSIM ptII_fire(), which invokes a single iteration of the TOSSIM scheduler. The TOSSIM scheduler processes a single TOSSIM event and runs tasks in the task queue. Note that processing a TOSSIM event may cause events with the same time stamp to be created, and for additional TinyOS tasks to be created. All events created in TOSSIM use the same event call sequence described above for the bootup event (see ptII_queue_insert_event()).

*Event processing in PtinyOSDirector and TOSSIM*
Java (PtinyOSDirector)	Java (PtinyOSLoader)	C (TOSSIM)
PtinyOSDirector.fire() Calls Java _loader.processEvent()	-	-
-	_loader.processEvent() calls JNI processEvent_unique_name() native method.	-
-	-	JNI processEvent_unique_name() calls TOSSIM ptII_fire(), which invokes a single iteration of the TOSSIM scheduler. The TOSSIM scheduler processes a single TOSSIM event and runs tasks in the task queue. Note that processing a TOSSIM event may cause events with the same time stamp to be created, and for additional TinyOS tasks to be created. All events created in TOSSIM use the same event call sequence described above for the bootup event (see ptII_queue_insert_event()).

Obtaining TOSSIM sensor values from Ptolemy II
Java (PtinyOSDirector) Java (PtinyOSLoader) C (TOSSIM)
- - TOSSIM requests sensor value in TOSSIM generic_adc_read() by calling ptII_get_adc_value(), which calls JNI _loader.getCharParameterValue().
- _loader.getCharParameterValue() calls Java PtinyOSDirector.getCharParameterValue(). -
PtinyOSDirector.getCharParameterValue() gets a double token from the requested PortParameter and converts it to a Java char and returns the value. - -
- _loader.getCharParameterValue() returns the Java char value. -
- - JNI _loader.getCharParameterValue() returns a JNI jchar value. TOSSIM ptII_get_adc_value() converts the JNI jchar into a C unsigned short and returns the value to TOSSIM generic_adc_read() for use as the sensor (ADC) value.

*Obtaining TOSSIM sensor values from Ptolemy II*
Java (PtinyOSDirector)	Java (PtinyOSLoader)	C (TOSSIM)
-	-	TOSSIM requests sensor value in TOSSIM generic_adc_read() by calling ptII_get_adc_value(), which calls JNI _loader.getCharParameterValue().
-	_loader.getCharParameterValue() calls Java PtinyOSDirector.getCharParameterValue().	-
PtinyOSDirector.getCharParameterValue() gets a double token from the requested PortParameter and converts it to a Java char and returns the value.	-	-
-	_loader.getCharParameterValue() returns the Java char value.	-
-	-	JNI _loader.getCharParameterValue() returns a JNI jchar value. TOSSIM ptII_get_adc_value() converts the JNI jchar into a C unsigned short and returns the value to TOSSIM generic_adc_read() for use as the sensor (ADC) value.

Transmitting LED or packet values from TOSSIM to Ptolemy II
Java (PtinyOSDirector) Java (PtinyOSLoader) C (TOSSIM)
- - TOSSIM generates an LED or packet value and calls TOSSIM ptII_updateLeds() or TOSSIM ptII_send_packet(), both of which call JNI _loader.sendToPort() with the port name and value as string arguments.
- _loader.sendToPort() calls Java PtinyOSDirector.sendToPort(). -
PtinyOSDirector.sendToPort() performs type conversion from a Java string to the appropriate Token type (depending on the type of the requested port), and sends the token to the requested port using the Java Ptolemy II Port.send() method. - -

*Transmitting LED or packet values from TOSSIM to Ptolemy II*
Java (PtinyOSDirector)	Java (PtinyOSLoader)	C (TOSSIM)
-	-	TOSSIM generates an LED or packet value and calls TOSSIM ptII_updateLeds() or TOSSIM ptII_send_packet(), both of which call JNI _loader.sendToPort() with the port name and value as string arguments.
-	_loader.sendToPort() calls Java PtinyOSDirector.sendToPort().	-
PtinyOSDirector.sendToPort() performs type conversion from a Java string to the appropriate Token type (depending on the type of the requested port), and sends the token to the requested port using the Java Ptolemy II Port.send() method.	-	-

Transmitting packet values from Ptolemy II to TOSSIM
Java (PtinyOSDirector) Java (PtinyOSLoader) C (TOSSIM)
PtinyOSDirector.receivePacket() called (e.g., by the fire() method of the container, which should be a PtinyOSCompositeActor, in response to a packet arriving at the packetIn port).

Calls Java _loader.receivePacket() with the packet as a Java String argument.
- -
- _loader.receivePacket() calls JNI receivePacket_unique_name() native method with the packet as a Java String argument. -
- - JNI receivePacket_unique_name() receives the packet as a JNI jstring argument and converts it into a C const char array. It then calls TOSSIM ptII_receive_packet(), which copies the C const char array into a TOS_Msg data structure. TOSSIM ptII_receive_packet() then calls TOSSIM ptII_insert_packet_event(), which creates a TOSSIM packet event.

*Transmitting packet values from Ptolemy II to TOSSIM*
Java (PtinyOSDirector)	Java (PtinyOSLoader)	C (TOSSIM)
PtinyOSDirector.receivePacket() called (e.g., by the fire() method of the container, which should be a PtinyOSCompositeActor, in response to a packet arriving at the packetIn port). Calls Java _loader.receivePacket() with the packet as a Java String argument.	-	-
-	_loader.receivePacket() calls JNI receivePacket_unique_name() native method with the packet as a Java String argument.	-
-	-	JNI receivePacket_unique_name() receives the packet as a JNI jstring argument and converts it into a C const char array. It then calls TOSSIM ptII_receive_packet(), which copies the C const char array into a TOS_Msg data structure. TOSSIM ptII_receive_packet() then calls TOSSIM ptII_insert_packet_event(), which creates a TOSSIM packet event.

Transmitting debug messages from TOSSIM to Ptolemy II
Java (PtinyOSDirector) Java (PtinyOSLoader) C (TOSSIM)
- - TOSSIM generates a debug message in dbg() or dbg_clear(), both of which call TOSSIM ptII_dbg(), which calls JNI _loader.tosDebug().
- _loader.tosDebug() calls Java PtinyOSDirector.tosDebug(). -
PtinyOSDirector.tosDebug() prints the debug message using the Java Ptolemy II _debug() method. - -

*Transmitting debug messages from TOSSIM to Ptolemy II*
Java (PtinyOSDirector)	Java (PtinyOSLoader)	C (TOSSIM)
-	-	TOSSIM generates a debug message in dbg() or dbg_clear(), both of which call TOSSIM ptII_dbg(), which calls JNI _loader.tosDebug().
-	_loader.tosDebug() calls Java PtinyOSDirector.tosDebug().	-
PtinyOSDirector.tosDebug() prints the debug message using the Java Ptolemy II _debug() method.	-	-

Shutting down TOSSIM from Ptolemy II
Java (PtinyOSDirector) Java (PtinyOSLoader) C (TOSSIM)
PtinyOSDirector.wrapup()

Calls Java _loader.wrapup()
- -
- _loader.wrapup() calls JNI wrapup_unique_name() native method. -
- - JNI wrapup_unique_name() calls TOSSIM shutdownSockets(), which:

Closes sockets.
Joins threads by calling TOSSIM ptII_joinThreads(), which calls JNI _loader.joinThreads().

- _loader.joinThreads() calls Java Thread.join() on all threads created during initialization. Returns Java int value of 0 upon success. -
- - JNI _loader.joinThreads() returns jint value of 0 upon success, which is converted into a C int and returned by ptII_joinThreads(). If successful, TOSSIM execution stops.

*Shutting down TOSSIM from Ptolemy II*
Java (PtinyOSDirector)	Java (PtinyOSLoader)	C (TOSSIM)
PtinyOSDirector.wrapup() Calls Java _loader.wrapup()	-	-
-	_loader.wrapup() calls JNI wrapup_unique_name() native method.	-
-	-	JNI wrapup_unique_name() calls TOSSIM shutdownSockets(), which: Closes sockets. Joins threads by calling TOSSIM ptII_joinThreads(), which calls JNI _loader.joinThreads().
-	_loader.joinThreads() calls Java Thread.join() on all threads created during initialization. Returns Java int value of 0 upon success.	-
-	-	JNI _loader.joinThreads() returns jint value of 0 upon success, which is converted into a C int and returned by ptII_joinThreads(). If successful, TOSSIM execution stops.

TOSSIM also contains JNI wrapper calls to Java socket routines in the Java PtinyOSLoader and in the Java PtinyOSDirector. We omit detailed discussion of these call sequence for these socket routines above, since they are not necessary for understanding the basics of the PtinyOS domain. The wrappers for the socket routines are similar for the wrappers in the Java PtinyOSLoader as discussed above.

Detailed list of socket routines:

acceptConnection()
selectorClose()
selectorCreate()
selectorRegister()
selectSocket()
serverSocketClose()
serverSocketCreate()
socketChannelClose()
socketChannelRead()
socketChannelWrite()