디바이스 드라이버 (Device Drivers)

Linux 커널 디바이스 드라이버: character/block/network 디바이스, platform driver, DMA 종합 가이드.

디바이스 드라이버 개요

디바이스 드라이버는 커널과 하드웨어 사이의 인터페이스입니다. Linux에서는 세 가지 주요 디바이스 유형으로 분류합니다:

Character Device 드라이버

#include <linux/cdev.h>
#include <linux/fs.h>
#include <linux/device.h>

static dev_t dev_num;
static struct cdev my_cdev;
static struct class *my_class;

static int my_open(struct inode *inode, struct file *file)
{
    pr_info("device opened\n");
    return 0;
}

static ssize_t my_read(struct file *file,
    char __user *buf, size_t len, loff_t *off)
{
    char msg[] = "Hello from driver\n";
    if (*off >= sizeof(msg))
        return 0;
    if (copy_to_user(buf, msg + *off, min(len, sizeof(msg) - *off)))
        return -EFAULT;
    *off += len;
    return len;
}

static const struct file_operations my_fops = {
    .owner = THIS_MODULE,
    .open  = my_open,
    .read  = my_read,
};

static int __init my_init(void)
{
    alloc_chrdev_region(&dev_num, 0, 1, "mydev");
    cdev_init(&my_cdev, &my_fops);
    cdev_add(&my_cdev, dev_num, 1);
    my_class = class_create("mydev_class");
    device_create(my_class, NULL, dev_num, NULL, "mydev");
    return 0;
}

Platform Driver

Platform Device 개념

PCI, USB 등 자동 열거(enumeration)가 가능한 버스와 달리, SoC(System-on-Chip) 내장 컨트롤러(UART, SPI, I2C, GPIO, 타이머 등)는 버스 프로토콜로 디바이스를 발견할 수 없습니다. 커널은 이러한 디바이스를 위해 Platform Bus라는 가상 버스를 제공합니다. Platform Bus는 실제 하드웨어 버스가 아니라, device-driver 매칭 인프라를 재사용하기 위한 소프트웨어 추상화입니다.

Platform Device의 하드웨어 정보(레지스터 주소, IRQ 번호 등)는 세 가지 방식으로 커널에 전달됩니다:

struct platform_device 분석

struct platform_device는 platform bus에 연결된 디바이스 하나를 나타냅니다. include/linux/platform_device.h에 정의되어 있습니다.

struct platform_device {
    const char      *name;          /* 디바이스 이름 (name 매칭에 사용) */
    int             id;             /* 인스턴스 번호 (-1이면 단일) */
    struct device   dev;            /* 임베디드 generic device */
    struct resource *resource;       /* I/O, 메모리, IRQ 리소스 배열 */
    u32             num_resources;  /* resource 배열 크기 */
    const struct platform_device_id *id_entry; /* 매칭된 id_table 항목 */
    const char      *driver_override; /* 강제 드라이버 바인딩 */
};

핵심 필드별 용도:

struct resource는 디바이스의 하드웨어 리소스를 기술합니다:

struct resource {
    resource_size_t start;  /* 리소스 시작 주소/번호 */
    resource_size_t end;    /* 리소스 끝 주소/번호 (inclusive) */
    const char      *name;
    unsigned long   flags;  /* 리소스 유형 */
};

/* 주요 리소스 유형 플래그 */
IORESOURCE_MEM   /* MMIO 메모리 영역 */
IORESOURCE_IRQ   /* 인터럽트 번호 */
IORESOURCE_DMA   /* DMA 채널 */
IORESOURCE_IO    /* I/O 포트 (x86) */

struct platform_driver 분석

struct platform_driver는 platform device를 다루는 드라이버를 나타냅니다:

struct platform_driver {
    int  (*probe)(struct platform_device *);    /* 디바이스 발견 시 호출 */
    void (*remove)(struct platform_device *);   /* 디바이스 제거 시 호출 */
    void (*shutdown)(struct platform_device *); /* reboot/poweroff 시 호출 */
    int  (*suspend)(struct platform_device *, pm_message_t); /* 레거시 PM */
    int  (*resume)(struct platform_device *);   /* 레거시 PM */
    struct device_driver driver;   /* 임베디드 generic driver */
    const struct platform_device_id *id_table; /* name+data 기반 매칭 */
    bool prevent_deferred_probe;
};

driver 필드의 주요 하위 필드:

id_table은 이름 기반 매칭에 사용되며, 드라이버별 데이터를 전달할 수 있습니다:

struct platform_device_id {
    char name[PLATFORM_NAME_SIZE];
    kernel_ulong_t driver_data;  /* 드라이버별 private 데이터 */
};

/* 사용 예: 여러 변형 디바이스를 하나의 드라이버로 지원 */
enum { CHIP_V1, CHIP_V2, CHIP_V3 };

static const struct platform_device_id my_ids[] = {
    { "my-chip-v1", CHIP_V1 },
    { "my-chip-v2", CHIP_V2 },
    { "my-chip-v3", CHIP_V3 },
    { }  /* sentinel */
};

매칭 메커니즘

Platform Bus의 platform_match() 함수는 다음 4단계 우선순위로 device-driver 매칭을 수행합니다:

커널 내부의 platform_match() 핵심 로직:

/* drivers/base/platform.c */
static int platform_match(struct device *dev, struct device_driver *drv)
{
    struct platform_device *pdev = to_platform_device(dev);
    struct platform_driver *pdrv = to_platform_driver(drv);

    /* 1단계: driver_override (sysfs 강제 바인딩) */
    if (pdev->driver_override)
        return !strcmp(pdev->driver_override, drv->name);

    /* 2단계: Device Tree compatible 매칭 */
    if (of_driver_match_device(dev, drv))
        return 1;

    /* 3단계: ACPI 매칭 */
    if (acpi_driver_match_device(dev, drv))
        return 1;

    /* 4단계: id_table 매칭 */
    if (pdrv->id_table)
        return platform_match_id(pdrv->id_table, pdev) != NULL;

    /* 5단계: driver.name 문자열 매칭 (fallback) */
    return (strcmp(pdev->name, drv->name) == 0);
}

각 매칭 방식별 드라이버 정의 예제:

/* Device Tree 매칭 (가장 일반적) */
static const struct of_device_id my_of_ids[] = {
    { .compatible = "vendor,my-ctrl-v2", .data = &chip_v2_data },
    { .compatible = "vendor,my-ctrl-v1", .data = &chip_v1_data },
    { }
};
MODULE_DEVICE_TABLE(of, my_of_ids);

/* ACPI 매칭 */
static const struct acpi_device_id my_acpi_ids[] = {
    { "VNDR0001", (kernel_ulong_t)&chip_v1_data },
    { "VNDR0002", (kernel_ulong_t)&chip_v2_data },
    { }
};
MODULE_DEVICE_TABLE(acpi, my_acpi_ids);

static struct platform_driver my_driver = {
    .probe  = my_probe,
    .remove = my_remove,
    .driver = {
        .name           = "my-ctrl",
        .of_match_table = my_of_ids,
        .acpi_match_table = ACPI_PTR(my_acpi_ids),
    },
};

Platform Device 등록

Platform Device가 커널에 등록되는 세 가지 경로:

1. 정적 등록 (레거시 보드 파일)

DT 이전의 ARM 보드에서 사용하던 방식입니다. 현재는 비권장이지만 레거시 코드에서 여전히 볼 수 있습니다:

/* 레거시 보드 파일 (arch/arm/mach-xxx/) */
static struct resource my_resources[] = {
    [0] = {
        .start = 0x40000000,
        .end   = 0x40000FFF,
        .flags = IORESOURCE_MEM,
    },
    [1] = {
        .start = 42,   /* IRQ 번호 */
        .end   = 42,
        .flags = IORESOURCE_IRQ,
    },
};

static struct platform_device my_pdev = {
    .name          = "my-ctrl",
    .id            = -1,
    .resource      = my_resources,
    .num_resources = ARRAY_SIZE(my_resources),
};

/* 보드 초기화 함수에서 */
platform_device_register(&my_pdev);

편의 함수로 간결하게 등록할 수도 있습니다:

/* 간편 등록 함수들 */
platform_device_register_simple("my-ctrl", -1, my_resources, 2);
platform_device_register_data(NULL, "my-ctrl", -1, &pdata, sizeof(pdata));
platform_device_register_resndata(NULL, "my-ctrl", -1,
    my_resources, 2, &pdata, sizeof(pdata));

2. Device Tree 기반 자동 생성

현대 임베디드 시스템의 표준 방식입니다. 부팅 시 커널이 DTB를 파싱하여 of_platform_populate()로 platform_device를 자동 생성합니다:

/* 커널 부팅 시 자동 실행 (drivers/of/platform.c) */
of_platform_default_populate(NULL, NULL, NULL);
    → DT의 최상위 "simple-bus" / "simple-mfd" 등의 자식 노드를
      순회하며 of_platform_device_create() 호출
    → struct platform_device 자동 생성 + 등록

3. ACPI 기반 자동 생성

x86 및 ARM 서버에서 ACPI 테이블의 디바이스 정보로 platform_device를 자동 생성합니다:

/* ACPI 열거 — DSDT/SSDT의 Device() 오브젝트가 platform_device로 변환
 *
 * ACPI 네임스페이스 예:
 *   Device (MYCT) {
 *       Name (_HID, "VNDR0001")
 *       Name (_CRS, ResourceTemplate() {
 *           Memory32Fixed(ReadWrite, 0x40000000, 0x1000)
 *           Interrupt(ResourceConsumer, ...) { 42 }
 *       })
 *   }
 *
 * → acpi_default_enumeration()이 platform_device로 변환
 */

probe/remove 생명주기

probe()는 device-driver 매칭이 성공했을 때 커널이 호출하는 진입점입니다. remove()는 디바이스 언바인드 또는 드라이버 언로드 시 역순으로 정리합니다.

probe 호출 조건:

• 디바이스가 등록될 때 이미 드라이버가 로드되어 있으면 즉시 호출
• 드라이버가 등록될 때 이미 디바이스가 존재하면 즉시 호출
• 둘 다 존재하고 platform_match()가 성공해야 함

probe 전형적 순서:

static int my_probe(struct platform_device *pdev)
{
    struct my_priv *priv;
    void __iomem *base;
    int irq, ret;

    /* 1. private 데이터 할당 */
    priv = devm_kzalloc(&pdev->dev, sizeof(*priv), GFP_KERNEL);
    if (!priv)
        return -ENOMEM;

    /* 2. 리소스 획득 — MMIO */
    base = devm_platform_ioremap_resource(pdev, 0);
    if (IS_ERR(base))
        return PTR_ERR(base);
    priv->base = base;

    /* 3. 리소스 획득 — IRQ */
    irq = platform_get_irq(pdev, 0);
    if (irq < 0)
        return irq;  /* 에러 코드 전파 */

    ret = devm_request_irq(&pdev->dev, irq, my_irq_handler,
                           0, dev_name(&pdev->dev), priv);
    if (ret)
        return ret;

    /* 4. 클록, 리셋, 레귤레이터 등 하드웨어 리소스 */
    priv->clk = devm_clk_get_enabled(&pdev->dev, NULL);
    if (IS_ERR(priv->clk))
        return dev_err_probe(&pdev->dev, PTR_ERR(priv->clk),
                              "failed to get clock\n");

    /* 5. 하드웨어 초기화 */
    writel(CTRL_ENABLE, base + REG_CTRL);

    /* 6. 서브시스템 등록 (misc device, input, net 등) */
    ret = misc_register(&priv->miscdev);
    if (ret)
        return ret;

    /* 7. private 데이터를 디바이스에 연결 */
    platform_set_drvdata(pdev, priv);

    dev_info(&pdev->dev, "probed successfully\n");
    return 0;
}

remove — 역순 정리:

static void my_remove(struct platform_device *pdev)
{
    struct my_priv *priv = platform_get_drvdata(pdev);

    /* probe의 역순으로 정리 */
    misc_deregister(&priv->miscdev);

    /* devm_ 계열 리소스는 자동 해제되므로 별도 처리 불필요 */
    /* devm_kzalloc, devm_request_irq, devm_ioremap 등 */
}

shutdown 콜백:

shutdown()은 시스템 reboot 또는 poweroff 시 호출됩니다. DMA 전송 중단, 인터럽트 비활성화 등 하드웨어를 안전한 상태로 전환합니다:

static void my_shutdown(struct platform_device *pdev)
{
    struct my_priv *priv = platform_get_drvdata(pdev);

    /* 하드웨어를 안전한 상태로 전환 */
    writel(0, priv->base + REG_CTRL);      /* 컨트롤러 비활성화 */
    disable_irq(priv->irq);                /* 인터럽트 차단 */
}

리소스 접근 API

Platform 드라이버에서 디바이스의 하드웨어 리소스에 접근하는 API들:

사용 예제:

/* 인덱스 기반 접근 */
struct resource *mem = platform_get_resource(pdev, IORESOURCE_MEM, 0);
int irq = platform_get_irq(pdev, 0);

/* 이름 기반 접근 (DT에서 reg-names, interrupt-names 지정 시) */
struct resource *cfg = platform_get_resource_byname(pdev, IORESOURCE_MEM, "config");
int tx_irq = platform_get_irq_byname(pdev, "tx");
int rx_irq = platform_get_irq_byname(pdev, "rx");

/* 리소스 획득 + ioremap 통합 (권장) */
void __iomem *base = devm_platform_ioremap_resource(pdev, 0);
if (IS_ERR(base))
    return PTR_ERR(base);

/* private 데이터 저장/조회 */
platform_set_drvdata(pdev, priv);          /* probe에서 */
struct my_priv *p = platform_get_drvdata(pdev);  /* remove 등에서 */

편의 매크로

module_platform_driver()는 모듈 init/exit 보일러플레이트를 자동 생성합니다:

/* include/linux/platform_device.h */
#define module_platform_driver(__platform_driver) \
    module_driver(__platform_driver, platform_driver_register, \
                  platform_driver_unregister)

/* 위 매크로는 아래와 동일한 코드를 생성 */
static int __init my_driver_init(void)
{
    return platform_driver_register(&my_driver);
}
module_init(my_driver_init);

static void __exit my_driver_exit(void)
{
    platform_driver_unregister(&my_driver);
}
module_exit(my_driver_exit);

관련 편의 매크로들:

MODULE_DEVICE_TABLE()은 modules.alias 파일에 항목을 추가하여, 디바이스 발견 시 udev가 해당 모듈을 자동 로드할 수 있게 합니다:

/* 드라이버 코드 */
static const struct of_device_id my_of_ids[] = {
    { .compatible = "vendor,my-ctrl" },
    { }
};
MODULE_DEVICE_TABLE(of, my_of_ids);

/* → /lib/modules/.../modules.alias 에 추가됨:
 *   alias of:N*T*Cvendor,my-ctrlC* my_driver
 * → DT에 "vendor,my-ctrl" 노드가 있으면 udev가 my_driver.ko 자동 로드
 */

sysfs 인터페이스

Platform Bus는 sysfs를 통해 사용자 공간에 노출됩니다:

# Platform Bus 디렉토리 구조
/sys/bus/platform/
├── devices/              # 등록된 모든 platform device 심볼릭 링크
│   ├── 40000000.uart → ../../../devices/platform/40000000.uart
│   ├── 40010000.spi  → ../../../devices/platform/40010000.spi
│   └── ...
└── drivers/              # 등록된 모든 platform driver
    ├── my-ctrl/
    │   ├── bind          # 디바이스 이름 기록 시 수동 바인딩
    │   ├── unbind        # 디바이스 이름 기록 시 언바인딩
    │   ├── module → ../../../../module/my_ctrl
    │   └── 40000000.uart → ../../../../devices/platform/40000000.uart
    └── ...

수동 드라이버 바인딩/언바인딩:

# 디바이스를 현재 드라이버에서 분리
echo "40000000.uart" > /sys/bus/platform/drivers/my-ctrl/unbind

# driver_override로 다른 드라이버 강제 지정
echo "other-driver" > /sys/devices/platform/40000000.uart/driver_override

# 새 드라이버에 수동 바인딩
echo "40000000.uart" > /sys/bus/platform/drivers/other-driver/bind

# driver_override 해제 (빈 문자열 기록)
echo "" > /sys/devices/platform/40000000.uart/driver_override

완전한 Platform Driver 예제:

#include <linux/module.h>
#include <linux/platform_device.h>
#include <linux/of.h>
#include <linux/io.h>
#include <linux/clk.h>
#include <linux/interrupt.h>

struct my_priv {
    void __iomem   *base;
    struct clk     *clk;
    int            irq;
};

static irqreturn_t my_irq_handler(int irq, void *data)
{
    struct my_priv *priv = data;
    u32 status = readl(priv->base + REG_STATUS);

    if (!(status & IRQ_PENDING))
        return IRQ_NONE;

    writel(status, priv->base + REG_STATUS);  /* ACK */
    return IRQ_HANDLED;
}

static int my_probe(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;
    struct my_priv *priv;

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

    priv->base = devm_platform_ioremap_resource(pdev, 0);
    if (IS_ERR(priv->base))
        return PTR_ERR(priv->base);

    priv->irq = platform_get_irq(pdev, 0);
    if (priv->irq < 0)
        return priv->irq;

    priv->clk = devm_clk_get_enabled(dev, NULL);
    if (IS_ERR(priv->clk))
        return dev_err_probe(dev, PTR_ERR(priv->clk), "clk failed\n");

    return devm_request_irq(dev, priv->irq, my_irq_handler,
                            0, dev_name(dev), priv);
}

static const struct of_device_id my_of_ids[] = {
    { .compatible = "vendor,my-ctrl-v2" },
    { .compatible = "vendor,my-ctrl" },
    { }
};
MODULE_DEVICE_TABLE(of, my_of_ids);

static struct platform_driver my_driver = {
    .probe  = my_probe,
    .driver = {
        .name           = "my-ctrl",
        .of_match_table = my_of_ids,
    },
};
module_platform_driver(my_driver);

MODULE_DESCRIPTION("My Platform Controller Driver");
MODULE_LICENSE("GPL");
MODULE_AUTHOR("Author Name");

DMA (Direct Memory Access)

#include <linux/dma-mapping.h>

/* Coherent DMA (CPU 캐시와 일관성 보장) */
void *buf = dma_alloc_coherent(dev, size, &dma_handle, GFP_KERNEL);
dma_free_coherent(dev, size, buf, dma_handle);

/* Streaming DMA (방향 지정, 캐시 sync 필요) */
dma_addr_t dma = dma_map_single(dev, buf, size, DMA_TO_DEVICE);
/* ... DMA 전송 ... */
dma_unmap_single(dev, dma, size, DMA_TO_DEVICE);

Linux 디바이스 모델 (Device Model)

Linux 디바이스 모델은 커널 2.6에서 도입된 통합 프레임워크로, 모든 디바이스와 드라이버를 bus → device → driver의 계층으로 추상화합니다. 이 모델은 kobject 인프라 위에 구축되며, sysfs(/sys/)를 통해 사용자 공간에 노출됩니다. udev/systemd-udevd가 디바이스 이벤트를 수신하고, 전원 관리(PM)와 핫플러그가 일관된 인터페이스로 동작합니다.

struct device — 모든 디바이스의 기반

struct device는 커널에 등록되는 모든 디바이스의 공통 기반 구조체입니다. PCI, USB, platform, I2C 등 각 버스별 디바이스 구조체(pci_dev, usb_device, platform_device 등)는 이 구조체를 임베디드합니다.

/* include/linux/device.h (핵심 필드 발췌) */
struct device {
    struct kobject           kobj;           /* sysfs 디렉토리 노드 */
    struct device           *parent;         /* 부모 디바이스 (물리적 계층) */
    const struct device_type *type;          /* 디바이스 타입 (선택적) */

    struct bus_type         *bus;            /* 소속 버스 */
    struct device_driver    *driver;         /* 바인딩된 드라이버 (NULL이면 미바인딩) */

    void                    *platform_data;  /* 보드 레벨 데이터 (레거시) */
    void                    *driver_data;    /* 드라이버 private 데이터 */

    struct device_node      *of_node;        /* Device Tree 노드 */
    struct fwnode_handle    *fwnode;         /* 통합 FW 노드 (DT/ACPI) */

    struct class            *class;          /* 디바이스 클래스 (net, block 등) */
    dev_t                    devt;           /* /dev 노드 번호 (major:minor) */

    const struct dev_pm_ops *pm;             /* 전원 관리 콜백 */
    struct dev_pm_info       power;          /* PM 런타임 상태 */

    struct dma_map_ops      *dma_ops;        /* DMA 매핑 연산 */
    u64                     *dma_mask;       /* DMA 주소 마스크 */
    u64                      coherent_dma_mask;

    struct list_head         devres_head;    /* devm 리소스 리스트 */
};

주요 도우미 함수:

/* 디바이스 등록/해제 */
int device_register(struct device *dev);    /* device_initialize + device_add */
void device_unregister(struct device *dev); /* device_del + put_device */

/* 참조 카운팅 */
struct device *get_device(struct device *dev);  /* kobject_get 래퍼 */
void put_device(struct device *dev);              /* kobject_put 래퍼 */

/* driver_data 접근 */
void *dev_get_drvdata(const struct device *dev);
void dev_set_drvdata(struct device *dev, void *data);

/* 로깅 (dev_name 자동 포함) */
dev_err(&dev, "error: %d\n", ret);
dev_warn(&dev, "warning\n");
dev_info(&dev, "initialized\n");
dev_dbg(&dev, "debug message\n");
dev_err_probe(&dev, ret, "deferred 시 dbg, 그 외 err\n");

struct device_driver — 드라이버 공통 구조체

struct device_driver는 모든 드라이버의 공통 기반입니다. 버스별 드라이버 구조체(pci_driver, platform_driver 등)가 이를 임베디드합니다.

/* include/linux/device/driver.h */
struct device_driver {
    const char              *name;           /* 드라이버 이름 */
    const struct bus_type   *bus;            /* 소속 버스 */
    struct module           *owner;          /* THIS_MODULE */

    const struct of_device_id   *of_match_table;   /* DT compatible 매칭 */
    const struct acpi_device_id *acpi_match_table; /* ACPI HID 매칭 */

    int  (*probe)(struct device *dev);           /* 버스별 probe가 호출 */
    void (*remove)(struct device *dev);          /* 언바인딩 시 호출 */
    void (*shutdown)(struct device *dev);        /* reboot/poweroff 시 */

    const struct dev_pm_ops *pm;                 /* PM 콜백 */
    const struct attribute_group **dev_groups;    /* 드라이버 sysfs 속성 */

    bool suppress_bind_attrs;  /* bind/unbind sysfs 파일 숨김 */
    enum probe_type probe_type; /* PROBE_DEFAULT_STRATEGY / PROBE_FORCE_SYNCHRONOUS */
};

struct bus_type — 버스 추상화

struct bus_type은 PCI, USB, Platform, I2C 등 버스 유형을 추상화합니다. 각 버스는 자신만의 device-driver 매칭 규칙과 probe 메커니즘을 정의합니다.

/* include/linux/device/bus.h */
struct bus_type {
    const char          *name;      /* 버스 이름 (sysfs: /sys/bus/NAME/) */
    const char          *dev_name;  /* 디바이스 이름 생성 접두어 */

    /* 핵심 콜백 */
    int  (*match)(struct device *dev, struct device_driver *drv);
    int  (*probe)(struct device *dev);
    void (*remove)(struct device *dev);
    void (*shutdown)(struct device *dev);

    /* uevent 환경변수 추가 (udev용) */
    int  (*uevent)(const struct device *dev, struct kobj_uevent_env *env);

    /* PM 콜백 */
    const struct dev_pm_ops *pm;

    /* 내부 데이터 */
    struct subsys_private *p;  /* klist_devices, klist_drivers, kset 등 */
};

/* 버스 등록/해제 */
int bus_register(const struct bus_type *bus);
void bus_unregister(const struct bus_type *bus);

커널에 등록된 주요 버스:

struct class — 디바이스 분류

struct class는 기능별로 디바이스를 분류합니다. 버스(bus)가 물리적 연결을 나타낸다면, 클래스(class)는 논리적 기능을 나타냅니다. 같은 PCI 버스에 연결된 디바이스라도 네트워크 카드는 net 클래스, 그래픽 카드는 drm 클래스에 속합니다.

/* 클래스 정의 예 */
static const struct class my_class = {
    .name    = "my_subsystem",     /* /sys/class/my_subsystem/ */
    .devnode = my_devnode,           /* /dev 노드 이름/퍼미션 제어 */
};

/* 클래스 등록 */
int ret = class_register(&my_class);

/* 클래스 소속 디바이스 생성 — /dev 노드도 자동 생성 (udev 연동) */
struct device *dev = device_create(&my_class, parent,
                                    MKDEV(major, minor),
                                    priv, "my_dev%d", index);

/* 제거 */
device_destroy(&my_class, MKDEV(major, minor));
class_unregister(&my_class);

# sysfs에서 class 확인
/sys/class/
├── net/            # 네트워크 인터페이스 (eth0, wlan0, lo ...)
├── block/          # 블록 디바이스 (sda, nvme0n1 ...)
├── input/          # 입력 디바이스 (event0, mouse0 ...)
├── tty/            # 터미널 디바이스 (ttyS0, ttyUSB0 ...)
├── drm/            # GPU (card0, renderD128 ...)
├── hwmon/          # 하드웨어 모니터링 (hwmon0 ...)
├── gpio/           # GPIO 칩과 라인
└── thermal/        # 열 관리 (thermal_zone0 ...)

# class 디바이스는 실제 디바이스로의 심볼릭 링크
$ ls -l /sys/class/net/eth0
lrwxrwxrwx ... eth0 -> ../../devices/pci0000:00/0000:00:1f.6/net/eth0

Device-Driver 바인딩 흐름

디바이스와 드라이버가 연결(bind)되는 과정은 디바이스 모델의 핵심 메커니즘입니다:

/* drivers/base/dd.c — 바인딩 핵심 흐름 (간략화) */
static int really_probe(struct device *dev, struct device_driver *drv)
{
    /* 1. dev->driver 설정 */
    dev->driver = drv;

    /* 2. 핀 설정 (pinctrl default state 적용) */
    pinctrl_bind_pins(dev);

    /* 3. DMA 설정 */
    dma_configure(dev);

    /* 4. probe 호출 — 버스 probe가 있으면 우선, 없으면 드라이버 probe */
    if (dev->bus->probe)
        ret = dev->bus->probe(dev);       /* platform_drv_probe() 등 */
    else if (drv->probe)
        ret = drv->probe(dev);

    /* 5. 결과 처리 */
    if (ret == -EPROBE_DEFER) {
        driver_deferred_probe_add(dev);  /* 재시도 큐에 추가 */
    } else if (ret == 0) {
        driver_bound(dev);               /* 바인딩 완료 */
        kobject_uevent(&dev->kobj, KOBJ_BIND);
    }
    return ret;
}

Deferred Probing (지연 프로빙)

커널 부팅 시 디바이스 간 의존성 때문에 probe 순서가 중요합니다. 예를 들어 SPI 컨트롤러 드라이버가 아직 로드되지 않은 상태에서 SPI 디바이스의 probe가 먼저 호출될 수 있습니다. 이때 -EPROBE_DEFER를 반환하면 커널이 해당 디바이스를 지연 큐(deferred probe list)에 넣고, 다른 probe가 성공할 때마다 재시도합니다.

static int my_probe(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;

    /* 의존하는 리소스가 아직 준비되지 않을 수 있음 */
    priv->clk = devm_clk_get(dev, NULL);
    if (IS_ERR(priv->clk)) {
        /* -EPROBE_DEFER이면 자동으로 재시도 큐에 추가됨 */
        return dev_err_probe(dev, PTR_ERR(priv->clk),
                              "failed to get clock\n");
    }

    priv->regulator = devm_regulator_get(dev, "vdd");
    if (IS_ERR(priv->regulator))
        return dev_err_probe(dev, PTR_ERR(priv->regulator),
                              "failed to get regulator\n");
    /* ... */
}

/* dev_err_probe()의 동작:
 *   - PTR_ERR가 -EPROBE_DEFER이면 → dev_dbg 수준 로깅 (dmesg 조용히)
 *   - 그 외 에러이면 → dev_err 수준 로깅
 *   - 두 경우 모두 에러 코드를 그대로 반환
 */

# 지연 프로빙 상태 확인
$ cat /sys/kernel/debug/devices_deferred
platform soc:spi@40010000: -517 (EPROBE_DEFER)
platform soc:i2c@40020000: -517 (EPROBE_DEFER)

# 부팅 완료 후에도 deferred 상태인 디바이스는 의존성 미해결
# 흔한 원인: 누락된 드라이버 모듈, DT 설정 오류, 순환 의존

fwnode — 통합 펌웨어 노드

struct fwnode_handle은 Device Tree와 ACPI를 통합하는 추상화 계층입니다. 하나의 드라이버 코드로 DT 환경(ARM)과 ACPI 환경(x86 서버) 모두를 지원할 수 있습니다.

#include <linux/property.h>

