User Manual stm32
User Manual stm32
User Manual stm32
User manual
Developing Applications on STM32Cube with FatFs
Introduction
The STMCubeTM initiative was originated by STMicroelectronics to ease developers life by
reducing development efforts, time and cost. STM32Cube covers the STM32 portfolio.
STM32Cube Version 1.x includes:
• The STM32CubeMX, a graphical software configuration tool that allows to generate C
initialization code using graphical wizards.
• A comprehensive embedded software platform, delivered per series (namely,
STM32CubeF4 for STM32F4 series)
– The STM32Cube HAL, an STM32 abstraction layer embedded software, ensuring
maximized portability across STM32 portfolio
– A consistent set of middleware components such as RTOS, USB, TCP/IP,
Graphics
– All embedded software utilities coming with a full set of examples.
A File System is the way in which files ares named and where they are placed logically for
storage and retrieval. Its primary objective is to manage access to the data of files, and to
manage the available space of the device(s) which contain it. Using a file system allows
user to ensure reliability and to organize data in an efficient manner.
This user manual is intended for developers who use STM32Cube firmware on STM32
microcontrollers. It provides a full description of how to use the STM32Cube firmware
components with a generic FAT File System (FatFs); this user manual comes also with
description of a set of examples based on common FatFs provided APIs.
Please refer to the release notes of the STM32Cube firmware package to know the version
of FatFs firmware component used.
This document is applicable to all STM32 devices; however for simplicity reason, the
STM32F4xx devices and STM32CubeF4 are used as reference platform. To know more
about supported physical media disk and the examples implementation on your STM32
device, please refer to the readme file provided within the associated STM32Cube FW
package.
Contents
3 FatFs applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.1 HAL drivers configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2 FatFs File System configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.1 Reentrancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.2 Long file name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.3 FatFs sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4 Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
List of tables
List of figures
ŽŽƚZĞŐŝŽŶ
Ϭdžϭ
WĂƌƚŝƚŝŽŶϬ
WĂƌƚŝƚŝŽŶdĂďůĞ
Ϭdžϭ
WĂƌƚŝƚŝŽŶϭ
Ϭdžϭ
WĂƌƚŝƚŝŽŶϮ
Ϭdžϭ
WĂƌƚŝƚŝŽŶϯ
Ϭdžϭ&
^ŝŐŶĂƚƵƌĞ
Some devices are formatted without an MBR and, therefore, have no partition table. This
configuration is not currently supported in the Dynamic C FAT file system.
WĂƌƚŝƚŝŽŶϬ WĂƌƚŝƚŝŽŶϭ
W W
DZ &d ĂƚĂƌĞĂ &d ĂƚĂƌĞĂ
ZKKd ZKKd
Root directory
The root directory has a predefined location and size. It has 512 entries of 32 bytes each.
An entry in the root directory is either empty or contains a file or subdirectory name (in 8.3
format), file size, date and time of last revision and the starting cluster number for the file or
subdirectory.
Data area
The data area takes up most of the partition. It contains file data and subdirectories. Note
that the data area of a partition must, by convention, start at cluster 2.
For more details, refer to the Microsoft® EFI FAT32 File System Specification.
The download license agreement allows using the Microsoft EFI FAT32 File System
Specification only in connection with a firmware implementation of the Extensible Firmware
Initiative Specification, v. 1.0. If you plan to implement the FAT32 File System specification
for other purposes, you must obtain an additional license from Microsoft.
For example, you must obtain an additional license in order to create a file system for
reading, or reading and writing FAT32 in digital cameras recording to Flash media, in
computer operating systems reading and writing internal/external hard disks or Flash media,
or in set-top boxes reading FAT-formatted media.
For more details about FAT and applicable licenses and/or copyrights, refer to Microsoft web
site.
ƉƉůŝĐĂƚŝŽŶ
>Žǁ>ĞǀĞůŝƐŬ/ͬK
Zd
;Ƶ^͕ZD͕h^͙Ϳ ͺ&^ͺZEdZEdсϭ
Therefore FatFs license is one of the BSD-style licenses, but there is a big difference.
Because FatFs is for embedded projects, the conditions for redistributions in binary form,
such as embedded code, hex file and binary library, are not specified to increase its
usability. The documentation of the distributions need not include about FatFs and its
license document, and it may also. Of course FatFs is compatible with the projects under
GNU GPL. When redistribute it with any modification, the license can also be changed to
GNU GPL or BSD-style license.
2.4.2 Reentrancy
The file operations to the different volumes are always reentrant and can work
simultaneously. The file operations to the same volume are not reentrant but it can also be
configured to thread-safe with _FS_REENTRANT option. In this case, also the OS
dependent synchronization object control functions, ff_cre_syncobj(), ff_del_syncobj(),
ff_req_grant() and ff_rel_grant() must be added to the project.
When a file function is called while the volume is in use by any other task, the file function is
suspended until that task leaves file function. If the wait time exceeded a period defined by
_TIMEOUT, the file function will abort with FR_TIMEOUT. The timeout feature might not be
supported on some RTOS.
There is an exception on f_mount() and f_mkfs() functions. These functions are not
reentrant to the same volume. When using these functions, all other tasks must close the
corresponding file on the volume and avoid accessing the volume.
Note that this section describes the reentrancy of the FatFs module itself, but also the low
level disk I/O layer must be reentrant.
&Ăƚ&ƐDŽĚƵůĞ
'ĞŶĞƌŝĐ>Žǁ>ĞǀĞůƌŝǀĞƌ/ŶƚĞƌĨĂĐĞ
>ŝŶŬŵĞĐŚĂŶŝƐŵ
>Žǁ>ĞǀĞůŝƐŬ/ͬK ^WƌŝǀĞƌƐ
ƌŝǀĞƌƐ
,>ƌŝǀĞƌƐ
The generic low level driver ff_gen_drv.c/h is located in the root directory of the FatFs
modules. Two disk I/O driver type definition structures are used to help dynamic
management of attached disk drives under the ff_gen_drv.h file, as mentioned below:
To link FatFs module with a low level disk I/O driver, user can use the following APIs:
• FATFS_LinkDriver(): to add dynamically a disk I/O driver,
• FATFS_UnLinkDriver(): to remove dynamically a disk I/O driver,
• FATFS_GetAttachedDriversNbr(): to know the number of current attached disk I/O
drivers
2.7.1 FATFS_LinkDriver()
This function links a compatible disk I/O driver and increments the number of active linked
drivers. It returns 0 in case of success, otherwise it returns 1.
Note: Due to FatFs limits the MAX number of attached disks (_VOLUMES) is up to 10
Implementation of FATFS_LinkDriver:
uint8_t FATFS_LinkDriver(Diskio_drvTypeDef *drv, char *path)
{
uint8_t ret = 1;
uint8_t DiskNum = 0;
if(disk.nbr <= _VOLUMES)
{
disk.drv[disk.nbr] = drv;
DiskNum = disk.nbr++;
path[0] = DiskNum + '0';
path[1] = ':';
path[2] = '/';
path[3] = 0;
ret = 0;
}
return ret;
}
2.7.2 FATFS_UnlinkDriver()
This function unlinks a disk I/O driver and decrements the number of active linked drivers. It
returns 0 in case of success, otherwise it returns 1.
Implementation of FATFS_UnLinkDriver:
uint8_t FATFS_UnLinkDriver(char *path)
{
uint8_t DiskNum = 0;
uint8_t ret = 1;
if(disk.nbr >= 1)
{
DiskNum = path[0] - '0';
if(DiskNum <= disk.nbr)
{
disk.drv[disk.nbr--] = 0;
ret = 0;
}
}
return ret;
}
2.7.3 FATFS_GetAttachedDriverNbr()
This function returns the number of linked drivers to the FatFs module.
Implementation of FATFS_GetAttachedDriversNbr:
uint8_t FATFS_GetAttachedDriversNbr(void)
{
return disk.nbr;
}
/* Includes ---------------------------------------------------------------*/
#include <string.h>
#include "ff_gen_drv.h"
/* Private define ---------------------------------------------------------*/
#define BLOCK_SIZE 512 /* Block Size in Bytes */
Diskio_drvTypeDef mynewdisk_Driver =
{
mynewdisk_initialize,
mynewdisk_status,
mynewdisk_read,
#if _USE_WRITE == 1
mynewdisk_write,
#endif /* _USE_WRITE == 1 */
return Stat;
}
// write your own code here to read sectors from the drive
return res;
}
return res;
}
#endif /* _USE_WRITE == 1 */
// write your own code here to control the drive specified features
// CTRL_SYNC, GET_SECTOR_SIZE, GET_SECTOR_COUNT, GET_BLOCK_SIZE
return res;
}
#endif /* _USE_IOCTL == 1 */
#endif /* __MYNEWDISK_DISKIO_H */
3 FatFs applications
The FatFs applications listed above provided within STM32CubeF4 solution are a set of
firmware available in two modes:
• Standalone mode
• RTOS mode, using FreeRTOS middleware component.
It is worth noting that user must guarantee appropriate values of stack and heap, when
using or developing FatFs applications based on ST provided disk I/O low level drivers.
Thus, stack value must be incremented by the handled maximum sector size _MAX_SS
value, available within ff_conf.h file, when using USB Disk application based on USB Host
Mass Storage Class (MSC) for scratch alignment reasons.
Heap value must be also adjusted when developing any FatFs application in RTOS mode,
using FreeRTOS middleware component based on CMSIS-OS wrapping layer common
APIs.
The main difference in HAL configuration files, between the supported disk drivers is the
definition of the right HAL driver corresponding to the used disk drive. The following defines
must be available depending on each drive:
• FatFs_uSD:
– #define HAL_SD_MODULE_ENABLED
• FatFs_RAMDisk:
– #define HAL_SDRAM_MODULE_ENABLED or
– #define HAL_SRAM_MODULE_ENABLED
• FatFs_USBDisk:
– #define HAL_HCD_MODULE_ENABLED
3.2.1 Reentrancy
Reentrancy is the key difference between the Standalone and the RTOS modes’
configurations, which can be set on FatFs configuration file ffconf.h:
• Reentrancy is disabled in Standalone mode:
– #define _FS_REENTRANT 0
• Reentrancy is enabled in RTOS mode:
– #define _FS_REENTRANT 1
Once enabled, user must provide the OS dependent type of synchronization object (#define
_SYNC_t osSemaphoreId)
RTOS mode applications’ projects need to include the syscall.c file providing the OS
depending functions, and found under: \Middlewares\Third_Party\FatFs\src\option
User can enable LFN feature either on standalone mode applications or in RTOS mode
ones.
/*-------------------------------------------------------------------------*/
/* main.c: Main program body */
/*-------------------------------------------------------------------------*/
/* Includes ---------------------------------------------------------------*/
#include "main.h"
int main(void)
{
uint32_t wbytes; /* File write counts */
uint8_t wtext[] = "text to write logical disk"; /* File write buffer */
if(FATFS_LinkDriver(&mynewdisk_Driver, mynewdiskPath) == 0)
{
if(f_mount(&mynewdiskFatFs, (TCHAR const*)mynewdiskPath, 0) == FR_OK)
{
if(f_open(&MyFile, "STM32.TXT", FA_CREATE_ALWAYS | FA_WRITE) == FR_OK)
{
if(f_write(&MyFile, wtext, sizeof(wtext), (void *)&wbytes) == FR_OK);
{
f_close(&MyFile);
}
}
}
}
FATFS_UnLinkDriver(mynewdiskPath);
}
User must include the generic drive, ff_gen_drv.h, header file and also the disk IO module
header file, mynewdisk_diskio.h
/*-------------------------------------------------------------------------*/
/* main.h: Header for main.c module */
/*-------------------------------------------------------------------------*/
/* Includes ---------------------------------------------------------------*/
#include "ff_gen_drv.h"
#include "mynewdisk_diskio.h"
4 Conclusions
This User Manual explains how to integrate the FatFs middleware components within the
STM32Cube HAL drivers.
A set of examples have been described to help users who develop applications based on
FatFs File System within STM32Cube solution.
5 FAQ
6 Revision history
Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve the
right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any
time, without notice.
All ST products are sold pursuant to ST’s terms and conditions of sale.
Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no
liability whatsoever relating to the choice, selection or use of the ST products and services described herein.
No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this
document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products
or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such
third party products or services or any intellectual property contained therein.
UNLESS OTHERWISE SET FORTH IN ST’S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS
OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
ST PRODUCTS ARE NOT DESIGNED OR AUTHORIZED FOR USE IN: (A) SAFETY CRITICAL APPLICATIONS SUCH AS LIFE
SUPPORTING, ACTIVE IMPLANTED DEVICES OR SYSTEMS WITH PRODUCT FUNCTIONAL SAFETY REQUIREMENTS; (B)
AERONAUTIC APPLICATIONS; (C) AUTOMOTIVE APPLICATIONS OR ENVIRONMENTS, AND/OR (D) AEROSPACE APPLICATIONS
OR ENVIRONMENTS. WHERE ST PRODUCTS ARE NOT DESIGNED FOR SUCH USE, THE PURCHASER SHALL USE PRODUCTS AT
PURCHASER’S SOLE RISK, EVEN IF ST HAS BEEN INFORMED IN WRITING OF SUCH USAGE, UNLESS A PRODUCT IS
EXPRESSLY DESIGNATED BY ST AS BEING INTENDED FOR “AUTOMOTIVE, AUTOMOTIVE SAFETY OR MEDICAL” INDUSTRY
DOMAINS ACCORDING TO ST PRODUCT DESIGN SPECIFICATIONS. PRODUCTS FORMALLY ESCC, QML OR JAN QUALIFIED ARE
DEEMED SUITABLE FOR USE IN AEROSPACE BY THE CORRESPONDING GOVERNMENTAL AGENCY.
Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void
any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any
liability of ST.
ST and the ST logo are trademarks or registered trademarks of ST in various countries.
Information in this document supersedes and replaces all information previously supplied.
The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.