BurstSPI.h

00001 #ifndef BURSTSPI_H
00002 #define BURSTSPI_H
00003 
00004 #include "mbed.h"
00005 
00006 
00007 /** An SPI Master, used for communicating with SPI slave devices at very high speeds
00008  *
00009  * The default mbed SPI class allows for communication via the SPI bus at high clock frequencies,
00010  * however at these frequencies there is alot of overhead from the mbed code.
00011  * While this code makes sure your code is alot more robust, it is also relative slow.
00012  * This library adds to your default SPI commands some extra commands to transmit data rapidly with
00013  * very little overhead. Downsides are that currently it is TX only (all RX packets are discarded),
00014  * and it requires some extra commands.
00015  *
00016  * Example:
00017  * @code
00018  *  //Send 1000 SPI packets as fast as possible
00019  *  spi.setFormat();
00020  *  for (int i = 0; i<1000; i++)
00021  *    spi.fastWrite(data[i]);
00022  *  spi.clearRX();
00023  * @endcode
00024  *
00025  * As an example, writing 76,800 16-bit data packets to an LCD screen at 48MHz requires 111ms with
00026  * the normal mbed library. With this library it takes 25ms, which is also the theoretical
00027  * amount of time it should take. If you are running at 1MHz this will do alot less.
00028  */
00029 class BurstSPI : public SPI
00030 {
00031 public:
00032     /** Create a SPI master connected to the specified pins
00033     *
00034     * Pin Options:
00035     *  (5, 6, 7) or (11, 12, 13)
00036     *
00037     *  mosi or miso can be specfied as NC if not used
00038     *
00039     *  @param mosi SPI Master Out, Slave In pin
00040     *  @param miso SPI Master In, Slave Out pin
00041     *  @param sclk SPI Clock pin
00042     */
00043     BurstSPI(PinName mosi, PinName miso, PinName sclk) : SPI(mosi, miso, sclk) {};
00044 
00045     /** Put data packet in the SPI TX FIFO buffer
00046     *
00047     *  If there is no space in the FIFO buffer it will block until there is space.
00048     * The FIFO buffer will automatically send the packets. There is no receiving here, only transmitting.
00049     *
00050     *  @param data Data to be sent to the SPI slave
00051     */
00052     void fastWrite(int data);
00053 
00054     /** Use this function before fastWrite to set the correct settings
00055     *
00056     * It is not needed to use this if the last SPI commands were either normal SPI transmissions,
00057     * or setting different format/frequency for this object. It is required to call this
00058     * function when several SPI objects use the same peripheral, and your last transmission was
00059     * from a different object with different settings. Not sure if you should use it?
00060     * Use it, it takes very little time to execute, so can't hurt.
00061     */
00062     void setFormat( void ) {
00063         format(_bits, _mode);
00064         frequency(_hz);
00065     }
00066 
00067     /** After you are done with fastWrite, call this function
00068     *
00069     * FastWrite simply fills the SPI's (SSP's actually) TX FIFO buffer as fast as it can,
00070     * and that is the only thing it does. It doesn't do anything with received packages (currently, may change),
00071     * so the the RX buffer is full with unneeded packets. This function waits until transmission is finished,
00072     * and clears the RX buffer. You always have to call this before you want to receive
00073     * SPI data after using fastWrite.
00074     */
00075     void clearRX( void );
00076 
00077 
00078     //Just for documentation:
00079 #if 0
00080     /** Configure the data transmission format
00081      *
00082      *  @param bits Number of bits per SPI frame (4 - 16)
00083      *  @param mode Clock polarity and phase mode (0 - 3)
00084      *
00085      * @code
00086      * mode | POL PHA
00087      * -----+--------
00088      *   0  |  0   0
00089      *   1  |  0   1
00090      *   2  |  1   0
00091      *   3  |  1   1
00092      * @endcode
00093      */
00094     void format(int bits, int mode = 0);
00095 
00096     /** Set the spi bus clock frequency
00097      *
00098      *  @param hz SCLK frequency in hz (default = 1MHz)
00099      */
00100     void frequency(int hz = 1000000);
00101 
00102     /** Write to the SPI Slave and return the response
00103      *
00104      *  @param value Data to be sent to the SPI slave
00105      *
00106      *  @returns
00107      *    Response from the SPI slave
00108     */
00109     virtual int write(int value);
00110 #endif
00111 
00112 };
00113 
00114 #endif