spi-memory.h

Go to the documentation of this file.

#ifndef DRIVER_SPI_MEMORY_H
#define DRIVER_SPI_MEMORY_H
/**********************************************************************/
/*
 * Copyright (c) 2013-2015, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * @brief Driver for SPI-based memories.
 *
 * @author KLO, Jetro AS
 */ /******************************************************************/

#include <dev/spi.h>
#include <dev/eve-module.h>

/**
 * \defgroup spimem SPI-based memory driver
 * \ingroup abstract
 * \{
 *
 * This SPI Memory driver can be used for FLASH, EEPROM and SRAM configuration.
 *
 * The configuration data is of type struct spi_memory_t, and is used to
 * configure used memory.
 *
 */

/***********************************************************************
 * Global defines
***********************************************************************/
#define SPI_MEMORY_HINT_GENERIC          0        /**< No special handling is needed */
#define SPI_MEMORY_HINT_GENERIC_SRAM     1        /**< RAM status register is programmed for sequential access */

#define SPI_MEMORY_DATA_BUFFER_COMMAND_SIZE 4     /**< Asynchronous data buffer header (command) size */

struct spi_memory_t;
struct spi_memory_data_buffer_header;

/**
 * Asynchronous callback type
 *
 * @param Memory        Pointer to the SPI memory instance object
 * @param BufferHeader  Pointer to the header of the buffer object. To be up-casted to the target type by container_of.
 */
typedef void (* spi_memory_completion_callback_t)(const struct spi_memory_t *Memory,
                                                  struct spi_memory_data_buffer_header *BufferHeader);

struct spi_memory_state_t
{
  spi_memory_completion_callback_t CompletionCallback;
  struct spi_memory_data_buffer_header *AsyncTransfer;
};

/**
 * spi_memory_t structure is used for configuration of SPI-based memory.
 * The structure must be initialized before the memory driver may be used.
 *
 */
struct spi_memory_t
{
  const struct spi_t *Spi;               /**< SPI instance */
  struct spi_memory_state_t *State;      /**< Pointer to the dynamic SPI memory state */
  struct spi_cs_t ChipSelect;            /**< Chip select */
  uint32_t Baudrate;                     /**< Baudrate */
  uint8_t MemorySizeExponent;            /**< Exponent for memory size (example value 15: 2^15 = 32768) */
  uint8_t PageSizeExponent;              /**< Exponent for page size */
  uint8_t SectorSizeExponent;            /**< Exponent for sector size */
  uint8_t BlockSizeExponent;             /**< Exponent for block size */
  uint32_t AddressBytes : 3;             /**< Number of bytes in the address */
  uint32_t HasPowerControl : 1;          /**< true if memory has power down instruction */
  uint32_t HasProtection : 1;            /**< true if memory has protection bits */
  uint32_t HasChipErase : 1;             /**< true if memory has chip erase instruction */
  uint32_t HasWriteEnable : 1;           /**< true if memory has write enable instruction */
  uint32_t HasProgrammingTime : 1;       /**< true if memory needs programming time after a programming instruction */
  uint32_t HasPowerPort : 1;             /**< true if memory power pin is controlled by external power switch */
  uint32_t Reserved1 : 3;
  uint32_t PowerPin : 5;                 /**< If HasPowerPort = true: Set port pin (0 - 31) */
  uint32_t PowerActiveHigh : 1;          /**< If HasPowerPort = true: Set true if PowerPin is active high, else false */
  uint32_t Reserved2 : 6;
  uint32_t Hint : 8;                     /**< != 0 if memory need special program */
  uint16_t EnterPdTimeUs;                /**< Time needed to enter power down (us) */
  uint16_t ReleasePdTimeAfterCommandUs;  /**< Time needed to release from power down after release command (us) */
  uint16_t ReleasePdTimeAfterCsActiveUs; /**< Time needed to release from power down after chip select active (us) */
  uint16_t VccPowerUpTimeUs;             /**< If HasPowerPort = true: Time needed after PowerPin is active (us) */
  uint8_t PowerUpTimeMs;                 /**< Time needed after power on (ms) */
};

