sysfs·configfs 활용 — kobject 기반 User 인터페이스

#한 줄 요약

“sysfs = driver가 user에 보여주는 작은 텍스트 파일.” kobject 트리에 attribute를 매다는 한 줄로 LED 밝기든 fan 속도든 똑같은 모양의 인터페이스가 됩니다.

#어떤 상황에서 쓰나

LED 모듈의 brightness나 산업용 ECU의 fan PWM duty처럼 저빈도 제어 값을 노출할 때 sysfs가 ioctl보다 단순할 수 있습니다. 실제 ABI와 권한은 subsystem 문서를 확인합니다.

자동차나 산업 장비의 운영 모니터링도 거의 sysfs로 끝납니다. 온도, 회전수, fault count를 모두 sysfs로 노출하면 별도의 daemon 없이 텍스트 파일 폴링만으로 telemetry가 만들어집니다. configfs는 user space가 새 객체를 만드는 정반대의 흐름인데, USB gadget이나 target framework가 표준으로 씁니다.

#핵심 개념

sysfs는 kobject 트리의 외부 표현입니다.

규칙은 단순합니다. attribute 파일 하나는 값 하나를 가지고, ASCII로 표현하며, 마지막에 newline을 둡니다. 한 파일에 여러 값을 채우면 race가 생기고 user side 파싱도 복잡해집니다.

configfs는 sysfs와 비슷한 모양이지만 user가 mkdir로 새 객체를 만들 수 있다는 점이 다릅니다. USB gadget을 새로 만들거나 NVMe target subsystem을 등록하는 등 생성·파괴가 동적이어야 하는 경우에 쓰입니다.

#코드 / 실제 사용 예

#Device attribute 한 개

1
#include <linux/device.h>
2

3
static unsigned int g_value;
4
static DEFINE_MUTEX(g_lock);
5

6
static ssize_t value_show(struct device *dev, struct device_attribute *a,
7
                          char *buf) {
8
    unsigned int v;
9
    mutex_lock(&g_lock);
10
    v = g_value;
11
    mutex_unlock(&g_lock);
12
    return sysfs_emit(buf, "%u\n", v);
13
}
14

15
static ssize_t value_store(struct device *dev, struct device_attribute *a,
16
                           const char *buf, size_t count) {
17
    unsigned int v;
18
    if (kstrtouint(buf, 10, &v)) return -EINVAL;
19
    if (v > 100) return -ERANGE;
20

21
    mutex_lock(&g_lock);
22
    g_value = v;
23
    mutex_unlock(&g_lock);
24
    return count;
25
}
26

27
static DEVICE_ATTR_RW(value);

DEVICE_ATTR_RW는 mode 0644로 read/write attribute를 등록합니다. 읽기 전용은 _RO, 쓰기 전용은 _WO를 씁니다. 출력에는 sprintf 대신 buffer 길이를 안전하게 처리하는 sysfs_emit을 사용합니다.

#Attribute group으로 한 번에 등록

1
static struct attribute *sample_attrs[] = {
2
    &dev_attr_value.attr,
3
    &dev_attr_mode.attr,
4
    &dev_attr_status.attr,
5
    NULL,
6
};
7

8
static const struct attribute_group sample_group = {
9
    .name  = "control",       /* /sys/.../control/ 디렉터리 생성 */
10
    .attrs = sample_attrs,
11
};
12

13
static int sample_probe(struct platform_device *pdev) {
14
    int rc = sysfs_create_group(&pdev->dev.kobj, &sample_group);
15
    if (rc) return rc;
16

17
    /* devm 형 helper도 있다 */
18
    return devm_device_add_group(&pdev->dev, &sample_group);
19
}

devm_device_add_group을 쓰면 driver unbind 시 자동으로 정리됩니다. 잘 쓰면 remove에서 cleanup을 빠뜨릴 일이 없습니다.

#결과 모양

1
$ ls /sys/devices/platform/sample/control/
2
mode  status  value
3

4
$ cat /sys/devices/platform/sample/control/value
5
0
6

7
$ echo 42 > /sys/devices/platform/sample/control/value
8
$ cat /sys/devices/platform/sample/control/value
9
42

device class와 결합하면 /sys/class/...에 안정된 symlink가 생기고, udev rule이 이걸 보고 hot-plug 동작을 정의합니다.

#udev rule과 결합

1
SUBSYSTEM=="sample", ACTION=="add", \
2
    RUN+="/usr/bin/setup-sample.sh %k"
3

4
KERNEL=="leds*", ATTR{brightness}="64"

device가 들어오면 udev가 sysfs 트리를 보고 rule을 매칭합니다. 초기값 설정은 udev로 처리하는 편이 driver 안에 hard-code하는 것보다 깔끔합니다.

#Binary attribute — 큰 데이터

1
static ssize_t fw_read(struct file *f, struct kobject *k,
2
                       struct bin_attribute *a,
3
                       char *buf, loff_t off, size_t count) {
4
    if (off >= fw_size) return 0;
5
    if (off + count > fw_size) count = fw_size - off;
6
    memcpy(buf, fw_data + off, count);
7
    return count;
8
}
9

