[Embedlets-dev] Re: JAPL versus Embedlet integration....

[Andrzej J. T. <an...@ch...>]

> The JAPL devices are abstract peripherals, not device drivers.  

Whatever....I'm using the term interchangeably in my posts.  I see the 
abstract peripheral API's as being just a generic version of a specific 
device driver.

> Lets set aside
> Robocode for the moment and discuss a JAPL UART because I think it is more
> typical of what most JAPL devices will look like.  A normal UART device driver
> can  a) configure the UART by placing data into its internal registers,  b)
> query the state of the UART by looking at its internal registers and  c) the
> UART can asynchronously notify its device driver that it needs to be serviced
> by asserting the interrupt line.

The JAPL API for a UART should provide get/set methods for the internal 
registers, but suitably "abstracted" so that you don't see the metal (actual 
registers) from the other side of the API.  In other words, the JAPL API 
should be functional in appearance, not tied to the specific hardware 
implementation of the functions. For example:

japl.setFlowControl( true );
japl.setParity( false );

are much better than more "hardware oriented" stuff like:

int	flags = 0x01 | 0x04 	// eg. Flags for flow control and Parity
device.setFlags( flags );

As for the asynchronous notifications (interrupts basically), see my last 
post about using a JAPL Wrapper class as a mediation layer that converts such 
an async callback into an Embedlet Event.  There is MASSIVE benefit to using 
such an approach....the principal one being keeping the JAPL and Embedlet 
layers nicely decoupled and flexible (so that JAPL can be used outside of an 
Embedlet Container).

> The Architecture document gives an Embedlet 2/3 of the capabilities it needs
> to serve as a JAPL UART device driver because it allows the Embedlet to have a
> direct reference to the JAPL UART and so enables it to do 'a' and 'b' above.

That is true.  And assembler code could do the same, but that does not mean 
you should use that technique even though you could.  And Embedlets were 
always intended to be where you put your "application logic", not driver 
logic.  Driver stuff should be performed (and hidden/encapsulated, eg. how do 
you talk to a device at a low level) in the JAPL layer.  Application stuff 
should be in an Embedlet (eg. what you do when something happens...a temp 
sensor flips, process bytes that have been read by a UART).

Architecturally, the better way is to integrate Embedlets and JAPL 
peripherals is to use a JAPL wrapper to "bridge" the gap per my other email.

> As for the UART interrupt, in all the conventional low level device drivers I
> have written, the interrupt is always channeled directly into the device
> driver that is also responsible for doing 'a' and 'b' for any given device and
> it is always a one-to-one bidirectional binding.  No other piece of code
> besides the peripheral's device driver should be interested in the interrupt.

We're in violent agreement here, Ted!  Kewl!  The JAPL Wrapper approach I 
have outlined resolves this, since the Wrapper class is more a part of the 
JAPL layer than the Embedlet layer, even though it does bridge those two 
worlds.  So the combo of the JAPL driver/peripheral code and the Wrapper 
perform all of a/b/c in your example.  The Embedlet doesn't do any of these 
operations.  The Embedlet reacts in an application-specific way to an 
Embedlet Event that the wrapper may or may not send as a result of an 
interrupt. (note:  an interrupt may not always generate an Embedlet 
Event....if a switch state didn't change, or you are buffering I/O in the 
JAPL layer, then events are not always sent when an interrupt arrives).

> But you are saying that Embedlets should not be used as device drivers either
> (see below).

EXACTLY what I am saying.  JAPL should implement the device driver level and 
Embedlets should know NOTHING about that.  Use a JAPL Wrapper class to 
translate hardware driver level events of interest into an Embedlet Event 
that will be propagated throughout the Outpost container.

One of the benefits of this approach is that you can easily and transparently 
add additional Embedlets that are interested in a particular Embedlet Event 
originated by a JAPL device.  You can add a logging Embedlet that streams out 
JAPL status info across an HTTP connection to the outside world without 
having to touch one line of your JAPL code or your other application-specific 
Embedlets, if you use this architectural model.

> Again, a JAPL peripheral is just a peripheral, not a device driver.  

From some perspective, I see the JAPL peripheral as doing a lot of low level 
device driver types of things and exposing a higher level API (see example of 
what I mean by this above).  So in that sense, JAPL is a device driver to a 
great degree.

> Besides this, the JAPL peripheral can't convert its interrupts into
> Embedlet events > or any other specific system's events because the JAPL is
> a generalized, > system neutral technology. 

