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), 인라인 암호화(Encryption)(ICE), RPMB, 전원 관리(Power Management), 디버깅(Debugging), 성능 튜닝까지 Linux 커널의 UFS 서브시스템(drivers/ufs/) 전체를 심층 분석합니다.

UFS 주요 개념과 구조체

• ufs_hba — UFS 호스트 컨트롤러 하나를 대표하는 최상위 구조체(Struct). UFSHCI 레지스터(Register), UTRL/UTMRL, 클럭, 전원 상태를 관리합니다.
• ufshcd_lrb — UFS Local Reference Block. 개별 I/O 요청의 SCSI 명령, UPIU, UTRD를 연결하는 중간 구조체입니다.
• utp_transfer_req_desc — UTP Transfer Request Descriptor(UTRD). UFSHCI 하드웨어가 DMA로 읽어가는 전송 요청 디스크립터입니다.
• scsi_device — UFS LU(Logical Unit) 하나에 대응하는 SCSI 디바이스. UFS는 최대 32개의 일반 LU와 4개의 Well-Known LU를 지원합니다.
• /dev/sda — UFS는 SCSI 계층을 사용하므로 블록 디바이스가 /dev/sda, /dev/sdb 등으로 나타납니다.

UFS 5.0(JESD220H/JESD223G) — 공표된 다음 세대 표준

JEDEC는 2026년 2월 26일 UFS 5.0(JESD220H)과 UFSHCI 5.0(JESD223G)을 발표했습니다. UFS 5.0은 UFS 4.x 하드웨어와의 호환성을 유지하면서 다음과 같은 확장을 담고 있습니다.

• 순차 처리량 최대 10.8 GB/s — MIPI M-PHY 6.0의 신규 HS-G6(레인당 방향별 46.6 Gb/s, HS-G5 대비 2배)를 UniPro 3.0과 함께 도입하여, 2레인 구성에서 유효 읽기/쓰기 대역폭이 약 10.8 GB/s에 도달합니다.
• 링크 이퀄라이제이션(Link Equalization) 통합 — 고속 동작에서의 신호 무결성 확보를 위해 TX 이퀄라이제이션 협상이 표준 동작으로 편입되었습니다(JEDEC·MIPI 공동 작업). 커널 쪽 선행 작업으로 뒤에서 설명할 적응형 TX EQ(ufs-txeq.c)와 qTxEQGnSettings 속성 프로그래밍이 있습니다.
• 전원 레일 분리 — PHY 영역과 메모리 서브시스템 영역에 별도 전원 핀을 두어 노이즈를 격리(Isolation)하고 시스템 통합을 단순화합니다.
• 인라인 해싱(Inline Hashing) — 저장 경로 안에서 데이터 무결성을 직접 검사하여 손상·변조를 빠르게 탐지합니다.
• AI 워크로드 지향 기능 — 벤더 발표 기준으로 Zone LU의 공식 반영, Pre-Erase(선 삭제) 같은 기능이 소개되었으며, UFS 4.1 대비 최대 2배 성능 향상과 더 빠른 부팅이 기대됩니다.

/* 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 배열 */
    /* (커널 ≤6.18) struct ufshcd_lrb *lrb 배열 — 6.19부터 제거,
       LRB는 scsi_cmd_priv(cmd)로 각 scsi_cmnd에 직접 부착 */
    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 디바이스 확인 — 일반 LU는 LUN 0부터, W-LU는 큰 LUN 번호로 보인다
$ lsscsi
[0:0:0:0]     disk SAMSUNG KLUDG4U1EA-B0C1 0200 /dev/sda    ← 일반 LU 0
# 그 외 W-LU도 별도 SCSI 디바이스로 등록된다:
#   [0:0:0:49456] ← Boot W-LU (UPIU W-LUN 0xB0 → SCSI LUN 0xC130)
#   [0:0:0:49472] ← RPMB W-LU (0xC4 → 0xC140)
#   [0:0:0:49488] ← Device W-LU (0xD0 → 0xC150)

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

# UFS 일반 LU의 SCSI 디바이스 속성 확인
$ cat /sys/class/scsi_device/0:0:0:0/device/vendor
SAMSUNG

UFS I/O 처리 흐름 상세

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

   /* SCSI mid-layer → UFS 호스트 드라이버 진입점 (커널 6.19+ 기준, 단순화) */
   static enum scsi_qc_status ufshcd_queuecommand(struct Scsi_Host *host,
                                                  struct scsi_cmnd *cmd)
   {
       struct ufs_hba *hba = shost_priv(host);
       struct ufs_hw_queue *hwq = ufshcd_mcq_req_to_hwq(hba,
                                           scsi_cmd_to_rq(cmd)); /* SDB면 NULL */
       int tag = scsi_cmd_to_rq(cmd)->tag;
       ufshcd_setup_scsi_cmd(hba, cmd,
                             ufshcd_scsi_to_upiu_lun(cmd->device->lun), tag);
           /* ├─ ufshcd_init_lrb(cmd): LRB 초기화 (lrbp = scsi_cmd_priv(cmd)) */
           /* ├─ ufshcd_prepare_lrbp_crypto(): blk-crypto 컨텍스트 연결 */
           /* └─ ufshcd_comp_scsi_upiu(hba, cmd): Command UPIU 구성 */
       ufshcd_send_command(hba, tag, hwq);   /* doorbell ring (SDB: UTRLDBR) */
       return 0;
   }

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

   /* Doorbell 링 — SDB(Single DoorBell) 모드에서 UFSHCI에 전송 시작 알림 */
   void ufshcd_send_command(struct ufs_hba *hba, unsigned int task_tag,
                            struct ufs_hw_queue *hwq)
   {
       if (hwq) {
           /* MCQ 모드: 해당 HW 큐의 SQ Tail Doorbell에 직접 기록 */
           ufshcd_writel(hba, task_tag, hwq->sq_sqctr_db);
       } else {
           /* SDB 모드: 공용 UTRLDBR의 태그 비트 설정 */
           ufshcd_writel(hba, 1 << task_tag,
                         REG_UTP_TRANSFER_REQ_DOOR_BELL);
       }
       /* 하드웨어가 해당 슬롯의 UTRD/UCD를 DMA로 fetch */
   }

4. M-PHY/UniPro 전송 및 디바이스 처리
   UFSHCI 하드웨어는 Command UPIU를 UniPro 프레임으로 캡슐화(Encapsulation)하고 M-PHY 물리 계층을 통해 UFS 디바이스에 전송합니다. 디바이스는 UPIU를 수신하여 SCSI 명령을 해석하고, NAND 플래시에 대한 읽기/쓰기를 수행합니다. 쓰기 요청의 경우, 디바이스는 먼저 RTT(Ready To Transfer) UPIU를 보내 호스트에 데이터 전송을 요청합니다.
5. 응답 UPIU 수신 및 SCSI 완료
   디바이스가 명령 처리를 완료하면 Response UPIU를 호스트에 전송합니다. UFSHCI가 이를 수신하여 UCD의 Response UPIU 영역에 기록하고, 인터럽트(Interrupt)를 발생시킵니다. 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/ 디렉터리에 집중되어 있습니다. 최근 메인라인 계열에서는 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 물리·전송 계층

모든 기어에 Rate A/B 두 계열이 존재하며(Rate B ≈ Rate A × 1.1667), 상용 UFS 제품은 주로 Rate B를 사용합니다. 실제 유효 대역폭은 라인 코딩과 UniPro/UPIU 프로토콜 오버헤드로 라인 레이트보다 낮아지므로, 실측 처리량은 라인 레이트를 그대로 MB/s로 환산한 값보다 작습니다.

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) 기반 재전송(Retransmission), TC(Traffic Class) 0/1 우선순위(Priority) 분리를 수행합니다.
• 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 {
    union {
        struct {
            __be32 dword_0;  /* Transaction Type | Flags | LUN | Task Tag */
            __be32 dword_1;  /* Cmd Set Type | Func Type | Response | Status */
            __be32 dword_2;  /* EHS Length | Device Info | Data Segment Length */
        };
        struct {
            /* DWORD 0 */
            u8 transaction_code;
            u8 flags;
            u8 lun;
            u8 task_tag;
            /* DWORD 1 */
            u8 command_set_type;
            u8 function_type;   /* Query Function 또는 TMF 코드 */
            u8 response;
            u8 status;
            /* DWORD 2 */
            u8 ehs_length;
            u8 device_info;
            __be16 data_segment_length;
        };
    };
};
static_assert(sizeof(struct utp_upiu_header) == 12);  /* 헤더 = 3 DWORD = 12바이트 */

/* 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_prepare_utp_scsi_cmd_upiu() */
static void ufshcd_prepare_utp_scsi_cmd_upiu(
    struct scsi_cmnd *cmd, u8 upiu_flags)
{
    struct ufshcd_lrb *lrbp = scsi_cmd_priv(cmd);
    struct utp_upiu_req *ucd_req_ptr = lrbp->ucd_req_ptr;

    /* DW0: Transaction Type | Flags | LUN | Task Tag */
    ucd_req_ptr->header.transaction_code = UPIU_TRANSACTION_COMMAND;
    ucd_req_ptr->header.flags           = upiu_flags;
    ucd_req_ptr->header.lun             = lrbp->lun;
    ucd_req_ptr->header.task_tag        = lrbp->task_tag;

    /* DW1: SCSI Command Set */
    ucd_req_ptr->header.command_set_type = UPIU_COMMAND_SET_TYPE_SCSI;

    /* 예상 데이터 전송 길이 + CDB 복사 (헤더+EDTL+CDB = 32바이트) */
    ucd_req_ptr->sc.exp_data_transfer_len = cpu_to_be32(scsi_bufflen(cmd));
    memcpy(ucd_req_ptr->sc.cdb, cmd->cmnd, 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 주요 필드 오프셋(Offset) */
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 {
    /* DW 0-3: 공용 디스크립터 헤더 (16바이트) */
    struct request_desc_header header;

    /* DW 4-5: UCD Base Address */
    __le64 command_desc_base_addr;

    /* DW 6: Response UPIU offset/length */
    __le16 response_upiu_length;  /* Response UPIU 길이 (DWord 단위) */
    __le16 response_upiu_offset;  /* UCD 내 Response UPIU 오프셋 */

    /* DW 7: PRDT offset/length */
    __le16 prd_table_length;      /* PRDT 엔트리 수 */
    __le16 prd_table_offset;      /* UCD 내 PRDT 오프셋 */
};  /* sizeof == 32바이트 — reserved 필드는 없음 */
static_assert(sizeof(struct utp_transfer_req_desc) == 32);

/* UTRD/UTMRD 공용 헤더 — include/ufs/ufshci.h */
struct request_desc_header {
    u8 cci;               /* Crypto Config Index (인라인 암호화 시 키 슬롯) */
    u8 ehs_length;
    u8 enable_crypto:1, reserved2:7;      /* CE 비트 */
    u8 interrupt:1, data_direction:2, command_type:4; /* DD, CT, IE */
    __le32 dunl;          /* Data Unit Number 하위 32비트 */
    u8 ocs;               /* Overall Command Status */
    u8 cds;
    __le16 ldbc;
    __le32 dunu;          /* Data Unit Number 상위 32비트 */
};
static_assert(sizeof(struct request_desc_header) == 16);

/* 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) === */
    /* (커널 ≤6.18) struct ufshcd_lrb *lrb 배열 존재 — 6.19부터 제거되어
       LRB는 scsi_cmd_priv(cmd)가 반환하는 scsi_cmnd 내부 영역에 부착됨 */
    unsigned long lrb_in_use;        /* 사용 중인 태그 비트맵 */

    /* === 벤더 콜백 === */
    const struct ufs_hba_variant_ops *vops;
    void *priv;                      /* 벤더 전용 데이터 (ufshcd_get_variant) */

    /* === 역량 및 슬롯 수 === */
    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 런타임 설정 */

    /* 프로그램 키 — 과거 vops에 존재했으나 최근 메인라인에서 제거됨.
       ICE 키슬롯 프로그래밍은 blk-crypto profile의 ll_ops
       (.keyslot_program 등)로 각 벤더가 직접 구현한다.
       예) ufs-qcom: ufs_qcom_ice_keyslot_program() → qcom_ice_program_key() */
};

/* 벤더 드라이버 등록 예시 (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 는 제거됨 — blk-crypto ll_ops로 이동 */
    .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() 호출
 *   (커널 6.19+: LRB는 scsi_cmd_priv(cmd)에 부착, 반환 타입 enum scsi_qc_status) */
static enum scsi_qc_status ufshcd_queuecommand(struct Scsi_Host *host,
                                               struct scsi_cmnd *cmd)
{
    struct ufs_hba *hba = shost_priv(host);
    struct request *rq = scsi_cmd_to_rq(cmd);
    int tag = rq->tag;
    /* SDB 모드면 NULL, MCQ 모드면 요청이 매핑된 HW 큐 */
    struct ufs_hw_queue *hwq = ufshcd_mcq_req_to_hwq(hba, rq);
    /* 커널 6.19+ : hba->lrb 배열 대신 scsi_cmd_priv(cmd) 사용 */
    struct ufshcd_lrb *lrbp = scsi_cmd_priv(cmd);