/* fwnode 통합 API — DT/ACPI 구분 없이 프로퍼티 접근 */
static int my_probe(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;
    u32 freq;
    const char *label;

    /* DT: device_property → of_property_read_u32 */
    /* ACPI: device_property → acpi_dev_get_property */
    if (device_property_read_u32(dev, "clock-frequency", &freq))
        freq = 100000;  /* 기본값 */

    if (device_property_read_string(dev, "label", &label))
        label = "default";

    /* 불리언 프로퍼티 (존재 여부만 확인) */
    bool wakeup = device_property_read_bool(dev, "wakeup-source");

    /* 배열 프로퍼티 */
    u32 regs[4];
    device_property_read_u32_array(dev, "reg-offsets", regs, 4);

    /* 자식 노드 순회 */
    struct fwnode_handle *child;
    device_for_each_child_node(dev, child) {
        u32 addr;
        fwnode_property_read_u32(child, "reg", &addr);
        /* ... 자식 디바이스 설정 ... */
    }
    return 0;
}

fwnode 통합 API 주요 함수:

struct device_type — 디바이스 세분화

device_type은 같은 버스에 속하지만 유형이 다른 디바이스를 구분합니다. USB 버스에서 디바이스(usb_device)와 인터페이스(usb_interface)가 대표적 예입니다.

struct device_type {
    const char *name;                           /* uevent DEVTYPE= 값 */
    const struct attribute_group **groups;       /* 추가 sysfs 속성 */
    int  (*uevent)(const struct device *, struct kobj_uevent_env *);
    char *(*devnode)(const struct device *, umode_t *, kuid_t *, kgid_t *);
    void (*release)(struct device *);
    const struct dev_pm_ops *pm;
};

/* 예: 블록 디바이스에서 disk_type과 partition_type 구분 */
/* net_device에서 이더넷, Wi-Fi, 브리지 등 구분 */
/* udev 규칙에서 DEVTYPE으로 매칭:
 *   SUBSYSTEM=="net", DEVTYPE=="wlan", ... */

디바이스 모델 전체 계층 구조

커스텀 버스 구현 예제

드라이버 서브시스템 개발자를 위한 커스텀 버스 타입 구현 예제입니다:

/* 커스텀 버스: 간단한 ID 기반 매칭 */
struct mybus_device {
    struct device dev;
    u32 device_id;
    const char *name;
};

struct mybus_driver {
    struct device_driver driver;
    const u32 *id_table;        /* 지원하는 device_id 배열 */
    int  (*probe)(struct mybus_device *);
    void (*remove)(struct mybus_device *);
};

/* match 콜백: device_id와 드라이버의 id_table 비교 */
static int mybus_match(struct device *dev, struct device_driver *drv)
{
    struct mybus_device *mdev = container_of(dev, struct mybus_device, dev);
    struct mybus_driver *mdrv = container_of(drv, struct mybus_driver, driver);

    for (const u32 *id = mdrv->id_table; *id; id++) {
        if (*id == mdev->device_id)
            return 1;  /* 매칭 성공 */
    }
    return 0;
}

/* probe 콜백: 버스 레벨에서 드라이버의 probe 호출 */
static int mybus_probe(struct device *dev)
{
    struct mybus_device *mdev = container_of(dev, struct mybus_device, dev);
    struct mybus_driver *mdrv = container_of(dev->driver,
                                              struct mybus_driver, driver);
    return mdrv->probe(mdev);
}

/* uevent: udev에 MYBUS_ID 환경변수 전달 */
static int mybus_uevent(const struct device *dev,
                        struct kobj_uevent_env *env)
{
    const struct mybus_device *mdev =
        container_of(dev, struct mybus_device, dev);
    return add_uevent_var(env, "MYBUS_ID=%u", mdev->device_id);
}

static const struct bus_type mybus_type = {
    .name   = "mybus",
    .match  = mybus_match,
    .probe  = mybus_probe,
    .uevent = mybus_uevent,
};

/* 초기화: /sys/bus/mybus/ 생성 */
bus_register(&mybus_type);

sysfs 디바이스 모델 전체 맵

# /sys 최상위 구조와 디바이스 모델의 관계
/sys/
├── bus/                    # 버스 타입별 디렉토리
│   ├── platform/
│   │   ├── devices/        # 등록된 platform device → /sys/devices/ 심링크
│   │   ├── drivers/        # 등록된 platform driver (bind/unbind 포함)
│   │   ├── drivers_autoprobe  # 1이면 자동 바인딩 활성
│   │   └── uevent          # 버스 레벨 uevent 트리거
│   ├── pci/
│   ├── usb/
│   ├── i2c/
│   └── spi/
│
├── devices/                # 물리적 디바이스 트리 (실제 디렉토리)
│   ├── platform/           # platform bus 디바이스
│   │   └── 40000000.uart/
│   │       ├── driver → ../../../bus/platform/drivers/my-uart
│   │       ├── of_node → ../../../firmware/devicetree/...
│   │       ├── uevent
│   │       ├── power/      # PM 런타임 상태
│   │       └── ...
│   ├── pci0000:00/         # PCI 호스트 브리지
│   │   └── 0000:00:1f.6/   # PCI 디바이스
│   │       ├── net/eth0/   # 네트워크 인터페이스
│   │       └── ...
│   └── system/             # CPU, 메모리 등 시스템 디바이스
│       ├── cpu/
│       └── memory/
│
├── class/                  # 기능별 디바이스 분류 (심링크)
│   ├── net/
│   │   └── eth0 → ../../devices/pci0000:00/.../net/eth0
│   ├── block/
│   └── tty/
│
├── firmware/               # 펌웨어 노드 (DT, ACPI, DMI)
│   ├── devicetree/         # Device Tree 노드 트리
│   └── acpi/               # ACPI 테이블/네임스페이스
│
└── module/                 # 로드된 커널 모듈
    └── my_driver/
        ├── parameters/     # 모듈 파라미터
        └── drivers/        # 이 모듈이 등록한 드라이버 심링크

커널 Notifier Chain (이벤트 통지 체인)

Linux 커널은 다양한 서브시스템 간에 이벤트를 전파하기 위해 Notifier Chain 메커니즘을 제공합니다. 이는 Observer(관찰자) / Publish-Subscribe 패턴의 커널 구현으로, 특정 이벤트가 발생했을 때 미리 등록된 콜백 함수들을 순차적으로 호출합니다. CPU hotplug, 네트워크 디바이스 상태 변경, reboot, panic 등 커널의 핵심 이벤트 대부분이 이 메커니즘을 통해 전파됩니다.

Notifier Chain 개요

Notifier Chain의 핵심은 struct notifier_block입니다. 이벤트를 수신하려는 서브시스템은 콜백 함수와 우선순위를 담은 notifier_block을 체인에 등록하고, 이벤트 발생 시 체인에 등록된 모든 콜백이 우선순위 순서대로 호출됩니다.

/* include/linux/notifier.h */
struct notifier_block {
    notifier_fn_t notifier_call;  /* 콜백 함수 포인터 */
    struct notifier_block __rcu *next;  /* 다음 블록 (우선순위 정렬 연결 리스트) */
    int priority;  /* 우선순위 (높을수록 먼저 호출, 기본값 0) */
};

/* 콜백 함수 시그니처 */
typedef int (*notifier_fn_t)(struct notifier_block *nb,
                            unsigned long action, void *data);

콜백 함수의 매개변수:

• nb: 현재 호출 중인 notifier_block 포인터 (container_of로 상위 구조체 접근 가능)
• action: 이벤트 유형 (예: NETDEV_UP, NETDEV_DOWN)
• data: 이벤트별 추가 데이터 (예: struct net_device *)

Notifier Chain 4가지 유형

커널은 사용 컨텍스트에 따라 4가지 유형의 Notifier Chain을 제공합니다. 각 유형은 잠금 메커니즘과 호출 가능한 컨텍스트가 다릅니다.

/* 각 유형의 헤드 구조체 (include/linux/notifier.h) */
struct atomic_notifier_head {
    spinlock_t lock;
    struct notifier_block __rcu *head;
};

struct blocking_notifier_head {
    struct rw_semaphore rwsem;
    struct notifier_block __rcu *head;
};

struct raw_notifier_head {
    struct notifier_block __rcu *head;
};

struct srcu_notifier_head {
    struct mutex mutex;
    struct srcu_struct srcu;
    struct notifier_block __rcu *head;
};

각 유형별 초기화 매크로:

/* 정적 초기화 매크로 */
ATOMIC_NOTIFIER_HEAD(my_atomic_chain);
BLOCKING_NOTIFIER_HEAD(my_blocking_chain);
RAW_NOTIFIER_HEAD(my_raw_chain);

/* SRCU는 동적 초기화 필요 */
struct srcu_notifier_head my_srcu_chain;
srcu_init_notifier_head(&my_srcu_chain);

/* 동적 초기화 함수 (atomic/blocking/raw에도 사용 가능) */
ATOMIC_INIT_NOTIFIER_HEAD(&my_atomic_chain);
BLOCKING_INIT_NOTIFIER_HEAD(&my_blocking_chain);
RAW_INIT_NOTIFIER_HEAD(&my_raw_chain);

Notifier Chain API 상세

모든 유형은 동일한 패턴의 API를 따릅니다. {type}_notifier_chain_register(), {type}_notifier_chain_unregister(), {type}_notifier_call_chain()으로 구성됩니다.

등록 / 해제

/* Atomic Notifier Chain */
int atomic_notifier_chain_register(struct atomic_notifier_head *nh,
                                    struct notifier_block *nb);
int atomic_notifier_chain_unregister(struct atomic_notifier_head *nh,
                                      struct notifier_block *nb);

/* Blocking Notifier Chain */
int blocking_notifier_chain_register(struct blocking_notifier_head *nh,
                                      struct notifier_block *nb);
int blocking_notifier_chain_unregister(struct blocking_notifier_head *nh,
                                        struct notifier_block *nb);

/* Raw Notifier Chain */
int raw_notifier_chain_register(struct raw_notifier_head *nh,
                                  struct notifier_block *nb);
int raw_notifier_chain_unregister(struct raw_notifier_head *nh,
                                    struct notifier_block *nb);

/* SRCU Notifier Chain */
int srcu_notifier_chain_register(struct srcu_notifier_head *nh,
                                   struct notifier_block *nb);
int srcu_notifier_chain_unregister(struct srcu_notifier_head *nh,
                                     struct notifier_block *nb);

모든 등록 함수는 성공 시 0을 반환합니다. 등록 시 notifier_block은 우선순위 내림차순으로 연결 리스트에 삽입됩니다 (높은 priority가 먼저 호출됨).

통지 호출

/* 체인의 모든 콜백을 호출 */
int atomic_notifier_call_chain(struct atomic_notifier_head *nh,
                                unsigned long val, void *v);
int blocking_notifier_call_chain(struct blocking_notifier_head *nh,
                                  unsigned long val, void *v);
int raw_notifier_call_chain(struct raw_notifier_head *nh,
                              unsigned long val, void *v);
int srcu_notifier_call_chain(struct srcu_notifier_head *nh,
                               unsigned long val, void *v);

콜백 반환값

콜백 함수는 다음 상수 중 하나를 반환해야 합니다:

/* call_chain()의 반환값에서 errno 추출 */
static inline int notifier_to_errno(int ret)
{
    ret &= ~NOTIFY_STOP_MASK;
    return ret > NOTIFY_OK ? ret - 1 : 0;
}

/* errno를 notifier 반환값으로 변환 */
static inline int notifier_from_errno(int err)
{
    if (err)
        return NOTIFY_STOP_MASK | (NOTIFY_OK - err);
    return NOTIFY_OK;
}

커널 주요 Notifier Chain 목록

다음은 커널에서 가장 자주 사용되는 주요 Notifier Chain입니다:

Notifier Chain 동작 흐름

실전 구현 예제

예제 1: 네트워크 디바이스 Notifier

네트워크 인터페이스의 상태 변경(UP/DOWN)을 감지하는 가장 일반적인 notifier 사용 예제입니다:

#include <linux/module.h>
#include <linux/netdevice.h>
#include <linux/notifier.h>

static int my_netdev_event(struct notifier_block *nb,
                            unsigned long event, void *ptr)
{
    struct net_device *dev = netdev_notifier_info_to_dev(ptr);

    switch (event) {
    case NETDEV_UP:
        pr_info("netdev UP: %s (ifindex=%d)\n",
                dev->name, dev->ifindex);
        break;
    case NETDEV_DOWN:
        pr_info("netdev DOWN: %s (ifindex=%d)\n",
                dev->name, dev->ifindex);
        break;
    case NETDEV_REGISTER:
        pr_info("netdev REGISTER: %s\n", dev->name);
        break;
    case NETDEV_UNREGISTER:
        pr_info("netdev UNREGISTER: %s\n", dev->name);
        break;
    default:
        break;
    }

    return NOTIFY_DONE;
}

static struct notifier_block my_netdev_nb = {
    .notifier_call = my_netdev_event,
    .priority = 0,
};

static int __init my_notifier_init(void)
{
    int ret;

    ret = register_netdevice_notifier(&my_netdev_nb);
    if (ret) {
        pr_err("netdev notifier 등록 실패: %d\n", ret);
        return ret;
    }

    pr_info("netdev notifier 등록 완료\n");
    return 0;
}

static void __exit my_notifier_exit(void)
{
    unregister_netdevice_notifier(&my_netdev_nb);
    pr_info("netdev notifier 해제 완료\n");
}

module_init(my_notifier_init);
module_exit(my_notifier_exit);
MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("Network device notifier example");

예제 2: 커스텀 Notifier Chain 정의 및 사용

자체 Notifier Chain을 정의하여 모듈 간 이벤트를 전파하는 예제입니다:

#include <linux/module.h>
#include <linux/notifier.h>

/* ===== 이벤트 정의 (공유 헤더에 배치) ===== */
#define MY_EVENT_START    0x01
#define MY_EVENT_STOP     0x02
#define MY_EVENT_ERROR    0x03

struct my_event_data {
    const char *name;
    int code;
};

/* ===== 이벤트 발행 측 (Producer) ===== */
static BLOCKING_NOTIFIER_HEAD(my_event_chain);

/* 외부 모듈이 사용할 등록/해제 API */
int my_register_notifier(struct notifier_block *nb)
{
    return blocking_notifier_chain_register(&my_event_chain, nb);
}
EXPORT_SYMBOL_GPL(my_register_notifier);

int my_unregister_notifier(struct notifier_block *nb)
{
    return blocking_notifier_chain_unregister(&my_event_chain, nb);
}
EXPORT_SYMBOL_GPL(my_unregister_notifier);

/* 이벤트 발생 시 호출 */
void my_fire_event(unsigned long event, struct my_event_data *data)
{
    int ret;

    ret = blocking_notifier_call_chain(&my_event_chain, event, data);
    if (notifier_to_errno(ret))
        pr_warn("이벤트 %lu 처리 중 에러 발생\n", event);
}

/* ===== 이벤트 수신 측 (Consumer) ===== */
static int my_event_handler(struct notifier_block *nb,
                             unsigned long event, void *data)
{
    struct my_event_data *ev = data;

    switch (event) {
    case MY_EVENT_START:
        pr_info("[Consumer] START: name=%s, code=%d\n",
                ev->name, ev->code);
        return NOTIFY_OK;
    case MY_EVENT_ERROR:
        pr_err("[Consumer] ERROR: name=%s, code=%d\n",
               ev->name, ev->code);
        return notifier_from_errno(-EIO);  /* 에러 전파 */
    default:
        return NOTIFY_DONE;
    }
}

static struct notifier_block my_handler_nb = {
    .notifier_call = my_event_handler,
    .priority = 0,
};

static int __init consumer_init(void)
{
    return my_register_notifier(&my_handler_nb);
}

static void __exit consumer_exit(void)
{
    my_unregister_notifier(&my_handler_nb);
}

module_init(consumer_init);
module_exit(consumer_exit);
MODULE_LICENSE("GPL");

Notifier Chain 내부 구현

Notifier Chain의 핵심 구현은 kernel/notifier.c에 있습니다. 모든 유형이 공유하는 내부 함수를 살펴보겠습니다.

우선순위 기반 삽입

등록 시 notifier_chain_register()는 우선순위 내림차순으로 연결 리스트에 삽입합니다:

/* kernel/notifier.c — 핵심 내부 함수 (간략화) */
static int notifier_chain_register(
    struct notifier_block **nl,
    struct notifier_block *n)
{
    while (*nl != NULL) {
        if (unlikely((*nl) == n)) {
            WARN(1, "notifier already registered");
            return -EEXIST;
        }
        /* 우선순위 내림차순 정렬: 높은 값이 리스트 앞쪽 */
        if (n->priority > (*nl)->priority)
            break;
        nl = &((*nl)->next);
    }
    n->next = *nl;
    rcu_assign_pointer(*nl, n);
    return 0;
}

체인 순회 (call_chain)

/* kernel/notifier.c — 통지 순회 (간략화) */
static int notifier_call_chain(
    struct notifier_block **nl,
    unsigned long val, void *v,
    int nr_to_call, int *nr_calls)
{
    int ret = NOTIFY_DONE;
    struct notifier_block *nb, *next_nb;

    nb = rcu_dereference_raw(*nl);
    while (nb && nr_to_call) {
        next_nb = rcu_dereference_raw(nb->next);

        ret = nb->notifier_call(nb, val, v);

        if (nr_calls)
            (*nr_calls)++;

        /* NOTIFY_STOP_MASK이 설정되면 순회 중단 */
        if (ret & NOTIFY_STOP_MASK)
            break;

        nb = next_nb;
        nr_to_call--;
    }
    return ret;
}

각 유형별 잠금 차이

/* Atomic: spinlock으로 등록 보호, RCU로 순회 보호 */
int atomic_notifier_call_chain(struct atomic_notifier_head *nh,
                                unsigned long val, void *v)
{
    int ret;
    rcu_read_lock();
    ret = notifier_call_chain(&nh->head, val, v, -1, NULL);
    rcu_read_unlock();
    return ret;
}

/* Blocking: rw_semaphore로 등록/순회 모두 보호 */
int blocking_notifier_call_chain(struct blocking_notifier_head *nh,
                                  unsigned long val, void *v)
{
    int ret;
    if (rcu_access_pointer(nh->head)) {
        down_read(&nh->rwsem);
        ret = notifier_call_chain(&nh->head, val, v, -1, NULL);
        up_read(&nh->rwsem);
    } else {
        ret = NOTIFY_DONE;
    }
    return ret;
}

/* SRCU: Sleepable RCU로 순회 보호, mutex로 등록 보호 */
int srcu_notifier_call_chain(struct srcu_notifier_head *nh,
                               unsigned long val, void *v)
{
    int ret, idx;
    idx = srcu_read_lock(&nh->srcu);
    ret = notifier_call_chain(&nh->head, val, v, -1, NULL);
    srcu_read_unlock(&nh->srcu, idx);
    return ret;
}

주의사항 및 디버깅

흔한 실수와 해결책

Deadlock 시나리오 상세

/* 위험! Blocking notifier 콜백 내에서 동일 체인 수정 */
static int bad_callback(struct notifier_block *nb,
                         unsigned long event, void *data)
{
    /* call_chain()이 rwsem read-lock을 잡고 있는 상태에서
       unregister()가 write-lock을 요청 → DEADLOCK */
    blocking_notifier_chain_unregister(&chain, nb);  /* 절대 금지! */
    return NOTIFY_DONE;
}

/* 올바른 방법: workqueue로 지연 해제 */
static struct work_struct unreg_work;

static void deferred_unregister(struct work_struct *work)
{
    blocking_notifier_chain_unregister(&chain, &my_nb);
}

static int safe_callback(struct notifier_block *nb,
                          unsigned long event, void *data)
{
    if (event == SOME_FINAL_EVENT) {
        schedule_work(&unreg_work);  /* workqueue에서 안전하게 해제 */
        return NOTIFY_STOP;
    }
    return NOTIFY_DONE;
}

ftrace / bpftrace를 이용한 디버깅

# ftrace로 notifier_call_chain 호출 추적
echo 1 > /sys/kernel/debug/tracing/events/notifier/notifier_run/enable
echo 1 > /sys/kernel/debug/tracing/tracing_on
cat /sys/kernel/debug/tracing/trace_pipe

# bpftrace로 특정 notifier 호출 시간 측정
bpftrace -e '
kprobe:blocking_notifier_call_chain {
    @start[tid] = nsecs;
}
kretprobe:blocking_notifier_call_chain /@start[tid]/ {
    @latency_us = hist((nsecs - @start[tid]) / 1000);
    delete(@start[tid]);
}'

# 특정 체인에 등록된 notifier 확인 (debugfs)
# CONFIG_DEBUG_NOTIFIERS=y 필요
cat /sys/kernel/debug/notifier_chains

Block Device 드라이버

#include <linux/blkdev.h>
#include <linux/blk-mq.h>

static struct gendisk *my_disk;
static struct blk_mq_tag_set tag_set;

/* blk-mq 요청 처리 */
static blk_status_t my_queue_rq(struct blk_mq_hw_ctx *hctx,
    const struct blk_mq_queue_data *bd)
{
    struct request *rq = bd->rq;
    struct bio_vec bvec;
    struct req_iterator iter;

    blk_mq_start_request(rq);

    rq_for_each_segment(bvec, rq, iter) {
        sector_t sector = iter.iter.bi_sector;
        void *buf = page_address(bvec.bv_page) + bvec.bv_offset;
        unsigned len = bvec.bv_len;

        if (rq_data_dir(rq) == WRITE)
            memcpy(my_data + sector * 512, buf, len);
        else
            memcpy(buf, my_data + sector * 512, len);
    }

    blk_mq_end_request(rq, BLK_STS_OK);
    return BLK_STS_OK;
}

static const struct blk_mq_ops my_mq_ops = {
    .queue_rq = my_queue_rq,
};

Network Device 드라이버

#include <linux/netdevice.h>
#include <linux/etherdevice.h>

static netdev_tx_t my_start_xmit(struct sk_buff *skb,
    struct net_device *dev)
{
    /* 패킷을 하드웨어로 전송 */
    write_to_hw_tx_ring(skb->data, skb->len);

    dev->stats.tx_packets++;
    dev->stats.tx_bytes += skb->len;

    dev_kfree_skb(skb);
    return NETDEV_TX_OK;
}

static int my_net_open(struct net_device *dev)
{
    netif_start_queue(dev);
    napi_enable(&priv->napi);
    enable_hw_irq(priv);
    return 0;
}

static const struct net_device_ops my_netdev_ops = {
    .ndo_open       = my_net_open,
    .ndo_stop       = my_net_stop,
    .ndo_start_xmit = my_start_xmit,
    .ndo_get_stats64 = my_get_stats64,
};

Device Tree (DTS/DTB) 심화

Device Tree는 하드웨어 구성을 기술하는 데이터 구조로, PCI/USB처럼 자동 열거(enumeration)가 불가능한 SoC 내장 디바이스의 정보를 커널에 전달합니다. ARM, RISC-V, PowerPC 등 임베디드 플랫폼에서 필수적이며, Open Firmware(IEEE 1275) 표준에서 유래했습니다.

Device Tree 아키텍처

DTS 문법 상세

/*
 * Device Tree Source (.dts) 문법
 *
 * 기본 구조: 노드(node)와 프로퍼티(property)의 트리
 *
 * 노드 형식:
 *   [label:] node-name[@unit-address] {
 *       [properties];
 *       [child nodes];
 *   };
 *
 * 프로퍼티 데이터 타입:
 *   - 빈 값:          속성 존재만 의미 (boolean)
 *   - u32:           < 0x1234 >
 *   - u64:           /bits/ 64 < 0x1234567890 >
 *   - 문자열:         "hello"
 *   - 문자열 목록:     "first", "second"
 *   - 바이트 배열:     [00 11 22 33]
 *   - phandle 참조:   <&label>
 *   - 혼합:           < 0x1234 >, "string", [00 ff]
 */

/* ===== 완전한 DTS 예제 ===== */
/dts-v1/;

/* .dtsi 인클루드 — SoC 공통 정의 재사용 */
#include "my-soc.dtsi"
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/arm-gic.h>
#include <dt-bindings/clock/my-soc-clk.h>

/ {
    /* 루트 노드 — 보드 전체 정보 */
    model = "MyVendor MyBoard Rev.A";
    compatible = "myvendor,myboard", "myvendor,my-soc";

    /* #address-cells / #size-cells:
     * 자식 노드의 reg 프로퍼티 해석 방법 지정
     * #address-cells = <2> → 주소가 u32 × 2 = 64-bit
     * #size-cells = <1> → 크기가 u32 × 1 = 32-bit */
    #address-cells = <2>;
    #size-cells = <2>;

    /* chosen 노드 — 부트로더→커널 런타임 파라미터 */
    chosen {
        bootargs = "console=ttyS0,115200 root=/dev/mmcblk0p2 rw";
        stdout-path = "serial0:115200n8";
    };

    /* aliases — 노드에 짧은 이름 부여 */
    aliases {
        serial0 = &uart0;
        ethernet0 = ð0;
        mmc0 = &sdhci0;
    };

    /* memory 노드 — 물리 메모리 레이아웃 */
    memory@80000000 {
        device_type = "memory";
        reg = <0x0 0x80000000 0x0 0x40000000>;  /* 1 GiB @ 0x80000000 */
    };

    /* cpus 노드 */
    cpus {
        #address-cells = <1>;
        #size-cells = <0>;

        cpu@0 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x0>;
            enable-method = "psci";
            clocks = <&cpu_clk>;
            operating-points-v2 = <&cpu_opp_table>;
        };
        cpu@1 {
            device_type = "cpu";
            compatible = "arm,cortex-a53";
            reg = <0x1>;
            enable-method = "psci";
        };
    };

    /* SoC 버스 — 주소 공간 정의 */
    soc {
        compatible = "simple-bus";
        #address-cells = <1>;
        #size-cells = <1>;
        ranges = <0x0 0x0 0x0 0x40000000>;  /* 자식→부모 주소 변환 */

        /* 인터럽트 컨트롤러 */
        gic: interrupt-controller@1c81000 {
            compatible = "arm,gic-400";
            interrupt-controller;        /* 빈 프로퍼티 (boolean) */
            #interrupt-cells = <3>;     /* 자식의 interrupts 해석: type irq flags */
            reg = <0x1c81000 0x1000>,   /* GICD */
                  <0x1c82000 0x2000>;   /* GICC */
        };

        /* 클럭 컨트롤러 — phandle로 참조 */
        ccu: clock-controller@1c20000 {
            compatible = "myvendor,my-soc-ccu";
            reg = <0x1c20000 0x400>;
            clocks = <&osc24m>, <&osc32k>;
            clock-names = "hosc", "losc";
            #clock-cells = <1>;      /* 자식이 참조 시 인덱스 1개 */
            #reset-cells = <1>;
        };

        /* UART — label로 phandle 자동 생성 */
        uart0: serial@1c28000 {
            compatible = "myvendor,my-soc-uart", "snps,dw-apb-uart";
            reg = <0x1c28000 0x400>;
            interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>;
            clocks = <&ccu CLK_UART0>;
            resets = <&ccu RST_UART0>;
            reg-shift = <2>;
            reg-io-width = <4>;
            status = "okay";
        };

        /* I2C 컨트롤러 + 자식 디바이스 */
        i2c0: i2c@1c2ac00 {
            compatible = "myvendor,my-soc-i2c";
            reg = <0x1c2ac00 0x400>;
            interrupts = <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>;
            clocks = <&ccu CLK_I2C0>;
            resets = <&ccu RST_I2C0>;
            #address-cells = <1>;
            #size-cells = <0>;
            status = "okay";

            /* I2C 슬레이브 디바이스 */
            sensor@48 {
                compatible = "ti,tmp102";
                reg = <0x48>;          /* I2C 주소 */
                interrupt-parent = <&gic>;
                interrupts = <GIC_SPI 20 IRQ_TYPE_EDGE_FALLING>;
            };

            pmic@34 {
                compatible = "xpower,axp803";
                reg = <0x34>;
                interrupt-parent = <&gic>;
                interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_LOW>;

                /* 서브노드: PMIC 내 레귤레이터 */
                regulators {
                    reg_dcdc1: dcdc1 {
                        regulator-name = "vcc-3v3";
                        regulator-min-microvolt = <3300000>;
                        regulator-max-microvolt = <3300000>;
                        regulator-always-on;
                    };
                };
            };
        };
    };
};

표준 프로퍼티 레퍼런스

.dtsi 인클루드 구조와 오버라이드

/*
 * .dtsi (Device Tree Source Include) — SoC 공통 정의
 * .dts  — 보드별 최종 파일, .dtsi를 인클루드하고 오버라이드
 *
 * 계층 구조 예시:
 *   arch/arm64/boot/dts/
 *   ├── myvendor/
 *   │   ├── my-soc.dtsi          ← SoC 공통 (IP 블록, 클럭, 인터럽트)
 *   │   ├── my-soc-gpu.dtsi      ← GPU 관련 (선택적 인클루드)
 *   │   ├── myboard-rev-a.dts    ← 보드 A (오버라이드, 확장)
 *   │   └── myboard-rev-b.dts    ← 보드 B (다른 설정)
 *
 * 오버라이드 규칙:
 * - .dts에서 .dtsi의 노드를 재정의하면 프로퍼티가 병합/덮어쓰기
 * - &label 참조로 기존 노드를 수정 (노드 경로 생략 가능)
 */

/* === my-soc.dtsi (SoC 공통) === */
/ {
    soc {
        uart0: serial@1c28000 {
            compatible = "myvendor,my-soc-uart";
            reg = <0x1c28000 0x400>;
            clocks = <&ccu CLK_UART0>;
            status = "disabled";  /* 기본: 비활성 */
        };

        i2c0: i2c@1c2ac00 {
            compatible = "myvendor,my-soc-i2c";
            reg = <0x1c2ac00 0x400>;
            #address-cells = <1>;
            #size-cells = <0>;
            status = "disabled";
        };
    };
};

