jdk.dio.spibus

Interface SPIDevice

All Superinterfaces:

java.lang.AutoCloseable, BufferAccess<java.nio.ByteBuffer>, java.nio.channels.ByteChannel, java.nio.channels.Channel, java.io.Closeable, Device<SPIDevice>, java.nio.channels.ReadableByteChannel, Transactional, java.nio.channels.WritableByteChannel

public interface SPIDevice
extends Device<SPIDevice>, java.nio.channels.ByteChannel, Transactional, BufferAccess<java.nio.ByteBuffer>

The SPIDevice interface provides methods for transmitting and receiving data to/from an SPI slave device.

An SPI slave device may be identified by the numerical ID and by the name (if any defined) that correspond to its registered configuration. An SPIDevice instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name. When an SPIDevice instance is opened with an ad-hoc SPIDeviceConfig configuration (which includes its hardware addressing information) using one of the DeviceManager.open(config,...) it is not assigned any ID nor name.

On an SPI bus, data is transferred between the SPI master device and an SPI slave device in full duplex. That is, data is transmitted by the SPI master to the SPI slave device at the same time data is received from the SPI slave device by the SPI master.

To perform such a bidirectional exchange of data with an SPI slave device, an application may use one of the writeAndRead methods.
When an application only wants to send data to or receive data from an SPI slave device, it may use the write or the read method, respectively. When writing only, the data received from the SPI slave device will be ignored/discarded. When reading only, dummy data will be sent to the slave.

A data exchange consists of words of a certain length which may vary from SPI slave device to SPI slave device.
Words in the sending and receiving byte buffers are not packed (bit-wise) and must be byte-aligned. The most significant bits of a word are stored at the lower index (that is first). If a word's length is not a multiple of 8 (the byte length in bits) then the most significant bits will be undefined when receiving or unused when sending. If the designated portion of a sending or receiving byte buffer cannot contain a (positive) integral number of words then an InvalidWordLengthException will be thrown. For example, if the word length is 16bits and the designated portion of buffer is only 1-byte long or is 3-byte long an InvalidWordLengthException will be thrown.
Assuming a word length w, the length l of the designated portion of the sending or receiving byte buffer must be such that:
((l % (((w - 1) / 8) + 1)) == 0)

Note that since the SPI master device controls the serial transmission clock read and write operations are non-blocking (unless another read or write operation is already on-going in a different thread on the same SPIDevice instance). It is the responsibility of the application to appropriately control the timing between a call to the begin method which may assert the Chip Select (depending on the configuration, see SPIDeviceConfig.CS_NOT_CONTROLLED) and subsequent calls to the read, write and writeAndRead methods.

When the data exchange is over, an application should call the SPIDevice.close method to close the SPI slave device. Any further attempt to transmit/write or receive/read to/from an SPI slave device which has been closed will result in a ClosedDeviceException been thrown.

See Also:

SPIPermission, InvalidWordLengthException, ClosedDeviceException

Field Summary

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
void	begin() Demarcates the beginning of an SPI transaction so that this slave's Select line (SS) will be remain asserted during the subsequent read and write operations and until the transaction ends.
void	end() Demarcates the end of a transaction hence ending the assertion of this slave's Select line (SS).
int	getWordLength() Gets the transfer word length in bits supported by this slave device.
int	read() Reads one data word of up to 32 bits from this slave device.
int	read(java.nio.ByteBuffer dst) Reads a sequence of bytes from this slave device into the given buffer.
int	read(int skip, java.nio.ByteBuffer dst) Reads a sequence of bytes from this device into the given buffer, skipping the first skip bytes read.
int	write(java.nio.ByteBuffer src) Writes a sequence of bytes to this slave device from the given buffer.
void	write(int txData) Writes one data word of up to 32 bits to this slave device.
int	writeAndRead(java.nio.ByteBuffer src, java.nio.ByteBuffer dst) Exchanges (transmits and receives) data with this slave device.
int	writeAndRead(java.nio.ByteBuffer src, int skip, java.nio.ByteBuffer dst) Exchanges (transmits and receives) data with this slave device skipping the specified number of bytes received.
int	writeAndRead(int txData) Exchanges (transmits and receives) one data word of up to 32 bits with this slave device.

Methods inherited from interface jdk.dio.Device

close, getDescriptor, isOpen, tryLock, unlock

Methods inherited from interface jdk.dio.BufferAccess

getInputBuffer, getOutputBuffer

Method Detail

begin

void begin()
           throws java.io.IOException,
                  UnavailableDeviceException,
                  ClosedDeviceException

Demarcates the beginning of an SPI transaction so that this slave's Select line (SS) will be remain asserted during the subsequent read and write operations and until the transaction ends.

Specified by:

begin in interface Transactional

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalStateException - if a transaction is already in progress.

end

void end()
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Demarcates the end of a transaction hence ending the assertion of this slave's Select line (SS).

Specified by:

end in interface Transactional

Throws:

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalStateException - if a transaction is not currently in progress.

getWordLength

int getWordLength()
                  throws java.io.IOException,
                         UnavailableDeviceException,
                         ClosedDeviceException

Gets the transfer word length in bits supported by this slave device.

If the length of data to be exchanged belies a slave's word length an InvalidWordLengthException will be thrown.

Returns:

this slave's transfer word length in bits.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

read

int read()
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Reads one data word of up to 32 bits from this slave device.

Returns:

the data word read.

Throws:

java.io.IOException - if some other I/O error occurs.

InvalidWordLengthException - if the number of bytes to receive belies word length; that is this slave's word length is bigger than 32 bits.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

read

int read(java.nio.ByteBuffer dst)
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Reads a sequence of bytes from this slave device into the given buffer.

Dummy data will be sent to this slave device by the platform.

Specified by:

read in interface java.nio.channels.ReadableByteChannel

Parameters:

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read into dst, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.lang.NullPointerException - If dst is null.

InvalidWordLengthException - if the number of bytes to receive belies word length.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - If some other I/O error occurs

read

int read(int skip,
       java.nio.ByteBuffer dst)
         throws java.io.IOException,
                UnavailableDeviceException,
                ClosedDeviceException

Reads a sequence of bytes from this device into the given buffer, skipping the first skip bytes read.

Dummy data will be sent to this slave device by the platform.

Apart from skipping the first skip bytes, this method behaves identically to read(java.nio.ByteBuffer).

Parameters:

skip - the number of read bytes that must be ignored/skipped before filling in the dst buffer.

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read into dst, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.lang.NullPointerException - If dst is null.

java.lang.IllegalArgumentException - If skip is negative.

InvalidWordLengthException - if the total number of bytes to receive belies word length.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - If some other I/O error occurs

write

int write(java.nio.ByteBuffer src)
          throws java.io.IOException,
                 UnavailableDeviceException,
                 ClosedDeviceException

Writes a sequence of bytes to this slave device from the given buffer.

Specified by:

write in interface java.nio.channels.WritableByteChannel

Parameters:

src - The buffer from which bytes are to be retrieved

Returns:

The number of bytes written from src, possibly zero

Throws:

java.lang.NullPointerException - If src is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - If some other I/O error occurs

write

void write(int txData)
           throws java.io.IOException,
                  UnavailableDeviceException,
                  ClosedDeviceException

Writes one data word of up to 32 bits to this slave device.

Parameters:

txData - the data word to be written

Throws:

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

InvalidWordLengthException - if the number of bytes to send belies word length; that is this slave's word length is bigger than 32 bits.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

writeAndRead

int writeAndRead(java.nio.ByteBuffer src,
               java.nio.ByteBuffer dst)
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Exchanges (transmits and receives) data with this slave device.

The designated portions of the sending and receiving byte buffers may not have the same length. When sending more than is being received the extra received bytes are ignored/discarded. Conversely, when sending less than is being received extra dummy data will be sent.

This method behaves as a combined write(java.nio.ByteBuffer) and read(java.nio.ByteBuffer).

Parameters:

src - The buffer from which bytes are to be retrieved

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read into dst, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.lang.NullPointerException - If src or dst is null.

InvalidWordLengthException - if the number of bytes to receive or send belies word length.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - If some other I/O error occurs

writeAndRead

int writeAndRead(java.nio.ByteBuffer src,
               int skip,
               java.nio.ByteBuffer dst)
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Exchanges (transmits and receives) data with this slave device skipping the specified number of bytes received.

The designated portions of the sending and receiving byte buffers may not have the same length. When sending more than is being received the extra received bytes are ignored/discarded. Conversely, when sending less than is being received extra dummy data will be sent.

This method behaves as a combined write(java.nio.ByteBuffer) and read(java.nio.ByteBuffer).

Parameters:

src - The buffer from which bytes are to be retrieved

skip - the number of received bytes that must be ignored/skipped before filling in the dst buffer.

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read into dst, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.lang.NullPointerException - If src or dst is null.

java.lang.IllegalArgumentException - If skip is negative.

InvalidWordLengthException - if the total number of bytes to receive or send belies word length.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - If some other I/O error occurs

writeAndRead

int writeAndRead(int txData)
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Exchanges (transmits and receives) one data word of up to 32 bits with this slave device.

Parameters:

txData - the word to send.

Returns:

the word received.

Throws:

java.io.IOException - if some other I/O error occurs.

InvalidWordLengthException - if the numbers of bytes to send or to receive bely word length; that is this slave's word length is bigger than 32 bits.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.