    ufshcd_setup_scsi_cmd(hba, cmd,
                          ufshcd_scsi_to_upiu_lun(cmd->device->lun), tag);
        /* ├─ LRB 초기화 (cmd / task_tag / lun / 암호화 컨텍스트) */
        /* └─ 내부에서 Command UPIU + PRDT 구성 */

    /* 2. Doorbell 링으로 HW에 전송 (SDB: UTRLDBR, MCQ: SQ Tail DB) */
    ufshcd_send_command(hba, tag, hwq);
    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. 개별 요청 완료 처리 — 커널 6.19+ 기준 (단순화) */
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 scsi_cmnd *cmd = scsi_host_find_tag(hba->host, tag);
        struct ufshcd_lrb *lrbp = scsi_cmd_priv(cmd);

        /* UTRD 헤더의 OCS(Overall Command Status) 확인 */
        if (lrbp->utr_descriptor_ptr->header.ocs == OCS_SUCCESS) {
            /* Response UPIU에서 SCSI Status 추출 */
            cmd->result = ufshcd_transfer_rsp_status(hba, lrbp);
        } else {
            /* OCS 에러 → 에러 핸들러로 위임 */
            cmd->result = DID_ERROR << 16;
        }

        scsi_done(cmd);   /* SCSI 레이어에 완료 통보 */
    }
}

/* 에러 핸들러 개요 */
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)를 통해 비동기적으로 처리됩니다. 인터럽트 컨텍스트에서 에러가 감지되면 워크를 스케줄하고, 별도 스레드(Thread)에서 복구를 수행합니다. 이 구조는 에러 복구 중에도 시스템이 응답성을 유지할 수 있게 합니다.

/* 에러 핸들러 워크 — 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,
    .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,
};

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

/* 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

제조사별 칩셋 심층 분석 (Vendor-Specific Deep Dive)

UFS 코어 드라이버(ufshcd.c)는 벤더 중립적이지만, 실제 SoC에서는 PHY 캘리브레이션, 인라인 암호화 엔진, 전원 도메인, 디버깅 인프라 등에서 제조사마다 상당히 다른 구현을 갖습니다. 이 섹션에서는 주요 SoC 벤더의 UFS 호스트 드라이버가 커널에서 어떻게 구현되어 있는지, 각 벤더의 고유 하드웨어 IP와 그에 대응하는 커널 코드를 심층 분석합니다.

Qualcomm — ICE, QMP PHY, Testbus

Qualcomm의 UFS 호스트 드라이버(ufs-qcom.c)는 커널 UFS 플랫폼 드라이버 중 가장 기능이 풍부하며, Snapdragon SoC의 주요 스토리지 경로를 담당합니다. ICE(Inline Crypto Engine), QMP PHY, Testbus 디버깅, MCQ 리소스 매핑, DevFreq 기반 성능 스케일링 등 다양한 하드웨어 IP를 커널에서 직접 제어합니다.

ICE (Inline Crypto Engine) 상세

ICE는 UFS 컨트롤러와 M-PHY 사이의 데이터 경로에 위치하여, CPU 개입 없이 읽기/쓰기 데이터를 실시간으로 암복호화합니다. Android의 파일 기반 암호화(FBE, File-Based Encryption)에서 핵심적인 역할을 수행하며, AES-256-XTS 모드를 하드웨어에서 직접 처리하여 소프트웨어 암호화 대비 성능 오버헤드가 거의 없습니다.

/* ICE 키 프로그래밍 흐름 — ufs-qcom.c + qcom-ice.c */

/*
 * 1단계: blk-crypto 프레임워크가 키슬롯 프로그래밍 요청
 *    → blk-crypto profile ll_ops.keyslot_program() → ufs_qcom_ice_program_key()
 */
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 ufs_crypto_cap_entry cap;
    union {
        u8 bytes[AES_256_XTS_KEY_SIZE];
        u32 words[AES_256_XTS_KEY_SIZE / sizeof(u32)];
    } key;

    /* crypto capability 확인 */
    cap = hba->crypto_cap_array[cfg->crypto_cap_idx];

    /* 키 데이터를 ICE 레지스터 형식으로 변환 */
    memcpy(key.bytes, cfg->crypto_key, AES_256_XTS_KEY_SIZE);

    /* qcom_ice 헬퍼를 통해 ICE 레지스터에 키 프로그래밍 */
    return qcom_ice_program_key(host->ice, cfg->crypto_cap_idx,
                                 QCOM_ICE_CRYPTO_KEY_SIZE_256,
                                 key.bytes, cfg->data_unit_size,
                                 slot);
}

/*
 * 2단계: ICE 레지스터에 키 쓰기 — qcom-ice.c
 *
 * ICE는 각 키슬롯에 대해 다음 레지스터를 프로그래밍:
 *   QCOM_ICE_REG_CRYPTOCFG      — 알고리즘, 키 크기, DUN(Data Unit Number) 크기
 *   QCOM_ICE_LUT_KEYS_CRYPTOCFG — 키 데이터 (256비트 × 2 = XTS 모드)
 *
 * 키 프로그래밍 순서:
 *   1. CRYPTOCFG.ENABLE = 0 (슬롯 비활성화)
 *   2. 키 데이터 레지스터에 32바이트씩 쓰기
 *   3. CRYPTOCFG = algorithm | key_size | dusize | ENABLE
 */

/*
 * 3단계: I/O 경로에서 ICE 자동 적용
 *   → UTRD의 crypto_enable 비트 설정
 *   → ICE가 DMA 전송 중 실시간 암복호화 수행
 *
 * ufshcd_prepare_req_desc_hdr()에서 (request_desc_header 필드 기준):
 *   req_desc->header.enable_crypto = 1;   // CE 비트
 *   req_desc->header.cci  = lrbp->crypto_key_slot;
 *   req_desc->header.dunl = lower_32_bits(lrbp->data_unit_num);
 *   req_desc->header.dunu = upper_32_bits(lrbp->data_unit_num);
 */

QMP UFS PHY

Qualcomm SoC는 QMP(Qualcomm Multi-Protocol) PHY IP를 사용하여 MIPI M-PHY 호환 직렬 링크를 구현합니다. QMP PHY는 USB, PCIe, UFS 등 여러 프로토콜을 지원하는 범용 SerDes(Serializer/Deserializer) IP이며, UFS 모드에서는 HS-Gear 4/5, Rate-A/B, 1~2 Lane을 지원합니다.

/* QMP UFS PHY 초기화 시퀀스 — 주요 흐름 */

/*
 * PHY 초기화는 link_startup_notify(PRE_CHANGE) 시점에 수행됩니다.
 * 핵심은 SoC별 캘리브레이션 테이블을 PHY 레지스터에 프로그래밍하는 것입니다.
 */
static int ufs_qcom_link_startup_notify(struct ufs_hba *hba,
                                         enum ufs_notify_change_status status)
{
    struct ufs_qcom_host *host = ufshcd_get_variant(hba);

    switch (status) {
    case PRE_CHANGE:
        /* UniPro 로컬 파라미터 설정 */
        ufshcd_dme_set(hba, UIC_ARG_MIB(PA_LOCAL_TX_LCC_ENABLE), 0);

        /* PHY 전원 On + 캘리브레이션 */
        if (host->phy)
            phy_power_on(host->phy);  /* → qmp_ufs_power_on() */
        break;

    case POST_CHANGE:
        /* 링크 수립 후 Gear/Rate 협상 결과 확인 */
        ufs_qcom_link_startup_post_change(hba);
        break;
    }
    return 0;
}

/*
 * QMP PHY 캘리브레이션 테이블 구조 (SoC별로 다름):
 *
 * static const struct qmp_phy_init_tbl sm8550_ufsphy_serdes[] = {
 *     QMP_PHY_INIT_CFG(QSERDES_UFS_V6_COM_SYSCLK_EN_SEL, 0xd9),
 *     QMP_PHY_INIT_CFG(QSERDES_UFS_V6_COM_CMN_CONFIG, 0x06),
 *     QMP_PHY_INIT_CFG(QSERDES_UFS_V6_COM_VCO_TUNE_MAP, 0x02),
 *     ... // SoC별 수십~수백 개의 레지스터 값
 * };
 *
 * 각 테이블은 TX(송신), RX(수신), PCS(Protocol Convergence Sublayer),
 * SERDES(PLL/CDR) 영역별로 분리되어 있습니다.
 */

Testbus 디버깅 인프라

Qualcomm UFS 컨트롤러는 내부 상태를 외부에서 관찰할 수 있는 Testbus 메커니즘을 제공합니다. 에러 핸들링 시 ufs_qcom_dump_dbg_regs()가 자동 호출되어 컨트롤러 내부 상태를 커널 로그에 덤프합니다.

/* Testbus 디버그 레지스터 덤프 — ufs-qcom.c */
static void ufs_qcom_dump_dbg_regs(struct ufs_hba *hba)
{
    struct ufs_qcom_host *host = ufshcd_get_variant(hba);

    /* 1. UFS 호스트 컨트롤러 레지스터 덤프 */
    ufshcd_dump_regs(hba, REG_UFS_SYS1CLK_1US, 16 * 4,
                     "HCI Vendor Specific Regs ");

    /* 2. Testbus 셀렉터별 상태 읽기 */
    ufs_qcom_testbus_read(hba);

    /*
     * Testbus 셀렉터 예시:
     *   TESTBUS_CFG = 0x   → UTP Transfer Request 상태
     *   TESTBUS_CFG = 0x05 → UTP Task Management 상태
     *   TESTBUS_CFG = 0x06 → UTRLCNR (완료 알림 레지스터) 상태
     *   TESTBUS_CFG = 0x07 → UTMRLCNR 상태
     *   TESTBUS_CFG = 0x10 → UFS-PHY 어댑터 레이어 상태
     *   TESTBUS_CFG = 0x11 → UniPro 상태
     *
     * 에러 분석 시 testbus 값의 비트 패턴으로
     * 요청이 어느 단계에서 멈췄는지 판별할 수 있습니다.
     */

    /* 3. PHY 상태 덤프 (선택) */
    if (host->dbg_print_en & UFS_QCOM_DBG_PRINT_PHY_EN)
        ufs_qcom_phy_dbg_register_dump(host->phy);
}

/*
 * sysfs를 통한 testbus 제어:
 *   echo <selector> > /sys/kernel/debug/ufshcd0/testbus
 *   cat /sys/kernel/debug/ufshcd0/testbus
 */

MCQ 리소스 매핑

UFS 4.0의 MCQ(Multi-Circular Queue) 모드에서 Qualcomm SoC는 SQ(Submission Queue)와 CQ(Completion Queue)의 도어벨(doorbell) 레지스터를 별도의 MMIO 영역에 매핑합니다. ufs_qcom_mcq_config_resource()는 디바이스 트리에서 이 영역의 물리 주소(Physical Address)를 읽어와 ioremap합니다.

/* Qualcomm MCQ 리소스 설정 — ufs-qcom.c */
static int ufs_qcom_mcq_config_resource(struct ufs_hba *hba)
{
    struct ufs_qcom_host *host = ufshcd_get_variant(hba);
    struct platform_device *pdev = to_platform_device(hba->dev);
    struct resource *res;

    /* MCQ SQ/CQ 도어벨 전용 MMIO 영역 */
    res = platform_get_resource_byname(pdev, IORESOURCE_MEM, "mcq");
    if (res) {
        host->mcq_base = devm_ioremap_resource(&pdev->dev, res);
        if (IS_ERR(host->mcq_base))
            return PTR_ERR(host->mcq_base);
    }

    /*
     * 각 SQ/CQ 쌍은 고유한 도어벨 레지스터 주소를 가짐:
     *   SQ[n] Tail Doorbell = mcq_base + 0x0 + (n * stride)
     *   CQ[n] Head Doorbell = mcq_base + 0x4 + (n * stride)
     *
     * 이 분리 매핑 덕분에 서로 다른 CPU 코어가
     * 각자의 큐에 독립적으로 접근할 수 있어 lock contention이 감소합니다.
     */

    return 0;
}