/* === myboard-rev-a.dts (보드별) === */
/dts-v1/;
#include "my-soc.dtsi"

/ {
    model = "MyBoard Rev.A";
};

/* &label 참조로 기존 노드 오버라이드 */
&uart0 {
    status = "okay";         /* 이 보드에서 UART0 활성화 */
    pinctrl-0 = <&uart0_pins>; /* 핀 설정 추가 */
    pinctrl-names = "default";
};

&i2c0 {
    status = "okay";

    /* 이 보드에 연결된 센서 추가 */
    accelerometer@1d {
        compatible = "st,lis3dh";
        reg = <0x1d>;
        interrupt-parent = <&gic>;
        interrupts = <GIC_SPI 25 IRQ_TYPE_EDGE_RISING>;
        vdd-supply = <®_3v3>;
    };
};

Device Tree Overlay

/*
 * Device Tree Overlay (.dtbo):
 *
 * 런타임에 기존 DTB에 노드/프로퍼티를 추가·수정·삭제합니다.
 * 용도:
 *   - HAT/Cape/Shield 등 확장 보드 자동 인식
 *   - Raspberry Pi, BeagleBone 등에서 광범위하게 사용
 *   - 재부팅 없이 하드웨어 구성 변경 (configfs 기반)
 *
 * Overlay 문법:
 *   /plugin/; 지시어로 overlay 파일임을 선언
 *   fragment 또는 __overlay__ 블록으로 수정할 노드 지정
 */

/* === my-hat-overlay.dts === */
/dts-v1/;
/plugin/;

/* &{/path} 또는 &label로 대상 노드 참조 */
&i2c0 {
    #address-cells = <1>;
    #size-cells = <0>;
    status = "okay";

    /* HAT에 장착된 OLED 디스플레이 */
    oled@3c {
        compatible = "solomon,ssd1306";
        reg = <0x3c>;
        width = <128>;
        height = <64>;
        solomon,com-invdir;
    };
};

/* fragment 문법 (대체 형식) */
/ {
    fragment@0 {
        target = <&spi0>;
        __overlay__ {
            status = "okay";
            cs-gpios = <&gpio 8 GPIO_ACTIVE_LOW>;

            can0: can@0 {
                compatible = "microchip,mcp2515";
                reg = <0>;
                spi-max-frequency = <10000000>;
                clocks = <&can_osc>;
                interrupt-parent = <&gpio>;
                interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
            };
        };
    };
};

# Overlay 컴파일
$ dtc -I dts -O dtb -@ -o my-hat.dtbo my-hat-overlay.dts
# -@ : __symbols__ 노드 생성 (overlay 심볼 해석에 필요)

# configfs를 통한 런타임 적용 (v4.4+)
$ mkdir -p /sys/kernel/config/device-tree/overlays/my-hat
$ cat my-hat.dtbo > /sys/kernel/config/device-tree/overlays/my-hat/dtbo
# → 커널이 overlay를 live DT에 병합, 새 디바이스 probe

# Overlay 제거
$ rmdir /sys/kernel/config/device-tree/overlays/my-hat
# → 관련 디바이스 remove, DT에서 노드 제거

# U-Boot에서 부팅 시 적용
# fdt apply ${fdtoverlay_addr}

Device Tree Bindings

/*
 * DT Binding = 특정 하드웨어에 필요한 프로퍼티 규격
 *
 * 위치: Documentation/devicetree/bindings/
 * 형식: YAML schema (dt-schema, v5.2+) 또는 텍스트 문서 (레거시)
 *
 * 검증 도구:
 *   make dt_binding_check    ← YAML 스키마 자체 검증
 *   make dtbs_check          ← DTB가 바인딩을 준수하는지 검증
 *
 * compatible 문자열 규칙:
 *   "vendor,device[-version]"
 *   vendor: JEDEC 또는 Documentation/devicetree/bindings/vendor-prefixes.yaml
 *   device: 구체적 칩/IP 이름
 *
 * 예시:
 *   "ti,am335x-uart"       ← TI AM335x SoC의 UART
 *   "samsung,exynos4210-i2c" ← Samsung Exynos4210의 I2C
 *   "snps,dw-apb-uart"     ← Synopsys DesignWare APB UART (IP 블록)
 */

# YAML 바인딩 예시: Documentation/devicetree/bindings/serial/snps,dw-apb-uart.yaml
# (간략화)

# $id: http://devicetree.org/schemas/serial/snps,dw-apb-uart.yaml#
# $schema: http://devicetree.org/meta-schemas/core.yaml#
# title: Synopsys DesignWare ABP UART
# 
# properties:
#   compatible:
#     oneOf:
#       - items:
#           - enum:
#               - myvendor,my-soc-uart
#           - const: snps,dw-apb-uart
#   reg:
#     maxItems: 1
#   interrupts:
#     maxItems: 1
#   clocks:
#     minItems: 1
#     maxItems: 2
#   clock-names:
#     items:
#       - const: baudclk
#       - const: apb_pclk
#   reg-shift:
#     enum: [0, 2]
# 
# required:
#   - compatible
#   - reg
#   - interrupts
#   - clocks

# 바인딩 검증 실행
$ make dt_binding_check DT_SCHEMA_FILES=serial/snps,dw-apb-uart.yaml
$ make dtbs_check DT_SCHEMA_FILES=serial/snps,dw-apb-uart.yaml

DTS 컴파일과 디컴파일

# ===== DTS → DTB 컴파일 =====

# 커널 빌드 시스템을 통해 (권장)
$ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- dtbs
# → arch/arm64/boot/dts/myvendor/*.dtb 생성

# 특정 DTB만 빌드
$ make ARCH=arm64 myvendor/myboard-rev-a.dtb

# DTB 설치
$ make ARCH=arm64 INSTALL_DTBS_PATH=/boot/dtbs dtbs_install

# dtc 직접 사용
$ dtc -I dts -O dtb -o myboard.dtb myboard.dts
# -I: 입력 형식 (dts, dtb, fs)
# -O: 출력 형식 (dts, dtb, asm)

# ===== DTB → DTS 디컴파일 =====
$ dtc -I dtb -O dts -o decompiled.dts myboard.dtb

# 실행 중인 시스템의 live DT 디컴파일
$ dtc -I fs -O dts -o live-dt.dts /sys/firmware/devicetree/base/

# ===== DTB 정보 조회 =====
$ fdtdump myboard.dtb | head -50        # 구조 덤프
$ fdtget myboard.dtb /soc/serial@1c28000 compatible
myvendor,my-soc-uart snps,dw-apb-uart
$ fdtget -t x myboard.dtb /soc/serial@1c28000 reg
1c28000 400

# DTB 수정 (디버깅/테스트용)
$ fdtput myboard.dtb /soc/serial@1c28000 status -ts "disabled"

# ===== CPP 전처리 =====
# 커널 빌드 시스템은 DTS를 dtc에 전달하기 전에 C 전처리기(cpp)를 먼저 실행합니다.
# 따라서 #include, #define, #ifdef 등 C 전처리 지시어가 DTS에서 동작합니다.
#
# dt-bindings/ 헤더: include/dt-bindings/ 디렉토리의 .h 파일
# → GPIO, 인터럽트, 클럭 등의 숫자 상수를 매크로로 정의
# 예: #include <dt-bindings/gpio/gpio.h>
#     GPIO_ACTIVE_HIGH = 0, GPIO_ACTIVE_LOW = 1

커널 OF(Open Firmware) API

#include <linux/of.h>
#include <linux/of_device.h>
#include <linux/of_address.h>
#include <linux/of_irq.h>
#include <linux/of_gpio.h>

/* ===== 프로퍼티 읽기 ===== */

u32 val;
of_property_read_u32(np, "my-prop", &val);       /* u32 1개 */

u32 arr[4];
of_property_read_u32_array(np, "my-array", arr, 4); /* u32 배열 */

u64 val64;
of_property_read_u64(np, "my-u64", &val64);    /* u64 */

const char *str;
of_property_read_string(np, "label", &str);    /* 문자열 */

int count = of_property_read_string_helper(      /* 문자열 목록 */
    np, "clock-names", NULL, 0, 0);

bool present = of_property_read_bool(np, "big-endian"); /* boolean */

/* ===== 노드 탐색 ===== */

struct device_node *child;
for_each_child_of_node(np, child) {             /* 자식 순회 */
    /* child 처리... */
}

struct device_node *node;
node = of_find_compatible_node(NULL, NULL,
    "myvendor,my-device");                        /* compatible로 검색 */

node = of_find_node_by_path("/soc/serial@1c28000"); /* 경로로 검색 */

node = of_parse_phandle(np, "clocks", 0);       /* phandle 참조 해석 */

/* ===== 리소스 가져오기 ===== */

struct resource res;
of_address_to_resource(np, 0, &res);            /* reg → struct resource */
void __iomem *base = of_iomap(np, 0);          /* reg → ioremap */

int irq = of_irq_get(np, 0);                    /* interrupts → IRQ 번호 */
int irq2 = platform_get_irq(pdev, 0);           /* platform 래퍼 (권장) */

/* ===== compatible 매칭 확인 ===== */

bool match = of_device_is_compatible(np, "vendor,dev");

const struct of_device_id *id;
id = of_match_device(my_of_ids, &pdev->dev);
if (id && id->data) {
    /* match-specific 데이터 사용 */
    const struct my_hw_data *hw = id->data;
}

Device Tree + Platform Driver 통합

/* ===== 완전한 DT 기반 Platform Driver 예제 ===== */

#include <linux/module.h>
#include <linux/platform_device.h>
#include <linux/of.h>
#include <linux/of_device.h>
#include <linux/clk.h>
#include <linux/reset.h>
#include <linux/io.h>

/* 칩 버전별 데이터 */
struct my_hw_data {
    int fifo_depth;
    bool has_dma;
};

static const struct my_hw_data hw_v1 = { .fifo_depth = 16, .has_dma = false };
static const struct my_hw_data hw_v2 = { .fifo_depth = 64, .has_dma = true  };

/* of_device_id: compatible 문자열 → 드라이버 매칭 테이블 */
static const struct of_device_id my_of_ids[] = {
    { .compatible = "myvendor,my-device-v1", .data = &hw_v1 },
    { .compatible = "myvendor,my-device-v2", .data = &hw_v2 },
    { /* sentinel */ }
};
MODULE_DEVICE_TABLE(of, my_of_ids);

struct my_dev {
    void __iomem *base;
    struct clk *clk;
    struct reset_control *rst;
    const struct my_hw_data *hw;
    int irq;
};

static int my_probe(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;
    struct my_dev *priv;
    u32 fifo_thr;
    int ret;

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

    /* 1. compatible에 연결된 하드웨어 데이터 가져오기 */
    priv->hw = of_device_get_match_data(dev);
    if (!priv->hw)
        return -ENODEV;

    /* 2. reg → MMIO 매핑 (devm 관리) */
    priv->base = devm_platform_ioremap_resource(pdev, 0);
    if (IS_ERR(priv->base))
        return PTR_ERR(priv->base);

    /* 3. interrupts → IRQ 번호 */
    priv->irq = platform_get_irq(pdev, 0);
    if (priv->irq < 0)
        return priv->irq;

    /* 4. clocks → 클럭 가져오기 + 활성화 */
    priv->clk = devm_clk_get_enabled(dev, NULL);  /* v6.3+ */
    if (IS_ERR(priv->clk))
        return dev_err_probe(dev, PTR_ERR(priv->clk),
                             "failed to get clock\n");

    /* 5. resets → 리셋 제어 */
    priv->rst = devm_reset_control_get_exclusive(dev, NULL);
    if (IS_ERR(priv->rst))
        return PTR_ERR(priv->rst);
    reset_control_deassert(priv->rst);

    /* 6. 커스텀 프로퍼티 읽기 (선택적, 기본값 지원) */
    ret = of_property_read_u32(dev->of_node, "fifo-threshold", &fifo_thr);
    if (ret)
        fifo_thr = priv->hw->fifo_depth / 2;  /* DT에 없으면 기본값 */

    platform_set_drvdata(pdev, priv);

    dev_info(dev, "probed: fifo=%d dma=%d irq=%d\n",
             priv->hw->fifo_depth, priv->hw->has_dma, priv->irq);
    return 0;
}

static void my_remove(struct platform_device *pdev)
{
    struct my_dev *priv = platform_get_drvdata(pdev);
    reset_control_assert(priv->rst);
}

static struct platform_driver my_driver = {
    .probe  = my_probe,
    .remove = my_remove,
    .driver = {
        .name = "my-device",
        .of_match_table = my_of_ids,         /* DT 매칭 테이블 등록 */
        .pm = &my_pm_ops,                    /* 전원 관리 (선택) */
    },
};
module_platform_driver(my_driver);

/*
 * 매칭 순서 (우선순위):
 * 1. of_match_table  — Device Tree compatible 매칭
 * 2. acpi_match_table — ACPI _HID 매칭
 * 3. id_table         — platform_device_id 이름 매칭
 * 4. driver.name      — platform_device.name 직접 비교 (폴백)
 */

특수 노드와 고급 패턴

/* ===== 주요 특수 노드들 ===== */

/* 1. reserved-memory — 커널이 사용하지 않을 메모리 영역 */
reserved-memory {
    #address-cells = <2>;
    #size-cells = <2>;
    ranges;

    /* CMA (Contiguous Memory Allocator) 영역 */
    linux,cma {
        compatible = "shared-dma-pool";
        reusable;
        size = <0x0 0x10000000>;   /* 256 MiB */
        linux,cma-default;
    };

    /* 펌웨어 전용 영역 */
    fw_reserved: framebuffer@be000000 {
        reg = <0x0 0xbe000000 0x0 0x2000000>;
        no-map;                  /* 커널이 매핑하지 않음 */
    };
};

/* 2. GPIO hog — 부팅 시 GPIO를 고정 상태로 설정 */
&gpio1 {
    led-hog {
        gpio-hog;
        gpios = <10 GPIO_ACTIVE_HIGH>;
        output-high;
        line-name = "status-led";
    };
};

/* 3. 클럭/레귤레이터 고정 정의 (물리 클럭을 DT에서 선언) */
osc24m: oscillator-24m {
    compatible = "fixed-clock";
    #clock-cells = <0>;
    clock-frequency = <24000000>;     /* 24 MHz */
    clock-output-names = "osc24m";
};

reg_3v3: regulator-3v3 {
    compatible = "regulator-fixed";
    regulator-name = "vcc-3v3";
    regulator-min-microvolt = <3300000>;
    regulator-max-microvolt = <3300000>;
    regulator-always-on;
};

/* 4. OPP (Operating Performance Points) 테이블 */
cpu_opp_table: opp-table {
    compatible = "operating-points-v2";

    opp-600000000 {
        opp-hz = /bits/ 64 <600000000>;
        opp-microvolt = <900000>;
    };
    opp-1200000000 {
        opp-hz = /bits/ 64 <1200000000>;
        opp-microvolt = <1100000>;
    };
    opp-1800000000 {
        opp-hz = /bits/ 64 <1800000000>;
        opp-microvolt = <1300000>;
        opp-suspend;                 /* suspend 시 이 OPP 사용 */
    };
};

/* 5. 인터럽트 매핑 (interrupt-map) — PCI 등 */
pcie@10000000 {
    interrupt-map-mask = <0x1800 0 0 7>;
    interrupt-map =
        <0x0000 0 0 1 &gic GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>,
        <0x0000 0 0 2 &gic GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>;
};

Device Tree 디버깅

# ===== 실행 중인 시스템에서 DT 확인 =====

# Live Device Tree (procfs)
$ ls /proc/device-tree/
#address-cells  cpus     memory@80000000  soc
#size-cells     chosen   model            compatible

# 특정 노드의 프로퍼티 읽기
$ cat /proc/device-tree/model
MyVendor MyBoard Rev.A
$ hexdump -C /proc/device-tree/soc/serial@1c28000/reg
00000000  01 c2 80 00 00 00 04 00

# sysfs를 통한 접근 (동일한 데이터)
$ ls /sys/firmware/devicetree/base/
$ cat /sys/firmware/devicetree/base/compatible

# ===== 커널 로그에서 DT 관련 메시지 =====
$ dmesg | grep -iE 'device.?tree|of_|dts|dtb|compatible'
OF: fdt: Machine model: MyVendor MyBoard Rev.A
OF: fdt: Ignoring memory range 0x0 - 0x80000000

# ===== probe 실패 디버깅 =====

# 매칭되지 않은(드라이버 없는) 디바이스 확인
$ ls /sys/bus/platform/devices/
# 1c28000.serial  1c2ac00.i2c  ...

# 특정 디바이스의 드라이버 바인딩 상태
$ ls -la /sys/bus/platform/devices/1c28000.serial/driver
# symlink → 해당 드라이버 (없으면 매칭 실패)

# deferred probe 목록 (의존성 대기 중)
$ cat /sys/kernel/debug/devices_deferred
# 1c2ac00.i2c  ← 클럭/레귤레이터 등 의존성 미충족

# 드라이버 강제 바인드/언바인드
$ echo "1c28000.serial" > /sys/bus/platform/drivers/my-device/bind
$ echo "1c28000.serial" > /sys/bus/platform/drivers/my-device/unbind

# ===== Overlay 상태 확인 =====
$ ls /sys/kernel/config/device-tree/overlays/
my-hat/
$ cat /sys/kernel/config/device-tree/overlays/my-hat/status
applied

# ===== ftrace로 DT 매칭 추적 =====
$ echo 1 > /sys/kernel/tracing/events/bus/bus_add_device/enable
$ echo 1 > /sys/kernel/tracing/events/bus/driver_bound/enable
$ cat /sys/kernel/tracing/trace_pipe
# bus_add_device: device 1c28000.serial
# driver_bound: device 1c28000.serial driver my-device

# ===== DT Validation (빌드 시) =====
$ make ARCH=arm64 dt_binding_check    # YAML 스키마 검증
$ make ARCH=arm64 dtbs_check          # DTB vs 바인딩 검증
$ make ARCH=arm64 W=1 dtbs            # 경고 활성화 빌드

FDT 바이너리 포맷 (Flattened Device Tree)

DTB 파일은 Flattened Device Tree(FDT) 바이너리 포맷으로 저장됩니다. 부트로더가 이 바이너리를 메모리에 로드하고, 커널의 unflatten_device_tree()가 파싱하여 struct device_node 트리를 구축합니다.

/* ===== FDT 헤더 구조체 (include/linux/libfdt_env.h → scripts/dtc/libfdt/) ===== */

struct fdt_header {
    fdt32_t magic;             /* 0xD00DFEED (big-endian) */
    fdt32_t totalsize;          /* DTB 전체 크기 (bytes) */
    fdt32_t off_dt_struct;      /* Structure Block 시작 오프셋 */
    fdt32_t off_dt_strings;     /* Strings Block 시작 오프셋 */
    fdt32_t off_mem_rsvmap;     /* Memory Reservation Block 오프셋 */
    fdt32_t version;            /* 포맷 버전 (현재 17) */
    fdt32_t last_comp_version;  /* 호환 가능한 최소 버전 (16) */
    fdt32_t boot_cpuid_phys;   /* 부팅 CPU의 physical ID */
    fdt32_t size_dt_strings;   /* Strings Block 크기 */
    fdt32_t size_dt_struct;    /* Structure Block 크기 */
};

/* FDT는 모두 big-endian으로 저장됨 — cpu_to_fdt32() / fdt32_to_cpu() 로 변환 */

/* ===== Structure Block 토큰 ===== */
#define FDT_BEGIN_NODE  0x00000001  /* 노드 시작 + 이름(NUL종료, 4-byte 정렬) */
#define FDT_END_NODE    0x00000002  /* 노드 종료 */
#define FDT_PROP        0x00000003  /* 프로퍼티: len(u32) + nameoff(u32) + data */
#define FDT_NOP         0x00000004  /* 무시 (편집 시 패딩용) */
#define FDT_END         0x00000009  /* Structure Block 종료 */

/* ===== Memory Reservation Block =====
 * 커널이 사용하면 안 되는 물리 메모리 영역 (예: DTB 자체, 펌웨어 영역)
 * { uint64_t address; uint64_t size; } 쌍의 배열
 * address=0, size=0 엔트리로 종료
 *
 * 참고: reserved-memory DT 노드와 다름!
 * - Memory Reservation Block: FDT 바이너리 레벨, early boot에서 처리
 * - reserved-memory 노드: DT 노드 레벨, memblock 서브시스템에서 처리
 */

/* ===== FDT 프로퍼티 인코딩 예시 =====
 *
 * DTS: compatible = "myvendor,my-soc-uart", "snps,dw-apb-uart";
 *
 * Structure Block에 저장되는 바이너리:
 * [FDT_PROP]                       ← 0x00000003
 * [len = 39]                       ← 두 문자열 + NUL 포함 길이
 * [nameoff = 0]                    ← Strings Block에서 "compatible" 오프셋
 * "myvendor,my-soc-uart\0snps,dw-apb-uart\0"  ← 실제 데이터
 * [padding]                        ← 4-byte 정렬 맞춤
 *
 * DTS: reg = <0x1c28000 0x400>;
 *
 * [FDT_PROP]
 * [len = 8]                        ← u32 × 2 = 8 bytes
 * [nameoff = 11]                   ← Strings Block에서 "reg" 오프셋
 * [0x01C28000] [0x00000400]        ← big-endian u32 값들
 */

/* ===== 커널에서 FDT 직접 접근 (early boot) ===== */
#include <linux/of_fdt.h>

/* early_init_dt_scan(): 부팅 초기에 FDT에서 핵심 정보 추출 */
void __init early_init_dt_scan_nodes(void)
{
    /* chosen 노드에서 bootargs, initrd 위치 추출 */
    early_init_dt_scan_chosen(boot_command_line);

    /* /memory 노드에서 물리 메모리 범위 추출 → memblock에 등록 */
    early_init_dt_scan_memory();

    /* root 노드에서 #address-cells, #size-cells 가져오기 */
    early_init_dt_scan_root();
}

/* unflatten: FDT 바이너리 → struct device_node 트리 변환 */
void __init unflatten_device_tree(void)
{
    /* 1차 패스: 필요한 메모리 크기 계산 */
    /* 2차 패스: device_node + property 구조체 할당 및 연결 */
    __unflatten_device_tree(initial_boot_params, NULL,
                           &of_root, early_init_dt_alloc_memory_arch, false);

    /* of_root: 전역 루트 device_node 포인터 */
    /* /proc/device-tree/와 /sys/firmware/devicetree/base/로 노출 */
}

struct device_node / struct property 내부 구조

unflatten_device_tree() 완료 후 커널 메모리에 존재하는 자료구조입니다. 모든 of_* API는 이 구조체를 통해 DT 정보에 접근합니다.

/* include/linux/of.h */

struct device_node {
    const char *name;            /* 노드 이름 (@ 앞 부분) */
    phandle phandle;              /* 고유 식별자 (phandle 프로퍼티 값) */
    const char *full_name;        /* 전체 경로명 또는 name[@unit-address] */
    struct fwnode_handle fwnode;   /* 펌웨어 노드 추상화 (DT/ACPI 통합) */

    struct property *properties;  /* 프로퍼티 연결 리스트 헤드 */
    struct property *deadprops;   /* 제거된 프로퍼티 (overlay undo용) */

    /* 트리 탐색 포인터 */
    struct device_node *parent;   /* 부모 노드 */
    struct device_node *child;    /* 첫 번째 자식 */
    struct device_node *sibling;  /* 다음 형제 */

#if defined(CONFIG_OF_KOBJ)
    struct kobject kobj;           /* sysfs 표현 (/sys/firmware/devicetree/) */
#endif
    unsigned long _flags;          /* OF_POPULATED, OF_DETACHED 등 */
    void *data;                    /* 드라이버 private 데이터 */
};

/* 플래그 상수 */
#define OF_DYNAMIC       1  /* overlay로 동적 생성된 노드 */
#define OF_DETACHED      2  /* 트리에서 분리된 노드 */
#define OF_POPULATED     3  /* platform_device가 이미 생성됨 */
#define OF_POPULATED_BUS 4  /* 자식 디바이스들도 생성됨 */

struct property {
    char *name;                   /* 프로퍼티 이름 ("compatible", "reg" 등) */
    int length;                    /* 값의 바이트 길이 */
    void *value;                   /* 프로퍼티 값 (raw 바이트) */
    struct property *next;        /* 같은 노드의 다음 프로퍼티 */
#if defined(CONFIG_OF_DYNAMIC) || defined(CONFIG_SPARC)
    unsigned long _flags;
#endif
#if defined(CONFIG_OF_KOBJ)
    struct bin_attribute attr;    /* sysfs 바이너리 속성 */
#endif
};

/* ===== device_node 트리 순회 매크로 ===== */

/* 모든 자식 노드 순회 */
for_each_child_of_node(parent, child) { ... }

/* available(status != "disabled") 자식만 순회 */
for_each_available_child_of_node(parent, child) { ... }

/* 특정 compatible을 가진 노드만 순회 */
for_each_compatible_node(dn, type, compatible) { ... }

/* 특정 프로퍼티를 가진 노드 순회 */
for_each_node_with_property(dn, prop_name) { ... }

/* of_node 참조 카운팅 */
struct device_node *np = of_node_get(node);  /* refcount++ */
of_node_put(np);                                /* refcount-- */
/* for_each_* 매크로는 루프 내에서 자동으로 get/put 처리
 * 주의: break로 루프를 탈출하면 of_node_put()을 수동 호출해야 함! */

/* ===== 노드 → platform_device 변환 흐름 =====
 *
 * 1. unflatten_device_tree() → device_node 트리 구축
 * 2. of_platform_default_populate()
 *    → 루트의 direct children 중 compatible 있는 노드를 platform_device로 생성
 *    → "simple-bus", "simple-mfd", "isa", "arm,amba-bus" compatible의 노드는
 *       재귀적으로 자식도 platform_device로 생성
 * 3. 각 platform_device의 compatible과 등록된 platform_driver의 of_match_table 비교
 * 4. 매칭 성공 → driver->probe() 호출
 * 5. probe 시 의존성(clk, regulator 등) 미충족이면 -EPROBE_DEFER 반환
 *    → 나중에 재시도 (deferred probe)
 */

주소 변환 (Address Translation) 상세

Device Tree에서 각 버스 레벨마다 독립적인 주소 공간을 가집니다. ranges 프로퍼티가 자식 주소 공간 → 부모 주소 공간으로의 변환 규칙을 정의합니다.

/* ===== ranges 프로퍼티 해석 규칙 =====
 *
 * ranges = < child_addr  parent_addr  length >;
 *
 * - child_addr의 셀 수 = 현재 노드의 #address-cells
 * - parent_addr의 셀 수 = 부모 노드의 #address-cells
 * - length의 셀 수 = 현재 노드의 #size-cells
 * - 빈 ranges (ranges;) → 1:1 매핑 (주소 동일)
 * - ranges 없음 → 자식 주소를 부모 주소로 변환 불가 (독립 주소 공간)
 */

/* 예시 1: 단순 SoC 버스 — 오프셋 변환 */
/ {
    #address-cells = <2>;   /* 루트: 64-bit 주소 */
    #size-cells = <2>;

    soc {
        compatible = "simple-bus";
        #address-cells = <1>; /* SoC: 32-bit 주소 */
        #size-cells = <1>;
        /* child(1 cell)  parent(2 cells)  size(1 cell)
         * 0x0          → 0x0_0000_0000    1 GiB 범위 */
        ranges = <0x0  0x0 0x0  0x40000000>;

        /* serial의 reg 0x1c28000은:
         * child_addr = 0x01c28000
         * ranges 적용: 0x01c28000 + 0x0 = 0x0_01c28000 (CPU 물리 주소) */
        serial@1c28000 {
            reg = <0x1c28000 0x400>;
        };
    };
};

/* 예시 2: 다중 ranges — 여러 주소 윈도우 */
soc {
    #address-cells = <1>;
    #size-cells = <1>;
    ranges = <0x00000000  0x0 0x00000000  0x20000000>,  /* 0~512M: 1:1 */
             <0x40000000  0x0 0x40000000  0x20000000>;  /* 1G~1.5G */
};

/* 예시 3: PCI 주소 공간 (#address-cells = <3>) */
pcie@10000000 {
    compatible = "pci-host-ecam-generic";
    /* PCI는 #address-cells = 3: (phys.hi  phys.mid  phys.lo)
     * phys.hi 비트 구조:
     *   [31]    = relocatable
     *   [30:29] = 프리페치 (01=I/O, 10=32-bit MEM, 11=64-bit MEM)
     *   [24]    = prefetchable
     *   [23:16] = bus number
     *   [15:11] = device number
     *   [10:8]  = function number
     *   [7:0]   = register number */
    #address-cells = <3>;
    #size-cells = <2>;

    /* PCI 주소(3 cells) → CPU 주소(2 cells), 크기(2 cells) */
    ranges =
        /* I/O 공간: PCI I/O 0x0 → CPU 0x1000_0000, 64KiB */
        <0x01000000 0x0 0x00000000  0x0 0x10000000  0x0 0x00010000>,
        /* 32-bit MEM: PCI MEM 0x2000_0000 → CPU 0x2000_0000, 256MiB */
        <0x02000000 0x0 0x20000000  0x0 0x20000000  0x0 0x10000000>,
        /* 64-bit MEM (prefetchable): PCI 0x8_0000_0000 → CPU 0x8_0000_0000, 4GiB */
        <0x43000000 0x8 0x00000000  0x8 0x00000000  0x1 0x00000000>;
};

