UFS (Universal Flash Storage) — MIPI M-PHY/UniPro & SCSI Protocol

UFS(Universal Flash Storage)는 JEDEC JESD220 표준으로 정의된 고성능 플래시 스토리지 인터페이스입니다. 플래그십 스마트폰, 태블릿, 자동차 인포테인먼트, 임베디드 시스템에서 핵심 저장 장치로 사용되며, MIPI M-PHY 물리 계층과 UniPro 전송 프로토콜 위에 SCSI 명령 체계를 운용합니다. 이 문서에서는 UFS 아키텍처, UFSHCI(UFS Host Controller Interface), ufshcd 호스트 드라이버, MCQ(Multi-Circular Queue), Write Booster, HPB(Host Performance Booster), 인라인 암호화(ICE), RPMB, 전원 관리, 디버깅, 성능 튜닝까지 Linux 커널의 UFS 서브시스템(drivers/ufs/) 전체를 심층 분석합니다.

/* UFS 핵심 구조체 관계 — drivers/ufs/core/ufshcd.c */
struct ufs_hba {
    struct Scsi_Host *host;          /* SCSI 호스트 어댑터 */
    void __iomem *mmio_base;         /* UFSHCI 레지스터 매핑 */
    struct utp_transfer_req_desc *utrdl_base_addr; /* UTRD 배열 */
    struct utp_task_req_desc *utmrdl_base_addr;    /* UTMRD 배열 */
    struct ufshcd_lrb *lrb;          /* LRB 배열 (태그별) */
    const struct ufs_hba_variant_ops *vops; /* 벤더 콜백 */
    struct ufs_dev_info dev_info;    /* 디바이스 정보 */
    enum ufs_pm_level rpm_lvl;       /* 런타임 PM 레벨 */
    enum ufs_pm_level spm_lvl;       /* 시스템 PM 레벨 */
    u32 capabilities;                /* 호스트 역량 비트맵 */
    unsigned int nutrs;              /* UTP Transfer Request 슬롯 수 */
    unsigned int nutmrs;             /* UTP Task Management 슬롯 수 */
    /* ... */
};

# UFS 디바이스 확인
$ lsscsi
[0:0:0:49488] disk    SAMSUNG  KLUDG4U1EA-B0C1  0200  /dev/sda
[0:0:0:49456] disk    SAMSUNG  KLUDG4U1EA-B0C1  0200  /dev/sdb

# UFS sysfs 정보 확인
$ cat /sys/bus/platform/drivers/ufshcd-qcom/*/device_descriptor/manufacturer_name
SAMSUNG

# UFS 디바이스 속성 확인
$ cat /sys/class/scsi_device/0:0:0:49488/device/vendor
SAMSUNG

단계별 이해: UFS I/O 처리 흐름

1. 블록 레이어 → SCSI mid-layer → ufshcd_queuecommand
   사용자 공간의 read()/write() 호출이 VFS, 파일시스템을 거쳐 블록 레이어의 struct request로 변환됩니다. blk-mq가 이를 SCSI mid-layer에 전달하면, scsi_queue_rq()가 struct scsi_cmnd를 생성하고 UFS 호스트 드라이버의 ufshcd_queuecommand()을 호출합니다.

   /* SCSI mid-layer → UFS 호스트 드라이버 진입점 */
   static int ufshcd_queuecommand(struct Scsi_Host *host,
                                   struct scsi_cmnd *cmd)
   {
       struct ufshcd_lrb *lrbp;
       int tag = scsi_cmd_to_rq(cmd)->tag;
   
       lrbp = &hba->lrb[tag];
       lrbp->cmd = cmd;
       lrbp->task_tag = tag;
       lrbp->lun = ufshcd_scsi_to_upiu_lun(cmd->device->lun);
   
       ufshcd_compose_devman_upiu(hba, lrbp);  /* UPIU 구성 */
       ufshcd_send_command(hba, tag);            /* doorbell ring */
       return 0;
   }

2. UPIU(UFS Protocol Information Unit) 및 UTRD 구성
   ufshcd_compose_devman_upiu()는 SCSI CDB(Command Descriptor Block)를 UPIU 형식으로 변환합니다. Command UPIU(32바이트 헤더 + CDB)를 UCD(UTP Command Descriptor) 내에 배치하고, 데이터 전송이 필요한 경우 PRDT(Physical Region Descriptor Table)를 scatter-gather 리스트로부터 구성합니다. UTRD(UTP Transfer Request Descriptor)는 UCD 주소, 데이터 방향, 응답 UPIU 오프셋 등을 담습니다.
3. UFSHCI DMA 매핑 및 Doorbell 링
   UTRD와 UCD가 DMA 접근 가능한 메모리에 준비되면, ufshcd_send_command()가 UFSHCI의 UTRLDBR(UTP Transfer Request List DoorBell Register)에 해당 태그 비트를 설정합니다. 호스트 컨트롤러 하드웨어는 이를 감지하여 DMA로 UTRD를 읽어가고, UCD 내의 Command UPIU를 추출합니다.

   /* Doorbell 링 — UFSHCI에 전송 시작 알림 */
   void ufshcd_send_command(struct ufs_hba *hba, unsigned int task_tag)
   {
       ufshcd_writel(hba, 1 << task_tag, REG_UTP_TRANSFER_REQ_DOOR_BELL);
       /* 하드웨어가 UTRD[task_tag]를 DMA로 fetch */
   }

4. M-PHY/UniPro 전송 및 디바이스 처리
   UFSHCI 하드웨어는 Command UPIU를 UniPro 프레임으로 캡슐화하고 M-PHY 물리 계층을 통해 UFS 디바이스에 전송합니다. 디바이스는 UPIU를 수신하여 SCSI 명령을 해석하고, NAND 플래시에 대한 읽기/쓰기를 수행합니다. 쓰기 요청의 경우, 디바이스는 먼저 RTT(Ready To Transfer) UPIU를 보내 호스트에 데이터 전송을 요청합니다.
5. 응답 UPIU 수신 및 SCSI 완료
   디바이스가 명령 처리를 완료하면 Response UPIU를 호스트에 전송합니다. UFSHCI가 이를 수신하여 UCD의 Response UPIU 영역에 기록하고, 인터럽트를 발생시킵니다. ufshcd_intr() → ufshcd_transfer_req_compl()가 호출되어 완료된 태그의 Response UPIU 상태를 확인하고, scsi_done()으로 SCSI 레이어에 완료를 알립니다.

   /* 인터럽트 핸들러 — 전송 완료 처리 */
   static irqreturn_t ufshcd_intr(int irq, void *__hba)
   {
       struct ufs_hba *hba = __hba;
       u32 intr_status = ufshcd_readl(hba, REG_INTERRUPT_STATUS);
   
       if (intr_status & UTP_TRANSFER_REQ_COMPL)
           ufshcd_transfer_req_compl(hba);
   
       if (intr_status & UTP_TASK_REQ_COMPL)
           ufshcd_tmc_handler(hba);
   
       return IRQ_HANDLED;
   }

UFS 아키텍처 개요

UFS의 프로토콜 스택은 네트워크 OSI 모델과 유사한 계층 구조를 갖습니다. 최상위 응용 계층에서 SCSI 명령을 생성하고, UTP 계층이 이를 UPIU로 캡슐화하며, UniPro 계층이 전송을 관리하고, M-PHY 물리 계층이 실제 직렬 데이터를 전송합니다.

Linux 커널의 UFS 관련 소스 코드는 drivers/ufs/ 디렉터리에 집중되어 있습니다. 커널 6.x 기준으로 core, host 서브디렉터리로 구분됩니다.

# UFS 커널 소스 구조 (Linux 6.x)
drivers/ufs/
├── core/
│   ├── ufshcd.c            # UFS 호스트 컨트롤러 드라이버 코어 (메인)
│   ├── ufshcd-crypto.c     # 인라인 암호화 (ICE) 지원
│   ├── ufshcd-priv.h       # 내부 선언
│   ├── ufs-sysfs.c         # sysfs 인터페이스
│   ├── ufs-debugfs.c       # debugfs 인터페이스
│   ├── ufs-mcq.c           # Multi-Circular Queue 지원
│   ├── ufs-hwmon.c         # 하드웨어 모니터 (온도)
│   └── ufs_bsg.c           # BSG(Block SCSI Generic) 인터페이스
├── host/
│   ├── ufs-qcom.c          # Qualcomm UFS PHY/호스트 드라이버
│   ├── ufs-exynos.c        # Samsung Exynos UFS 드라이버
│   ├── ufs-mediatek.c      # MediaTek UFS 드라이버
│   ├── ufs-hisi.c          # HiSilicon UFS 드라이버
│   ├── ufs-renesas.c       # Renesas UFS 드라이버
│   ├── ufshcd-pci.c        # PCI 기반 UFS 호스트 (Intel)
│   ├── ufshcd-pltfrm.c     # 플랫폼 디바이스 공통 코드
│   ├── ufs-qcom.h          # Qualcomm 전용 헤더
│   └── tc-dwc-g210.c       # Synopsys DWC UFS PHY
└── Kconfig / Makefile

/* UFS 관련 주요 헤더 파일 */
#include <ufs/ufshcd.h>       /* struct ufs_hba, ufshcd_* API */
#include <ufs/ufshci.h>       /* UFSHCI 레지스터, UTRD/UTMRD 정의 */
#include <ufs/ufs.h>          /* UFS 스펙 상수, UPIU 정의 */
#include <ufs/unipro.h>       /* UniPro DME 속성 정의 */

/* UFS 버전 매크로 */
#define UFS_SPEC_VER_20   0x0200
#define UFS_SPEC_VER_21   0x0210
#define UFS_SPEC_VER_30   0x0300
#define UFS_SPEC_VER_31   0x0310
#define UFS_SPEC_VER_40   0x0400

MIPI M-PHY / UniPro 물리·전송 계층

UniPro는 M-PHY 위에 4개 서브 계층(L1.5, L2, L3, L4)을 쌓아 신뢰성 있는 데이터 전송을 보장합니다.

• L1.5 (PHY Adapter) — M-PHY 레인을 관리합니다. 다중 레인 병합(lane merging), 기어/모드 전환, 전력 모드(FAST/SLOW/FASTAUTO/SLOWAUTO) 설정을 담당합니다.
• L2 (Data Link) — AFC(Adaptive Flow Control)를 통한 흐름 제어, CRC 기반 오류 검출, NAC(Negative Acknowledgment) 기반 재전송, TC(Traffic Class) 0/1 우선순위 분리를 수행합니다.
• L3 (Network) — DeviceID 기반 라우팅을 제공합니다. UFS는 점대점(point-to-point) 연결이므로 라우팅이 단순하지만, UniPro 스위치를 통한 다중 디바이스 연결도 규격상 가능합니다.
• L4 (Transport) — CPort(Connection Port) 기반 멀티플렉싱을 제공합니다. 하나의 물리적 링크 위에 여러 논리적 연결(connection)을 생성할 수 있으며, UFS는 CPort 0을 데이터 전송에 사용합니다.

/* UniPro DME 속성 설정 — ufshcd_dme_set() */
int ufshcd_dme_set_attr(struct ufs_hba *hba, u32 attr_sel,
                         u8 attr_set, u32 mib_val, u8 peer)
{
    struct uic_command uic_cmd = {0};

    uic_cmd.command = peer ?
        UIC_CMD_DME_PEER_SET : UIC_CMD_DME_SET;
    uic_cmd.argument1 = attr_sel;   /* MIB 속성 ID + GenSelector */
    uic_cmd.argument2 = UIC_ARG_ATTR_TYPE(attr_set);
    uic_cmd.argument3 = mib_val;    /* 설정할 값 */

    return ufshcd_send_uic_cmd(hba, &uic_cmd);
}

/* 사용 예: HS-G4, Rate B, 2 Lane 설정 */
ufshcd_dme_set(hba, UIC_ARG_MIB(PA_HSGEAR), 4);     /* HS-Gear 4 */
ufshcd_dme_set(hba, UIC_ARG_MIB(PA_HSRATESERIRES), 2); /* Rate B */
ufshcd_dme_set(hba, UIC_ARG_MIB(PA_ACTIVETXDATALANES), 2); /* 2 Lane TX */
ufshcd_dme_set(hba, UIC_ARG_MIB(PA_ACTIVERXDATALANES), 2); /* 2 Lane RX */
ufshcd_dme_set(hba, UIC_ARG_MIB(PA_PWRMODE),
    FAST_MODE << 4 | FAST_MODE);   /* TX/RX 모두 FAST 모드 */

/* UniPro 주요 DME 속성 상수 (include/ufs/unipro.h) */
#define PA_ACTIVETXDATALANES    0x1560
#define PA_ACTIVERXDATALANES    0x1580
#define PA_TXGEAR               0x1568
#define PA_RXGEAR               0x1583
#define PA_HSSERIES             0x156A
#define PA_PWRMODE              0x1571
#define PA_MAXRXHSGEAR          0x1587
#define PA_LOCALVERINFO         0x15A0
#define PA_GRANULARITY          0x15AA
#define PA_PACPREQTIMEOUT       0x1590
#define PA_PACPREQEOBTIMEOUT    0x1591
#define DME_LOCALFC_PROTECTION_TIMEOUT_ATTR  0x1590

/* Power Mode 값 */
#define FAST_MODE       1
#define SLOW_MODE       2
#define FASTAUTO_MODE   4
#define SLOWAUTO_MODE   5
#define UNCHANGED       7

UPIU (UFS Protocol Information Unit) 프로토콜