/*
 * DevFreq 성능 스케일링 — ufs_qcom_config_scaling_param()
 *
 * Qualcomm SoC는 UFS 컨트롤러의 동작 주파수를 DevFreq 프레임워크로 제어합니다.
 * I/O 부하가 낮을 때 Gear를 낮추고, 높을 때 최대 Gear로 올려
 * 전력-성능 균형을 자동으로 조절합니다.
 *
 * static void ufs_qcom_config_scaling_param(struct ufs_hba *hba,
 *                                   struct devfreq_dev_profile *p,
 *                                   struct devfreq_simple_ondemand_data *d)
 * {
 *     p->polling_ms = 60;       // 60ms마다 부하 샘플링
 *     d->upthreshold = 70;      // 70% 이상 → Gear Up
 *     d->downdifferential = 5;  // 65% 이하 → Gear Down
 * }
 */

Samsung Exynos — FMP, EOM, PHY 캘리브레이션

Samsung Exynos SoC의 UFS 드라이버(ufs-exynos.c)는 FMP(Flash Memory Protector)라는 자체 인라인 암호화 엔진, Exynos UFS PHY의 PMA(Physical Medium Attachment) 레지스터 직접 제어, EOM(Eye Opening Monitor)을 통한 신호 품질 분석 등 고유한 기능을 갖습니다.

FMP (Flash Memory Protector)

FMP는 Qualcomm의 ICE와 유사한 역할을 수행하지만, 구현 방식이 다릅니다. ICE가 별도의 레지스터 블록을 통해 키를 관리하는 반면, FMP는 PRDT(Physical Region Descriptor Table)의 각 엔트리에 암호화 정보를 직접 포함시킵니다.

/* FMP 키 프로그래밍 — PRDT 기반 방식 */

/*
 * FMP는 PRDT의 각 세그먼트에 암호화 파라미터를 직접 삽입합니다.
 * 표준 PRDT 엔트리(16바이트)가 FMP 확장 필드(추가 16바이트)를 포함하여
 * 총 32바이트로 확장됩니다.
 *
 * struct fmp_sg_entry {
 *     // 표준 PRDT 필드 (16바이트)
 *     __le32  des0;     // base address lower
 *     __le32  des1;     // base address upper
 *     __le32  des2;     // reserved
 *     __le32  des3;     // size (+ ODD/EDD 비트)
 *
 *     // FMP 확장 필드 (16바이트) — 암호화 설정
 *     __le32  file_iv0; // IV (Initialization Vector) [31:0]
 *     __le32  file_iv1; // IV [63:32]
 *     __le32  file_iv2; // IV [95:64]
 *     __le32  file_iv3; // IV [127:96]
 * };
 *
 * FMP 활성화: des3의 FAS(File Algorithm Select) 비트를 설정
 *   FAS = 0b00 : 암호화 비활성화
 *   FAS = 0b10 : AES-256-XTS 파일 암호화
 */

/*
 * 메인라인 ufs-exynos.c의 실제 FMP 연동 (단순화):
 *
 * 1) PRDT 채우기 — ufshcd_prepare_req_desc_hdr() 경로에서
 *    exynos_ufs_fmp_fill_prdt()가 각 SG 세그먼트마다
 *    fmp_sg_entry 확장 필드에 IV·알고리즘(FAS)을 기록한다.
 *
 * 2) 키 프로그래밍 — TrustZone으로 전달되는 SMC 명령
 *    (SMC_CMD_FMP_SECURITY)으로 FMP 키슬롯을 설정한다.
 *    키 관리는 SoC 보안 월드에서 수행된다.
 *
 * 즉, FMP도 blk-crypto 프로파일에 등록되어 동작하며,
 * "PRDT 단위 암호화 + SMC 기반 키 설정"인 점만 ICE와 다르다.
 */

Exynos UFS PHY — PMA 캘리브레이션

Exynos UFS PHY는 PMA(Physical Medium Attachment) 레지스터를 통해 TX/RX 신호 특성을 세밀하게 조절합니다. TXHSLV(TX High-Speed Level)와 RXHSLV(RX High-Speed Level) 값은 PCB 트레이스 길이, 임피던스, 보드 레이아웃에 따라 SoC별로 달라지며, 캘리브레이션이 부정확하면 링크 수립 실패나 CRC 에러가 발생합니다.

/* Exynos UFS PHY 캘리브레이션 — ufs-exynos.c */

/*
 * link_startup_notify(PRE_CHANGE)에서 PHY 파라미터를 설정합니다.
 * 각 SoC(Exynos 990, 2100, 2200 등)별로 최적 값이 다릅니다.
 */
static int exynos_ufs_pre_link(struct exynos_ufs *ufs)
{
    struct ufs_hba *hba = ufs->hba;

    /* UniPro 파라미터 설정 */
    ufshcd_dme_set(hba, UIC_ARG_MIB(PA_LOCAL_TX_LCC_ENABLE), 0);

    /* TX 캘리브레이션 */
    for_each_ufs_tx_lane(ufs, i) {
        ufshcd_dme_set(hba,
            UIC_ARG_MIB_SEL(TX_HIBERN8TIME_CAPABILITY, i), 0x01);
        ufshcd_dme_set(hba,
            UIC_ARG_MIB_SEL(TX_HS_EQUALIZER_SETTING, i),
            ufs->drv_data->tx_eq_val);  /* SoC별 이퀄라이저 값 */
    }

    /* RX 캘리브레이션 */
    for_each_ufs_rx_lane(ufs, i) {
        ufshcd_dme_set(hba,
            UIC_ARG_MIB_SEL(RX_HS_G1_SYNC_LENGTH_CAPABILITY, i), 0x4F);
        ufshcd_dme_set(hba,
            UIC_ARG_MIB_SEL(RX_HS_G2_SYNC_LENGTH_CAPABILITY, i), 0x4F);
        ufshcd_dme_set(hba,
            UIC_ARG_MIB_SEL(RX_HS_G3_SYNC_LENGTH_CAPABILITY, i), 0x4F);
    }

    /* Vendor-Specific 파라미터 (M-PHY 표준 외 확장) */
    exynos_ufs_config_phy(ufs);

    return 0;
}

/*
 * post_link에서 Gear/Rate 변경 후 추가 캘리브레이션 수행:
 * - HS-Series B (Rate-B)에서는 추가 SYNC 길이 조정 필요
 * - Gear 4에서는 RX 이퀄라이저 부스트 값 증가
 */

EOM (Eye Opening Monitor)

EOM은 Exynos UFS PHY에 내장된 신호 품질 측정 기능으로, 수신 데이터의 아이 다이어그램(Eye Diagram)을 소프트웨어에서 분석할 수 있게 합니다. PHY 캘리브레이션의 적절성을 검증하거나, 보드 설계의 시그널 인테그리티 문제를 진단할 때 사용됩니다.

/* EOM (Eye Opening Monitor) — debugfs를 통한 아이 다이어그램 측정 */

/*
 * 측정 원리:
 *   1. PHY RX 샘플링 포인트를 시간(phase)·전압(voltage) 축으로 이동
 *   2. 각 좌표에서 비트 에러율(BER) 측정
 *   3. BER < 임계값인 영역 = "Eye Opening" (개방 영역)
 *   4. 개방 영역이 클수록 신호 품질이 양호
 *
 * debugfs 인터페이스:
 *   /sys/kernel/debug/ufshcd0/eom
 *
 * 출력 예시 (phase × voltage 격자의 BER 맵):
 *   phase[-32..+32], voltage[-32..+32]
 *   중앙 영역의 BER = 0 → Eye Open
 *   가장자리 BER > 0 → Eye Closing (jitter/noise 영향)
 *
 * 실무 활용:
 *   - 보드 브링업 시 Eye가 충분히 열려 있는지 확인
 *   - HS-Gear 4/5에서 Eye가 닫히면 TX 이퀄라이저 또는 RX DFE 조정
 *   - 온도/전압 변동에 따른 마진 확인
 */

/*
 * Samsung 자체 VS(Vendor-Specific) 레지스터를 통한 EOM 제어:
 *   VS_DEBUGCLOCKENABLE — 디버그 클럭 활성화
 *   VS_SAVECONFIGTIME    — 캘리브레이션 저장 시간
 *   VS_DEBUGCOUNTENABLE  — 에러 카운터 활성화
 */

MediaTek — VA09, MPHY, 클럭 게이팅

MediaTek의 UFS 드라이버(ufs-mediatek.c)는 MT8183, MT8195, Dimensity 시리즈 등의 SoC에서 사용됩니다. VA09 레귤레이터 관리, 자체 MPHY IP, 다단계 클럭 게이팅 등 전력 효율에 초점을 맞춘 구현이 특징입니다.

VA09 레귤레이터 및 전원 시퀀싱

/* MediaTek UFS 전원 관리 — ufs-mediatek.c */

/*
 * MediaTek SoC는 UFS PHY에 VA09(0.9V 아날로그 전원)를 별도 레귤레이터로 공급합니다.
 * 이 전원은 M-PHY 아날로그 프론트엔드에 필수이며,
 * 전원 On/Off 순서가 정확하지 않으면 PHY가 불안정해집니다.
 */
static int ufs_mtk_mphy_power_on(struct ufs_hba *hba, bool on)
{
    struct ufs_mtk_host *host = ufshcd_get_variant(hba);
    int ret = 0;

    if (on) {
        /* 전원 On 순서: VA09 → MPHY → Reference Clock */
        ret = regulator_enable(host->reg_va09);
        if (ret)
            return ret;

        /* PHY 안정화 대기 */
        usleep_range(200, 210);

        /* MPHY 활성화 */
        ufs_mtk_setup_ref_clk(hba, true);

        /* MPHY 캘리브레이션 트리거 */
        ufs_mtk_mphy_ctrl(host, true);
    } else {
        /* 전원 Off 순서: MPHY → Reference Clock → VA09 (역순) */
        ufs_mtk_mphy_ctrl(host, false);
        ufs_mtk_setup_ref_clk(hba, false);
        regulator_disable(host->reg_va09);
    }

    return ret;
}

/*
 * MediaTek 전원 도메인 구조:
 *
 *   VCC (3.3V/1.8V) ──→ UFS 디바이스 (NAND 전원)
 *   VCCQ (1.2V)     ──→ UFS 디바이스 (I/O 전원)
 *   VCCQ2 (1.8V)    ──→ UFS 디바이스 (보조 I/O)
 *   VA09 (0.9V)     ──→ MPHY 아날로그 프론트엔드 (SoC 내부)
 *   VCC_HCI          ──→ UFS 호스트 컨트롤러 (SoC 내부)
 *
 * Suspend 시 VA09를 끄면 ~5mW 추가 절전 효과가 있으나,
 * Resume 시 PHY 재캘리브레이션이 필요하여 ~2ms 지연이 발생합니다.
 */

다단계 클럭 게이팅

/* MediaTek 클럭 관리 — 세분화된 클럭 게이팅 */

/*
 * MediaTek SoC는 UFS 관련 클럭을 5개 이상으로 세분화하여
 * 각 클럭을 독립적으로 게이팅할 수 있습니다.
 *
 * 클럭 구성 예시 (MT8195):
 *   1. ufs_sel       — UFS 코어 클럭 소스 선택 (200MHz/400MHz)
 *   2. ufs_hclk      — AHB 버스 클럭 (호스트 레지스터 접근)
 *   3. ufs_unipro    — UniPro 계층 클럭
 *   4. ufs_mp_sap    — MPHY 서브-어댑터 프로토콜 클럭
 *   5. ufs_encrypt   — 암호화 엔진 클럭
 *
 * 유휴 상태에서는 1~5 모두 게이팅 → 최소 전력 소비
 * Hibernate 상태에서는 2~5만 게이팅 → 빠른 복귀
 * 활성 상태에서는 5만 조건부 게이팅 → 암호화 미사용 시 절전
 */

static int ufs_mtk_setup_clocks(struct ufs_hba *hba, bool on,
                                 enum ufs_notify_change_status status)
{
    struct ufs_mtk_host *host = ufshcd_get_variant(hba);

    if (status == PRE_CHANGE && !on) {
        /* 클럭 Off 전: 진행 중인 트랜잭션 완료 대기 */
        ufs_mtk_wait_idle_state(hba, 5);

        /* Reference 클럭 비활성화 */
        ufs_mtk_setup_ref_clk(hba, false);
    } else if (status == POST_CHANGE && on) {
        /* 클럭 On 후: Reference 클럭 활성화 + PHY 안정화 */
        ufs_mtk_setup_ref_clk(hba, true);
    }

