Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2016 Intel Corporation.
       3             :  * Copyright (c) 2021 Nordic Semiconductor ASA
       4             :  *
       5             :  * SPDX-License-Identifier: Apache-2.0
       6             :  */
       7             : 
       8             : /**
       9             :  * @file
      10             :  * @brief Disk Driver Interface
      11             :  *
      12             :  * This file contains interface for disk access. Apart from disks, various
      13             :  * other storage media like Flash and RAM disks may implement this interface to
      14             :  * be used by various higher layers(consumers) like USB Mass storage
      15             :  * and Filesystems.
      16             :  */
      17             : 
      18             : #ifndef ZEPHYR_INCLUDE_DRIVERS_DISK_H_
      19             : #define ZEPHYR_INCLUDE_DRIVERS_DISK_H_
      20             : 
      21             : /**
      22             :  * @brief Disk Driver Interface
      23             :  * @defgroup disk_driver_interface Disk Driver Interface
      24             :  * @since 1.6
      25             :  * @version 1.0.0
      26             :  * @ingroup io_interfaces
      27             :  * @{
      28             :  */
      29             : 
      30             : #include <zephyr/kernel.h>
      31             : #include <zephyr/types.h>
      32             : #include <zephyr/sys/dlist.h>
      33             : 
      34             : #ifdef __cplusplus
      35             : extern "C" {
      36             : #endif
      37             : 
      38             : /**
      39             :  * @brief Possible Cmd Codes for disk_ioctl()
      40             :  */
      41             : 
      42             : /** Get the number of sectors in the disk  */
      43           1 : #define DISK_IOCTL_GET_SECTOR_COUNT             1
      44             : /** Get the size of a disk SECTOR in bytes */
      45           1 : #define DISK_IOCTL_GET_SECTOR_SIZE              2
      46             : /** reserved. It used to be DISK_IOCTL_GET_DISK_SIZE */
      47           1 : #define DISK_IOCTL_RESERVED                     3
      48             : /** How many  sectors constitute a FLASH Erase block */
      49           1 : #define DISK_IOCTL_GET_ERASE_BLOCK_SZ           4
      50             : /** Commit any cached read/writes to disk */
      51           1 : #define DISK_IOCTL_CTRL_SYNC                    5
      52             : /** Initialize the disk. This IOCTL must be issued before the disk can be
      53             :  * used for I/O. It is reference counted, so only the first successful
      54             :  * invocation of this macro on an uninitialized disk will initialize the IO
      55             :  * device
      56             :  */
      57           1 : #define DISK_IOCTL_CTRL_INIT                    6
      58             : /** Deinitialize the disk. This IOCTL can be used to de-initialize the disk,
      59             :  * enabling it to be removed from the system if the disk is hot-pluggable.
      60             :  * Disk usage is reference counted, so for a given disk the
      61             :  * `DISK_IOCTL_CTRL_DEINIT` IOCTL must be issued as many times as the
      62             :  * `DISK_IOCTL_CTRL_INIT` IOCTL was issued in order to de-initialize it.
      63             :  *
      64             :  * This macro optionally accepts a pointer to a boolean as the `buf` parameter,
      65             :  * which if true indicates the disk should be forcibly stopped, ignoring all
      66             :  * reference counts. The disk driver must report success if a forced stop is
      67             :  * requested, but this operation is inherently unsafe.
      68             :  */
      69           1 : #define DISK_IOCTL_CTRL_DEINIT                  7
      70             : 
      71             : /**
      72             :  * @brief Possible return bitmasks for disk_status()
      73             :  */
      74             : 
      75             : /** Disk status okay */
      76           1 : #define DISK_STATUS_OK                  0x00
      77             : /** Disk status uninitialized */
      78           1 : #define DISK_STATUS_UNINIT              0x01
      79             : /** Disk status no media */
      80           1 : #define DISK_STATUS_NOMEDIA             0x02
      81             : /** Disk status write protected */
      82           1 : #define DISK_STATUS_WR_PROTECT          0x04
      83             : 
      84             : struct disk_operations;
      85             : 
      86             : /**
      87             :  * @brief Disk info
      88             :  */
      89           1 : struct disk_info {
      90             :         /** Internally used list node */
      91           1 :         sys_dnode_t node;
      92             :         /** Disk name */
      93           1 :         const char *name;
      94             :         /** Disk operations */
      95           1 :         const struct disk_operations *ops;
      96             :         /** Device associated to this disk */
      97           1 :         const struct device *dev;
      98             :         /** Internally used disk reference count */
      99           1 :         uint16_t refcnt;
     100             : };
     101             : 
     102             : /**
     103             :  * @brief Disk operations
     104             :  */
     105           1 : struct disk_operations {
     106           0 :         int (*init)(struct disk_info *disk);
     107           0 :         int (*status)(struct disk_info *disk);
     108           0 :         int (*read)(struct disk_info *disk, uint8_t *data_buf,
     109             :                     uint32_t start_sector, uint32_t num_sector);
     110           0 :         int (*write)(struct disk_info *disk, const uint8_t *data_buf,
     111             :                      uint32_t start_sector, uint32_t num_sector);
     112           0 :         int (*ioctl)(struct disk_info *disk, uint8_t cmd, void *buff);
     113             : };
     114             : 
     115             : /**
     116             :  * @brief Register disk
     117             :  *
     118             :  * @param[in] disk Pointer to the disk info structure
     119             :  *
     120             :  * @return 0 on success, negative errno code on fail
     121             :  */
     122           1 : int disk_access_register(struct disk_info *disk);
     123             : 
     124             : /**
     125             :  * @brief Unregister disk
     126             :  *
     127             :  * @param[in] disk Pointer to the disk info structure
     128             :  *
     129             :  * @return 0 on success, negative errno code on fail
     130             :  */
     131           1 : int disk_access_unregister(struct disk_info *disk);
     132             : 
     133             : #ifdef __cplusplus
     134             : }
     135             : #endif
     136             : 
     137             : /**
     138             :  * @}
     139             :  */
     140             : 
     141             : #endif /* ZEPHYR_INCLUDE_DRIVERS_DISK_H_ */