1 /* ---------------------------------------------------------------------------- 2 * Copyright (c) Huawei Technologies Co., Ltd. 2021-2021. All rights reserved. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 15 * Description: LiteOS FS Headfile 16 * Author: Huawei LiteOS Team 17 * Create: 2021-07-16 18 * Redistribution and use in source and binary forms, with or without modification, 19 * are permitted provided that the following conditions are met: 20 * 1. Redistributions of source code must retain the above copyright notice, this list of 21 * conditions and the following disclaimer. 22 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 23 * of conditions and the following disclaimer in the documentation and/or other materials 24 * provided with the distribution. 25 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 26 * to endorse or promote products derived from this software without specific prior written 27 * permission. 28 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 29 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 30 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 31 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 32 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 33 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 34 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 35 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 36 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 37 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 38 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 39 * --------------------------------------------------------------------------- */ 40 41 #ifndef _INCLUDE_LOS_FS_H 42 #define _INCLUDE_LOS_FS_H 43 44 #include "errno.h" 45 #include "compiler.h" 46 #include "sys/statfs.h" 47 #include "sys/types.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif /* __cplusplus */ 52 53 #ifdef LOSCFG_FS_FAT_VIRTUAL_PARTITION 54 #define _MAX_ENTRYLENGTH 16 /* MAX virtual partition name length */ 55 #define _MAX_VIRVOLUMES 5 /* MAX virtual partition number */ 56 typedef struct virtual_partition_info 57 { 58 char *devpartpath; /* partition name need set virtual partition,e.g. /dev/mmcblk0p0 */ 59 int virpartnum; /* virtual partition numbers, MAX number is 5 */ 60 double virpartpercent[_MAX_VIRVOLUMES]; /* every virtual partition percent,e.g 0.6,0.3,0.1 */ 61 char virpartname[_MAX_VIRVOLUMES][_MAX_ENTRYLENGTH + 1]; /* every virtual partition name, MAX length is 16 */ 62 } virpartinfo; 63 #endif 64 65 struct fsmap_t 66 { 67 const char *fs_filesystemtype; 68 const struct mountpt_operations *fs_mops; 69 const BOOL is_mtd_support; 70 const BOOL is_bdfs; 71 }; 72 73 #define FSMAP_WOW_ENTRY(_l, _name, _mop, _is_mtd_support, _is_bdfs) \ 74 struct fsmap_t _l LOS_HAL_TABLE_WOW_ENTRY(fsmap) = \ 75 { \ 76 _name, \ 77 &_mop, \ 78 _is_mtd_support, \ 79 _is_bdfs \ 80 } 81 82 #define FSMAP_SCATTER_ENTRY(_l, _name, _mop, _is_mtd_support, _is_bdfs) \ 83 struct fsmap_t _l LOS_HAL_TABLE_SCATTER_ENTRY(fsmap) = \ 84 { \ 85 _name, \ 86 &_mop, \ 87 _is_mtd_support, \ 88 _is_bdfs \ 89 } 90 91 #define FSMAP_ENTRY(_l, _name, _mop, _is_mtd_support, _is_bdfs) \ 92 struct fsmap_t _l LOS_HAL_TABLE_ENTRY(fsmap) = \ 93 { \ 94 _name, \ 95 &_mop, \ 96 _is_mtd_support, \ 97 _is_bdfs \ 98 } 99 100 typedef enum mount_status 101 { 102 STAT_UNMOUNTED = 0, 103 STAT_MOUNTED, 104 } MOUNT_STATE; 105 106 /** 107 * @ingroup fs 108 * @brief Initializes the vfs filesystem 109 * 110 * @par Description: 111 * This API is used to initializes the vfs filesystem 112 * 113 * @attention 114 * <ul> 115 * <li>Called only once, multiple calls will cause file system error.</li> 116 * </ul> 117 * 118 * @param none 119 * 120 * @retval none 121 * @par Dependency: 122 * <ul><li>fs.h: the header file that contains the API declaration.</li></ul> 123 * @see NULL 124 * @since Huawei LiteOS V100R001C00 125 */ 126 127 void los_vfs_init(void); 128 129 /** 130 * @ingroup fs 131 * @brief list directory contents. 132 * 133 * @par Description: 134 * List information about the FILEs (the current directory by default). 135 * 136 * @attention 137 * <ul> 138 * <li>The total length of parameter pathname must be less than the value defined by PATH_MAX.</li> 139 * </ul> 140 * 141 * @param pathname [IN] Type #const char* The file pathname. 142 * 143 * @retval 144 * <ul>None.</ul> 145 * 146 * @par Dependency: 147 * <ul><li>fs.h: the header file that contains the API declaration.</li></ul> 148 * @see ls 149 * @since Huawei LiteOS V100R001C00 150 */ 151 152 extern void ls(const char *pathname); 153 154 /** 155 * @ingroup fs 156 * @brief locate character in string. 157 * 158 * @par Description: 159 * The API function returns a pointer to the last occurrence of the character c in the string s. 160 * 161 * @attention 162 * <ul> 163 * <li>The parameter s must point a valid string, which end with the terminating null byte.</li> 164 * </ul> 165 * 166 * @param s [IN] Type #const char* A pointer to string. 167 * @param c [IN] Type #int The character. 168 * 169 * @retval #char* a pointer to the matched character or NULL if the character is not found. 170 * 171 * @par Dependency: 172 * <ul><li>fs.h: the header file that contains the API declaration.</li></ul> 173 * @see rindex 174 * @since Huawei LiteOS V100R001C00 175 */ 176 177 extern char *rindex(const char *s, int c); 178 179 /** 180 * @ingroup fs 181 * @brief list directory contents. 182 * 183 * @par Description: 184 * Get the volume label of the FAT partition. 185 * 186 * @attention 187 * <ul> 188 * <li>The function support FAT filesystem only.</li> 189 * <li>The label must allocated more than 11 charactors space first</li> 190 * </ul> 191 * 192 * @param target [IN] Type #const char* The file pathname. 193 * @param label [OUT] Type #const char* The string pointer transform the label massge back. 194 * 195 * @retval #int Point the status which is successed or failed. 196 * 197 * @par Dependency: 198 * <ul><li>fs.h: the header file that contains the API declaration.</li></ul> 199 */ 200 201 int getlabel(const char *target, char *label); 202 203 /** 204 * @ingroup fs 205 * 206 * @par Description: 207 * The set_label() function shall set the value of a global variable, 208 * the value will be used to set the label of SD card in format(). 209 * 210 * @param name [IN] label to set, the length must be less than 12 211 * 212 * @attention 213 * <ul> 214 * <li>The function must be called before format().</li> 215 * </ul> 216 * 217 * @retval #void None. 218 * 219 * @par Dependency: 220 * <ul><li>fs.h</li></ul> 221 * @see format 222 * @since Huawei LiteOS V100R001C00 223 */ 224 225 extern void set_label(const char *name); 226 227 /** 228 * @ingroup fs 229 * @brief formatting sd card 230 * 231 * @par Description: 232 * formatting sd card. 233 * 234 * @attention 235 * <ul> 236 * <li>The prefix of the parameter dev must be "/dev", and the length must be less than the value defined by PATH_MAX. 237 * There are four kind of format option: FMT_FAT16, FMT_FAT32, FMT_ANY, FMT_ERASE. If users input anything else, 238 * the default format option is FMT_ANY. Format option is decided by the number of clusters. Choosing the wrong 239 * option will cause error of format. The detailed information of (FAT16,FAT32) is ff.h. 240 * </li> 241 * </ul> 242 * 243 * @param dev [IN] Type #const char* path of the block device to format, which must be a really existing block device node. 244 * @param sectors [IN] Type #int number of sectors per cluster. 245 * @param option [IN] Type #int option of format. 246 * 247 * @retval #0 Format success. 248 * @retval #-1 Format failed. 249 * 250 * @par Dependency: 251 * <ul><li>unistd.h: the header file that contains the API declaration.</li></ul> 252 * @see 253 * 254 * @since Huawei LiteOS V100R001C00 255 */ 256 257 extern int format(const char *dev, int sectors, int option); 258 259 /** 260 * @ingroup fs 261 * @brief set current system time is valid or invalid for FAT file system. 262 * 263 * @par Description: 264 * The function is used for setting current system time is valid or invalid for FAT file system. 265 * The value can be set as FAT_SYSTEM_TIME_ENABLE/FAT_SYSTEM_TIME_DISABLE. 266 * 267 * @attention 268 * <ul> 269 * <li>When the system time is valid, it should set FAT_SYSTEM_TIME_ENABLE.</li> 270 * <li>When the system time is invalid, it should set FAT_SYSTEM_TIME_DISABLE.</li> 271 * </ul> 272 * 273 * @param b_status [IN] Type #BOOL system time status. 274 * 275 * @retval #0 set status success 276 * @retval #-22 Invalid argument 277 * 278 * @par Dependency: 279 * <ul><li>fs.h: the header file that contains the API declaration.</li></ul> 280 * @see 281 * 282 * @since Huawei LiteOS V200R001C00 283 */ 284 285 extern int los_set_systime_status(BOOL b_status); 286 287 /** 288 * @ingroup fs 289 * @check the three latest files in path 290 * 291 * @par Description: 292 * The fscheck() function check the latest three files in path and subdirectories. 293 * The function will fix the FAT when the file size info of directory is not matched with FAT. 294 * 295 * @attention 296 * <ul> 297 * <li>This function only support for FAT32.</li> 298 * </ul> 299 * 300 * @param path [IN] Type #const char * The path of the directory to be checked. 301 * 302 * @retval #0 truncate success. 303 * @retval #-1 truncate failed. 304 * 305 * @par Dependency: 306 * <ul><li>fs.h: the header file that contains the API declaration.</li></ul> 307 * @see 308 * 309 * @since Huawei LiteOS V200R001C00 310 */ 311 312 FAR int fscheck(FAR const char *path); 313 314 #ifdef LOSCFG_FS_FAT_VIRTUAL_PARTITION 315 /** 316 * @ingroup fs 317 * @get the virtual partitions' or free space information in virtual parition feature. 318 * 319 * @par Description: 320 * The virstatfs() function returns the information about the a virtual partition or the free space 321 * outside the virtual partition. 322 * 323 * @attention 324 * <ul> 325 * <li>This function only support for FAT32.</li> 326 * <li>This function only support for the virtual partition feature.</li> 327 * <li>The parameter 'buf' need to be allocate enough memory space outside the function first.</li> 328 * </ul> 329 * 330 * @param path [IN] Type #const char * The path which virtual partition or free space to be checked. 331 * @param buf [OUT] Type #struct statfs * The statfs buffer saving the information. 332 * 333 * @retval #0 virstatfs success. 334 * @retval #-1 virstatfs failed. 335 * 336 * @par Dependency: 337 * <ul><li>fs.h: the header file that contains the API declaration.</li></ul> 338 * @see 339 * 340 * @since Huawei LiteOS V200R002C00 341 */ 342 343 extern int virstatfs(FAR const char *path, FAR struct statfs *buf); 344 345 /** 346 * @ingroup fs 347 * @set the virtual partition information. 348 * 349 * @par Description: 350 * The los_set_virpartparam() function use for set virtual partition parameter. 351 * The parameter include virtual partition number, virtual partition percent, virtual partition name 352 * and the partition path which need mount virtual partition. 353 * 354 * @attention 355 * <ul> 356 * <li>This function only support for FAT32.</li> 357 * <li>This function only support for the virtual partition feature.</li> 358 * <li>This function only can be used before mount function.</li> 359 * <li>The function can be invoked once before umount partition.</li> 360 * <li>Now support set single partition,the partition information will be replaced if it used for set another partition name.</li> 361 * <li>The function has no effert if virtual partition information is already in the partition.</li> 362 * </ul> 363 * 364 * @param virtualinfo [IN] Type #virpartinfo The struct which include virtual partition information. 365 * 366 * @retval #0 los_set_virpartparam success. 367 * @retval #-1 los_set_virpartparam failed. 368 * 369 * @par Dependency: 370 * <ul><li>fs.h: the header file that contains the API declaration.</li></ul> 371 * @see 372 * 373 * @since Huawei LiteOS V200R002C00 374 */ 375 376 int los_set_virpartparam(virpartinfo virtualinfo); 377 378 #endif 379 380 /** 381 * @ingroup fs 382 * 383 * @par Description: 384 * The chattr() function shall change the mode of file named by the pathname pointed to by the path argument. 385 * 386 * @attention 387 * <ul> 388 * <li>Now only fat filesystem support this function.</li> 389 * </ul> 390 * 391 * @retval #0 On success. 392 * @retval #-1 On failure with errno set. 393 * 394 * @par Errors 395 * <ul> 396 * <li><b>EINVAL</b>: The path is a null pointer or points to an empty string.</li> 397 * <li><b>ENAMETOOLONG</b>: The length of a component of a pathname is longer than {NAME_MAX}.</li> 398 * <li><b>ENOENT</b>: A component of the path does not exist.</li> 399 * <li><b>EPERM</b>: The entry represented by the path is a mount point.</li> 400 * <li><b>ENOSYS</b>: The file system doesn't support this function.</li> 401 * <li><b>EACCES</b>: It is a read-only file system.</li> 402 * <li><b>ENOMEM</b>: Out of memory.</li> 403 * <li><b>EIO</b>: A hard error occurred in the low level disk I/O layer or the physical drive cannot work.</li> 404 * <li><b>ENODEV</b>: The device is not existed.</li> 405 * </ul> 406 * 407 * @par Dependency: 408 * <ul><li>fs.h</li></ul> 409 * @see None 410 * @since Huawei LiteOS V100R001C00 411 */ 412 413 int chattr(const char *path, mode_t mode); 414 415 /** 416 * @ingroup fs 417 * 418 * @par Description: 419 * The LOS_BcacheSyncByName() function shall sync all the data in the cache corresponding to the disk name to the disk. 420 * 421 * @param name [IN] name of the disk 422 * 423 * @attention 424 * <ul> 425 * <li>Now only fat filesystem support this function.</li> 426 * </ul> 427 * 428 * @retval #0 On success. 429 * @retval #INT32 On failure. 430 * 431 * @par Dependency: 432 * <ul><li>fs.h</li></ul> 433 * @see None 434 * @since Huawei LiteOS V200R002C10 435 */ 436 437 extern INT32 LOS_BcacheSyncByName(const CHAR *name); 438 439 /** 440 * @ingroup fs 441 * 442 * @par Description: 443 * The LOS_GetDirtyRatioByName() function shall return the percentage of dirty blocks in the cache corresponding 444 * to the disk name. 445 * 446 * @param name [IN] name of the disk 447 * 448 * @attention 449 * <ul> 450 * <li>Now only fat filesystem support this function.</li> 451 * </ul> 452 * 453 * @retval #INT32 the percentage of dirty blocks. 454 * @retval #-1 On failure. 455 * 456 * @par Dependency: 457 * <ul><li>fs.h</li></ul> 458 * @see None 459 * @since Huawei LiteOS V200R002C10 460 */ 461 462 extern INT32 LOS_GetDirtyRatioByName(const CHAR *name); 463 464 #ifdef LOSCFG_FS_FAT_CACHE_SYNC_THREAD 465 /** 466 * @ingroup fs 467 * 468 * @par Description: 469 * The LOS_SetDirtyRatioThreshold() function shall set the dirty ratio threshold of bcache. When the percentage 470 * of dirty blocks in the cache is greater than the threshold, write back data to disk. 471 * 472 * @param dirtyRatio [IN] Threshold of the percentage of dirty blocks, expressed in %. 473 * 474 * @attention 475 * <ul> 476 * <li>The dirtyRatio must be less than or equal to 100, or the setting is invalid.</li> 477 * </ul> 478 * 479 * @retval #VOID None. 480 * 481 * @par Dependency: 482 * <ul><li>fs.h</li></ul> 483 * @see LOS_SetSyncThreadInterval | LOS_SetSyncThreadPrio 484 * @since Huawei LiteOS V200R002C10 485 */ 486 487 extern VOID LOS_SetDirtyRatioThreshold(UINT32 dirtyRatio); 488 489 /** 490 * @ingroup fs 491 * @brief Obtain the dirty ratio threshold of bcache. 492 * 493 * @par Description: 494 * This API is used to obtain the dirty ratio threshold of bcache. 495 * 496 * @attention None. 497 * 498 * @retval #UINT32 Dirty ratio. 499 * 500 * @par Dependency: 501 * <ul><li>fs.h</li></ul> 502 * @see LOS_SetDirtyRatioThreshold 503 * @since Huawei LiteOS 206.1.0 504 */ 505 extern UINT32 LOS_GetDirtyRatioThreshold(VOID); 506 507 /** 508 * @ingroup fs 509 * 510 * @par Description: 511 * The LOS_SetSyncThreadInterval() function shall set the interval for the sync thread to wake up. 512 * 513 * @param interval [IN] the interval time for the sync thread to wake up, in milliseconds, accuracy is 10ms. 514 * 515 * @attention 516 * <ul> 517 * <li>None</li> 518 * </ul> 519 * 520 * @retval #VOID None. 521 * 522 * @par Dependency: 523 * <ul><li>fs.h</li></ul> 524 * @see LOS_SetDirtyRatioThreshold | LOS_SetSyncThreadPrio 525 * @since Huawei LiteOS V200R002C10 526 */ 527 528 extern VOID LOS_SetSyncThreadInterval(UINT32 interval); 529 530 /** 531 * @ingroup fs 532 * @brief Obtain the interval for the sync thread to wake up. 533 * 534 * @par Description: 535 * This API is used to obtain the interval for the sync thread to wake up. 536 * 537 * @attention None. 538 * 539 * @retval #UINT32 The interval time for the sync thread to wake up, in milliseconds. 540 * 541 * @par Dependency: 542 * <ul><li>fs.h</li></ul> 543 * @see LOS_SetSyncThreadInterval 544 * @since Huawei LiteOS 206.1.0 545 */ 546 extern UINT32 LOS_GetSyncThreadInterval(VOID); 547 548 /** 549 * @ingroup fs 550 * 551 * @par Description: 552 * The LOS_SetSyncThreadPrio() function shall set the priority of the sync thread. 553 * 554 * @param prio [IN] priority of sync thread to be set 555 * @param name [IN] name of the disk 556 * 557 * @attention 558 * <ul> 559 * <li>The prio must be less than 31 and be greater than 0, or the setting is invalid.</li> 560 * <li>If the parameter name is NULL, it only set the value of a global variable, and take effect the next time the 561 * thread is created. If name is not NULL and can't find the disk corresponding to name, it shall return an error.</li> 562 * </ul> 563 * 564 * @retval #INT32 On failure. 565 * @retval 0 On success. 566 * 567 * @par Dependency: 568 * <ul><li>fs.h</li></ul> 569 * @see LOS_SetDirtyRatioThreshold | LOS_SetSyncThreadInterval | LOS_TaskPriSet 570 * @since Huawei LiteOS V200R002C10 571 */ 572 573 extern INT32 LOS_SetSyncThreadPrio(UINT32 prio, const CHAR *name); 574 575 #endif 576 577 /** 578 * @ingroup fs 579 * 580 * @par Description: 581 * The LOS_SetBlockExpireInterval() function shall set the max expire interval for block. 582 * If the expire interval of blocks is reached, the current block will be synchronized 583 * 584 * @param interval [IN] the expire interval for the block 585 * 586 * @attention 587 * <ul> 588 * <li>None</li> 589 * </ul> 590 * 591 * @retval #VOID None. 592 * 593 * @par Dependency: 594 * <ul><li>fs.h</li></ul> 595 * @see LOS_SetBlockExpireInterval 596 * @since Huawei LiteOS V200R006C00 597 */ 598 599 extern VOID LOS_SetBlockExpireInterval(UINT32 interval); 600 601 /** 602 * @ingroup fs 603 * @brief Obtain the max expire interval for block. 604 * 605 * @par Description: 606 * This API is used to obtain the max expire interval for block. 607 * 608 * @attention None. 609 * 610 * @retval #UINT32 The expire interval for the block, in milliseconds. 611 * 612 * @par Dependency: 613 * <ul><li>fs.h</li></ul> 614 * @see LOS_SetBlockExpireInterval 615 * @since Huawei LiteOS 206.1.0 616 */ 617 extern UINT32 LOS_GetBlockExpireInterval(VOID); 618 619 #ifdef __cplusplus 620 } 621 #endif /* __cplusplus */ 622 623 #endif /* _INCLUDE_LOS_FS_H */ 624