See: Description
Package | Description |
---|---|
com.oracle.deviceaccess |
Provides interfaces and classes for device I/O access and control.
|
com.oracle.deviceaccess.adc |
Interfaces and classes for reading analog inputs using an Analog to Digital Converter (ADC).
|
com.oracle.deviceaccess.atcmd |
Interfaces and classes for controlling a Data Communication Equipment such as a modem or a cellular module using AT
commands.
|
com.oracle.deviceaccess.counter |
Interfaces and classes for counting pulses (or events) on a digital input line.
|
com.oracle.deviceaccess.dac |
Interfaces and classes for writing analog outputs using a Digital to Analog Converter (DAC).
|
com.oracle.deviceaccess.generic |
Interfaces and classes for controlling devices using generic I/O operations.
|
com.oracle.deviceaccess.gpio |
Interfaces and classes for reading and writing from/to GPIO (General Purpose Input Output) pins and ports of the
device.
|
com.oracle.deviceaccess.i2cbus |
Interfaces and classes for I2C (Inter-Integrated Circuit Bus) device access.
|
com.oracle.deviceaccess.mmio |
Interfaces and classes for performing memory-mapped I/O.
|
com.oracle.deviceaccess.modem |
Interfaces and classes for controlling MODEM signals.
|
com.oracle.deviceaccess.power |
Interfaces and classes for power management of peripheral devices.
|
com.oracle.deviceaccess.spibus |
Interfaces and classes for SPI (Serial Peripheral Interface Bus) device access.
|
com.oracle.deviceaccess.uart |
Interfaces and classes for controlling and reading and writing from/to Universal Asynchronous Receiver/Transmitter
(UART), with optional Modem signals control.
|
com.oracle.deviceaccess.watchdog |
Interfaces and classes for using system watchdog timers (WDT).
|
0
and must be unique.
Yet the same peripheral device may be directly and indirectly mapped through several IDs.
For example, an Analog Digital Converter may be both an I2C slave device and an ADC device.
In this case, there may be one ID to retrieve the device as an I2CDevice
instance and four other IDs to retrieve each of its four ADC channels as ADCChannel
instances.
Peripheral
offering different levels of abstractions. Each of these instances would have the same name.
In the last example above, both implementations of
the real-time clock peripheral device may have the same name "RTC" though they have different IDs and interfaces.
ATDevice
defines - as properties - certain capabilities
for modems.
Properties can be use to represent intrinsic properties of a peripheral device such as its capabilities as well as
extrinsic properties of a peripheral device such as its placement on the board or whether a peripheral device is embedded,
removable or even external to a module. Properties defined for a peripheral device driver may be published as part of its specification.
Using the RTC example,
because of the tight dependency to its hardware chip, the memory-mapped Real-Time Clock peripheral
device may have been registered with the following property: "com.acme.rtc.chip=146818", which actually refers to the RTC chip designation.
The user-defined Peripheral
implementation
may then rely on this property to lookup the MMIODevice
for which it wants to provide
a higher-level abstraction.
Another example is the properties of an I2C slave device which could include whether it supports the SMBus
specification (see http://smbus.org/specs/index.html) or the
properties of a temperature sensor which may include its placement on the board or module.
By convention properties should use the following format:
<name>=
<value>
Note that property-based lookup only uses exact (case-insensitive) matching and does not perform any semantic interpretation.
For example, a negatively asserted boolean property (eg. "com.foobar.rtc.alarm=false") will not match the absence of
the corresponding positively asserted boolean property (eg. "com.foobar.rtc.alarm=true").
"java."
, "javax."
are reserved for definition by this
specification. According to this convention, the property of an I2C slave device to support the SMBus
specification should be named with the prefix "org.smbus."
.
PeripheralConfig
objects when opening a peripheral device with an adhoc configuration.
Peripheral
sub-interfaces. They are especially not granted the "com.oracle.deviceaccess.PeripheralManager.configure"
permission and will especially not be allowed to use the PeripheralManager.open(PeripheralConfig)
to open
peripheral devices with an ad-hoc configuration.
Peripheral
interfaces.
Still applications will be able to discover or address peripheral devices which are not part of the pre-configured set
and especially new peripheral devices that may be added to the platform, for example on an I2C bus.
To address and access such a newly plugged in I2C slave device, an application may use an instance of I2CDeviceConfig
with the bus number and slave address properly set.
In order to retrieve a peripheral device with an adhoc configuration, an application must be granted the "com.oracle.deviceaccess.PeripheralManager.configure"
permission.
PeripheralManager.register(int, Class, com.oracle.deviceaccess.PeripheralConfig, String, String[])
method.
In order to register a peripheral device, an application must be granted the "com.oracle.deviceaccess.PeripheralManager.register"
permission.
An application may unregister an application-registered peripheral device provided it is granted the "com.oracle.deviceaccess.PeripheralManager.unregister"
permission.
GPIOPin
instances and can be accessed concurrently even
though they may be supported by the same GPIO controller hardware; individual ADC channels are modeled as separate ADCChannel
instances and can be accessed concurrently. While access to the underlying hardware device may be shared and the sharing controlled by the underlying peripheral device driver,
access to individual peripheral device resources modeled as Peripheral
instances may be exclusive or shared.
Whether access to individual peripheral device resources modeled as Peripheral
instances is exclusive or shared
depends on the peripheral's type, configuration and on the underlying device driver implementation.
Three cases of peripheral device resource abstraction may be considered:
Peripheral
instance may be a dedicated abstraction of a peripheral device resource. Only one Peripheral
instance
for that individual peripheral device resource may be open at a particular time and access to the resource through Peripheral
instance is exclusive.
Attempting to open such a peripheral device resource while it is already open will result in a PeripheralNotAvailableException
being thrown.
Peripheral
instances are assumed to be dedicated abstraction of peripheral device resources.
Peripheral
instance may be a virtualized abstraction of a peripheral device resource. Several Peripheral
instance
mapped onto that same individual peripheral device resource may be open concurrently and access to the resource through the Peripheral
instances
may appear as exclusive as if dedicated abstractions.
Peripheral
instance may be a shared abstraction of a peripheral device resource. Several Peripheral
instance
mapped onto that same individual peripheral device resource may be open concurrently but access to the resource through the Peripheral
instances
must be explicitly synchronized.
I2CDevice
instances will be synchronized on I2C transactions if not by other means.
PeripheralManager.open
methods always return a new instance upon each call regardless of whether it is a dedicated, virtualized or shared
peripheral device resource abstraction.
Instances of Peripheral
must be thread-safe.
For example, if a thread has already initiated an I/O operation upon a peripheral device through a Peripheral
instance, an
invocation of another I/O method on that same Peripheral
instance will block until the first operation is complete.
PeripheralEvent
)
and are dispatched for processing by application-registered event listeners
(instances of PeripheralEventListener
).
Because some events may be time-sensitive, events are time-stamped. Additionally,
to account for event bursts, that is cases where events are produced more rapidly than they are handled,
events may be coalesced. Coalesced events regroup in one event object several occurrences of events
of the same type and keep track of the number of events that have been coalesced.
Only the last occurring value that may be attached to the event such as the state of a GPIO pin, is retained.
Also, the timestamps of both the first occurrence and the last occurrence are retained.
Not all events can be coalesced. Coalescing of events are event and peripheral -type-dependent.
Event handling methods should be implemented in such a way that they quickly process the events and return.
RealTimeClock
can be provided for a memory-mapped Real-Time Clock
chip accessible as an MMIODevice
peripheral.
The Real Time Clock peripheral device interface:
The Real Time Clock peripheral device implementation class:public interface RealTimeClock { int getHours() throws IOException, PeripheralNotAvailableException; int getID(); int getMinutes() throws IOException, PeripheralNotAvailableException; String getName(); int getSeconds() throws IOException, PeripheralNotAvailableException; void setAlarm(byte delaySeconds, byte delayMinutes, byte delayHours, AlarmListener listener) throws IOException, PeripheralException; void setHours(int hrs) throws IOException, PeripheralNotAvailableException; void setMinutes(int mins) throws IOException, PeripheralNotAvailableException; void setSeconds(int secs) throws IOException, PeripheralNotAvailableException; void cancelAlarm() throws IOException, PeripheralNotAvailableException; interface AlarmListener { void fired(RealTimeClock rtc); } }
public class RealTimeClockImpl implements RealTimeClock { private static final int INTERRUPT = 0; private int id; private String name; private String[] properties; private MMIODevice rtc = null; RawByte seconds; RawByte secAlarm; RawByte minutes; RawByte minAlarm; RawByte hours; RawByte hrAlarm; RawByte registerB; RawByte registerC; RawBlock userRAM; private RealTimeClockImpl(int id, String name, String[] properties) { this.id = id; this.name = name; this.properties = properties; } void open() throws IOException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, PeripheralNotAvailableException { rtc = (MMIODevice) PeripheralManager.open(name, MMIODevice.class, new String[] { "com.acme.rtc.chip=146818" }); //The RealTimeClockImpl device has 14 bytes of clock and control registers and 50 bytes // of general purpose RAM (see the data sheet of the HITACHI HD146818 Real Time Clock). seconds = rtc.getByteRegister("Seconds"); secAlarm = rtc.getByteRegister("SecAlarm"); minutes = rtc.getByteRegister("Minutes"); minAlarm = rtc.getByteRegister("MinAlarm"); hours = rtc.getByteRegister("Hours"); hrAlarm = rtc.getByteRegister("HrAlarm"); // More date registers... but not supported in this example registerB = rtc.getByteRegister("RegisterB"); registerC = rtc.getByteRegister("RegisterC"); userRAM = rtc.getBlock("UserRam"); } public void setSeconds(int secs) throws IOException, PeripheralNotAvailableException { seconds.set((byte) secs); } public int getSeconds() throws IOException, PeripheralNotAvailableException { return seconds.get(); } public void setMinutes(int mins) throws IOException, PeripheralNotAvailableException { minutes.set((byte) mins); } public int getMinutes() throws IOException, PeripheralNotAvailableException { return minutes.get(); } public void setHours(int hrs) throws IOException, PeripheralNotAvailableException { hours.set((byte) hrs); } public int getHours() throws IOException, PeripheralNotAvailableException { return hours.get(); } // Sets the daily alarm for after some delay public void setAlarm(byte delaySeconds, byte delayMinutes, byte delayHours, final AlarmListener listener) throws IOException, PeripheralException { //Directly read from/write to the registers using RawByte instances. byte currentSeconds = seconds.get(); byte currentMinutes = minutes.get(); byte currentHours = hours.get(); int i = (currentSeconds + delaySeconds) % 60; int j = (currentSeconds + delaySeconds) / 60; secAlarm.set((byte) i); i = (currentMinutes + delayMinutes + j) % 60; j = (currentMinutes + delayMinutes + j) / 60; minAlarm.set((byte) i); i = (currentHours + delayHours + j) % 24; hrAlarm.set((byte) i); rtc.setMMIOEventListener(INTERRUPT, new MMIOEventListener() { public void eventDispatched(MMIOEvent event) { try { MMIODevice rtc = (MMIODevice) event.getPeripheral(); RawByte registerC = rtc.getByteRegister("RegisterC"); // Check the Alarm Interrupt Flag (AF) if ((registerC.get() & 0X20) != 0) { listener.fired(RealTimeClockImpl.this); } } catch (IOException ex) { ex.printStackTrace(); } catch (PeripheralNotAvailableException ex) { ex.printStackTrace(); } } }); // Set the Alarm Interrupt Enabled (AIE) flag registerB.set((byte) (registerB.get() | 0X20)); } public void cancelAlarm() throws IOException, PeripheralNotAvailableException { // Clear the Alarm Interrupt Enabled (AIE) flag registerB.set((byte) (registerB.get() & ~0X20)); } public void close() throws IOException { if (rtc != null) { rtc.close(); } } }
PeripheralManager.register(11, // the peripheral device ID UART.class, // the peripheral device type/interface new UARTConfig(0, 2400, UARTConfig.DATABITS_8, UARTConfig.PARITY_EVEN, UARTConfig.STOPBITS_1, UARTConfig.FLOWCONTROL_NONE), // the peripheral device configuration "HOST", // the peripheral device name new String[] { "com.foobar.uart.xxx=true", "com.foobar.uart.yyy=true" } // the peripheral device capabilities );
PeripheralManager.register(12, // the peripheral device ID ModemUART.class, // the peripheral device type/interface new UARTConfig(1, 2400, UARTConfig.DATABITS_8, UARTConfig.PARITY_EVEN, UARTConfig.STOPBITS_1, UARTConfig.FLOWCONTROL_NONE), // the peripheral device configuration "MODEM", // the peripheral device name new String[] { "com.foobar.modem.xxx=true", "com.foobar.modem.yyy=true" } // the peripheral device capabilities );
Copyright (c) 2012, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.