changeset 124:24c0e0ad84bc

8076336: DAAPI 1.1 Adding UnsupportedByteOrderException Summary: The fix add UnsupportedByteOrderException Reviewed-by: snazarki
author amironov
date Tue, 31 Mar 2015 20:05:25 +0300
parents b545e51fda12
children 59f15c907e91 272acbd84e9c
files src/share/classes/jdk/dio/Device.java src/share/classes/jdk/dio/UnsupportedByteOrderException.java src/share/classes/jdk/dio/adc/ADCChannel.java src/share/classes/jdk/dio/dac/DACChannel.java src/share/classes/jdk/dio/generic/GenericBufferIODevice.java src/share/classes/jdk/dio/pwm/PWMChannel.java src/share/classes/jdk/dio/spibus/SPIDevice.java
diffstat 7 files changed, 206 insertions(+), 82 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/jdk/dio/Device.java	Fri Mar 27 12:28:09 2015 +0300
+++ b/src/share/classes/jdk/dio/Device.java	Tue Mar 31 20:05:25 2015 +0300
@@ -39,6 +39,15 @@
  * mode by the same application, locking one of the {@code Device} instances will prevent the
  * other form being accessed/used.
  *
+ * <h3><a name="byte_order">Device Byte Order</a></h3>
+ * Devices that perform multi-byte value I/O operations have a "native" byte order
+ * (see {@link #getByteOrder getByteOrder}).
+ * Passing to such a device a buffer with a byte order different from its native
+ * byte order may result in byte re-ordering (byte order conversion). These byte
+ * re-ordering may have an impact on performance, memory consumption and I/O throughput.
+ * On resource-constrained platforms a device driver may throw an {@link UnsupportedByteOrderException} when a
+ * byte re-ordering may induce a detrimental loss of quality or performance.
+ *
  * @param <P>
  *            the device type the descriptor is defined for.
  * @since 1.0
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/share/classes/jdk/dio/UnsupportedByteOrderException.java	Tue Mar 31 20:05:25 2015 +0300
@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package jdk.dio;
+
+/**
+ * Thrown by a {@link Device} to indicate that the attempted I/O operation does
+ * not support the byte ordering of the provided {@link java.nio.Buffer} or that the
+ * needed byte re-ordering would induce a detrimental loss of performance or quality
+ * on the intended I/O operation.
+ *
+ * @since 1.1
+ */
+public class UnsupportedByteOrderException extends DeviceException {
+
+    /**
+     * Constructs a new {@code UnsupportedByteOrderException} instance with {@code null} as
+     * its detailed reason message.
+     */
+    public UnsupportedByteOrderException() {
+        super();
+    }
+
+    /**
+     * Constructs a new {@code UnsupportedByteOrderException} instance with the specified
+     * detailed reason message. The error message string {@code message} can later be retrieved by
+     * the {@link Throwable#getMessage() getMessage} method.
+     *
+     * @param message
+     *            the detailed reason of the exception
+     */
+    public UnsupportedByteOrderException(String message) {
+        super(message);
+    }
+}
--- a/src/share/classes/jdk/dio/adc/ADCChannel.java	Fri Mar 27 12:28:09 2015 +0300
+++ b/src/share/classes/jdk/dio/adc/ADCChannel.java	Tue Mar 31 20:05:25 2015 +0300
@@ -30,6 +30,7 @@
 import jdk.dio.DeviceManager;
 import jdk.dio.ClosedDeviceException;
 import jdk.dio.UnavailableDeviceException;
+import jdk.dio.UnsupportedByteOrderException;
 import java.io.IOException;
 import java.nio.*;
 import romizer.WeakDontRenameClass;
@@ -344,21 +345,23 @@
      *            input values have been read.
      * @throws NullPointerException
      *             If {@code dst} or {@code listener} is {@code null}.
-     * @throws IOException
-     *             if some other I/O error occurs.
+     * @throws IllegalStateException
+     *             if another synchronous or asynchronous acquisition is already active.
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another
      *             application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
-     * @throws IllegalStateException
-     *             if another synchronous or asynchronous acquisition is already active.
+     * @throws IOException
+     *             if some other I/O error occurs.
      * @throws UnsupportedOperationException
      *             if an asynchronous monitoring is already active and acquisition and monitoring
      *             cannot be performed concurrently.
      */
     void startAcquisition(IntBuffer dst, AcquisitionRoundListener listener) throws IOException,
-            UnavailableDeviceException, ClosedDeviceException;
+            UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Starts asynchronous analog input acquisition on this channel and reads a series of raw
@@ -407,24 +410,26 @@
      *            input values have been read.
      * @throws NullPointerException
      *             If {@code dst1}, {@code dst2} or {@code listener} is {@code null}.
-     * @throws IOException
-     *             if some other I/O error occurs.
-     * @throws UnavailableDeviceException
-     *             if this device is not currently available - such as it is locked by another
-     *             application.
-     * @throws ClosedDeviceException
-     *             if the device has been closed.
      * @throws IllegalStateException
      *             if another synchronous or asynchronous acquisition is already active.
      * @throws IllegalArgumentException
      *             if any of the buffers {@code dst1} and {@code dst2} has a zero-capacity or
      *             if they are the same or overlap.
+     * @throws UnavailableDeviceException
+     *             if this device is not currently available - such as it is locked by another
+     *             application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the any of the provided buffers is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
+     * @throws ClosedDeviceException
+     *             if the device has been closed.
+     * @throws IOException
+     *             if some other I/O error occurs.
      * @throws UnsupportedOperationException
      *             if an asynchronous monitoring is already active and acquisition and monitoring
      *             cannot be performed concurrently.
      */
     void startAcquisition(IntBuffer dst1, IntBuffer dst2, AcquisitionRoundListener listener) throws IOException,
-            UnavailableDeviceException, ClosedDeviceException;
+            UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Starts monitoring this channel analog input and asynchronously notifies the provided
--- a/src/share/classes/jdk/dio/dac/DACChannel.java	Fri Mar 27 12:28:09 2015 +0300
+++ b/src/share/classes/jdk/dio/dac/DACChannel.java	Tue Mar 31 20:05:25 2015 +0300
@@ -25,11 +25,8 @@
 
 package jdk.dio.dac;
 
-import jdk.dio.BufferAccess;
-import jdk.dio.Device;
-import jdk.dio.DeviceManager;
-import jdk.dio.ClosedDeviceException;
-import jdk.dio.UnavailableDeviceException;
+import jdk.dio.*;
+
 import java.io.IOException;
 import java.nio.IntBuffer;
 import romizer.WeakDontRenameClass;
@@ -275,19 +272,21 @@
      *
      * @param src
      *            the buffer from which the integer raw values can be retrieved.
-     * @throws IOException
-     *             if some other I/O error occurs.
      * @throws NullPointerException
      *             If {@code src} is {@code null}.
+     * @throws IllegalStateException
+     *             if an asynchronous output generation is already active.
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another
      *             application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
-     * @throws IllegalStateException
-     *             if an asynchronous output generation is already active.
+     * @throws IOException
+     *             if some other I/O error occurs.
      */
-    void generate(IntBuffer src) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    void generate(IntBuffer src) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Starts asynchronous analog output generation on this channel from a series of raw output
@@ -309,10 +308,18 @@
      * buffer's position will be equal to <i>{@code p + n}</i>; its limit will not have changed. <br />
      * The buffer's position upon stopping this asynchronous operation by a call to
      * {@link #stopGeneration stopGeneration} is not predictable unless called from within the
-     * listener..
+     * listener. <br />
+     * If the provided {@code src} buffer is a direct buffer fulfilling the direct
+     * I/O requirements of this device (see {@link #prepareBuffer(java.nio.Buffer, int) prepareBuffer}) then the listener will only
+     * be invoked after all the <i>r</i> raw output values remaining in the provided
+     * {@code src} buffer have been consumed by the driver/hardware. If this channel
+     * uses an output buffer and is therefore working in buffering mode the listener will only be
+     * invoked after all the <i>r</i> raw output values have been copied to the
+     * output buffer; otherwise the listener will only be invoked after all the
+     * <i>r</i> raw output values have been consumed by the driver/hardware.
      * <p />
      * The raw output values (samples) will be converted according to the current output sampling
-     * interval as returned by {@link #getSamplingInterval getSamplingInterval}.
+     * interval as returned by {@link #getSamplingRate getSamplingRate}.
      * <p />
      * Upon notification of the provided {@code GenerationRoundListener}
      * the reference to the provided {@code src} buffer can be retrieved from the
@@ -341,24 +348,26 @@
      * significant bits beyond the {@code n} bits of the DAC device resolution have been truncated.
      *
      * @param src
-     *            the buffer from which the integer raw sampled input values are to be retrieved.
+     *            the buffer from which the integer raw sampled output values are to be retrieved.
      * @param listener
      *            the {@link GenerationRoundListener} instance to be notified when all the output
      *            values have been converted.
      * @throws NullPointerException
      *             If {@code src} or {@code listener} is {@code null}.
-     * @throws IOException
-     *             if some other I/O error occurs.
+     * @throws IllegalStateException
+     *             if another synchronous or asynchronous output generation is already active.
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another
      *             application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
-     * @throws IllegalStateException
-     *             if another synchronous or asynchronous output generation is already active.
+     * @throws IOException
+     *             if some other I/O error occurs.
      */
     void startGeneration(IntBuffer src, GenerationRoundListener listener) throws IOException,
-            UnavailableDeviceException, ClosedDeviceException;
+            UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Starts asynchronous analog output generation on this channel from a series of raw output
@@ -374,7 +383,15 @@
      * will only be suspended if the previous event has not yet been handled. Also,
      * the position of the current working buffer upon stopping this asynchronous operation by a call to
      * {@link #stopGeneration stopGeneration} is not predictable even if called from within the
-     * listener.
+     * listener. <br />
+     * If both buffers are direct buffer fulfilling the direct I/O requirements of
+     * this device (see {@link #prepareBuffer(java.nio.Buffer, int) prepareBuffer} ) then the
+     * listener will only be invoked after all the raw output values remaining in
+     * the current working buffer are consumed by the driver/hardware; otherwise if this
+     * channel uses an output buffer and is therefore working in buffering mode
+     * the listener will only
+     * be invoked after all the raw output values remaining in the current working
+     * buffer have been copied to the output buffer.
      * <p />
      * Upon notification of the provided {@code GenerationRoundListener}
      * the reference to the  current working buffer (initially {@code src1}) can be retrieved from the
@@ -403,31 +420,33 @@
      * significant bits beyond the {@code n} bits of the DAC device resolution have been truncated.
      *
      * @param src1
-     *            the first buffer from which the integer raw sampled input values are to be
+     *            the first buffer from which the integer raw sampled output values are to be
      *            retrieved.
      * @param src2
-     *            the second buffer from which the integer raw sampled input values are to be
+     *            the second buffer from which the integer raw sampled output values are to be
      *            retrieved.
      * @param listener
      *            the {@link GenerationRoundListener} instance to be notified when all the output
      *            values have been converted.
      * @throws NullPointerException
      *             If {@code src1}, {@code src2} or {@code listener} is {@code null}.
-     * @throws IOException
-     *             if some other I/O error occurs.
-     * @throws UnavailableDeviceException
-     *             if this device is not currently available - such as it is locked by another
-     *             application.
-     * @throws ClosedDeviceException
-     *             if the device has been closed.
      * @throws IllegalStateException
      *             if another synchronous or asynchronous output generation is already active.
      * @throws IllegalArgumentException
      *             if any of the buffers {@code src1} and {@code src2} has a zero-capacity or
      *             if they are the same or overlap.
+     * @throws UnavailableDeviceException
+     *             if this device is not currently available - such as it is locked by another
+     *             application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the any of the provided buffers is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
+     * @throws ClosedDeviceException
+     *             if the device has been closed.
+     * @throws IOException
+     *             if some other I/O error occurs.
      */
     void startGeneration(IntBuffer src1, IntBuffer src2, GenerationRoundListener listener) throws IOException,
-            UnavailableDeviceException, ClosedDeviceException;
+            UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Stops the asynchronous analog output generation on this channel as started by a call to one
--- a/src/share/classes/jdk/dio/generic/GenericBufferIODevice.java	Fri Mar 27 12:28:09 2015 +0300
+++ b/src/share/classes/jdk/dio/generic/GenericBufferIODevice.java	Tue Mar 31 20:05:25 2015 +0300
@@ -28,6 +28,7 @@
 import jdk.dio.BufferAccess;
 import jdk.dio.ClosedDeviceException;
 import jdk.dio.UnavailableDeviceException;
+import jdk.dio.UnsupportedByteOrderException;
 import java.io.*;
 import java.nio.*;
 import java.nio.channels.ByteChannel;
@@ -64,13 +65,15 @@
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another
      *             application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
      * @throws IOException
      *             if an I/O error occurred such as the device is not readable.
      */
     @Override
-    int read(ByteBuffer dst) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    int read(ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Reads a sequence of bytes from this device into the given buffer, skipping the first
@@ -93,12 +96,14 @@
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another
      *             application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
      * @throws IOException
      *             if an I/O error occurred such as the device is not readable.
      */
-    int read(int skip, ByteBuffer dst) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    int read(int skip, ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Writes a sequence of bytes to this device from the given buffer.
@@ -116,11 +121,13 @@
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another
      *             application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
      * @throws IOException
      *             if an I/O error occurred such as the device is not writable.
      */
     @Override
-    int write(ByteBuffer src) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    int write(ByteBuffer src) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 }
--- a/src/share/classes/jdk/dio/pwm/PWMChannel.java	Fri Mar 27 12:28:09 2015 +0300
+++ b/src/share/classes/jdk/dio/pwm/PWMChannel.java	Tue Mar 31 20:05:25 2015 +0300
@@ -30,6 +30,7 @@
 import jdk.dio.Device;
 import jdk.dio.DeviceManager;
 import jdk.dio.UnavailableDeviceException;
+import jdk.dio.UnsupportedByteOrderException;
 import java.io.IOException;
 import java.nio.IntBuffer;
 import romizer.WeakDontRenameClass;
@@ -202,7 +203,7 @@
      * <p />
      * The operation will return only after generating all of the <i>r</i> requested pulses.
      * <p />
-     * The pulses will be generated according to the current pulse period as returned by {@link #getPulsePeriod getPulsePeriod}.
+     * The pulses will be generated according to the current pulse rate as returned by {@link #getPulseRate getPulseRate}.
      * <p />
      * This method may be invoked at any time. If another thread has already initiated a synchronous pulse generation
      * upon this channel, however, then an invocation of this method will block until the first operation is complete.
@@ -222,18 +223,20 @@
      *
      * @param src
      *            the buffer from which the pulse width integer values can be retrieved.
+     * @throws NullPointerException
+     *             If {@code src} is {@code null}.
+     * @throws IllegalStateException
+     *             if an asynchronous pulse generation is already active.
+     * @throws UnavailableDeviceException
+     *             if this device is not currently available - such as it is locked by another application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
+     * @throws ClosedDeviceException
+     *             if the device has been closed.
      * @throws IOException
      *             if some other I/O error occurs.
-     * @throws NullPointerException
-     *             If {@code src} is {@code null}.
-     * @throws UnavailableDeviceException
-     *             if this device is not currently available - such as it is locked by another application.
-     * @throws ClosedDeviceException
-     *             if the device has been closed.
-     * @throws IllegalStateException
-     *             if an asynchronous pulse generation is already active.
      */
-    void generate(IntBuffer src) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    void generate(IntBuffer src) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Starts an asynchronous pulse train generation session - continuously generating pulses of the specified width
@@ -332,8 +335,8 @@
      * The buffer's position upon stopping this asynchronous operation by a call to {@link #stopGeneration stopGeneration}
      * is not predictable unless called from within the listener.
      * <p />
-     * The pulses will be generated according to the current pulse period as returned by {@link #getPulsePeriod getPulsePeriod}. The
-     * pulse period can be changed by the provided {@link GenerationRoundListener} instance upon notification of each
+     * The pulses will be generated according to the current pulse rate as returned by {@link #getPulseRate getPulseRate}. The
+     * pulse rate can be changed by the provided {@link GenerationRoundListener} instance upon notification of each
      * pulse train subsequence.
      * <p />
      * Upon notification of the provided {@code GenerationRoundListener}
@@ -372,17 +375,19 @@
      *            the width values remaining in the buffer.
      * @throws NullPointerException
      *             If {@code src} or {@code listener} is {@code null}.
+     * @throws IllegalStateException
+     *             if another synchronous or asynchronous output generation is already active.
+     * @throws UnavailableDeviceException
+     *             if this device is not currently available - such as it is locked by another application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffers is not supported.
+     * @throws ClosedDeviceException
+     *             if the device has been closed.
      * @throws IOException
      *             if some other I/O error occurs.
-     * @throws UnavailableDeviceException
-     *             if this device is not currently available - such as it is locked by another application.
-     * @throws ClosedDeviceException
-     *             if the device has been closed.
-     * @throws IllegalStateException
-     *             if another synchronous or asynchronous output generation is already active.
      */
     void startGeneration(IntBuffer src, GenerationRoundListener listener) throws IOException,
-            UnavailableDeviceException, ClosedDeviceException;
+            UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Starts asynchronous pulse train generation in successive rounds.
@@ -435,20 +440,22 @@
      *            the width values remaining in the working buffer.
      * @throws NullPointerException
      *             If {@code src1}, {@code src2} or {@code listener} is {@code null}.
-     * @throws IOException
-     *             if some other I/O error occurs.
-     * @throws UnavailableDeviceException
-     *             if this device is not currently available - such as it is locked by another application.
-     * @throws ClosedDeviceException
-     *             if the device has been closed.
      * @throws IllegalStateException
      *             if another synchronous or asynchronous output generation is already active.
      * @throws IllegalArgumentException
      *             if any of the buffers {@code src1} and {@code src2} has a zero-capacity or
      *             if they are the same or overlap.
+     * @throws UnavailableDeviceException
+     *             if this device is not currently available - such as it is locked by another application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the any of the provided buffers is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
+     * @throws ClosedDeviceException
+     *             if the device has been closed.
+     * @throws IOException
+     *             if some other I/O error occurs.
      */
     void startGeneration(IntBuffer src1, IntBuffer src2, GenerationRoundListener listener) throws IOException,
-            UnavailableDeviceException, ClosedDeviceException;
+            UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Stops (cancels) the currently active pulse generation session as started by a call to one
--- a/src/share/classes/jdk/dio/spibus/SPIDevice.java	Fri Mar 27 12:28:09 2015 +0300
+++ b/src/share/classes/jdk/dio/spibus/SPIDevice.java	Tue Mar 31 20:05:25 2015 +0300
@@ -30,6 +30,7 @@
 import jdk.dio.DeviceManager;
 import jdk.dio.ClosedDeviceException;
 import jdk.dio.UnavailableDeviceException;
+import jdk.dio.UnsupportedByteOrderException;
 import java.io.IOException;
 import java.nio.*;
 import java.nio.channels.ByteChannel;
@@ -58,18 +59,28 @@
  * data received from the SPI slave device will be ignored/discarded. When reading only, dummy data will be sent to the
  * slave.
  * <p/>
- * A data exchange consists of words of a certain length which may vary from SPI slave device to SPI slave device. <br />
- * 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
+ * A data exchange consists of words of a certain length which may vary from SPI
+ * slave device to SPI slave device. <br />
+ * Words in the sending and receiving byte buffers are not packed (bit-wise) and
+ * must be byte-aligned; bytes are copied out or in, respectively, from/to these
+ * buffers according to their byte orders (see
+ * {@link ByteBuffer#order() ByteBuffer.order}) and the bits are shifted out or
+ * in, respectively, according to the bit ordering configured for the device
+ * (see
+ * {@link SPIDeviceConfig#getBitOrdering() SPIDeviceConfig.getBitOrdering}).
+ * 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 {@link 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 {@link InvalidWordLengthException} will be
  * thrown. <br />
  * Assuming a word length <em>w</em>, the length <em>l</em> of the designated portion of the sending or receiving byte
- * buffer must be such that: <br />
- * <em>((l % (((w - 1) / 8) + 1)) == 0)</em>
- * <p />
+ * buffer must be such that:
+ * <blockquote>
+ * <pre>
+ * {@code ((l % (((w - 1) / 8) + 1)) == 0)}
+ * </pre>
+ * </blockquote>
  * Since the SPI master device controls the serial transmission clock read and write operations are never blocked nor delayed by
  * unresponsive slave devices. Not though that a read or write operation may be blocked if another read or write operation
  * is concurrently being performed on the same {@code SPIDevice} instance.
@@ -180,13 +191,15 @@
      *             if the number of bytes to receive belies word length.
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
      * @throws IOException
      *             if some other I/O error occurs.
      */
     @Override
-    int read(ByteBuffer dst) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    int read(ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Reads a sequence of bytes from this device into the given buffer, skipping the first {@code skip} bytes read.
@@ -211,12 +224,14 @@
      *             if the total number of bytes to receive belies word length.
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
      * @throws IOException
      *             if some other I/O error occurs.
      */
-    int read(int skip, ByteBuffer dst) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    int read(int skip, ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Writes a sequence of bytes to this slave device from the given buffer.
@@ -246,13 +261,15 @@
      *             if {@code src} is {@code null}.
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the provided buffer is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
      * @throws IOException
      *             if some other I/O error occurs.
      */
     @Override
-    int write(ByteBuffer src) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    int write(ByteBuffer src) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Writes one data word of up to 32 bits to this slave device.
@@ -296,12 +313,14 @@
      *             if the number of bytes to receive or send belies word length.
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the any of the provided buffers is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
      * @throws IOException
      *             if some other I/O error occurs.
      */
-    int writeAndRead(ByteBuffer src, ByteBuffer dst) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    int writeAndRead(ByteBuffer src, ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Exchanges (transmits and receives) data with this slave device skipping the specified number of bytes received.
@@ -328,12 +347,14 @@
      *             if the total number of bytes to receive or send belies word length.
      * @throws UnavailableDeviceException
      *             if this device is not currently available - such as it is locked by another application.
+     * @throws UnsupportedByteOrderException
+     *             if the byte ordering of the any of the provided buffers is not supported (see <a href="{@docRoot}/jdk/dio/Device.html#byte_order">Device Byte Order</a>).
      * @throws ClosedDeviceException
      *             if the device has been closed.
      * @throws IOException
      *             if some other I/O error occurs.
      */
-    int writeAndRead(ByteBuffer src, int skip, ByteBuffer dst) throws IOException, UnavailableDeviceException, ClosedDeviceException;
+    int writeAndRead(ByteBuffer src, int skip, ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException;
 
     /**
      * Exchanges (transmits and receives) one data word of up to 32 bits with this slave device.