/* ===== 커널의 주소 변환 API ===== */
#include <linux/of_address.h>

/* of_translate_address(): DT 주소 → CPU 물리 주소 변환
 * ranges 체인을 루트까지 재귀적으로 따라가며 변환 */
u64 cpu_addr = of_translate_address(np, addr_prop);

/* of_address_to_resource(): reg → struct resource 변환
 * 내부적으로 of_translate_address() + 크기 정보 포함 */
struct resource res;
of_address_to_resource(np, 0, &res);  /* 첫 번째 reg 엔트리 */
/* res.start = 변환된 CPU 물리 주소
 * res.end   = start + size - 1
 * res.flags = IORESOURCE_MEM 또는 IORESOURCE_IO */

/* of_translate_dma_address(): DMA 주소 변환 (dma-ranges 사용) */
u64 dma_addr = of_translate_dma_address(np, addr_prop);

/* dma-ranges: DMA 엔진이 보는 주소 ≠ CPU 물리 주소일 때
 * 예: GPU나 DMA 컨트롤러가 IOMMU 없이 다른 주소로 메모리 접근 */
soc {
    /* DMA 주소 0x0 → CPU 물리 주소 0x8000_0000 */
    dma-ranges = <0x0  0x0 0x80000000  0x80000000>;
};

인터럽트 도메인과 Nexus 노드 심화

Device Tree의 인터럽트 계층은 디바이스 트리 구조(부모-자식)와 독립적입니다. interrupt-parent가 인터럽트 도메인 트리를 형성하고, interrupt-map이 도메인 간 인터럽트 번호 변환을 수행합니다.

/* ===== 인터럽트 처리 핵심 개념 =====
 *
 * 1. interrupt-controller: 이 노드가 인터럽트 컨트롤러임을 선언 (빈 프로퍼티)
 * 2. #interrupt-cells: 자식이 interrupts에 넣는 셀 수 (GIC=3, GPIO=2 등)
 * 3. interrupt-parent: 인터럽트를 수신할 컨트롤러 (생략 시 DT 부모에서 상속)
 * 4. interrupts: 인터럽트 지정자 (해석은 컨트롤러의 #interrupt-cells에 의존)
 * 5. interrupt-map: 인터럽트 도메인 간 변환 (nexus 노드에서 사용)
 */

/* ===== GIC (ARM Generic Interrupt Controller) ===== */
gic: interrupt-controller@1c81000 {
    compatible = "arm,gic-400";
    interrupt-controller;
    #interrupt-cells = <3>;
    /* 셀 해석:
     * [0] type: 0=SPI(Shared), 1=PPI(Private Per-Processor)
     * [1] irq number: SPI=0~987, PPI=0~15 (GIC HW IRQ = SPI+32, PPI+16)
     * [2] flags: 1=rising edge, 2=falling edge, 4=level high, 8=level low */
    reg = <0x1c81000 0x1000>,
          <0x1c82000 0x2000>;
};

/* ===== GPIO 인터럽트 컨트롤러 (계층적) ===== */
gpio0: gpio@1c20800 {
    compatible = "myvendor,my-soc-gpio";
    reg = <0x1c20800 0x40>;
    /* GPIO 컨트롤러이면서 인터럽트 컨트롤러 */
    gpio-controller;
    #gpio-cells = <2>;
    interrupt-controller;
    #interrupt-cells = <2>;
    /* 셀 해석: [0] GPIO 핀 번호, [1] 트리거 타입 (IRQ_TYPE_*) */

    /* 이 GPIO 컨트롤러의 인터럽트가 GIC로 전달됨 */
    interrupt-parent = <&gic>;
    interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
};

/* GPIO 핀을 인터럽트로 사용하는 디바이스 */
button@0 {
    compatible = "gpio-keys";
    interrupt-parent = <&gpio0>;     /* GIC가 아닌 GPIO 컨트롤러로! */
    interrupts = <7 IRQ_TYPE_EDGE_FALLING>;  /* GPIO 핀 7, 하강 에지 */
};

/* ===== interrupt-map (Nexus 노드) =====
 *
 * PCI, USB 등의 버스에서 디바이스 인터럽트를 부모 컨트롤러로 변환합니다.
 * nexus 노드: interrupt-controller는 아니지만 interrupt-map으로 변환 수행
 */
pcie@10000000 {
    /* PCI 인터럽트: INTA=1, INTB=2, INTC=3, INTD=4 */
    #interrupt-cells = <1>;

    /* interrupt-map-mask: 매칭에 사용할 비트 마스크
     * PCI 주소(3 cells) + 인터럽트(1 cell) 총 4 cells
     * device 번호(bit 15:11)와 인터럽트 번호만 매칭 */
    interrupt-map-mask = <0xf800 0 0 7>;

    /* interrupt-map: (child_unit_addr  child_irq  parent  parent_irq)
     * child_unit_addr: #address-cells 만큼의 셀 (AND mask 적용 후 비교)
     * child_irq: #interrupt-cells 만큼의 셀
     * parent: phandle → 부모 인터럽트 컨트롤러
     * parent_irq: 부모의 #interrupt-cells 만큼의 셀 */
    interrupt-map =
        /* Device 0, INTA → GIC SPI 100 */
        <0x0000 0 0 1  &gic GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>,
        /* Device 0, INTB → GIC SPI 101 */
        <0x0000 0 0 2  &gic GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>,
        /* Device 0, INTC → GIC SPI 102 */
        <0x0000 0 0 3  &gic GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>,
        /* Device 0, INTD → GIC SPI 103 */
        <0x0000 0 0 4  &gic GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>,
        /* Device 1, INTA → GIC SPI 104 (rotation: INTB부터 시작) */
        <0x0800 0 0 1  &gic GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>,
        <0x0800 0 0 2  &gic GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>,
        <0x0800 0 0 3  &gic GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>,
        <0x0800 0 0 4  &gic GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>;

    /* PCI 인터럽트 회전(swizzle):
     * IRQ = (device_slot + interrupt_pin - 1) % 4 + 1
     * 이를 통해 여러 디바이스의 인터럽트가 4개 GIC IRQ에 분산 */
};

/* ===== interrupts-extended: 여러 컨트롤러의 인터럽트를 한 노드에서 사용 ===== */
my-device {
    /* interrupt-parent + interrupts는 하나의 컨트롤러만 가능.
     * interrupts-extended는 여러 컨트롤러의 인터럽트를 지정 가능 */
    interrupts-extended =
        <&gic GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>,    /* GIC에서 오는 인터럽트 */
        <&gpio0 7 IRQ_TYPE_EDGE_FALLING>;           /* GPIO에서 오는 인터럽트 */
    interrupt-names = "data-irq", "wakeup-irq";
};

/* ===== 커널 인터럽트 도메인 API (drivers/irqchip/) ===== */
#include <linux/irqdomain.h>

/* irq_domain: HW IRQ 번호 → Linux virq(가상 IRQ) 번호 매핑
 * 각 인터럽트 컨트롤러가 자신의 도메인을 등록
 * DT의 interrupts 값이 HW IRQ로, irq_domain을 통해 Linux IRQ로 변환 */

struct irq_domain *domain;
domain = irq_domain_add_linear(np, nr_irqs, &my_domain_ops, priv);
/* linear: HW IRQ → virq 직접 테이블 매핑 (소규모)
 * hierarchy: 계층적 도메인 (GIC→GPIO 등 cascaded 구조) */

domain = irq_domain_create_hierarchy(parent_domain, 0, nr_irqs,
    of_fwnode_handle(np), &my_domain_ops, priv);
/* hierarchy 도메인: 인터럽트 처리가 여러 컨트롤러를 거침
 * button → GPIO IRQ 7 → GIC SPI 11 → CPU
 * 각 단계의 도메인이 HW IRQ를 변환 */

Pinctrl 서브시스템과 DT 연동

SoC의 핀 다중화(muxing)와 전기적 설정을 DT에서 선언합니다. 드라이버의 probe() 시 자동으로 pinctrl-0이 적용됩니다.

/* ===== 핀 컨트롤러 노드 (SoC .dtsi) ===== */
pio: pinctrl@1c20800 {
    compatible = "myvendor,my-soc-pinctrl";
    reg = <0x1c20800 0x400>;
    clocks = <&ccu CLK_APB1>;

    /* UART0 핀 그룹 정의 */
    uart0_pins: uart0-pins {
        pins = "PA4", "PA5";       /* TX, RX */
        function = "uart0";         /* 핀 기능 선택 (mux) */
        drive-strength = <10>;     /* mA 단위 출력 세기 */
        bias-pull-up;                /* 풀업 활성화 */
    };

    uart0_sleep_pins: uart0-sleep-pins {
        pins = "PA4", "PA5";
        function = "gpio_in";       /* sleep 시 GPIO 입력으로 */
        bias-disable;
    };

    /* I2C0 핀 그룹 */
    i2c0_pins: i2c0-pins {
        pins = "PA11", "PA12";    /* SDA, SCL */
        function = "i2c0";
        drive-strength = <10>;
        bias-pull-up;
    };

    /* SPI0 핀 그룹 + CS */
    spi0_pins: spi0-pins {
        pins = "PC0", "PC1", "PC2", "PC3"; /* CLK, MOSI, MISO, CS */
        function = "spi0";
        drive-strength = <10>;
    };

    /* GPIO 키 (외부 풀업, 내부 바이어스 없음) */
    key_pins: key-pins {
        pins = "PG7";
        function = "gpio_in";
        bias-disable;
    };
};

/* ===== 디바이스에서 pinctrl 참조 ===== */
&uart0 {
    pinctrl-names = "default", "sleep";
    pinctrl-0 = <&uart0_pins>;        /* "default" 상태 (probe 시 적용) */
    pinctrl-1 = <&uart0_sleep_pins>;   /* "sleep" 상태 (suspend 시 적용) */
    status = "okay";
};

/* pinctrl-names와 pinctrl-N은 순서 대응:
 * pinctrl-names[0] = "default" → pinctrl-0
 * pinctrl-names[1] = "sleep"   → pinctrl-1
 *
 * 커널 PM 시스템이 suspend/resume 시 자동으로 상태 전환:
 * probe → "default", suspend → "sleep", resume → "default"
 *
 * "init" 상태: probe 중에만 사용, probe 완료 후 "default"로 전환 */

/* ===== 핀 설정 바인딩 주요 프로퍼티 (vendor-independent) ===== */
/*
 * pins:            핀 이름 목록
 * groups:          핀 그룹 이름 (대체)
 * function:        핀 기능 (mux 선택)
 * bias-disable:    바이어스 없음
 * bias-pull-up:    내부 풀업 활성화
 * bias-pull-down:  내부 풀다운 활성화
 * drive-strength:  출력 드라이브 세기 (mA)
 * input-enable:    입력 활성화
 * output-high:     출력 High로 설정
 * output-low:      출력 Low로 설정
 * slew-rate:       슬루율 (0=slow, 1=fast)
 */

IOMMU와 DMA 관련 DT 프로퍼티

/* ===== IOMMU (I/O Memory Management Unit) DT 바인딩 ===== */

/* IOMMU 컨트롤러 노드 */
smmu: iommu@12c00000 {
    compatible = "arm,smmu-v2";
    reg = <0x12c00000 0x10000>;
    #iommu-cells = <1>;              /* 자식이 참조 시 stream ID 1개 */
    interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>;
};

/* DMA를 수행하는 디바이스에서 IOMMU 참조 */
gpu@12000000 {
    compatible = "vendor,my-gpu";
    reg = <0x12000000 0x10000>;
    iommus = <&smmu 0x100>;          /* SMMU stream ID = 0x100 */
    /* 커널이 자동으로 IOMMU 도메인을 설정하여 DMA 주소 변환 수행 */
};

ethernet@1c30000 {
    compatible = "vendor,my-eth";
    reg = <0x1c30000 0x10000>;
    iommus = <&smmu 0x200>;          /* 다른 stream ID */
};

/* ===== DMA 관련 프로퍼티 ===== */

my-device@1000 {
    compatible = "vendor,my-dev";

    /* dma-coherent: 하드웨어가 캐시 코히어런시 보장
     * → 커널이 수동 캐시 flush/invalidate 생략 (성능 향상) */
    dma-coherent;

    /* dma-ranges가 부모에 있으면 DMA 주소 ≠ CPU 주소 */

    /* DMA 컨트롤러 참조 (slave DMA 사용 시) */
    dmas = <&dma_controller 5>, <&dma_controller 6>;
    dma-names = "tx", "rx";
};

/* DMA 컨트롤러 노드 */
dma_controller: dma-controller@1c02000 {
    compatible = "myvendor,my-soc-dma";
    reg = <0x1c02000 0x1000>;
    interrupts = <GIC_SPI 27 IRQ_TYPE_LEVEL_HIGH>;
    #dma-cells = <1>;              /* 자식 참조 시 채널 번호 1개 */
    clocks = <&ccu CLK_DMA>;
    resets = <&ccu RST_DMA>;
};

/* ===== 커널에서 DMA 채널 가져오기 ===== */
#include <linux/dmaengine.h>

struct dma_chan *tx_chan, *rx_chan;
tx_chan = dma_request_chan(dev, "tx");  /* dma-names의 "tx"에 대응하는 채널 */
rx_chan = dma_request_chan(dev, "rx");  /* dma-names의 "rx"에 대응하는 채널 */

/* restricted-dma-pool: 특정 디바이스용 DMA 메모리 제한 */
reserved-memory {
    #address-cells = <2>;
    #size-cells = <2>;
    ranges;

    gpu_dma_pool: dma-pool@90000000 {
        compatible = "restricted-dma-pool";
        reg = <0x0 0x90000000 0x0 0x10000000>;  /* 256MiB */
    };
};

gpu@12000000 {
    memory-region = <&gpu_dma_pool>;  /* 이 디바이스의 DMA는 이 영역만 사용 */
};

Thermal-zones DT 바인딩

/* ===== SoC 온도 센서와 쿨링 제어를 DT에서 정의 ===== */

/* 온도 센서 노드 */
tsensor: thermal-sensor@1c25000 {
    compatible = "myvendor,my-soc-thermal";
    reg = <0x1c25000 0x400>;
    #thermal-sensor-cells = <1>;   /* 센서 인덱스 1개 (다중 존) */
    clocks = <&ccu CLK_THS>;
    resets = <&ccu RST_THS>;
};

/* 쿨링 디바이스: CPU freq 스로틀링 */
/* cpu 노드에 #cooling-cells = <2>; 추가 필요 */
&cpu0 {
    #cooling-cells = <2>;  /* min_state, max_state */
};

/* thermal-zones 노드 */
thermal-zones {
    /* 각 zone = 센서 + 트립 포인트 + 쿨링 맵 */
    cpu-thermal {
        polling-delay-passive = <250>;  /* 트립 후 폴링 주기 (ms) */
        polling-delay = <1000>;          /* 평상시 폴링 주기 (ms) */

        thermal-sensors = <&tsensor 0>;  /* 센서 0번 (CPU zone) */

        trips {
            /* 패시브 쿨링: CPU freq 스로틀 시작 */
            cpu_alert: cpu-alert {
                temperature = <75000>;  /* 75°C (밀리도) */
                hysteresis = <2000>;    /* 73°C에서 해제 */
                type = "passive";
            };
            /* 크리티컬: 시스템 셧다운 */
            cpu_crit: cpu-critical {
                temperature = <100000>; /* 100°C */
                hysteresis = <0>;
                type = "critical";
            };
            /* 핫: 능동 쿨링(팬) 시작 */
            cpu_hot: cpu-hot {
                temperature = <85000>;  /* 85°C */
                hysteresis = <5000>;
                type = "hot";
            };
        };

        cooling-maps {
            /* 75°C 이상: CPU freq 스로틀 (state 0~최대) */
            cpu-throttle {
                trip = <&cpu_alert>;
                cooling-device = <&cpu0
                    THERMAL_NO_LIMIT       /* min state */
                    THERMAL_NO_LIMIT>;    /* max state */
            };
            /* 85°C 이상: 팬 활성화 */
            fan-cooling {
                trip = <&cpu_hot>;
                cooling-device = <&fan0 0 3>;  /* 팬 레벨 0~3 */
            };
        };
    };

    gpu-thermal {
        polling-delay-passive = <250>;
        polling-delay = <1000>;
        thermal-sensors = <&tsensor 1>;  /* 센서 1번 (GPU zone) */

        trips {
            gpu_alert: gpu-alert {
                temperature = <80000>;
                hysteresis = <2000>;
                type = "passive";
            };
        };
    };
};

/* 팬 제어용 PWM 쿨링 디바이스 */
fan0: pwm-fan {
    compatible = "pwm-fan";
    pwms = <&pwm0 0 25000>;            /* PWM 채널 0, 25kHz */
    #cooling-cells = <2>;
    cooling-levels = <0 64 128 255>;  /* state 0~3의 PWM duty */
};

/* sysfs 확인 */
/* /sys/class/thermal/thermal_zone0/temp     → 현재 온도 */
/* /sys/class/thermal/thermal_zone0/type     → "cpu-thermal" */
/* /sys/class/thermal/thermal_zone0/trip_point_0_temp → 75000 */
/* /sys/class/thermal/cooling_device0/cur_state → 현재 쿨링 레벨 */

전력 도메인 (Power Domain) DT

/* ===== 전력 도메인: SoC 내 독립적으로 전원을 제어할 수 있는 영역 =====
 *
 * SoC 설계에서 GPU, DSP, ISP 등은 별도 전력 도메인에 배치되어
 * 사용하지 않을 때 완전히 전원을 차단(power gating)할 수 있습니다.
 * DT에서 이 관계를 선언하면 커널 PM 시스템이 자동 관리합니다.
 */

/* 전력 도메인 컨트롤러 (PMU, Power Management Unit) */
pmu: power-controller@1c20000 {
    compatible = "myvendor,my-soc-power";
    reg = <0x1c20000 0x100>;
    #power-domain-cells = <1>;    /* 도메인 인덱스 1개 */

    /* 서브노드 형태도 가능 (일부 SoC) */
    pd_gpu: power-domain@0 {
        reg = <0>;
        #power-domain-cells = <0>;
        clocks = <&ccu CLK_GPU>;
        resets = <&ccu RST_GPU>;
    };
    pd_dsp: power-domain@1 {
        reg = <1>;
        #power-domain-cells = <0>;
    };
};

/* 디바이스에서 전력 도메인 참조 */
gpu@12000000 {
    compatible = "vendor,my-gpu";
    reg = <0x12000000 0x10000>;

    /* 방법 1: 인덱스 기반 (#power-domain-cells = <1>) */
    power-domains = <&pmu 0>;       /* 도메인 0 = GPU */

    /* 방법 2: 서브노드 phandle (#power-domain-cells = <0>) */
    /* power-domains = <&pd_gpu>; */

    power-domain-names = "gpu";
};

/* 여러 전력 도메인에 걸친 디바이스 */
isp@14000000 {
    compatible = "vendor,my-isp";
    reg = <0x14000000 0x10000>;
    power-domains = <&pmu 2>, <&pmu 3>;
    power-domain-names = "isp-core", "isp-io";
};

/* ===== 커널에서 전력 도메인 관리 =====
 *
 * Runtime PM과 연동:
 * - pm_runtime_get_sync() → 전력 도메인 ON (참조 카운트 기반)
 * - pm_runtime_put()      → 전력 도메인 OFF (모든 사용자가 put하면)
 *
 * 커널 내부 흐름:
 * 1. DT 파싱 → genpd(Generic Power Domain) 구조체 생성
 * 2. pm_genpd_add_device() → 디바이스를 도메인에 연결
 * 3. dev_pm_domain_attach() → probe 시 자동 호출
 * 4. Runtime PM 콜백에서 genpd_power_on/off() 자동 호출
 *
 * 디버깅:
 * $ cat /sys/kernel/debug/pm_genpd/pm_genpd_summary
 *   domain                status  /device          runtime status
 *   gpu_pd                on      /12000000.gpu    active
 *   dsp_pd                off
 */

Device Tree vs ACPI 비교

/* ===== fwnode API: DT/ACPI 통합 드라이버 패턴 ===== */
#include <linux/property.h>

static int my_unified_probe(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;
    u32 val;
    const char *str;
    bool flag;

    /* of_property_read_u32() 대신 → DT/ACPI 모두 동작 */
    device_property_read_u32(dev, "fifo-depth", &val);
    device_property_read_string(dev, "label", &str);
    flag = device_property_read_bool(dev, "big-endian");

    /* fwnode 기반 자식 순회 */
    struct fwnode_handle *child;
    device_for_each_child_node(dev, child) {
        u32 reg;
        fwnode_property_read_u32(child, "reg", ®);
    }

    return 0;
}

/* DT + ACPI 듀얼 매칭 테이블 */
static const struct of_device_id my_of_ids[] = {
    { .compatible = "vendor,my-dev" },
    { }
};

#ifdef CONFIG_ACPI
static const struct acpi_device_id my_acpi_ids[] = {
    { "VNDR0001", 0 },    /* _HID 매칭 */
    { }
};
MODULE_DEVICE_TABLE(acpi, my_acpi_ids);
#endif

static struct platform_driver my_driver = {
    .probe  = my_unified_probe,
    .driver = {
        .name = "my-device",
        .of_match_table = my_of_ids,
        .acpi_match_table = ACPI_PTR(my_acpi_ids),
    },
};

실제 SoC DTS 분석 (Raspberry Pi / Allwinner)

/* ===== 실제 커널 소스 DTS 구조 분석 =====
 *
 * 커널 소스 내 DTS 파일 위치:
 *   arch/arm64/boot/dts/broadcom/   ← Raspberry Pi 4/5
 *   arch/arm64/boot/dts/allwinner/  ← Allwinner (Pine64, OrangePi)
 *   arch/arm64/boot/dts/rockchip/   ← Rockchip (Rock5B)
 *   arch/arm64/boot/dts/amlogic/    ← Amlogic (Odroid)
 *   arch/arm64/boot/dts/freescale/  ← NXP i.MX
 *   arch/arm64/boot/dts/qcom/       ← Qualcomm
 *
 * 일반적인 .dtsi/.dts 계층 구조:
 *   SoC계열.dtsi       ← SoC 공통 (예: sun50i-h5.dtsi)
 *   └── SoC.dtsi       ← 특정 SoC (예: sun50i-h5.dtsi → sun50i-a64.dtsi 포함)
 *       └── Board.dts  ← 보드별 (예: sun50i-h5-orangepi-pc2.dts)
 */

/* ===== Raspberry Pi 4B (BCM2711) DTS 구조 분석 ===== */
/*
 * arch/arm64/boot/dts/broadcom/bcm2711-rpi-4-b.dts
 * └── #include "bcm2711.dtsi"
 *     └── #include "bcm283x.dtsi"  ← BCM SoC 공통
 *
 * BCM2711 특징:
 * - VideoCore GPU가 주소 공간을 관리 (VC 주소 ≠ ARM 주소)
 * - dma-ranges로 VC↔ARM 주소 변환
 * - 독자적인 인터럽트 컨트롤러 (GIC-400)
 */

/* bcm283x.dtsi 핵심 구조 (간략화) */
/ {
    compatible = "brcm,bcm2835";
    #address-cells = <1>;
    #size-cells = <1>;

    soc {
        compatible = "simple-bus";
        #address-cells = <1>;
        #size-cells = <1>;
        /* ARM 주소 0x7E000000이 버스 주소 0xFE000000으로 매핑 (BCM2711) */
        ranges = <0x7e000000  0xfe000000  0x01800000>;
        /* DMA 엔진은 레거시 주소를 사용 */
        dma-ranges = <0xc0000000  0x00000000  0x40000000>;

        gpio: gpio@7e200000 {
            compatible = "brcm,bcm2711-gpio";
            reg = <0x7e200000 0xb4>;
            gpio-controller;
            #gpio-cells = <2>;
            interrupt-controller;
            #interrupt-cells = <2>;
            gpio-ranges = <&gpio 0 0 58>; /* pinctrl 연동 */
        };

        uart0: serial@7e201000 {
            compatible = "arm,pl011", "arm,primecell";
            reg = <0x7e201000 0x200>;
            clocks = <&clocks BCM2835_CLOCK_UART>,
                     <&clocks BCM2835_CLOCK_VPU>;
            clock-names = "uartclk", "apb_pclk";
            arm,primecell-periphid = <0x00241011>;
            status = "disabled";
        };
    };
};

/* bcm2711-rpi-4-b.dts에서 오버라이드 */
&uart0 {
    pinctrl-names = "default";
    pinctrl-0 = <&uart0_gpio14>;
    status = "okay";
};

/* ===== Allwinner H6 (Pine H64) DTS 구조 분석 ===== */
/*
 * arch/arm64/boot/dts/allwinner/sun50i-h6-pine-h64.dts
 * └── #include "sun50i-h6.dtsi"
 *
 * Allwinner 특징:
 * - CCU(Clock Control Unit) 드라이버가 클럭 + 리셋 모두 관리
 * - R_ 접두사 노드: Always-On 도메인 (대기 전력)
 * - MBUS: 메모리 버스 대역폭 제어
 */

/* sun50i-h6.dtsi 핵심 구조 (간략화) */
/ {
    #address-cells = <1>;
    #size-cells = <1>;

    cpus {
        #address-cells = <1>;
        #size-cells = <0>;

        cpu0: cpu@0 {
            compatible = "arm,cortex-a53";
            device_type = "cpu";
            reg = <0>;
            enable-method = "psci";
            clocks = <&ccu CLK_CPUX>;
            operating-points-v2 = <&cpu_opp_table>;
            #cooling-cells = <2>;
        };
    };

    /* PSCI: ARM 표준 CPU 전원 관리 인터페이스 */
    psci {
        compatible = "arm,psci-1.0";
        method = "smc";  /* Secure Monitor Call */
    };

    soc@3000000 {
        compatible = "simple-bus";
        #address-cells = <1>;
        #size-cells = <1>;
        ranges = <0x0 0x03000000 0x1000000>;

        /* CCU: 클럭 + 리셋 통합 컨트롤러 */
        ccu: clock@3001000 {
            compatible = "allwinner,sun50i-h6-ccu";
            reg = <0x01000 0x1000>;
            clocks = <&osc24M>, <&rtc 0>, <&rtc 2>;
            clock-names = "hosc", "losc", "iosc";
            #clock-cells = <1>;
            #reset-cells = <1>;
        };

        /* EMAC (이더넷) — 완전한 DT 바인딩 예 */
        emac: ethernet@5020000 {
            compatible = "allwinner,sun50i-h6-emac",
                         "allwinner,sun50i-a64-emac";
            reg = <0x5020000 0x10000>;
            interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>;
            interrupt-names = "macirq";
            clocks = <&ccu CLK_BUS_EMAC>;
            clock-names = "stmmaceth";
            resets = <&ccu RST_BUS_EMAC>;
            reset-names = "stmmaceth";
            syscon = <&syscon>;
            status = "disabled";

            mdio: mdio {
                compatible = "snps,dwmac-mdio";
                #address-cells = <1>;
                #size-cells = <0>;
            };
        };
    };
};

/* 보드 .dts에서 활성화 + PHY 추가 */
&emac {
    pinctrl-names = "default";
    pinctrl-0 = <&ext_rgmii_pins>;
    phy-mode = "rgmii-id";
    phy-handle = <&ext_rgmii_phy>;
    phy-supply = <®_gmac_3v3>;
    status = "okay";
};

&mdio {
    ext_rgmii_phy: ethernet-phy@1 {
        compatible = "ethernet-phy-ieee802.3-c22";
        reg = <1>;               /* PHY 주소 */
        reset-gpios = <&pio 3 14 GPIO_ACTIVE_LOW>;
        reset-assert-us = <15000>;
        reset-deassert-us = <40000>;
    };
};

Managed Device Resources (devm)

devm_* API는 디바이스 해제 시 리소스를 자동으로 정리합니다. 에러 경로에서의 수동 해제가 불필요합니다.

/* devm 사용 예: 에러 시 자동 해제, goto 불필요 */
static int my_probe(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;

    void *data = devm_kzalloc(dev, 4096, GFP_KERNEL);
    if (!data) return -ENOMEM;

    void __iomem *base = devm_platform_ioremap_resource(pdev, 0);
    if (IS_ERR(base)) return PTR_ERR(base);

    int irq = platform_get_irq(pdev, 0);
    devm_request_irq(dev, irq, my_handler, 0, "mydev", data);
    /* remove 시 모든 리소스 자동 해제 */
    return 0;
}

전원 관리 (PM)

static int my_suspend(struct device *dev)
{
    /* 하드웨어 상태 저장, 클럭 비활성화 */
    clk_disable_unprepare(priv->clk);
    return 0;
}

static int my_resume(struct device *dev)
{
    /* 하드웨어 상태 복원 */
    clk_prepare_enable(priv->clk);
    reinit_hardware(priv);
    return 0;
}

static DEFINE_SIMPLE_DEV_PM_OPS(my_pm_ops, my_suspend, my_resume);

static struct platform_driver my_driver = {
    .driver = {
        .name = "my-device",
        .pm   = pm_sleep_ptr(&my_pm_ops),
    },
};

DMA 심화 — 주의사항과 고려사항

DMA 매핑 API 유형과 선택 기준

