1    /* 
     2     * Copyright (c) 2012, 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     *  ======== FatFS.xdc ========
    34     */
    35    
    36    /*!
    37     *  ======== FatFS ========
    38     *  Configuration and integration of the open-source FAT filesystem project,
    39     *  FatFs, with SYS/BIOS.
    40     *
    41     *  The FatFs project homepage: http://elm-chan.org/fsw/ff/00index_e.html
    42     *
    43     *  This initial integration supports (only) a simple RAM disk. The FatFs source
    44     *  is included and pre-built, together with support for SYS/BIOS
    45     *  synchronization. Also included is an implementation of the "device I/O"
    46     *  model for the TI compiler C runtime support (RTS) library. This provides
    47     *  transparent support for using the C stdio.h library functions (fopen,
    48     *  fwrite, fclose) instead of the raw, project-specific, API functions
    49     *  provided by FatFs (f_open, f_write).
    50     *
    51     *  The configuration options initially defined here are subject to change
    52     *  as more device driver support is added, such as MMC/SD, SATA, and USB.
    53     *
    54     *  To incorporate the FatFs functionality into an application, simply "use"
    55     *  this module in a SYS/BIOS configuration. This will automatically generate
    56     *  a startup function to "plug in" the filesystem into the TI RTS, and provide
    57     *  the needed libraries for linking. xgconf users can simply right-click on
    58     *  the module icon and select "Use Module". Script users simply add a
    59     *  xdc.useModule("ti.sysbios.fatfs.FatFS") to their .cfg file.
    60     *
    61     *  There are currently three configuration options, one related to the C
    62     *  RTS stdio implementation, and two for the ramdisk support. First, the
    63     *  fatfsPrefix parameter is used as the namespace "prefix" for the C RTS
    64     *  fopen() function. See the TI C Compiler User's Guide (such as spru187)
    65     *  for more details. Basically, this prefix must be supplied as part of the
    66     *  filename when calling fopen(). For example, with the default value of
    67     *  "fat", an application would use:
    68     *
    69     *  @p(code)
    70     *  FILE * fp = fopen("fat:/signal.dat", "w");
    71     *  @p
    72     *
    73     *  Note the ":" as a separator. This must be part of the fopen() call, but
    74     *  is not specified as part of the fatfsPrefix configuration parameter.
    75     *
    76     *  The other parameters control how the RAM disk is configured into the
    77     *  system. The ramdiskSymbolName parameter can be used to specify an
    78     *  address of a pre-initialized (formatted) filesystem. This would be
    79     *  typically provided by linking in a (large) C data array. When using this
    80     *  parameter, the other configuration parameter, ramdiskSize, should be set
    81     *  to the size of the data array in units of bytes.
    82     *
    83     *  For example, assume a FAT filesystem that has been "serialized"
    84     *  into the file ramdisk.c that contains the following:
    85     *
    86     *  @p(code)
    87     *  unsigned int ramdiskData[32768] = {
    88     *  @p
    89     *
    90     *  then the values for these two configuration parameters should be:
    91     *
    92     *  @p(code)
    93     *  var FatFS = xdc.useModule("ti.sysbios.fatfs.FatFS");
    94     *  FatFS.ramdiskSymbolName = "ramdiskData";
    95     *  FatFS.ramdiskSize = 32768 * 4;
    96     *  @p
    97     *
    98     *  When the ramdiskSymbolName parameter is left "empty", .ie., "",
    99     *  then the ramdiskSize
   100     *  parameter is used to create an empty FAT filesystem at boot time of size
   101     *  ramdiskSize.
   102     *
   103     *  User Defined Hook For get_fattime()
   104     *
   105     *  The proper implementation of the get_fattime() function requires hardware
   106     *  for a real time clock.  Since not all TI hardware platforms support a real
   107     *  time clock, the get_fattime() function will by default return a hard coded
   108     *  time value.  However, it is possible to override this by defining a hook
   109     *  function instead that can be written to take advantage of a real time clock
   110     *  that's present.  This function will then be called from get_fattime().
   111     *
   112     *  A hook function must be defined using the following format:
   113     *
   114     *  @p(code)
   115     *      Int32 <functionName>(Void)
   116     *  @p
   117     *
   118     *  Note if the user specifies a hook function in the RTSC configuration
   119     *  script, but does not define this function in their C code, a linker error
   120     *  will result.
   121    
   122     */
   123    
   124    @Template("./FatFS.xdt")
   125    metaonly module FatFS
   126    {
   127        /*! Function signature for user defined get_fattime() hook function */
   128        typedef Int32 (*fatTimeHookFxn)();
   129    
   130        /*!
   131         *  User defined hook function to return the time from a real time clock 
   132         *
   133         *  By default, a hard coded time is returned from get_fattime(). If the
   134         *  user's hardware supports a real time clock, then the code to read the
   135         *  time from that hardware component can be implemented in a user defined
   136         *  function hook function and set to this configuration parameter.  This
   137         *  hook function will then be called from the get_fattime() function.
   138         *
   139         *  As an example, to configure a hook function called "myTimeFxn", you
   140         *  would first need to implement "myTimeFxn" in C to get the time from
   141         *  the real time clock on your hardware.  Then, in your RTSC configuration
   142         *  script, set "getFatTimeHook" to point to "myTimeFxn":
   143         *
   144         *  @p(code)
   145         *  var FatFS = xdc.useModule('ti.sysbios.fatfs.FatFS");
   146         *  FatFS.getFatTimeHook = '&myTimeFxn';
   147         *  @p
   148         *
   149         *  Note if the user specifies a hook function in the RTSC configuration
   150         *  script, but does not define this function in their C code, a linker error
   151         *  will result.
   152         */
   153        config fatTimeHookFxn getFatTimeHook = null;
   154    
   155        /*!
   156         * File name prefix for this filesystem for use with TI C RTS
   157         *
   158         * This prefix should be supplied as part of the filename passed when
   159         * calling fopen().  For example: 
   160         *  @p(code)
   161         *  FILE * fp = fopen("fat:/signal.dat", "w");
   162         *  @p
   163         */
   164        config String fatfsPrefix = "fat";
   165        
   166        /*!
   167         * Symbol name or address of a pre-existing FAT File System.
   168         *
   169         * The ramdisk allows for the loading of an existing file system image
   170         * stored in an C array or at a particular address.  The value of this
   171         * parameter should be the name of this array or the address of where the
   172         * file system image is located. If left empty, an empty filesystem will be
   173         * created at boot time.
   174         */
   175        config String ramdiskSymbolName = "";
   176    
   177        /*! Size of the FAT filesystem in bytes. */
   178        config UInt ramdiskSize = 512 * 256;
   179    
   180        /*!
   181         * Disable the ramdisk or select the drive ID for a ramdisk (-1 to disable).
   182         *
   183         * Parameter used to specify whether to create a ramdisk or not, and if so,
   184         * specify the drive ID to use for the ramdisk.  Valid ID numbers are in the
   185         * set [0, 1, 2, 3].  If using a ramdisk in combination with other media,
   186         * the user is responsible for managing these drive IDs so that they do not
   187         * conflict with one another.
   188         *
   189         * By default, no ramdisk is created.
   190         *
   191         * -1 : do not create a ramdisk
   192         *  0 : create a ramdisk with drive ID 0
   193         *  1 : create a ramdisk with drive ID 1
   194         *  2 : create a ramdisk with drive ID 2
   195         *  3 : create a ramdisk with drive ID 3
   196         */
   197        config Int ramdiskDriveId = -1;
   198    }
   199    /*
   200     *  @(#) ti.sysbios.fatfs; 1, 0, 0,213; 2-24-2012 11:41:45; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   201    
   202     */
   203