jdk.dio

Interface DeviceConfig<P extends Device<? super P>>

Type Parameters:

P - the device type the configuration is defined for.

All Known Implementing Classes:

ADCChannelConfig, ATDeviceConfig, DACChannelConfig, GenericDeviceConfig, GPIOPinConfig, GPIOPortConfig, I2CDeviceConfig, MMIODeviceConfig, PulseCounterConfig, PWMChannelConfig, SPIDeviceConfig, UARTConfig, WatchdogTimerConfig

public interface DeviceConfig<P extends Device<? super P>>

The DeviceConfig class is the base interface for all device configuration classes.

A device's configuration consists of the following elements:

Hardware Addressing Information

Information required to address the device. Examples are an I2C bus number and an I2C slave device address or a GPIO controller number and pin index.

Static Configuration Parameters

Configuration parameters that must be set upon opening the device and which may not be changed afterwards. Examples are an SPI slave device clock mode or word length.

Dynamic Configuration Parameters

Configuration parameters for which an initial value is set upon opening the device and that an application may change while the device is still open. Dynamic configuration parameters can be changed after the device is open through methods of Device sub-interfaces. Examples are a UART baud rate or the current direction of a bidirectional GPIO pin. The initial values of dynamic configuration parameters are initial default values from the point of view of the application accessing the device. Runtime changes to the values of dynamic configuration parameters are not reflected in the DeviceConfig object of that device, which retains its initial values.

The open(DeviceConfig, ...) and open(Class, DeviceConfig, ...) methods of the DeviceManager can be used to open a device and obtain a Device instance to access it. The device to open is designated by the hardware addressing information encapsulated in the provided DeviceConfig object; it is then configured according to the static and runtime configuration parameters encapsulated in the same provided DeviceConfig object. If the device designated by the provided hardware addressing information cannot be found a DeviceNotFoundException is thrown. If a static or runtime configuration parameter or a combination thereof is not valid or not supported a InvalidDeviceConfigException.

Immutability of DeviceConfig Objects

DeviceConfig objects should be immutable. If a DeviceConfig-implementing class is not immutable it should implement the Cloneable interface. A compliant implementation of this specification MUST do its best to ensure that information encapsulated in a DeviceConfig instance cannot be altered while it is handling it and SHOULD, when necessary (that is when an instance is not considered immutable), create its own private copy either of the instance (such as by cloning it) or of the information it contains. If a DeviceConfig-implementing class does not implement the Cloneable interface then it SHALL - for that purpose - be considered immutable.
As per the above requirements, a compliant implementation of this specification may return the same (immutable) DeviceConfig instance over several calls; an application must therefore not synchronize on DeviceConfig objects.

Persistency of DeviceConfig Objects

A compliant implementation of this specification MUST support the persistence of the device configuration registry across platform reboots; it MUST guarantee in particular that a device configuration registered by an application remains registered after the application has terminated and across platform reboots until it is explictly unregistered by an application (possibly the same) that has been granted the necessary permissions.
To allow for persistency of the device configuration registry, DeviceConfig objects must support saving their states to an OutputStream and restoring their states from an InputStream. The DeviceManager saves the state of an DeviceConfig object by invoking its serialize method. The DeviceManager restores the state of an DeviceConfig object by invoking the deserialize on its associated DeviceProvider.
On the Java Platform Standard Edition, these methods may delegate to the Object Serialization framework. In order to facilitate the implementation of compound or layered device abstractions, on the Java Platform Micro Edition, which does not support Object Serialization, DeviceConfig-implementing classes should provide methods for creating new instances initialized from an InputStream; see example below:

 public class RealTimeClockConfig implements DeviceConfig<RealTimeClock>, HardwareAddressing {

   private MMIODeviceConfig mmioConfig;

   public RealTimeClockConfig(MMIODeviceConfig mmioConfig) {
     this.mmioConfig = mmioConfig;
   }

   public static RealTimeClockConfig deserialize(InputStream in) throws IOException {
     return new RealTimeClockConfig(MMIODeviceConfig.deserialize(in));
   }
   
   ...
   
   public MMIODeviceConfig getMmioConfig() {
     return mmioConfig;
   }

   @Override
   public int serialize(OutputStream out) throws IOException {
     return mmioConfig.serialize(out);
   }
 }
   

Unassigned, Default or Unused Parameter Values

Some hardware addressing, static or dynamic configuration parameters may be set to UNASSIGNED (or null) when opening or registering a device configuration. Device drivers may substitute hardware addressing parameters and static and dynamic configuration parameters set to UNASSIGNED (or null) with actual default values; whether such default settings are supported is platform- as well as device driver-dependent; if a required parameter is set to UNASSIGNED (or null) the device driver MUST reject the configuration and throw an InvalidDeviceConfigException. When querying the configuration of an open device using the DeviceDescriptor.getConfiguration method the actual settings are returned; parameters that are neither supported nor required by the underlying hardware or driver are still set to UNASSIGNED (or null); whether or not this is the case when listing registered device configuration using the DeviceManager.list methods depends on whether the device could be probed upon registration of the configuration (see Device Probing).

Since:

1.0

See Also:

DeviceManager.open(DeviceConfig), DeviceManager.open(DeviceConfig, int), DeviceManager.open(Class, DeviceConfig), DeviceManager.open(Class, DeviceConfig, int), DeviceManager.list(), DeviceDescriptor.getConfiguration(), InvalidDeviceConfigException

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	DeviceConfig.HardwareAddressing The HardwareAddressing interface defines an abstraction of an hardware addressing information common on different platforms.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT Deprecated. As of 1.1 replaced by UNASSIGNED.
static int	UNASSIGNED Used to indicate that the default value of a hardware addressing or configuration parameter is requested upon opening or registering a device configuration or to indicate that a configuration parameter is unused (such as when it is neither supported nor required by the underlying hardware or driver).

Method Summary

Methods

Modifier and Type	Method and Description
int	serialize(java.io.OutputStream out) Serializes the state of this DeviceConfig object to the specified OutputStream.

Field Detail

DEFAULT

@Deprecated
static final int DEFAULT

Deprecated. As of 1.1 replaced by UNASSIGNED.

Used to indicate that the default value of a hardware addressing or configuration parameter is requested upon opening or registering a device configuration or to indicate that a configuration parameter is unassigned (such as when it is not supported).

See Also:

Constant Field Values

UNASSIGNED

static final int UNASSIGNED

Used to indicate that the default value of a hardware addressing or configuration parameter is requested upon opening or registering a device configuration or to indicate that a configuration parameter is unused (such as when it is neither supported nor required by the underlying hardware or driver).

See Also:

Constant Field Values

Method Detail

serialize

int serialize(java.io.OutputStream out)
              throws java.io.IOException

Serializes the state of this DeviceConfig object to the specified OutputStream. This method may be invoked by the DeviceManager to save the state of a DeviceConfig object to a persistent store in order to support persistence of device configuration registration.

Parameters:

out - the stream to write to.

Returns:

the number of bytes written to the stream.

Throws:

java.io.IOException - if an I/O error occurs.

Since:

1.1

See Also:

DeviceProvider.deserialize(java.io.InputStream)