10
static struct bin_attribute fw_attr = {
11
    .attr = { .name = "firmware", .mode = 0444 },
12
    .read = fw_read,
13
    .size = 0,                /* runtime 결정 */
14
};
15

16
sysfs_create_bin_file(&pdev->dev.kobj, &fw_attr);

ASCII 텍스트가 어색한 firmware blob·calibration data는 binary attribute로 노출할 수 있습니다. 일반 attribute는 텍스트 출력과 ABI 규칙에 제약이 있어 큰 데이터에는 부적합합니다.

#configfs — user가 객체를 만든다

1
mount -t configfs none /sys/kernel/config
2

3
# USB gadget 인스턴스 생성
4
mkdir /sys/kernel/config/usb_gadget/g1
5
echo 0x1d6b > /sys/kernel/config/usb_gadget/g1/idVendor
6
echo 0x0104 > /sys/kernel/config/usb_gadget/g1/idProduct
7

8
mkdir /sys/kernel/config/usb_gadget/g1/configs/c.1
9
mkdir /sys/kernel/config/usb_gadget/g1/functions/acm.0
10
ln -s ../../functions/acm.0 ../../configs/c.1/
11
echo musb-hdrc.0 > /sys/kernel/config/usb_gadget/g1/UDC

mkdir 한 번이 kernel 객체 하나의 생성에 대응합니다. USB gadget, NVMe-oF target, LIO iSCSI target이 같은 패턴을 사용합니다.

#sysfs_notify로 user에게 신호 보내기

1
/* 값이 바뀌었음을 알린다 */
2
sysfs_notify(&pdev->dev.kobj, NULL, "value");

user 쪽에서는 poll이나 epoll로 attribute 파일을 감시하다가 변화 시점에 깨어납니다. 주기적 polling 없이 이벤트 기반 monitoring이 가능합니다.

#측정 / 성능 비교

sysfs read/write 자체는 가벼운 syscall + kernel function call입니다. fast path 인터페이스가 아니라 제어 plane이라는 점만 잊지 않으면 됩니다.

LED brightness나 fan duty처럼 저빈도 제어에는 sysfs가 적합할 수 있습니다. 고주기 sensor sampling이나 audio stream은 전용 data interface를 사용하고 syscall·buffer 비용을 측정합니다.

#자주 보는 함정

한 파일에 여러 값

1
return sysfs_emit(buf, "%u %u %u\n", a, b, c);

규약상 한 attribute = 한 값입니다. 여러 값을 모아 두면 parser가 깨지고, store 쪽에서 partial write도 처리하기 어렵습니다. 값마다 별도 attribute로 쪼개는 편이 좋습니다.

store 안에서 긴 작업

1
static ssize_t reset_store(...) {
2
    msleep(500);   /* user는 echo 동안 차단 */
3
    return count;
4
}

echo가 500 ms 멈춥니다. 긴 작업은 work queue에 큐잉하고 store는 즉시 반환합니다. 완료 통지는 sysfs_notify로 보냅니다.

Lock 없이 share state read·write

1
return sysfs_emit(buf, "%u\n", g_value);   /* tearing 가능 */

여러 user가 동시에 read/write하면 32비트 이상의 값에서 tearing이 일어날 수 있습니다. mutex 또는 atomic으로 보호합니다.

ASCII 규약 무시

1
return sysfs_emit(buf, "%08x", v);   /* 마지막 newline 누락 */

마지막 newline이 빠지면 cat 출력이 prompt와 붙고, 일부 parser가 EOF를 잘못 잡습니다. \n을 잊지 않습니다.

Cleanup 누락

1
static void sample_remove(struct platform_device *pdev) {
2
    /* sysfs_remove_group 누락 */
3
}

다음 bind 때 sysfs: cannot create duplicate filename 오류가 납니다. devm_device_add_group 같은 managed API로 등록과 해제를 한 쌍으로 묶는 편이 안전합니다.

#정리

• sysfs는 driver state를 ASCII 한 줄로 노출하는 가장 단순한 인터페이스입니다.
• 한 attribute = 한 값, 마지막 newline 포함이라는 규약을 지켜야 user 도구와 호환됩니다.
• DEVICE_ATTR_RW·sysfs_emit·devm_device_add_group을 묶어 쓰면 등록·해제·출력 모두 안전하게 처리됩니다.
• udev rule은 sysfs 트리를 보고 동작을 정의하므로 driver와 자연스럽게 결합됩니다.
• sysfs_notify는 user 쪽 polling을 이벤트 기반으로 바꿔 줍니다.
• configfs는 정반대로 user가 객체를 만드는 인터페이스이고, USB gadget·NVMe target이 대표 사례입니다.
• sysfs는 제어 plane이라는 점을 기억합니다. 고빈도 data path는 mmap·io_uring·char device로 보내야 합니다.

다음 편은 IRQ Affinity입니다.

#관련 항목

• 1-04: Device Tree
• 4-01: Kernel Module
• 4-06: IRQ Affinity