Improve comments on the ahal SPI class
Change-Id: I2bdb9e94b016a58daca3e6b345c1da5b96d0b02b
diff --git a/frc971/wpilib/ahal/SPI.h b/frc971/wpilib/ahal/SPI.h
index c1172ce..dbac4ae 100644
--- a/frc971/wpilib/ahal/SPI.h
+++ b/frc971/wpilib/ahal/SPI.h
@@ -36,23 +36,66 @@
SPI(const SPI &) = delete;
SPI &operator=(const SPI &) = delete;
+ // Configure the rate of the generated clock signal.
+ //
+ // The claimed default value is 500,000Hz, and the claimed maximum value is
+ // 4,000,000Hz.
+ //
+ // This appears to have a very inflexible clocking setup. You can get 0.781MHz
+ // or 1.563MHz, but nothing in between. At least it rounds down the requested
+ // value like it should... 0.781MHz also appears to be the minimum.
void SetClockRate(double hz);
+ // Configure the order that bits are sent and received on the wire
+ // to be most significant bit first.
void SetMSBFirst();
+ // Configure the order that bits are sent and received on the wire
+ // to be least significant bit first.
void SetLSBFirst();
+ // Configure that the data is stable on the falling edge and the data
+ // changes on the rising edge.
void SetSampleDataOnFalling();
+ // Configure that the data is stable on the rising edge and the data
+ // changes on the falling edge.
void SetSampleDataOnRising();
+ // Configure the clock output line to be active low.
+ // This is sometimes called clock polarity high or clock idle high.
void SetClockActiveLow();
+ // Configure the clock output line to be active high.
+ // This is sometimes called clock polarity low or clock idle low.
void SetClockActiveHigh();
+ // Configure the chip select line to be active high.
void SetChipSelectActiveHigh();
+ // Configure the chip select line to be active low.
void SetChipSelectActiveLow();
- virtual int Write(uint8_t *data, int size);
- virtual int Read(bool initiate, uint8_t *dataReceived, int size);
- virtual int Transaction(uint8_t *dataToSend, uint8_t *dataReceived, int size);
+ // Write data to the slave device. Blocks until there is space in the
+ // output FIFO.
+ //
+ // If not running in output only mode, also saves the data received
+ // on the MISO input during the transfer into the receive FIFO.
+ int Write(uint8_t *data, int size);
+ // Read a word from the receive FIFO.
+ //
+ // Waits for the current transfer to complete if the receive FIFO is empty.
+ //
+ // If the receive FIFO is empty, there is no active transfer, and initiate
+ // is false, errors.
+ //
+ // @param initiate If true, this function pushes "0" into the transmit buffer
+ // and initiates a transfer. If false, this function assumes
+ // that data is already in the receive FIFO from a previous
+ // write.
+ int Read(bool initiate, uint8_t *dataReceived, int size);
+ // Perform a simultaneous read/write transaction with the device
+ //
+ // @param dataToSend The data to be written out to the device
+ // @param dataReceived Buffer to receive data from the device
+ // @param size The length of the transaction, in bytes
+ int Transaction(uint8_t *dataToSend, uint8_t *dataReceived, int size);
protected:
#ifdef WPILIB2017