/**
 * spi_memory_data_buffer_header structure represents a buffer for SPI command exchange towards memory chip.
 * Asynchronous data transfer functions use the buffer as a storage for the 'command' part of the SPI message.
 */
struct spi_memory_data_buffer_header
{
  uint8_t Command[SPI_MEMORY_DATA_BUFFER_COMMAND_SIZE]; /**< Command buffer */
};

/**
 * Defines a new type for the asynchronous SPI memory buffer of the desired size.
 *
 * @param type        Typename of the newly created type.
 * @param size        Amount of bytes in the 'data' part of the message.
 */
#define SPI_MEMORY_DATA_BUFFER_TYPE(type, size) \
  typedef struct type \
  { \
    struct spi_memory_data_buffer_header Header; \
    uint8_t Data[(size)]; \
  } type

/**
 * Defines a type for a generic buffer with unknown size.
 */
SPI_MEMORY_DATA_BUFFER_TYPE(spi_memory_generic_buffer_t, 0);

 /**
  * @name Functions called from application programs
  * @{
  */

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryInit\n
 * Waits for power on and then release SPI memory from deep powerdown. KØ!! ????????????
 * Called from main program level.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @return          true if SPI memory was initialized, else false
 ***********************************************************************/
extern bool SpiMemoryInit(const struct spi_memory_t *Memory);

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryDisable\n
 * Sets SPI memory in deep powerdown.
 * Called from main program level.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @return          true if SPI memory was set disabled, else false
 ***********************************************************************/
extern bool SpiMemoryDisable(const struct spi_memory_t *Memory);

/**********************************************************************/
/**
 * @brief Name:      SpiMemorySetWriteProtection\n
 * Sets write protection for SPI memory and waits for completion.
 * Called from main program level.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param Protection Parameters for protection to be used
 * @return           true if SPI memory protection was set properly, else false
 ***********************************************************************/
extern bool SpiMemorySetWriteProtection(const struct spi_memory_t *Memory,
                                        enum spi_memory_protection_t Protection);

/**********************************************************************/
/**
 * @brief Name:       SpiMemoryEraseSectorAsync\n
 * Begines erasing given sector in SPI memory.
 * Called from main program level.
 * At function return SPI transfer is completed; erase is started, but not completed.
 * Caller code should use SpiMemoryIsBusy to wait for the completion.
 *
 * @param Memory      Pointer to the SPI memory instance object
 * @param SectorIndex Index for sector to be erased (0 to < (.MemorySize / .SectorSize))
 * @return            true if SPI memory sector erase command was sent, else false
 ***********************************************************************/
extern bool SpiMemoryEraseSectorAsync(const struct spi_memory_t *Memory,
                                      uint32_t SectorIndex);

/**********************************************************************/
/**
 * @brief Name:       SpiMemoryEraseSector\n
 * Erases given sector in SPI memory and waits for completion.
 * Called from main program level.
 *
 * @param Memory      Pointer to the SPI memory instance object
 * @param SectorIndex Index for sector to be erased (0 to < (.MemorySize / .SectorSize))
 * @return            true if SPI memory sector was erased, else false
 ***********************************************************************/
extern bool SpiMemoryEraseSector(const struct spi_memory_t *Memory,
                                 uint32_t SectorIndex);

/**********************************************************************/
/**
 * @brief Name:       SpiMemoryEraseBlockAsync\n
 * Begines erasing given block in SPI memory.
 * Called from main program level.
 * At function return SPI transfer is completed; erase is started, but not completed.
 * Caller code should use SpiMemoryIsBusy to wait for the completion.
 *
 * @param Memory      Pointer to the SPI memory instance object
 * @param BlockIndex  Index for block to be erased (0 to < (.MemorySize / .BlockSize))
 * @return            true if SPI memory block erase command was sent, else false
 ***********************************************************************/
extern bool SpiMemoryEraseBlockAsync(const struct spi_memory_t *Memory,
                                     uint32_t BlockIndex);

/**********************************************************************/
/**
 * @brief Name:       SpiMemoryEraseBlock\n
 * Erases given block in SPI memory and waits for completion.
 * Called from main program level.
 *
 * @param Memory      Pointer to the SPI memory instance object
 * @param BlockIndex  Index for block to be erased (0 to < (.MemorySize / .BlockSize))
 * @return            true if SPI memory block was erased, else false
 ***********************************************************************/
