SpiNNakerManchester / JavaSpiNNaker / 6270187726

/*

 * Copyright (c) 2018 The University of Manchester

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *     https://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package uk.ac.manchester.spinnaker.transceiver;

import static java.lang.Thread.interrupted;

import static java.nio.ByteBuffer.allocate;

import static java.nio.ByteOrder.LITTLE_ENDIAN;

import static uk.ac.manchester.spinnaker.machine.MemoryLocation.NULL;

import static uk.ac.manchester.spinnaker.messages.Constants.WORD_SIZE;

import static uk.ac.manchester.spinnaker.messages.Utils.wordAsBuffer;

import static uk.ac.manchester.spinnaker.messages.model.PowerCommand.POWER_OFF;

import static uk.ac.manchester.spinnaker.messages.model.PowerCommand.POWER_ON;

import static uk.ac.manchester.spinnaker.transceiver.BMPConstants.BLACKLIST_BLANK;

import static uk.ac.manchester.spinnaker.transceiver.BMPConstants.BMP_BOOT_BLACKLIST_OFFSET;

import static uk.ac.manchester.spinnaker.transceiver.BMPConstants.BMP_BOOT_CRC_OFFSET;

import static uk.ac.manchester.spinnaker.transceiver.BMPConstants.BMP_BOOT_SECTOR_ADDR;

import static uk.ac.manchester.spinnaker.transceiver.BMPConstants.BMP_BOOT_SECTOR_SIZE;

import static uk.ac.manchester.spinnaker.transceiver.BMPConstants.SF_BL_ADDR;

import static uk.ac.manchester.spinnaker.transceiver.BMPConstants.SF_BL_LEN;

import static uk.ac.manchester.spinnaker.transceiver.Utils.crc;

import static uk.ac.manchester.spinnaker.transceiver.Utils.fill;

import java.io.File;

import java.io.IOException;

import java.io.InputStream;

import java.nio.ByteBuffer;

import java.util.Collection;

import java.util.Set;

import javax.validation.Valid;

import javax.validation.constraints.NotNull;

import javax.validation.constraints.Positive;

import com.google.errorprone.annotations.CheckReturnValue;

import uk.ac.manchester.spinnaker.machine.MemoryLocation;

import uk.ac.manchester.spinnaker.machine.board.BMPBoard;

import uk.ac.manchester.spinnaker.machine.board.BMPCoords;

import uk.ac.manchester.spinnaker.messages.bmp.WriteFlashBuffer;

import uk.ac.manchester.spinnaker.messages.model.ADCInfo;

import uk.ac.manchester.spinnaker.messages.model.Blacklist;

import uk.ac.manchester.spinnaker.messages.model.FPGA;

import uk.ac.manchester.spinnaker.messages.model.FPGALinkRegisters;

import uk.ac.manchester.spinnaker.messages.model.FPGAMainRegisters;

import uk.ac.manchester.spinnaker.messages.model.FPGARecevingLinkCounters;

import uk.ac.manchester.spinnaker.messages.model.FPGASendingLinkCounters;

import uk.ac.manchester.spinnaker.messages.model.FirmwareDescriptor;

import uk.ac.manchester.spinnaker.messages.model.FirmwareDescriptors;

import uk.ac.manchester.spinnaker.messages.model.LEDAction;

import uk.ac.manchester.spinnaker.messages.model.PowerCommand;

import uk.ac.manchester.spinnaker.messages.model.VersionInfo;

import uk.ac.manchester.spinnaker.utils.MappableIterable;

/**

 * The interface supported by the {@link Transceiver} for talking to a BMP.

 * Emulates a lot of default handling and variant-type handling by Python.

 * <p>

 * Note that operations on a particular BMP (i.e., with the same

 * {@link BMPCoords}) are <strong>always</strong> thread-unsafe.

 *

 * @author Donal Fellows

 */

public interface BMPTransceiverInterface extends AutoCloseable {

        /**

         * Set the default BMP coordinates, at least for cabinet and frame.

         *

         * @param bmp

         *            The new default coordinates.

         */

        void bind(@Valid BMPCoords bmp);

        /**

         * @return The currently bound BMP coordinates. Defaults to 0,0 if not set

         *         by {@link #bind(BMPCoords)}.

         */

        BMPCoords getBoundBMP();