    return 0;
}

MediaTek 전용 Crypto IP

MediaTek SoC는 UFS 인라인 암호화를 위해 자체 설계한 crypto IP를 사용합니다. Qualcomm ICE와 달리 암호화 엔진이 UFS 컨트롤러 내부에 더 긴밀하게 통합되어 있으며, UFSHCI 표준의 crypto_cap 레지스터를 통해 능력(capability)을 보고합니다.

/* MediaTek Crypto 초기화 — ufs-mediatek.c */
static int ufs_mtk_init_crypto(struct ufs_hba *hba)
{
    struct ufs_mtk_host *host = ufshcd_get_variant(hba);

    /* Crypto 엔진 클럭 활성화 */
    if (host->clk_encrypt) {
        clk_prepare_enable(host->clk_encrypt);
    }

    /*
     * UFSHCI 표준 crypto 인터페이스 사용:
     *   hba->crypto_capabilities   — 지원 알고리즘/키 크기
     *   hba->crypto_cap_array      — 각 capability의 세부 사항
     *
     * MediaTek은 표준 UFSHCI crypto 레지스터를 통해
     * 키 프로그래밍을 수행하므로 별도의 vops->program_key가
     * 불필요한 경우도 있습니다.
     *
     * 단, SoC에 따라 crypto 엔진 리셋 순서에 quirk가 있어
     * suspend/resume 시 특별한 처리가 필요합니다:
     *   - Resume 후 crypto 엔진 리셋 + 키 재프로그래밍
     *   - hba->caps |= UFSHCD_CAP_CRYPTO를 설정하여 코어 드라이버에 알림
     */

    return 0;
}

HiSilicon Kirin — 다단계 PHY 초기화

HiSilicon(화웨이 반도체 부문)의 UFS 드라이버(ufs-hisi.c)는 Kirin 960/970/980/990 SoC를 지원합니다. 다른 벤더 드라이버에 비해 상대적으로 단순하지만, PHY 초기화 시퀀스가 매우 길고 SoC 리비전별로 세밀한 차이가 있는 것이 특징입니다.

/* HiSilicon UFS PHY 초기화 — ufs-hisi.c */

/*
 * Kirin SoC의 PHY 초기화는 3단계로 수행됩니다:
 *   1단계: SYSCTRL 레지스터를 통한 전원/리셋 제어
 *   2단계: PHY 레지스터 직접 프로그래밍 (수십 개의 레지스터)
 *   3단계: PLL 락(Lock) 확인 및 캘리브레이션 완료 대기
 */
static int ufs_hisi_link_startup_pre_change(struct ufs_hba *hba)
{
    struct ufs_hisi_host *host = ufshcd_get_variant(hba);
    int ret;

    /* SYSCTRL: UFS 리셋 해제 */
    writel(BIT_UFS_PSW_MTCMOS_EN,
           host->ufs_sys_ctrl + UFS_SYS_PSW_POWER_CTRL);
    udelay(10);

    /* PHY 레지스터 프로그래밍 (SoC별) */
    if (host->caps & UFS_HISI_CAP_PHY10nm) {
        /* Hi3670/Kirin 980: 10nm PHY */
        ufs_hisi_phy_init_10nm(host);
    } else {
        /* Hi3660/Kirin 960: 이전 세대 PHY */
        ufs_hisi_phy_init(host);
    }

    /* UniPro 파라미터 */
    ufshcd_dme_set(hba, UIC_ARG_MIB(PA_LOCAL_TX_LCC_ENABLE), 0);

    /*
     * Hi3660 특유 Quirk:
     * - Hibernate Exit 후 첫 번째 커맨드가 간헐적으로 타임아웃
     * - 워크어라운드: H8 Exit 후 100μs 추가 대기
     *
     * Hi3670 특유 Quirk:
     * - HS-Gear 3 Rate-B에서 RX 에러 발생 가능
     * - 워크어라운드: RX_HS_G3_SYNC_LENGTH를 표준보다 길게 설정
     */

    return 0;
}

/*
 * HiSilicon은 PHY를 별도 드라이버로 분리하지 않고
 * UFS 호스트 드라이버 내부에서 직접 PHY 레지스터를 제어합니다.
 * (다른 벤더는 대부분 drivers/phy/ 아래 별도 PHY 드라이버를 사용)
 *
 * 이 때문에 코드가 하드웨어에 강하게 결합되어 있으며,
 * SoC 리비전 추가 시 if/else 분기가 늘어나는 구조적 한계가 있습니다.
 */

Renesas R-Car — 자동차 등급 UFS

Renesas의 UFS 드라이버(ufs-renesas.c)는 R-Car Gen4(V4H) SoC를 대상으로 하며, 자동차 인포테인먼트와 ADAS(Advanced Driver-Assistance Systems) 시스템에서 사용됩니다. 자동차 환경의 넓은 온도 범위(-40°C~+125°C)와 높은 신뢰성 요구사항에 대응하는 것이 핵심입니다.

/* Renesas R-Car UFS — ufs-renesas.c */

/*
 * R-Car Gen4 UFS의 특징:
 *   1. 자동차 등급 온도 범위 대응: -40°C ~ +125°C
 *   2. 자체 설계 MPHY (Synopsys DesignWare 기반이 아님)
 *   3. 최소한의 vops 구현 — 핵심 기능만 포함
 */

static int ufs_renesas_init(struct ufs_hba *hba)
{
    struct ufs_renesas_priv *priv;

    priv = devm_kzalloc(hba->dev, sizeof(*priv), GFP_KERNEL);
    if (!priv)
        return -ENOMEM;

    ufshcd_set_variant(hba, priv);

    /*
     * R-Car Gen4 계열에서는 Auto-Hibernate를 기본으로 사용하는 구성이 흔합니다.
     * 자동차 환경에서는 빈번한 Sleep/Wake 전이가 발생하므로
     * H8 타이머를 짧게(1ms) 설정하여 전력 소비를 최소화합니다.
     */
    hba->ahit = FIELD_PREP(UFSHCI_AHIBERN8_TIMER_MASK, 1) |
                FIELD_PREP(UFSHCI_AHIBERN8_SCALE_MASK, 3); /* 1ms */

    return 0;
}

static int ufs_renesas_pwr_change_notify(
    struct ufs_hba *hba,
    enum ufs_notify_change_status status,
    struct ufs_pa_layer_attr *dev_max_params,
    struct ufs_pa_layer_attr *dev_req_params)
{
    if (status == PRE_CHANGE) {
        /*
         * PHY 캘리브레이션 파라미터를 Gear에 맞게 조정
         *
         * 자동차 온도 범위에서는 고온에서 PHY 마진이 줄어들므로
         * HS-Gear 3 이상에서 TX/RX 이퀄라이저를 보수적으로 설정
         *
         * 레지스터 값은 Renesas 데이터시트에 의한 권장값:
         * - TX_AMPLITUDE: 고온 보상 +10%
         * - RX_THRESHOLD: 노이즈 마진 확보
         */
        ufs_renesas_set_phy_params(hba, dev_req_params);
    }

    return 0;
}

/*
 * 자동차 등급 UFS 디바이스의 특성:
 *   - eUFS(Embedded UFS) 2.1/3.1 사양 준수
 *   - AEC-Q100 인증 (자동차 전자부품 신뢰성)
 *   - 넓은 동작 온도 범위에서 성능 일관성 보장
 *   - RPMB를 통한 보안 저장 (차량 보안 키, OTA 검증)
 *   - Write Protect로 펌웨어 영역 보호
 */

Intel / Synopsys — PCI 기반 UFS

서버, 데스크탑, 개발 보드 환경에서는 UFS 컨트롤러가 PCI 버스(Bus)에 연결됩니다. ufshcd-pci.c는 PCI 기반 UFS 호스트를 지원하며, Synopsys DesignWare UFS IP를 사용하는 SoC도 ufshcd-dwc.c 헬퍼를 통해 지원됩니다.

/* PCI 기반 UFS — ufshcd-pci.c */

/*
 * PCI UFS는 디바이스 트리 대신 PCI VID/DID로 디바이스를 식별합니다.
 * 플랫폼(SoC) 드라이버와 달리 PHY 초기화, 레귤레이터, 클럭 관리가
 * 불필요하거나 PCI 서브시스템이 담당합니다.
 */
static const struct pci_device_id ufshcd_pci_tbl[] = {
    { PCI_VENDOR_ID_INTEL, 0x9DFA,  /* Intel Ice Lake */
      PCI_ANY_ID, PCI_ANY_ID, 0, 0, (kernel_ulong_t)&ufs_intel_cnl_hba_vops },
    { PCI_VENDOR_ID_INTEL, 0x4B41,  /* Intel Elkhart Lake */
      PCI_ANY_ID, PCI_ANY_ID, 0, 0, (kernel_ulong_t)&ufs_intel_ehl_hba_vops },
    { PCI_VENDOR_ID_INTEL, 0x0,     /* Intel LKF */
      PCI_ANY_ID, PCI_ANY_ID, 0, 0, (kernel_ulong_t)&ufs_intel_lkf_hba_vops },
    { }  /* terminate list */
};

/*
 * Intel UFS vops는 최소한의 구현:
 *   - init: LTR(Latency Tolerance Reporting) 설정
 *   - resume: PCI D0 복귀 후 레지스터 복원
 *   - link_startup: Intel PHY 고유 파라미터 설정
 *
 * Synopsys DesignWare UFS TC(Test Chip):
 *   - FPGA/ASIC 검증용 UFS 호스트 컨트롤러
 *   - ufshcd-dwc.c + tc-dwc-g210 시리즈 드라이버
 *   - 40비트 어드레싱 지원 (DMA_BIT_MASK(40))
 */

디바이스 Quirks — ufs_fixups[] 테이블

UFS 디바이스(NAND 측) 제조사마다 표준 사양과 미묘하게 다른 동작을 보이는 경우가 있습니다. Linux 커널은 ufs_fixups[] 테이블을 통해 이러한 디바이스별 워크어라운드(quirk)를 관리합니다. 디바이스의 Manufacturer ID와 Model 문자열을 매칭하여 적절한 quirk 플래그를 적용합니다.

/* ufs_fixups[] — 디바이스별 워크어라운드 테이블 (ufshcd.c) */
static const struct ufs_dev_quirk ufs_fixups[] = {
    /*
     * Samsung UFS 디바이스
     * - 초기 모델에서 DL(Data Link) NAC 에러 복구 문제
     * - PA_TACTIVATE 타이밍 조정 필요
     */
    { .wmanufacturerid = UFS_VENDOR_SAMSUNG,
      .model = UFS_ANY_MODEL,
      .quirk = UFS_DEVICE_QUIRK_RECOVERY_FROM_DL_NAC_ERRORS |
               UFS_DEVICE_QUIRK_HOST_PA_SAVECONFIGTIME |
               UFS_DEVICE_QUIRK_PA_TACTIVATE },

    /*
     * SK hynix UFS 디바이스
     * - Hibernate 진입 전 지연 필요 (NAND 내부 GC 완료 대기)
     * - PA_TACTIVATE 표준보다 긴 값 필요
     */
    { .wmanufacturerid = UFS_VENDOR_SKHYNIX,
      .model = UFS_ANY_MODEL,
      .quirk = UFS_DEVICE_QUIRK_HOST_PA_SAVECONFIGTIME |
               UFS_DEVICE_QUIRK_PA_TACTIVATE },

    /*
     * Kioxia (구 Toshiba) UFS 디바이스
     * - PA_TACTIVATE 타이밍 조정
     * - 일부 모델에서 Hibernate 후 링크 재수립 지연
     */
    { .wmanufacturerid = UFS_VENDOR_TOSHIBA,
      .model = UFS_ANY_MODEL,
      .quirk = UFS_DEVICE_QUIRK_HOST_PA_SAVECONFIGTIME |
               UFS_DEVICE_QUIRK_PA_TACTIVATE |
               UFS_DEVICE_QUIRK_DELAY_AFTER_LPM },

    /*
     * Micron UFS 디바이스
     * - 특정 모델에서 확장 기능(Extended Features) 보고 방식이 다름
     */
    { .wmanufacturerid = UFS_VENDOR_MICRON,
      .model = UFS_ANY_MODEL,
      .quirk = UFS_DEVICE_QUIRK_DELAY_BEFORE_LPM },

    { } /* sentinel */
};

