services/storage/disk/access.html · services/storage/disk/access.rst 공식 원문 ↗

Zephyr 3.7.0 · Storage · Block Devices

Disk Access

Hotplug media와 block device를 sector 단위 공통 interface로 다룹니다.

Official pathservices/storage/disk/access.html
Source fileservices/storage/disk/access.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

Balanced disk initialization, SDMMC·SPI SD, eMMC, flash partition block device, Disk Access와 driver contract를 설명합니다.

Lifecycle

Init · deinit

I/O

Sector read · write

Media

SD · eMMC · flash · NVMe

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 45A83A181C8F5AD84DFD053D73FBF19FA76900D14DBE2A902EFB233D4F5C2DB9
.. _disk_access_api:

Disk Access
###########

Overview
********

The disk access API provides access to storage devices.

Initializing Disks
******************

Since many disk devices (such as SD cards) are hotpluggable, the disk access
API provides IOCTLs to initialize and de-initialize the disk. They are
as follows:

* :c:macro:`DISK_IOCTL_CTRL_INIT`: Initialize the disk. Must be called before
  additional I/O operations can be run on the disk device. Equivalent to
  calling the legacy function :c:func:`disk_access_init`.

* :c:macro:`DISK_IOCTL_CTRL_DEINIT`: De-initialize the disk. Once this IOCTL
  is issued, the :c:macro:`DISK_IOCTL_CTRL_INIT` must be issued before
  the disk can be used for addition I/O operations.

Init/deinit IOCTL calls are balanced, so a disk will not de-initialize until
an equal number of deinit IOCTLs have been issued as init IOCTLs.

It is also possible to force a disk de-initialization by passing a
pointer to a boolean set to ``true`` as a parameter to the
:c:macro:`DISK_IOCTL_CTRL_DEINIT` IOCTL. This is an unsafe operation which
each disk driver may handle differently, but it will always return
a value indicating success.

Note that de-initializing a disk is a low level operation- typically the
de-initialization and initialization calls should be left to the filesystem
implementation, and the user application should not need to manually
de-initialize the disk and can instead call :c:func:`fs_unmount`

SD Card support
***************

Zephyr has support for some SD card controllers and support for interfacing
SD cards via SPI. These drivers use disk driver interface and a file system
can access the SD cards via disk access API.
Both standard and high-capacity SD cards are supported.

.. note:: FAT filesystems are not power safe so the filesystem may become
   corrupted if power is lost or if the card is removed without unmounting
   the filesystem

SD Memory Card subsystem
========================

Zephyr supports SD memory cards via the disk driver API, or via the SDMMC
subsystem. This subsystem can be used transparently via the disk driver API,
but also supports direct block level access to cards. The SDMMC subsystem
interacts with the :ref:`sd host controller api <sdhc_api>` to communicate
with attached SD cards.


SD Card support via SPI
=======================

Example devicetree fragment below shows how to add SD card node to ``spi1``
interface. Example uses pin ``PA27`` for chip select, and runs the SPI bus
at 24 MHz once the SD card has been initialized:

.. code-block:: devicetree

    &spi1 {
            status = "okay";
            cs-gpios = <&porta 27 GPIO_ACTIVE_LOW>;

            sdhc0: sdhc@0 {
		    compatible = "zephyr,sdhc-spi-slot";
                    reg = <0>;
                    status = "okay";
		    mmc {
			compatible = "zephyr,sdmmc-disk";
			status = "okay";
		    };
                    spi-max-frequency = <24000000>;
            };
    };

The SD card will be automatically detected and initialized by the
filesystem driver when the board boots.

To read and write files and directories, see the :ref:`file_system_api` in
:zephyr_file:`include/zephyr/fs/fs.h` such as :c:func:`fs_open()`,
:c:func:`fs_read()`, and :c:func:`fs_write()`.

eMMC Device Support
*******************

Zephyr also has support for eMMC devices using the Disk Access API.
MMC in zephyr is implemented using the SD subsystem because the MMC bus
shares a lot of similarity with the SD bus. MMC controllers also use the
SDHC device driver API.

Emulated block device on flash partition support
************************************************

Zephyr flashdisk driver makes it possible to use flash memory partition as
a block device. The flashdisk instances are defined in devicetree:

.. code-block:: devicetree

    / {
        msc_disk0 {
            compatible = "zephyr,flash-disk";
            partition = <&storage_partition>;
            disk-name = "NAND";
            cache-size = <4096>;
        };
    };

The cache size specified in :dtcompatible:`zephyr,flash-disk` node should be
equal to backing partition minimum erasable block size.

NVMe disk support
=================

NVMe disks are also supported

.. toctree::
    :maxdepth: 1

    nvme.rst


Disk Access API Configuration Options
*************************************

Related configuration options:

* :kconfig:option:`CONFIG_DISK_ACCESS`

API Reference
*************

.. doxygengroup:: disk_access_interface

Disk Driver Configuration Options
*********************************

Related driver configuration options:

* :kconfig:option:`CONFIG_DISK_DRIVERS`

Disk Driver Interface
*********************

.. doxygengroup:: disk_driver_interface

Part 3

한국어 전문 번역

Overview

Disk Access API는 sector-oriented storage device에 공통 access를 제공합니다.

Initializing Disks

SD card처럼 hotpluggable한 device가 많으므로 IOCTL로 disk를 initialize·deinitialize합니다. DISK_IOCTL_CTRL_INIT은 추가 I/O 전에 반드시 호출하며 legacy disk_access_init()과 같습니다. DISK_IOCTL_CTRL_DEINIT 뒤 다시 쓰려면 INIT을 다시 호출해야 합니다.

Init/deinit은 balanced reference count입니다. INIT 수와 같은 DEINIT 수가 들어오기 전에는 실제 deinitialize하지 않습니다.