DMA 방향(Direction)과 캐시 동기화

/* DMA 방향 상수 — 반드시 정확히 지정해야 함 */
DMA_TO_DEVICE       /* CPU → Device: CPU 캐시 → 메모리 flush */
DMA_FROM_DEVICE     /* Device → CPU: 캐시 invalidate */
DMA_BIDIRECTIONAL   /* 양방향: flush + invalidate (비용 큼) */

/* Streaming DMA의 올바른 사용 패턴 */
dma_addr_t dma = dma_map_single(dev, buf, len, DMA_FROM_DEVICE);
if (dma_mapping_error(dev, dma)) {
    dev_err(dev, "DMA mapping failed\n");
    return -ENOMEM;
}

/* DMA 전송 시작 (H/W에 dma 주소 전달) */
writel(dma, hw_base + DMA_ADDR_REG);
writel(len, hw_base + DMA_LEN_REG);
writel(DMA_START, hw_base + DMA_CTRL_REG);

/* 전송 완료 후 — CPU가 데이터를 읽기 전에 반드시 sync */
dma_sync_single_for_cpu(dev, dma, len, DMA_FROM_DEVICE);
/* 이제 CPU에서 buf 데이터를 안전하게 읽을 수 있음 */
process_data(buf, len);

/* 다시 디바이스에게 버퍼를 넘기려면 */
dma_sync_single_for_device(dev, dma, len, DMA_FROM_DEVICE);

/* 최종 해제 */
dma_unmap_single(dev, dma, len, DMA_FROM_DEVICE);

IOMMU와 DMA 주소 공간

/* IOMMU 존재 시 DMA 주소 변환 흐름:
 *
 *  CPU Virtual Addr → (MMU) → Physical Addr
 *  DMA/Bus Addr     → (IOMMU) → Physical Addr
 *
 *  IOMMU가 없으면: dma_addr_t == phys_addr_t (1:1 매핑)
 *  IOMMU가 있으면: dma_addr_t는 IOMMU가 매핑한 I/O 가상 주소
 */

/* DMA 주소 마스크 설정 — 디바이스의 주소 지정 능력 선언 */
int ret = dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64));
if (ret) {
    /* 64비트 실패 시 32비트로 fallback */
    ret = dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32));
    if (ret) {
        dev_err(dev, "No suitable DMA available\n");
        return ret;
    }
}

DMA 프로그래밍 핵심 주의사항

DMA 디버깅

# DMA 디버그 활성화 (커널 부트 파라미터)
dma_debug=on

# 또는 CONFIG_DMA_API_DEBUG=y 로 빌드

# DMA 디버그 통계 확인
cat /sys/kernel/debug/dma-api/error_count
cat /sys/kernel/debug/dma-api/all_errors
cat /sys/kernel/debug/dma-api/num_errors

# 일반적으로 검출되는 DMA 오류:
# - DMA-API: device driver frees DMA memory with wrong function
# - DMA-API: device driver maps memory from kernel text
# - DMA-API: device driver tries to sync DMA memory it has not allocated

커널 버스 서브시스템 심화

PCI/PCIe 서브시스템

#include <linux/pci.h>

/* PCI 디바이스 ID 테이블 */
static const struct pci_device_id my_pci_ids[] = {
    { PCI_DEVICE(0x8086, 0x1234) },  /* vendor, device */
    { PCI_DEVICE_CLASS(0x020000, 0xFFFF00) }, /* 클래스 매칭 */
    { 0, }
};
MODULE_DEVICE_TABLE(pci, my_pci_ids);

/* PCI 드라이버 프로브 */
static int my_pci_probe(struct pci_dev *pdev,
        const struct pci_device_id *id)
{
    int ret;

    /* 1. PCI 디바이스 활성화 */
    ret = pcim_enable_device(pdev);  /* devm 버전 */

    /* 2. BAR (Base Address Register) 매핑 */
    ret = pcim_iomap_regions(pdev, BIT(0), "my_driver");
    void __iomem *base = pcim_iomap_table(pdev)[0];

    /* 3. DMA 마스크 설정 */
    ret = dma_set_mask_and_coherent(&pdev->dev, DMA_BIT_MASK(64));

    /* 4. Bus Master 활성화 (DMA 사용 시 필수) */
    pci_set_master(pdev);

    /* 5. MSI/MSI-X 인터럽트 설정 */
    ret = pci_alloc_irq_vectors(pdev, 1, 32, PCI_IRQ_MSIX | PCI_IRQ_MSI);

    return 0;
}

static struct pci_driver my_pci_driver = {
    .name     = "my_pci",
    .id_table = my_pci_ids,
    .probe    = my_pci_probe,
};
module_pci_driver(my_pci_driver);

I2C/SMBus 서브시스템

/* === I2C (Inter-Integrated Circuit) 프로토콜 개요 ===
 *
 * Philips(NXP)가 1982년 개발한 2-wire 직렬 버스.
 * 저속 주변장치(센서, EEPROM, RTC, PMIC 등) 연결에 표준적으로 사용.
 *
 * 물리 계층:
 *   SDA (Serial Data)  — 양방향 데이터 라인
 *   SCL (Serial Clock)  — 마스터가 생성하는 클럭 라인
 *   둘 다 오픈 드레인 + 외부 풀업 저항 (보통 4.7kΩ~10kΩ)
 *   → 다중 마스터/슬레이브가 하나의 버스를 공유 (wired-AND)
 *
 * 속도 모드:
 *   Standard Mode (SM)     —  100 kbit/s    (기본)
 *   Fast Mode (FM)         —  400 kbit/s    (대부분의 센서)
 *   Fast Mode Plus (FM+)   —    1 Mbit/s    (20mA 전류 드라이버)
 *   High Speed Mode (Hs)   —  3.4 Mbit/s    (마스터 코드 필요)
 *   Ultra Fast Mode (UFm)  —    5 Mbit/s    (단방향, 푸시풀)
 *
 * 트랜잭션 포맷:
 *   [S] [ADDR(7bit)] [R/W(1bit)] [ACK] [DATA(8bit)] [ACK] ... [P]
 *
 *   S = START 조건 (SDA↓ while SCL=HIGH)
 *   P = STOP  조건 (SDA↑ while SCL=HIGH)
 *   Sr = Repeated START (STOP 없이 새 트랜잭션 시작)
 *   ACK  = 수신자가 SDA를 LOW로 당김 (정상)
 *   NACK = 수신자가 응답하지 않음 (SDA=HIGH 유지)
 *
 * 7-bit 주소: 0x00~0x7F (유효 범위 0x08~0x77, 나머지는 예약)
 * 10-bit 주소: 첫 바이트 11110XX + 두 번째 바이트 8bit (드물게 사용)
 *
 * Clock Stretching:
 *   슬레이브가 SCL을 LOW로 유지하여 마스터를 대기시킴
 *   → 느린 디바이스의 처리 시간 확보
 *   → 하드웨어 I2C 컨트롤러가 지원해야 함
 *
 * Multi-Master:
 *   여러 마스터가 동시에 전송 시도 → 중재(Arbitration)
 *   SDA에서 0(LOW)을 보낸 마스터가 1(HIGH)을 읽으면 → 중재 패배, 버스 양보
 */

/* === SMBus vs I2C 차이 ===
 *
 * SMBus(System Management Bus)는 Intel이 1995년 정의한 I2C의 부분집합.
 * PC 메인보드의 전원 관리, 팬 제어, 온도 센서, DIMM SPD EEPROM 등에 사용.
 *
 * ┌────────────────────┬──────────────────────┬──────────────────────┐
 * │     항목           │       I2C            │       SMBus          │
 * ├────────────────────┼──────────────────────┼──────────────────────┤
 * │ 전압 범위          │ Vdd 자유 (1.8~5V)   │ 1.8V 또는 3.3V 고정 │
 * │ 최대 속도          │ 3.4 Mbit/s (Hs)     │ 100kHz (1.0)         │
 * │                    │                      │ 400kHz (2.0)         │
 * │                    │                      │ 1MHz (3.0)           │
 * │ 클럭 최소 주파수   │ 없음 (DC 허용)       │ 10kHz (타임아웃)     │
 * │ 타임아웃           │ 없음                 │ 25~35ms SCL LOW      │
 * │ 최대 데이터 크기   │ 제한 없음            │ 32바이트 (블록)      │
 * │ 주소 해석 (ARP)    │ 없음                 │ 지원 (동적 주소 할당)│
 * │ 패킷 에러 체크     │ 없음                 │ PEC (CRC-8) 선택적   │
 * │ Alert 핀           │ 없음                 │ SMBALERT# (인터럽트)  │
 * │ Host Notify        │ 없음                 │ 슬레이브→마스터 알림 │
 * └────────────────────┴──────────────────────┴──────────────────────┘
 *
 * 리눅스 커널에서의 권장:
 *   - 디바이스가 SMBus 호환이면 → i2c_smbus_*() 함수 사용
 *   - SMBus 전용 컨트롤러(Intel PCH 등)에서도 동작 보장
 *   - Raw I2C 필요 시에만 → i2c_transfer() 사용
 *     (SMBus 전용 컨트롤러에서는 동작 안 할 수 있음)
 */

/* === SMBus 프로토콜 명령 유형 ===
 *
 * Quick Command:     [S][Addr][R/W][A][P]           (데이터 없이 R/W 비트만)
 * Send Byte:         [S][Addr][W][A][Data][A][P]    (1바이트 전송)
 * Receive Byte:      [S][Addr][R][A][Data][NA][P]   (1바이트 수신)
 * Write Byte:        [S][Addr][W][A][Cmd][A][Data][A][P]
 * Read Byte:         [S][Addr][W][A][Cmd][A][Sr][Addr][R][A][Data][NA][P]
 * Write Word:        [S][Addr][W][A][Cmd][A][DataLow][A][DataHigh][A][P]
 * Read Word:         Write Cmd → Repeated Start → Read 2 bytes
 * Block Write:       [S][Addr][W][A][Cmd][A][Count][A][Data0]...[DataN][A][P]
 * Block Read:        Write Cmd → Sr → Read Count + Data bytes
 * I2C Block:         커널 확장 (Count 바이트 없이 직접 블록 전송)
 * Process Call:      Write Word → Sr → Read Word (요청-응답)
 * Block Process Call: Block Write → Sr → Block Read
 *
 * Cmd = 커맨드/레지스터 주소 (8-bit)
 * Count = 이후 데이터 바이트 수 (1~32)
 * PEC = 선택적 CRC-8 체크 바이트 (마지막에 추가)
 */

/* === 리눅스 I2C 서브시스템 아키텍처 ===
 *
 * 소스: drivers/i2c/
 *
 * ┌───────────────────────────────────────────────────┐
 * │            사용자 공간 (i2c-tools, 응용 프로그램)  │
 * │   i2cdetect / i2cdump / i2cget / i2cset           │
 * ├────────────────────┬──────────────────────────────┤
 * │  /dev/i2c-N        │  sysfs (/sys/bus/i2c/)       │
 * │  (i2c-dev 캐릭터)  │  (디바이스/드라이버 바인딩)  │
 * ├────────────────────┴──────────────────────────────┤
 * │              I2C Core (drivers/i2c/i2c-core-*.c)  │
 * │   i2c_transfer() / i2c_smbus_xfer()               │
 * │   디바이스 등록/매칭, 버스 잠금, 재시도 로직       │
 * ├───────────────────────────────────────────────────┤
 * │   I2C Adapter Driver (I2C 컨트롤러 H/W 드라이버)  │
 * │   drivers/i2c/busses/i2c-designware-*.c (Intel)   │
 * │   drivers/i2c/busses/i2c-bcm2835.c (Raspberry Pi) │
 * │   drivers/i2c/busses/i2c-imx.c (i.MX)             │
 * │   drivers/i2c/busses/i2c-i801.c (Intel PCH SMBus) │
 * ├───────────────────────────────────────────────────┤
 * │              하드웨어 I2C/SMBus 컨트롤러           │
 * └───────────────────────────────────────────────────┘
 *
 * 핵심 구조체:
 *   struct i2c_adapter  — I2C 버스(컨트롤러) 인스턴스
 *   struct i2c_algorithm — 컨트롤러의 전송 함수 (master_xfer, smbus_xfer)
 *   struct i2c_client   — 버스에 연결된 I2C 슬레이브 디바이스
 *   struct i2c_driver   — 슬레이브 디바이스 드라이버
 *   struct i2c_msg      — 단일 I2C 메시지 (방향, 주소, 버퍼, 길이)
 */

#include <linux/i2c.h>

/* === I2C 디바이스 드라이버 (클라이언트 드라이버) === */

/* 디바이스 ID 테이블 (platform 매칭용) */
static const struct i2c_device_id my_i2c_ids[] = {
    { "my_sensor", 0 },
    { "my_sensor_v2", 1 },  /* driver_data로 변형 구분 */
    { }
};
MODULE_DEVICE_TABLE(i2c, my_i2c_ids);

/* Device Tree 매칭 */
static const struct of_device_id my_of_ids[] = {
    { .compatible = "vendor,my-sensor", .data = (void *)0 },
    { .compatible = "vendor,my-sensor-v2", .data = (void *)1 },
    { }
};
MODULE_DEVICE_TABLE(of, my_of_ids);

/* ACPI 매칭 (x86 플랫폼) */
static const struct acpi_device_id my_acpi_ids[] = {
    { "VNDR0001", 0 },  /* ACPI _HID */
    { }
};
MODULE_DEVICE_TABLE(acpi, my_acpi_ids);

static int my_i2c_probe(struct i2c_client *client)
{
    u8 reg_val;
    s32 ret;

    /* SMBus 기능 확인 */
    if (!i2c_check_functionality(client->adapter,
            I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA)) {
        dev_err(&client->dev, "SMBus byte/word 미지원\n");
        return -ENODEV;
    }

    /* === SMBus 전송 함수 (권장) === */

    /* 1바이트 레지스터 읽기 */
    ret = i2c_smbus_read_byte_data(client, 0x00);
    if (ret < 0)
        return ret;
    reg_val = ret & 0xFF;

    /* 1바이트 레지스터 쓰기 */
    ret = i2c_smbus_write_byte_data(client, 0x01, 0xFF);

    /* 2바이트(word) 읽기/쓰기 */
    s32 word = i2c_smbus_read_word_data(client, 0x02);
    i2c_smbus_write_word_data(client, 0x02, 0x1234);

    /* 블록 읽기 (최대 I2C_SMBUS_BLOCK_MAX = 32 바이트) */
    u8 block[I2C_SMBUS_BLOCK_MAX];
    ret = i2c_smbus_read_i2c_block_data(client, 0x10,
                                          sizeof(block), block);

    /* === Raw I2C 전송 (SMBus로 불가능한 경우) === */
    u8 reg_addr = 0x20;
    u8 buf[256];
    struct i2c_msg msgs[2] = {
        {   /* 첫 번째 메시지: 레지스터 주소 쓰기 */
            .addr = client->addr,
            .flags = 0,          /* 쓰기 */
            .len = 1,
            .buf = ®_addr,
        },
        {   /* 두 번째 메시지: 데이터 읽기 (Repeated START) */
            .addr = client->addr,
            .flags = I2C_M_RD,   /* 읽기 */
            .len = sizeof(buf),
            .buf = buf,
        },
    };
    ret = i2c_transfer(client->adapter, msgs, 2);
    if (ret != 2)  /* 반환값 = 성공한 메시지 수 */
        return ret < 0 ? ret : -EIO;

    return 0;
}

static struct i2c_driver my_i2c_driver = {
    .driver = {
        .name = "my_sensor",
        .of_match_table = my_of_ids,
        .acpi_match_table = my_acpi_ids,
        .pm = &my_pm_ops,          /* 전원 관리 콜백 */
    },
    .probe = my_i2c_probe,
    .id_table = my_i2c_ids,
};
module_i2c_driver(my_i2c_driver);
/* module_i2c_driver(): module_init + module_exit +
 * i2c_add_driver / i2c_del_driver를 자동 생성하는 매크로 */

/* === regmap을 통한 I2C 레지스터 접근 (권장 패턴) ===
 *
 * 소스: drivers/base/regmap/regmap-i2c.c
 *
 * regmap은 I2C/SPI/MMIO 등 다양한 버스에 대해 통일된 레지스터 접근 API를 제공.
 * 캐싱, 바이트 순서 변환, 범위 검증, 디버깅을 자동 처리.
 */
#include <linux/regmap.h>

static const struct regmap_config my_regmap_config = {
    .reg_bits = 8,               /* 레지스터 주소 비트 수 */
    .val_bits = 8,               /* 레지스터 값 비트 수 */
    .max_register = 0xFF,        /* 최대 레지스터 주소 (범위 검증) */
    .cache_type = REGCACHE_RBTREE, /* 레지스터 캐시 (suspend/resume 복원) */
    .volatile_reg = my_volatile,  /* 캐시하지 않을 레지스터 (상태 레지스터 등) */
};

static int my_probe(struct i2c_client *client)
{
    struct regmap *regmap;
    unsigned int val;

    regmap = devm_regmap_init_i2c(client, &my_regmap_config);
    if (IS_ERR(regmap))
        return PTR_ERR(regmap);

    /* 통일된 읽기/쓰기 API */
    regmap_read(regmap, 0x00, &val);
    regmap_write(regmap, 0x01, 0xFF);

    /* 비트 조작 (read-modify-write 원자적 수행) */
    regmap_update_bits(regmap, 0x02,
        0x30,    /* mask: 비트 4,5 */
        0x20);   /* val:  비트 5만 설정 */

    /* 벌크 읽기/쓰기 */
    regmap_bulk_read(regmap, 0x10, buf, 16);
    regmap_bulk_write(regmap, 0x20, data, 8);

    return 0;
}

/* suspend 시 regmap 캐시 자동 활용:
 * regcache_cache_only(regmap, true)  → H/W 접근 차단, 캐시만 사용
 * regcache_mark_dirty(regmap)        → 모든 캐시를 dirty 표시
 * regcache_cache_only(regmap, false) → H/W 접근 재개
 * regcache_sync(regmap)              → dirty 레지스터를 H/W에 기록 (resume) */

/* === I2C Adapter (컨트롤러) 드라이버 ===
 *
 * I2C 컨트롤러 하드웨어를 구동하는 드라이버.
 * i2c_algorithm을 구현하여 I2C core에 등록.
 */
static int my_i2c_xfer(struct i2c_adapter *adap,
                        struct i2c_msg *msgs, int num)
{
    struct my_i2c_dev *dev = i2c_get_adapdata(adap);
    int i;

    for (i = 0; i < num; i++) {
        if (msgs[i].flags & I2C_M_RD)
            my_hw_read(dev, &msgs[i]);    /* H/W 레지스터로 읽기 */
        else
            my_hw_write(dev, &msgs[i]);   /* H/W 레지스터로 쓰기 */
    }
    return num;  /* 성공한 메시지 수 반환 */
}

static u32 my_i2c_func(struct i2c_adapter *adap)
{
    /* 이 컨트롤러가 지원하는 기능 플래그 반환 */
    return I2C_FUNC_I2C              /* raw I2C 전송 */
         | I2C_FUNC_SMBUS_BYTE_DATA   /* SMBus byte 읽기/쓰기 */
         | I2C_FUNC_SMBUS_WORD_DATA   /* SMBus word 읽기/쓰기 */
         | I2C_FUNC_SMBUS_BLOCK_DATA  /* SMBus block 전송 */
         | I2C_FUNC_10BIT_ADDR;       /* 10-bit 주소 지원 */
}

static const struct i2c_algorithm my_i2c_algo = {
    .master_xfer = my_i2c_xfer,       /* raw I2C 전송 구현 */
    .functionality = my_i2c_func,      /* 기능 플래그 조회 */
    /* .smbus_xfer = my_smbus_xfer,  — SMBus 전용 컨트롤러일 때 */
};

/* Adapter 등록 (platform driver의 probe에서) */
static int my_i2c_controller_probe(struct platform_device *pdev)
{
    struct my_i2c_dev *dev;
    int ret;

    dev = devm_kzalloc(&pdev->dev, sizeof(*dev), GFP_KERNEL);

    dev->adap.owner = THIS_MODULE;
    dev->adap.algo = &my_i2c_algo;
    dev->adap.dev.parent = &pdev->dev;
    dev->adap.dev.of_node = pdev->dev.of_node;  /* DT 자식 디바이스 열거 */
    strlcpy(dev->adap.name, "my-i2c", sizeof(dev->adap.name));
    i2c_set_adapdata(&dev->adap, dev);

    ret = devm_i2c_add_adapter(&pdev->dev, &dev->adap);
    /* devm: remove 시 자동 i2c_del_adapter() */

    return ret;
}

/* === I2C Mux (멀티플렉서) ===
 *
 * 소스: drivers/i2c/i2c-mux.c, drivers/i2c/muxes/
 *
 * 하나의 I2C 버스를 여러 세그먼트로 분할.
 * 동일 주소의 디바이스를 서로 다른 세그먼트에 배치 가능.
 *
 * 일반적인 MUX 칩: PCA9548A (8채널), PCA9546A (4채널), TCA9548A
 *
 * Device Tree 예시:
 *   i2c-mux@70 {
 *       compatible = "nxp,pca9548";
 *       reg = <0x70>;
 *       #address-cells = <1>;
 *       #size-cells = <0>;
 *
 *       i2c@0 {  ← 채널 0 (가상 I2C 버스)
 *           reg = <0>;
 *           #address-cells = <1>;
 *           #size-cells = <0>;
 *           sensor@48 { compatible = "ti,tmp102"; reg = <0x48>; };
 *       };
 *       i2c@1 {  ← 채널 1 (같은 주소 0x48도 가능)
 *           reg = <1>;
 *           sensor@48 { compatible = "ti,tmp102"; reg = <0x48>; };
 *       };
 *   };
 *
 * 커널 내부: i2c_mux_alloc() → i2c_mux_add_adapter()
 * → 각 채널마다 가상 i2c_adapter 생성
 * → select/deselect 콜백으로 MUX 채널 전환 */

/* === I2C Slave Mode (커널 5.2+) ===
 *
 * 소스: drivers/i2c/i2c-slave-*.c
 *
 * 리눅스를 I2C 슬레이브로 동작시키는 기능.
 * 임베디드에서 BMC(Baseboard Management Controller) 등에 활용.
 *
 * i2c_slave_register(client, I2C_SLAVE_DEFAULTS, slave_cb)
 *
 * 콜백 이벤트:
 *   I2C_SLAVE_WRITE_REQUESTED — 마스터가 쓰기 시작
 *   I2C_SLAVE_WRITE_RECEIVED  — 데이터 바이트 수신
 *   I2C_SLAVE_READ_REQUESTED  — 마스터가 읽기 요청
 *   I2C_SLAVE_READ_PROCESSED  — 데이터 바이트 전송 완료
 *   I2C_SLAVE_STOP            — STOP 조건 감지
 *
 * 기본 제공 슬레이브 백엔드:
 *   i2c-slave-eeprom  — EEPROM 에뮬레이션 (256바이트)
 *   i2c-slave-testunit — 테스트용 슬레이브
 */

# === I2C/SMBus 사용자 공간 도구 (i2c-tools) ===

# 시스템의 I2C 버스 목록 확인
ls /dev/i2c-*
# /dev/i2c-0  /dev/i2c-1  /dev/i2c-2 ...

# I2C 버스 컨트롤러 정보
cat /sys/bus/i2c/devices/i2c-0/name
# "SMBus I801 adapter at efa0"  (Intel PCH)

# 버스 스캔 — 응답하는 슬레이브 주소 탐지
i2cdetect -y 0           # Quick Command 방식
i2cdetect -y -r 0        # Read Byte 방식 (Quick 미지원 디바이스)
#      0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
# 20: -- -- -- -- -- -- -- --
# 30: -- -- -- -- -- -- -- --
# 40: -- -- -- -- -- -- -- --
# 50: 50 -- -- -- -- -- -- --  ← 0x50에 디바이스 존재 (EEPROM)

# 단일 레지스터 읽기/쓰기
i2cget -y 0 0x50 0x00          # 버스0, 주소0x50, 레지스터0x00 읽기
i2cset -y 0 0x50 0x00 0xFF     # 레지스터 0x00에 0xFF 쓰기

# 전체 레지스터 덤프
i2cdump -y 0 0x50              # 기본: SMBus byte 방식
i2cdump -y -r 0x00-0x0f 0 0x50 # 범위 지정 덤프

# raw I2C 메시지 전송 (i2c-tools 4.0+)
i2ctransfer -y 0 w1@0x50 0x00 r4  # reg 0x00 쓰기 후 4바이트 읽기
# w1@0x50 = 쓰기 1바이트 주소 0x50, r4 = 읽기 4바이트
i2ctransfer -y 0 w2@0x50 0x00 0x10 0xFF  # 2바이트 레지스터 + 데이터 쓰기

# SMBus 컨트롤러 기능 확인
i2cdetect -F 0
# I2C                            yes
# SMBus Quick Command             yes
# SMBus Byte                      yes
# SMBus Byte Data                 yes
# SMBus Word Data                 yes
# SMBus Block Data                yes

# DIMM SPD EEPROM 읽기 (DDR4/DDR5 메모리 정보)
# SMBus에 연결된 DIMM SPD (주소 0x50~0x57)
i2cdump -y 0 0x50 s  # SMBus block 방식으로 SPD 덤프
decode-dimms           # i2c-tools 부가 도구: SPD 데이터를 사람이 읽을 수 있게 파싱

# 커널 I2C 디바이스 트리 확인
ls /sys/bus/i2c/devices/
# 0-0050  1-0020  i2c-0  i2c-1
# 형식: {버스번호}-{16진수주소}
cat /sys/bus/i2c/devices/0-0050/name

I3C (MIPI I3C) 서브시스템

/* === I3C (MIPI Improved Inter-Integrated Circuit) 개요 ===
 *
 * MIPI Alliance가 2017년 발표한 차세대 저속 직렬 버스 규격.
 * I2C의 한계를 극복하면서 물리적 호환성(SDA/SCL 2-wire) 유지.
 *
 * 핵심 특징:
 *
 * 1. 동적 주소 할당 (DAA — Dynamic Address Assignment)
 *    - I2C: 제조 시 고정된 7-bit 주소 → 동일 칩 다수 사용 시 충돌
 *    - I3C: 마스터가 버스 초기화 시 각 디바이스에 7-bit 주소 동적 할당
 *    - ENTDAA CCC: 디바이스의 48-bit Provisioned ID로 식별 후 주소 배정
 *    - SETDASA CCC: 레거시 I2C 디바이스에 정적 주소 설정
 *
 * 2. In-Band Interrupt (IBI)
 *    - I2C: 인터럽트마다 별도 GPIO 라인 필요 → 핀 수 증가
 *    - I3C: 슬레이브가 SDA 라인으로 직접 인터럽트 신호 전달
 *    - 마스터가 버스 유휴 시 SDA를 모니터링 → 슬레이브가 LOW로 당김
 *    - 중재 후 해당 슬레이브의 주소 + MDB(Mandatory Data Byte) 수신
 *    - → 추가 GPIO 핀 불필요 → 패키지 크기/비용 절감
 *
 * 3. HDR (High Data Rate) 모드
 *    - SDR (Single Data Rate): 12.5 Mbps (기본, 오픈 드레인/푸시풀 혼합)
 *    - HDR-DDR (Double Data Rate): 25 Mbps (양 에지 데이터 전송)
 *    - HDR-TSP (Ternary Symbol Pure): 25 Mbps (3-레벨 신호)
 *    - HDR-TSL (Ternary Symbol Legacy): HDR-TSP + I2C 호환 레벨
 *    - HDR-BT (Bulk Transport): 최대 50 Mbps (I3C v1.1.1)
 *
 * 4. Hot-Join
 *    - 동작 중인 버스에 새 디바이스 추가 가능
 *    - 새 디바이스가 Hot-Join 요청 → 마스터가 DAA 수행 → 주소 할당
 *
 * 5. CCC (Common Command Codes)
 *    - 브로드캐스트 CCC: 모든 디바이스에 전달 (RSTDAA, ENEC, DISEC 등)
 *    - 다이렉트 CCC: 특정 디바이스에 전달 (SETDASA, GETMRL 등)
 */

/* === I3C 버스 초기화 순서 ===
 *
 * 1. 마스터가 SCL을 12.5MHz로 설정, 버스 리셋
 * 2. RSTDAA (브로드캐스트) — 기존 동적 주소 모두 해제
 * 3. SETDASA (다이렉트)  — 레거시 I2C 디바이스에 정적 주소 할당
 * 4. ENTDAA (브로드캐스트) — I3C 디바이스 동적 주소 할당
 *    ├── 각 디바이스가 48-bit PID(Provisioned ID) 응답
 *    │     ├── bits[47:33] — MIPI 제조사 ID
 *    │     ├── bits[32]    — ID 유형 (랜덤/고정)
 *    │     └── bits[31:0]  — 파트/인스턴스 번호
 *    ├── BCR (Bus Characteristics Register, 8-bit)
 *    │     ├── bit[7:6] — 디바이스 역할 (I3C slave, Master-capable 등)
 *    │     ├── bit[5]   — HDR 지원 여부
 *    │     ├── bit[3]   — IBI 페이로드 유무
 *    │     └── bit[1]   — IBI 요청 가능 여부
 *    ├── DCR (Device Characteristics Register, 8-bit)
 *    │     → 디바이스 타입: 가속도계, 자이로, 기압계, 온도 등
 *    └── 마스터가 7-bit 동적 주소 배정 → ACK → 다음 디바이스
 *
 * 5. ENEC (브로드캐스트) — IBI, Hot-Join 이벤트 활성화
 * 6. 정상 통신 시작 (SDR 또는 HDR 모드)
 */