/* UPIU 헤더 구조체 — include/ufs/ufs.h */
struct utp_upiu_header {
    __be32 dword_0;  /* Transaction Type | Flags | LUN | Task Tag */
    __be32 dword_1;  /* Cmd Set Type/IID | Query Func | Response | Status */
    __be32 dword_2;  /* EHS Length | Device Info | Data Segment Length */
    __be32 dword_3;  /* Reserved (or Query specific) */
};

/* Transaction Type 추출 매크로 */
#define UPIU_HEADER_TRANSACTION_TYPE(dword0) \
    (((dword0) >> 24) & 0xFF)

/* Command UPIU 구조체 */
struct utp_upiu_cmd {
    struct utp_upiu_header header;
    __be32 exp_data_transfer_len;  /* 예상 데이터 전송 길이 */
    u8     cdb[UFS_CDB_SIZE];     /* SCSI CDB (16바이트) */
};

/* Query UPIU 구조체 */
struct utp_upiu_query {
    struct utp_upiu_header header;
    u8     opcode;     /* Query 종류: Read/Write Descriptor/Attribute/Flag */
    u8     idn;        /* Descriptor/Attribute/Flag IDN */
    u8     index;      /* 인덱스 */
    u8     selector;   /* 선택자 */
    __be16 reserved_osf;
    __be16 length;     /* 데이터 길이 */
    __be32 value;      /* Attribute 값 또는 Flag 값 */
    __be32 reserved[2];
};

/* Command UPIU 구성 — ufshcd_compose_devman_upiu() */
static void ufshcd_prepare_utp_scsi_cmd_upiu(
    struct ufshcd_lrb *lrbp, u8 upiu_flags)
{
    struct utp_upiu_req *ucd_req_ptr = lrbp->ucd_req_ptr;
    struct scsi_cmnd *cmd = lrbp->cmd;

    /* UPIU 헤더 설정 */
    ucd_req_ptr->header.dword_0 = cpu_to_be32(
        UPIU_TRANSACTION_COMMAND << 24 |   /* Transaction Type */
        upiu_flags << 16 |                  /* Flags (R/W/None) */
        lrbp->lun << 8 |                   /* LUN */
        lrbp->task_tag);                    /* Task Tag */

    ucd_req_ptr->header.dword_1 = cpu_to_be32(
        UPIU_COMMAND_SET_TYPE_SCSI << 24);  /* SCSI Command Set */

    /* 예상 데이터 전송 길이 */
    ucd_req_ptr->sc.exp_data_transfer_len =
        cpu_to_be32(scsi_bufflen(cmd));

    /* SCSI CDB 복사 */
    memcpy(ucd_req_ptr->sc.cdb, cmd->cmnd, min_t(u8, cmd->cmd_len, UFS_CDB_SIZE));
}

UFS 디바이스 아키텍처

UFS 디바이스의 설정과 상태는 Descriptor, Attribute, Flag 세 가지 체계로 관리됩니다. 모두 Query UPIU를 통해 읽기/쓰기가 가능합니다.

/* Device Descriptor 읽기 — Query UPIU 사용 */
static int ufshcd_read_device_desc(struct ufs_hba *hba, u8 *buf, u32 size)
{
    return ufshcd_read_desc_param(hba,
        QUERY_DESC_IDN_DEVICE,  /* IDN = 0x00 */
        0,                       /* Index */
        0,                       /* Offset */
        buf, size);
}

/* Device Descriptor 주요 필드 오프셋 */
enum device_desc_param {
    DEVICE_DESC_PARAM_LEN           = 0x00,
    DEVICE_DESC_PARAM_TYPE          = 0x01,
    DEVICE_DESC_PARAM_DEVICE_TYPE   = 0x02,
    DEVICE_DESC_PARAM_DEVICE_CLASS  = 0x03,
    DEVICE_DESC_PARAM_DEVICE_SUB_CLASS = 0x04,
    DEVICE_DESC_PARAM_PRTCL         = 0x05,
    DEVICE_DESC_PARAM_NUM_LU        = 0x06,
    DEVICE_DESC_PARAM_NUM_WLU       = 0x07,
    DEVICE_DESC_PARAM_BOOT_ENBL     = 0x08,
    DEVICE_DESC_PARAM_MANF_ID       = 0x18, /* 제조사 ID (2바이트) */
    DEVICE_DESC_PARAM_SPEC_VER      = 0x10, /* UFS 스펙 버전 */
    DEVICE_DESC_PARAM_UFS_FEAT      = 0x1F, /* 지원 기능 비트맵 */
    DEVICE_DESC_PARAM_HPB_VER       = 0x40, /* HPB 버전 */
    DEVICE_DESC_PARAM_WB_TYPE       = 0x45, /* Write Booster 타입 */
};

/* Attribute 읽기/쓰기 예시 */
/* bCurrentPowerMode 읽기 */
u32 power_mode;
ufshcd_query_attr(hba, UPIU_QUERY_OPCODE_READ_ATTR,
    QUERY_ATTR_IDN_POWER_MODE, 0, 0, &power_mode);

/* bActiveICCLevel 쓰기 — 전류 소비 레벨 설정 */
u32 icc_level = 0x0F; /* 최대 레벨 */
ufshcd_query_attr(hba, UPIU_QUERY_OPCODE_WRITE_ATTR,
    QUERY_ATTR_IDN_ACTIVE_ICC_LVL, 0, 0, &icc_level);

/* Flag 설정 예시 — fDeviceInit 플래그로 디바이스 초기화 트리거 */
ufshcd_query_flag(hba, UPIU_QUERY_OPCODE_SET_FLAG,
    QUERY_FLAG_IDN_FDEVICEINIT, 0, NULL);

UFSHCI (UFS Host Controller Interface) 레지스터 아키텍처

UTRD(UTP Transfer Request Descriptor)는 UFSHCI 하드웨어가 DMA로 읽어가는 32바이트 구조체로, UCD(UTP Command Descriptor)의 DMA 주소와 데이터 전송 방향을 담습니다.

/* UTRD 구조체 — include/ufs/ufshci.h */
struct utp_transfer_req_desc {
    /* DWord 0-1: Command Descriptor 관련 */
    struct {
        __le32 dword_0;  /* CT(Command Type) | DD(Data Direction) | I(Interrupt) | OCS */
        __le32 dword_1;  /* Reserved */
    } header;

    /* DWord 2-3: UCD Base Address (Command UPIU 주소) */
    __le32 command_desc_base_addr_lo;  /* UCD 하위 32비트 주소 */
    __le32 command_desc_base_addr_hi;  /* UCD 상위 32비트 주소 */

    /* DWord 4-5: Response UPIU offset/length + PRDT offset/length */
    __le16 response_upiu_length;  /* Response UPIU 길이 (DWord 단위) */
    __le16 response_upiu_offset;  /* UCD 내 Response UPIU 오프셋 */
    __le16 prd_table_length;      /* PRDT 엔트리 수 */
    __le16 prd_table_offset;      /* UCD 내 PRDT 오프셋 */

    /* DWord 6-7: Reserved */
    __le32 reserved[2];
};

/* OCS (Overall Command Status) 값 */
enum utp_ocs {
    OCS_SUCCESS                  = 0x00,
    OCS_INVALID_CMD_TABLE_ATTR   = 0x01,
    OCS_INVALID_PRDT_ATTR        = 0x02,
    OCS_MISMATCH_DATA_BUF_SIZE   = 0x03,
    OCS_MISMATCH_RESP_UPIU_SIZE  = 0x04,
    OCS_PEER_COMM_FAILURE        = 0x05,
    OCS_ABORTED                  = 0x06,
    OCS_FATAL_ERROR              = 0x07,
    OCS_DEVICE_FATAL_ERROR       = 0x08,
    OCS_INVALID_CRYPTO_CONFIG    = 0x09,
    OCS_GENERAL_CRYPTO_ERROR     = 0x0A,
    OCS_INVALID_COMMAND_STATUS   = 0x0F,
};

/* LRB(Local Reference Block) 구조체 — 각 태그의 런타임 정보 */
struct ufshcd_lrb {
    struct utp_transfer_req_desc *utr_descriptor_ptr; /* UTRD 포인터 */
    struct utp_upiu_req *ucd_req_ptr;  /* UCD 내 Command UPIU 포인터 */
    struct utp_upiu_rsp *ucd_rsp_ptr;  /* UCD 내 Response UPIU 포인터 */
    struct ufshcd_sg_entry *ucd_prdt_ptr; /* PRDT 포인터 */

    struct scsi_cmnd *cmd;          /* 연결된 SCSI 명령 */
    u8 *sense_buffer;               /* Sense Data 버퍼 */
    unsigned int sense_bufflen;

    int scsi_status;
    int command_type;               /* SCSI / DEV_MANAGE / NOP */
    int task_tag;                   /* 슬롯 번호 (0~31) */
    u8 lun;                         /* 대상 LUN */
    bool req_abort_skip;            /* abort skip 플래그 */
    int crypto_key_slot;            /* 인라인 암호화 키 슬롯 (-1: 비활성) */
};

ufshcd 호스트 컨트롤러 드라이버

ufshcd의 핵심은 struct ufs_hba입니다. 이 구조체는 UFS 호스트 컨트롤러의 모든 상태를 관리하며, SCSI 호스트(Scsi_Host), UFSHCI 레지스터 매핑(mmio_base), UTRD/LRB 배열, 벤더 콜백(vops), 클럭/레귤레이터, 전원 관리 상태 등을 포함합니다.

/* ufs_hba 주요 필드 상세 — include/ufs/ufshcd.h */
struct ufs_hba {
    /* === SCSI 호스트 === */
    struct Scsi_Host *host;
    struct device *dev;

    /* === UFSHCI 레지스터 === */
    void __iomem *mmio_base;         /* MMIO 베이스 주소 */
    u32 ahit;                        /* 오토 히버네이트 타이머 값 */

    /* === UTRL / UTMRL DMA 메모리 === */
    struct utp_transfer_req_desc *utrdl_base_addr;  /* UTRD 배열 */
    dma_addr_t utrdl_dma_addr;                      /* UTRD DMA 주소 */
    struct utp_task_req_desc *utmrdl_base_addr;     /* UTMRD 배열 */
    dma_addr_t utmrdl_dma_addr;

    /* === UCD(Command Descriptor) DMA 메모리 === */
    struct utp_transfer_cmd_desc *ucdl_base_addr;   /* UCD 배열 */
    dma_addr_t ucdl_dma_addr;

    /* === LRB (Local Reference Block) 배열 === */
    struct ufshcd_lrb *lrb;          /* 태그별 런타임 정보 */
    unsigned long lrb_in_use;        /* 사용 중인 태그 비트맵 */

    /* === 벤더 콜백 === */
    const struct ufs_hba_variant_ops *vops;
    struct ufs_hba_variant *priv;    /* 벤더 전용 데이터 */

    /* === 역량 및 슬롯 수 === */
    u32 capabilities;                /* UFSHCI CAP 레지스터 값 */
    unsigned int nutrs;              /* Transfer Request 슬롯 수 (1~32) */
    unsigned int nutmrs;             /* Task Mgmt 슬롯 수 (1~8) */

    /* === 클럭 및 전원 === */
    struct list_head clk_list_head;  /* 클럭 목록 */
    struct ufs_vreg_info vreg_info;  /* vcc, vccq, vccq2 레귤레이터 */

    /* === 전원 관리 === */
    enum ufs_pm_level rpm_lvl;       /* 런타임 PM 레벨 */
    enum ufs_pm_level spm_lvl;       /* 시스템 PM 레벨 */
    int pm_op_in_progress;

    /* === 디바이스 정보 === */
    struct ufs_dev_info dev_info;    /* LU 수, WB 지원, HPB 지원 등 */
    u16 dev_quirks;                  /* 디바이스 quirk 비트맵 */

    /* === 에러 처리 === */
    struct work_struct eh_work;      /* 에러 핸들러 워크큐 */
    u32 errors;                      /* 마지막 에러 상태 */
    u32 uic_error;                   /* UIC 에러 상태 */

    /* === MCQ (UFS 4.0+) === */
    bool mcq_enabled;
    unsigned int nr_hw_queues;       /* MCQ 하드웨어 큐 수 */
    struct ufs_hw_queue *uhq;        /* MCQ 큐 배열 */
};

벤더별 플랫폼 드라이버는 ufs_hba_variant_ops(vops) 구조체를 통해 하드웨어 특화 초기화, PHY 설정, 전력 모드 전환 등의 콜백을 제공합니다.

/* 벤더 콜백 구조체 — include/ufs/ufshcd.h */
struct ufs_hba_variant_ops {
    const char *name;

    /* 초기화/해제 */
    int  (*init)(struct ufs_hba *);
    void (*exit)(struct ufs_hba *);

    /* 클럭 제어 */
    int  (*setup_clocks)(struct ufs_hba *, bool, enum ufs_notify_change_status);

    /* HCE(Host Controller Enable) 전후 알림 */
    int  (*hce_enable_notify)(struct ufs_hba *, enum ufs_notify_change_status);

    /* 링크 스타트업 전후 알림 */
    int  (*link_startup_notify)(struct ufs_hba *, enum ufs_notify_change_status);

    /* 전력 모드 변경 전후 알림 (Gear/Lane/Rate 변경) */
    int  (*pwr_change_notify)(struct ufs_hba *,
            enum ufs_notify_change_status,
            struct ufs_pa_layer_attr *desired,
            struct ufs_pa_layer_attr *final);

    /* 런타임 suspend/resume */
    int  (*suspend)(struct ufs_hba *, enum ufs_pm_op, enum ufs_notify_change_status);
    int  (*resume)(struct ufs_hba *, enum ufs_pm_op);