Balanced disk initialization
UNINIThotplug media를 아직 사용하지 않음
DISK_IOCTL_CTRL_INIT · ref++
READYread · write · ioctl 가능
같은 수의 DEINIT · ref--
UNINITrefcount가 0일 때 실제 deinit
force=true는 unsafe

DEINIT parameter로 true boolean pointer를 넘기면 강제 deinitialize할 수 있습니다. Driver마다 처리 방식이 다르고 항상 success를 반환하는 unsafe operation이므로 정상 ownership 해제 대신 사용하면 안 됩니다.

Disk deinit은 low-level operation입니다. 보통 filesystem이 init/deinit을 담당하므로 application은 직접 deinitialize하지 말고 fs_unmount()를 호출합니다.

SD Card support

Zephyr는 일부 SD controller와 SPI-connected SD card를 지원합니다. Driver는 disk interface를 제공하므로 filesystem이 Disk Access API로 standard와 high-capacity SD card를 모두 사용할 수 있습니다.

SD Memory Card subsystem

SD card는 disk driver API 또는 SDMMC subsystem으로 사용할 수 있습니다. SDMMC도 disk API를 투명하게 제공하면서 direct block access를 지원하고, attached card와 통신할 때 SD host controller API를 사용합니다.

SD Card support via SPI

다음 overlay는 spi1에 SD slot을 만들고 PA27을 chip select로 사용하며 initialization 뒤 24MHz로 동작합니다.

&spi1 {
        status = "okay";
        cs-gpios = <&porta 27 GPIO_ACTIVE_LOW>;

        sdhc0: sdhc@0 {
                compatible = "zephyr,sdhc-spi-slot";
                reg = <0>;
                status = "okay";
                mmc {
                    compatible = "zephyr,sdmmc-disk";
                    status = "okay";
                };
                spi-max-frequency = <24000000>;
        };
};

Board boot 때 filesystem driver가 card를 자동 detect·initialize합니다. File과 directory는 include/zephyr/fs/fs.h의 fs_open(), fs_read(), fs_write() 등을 사용합니다.

eMMC Device Support

eMMC도 Disk Access API로 지원합니다. MMC bus는 SD bus와 유사해 Zephyr MMC 구현은 SD subsystem과 SDHC driver API를 재사용합니다.

Emulated block device on flash partition support

Flashdisk driver는 flash partition을 block device로 노출합니다. Instance는 Devicetree에 정의합니다.

/ {
    msc_disk0 {
        compatible = "zephyr,flash-disk";
        partition = <&storage_partition>;
        disk-name = "NAND";
        cache-size = <4096>;
    };
};

zephyr,flash-disk node의 cache-size는 backing partition의 minimum erasable block size와 같아야 합니다.

NVMe disk support

NVMe disk도 지원하며 세부 controller·namespace 설정은 NVMe 문서를 참고합니다.

Disk Access API Configuration Options

공통 Disk Access layer는 CONFIG_DISK_ACCESS로 활성화합니다.

API Reference

disk_access_init
Legacy API로 name의 disk를 initialize합니다. CTRL_INIT IOCTL과 같습니다.
disk_access_status
Disk의 initialized, no-media, write-protect status bit를 읽습니다.
disk_access_read
지정 sector부터 sector count만큼 caller buffer로 읽습니다.
disk_access_write
Caller buffer를 지정 sector range에 씁니다.
disk_access_ioctl
Initialization, sync와 geometry query 같은 control command를 실행합니다.
DISK_IOCTL_GET_SECTOR_COUNT
전체 addressable sector 수를 반환합니다.
DISK_IOCTL_GET_SECTOR_SIZE
한 logical sector의 byte 크기를 반환합니다.
DISK_IOCTL_RESERVED
Driver-specific IOCTL 번호가 시작되는 reserved boundary입니다.
DISK_IOCTL_GET_ERASE_BLOCK_SZ
Sector 단위 erase block 크기를 반환합니다.
DISK_IOCTL_CTRL_SYNC
Pending write를 physical media에 flush합니다.
DISK_IOCTL_CTRL_INIT
Disk reference를 증가시키고 필요하면 media를 initialize합니다.
DISK_IOCTL_CTRL_DEINIT
Disk reference를 감소시키고 마지막 reference에서 deinitialize합니다.
DISK_STATUS_OK
Disk가 정상적으로 준비된 status입니다.
DISK_STATUS_UNINIT
Disk가 아직 initialize되지 않은 status bit입니다.
DISK_STATUS_NOMEDIA
Removable media가 감지되지 않은 status bit입니다.
DISK_STATUS_WR_PROTECT
Media가 write-protected 상태임을 나타냅니다.
disk_access_register
Name과 operation table을 가진 disk_info를 global registry에 추가합니다.
disk_access_unregister
Disk info를 registry에서 제거합니다.
disk_info
Disk name, operation, device pointer와 init reference count를 보관합니다.
disk_info.node
Global disk list에 연결하는 internal node입니다.
disk_info.name
Application과 filesystem이 disk를 찾을 때 쓰는 unique name입니다.
disk_info.ops
이 disk driver의 operation table입니다.
disk_info.dev
Backing Zephyr device pointer입니다.
disk_info.refcnt
Balanced CTRL_INIT/DEINIT 호출의 active reference 수입니다.
disk_operations
Driver가 구현하는 init, status, read, write와 ioctl callback table입니다.

Disk Driver Configuration Options

Disk driver implementation은 CONFIG_DISK_DRIVERS로 활성화합니다.

Disk Driver Interface

Driver는 disk_operations table로 init, status, sector read/write와 IOCTL을 구현하고 disk_info를 registry에 등록합니다.

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.