extern bool SpiMemoryEraseBlock(const struct spi_memory_t *Memory,
                                uint32_t BlockIndex);

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryEraseAsync\n
 * Begines erasing the whole SPI memory.
 * Called from main program level.
 * At function return SPI transfer is completed; erase is started, but not completed.
 * Caller code should use SpiMemoryIsBusy to wait for the completion.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @return          true if SPI memory erase command was sent, else false
 ***********************************************************************/
extern bool SpiMemoryEraseAsync(const struct spi_memory_t *Memory);

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryErase\n
 * Erases the whole SPI memory and waits for completion.
 * Called from main program level.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @return          true if SPI memory was erased, else false
 ***********************************************************************/
extern bool SpiMemoryErase(const struct spi_memory_t *Memory);

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryReadAsync\n
 * Reads bytes from SPI memory to DstBuffer.
 * Called from main program level.
 * Does not wait for completion, the completion callback is called instead
 * when transfer is finished. Calling code should not use SPI bus until
 * the completion callback is called.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param DstBuffer  Destination buffer for read data.
 * @param SrcAddress Address of first byte to read from SPI memory
 * @param ByteCount  Number of bytes to read from SPI memory
 * @param Callback   Completion callback
 * @return           true if SPI memory read command was sent, else false
 ***********************************************************************/
extern bool SpiMemoryReadAsync(const struct spi_memory_t *Memory,
                               struct spi_memory_data_buffer_header *DstBuffer,
                               uint32_t SrcAddress,
                               uint32_t ByteCount,
                               spi_memory_completion_callback_t Callback);

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryRead\n
 * Reads bytes from SPI memory to DstBuffer.
 * Called from main program level.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param DstBuffer  Destination buffer for read data
 * @param SrcAddress Address of first byte to read from SPI memory
 * @param ByteCount  Number of bytes to read from SPI memory
 * @return           true if SPI memory was read, else false
 ***********************************************************************/
extern bool SpiMemoryRead(const struct spi_memory_t *Memory,
                          void *DstBuffer,
                          uint32_t SrcAddress,
                          uint32_t ByteCount);

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryReadPageAsync\n
 * Reads the page PageIndex from SPI memory to DstBuffer.
 * Called from main program level.
 * Does not wait for completion, the completion callback is called instead
 * when transfer is finished. Calling code should not use SPI bus until
 * the completion callback is called.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @param DstBuffer Destination buffer for read data
 * @param PageIndex Index of page to read from SPI memory
 * @param Callback   Completion callback
 * @return          true if SPI memory was read, else false
 ***********************************************************************/
static inline bool SpiMemoryReadPageAsync(const struct spi_memory_t *Memory,
                                          struct spi_memory_data_buffer_header *DstBuffer,
                                          uint32_t PageIndex,
                                          spi_memory_completion_callback_t Callback)
{
  return SpiMemoryReadAsync(Memory, DstBuffer, PageIndex << Memory->PageSizeExponent, 1 << Memory->PageSizeExponent, Callback);
}

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryReadPage\n
 * Reads the page PageIndex from SPI memory to DstBuffer.
 * Called from main program level.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @param DstBuffer Destination buffer for read data
 * @param PageIndex Index of page to read from SPI memory
 * @return          true if SPI memory was read, else false
 ***********************************************************************/
static inline bool SpiMemoryReadPage(const struct spi_memory_t *Memory,
                                     void *DstBuffer,
                                     uint32_t PageIndex)
{
  return SpiMemoryRead(Memory, DstBuffer, PageIndex << Memory->PageSizeExponent, 1 << Memory->PageSizeExponent);
}

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryReadPageWithOffsetAsync\n
 * Reads the page PageIndex with offset from SPI memory to DstBuffer.
 * Called from main program level.
 * Does not wait for completion, the completion callback is called instead
 * when transfer is finished. Calling code should not use SPI bus until
 * the completion callback is called.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param DstBuffer  Destination buffer for read data
 * @param PageIndex  Index of page to read from SPI memory
 * @param PageOffset Offset in page, must be < .PageSize
 * @param ByteCount  Number of bytes to read from SPI memory
 * @param Callback   Completion callback
 * @return           true if SPI memory was read, else false
 ***********************************************************************/