/*
 * Quirk 적용 시점: ufshcd_probe_hba() → ufshcd_fixup_dev_quirks()
 *
 * 매칭 알고리즘:
 *   1. ufs_fixups[] 순회
 *   2. wmanufacturerid 비교 (UFS_ANY_VENDOR는 전체 매칭)
 *   3. model 문자열 비교 (UFS_ANY_MODEL은 전체 매칭)
 *   4. 매칭되면 hba->dev_quirks |= fixup->quirk
 *
 * 벤더 추가 quirk: vops->apply_dev_quirks()로 플랫폼별 추가 적용 가능
 */
static void ufshcd_fixup_dev_quirks(struct ufs_hba *hba,
                                     const struct ufs_dev_quirk *fixups)
{
    const struct ufs_dev_quirk *f;
    struct ufs_dev_info *dev_info = &hba->dev_info;

    if (!fixups)
        return;

    for (f = fixups; f->quirk; f++) {
        if ((f->wmanufacturerid == dev_info->wmanufacturerid ||
             f->wmanufacturerid == UFS_ANY_VENDOR) &&
            ((f->model == UFS_ANY_MODEL) ||
             !strcmp(f->model, dev_info->model)))
            hba->dev_quirks |= f->quirk;
    }
}

주요 Quirk 상세 설명

UFS 디바이스 제조사별 NAND 특성

UFS 디바이스의 성능과 수명은 내부 NAND 플래시의 특성에 크게 좌우됩니다. 각 디바이스 제조사는 자체 NAND 기술을 기반으로 Write Booster, HPB, 가비지 컬렉션(GC) 등의 FTL(Flash Translation Layer) 전략을 다르게 구현하며, 이러한 차이가 실제 워크로드에서의 성능과 수명에 영향을 미칩니다.

Write Booster 동작 차이

Write Booster는 TLC/QLC NAND의 일부 영역을 SLC 모드로 사용하여 쓰기 속도를 가속하는 기능입니다. 제조사마다 SLC 버퍼 크기, 플러싱 정책, 잔여 용량에 따른 동작이 다릅니다.

/* Write Booster 제조사별 동작 차이 */

/*
 * 공통 동작 원리:
 *   1. 호스트가 Write Booster 활성화 → bWriteBoosterBufferFlushEn = 1
 *   2. 쓰기 데이터가 SLC 버퍼에 먼저 기록 (고속)
 *   3. 유휴 시간에 SLC → TLC 플러싱 (저속, 백그라운드)
 *   4. SLC 버퍼가 가득 차면 직접 TLC에 기록 (저속)
 *
 * Samsung 특성:
 *   - 상대적으로 큰 SLC 버퍼 (전체 용량의 ~3~5%)
 *   - 어그레시브한 플러싱 정책 (유휴 1초 이내 시작)
 *   - bAvailableWriteBoosterBufferSize로 잔여 SLC 버퍼 조회 가능
 *   - 온도가 높으면 (>45°C) 플러싱 우선도 증가
 *
 * SK hynix 특성:
 *   - 적응형 버퍼 관리 (사용 패턴에 따라 SLC 영역 크기 조절)
 *   - 디바이스 수명에 따라 SLC 영역 축소 (수명 보호)
 *
 * Kioxia/WD 특성:
 *   - 보수적 플러싱 (유휴 시간이 길어야 플러싱 시작)
 *   - 높은 온도에서 WB 비활성화 가능
 *
 * Micron 특성:
 *   - WB 모드 전환 시 약간의 지연 (DELAY_BEFORE_LPM quirk 관련)
 *   - 예측 기반 플러싱 (연속 쓰기 패턴 감지 시 사전 플러싱)
 */

/*
 * Write Booster 상태 확인 (공통):
 *   cat /sys/bus/platform/devices/*/attributes/wb_on
 *   cat /sys/bus/platform/devices/*/attributes/wb_buf_flush_status
 *   cat /sys/bus/platform/devices/*/attributes/wb_avail_buf
 *   cat /sys/bus/platform/devices/*/attributes/wb_buf_lifetime_est
 */

HPB 구현 차이

HPB(Host Performance Booster)는 UFS 디바이스의 L2P(Logical-to-Physical) 매핑 테이블 중 자주 접근하는 영역을 호스트 메모리(DRAM)에 캐싱하여 랜덤 읽기 성능을 개선합니다. HPB 1.0은 디바이스가 능동적으로 매핑을 추천하고, HPB 2.0은 호스트가 주도적으로 관리합니다.

/* HPB 제조사별 차이 — drivers/ufs/core/ufshpb.c */

/*
 * HPB 2.0 공통 동작:
 *   1. 호스트가 READ BUFFER(HPB_READ) 커맨드로 L2P 엔트리 요청
 *   2. 디바이스가 L2P 데이터를 응답
 *   3. 호스트가 DRAM에 캐싱
 *   4. 이후 읽기 시 HPB_READ 커맨드에 물리 주소를 직접 포함
 *   5. 디바이스가 L2P 테이블 조회를 건너뛰어 지연 시간 감소
 *
 * Samsung HPB 특성:
 *   - Active Region 수: 최대 64개 (디바이스 모델에 따라 다름)
 *   - Active Region당 Subregion: 최대 8개
 *   - L2P 캐시 적중 시 랜덤 읽기 지연 개선 (정확한 폭은 디바이스·환경 의존)
 *   - 디바이스 내부에서도 L2P 캐시 유지 (호스트 캐시와 이중)
 *
 * SK hynix HPB 특성:
 *   - 좀 더 공격적인 Inactive/Active 전환
 *   - 써멀 스로틀링 시 HPB 동작 축소
 *
 * HPB 활성화 확인:
 *   cat /sys/bus/platform/devices/*/device_descriptor/hpb_version
 *   cat /sys/bus/platform/devices/*/geometry_descriptor/hpb_region_size
 *   cat /sys/bus/platform/devices/*/geometry_descriptor/hpb_number_lu
 */

/*
 * HPB sysfs 제어:
 *   echo 1 > /sys/class/scsi_device/0:0:0:0/device/hpb_param/requeue_timeout_ms
 *   cat /sys/class/scsi_device/0:0:0:0/device/hpb_stats/hit_cnt
 *   cat /sys/class/scsi_device/0:0:0:0/device/hpb_stats/miss_cnt
 *   cat /sys/class/scsi_device/0:0:0:0/device/hpb_stats/rb_noti_cnt
 */

Logical Unit 배치 전략

UFS 디바이스는 최대 32개의 LU(Logical Unit)를 지원하며, 각 LU는 독립적인 속성(용량, 메모리 타입, Write Protect 등)을 가질 수 있습니다. 제조사마다 기본 LU 배치가 다르며, 출하 시 UFS Provisioning으로 구성합니다.

# LU 구성 확인
lsscsi -g
# [0:0:0:0]  disk  SAMSUNG  KLUEG4UHDB-B0D1  0400  /dev/sda  /dev/sg0
# [0:0:0:1]  disk  SAMSUNG  KLUEG4UHDB-B0D1  0400  /dev/sdb  /dev/sg1
# [0:0:0:2]  disk  SAMSUNG  KLUEG4UHDB-B0D1  0400  /dev/sdc  /dev/sg2
# [0:0:0:49152] ...  SAMSUNG  KLUEG4UHDB-B0D1       /dev/sg3  ← RPMB W-LU

# 각 LU 속성 확인 (ufs-utils)
ufs-utils desc -a -p /dev/bsg/ufs-bsg0 -t unit -i 0
# bLUEnable: 0x01
# bBootLunID: 0x01
# bLUWriteProtect: 0x00
# bMemoryType: 0x03 (Enhanced 1 = SLC)
# qPhyMemResourceCount: 0x00001000

# Provisioning (LU 재구성) — 주의: 데이터 완전 삭제
ufs-utils desc -w -p /dev/bsg/ufs-bsg0 -t conf -i 0
# bConfigDescrLock이 0x00인 경우에만 가능 (공장 출하 상태)

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 진입점
 * (커널 6.19+: LRB가 hba->lrb 배열에서 scsi_cmd_priv(cmd)로 이동) */
static enum scsi_qc_status ufshcd_queuecommand(struct Scsi_Host *host,
                               struct scsi_cmnd *cmd)
{
    struct ufs_hba *hba = shost_priv(host);
    struct request *rq = scsi_cmd_to_rq(cmd);
    int tag = rq->tag;
    struct ufs_hw_queue *hwq = ufshcd_mcq_req_to_hwq(hba, rq); /* SDB: NULL */
    struct ufshcd_lrb *lrbp = scsi_cmd_priv(cmd);

    /* 1. LRB 설정 + Command UPIU 패킹(CDB 복사 포함) */
    ufshcd_setup_scsi_cmd(hba, cmd,
                          ufshcd_scsi_to_upiu_lun(cmd->device->lun), tag);

    /* 2. UTRD 헤더 구성 (데이터 방향, 암호화 CE/CCI/DUN) */
    ufshcd_prepare_req_desc_hdr(lrbp, &upiu_flags,
                                cmd->sc_data_direction);

    /* 3. Doorbell Ring — HW에 전송 요청 */
    ufshcd_send_command(hba, tag, hwq);

    return 0;
}

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

Well-Known LU (W-LU)

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

커널은 UPIU의 W-LUN 값을 그대로 SCSI LUN으로 쓰지 않고, SCSI_W_LUN_BASE(0xC100)에 W-LUN ID를 더한 64비트 확장 주소로 매핑합니다. 예를 들어 Device W-LU(0xD0)는 0xC150 = 십진수 49488이 되어 lsscsi 출력에 큰 LUN 번호로 나타납니다.

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 초기화 핵심 (개념 설명용 의사코드).
 * 실제 구현은 ufshcd_mcq_config_nr_queues(), ufshcd_mcq_alloc_hw_queues(),
 * ufshcd_mcq_make_queues_operational() 등을 참조.
 * 큐당 깊이: hwq->max_entries = hba->nutrs + 1 */
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. 큐 가동 — 링크 스타트업 성공 후 한 번에 수행.
     *    SQATTR/SQLBA/SQUBA/SQDAO/SQISAO 및
     *    CQATTR/CQLBA/CQUBA/CQDAO 레지스터 프로그래밍 포함 */
    ufshcd_mcq_make_queues_operational(hba);

    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 정지(개념도) — 실제 에러 복구는 ufshcd_mcq_sq_cleanup(hba, task_tag)과
 * ufshcd_abort() 흐름에서 처리된다 */
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;

    /* on/off 모두 동일 속성 fWriteBoosterEn(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 디바이스의 논리적 주소 공간(Address Space)을 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 */
};

UFS 4.0 Advanced RPMB (커널 6.11+)

UFS 4.0은 기존 RPMB 왕복을 크게 줄인 Advanced RPMB를 도입했고, 커널 6.11에서 이에 대한 host 측 지원이 본격적으로 정비되었습니다. 전통적인 RPMB는 "write-counter read → authenticated write → result read"의 다단계 UPIU 교환이 필요했지만, Advanced RPMB는 Extra Header Segment(EHS)를 포함한 단일 SECURITY PROTOCOL OUT 커맨드로 인증·nonce·데이터 전송을 함께 수행합니다. ufs_bsg 경로로 노출되어 사용자 공간 도구가 표준화된 BSG SG_IO 인터페이스로 접근할 수 있습니다.

# UFS 4.0 디바이스의 Advanced RPMB 지원 비트 확인
$ ufs-utils desc -t 0 -i 0 -p /dev/bsg/ufs-bsg0
  bAdvancedRPMBVersion: 0x01
  bAdvancedRPMBCapabilities: 0x03   # ARPMB + Secure Write Counter

# BSG ioctl 경로로 ARPMB 단일-round 전송 (예시)
$ ufs-utils arpmb-write -p /dev/bsg/ufs-bsg0 \
    --key /etc/ufs-rpmb.key \
    --data payload.bin --counter-file rpmb.counter

UFS 4.0 MCQ 및 MCQ별 스케줄러 (커널 6.10~6.13)

UFSHCI 4.0 기반 MCQ(Multi-Circular Queue)는 커널 6.10~6.13 구간에서 Qualcomm ufs-qcom, MediaTek ufs-mediatek에 본격 반영되어 실제 상용 제품에서 NVMe 수준의 per-CPU 제출·완료 경로가 열렸습니다. 다음은 관전 포인트입니다.