    /* PHY 특화 설정 */
    int  (*phy_initialization)(struct ufs_hba *);

    /* 디바이스 리셋 GPIO 제어 */
    int  (*device_reset)(struct ufs_hba *);

    /* MCQ 관련 (UFS 4.0+) */
    int  (*mcq_config_resource)(struct ufs_hba *);
    int  (*get_hba_mac)(struct ufs_hba *);      /* 최대 활성 명령 수 */
    int  (*op_runtime_config)(struct ufs_hba *); /* MCQ 런타임 설정 */

    /* 프로그램 키 (인라인 암호화) */
    int  (*program_key)(struct ufs_hba *,
            const union ufs_crypto_cfg_entry *, int);
};

/* 벤더 드라이버 등록 예시 (Qualcomm) */
static const struct ufs_hba_variant_ops ufs_hba_qcom_vops = {
    .name                   = "qcom",
    .init                   = ufs_qcom_init,
    .exit                   = ufs_qcom_exit,
    .setup_clocks           = ufs_qcom_setup_clocks,
    .hce_enable_notify      = ufs_qcom_hce_enable_notify,
    .link_startup_notify    = ufs_qcom_link_startup_notify,
    .pwr_change_notify      = ufs_qcom_pwr_change_notify,
    .suspend                = ufs_qcom_suspend,
    .resume                 = ufs_qcom_resume,
    .device_reset           = ufs_qcom_device_reset,
    .config_scaling_param   = ufs_qcom_config_scaling_param,
    .program_key            = ufs_qcom_ice_program_key,
    .mcq_config_resource    = ufs_qcom_mcq_config_resource,
    .get_hba_mac            = ufs_qcom_get_hba_mac,
    .op_runtime_config      = ufs_qcom_op_runtime_config,
};

ufshcd 등록 및 초기화 흐름

플랫폼 드라이버가 ufshcd_pltfrm_init()을 호출하면 다음 순서로 초기화가 진행됩니다:

1. ufshcd_alloc_host() — Scsi_Host와 ufs_hba 할당, SCSI 호스트 템플릿 설정
2. ufshcd_init() — UTRL/UTMRL/UCD DMA 메모리 할당, LRB 배열 초기화, 인터럽트 등록, 워크큐 생성
3. ufshcd_async_scan() (비동기) — HCE 활성화 → 링크 스타트업 → NOP OUT 확인 → Device Descriptor 읽기 → Gear 전환 → SCSI 호스트 스캔

/* 초기화 핵심 흐름 */
int ufshcd_pltfrm_init(struct platform_device *pdev,
                        const struct ufs_hba_variant_ops *vops)
{
    struct ufs_hba *hba;
    void __iomem *mmio_base;
    int irq, err;

    mmio_base = devm_platform_ioremap_resource(pdev, 0);
    irq = platform_get_irq(pdev, 0);

    err = ufshcd_alloc_host(&pdev->dev, &hba);
    hba->vops = vops;

    err = ufshcd_init(hba, mmio_base, irq);
    /* → 내부에서 ufshcd_async_scan() 스케줄링 */

    platform_set_drvdata(pdev, hba);
    return err;
}

/* ufshcd_async_scan() 주요 단계 */
static void ufshcd_async_scan(void *data, async_cookie_t cookie)
{
    struct ufs_hba *hba = data;

    /* 1. HCE 활성화: HCE 레지스터에 1 기록 */
    ufshcd_hba_enable(hba);

    /* 2. 링크 스타트업: UniPro 링크 초기화 (PWM-G1에서 시작) */
    ufshcd_link_startup(hba);

    /* 3. NOP OUT/IN 교환으로 링크 상태 확인 */
    ufshcd_verify_dev_init(hba);

    /* 4. Device Descriptor 읽기 → 디바이스 정보 파싱 */
    ufshcd_probe_hba(hba, false);
    /* → bNumberLU, bUFSFeaturesSupport, wManufacturerID 등 */

    /* 5. 최고 HS-Gear로 전환 */
    ufshcd_config_pwr_mode(hba, &hba->max_pwr_info.info);
    /* → vops->pwr_change_notify() → DME_SET(PA_PWRMODE) */

    /* 6. SCSI 호스트 스캔: LU 탐지 → /dev/sdX 생성 */
    scsi_scan_host(hba->host);
}

I/O 경로 상세

일반 I/O 경로의 핵심 함수 호출 순서를 추적합니다.

/* ===== I/O 발행 경로 ===== */

/* 1. SCSI mid-layer가 ufshcd_queuecommand() 호출 */
static int ufshcd_queuecommand(struct Scsi_Host *host,
                                struct scsi_cmnd *cmd)
{
    struct ufs_hba *hba = shost_priv(host);
    int tag = scsi_cmd_to_rq(cmd)->tag;
    struct ufshcd_lrb *lrbp = &hba->lrb[tag];

    /* 히버네이트 상태면 resume 먼저 */
    ufshcd_hold(hba);

    /* LRB 설정 */
    lrbp->cmd = cmd;
    lrbp->task_tag = tag;
    lrbp->lun = ufshcd_scsi_to_upiu_lun(cmd->device->lun);

    /* UTRD 기본 필드 설정 */
    ufshcd_prepare_lrbp_crypto(cmd, lrbp);  /* 인라인 암호화 */
    lrbp->req_abort_skip = false;

    /* UPIU + PRDT 구성 */
    ufshcd_comp_scsi_upiu(hba, lrbp);
    /* → Command UPIU 헤더, CDB, PRDT scatter-gather 설정 */

    /* 2. Doorbell 링으로 HW에 전송 */
    ufshcd_send_command(hba, tag);
    return 0;
}

/* ===== I/O 완료 경로 ===== */

/* 3. 인터럽트 핸들러 */
static irqreturn_t ufshcd_intr(int irq, void *__hba)
{
    u32 intr_status = ufshcd_readl(hba, REG_INTERRUPT_STATUS);

    /* Transfer Request 완료 인터럽트 */
    if (intr_status & UTP_TRANSFER_REQ_COMPL) {
        u32 completed = ~ufshcd_readl(hba, REG_UTP_TRANSFER_REQ_DOOR_BELL)
                        & hba->outstanding_reqs;
        ufshcd_transfer_req_compl(hba, completed);
    }

    /* 에러 인터럽트 */
    if (intr_status & UFSHCD_ERROR_MASK)
        ufshcd_check_errors(hba, intr_status);

    return IRQ_HANDLED;
}

/* 4. 개별 요청 완료 처리 */
static void ufshcd_transfer_req_compl(struct ufs_hba *hba,
                                       unsigned long completed_reqs)
{
    int tag;

    for_each_set_bit(tag, &completed_reqs, hba->nutrs) {
        struct ufshcd_lrb *lrbp = &hba->lrb[tag];
        struct scsi_cmnd *cmd = lrbp->cmd;

        /* UTRD의 OCS(Overall Command Status) 확인 */
        int ocs = le32_to_cpu(lrbp->utr_descriptor_ptr->header.dword_0)
                  & OCS_MASK;

        if (ocs == OCS_SUCCESS) {
            /* Response UPIU에서 SCSI Status 추출 */
            int result = ufshcd_transfer_rsp_status(hba, lrbp);
            cmd->result = result;
        } else {
            /* OCS 에러 → 에러 핸들러로 위임 */
            cmd->result = DID_ERROR << 16;
        }

        scsi_done(cmd);   /* SCSI 레이어에 완료 통보 */
        hba->outstanding_reqs &= ~(1UL << tag);
    }
}

/* 에러 핸들러 개요 */
static void ufshcd_err_handler(struct work_struct *work)
{
    struct ufs_hba *hba = container_of(work, struct ufs_hba, eh_work);

    /* 1단계: 개별 명령 Abort */
    for_each_set_bit(tag, &hba->outstanding_reqs, hba->nutrs) {
        err = ufshcd_try_to_abort_task(hba, tag);
        if (err) goto reset_lu;
    }
    return;

reset_lu:
    /* 2단계: LU 리셋 (Task Management UPIU) */
    err = ufshcd_eh_device_reset_handler(/* ... */);
    if (err) goto reset_host;
    return;

reset_host:
    /* 3단계: 호스트 전체 리셋 */
    ufshcd_reset_and_restore(hba);
    /* → HCE disable → HCE enable → link startup → restore */
}

# ufshcd 디바이스 트리 바인딩 예시 (Qualcomm SM8550)
ufs_mem_hc: ufshc@1d84000 {
    compatible = "qcom,sm8550-ufshc", "qcom,ufshc", "jedec,ufs-2.0";
    reg = <0x01d84000 0x3000>,       /* UFSHCI MMIO */
          <0x01d90000 0x8000>;        /* UFS PHY */
    reg-names = "std", "ice";

    interrupts = <GIC_SPI 265 IRQ_TYPE_LEVEL_HIGH>;

    clocks = <&gcc GCC_UFS_PHY_AXI_CLK>,
             <&gcc GCC_UFS_PHY_ICE_CORE_CLK>,
             <&gcc GCC_UFS_PHY_UNIPRO_CORE_CLK>,
             <&rpmhcc RPMH_CXO_CLK>;
    clock-names = "core_clk", "ice_core_clk",
                  "unipro_core_clk", "ref_clk";

    freq-table-hz = <75000000 300000000>,   /* core_clk */
                    <75000000 300000000>,   /* ice_core_clk */
                    <75000000 300000000>,   /* unipro_core_clk */
                    <75000000 75000000>;    /* ref_clk */

    vcc-supply = <&vreg_l17b_2p5>;
    vccq-supply = <&vreg_l6b_1p2>;
    vcc-max-microamp = <800000>;
    vccq-max-microamp = <900000>;

    power-domains = <&gcc GCC_UFS_PHY_GDSC>;

    resets = <&gcc GCC_UFS_PHY_BCR>;
    reset-names = "rst";

    phys = <&ufs_mem_phy>;
    phy-names = "ufsphy";

    lanes-per-direction = <2>;  /* 2-Lane 구성 */

    status = "okay";
};

커널 소스 분석 — drivers/ufs/ 구조

UFS 호스트 컨트롤러 드라이버의 핵심은 drivers/ufs/ 디렉터리에 위치합니다. Linux 6.x 기준으로 이 디렉터리는 코어 드라이버, 플랫폼별 글루(glue) 드라이버, 그리고 보조 기능 모듈로 구성됩니다. 전체 구조를 파악하면 UFS 스택의 동작 원리를 소스 레벨에서 이해할 수 있습니다.

소스 파일 맵

핵심 함수 호출 체인

UFS 드라이버의 전체 생명주기를 이해하려면 주요 함수들의 호출 관계를 파악해야 합니다. 아래는 드라이버 초기화부터 I/O 처리까지의 핵심 콜 체인입니다.

/* === 드라이버 초기화 콜 체인 === */
ufshcd_pltfrm_init()            /* 플랫폼 드라이버 진입점 */
  └─ ufshcd_alloc_host()        /* Scsi_Host + ufs_hba 할당 */
  └─ ufshcd_init()              /* 코어 초기화 */
       ├─ ufshcd_hba_init()     /* HBA 하드웨어 초기화 */
       ├─ ufshcd_host_reset_and_restore()
       ├─ scsi_add_host()       /* SCSI 미드 레이어 등록 */
       └─ async_schedule(ufshcd_async_scan, hba)
            └─ ufshcd_probe_hba()   /* 디바이스 탐색 및 설정 */
                 ├─ ufshcd_link_startup()    /* UniPro 링크 수립 */
                 ├─ ufshcd_verify_dev_init()
                 ├─ ufshcd_complete_dev_init()
                 ├─ ufshcd_device_params_init()
                 ├─ ufs_get_device_desc()   /* Device Descriptor 읽기 */
                 ├─ ufshcd_tune_unipro_params()
                 └─ scsi_scan_host()   /* LU 스캔 → /dev/sdX 생성 */

ufshcd_probe_hba() 상세 흐름

ufshcd_probe_hba()는 UFS 디바이스 탐색과 초기 설정의 핵심입니다. 이 함수는 비동기 스캔 콜백으로 호출되며, 링크 수립부터 LU(Logical Unit) 등록까지 전 과정을 담당합니다.

/* drivers/ufs/core/ufshcd.c — ufshcd_probe_hba() 핵심 흐름 */
static int ufshcd_probe_hba(struct ufs_hba *hba, bool init_dev_params)
{
    int ret;

    /* 1단계: UniPro 링크 수립 */
    ret = ufshcd_link_startup(hba);
    if (ret)
        goto out;

    /* 2단계: 디바이스 초기화 확인 */
    ret = ufshcd_verify_dev_init(hba);
    if (ret)
        goto out;

    /* 3단계: UFS 디바이스 파라미터 초기화 */
    if (init_dev_params) {
        ret = ufshcd_device_params_init(hba);
        if (ret)
            goto out;
    }

    /* 4단계: UniPro 파라미터 튜닝 (Gear, Lane, Rate) */
    ufshcd_tune_unipro_params(hba);

    /* 5단계: UFS Power Mode 변경 (HS-G4 등) */
    ret = ufshcd_config_pwr_mode(hba, &hba->max_pwr_info.info);
    if (ret)
        goto out;

    /* 6단계: Write Booster 초기화 */
    ufshcd_wb_config(hba);

    /* 7단계: SCSI 호스트 스캔 → /dev/sdX 생성 */
    if (hba->scsi_host_added)
        scsi_scan_host(hba->host);

    ufshcd_set_ufs_dev_active(hba);
out:
    return ret;
}

에러 핸들링: ufshcd_err_handler()