static inline bool SpiMemoryReadPageWithOffsetAsync(const struct spi_memory_t *Memory,
                                                    struct spi_memory_data_buffer_header *DstBuffer,
                                                    uint32_t PageIndex,
                                                    uint32_t PageOffset,
                                                    uint32_t ByteCount,
                                                    spi_memory_completion_callback_t Callback)
{
  return SpiMemoryReadAsync(Memory, DstBuffer, (PageIndex << Memory->PageSizeExponent) + PageOffset, ByteCount, Callback);
}

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryReadPageWithOffset\n
 * Reads the page PageIndex with offset from SPI memory to DstBuffer.
 * Called from main program level.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param DstBuffer  Destination buffer for read data
 * @param PageIndex  Index of page to read from SPI memory
 * @param PageOffset Offset in page, must be < .PageSize
 * @param ByteCount  Number of bytes to read from SPI memory
 * @return           true if SPI memory was read, else false
 ***********************************************************************/
static inline bool SpiMemoryReadPageWithOffset(const struct spi_memory_t *Memory,
                                               void *DstBuffer,
                                               uint32_t PageIndex,
                                               uint32_t PageOffset,
                                               uint32_t ByteCount)
{
  return SpiMemoryRead(Memory, DstBuffer, (PageIndex << Memory->PageSizeExponent) + PageOffset, ByteCount);
}

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryWriteAsync\n
 * Writes bytes from SrcBuffer to SPI memory.
 * It the SPI memory is page based, the data must fit into a single page, and
 * the page must be erased before writing.
 * Return after writing is finished.
 * Called from main program level.
 * Does not wait for completion, the completion callback is called instead
 * when SPI transfer is finished. Calling code should not use SPI bus until
 * the completion callback is called. Note that completion of the in-chip
 * writing process is not indicated by any kind of callback. Calling code
 * should use SpiMemoryIsBusy to wait for the completion.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param DstAddress Address of first byte to write to SPI memory
 * @param SrcBuffer  Source buffer for the data to be written
 * @param ByteCount  Number of bytes to write to SPI memory
 * @param Callback   Completion callback
 * @return           true if SPI memory was written, else false
 ***********************************************************************/
extern bool SpiMemoryWriteAsync(const struct spi_memory_t *Memory,
                                uint32_t DstAddress,
                                struct spi_memory_data_buffer_header *SrcBuffer,
                                uint32_t ByteCount,
                                spi_memory_completion_callback_t Callback);

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryWrite\n
 * Writes bytes from SrcBuffer to SPI memory.
 * It the SPI memory is page based, the data must fit into a single page, and
 * the page must be erased before writing.
 * Return after writing is finished.
 * Called from main program level.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param DstAddress Address of first byte to write to SPI memory
 * @param SrcBuffer  Source buffer for the data to be written
 * @param ByteCount  Number of bytes to write to SPI memory
 * @return           true if SPI memory was written, else false
 ***********************************************************************/
extern bool SpiMemoryWrite(const struct spi_memory_t *Memory,
                           uint32_t DstAddress,
                           const void *SrcBuffer,
                           uint32_t ByteCount);

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryWritePageAsync\n
 * Writes page data from SrcBuffer to page PageIndex in SPI memory.
 * The page must be erased before writing.
 * Return after writing is finished.
 * Called from main program level.
 * Does not wait for completion, the completion callback is called instead
 * when SPI transfer is finished. Calling code should not use SPI bus until
 * the completion callback is called. Note that completion of the in-chip
 * writing process is not indicated by any kind of callback. Calling code
 * should use SpiMemoryIsBusy to wait for the completion.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @param PageIndex Index of page to write to SPI memory
 * @param SrcBuffer Source buffer for page data to be written
 * @param Callback  Completion callback
 * @return          true if SPI memory was written, else false
 ***********************************************************************/