• 최대 32 SQ/CQ 쌍: NVMe와 동일한 per-CPU 맵핑이 가능하며, /sys/class/scsi_host/hostN/mcq_nr_hw_queues로 관측합니다.
• ESI(Event-Specific Interrupt): MCQ별 독립 인터럽트 벡터로 분배되어 대용량 IOPS에서 IRQ affinity 설정이 NVMe처럼 중요해졌습니다. irqbalance 또는 set_irq_affinity.sh로 CPU 바인딩을 수행합니다.
• WriteBooster 게이팅 수정(6.10.10): 일부 벤더 디바이스에서 WriteBooster 미지원인데도 호스트가 활성화 요청을 보내 기아(Starvation) 현상을 일으키던 버그가 수정되었습니다.
• rk3576 / CV1812H: 6.13~6.15 구간으로 Rockchip RK3576, Sophgo CV1812H 등이 MCQ-capable 플랫폼으로 합류합니다.

# MCQ 활성화 플랫폼에서 하드웨어 큐 수 확인
$ cat /sys/class/scsi_host/host0/mcq_nr_hw_queues
8

$ cat /sys/block/sda/queue/nr_hw_queues
8   # blk-mq 하드웨어 컨텍스트 수 (MCQ와 일대일 대응)

$ cat /sys/class/scsi_host/host0/use_mcq_mode
1

# MCQ 지원 컨트롤러에서만 존재하는 sysfs
$ ls /sys/class/scsi_host/host0/
  mcq_nr_hw_queues  mcq_poll_queues  use_mcq_mode  ...

인라인 암호화 — 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를 통해 데이터의 무결성(Integrity)과 재생 공격(Replay Attack) 방지를 보장합니다. RPMB는 Well-Known LU(W-LUN 0xC4)로 접근하며, 보안 부팅(Secure Boot) 인증 정보, 롤백(Rollback) 방지 카운터, 디바이스 키 저장 등에 사용됩니다.

RPMB 프레임 구조

RPMB 요청/응답 타입

응답(Request/Response Type) 값은 대응하는 요청 타입에 | 0x0100을 OR한 값입니다. 예를 들어 Authenticated Data Write 요청(0x0003)의 응답은 0x0103이며, 커널 drivers/ufs/core/ufs-rpmb.c(OP-TEE 기반 RPMB 프레임워크 연동)에서도 이 규칙으로 응답 프레임을 검증합니다. Result Read(0x0005)는 별도 응답 타입 없이, 직전 쓰기에 해당하는 0x0103 프레임으로 결과를 회수합니다.

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

커널 표준 RPMB 프레임워크와 ufs-rpmb.c (6.15 → 6.19)

커널 6.15에 범용 RPMB 프레임워크(CONFIG_RPMB)가 들어오면서 eMMC·UFS·NVMe 어느 쪽 RPMB든 동일한 커널 내부 API로 다룰 수 있게 되었고, 커널 6.19의 drivers/ufs/core/ufs-rpmb.c("UFS OP-TEE based RPMB Driver")가 UFS를 이 프레임워크에 연결했습니다. OP-TEE처럼 커널 안에서 RPMB가 필요한 서브시스템은 더 이상 스토리지 종류를 알 필요가 없습니다.

/* include/linux/rpmb.h — 하위 드라이버가 채우는 디스크립터 (발췌) */
struct rpmb_descr {
    enum rpmb_type type;        /* RPMB_TYPE_EMMC / UFS / NVME */
    int (*route_frames)(struct device *dev, u8 *req, unsigned int req_len,
                        u8 *resp, unsigned int resp_len);
    u8  *dev_id;                /* 인증 키 유도에 쓰는 하드웨어 고유 ID */
    size_t dev_id_len;
    u16 reliable_wr_count;      /* 한 번에 reliable write 가능한 섹터 수 */
    u16 capacity;               /* 용량 (128KB 단위) */
};

/* 표준 512바이트 RPMB 프레임 (모든 필드 빅엔디안) */
struct rpmb_frame {
    u8     stuff[196];          /* 패딩 — 프레임 길이를 512바이트로 맞춤 */
    u8     key_mac[32];         /* 인증 키 또는 HMAC-SHA256 MAC */
    u8     data[256];
    u8     nonce[16];
    __be32 write_counter;
    __be16 addr;                /* 256바이트(half sector) 블록 단위 주소 */
    __be16 block_count;
    __be16 result;
    __be16 req_resp;            /* 요청/응답 타입 — 프레임 마지막 필드 */
};

ufs-rpmb.c의 등록 흐름은 다음과 같습니다.

• Advanced RPMB(UFS 4.0) 디바이스는 제외 — dev_info.b_advanced_rpmb_en이 설정된 디바이스는 기존 전용 경로를 그대로 사용하므로 등록을 건너뛰며, RPMB W-LU(hba->ufs_rpmb_wlun)가 없을 때도 등록하지 않습니다.
• 멀티 리전 지원 — 디바이스 디스크립터가 보고한 리전 크기 배열(dev_info.rpmb_region_size[])을 순회하면서 크기가 0이 아닌 각 리전마다 ufs_rpmb<region> 디바이스를 만들어 rpmb_dev_register()로 등록합니다. 프레임워크에 알리는 고유 ID는 "<device_id>-R<region>" 형태로 리전별로 구분됩니다.

프레임 전송은 SECURITY PROTOCOL IN/OUT 커맨드로 이루어집니다. 주목할 점은 Security Protocol Specific(SPS) 필드에 리전 번호가 포함된다는 것입니다.

/* drivers/ufs/core/ufs-rpmb.c — 프레임 라우팅 (발췌·단순화) */
#define UFS_RPMB_SEC_PROTOCOL     0xEC  /* JEDEC UFS 애플리케이션 프로토콜 */
#define UFS_RPMB_SEC_PROTOCOL_ID  0x01  /* JEDEC UFS RPMB 프로토콜 ID */

static int ufs_sec_submit(struct ufs_hba *hba, u16 spsp, void *buffer,
                          size_t len, bool send)
{
    struct scsi_device *sdev = hba->ufs_rpmb_wlun;
    u8 cdb[12] = { };

    cdb[0] = send ? SECURITY_PROTOCOL_OUT : SECURITY_PROTOCOL_IN;
    cdb[1] = UFS_RPMB_SEC_PROTOCOL;
    put_unaligned_be16(spsp, &cdb[2]);  /* 상위 바이트=리전, 하위 바이트=0x01 */
    put_unaligned_be32(len, &cdb[6]);

    return scsi_execute_cmd(sdev, cdb,
                            send ? REQ_OP_DRV_OUT : REQ_OP_DRV_IN,
                            buffer, len, 30 * HZ, 0, NULL);
}

static int ufs_rpmb_route_frames(struct device *dev, u8 *req,
                                 unsigned int req_len, u8 *resp,
                                 unsigned int resp_len)
{
    req_type = get_unaligned_be16(&frm_out->req_resp);

    switch (req_type) {
    case RPMB_PROGRAM_KEY:       /* 1프레임 요청 -> 1프레임 응답 */
        break;
    case RPMB_GET_WRITE_COUNTER: /* 결과 읽기 불필요 */
        need_result_read = false;
        break;
    case RPMB_WRITE_DATA:        /* N프레임 요청(512B 배수) -> 1프레임 응답 */
        break;
    case RPMB_READ_DATA:         /* 1프레임 요청 -> N프레임 응답 */
        need_result_read = false;
        break;
    }

    protocol_id = ufs_rpmb->region_id << 8 | UFS_RPMB_SEC_PROTOCOL_ID;

    ret = ufs_sec_submit(hba, protocol_id, req, req_len, true);   /* 1. 요청 전송 */
    if (need_result_read) {                                       /* 2. 결과 읽기 */
        frm_resp->req_resp = cpu_to_be16(RPMB_RESULT_READ);
        ret = ufs_sec_submit(hba, protocol_id, resp, resp_len, true);
    }
    ret = ufs_sec_submit(hba, protocol_id, resp, resp_len, false); /* 3. 응답 수신 */
    return ret;
}

전원 관리 (Power Management)

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

전원 모드 비교

클럭 게이팅 (Clock Gating)

UFS 호스트 드라이버는 일정 시간 유휴 상태(Idle State)가 지속되면 자동으로 클럭을 차단합니다. 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 기능을 사용하면 하드웨어가 유휴 타이머(Timer) 만료 시 자동으로 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 상태 확인 — 메인라인 표준 경로는 devfreq
ls /sys/class/devfreq/ | grep -i ufs
cat /sys/class/devfreq/1d84000.ufshc/cur_freq    # 현재 동작 주파수
cat /sys/class/devfreq/1d84000.ufshc/governor    # 스케일링 거버너

# Gear scaling 일시 고정 (디버깅/벤치마크 시)
echo performance > /sys/class/devfreq/1d84000.ufshc/governor

# 현재 링크 속도 확인 — 부팅 로그의 기어 협상 결과 활용
dmesg | grep -iE "ufshc.*(gear|lane)" | tail -3
# 출력 예: 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 = <GIC_SPI 265 IRQ_TYPE_LEVEL_HIGH>;

    /* 클럭 설정 */
    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 = <GIC_SPI 131 IRQ_TYPE_LEVEL_HIGH>;

    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 = <GIC_SPI 104 IRQ_TYPE_LEVEL_HIGH>;

    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 타이머 설정 (1000µs = 1ms)
echo 1000 > ${UFS_PATH}/auto_hibern8

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

# Clock gating 지연(clkgate_delay_ms)과 Gear scaling(clkscale_enable)은
# 메인라인 표준 sysfs가 아니라 devfreq 및 일부 BSP 확장으로 제공된다.
# 표준 방식의 벤치마크용 성능 고정 예:
echo performance > /sys/class/devfreq/$(basename ${UFS_PATH})/governor

# 건강 정보 조회
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 엔트리 확인 (루트: ufshcd, HBA마다 dev_name() 하위 디렉터리)
ls /sys/kernel/debug/ufshcd/
# ufshcd0/

ls /sys/kernel/debug/ufshcd/ufshcd0/
# stats                         # 이벤트 히스토그램 (아래 출력 예)
# saved_err  saved_uic_err      # 에러 핸들러 진행 값 (쓰면 EH 재유발)
# exception_event_mask          # EE(예외 이벤트) 사용자 마스크
# exception_event_rate_limit_ms # EE 알림 억제 시간 (기본 20ms)

# 에러 통계 확인
cat /sys/kernel/debug/ufshcd/ufshcd0/stats
# PHY Adapter Layer errors (except LINERESET): 0
# Data Link Layer errors: 0
# Network Layer errors: 0
# Transport Layer errors: 0
# Generic DME errors: 0
# Auto-hibernate errors: 0
# IS Fatal errors (CEFES, SBFES, HCFES, DFES): 0
# DME Link Startup errors: 0
# PM Resume errors: 0
# PM Suspend errors : 0
# Logical Unit Resets: 0
# Host Resets: 0
# SCSI command aborts: 0

# TX Equalization 지원 시 기어별 디렉터리 생성 (HS-G4+는 EQTR 기록 포함)
# (주의: tx_eq_* 계열은 커널 6.20에 병합 예정 — 2026년 8월 master 기준)
ls /sys/kernel/debug/ufshcd/ufshcd0/tx_eq_hs_gear4/
# host_tx_eq_params    device_tx_eq_params
# host_tx_eqtr_record  device_tx_eqtr_record
# tx_eq_ctrl           ← echo retrain > tx_eq_ctrl 로 TX EQ 재학습

# 참고: 디스크립터 덤프(device/string/health)와 레지스터 덤프는 debugfs가 아니라
# sysfs(device_descriptor/, string_descriptors/, health_descriptor/)로 제공된다

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            # (커널 6.6부터 옵션 자체가 제거됨)
# 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), 블록 레이어, 파일시스템에 이르기까지 다층적으로 접근해야 합니다. 각 계층의 튜닝 포인트를 이해하면 단일 스토리지에서도 큰 성능 차이를 만들 수 있습니다.

튜닝 파라미터 정리

Gear/Lane 최적화

# 현재 Gear/Lane 상태 확인 — 부팅 로그의 전원 모드 협상 결과 활용
dmesg | grep -iE "ufshc.*(gear|lane|pwr)" | tail -6
# 출력 예: ufs_device_wlun 0: HS-G4B, 2-lane 연결

# Gear scaling 고정 (최대 성능) — 메인라인 표준은 devfreq 거버너
echo performance > /sys/class/devfreq/1d84000.ufshc/governor
cat /sys/class/devfreq/1d84000.ufshc/cur_freq

# Power mode 변경 테스트는 DME UIC 쓰기가 필요하므로 드라이버 경유만 가능.
# 주의: 호스트와 디바이스의 Gear 불일치는 링크 드롭을 유발하므로
# 반드시 ufshcd_config_pwr_mode() 흐름(DME_SET(PA_PWRMODE))으로 변경한다.
# 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 서브시스템 변경 (커널 6.15~6.20)