UFS 에러 핸들링은 전용 워크 큐(eh_work)를 통해 비동기적으로 처리됩니다. 인터럽트 컨텍스트에서 에러가 감지되면 워크를 스케줄하고, 별도 스레드에서 복구를 수행합니다. 이 구조는 에러 복구 중에도 시스템이 응답성을 유지할 수 있게 합니다.

/* 에러 핸들러 워크 — ufshcd_err_handler() 주요 단계 */
static void ufshcd_err_handler(struct work_struct *work)
{
    struct ufs_hba *hba = container_of(work, struct ufs_hba, eh_work);

    /* 1. 미완료 태스크 정리 */
    ufshcd_clear_pending_tasks(hba);

    /* 2. 에러 유형별 분기 */
    if (hba->saved_err & UIC_ERROR) {
        /* UniPro 에러 → 링크 복구 시도 */
        ufshcd_update_evt_hist(hba, UFS_EVT_LINK_STARTUP_FAIL, 0);
        ret = ufshcd_uic_hibern8_exit(hba);
    }

    if (hba->saved_err & UFSHCD_UIC_DL_TCx_REPLAY_ERROR) {
        /* Data Link 에러 → 호스트 리셋 */
        ret = ufshcd_host_reset_and_restore(hba);
    }

    if (hba->saved_err & INT_FATAL_ERRORS) {
        /* Fatal 에러 → 전체 리셋 */
        ret = ufshcd_reset_and_restore(hba);
    }

    /* 3. 복구 완료 후 I/O 재개 */
    ufshcd_recover_pm_error(hba);
    ufshcd_release(hba);
}

주요 구조체 관계

플랫폼별 드라이버 — Platform-Specific Glue Drivers

UFS 코어 드라이버(ufshcd.c)는 하드웨어 독립적인 로직을 제공하고, 각 SoC 벤더는 ufs_hba_variant_ops(통칭 vops) 콜백을 구현하여 플랫폼 고유의 PHY 초기화, 클럭 설정, 암호화 엔진 등을 처리합니다. 이 분리 구조 덕분에 새 플랫폼 지원을 추가할 때 코어 드라이버 수정 없이 글루 드라이버만 작성하면 됩니다.

플랫폼 드라이버 비교

vops 콜백 구현 예시

/* Qualcomm UFS vops — ufs-qcom.c */
static const struct ufs_hba_variant_ops ufs_hba_qcom_vops = {
    .name                   = "qcom",
    .init                   = ufs_qcom_init,
    .exit                   = ufs_qcom_exit,
    .set_dma_mask           = ufs_qcom_set_dma_mask,
    .hce_enable_notify      = ufs_qcom_hce_enable_notify,
    .link_startup_notify    = ufs_qcom_link_startup_notify,
    .pwr_change_notify      = ufs_qcom_pwr_change_notify,
    .apply_dev_quirks       = ufs_qcom_apply_dev_quirks,
    .suspend                = ufs_qcom_suspend,
    .resume                 = ufs_qcom_resume,
    .dbg_register_dump      = ufs_qcom_dump_dbg_regs,
    .device_reset           = ufs_qcom_device_reset,
    .config_scaling_param   = ufs_qcom_config_scaling_param,
    .program_key            = ufs_qcom_ice_program_key,  /* ICE 암호화 */
    .event_notify           = ufs_qcom_event_notify,
    .mcq_config_resource    = ufs_qcom_mcq_config_resource,
};

/* Samsung Exynos UFS vops — ufs-exynos.c */
static const struct ufs_hba_variant_ops ufs_hba_exynos_ops = {
    .name                   = "exynos",
    .init                   = exynos_ufs_init,
    .exit                   = exynos_ufs_exit,
    .hce_enable_notify      = exynos_ufs_hce_enable_notify,
    .link_startup_notify    = exynos_ufs_link_startup_notify,
    .pwr_change_notify      = exynos_ufs_pwr_change_notify,
    .suspend                = exynos_ufs_suspend,
    .resume                 = exynos_ufs_resume,
    .program_key            = exynos_ufs_program_key,    /* FMP 암호화 */
};

새 플랫폼 드라이버 작성 스켈레톤

/* drivers/ufs/host/ufs-myplatform.c — 새 플랫폼 드라이버 스켈레톤 */
#include <ufs/ufshcd.h>
#include <ufs/ufshcd-pltfrm.h>
#include <ufs/unipro.h>

struct ufs_myplatform_host {
    struct ufs_hba *hba;
    void __iomem *phy_base;
    struct clk *ref_clk;
    struct regulator *vcc_supply;
    /* 플랫폼 고유 필드 */
};

static int ufs_myplatform_init(struct ufs_hba *hba)
{
    struct ufs_myplatform_host *host;
    struct device *dev = hba->dev;

    host = devm_kzalloc(dev, sizeof(*host), GFP_KERNEL);
    if (!host)
        return -ENOMEM;

    host->hba = hba;
    ufshcd_set_variant(hba, host);

    /* PHY 초기화 */
    host->phy_base = devm_platform_ioremap_resource_byname(
        to_platform_device(dev), "phy");
    if (IS_ERR(host->phy_base))
        return PTR_ERR(host->phy_base);

    /* 클럭, 레귤레이터 설정 */
    host->ref_clk = devm_clk_get(dev, "ref_clk");
    clk_prepare_enable(host->ref_clk);

    /* UFS Host Controller 특화 초기화 */
    hba->caps |= UFSHCD_CAP_CLK_GATING |
                  UFSHCD_CAP_HIBERN8_WITH_CLK_GATING;

    return 0;
}

static void ufs_myplatform_exit(struct ufs_hba *hba)
{
    struct ufs_myplatform_host *host = ufshcd_get_variant(hba);
    clk_disable_unprepare(host->ref_clk);
}

static int ufs_myplatform_link_startup_notify(
    struct ufs_hba *hba, enum ufs_notify_change_status status)
{
    if (status == PRE_CHANGE) {
        /* UniPro 파라미터 사전 설정 */
        ufshcd_dme_set(hba, UIC_ARG_MIB(PA_LOCAL_TX_LCC_ENABLE), 0);
    }
    return 0;
}

static const struct ufs_hba_variant_ops ufs_myplatform_vops = {
    .name                = "myplatform",
    .init                = ufs_myplatform_init,
    .exit                = ufs_myplatform_exit,
    .link_startup_notify = ufs_myplatform_link_startup_notify,
};

static const struct of_device_id ufs_myplatform_of_match[] = {
    { .compatible = "myvendor,my-ufshc", .data = &ufs_myplatform_vops },
    { },
};
MODULE_DEVICE_TABLE(of, ufs_myplatform_of_match);

static int ufs_myplatform_probe(struct platform_device *pdev)
{
    const struct ufs_hba_variant_ops *vops;

    vops = of_device_get_match_data(&pdev->dev);
    return ufshcd_pltfrm_init(pdev, vops);
}

static void ufs_myplatform_remove(struct platform_device *pdev)
{
    ufshcd_pltfrm_remove(pdev);
}

static struct platform_driver ufs_myplatform_driver = {
    .probe  = ufs_myplatform_probe,
    .remove = ufs_myplatform_remove,
    .driver = {
        .name = "ufs-myplatform",
        .of_match_table = ufs_myplatform_of_match,
        .pm = &ufshcd_of_pm_ops,
    },
};
module_platform_driver(ufs_myplatform_driver);

Kconfig 설정

# UFS 플랫폼 드라이버 Kconfig 예시
CONFIG_SCSI_UFS_QCOM=m          # Qualcomm UFS 호스트
CONFIG_SCSI_UFS_EXYNOS=m        # Samsung Exynos UFS 호스트
CONFIG_SCSI_UFS_MEDIATEK=m      # MediaTek UFS 호스트
CONFIG_SCSI_UFS_HISI=m          # HiSilicon UFS 호스트
CONFIG_SCSI_UFS_RENESAS=m       # Renesas UFS 호스트
CONFIG_SCSI_UFSHCD_PCI=m        # PCI 기반 UFS 호스트
CONFIG_SCSI_UFS_DWC_TC_PCI=m    # Synopsys DesignWare PCI

SCSI 통합 및 블록 레이어 연동

UFS는 SCSI 프로토콜 위에 구축되어 있으므로, Linux 커널에서 UFS 디바이스는 SCSI 서브시스템을 통해 관리됩니다. 애플리케이션의 I/O 요청이 VFS → Block Layer(blk-mq) → SCSI mid-layer → UFS HCD → UFSHCI → M-PHY를 거쳐 UFS 디바이스에 도달하는 전체 경로를 이해하는 것이 UFS 성능 최적화와 디버깅의 핵심입니다.

scsi_host_template 정의

UFS 드라이버는 struct scsi_host_template을 통해 SCSI 미드 레이어에 등록됩니다. 이 템플릿은 I/O 처리(queuecommand)와 에러 복구(eh_*_handler) 콜백을 정의합니다.

/* drivers/ufs/core/ufshcd.c — SCSI host template */
static const struct scsi_host_template ufshcd_driver_template = {
    .module                 = THIS_MODULE,
    .name                   = UFSHCD,
    .proc_name              = UFSHCD,
    .map_queues             = ufshcd_map_queues,
    .queuecommand           = ufshcd_queuecommand,
    .mq_poll                = ufshcd_poll,
    .slave_alloc            = ufshcd_slave_alloc,
    .slave_configure        = ufshcd_slave_configure,
    .slave_destroy          = ufshcd_slave_destroy,
    .change_queue_depth     = ufshcd_change_queue_depth,
    .eh_abort_handler       = ufshcd_abort,
    .eh_device_reset_handler = ufshcd_eh_device_reset_handler,
    .eh_host_reset_handler  = ufshcd_eh_host_reset_handler,
    .this_id                = -1,
    .sg_tablesize           = SG_ALL,
    .cmd_per_lun            = UFSHCD_CMD_PER_LUN,
    .can_queue              = UFSHCD_CAN_QUEUE,
    .max_segment_size       = PRDT_DATA_BYTE_COUNT_MAX,
    .max_host_blocked       = 1,
    .track_queue_depth      = 1,
    .skip_settle_delay      = 1,
    .sdev_groups            = ufshcd_driver_groups,
};

queuecommand — I/O 요청 처리

/* ufshcd_queuecommand() — blk-mq → SCSI → UFS 진입점 */
static int ufshcd_queuecommand(struct Scsi_Host *host,
                               struct scsi_cmnd *cmd)
{
    struct ufs_hba *hba = shost_priv(host);
    int tag = scsi_cmd_to_rq(cmd)->tag;
    struct ufshcd_lrb *lrbp = &hba->lrb[tag];

    /* 1. LRB(Local Reference Block) 설정 */
    lrbp->cmd = cmd;
    lrbp->task_tag = tag;
    lrbp->lun = ufshcd_scsi_to_upiu_lun(cmd->device->lun);

    /* 2. UPIU 구성 (Command UPIU 패킹) */
    ufshcd_compose_devman_upiu(hba, lrbp);  /* 또는 ufshcd_compose_scsi_cmd() */

    /* 3. UTRD(Transfer Request Descriptor) 설정 */
    ufshcd_prepare_utp_scsi_cmd_upiu(lrbp, cmd->sc_data_direction);

    /* 4. Crypto 설정 (인라인 암호화 사용 시) */
    ufshcd_prepare_req_desc_hdr(lrbp, &lrbp->tr_type, UTP_CMD_TYPE_SCSI);

    /* 5. Doorbell Ring — HW에 전송 요청 */
    ufshcd_send_command(hba, tag, hba->nutrs);

    return 0;
}

/dev/sdX 디바이스 생성 흐름

Well-Known LU (W-LU)

UFS 스펙은 일반 데이터 LU 외에 특수 목적의 Well-Known LU를 정의합니다. 이 W-LU들은 SCSI generic(/dev/sgX) 디바이스로 접근 가능하며, 디바이스 관리, RPMB 접근, 부트 LU 등의 기능을 제공합니다.

MCQ — Multi-Circular Queue (UFS 4.0+)

MCQ(Multi-Circular Queue)는 UFS 4.0 스펙에서 도입된 새로운 큐 모델로, 기존의 Single Doorbell(SDB) 방식을 대체합니다. SDB에서는 모든 I/O 요청이 하나의 UTRL(UTP Transfer Request List)을 공유하고 단일 Doorbell 레지스터로 전송을 트리거했지만, MCQ는 NVMe와 유사한 Submission Queue(SQ)/Completion Queue(CQ) 쌍을 여러 개 생성하여 CPU별 독립적인 I/O 처리를 가능하게 합니다.

MCQ 레지스터 셋

MCQ 초기화 및 큐 생성

/* drivers/ufs/core/ufs-mcq.c — MCQ 초기화 핵심 */
int ufshcd_mcq_init(struct ufs_hba *hba)
{
    int ret, i;
    int num_queues;

    /* 1. MCQ 지원 여부 확인 */
    if (!(hba->mcq_capabilities & MASK_MCQ_SUPPORT))
        return -EOPNOTSUPP;

    /* 2. 큐 수 결정 (online CPU 수 기반) */
    num_queues = min_t(int, num_online_cpus(),
                       hba->mcq_capabilities & MCQ_MAX_QUEUES_MASK);

    /* 3. SQ/CQ 메모리 할당 (DMA coherent) */
    for (i = 0; i < num_queues; i++) {
        ret = ufshcd_mcq_sq_alloc(hba, i);
        if (ret)
            goto err;
        ret = ufshcd_mcq_cq_alloc(hba, i);
        if (ret)
            goto err;
    }

    /* 4. MCQ 레지스터 설정 */
    ufshcd_mcq_config_nr_queues(hba);

    /* 5. SQ/CQ 활성화 */
    for (i = 0; i < num_queues; i++) {
        ufshcd_mcq_sq_start(hba, &hba->mcq_sq[i]);
        ufshcd_mcq_cq_start(hba, &hba->mcq_cq[i]);
    }

    return 0;
err:
    ufshcd_mcq_release(hba);
    return ret;
}

