Adding reference counters (krefs) to kernel objects

문서 정보

Kernel object에 reference counter(kref) 추가하기 (Adding reference counters (krefs) to kernel objects)

저자: Corey Minyard <minyard@acm.org>

저자: Thomas Hellström <thomas.hellstrom@linux.intel.com>

이 문서의 많은 내용은 Greg Kroah-Hartman의 2004 OLS kref 논문과 발표에서 가져왔습니다.

• http://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf
• http://www.kroah.com/linux/talks/ols_2004_kref_talk/

kref 소개와 embedding

소개 (Introduction)

Kref를 사용하면 object에 reference counter를 추가할 수 있습니다. 여러 곳에서 사용하고 전달하는 object에 refcount가 없다면 code는 거의 확실히 잘못되어 있습니다. Refcount가 필요하면 kref를 사용해야 합니다.

Kref를 사용하려면 다음과 같이 data structure에 하나를 추가합니다.

struct my_data
{
    .
    .
    struct kref refcount;
    .
    .
};

Kref는 data structure 안의 어느 위치에 있어도 됩니다.

kref 초기화

초기화 (Initialization)

Kref를 할당한 뒤에는 반드시 초기화해야 합니다. 다음과 같이 `kref_init`을 호출합니다.

struct my_data *data;

data = kmalloc(sizeof(*data), GFP_KERNEL);
if (!data)
       return -ENOMEM;
kref_init(&data->refcount);

이 호출은 kref의 refcount를 1로 설정합니다.

kref의 세 가지 규칙

Kref 규칙 (Kref rules)

초기화된 kref를 사용하려면 다음 규칙을 지켜야 합니다.

• 임시가 아닌 pointer 사본을 만들 때, 특히 다른 execution thread로 전달할 수 있다면 전달하기 전에 `kref_get()`으로 refcount를 증가시켜야 합니다.
• Pointer 사용을 마치면 `kref_put()`을 호출해야 합니다. 마지막 reference라면 release routine이 호출됩니다.
• 유효한 pointer를 이미 보유하지 않은 상태에서 kref가 있는 structure의 reference를 얻으려면 `kref_get()` 도중 `kref_put()`이 일어날 수 없도록 접근을 serialize해야 하며, `kref_get()` 동안 structure가 유효하게 남아 있어야 합니다.

첫 번째 규칙의 reference 획득 호출은 다음과 같습니다.

kref_get(&data->refcount);

Refcount가 0이 될 수 없는 kref structure의 유효한 pointer를 이미 가지고 있다면 lock 없이 `kref_get()`을 호출할 수 있습니다.

두 번째 규칙의 reference 해제 호출은 다음과 같습니다.

kref_put(&data->refcount, data_release);

이 pointer의 마지막 reference라면 release routine이 호출됩니다. 유효한 pointer를 보유하지 않고 kref structure의 pointer를 얻으려는 code가 없다면 이 작업도 lock 없이 안전하게 수행할 수 있습니다.

두 thread 사이에서 object 전달하기

예를 들어 data를 할당해 다른 thread가 처리하도록 전달하는 code는 다음과 같습니다.

void data_release(struct kref *ref)
{
    struct my_data *data = container_of(ref, struct my_data, refcount);
    kfree(data);
}

void more_data_handling(void *cb_data)
{
    struct my_data *data = cb_data;
    .
    . do stuff with data here
    .
    kref_put(&data->refcount, data_release);
}

int my_data_handler(void)
{
    int rv = 0;
    struct my_data *data;
    struct task_struct *task;
    data = kmalloc(sizeof(*data), GFP_KERNEL);
    if (!data)
            return -ENOMEM;
    kref_init(&data->refcount);

    kref_get(&data->refcount);
    task = kthread_run(more_data_handling, data, "more_data_handling");
    if (task == ERR_PTR(-ENOMEM)) {
            rv = -ENOMEM;
            kref_put(&data->refcount, data_release);
            goto out;
    }

    .
    . do stuff with data here
    .
out:
    kref_put(&data->refcount, data_release);
    return rv;
}

두 thread가 어떤 순서로 data를 처리하든 `kref_put()`이 더는 reference되지 않는 시점을 판단해 data를 release합니다. 이미 자신이 reference를 보유한 유효한 pointer가 있으므로 `kref_get()`에는 lock이 필요하지 않습니다. Pointer를 보유하지 않은 code가 data를 얻으려 하지 않으므로 put에도 lock이 필요 없습니다.

위 예제에서는 success path와 error path 모두 `kref_put()`을 두 번 호출합니다. `kref_init()`과 `kref_get()`이 reference count를 두 번 증가시켰으므로 두 번 감소시켜야 합니다.

handoff 전에 reference 얻기

첫 번째 규칙의 '전에(before)'는 매우 중요합니다. 다음과 같이 handoff 뒤에 reference를 얻으면 안 됩니다.

task = kthread_run(more_data_handling, data, "more_data_handling");
if (task == ERR_PTR(-ENOMEM)) {
        rv = -ENOMEM;
        goto out;
} else
        /* BAD BAD BAD - get is after the handoff */
        kref_get(&data->refcount);

자신이 상황을 정확히 안다고 가정해 이런 구문을 사용하지 마십시오. Locking 때문에 합법적인 특수 상황이 있더라도 나중에 다른 사람이 code를 변경하거나 복사할 수 있습니다. 나쁜 style이므로 사용하지 않아야 합니다.

get/put 대신 reference 소유권 넘기기

일부 상황에서는 get과 put을 최적화할 수 있습니다. Object 사용을 끝내면서 다른 작업을 위해 enqueue하거나 다른 곳으로 넘긴다면 get 직후 put을 수행할 이유가 없습니다.