커널 6.15부터 6.20 머지 윈도우(2026년 8월 기준)까지 UFS 서브시스템은 장치 예외(exception) 처리, 공유 ICE(Inline Crypto Engine), OPP V2 기반 다중 주파수 스케일링, HID(Host Initiated Defragmentation), 범용 RPMB 프레임워크 편입, LRB(Local Reference Block) 배열 제거, 적응형 TX 이퀄라이제이션 등 폭넓은 정비를 거쳤습니다. 각 버전 귀속은 릴리스 태그(v6.14~v6.19)와 master 소스를 직접 대조해 확인했습니다.

인프라 타임라인 — RPMB 프레임워크와 신규 코어 파일(6.15 → 6.20)

최근 릴리스에서 RPMB와 링크 품질 관련 인프라가 단계적으로 편입되었습니다.

• 커널 6.15 — 범용 RPMB 프레임워크(include/linux/rpmb.h, CONFIG_RPMB)가 병합되었습니다. 저장소 종류를 enum rpmb_type(eMMC/UFS/NVMe)으로 추상화하고, 하위 디바이스 드라이버는 디스크립터(struct rpmb_descr: 프레임 라우팅 콜백, 고유 ID, reliable write 카운트, 용량)를 rpmb_dev_register()로 등록합니다.
• 커널 6.18 — rpmb.h에 512바이트 표준 프레임(struct rpmb_frame)과 요청 타입 상수(RPMB_PROGRAM_KEY, RPMB_GET_WRITE_COUNTER, RPMB_WRITE_DATA, RPMB_READ_DATA, RPMB_RESULT_READ)가 추가되어 프레임 처리가 공통화되었습니다.
• 커널 6.19 — drivers/ufs/core/ufs-rpmb.c("UFS OP-TEE based RPMB Driver", Micron·Qualcomm 기여)가 신설되어 UFS RPMB W-LU를 범용 프레임워크에 연결합니다(CONFIG_RPMB 활성 시 빌드). 상세는 RPMB 절의 "커널 표준 RPMB 프레임워크" 단락을 참조합니다.
• 커널 6.20(병합 예정) — 적응형 TX 이퀄라이제이션 담당 신규 파일 drivers/ufs/core/ufs-txeq.c가 SCSI 트리를 통해 병합을 앞두고 있습니다(2026년 8월 master 확인). 아래 전용 단락에서 자세히 설명합니다.

신규 파일 — ufs-rpmb.c(OP-TEE RPMB), ufs-txeq.c(TX Equalization)

• drivers/ufs/core/ufs-rpmb.c — MMC 쪽 rpmb 프레임워크와 UFS RPMB W-LU를 잇는 인터페이스입니다. OP-TEE 기반 백엔드가 커널 표준 rpmb API로 UFS RPMB 구역을 사용할 수 있게 하며, "요청 타입 | 0x0100" 규칙으로 응답을 검증합니다(Micron·Qualcomm 기여, 2025년).
• drivers/ufs/core/ufs-txeq.c — M-PHY TX Equalization(EQTR) 교환 로직입니다. HS-Gear 진입 전 PreShoot/DeEmphasis 파라미터를 디바이스와 협상하고 결과를 debugfs(tx_eq_hs_gearN/)로 노출합니다. 앞선 debugfs 절의 tx_eq_ctrl(retrain)도 이 모듈과 연동됩니다.

6.15: 장치 수준 예외(Device Exception) 처리 지원

커널 6.15에서 UFS 장치가 발생시키는 장치 예외(Device Exception)를 호스트 드라이버가 처리하는 기능이 추가되었습니다. UFS 장치는 특정 조건(예: 온도 임계값 초과, 내부 오류)에서 예외 이벤트를 발생시킬 수 있으며, 이를 UIC(UFS Interconnect) 레이어를 통해 호스트에 통보합니다.

기존에는 이러한 장치 예외 알림이 무시되거나 일반 오류로 처리되었으나, 6.15부터 ufshcd 드라이버가 장치 예외 인터럽트(Exception Event Interrupt)를 별도로 처리하는 경로가 구현되어 장치 상태를 더 세밀하게 관리할 수 있게 되었습니다.

커널 6.15부터: UFS 장치가 발생시키는 예외 이벤트를 ufshcd가 명시적으로 처리합니다. 장치 온도 제한이나 내부 오류 상황에서 더 안정적인 동작이 기대됩니다.

6.15: Qualcomm 공유 ICE (Shared Inline Crypto Engine)

커널 6.15에서 Qualcomm UFS 드라이버(drivers/ufs/host/ufs-qcom.c)에 공유 ICE(Shared Inline Crypto Engine) 지원이 추가되었습니다. 일부 Qualcomm SoC에서는 UFS와 eMMC/SD가 동일한 ICE 하드웨어 블록을 공유하는 구조로 설계되어 있습니다. 기존 드라이버는 UFS 전용 ICE만 가정하고 있었으나, 공유 ICE 구조에서는 다른 초기화 시퀀스와 클럭 관리가 필요합니다.

이 변경으로 Qualcomm 플랫폼에서 UFS 인라인 암호화가 공유 ICE를 통해 올바르게 초기화되고 동작합니다.

커널 6.15부터: Qualcomm 공유 ICE를 사용하는 플랫폼(예: 일부 SM8xxx 계열)에서 UFS 인라인 암호화가 올바르게 동작합니다.

6.15: OPP V2 기반 다중 주파수 스케일링

커널 6.15에서 UFS 클럭 스케일링(Clock Scaling)이 기존의 단순 고속/저속 2단계 방식에서 OPP(Operating Performance Points) V2 테이블 기반의 다중 주파수 스케일링(Frequency Scaling)으로 확장되었습니다.

핵심 변경 사항은 다음과 같습니다.

• freq_to_gear_speed(): OPP 주파수 값을 UFS Gear 속도(Gear 1~5)로 변환하는 새 헬퍼 함수. 플랫폼별 OPP 테이블에서 적절한 기어 속도를 산출합니다.
• clk_scale_notify(): 클럭 주파수 변경 요청 시 호출되는 콜백으로, 기어 전환 전 UFS 링크를 적절히 준비(hibernate/unhibernate)합니다.
• Write Booster per-gear 토글: Gear 전환 시 Write Booster(쓰기 버퍼링) 활성화 여부를 기어별로 별도 제어합니다. 저속 기어에서는 Write Booster를 비활성화하여 전력 소모를 줄이고, 고속 기어에서만 활성화합니다.

/* ufshcd-core.h — freq_to_gear_speed 선언 (6.15+) */
int freq_to_gear_speed(struct ufs_hba *hba, unsigned long freq,
                       u32 *gear_speed);

/* ufshcd.c — 클럭 스케일 노티파이 콜백 */
static int ufshcd_clk_scale_notify(struct notifier_block *nb,
                                    unsigned long event, void *data);

커널 6.15부터: UFS 클럭 스케일링이 OPP V2 테이블을 지원합니다. 플랫폼 DTS에 operating-points-v2 속성을 추가하면 세밀한 주파수 제어가 가능합니다.

6.16: WriteBooster 버퍼 리사이즈와 디바이스 명령 타임아웃 제어

커널 6.16의 UFS 코어 변경은 운영 편의성에 초점이 맞춰져 있습니다.

• WriteBooster 버퍼 리사이즈 — Query 속성 bWriteBoosterBufferResizeHint(0x3C), bWriteBoosterBufferResizeEn(0x3D), bWriteBoosterBufferResizeStatus(0x3E)를 다루는 경로가 코어에 추가되어 Dedicated/Shared 버퍼 배분을 런타임에 조정할 수 있게 되었습니다. 리사이즈 상태는 sysfs에서 문자열로 보고됩니다.
• 디바이스 명령 타임아웃 갱신 — Query/NOP/RPMB 같은 디바이스 관리 명령의 타임아웃을 상황에 맞게 조정하는 인터페이스가 추가되었습니다.
• Qualcomm 확장 — wrapped key(하드웨어 래핑 키) 지원과 HW/SW hibern8 카운트·MCQ 레지스터·testbus 덤프 기능이 ufs-qcom에 추가되었습니다(덤프는 앞선 Qualcomm Testbus 절과 연결됩니다).

6.17: HID(Host Initiated Defragmentation) 지원

UFS 4.1(JESD220G)이 추가한 HID(호스트 주도 디프래그먼테이션, Host Initiated Defragmentation)를 커널 6.17이 지원합니다(vivo 기여). NAND 플래시에서는 반복된 쓰기로 논리 블록이 물리 페이지 곳곳에 흩어지는 단편화(Fragmentation)가 진행되고, 이는 읽기 성능 저하로 이어집니다. HID는 호스트가 디바이스에게 단편화 분석과 재배치(Relocation)를 지시하는 표준 수단입니다.