SQ/CQ 시작/정지 제어

/* SQ 시작 — Tail Doorbell 초기화 */
void ufshcd_mcq_sq_start(struct ufs_hba *hba, struct ufs_hw_queue *hwq)
{
    u32 val;

    /* SQATTR: 큐 크기, 활성화 비트 설정 */
    val = FIELD_PREP(SQ_SIZE_MASK, hwq->max_entries - 1) | SQ_EN;
    writel(val, hba->mmio_base + hwq->sq_attr_offset);

    /* SQ Base Address 설정 */
    writel(lower_32_bits(hwq->sq_dma), hba->mmio_base + hwq->sq_lba_offset);
    writel(upper_32_bits(hwq->sq_dma), hba->mmio_base + hwq->sq_uba_offset);

    /* Tail Pointer 초기화 */
    hwq->sq_tail = 0;
    writel(0, hwq->sq_tail_db);
}

/* SQ 정지 — 에러 복구 또는 shutdown 시 */
void ufshcd_mcq_sq_stop(struct ufs_hba *hba, struct ufs_hw_queue *hwq)
{
    u32 val;

    val = readl(hba->mmio_base + hwq->sq_attr_offset);
    val &= ~SQ_EN;  /* 비활성화 */
    writel(val, hba->mmio_base + hwq->sq_attr_offset);

    /* SQ가 완전히 정지할 때까지 대기 */
    ufshcd_mcq_poll_sq_stopped(hba, hwq);
}

Write Booster — SLC 캐시 기반 쓰기 가속

Write Booster(WB)는 UFS 3.1 스펙에서 도입된 쓰기 성능 향상 기능입니다. UFS 디바이스 내부의 SLC(Single Level Cell) 모드 영역을 캐시로 활용하여 TLC/QLC NAND의 느린 쓰기 속도를 보상합니다. 호스트 드라이버는 sysfs를 통해 WB를 활성화/비활성화하고, 버퍼 플러시를 제어할 수 있습니다.

Dedicated Buffer vs Shared Buffer

Write Booster sysfs 인터페이스

WB 활성화/비활성화 코드

/* drivers/ufs/core/ufshcd.c — Write Booster 토글 */
int ufshcd_wb_toggle(struct ufs_hba *hba, bool enable)
{
    enum attr_idn attr;
    int ret;

    if (!ufshcd_is_wb_allowed(hba))
        return 0;

    /* fWriteBoosterEn 플래그 설정/해제 */
    if (enable)
        attr = QUERY_ATTR_IDN_WB_EN;
    else
        attr = QUERY_ATTR_IDN_WB_EN;

    ret = ufshcd_query_attr_retry(hba, UPIU_QUERY_OPCODE_WRITE_ATTR,
                                  attr, 0, 0, &enable);
    if (ret) {
        dev_err(hba->dev, "%s: Write Booster %s failed: %d\n",
                __func__, enable ? "enable" : "disable", ret);
        return ret;
    }

    hba->dev_info.wb_enabled = enable;
    dev_info(hba->dev, "Write Booster %s\n",
             enable ? "enabled" : "disabled");

    return 0;
}

/* WB 버퍼 플러시 트리거 */
static int ufshcd_wb_buf_flush_enable(struct ufs_hba *hba)
{
    int ret;
    u32 val = 1;

    /* fWriteBoosterBufferFlushEn 플래그 설정 */
    ret = ufshcd_query_attr_retry(hba, UPIU_QUERY_OPCODE_WRITE_ATTR,
                                  QUERY_ATTR_IDN_WB_BUFF_FLUSH_EN,
                                  0, 0, &val);
    return ret;
}

sysfs 읽기/쓰기 구현

/* drivers/ufs/core/ufs-sysfs.c — wb_on sysfs */
static ssize_t wb_on_show(struct device *dev,
                          struct device_attribute *attr, char *buf)
{
    struct ufs_hba *hba = dev_get_drvdata(dev);
    return sysfs_emit(buf, "%d\n", hba->dev_info.wb_enabled);
}

static ssize_t wb_on_store(struct device *dev,
                           struct device_attribute *attr,
                           const char *buf, size_t count)
{
    struct ufs_hba *hba = dev_get_drvdata(dev);
    bool enable;
    int ret;

    if (kstrtobool(buf, &enable))
        return -EINVAL;

    /* Runtime PM 활성 상태에서만 설정 가능 */
    ufshcd_rpm_get_sync(hba);
    ret = ufshcd_wb_toggle(hba, enable);
    ufshcd_rpm_put_sync(hba);

    return ret ? ret : count;
}
static DEVICE_ATTR_RW(wb_on);

성능 영향 분석

# Write Booster ON/OFF 성능 비교 (fio 예시)
# WB OFF 상태에서 순차 쓰기 측정
echo 0 > /sys/bus/platform/drivers/ufshcd/*/wb_on
fio --name=seq_write --ioengine=libaio --direct=1 --bs=128k \
    --rw=write --numjobs=1 --size=1G --filename=/dev/sda

# WB ON 상태에서 동일 측정
echo 1 > /sys/bus/platform/drivers/ufshcd/*/wb_on
fio --name=seq_write --ioengine=libaio --direct=1 --bs=128k \
    --rw=write --numjobs=1 --size=1G --filename=/dev/sda

# WB 버퍼 상태 모니터링
cat /sys/bus/platform/drivers/ufshcd/*/wb_avail_buf
cat /sys/bus/platform/drivers/ufshcd/*/wb_cur_buf
cat /sys/bus/platform/drivers/ufshcd/*/wb_buf_life_time_est

HPB — Host Performance Booster

HPB(Host Performance Booster)는 UFS 디바이스의 L2P(Logical to Physical) 매핑 테이블 일부를 호스트 메모리(DRAM)에 캐시하여 읽기 성능을 향상시키는 기능입니다. 일반적으로 UFS 디바이스는 읽기 요청 시 내부 SRAM에 캐시된 L2P 테이블을 참조하는데, 테이블 미스가 발생하면 NAND에서 L2P를 읽어야 하므로 수백 마이크로초의 지연이 추가됩니다. HPB는 호스트가 L2P 정보를 미리 보유하여 이 NAND 접근을 건너뛸 수 있게 합니다.

Region과 Subregion 개념

HPB는 UFS 디바이스의 논리적 주소 공간을 Region과 Subregion으로 나누어 관리합니다. Region은 L2P 캐싱의 기본 관리 단위이고, Subregion은 실제 L2P 엔트리를 전송하는 최소 단위입니다. 호스트는 디바이스로부터 HPB 업데이트 알림을 받아 L2P 캐시를 갱신합니다.

HPB sysfs 인터페이스

HPB READ(16) 커맨드 구성

/* drivers/ufs/core/ufshpb.c — HPB READ(16) 커맨드 준비 */
void ufshpb_prep(struct ufs_hba *hba, struct ufshcd_lrb *lrbp)
{
    struct ufshpb_lu *hpb_lu;
    struct ufshpb_region *rgn;
    struct ufshpb_subregion *srgn;
    u64 ppn;
    unsigned long lpn;
    int transfer_len;

    if (!ufshpb_is_enabled(hba))
        return;

    hpb_lu = ufshpb_get_lu(hba, lrbp->lun);
    if (!hpb_lu)
        return;

    /* 1. LBA → LPN(Logical Page Number) 변환 */
    lpn = ufshpb_get_lpn(lrbp);
    transfer_len = ufshpb_get_len(lrbp);

    /* 2. Region/Subregion 인덱스 계산 */
    rgn = ufshpb_get_region(hpb_lu, lpn);
    srgn = ufshpb_get_subregion(rgn, lpn);

    /* 3. L2P 캐시에서 PPN 조회 */
    if (!ufshpb_get_ppn(srgn, lpn, &ppn)) {
        /* HPB 미스 — 일반 READ(10) 사용 */
        hpb_lu->stats.miss_cnt++;
        return;
    }

    /* 4. HPB READ(16) CDB 구성 */
    hpb_lu->stats.hit_cnt++;
    ufshpb_set_hpb_read_to_upiu(lrbp, lpn, ppn, transfer_len);
}

/* HPB READ(16) CDB 설정 */
static void ufshpb_set_hpb_read_to_upiu(
    struct ufshcd_lrb *lrbp, u64 lpn, u64 ppn, int len)
{
    unsigned char *cdb = lrbp->cmd->cmnd;

    /* Opcode: 0x94 (HPB READ) */
    cdb[0] = HPB_READ_16;
    /* LBA (Big-Endian) */
    put_unaligned_be64(lpn, &cdb[2]);
    /* Transfer Length */
    put_unaligned_be32(len, &cdb[10]);
    /* HPB Entry (PPN) → UPIU에 별도 필드로 전달 */
    lrbp->hpb_entry = ppn;
}

HPB 버전 차이

/* HPB 1.0 (Device-initiated) vs HPB 2.0 (Host-initiated) */

/*
 * HPB 1.0: 디바이스가 주도적으로 Region 활성화/비활성화 결정
 *   - DEV_HPB_RECOMMENDATION UPIU: 디바이스 → 호스트 (Region 추천)
 *   - 호스트는 추천에 따라 READ BUFFER로 L2P 다운로드
 */

/*
 * HPB 2.0: 호스트가 Region 활성화/비활성화를 결정
 *   - 호스트가 접근 패턴 분석 → 자주 접근하는 Region 활성화
 *   - 호스트 주도로 READ BUFFER 발행하여 L2P 캐시
 *   - 더 높은 히트율, 호스트 메모리 관리 최적화 가능
 */
enum ufshpb_mode {
    HPB_MODE_OFF            = 0,
    HPB_MODE_HOST_CONTROL   = 1,  /* HPB 2.0 */
    HPB_MODE_DEVICE_CONTROL = 2,  /* HPB 1.0 */
};

인라인 암호화 — Inline Encryption Framework

UFS 인라인 암호화(Inline Encryption)는 호스트 컨트롤러에 내장된 암호화 엔진(Crypto Engine 또는 ICE)을 활용하여 스토리지 I/O 경로에서 직접 데이터를 암복호화하는 기능입니다. CPU가 소프트웨어적으로 암복호화를 수행하는 대신, 하드웨어가 DMA 전송 과정에서 투명하게 처리하므로 성능 오버헤드가 거의 없습니다. Linux 커널의 blk-crypto 프레임워크와 통합되어 fscrypt, dm-crypt 등에서 활용됩니다.

지원 알고리즘

blk-crypto 프레임워크 연동

/* drivers/ufs/core/ufshcd-crypto.c — crypto profile 초기화 */
int ufshcd_hba_init_crypto_capabilities(struct ufs_hba *hba)
{
    struct blk_crypto_profile *profile = &hba->crypto_profile;
    int cap_idx, err;
    unsigned int num_keyslots;

    /* 1. UFSHCI Crypto Capability 레지스터 읽기 */
    hba->crypto_capabilities.reg_val =
        cpu_to_le32(ufshcd_readl(hba, REG_UFS_CCAP));

    num_keyslots = hba->crypto_capabilities.config_count + 1;

    /* 2. blk_crypto_profile 초기화 */
    err = devm_blk_crypto_profile_init(hba->dev, profile, num_keyslots);
    if (err)
        return err;

    profile->ll_ops = ufshcd_crypto_ops;
    profile->max_dun_bytes_supported = 8;  /* 64-bit DUN */

    /* 3. 지원 알고리즘 등록 */
    for (cap_idx = 0; cap_idx < hba->crypto_capabilities.num_crypto_cap; cap_idx++) {
        enum blk_crypto_mode_num blk_mode;
        union ufs_crypto_cap_entry cap;

        cap = hba->crypto_cap_array[cap_idx];

        switch (cap.algorithm_id) {
        case UFS_CRYPTO_ALG_AES_XTS:
            blk_mode = BLK_ENCRYPTION_MODE_AES_256_XTS;
            break;
        default:
            continue;
        }

        profile->modes_supported[blk_mode] |=
            cap.sdus_mask * 512;  /* 지원 데이터 유닛 크기 */
    }

    return 0;
}

UTRD Crypto 필드 설정

/* UTRD에 Crypto 정보 삽입 */
static void ufshcd_prepare_req_desc_hdr_crypto(
    struct ufshcd_lrb *lrbp, struct utp_transfer_req_desc *req_desc)
{
    struct bio_crypt_ctx *bc;
    struct request *rq = scsi_cmd_to_rq(lrbp->cmd);

    if (!rq || !rq->crypt_ctx)
        return;

    bc = rq->crypt_ctx;

    /* CCI (Crypto Configuration Index) — 키슬롯 번호 */
    req_desc->header.crypto_config_index =
        cpu_to_le16(bc->bc_keyslot);

    /* CE (Crypto Enable) 비트 설정 */
    req_desc->header.cci |= UTP_REQ_DESC_CRYPTO_ENABLE;

    /* DUN (Data Unit Number) — IV 생성에 사용 */
    req_desc->header.dunu = cpu_to_le32(
        upper_32_bits(bc->bc_dun[0]));
    req_desc->header.dunl = cpu_to_le32(
        lower_32_bits(bc->bc_dun[0]));
}

플랫폼별 Crypto 구현

