1.. _disk_access_api:
2
3Disk Access
4###########
5
6Overview
7********
8
9The disk access API provides access to storage devices.
10
11Initializing Disks
12******************
13
14Since many disk devices (such as SD cards) are hotpluggable, the disk access
15API provides IOCTLs to initialize and de-initialize the disk. They are
16as follows:
17
18* :c:macro:`DISK_IOCTL_CTRL_INIT`: Initialize the disk. Must be called before
19  additional I/O operations can be run on the disk device. Equivalent to
20  calling the legacy function :c:func:`disk_access_init`.
21
22* :c:macro:`DISK_IOCTL_CTRL_DEINIT`: De-initialize the disk. Once this IOCTL
23  is issued, the :c:macro:`DISK_IOCTL_CTRL_INIT` must be issued before
24  the disk can be used for addition I/O operations.
25
26Init/deinit IOCTL calls are balanced, so a disk will not de-initialize until
27an equal number of deinit IOCTLs have been issued as init IOCTLs.
28
29It is also possible to force a disk de-initialization by passing a
30pointer to a boolean set to ``true`` as a parameter to the
31:c:macro:`DISK_IOCTL_CTRL_DEINIT` IOCTL. This is an unsafe operation which
32each disk driver may handle differently, but it will always return
33a value indicating success.
34
35Note that de-initializing a disk is a low level operation- typically the
36de-initialization and initialization calls should be left to the filesystem
37implementation, and the user application should not need to manually
38de-initialize the disk and can instead call :c:func:`fs_unmount`
39
40SD Card support
41***************
42
43Zephyr has support for some SD card controllers and support for interfacing
44SD cards via SPI. These drivers use disk driver interface and a file system
45can access the SD cards via disk access API.
46Both standard and high-capacity SD cards are supported.
47
48.. note:: FAT filesystems are not power safe so the filesystem may become
49   corrupted if power is lost or if the card is removed without unmounting
50   the filesystem
51
52SD Memory Card subsystem
53========================
54
55Zephyr supports SD memory cards via the disk driver API, or via the SDMMC
56subsystem. This subsystem can be used transparently via the disk driver API,
57but also supports direct block level access to cards. The SDMMC subsystem
58interacts with the :ref:`sd host controller api <sdhc_api>` to communicate
59with attached SD cards.
60
61
62SD Card support via SPI
63=======================
64
65Example devicetree fragment below shows how to add SD card node to ``spi1``
66interface. Example uses pin ``PA27`` for chip select, and runs the SPI bus
67at 24 MHz once the SD card has been initialized:
68
69.. code-block:: devicetree
70
71    &spi1 {
72            status = "okay";
73            cs-gpios = <&porta 27 GPIO_ACTIVE_LOW>;
74
75            sdhc0: sdhc@0 {
76		    compatible = "zephyr,sdhc-spi-slot";
77                    reg = <0>;
78                    status = "okay";
79		    mmc {
80			compatible = "zephyr,sdmmc-disk";
81                        disk-name = "SD";
82			status = "okay";
83		    };
84                    spi-max-frequency = <24000000>;
85            };
86    };
87
88The SD card will be automatically detected and initialized by the
89filesystem driver when the board boots.
90
91To read and write files and directories, see the :ref:`file_system_api` in
92:zephyr_file:`include/zephyr/fs/fs.h` such as :c:func:`fs_open()`,
93:c:func:`fs_read()`, and :c:func:`fs_write()`.
94
95eMMC Device Support
96*******************
97
98Zephyr also has support for eMMC devices using the Disk Access API.
99MMC in zephyr is implemented using the SD subsystem because the MMC bus
100shares a lot of similarity with the SD bus. MMC controllers also use the
101SDHC device driver API.
102
103Emulated block device on flash partition support
104************************************************
105
106Zephyr flashdisk driver makes it possible to use flash memory partition as
107a block device. The flashdisk instances are defined in devicetree:
108
109.. code-block:: devicetree
110
111    / {
112        msc_disk0 {
113            compatible = "zephyr,flash-disk";
114            partition = <&storage_partition>;
115            disk-name = "NAND";
116            cache-size = <4096>;
117        };
118    };
119
120The cache size specified in :dtcompatible:`zephyr,flash-disk` node should be
121equal to backing partition minimum erasable block size.
122
123NVMe disk support
124=================
125
126NVMe disks are also supported
127
128.. toctree::
129    :maxdepth: 1
130
131    nvme.rst
132
133
134Disk Access API Configuration Options
135*************************************
136
137Related configuration options:
138
139* :kconfig:option:`CONFIG_DISK_ACCESS`
140
141API Reference
142*************
143
144.. doxygengroup:: disk_access_interface
145
146Disk Driver Configuration Options
147*********************************
148
149Related driver configuration options:
150
151* :kconfig:option:`CONFIG_DISK_DRIVERS`
152
153Disk Driver Interface
154*********************
155
156.. doxygengroup:: disk_driver_interface
157