Release merge for v1.03 for MLA v2016-04-27:

* Added required user defined callback for internal flash physical layer:
DRV_FILEIO_INTERNAL_FLASH_CONFIG_UNLOCK_VERIFICATION_FUNCTION. This function should validate that
the system parameters are valid for flash writes on the device on the board (Vdd, clock speeds, etc. are all in valid range
for self writes).
* migrated from system_config.h to direct include of fileio_config.h

Author: davidflowers

doc/help_mla_fileio.jar

@@ -676,74 +676,34 @@ void EraseBlock(const uint8_t* dest)
 }
 
 
-//------------------------------------------------------------------------------
-#if defined(__XC16__)
-    #pragma message "Double click this message and read inline code comments.  For production designs, recommend adding application specific robustness features here."
-#else
-    #warning "Double click this message and read inline code comments.  For production designs, recommend adding application specific robustness features here."
+
+#ifndef DRV_FILEIO_INTERNAL_FLASH_CONFIG_UNLOCK_VERIFICATION_FUNCTION
+    #error "User must define the DRV_FILEIO_INTERNAL_FLASH_CONFIG_UNLOCK_VERIFICATION_FUNCTION macro in the fileio_config.h file.  Click this message for more details in comments."
+    /* The DRV_FILEIO_INTERNAL_FLASH_CONFIG_UNLOCK_VERIFICATION_FUNCTION macro
+     * is used to verify that the system is in a condition where a self write 
+     * is valid.  This could include checks for system voltage levels, clocking
+     * vs voltage, address checking for write locations, etc.  The prototype of
+     * the function that this micro should point to is the following:
+     *   bool functionName(void);
+     * The functions should return true if the self write is allowed and false
+     * if the self write is not allowed. 
+     */
 #endif
-//Function: void UnlockAndActivate(uint8_t UnlockKey)
-//Description: Activates and initiates a flash memory self erase or program 
-//operation.  Useful for writing to the MSD drive volume.
-//Note: Self erase/writes to flash memory could potentially corrupt the
-//firmware of the application, if the unlock sequence is ever executed
-//unintentionally, or if the table pointer is pointing to an invalid
-//range (not inside the MSD volume range).  Therefore, in order to ensure
-//a fully reliable design that is suitable for mass production, it is strongly
-//recommended to implement several robustness checks prior to actually
-//performing any self erase/program unlock sequence.  See additional inline 
-//code comments.
+
+bool DRV_FILEIO_INTERNAL_FLASH_CONFIG_UNLOCK_VERIFICATION_FUNCTION(void);
+    
+
 //------------------------------------------------------------------------------
 void UnlockAndActivate(uint8_t UnlockKey)
 {
     #if defined(__XC8) || defined(__18CXX)
         uint8_t InterruptEnableSave;
     #endif
 
-    //Should verify that the voltage on Vdd/Vddcore is high enough to meet
-    //the datasheet minimum voltage vs. frequency graph for the device.
-    //If the microcontroller is "overclocked" (ex: by running at maximum rated
-    //frequency, but then not suppling enough voltage to meet the datasheet
-    //voltage vs. frequency graph), errant code execution could occur.  It is
-    //therefore strongly recommended to check the voltage prior to performing a 
-    //flash self erase/write unlock sequence.  If the voltage is too low to meet
-    //the voltage vs. frequency graph in the datasheet, the firmware should not 
-    //inititate a self erase/program operation, and instead it should either:
-    //1.  Clock switch to a lower frequency that does meet the voltage/frequency graph.  Or,
-    //2.  Put the microcontroller to Sleep mode.
-    
-    //The method used to measure Vdd and/or Vddcore will depend upon the 
-    //microcontroller model and the module features available in the device, but
-    //several options are available on many of the microcontrollers, ex:
-    //1.  HLVD module
-    //2.  WDTCON<LVDSTAT> indicator bit
-    //3.  Perform ADC operation, with the VBG channel selected, using Vdd/Vss as 
-    //      references to the ADC.  Then perform math operations to calculate the Vdd.
-    //      On some micros, the ADC can also measure the Vddcore voltage, allowing
-    //      the firmware to calculate the absolute Vddcore voltage, if it has already
-    //      calculated and knows the ADC reference voltage.
-    //4.  Use integrated general purpose comparator(s) to sense Vdd/Vddcore voltage
-    //      is above proper threshold.
-    //5.  If the micrcontroller implements a user adjustable BOR circuit, enable
-    //      it and set the trip point high enough to avoid overclocking altogether.
-    
-    //Example psuedo code.  Exact implementation will be application specific.
-    //Please implement appropriate code that best meets your application requirements.
-    //if(GetVddcoreVoltage() < MIN_ALLOWED_VOLTAGE)
-    //{
-    //    ClockSwitchToSafeFrequencyForGivenVoltage();    //Or even better, go to sleep mode.
-    //    return;       
-    //}    
-
-
-    //Should also verify the TBLPTR is pointing to a valid range (part of the MSD
-    //volume, and not a part of the application firmware space).
-    //Example code for PIC18 (commented out since the actual address range is 
-    //application specific):
-    //if((TBLPTR > MSD_VOLUME_MAX_ADDRESS) || (TBLPTR < MSD_VOLUME_START_ADDRESS)) 
-    //{
-    //    return;
-    //}  
+    if(DRV_FILEIO_INTERNAL_FLASH_CONFIG_UNLOCK_VERIFICATION_FUNCTION() == false)
+    {
+        return;
+    }
 
     //Verify the UnlockKey is the correct value, to make sure this function is 
     //getting executed intentionally, from a calling function that knew it

doc/help_mla_fileio.pdf

@@ -21,6 +21,7 @@ please contact [email protected]
 
 #include "fileio_config.h"
 #include <fileio.h>
+#include <fileio_media.h>
 
 uint8_t FILEIO_InternalFlash_MediaDetect(void* config);
 FILEIO_MEDIA_INFORMATION * FILEIO_InternalFlash_MediaInitialize(void* config);

drivers/internal_flash/internal_flash.c

@@ -0,0 +1,27 @@
+// DOM-IGNORE-BEGIN
+/*******************************************************************************
+Copyright 2016 Microchip Technology Inc. (www.microchip.com)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+To request to license the code under the MLA license (www.microchip.com/mla_license), 
+please contact [email protected]
+*******************************************************************************/
+//DOM-IGNORE-END
+
+// Macro maps to a user function that will determine if the system parameters are valid for a self write
+//  for the processor on the board.  Returns true if the write can continue and false if it should not.
+#define DRV_FILEIO_INTERNAL_FLASH_CONFIG_UNLOCK_VERIFICATION_FUNCTION() true
+
+
+

drivers/internal_flash/internal_flash.h

@@ -27,6 +27,7 @@ please contact [email protected]
 #include <stdint.h>
 #include <stdbool.h>
 
+#include <fileio_media.h>
 
 /*****************************************************************************/
 /*                        Custom structures and definitions                  */

drivers/internal_flash/internal_flash_config_template.h

@@ -26,9 +26,11 @@ please contact [email protected]
 #include <stdint.h>
 #include <stdbool.h>
 #include <stddef.h>
-#include "system_config.h"
+#include "fileio_config.h"
 #include "system.h"
 
+#include <fileio_media.h>
+
 
 /*******************************************************************/
 /*                     Structures and defines                     */
@@ -176,33 +178,6 @@ typedef enum
     FILEIO_GET_PROPERTIES_STILL_WORKING = 0xFF
 } FILEIO_DRIVE_ERRORS;
 