실행 정책은 사용자 공간의 몫입니다. 커널은 다음 sysfs 그룹(/sys/bus/platform/devices/*.ufs/hid/)만 제공합니다.

# HID 지원 여부는 디바이스 디스크립터의 dExtendedUFSFeatures BIT(13)로 판단합니다
cat /sys/bus/platform/devices/1d84000.ufshc/hid/state
# idle

echo enable > /sys/bus/platform/devices/1d84000.ufshc/hid/analysis_trigger
sleep 5
cat /sys/bus/platform/devices/1d84000.ufshc/hid/fragmented_size
cat /sys/bus/platform/devices/1d84000.ufshc/hid/state             # defrag_required?

echo enable > /sys/bus/platform/devices/1d84000.ufshc/hid/defrag_trigger
while [ "$(cat /sys/bus/platform/devices/1d84000.ufshc/hid/state)" != "defrag_completed" ]; do
    cat /sys/bus/platform/devices/1d84000.ufshc/hid/progress_ratio
    sleep 10
done

6.19: LRB 배열 제거와 ufs-rpmb.c 편입

• hba->lrb[] 배열 제거 — 오랫동안 유지되던 태그→LRB 조회 배열(struct ufshcd_lrb *lrb)이 사라지고, LRB는 scsi_cmd_priv(cmd)가 반환하는 struct scsi_cmnd의 드라이버 프라이빗 영역에 직접 부착됩니다. 완료 인터럽트에서 태그로 배열을 역추적(Backtrace)하지 않으므로 간접층이 줄고 캐시 지역성도 좋아집니다. 현재 ufshcd.c에는 scsi_cmd_priv(cmd) 호출이 수십 곳에 이르며, 앞선 I/O 경로·완료 경로 코드가 바로 이 새 구조를 반영합니다.
• ufs-rpmb.c 신설 — UFS RPMB가 커널 표준 RPMB 프레임워크의 일등 시민이 되었습니다. OP-TEE처럼 커널 안에서 RPMB가 필요한 서브시스템은 rpmb_route_frames() 공통 API만으로 UFS RPMB 구역을 사용할 수 있으며, 상세 동작은 RPMB 절의 전용 단락에서 다룹니다.

6.20 병합 예정(master): 적응형 TX 이퀄라이제이션(EQTR)과 전원 협상 통합

2026년 8월 기준 master에는 다음 변경이 들어왔으며 커널 6.20에 포함될 예정입니다.

• 전원 협상 경로 통합 — vops에 negotiate_pwr_mode() 콜백이 추가되어 기어·레인·레이트 결정 절차를 벤더가 개입할 수 있는 한 지점으로 모읍니다.
• DevMan(디바이스 관리 명령) 전용 UCD — Query/NOP 처리가 SCSI UTRD와 별개의 struct utp_devman_cmd_desc와 전용 DMA 버퍼(최대 4KiB PRDT 전송)를 사용해, 대형 Query Response가 기존 전송 디스크립터 한계에 걸리던 문제를 해소합니다(devman_ucd_base_addr).
• 적응형 TX 이퀄라이제이션 — 신규 파일 drivers/ufs/core/ufs-txeq.c. 아래에서 상세히 설명합니다.

M-PHY TX Equalization(EQTR)이 필요한 이유

HS-G4 이상 고속 링크에서는 TX 프리엠파시스(pre-shoot)/디엠파시스(de-emphasis) 설정이 눈금 단위로 신호 품질을 좌우합니다. UFS는 디바이스와 호스트가 서로의 TX 특성을 교환해 최적 조합을 찾는 TX EQ 학습(TX EQ Training, EQTR) 절차를 제공하며, 학습 결과는 레인별 PreShoot×DeEmphasis 조합의 FOM(Figure of Merit) 행렬로 남습니다.

ufs-txeq.c는 전원 모드 변경 전에 최적 설정을 찾아 적용하는 적응형(adaptive) 엔진입니다. 핵심 인터페이스는 다음과 같습니다.

/* drivers/ufs/core/ufs-txeq.c — 핵심 인터페이스 발췌 */

/* 모듈 파라미터: 전원 모드 변경 전 적응형 TX EQ 수행 여부(기본 false) */
static bool use_adaptive_txeq;
module_param(use_adaptive_txeq, bool, 0644);
MODULE_PARM_DESC(use_adaptive_txeq,
    "Find and apply optimal TX Equalization settings before changing Power Mode");

/* 목표 기어(기본 HS-G6, UFS_HS_G1~UFS_HS_GEAR_MAX 범위로 제한) */
static unsigned int adaptive_txeq_gear = UFS_HS_G6;

/* 학습된 설정을 디바이스 속성에 기록 — 기어별 Selector 단위 */
static void ufshcd_update_tx_eq_settings_attrs(struct ufs_hba *hba, u32 gear)
{
    /* qTxEQGnSettings(64비트 qword 속성) 기록 */
    ret = ufshcd_query_attr_qword(hba, UPIU_QUERY_OPCODE_WRITE_ATTR,
                                  QUERY_ATTR_IDN_TX_EQ_GN_SETTINGS,
                                  gear - 1, (u8)txeq_setting_sel, &eq);
    /* wTxEQGnSettingsExt(확장 비트 필드) 기록 */
    ret = ufshcd_query_attr(hba, UPIU_QUERY_OPCODE_WRITE_ATTR,
                            QUERY_ATTR_IDN_TX_EQ_GN_SETTINGS_EXT,
                            gear - 1, (u8)txeq_setting_sel, &eq_ext);
}

/* 전원 모드 변경 경로에서 호출 — 유효한 모든 기어에 설정 기록 */
void ufshcd_store_tx_eq_settings(struct ufs_hba *hba);

debugfs 인터페이스(앞선 debugfs 절 참조)와 연동하면 다음 흐름이 됩니다.

# 1. 재학습(retrain) 지시 — EQTR 기록은 HS-G4 이상 기어 디렉터리에만 존재
echo retrain > /sys/kernel/debug/ufshcd/ufshcd0/tx_eq_hs_gear4/tx_eq_ctrl

# 2. 학습 결과(FOM 행렬) 확인 — PreShoot(행) × DeEmphasis(열),
#    '*'는 Pre-Coding이 활성된 조합, 'x'는 PHY capability 밖 조합
cat /sys/kernel/debug/ufshcd/ufshcd0/tx_eq_hs_gear4/host_tx_eqtr_record

# 3. 최종 선택된 파라미터(레인별 preshoot/deemphasis/precode) 확인
cat /sys/kernel/debug/ufshcd/ufshcd0/tx_eq_hs_gear4/host_tx_eq_params
cat /sys/kernel/debug/ufshcd/ufshcd0/tx_eq_hs_gear4/device_tx_eq_params

6.15: Renesas R-Car S4-8 ES1.2 지원

커널 6.15에서 Renesas R-Car S4-8 SoC의 ES1.2(Engineering Sample 1.2) 실리콘에 대한 UFS 호스트 컨트롤러 지원이 추가되었습니다. ES1.2는 ES1.1 대비 PHY 초기화 시퀀스와 타이밍 파라미터가 변경되었으며, drivers/ufs/host/ufs-renesas.c에 ES1.2 전용 초기화 코드가 추가되었습니다.

6.15/6.14: Rockchip RK3576 UFS 컨트롤러 지원

Rockchip RK3576 SoC에 탑재된 UFS 호스트 컨트롤러 지원이 추가되었습니다(SCSI 트리를 통해 6.14에 병합). RK3576은 Rockchip의 고성능 임베디드 SoC로, UFS 2.x 인터페이스를 지원하며 drivers/ufs/host/ufs-rockchip.c에 전용 초기화 및 PHY 제어 코드가 포함됩니다.

커널 6.14/6.15부터: Rockchip RK3576 기반 시스템에서 UFS 스토리지를 사용할 수 있습니다. 커널 구성 시 CONFIG_SCSI_UFS_ROCKCHIP을 활성화해야 합니다.

관련 문서

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

내부 문서 (사이트 내)

외부 참고 자료

표준 사양서

• JEDEC JESD220F: UFS 4.0 표준 사양서 — SCSI 커맨드 매핑, 디스크립터, 전원 관리, Write Booster, HPB 전체 정의
• JEDEC JESD223E: UFS Host Controller Interface (UFSHCI) 4.0 사양서 — UTRD, UTMRD, MCQ, 레지스터 맵 정의 (UFS 4.1은 JESD220G/JESD223F, UFS 5.0은 JESD220H/JESD223G)
• MIPI M-PHY v5.0: UFS 물리 계층 사양 — HS/PWM 모드, Gear/Rate/Lane, 시그널링, 전기적 특성
• MIPI UniPro v2.0: UFS 전송 계층 사양 — Data Link, Network, Transport 레이어, E2E 플로우 컨트롤
• JEDEC UFS 표준 페이지 — UFS 관련 JEDEC 표준(JESD220, JESD223) 문서 목록 및 정보를 제공합니다
• MIPI M-PHY 사양 — UFS 물리 계층의 공식 사양으로, HS/PWM Gear 및 시그널링을 정의합니다
• MIPI UniPro 사양 — UFS 전송 계층(Data Link, Network, Transport)의 공식 사양입니다

커널 문서 및 소스 코드

• 커널 Documentation/scsi/ufs.rst: UFS 드라이버 개발자 문서, sysfs 속성 설명
• 커널 Documentation/ABI/testing/sysfs-driver-ufs: sysfs ABI 정의 문서
• 커널 공식 UFS 문서 — 리눅스 커널 UFS 드라이버의 공식 문서입니다
• drivers/ufs/core/ (Bootlin Elixir) — UFS 코어 드라이버(ufshcd, MCQ, sysfs, crypto) 소스 코드를 탐색할 수 있습니다
• drivers/ufs/host/ (Bootlin Elixir) — Qualcomm, MediaTek, Samsung 등 플랫폼별 UFS 호스트 드라이버입니다
• ufs-qcom.c (Bootlin) — Qualcomm UFS 호스트 드라이버: ICE, QMP PHY, Testbus, MCQ 리소스 매핑
• ufs-exynos.c (Bootlin) — Samsung Exynos UFS 호스트 드라이버: FMP 인라인 암호화, PHY PMA 캘리브레이션
• ufs-mediatek.c (Bootlin) — MediaTek UFS 호스트 드라이버: VA09 레귤레이터, MPHY 캘리브레이션, 클럭 게이팅
• ufs-hisi.c (Bootlin) — HiSilicon Kirin UFS 호스트 드라이버: 다단계 PHY 초기화, SoC 리비전별 분기
• ufs-renesas.c (Bootlin) — Renesas R-Car Gen4 UFS 호스트 드라이버: 자동차 등급 UFS
• include/ufs/ufshci.h (Bootlin) — UFSHCI 레지스터 오프셋, UTRD/UTMRD 구조체 정의입니다
• include/ufs/ufs.h (Bootlin) — UFS 벤더 ID 정의(UFS_VENDOR_SAMSUNG 등), 디바이스 quirk 플래그, UPIU 구조체
• ufshpb.c 변경 이력 (kernel.org) — HPB(Host Performance Booster) 코어 구현 이력. 커널 5.15 병합, 6.6에서 제거됨
• qcom-ice.c (Bootlin) — Qualcomm ICE(Inline Crypto Engine) 공통 드라이버: 키슬롯 프로그래밍

기술 문서 및 분석 기사

• LWN: Multi-circular queues for UFS (2022) — UFS MCQ(Multi-Circular Queue) 지원의 커널 구현을 다루는 기사입니다
• LWN: Inline encryption and UFS (2021) — UFS 인라인 암호화(ICE) 엔진의 커널 통합을 설명합니다
• 커널 Documentation/block/inline-encryption.rst: blk-crypto 프레임워크, 키슬롯 관리, ICE/FMP 통합 방식 설명
• 커널 Documentation/devicetree/bindings/ufs/: 벤더별 UFS DT 바인딩 스키마 (qcom,ufs / samsung,exynos-ufs / mediatek,ufs 등)
• 커널 Documentation/phy/: PHY 서브시스템 개요, QMP PHY / Exynos UFS PHY 드라이버 구조

커널 소스 읽기 순서

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

1단계: 헤더 및 프로토콜 정의

1. include/ufs/ufs.h — UFS 프로토콜 상수, UPIU 구조체, 디스크립터 IDN, 전원 모드, 벤더 ID 정의(UFS_VENDOR_SAMSUNG 등), 디바이스 quirk 플래그
2. include/ufs/ufshci.h — UFSHCI 레지스터 오프셋, UTRD/UTMRD 구조체, OCS 코드 정의
3. include/ufs/ufshcd.h — struct ufs_hba, struct ufs_hba_variant_ops(vops) 정의, quirk 플래그 적용 매크로

2단계: 코어 드라이버

4. drivers/ufs/core/ufshcd.c — UFS 호스트 컨트롤러 드라이버 코어 (초기화, I/O 경로, 에러 핸들링, PM, ufs_fixups[] 테이블)
5. drivers/ufs/core/ufs-mcq.c — Multi-Circular Queue 구현 (SQ/CQ 관리, 큐 매핑)
6. drivers/ufs/core/ufs-sysfs.c — sysfs 속성 정의 및 읽기/쓰기 핸들러
7. drivers/ufs/core/ufshcd-crypto.c — 인라인 암호화(ICE) 키 프로그래밍 및 crypto 프로파일
8. drivers/ufs/core/ufshpb.c — HPB 코어 구현(L2P 캐시 관리, Region 전환) — 커널 6.6에서 삭제됨, 과거 코드 이해용

3단계: 플랫폼별 드라이버 (벤더 심층 분석 대응)

9. drivers/ufs/host/ufs-qcom.c — Qualcomm: ICE 키 프로그래밍, QMP PHY 연동, Testbus 덤프, MCQ 리소스 매핑, DevFreq 스케일링
10. drivers/ufs/host/ufs-exynos.c — Samsung Exynos: FMP(PRDT 기반 암호화), PMA PHY 캘리브레이션, TXHSLV/RXHSLV 조정, EOM
11. drivers/ufs/host/ufs-mediatek.c — MediaTek: VA09 레귤레이터 시퀀싱, 다단계 클럭 게이팅, 전용 Crypto IP 초기화
12. drivers/ufs/host/ufs-hisi.c — HiSilicon: Kirin SoC PHY 다단계 초기화, Hi3660/Hi3670 리비전별 분기
13. drivers/ufs/host/ufs-renesas.c — Renesas: R-Car Gen4 자동차 등급 PHY, Auto-Hibernate 정책
14. drivers/ufs/host/ufshcd-pci.c — Intel/PCI: PCI 기반 UFS, LTR 설정, VID/DID 매칭

4단계: 관련 서브시스템

15. drivers/soc/qcom/ice.c — Qualcomm ICE 공통 드라이버 (키슬롯 레지스터 접근, Wrapped Key 처리)
16. drivers/phy/qualcomm/phy-qcom-qmp-ufs.c — QMP UFS PHY 드라이버 (SoC별 캘리브레이션 테이블)
17. drivers/phy/samsung/phy-exynos-ufs.c — Exynos UFS PHY 드라이버 (PMA 레지스터, EOM 구현)

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

1. SCSI 미들레이어가 scsi_cmnd를 전달 → ufshcd_queuecommand()
2. UPIU 구성
   • ufshcd_comp_devman_upiu() (Query/NOP)
   • ufshcd_comp_scsi_upiu() (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
grep -n "ufs_hba_exynos_ops" drivers/ufs/host/ufs-exynos.c
grep -n "ufs_hba_mtk_vops" drivers/ufs/host/ufs-mediatek.c

# 6. 디바이스 Quirks 테이블 — 벤더별 워크어라운드 확인
grep -n "ufs_fixups\[\]" drivers/ufs/core/ufshcd.c

# 7. ICE 키 프로그래밍 흐름
grep -n "program_key" drivers/ufs/host/ufs-qcom.c
grep -n "qcom_ice_program_key" drivers/soc/qcom/ice.c

# 8. FMP PRDT 확장 구조
grep -n "fmp\|FMP" drivers/ufs/host/ufs-exynos.c

# 9. 벤더 ID 및 quirk 플래그 정의
grep -n "UFS_VENDOR_\|UFS_DEVICE_QUIRK_" include/ufs/ufs.h