com.oracle.deviceaccess.spibus

Interface SPIDevice

All Superinterfaces:

Peripheral, Transactional

public interface SPIDevice
extends Peripheral, Transactional

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

Each SPI slave device is identified by a numerical ID and by a name.
An SPIDevice instance can be opened by a call to one of the PeripheralManager.open() methods.

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)

When the data exchange is over, an application should call the SPIDevice.close() method to release 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 PeripheralNotAvailableException been thrown.

See Also:

InvalidWordLengthException, PeripheralNotAvailableException

Field Summary

Fields inherited from interface com.oracle.deviceaccess.Peripheral

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN, UNDEFINED_ID

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(byte[] rxBuf, int rxOff, int rxLen) Receives/reads up to rxLen bytes of data from this slave device into an array of bytes.
int	read(int skip, byte[] rxBuf, int rxOff, int rxLen) Receives/reads up to rxLen bytes of data from this slave device into an array of bytes skipping the first skip bytes read.
void	write(byte[] txBuf, int txOff, int txLen) Transmits/writes data to this slave device.
void	write(int txData) Writes one data word of up to 32 bits to this slave device.
int	writeAndRead(byte[] txBuf, int txOff, int txLen, byte[] rxBuf, int rxOff, int rxLen) Exchanges (transmits and receives) data with this slave device.
int	writeAndRead(byte[] txBuf, int txOff, int txLen, int skip, byte[] rxBuf, int rxOff, int rxLen) 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 com.oracle.deviceaccess.Peripheral

close, getID, getName, getProperties, isOpen

Method Detail

begin

void begin()
           throws java.io.IOException,
                  PeripheralNotAvailableException

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:

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.io.IOException - if an IO error occurred.

InvalidStateException - if a transaction is already in progress.

end

void end()
         throws java.io.IOException,
                PeripheralNotAvailableException

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

Specified by:

end in interface Transactional

Throws:

java.io.IOException - if an IO error occurred.

InvalidStateException - if a transaction is not currently in progress.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

getWordLength

int getWordLength()
                  throws java.io.IOException,
                         PeripheralNotAvailableException

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 an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

read

int read()
         throws java.io.IOException,
                PeripheralNotAvailableException

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

Returns:

the data word read.

Throws:

java.io.IOException - if an 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.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

read

int read(byte[] rxBuf,
       int rxOff,
       int rxLen)
         throws java.io.IOException,
                PeripheralNotAvailableException

Receives/reads up to rxLen bytes of data from this slave device into an array of bytes.

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

The length of the designated portion of the receiving byte buffers must correspond to a (positive) integral number of words.

Parameters:

rxBuf - buffer for the received bytes.

rxOff - the offset in rxBuf where to start copying the bytes received.

rxLen - the number of bytes to receive.

Returns:

the total number of bytes copied into the buffer.

Throws:

java.io.IOException - if an IO error occurred.

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

java.lang.NullPointerException - If rxBuf is null.

java.lang.IndexOutOfBoundsException - rxOff or rxLen points or results in pointing outside rxBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

read

int read(int skip,
       byte[] rxBuf,
       int rxOff,
       int rxLen)
         throws java.io.IOException,
                PeripheralNotAvailableException

Receives/reads up to rxLen bytes of data from this slave device into an array of bytes skipping the first skip bytes read.

Parameters:

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

rxBuf - buffer for the received bytes.

rxOff - the offset in rxBuf where to start copying the bytes received.

rxLen - the number of bytes to receive.

Returns:

the total number of bytes copied into the buffer.

Throws:

java.io.IOException - if an IO error occurred.

InvalidWordLengthException - if the total number of bytes to receive (skip + rxLen ) belies word length.

java.lang.NullPointerException - If rxBuf is null.

java.lang.IndexOutOfBoundsException - rxOff or rxLen points or results in pointing outside rxBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

write

void write(byte[] txBuf,
         int txOff,
         int txLen)
           throws java.io.IOException,
                  PeripheralNotAvailableException

Transmits/writes data to this slave device.

Received data will be ignored.

The length of the designated portion of the sending byte buffers must correspond to a (positive) integral number of words.

Parameters:

txBuf - the buffer containing the bytes to send.

txOff - the offset in txBuf of the first byte to send.

txLen - the number of bytes from txBuf to send.

Throws:

java.io.IOException - if an IO error occurred.

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

java.lang.NullPointerException - If txBuf is null.

java.lang.IndexOutOfBoundsException - txOff or txLen points or results in pointing outside txBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

write

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

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.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

writeAndRead

int writeAndRead(byte[] txBuf,
               int txOff,
               int txLen,
               byte[] rxBuf,
               int rxOff,
               int rxLen)
                 throws java.io.IOException,
                        PeripheralNotAvailableException

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.

Parameters:

txBuf - the buffer containing the bytes to send.

txOff - the offset in txBuf of the first byte to send.

txLen - the number of bytes from txBuf to send.

rxBuf - the buffer for the received bytes.

rxOff - the offset in rxBuf where to start copying the bytes received.

rxLen - the number of bytes to receive.

Returns:

the total number of bytes copied into the buffer rxBuf.

Throws:

java.io.IOException - if an IO error occurred.

InvalidWordLengthException - if the numbers of bytes to send or to receive bely word length.

java.lang.NullPointerException - If txBuf or rxBuf is null.

java.lang.IndexOutOfBoundsException - txOff, txLen, rxOff or rxLen points or results in pointing outside txBuf or rxBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

writeAndRead

int writeAndRead(byte[] txBuf,
               int txOff,
               int txLen,
               int skip,
               byte[] rxBuf,
               int rxOff,
               int rxLen)
                 throws java.io.IOException,
                        PeripheralNotAvailableException

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.

Parameters:

txBuf - the buffer containing the bytes to send.

txOff - the offset in txBuf of the first byte to send.

txLen - the number of bytes from txBuf to send.

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

rxBuf - buffer for the received bytes.

rxOff - the offset in rxBuf where to start copying the bytes received.

rxLen - the number of bytes to receive.

Returns:

the total number of bytes copied into the buffer rxBuf.

Throws:

java.io.IOException - if an IO error occurred.

InvalidWordLengthException - if the numbers of bytes to send or to receive bely word length.

java.lang.NullPointerException - If txBuf or rxBuf is null.

java.lang.IndexOutOfBoundsException - txOff, txLen, rxOff or rxLen points or results in pointing outside txBuf or rxBuf.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

writeAndRead

int writeAndRead(int txData)
                 throws java.io.IOException,
                        PeripheralNotAvailableException

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 an IO error occurred.

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.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).