All Downloads are FREE. Search and download functionalities are using the official Maven repository.

jdk.dio.spibus.SPIDeviceConfig Maven / Gradle / Ivy

The newest version!
/*
 * 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.spibus;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Objects;

import com.oracle.dio.impl.Platform;
import com.oracle.dio.utils.Utils;

import jdk.dio.DeviceConfig;
import jdk.dio.DeviceManager;
import jdk.dio.InvalidDeviceConfigException;

import romizer.DontRenameMethod;

import serializator.*;

/**
 * The {@code SPIDeviceConfig} class encapsulates the hardware addressing information, and static and dynamic
 * configuration parameters of an SPI slave device.
 * 

* Some hardware addressing, static or dynamic configuration parameters may be * set to {@link #UNASSIGNED UNASSIGNED} or {@code null} (see * Unassigned, Default or Unused Parameter Values). *

*

SPI Clock Modes

* The clock mode is a number from 0 to 3 which represents the combination of the CPOL (SPI Clock Polarity Bit) and CPHA * (SPI Clock Phase Bit) signals where CPOL is the high order bit and CPHA is the low order bit: *
* * * * * * * * * * * * * * * * * * * * * * * * * *
ModeCPOLCPHA
00 = Active-high clocks selected.0 = Sampling of data occurs at odd edges of the SCK clock
10 = Active-high clocks selected.1 = Sampling of data occurs at even edges of the SCK clock
21 = Active-low clocks selected.0 = Sampling of data occurs at odd edges of the SCK clock
31 = Active-low clocks selected.1 = Sampling of data occurs at even edges of the SCK clock
*

* An instance of {@code SPIDeviceConfig} can be passed to the {@link DeviceManager#open(DeviceConfig) open(DeviceConfig, ...)} and * {@link DeviceManager#open(Class, DeviceConfig) open(Class, DeviceConfig, ...)} * methods of the {@link DeviceManager} to open the designated SPI slave device with the * specified configuration. A {@link InvalidDeviceConfigException} is thrown when attempting to open a * device with an invalid or unsupported configuration. *

* * @see DeviceManager#open(DeviceConfig) * @see DeviceManager#open(DeviceConfig, int) * @see DeviceManager#open(Class, DeviceConfig) * @see DeviceManager#open(Class, DeviceConfig, int) * @since 1.0 */ @SerializeMe @apimarker.API("device-io_1.1_spibus") public final class SPIDeviceConfig implements DeviceConfig, DeviceConfig.HardwareAddressing { /** * High Chip Select active level. */ public static final int CS_ACTIVE_HIGH = 0; /** * Low Chip Select active level. */ public static final int CS_ACTIVE_LOW = 1; /** * Chip Select not controlled by driver. If this mode is configured, the Chip Select signal * is assumed to be controlled independently such as with an independent {@link jdk.dio.gpio.GPIOPin GPIOPin}. */ public static final int CS_NOT_CONTROLLED = 2; private String controllerName; private int address = UNASSIGNED; private int csActive = UNASSIGNED; private int controllerNumber = UNASSIGNED; private int bitOrdering = UNASSIGNED; private int clockFrequency = UNASSIGNED; private int clockMode; private int wordLength = UNASSIGNED; private int inputBufferSize = UNASSIGNED; private int outputBufferSize = UNASSIGNED; /** * The {@code Builder} class allows for creating and initializing * {@code SPIDeviceConfig} objects. Calls can be chained in the following * manner: *
*
     *   SPIDeviceConfig config = new SPIDeviceConfig.Builder()
     *           .setControllerNumber(1)
     *           .setAddress(0x8)
     *           .setClockFrequency(8000000)
     *           .setClockMode(2)
     *           .setWordLength(10)
     *           .setBitOrdering(LITTLE_ENDIAN)
     *           .build();
     * 
*
* * @since 1.1 */ @apimarker.API("device-io_1.1_spibus") public static final class Builder { private final SPIDeviceConfig instance = new SPIDeviceConfig(); /** * Creates a new {@code Builder} instance. */ public Builder() { } /** * Creates a new {@code SPIDeviceConfig} instance initialized with the * values set for each configuration parameters. If a configuration * parameter was not explictly set its default value will be used. * * @return a new initialized {@code SPIDeviceConfig} instance. * @throws IllegalStateException if any of the following is true: *
    *
  • the Chip Select address of the slave device on the bus is not set.
  • *
*/ public SPIDeviceConfig build() { if (UNASSIGNED == instance.address) { throw new IllegalStateException(); } return instance; } /** * Sets the name of the bus the slave device is connected to (default * value is {@code null} if not set). * * @param controllerName the name of the bus the slave device is * connected to (such as its device file name on UNIX systems) or {@code null}. * @return this {@code Builder} instance. */ public Builder setControllerName(String controllerName) { instance.controllerName = controllerName; return this; } /** * Sets the Chip Select address of the slave device on the bus. * * @param address the Chip Select address of the slave device on the bus * (a positive or zero integer). * @return this {@code Builder} instance. * @throws IllegalArgumentException if any of the following is true: *
    *
  • {@code address} is not in the defined range;
  • *
*/ public Builder setAddress(int address) { Utils.checkIntZeroOrPozitive(address); instance.address = address; return this; } /** * Sets the number of the bus the slave device is connected to (default * value is {@code UNASSIGNED} if not set). * * @param controllerNumber the number of the bus the slave device is * connected to (a positive or zero integer) or {@link #UNASSIGNED UNASSIGNED}. * @return this {@code Builder} instance. * @throws IllegalArgumentException if {@code controllerNumber} is not * in the defined range. */ public Builder setControllerNumber(int controllerNumber) { Utils.checkIntValue(controllerNumber); instance.controllerNumber = controllerNumber; return this; } /** * Sets the requested input buffer size (default value is * {@code UNASSIGNED} if not set). * * @param inputBufferSize the requested input buffer size in number of * samples (a positive or zero integer) or * {@code UNASSIGNED}. * @return this {@code Builder} instance. * @throws IllegalArgumentException if {@code inputBufferSize} is not in * the defined range. */ public Builder setInputBufferSize(int inputBufferSize) { Utils.checkIntValue(inputBufferSize); instance.inputBufferSize = inputBufferSize; return this; } /** * Sets the requested output buffer size (default value is * {@code UNASSIGNED} if not set). * * @param outputBufferSize the requested output buffer size in number of * samples (a positive or zero integer) or * {@code UNASSIGNED}. * @return this {@code Builder} instance. * @throws IllegalArgumentException if {@code outputBufferSize} is not * in the defined range. */ public Builder setOutputBufferSize(int outputBufferSize) { Utils.checkIntValue(outputBufferSize); instance.outputBufferSize = outputBufferSize; return this; } /** * Sets the Chip Select active level (default value is * {@code UNASSIGNED} if not set). * * @param csActive the Chip Select active level, one of {@link #CS_ACTIVE_LOW}, * {@link #CS_ACTIVE_HIGH}, {@link #CS_NOT_CONTROLLED} or * {@link #UNASSIGNED UNASSIGNED}. * @return this {@code Builder} instance. * @throws IllegalArgumentException if {@code csActive} is not in the * defined range. */ public Builder setCSActiveLevel(int csActive) { checkCsActive(csActive); instance.csActive = csActive; return this; } /** * Sets the bit (shifting) ordering of the slave device (default value * is {@code UNASSIGNED} if not set). * * @param bitOrdering the bit (shifting) ordering of the slave device, * one of: {@link SPIDevice#BIG_ENDIAN}, * {@link SPIDevice#LITTLE_ENDIAN}, {@link SPIDevice#MIXED_ENDIAN} or * {@link #UNASSIGNED UNASSIGNED}. * @return this {@code Builder} instance. * @throws IllegalArgumentException if {@code bitOrdering} is not in the * defined range. */ public Builder setBitOrdering(int bitOrdering) { checkBitOrdering(bitOrdering); instance.bitOrdering = bitOrdering; return this; } /** * Sets the clock mode (default value is {@code 0} if not set). * * @param clockMode the clock mode, one of: * {@code 0}, {@code 1}, {@code 2} or {@code 3} (see SPI * Clock Modes). * @return this {@code Builder} instance. * @throws IllegalArgumentException if {@code clockMode} is not in the * defined range. */ public Builder setClockMode(int clockMode) { checkClockMode(clockMode); instance.clockMode = clockMode; return this; } /** * Sets the word length of the slave device (default value is * {@code UNASSIGNED} if not set). * * @param wordLength the word length of the slave device (a positive * integer) or {@link #UNASSIGNED UNASSIGNED}. * @return this {@code Builder} instance. * @throws IllegalArgumentException if {@code wordLength} is not in the * defined range. */ public Builder setWordLength(int wordLength) { Utils.checkGreaterThanZero(wordLength); instance.wordLength = wordLength; return this; } /** * Sets the clock frequency of the slave device in Hz (default value is * {@code UNASSIGNED} if not set). * * @param clockFrequency the clock frequency of the slave device in Hz * (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @return this {@code Builder} instance. * @throws IllegalArgumentException if {@code clockFrequency} is not in * the defined range. */ public Builder setClockFrequency(int clockFrequency) { Utils.checkGreaterThanZero(clockFrequency); instance.clockFrequency = clockFrequency; return this; } } // hidden constructor for serializer @DontRenameMethod SPIDeviceConfig(){} /** * Creates a new {@code SPIDeviceConfig} with the specified hardware addressing information and configuration * parameters. The Chip Select active level is platform and/or driver-dependent (i.e. {@link #UNASSIGNED UNASSIGNED}). *

* The controller name is set to {@code null}. * The requested input and output buffer sizes are set to {@code UNASSIGNED}. *

* * @param controllerNumber * the number of the bus the slave device is connected to (a positive or zero integer) or * {@link #UNASSIGNED UNASSIGNED}. * @param address * the Chip Select address of the slave device on the bus (a positive or zero integer). * @param clockFrequency * the clock frequency of the slave device in Hz (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @param clockMode * the clock mode, one of: {@code 0}, {@code 1}, {@code 2} or {@code 3} (see SPI Clock * Modes). * @param wordLength * the word length of the slave device (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @param bitOrdering * the bit (shifting) ordering of the slave device, one of: {@link SPIDevice#BIG_ENDIAN}, * {@link SPIDevice#LITTLE_ENDIAN}, {@link SPIDevice#MIXED_ENDIAN} or {@link #UNASSIGNED UNASSIGNED}. * @throws IllegalArgumentException * if any of the following is true: *
    *
  • {@code controllerNumber} is not in the defined range;
  • *
  • {@code address} is not in the defined range;
  • *
  • {@code clockFrequency} is not in the defined range;
  • *
  • {@code clockMode} is not one of the defined values;
  • *
  • {@code wordLength} is not in the defined range;
  • *
  • {@code bitOrdering} is not one of the defined values.
  • *
* * @deprecated As of 1.1, use {@link Builder} instead. */ @Deprecated public SPIDeviceConfig(int controllerNumber, int address, int clockFrequency, int clockMode, int wordLength, int bitOrdering) { this(controllerNumber, address, UNASSIGNED, clockFrequency, clockMode, wordLength, bitOrdering); } /** * Creates a new {@code SPIDeviceConfig} with the specified hardware addressing information and configuration * parameters. *

* The controller name is set to {@code null}. * The requested input and output buffer sizes are set to {@code UNASSIGNED}. *

* * @param controllerNumber * the number of the bus the slave device is connected to (a positive or zero integer) or * {@link #UNASSIGNED UNASSIGNED}. * @param address * the Chip Select address of the slave device on the bus (a positive or zero integer). * @param csActive * the Chip Select active level, one of {@link #CS_ACTIVE_LOW}, * {@link #CS_ACTIVE_HIGH}, {@link #CS_NOT_CONTROLLED} or {@link #UNASSIGNED UNASSIGNED}. * @param clockFrequency * the clock frequency of the slave device in Hz (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @param clockMode * the clock mode, one of: {@code 0}, {@code 1}, {@code 2} or {@code 3} (see SPI Clock * Modes). * @param wordLength * the word length of the slave device (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @param bitOrdering * the bit (shifting) ordering of the slave device, one of: {@link SPIDevice#BIG_ENDIAN}, * {@link SPIDevice#LITTLE_ENDIAN}, {@link SPIDevice#MIXED_ENDIAN} or {@link #UNASSIGNED UNASSIGNED}. * @throws IllegalArgumentException * if any of the following is true: *
    *
  • {@code controllerNumber} is not in the defined range;
  • *
  • {@code address} is not in the defined range;
  • *
  • {@code clockFrequency} is not in the defined range;
  • *
  • {@code clockMode} is not one of the defined values;
  • *
  • {@code wordLength} is not in the defined range;
  • *
  • {@code bitOrdering} is not one of the defined values.
  • *
* * @deprecated As of 1.1, use {@link Builder} instead. */ @Deprecated public SPIDeviceConfig(int controllerNumber, int address, int csActive, int clockFrequency, int clockMode, int wordLength, int bitOrdering) { this.controllerNumber = controllerNumber; this.address = address; this.csActive = csActive; this.clockFrequency = clockFrequency; this.clockMode = clockMode; this.wordLength = wordLength; this.bitOrdering = bitOrdering; checkParameters(); } /** * Creates a new {@code SPIDeviceConfig} with the specified hardware addressing information and configuration * parameters. The Chip Select active level is platform and/or driver-dependent (i.e. {@link #UNASSIGNED UNASSIGNED}). *

* The controller number is set to {@code UNASSIGNED}. * The requested input and output buffer sizes are set to {@code UNASSIGNED}. *

* * @param controllerName * the controller name (such as its device file name on UNIX systems). * @param address * the Chip Select address of the slave device on the bus (a positive or zero integer). * @param clockFrequency * the clock frequency of the slave device in Hz (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @param clockMode * the clock mode, one of: {@code 0}, {@code 1}, {@code 2} or {@code 3} (see SPI Clock * Modes). * @param wordLength * the word length of the slave device (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @param bitOrdering * the bit (shifting) ordering of the slave device, one of: {@link SPIDevice#BIG_ENDIAN}, * {@link SPIDevice#LITTLE_ENDIAN}, {@link SPIDevice#MIXED_ENDIAN} or {@link #UNASSIGNED UNASSIGNED}. * @throws IllegalArgumentException * if any of the following is true: *
    *
  • {@code address} is not in the defined range;
  • *
  • {@code clockFrequency} is not in the defined range;
  • *
  • {@code clockMode} is not one of the defined values;
  • *
  • {@code wordLength} is not in the defined range;
  • *
  • {@code bitOrdering} is not one of the defined values.
  • *
* @throws NullPointerException * if {@code controllerName} is {@code null}. * * @deprecated As of 1.1, use {@link Builder} instead. */ @Deprecated public SPIDeviceConfig(String controllerName, int address, int clockFrequency, int clockMode, int wordLength, int bitOrdering) { this(controllerName, address, UNASSIGNED, clockFrequency, clockMode, wordLength, bitOrdering); } /** * Creates a new {@code SPIDeviceConfig} with the specified hardware addressing information and configuration * parameters. *

* The controller number is set to {@code UNASSIGNED}. * The requested input and output buffer sizes are set to {@code UNASSIGNED}. *

* * @param controllerName * the controller name (such as its device file name on UNIX systems). * @param address * the Chip Select address of the slave device on the bus (a positive or zero integer). * @param csActive * the Chip Select active level, one of {@link #CS_ACTIVE_LOW}, * {@link #CS_ACTIVE_HIGH}, {@link #CS_NOT_CONTROLLED} or {@link #UNASSIGNED UNASSIGNED}. * @param clockFrequency * the clock frequency of the slave device in Hz (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @param clockMode * the clock mode, one of: {@code 0}, {@code 1}, {@code 2} or {@code 3} (see SPI Clock * Modes). * @param wordLength * the word length of the slave device (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. * @param bitOrdering * the bit (shifting) ordering of the slave device, one of: {@link SPIDevice#BIG_ENDIAN}, * {@link SPIDevice#LITTLE_ENDIAN}, {@link SPIDevice#MIXED_ENDIAN} or {@link #UNASSIGNED UNASSIGNED}. * @throws IllegalArgumentException * if any of the following is true: *
    *
  • {@code address} is not in the defined range;
  • *
  • {@code clockFrequency} is not in the defined range;
  • *
  • {@code clockMode} is not one of the defined values;
  • *
  • {@code wordLength} is not in the defined range;
  • *
  • {@code bitOrdering} is not one of the defined values.
  • *
* @throws NullPointerException * if {@code controllerName} is {@code null}. * * @deprecated As of 1.1, use {@link Builder} instead. */ @Deprecated public SPIDeviceConfig(String controllerName, int address, int csActive, int clockFrequency, int clockMode, int wordLength, int bitOrdering) { this(UNASSIGNED, address, csActive, clockFrequency, clockMode, wordLength, bitOrdering); // checks for null controllerName.length(); this.controllerName = controllerName; } /** * Creates a new {@code SPIDeviceConfig} whose state is deserialized from the specified {@code InputStream}. * This method may be invoked to restore the state of a {@code SPIDeviceConfig} * object from a persistent store. * * @param in the stream to read from. * @return a new {@code SPIDeviceConfig} instance. * @throws IOException if an I/O error occurs or if the provided stream does not * contain a representation of a {@code SPIDeviceConfig} object. * * @since 1.1 */ public static SPIDeviceConfig deserialize(InputStream in) throws IOException { return (SPIDeviceConfig) Platform.deserialize(in); } /** * Serializes the state of this {@code SPIDeviceConfig} object to the specified {@code OutputStream}. * This method may be invoked by the {@link jdk.dio.DeviceManager DeviceManager} * to save the state of this {@code SPIDeviceConfig} object to a persistent store. * * @param out the stream to write to. * @throws IOException if an I/O error occurs. * * @since 1.1 */ @Override public int serialize(OutputStream out) throws IOException { return Platform.serialize(this, out); } /** * Gets the configured address of the SPI slave device. * * @return the Chip Select address of the slave device on the bus (a positive or zero integer). */ public int getAddress() { return address; } /** * Gets the configured controller number (the controller number of the SPI bus adapter the slave device is connected to). * * @return the controller number (a positive or zero integer) or {@link #UNASSIGNED UNASSIGNED}. */ @Override public int getControllerNumber() { return controllerNumber; } /** * Gets the configured controller name (such as its device file name on UNIX systems). * * @return the controller name or {@code null}. */ @Override public String getControllerName() { return controllerName; } /** * Gets the requested or allocated input buffer size. The platform/underlying * driver may or may not allocate the requested size * for the input buffer. * When querying the configuration of an opened or registered device the * allocated buffer size is returned. * * @return the requested or allocated input buffer size (a positive or zero integer) or {@link #UNASSIGNED UNASSIGNED}. * * @since 1.1 */ public int getInputBufferSize() { return inputBufferSize; } /** * Gets the requested or allocated output buffer size. The platform/underlying * driver may or may not allocate the requested size * for the output buffer. * When querying the configuration of an opened or registered device the * allocated buffer size is returned. * * @return the requested or allocated output buffer size (a positive or zero integer) or {@link #UNASSIGNED UNASSIGNED}. * * @since 1.1 */ public int getOutputBufferSize() { return outputBufferSize; } /** * Gets the configured bit (shifting) ordering of the SPI slave device. * * @return the bit ordering of the slave device, one of: {@link SPIDevice#BIG_ENDIAN}, * {@link SPIDevice#LITTLE_ENDIAN}, {@link SPIDevice#MIXED_ENDIAN} or {@link #UNASSIGNED UNASSIGNED}. */ public int getBitOrdering() { return bitOrdering; } /** * Gets the clock frequency (in Hz) supported by the SPI slave device. * * @return the clock frequency of the slave device in Hz (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. */ public int getClockFrequency() { return clockFrequency; } /** * Gets the configured clock mode (combining clock polarity and phase) for communicating with the SPI slave device. * * @return the clock mode, one of: {@code 0}, {@code 1}, {@code 2} or {@code 3} (see SPI Clock * Modes). */ public int getClockMode() { return clockMode; } /** * Gets the configured Chip Select active level for selecting the SPI slave device. * * @return the Chip Select active level,one of {@link #CS_ACTIVE_LOW}, * {@link #CS_ACTIVE_HIGH}, {@link #CS_NOT_CONTROLLED} or {@link #UNASSIGNED UNASSIGNED}. */ public int getCSActiveLevel() { return csActive; } /** * Gets the configured word length for communicating with the SPI slave device. * * @return the word length of the slave device (a positive integer) or {@link #UNASSIGNED UNASSIGNED}. */ public int getWordLength() { return wordLength; } /** * Returns the hash code value for this object. * * @return a hash code value for this object. */ @Override public int hashCode() { return Platform.hash(this, 7, 47); } /** * Checks two {@code SPIDeviceConfig} objects for equality. * * @param obj * the object to test for equality with this object. * * @return {@code true} if {@code obj} is a {@code SPIDeviceConfig} and has * the same hardware addressing information and configuration parameter values * as this {@code SPIDeviceConfig} object; {@code false} otherwise. */ @Override public boolean equals(Object obj) { return Platform.equals(this, obj); } private static void checkCsActive(int csActive) { if (csActive < UNASSIGNED || csActive > CS_NOT_CONTROLLED) { throw new IllegalArgumentException(Integer.toString(csActive)); } } private static void checkClockMode(int clockMode) { if (clockMode < 0 || clockMode > 3) { throw new IllegalArgumentException(Integer.toString(clockMode)); } } private static void checkBitOrdering(int bitOrdering) { if (bitOrdering < UNASSIGNED || bitOrdering > SPIDevice.MIXED_ENDIAN) { throw new IllegalArgumentException(Integer.toString(bitOrdering)); } } private void checkParameters(){ Utils.checkIntValue(controllerNumber); Utils.checkIntZeroOrPozitive(address); Utils.checkGreaterThanZero(clockFrequency); checkCsActive(csActive); checkClockMode(clockMode); checkBitOrdering(bitOrdering); Utils.checkGreaterThanZero(wordLength); } }




© 2015 - 2025 Weber Informatics LLC | Privacy Policy