/* Qualcomm ICE — ufs-qcom.c */
static int ufs_qcom_ice_program_key(struct ufs_hba *hba,
                                     const union ufs_crypto_cfg_entry *cfg,
                                     int slot)
{
    struct ufs_qcom_host *host = ufshcd_get_variant(hba);
    union {
        u8 bytes[AES_256_XTS_KEY_SIZE];
        u32 words[AES_256_XTS_KEY_SIZE / sizeof(u32)];
    } key;

    /* ICE 키 레지스터에 AES-256-XTS 키 프로그래밍 */
    memcpy(key.bytes, cfg->crypto_key, AES_256_XTS_KEY_SIZE);

    qcom_ice_program_key(host->ice, QCOM_ICE_CRYPTO_ALG_AES_XTS,
                         QCOM_ICE_CRYPTO_KEY_SIZE_256,
                         key.words, cfg->data_unit_size, slot);

    memzero_explicit(&key, sizeof(key));
    return 0;
}

/* Samsung FMP — ufs-exynos.c */
static int exynos_ufs_program_key(struct ufs_hba *hba,
                                   const union ufs_crypto_cfg_entry *cfg,
                                   int slot)
{
    /* FMP(Flash Memory Protector)는 UTRD의 PRDT 엔트리 내에
     * 암호화 키와 IV를 직접 삽입하는 방식을 사용 */
    struct exynos_ufs *ufs = ufshcd_get_variant(hba);
    return exynos_fmp_program_key(ufs->fmp, cfg, slot);
}

RPMB — Replay Protected Memory Block

RPMB(Replay Protected Memory Block)는 UFS 디바이스 내의 보안 스토리지 영역으로, HMAC-SHA256 인증과 단조 증가 Write Counter를 통해 데이터의 무결성과 재생 공격(Replay Attack) 방지를 보장합니다. RPMB는 Well-Known LU(W-LUN 0xC4)로 접근하며, 보안 부팅(Secure Boot) 인증 정보, 롤백 방지 카운터, 디바이스 키 저장 등에 사용됩니다.

RPMB 프레임 구조

RPMB 요청/응답 타입

RPMB SCSI 커맨드

/* RPMB 접근은 SECURITY PROTOCOL IN/OUT SCSI 커맨드를 사용 */

/* SECURITY PROTOCOL OUT — RPMB 요청 전송 */
/*
 * CDB (12 bytes):
 * [0] = 0xB5 (SECURITY PROTOCOL OUT)
 * [1] = 0xEC (Security Protocol: UFS)
 * [2-3] = 0x0001 (Security Protocol Specific: RPMB)
 * [4] = 0x00 (INC_512 = 0)
 * [5] = 0x00
 * [6-9] = Transfer Length
 * [10-11] = 0x00
 */

/* SECURITY PROTOCOL IN — RPMB 응답 수신 */
/*
 * CDB (12 bytes):
 * [0] = 0xA2 (SECURITY PROTOCOL IN)
 * [1] = 0xEC (Security Protocol: UFS)
 * [2-3] = 0x0001 (Security Protocol Specific: RPMB)
 * [4] = 0x00 (INC_512 = 0)
 * [5] = 0x00
 * [6-9] = Allocation Length
 * [10-11] = 0x00
 */

/* RPMB 인증 쓰기 시퀀스 */
static int ufs_rpmb_authenticated_write(struct ufs_hba *hba,
                                         u8 *data, u16 addr,
                                         u16 block_count, u8 *key)
{
    struct rpmb_frame frame;
    u8 mac[32];
    int ret;

    memset(&frame, 0, sizeof(frame));

    /* 1. Write Counter 읽기 */
    frame.req_resp_type = cpu_to_be16(0x0002);  /* Read Counter */
    ret = ufs_rpmb_security_out(hba, &frame, sizeof(frame));
    ret = ufs_rpmb_security_in(hba, &frame, sizeof(frame));

    /* 2. 쓰기 프레임 구성 */
    frame.req_resp_type = cpu_to_be16(0x0003);  /* Auth Write */
    frame.write_counter = frame.write_counter;   /* 응답에서 받은 값 */
    frame.address = cpu_to_be16(addr);
    frame.block_count = cpu_to_be16(block_count);
    memcpy(frame.data, data, block_count * 256);

    /* 3. HMAC-SHA256 계산 */
    hmac_sha256(key, 32, (u8 *)&frame.data,
                284,  /* data + nonce + counter + addr + count + type */
                mac);
    memcpy(frame.key_mac, mac, 32);

    /* 4. SECURITY PROTOCOL OUT 전송 */
    ret = ufs_rpmb_security_out(hba, &frame, sizeof(frame));

    /* 5. Result 확인 (SECURITY PROTOCOL IN) */
    frame.req_resp_type = cpu_to_be16(0x0005);  /* Result Read */
    ret = ufs_rpmb_security_out(hba, &frame, sizeof(frame));
    ret = ufs_rpmb_security_in(hba, &frame, sizeof(frame));

    if (be16_to_cpu(frame.result) != 0x0000)
        return -EIO;

    return 0;
}

ufs_bsg 인터페이스

/* drivers/ufs/core/ufs-bsg.c — BSG를 통한 RPMB 접근 */

/*
 * 사용자 공간에서 /dev/bsg/ufs-bsg0 또는 /dev/0:0:0:49476을 통해
 * RPMB 커맨드를 전송할 수 있습니다.
 *
 * W-LUN 0xC4는 SCSI LUN 49476 (0xC140)으로 매핑됩니다.
 * (UFS W-LUN → SCSI LUN 변환 규칙 적용)
 */

/* BSG RPMB 요청 처리 */
static int ufs_bsg_request(struct bsg_job *job)
{
    struct ufs_hba *hba = shost_priv(dev_to_shost(job->dev->parent));
    struct ufs_bsg_request *bsg_request = job->request;
    struct ufs_bsg_reply *bsg_reply = job->reply;
    int ret;

    switch (bsg_request->msgcode) {
    case UPIU_TRANSACTION_QUERY_REQ:
        ret = ufshcd_exec_raw_upiu_cmd(hba, ...);
        break;
    case UPIU_TRANSACTION_NOP_OUT:
        ret = ufshcd_exec_raw_upiu_cmd(hba, ...);
        break;
    default:
        ret = -ENOTSUPP;
    }

    bsg_reply->result = ret;
    job->reply_len = sizeof(*bsg_reply);
    bsg_job_done(job, ret, 0);
    return 0;
}

UFS RPMB v2 vs v3

사용자 공간에서 RPMB 접근

# ufs-utils를 사용한 RPMB 접근 예시

# 1. RPMB 키 프로그래밍 (주의: 최초 1회만 가능, 변경 불가!)
ufs-utils rpmb write-key /dev/bsg/ufs-bsg0 --key-file rpmb_key.bin

# 2. Write Counter 읽기
ufs-utils rpmb read-counter /dev/bsg/ufs-bsg0 --key-file rpmb_key.bin

# 3. 데이터 쓰기
ufs-utils rpmb write /dev/bsg/ufs-bsg0 --key-file rpmb_key.bin \
    --address 0 --data-file data.bin

# 4. 데이터 읽기
ufs-utils rpmb read /dev/bsg/ufs-bsg0 --key-file rpmb_key.bin \
    --address 0 --block-count 1 --out-file output.bin

# 5. RPMB 상태 확인
cat /sys/class/scsi_device/0:0:0:49476/device/model

전원 관리 (Power Management)

UFS 전원 관리는 모바일 디바이스의 배터리 수명에 직접적인 영향을 미치는 핵심 요소입니다. UFS 호스트 컨트롤러(ufshcd)는 Linux 커널의 Runtime PM 프레임워크와 통합되어, 유휴 시 자동으로 링크 상태를 전환하고 클럭을 게이팅하여 전력 소비를 최소화합니다.

전원 모드 비교

클럭 게이팅 (Clock Gating)

UFS 호스트 드라이버는 일정 시간 유휴 상태가 지속되면 자동으로 클럭을 차단합니다. ufshcd_gate_clk_work()는 gate_delay(기본 150ms)가 경과한 후 실행되어, 호스트 컨트롤러와 PHY 클럭을 순차적으로 게이팅합니다.

/* drivers/ufs/core/ufshcd.c — 클럭 게이팅 워크 */
static void ufshcd_gate_work(struct work_struct *work)
{
    struct ufs_hba *hba = container_of(work, struct ufs_hba,
                                       clk_gating.gate_work);
    unsigned long flags;

    spin_lock_irqsave(hba->host->host_lock, flags);

    /* 아직 활성 요청이 있으면 게이팅 취소 */
    if (hba->clk_gating.active_reqs ||
        hba->clk_gating.state == CLKS_ON) {
        spin_unlock_irqrestore(hba->host->host_lock, flags);
        return;
    }

    /* 클럭 상태 전이: REQ_CLKS_OFF → CLKS_OFF */
    hba->clk_gating.state = CLKS_OFF;
    spin_unlock_irqrestore(hba->host->host_lock, flags);

    /* 실제 클럭 비활성화 */
    ufshcd_setup_clocks(hba, false);
}

/* 클럭 언게이팅: I/O 요청 시 자동 호출 */
static void ufshcd_ungate_work(struct work_struct *work)
{
    struct ufs_hba *hba = container_of(work, struct ufs_hba,
                                       clk_gating.ungate_work);

    cancel_delayed_work_sync(&hba->clk_gating.gate_work);

    /* 클럭 재활성화 */
    ufshcd_setup_clocks(hba, true);

    /* Hibern8 상태였으면 exit 수행 */
    if (ufshcd_is_link_hibern8(hba))
        ufshcd_uic_hibern8_exit(hba);
}

Hibernate (H8) 진입/탈출

Hibernate(H8)는 UniPro 링크를 저전력 상태로 전환하는 UFS 고유 기능입니다. Auto-Hibernate8 기능을 사용하면 하드웨어가 유휴 타이머 만료 시 자동으로 H8에 진입하고, 새로운 UTRD/UTMRD 발행 시 자동으로 탈출합니다.

/* drivers/ufs/core/ufshcd.c — Hibernate8 진입 */
int ufshcd_uic_hibern8_enter(struct ufs_hba *hba)
{
    struct uic_command uic_cmd = {0};
    int ret;

    uic_cmd.command = UIC_CMD_DME_HIBER_ENTER;
    ret = ufshcd_uic_pwr_ctrl(hba, &uic_cmd);
    if (ret) {
        dev_err(hba->dev, "hibern8 enter failed: %d\n", ret);
        /* 에러 복구 시도 */
        ufshcd_update_evt_hist(hba, UFS_EVT_HIB_ERR, ret);
        return ret;
    }
    hba->ufs_stats.hibern8_enter_cnt++;
    return 0;
}

/* Auto-Hibernate8 설정 (UFSHCI 3.0+) */
void ufshcd_auto_hibern8_enable(struct ufs_hba *hba)
{
    u32 ahit;

    if (!ufshcd_is_auto_hibern8_supported(hba))
        return;

    /* 타이머 값 설정: scale(10us/100us/1ms/10ms) + timer_val */
    ahit = FIELD_PREP(UFSHCI_AHIBERN8_TIMER_MASK, hba->ahit) |
           FIELD_PREP(UFSHCI_AHIBERN8_SCALE_MASK, UFSHCI_AHIBERN8_1MS);

    ufshcd_writel(hba, ahit, REG_AUTO_HIBERNATE_IDLE_TIMER);
}

Runtime PM 통합

UFS 드라이버는 Linux Runtime PM과 완전히 통합됩니다. rpm_lvl과 spm_lvl sysfs 속성으로 Runtime Suspend와 System Suspend 시의 전원 레벨을 독립적으로 제어할 수 있습니다.

/* drivers/ufs/core/ufshcd.c — System Suspend/Resume */
int ufshcd_system_suspend(struct device *dev)
{
    struct ufs_hba *hba = dev_get_drvdata(dev);
    int ret;

    /* 이미 Runtime Suspended 상태면 추가 작업 불필요 */
    if (pm_runtime_suspended(hba->dev))
        return 0;

    ret = ufshcd_suspend(hba, UFS_SYSTEM_PM);
    if (ret)
        dev_err(hba->dev, "system suspend failed: %d\n", ret);
    return ret;
}

int ufshcd_system_resume(struct device *dev)
{
    struct ufs_hba *hba = dev_get_drvdata(dev);

    if (pm_runtime_suspended(hba->dev))
        return 0;

    return ufshcd_resume(hba, UFS_SYSTEM_PM);
}

/* 내부 suspend 함수 — rpm_lvl/spm_lvl에 따라 동작 결정 */
static int ufshcd_suspend(struct ufs_hba *hba, enum ufs_pm_op pm_op)
{
    enum ufs_pm_level pm_lvl;
    enum ufs_dev_pwr_mode req_dev_pwr_mode;
    enum uic_link_state req_link_state;

    pm_lvl = (pm_op == UFS_RUNTIME_PM) ?
             hba->rpm_lvl : hba->spm_lvl;

    req_dev_pwr_mode = ufs_get_pm_lvl_to_dev_pwr_mode(pm_lvl);
    req_link_state = ufs_get_pm_lvl_to_link_pwr_state(pm_lvl);

    /* BKOPS flush → SSU(PowerMode) → Hibern8/Off → Clock gate */
    if (req_dev_pwr_mode != hba->curr_dev_pwr_mode)
        ufshcd_set_dev_pwr_mode(hba, req_dev_pwr_mode);

    if (req_link_state == UIC_LINK_HIBERN8_STATE)
        ufshcd_uic_hibern8_enter(hba);

    ufshcd_setup_clocks(hba, false);
    return 0;
}

Gear Scaling (동적 기어 변경)