        /**

         * List which boards are actually available to be manipulated by a

         * particular BMP.

         *

         * @param bmp

         *            Which BMP are we asking?

         * @return Ordered list of board identifiers.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        @CheckReturnValue

        MappableIterable<BMPBoard> availableBoards(@Valid BMPCoords bmp)

                        throws IOException, ProcessException, InterruptedException;

        /**

         * List which boards are actually available to be manipulated by the current

         * bound BMP.

         *

         * @return Ordered list of board identifiers.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        @CheckReturnValue

        default MappableIterable<BMPBoard> availableBoards()

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Power on the whole machine.

         * <p>

         * <strong>WARNING!</strong> This operation is <em>unsafe</em> in a

         * multi-threaded context.

         *

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the thread is interrupted while waiting.

         */

        @ParallelUnsafe

        void powerOnMachine()

                        throws InterruptedException, IOException, ProcessException;

        /**

         * Power on some boards in the machine.

         * <p>

         * <strong>WARNING!</strong> This operation is <em>unsafe</em> in a

         * multi-threaded context.

         *

         * @param boards

         *            The boards to power on (managed by default BMP)

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the thread is interrupted while waiting.

         */

        @ParallelSafeWithCare

        default void powerOn(Collection<@Valid BMPBoard> boards)

                        throws InterruptedException, IOException, ProcessException {

        /**

         * Power on a board in the machine.

         * <p>

         * <strong>WARNING!</strong> This operation is <em>unsafe</em> in a

         * multi-threaded context.

         *

         * @param board

         *            The board to power on (managed by default BMP)

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the thread is interrupted while waiting.

         */

        @ParallelSafeWithCare

        default void powerOn(@Valid BMPBoard board)

                        throws InterruptedException, IOException, ProcessException {

        /**

         * Power off the whole machine.

         * <p>

         * <strong>WARNING!</strong> This operation is <em>unsafe</em> in a

         * multi-threaded context.

         *

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the thread is interrupted while waiting.

         */

        @ParallelUnsafe

        void powerOffMachine()

                        throws InterruptedException, IOException, ProcessException;

        /**

         * Power off some boards in the machine.

         * <p>

         * <strong>WARNING!</strong> This operation is <em>unsafe</em> in a

         * multi-threaded context.

         *

         * @param boards

         *            The boards to power off (managed by default BMP)

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the thread is interrupted while waiting.

         */

        @ParallelSafeWithCare

        default void powerOff(Collection<@Valid BMPBoard> boards)

                        throws InterruptedException, IOException, ProcessException {

        /**

         * Power off a board in the machine.

         * <p>

         * <strong>WARNING!</strong> This operation is <em>unsafe</em> in a

         * multi-threaded context.

         *

         * @param board

         *            The board to power off (in the bound BMP)

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the thread is interrupted while waiting.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        default void powerOff(@Valid BMPBoard board)

                        throws InterruptedException, IOException, ProcessException {

        /**

         * Send a power request to the machine.

         * <p>

         * <strong>WARNING!</strong> This operation is <em>unsafe</em> in a

         * multi-threaded context.

         *

         * @param powerCommand

         *            The power command to send

         * @param bmp

         *            the coordinates of the BMP; components are zero for a board

         *            not in a frame of a cabinet

         * @param boards

         *            The boards to send the command to

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the thread is interrupted while waiting.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelUnsafe

        void power(@NotNull PowerCommand powerCommand, @Valid BMPCoords bmp,

                        Collection<@Valid BMPBoard> boards)

                        throws InterruptedException, IOException, ProcessException;

        /**

         * Set the LED state of a board in the machine.

         *

         * @param leds

         *            Collection of LED numbers to set the state of (0-7)

         * @param action

         *            State to set the LED to, either on, off or toggle

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param boards

         *            Specifies the board to control the LEDs of. The command will

         *            actually be sent to the first board in the collection.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        void setLED(Collection<Integer> leds, LEDAction action,

                        @Valid BMPCoords bmp, Collection<@Valid BMPBoard> boards)

                        throws IOException, ProcessException, InterruptedException;

        /**

         * Set the LED state of a board in the machine.

         *

         * @param leds

         *            Collection of LED numbers to set the state of (0-7)

         * @param action

         *            State to set the LED to, either on, off or toggle

         * @param board

         *            Specifies the board to control the LEDs of.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        default void setLED(Collection<Integer> leds, LEDAction action,

                        @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        /**

         * Read a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param register

         *            Register to read.

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGARegister(FPGA fpga, FPGAMainRegisters register,

                        @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param register

         *            Register to read.

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGARegister(FPGA fpga, FPGAMainRegisters register,

                        @Valid BMPCoords bmp, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param registerBank

         *            Which bank of link registers to read from.

         * @param register

         *            Register to read.

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGARegister(FPGA fpga, int registerBank,

                        FPGALinkRegisters register, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

                                board);

        }

        /**

         * Read a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param registerBank

         *            Which bank of link registers to read from.

         * @param register

         *            Register to read.

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGARegister(FPGA fpga, int registerBank,

                        FPGALinkRegisters register, @Valid BMPCoords bmp,

                        @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

                                board);

        }

        /**

         * Read a link counter on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param linkNumber

         *            Which bank of link counters to read from.

         * @param counter

         *            Counter to read.

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGALinkCounter(FPGA fpga, int linkNumber,

                        FPGARecevingLinkCounters counter, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

                                board);

        }

        /**

         * Read a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param linkNumber

         *            Which bank of link counters to read from.

         * @param counter

         *            Counter to read.

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGALinkCounter(FPGA fpga, int linkNumber,

                        FPGARecevingLinkCounters counter, @Valid BMPCoords bmp,

                        @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read a link counter on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param linkNumber

         *            Which bank of link counters to read from.

         * @param counter

         *            Counter to read.

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGALinkCounter(FPGA fpga, int linkNumber,

                        FPGASendingLinkCounters counter, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

                                board);

        }

        /**

         * Read a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param linkNumber

         *            Which bank of link counters to read from.

         * @param counter

         *            Counter to read.

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGALinkCounter(FPGA fpga, int linkNumber,

                        FPGASendingLinkCounters counter, @Valid BMPCoords bmp,

                        @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read a register on a FPGA of a board. The meaning of the register's

         * contents will depend on the FPGA's configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param register

         *            Register address to read to (will be rounded down to the

         *            nearest 32-bit word boundary).

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default int readFPGARegister(FPGA fpga, @NotNull MemoryLocation register,

                        @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read a register on a FPGA of a board. The meaning of the register's

         * contents will depend on the FPGA's configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param register

         *            Register address to read to (will be rounded down to the

         *            nearest 32-bit word boundary).

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to request the FPGA register from

         * @return the register data

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        int readFPGARegister(FPGA fpga, @NotNull MemoryLocation register,

                        @Valid BMPCoords bmp, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException;

        /**

         * Write a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param register

         *            Register to write.

         * @param value

         *            the value to write into the FPGA register

         * @param board

         *            which board to write the FPGA register to

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        default void writeFPGARegister(FPGA fpga, FPGAMainRegisters register,

                        int value, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        /**

         * Write a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param register

         *            Register to write.

         * @param value

         *            the value to write into the FPGA register

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to write the FPGA register to

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        default void writeFPGARegister(FPGA fpga, FPGAMainRegisters register,

                        int value, @Valid BMPCoords bmp, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        /**

         * Write a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param registerBank

         *            Which bank of link registers to read from.

         * @param register

         *            Register to write.

         * @param value

         *            the value to write into the FPGA register

         * @param board

         *            which board to write the FPGA register to

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        default void writeFPGARegister(FPGA fpga, int registerBank,

                        FPGALinkRegisters register, int value, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

                                board);

        /**

         * Write a register on a FPGA of a board, assuming the standard FPGA

         * configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param registerBank

         *            Which bank of link registers to read from.

         * @param register

         *            Register to write.

         * @param value

         *            the value to write into the FPGA register

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to write the FPGA register to

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        default void writeFPGARegister(FPGA fpga, int registerBank,

                        FPGALinkRegisters register, int value, @Valid BMPCoords bmp,

                        @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

                                board);

        /**

         * Write a register on a FPGA of a board. The meaning of setting the

         * register's contents will depend on the FPGA's configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param register

         *            Register address to read to (will be rounded down to the

         *            nearest 32-bit word boundary).

         * @param value

         *            the value to write into the FPGA register

         * @param board

         *            which board to write the FPGA register to

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        default void writeFPGARegister(FPGA fpga, @NotNull MemoryLocation register,

                        int value, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        /**

         * Write a register on a FPGA of a board. The meaning of setting the

         * register's contents will depend on the FPGA's configuration.

         *

         * @param fpga

         *            FPGA (0, 1 or 2) to communicate with.

         * @param register

         *            Register address to read to (will be rounded down to the

         *            nearest 32-bit word boundary).

         * @param value

         *            the value to write into the FPGA register

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to write the FPGA register to

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        void writeFPGARegister(FPGA fpga, @NotNull MemoryLocation register,

                        int value, @Valid BMPCoords bmp, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException;

        /**

         * Read the ADC data.

         *

         * @param board

         *            which board to request the ADC data from

         * @return the FPGA's ADC data object

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default ADCInfo readADCData(@Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read the ADC data.

         *

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to request the ADC data from

         * @return the FPGA's ADC data object

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        ADCInfo readADCData(@Valid BMPCoords bmp, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException;

        /**

         * Read the BMP version.

         *

         * @param boards

         *            which board to request the data from; the first board in the

         *            collection will be queried

         * @return the parsed SVER from the BMP

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelUnsafe

        @CheckReturnValue

        default VersionInfo readBMPVersion(Iterable<@Valid BMPBoard> boards)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read the BMP version.

         *

         * @param board

         *            which board to request the data from

         * @return the parsed SVER from the BMP

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafe

        @CheckReturnValue

        default VersionInfo readBMPVersion(@Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read the BMP version.

         *

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param boards

         *            which board to request the data from; the first board in the

         *            collection will be queried

         * @return the parsed SVER from the BMP

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelUnsafe

        @CheckReturnValue

        default VersionInfo readBMPVersion(@Valid BMPCoords bmp,

                        Iterable<@Valid BMPBoard> boards)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read the BMP version.

         *

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to request the data from

         * @return the parsed SVER from the BMP

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        @CheckReturnValue

        VersionInfo readBMPVersion(@Valid BMPCoords bmp, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException;

        /**

         * Read the BMP firmware descriptor.

         *

         * @param board

         *            which board to request the descriptor from

         * @param type

         *            Which firmware descriptor to read

         * @return the firmware descriptor

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        @CheckReturnValue

        default FirmwareDescriptor readBMPFirmwareDescriptor(

                        @Valid BMPBoard board, FirmwareDescriptors type)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Read the BMP firmware descriptor.

         *

         * @param bmp

         *            the coordinates of the BMP this is targeting

         * @param board

         *            which board to request the descriptor from

         * @param type

         *            Which firmware descriptor to read

         * @return the firmware descriptor

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        @CheckReturnValue

        default FirmwareDescriptor readBMPFirmwareDescriptor(@Valid BMPCoords bmp,

                        @Valid BMPBoard board, FirmwareDescriptors type)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Get the FPGA reset status.

         *

         * @param board

         *            Which board are the FPGAs on?

         * @return What the state of the reset line is.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        @CheckReturnValue

        default boolean getResetStatus(@Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Get the FPGA reset status.

         *

         * @param bmp

         *            Which BMP are we talking to?

         * @param board

         *            Which board are the FPGAs on?

         * @return What the state of the reset line is.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        @CheckReturnValue

        boolean getResetStatus(@Valid BMPCoords bmp, @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException;

        /**

         * Get the address of the serial flash buffer.

         *

         * @param board

         *            Which BMP's buffer do we want the address of?

         * @return The adress of the serial flash buffer.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        default MemoryLocation getSerialFlashBuffer(@Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException {

        }

        /**

         * Get the address of the serial flash buffer.

         *

         * @param bmp

         *            Which BMP are we talking to?

         * @param board

         *            Which BMP's buffer do we want the address of?

         * @return The adress of the serial flash buffer.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.

         */

        @ParallelSafeWithCare

        MemoryLocation getSerialFlashBuffer(@Valid BMPCoords bmp,

                        @Valid BMPBoard board)

                        throws IOException, ProcessException, InterruptedException;

        /** The type of reset to perform. */

                // NB: The order of these values is important

                /** Reset by taking the reset line low. */

                /** Reset by taking the reset line high. */

                /** Reset by sending a pulse on the reset line. */

        }

        /**

         * Reset the FPGAs on a board.

         *

         * @param board

         *            Which board are the FPGAs on?

         * @param resetType

         *            What kind of reset to perform.

         * @throws IOException

         *             If anything goes wrong with networking.

         * @throws ProcessException

         *             If SpiNNaker rejects a message.

         * @throws InterruptedException

         *             If the communications were interrupted.