fd7b794e81
This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
252 lines
11 KiB
C
252 lines
11 KiB
C
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
|
|
//
|
|
// 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.
|
|
|
|
#pragma once
|
|
#include <stddef.h>
|
|
#include "esp_err.h"
|
|
#include "driver/gpio.h"
|
|
#include "driver/sdmmc_types.h"
|
|
#include "driver/sdmmc_host.h"
|
|
#include "driver/sdspi_host.h"
|
|
#include "ff.h"
|
|
#include "wear_levelling.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Register FATFS with VFS component
|
|
*
|
|
* This function registers given FAT drive in VFS, at the specified base path.
|
|
* If only one drive is used, fat_drive argument can be an empty string.
|
|
* Refer to FATFS library documentation on how to specify FAT drive.
|
|
* This function also allocates FATFS structure which should be used for f_mount
|
|
* call.
|
|
*
|
|
* @note This function doesn't mount the drive into FATFS, it just connects
|
|
* POSIX and C standard library IO function with FATFS. You need to mount
|
|
* desired drive into FATFS separately.
|
|
*
|
|
* @param base_path path prefix where FATFS should be registered
|
|
* @param fat_drive FATFS drive specification; if only one drive is used, can be an empty string
|
|
* @param max_files maximum number of files which can be open at the same time
|
|
* @param[out] out_fs pointer to FATFS structure which can be used for FATFS f_mount call is returned via this argument.
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_register was already called
|
|
* - ESP_ERR_NO_MEM if not enough memory or too many VFSes already registered
|
|
*/
|
|
esp_err_t esp_vfs_fat_register(const char* base_path, const char* fat_drive,
|
|
size_t max_files, FATFS** out_fs);
|
|
|
|
/**
|
|
* @brief Un-register FATFS from VFS
|
|
*
|
|
* @note FATFS structure returned by esp_vfs_fat_register is destroyed after
|
|
* this call. Make sure to call f_mount function to unmount it before
|
|
* calling esp_vfs_fat_unregister.
|
|
* This function is left for compatibility and will be changed in
|
|
* future versions to accept base_path and replace the method below
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_INVALID_STATE if FATFS is not registered in VFS
|
|
*/
|
|
esp_err_t esp_vfs_fat_unregister() __attribute__((deprecated));
|
|
|
|
/**
|
|
* @brief Un-register FATFS from VFS
|
|
*
|
|
* @note FATFS structure returned by esp_vfs_fat_register is destroyed after
|
|
* this call. Make sure to call f_mount function to unmount it before
|
|
* calling esp_vfs_fat_unregister_ctx.
|
|
* Difference between this function and the one above is that this one
|
|
* will release the correct drive, while the one above will release
|
|
* the last registered one
|
|
*
|
|
* @param base_path path prefix where FATFS is registered. This is the same
|
|
* used when esp_vfs_fat_register was called
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_INVALID_STATE if FATFS is not registered in VFS
|
|
*/
|
|
esp_err_t esp_vfs_fat_unregister_path(const char* base_path);
|
|
|
|
|
|
/**
|
|
* @brief Configuration arguments for esp_vfs_fat_sdmmc_mount and esp_vfs_fat_spiflash_mount functions
|
|
*/
|
|
typedef struct {
|
|
/**
|
|
* If FAT partition can not be mounted, and this parameter is true,
|
|
* create partition table and format the filesystem.
|
|
*/
|
|
bool format_if_mount_failed;
|
|
int max_files; ///< Max number of open files
|
|
/**
|
|
* If format_if_mount_failed is set, and mount fails, format the card
|
|
* with given allocation unit size. Must be a power of 2, between sector
|
|
* size and 128 * sector size.
|
|
* For SD cards, sector size is always 512 bytes. For wear_levelling,
|
|
* sector size is determined by CONFIG_WL_SECTOR_SIZE option.
|
|
*
|
|
* Using larger allocation unit size will result in higher read/write
|
|
* performance and higher overhead when storing small files.
|
|
*
|
|
* Setting this field to 0 will result in allocation unit set to the
|
|
* sector size.
|
|
*/
|
|
size_t allocation_unit_size;
|
|
} esp_vfs_fat_mount_config_t;
|
|
|
|
// Compatibility definition
|
|
typedef esp_vfs_fat_mount_config_t esp_vfs_fat_sdmmc_mount_config_t;
|
|
|
|
/**
|
|
* @brief Convenience function to get FAT filesystem on SD card registered in VFS
|
|
*
|
|
* This is an all-in-one function which does the following:
|
|
* - initializes SDMMC driver or SPI driver with configuration in host_config
|
|
* - initializes SD card with configuration in slot_config
|
|
* - mounts FAT partition on SD card using FATFS library, with configuration in mount_config
|
|
* - registers FATFS library with VFS, with prefix given by base_prefix variable
|
|
*
|
|
* This function is intended to make example code more compact.
|
|
* For real world applications, developers should implement the logic of
|
|
* probing SD card, locating and mounting partition, and registering FATFS in VFS,
|
|
* with proper error checking and handling of exceptional conditions.
|
|
*
|
|
* @param base_path path where partition should be registered (e.g. "/sdcard")
|
|
* @param host_config Pointer to structure describing SDMMC host. When using
|
|
* SDMMC peripheral, this structure can be initialized using
|
|
* SDMMC_HOST_DEFAULT() macro. When using SPI peripheral,
|
|
* this structure can be initialized using SDSPI_HOST_DEFAULT()
|
|
* macro.
|
|
* @param slot_config Pointer to structure with slot configuration.
|
|
* For SDMMC peripheral, pass a pointer to sdmmc_slot_config_t
|
|
* structure initialized using SDMMC_SLOT_CONFIG_DEFAULT.
|
|
* For SPI peripheral, pass a pointer to sdspi_slot_config_t
|
|
* structure initialized using SDSPI_SLOT_CONFIG_DEFAULT.
|
|
* @param mount_config pointer to structure with extra parameters for mounting FATFS
|
|
* @param[out] out_card if not NULL, pointer to the card information structure will be returned via this argument
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
|
|
* - ESP_ERR_NO_MEM if memory can not be allocated
|
|
* - ESP_FAIL if partition can not be mounted
|
|
* - other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
|
|
*/
|
|
esp_err_t esp_vfs_fat_sdmmc_mount(const char* base_path,
|
|
const sdmmc_host_t* host_config,
|
|
const void* slot_config,
|
|
const esp_vfs_fat_mount_config_t* mount_config,
|
|
sdmmc_card_t** out_card);
|
|
|
|
/**
|
|
* @brief Unmount FAT filesystem and release resources acquired using esp_vfs_fat_sdmmc_mount
|
|
*
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount hasn't been called
|
|
*/
|
|
esp_err_t esp_vfs_fat_sdmmc_unmount();
|
|
|
|
/**
|
|
* @brief Convenience function to initialize FAT filesystem in SPI flash and register it in VFS
|
|
*
|
|
* This is an all-in-one function which does the following:
|
|
*
|
|
* - finds the partition with defined partition_label. Partition label should be
|
|
* configured in the partition table.
|
|
* - initializes flash wear levelling library on top of the given partition
|
|
* - mounts FAT partition using FATFS library on top of flash wear levelling
|
|
* library
|
|
* - registers FATFS library with VFS, with prefix given by base_prefix variable
|
|
*
|
|
* This function is intended to make example code more compact.
|
|
*
|
|
* @param base_path path where FATFS partition should be mounted (e.g. "/spiflash")
|
|
* @param partition_label label of the partition which should be used
|
|
* @param mount_config pointer to structure with extra parameters for mounting FATFS
|
|
* @param[out] wl_handle wear levelling driver handle
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_NOT_FOUND if the partition table does not contain FATFS partition with given label
|
|
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount was already called
|
|
* - ESP_ERR_NO_MEM if memory can not be allocated
|
|
* - ESP_FAIL if partition can not be mounted
|
|
* - other error codes from wear levelling library, SPI flash driver, or FATFS drivers
|
|
*/
|
|
esp_err_t esp_vfs_fat_spiflash_mount(const char* base_path,
|
|
const char* partition_label,
|
|
const esp_vfs_fat_mount_config_t* mount_config,
|
|
wl_handle_t* wl_handle);
|
|
|
|
/**
|
|
* @brief Unmount FAT filesystem and release resources acquired using esp_vfs_fat_spiflash_mount
|
|
*
|
|
* @param base_path path where partition should be registered (e.g. "/spiflash")
|
|
* @param wl_handle wear levelling driver handle returned by esp_vfs_fat_spiflash_mount
|
|
*
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount hasn't been called
|
|
*/
|
|
esp_err_t esp_vfs_fat_spiflash_unmount(const char* base_path, wl_handle_t wl_handle);
|
|
|
|
|
|
/**
|
|
* @brief Convenience function to initialize read-only FAT filesystem and register it in VFS
|
|
*
|
|
* This is an all-in-one function which does the following:
|
|
*
|
|
* - finds the partition with defined partition_label. Partition label should be
|
|
* configured in the partition table.
|
|
* - mounts FAT partition using FATFS library
|
|
* - registers FATFS library with VFS, with prefix given by base_prefix variable
|
|
*
|
|
* @note Wear levelling is not used when FAT is mounted in read-only mode using this function.
|
|
*
|
|
* @param base_path path where FATFS partition should be mounted (e.g. "/spiflash")
|
|
* @param partition_label label of the partition which should be used
|
|
* @param mount_config pointer to structure with extra parameters for mounting FATFS
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_NOT_FOUND if the partition table does not contain FATFS partition with given label
|
|
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_rawflash_mount was already called for the same partition
|
|
* - ESP_ERR_NO_MEM if memory can not be allocated
|
|
* - ESP_FAIL if partition can not be mounted
|
|
* - other error codes from SPI flash driver, or FATFS drivers
|
|
*/
|
|
esp_err_t esp_vfs_fat_rawflash_mount(const char* base_path,
|
|
const char* partition_label,
|
|
const esp_vfs_fat_mount_config_t* mount_config);
|
|
|
|
/**
|
|
* @brief Unmount FAT filesystem and release resources acquired using esp_vfs_fat_rawflash_mount
|
|
*
|
|
* @param base_path path where partition should be registered (e.g. "/spiflash")
|
|
* @param partition_label label of partition to be unmounted
|
|
*
|
|
* @return
|
|
* - ESP_OK on success
|
|
* - ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount hasn't been called
|
|
*/
|
|
esp_err_t esp_vfs_fat_rawflash_unmount(const char* base_path, const char* partition_label);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|