git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M4_SimpleLink_CC3220SF_CCS/ti/drivers/SD.h

   1 /*
   2  * Copyright (c) 2016, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /** ============================================================================
  34  *  @file       SD.h
  35  *
  36  *  @brief      SD driver interface
  37  *
  38  *  The SD header file should be included in an application as follows:
  39  *  @code
  40  *  #include <ti/drivers/SD.h>
  41  *  @endcode
  42  *
  43  *  # Operation #
  44  *
  45  *  The SD driver is designed to serve as an interface to perform basic
  46  *  transfers directly to the SD card.
  47  *
  48  *  ## Opening the driver #
  49  *
  50  *  @code
  51  *  SD_Handle handle;
  52  *
  53  *  handle = SD_open(index, NULL);
  54  *  if (handle == NULL) {
  55  *      System_printf("Error opening SD driver\n");
  56  *  }
  57  *  @endcode
  58  *
  59  *  # Implementation #
  60  *
  61  *  This module serves as the main interface for TI-RTOS applications. Its
  62  *  purpose is to redirect the module's APIs to specific peripheral
  63  *  implementations which are specified using a pointer to a
  64  *  SD_FxnTable.
  65  *
  66  *  The SD driver interface module is joined (at link time) to a
  67  *  NULL-terminated array of SD_Config data structures named *SD_config*.
  68  *  *SD_config* is implemented in the application with each entry being an
  69  *  instance of a SD peripheral. Each entry in *SD_config* contains a:
  70  *  - (SD_FxnTable *) to a set of functions that implement a SD peripheral
  71  *  - (uintptr_t) data object that is associated with the SD_FxnTable
  72  *  - (uintptr_t) hardware attributes that are associated to the SD_FxnTable
  73  *
  74  *  # Instrumentation #
  75  *
  76  *  The SD driver interface produces log statements if
  77  *  instrumentation is enabled.
  78  *
  79  *  Diagnostics Mask | Log details                   |
  80  *  ---------------- | -----------                   |
  81  *  Diags_USER1      | basic operations performed    |
  82  *  Diags_USER2      | detailed operations performed |
  83  *
  84  *  ============================================================================
  85  */
  86
  87 #ifndef ti_drivers_SD__include
  88 #define ti_drivers_SD__include
  89
  90 #ifdef __cplusplus
  91 extern "C" {
  92 #endif
  93
  94 #include <stdint.h>
  95
  96 /**
  97  *  @defgroup SD_CONTROL SD_control command and status codes
  98  *  @{
  99  */
 100
 101 /*!
 102  * Common SD_control command code reservation offset.
 103  * SD driver implementations should offset command codes with
 104  * SD_CMD_RESERVED growing positively.
 105  *
 106  * Example implementation specific command codes:
 107  * @code
 108  * #define SDXYZ_CMD_COMMAND0    (SD_CMD_RESERVED + 0)
 109  * #define SDXYZ_CMD_COMMAND1    (SD_CMD_RESERVED + 1)
 110  * @endcode
 111  */
 112 #define SD_CMD_RESERVED    (32)
 113
 114 /*!
 115  * Common SD_control status code reservation offset.
 116  * SD driver implementations should offset status codes with
 117  * SD_STATUS_RESERVED growing negatively.
 118  *
 119  * Example implementation specific status codes:
 120  * @code
 121  * #define SDXYZ_STATUS_ERROR0    (SD_STATUS_RESERVED - 0)
 122  * #define SDXYZ_STATUS_ERROR1    (SD_STATUS_RESERVED - 1)
 123  * #define SDXYZ_STATUS_ERROR2    (SD_STATUS_RESERVED - 2)
 124  * @endcode
 125  */
 126 #define SD_STATUS_RESERVED    (-32)
 127
 128 /**
 129  *  @defgroup SD_STATUS Status Codes
 130  *  SD_STATUS_* macros are general status codes returned by SD_control()
 131  *  @{
 132  *  @ingroup SD_CONTROL
 133  */
 134
 135 /*!
 136  * @brief Successful status code returned by SD_control().
 137  *
 138  * SD_control() returns SD_STATUS_SUCCESS if the control code was executed
 139  * successfully.
 140  */
 141 #define SD_STATUS_SUCCESS    (0)
 142
 143 /*!
 144  * @brief Generic error status code returned by SD_control().
 145  *
 146  * SD_control() returns SD_STATUS_ERROR if the control code
 147  * was not executed successfully.
 148  */
 149 #define SD_STATUS_ERROR    (-1)
 150
 151 /*!
 152  * @brief   An error status code returned by SD_control() for
 153  * undefined command codes.
 154  *
 155  * SD_control() returns SD_STATUS_UNDEFINEDCMD if the
 156  * control code is not recognized by the driver implementation.
 157  */
 158 #define SD_STATUS_UNDEFINEDCMD    (-2)
 159 /** @}*/
 160
 161 /**
 162  *  @defgroup SD_CMD Command Codes
 163  *  SD_CMD_* macros are general command codes for SD_control(). Not all SD
 164  *  driver implementations support these command codes.
 165  *  @{
 166  *  @ingroup SD_CONTROL
 167  */
 168
 169 /* Add SD_CMD_<commands> here */
 170
 171 /** @}*/
 172
 173 /** @}*/
 174
 175 /*!
 176  *  @brief  SD Card type inserted
 177  */
 178 typedef enum SD_CardType_ {
 179     SD_NOCARD = 0, /*!< Unrecognized Card */
 180     SD_MMC = 1,    /*!< Multi-media Memory Card (MMC) */
 181     SD_SDSC = 2,   /*!< Standard SDCard (SDSC) */
 182     SD_SDHC = 3    /*!< High Capacity SDCard (SDHC) */
 183 } SD_CardType;
 184
 185 /*!
 186  *  @brief      A handle that is returned from a SD_open() call.
 187  */
 188 typedef struct SD_Config_ *SD_Handle;
 189
 190 /*!
 191  *  @brief SD Parameters
 192  *
 193  *  SD Parameters are used to with the SD_open() call.
 194  *  Default values for these parameters are set using SD_Params_init().
 195  *
 196  *  @sa SD_Params_init()
 197  */
 198
 199 /* SD Parameters */
 200 typedef struct SD_Params_ {
 201     void   *custom;  /*!< Custom argument used by driver implementation */
 202 } SD_Params;
 203
 204 /*!
 205  *  @brief A function pointer to a driver specific implementation of
 206  *         SD_CloseFxn().
 207  */
 208 typedef void (*SD_CloseFxn) (SD_Handle handle);
 209
 210 /*!
 211  *  @brief A function pointer to a driver specific implementation of
 212  *         SD_controlFxn().
 213  */
 214 typedef int_fast16_t (*SD_ControlFxn) (SD_Handle handle,
 215     uint_fast16_t cmd, void *arg);
 216
 217 /*!
 218  *  @brief A function pointer to a driver specific implementation of
 219  *         SD_getNumSectorsFxn().
 220  */
 221 typedef uint_fast32_t (*SD_getNumSectorsFxn) (SD_Handle handle);
 222
 223 /*!
 224  *  @brief A function pointer to a driver specific implementation of
 225  *         SD_getSectorSizeFxn().
 226  */
 227 typedef uint_fast32_t (*SD_getSectorSizeFxn) (void);
 228
 229 /*!
 230  *  @brief A function pointer to a driver specific implementation of
 231  *         SD_InitFxn().
 232  */
 233 typedef void (*SD_InitFxn) (SD_Handle handle);
 234
 235 /*!
 236  *  @brief A function pointer to a driver specific implementation of
 237  *         SD_initializeFxn().
 238  */
 239 typedef int_fast16_t (*SD_InitializeFxn) (SD_Handle handle);
 240
 241 /*!
 242  *  @brief A function pointer to a driver specific implementation of
 243  *         SD_OpenFxn().
 244  */
 245 typedef SD_Handle (*SD_OpenFxn) (SD_Handle handle, SD_Params *params);
 246
 247 /*!
 248  *  @brief A function pointer to a driver specific implementation of
 249  *         SD_readFxn().
 250  */
 251 typedef int_fast16_t (*SD_ReadFxn) (SD_Handle handle, void *buf,
 252     int_fast32_t sector, uint_fast32_t secCount);
 253
 254 /*!
 255  *  @brief A function pointer to a driver specific implementation of
 256  *         SD_writeFxn().
 257  */
 258 typedef int_fast16_t (*SD_WriteFxn) (SD_Handle handle, const void *buf,
 259     int_fast32_t sector, uint_fast32_t secCount);
 260
 261 /*!
 262  *  @brief The definition of a SD function table that contains the
 263  *         required set of functions to control a specific SD driver
 264  *         implementation.
 265  */
 266 typedef struct SD_FxnTable_ {
 267     /*! Function to close the specified peripheral */
 268     SD_CloseFxn             closeFxn;
 269     /*! Function to implementation specific control function */
 270     SD_ControlFxn           controlFxn;
 271     /*! Function to return the total number of sectors on the SD card */
 272     SD_getNumSectorsFxn     getNumSectorsFxn;
 273     /*! Function to return the sector size used to address the SD card */
 274     SD_getSectorSizeFxn     getSectorSizeFxn;
 275     /*! Function to initialize the given data object */
 276     SD_InitFxn              initFxn;
 277     /*! Function to initialize the SD card */
 278     SD_InitializeFxn        initializeFxn;
 279     /*! Function to open the specified peripheral */
 280     SD_OpenFxn              openFxn;
 281     /*! Function to read from the SD card */
 282     SD_ReadFxn              readFxn;
 283     /*! Function to write to the SD card */
 284     SD_WriteFxn             writeFxn;
 285 } SD_FxnTable;
 286
 287 /*!
 288  *  @brief SD Global configuration
 289  *
 290  *  The SD_Config structure contains a set of pointers used
 291  *  to characterize the SD driver implementation.
 292  *
 293  *  This structure needs to be defined before calling SD_init() and it must
 294  *  not be changed thereafter.
 295  *
 296  *  @sa SD_init()
 297  */
 298 typedef struct SD_Config_ {
 299     /*! Pointer to a table of driver-specific implementations of SD APIs */
 300     SD_FxnTable const    *fxnTablePtr;
 301
 302     /*! Pointer to a driver specific data object */
 303     void                 *object;
 304
 305     /*! Pointer to a driver specific hardware attributes structure */
 306     void const           *hwAttrs;
 307 } SD_Config;
 308
 309 /*!
 310  *  @brief Function to close a SD peripheral specified by the SD handle.
 311  *
 312  *  @pre SD_open() had to be called first.
 313  *
 314  *  @param handle A SD handle returned from SD_open
 315  *
 316  *  @sa SD_open()
 317  */
 318 extern void SD_close(SD_Handle handle);
 319
 320 /*!
 321  *  @brief  Function performs implementation specific features on a given
 322  *          SD_Handle.
 323  *
 324  *  Commands for SD_control can originate from SD.h or from implementation
 325  *  specific SD*.h (SDHostCC32XX.h etc.. ) files.
 326  *  While commands from SD.h are API portable across driver implementations,
 327  *  not all implementations may support all these commands.
 328  *  Conversely, commands from driver implementation specific SD*.h files add
 329  *  unique driver capabilities but are not API portable across all SD driver
 330  *  implementations.
 331  *
 332  *  Commands supported by SD.h follow a SD*_CMD naming
 333  *  convention.
 334  *
 335  *  Commands supported by SD*.h follow a SD*_CMD naming
 336  *  convention.
 337  *  Each control command defines arg differently. The types of arg are
 338  *  documented with each command.
 339  *
 340  *  See @ref SD_CMD "SD_control command codes" for command codes.
 341  *
 342  *  See @ref SD_STATUS "SD_control return status codes" for status codes.
 343  *
 344  *  @pre SD_open() has to be called first.
 345  *
 346  *  @param handle A SD handle returned from SD_open().
 347  *
 348  *  @param cmd SD.h or SD*.h commands.
 349  *
 350  *  @param arg An optional R/W (read/write) command argument
 351  *              accompanied with cmd.
 352  *
 353  *  @return Implementation specific return codes. Negative values indicate
 354  *          unsuccessful operations.
 355  *
 356  *  @sa SD_open()
 357  */
 358 extern int_fast16_t SD_control(SD_Handle handle, uint_fast16_t cmd, void *arg);
 359
 360 /*!
 361  *  @brief A function pointer to a driver specific implementation of
 362  *         SD_getNumSectors().
 363  *         Note: Total Card capacity is the (NumberOfSectors * SectorSize).
 364  *
 365  *  @pre SD Card has been initialized using SD_initialize().
 366  *
 367  *  @param  handle A SD handle returned from SD_open().
 368  *
 369  *  @return The total number of sectors on the SD card,
 370  *          or 0 if an error occurred.
 371  *
 372  *  @sa SD_initialize()
 373  */
 374 extern uint_fast32_t SD_getNumSectors(SD_Handle handle);
 375
 376 /*!
 377  *  @brief Function to obtain the sector size used to access the SD card.
 378  *
 379  *  @pre SD Card has been initialized using SD_initialize().
 380  *
 381  *  @param handle A SD handle returned from SD_open().
 382  *
 383  *  @return The sector size set for use during SD card read/write operations.
 384  *
 385  *  @sa SD_initialize()
 386  */
 387 extern uint_fast32_t SD_getSectorSize(SD_Handle handle);
 388
 389 /*!
 390  *  @brief This function initializes the SD driver.
 391  *
 392  *  @pre The SD_config structure must exist and be persistent before this
 393  *       function can be called. This function must also be called before
 394  *       any other SD driver APIs. This function call does not modify any
 395  *       peripheral registers.
 396  */
 397 extern void SD_init(void);
 398
 399 /*!
 400  *  @brief Function to initialize the SD_Params struct to its defaults.
 401  *
 402  *  @param params A pointer to SD_Params structure for initialization.
 403  */
 404 extern void SD_Params_init(SD_Params *params);
 405
 406  /*!
 407  *  @brief  A function pointer to a driver specific implementation of
 408  *          SD_initialize().
 409  *
 410  *  @pre    SD controller has been opened by calling SD_open().
 411  *
 412  *  @param  handle A SD handle returned from SD_open().
 413  *
 414  *  @return SD_STATUS_SUCCESS if no errors occurred during the initialization,
 415  *          SD_STATUS_ERROR otherwise.
 416  */
 417 extern int_fast16_t SD_initialize(SD_Handle handle);
 418
 419 /*!
 420  *  @brief A function pointer to a driver specific implementation of
 421  *          SD_open().
 422  *
 423  *  @pre SD controller has been initialized using SD_init().
 424  *
 425  *  @param index  Logical peripheral number for the SD indexed into
 426  *                the SD_config table.
 427  *
 428  *  @param params Pointer to a parameter block, if NULL it will use
 429  *                default values. All the fields in this structure are
 430  *                RO (read-only).
 431  *
 432  *  @return A SD_Handle on success or a NULL on an error or if it has been
 433  *          opened already.
 434  *
 435  *  @sa SD_init()
 436  *  @sa SD_close()
 437  */
 438 extern SD_Handle SD_open(uint_least8_t index, SD_Params *params);
 439
 440 /*!
 441  *  @brief A function pointer to a driver specific implementation of
 442  *          SD_read().
 443  *
 444  *  @pre SD controller has been opened and initialized by calling SD_open()
 445  *       followed by SD_initialize().
 446  *
 447  *  @param handle A SD handle returned from SD_open().
 448  *
 449  *  @param buf Pointer to a buffer to read data into.
 450  *
 451  *  @param sector Starting sector on the disk to read from.
 452  *
 453  *  @param secCount Number of sectors to be read.
 454  *
 455  *  @return SD_STATUS_SUCCESS if no errors occurred during the write,
 456  *          SD_STATUS_ERROR otherwise.
 457  *
 458  *  @sa SD_initialize()
 459  */
 460 extern int_fast16_t SD_read(SD_Handle handle, void *buf,
 461     int_fast32_t sector, uint_fast32_t secCount);
 462
 463 /*!
 464  *  @brief A function pointer to a driver specific implementation of
 465  *         SD_write().
 466  *
 467  *  @pre SD controller has been opened and initialized by calling SD_open()
 468  *       followed by SD_initialize().
 469  *
 470  *  @param  handle A SD handle returned from SD_open().
 471  *
 472  *  @param  buf Pointer to a buffer containing data to write to disk.
 473  *
 474  *  @param  sector Starting sector on the disk to write to.
 475  *
 476  *  @param  secCount Number of sectors to be written.
 477  *
 478  *  @return SD_STATUS_SUCCESS if no errors occurred during the write,
 479  *          SD_STATUS_ERROR otherwise.
 480  *
 481  *  @sa     SD_initialize()
 482  */
 483 extern int_fast16_t SD_write(SD_Handle handle, const void *buf,
 484     int_fast32_t sector, uint_fast32_t secCount);
 485
 486 #ifdef __cplusplus
 487 }
 488 #endif
 489
 490 #endif /* ti_drivers_SD__include */