/* === 리눅스 I3C 서브시스템 아키텍처 (커널 5.0+) ===
 *
 * 소스: drivers/i3c/
 *
 * ┌───────────────────────────────────────────────────┐
 * │           사용자 공간 (향후 i3c-tools 등)         │
 * ├───────────────────────────────────────────────────┤
 * │              I3C Core (drivers/i3c/master.c)      │
 * │   i3c_device_do_priv_xfers()  — 프라이빗 전송     │
 * │   i3c_device_send_ccc_cmd()   — CCC 명령          │
 * │   DAA 수행, IBI 관리, 디바이스 등록/매칭           │
 * ├───────────────────────────────────────────────────┤
 * │   I3C Master Controller Driver                    │
 * │   drivers/i3c/master/dw-i3c-master.c (DesignWare) │
 * │   drivers/i3c/master/svc-i3c-master.c (Silvaco)   │
 * │   drivers/i3c/master/mipi-i3c-hci.c (MIPI HCI)    │
 * │   drivers/i3c/master/cdns-i3c-master.c (Cadence)   │
 * ├───────────────────────────────────────────────────┤
 * │              하드웨어 I3C 컨트롤러                 │
 * └───────────────────────────────────────────────────┘
 *
 * 핵심 구조체:
 *   struct i3c_master_controller — I3C 마스터 인스턴스
 *   struct i3c_master_controller_ops — 컨트롤러 드라이버 콜백
 *   struct i3c_device             — I3C 디바이스 (동적 주소 보유)
 *   struct i3c_driver             — I3C 디바이스 드라이버
 *   struct i2c_dev_desc           — I3C 버스의 레거시 I2C 디바이스
 */

/* === I3C 디바이스 드라이버 예시 === */
#include <linux/i3c/device.h>
#include <linux/i3c/master.h>

static const struct i3c_device_id my_i3c_ids[] = {
    /* MIPI 제조사 ID + 파트 ID + 추가 정보 */
    I3C_DEVICE(0x0123, 0x0456, NULL),
    /* 또는 DCR 기반 매칭 (디바이스 타입별) */
    I3C_DEVICE_EXTRA_INFO(0x0123, 0x0456, 0, NULL),
    { }
};
MODULE_DEVICE_TABLE(i3c, my_i3c_ids);

static int my_i3c_probe(struct i3c_device *i3cdev)
{
    struct i3c_device_info info;
    u8 tx_buf[2], rx_buf[4];

    /* 디바이스 정보 조회 (PID, BCR, DCR, 동적 주소) */
    i3c_device_get_info(i3cdev, &info);
    dev_info(&i3cdev->dev,
        "PID: 0x%012llx, BCR: 0x%02x, DCR: 0x%02x, addr: 0x%02x\n",
        info.pid, info.bcr, info.dcr, info.dyn_addr);

    /* === 프라이빗 전송 (SDR 모드) ===
     * I2C의 i2c_transfer()에 해당 */
    struct i3c_priv_xfer xfers[2] = {
        {   /* 레지스터 주소 쓰기 */
            .rnw = false,         /* 쓰기 */
            .len = sizeof(tx_buf),
            .data.out = tx_buf,
        },
        {   /* 데이터 읽기 */
            .rnw = true,          /* 읽기 */
            .len = sizeof(rx_buf),
            .data.in = rx_buf,
        },
    };
    tx_buf[0] = 0x00;  /* 레지스터 주소 */
    i3c_device_do_priv_xfers(i3cdev, xfers, 2);

    /* === IBI (In-Band Interrupt) 등록 === */
    struct i3c_ibi_setup ibi_setup = {
        .handler = my_ibi_handler,     /* IBI 수신 콜백 */
        .max_payload_len = 2,          /* IBI 페이로드 최대 크기 */
        .num_slots = 4,                /* IBI 큐 슬롯 수 */
    };
    i3c_device_request_ibi(i3cdev, &ibi_setup);
    i3c_device_enable_ibi(i3cdev);

    return 0;
}

/* IBI 핸들러 — 워크큐 컨텍스트에서 호출 */
static void my_ibi_handler(struct i3c_device *i3cdev,
                            const struct i3c_ibi_payload *payload)
{
    /* payload->data: IBI와 함께 전달된 데이터 (MDB + 추가 바이트)
     * payload->len:  페이로드 길이
     * MDB(Mandatory Data Byte): 인터럽트 원인 식별자 */
    dev_dbg(&i3cdev->dev, "IBI: MDB=0x%02x, len=%zu\n",
        payload->data[0], payload->len);
}

static void my_i3c_remove(struct i3c_device *i3cdev)
{
    i3c_device_disable_ibi(i3cdev);
    i3c_device_free_ibi(i3cdev);
}

static struct i3c_driver my_i3c_driver = {
    .driver = { .name = "my_i3c_sensor" },
    .probe = my_i3c_probe,
    .remove = my_i3c_remove,
    .id_table = my_i3c_ids,
};
module_i3c_driver(my_i3c_driver);

/* === I3C Master Controller 드라이버 핵심 콜백 ===
 *
 * 컨트롤러 하드웨어를 구동하는 드라이버가 구현해야 하는 ops:
 */
struct i3c_master_controller_ops {
    /* 버스 초기화 (DAA 수행, 클럭 설정 등) */
    int (*bus_init)(struct i3c_master_controller *master);
    void (*bus_cleanup)(struct i3c_master_controller *master);

    /* 동적 주소 할당 (ENTDAA 수행) */
    int (*do_daa)(struct i3c_master_controller *master);

    /* I3C 프라이빗 전송 (SDR/HDR) */
    int (*send_ccc_cmd)(struct i3c_master_controller *master,
                         struct i3c_ccc_cmd *cmd);
    int (*priv_xfers)(struct i3c_dev_desc *dev,
                       struct i3c_priv_xfer *xfers, int nxfers);

    /* 레거시 I2C 전송 (버스의 I2C 디바이스용) */
    int (*i2c_xfers)(struct i2c_dev_desc *dev,
                      const struct i2c_msg *xfers, int nxfers);

    /* IBI (In-Band Interrupt) 관리 */
    int (*request_ibi)(struct i3c_dev_desc *dev,
                        const struct i3c_ibi_setup *req);
    void (*free_ibi)(struct i3c_dev_desc *dev);
    int (*enable_ibi)(struct i3c_dev_desc *dev);
    int (*disable_ibi)(struct i3c_dev_desc *dev);
    void (*recycle_ibi_slot)(struct i3c_dev_desc *dev,
                              struct i3c_ibi_slot *slot);
};

/* Device Tree 예시:
 *
 * i3c-master@d040000 {
 *     compatible = "snps,dw-i3c-master";
 *     reg = <0x0d040000 0x1000>;
 *     interrupts = ;
 *     clocks = <&i3c_clk>;
 *     #address-cells = <3>;  ← I3C: 3셀 (정적주소, PID 상위, PID 하위)
 *     #size-cells = <0>;
 *     i2c-scl-hz = <400000>;   ← 레거시 I2C SCL 속도
 *     i3c-scl-hz = <12500000>; ← I3C SCL 속도
 *
 *     ← I3C 디바이스 (동적 주소 할당 대상)
 *     sensor@0,11220000000 {
 *         reg = <0 0x112 0x20000000>;  ← 정적주소=0, PID
 *         assigned-address = <0x09>;    ← 원하는 동적 주소 (힌트)
 *     };
 *
 *     ← 레거시 I2C 디바이스 (정적 주소)
 *     eeprom@50 {
 *         compatible = "atmel,24c64";
 *         reg = <0x50 0 0>;  ← I2C 주소 0x50
 *     };
 * };
 */

SPI 서브시스템

/* === SPI (Serial Peripheral Interface) 프로토콜 개요 ===
 *
 * Motorola가 1980년대 개발한 전이중(full-duplex) 동기식 직렬 버스.
 * I2C보다 빠른 속도가 필요한 주변장치(Flash, ADC/DAC, 디스플레이, 센서) 연결에 사용.
 *
 * 물리 계층 (4-wire 기본):
 *   SCLK (Serial Clock)  — 마스터가 생성하는 클럭
 *   MOSI (Master Out Slave In) — 마스터→슬레이브 데이터 (= SDO, COPI)
 *   MISO (Master In Slave Out) — 슬레이브→마스터 데이터 (= SDI, CIPO)
 *   CS/SS (Chip Select)   — 슬레이브 선택 (Active Low, 디바이스별 1개)
 *
 *   ┌──────────┐          SCLK           ┌──────────┐
 *   │          │─────────────────────────→│          │
 *   │          │          MOSI            │          │
 *   │  Master  │─────────────────────────→│  Slave   │
 *   │  (SoC)   │          MISO            │ (Flash)  │
 *   │          │←─────────────────────────│          │
 *   │          │          CS#             │          │
 *   │          │─────────────────────────→│          │
 *   └──────────┘                          └──────────┘
 *
 * I2C와의 핵심 차이:
 *   - 풀업 저항 불필요 (푸시풀 출력)
 *   - 주소 체계 없음 — CS 라인으로 디바이스 선택
 *   - 전이중 통신 — 동시에 송수신 가능
 *   - 클럭 속도 제한 없음 — 수십~수백 MHz 가능 (PCB 설계가 제한 요인)
 *   - 디바이스마다 CS 핀 1개 필요 → 다수 디바이스 시 핀 소모
 *
 * SPI 모드 (CPOL/CPHA):
 *   ┌──────┬──────┬──────┬─────────────────────────────────────┐
 *   │ Mode │ CPOL │ CPHA │ 설명                                │
 *   ├──────┼──────┼──────┼─────────────────────────────────────┤
 *   │  0   │  0   │  0   │ 유휴=LOW,  첫 번째 에지(상승)에서 샘플 │
 *   │  1   │  0   │  1   │ 유휴=LOW,  두 번째 에지(하강)에서 샘플 │
 *   │  2   │  1   │  0   │ 유휴=HIGH, 첫 번째 에지(하강)에서 샘플 │
 *   │  3   │  1   │  1   │ 유휴=HIGH, 두 번째 에지(상승)에서 샘플 │
 *   └──────┴──────┴──────┴─────────────────────────────────────┘
 *
 * 변형 프로토콜:
 *   - Dual SPI: MOSI/MISO를 양방향 2-bit으로 → 2배 속도 (QSPI Flash 읽기)
 *   - Quad SPI (QSPI): 4-bit 데이터 라인 → 4배 속도 (NOR Flash 표준)
 *   - Octal SPI (OSPI): 8-bit 데이터 라인 → 8배 속도 (xSPI/HyperBus)
 *   - 3-wire SPI: MOSI/MISO를 단일 양방향 라인으로 (반이중)
 */

/* === 리눅스 SPI 서브시스템 아키텍처 ===
 *
 * 소스: drivers/spi/
 *
 * ┌────────────────────────────────────────────────────────┐
 * │          사용자 공간                                    │
 * │   /dev/spidevB.C  (B=버스, C=CS)                       │
 * │   libgpiod, spi-tools, flashrom 등                     │
 * ├────────────────────────────────────────────────────────┤
 * │          SPI Core (drivers/spi/spi.c)                  │
 * │   spi_sync() / spi_async()  — 메시지 전송              │
 * │   spi_register_controller() — 컨트롤러 등록            │
 * │   spi_register_driver()     — 디바이스 드라이버 등록    │
 * │   DMA 매핑, CS 관리, 큐 처리, 통계                     │
 * ├────────────────────────────────────────────────────────┤
 * │   SPI Controller Driver (= Master Driver)              │
 * │   drivers/spi/spi-bcm2835.c   (Raspberry Pi)           │
 * │   drivers/spi/spi-sun6i.c     (Allwinner)              │
 * │   drivers/spi/spi-stm32.c     (STM32)                  │
 * │   drivers/spi/spi-rockchip.c  (Rockchip)               │
 * │   drivers/spi/spi-imx.c       (i.MX)                   │
 * │   drivers/spi/spi-pl022.c     (ARM PrimeCell)           │
 * ├────────────────────────────────────────────────────────┤
 * │          하드웨어 SPI 컨트롤러 (FIFO, DMA 채널)         │
 * └────────────────────────────────────────────────────────┘
 *
 * 핵심 구조체:
 *   struct spi_controller  — SPI 마스터/슬레이브 컨트롤러 인스턴스
 *   struct spi_device      — SPI 버스의 개별 디바이스 (CS, 모드, 속도 보유)
 *   struct spi_driver      — SPI 디바이스 드라이버 (probe/remove 콜백)
 *   struct spi_transfer    — 단일 전송 단위 (tx_buf, rx_buf, len, speed_hz)
 *   struct spi_message     — 전송 묶음 (atomic CS assert ~ deassert)
 */

/* === SPI 디바이스 드라이버 개발 === */
#include <linux/spi/spi.h>
#include <linux/module.h>

struct my_spi_data {
    struct spi_device *spi;
    u8 tx_buf[64] ____cacheline_aligned;  /* DMA 정렬 */
    u8 rx_buf[64] ____cacheline_aligned;
};

static int my_spi_read_reg(struct my_spi_data *priv,
                            u8 reg, u8 *val, size_t len)
{
    struct spi_transfer xfers[2] = {
        {
            .tx_buf = ®,
            .len = 1,
        },
        {
            .rx_buf = val,
            .len = len,
        },
    };
    struct spi_message msg;

    /* spi_message에 transfer 체인 구성 */
    spi_message_init(&msg);
    spi_message_add_tail(&xfers[0], &msg);
    spi_message_add_tail(&xfers[1], &msg);

    /* 동기 전송: CS assert → xfers[0] → xfers[1] → CS deassert */
    return spi_sync(priv->spi, &msg);
}

static int my_spi_probe(struct spi_device *spi)
{
    struct my_spi_data *priv;
    u8 chip_id;
    int ret;

    /* SPI 모드, 비트 순서, 워드 크기 설정 */
    spi->mode = SPI_MODE_0;       /* CPOL=0, CPHA=0 */
    spi->bits_per_word = 8;
    spi->max_speed_hz = 10000000; /* 10 MHz */
    ret = spi_setup(spi);
    if (ret)
        return ret;

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

    priv->spi = spi;
    spi_set_drvdata(spi, priv);

    /* Chip ID 읽기 */
    ret = my_spi_read_reg(priv, 0x00, &chip_id, 1);
    if (ret)
        return ret;

    dev_info(&spi->dev, "Chip ID: 0x%02x, SPI mode %d, %u Hz\n",
        chip_id, spi->mode, spi->max_speed_hz);

    return 0;
}

/* SPI 간편 API — 단일 전송 시 spi_message 구성 불필요 */
static int my_spi_simple_ops(struct spi_device *spi)
{
    u8 cmd = 0x9F;        /* JEDEC Read ID */
    u8 id[3];
    int ret;

    /* spi_write(): 단순 쓰기 (CS assert → 데이터 전송 → CS deassert) */
    ret = spi_write(spi, &cmd, 1);

    /* spi_read(): 단순 읽기 */
    ret = spi_read(spi, id, 3);

    /* spi_write_then_read(): 쓰기 후 읽기 (가장 많이 사용)
     * 내부적으로 임시 DMA 버퍼 할당 → 소량 데이터에 적합 */
    ret = spi_write_then_read(spi, &cmd, 1, id, 3);
    /* id[0]=제조사, id[1]=메모리타입, id[2]=용량 */

    /* spi_w8r8(): 1바이트 쓰고 1바이트 읽기 (레지스터 읽기) */
    ret = spi_w8r8(spi, 0x05);  /* 상태 레지스터 읽기, 반환값=레지스터값 */

    /* spi_w8r16(): 1바이트 쓰고 2바이트 읽기 (16-bit 레지스터) */
    ret = spi_w8r16(spi, 0x01); /* 반환값=16bit 값 (big-endian) */

    return ret;
}

/* Device Tree / ACPI 매칭 테이블 */
static const struct of_device_id my_spi_of_match[] = {
    { .compatible = "vendor,my-spi-sensor" },
    { .compatible = "vendor,my-spi-adc", .data = &adc_chip_info },
    { }
};
MODULE_DEVICE_TABLE(of, my_spi_of_match);

static const struct spi_device_id my_spi_ids[] = {
    { "my-spi-sensor", 0 },
    { "my-spi-adc",    1 },
    { }
};
MODULE_DEVICE_TABLE(spi, my_spi_ids);

static struct spi_driver my_spi_driver = {
    .driver = {
        .name = "my-spi-device",
        .of_match_table = my_spi_of_match,
    },
    .probe = my_spi_probe,
    .id_table = my_spi_ids,
};
module_spi_driver(my_spi_driver);

/* === SPI 비동기 전송 (고성능/DMA) ===
 *
 * spi_async()는 비블로킹. 완료 시 콜백 호출.
 * DMA 전송 시 반드시 DMA-safe 버퍼 사용 (kmalloc, not stack/global).
 */

static void my_spi_complete(void *context)
{
    struct completion *done = context;
    complete(done);
}

static int my_spi_async_xfer(struct my_spi_data *priv,
                              u8 *tx, u8 *rx, size_t len)
{
    struct spi_transfer xfer = {
        .tx_buf = tx,
        .rx_buf = rx,
        .len = len,
        .speed_hz = 20000000,   /* 전송별 속도 오버라이드 */
        .bits_per_word = 8,
    };
    struct spi_message msg;
    DECLARE_COMPLETION_ONSTACK(done);

    spi_message_init(&msg);
    spi_message_add_tail(&xfer, &msg);
    msg.complete = my_spi_complete;
    msg.context = &done;

    /* 비블로킹 전송 — 즉시 반환, 완료 시 콜백 */
    int ret = spi_async(priv->spi, &msg);
    if (ret)
        return ret;

    /* 완료 대기 (또는 워크큐에서 처리) */
    wait_for_completion(&done);
    return msg.status;
}

/* === SPI와 regmap 통합 ===
 *
 * I2C와 동일하게 regmap API로 통합 접근 가능.
 * 내부적으로 SPI 전송을 자동 처리.
 */
#include <linux/regmap.h>

static const struct regmap_config my_spi_regmap_cfg = {
    .reg_bits = 8,          /* 레지스터 주소 비트 수 */
    .val_bits = 8,          /* 레지스터 값 비트 수 */
    .max_register = 0xFF,
    .read_flag_mask = 0x80,  /* 읽기 시 레지스터 주소에 OR (디바이스 관례) */
    .cache_type = REGCACHE_RBTREE,
};

/* probe에서: */
struct regmap *regmap = devm_regmap_init_spi(spi, &my_spi_regmap_cfg);
regmap_read(regmap, 0x00, &chip_id);   /* 내부적으로 SPI 전송 */
regmap_write(regmap, 0x01, 0x42);      /* 레지스터 쓰기 */
regmap_update_bits(regmap, 0x02, 0x0F, 0x05); /* RMW */

/* === SPI 컨트롤러 (Master) 드라이버 핵심 구조 ===
 *
 * SoC의 SPI 하드웨어 블록을 제어하는 드라이버.
 * spi_controller 구조체의 콜백을 구현.
 */

static int my_spi_transfer_one(struct spi_controller *ctlr,
                                struct spi_device *spi,
                                struct spi_transfer *xfer)
{
    /* 하드웨어 레지스터에 FIFO/DMA로 데이터 전송
     *
     * xfer->tx_buf  — 송신 데이터 (NULL이면 더미 바이트 전송)
     * xfer->rx_buf  — 수신 버퍼   (NULL이면 수신 데이터 폐기)
     * xfer->len     — 전송 바이트 수
     * xfer->speed_hz — 이 전송의 클럭 속도
     * xfer->bits_per_word — 워드 크기 (8, 16, 32)
     *
     * 반환: 0=완료, 1=진행중(비동기 완료 시 spi_finalize_current_transfer 호출)
     */

    /* 클럭 분주비 설정 */
    my_hw_set_speed(ctlr, xfer->speed_hz);

    /* FIFO 방식 전송 예시 */
    for (int i = 0; i < xfer->len; i++) {
        if (xfer->tx_buf)
            writel(xfer->tx_buf[i], regs + SPI_TX_FIFO);
        else
            writel(0x00, regs + SPI_TX_FIFO);

        /* TX 완료 대기 */
        my_hw_wait_tx_done(ctlr);

        if (xfer->rx_buf)
            xfer->rx_buf[i] = readl(regs + SPI_RX_FIFO);
    }

    return 0;
}

static int my_spi_controller_probe(struct platform_device *pdev)
{
    struct spi_controller *ctlr;

    /* SPI 마스터 컨트롤러 할당 (0 = 추가 private 데이터 크기) */
    ctlr = devm_spi_alloc_master(&pdev->dev, 0);
    if (!ctlr)
        return -ENOMEM;

    /* 컨트롤러 능력 설정 */
    ctlr->mode_bits = SPI_CPOL | SPI_CPHA | SPI_CS_HIGH | SPI_LSB_FIRST;
    ctlr->bits_per_word_mask = SPI_BPW_MASK(8) | SPI_BPW_MASK(16);
    ctlr->min_speed_hz = 100000;     /* 100 KHz */
    ctlr->max_speed_hz = 50000000;   /* 50 MHz */
    ctlr->num_chipselect = 4;        /* CS 라인 수 */
    ctlr->bus_num = -1;              /* 자동 할당 */

    /* 핵심 콜백 등록 */
    ctlr->transfer_one = my_spi_transfer_one;
    ctlr->set_cs = my_spi_set_cs;    /* CS assert/deassert */
    ctlr->use_gpio_descriptors = true; /* DT의 cs-gpios 자동 처리 */

    /* DMA 지원 설정 (선택) */
    ctlr->can_dma = my_spi_can_dma;
    ctlr->max_dma_len = 65536;

    platform_set_drvdata(pdev, ctlr);
    return devm_spi_register_controller(&pdev->dev, ctlr);
}

/* === SPI Device Tree 바인딩 ===
 *
 * SPI 컨트롤러 노드 아래에 슬레이브 디바이스를 자식 노드로 정의.
 * reg 속성은 CS(Chip Select) 번호.
 */

/* spi0: spi@fe204000 {
 *     compatible = "brcm,bcm2835-spi";
 *     reg = <0xfe204000 0x200>;
 *     interrupts = ;
 *     clocks = <&clk_spi>;
 *     #address-cells = <1>;   ← CS 번호
 *     #size-cells = <0>;
 *     cs-gpios = <&gpio 8 GPIO_ACTIVE_LOW>,   ← CS0: GPIO8
 *                <&gpio 7 GPIO_ACTIVE_LOW>;    ← CS1: GPIO7
 *     dmas = <&dma 6>, <&dma 7>;
 *     dma-names = "tx", "rx";
 *     status = "okay";
 *
 *     ← CS0에 연결된 NOR Flash
 *     flash@0 {
 *         compatible = "jedec,spi-nor";
 *         reg = <0>;                    ← CS 번호 = 0
 *         spi-max-frequency = <50000000>; ← 최대 50MHz
 *         spi-rx-bus-width = <4>;       ← Quad SPI 읽기 (4-bit)
 *         spi-tx-bus-width = <1>;       ← 단일 라인 쓰기
 *         m25p,fast-read;               ← Fast Read 명령 사용
 *
 *         partitions {
 *             compatible = "fixed-partitions";
 *             #address-cells = <1>;
 *             #size-cells = <1>;
 *
 *             boot@0 {
 *                 reg = <0x000000 0x100000>; ← 1MB 부트 파티션
 *                 label = "boot";
 *             };
 *             rootfs@100000 {
 *                 reg = <0x100000 0xF00000>;
 *                 label = "rootfs";
 *             };
 *         };
 *     };
 *
 *     ← CS1에 연결된 ADC
 *     adc@1 {
 *         compatible = "ti,ads7950";
 *         reg = <1>;                    ← CS 번호 = 1
 *         spi-max-frequency = <10000000>;
 *         spi-cpol;                     ← CPOL=1 (Mode 2 or 3)
 *         spi-cpha;                     ← CPHA=1 (Mode 1 or 3) → Mode 3
 *         #io-channel-cells = <1>;
 *         vref-supply = <&vref_3v3>;
 *     };
 * }; */

/* === spidev — 유저스페이스 SPI 접근 ===
 *
 * /dev/spidevB.C (B=버스번호, C=CS번호)를 통해
 * 유저스페이스에서 직접 SPI 전송 가능.
 *
 * Device Tree에서 spidev 활성화:
 *   test_device@0 {
 *       compatible = "linux,spidev";  ← 또는 "rohm,dh2228fv" 등
 *       reg = <0>;
 *       spi-max-frequency = <1000000>;
 *   };
 */

/* 유저스페이스 SPI 프로그래밍 예시 */
#include <fcntl.h>
#include <linux/spi/spidev.h>
#include <sys/ioctl.h>

int main(void)
{
    int fd = open("/dev/spidev0.0", O_RDWR);

    /* SPI 모드 설정 */
    uint8_t mode = SPI_MODE_0;
    ioctl(fd, SPI_IOC_WR_MODE, &mode);

    /* 클럭 속도 설정 */
    uint32_t speed = 1000000;  /* 1 MHz */
    ioctl(fd, SPI_IOC_WR_MAX_SPEED_HZ, &speed);

    /* 전이중 전송 (ioctl) */
    uint8_t tx[] = {0x9F, 0x00, 0x00, 0x00};
    uint8_t rx[4] = {0};

    struct spi_ioc_transfer tr = {
        .tx_buf = (unsigned long)tx,
        .rx_buf = (unsigned long)rx,
        .len = 4,
        .speed_hz = speed,
        .bits_per_word = 8,
    };
    ioctl(fd, SPI_IOC_MESSAGE(1), &tr);
    /* rx[1..3] = JEDEC ID (제조사, 타입, 용량) */

    close(fd);
    return 0;
}

# SPI 디버깅/확인 명령

# 등록된 SPI 디바이스 확인
ls /sys/bus/spi/devices/
# spi0.0  spi0.1  spi1.0
# 형식: spi{버스}.{CS}

# SPI 디바이스 상세 정보
cat /sys/bus/spi/devices/spi0.0/modalias
# spi:spidev
cat /sys/bus/spi/devices/spi0.0/max_speed_hz
# 1000000

# SPI 컨트롤러 통계 (커널 4.16+)
cat /sys/class/spi_master/spi0/statistics/transfers
cat /sys/class/spi_master/spi0/statistics/bytes
cat /sys/class/spi_master/spi0/statistics/errors

# spi-tools를 이용한 유저스페이스 전송
# spi-config -d /dev/spidev0.0 -q  # 현재 설정 조회
# spi-pipe -d /dev/spidev0.0 -s 1000000 < tx_data > rx_data

# flashrom으로 SPI NOR Flash 읽기/쓰기
# flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=10000 -r backup.bin

GPIO 서브시스템

/* === GPIO (General Purpose Input/Output) 서브시스템 개요 ===
 *
 * GPIO는 소프트웨어로 제어 가능한 범용 디지털 핀.
 * LED 제어, 버튼 입력, 리셋 신호, 인터럽트, CS 라인 등에 사용.
 *
 * 리눅스 GPIO 서브시스템 아키텍처:
 *
 * ┌─────────────────────────────────────────────────────────────┐
 * │              사용자 공간                                     │
 * │   /dev/gpiochipN  (libgpiod, gpioget, gpioset, gpiomon)    │
 * │   /sys/class/gpio/ (레거시 sysfs — deprecated)              │
 * ├─────────────────────────────────────────────────────────────┤
 * │              GPIO Character Device (drivers/gpio/gpiolib-cdev.c) │
 * │   GPIO_V2_GET_LINE_IOCTL  — 라인 요청                      │
 * │   GPIO_V2_LINE_SET_VALUES — 값 설정                         │
 * │   GPIO_V2_LINE_GET_VALUES — 값 읽기                         │
 * │   poll()/read()           — 에지 이벤트 감지                │
 * ├─────────────────────────────────────────────────────────────┤
 * │              gpiolib Core (drivers/gpio/gpiolib.c)          │
 * │   gpiod_get() / gpiod_set_value() — descriptor API         │
 * │   gpiochip_add_data()             — 칩 등록                 │
 * │   GPIO ↔ IRQ 도메인 연결                                    │
 * │   pinctrl 연동 (GPIO muxing)                                │
 * ├─────────────────────────────────────────────────────────────┤
 * │   GPIO Controller Drivers (gpio_chip 구현)                  │
 * │   drivers/gpio/gpio-mmio.c     (MMIO 기반 범용)             │
 * │   drivers/gpio/gpio-pl061.c    (ARM PrimeCell)              │
 * │   drivers/gpio/gpio-dwapb.c    (DesignWare APB)             │
 * │   drivers/gpio/gpio-pca953x.c  (I2C GPIO expander)         │
 * │   drivers/gpio/gpio-mcp23s08.c (SPI GPIO expander)         │
 * │   drivers/gpio/gpio-rockchip.c (Rockchip)                  │
 * ├─────────────────────────────────────────────────────────────┤
 * │              하드웨어 GPIO 컨트롤러 (SoC / I2C / SPI)       │
 * └─────────────────────────────────────────────────────────────┘
 *
 * API 진화 (반드시 최신 API 사용):
 *   v1 (레거시): gpio_request() / gpio_set_value() — deprecated
 *   v2 (현재):   gpiod_get()    / gpiod_set_value() — descriptor 기반
 *   sysfs:       /sys/class/gpio/export — deprecated (커널 4.8+에서 chardev 도입)
 *   chardev:     /dev/gpiochipN + ioctl — 현재 권장 유저스페이스 인터페이스
 */