I should have explained myself more fully in my first response (but was 
hoping that everyone would figure it out).  Use a JAPL Wrapper class to 
bridge the two worlds and all is wonderful! ;-)

> If an Embedlet is being used as a device driver for a JAPL device then I would
> say that device drivers commonly have bidirectional references to the devices
> they are controlling.  My current thinking is that routing a peripheral's
> interrupt only to the device driver that is directly responsible for it
> maintains complete encapsulation but allowing this interrupt to be arbitrarily
> routed to other pieces of software in the system breaks it.

But an Embedlet should NOT be used as a device driver....it is intended to be 
used for application specific code.  Not low level hardware interfacing 
stuff.

Design patterns to the rescue....use a JAPL Wrapper class.

> What I hear you saying, though, is that Embedlets should not be used as JAPL
> device drivers and I can certainly go along with this philosophy if Embedlets
> are blocked from having direct references to JAPL peripherals. 

Grasshoppa....you are missing the point.  Embedlets can and have to have 
references to JAPL peripherals.  They need to do get/set properties on JAPL 
devices (using a higher level device API that JAPL exposes).  It's the 
reverse that is verbotten....the JAPL device is NOT allowed to have a 
reference to an Embedlet.  The Wrapper approach resolves this impedence 
mismatch.

> If an Embedlet
> is being constrained as only operating as a high level piece of code then how
> can it be ok to give it a direct reference to a low level peripheral like a
> UART?  

For the same reason that a higher level routine can reference lower level 
subroutines/methods to do it's work.  However, the reverse is considered a 
very bad practices.

Higher level components can employ lower level components to do their work.  
The reverse is not a good idea.

Keep in mind that the data coming in on the UART is typically application 
specific, (medical data?  shop floor sensors?  engine sensors?) and so at 
some level has to be processed by app-level code....meaning an Embedlet.

Maybe I am misinterpreting what JAPL does.  If all it provides is a thin 
generalization layer for specific classes of peripherals, then we may need a 
Device Driver level of code layered on top of that.  But I see that as still 
in the JAPL domain, and not part of the Embedlet container, and you still 
need a wrapper approach to bridge the two worlds.  If such a Device Driver is 
needed on top of JAPL, it should also be independent of the Embedlet 
Container so that it can be used in non-embedlet based code.

> Assuming that a JAPL peripheral can not be its own device driver 

Why not?  In fact, there are a lot of good reasons for the JAPL peripheral to 
act as it's own device driver.  Maybe we are just using different definitions 
of what a device driver is/does?

> Embedlets are not permitted to be device drivers, then we still need some kind
> of a device driver that is part of the Embedlet framework that can do the
> following:

I believe such a driver should be part of the JAPL layer and not the Embedlet 
layer.

> 1) Hold direct references to JAPL peripherals.
> 2) Accept interrupt events from these peripherals.
> 4) Convert the peripheral's interrupt events into Embedlet events.

The combination of the JAPL peripheral (and any "device driver code) and the 
proposed JAPL wrapper approach nicely handle all of the above situations.  
But an Embedlet can hold a reference to a JAPL peripheral (so as to issue API 
method calls on it to get it's work done.  eg.  japl.setSwitch( true ) ).

Keep in mind that what Embedlet Event(s) an interrupt is mapped to is 
application specific, so it does not belong in the JAPL peripheral/driver 
code.

> 3) Convert Embedlet events into method calls on the peripheral.

That is not required since it presumes that low level devices understand 
Embedlet Events which they have no need to.  There is nothing wrong with an 
Embedlet doing method calls on a peripheral as requried.

I think some of the problem is that we had a stated design goal of keeping 
JAPL independent of Embedlets.  If we drop that requirement, then sure, we 
can create a new Embedlet-level component (eg. DeviceDriver) that understands 
Embedlet Events (both as producer and consumer), but then that code would not 
be useable outside of the container.

> The current Adapter might be suitable for this purpose and if not the Adapter
> then perhaps an Embedlet Container DeviceDriver?

Adapters are specifically intended to be used for integration of external 
systems/communications, not attached devices.

> Anyway, I am going to hold off doing more work in this area until we get
> this JAPL issue resolved.  Actually I have been hitting JGraph fairly hard
> during the past week in preparation for beginning work on the Wiring Tool
> and so I have plenty to keep me busy. ;-) 

Have my explanations of the use of a JAPL Wrapper class helped resolve this?

Glad to hear that you are pushing down the Wiring road.  Kewlness!

Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com