Gear scaling은 부하에 따라 UFS 링크 속도(Gear)를 동적으로 조절하는 기능입니다. 높은 I/O 부하 시 HS-G4로 올리고, 유휴 시 HS-G1으로 내려 전력을 절감합니다. devfreq 프레임워크와 통합되어 자동으로 동작합니다.

# Gear scaling 상태 확인
cat /sys/bus/platform/devices/*/clkscale_enable

# Gear scaling 비활성화 (디버깅/벤치마크 시)
echo 0 > /sys/bus/platform/devices/1d84000.ufshc/clkscale_enable

# 현재 링크 속도 확인
cat /sys/kernel/debug/ufshcd0/show_hba
# 출력 예: HS Gear: 4, Lanes: 2, Rate: B (HS-G4B 2-Lane)

디바이스 건강 모니터링 (Device Health Monitoring)

UFS 디바이스는 내장 건강 지표를 제공하여 수명 예측과 사전 장애 대응을 가능하게 합니다. bDeviceLifeTimeEstA/B와 bPreEOLInfo 속성은 디바이스 디스크립터를 통해 조회하며, 임계치를 초과하면 Exception Event를 통해 호스트에 알립니다.

수명 추정치 (Device Life Time Estimation)

UFS 디바이스는 두 가지 수명 추정 속성을 제공합니다. bDeviceLifeTimeEstA는 SLC 영역(Boot/RPMB 포함)의 수명을, bDeviceLifeTimeEstB는 MLC/TLC 사용자 데이터 영역의 수명을 나타냅니다.

Pre-EOL 정보 (bPreEOLInfo)

bPreEOLInfo는 디바이스의 예비 블록 상태를 세 단계로 간략화한 지표입니다. 이 값이 0x02(Warning) 이상이면 BKOPS 빈도 증가, 쓰기 앰플리피케이션 악화, 갑작스러운 성능 저하가 발생할 수 있습니다.

Exception Events

UFS 디바이스는 긴급 상황 시 Exception Event를 호스트에 통보합니다. 호스트 드라이버(ufshcd)는 이 이벤트를 인터럽트로 수신하고 적절한 대응 동작을 수행합니다.

/* drivers/ufs/core/ufshcd.c — Exception Event 처리 */
static void ufshcd_exception_event_handler(struct work_struct *work)
{
    struct ufs_hba *hba = container_of(work, struct ufs_hba,
                                       eeh_work);
    u32 status = 0;

    /* Exception Event Status 읽기 */
    ufshcd_query_attr(hba, UPIU_QUERY_OPCODE_READ_ATTR,
                      QUERY_ATTR_IDN_EE_STATUS, 0, 0, &status);

    /* Urgent BKOPS 필요 */
    if (status & MASK_EE_URGENT_BKOPS)
        ufshcd_bkops_exception_event_handler(hba);

    /* 동적 용량 부족 */
    if (status & MASK_EE_URGENT_TEMP)
        dev_warn(hba->dev, "UFS: device temperature warning!\n");

    /* Write Booster 버퍼 부족 */
    if (status & MASK_EE_WRITEBOOSTER_EVENT)
        ufshcd_wb_exception_event_handler(hba);
}

/* BKOPS (Background Operations) 관리 */
static int ufshcd_bkops_ctrl(struct ufs_hba *hba,
                             enum bkops_status status)
{
    int err;
    u32 curr_status = 0;

    err = ufshcd_query_attr(hba, UPIU_QUERY_OPCODE_READ_ATTR,
                            QUERY_ATTR_IDN_BKOPS_STATUS,
                            0, 0, &curr_status);
    if (err)
        return err;

    /*
     * BKOPS Status:
     *   0x00 = No operations needed
     *   0x01 = Non-critical (수행 권장)
     *   0x02 = Performance impacted (즉시 수행 필요)
     *   0x03 = Critical (즉시 수행, 커맨드 처리 불가 수준)
     */
    if (curr_status >= BKOPS_STATUS_PERF_IMPACT) {
        err = ufshcd_enable_auto_bkops(hba);
        dev_info(hba->dev, "BKOPS critical: status=%d, enabled auto\n",
                 curr_status);
    }
    return err;
}

건강 정보 읽기

# sysfs를 통한 건강 정보 읽기
cat /sys/bus/platform/devices/*/health_descriptor/life_time_estimation_a
cat /sys/bus/platform/devices/*/health_descriptor/life_time_estimation_b
cat /sys/bus/platform/devices/*/health_descriptor/eol_info

# ufs-utils를 사용한 건강 정보 조회
ufs-utils desc -a -p /dev/bsg/ufs-bsg0 -t health
# 출력 예:
#   bLength: 0x25
#   bDescriptorIDN: 0x09
#   bPreEOLInfo: 0x01
#   bDeviceLifeTimeEstA: 0x02
#   bDeviceLifeTimeEstB: 0x01

# Query UPIU로 직접 읽기 (bPreEOLInfo)
ufs-utils attr -a -p /dev/bsg/ufs-bsg0 -t 2 -i 0x02
# bPreEOLInfo at Health Descriptor offset 0x02

모니터링 스크립트

#!/bin/bash
# UFS 건강 모니터링 스크립트
# 주기적으로 실행하여 디바이스 상태를 추적

UFS_SYSFS="/sys/bus/platform/devices/1d84000.ufshc"
LOG="/var/log/ufs_health.log"
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')

# 건강 디스크립터 읽기
LIFE_A=$(cat "${UFS_SYSFS}/health_descriptor/life_time_estimation_a" 2>/dev/null)
LIFE_B=$(cat "${UFS_SYSFS}/health_descriptor/life_time_estimation_b" 2>/dev/null)
EOL=$(cat "${UFS_SYSFS}/health_descriptor/eol_info" 2>/dev/null)

echo "[${TIMESTAMP}] LifeA=${LIFE_A} LifeB=${LIFE_B} EOL=${EOL}" >> "${LOG}"

# 경고 조건 확인
if [ "${EOL}" = "0x02" ] || [ "${EOL}" = "0x03" ]; then
    echo "[${TIMESTAMP}] WARNING: PreEOL=${EOL} — 디바이스 교체 필요!" >> "${LOG}"
    # 알림 전송 (선택)
    logger -p user.crit "UFS PreEOL Warning: ${EOL}"
fi

if [ "${LIFE_A}" = "0x0A" ] || [ "${LIFE_A}" = "0x0B" ] ||
   [ "${LIFE_B}" = "0x0A" ] || [ "${LIFE_B}" = "0x0B" ]; then
    echo "[${TIMESTAMP}] CRITICAL: Lifetime exceeded 90%!" >> "${LOG}"
    logger -p user.crit "UFS Lifetime Critical: A=${LIFE_A} B=${LIFE_B}"
fi

디바이스 트리 바인딩 (Device Tree Bindings)

UFS 호스트 컨트롤러의 디바이스 트리 바인딩은 하드웨어 자원(레지스터, 인터럽트, 클럭, 레귤레이터, PHY)과 플랫폼별 설정을 선언합니다. 정확한 DT 설정은 UFS 초기화 성공과 최적 성능의 전제 조건입니다.

표준 DT 속성

Qualcomm 플랫폼 예시 (SM8550)

/* Qualcomm SM8550 UFS 호스트 컨트롤러 DT 노드 */
ufshc@1d84000 {
    compatible = "qcom,sm8550-ufshc", "qcom,ufshc", "jedec,ufs-2.0";
    reg = <0x1d84000 0x3000>;
    interrupts = ;

    /* 클럭 설정 */
    clocks = <&gcc GCC_UFS_PHY_AXI_CLK>,
             <&gcc GCC_AGGRE_UFS_PHY_AXI_CLK>,
             <&gcc GCC_UFS_PHY_AHB_CLK>,
             <&gcc GCC_UFS_PHY_UNIPRO_CORE_CLK>,
             <&gcc GCC_UFS_PHY_TX_SYMBOL_0_CLK>,
             <&gcc GCC_UFS_PHY_RX_SYMBOL_0_CLK>,
             <&gcc GCC_UFS_PHY_RX_SYMBOL_1_CLK>;
    clock-names = "core_clk",
                  "bus_aggr_clk",
                  "iface_clk",
                  "core_clk_unipro",
                  "tx_lane0_sync_clk",
                  "rx_lane0_sync_clk",
                  "rx_lane1_sync_clk";
    freq-table-hz = <75000000 300000000>,   /* core_clk */
                    <0 0>,                   /* bus_aggr_clk */
                    <0 0>,                   /* iface_clk */
                    <75000000 300000000>,    /* core_clk_unipro */
                    <0 0>,                   /* tx_lane0_sync */
                    <0 0>,                   /* rx_lane0_sync */
                    <0 0>;                   /* rx_lane1_sync */

    /* 레귤레이터 */
    vcc-supply = <&vreg_l7b_2p96>;
    vccq-supply = <&vreg_l9b_1p2>;
    vccq2-supply = <&vreg_s4a_1p8>;
    vcc-max-microamp = <800000>;
    vccq-max-microamp = <900000>;
    vccq2-max-microamp = <800000>;

    /* PHY 참조 */
    phys = <&ufs_mem_phy>;
    phy-names = "ufsphy";

    /* 리셋 */
    resets = <&gcc GCC_UFS_PHY_BCR>;
    reset-names = "rst";

    /* 플랫폼별 속성 */
    qcom,ice = <&ice>;

    status = "okay";

    /* Auto-Hibernate8 타이머 (ms) */
    /* 런타임에 sysfs로도 변경 가능 */
};

Samsung Exynos 플랫폼 예시

/* Samsung Exynos 2200 UFS 호스트 컨트롤러 */
ufs: ufshc@13100000 {
    compatible = "samsung,exynos2200-ufs";
    reg = <0x13100000 0x100>,   /* HCI 레지스터 */
          <0x13180000 0x8000>,  /* UNIPRO 레지스터 */
          <0x131A0000 0x2000>;  /* UFS protector 레지스터 */
    reg-names = "hci", "unipro", "ufsp";
    interrupts = ;

    clocks = <&cmu_hsi2 CLK_GOUT_HSI2_UFS_EMBD_ACLK>,
             <&cmu_hsi2 CLK_GOUT_HSI2_UFS_EMBD_UNIPRO>;
    clock-names = "core_clk", "core_clk_unipro";
    freq-table-hz = <0 267000000>, <0 267000000>;

    vcc-supply = <&ldo15_reg>;
    vccq-supply = <&ldo16_reg>;
    vccq2-supply = <&ldo17_reg>;

    phys = <&ufs_phy>;
    phy-names = "ufsphy";
    samsung,sysreg-phandle = <&sysreg_hsi2>;

    status = "okay";
};

MediaTek 플랫폼 예시

/* MediaTek Dimensity 9200 (MT6985) UFS 호스트 컨트롤러 */
ufshci: ufshci@11270000 {
    compatible = "mediatek,mt6985-ufshci", "mediatek,ufshci";
    reg = <0x11270000 0x2C00>,   /* HCI */
          <0x11280000 0x2000>;   /* MPHY */
    reg-names = "hci", "mphy";
    interrupts = ;

    clocks = <&topckgen CLK_TOP_UFS_SEL>,
             <&infracfg CLK_INFRA_UFS_AXI>,
             <&infracfg CLK_INFRA_UFS_AHB>,
             <&infracfg CLK_INFRA_UNIPRO_SYS>,
             <&infracfg CLK_INFRA_UNIPRO_TICK>;
    clock-names = "ufs_sel", "ufs_axi", "ufs_ahb",
                  "unipro_sys", "unipro_tick";
    freq-table-hz = <0 416000000>, <0 0>, <0 0>,
                    <0 416000000>, <0 0>;

    vcc-supply = <&mt6373_vemc>;
    vccq-supply = <&mt6373_vufs>;
    vccq2-supply = <&mt6373_vufs18>;

    phys = <&ufsphy>;
    phy-names = "ufsphy";

    mediatek,top-gpio = <&pio>;

    status = "okay";
};

sysfs 인터페이스

UFS 드라이버는 /sys/ 아래에 다양한 속성을 노출하여 런타임 모니터링과 튜닝을 지원합니다. 재컴파일 없이 전원 정책, Write Booster, Auto-Hibernate8 등의 동작을 변경할 수 있어 개발 및 디버깅에 필수적인 인터페이스입니다.

주요 sysfs 속성

전원 레벨 상세

sysfs 읽기/쓰기 예시

# UFS sysfs 베이스 경로 확인
UFS_PATH=$(find /sys/bus/platform/devices -maxdepth 1 -name "*ufshc*" | head -1)
echo "UFS sysfs path: ${UFS_PATH}"

# 현재 전원 레벨 확인
cat ${UFS_PATH}/rpm_lvl
cat ${UFS_PATH}/spm_lvl

# Runtime PM 레벨을 Sleep+Hibern8으로 변경
echo 3 > ${UFS_PATH}/rpm_lvl

# Auto-Hibernate8 타이머 설정 (10ms)
echo 10 > ${UFS_PATH}/auto_hibern8

# Write Booster 활성화/비활성화
echo 1 > ${UFS_PATH}/wb_on
echo 0 > ${UFS_PATH}/wb_on

# Clock gating 지연 조정 (200ms)
echo 200 > ${UFS_PATH}/clkgate_delay_ms

# Gear scaling 비활성화 (벤치마크 시)
echo 0 > ${UFS_PATH}/clkscale_enable

# 건강 정보 조회
ls ${UFS_PATH}/health_descriptor/
cat ${UFS_PATH}/health_descriptor/life_time_estimation_a
cat ${UFS_PATH}/health_descriptor/eol_info

# Unit descriptor 정보 (LUN별)
ls ${UFS_PATH}/unit_descriptor/
cat ${UFS_PATH}/unit_descriptor/unit0/boot_lun_id