/* === GPIO 소비자 API (커널 드라이버에서 GPIO 사용) === */
#include <linux/gpio/consumer.h>

static int my_probe(struct platform_device *pdev)
{
    struct gpio_desc *reset_gpio, *irq_gpio;
    struct gpio_descs *leds;

    /* === 기본: 단일 GPIO 가져오기 ===
     * devm_gpiod_get(dev, con_id, flags)
     *   con_id: DT의 "{con_id}-gpios" 속성에서 가져옴
     *   flags:  GPIOD_OUT_LOW, GPIOD_OUT_HIGH, GPIOD_IN,
     *           GPIOD_OUT_LOW_OPEN_DRAIN, GPIOD_ASIS
     */
    reset_gpio = devm_gpiod_get(&pdev->dev, "reset", GPIOD_OUT_HIGH);
    if (IS_ERR(reset_gpio))
        return PTR_ERR(reset_gpio);

    /* === 선택적 GPIO (없어도 에러 아님) === */
    struct gpio_desc *enable_gpio;
    enable_gpio = devm_gpiod_get_optional(&pdev->dev, "enable", GPIOD_OUT_LOW);
    /* NULL 반환이면 DT에 해당 GPIO 없음 → 정상 */

    /* === 복수 GPIO 한번에 가져오기 === */
    leds = devm_gpiod_get_array(&pdev->dev, "led", GPIOD_OUT_LOW);
    /* DT: led-gpios = <&gpio1 0 0>, <&gpio1 1 0>, <&gpio1 2 0>;
     * leds->ndescs = 3, leds->desc[0..2] */

    /* === 인덱스로 GPIO 가져오기 (동일 이름 복수) === */
    struct gpio_desc *cs_gpio;
    cs_gpio = devm_gpiod_get_index(&pdev->dev, "cs", 1, GPIOD_OUT_HIGH);
    /* DT: cs-gpios = <&gpio1 8 0>, <&gpio1 7 0>; → index 1 = gpio1 7 */

    /* === GPIO 출력 제어 === */
    gpiod_set_value_cansleep(reset_gpio, 0);  /* 논리 LOW */
    msleep(10);
    gpiod_set_value_cansleep(reset_gpio, 1);  /* 논리 HIGH */

    /* === 복수 GPIO 한번에 설정 === */
    unsigned long values[] = { 0x05 }; /* 비트마스크: LED0=1, LED1=0, LED2=1 */
    gpiod_set_array_value_cansleep(leds->ndescs, leds->desc,
                                    leds->info, values);

    /* === GPIO 입력 읽기 === */
    int val = gpiod_get_value_cansleep(irq_gpio); /* 0 또는 1 (논리값) */

    /* === GPIO 방향 런타임 변경 === */
    gpiod_direction_output(reset_gpio, 1); /* 출력으로 변경, 값=1 */
    gpiod_direction_input(reset_gpio);      /* 입력으로 변경 */

    /* === GPIO → 인터럽트 변환 === */
    irq_gpio = devm_gpiod_get(&pdev->dev, "irq", GPIOD_IN);
    int irq = gpiod_to_irq(irq_gpio);
    if (irq < 0)
        return irq;

    devm_request_threaded_irq(&pdev->dev, irq,
        NULL,              /* hardirq handler (NULL → threaded only) */
        my_irq_handler,    /* threaded handler */
        IRQF_TRIGGER_FALLING | IRQF_ONESHOT,
        "my_gpio_irq", priv);

    return 0;
}

/* === Device Tree 예시 === */
/* my_device {
 *     compatible = "vendor,my-device";
 *
 *     // GPIO 소비자 속성 (이름-gpios = <&컨트롤러 핀번호 플래그>)
 *     reset-gpios = <&gpio1 5 GPIO_ACTIVE_LOW>;
 *     irq-gpios   = <&gpio2 12 GPIO_ACTIVE_HIGH>;
 *     enable-gpios = <&gpio1 20 GPIO_ACTIVE_HIGH>;
 *
 *     // 복수 GPIO (배열)
 *     led-gpios = <&gpio1 0 GPIO_ACTIVE_HIGH>,  // LED0
 *                 <&gpio1 1 GPIO_ACTIVE_HIGH>,  // LED1
 *                 <&gpio1 2 GPIO_ACTIVE_LOW>;   // LED2 (active low)
 *
 *     // CS GPIO (SPI 컨트롤러에서도 사용)
 *     cs-gpios = <&gpio1 8 GPIO_ACTIVE_LOW>,
 *                <&gpio1 7 GPIO_ACTIVE_LOW>;
 * }; */

/* === GPIO 컨트롤러 드라이버 (gpio_chip 구현) ===
 *
 * SoC 내장 GPIO 블록이나 I2C/SPI GPIO expander를 제어.
 * struct gpio_chip의 콜백을 구현.
 */
#include <linux/gpio/driver.h>

struct my_gpio {
    struct gpio_chip gc;
    void __iomem *regs;
    struct irq_chip irq_chip;
    raw_spinlock_t lock;
};

/* 방향 설정 콜백 */
static int my_gpio_direction_input(struct gpio_chip *gc,
                                    unsigned int offset)
{
    struct my_gpio *priv = gpiochip_get_data(gc);
    u32 val;
    unsigned long flags;

    raw_spin_lock_irqsave(&priv->lock, flags);
    val = readl(priv->regs + GPIO_DIR_REG);
    val &= ~BIT(offset);   /* 0 = 입력 */
    writel(val, priv->regs + GPIO_DIR_REG);
    raw_spin_unlock_irqrestore(&priv->lock, flags);

    return 0;
}

static int my_gpio_direction_output(struct gpio_chip *gc,
                                     unsigned int offset, int value)
{
    struct my_gpio *priv = gpiochip_get_data(gc);
    u32 val;
    unsigned long flags;

    raw_spin_lock_irqsave(&priv->lock, flags);

    /* 출력 값 먼저 설정 */
    val = readl(priv->regs + GPIO_DATA_REG);
    if (value)
        val |= BIT(offset);
    else
        val &= ~BIT(offset);
    writel(val, priv->regs + GPIO_DATA_REG);

    /* 방향을 출력으로 설정 */
    val = readl(priv->regs + GPIO_DIR_REG);
    val |= BIT(offset);    /* 1 = 출력 */
    writel(val, priv->regs + GPIO_DIR_REG);

    raw_spin_unlock_irqrestore(&priv->lock, flags);

    return 0;
}

/* 값 읽기/쓰기 콜백 */
static int my_gpio_get(struct gpio_chip *gc, unsigned int offset)
{
    struct my_gpio *priv = gpiochip_get_data(gc);
    return !!(readl(priv->regs + GPIO_DATA_REG) & BIT(offset));
}

static void my_gpio_set(struct gpio_chip *gc,
                          unsigned int offset, int value)
{
    struct my_gpio *priv = gpiochip_get_data(gc);
    u32 val;
    unsigned long flags;

    raw_spin_lock_irqsave(&priv->lock, flags);
    val = readl(priv->regs + GPIO_DATA_REG);
    if (value)
        val |= BIT(offset);
    else
        val &= ~BIT(offset);
    writel(val, priv->regs + GPIO_DATA_REG);
    raw_spin_unlock_irqrestore(&priv->lock, flags);
}

/* 복수 핀 한번에 읽기 (성능 최적화) */
static int my_gpio_get_multiple(struct gpio_chip *gc,
                                unsigned long *mask,
                                unsigned long *bits)
{
    struct my_gpio *priv = gpiochip_get_data(gc);
    *bits = readl(priv->regs + GPIO_DATA_REG) & *mask;
    return 0;
}

/* 복수 핀 한번에 쓰기 */
static void my_gpio_set_multiple(struct gpio_chip *gc,
                                  unsigned long *mask,
                                  unsigned long *bits)
{
    struct my_gpio *priv = gpiochip_get_data(gc);
    u32 val;
    unsigned long flags;

    raw_spin_lock_irqsave(&priv->lock, flags);
    val = readl(priv->regs + GPIO_DATA_REG);
    val = (val & ~*mask) | (*bits & *mask);
    writel(val, priv->regs + GPIO_DATA_REG);
    raw_spin_unlock_irqrestore(&priv->lock, flags);
}

/* GPIO 컨트롤러 등록 */
static int my_gpio_probe(struct platform_device *pdev)
{
    struct my_gpio *priv;

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

    priv->regs = devm_platform_ioremap_resource(pdev, 0);
    if (IS_ERR(priv->regs))
        return PTR_ERR(priv->regs);

    raw_spin_lock_init(&priv->lock);

    /* gpio_chip 초기화 */
    priv->gc.label = "my-gpio";
    priv->gc.parent = &pdev->dev;
    priv->gc.owner = THIS_MODULE;
    priv->gc.base = -1;              /* 동적 번호 할당 */
    priv->gc.ngpio = 32;             /* 핀 수 */
    priv->gc.direction_input = my_gpio_direction_input;
    priv->gc.direction_output = my_gpio_direction_output;
    priv->gc.get = my_gpio_get;
    priv->gc.set = my_gpio_set;
    priv->gc.get_multiple = my_gpio_get_multiple;
    priv->gc.set_multiple = my_gpio_set_multiple;
    priv->gc.can_sleep = false;     /* MMIO → atomic 접근 가능 */

    return devm_gpiochip_add_data(&pdev->dev, &priv->gc, priv);
}

/* === GPIO 인터럽트 지원 (irqchip 통합) ===
 *
 * GPIO 컨트롤러가 인터럽트를 지원하면 gpio_irq_chip을 설정.
 * gpiolib이 irq_domain을 자동 생성하여 gpiod_to_irq() 지원.
 */

static void my_gpio_irq_ack(struct irq_data *d)
{
    struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
    struct my_gpio *priv = gpiochip_get_data(gc);
    writel(BIT(d->hwirq), priv->regs + GPIO_INT_CLR);
}

static void my_gpio_irq_mask(struct irq_data *d)
{
    struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
    struct my_gpio *priv = gpiochip_get_data(gc);
    u32 val = readl(priv->regs + GPIO_INT_EN);
    val &= ~BIT(d->hwirq);
    writel(val, priv->regs + GPIO_INT_EN);
}

static void my_gpio_irq_unmask(struct irq_data *d)
{
    struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
    struct my_gpio *priv = gpiochip_get_data(gc);
    u32 val = readl(priv->regs + GPIO_INT_EN);
    val |= BIT(d->hwirq);
    writel(val, priv->regs + GPIO_INT_EN);
}

static int my_gpio_irq_set_type(struct irq_data *d,
                                 unsigned int type)
{
    struct gpio_chip *gc = irq_data_get_irq_chip_data(d);
    struct my_gpio *priv = gpiochip_get_data(gc);
    u32 val = readl(priv->regs + GPIO_INT_TYPE);

    switch (type & IRQ_TYPE_SENSE_MASK) {
    case IRQ_TYPE_EDGE_RISING:
        val |= BIT(d->hwirq);     /* 상승 에지 */
        break;
    case IRQ_TYPE_EDGE_FALLING:
        val &= ~BIT(d->hwirq);    /* 하강 에지 */
        break;
    case IRQ_TYPE_EDGE_BOTH:
        /* 양쪽 에지 — 하드웨어 지원 여부에 따라 SW 에뮬레이션 */
        break;
    case IRQ_TYPE_LEVEL_HIGH:
    case IRQ_TYPE_LEVEL_LOW:
        /* 레벨 트리거 설정 */
        break;
    default:
        return -EINVAL;
    }

    writel(val, priv->regs + GPIO_INT_TYPE);
    return 0;
}

/* GPIO 인터럽트 핸들러 (부모 IRQ에서 호출) */
static void my_gpio_irq_handler(struct irq_desc *desc)
{
    struct gpio_chip *gc = irq_desc_get_handler_data(desc);
    struct my_gpio *priv = gpiochip_get_data(gc);
    struct irq_chip *irqchip = irq_desc_get_chip(desc);
    u32 pending;

    chained_irq_enter(irqchip, desc);

    pending = readl(priv->regs + GPIO_INT_STATUS);
    while (pending) {
        int bit = __ffs(pending);
        generic_handle_domain_irq(gc->irq.domain, bit);
        pending &= ~BIT(bit);
    }

    chained_irq_exit(irqchip, desc);
}

/* probe에서 GPIO irqchip 등록 (커널 5.x+ 방식) */
static int my_gpio_probe_with_irq(struct platform_device *pdev)
{
    struct my_gpio *priv;
    struct gpio_irq_chip *girq;
    int parent_irq;

    /* ... gpio_chip 기본 설정 생략 ... */

    /* irq_chip 설정 */
    priv->irq_chip.name = "my-gpio-irq";
    priv->irq_chip.irq_ack = my_gpio_irq_ack;
    priv->irq_chip.irq_mask = my_gpio_irq_mask;
    priv->irq_chip.irq_unmask = my_gpio_irq_unmask;
    priv->irq_chip.irq_set_type = my_gpio_irq_set_type;
    priv->irq_chip.flags = IRQCHIP_IMMUTABLE;
    INIT_IRQ_DEFAULT_HANDLER(priv->irq_chip);

    parent_irq = platform_get_irq(pdev, 0);

    /* gpio_chip에 irqchip 연결 */
    girq = &priv->gc.irq;
    gpio_irq_chip_set_chip(girq, &priv->irq_chip);
    girq->parent_handler = my_gpio_irq_handler;
    girq->num_parents = 1;
    girq->parents = devm_kcalloc(&pdev->dev, 1,
                                   sizeof(*girq->parents), GFP_KERNEL);
    girq->parents[0] = parent_irq;
    girq->default_type = IRQ_TYPE_NONE;
    girq->handler = handle_bad_irq; /* set_type에서 변경 */

    return devm_gpiochip_add_data(&pdev->dev, &priv->gc, priv);
}

/* === GPIO Expander (I2C/SPI 기반 외부 GPIO 컨트롤러) ===
 *
 * SoC의 GPIO 핀이 부족할 때 I2C/SPI로 연결하는 GPIO 확장 칩.
 * 커널에 이미 다수의 GPIO expander 드라이버가 포함되어 있음.
 *
 * 주요 칩과 커널 드라이버:
 *   ┌──────────────┬──────────┬────────┬─────────────────────────┐
 *   │ 칩           │ 인터페이스│ GPIO수 │ 커널 드라이버            │
 *   ├──────────────┼──────────┼────────┼─────────────────────────┤
 *   │ PCA9535/9555 │ I2C      │ 16     │ gpio-pca953x.c          │
 *   │ PCA9534/9538 │ I2C      │ 8      │ gpio-pca953x.c          │
 *   │ PCAL6524     │ I2C      │ 24     │ gpio-pca953x.c          │
 *   │ MCP23017     │ I2C      │ 16     │ gpio-mcp23s08.c (공용)  │
 *   │ MCP23S17     │ SPI      │ 16     │ gpio-mcp23s08.c         │
 *   │ PCF8574      │ I2C      │ 8      │ gpio-pcf857x.c          │
 *   │ TCA6416      │ I2C      │ 16     │ gpio-pca953x.c          │
 *   │ SX1509       │ I2C      │ 16     │ gpio-sx150x.c           │
 *   │ MAX7301      │ SPI      │ 28     │ gpio-max7301.c          │
 *   └──────────────┴──────────┴────────┴─────────────────────────┘
 *
 * I2C GPIO expander의 핵심 차이:
 *   - can_sleep = true → gpiod_set_value_cansleep() 만 사용 가능
 *   - IRQ 컨텍스트(hardirq)에서 접근 불가 → threaded IRQ 사용 필수
 *   - I2C 전송 지연으로 토글 속도 제한 (수십 kHz 이하)
 *
 * Device Tree 예시:
 *
 * &i2c1 {
 *     gpio_exp: gpio@20 {
 *         compatible = "nxp,pca9555";
 *         reg = <0x20>;
 *         gpio-controller;
 *         #gpio-cells = <2>;
 *         interrupt-parent = <&gpio1>;     ← SoC GPIO를 부모 IRQ로
 *         interrupts = <15 IRQ_TYPE_EDGE_FALLING>;
 *         interrupt-controller;
 *         #interrupt-cells = <2>;
 *
 *         // GPIO 라인 이름 지정 (디버깅용)
 *         gpio-line-names = "EXT_LED0", "EXT_LED1", "EXT_BTN0", "EXT_BTN1",
 *                           "EXT_CS0", "EXT_CS1", "EXT_RST", "EXT_EN",
 *                           "IO8", "IO9", "IO10", "IO11",
 *                           "IO12", "IO13", "IO14", "IO15";
 *     };
 * };
 *
 * // 다른 디바이스에서 expander의 GPIO 참조
 * my_device {
 *     enable-gpios = <&gpio_exp 7 GPIO_ACTIVE_HIGH>;  // EXT_EN
 *     reset-gpios  = <&gpio_exp 6 GPIO_ACTIVE_LOW>;   // EXT_RST
 * };
 */

/* === GPIO와 pinctrl 연동 ===
 *
 * 대부분의 SoC에서 GPIO 핀은 다중 기능(mux) 핀.
 * 동일 핀이 GPIO, UART TX, SPI MOSI 등으로 사용 가능.
 * pinctrl 서브시스템이 핀 기능 선택과 전기적 특성(풀업/풀다운, 드라이브 강도) 관리.
 *
 * GPIO 요청 시 자동으로 pinctrl과 연동:
 *   gpiod_get() → gpiolib → pinctrl_gpio_request()
 *                          → 핀을 GPIO 모드로 mux
 *   gpiod_put() → gpiolib → pinctrl_gpio_free()
 *                          → 핀 해제
 *
 * gpio_chip에서 pinctrl 연동을 위한 gpio_ranges 설정:
 */

/* Device Tree에서 GPIO ↔ pinctrl 매핑:
 *
 * gpio1: gpio@e6051000 {
 *     compatible = "renesas,gpio-r8a7795";
 *     reg = <0 0xe6051000 0 0x50>;
 *     #gpio-cells = <2>;
 *     gpio-controller;
 *     gpio-ranges = <&pfc 0 32 32>;
 *     // &pfc: pinctrl 노드
 *     // 0: GPIO 시작 오프셋
 *     // 32: pinctrl 핀 시작 번호
 *     // 32: 핀 개수
 *
 *     // 핀 설정 (풀업, 드라이브 강도 등)은 pinctrl에서:
 *     // &pfc {
 *     //     button_pins: button {
 *     //         pins = "GP_1_4";
 *     //         bias-pull-up;
 *     //     };
 *     // };
 * };
 */

# === GPIO 유저스페이스 도구 (libgpiod) ===
# libgpiod는 /dev/gpiochipN chardev 기반의 현대적 유저스페이스 GPIO 라이브러리
# sysfs (/sys/class/gpio/export)는 deprecated — libgpiod v2 사용 권장

# GPIO 컨트롤러 목록
gpiodetect
# gpiochip0 [pinctrl-bcm2835] (54 lines)
# gpiochip1 [pca9555] (16 lines)

# GPIO 라인 정보 (방향, 활성 상태, 사용자)
gpioinfo gpiochip0
# gpiochip0 - 54 lines:
#   line   0: "ID_SDA"    unused   input  active-high
#   line   1: "ID_SCL"    unused   input  active-high
#   line   2: "SDA1"      "i2c1"   input  active-high [used]
#   line  18: "GPIO18"    unused   input  active-high

# GPIO 값 읽기 (라인 번호 지정)
gpioget gpiochip0 18
# 0 또는 1

# GPIO 값 쓰기 (출력)
gpioset gpiochip0 18=1     # GPIO18을 HIGH
gpioset gpiochip0 18=0     # GPIO18을 LOW

# 복수 GPIO 동시 제어
gpioset gpiochip0 17=1 18=0 27=1

# GPIO 라인 이름으로 접근 (gpio-line-names DT 속성 설정 시)
gpioget --by-name EXT_BTN0
gpioset --by-name EXT_LED0=1

# GPIO 이벤트 모니터링 (에지 감지)
gpiomon gpiochip0 18
# 18  1  1707564890.123456789  rising
# 18  0  1707564891.234567890  falling

# 특정 에지만 감지
gpiomon --rising-edge gpiochip0 18
gpiomon --falling-edge gpiochip0 18

# 복수 라인 동시 모니터링
gpiomon gpiochip0 17 18 27

# 타임아웃 설정 (밀리초)
gpioget --bias=pull-up gpiochip0 18    # 풀업 활성화하고 읽기
gpioget --bias=pull-down gpiochip0 18  # 풀다운 활성화하고 읽기
gpioget --active-low gpiochip0 18      # active-low로 해석

# === GPIO sysfs 디버깅 정보 ===

# 등록된 모든 GPIO 컨트롤러 목록
ls /sys/bus/gpio/devices/
# gpiochip0  gpiochip1

# GPIO 컨트롤러 상세 정보
cat /sys/class/gpio/gpiochip0/label
# pinctrl-bcm2835
cat /sys/class/gpio/gpiochip0/ngpio
# 54
cat /sys/class/gpio/gpiochip0/base
# 0

# debugfs GPIO 상태 (커널 디버깅에 유용)
cat /sys/kernel/debug/gpio
# gpiochip0: GPIOs 0-53, parent: 20200000.gpio, pinctrl-bcm2835:
#  gpio-2   (SDA1                ) in  hi IRQ
#  gpio-3   (SCL1                ) in  hi IRQ
#  gpio-18  (                    ) out lo
# gpiochip1: GPIOs 496-511, parent: 1-0020, pca9555:
#  gpio-496 (EXT_LED0            ) out lo
#  gpio-497 (EXT_LED1            ) out hi

# pinctrl 연동 상태
cat /sys/kernel/debug/pinctrl/pinctrl-bcm2835/gpio-ranges
# GPIO ranges handled:
#  0: pinctrl-bcm2835 GPIOS [0 - 53] PINS [0 - 53]

&gpio1 {
    usb_pwr_en {
        gpio-hog;
        gpios = <5 GPIO_ACTIVE_HIGH>;
        output-high;           /* 부팅 시 HIGH 출력 (USB 전원 활성) */
        line-name = "USB_PWR_EN";
    };
    debug_led {
        gpio-hog;
        gpios = <10 GPIO_ACTIVE_LOW>;
        output-low;            /* 부팅 시 LOW 출력 (LED 꺼짐) */
        line-name = "DEBUG_LED";
    };
};

SATA (libata) 서브시스템

# SATA 링크 상태 확인
dmesg | grep -i ata
# ata1: SATA link up 6.0 Gbps (SStatus 133 SControl 300)

# AHCI 포트 정보
cat /sys/class/ata_port/ata1/port_no

# NCQ (Native Command Queuing) 지원 확인
hdparm -I /dev/sda | grep -i ncq
# Queue depth: 32

# SATA 전원 관리 (ALPM)
cat /sys/class/scsi_host/host0/link_power_management_policy
# max_performance | medium_power | min_power | med_power_with_dipm

버스 비교 요약

입출력 장치 서브시스템 심화

Input 서브시스템 (키보드, 마우스, 터치)

리눅스 Input 서브시스템(drivers/input/)은 키보드, 마우스, 터치스크린, 조이스틱, 리모컨 등 모든 종류의 입력 장치를 통합 관리하는 프레임워크입니다. 하드웨어별 드라이버가 이벤트를 생성하면, Input Core가 이를 적절한 핸들러(evdev, kbd, mousedev 등)로 라우팅하여 유저 공간에 전달합니다.

Input 서브시스템은 3계층으로 구성됩니다:

• Device Drivers: 하드웨어와 직접 통신하여 input_event를 생성 (input_report_* API)
• Input Core (drivers/input/input.c): 디바이스와 핸들러 사이의 매칭·라우팅 — input_register_device() / input_register_handler()
• Event Handlers: 이벤트를 유저 공간에 전달 — evdev (범용), kbd (콘솔 키보드), mousedev (/dev/input/mice), joydev (조이스틱)

핵심 데이터 구조

/* === struct input_dev — Input 디바이스를 나타내는 핵심 구조체 ===
 * include/linux/input.h
 * 하드웨어 드라이버가 할당·등록하며, 지원하는 이벤트 유형과 코드를 비트마스크로 선언 */
struct input_dev {
    const char *name;           /* 사람이 읽을 수 있는 디바이스 이름 */
    const char *phys;           /* 물리적 경로 (예: "usb-0000:00:1d.0-1/input0") */
    const char *uniq;           /* 고유 식별자 (시리얼 번호 등) */
    struct input_id id;          /* bustype, vendor, product, version */

    /* 이벤트 능력(capability) 비트마스크 */
    unsigned long evbit[BITS_TO_LONGS(EV_CNT)];    /* 지원 이벤트 유형 */
    unsigned long keybit[BITS_TO_LONGS(KEY_CNT)];  /* 지원 키 코드 */
    unsigned long relbit[BITS_TO_LONGS(REL_CNT)];  /* 상대축 코드 */
    unsigned long absbit[BITS_TO_LONGS(ABS_CNT)];  /* 절대축 코드 */
    unsigned long mscbit[BITS_TO_LONGS(MSC_CNT)];  /* 기타 이벤트 */
    unsigned long ledbit[BITS_TO_LONGS(LED_CNT)];  /* LED 상태 */
    unsigned long swbit[BITS_TO_LONGS(SW_CNT)];    /* 스위치 상태 */
    unsigned long ffbit[BITS_TO_LONGS(FF_CNT)];    /* Force Feedback */

    /* 절대축 파라미터 (min, max, fuzz, flat, resolution) */
    struct input_absinfo *absinfo;

    /* 콜백 함수 */
    int (*open)(struct input_dev *dev);    /* 첫 핸들러 연결 시 */
    void (*close)(struct input_dev *dev);  /* 마지막 핸들러 해제 시 */
    int (*event)(struct input_dev *dev,
                 unsigned int type,
                 unsigned int code, int value); /* LED/FF 출력 이벤트 */

    struct device dev;            /* 내장 device 구조체 */
    struct list_head h_list;     /* 연결된 input_handle 리스트 */
    struct list_head node;       /* 전역 input_dev 리스트 */
};

/* === struct input_handler — 이벤트 핸들러 (evdev, kbd, mousedev 등) ===
 * Input Core에 등록되어 매칭되는 디바이스의 이벤트를 처리 */
struct input_handler {
    void (*event)(struct input_handle *handle,
                  unsigned int type,
                  unsigned int code, int value);
    void (*events)(struct input_handle *handle,
                   const struct input_value *vals,
                   unsigned int count);         /* 배치 이벤트 (성능 최적화) */
    bool (*filter)(struct input_handle *handle,
                   unsigned int type,
                   unsigned int code, int value); /* 이벤트 필터링 */
    bool (*match)(struct input_handler *handler,
                  struct input_dev *dev);        /* 추가 매칭 조건 */
    int  (*connect)(struct input_handler *handler,
                    struct input_dev *dev,
                    const struct input_device_id *id);
    void (*disconnect)(struct input_handle *handle);

    const char *name;
    const struct input_device_id *id_table;   /* 매칭 테이블 */
    struct list_head h_list;                   /* 연결된 handle 리스트 */
    struct list_head node;                     /* 전역 handler 리스트 */
};

/* === struct input_handle — input_dev와 input_handler 연결 ===
 * 하나의 디바이스는 여러 핸들러에 연결 가능 (예: evdev + kbd 동시) */
struct input_handle {
    void *private;                     /* 핸들러별 개인 데이터 */
    int open;                           /* 열린 파일 디스크립터 수 */
    const char *name;
    struct input_dev *dev;              /* 연결된 디바이스 */
    struct input_handler *handler;      /* 연결된 핸들러 */
    struct list_head d_node;            /* dev->h_list 노드 */
    struct list_head h_node;            /* handler->h_list 노드 */
};

/* === struct input_event — 유저 공간에 전달되는 이벤트 구조 ===
 * /dev/input/eventN에서 read() 시 이 구조체 배열로 전달됨 */
struct input_event {
    struct timeval time;   /* 이벤트 발생 시각 (또는 input_event_usec) */
    __u16 type;             /* EV_KEY, EV_REL, EV_ABS ... */
    __u16 code;             /* KEY_A, REL_X, ABS_MT_POSITION_X ... */
    __s32 value;            /* 키: 1(press)/0(release)/2(repeat), 축: 좌표값 */
};

이벤트 유형 상세

Input 디바이스 등록

#include <linux/input.h>
#include <linux/module.h>
#include <linux/platform_device.h>

struct my_kbd_data {
    struct input_dev *idev;
    int irq;
};

/* 인터럽트 핸들러 — 하드웨어에서 키 이벤트 수신 */
static irqreturn_t my_kbd_irq(int irq, void *dev_id)
{
    struct my_kbd_data *data = dev_id;
    u8 scancode;

    /* 하드웨어에서 스캔코드 읽기 (실제로는 MMIO/I2C/SPI 등) */
    scancode = read_hw_scancode();

    /* 이벤트 보고 — Input Core가 연결된 모든 handler에 전파 */
    input_report_key(data->idev, scancode, 1);  /* 키 누름 */
    input_sync(data->idev);                      /* SYN_REPORT */

    /* 키 해제 (간단한 예제 — 실제로는 별도 인터럽트) */
    input_report_key(data->idev, scancode, 0);  /* 키 해제 */
    input_sync(data->idev);

    return IRQ_HANDLED;
}

