mbed | Mbed

Users » mbed_official » Code » mbed

Dependents: hello SerialTestv11 SerialTestv12 Sierpinski ... more

drivers/SPI.h@145:64910690c574, 2017-06-21 (annotated)

Committer:: AnnaBridge
Date:: Wed Jun 21 17:31:38 2017 +0100
Revision:: 145:64910690c574
Parent:: 128:9bcdf88f62b0
Child:: 146:22da6e220af6

Release 145 of the mbed library.

Who changed what in which revision?

User	Revision	Line number	New contents of line
<>	128:9bcdf88f62b0	1	/* mbed Microcontroller Library
<>	128:9bcdf88f62b0	2	* Copyright (c) 2006-2015 ARM Limited
<>	128:9bcdf88f62b0	3	*
<>	128:9bcdf88f62b0	4	* Licensed under the Apache License, Version 2.0 (the "License");
<>	128:9bcdf88f62b0	5	* you may not use this file except in compliance with the License.
<>	128:9bcdf88f62b0	6	* You may obtain a copy of the License at
<>	128:9bcdf88f62b0	7	*
<>	128:9bcdf88f62b0	8	* http://www.apache.org/licenses/LICENSE-2.0
<>	128:9bcdf88f62b0	9	*
<>	128:9bcdf88f62b0	10	* Unless required by applicable law or agreed to in writing, software
<>	128:9bcdf88f62b0	11	* distributed under the License is distributed on an "AS IS" BASIS,
<>	128:9bcdf88f62b0	12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
<>	128:9bcdf88f62b0	13	* See the License for the specific language governing permissions and
<>	128:9bcdf88f62b0	14	* limitations under the License.
<>	128:9bcdf88f62b0	15	*/
<>	128:9bcdf88f62b0	16	#ifndef MBED_SPI_H
<>	128:9bcdf88f62b0	17	#define MBED_SPI_H
<>	128:9bcdf88f62b0	18
<>	128:9bcdf88f62b0	19	#include "platform/platform.h"
<>	128:9bcdf88f62b0	20
AnnaBridge	145:64910690c574	21	#if defined (DEVICE_SPI) \|\| defined(DOXYGEN_ONLY)
<>	128:9bcdf88f62b0	22
<>	128:9bcdf88f62b0	23	#include "platform/PlatformMutex.h"
<>	128:9bcdf88f62b0	24	#include "hal/spi_api.h"
<>	128:9bcdf88f62b0	25	#include "platform/SingletonPtr.h"
<>	128:9bcdf88f62b0	26
<>	128:9bcdf88f62b0	27	#if DEVICE_SPI_ASYNCH
<>	128:9bcdf88f62b0	28	#include "platform/CThunk.h"
<>	128:9bcdf88f62b0	29	#include "hal/dma_api.h"
<>	128:9bcdf88f62b0	30	#include "platform/CircularBuffer.h"
<>	128:9bcdf88f62b0	31	#include "platform/FunctionPointer.h"
<>	128:9bcdf88f62b0	32	#include "platform/Transaction.h"
<>	128:9bcdf88f62b0	33	#endif
<>	128:9bcdf88f62b0	34
<>	128:9bcdf88f62b0	35	namespace mbed {
<>	128:9bcdf88f62b0	36	/** \addtogroup drivers */
<>	128:9bcdf88f62b0	37
<>	128:9bcdf88f62b0	38	/** A SPI Master, used for communicating with SPI slave devices
<>	128:9bcdf88f62b0	39	*
<>	128:9bcdf88f62b0	40	* The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz
<>	128:9bcdf88f62b0	41	*
<>	128:9bcdf88f62b0	42	* Most SPI devices will also require Chip Select and Reset signals. These
AnnaBridge	145:64910690c574	43	* can be controlled using DigitalOut pins
<>	128:9bcdf88f62b0	44	*
AnnaBridge	145:64910690c574	45	* @note Synchronization level: Thread safe
<>	128:9bcdf88f62b0	46	*
<>	128:9bcdf88f62b0	47	* Example:
<>	128:9bcdf88f62b0	48	* @code
<>	128:9bcdf88f62b0	49	* // Send a byte to a SPI slave, and record the response
<>	128:9bcdf88f62b0	50	*
<>	128:9bcdf88f62b0	51	* #include "mbed.h"
<>	128:9bcdf88f62b0	52	*
<>	128:9bcdf88f62b0	53	* // hardware ssel (where applicable)
<>	128:9bcdf88f62b0	54	* //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel
<>	128:9bcdf88f62b0	55	*
<>	128:9bcdf88f62b0	56	* // software ssel
<>	128:9bcdf88f62b0	57	* SPI device(p5, p6, p7); // mosi, miso, sclk
<>	128:9bcdf88f62b0	58	* DigitalOut cs(p8); // ssel
<>	128:9bcdf88f62b0	59	*
<>	128:9bcdf88f62b0	60	* int main() {
<>	128:9bcdf88f62b0	61	* // hardware ssel (where applicable)
<>	128:9bcdf88f62b0	62	* //int response = device.write(0xFF);
<>	128:9bcdf88f62b0	63	*
<>	128:9bcdf88f62b0	64	* device.lock();
<>	128:9bcdf88f62b0	65	* // software ssel
<>	128:9bcdf88f62b0	66	* cs = 0;
<>	128:9bcdf88f62b0	67	* int response = device.write(0xFF);
<>	128:9bcdf88f62b0	68	* cs = 1;
<>	128:9bcdf88f62b0	69	* device.unlock();
<>	128:9bcdf88f62b0	70	*
<>	128:9bcdf88f62b0	71	* }
<>	128:9bcdf88f62b0	72	* @endcode
AnnaBridge	145:64910690c574	73	* @ingroup drivers
<>	128:9bcdf88f62b0	74	*/
<>	128:9bcdf88f62b0	75	class SPI {
<>	128:9bcdf88f62b0	76
<>	128:9bcdf88f62b0	77	public:
<>	128:9bcdf88f62b0	78
<>	128:9bcdf88f62b0	79	/** Create a SPI master connected to the specified pins
<>	128:9bcdf88f62b0	80	*
<>	128:9bcdf88f62b0	81	* mosi or miso can be specfied as NC if not used
<>	128:9bcdf88f62b0	82	*
<>	128:9bcdf88f62b0	83	* @param mosi SPI Master Out, Slave In pin
<>	128:9bcdf88f62b0	84	* @param miso SPI Master In, Slave Out pin
<>	128:9bcdf88f62b0	85	* @param sclk SPI Clock pin
<>	128:9bcdf88f62b0	86	* @param ssel SPI chip select pin
<>	128:9bcdf88f62b0	87	*/
<>	128:9bcdf88f62b0	88	SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel=NC);
<>	128:9bcdf88f62b0	89
<>	128:9bcdf88f62b0	90	/** Configure the data transmission format
<>	128:9bcdf88f62b0	91	*
<>	128:9bcdf88f62b0	92	* @param bits Number of bits per SPI frame (4 - 16)
<>	128:9bcdf88f62b0	93	* @param mode Clock polarity and phase mode (0 - 3)
<>	128:9bcdf88f62b0	94	*
<>	128:9bcdf88f62b0	95	* @code
<>	128:9bcdf88f62b0	96	* mode \| POL PHA
<>	128:9bcdf88f62b0	97	* -----+--------
<>	128:9bcdf88f62b0	98	* 0 \| 0 0
<>	128:9bcdf88f62b0	99	* 1 \| 0 1
<>	128:9bcdf88f62b0	100	* 2 \| 1 0
<>	128:9bcdf88f62b0	101	* 3 \| 1 1
<>	128:9bcdf88f62b0	102	* @endcode
<>	128:9bcdf88f62b0	103	*/
<>	128:9bcdf88f62b0	104	void format(int bits, int mode = 0);
<>	128:9bcdf88f62b0	105
<>	128:9bcdf88f62b0	106	/** Set the spi bus clock frequency
<>	128:9bcdf88f62b0	107	*
<>	128:9bcdf88f62b0	108	* @param hz SCLK frequency in hz (default = 1MHz)
<>	128:9bcdf88f62b0	109	*/
<>	128:9bcdf88f62b0	110	void frequency(int hz = 1000000);
<>	128:9bcdf88f62b0	111
<>	128:9bcdf88f62b0	112	/** Write to the SPI Slave and return the response
<>	128:9bcdf88f62b0	113	*
<>	128:9bcdf88f62b0	114	* @param value Data to be sent to the SPI slave
<>	128:9bcdf88f62b0	115	*
<>	128:9bcdf88f62b0	116	* @returns
<>	128:9bcdf88f62b0	117	* Response from the SPI slave
AnnaBridge	145:64910690c574	118	*/
<>	128:9bcdf88f62b0	119	virtual int write(int value);
<>	128:9bcdf88f62b0	120
AnnaBridge	145:64910690c574	121	/** Write to the SPI Slave and obtain the response
AnnaBridge	145:64910690c574	122	*
AnnaBridge	145:64910690c574	123	* The total number of bytes sent and recieved will be the maximum of
AnnaBridge	145:64910690c574	124	* tx_length and rx_length. The bytes written will be padded with the
AnnaBridge	145:64910690c574	125	* value 0xff.
AnnaBridge	145:64910690c574	126	*
AnnaBridge	145:64910690c574	127	* @param tx_buffer Pointer to the byte-array of data to write to the device
AnnaBridge	145:64910690c574	128	* @param tx_length Number of bytes to write, may be zero
AnnaBridge	145:64910690c574	129	* @param rx_buffer Pointer to the byte-array of data to read from the device
AnnaBridge	145:64910690c574	130	* @param rx_length Number of bytes to read, may be zero
AnnaBridge	145:64910690c574	131	* @returns
AnnaBridge	145:64910690c574	132	* The number of bytes written and read from the device. This is
AnnaBridge	145:64910690c574	133	* maximum of tx_length and rx_length.
AnnaBridge	145:64910690c574	134	*/
AnnaBridge	145:64910690c574	135	virtual int write(const char tx_buffer, int tx_length, char rx_buffer, int rx_length);
AnnaBridge	145:64910690c574	136
<>	128:9bcdf88f62b0	137	/** Acquire exclusive access to this SPI bus
<>	128:9bcdf88f62b0	138	*/
<>	128:9bcdf88f62b0	139	virtual void lock(void);
<>	128:9bcdf88f62b0	140
<>	128:9bcdf88f62b0	141	/** Release exclusive access to this SPI bus
<>	128:9bcdf88f62b0	142	*/
<>	128:9bcdf88f62b0	143	virtual void unlock(void);
<>	128:9bcdf88f62b0	144
<>	128:9bcdf88f62b0	145	#if DEVICE_SPI_ASYNCH
<>	128:9bcdf88f62b0	146
<>	128:9bcdf88f62b0	147	/** Start non-blocking SPI transfer using 8bit buffers.
<>	128:9bcdf88f62b0	148	*
<>	128:9bcdf88f62b0	149	* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
<>	128:9bcdf88f62b0	150	* the default SPI value is sent
<>	128:9bcdf88f62b0	151	* @param tx_length The length of TX buffer in bytes
<>	128:9bcdf88f62b0	152	* @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
<>	128:9bcdf88f62b0	153	* received data are ignored
<>	128:9bcdf88f62b0	154	* @param rx_length The length of RX buffer in bytes
<>	128:9bcdf88f62b0	155	* @param callback The event callback function
<>	128:9bcdf88f62b0	156	* @param event The logical OR of events to modify. Look at spi hal header file for SPI events.
<>	128:9bcdf88f62b0	157	* @return Zero if the transfer has started, or -1 if SPI peripheral is busy
<>	128:9bcdf88f62b0	158	*/
<>	128:9bcdf88f62b0	159	template<typename Type>
<>	128:9bcdf88f62b0	160	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) {
<>	128:9bcdf88f62b0	161	if (spi_active(&_spi)) {
<>	128:9bcdf88f62b0	162	return queue_transfer(tx_buffer, tx_length, rx_buffer, rx_length, sizeof(Type)*8, callback, event);
<>	128:9bcdf88f62b0	163	}
<>	128:9bcdf88f62b0	164	start_transfer(tx_buffer, tx_length, rx_buffer, rx_length, sizeof(Type)*8, callback, event);
<>	128:9bcdf88f62b0	165	return 0;
<>	128:9bcdf88f62b0	166	}
<>	128:9bcdf88f62b0	167
<>	128:9bcdf88f62b0	168	/** Abort the on-going SPI transfer, and continue with transfer's in the queue if any.
<>	128:9bcdf88f62b0	169	*/
<>	128:9bcdf88f62b0	170	void abort_transfer();
<>	128:9bcdf88f62b0	171
<>	128:9bcdf88f62b0	172	/** Clear the transaction buffer
<>	128:9bcdf88f62b0	173	*/
<>	128:9bcdf88f62b0	174	void clear_transfer_buffer();
<>	128:9bcdf88f62b0	175
<>	128:9bcdf88f62b0	176	/** Clear the transaction buffer and abort on-going transfer.
<>	128:9bcdf88f62b0	177	*/
<>	128:9bcdf88f62b0	178	void abort_all_transfers();
<>	128:9bcdf88f62b0	179
<>	128:9bcdf88f62b0	180	/** Configure DMA usage suggestion for non-blocking transfers
<>	128:9bcdf88f62b0	181	*
<>	128:9bcdf88f62b0	182	* @param usage The usage DMA hint for peripheral
<>	128:9bcdf88f62b0	183	* @return Zero if the usage was set, -1 if a transaction is on-going
<>	128:9bcdf88f62b0	184	*/
<>	128:9bcdf88f62b0	185	int set_dma_usage(DMAUsage usage);
<>	128:9bcdf88f62b0	186
<>	128:9bcdf88f62b0	187	protected:
<>	128:9bcdf88f62b0	188	/** SPI IRQ handler
<>	128:9bcdf88f62b0	189	*
<>	128:9bcdf88f62b0	190	*/
<>	128:9bcdf88f62b0	191	void irq_handler_asynch(void);
<>	128:9bcdf88f62b0	192
<>	128:9bcdf88f62b0	193	/** Common transfer method
<>	128:9bcdf88f62b0	194	*
<>	128:9bcdf88f62b0	195	* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
<>	128:9bcdf88f62b0	196	* the default SPI value is sent
<>	128:9bcdf88f62b0	197	* @param tx_length The length of TX buffer in bytes
<>	128:9bcdf88f62b0	198	* @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
<>	128:9bcdf88f62b0	199	* received data are ignored
<>	128:9bcdf88f62b0	200	* @param rx_length The length of RX buffer in bytes
<>	128:9bcdf88f62b0	201	* @param bit_width The buffers element width
<>	128:9bcdf88f62b0	202	* @param callback The event callback function
<>	128:9bcdf88f62b0	203	* @param event The logical OR of events to modify
<>	128:9bcdf88f62b0	204	* @return Zero if the transfer has started or was added to the queue, or -1 if SPI peripheral is busy/buffer is full
<>	128:9bcdf88f62b0	205	*/
<>	128:9bcdf88f62b0	206	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);
<>	128:9bcdf88f62b0	207
<>	128:9bcdf88f62b0	208	/**
<>	128:9bcdf88f62b0	209	*
<>	128:9bcdf88f62b0	210	* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
<>	128:9bcdf88f62b0	211	* the default SPI value is sent
<>	128:9bcdf88f62b0	212	* @param tx_length The length of TX buffer in bytes
<>	128:9bcdf88f62b0	213	* @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
<>	128:9bcdf88f62b0	214	* received data are ignored
<>	128:9bcdf88f62b0	215	* @param rx_length The length of RX buffer in bytes
<>	128:9bcdf88f62b0	216	* @param bit_width The buffers element width
<>	128:9bcdf88f62b0	217	* @param callback The event callback function
<>	128:9bcdf88f62b0	218	* @param event The logical OR of events to modify
<>	128:9bcdf88f62b0	219	* @return Zero if a transfer was added to the queue, or -1 if the queue is full
<>	128:9bcdf88f62b0	220	*/
<>	128:9bcdf88f62b0	221	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);
<>	128:9bcdf88f62b0	222
<>	128:9bcdf88f62b0	223	/** Configures a callback, spi peripheral and initiate a new transfer
<>	128:9bcdf88f62b0	224	*
<>	128:9bcdf88f62b0	225	* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
<>	128:9bcdf88f62b0	226	* the default SPI value is sent
<>	128:9bcdf88f62b0	227	* @param tx_length The length of TX buffer in bytes
<>	128:9bcdf88f62b0	228	* @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
<>	128:9bcdf88f62b0	229	* received data are ignored
<>	128:9bcdf88f62b0	230	* @param rx_length The length of RX buffer in bytes
<>	128:9bcdf88f62b0	231	* @param bit_width The buffers element width
<>	128:9bcdf88f62b0	232	* @param callback The event callback function
<>	128:9bcdf88f62b0	233	* @param event The logical OR of events to modify
<>	128:9bcdf88f62b0	234	*/
<>	128:9bcdf88f62b0	235	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);
<>	128:9bcdf88f62b0	236
<>	128:9bcdf88f62b0	237	#if TRANSACTION_QUEUE_SIZE_SPI
<>	128:9bcdf88f62b0	238
<>	128:9bcdf88f62b0	239	/** Start a new transaction
<>	128:9bcdf88f62b0	240	*
<>	128:9bcdf88f62b0	241	* @param data Transaction data
<>	128:9bcdf88f62b0	242	*/
<>	128:9bcdf88f62b0	243	void start_transaction(transaction_t *data);
<>	128:9bcdf88f62b0	244
<>	128:9bcdf88f62b0	245	/** Dequeue a transaction
<>	128:9bcdf88f62b0	246	*
<>	128:9bcdf88f62b0	247	*/
<>	128:9bcdf88f62b0	248	void dequeue_transaction();
<>	128:9bcdf88f62b0	249	static CircularBuffer<Transaction<SPI>, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer;
<>	128:9bcdf88f62b0	250	#endif
<>	128:9bcdf88f62b0	251
<>	128:9bcdf88f62b0	252	#endif
<>	128:9bcdf88f62b0	253
<>	128:9bcdf88f62b0	254	public:
<>	128:9bcdf88f62b0	255	virtual ~SPI() {
<>	128:9bcdf88f62b0	256	}
<>	128:9bcdf88f62b0	257
<>	128:9bcdf88f62b0	258	protected:
<>	128:9bcdf88f62b0	259	spi_t _spi;
<>	128:9bcdf88f62b0	260
<>	128:9bcdf88f62b0	261	#if DEVICE_SPI_ASYNCH
<>	128:9bcdf88f62b0	262	CThunk<SPI> _irq;
<>	128:9bcdf88f62b0	263	event_callback_t _callback;
<>	128:9bcdf88f62b0	264	DMAUsage _usage;
<>	128:9bcdf88f62b0	265	#endif
<>	128:9bcdf88f62b0	266
<>	128:9bcdf88f62b0	267	void aquire(void);
<>	128:9bcdf88f62b0	268	static SPI *_owner;
<>	128:9bcdf88f62b0	269	static SingletonPtr<PlatformMutex> _mutex;
<>	128:9bcdf88f62b0	270	int _bits;
<>	128:9bcdf88f62b0	271	int _mode;
<>	128:9bcdf88f62b0	272	int _hz;
<>	128:9bcdf88f62b0	273	};
<>	128:9bcdf88f62b0	274
<>	128:9bcdf88f62b0	275	} // namespace mbed
<>	128:9bcdf88f62b0	276
<>	128:9bcdf88f62b0	277	#endif
<>	128:9bcdf88f62b0	278
<>	128:9bcdf88f62b0	279	#endif