ufs-utils 도구

ufs-utils는 UFS 디바이스 관리를 위한 커맨드라인 유틸리티로, /dev/bsg/ufs-bsg0 디바이스 노드를 통해 Query UPIU를 직접 전송합니다.

# ufs-utils 설치 (소스 빌드)
git clone https://github.com/westerndigitalcorporation/ufs-utils.git
cd ufs-utils && make && sudo make install

# 디바이스 디스크립터 읽기
sudo ufs-utils desc -a -p /dev/bsg/ufs-bsg0 -t device
# 출력 예:
#   bLength: 0x59
#   bDescriptorIDN: 0x00
#   bDevice: 0x00
#   bDeviceClass: 0x00
#   bDeviceSubClass: 0x01
#   bNumberLU: 0x01
#   wSpecVersion: 0x0310 (UFS 3.1)

# 설정 디스크립터 읽기
sudo ufs-utils desc -a -p /dev/bsg/ufs-bsg0 -t config

# Attribute 읽기 (bCurrentPowerMode)
sudo ufs-utils attr -a -p /dev/bsg/ufs-bsg0 -t 2

# Flag 읽기 (fDeviceInit, fPermanentWPEn 등)
sudo ufs-utils flag -a -p /dev/bsg/ufs-bsg0

# UFS 디바이스 정보 요약
sudo ufs-utils desc -a -p /dev/bsg/ufs-bsg0 -t device | grep -E "wSpec|bNumber|wManufacturer"

디버깅 및 문제 해결 (Debugging & Troubleshooting)

UFS 디버깅은 에러 핸들러의 동작 이해, 트레이스포인트 활용, debugfs 분석의 세 축으로 이루어집니다. ufshcd_err_handler는 OCS 에러, UIC 에러, SCSI 에러를 분류하고 단계적 복구를 수행합니다.

OCS 에러 코드

UIC 에러 유형

트레이스포인트 활용

# UFS 트레이스포인트 목록 확인
ls /sys/kernel/debug/tracing/events/ufs/
# ufshcd_command, ufshcd_uic_command, ufshcd_clk_gating,
# ufshcd_clk_scaling, ufshcd_auto_bkops_state, ...

# 커맨드 트레이스 활성화
echo 1 > /sys/kernel/debug/tracing/events/ufs/ufshcd_command/enable

# UIC 커맨드 트레이스 활성화
echo 1 > /sys/kernel/debug/tracing/events/ufs/ufshcd_uic_command/enable

# 트레이스 버퍼 읽기
cat /sys/kernel/debug/tracing/trace_pipe | head -50
# 출력 예:
# ufshcd_command: 0.0.0: send tag: 0, DB: 0x1, size: 4096,
#   IS: 0, LBA: 0x1234, opcode: 0x28 (READ_10), group_id: 0x0
# ufshcd_command: 0.0.0: complete tag: 0, DB: 0x0, size: 4096,
#   IS: 0, scsi_status: 0x0 (GOOD), OCS: 0x0 (SUCCESS)

# ftrace로 UFS I/O 지연 분석
echo function_graph > /sys/kernel/debug/tracing/current_tracer
echo ufshcd_queuecommand > /sys/kernel/debug/tracing/set_graph_function
echo 1 > /sys/kernel/debug/tracing/tracing_on
# ... I/O 수행 ...
echo 0 > /sys/kernel/debug/tracing/tracing_on
cat /sys/kernel/debug/tracing/trace

debugfs 엔트리

# debugfs 마운트 확인
mount | grep debugfs
# debugfs on /sys/kernel/debug type debugfs

# UFS debugfs 엔트리 확인
ls /sys/kernel/debug/ufshcd0/
# dump_device_desc  dump_health_desc  dump_string_desc
# err_stats         host_regs         req_stats
# show_hba          stats

# HBA 상태 전체 덤프
cat /sys/kernel/debug/ufshcd0/show_hba
# 출력 예:
#   UFS Host state: OPERATIONAL
#   lrb in use: 0x0
#   Outstanding reqs: 0x0
#   HS Gear: 4, Lanes: 2, Rate: B
#   Dev Power Mode: ACTIVE
#   Link State: UP

# 에러 통계 확인
cat /sys/kernel/debug/ufshcd0/err_stats
# UIC Errors (PA): 0
# UIC Errors (DL): 0
# UIC Errors (NL): 0
# UIC Errors (TL): 0
# UIC Errors (DME): 0
# SCSI cmd errors: 0
# Host reset count: 0

# 호스트 레지스터 덤프 (하드웨어 상태 분석)
cat /sys/kernel/debug/ufshcd0/host_regs

Kconfig 디버깅 옵션

# UFS 관련 Kconfig 옵션 확인
grep -E "CONFIG_SCSI_UFS|CONFIG_TRACING" /boot/config-$(uname -r) | sort
# CONFIG_SCSI_UFSHCD=y           # UFS 호스트 컨트롤러 드라이버
# CONFIG_SCSI_UFSHCD_PCI=m       # PCI 기반 UFS (인텔 등)
# CONFIG_SCSI_UFSHCD_PLATFORM=y  # 플랫폼 기반 UFS (모바일)
# CONFIG_SCSI_UFS_BSG=y          # BSG 노드 (/dev/bsg/ufs-bsg0)
# CONFIG_SCSI_UFS_CRYPTO=y       # 인라인 암호화 지원
# CONFIG_SCSI_UFS_HPB=y          # Host Performance Booster
# CONFIG_SCSI_UFS_FAULT_INJECTION=n  # 장애 주입 테스트
# CONFIG_TRACING=y               # ftrace 프레임워크

# dmesg에서 UFS 초기화 로그 분석
dmesg | grep -i "ufshcd\|ufs" | head -30
# [    1.234] ufshcd-qcom 1d84000.ufshc: ufshcd_pltfrm_init() start
# [    1.240] ufshcd-qcom 1d84000.ufshc: UFS Host Controller version: 3.0
# [    1.251] ufshcd-qcom 1d84000.ufshc: Linked as scsi host0
# [    1.312] ufshcd-qcom 1d84000.ufshc: HS-G4B (2-lane) connected
# [    1.315] ufshcd-qcom 1d84000.ufshc: UFS device is SAMSUNG KLUEG8UHDB
# [    1.320] scsi 0:0:0:0: Direct-Access UFS 3.1 PQ: 0 ANSI: 6

성능 튜닝 (Performance Tuning)

UFS 성능 최적화는 하드웨어 계층(Gear/Lane), 컨트롤러 계층(MCQ), 디바이스 기능(WB/HPB), 블록 레이어, 파일시스템에 이르기까지 다층적으로 접근해야 합니다. 각 계층의 튜닝 포인트를 이해하면 단일 스토리지에서도 2~5배의 성능 차이를 만들 수 있습니다.

튜닝 파라미터 정리

Gear/Lane 최적화

# 현재 Gear/Lane 상태 확인
cat /sys/kernel/debug/ufshcd0/show_hba | grep -E "Gear|Lane|Rate"
# HS Gear: 4, Lanes: 2, Rate: B

# Gear scaling 비활성화 (최대 성능 고정)
echo 0 > /sys/bus/platform/devices/1d84000.ufshc/clkscale_enable

# Power mode 변경 테스트 (개발 환경)
# 주의: 잘못된 Gear 설정은 링크 드롭을 유발
echo "HS-G4" > /sys/kernel/debug/ufshcd0/power_mode
# Rate-B, 2-Lane이 기본 최대 설정

블록 레이어 튜닝

# UFS 블록 디바이스 확인
DISK="sda"  # UFS는 SCSI 서브시스템 → /dev/sdX

# I/O 스케줄러 변경 (MCQ 사용 시 none 권장)
echo none > /sys/block/${DISK}/queue/scheduler
cat /sys/block/${DISK}/queue/scheduler
# [none] mq-deadline kyber bfq

# 큐 깊이 조정
echo 512 > /sys/block/${DISK}/queue/nr_requests

# Read-ahead 증가 (순차 읽기 워크로드)
echo 512 > /sys/block/${DISK}/queue/read_ahead_kb

# RQ affinity 설정 (완료 인터럽트 → 요청 CPU)
echo 2 > /sys/block/${DISK}/queue/rq_affinity

# Write Booster 활성화 확인 및 플러시 임계값 설정
echo 1 > /sys/bus/platform/devices/1d84000.ufshc/wb_on
echo 60 > /sys/bus/platform/devices/1d84000.ufshc/wb_flush_threshold

fio 벤치마크 설정

# === UFS Sequential Read 벤치마크 ===
cat > /tmp/ufs_seq_read.fio << 'FIOEOF'
[global]
ioengine=io_uring
direct=1
bs=128k
iodepth=32
numjobs=1
runtime=30
time_based
group_reporting

[seq-read]
filename=/dev/sda
rw=read
FIOEOF

sudo fio /tmp/ufs_seq_read.fio

# === UFS Random Read 벤치마크 (HPB 효과 측정) ===
cat > /tmp/ufs_rand_read.fio << 'FIOEOF'
[global]
ioengine=io_uring
direct=1
bs=4k
iodepth=32
numjobs=4
runtime=30
time_based
group_reporting

[rand-read]
filename=/dev/sda
rw=randread
FIOEOF

sudo fio /tmp/ufs_rand_read.fio

# === UFS Random Write 벤치마크 (WB 효과 측정) ===
cat > /tmp/ufs_rand_write.fio << 'FIOEOF'
[global]
ioengine=io_uring
direct=1
bs=4k
iodepth=16
numjobs=4
runtime=30
time_based
group_reporting

[rand-write]
filename=/dev/sda
rw=randwrite
FIOEOF

sudo fio /tmp/ufs_rand_write.fio

튜닝 전후 비교

관련 문서

UFS 서브시스템을 더 깊이 이해하거나 관련 기술을 학습할 때 참고할 문서를 정리합니다.

내부 문서 (사이트 내)

외부 참고 자료

• JEDEC JESD220F: UFS 4.0 표준 사양서 — SCSI 커맨드 매핑, 디스크립터, 전원 관리, Write Booster, HPB 전체 정의
• JEDEC JESD223D: UFS Host Controller Interface (UFSHCI) 4.0 사양서 — UTRD, UTMRD, MCQ, 레지스터 맵 정의
• MIPI M-PHY v5.0: UFS 물리 계층 사양 — HS/PWM 모드, Gear/Rate/Lane, 시그널링, 전기적 특성
• MIPI UniPro v2.0: UFS 전송 계층 사양 — Data Link, Network, Transport 레이어, E2E 플로우 컨트롤
• 커널 Documentation/scsi/ufs.rst: UFS 드라이버 개발자 문서, sysfs 속성 설명
• 커널 Documentation/ABI/testing/sysfs-driver-ufs: sysfs ABI 정의 문서

커널 소스 읽기 순서

UFS 서브시스템을 소스 코드 레벨에서 이해하려면 다음 순서로 읽는 것을 권장합니다.

1. include/ufs/ufs.h — UFS 프로토콜 상수, UPIU 구조체, 디스크립터 IDN, 전원 모드 정의
2. include/ufs/ufshci.h — UFSHCI 레지스터 오프셋, UTRD/UTMRD 구조체, OCS 코드 정의
3. drivers/ufs/core/ufshcd.c — UFS 호스트 컨트롤러 드라이버 코어 (초기화, I/O 경로, 에러 핸들링, PM)
4. drivers/ufs/core/ufs-mcq.c — Multi-Circular Queue 구현 (SQ/CQ 관리, 큐 매핑)
5. drivers/ufs/core/ufs-sysfs.c — sysfs 속성 정의 및 읽기/쓰기 핸들러
6. drivers/ufs/core/ufshcd-crypto.c — 인라인 암호화(ICE) 키 프로그래밍 및 crypto 프로파일
7. drivers/ufs/host/ufs-qcom.c — Qualcomm 플랫폼 드라이버 (ICE, PHY, testbus 등 벤더 확장 예시)

/* 핵심 I/O 경로 — ufshcd_queuecommand() 에서 시작 */

/*
 * 1. SCSI 미들레이어가 scsi_cmnd를 전달
 *    → ufshcd_queuecommand()
 *
 * 2. UPIU 구성
 *    → ufshcd_compose_devman_upiu()  (Query/NOP)
 *    → ufshcd_compose_scsi_cmd()     (SCSI Command)
 *
 * 3. UTRD 설정 + DMA 매핑
 *    → ufshcd_prepare_utp_scsi_cmd_upiu()
 *    → ufshcd_map_sg()  (scatter-gather → PRDT)
 *
 * 4. Doorbell 레지스터 쓰기 (SDB) 또는 SQ Tail 갱신 (MCQ)
 *    → ufshcd_send_command()
 *
 * 5. 인터럽트 → 완료 처리
 *    → ufshcd_transfer_req_compl()
 *    → ufshcd_compl_one_cqe()  (MCQ)
 */

# 소스 코드 탐색 팁
# 1. I/O 경로 시작점
grep -n "ufshcd_queuecommand" drivers/ufs/core/ufshcd.c | head -5

# 2. 에러 핸들러 진입점
grep -n "ufshcd_err_handler" drivers/ufs/core/ufshcd.c | head -5

# 3. 전원 관리 진입점
grep -n "ufshcd_suspend\|ufshcd_resume" drivers/ufs/core/ufshcd.c | head -10

# 4. MCQ 관련 함수
grep -n "ufshcd_mcq" drivers/ufs/core/ufs-mcq.c | head -10

# 5. 플랫폼 드라이버 ops 정의
grep -n "ufs_hba_qcom_vops" drivers/ufs/host/ufs-qcom.c