static int my_kbd_probe(struct platform_device *pdev)
{
    struct my_kbd_data *data;
    struct input_dev *idev;
    int ret, i;

    data = devm_kzalloc(&pdev->dev, sizeof(*data), GFP_KERNEL);
    if (!data)
        return -ENOMEM;

    /* === 1. devm_input_allocate_device — managed 할당 ===
     * 드라이버 해제 시 자동으로 input_free_device() 호출됨
     * input_allocate_device()와 달리 수동 free 불필요 */
    idev = devm_input_allocate_device(&pdev->dev);
    if (!idev)
        return -ENOMEM;

    /* === 2. 디바이스 식별 정보 설정 === */
    idev->name = "My Custom Keyboard";
    idev->phys = "my-kbd/input0";
    idev->id.bustype = BUS_HOST;       /* BUS_USB, BUS_I2C, BUS_SPI 등 */
    idev->id.vendor  = 0x1234;
    idev->id.product = 0x5678;
    idev->id.version = 0x0100;

    /* === 3. 이벤트 능력(capability) 선언 ===
     * 이 디바이스가 생성할 수 있는 이벤트 유형과 코드를 선언
     * Input Core가 이 정보로 적절한 handler를 매칭 */
    input_set_capability(idev, EV_KEY, KEY_A);     /* EV_KEY + KEY_A 동시 설정 */
    input_set_capability(idev, EV_KEY, KEY_B);

    /* 또는 set_bit로 개별 설정 */
    set_bit(EV_KEY, idev->evbit);
    for (i = KEY_ESC; i <= KEY_MICMUTE; i++)
        set_bit(i, idev->keybit);

    /* 키 반복(autorepeat) 자동 지원 */
    set_bit(EV_REP, idev->evbit);

    /* === 4. open/close 콜백 (선택) ===
     * 유저 공간에서 디바이스 열기/닫기 시 호출
     * 전력 절약: 열린 핸들러가 없으면 하드웨어 비활성화 */
    idev->open  = my_kbd_open;
    idev->close = my_kbd_close;

    /* === 5. 인터럽트 등록 === */
    data->irq = platform_get_irq(pdev, 0);
    if (data->irq < 0)
        return data->irq;

    ret = devm_request_irq(&pdev->dev, data->irq,
                           my_kbd_irq, IRQF_TRIGGER_FALLING,
                           "my-kbd", data);
    if (ret)
        return ret;

    data->idev = idev;
    platform_set_drvdata(pdev, data);

    /* === 6. 디바이스 등록 ===
     * Input Core에 디바이스 등록 → 매칭되는 handler와 자동 연결
     * 등록 후에는 capability 변경 금지 */
    ret = input_register_device(idev);
    if (ret)
        return ret;  /* devm이므로 idev는 자동 해제 */

    dev_info(&pdev->dev, "keyboard registered\n");
    return 0;
}

이벤트 보고 API

/* 마우스 이동 + 클릭 보고 예제 */
input_report_rel(idev, REL_X, dx);
input_report_rel(idev, REL_Y, dy);
input_report_rel(idev, REL_WHEEL, wheel);
input_report_key(idev, BTN_LEFT, left_pressed);
input_sync(idev);   /* 하나의 패킷으로 원자적 전달 */

/* 절대 좌표 + 압력 보고 예제 (태블릿) */
input_report_abs(idev, ABS_X, x);
input_report_abs(idev, ABS_Y, y);
input_report_abs(idev, ABS_PRESSURE, pressure);
input_report_key(idev, BTN_TOUCH, pressure > 0);
input_sync(idev);

절대축 파라미터 (ABS)

/* input_set_abs_params(dev, axis, min, max, fuzz, flat)
 *
 * min/max  : 축의 유효 범위
 * fuzz     : 노이즈 필터링 — |new - old| < fuzz이면 무시 (jitter 제거)
 * flat     : 데드존 — |value| < flat이면 0으로 처리 (조이스틱 중앙)
 * resolution: input_abs_set_res()로 별도 설정 (units/mm 등)
 */

/* 터치스크린: 1920x1080 해상도, 노이즈 필터링 4픽셀 */
input_set_abs_params(idev, ABS_X, 0, 1920, 4, 0);
input_set_abs_params(idev, ABS_Y, 0, 1080, 4, 0);
input_set_abs_params(idev, ABS_PRESSURE, 0, 255, 0, 0);

/* resolution 설정 — libinput이 물리적 크기 계산에 사용 */
input_abs_set_res(idev, ABS_X, 40);   /* 40 units/mm */
input_abs_set_res(idev, ABS_Y, 40);

/* 조이스틱: -32768 ~ 32767, 데드존 4096 */
input_set_abs_params(idev, ABS_X, -32768, 32767, 16, 4096);
input_set_abs_params(idev, ABS_Y, -32768, 32767, 16, 4096);

멀티터치 프로토콜

리눅스 커널은 멀티터치를 위한 두 가지 프로토콜을 정의합니다 (Documentation/input/multi-touch-protocol.rst):

/* === Multitouch Protocol B — 슬롯 기반 (권장) ===
 * input_mt_init_slots()로 슬롯 수를 미리 선언
 * 각 슬롯에 tracking_id를 할당하여 터치 추적 */

#include <linux/input/mt.h>

static int ts_probe(struct i2c_client *client)
{
    struct input_dev *idev;
    int ret;

    idev = devm_input_allocate_device(&client->dev);

    /* 절대 좌표 설정 */
    input_set_abs_params(idev, ABS_MT_POSITION_X, 0, 1920, 0, 0);
    input_set_abs_params(idev, ABS_MT_POSITION_Y, 0, 1080, 0, 0);
    input_set_abs_params(idev, ABS_MT_TOUCH_MAJOR, 0, 255, 0, 0);
    input_set_abs_params(idev, ABS_MT_PRESSURE, 0, 255, 0, 0);

    /* 최대 10개 동시 터치, DIRECT = 터치스크린 (POINTER = 터치패드) */
    ret = input_mt_init_slots(idev, 10, INPUT_MT_DIRECT | INPUT_MT_DROP_UNUSED);
    if (ret)
        return ret;

    input_set_capability(idev, EV_KEY, BTN_TOUCH);

    return input_register_device(idev);
}

/* 터치 이벤트 보고 (인터럽트 핸들러 또는 threaded irq에서) */
static void ts_report_touches(struct input_dev *idev,
                              struct touch_point *tp, int count)
{
    int i;

    for (i = 0; i < count; i++) {
        /* 슬롯 선택 — 같은 tracking_id를 같은 슬롯에 유지 */
        input_mt_slot(idev, tp[i].slot);

        /* tracking_id 할당: 양수=활성 터치, -1=터치 해제 */
        input_mt_report_slot_state(idev, MT_TOOL_FINGER, tp[i].active);

        if (tp[i].active) {
            input_report_abs(idev, ABS_MT_POSITION_X, tp[i].x);
            input_report_abs(idev, ABS_MT_POSITION_Y, tp[i].y);
            input_report_abs(idev, ABS_MT_TOUCH_MAJOR, tp[i].width);
            input_report_abs(idev, ABS_MT_PRESSURE, tp[i].pressure);
        }
    }

    /* INPUT_MT_DROP_UNUSED: 보고되지 않은 슬롯 자동 해제 */
    input_mt_sync_frame(idev);

    /* 단일 터치 이벤트도 함께 생성 (Protocol B가 자동 처리) */
    input_sync(idev);
}

폴링 Input 디바이스

인터럽트를 지원하지 않는 하드웨어의 경우, input_setup_polling()을 사용하여 커널이 주기적으로 하드웨어를 폴링합니다. 이전의 input_polled_dev 구조체는 deprecated되었으며, v5.12부터 통합 API로 대체되었습니다.

/* === 폴링 Input 디바이스 예제 (v5.12+) === */
static void my_sensor_poll(struct input_dev *idev)
{
    struct my_sensor *sensor = input_get_drvdata(idev);
    int x, y;

    /* 하드웨어에서 현재 값 읽기 */
    x = read_sensor_x(sensor);
    y = read_sensor_y(sensor);

    input_report_abs(idev, ABS_X, x);
    input_report_abs(idev, ABS_Y, y);
    input_sync(idev);
}

static int my_sensor_probe(struct i2c_client *client)
{
    struct input_dev *idev;
    struct my_sensor *sensor;

    sensor = devm_kzalloc(&client->dev, sizeof(*sensor), GFP_KERNEL);
    idev = devm_input_allocate_device(&client->dev);

    idev->name = "My Analog Sensor";
    input_set_abs_params(idev, ABS_X, 0, 4095, 2, 0);
    input_set_abs_params(idev, ABS_Y, 0, 4095, 2, 0);

    input_set_drvdata(idev, sensor);

    /* 폴링 설정: 콜백 + 주기 */
    input_setup_polling(idev, my_sensor_poll);
    input_set_poll_interval(idev, 20);       /* 20ms = 50Hz */
    input_set_min_poll_interval(idev, 10);   /* 최소 10ms */
    input_set_max_poll_interval(idev, 100);  /* 최대 100ms */

    /* 유저 공간에서 poll_interval 조정 가능:
     * /sys/class/input/inputN/device/poll_interval */

    return input_register_device(idev);
}

Device Tree 바인딩

커널은 gpio-keys, gpio-keys-polled, matrix-keypad 등 범용 Input 드라이버를 제공합니다. Device Tree만으로 입력 장치를 정의할 수 있어 별도 드라이버 작성이 불필요합니다.

/* === gpio-keys: GPIO 기반 버튼 (인터럽트 지원) === */
gpio-keys {
    compatible = "gpio-keys";

    power-button {
        label = "Power Button";
        gpios = <&gpio1 5 GPIO_ACTIVE_LOW>;
        linux,code = <KEY_POWER>;        /* input-event-codes.h 참조 */
        wakeup-source;                    /* 이 버튼으로 시스템 깨우기 */
        debounce-interval = <20>;        /* ms 단위 디바운스 */
    };

    volume-up {
        label = "Volume Up";
        gpios = <&gpio1 12 GPIO_ACTIVE_LOW>;
        linux,code = <KEY_VOLUMEUP>;
        autorepeat;                       /* 키 반복 활성화 */
    };

    lid-switch {
        label = "Lid Switch";
        gpios = <&gpio2 3 GPIO_ACTIVE_LOW>;
        linux,input-type = <EV_SW>;      /* 스위치 이벤트 */
        linux,code = <SW_LID>;
    };
};

/* === gpio-keys-polled: 인터럽트 없는 GPIO 폴링 === */
gpio-keys-polled {
    compatible = "gpio-keys-polled";
    poll-interval = <100>;              /* 100ms 간격 폴링 */

    button-0 {
        label = "Reset";
        gpios = <&gpio3 8 GPIO_ACTIVE_LOW>;
        linux,code = <KEY_RESTART>;
    };
};

/* === matrix-keypad: 행/열 매트릭스 키패드 === */
matrix-keypad {
    compatible = "gpio-matrix-keypad";
    row-gpios = <&gpio1 0 0>, <&gpio1 1 0>, <&gpio1 2 0>;
    col-gpios = <&gpio1 3 0>, <&gpio1 4 0>, <&gpio1 5 0>;
    debounce-delay-ms = <5>;
    col-scan-delay-us = <2>;

    linux,keymap = <
        MATRIX_KEY(0, 0, KEY_1)
        MATRIX_KEY(0, 1, KEY_2)
        MATRIX_KEY(0, 2, KEY_3)
        MATRIX_KEY(1, 0, KEY_4)
        MATRIX_KEY(1, 1, KEY_5)
        MATRIX_KEY(1, 2, KEY_6)
        MATRIX_KEY(2, 0, KEY_7)
        MATRIX_KEY(2, 1, KEY_8)
        MATRIX_KEY(2, 2, KEY_9)
    >;
};

내장 Event Handler

evdev 유저 공간 인터페이스

evdev는 가장 중요한 핸들러로, /dev/input/eventN 캐릭터 디바이스를 통해 모든 이벤트를 있는 그대로(raw) 유저 공간에 전달합니다.

/* === 유저 공간에서 evdev 이벤트 읽기 === */
#include <linux/input.h>
#include <fcntl.h>
#include <stdio.h>
#include <unistd.h>

int main(void)
{
    int fd = open("/dev/input/event0", O_RDONLY);
    struct input_event ev;
    char name[256];

    /* 디바이스 이름 조회 */
    ioctl(fd, EVIOCGNAME(sizeof(name)), name);
    printf("Device: %s\n", name);

    /* 이벤트 루프 */
    while (read(fd, &ev, sizeof(ev)) == sizeof(ev)) {
        if (ev.type == EV_KEY)
            printf("Key %d %s\n", ev.code,
                   ev.value ? "pressed" : "released");
    }
    close(fd);
}

Force Feedback (FF)

Force Feedback은 게임패드 진동, 스티어링 휠 저항, 햅틱 피드백 등을 지원합니다. 커널은 FF 효과를 디바이스에 업로드하고 재생/정지를 제어하는 프레임워크를 제공합니다.

/* === 커널 드라이버: FF 지원 등록 === */
#include <linux/input.h>

static int my_ff_upload(struct input_dev *dev,
                        struct ff_effect *effect,
                        struct ff_effect *old)
{
    /* 효과를 하드웨어에 프로그래밍 */
    write_ff_to_hw(effect);
    return 0;
}

static int my_ff_playback(struct input_dev *dev,
                          int effect_id, int value)
{
    /* value: 1=재생, 0=정지 */
    if (value)
        start_hw_effect(effect_id);
    else
        stop_hw_effect(effect_id);
    return 0;
}

static int setup_ff(struct input_dev *idev)
{
    input_set_capability(idev, EV_FF, FF_RUMBLE);
    input_set_capability(idev, EV_FF, FF_PERIODIC);
    input_set_capability(idev, EV_FF, FF_CONSTANT);

    /* 최대 동시 효과 수, 업로드/재생 콜백 */
    return input_ff_create(idev, 16);
    /* input_ff_create() 이후 콜백 설정 */
    idev->ff->upload = my_ff_upload;
    idev->ff->playback = my_ff_playback;
}

/* === 간편 rumble API (많은 게임패드에서 사용) ===
 * upload/playback 콜백 없이 드라이버가 직접 모터 제어 */
static int my_play_effect(struct input_dev *dev,
                          void *data,
                          struct ff_effect *effect)
{
    u16 strong = effect->u.rumble.strong_magnitude;
    u16 weak   = effect->u.rumble.weak_magnitude;

    /* 모터 강도 설정 */
    set_motor_speed(data, strong, weak);
    return 0;
}

/* input_ff_create_memless()로 간편 등록 */
input_ff_create_memless(idev, priv, my_play_effect);

Input 프로퍼티 (INPUT_PROP_*)

Input 프로퍼티는 디바이스의 물리적 특성을 유저 공간에 알려줍니다. input_set_capability()가 아닌 set_bit()으로 dev->propbit에 설정합니다.

/* 터치스크린: DIRECT 프로퍼티 설정 */
set_bit(INPUT_PROP_DIRECT, idev->propbit);

/* 터치패드: POINTER + BUTTONPAD */
set_bit(INPUT_PROP_POINTER, idev->propbit);
set_bit(INPUT_PROP_BUTTONPAD, idev->propbit);

키코드 매핑과 스캔코드

Input 서브시스템은 하드웨어 스캔코드(scancode)를 리눅스 키코드(keycode)로 변환하는 2단계 매핑을 지원합니다. 키코드 테이블은 런타임에 변경 가능하여 유저 공간에서 키 재매핑이 가능합니다.

/* 커널 드라이버에서 키코드 테이블 설정 */
static const unsigned short my_keymap[] = {
    [0x01] = KEY_ESC,
    [0x02] = KEY_1,
    [0x03] = KEY_2,
    /* ... */
};

idev->keycode     = my_keymap;
idev->keycodesize = sizeof(my_keymap[0]);
idev->keycodemax  = ARRAY_SIZE(my_keymap);

/* 선택: 커스텀 getkeycode/setkeycode 콜백
 * 기본 구현은 keycode[] 배열을 인덱스로 접근
 * 희소(sparse) 매핑이 필요하면 커스텀 콜백 구현 */
idev->getkeycode = my_getkeycode;
idev->setkeycode = my_setkeycode;

# 유저 공간에서 키 재매핑 (evdev ioctl)
# EVIOCSKEYCODE — scancode → keycode 변경

# udevadm hwdb 기반 자동 매핑 (권장)
# /etc/udev/hwdb.d/70-keyboard.hwdb:
evdev:input:b0003v046DpC52B*
 KEYBOARD_KEY_70039=esc        # CapsLock → Escape
 KEYBOARD_KEY_70029=capslock   # Escape → CapsLock

# hwdb 업데이트 적용
sudo systemd-hwdb update
sudo udevadm trigger

디버깅 도구

# === /proc/bus/input/devices — 등록된 모든 Input 디바이스 === 
cat /proc/bus/input/devices
# I: Bus=0011 Vendor=0001 Product=0001 Version=ab54
# N: Name="AT Translated Set 2 keyboard"
# P: Phys=isa0060/serio0/input0
# S: Sysfs=/devices/platform/i8042/serio0/input/input0
# U: Uniq=
# H: Handlers=sysrq kbd leds event0
# B: PROP=0
# B: EV=120013
# B: KEY=402000000 3803078f800d001 feffffdfffefffff fffffffffffffffe
# B: MSC=10
# B: LED=7

# === /proc/bus/input/handlers — 등록된 핸들러 목록 ===
cat /proc/bus/input/handlers
# N: Number=0 Name=rfkill
# N: Number=1 Name=kbd
# N: Number=2 Name=mousedev Minor=32
# N: Number=3 Name=evdev Minor=64
# N: Number=4 Name=joydev Minor=0

# === sysfs Input 디바이스 정보 ===
ls /sys/class/input/input0/
# capabilities/  device/  event0/  id/  inhibited  name  phys  properties  uevent  uniq

# 디바이스 활성/비활성 (v5.14+)
echo 1 > /sys/class/input/input0/inhibited   # 일시 비활성
echo 0 > /sys/class/input/input0/inhibited   # 재활성

# === evtest — 실시간 이벤트 모니터링 (가장 유용한 도구) ===
sudo evtest /dev/input/event0
# Event: time 1234567890.123456, type 1 (EV_KEY), code 30 (KEY_A), value 1
# Event: time 1234567890.123456, type 0 (EV_SYN), code 0 (SYN_REPORT), value 0
# Event: time 1234567890.234567, type 1 (EV_KEY), code 30 (KEY_A), value 0
# Event: time 1234567890.234567, type 0 (EV_SYN), code 0 (SYN_REPORT), value 0

# === libinput debug-events — 고수준 이벤트 분석 ===
sudo libinput debug-events
# -event2   KEYBOARD_KEY     +3.24s  KEY_A (30) pressed
# -event2   KEYBOARD_KEY     +3.38s  KEY_A (30) released
# -event5   POINTER_MOTION   +5.12s  12.00/ -3.00

# === evemu — 이벤트 녹화/재생 (재현 테스트용) ===
sudo evemu-record /dev/input/event0 > recording.txt   # 녹화
sudo evemu-play /dev/input/event0 < recording.txt     # 재생

# === 커널 디버그: input 이벤트 추적 ===
echo 1 > /sys/module/evdev/parameters/debug            # evdev 디버그 (if available)

# ftrace로 Input 이벤트 추적
echo 1 > /sys/kernel/debug/tracing/events/input/input_event/enable
cat /sys/kernel/debug/tracing/trace_pipe
# irq/18-i8042-18 input_event: dev=input0, type=1, code=30, value=1

/* === uinput: 유저 공간에서 가상 Input 디바이스 생성 === */
#include <linux/uinput.h>
#include <fcntl.h>
#include <string.h>
#include <unistd.h>

int create_virtual_kbd(void)
{
    int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
    struct uinput_setup usetup;

    /* 이벤트 유형 활성화 */
    ioctl(fd, UI_SET_EVBIT, EV_KEY);
    ioctl(fd, UI_SET_KEYBIT, KEY_A);
    ioctl(fd, UI_SET_KEYBIT, KEY_B);

    /* 디바이스 정보 설정 */
    memset(&usetup, 0, sizeof(usetup));
    usetup.id.bustype = BUS_USB;
    usetup.id.vendor  = 0x1234;
    usetup.id.product = 0x5678;
    strcpy(usetup.name, "Virtual Keyboard");

    ioctl(fd, UI_DEV_SETUP, &usetup);
    ioctl(fd, UI_DEV_CREATE);

    /* 키 이벤트 주입 */
    struct input_event ev = { .type = EV_KEY, .code = KEY_A, .value = 1 };
    write(fd, &ev, sizeof(ev));
    ev.type = EV_SYN; ev.code = SYN_REPORT; ev.value = 0;
    write(fd, &ev, sizeof(ev));

    /* 해제 */
    ioctl(fd, UI_DEV_DESTROY);
    close(fd);
    return 0;
}

이벤트 흐름 요약

USB 서브시스템

USB(Universal Serial Bus) 서브시스템은 리눅스 커널에서 가장 크고 복잡한 드라이버 프레임워크 중 하나입니다. 호스트 컨트롤러 드라이버(HCD), USB 코어, 디바이스 드라이버의 3계층으로 구성되며, 핫플러그와 다양한 전송 유형을 지원합니다.

USB 프로토콜 버전 비교

USB 디스크립터 계층 구조 — USB 디바이스는 계층적 디스크립터로 자신의 기능을 호스트에 알립니다. 커널은 열거(enumeration) 과정에서 이 디스크립터들을 읽어 적절한 드라이버를 바인딩합니다.

USB 전송 유형 — 4가지 전송 유형은 각각 다른 QoS 특성을 가지며, 디바이스의 엔드포인트 디스크립터에 정의됩니다.

URB(USB Request Block) 라이프사이클 — URB는 USB I/O의 핵심 데이터 구조로, 비동기적으로 USB 코어에 전송 요청을 전달합니다.

/* URB 라이프사이클: 할당 → 초기화(fill) → 제출(submit) → 완료 콜백 → 해제 */

/* 1. URB 할당 */
struct urb *urb = usb_alloc_urb(0, GFP_KERNEL);  /* iso_packets=0 (non-iso) */
if (!urb)
    return -ENOMEM;

/* 2. 전송 유형별 초기화 함수 */
usb_fill_control_urb(urb, udev, pipe, setup, buf, len, callback, context);
usb_fill_bulk_urb(urb, udev, pipe, buf, len, callback, context);
usb_fill_int_urb(urb, udev, pipe, buf, len, callback, context, interval);
/* isochronous는 fill 함수 없음 — 수동으로 urb 필드 설정 필요 */

/* 3. URB 제출 (비동기) */
int ret = usb_submit_urb(urb, GFP_KERNEL);
if (ret) {
    dev_err(&intf->dev, "URB submit failed: %d\n", ret);
    usb_free_urb(urb);
    return ret;
}

/* 4. 완료 콜백 (인터럽트 컨텍스트에서 호출됨!) */
static void my_urb_complete(struct urb *urb)
{
    if (urb->status) {
        if (urb->status == -ENOENT ||     /* usb_kill_urb() */
            urb->status == -ECONNRESET || /* usb_unlink_urb() */
            urb->status == -ESHUTDOWN)    /* 디바이스 제거 */
            return;
        /* 기타 에러 처리 */
    }

    /* urb->actual_length 바이트만큼 데이터 수신 완료 */
    process_data(urb->transfer_buffer, urb->actual_length);

    /* Interrupt/Isochronous: 연속 전송을 위해 재제출 */
    usb_submit_urb(urb, GFP_ATOMIC);  /* 인터럽트 컨텍스트 → GFP_ATOMIC */
}

/* 5. URB 취소 및 해제 (disconnect 시) */
usb_kill_urb(urb);   /* 동기적으로 취소 후 콜백 완료까지 대기 */
usb_free_urb(urb);   /* 참조 카운트 감소, 0이면 해제 */

완전한 USB 드라이버 예제 — probe, disconnect, URB 기반 데이터 수신을 포함하는 실용적인 USB 드라이버 골격입니다.

#include <linux/module.h>
#include <linux/usb.h>
#include <linux/slab.h>

#define MY_VENDOR_ID   0x1234
#define MY_PRODUCT_ID  0x5678
#define MY_BUF_SIZE    512

struct my_usb_dev {
    struct usb_device    *udev;
    struct usb_interface *intf;
    struct urb           *bulk_in_urb;
    unsigned char        *bulk_in_buf;
    size_t                bulk_in_size;
    __u8                  bulk_in_addr;
    __u8                  bulk_out_addr;
};

static void my_bulk_complete(struct urb *urb)
{
    struct my_usb_dev *dev = urb->context;

    if (urb->status) {
        if (urb->status == -ENOENT ||
            urb->status == -ECONNRESET ||
            urb->status == -ESHUTDOWN)
            return;
        dev_err(&dev->intf->dev, "bulk IN error: %d\n", urb->status);
        return;
    }

    dev_dbg(&dev->intf->dev, "received %d bytes\n", urb->actual_length);
    /* 수신 데이터 처리 ... */
}

/* USB 디바이스 ID 테이블 */
static const struct usb_device_id my_usb_ids[] = {
    { USB_DEVICE(MY_VENDOR_ID, MY_PRODUCT_ID) },
    { USB_INTERFACE_INFO(USB_CLASS_VENDOR_SPEC, 0x01, 0x01) },
    { }  /* 종료 엔트리 */
};
MODULE_DEVICE_TABLE(usb, my_usb_ids);

static int my_usb_probe(struct usb_interface *intf,
        const struct usb_device_id *id)
{
    struct usb_device *udev = interface_to_usbdev(intf);
    struct usb_host_interface *iface_desc = intf->cur_altsetting;
    struct usb_endpoint_descriptor *ep;
    struct my_usb_dev *dev;
    int i;

    /* 디바이스 구조체 할당 */
    dev = kzalloc(sizeof(*dev), GFP_KERNEL);
    if (!dev)
        return -ENOMEM;

    dev->udev = usb_get_dev(udev);
    dev->intf = intf;

    /* 엔드포인트 탐색 — Bulk IN/OUT 찾기 */
    for (i = 0; i < iface_desc->desc.bNumEndpoints; i++) {
        ep = &iface_desc->endpoint[i].desc;

        if (usb_endpoint_is_bulk_in(ep) && !dev->bulk_in_addr) {
            dev->bulk_in_size = usb_endpoint_maxp(ep);
            dev->bulk_in_addr = ep->bEndpointAddress;
        }
        if (usb_endpoint_is_bulk_out(ep) && !dev->bulk_out_addr)
            dev->bulk_out_addr = ep->bEndpointAddress;
    }

    if (!dev->bulk_in_addr || !dev->bulk_out_addr) {
        dev_err(&intf->dev, "required endpoints not found\n");
        goto error;
    }

    /* Bulk IN URB 준비 */
    dev->bulk_in_buf = kmalloc(MY_BUF_SIZE, GFP_KERNEL);
    dev->bulk_in_urb = usb_alloc_urb(0, GFP_KERNEL);
    if (!dev->bulk_in_buf || !dev->bulk_in_urb) {
        dev_err(&intf->dev, "allocation failed\n");
        goto error;
    }

    usb_fill_bulk_urb(dev->bulk_in_urb, udev,
        usb_rcvbulkpipe(udev, dev->bulk_in_addr),
        dev->bulk_in_buf, MY_BUF_SIZE,
        my_bulk_complete, dev);

    /* 인터페이스에 드라이버 데이터 저장 */
    usb_set_intfdata(intf, dev);

    dev_info(&intf->dev, "USB device connected (VID=%04x PID=%04x)\n",
        le16_to_cpu(udev->descriptor.idVendor),
        le16_to_cpu(udev->descriptor.idProduct));
    return 0;

error:
    usb_free_urb(dev->bulk_in_urb);
    kfree(dev->bulk_in_buf);
    usb_put_dev(dev->udev);
    kfree(dev);
    return -ENOMEM;
}

static void my_usb_disconnect(struct usb_interface *intf)
{
    struct my_usb_dev *dev = usb_get_intfdata(intf);

    usb_set_intfdata(intf, NULL);
    usb_kill_urb(dev->bulk_in_urb);  /* 진행 중인 URB 동기적 취소 */
    usb_free_urb(dev->bulk_in_urb);
    kfree(dev->bulk_in_buf);
    usb_put_dev(dev->udev);
    kfree(dev);

    dev_info(&intf->dev, "USB device disconnected\n");
}

static struct usb_driver my_usb_driver = {
    .name       = "my_usb_drv",
    .id_table   = my_usb_ids,
    .probe      = my_usb_probe,
    .disconnect = my_usb_disconnect,
};

module_usb_driver(my_usb_driver);
MODULE_LICENSE("GPL");
MODULE_DESCRIPTION("Example USB driver");

호스트 컨트롤러 드라이버(HCD) 비교 — 호스트 컨트롤러는 USB 버스의 물리적 인터페이스를 제어하며, 각 세대별로 다른 HCD 모듈이 필요합니다.

Video 서브시스템 (V4L2 / DRM)

Audio 서브시스템 (ALSA)

ALSA(Advanced Linux Sound Architecture)는 리눅스 커널의 사운드 서브시스템으로, sound/ 디렉토리에 위치합니다. OSS(Open Sound System)를 대체하며, PCM 재생/녹음, MIDI, 하드웨어 믹서, 시퀀서 등을 지원합니다.

ALSA 아키텍처