/* Silly extra get and put */
kref_get(&obj->ref);
enqueue(obj);
kref_put(&obj->ref, obj_cleanup);

그 대신 enqueue만 수행하십시오. Reference 소유권을 queue에 넘겼으며 이후 object를 건드리면 안 된다는 comment를 남기는 것이 좋습니다.

enqueue(obj);
/* We are done with obj, so we pass our refcount off
   to the queue.  DON'T TOUCH obj AFTER HERE! */

유효한 pointer 없이 reference 얻기

마지막 규칙인 세 번째 규칙이 가장 다루기 어렵습니다. 각각 kref를 가진 item의 list에서 첫 item을 얻는 경우, 유효한 pointer를 아직 보유하지 않았으므로 item을 list에서 꺼낸 뒤 바로 `kref_get()`을 호출할 수 없습니다. 이 접근에는 mutex 또는 다른 lock을 추가해야 합니다.

static DEFINE_MUTEX(mutex);
static LIST_HEAD(q);
struct my_data
{
        struct kref      refcount;
        struct list_head link;
};

static struct my_data *get_entry()
{
        struct my_data *entry = NULL;
        mutex_lock(&mutex);
        if (!list_empty(&q)) {
                entry = container_of(q.next, struct my_data, link);
                kref_get(&entry->refcount);
        }
        mutex_unlock(&mutex);
        return entry;
}

static void release_entry(struct kref *ref)
{
        struct my_data *entry = container_of(ref, struct my_data, refcount);

        list_del(&entry->link);
        kfree(entry);
}

static void put_entry(struct my_data *entry)
{
        mutex_lock(&mutex);
        kref_put(&entry->refcount, release_entry);
        mutex_unlock(&mutex);
}

kref_put() 반환값으로 lock 범위 줄이기

전체 release operation 동안 lock을 유지하고 싶지 않을 때 `kref_put()`의 반환값이 유용합니다. 예를 들어 lock을 잡은 채 `kfree()`를 호출하고 싶지 않다면 다음처럼 사용할 수 있습니다.

static void release_entry(struct kref *ref)
{
        /* All work is done after the return from kref_put(). */
}

static void put_entry(struct my_data *entry)
{
        mutex_lock(&mutex);
        if (kref_put(&entry->refcount, release_entry)) {
                list_del(&entry->link);
                mutex_unlock(&mutex);
                kfree(entry);
        } else
                mutex_unlock(&mutex);
}

Free 과정의 일부로 오래 걸리거나 같은 lock을 획득할 수 있는 다른 routine을 호출해야 할 때 특히 유용합니다. 다만 모든 작업을 release routine 안에서 수행하는 쪽이 조금 더 깔끔하므로 여전히 선호됩니다.

kref_get_unless_zero() 최적화

위 예제는 `kref_get_unless_zero()`를 사용해 다음과 같이 최적화할 수도 있습니다.

static struct my_data *get_entry()
{
        struct my_data *entry = NULL;
        mutex_lock(&mutex);
        if (!list_empty(&q)) {
                entry = container_of(q.next, struct my_data, link);
                if (!kref_get_unless_zero(&entry->refcount))
                        entry = NULL;
        }
        mutex_unlock(&mutex);
        return entry;
}

static void release_entry(struct kref *ref)
{
        struct my_data *entry = container_of(ref, struct my_data, refcount);

        mutex_lock(&mutex);
        list_del(&entry->link);
        mutex_unlock(&mutex);
        kfree(entry);
}

static void put_entry(struct my_data *entry)
{
        kref_put(&entry->refcount, release_entry);
}

이 방식은 `put_entry()`에서 `kref_put()` 주위의 mutex lock을 없앨 때 유용합니다. 다만 `kref_get_unless_zero()`는 lookup table에서 entry를 찾는 것과 같은 critical section 안에 있어야 합니다. 그렇지 않으면 이미 free된 memory를 참조할 수 있습니다.

`kref_get_unless_zero()`의 반환값을 확인하지 않고 사용하는 것은 잘못입니다. 이미 유효한 pointer를 보유해 이 함수가 true를 반환한다고 확신할 수 있다면 대신 `kref_get()`을 사용하십시오.

Kref와 RCU

Kref와 RCU (Krefs and RCU)

`kref_get_unless_zero`를 사용하면 위 예제의 lookup에 RCU locking을 사용할 수도 있습니다.

struct my_data
{
        struct rcu_head rhead;
        .
        struct kref refcount;
        .
        .
};

static struct my_data *get_entry_rcu()
{
        struct my_data *entry = NULL;
        rcu_read_lock();
        if (!list_empty(&q)) {
                entry = container_of(q.next, struct my_data, link);
                if (!kref_get_unless_zero(&entry->refcount))
                        entry = NULL;
        }
        rcu_read_unlock();
        return entry;
}

static void release_entry_rcu(struct kref *ref)
{
        struct my_data *entry = container_of(ref, struct my_data, refcount);

        mutex_lock(&mutex);
        list_del_rcu(&entry->link);
        mutex_unlock(&mutex);
        kfree_rcu(entry, rhead);
}

static void put_entry(struct my_data *entry)
{
        kref_put(&entry->refcount, release_entry_rcu);
}

`release_entry_rcu`를 호출한 뒤 RCU grace period 동안 `struct kref` member가 유효한 memory에 남아 있어야 합니다. 위처럼 `kfree_rcu(entry, rhead)`를 사용하거나 `kfree` 전에 `synchronize_rcu()`를 호출하면 됩니다. 다만 `synchronize_rcu()`는 상당히 오래 sleep할 수 있습니다.

함수와 structure

함수와 structure (Functions and structures)

Kref API의 kernel-doc 원문은 `include/linux/kref.h`에서 가져옵니다.

.. kernel-doc:: include/linux/kref.h