test
Fork of mbed-dev-bin by
Diff: SPI.h
- Revision:
- 0:e1a608bb55e8
diff -r 000000000000 -r e1a608bb55e8 SPI.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/SPI.h Thu Apr 07 18:33:58 2016 +0100 @@ -0,0 +1,245 @@ +/* mbed Microcontroller Library + * Copyright (c) 2006-2015 ARM Limited + * + * 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 + * + * http://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. + */ +#ifndef MBED_SPI_H +#define MBED_SPI_H + +#include "platform.h" + +#if DEVICE_SPI + +#include "spi_api.h" + +#if DEVICE_SPI_ASYNCH +#include "CThunk.h" +#include "dma_api.h" +#include "CircularBuffer.h" +#include "FunctionPointer.h" +#include "Transaction.h" +#endif + +namespace mbed { + +/** A SPI Master, used for communicating with SPI slave devices + * + * The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz + * + * Most SPI devices will also require Chip Select and Reset signals. These + * can be controlled using <DigitalOut> pins + * + * Example: + * @code + * // Send a byte to a SPI slave, and record the response + * + * #include "mbed.h" + * + * // hardware ssel (where applicable) + * //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel + * + * // software ssel + * SPI device(p5, p6, p7); // mosi, miso, sclk + * DigitalOut cs(p8); // ssel + * + * int main() { + * // hardware ssel (where applicable) + * //int response = device.write(0xFF); + * + * // software ssel + * cs = 0; + * int response = device.write(0xFF); + * cs = 1; + * } + * @endcode + */ +class SPI { + +public: + + /** Create a SPI master connected to the specified pins + * + * mosi or miso can be specfied as NC if not used + * + * @param mosi SPI Master Out, Slave In pin + * @param miso SPI Master In, Slave Out pin + * @param sclk SPI Clock pin + * @param ssel SPI chip select pin + */ + SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel=NC); + + /** Configure the data transmission format + * + * @param bits Number of bits per SPI frame (4 - 16) + * @param mode Clock polarity and phase mode (0 - 3) + * + * @code + * mode | POL PHA + * -----+-------- + * 0 | 0 0 + * 1 | 0 1 + * 2 | 1 0 + * 3 | 1 1 + * @endcode + */ + void format(int bits, int mode = 0); + + /** Set the spi bus clock frequency + * + * @param hz SCLK frequency in hz (default = 1MHz) + */ + void frequency(int hz = 1000000); + + /** Write to the SPI Slave and return the response + * + * @param value Data to be sent to the SPI slave + * + * @returns + * Response from the SPI slave + */ + virtual int write(int value); + +#if DEVICE_SPI_ASYNCH + + /** Start non-blocking SPI transfer using 8bit buffers. + * + * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, + * the default SPI value is sent + * @param tx_length The length of TX buffer in bytes + * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, + * received data are ignored + * @param rx_length The length of RX buffer in bytes + * @param callback The event callback function + * @param event The logical OR of events to modify. Look at spi hal header file for SPI events. + * @return Zero if the transfer has started, or -1 if SPI peripheral is busy + */ + template<typename Type> + int transfer(const Type *tx_buffer, int tx_length, Type *rx_buffer, int rx_length, const event_callback_t& callback, int event = SPI_EVENT_COMPLETE) { + if (spi_active(&_spi)) { + return queue_transfer(tx_buffer, tx_length, rx_buffer, rx_length, sizeof(Type)*8, callback, event); + } + start_transfer(tx_buffer, tx_length, rx_buffer, rx_length, sizeof(Type)*8, callback, event); + return 0; + } + + /** Abort the on-going SPI transfer, and continue with transfer's in the queue if any. + */ + void abort_transfer(); + + /** Clear the transaction buffer + */ + void clear_transfer_buffer(); + + /** Clear the transaction buffer and abort on-going transfer. + */ + void abort_all_transfers(); + + /** Configure DMA usage suggestion for non-blocking transfers + * + * @param usage The usage DMA hint for peripheral + * @return Zero if the usage was set, -1 if a transaction is on-going + */ + int set_dma_usage(DMAUsage usage); + +protected: + /** SPI IRQ handler + * + */ + void irq_handler_asynch(void); + + /** Common transfer method + * + * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, + * the default SPI value is sent + * @param tx_length The length of TX buffer in bytes + * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, + * received data are ignored + * @param rx_length The length of RX buffer in bytes + * @param bit_width The buffers element width + * @param callback The event callback function + * @param event The logical OR of events to modify + * @return Zero if the transfer has started or was added to the queue, or -1 if SPI peripheral is busy/buffer is full + */ + int transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t& callback, int event); + + /** + * + * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, + * the default SPI value is sent + * @param tx_length The length of TX buffer in bytes + * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, + * received data are ignored + * @param rx_length The length of RX buffer in bytes + * @param bit_width The buffers element width + * @param callback The event callback function + * @param event The logical OR of events to modify + * @return Zero if a transfer was added to the queue, or -1 if the queue is full + */ + int queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t& callback, int event); + + /** Configures a callback, spi peripheral and initiate a new transfer + * + * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, + * the default SPI value is sent + * @param tx_length The length of TX buffer in bytes + * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, + * received data are ignored + * @param rx_length The length of RX buffer in bytes + * @param bit_width The buffers element width + * @param callback The event callback function + * @param event The logical OR of events to modify + */ + void start_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t& callback, int event); + +#if TRANSACTION_QUEUE_SIZE_SPI + + /** Start a new transaction + * + * @param data Transaction data + */ + void start_transaction(transaction_t *data); + + /** Dequeue a transaction + * + */ + void dequeue_transaction(); + static CircularBuffer<Transaction<SPI>, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer; +#endif + +#endif + +public: + virtual ~SPI() { + } + +protected: + spi_t _spi; + +#if DEVICE_SPI_ASYNCH + CThunk<SPI> _irq; + event_callback_t _callback; + DMAUsage _usage; +#endif + + void aquire(void); + static SPI *_owner; + int _bits; + int _mode; + int _hz; +}; + +} // namespace mbed + +#endif + +#endif