-// Enumeration to define media error types
-typedef enum
-{
-    MEDIA_NO_ERROR,                     // No errors
-    MEDIA_DEVICE_NOT_PRESENT,           // The requested device is not present
-    MEDIA_CANNOT_INITIALIZE             // Cannot initialize media
-} FILEIO_MEDIA_ERRORS;
-
-// Media information flags.  The driver's MediaInitialize function will return a pointer to one of these structures.
-typedef struct
-{
-    FILEIO_MEDIA_ERRORS errorCode;              // The status of the intialization FILEIO_MEDIA_ERRORS
-    // Flags
-    union
-    {
-        uint8_t    value;
-        struct
-        {
-            uint8_t    sectorSize  : 1;         // The sector size parameter is valid.
-            uint8_t    maxLUN      : 1;         // The max LUN parameter is valid.
-        }   bits;
-    } validityFlags;
-
-    uint16_t    sectorSize;                     // The sector size of the target device.
-    uint8_t    maxLUN;                          // The maximum Logical Unit Number of the device.
-} FILEIO_MEDIA_INFORMATION;
-
 /***************************************************************************
     Function:
         void (*FILEIO_DRIVER_IOInitialize)(void * mediaConfig);

drivers/sd_spi/sd_spi.h

@@ -29,6 +29,8 @@ please contact [email protected]
 #include "system_config.h"
 #include "system.h"
 
+#include <fileio_media.h>
+
 
 /*******************************************************************/
 /*                     Structures and defines                     */
@@ -178,32 +180,6 @@ typedef enum
     FILEIO_GET_PROPERTIES_STILL_WORKING = 0xFF
 } FILEIO_DRIVE_ERRORS;
 
