/* Copyright 2007, Freie Universitaet Berlin. All rights reserved. These sources were developed at the Freie Universität Berlin, Computer Systems and Telematics group. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - 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. - Neither the name of Freie Universitaet Berlin (FUB) nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. This software is provided by FUB and the contributors on an "as is" basis, without any representations or warranties of any kind, express or implied including, but not limited to, representations or warranties of non-infringement, merchantability or fitness for a particular purpose. In no event shall FUB or contributors 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 implementation was developed by the CST group at the FUB. For documentation and questions please use the web site http://scatterweb.mi.fu-berlin.de and the mailinglist scatterweb@lists.spline.inf.fu-berlin.de (subscription via the Website). Berlin, 2007 */ /** * @file ScatterWeb.Sd.h * @ingroup libsd * @brief MMC-/SD-Card library, Public interface * * @author Michael Baar <baar@inf.fu-berlin.de> * @version $Revision: 1.4 $ * * $Id: sd.h,v 1.4 2008/03/31 13:48:03 nvt-se Exp $ */ /** * @ingroup libsd * @{ */ #ifndef __SD_H__ #define __SD_H__ #include "contiki-conf.h" #define SD_BLOCKLENGTH_INVALID 0xFF #define SD_WRITE_BLOCKLENGTH_BIT 9 #define SD_WRITE_BLOCKLENGTH 0x200 /****************************************************************************** * @name Setup, initialisation, configuration * @{ */ /** * @brief SD Flags * @see sd_state_t * @{ */ enum sd_state_flags { SD_READ_PARTIAL = 0x80, SD_WRITE_PARTIAL = 0x40, SD_INITIALIZED = 0x01 }; /** @} */ #ifdef __TI_COMPILER_VERSION__ #pragma pack(1) #endif /** * @brief Card Identification Register */ #ifndef __TI_COMPILER_VERSION__ __attribute__ ((packed)) #endif #if defined(__MSP430GCC__) __attribute__ ((packed)) #endif struct sd_cid { uint8_t mid; char oid[2]; char pnm[5]; uint8_t revision; uint32_t psn; uint16_t:4; uint16_t mdt:12; uint8_t crc7:7; uint8_t:1; }; #ifdef __TI_COMPILER_VERSION__ #pragma pack() #endif /** * @name Card Specific Data register * @{ */ struct sd_csd { uint8_t raw[16]; }; #define SD_CSD_READ_BL_LEN(csd) (( csd ).raw[5] & 0x0F) // uchar : 4 #define SD_CSD_READ_PARTIAL(csd) (( csd ).raw[ 6] & 0x80) // bool #define SD_CSD_CCC(csd) ( (( csd ).raw[4]<<4) | (( csd ).raw[5]>>4) ) // uchar #define SD_CSD_WRITE_PARTIAL(csd) (( csd ).raw[13] & 0x04) // bool #define SD_CSD_C_SIZE(csd) ( ((( csd ).raw[6] & 0x03)<<10) | (( csd ).raw[7]<<2) | (( csd ).raw[8]>>6) ) // uint : 12 #define SD_CSD_C_MULT(csd) ( ((( csd ).raw[9] & 0x03)<<1) | (( csd ).raw[10]>>7) ) // uchar : 4 /** @} */ /// Card access library state #define SD_CACHE_LOCKED 0x01 #define SD_CACHE_DIRTY 0x02 typedef struct { char buffer[SD_WRITE_BLOCKLENGTH]; uint32_t address; uint8_t state; } sd_cache_t; typedef struct { uint16_t MinBlockLen_bit:4; ///< minimum supported blocklength uint16_t MaxBlockLen_bit:4; ///< maximum supported blocklength uint16_t Flags:8; ///< feature flags uint8_t BlockLen_bit; ///< currently selected blocklength as bit value (n where BlockLen is 2^n) uint16_t BlockLen; ///< currently selected blocklength for reading and writing #if SD_CACHE sd_cache_t *Cache; #endif } sd_state_t; extern volatile sd_state_t sd_state; ///< Card access library state /** * @brief Library initialisation */ void sd_init(void); /** * @brief Setup ports for sd card communication * * This function needs to be called once before any other library function. * It invokes ::Spi_enable to configure UART1 for SPI communication. * * If you need to reconfigure the UART for other operations only call * ::Spi_enable to return to SPI mode. ::sd_setup needs to be run only once. */ void sd_init_platform(void); /** * @brief Return value of ::sd_init function */ enum sd_init_ret { SD_INIT_SUCCESS = 0, SD_INIT_NOCARD = 1, SD_INIT_FAILED = 2, SD_INIT_NOTSUPP = 3 }; /** * @brief Return value of write functions * @see ::sd_write, ::sd_write_block */ enum sd_write_ret { SD_WRITE_SUCCESS = 0, ///< writing successfull SD_WRITE_PROTECTED_ERR = 1, ///< card write protected SD_WRITE_INTERFACE_ERR = 2, ///< error in UART SPI interface SD_WRITE_COMMAND_ERR = 3, ///< error in write command or command arguments (e.g. target address) SD_WRITE_STORE_ERR = 4, ///< storing written data to persistant memory on card failed SD_WRITE_DMA_ERR = 5 }; /** * @brief Initialize card and state * @return one of sd_init_ret * * Initializes the memory card, checks supported voltage range and * functionality. Initializes the global state struct sd_state. * Should be invoked once immediately after ::sd_setup. */ enum sd_init_ret sd_init_card(sd_cache_t * pCache); /** * @brief Last operation to call when finished with using the card. */ void sd_close(void); /** * @brief SD Card physically present? * @return if no card present returns 0 */ #define sd_detected() ((P2IN & 0x40) == 0) /** * @brief SD Card locked by switch? * @return if card is not locked returns 0 */ #define sd_protected() ((P2IN & 0x80) != 0) /** * @brief Set blocklength to 2 ^ n * * Tries to set the card's blocklength for reading and writing to any * 2^n value, where n shall be between 0 and 11. * Be aware that a card may or may not support different blocksizes. * * Since all read and write operations have to use blockaligned addresses * and need to process complete blocks always try to use the optimal blocksize * and let ::sd_read do the rest. If the blocklength is already set to the new * value nothing is done. * * \Note * The default blocklength is 512 (n=9). SD Cards usually support partial blocks * with a blocklength of 1 to 512 (n=0 to n=9), MMC cards don't. * Large cards support blocklength up to 2048 (n=11). * The supported range of blocklengths can be read as n-value from * sd_state.BlockLenMin_bit and sd_state.BlockLneMax_bit. The current value * is available as n-value in sd_state.Blocsd_state.BlockLen_bit and as byte-value * in sd_state.BlockLen. * * @param[in] blocklength_bit blocklength as n-value of 2^n * * @return Returns blocklength_bit if set operation was successful or * SD_BLOCKLENGTH_INVALID otherwise. * */ uint8_t sd_set_blocklength(const uint8_t blocklength_bit); /** * @brief Align byte address to current blocklength * @param[in,out] pAddress address to align, will be modified to be block aligned * @return Offset from aligned address to original address */ uint16_t sd_AlignAddress(uint32_t * pAddress); /** * @brief Read one complete block from a block aligned address into buffer * * This function reads a single block of the currently set blocklength * from a block aligned address. * * \Note: If address is not block aligned the card will respond with an error * and no bytes will be read. * * @param[out] pBuffer Pointer to a buffer to which data is read. It should be least * 1 byte large * @param[in] address The address of the first byte that shall be read to pBuffer * * @return Number of bytes read (should always be = sd_state.BlockLen) */ uint16_t sd_read_block(void (*const pBuffer), const uint32_t address); #if SD_READ_BYTE /** * @brief Read one byte from any address * This function reads a single byte from any address. It is optimized for best speed * at any blocklength. * \Note: blocklength is modified * * @param[out] pBuffer Pointer to a buffer to which data is read. It should be least * 1 byte large * @param[in] address The address of the byte that shall be read to pBuffer * * @return Number of bytes read (usually 1) */ bool sd_read_byte(void *pBuffer, const uint32_t address); #endif #if SD_WRITE /** * @brief Write one complete block at a block aligned address from buffer to card * * @param[in] address block aligned address to write to * @param[in] pBuffer pointer to buffer with a block of data to write * @return result code (see enum #sd_write_ret) * * \Note * Only supported block size for writing is usually 512 bytes. */ enum sd_write_ret sd_write_block(const uint32_t address, void const (*const pBuffer)); /** * @brief Fill one complete block at a block aligned address with * a single character. * * @param[in] address block aligned address to write to * @param[in] pChar pointer to buffer with a character to write * @return result code (see enum #sd_write_ret) * * @note Use this for settings blocks to 0x00. * Only supported block size for writing is usually 512 bytes. */ enum sd_write_ret sd_set_block(const uint32_t address, const char (*const pChar)); /** * @brief Flush the DMA write buffer * * Wait for a running DMA write operation to finish */ enum sd_write_ret sd_write_flush(void); #endif #if SD_CACHE #define SD_WAIT_LOCK(x) while( x ->state & SD_CACHE_LOCKED ) { _NOP(); } #define SD_GET_LOCK(x) do { while( x ->state & SD_CACHE_LOCKED ) { _NOP(); }; x ->state |= SD_CACHE_LOCKED; } while(0) #define SD_FREE_LOCK(x) do { x ->state &= ~SD_CACHE_LOCKED; } while(0) /** * @brief Flush the sd cache * * Writes back the cache buffer, if it has been modified. Call this if * a high level operation has finished and you want to store all data * persistantly. The write back operation does not use timers. */ void sd_cache_flush(void); /** * @brief Read a block into the cache buffer * @internal * * You won't usually need this operation. */ sd_cache_t *sd_cache_read_block(const uint32_t * blAdr); #endif /** * @brief Erase (clear) blocks of data * @param[in] address Starting address of first block to erase * @param[in] numBlocks Number of blocks to erase (starting at address) * @return true if successful * @note Data can only be erased in whole blocks. All bytes will be set * predifined character (see CSD). Common cards use 0xFF. */ bool sd_erase_blocks(const uint32_t address, const uint16_t numBlocks); /** * @brief Read card identification register (CID) * @param[out] pCID Pointer to buffer for CID * @return Number of bytes read (= size of CID) or 0 if failed * * @see ::sd_cid_t */ uint16_t sd_read_cid(struct sd_cid *pCID); /** * @brief Read size of card * @return Number of bytes available * * Reads the number of bytes in the card memory from the CSD register. */ uint32_t sd_get_size(void); #if SD_READ_ANY /** * @brief Read any number of bytes from any address into buffer * * @param[out] pBuffer Pointer to a buffer to which data is read. It should be least * size bytes large * @param[in] address The address of the first byte that shall be read to pBuffer * @param[in] size Number of bytes which shall be read starting at address */ uint16_t sd_read(void *pBuffer, uint32_t address, uint16_t size); #endif #endif /*__SD_H__*/ /** @} */