static inline bool SpiMemoryWritePageAsync(const struct spi_memory_t *Memory,
                                           uint32_t PageIndex,
                                           struct spi_memory_data_buffer_header *SrcBuffer,
                                           spi_memory_completion_callback_t Callback)
{
  return SpiMemoryWriteAsync(Memory, PageIndex << Memory->PageSizeExponent, SrcBuffer, 1 << Memory->PageSizeExponent, Callback);
}

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryWritePage\n
 * Writes page data from SrcBuffer to page PageIndex in SPI memory.
 * The page must be erased before writing.
 * Return after writing is finished.
 * Called from main program level.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @param PageIndex Index of page to write to SPI memory
 * @param SrcBuffer Source buffer for page data to be written
 * @return          true if SPI memory was written, else false
 ***********************************************************************/
static inline bool SpiMemoryWritePage(const struct spi_memory_t *Memory, uint32_t PageIndex, const void *SrcBuffer)
{
  return SpiMemoryWrite(Memory, PageIndex << Memory->PageSizeExponent, SrcBuffer, 1 << Memory->PageSizeExponent);
}

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryVerify\n
 * Verifies data in SPI memory with SrcBuffer.
 * Called from main program level.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param SrcAddress First address to be verified in SPI memory
 * @param SrcBuffer  Source buffer for data to be verified
 * @param ByteCount  Number of bytes to verify in SPI memory
 * @return           true if flash is accessable and verify OK, else false
 ***********************************************************************/
extern bool SpiMemoryVerify(const struct spi_memory_t *Memory, uint32_t SrcAddress, const void *SrcBuffer, uint32_t ByteCount);

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryVerifyPage\n
 * Verifies data in page PageIndex in SPI memory with SrcBuffer.
 * Called from main program level.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @param PageIndex Index of page to be verified in SPI memory
 * @param SrcBuffer Source buffer for data to be verified
 * @return          true if flash is accessable and verify OK, else false
 ***********************************************************************/
static inline bool SpiMemoryVerifyPage(const struct spi_memory_t *Memory, uint32_t PageIndex, const void *SrcBuffer)
{
  return (SpiMemoryVerify(Memory, PageIndex << Memory->PageSizeExponent, SrcBuffer, 1 << Memory->PageSizeExponent));
}

/**********************************************************************/
/**
 * @brief Name:     SpiMemoryIsBusy\n
 * Checks if the memory write or erase operation is in progress
 * Called from main program level.
 *
 * @param Memory    Pointer to the SPI memory instance object
 * @return          true if flash is busy, else false
 ***********************************************************************/
extern bool SpiMemoryIsBusy(const struct spi_memory_t *Memory);

#ifdef CONTIKI
/**********************************************************************/
/**
 * @brief Name:      SpiMemoryChecksum\n
 * Calculates CRC16 checksum for given range in SPI memory.
 * Checksum is used as both input and output argument.
 * Called from main program level.
 *
 * @param Memory     Pointer to the SPI memory instance object
 * @param Checksum   Pointer to checksum accumulator
 * @param SrcAddress First address to be verified in SPI memory
 * @param ByteCount  Number of bytes to verify in SPI memory
 * @param Inverse    Inverse content of the flash before the checksuming
 * @return           true if flash is accessable, else false
 ***********************************************************************/
extern bool SpiMemoryChecksum(const struct spi_memory_t *Memory,
                              uint16_t *Checksum,
                              uint32_t SrcAddress,
                              uint32_t ByteCount,
                              bool Inverse);
#endif /* CONTIKI */

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryPowerUp\n
 * Power up VCC for SPI memory.
 * SpiEnable() must be called after this function to get SPI pin setup.
 * Only to be used from EveSpiPowerUp()
 *
 * @param Memory     Pointer to the SPI memory instance object
 **********************************************************************/
extern void SpiMemoryPowerUp(const struct spi_memory_t *Memory);

/**********************************************************************/
/**
 * @brief Name:      SpiMemoryPowerDown\n
 * Power down VCC for SPI memory.
 * SpiDisable() must be called prior to this function to get default pin setup.
 * Only to be used from EveSpiPowerDown()
 *
 * @param Memory     Pointer to the SPI memory instance object
 **********************************************************************/
extern void SpiMemoryPowerDown(const struct spi_memory_t *Memory);

/** @} */
/** \} */

#endif // DRIVER_SPI_MEMORY_H