-// Enumeration to define media error types
-typedef enum
-{
-    MEDIA_NO_ERROR,                     // No errors
-    MEDIA_DEVICE_NOT_PRESENT,           // The requested device is not present
-    MEDIA_CANNOT_INITIALIZE             // Cannot initialize media
-} FILEIO_MEDIA_ERRORS;
-
-// Media information flags.  The driver's MediaInitialize function will return a pointer to one of these structures.
-typedef struct
-{
-    FILEIO_MEDIA_ERRORS errorCode;              // The status of the intialization FILEIO_MEDIA_ERRORS
-    // Flags
-    union
-    {
-        uint8_t    value;
-        struct
-        {
-            uint8_t    sectorSize  : 1;         // The sector size parameter is valid.
-            uint8_t    maxLUN      : 1;         // The max LUN parameter is valid.
-        }   bits;
-    } validityFlags;
-
-    uint16_t    sectorSize;                     // The sector size of the target device.
-    uint8_t    maxLUN;                          // The maximum Logical Unit Number of the device.
-} FILEIO_MEDIA_INFORMATION;
 
 /***************************************************************************
     Function:

inc/fileio.h

@@ -0,0 +1,52 @@
+// DOM-IGNORE-BEGIN
+/*******************************************************************************
+Copyright 2015 Microchip Technology Inc. (www.microchip.com)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+To request to license the code under the MLA license (www.microchip.com/mla_license), 
+please contact [email protected]
+*******************************************************************************/
+//DOM-IGNORE-END
+
+#ifndef  _FILEIO_MEDIA_H
+#define  _FILEIO_MEDIA_H
+
+// Enumeration to define media error types
+typedef enum
+{
+    MEDIA_NO_ERROR,                     // No errors
+    MEDIA_DEVICE_NOT_PRESENT,           // The requested device is not present
+    MEDIA_CANNOT_INITIALIZE             // Cannot initialize media
+} FILEIO_MEDIA_ERRORS;
+
+// Media information flags.  The driver's MediaInitialize function will return a pointer to one of these structures.
+typedef struct
+{
+    FILEIO_MEDIA_ERRORS errorCode;              // The status of the initialization FILEIO_MEDIA_ERRORS
+    // Flags
+    union
+    {
+        uint8_t    value;
+        struct
+        {
+            uint8_t    sectorSize  : 1;         // The sector size parameter is valid.
+            uint8_t    maxLUN      : 1;         // The max LUN parameter is valid.
+        }   bits;
+    } validityFlags;
+
+    uint16_t    sectorSize;                     // The sector size of the target device.
+    uint8_t    maxLUN;                          // The maximum Logical Unit Number of the device.
+} FILEIO_MEDIA_INFORMATION;
+
+#endif

inc/fileio_lfn.h

@@ -19,7 +19,7 @@ please contact [email protected]
 *******************************************************************************/
 //DOM-IGNORE-END
 
-#include <system_config.h>
+#include <fileio_config.h>
 #include <system.h>
 #include <fileio.h>
 #include "fileio_private.h"
@@ -798,7 +798,6 @@ void FILEIO_FormatShortFileName (const char * fileName, FILEIO_OBJECT * filePtr)
     }
 }
 
-
 int FILEIO_Open (FILEIO_OBJECT * filePtr, const char * fileName, uint16_t mode)
 {
     FILEIO_ERROR_TYPE error;
@@ -811,11 +810,11 @@ int FILEIO_Open (FILEIO_OBJECT * filePtr, const char * fileName, uint16_t mode)
     uint16_t currentClusterOffset = 0;
 
     fileName = FILEIO_CacheDirectory (&directory, fileName, false);
-
+   
     if (fileName == NULL)
     {
         return FILEIO_RESULT_FAILURE;
-    }
+    }  
 
     currentCluster = directory.cluster;
 
@@ -939,7 +938,7 @@ int FILEIO_Open (FILEIO_OBJECT * filePtr, const char * fileName, uint16_t mode)
         }
     }
 
-    // Check to ensure no errors occured
+    // Check to ensure no errors occurred
     if (error != FILEIO_ERROR_NONE)
     {
         directory.drive->error = error;
@@ -1061,7 +1060,7 @@ const char * FILEIO_CacheDirectory (FILEIO_DIRECTORY * dir, const char * path, b
 #endif
 
     // Find the next forward slash (indicates part of the path is a directory)
-    while ((i = FILEIO_FindNextDelimiter(path)) != -1)
+    while ((i = FILEIO_FindNextDelimiter(path)) != ((uint16_t)-1))
     {
         // If someone terminated a directory path with a delimiter, break out of the loop
         if (*(path + i) == FILEIO_CONFIG_DELIMITER)
@@ -1126,7 +1125,7 @@ uint16_t FILEIO_FindNextDelimiter(const char * path)
 
     if (c == 0)
     {
-        return -1;
+        return ((uint16_t)-1);
     }
     else
     {