com.oracle.deviceaccess.spibus
Interface SPISlave

All Superinterfaces:

Peripheral

public interface SPISlave
extends Peripheral

The SPISlave 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 SPISlave instance can be retrieved by a call to SPIManager.getSlave(int) or SPIManager.getSlave(java.lang.String).

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 at the same time data is received from the SPI slave by the SPI master.

To perform such an exchange of data with an SPI slave, an application may use one of the exchange methods.
When an application only wants to send data to or receive data from an SPI slave, it may use the write or the read method, respectively. When writing only, the data received from the SPI slave 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 to SPI slave.
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 SPISlave.close() method to release the SPI slave. Any further attempt to transmit/write or receive/read to/from an SPI slave which has been released will result in a PeripheralNotAvailableException been thrown.

Note that the appropriate SPI clock frequency, polarity and phase as well as finer slave select line handling (whether it remains asserted during a series of word exchanges), the endianness, the word length and the dummy writing data for exchanging data with a particular SPI slave device are set by the platform.

See Also:

SPIManager, SPIPermission, InvalidWordLengthException, PeripheralNotAvailableException

Method Summary

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)
int	read(int rxSkip, byte[] rxBuf, int rxOff, int rxLen)
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)
int	writeAndRead(byte[] txBuf, int txOff, int txLen, int rxSkip, byte[] rxBuf, int rxOff, int rxLen) Send and Receive data.
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

Method Detail

writeAndRead

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

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:

rxLen

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 released).

writeAndRead

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

Send and Receive data. Transmit data to/from current slave.

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.

rxSkip - - 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:

rxLen

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 released).

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 released).

write

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

Transmits/writes data to this slave device.

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 released).

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 numbers of bytes to send 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 released).

read

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

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.

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 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 released).

read

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

Parameters:

rxSkip - - 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.

Throws:

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

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

read

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

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

Throws:

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

InvalidWordLengthException - - if the numbers of bytes 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 released).

getWordLength

int getWordLength()

Gets the transfer word length in bits supported by this slave device. If the length of data to be writeAndReadd belies a slave's word length an InvalidWordLengthException will be thrown.

Returns:

this slave's transfer word length in bits.