€•¡      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”(hhŒparent”hubaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ!/translations/zh_CN/core-api/kref”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”(hhhh2ubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ!/translations/zh_TW/core-api/kref”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”(hhhhFubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ!/translations/it_IT/core-api/kref”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”(hhhhZubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ!/translations/ja_JP/core-api/kref”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”(hhhhnubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ!/translations/ko_KR/core-api/kref”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”(hhhh‚ubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ!/translations/sp_SP/core-api/kref”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ3Adding reference counters (krefs) to kernel objects”h]”hŒ3Adding reference counters (krefs) to kernel objects”…””}”(hhªhh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒ;/var/lib/git/docbuild/linux/Documentation/core-api/kref.rst”h KubhŒ
field_list”“”)”}”(hhh]”(hŒfield”“”)”}”(hhh]”(hŒ
field_name”“”)”}”(hŒAuthor”h]”hŒAuthor”…””}”(hhÅhhÃhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÁhh¾hŸh¶h K ubhŒ
field_body”“”)”}”(hŒCorey Minyard <minyard@acm.org>”h]”hŒ	paragraph”“”)”}”(hhÕh]”(hŒCorey Minyard <”…””}”(hŒCorey Minyard <”hhÙhžhhŸNh NubhŒ	reference”“”)”}”(hŒminyard@acm.org”h]”hŒminyard@acm.org”…””}”(hhhhãhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:minyard@acm.org”uh1háhhÙubhŒ>”…””}”(hŒ>”hhÙhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KhhÓubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑhh¾ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h¼hŸh¶h Khh¹hžhubh½)”}”(hhh]”(hÂ)”}”(hŒAuthor”h]”hŒAuthor”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÁhj
  hŸh¶h K ubhÒ)”}”(hŒ)Thomas Hellstrom <thellstrom@vmware.com>
”h]”hØ)”}”(hŒ(Thomas Hellstrom <thellstrom@vmware.com>”h]”(hŒThomas Hellstrom <”…””}”(hŒThomas Hellstrom <”hj  hžhhŸNh Nubhâ)”}”(hŒthellstrom@vmware.com”h]”hŒthellstrom@vmware.com”…””}”(hhhj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:thellstrom@vmware.com”uh1háhj  ubhŒ>”…””}”(hh÷hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑhj
  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h¼hŸh¶h Khh¹hžhubeh}”(h]”h ]”h"]”h$]”h&]”uh1h·hh£hžhhŸh¶h KubhØ)”}”(hŒsA lot of this was lifted from Greg Kroah-Hartman's 2004 OLS paper and
presentation on krefs, which can be found at:”h]”hŒuA lot of this was lifted from Greg Kroah-Hartmanâ€™s 2004 OLS paper and
presentation on krefs, which can be found at:”…””}”(hjV  hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khh£hžhubhŒblock_quote”“”)”}”(hhh]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒVhttp://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf”h]”hØ)”}”(hjp  h]”hâ)”}”(hjp  h]”hŒVhttp://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf”…””}”(hhhju  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jp  uh1háhjr  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khjn  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jl  hji  ubjm  )”}”(hŒ5http://www.kroah.com/linux/talks/ols_2004_kref_talk/
”h]”hØ)”}”(hŒ4http://www.kroah.com/linux/talks/ols_2004_kref_talk/”h]”hâ)”}”(hj•  h]”hŒ4http://www.kroah.com/linux/talks/ols_2004_kref_talk/”…””}”(hhhj—  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j•  uh1háhj“  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jl  hji  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jg  hŸh¶h Khjd  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jb  hh£hžhhŸNh Nubh¢)”}”(hhh]”(h§)”}”(hŒIntroduction”h]”hŒIntroduction”…””}”(hjÄ  hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj¿  hžhhŸh¶h KubhØ)”}”(hŒøkrefs allow you to add reference counters to your objects.  If you
have objects that are used in multiple places and passed around, and
you don't have refcounts, your code is almost certainly broken.  If
you want refcounts, krefs are the way to go.”h]”hŒúkrefs allow you to add reference counters to your objects.  If you
have objects that are used in multiple places and passed around, and
you donâ€™t have refcounts, your code is almost certainly broken.  If
you want refcounts, krefs are the way to go.”…””}”(hjÒ  hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj¿  hžhubhØ)”}”(hŒ5To use a kref, add one to your data structures like::”h]”hŒ4To use a kref, add one to your data structures like:”…””}”(hŒ4To use a kref, add one to your data structures like:”hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj¿  hžhubhŒliteral_block”“”)”}”(hŒEstruct my_data
{
    .
    .
    struct kref refcount;
    .
    .
};”h]”hŒEstruct my_data
{
    .
    .
    struct kref refcount;
    .
    .
};”…””}”(hhhjï  ubah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jí  hŸh¶h Khj¿  hžhubhØ)”}”(hŒ6The kref can occur anywhere within the data structure.”h]”hŒ6The kref can occur anywhere within the data structure.”…””}”(hj  hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K!hj¿  hžhubeh}”(h]”Œintroduction”ah ]”h"]”Œintroduction”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒInitialization”h]”hŒInitialization”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h K$ubhØ)”}”(hŒWYou must initialize the kref after you allocate it.  To do this, call
kref_init as so::”h]”hŒVYou must initialize the kref after you allocate it.  To do this, call
kref_init as so:”…””}”(hŒVYou must initialize the kref after you allocate it.  To do this, call
kref_init as so:”hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K&hj  hžhubjî  )”}”(hŒstruct my_data *data;

data = kmalloc(sizeof(*data), GFP_KERNEL);
if (!data)
       return -ENOMEM;
kref_init(&data->refcount);”h]”hŒstruct my_data *data;

data = kmalloc(sizeof(*data), GFP_KERNEL);
if (!data)
       return -ENOMEM;
kref_init(&data->refcount);”…””}”(hhhj5  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h K)hj  hžhubhØ)”}”(hŒ(This sets the refcount in the kref to 1.”h]”hŒ(This sets the refcount in the kref to 1.”…””}”(hjE  hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K0hj  hžhubeh}”(h]”Œinitialization”ah ]”h"]”Œinitialization”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K$ubh¢)”}”(hhh]”(h§)”}”(hŒ
Kref rules”h]”hŒ
Kref rules”…””}”(hj^  hj\  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjY  hžhhŸh¶h K3ubhØ)”}”(hŒGOnce you have an initialized kref, you must follow the following
rules:”h]”hŒGOnce you have an initialized kref, you must follow the following
rules:”…””}”(hjl  hjj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K5hjY  hžhubhŒenumerated_list”“”)”}”(hhh]”(jm  )”}”(hXS  If you make a non-temporary copy of a pointer, especially if
it can be passed to another thread of execution, you must
increment the refcount with kref_get() before passing it off::

    kref_get(&data->refcount);

If you already have a valid pointer to a kref-ed structure (the
refcount cannot go to zero) you may do this without a lock.
”h]”(hØ)”}”(hŒµIf you make a non-temporary copy of a pointer, especially if
it can be passed to another thread of execution, you must
increment the refcount with kref_get() before passing it off::”h]”hŒ´If you make a non-temporary copy of a pointer, especially if
it can be passed to another thread of execution, you must
increment the refcount with kref_get() before passing it off:”…””}”(hŒ´If you make a non-temporary copy of a pointer, especially if
it can be passed to another thread of execution, you must
increment the refcount with kref_get() before passing it off:”hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K8hj}  ubjî  )”}”(hŒkref_get(&data->refcount);”h]”hŒkref_get(&data->refcount);”…””}”(hhhj  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h K<hj}  ubhØ)”}”(hŒ{If you already have a valid pointer to a kref-ed structure (the
refcount cannot go to zero) you may do this without a lock.”h]”hŒ{If you already have a valid pointer to a kref-ed structure (the
refcount cannot go to zero) you may do this without a lock.”…””}”(hj   hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K>hj}  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jl  hjz  hžhhŸh¶h Nubjm  )”}”(hXT  When you are done with a pointer, you must call kref_put()::

    kref_put(&data->refcount, data_release);

If this is the last reference to the pointer, the release
routine will be called.  If the code never tries to get
a valid pointer to a kref-ed structure without already
holding a valid pointer, it is safe to do this without
a lock.
”h]”(hØ)”}”(hŒ<When you are done with a pointer, you must call kref_put()::”h]”hŒ;When you are done with a pointer, you must call kref_put():”…””}”(hŒ;When you are done with a pointer, you must call kref_put():”hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KAhj²  ubjî  )”}”(hŒ(kref_put(&data->refcount, data_release);”h]”hŒ(kref_put(&data->refcount, data_release);”…””}”(hhhjÅ  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h KChj²  ubhØ)”}”(hŒçIf this is the last reference to the pointer, the release
routine will be called.  If the code never tries to get
a valid pointer to a kref-ed structure without already
holding a valid pointer, it is safe to do this without
a lock.”h]”hŒçIf this is the last reference to the pointer, the release
routine will be called.  If the code never tries to get
a valid pointer to a kref-ed structure without already
holding a valid pointer, it is safe to do this without
a lock.”…””}”(hjÕ  hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KEhj²  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jl  hjz  hžhhŸh¶h Nubjm  )”}”(hŒôIf the code attempts to gain a reference to a kref-ed structure
without already holding a valid pointer, it must serialize access
where a kref_put() cannot occur during the kref_get(), and the
structure must remain valid during the kref_get().
”h]”hØ)”}”(hŒóIf the code attempts to gain a reference to a kref-ed structure
without already holding a valid pointer, it must serialize access
where a kref_put() cannot occur during the kref_get(), and the
structure must remain valid during the kref_get().”h]”hŒóIf the code attempts to gain a reference to a kref-ed structure
without already holding a valid pointer, it must serialize access
where a kref_put() cannot occur during the kref_get(), and the
structure must remain valid during the kref_get().”…””}”(hjí  hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KKhjç  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jl  hjz  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ)”uh1jx  hjY  hžhhŸh¶h K8ubhØ)”}”(hŒVFor example, if you allocate some data and then pass it to another
thread to process::”h]”hŒUFor example, if you allocate some data and then pass it to another
thread to process:”…””}”(hŒUFor example, if you allocate some data and then pass it to another
thread to process:”hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KPhjY  hžhubjî  )”}”(hXk  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;
}”h]”hXk  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;
}”…””}”(hhhj  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h KShjY  hžhubhØ)”}”(hXl  This way, it doesn't matter what order the two threads handle the
data, the kref_put() handles knowing when the data is not referenced
any more and releasing it.  The kref_get() does not require a lock,
since we already have a valid pointer that we own a refcount for.  The
put needs no lock because nothing tries to get the data without
already holding a pointer.”h]”hXn  This way, it doesnâ€™t matter what order the two threads handle the
data, the kref_put() handles knowing when the data is not referenced
any more and releasing it.  The kref_get() does not require a lock,
since we already have a valid pointer that we own a refcount for.  The
put needs no lock because nothing tries to get the data without
already holding a pointer.”…””}”(hj)  hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K|hjY  hžhubhØ)”}”(hŒ½In the above example, kref_put() will be called 2 times in both success
and error paths. This is necessary because the reference count got
incremented 2 times by kref_init() and kref_get().”h]”hŒ½In the above example, kref_put() will be called 2 times in both success
and error paths. This is necessary because the reference count got
incremented 2 times by kref_init() and kref_get().”…””}”(hj7  hj5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KƒhjY  hžhubhØ)”}”(hŒYNote that the "before" in rule 1 is very important.  You should never
do something like::”h]”hŒ\Note that the â€œbeforeâ€ in rule 1 is very important.  You should never
do something like:”…””}”(hŒXNote that the "before" in rule 1 is very important.  You should never
do something like:”hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K‡hjY  hžhubjî  )”}”(hŒê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);”h]”hŒê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);”…””}”(hhhjR  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h KŠhjY  hžhubhØ)”}”(hXo  Don't assume you know what you are doing and use the above construct.
First of all, you may not know what you are doing.  Second, you may
know what you are doing (there are some situations where locking is
involved where the above may be legal) but someone else who doesn't
know what they are doing may change the code or copy the code.  It's
bad style.  Don't do it.”h]”hXw  Donâ€™t assume you know what you are doing and use the above construct.
First of all, you may not know what you are doing.  Second, you may
know what you are doing (there are some situations where locking is
involved where the above may be legal) but someone else who doesnâ€™t
know what they are doing may change the code or copy the code.  Itâ€™s
bad style.  Donâ€™t do it.”…””}”(hjb  hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K’hjY  hžhubhØ)”}”(hŒåThere are some situations where you can optimize the gets and puts.
For instance, if you are done with an object and enqueuing it for
something else or passing it off to something else, there is no reason
to do a get then a put::”h]”hŒäThere are some situations where you can optimize the gets and puts.
For instance, if you are done with an object and enqueuing it for
something else or passing it off to something else, there is no reason
to do a get then a put:”…””}”(hŒäThere are some situations where you can optimize the gets and puts.
For instance, if you are done with an object and enqueuing it for
something else or passing it off to something else, there is no reason
to do a get then a put:”hjn  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K™hjY  hžhubjî  )”}”(hŒb/* Silly extra get and put */
kref_get(&obj->ref);
enqueue(obj);
kref_put(&obj->ref, obj_cleanup);”h]”hŒb/* Silly extra get and put */
kref_get(&obj->ref);
enqueue(obj);
kref_put(&obj->ref, obj_cleanup);”…””}”(hhhj}  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h KžhjY  hžhubhØ)”}”(hŒ>Just do the enqueue.  A comment about this is always welcome::”h]”hŒ=Just do the enqueue.  A comment about this is always welcome:”…””}”(hŒ=Just do the enqueue.  A comment about this is always welcome:”hj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K£hjY  hžhubjî  )”}”(hŒsenqueue(obj);
/* We are done with obj, so we pass our refcount off
   to the queue.  DON'T TOUCH obj AFTER HERE! */”h]”hŒsenqueue(obj);
/* We are done with obj, so we pass our refcount off
   to the queue.  DON'T TOUCH obj AFTER HERE! */”…””}”(hhhjš  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h K¥hjY  hžhubhØ)”}”(hXf  The last rule (rule 3) is the nastiest one to handle.  Say, for
instance, you have a list of items that are each kref-ed, and you wish
to get the first one.  You can't just pull the first item off the list
and kref_get() it.  That violates rule 3 because you are not already
holding a valid pointer.  You must add a mutex (or some other lock).
For instance::”h]”hXg  The last rule (rule 3) is the nastiest one to handle.  Say, for
instance, you have a list of items that are each kref-ed, and you wish
to get the first one.  You canâ€™t just pull the first item off the list
and kref_get() it.  That violates rule 3 because you are not already
holding a valid pointer.  You must add a mutex (or some other lock).
For instance:”…””}”(hXe  The last rule (rule 3) is the nastiest one to handle.  Say, for
instance, you have a list of items that are each kref-ed, and you wish
to get the first one.  You can't just pull the first item off the list
and kref_get() it.  That violates rule 3 because you are not already
holding a valid pointer.  You must add a mutex (or some other lock).
For instance:”hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K©hjY  hžhubjî  )”}”(hX  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);
}”h]”hX  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);
}”…””}”(hhhj·  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h K°hjY  hžhubhØ)”}”(hX  The kref_put() return value is useful if you do not want to hold the
lock during the whole release operation.  Say you didn't want to call
kfree() with the lock held in the example above (since it is kind of
pointless to do so).  You could use kref_put() as follows::”h]”hX  The kref_put() return value is useful if you do not want to hold the
lock during the whole release operation.  Say you didnâ€™t want to call
kfree() with the lock held in the example above (since it is kind of
pointless to do so).  You could use kref_put() as follows:”…””}”(hX
  The kref_put() return value is useful if you do not want to hold the
lock during the whole release operation.  Say you didn't want to call
kfree() with the lock held in the example above (since it is kind of
pointless to do so).  You could use kref_put() as follows:”hjÅ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÓhjY  hžhubjî  )”}”(hX˜  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);
}”h]”hX˜  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);
}”…””}”(hhhjÔ  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h KØhjY  hžhubhØ)”}”(hŒöThis is really more useful if you have to call other routines as part
of the free operations that could take a long time or might claim the
same lock.  Note that doing everything in the release routine is still
preferred as it is a little neater.”h]”hŒöThis is really more useful if you have to call other routines as part
of the free operations that could take a long time or might claim the
same lock.  Note that doing everything in the release routine is still
preferred as it is a little neater.”…””}”(hjä  hjâ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KèhjY  hžhubhØ)”}”(hŒ]The above example could also be optimized using kref_get_unless_zero() in
the following way::”h]”hŒ\The above example could also be optimized using kref_get_unless_zero() in
the following way:”…””}”(hŒ\The above example could also be optimized using kref_get_unless_zero() in
the following way:”hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KíhjY  hžhubjî  )”}”(hXÀ  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);
}”h]”hXÀ  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);
}”…””}”(hhhjÿ  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h KðhjY  hžhubhØ)”}”(hXã  Which is useful to remove the mutex lock around kref_put() in put_entry(), but
it's important that kref_get_unless_zero is enclosed in the same critical
section that finds the entry in the lookup table,
otherwise kref_get_unless_zero may reference already freed memory.
Note that it is illegal to use kref_get_unless_zero without checking its
return value. If you are sure (by already having a valid pointer) that
kref_get_unless_zero() will return true, then use kref_get() instead.”h]”hXå  Which is useful to remove the mutex lock around kref_put() in put_entry(), but
itâ€™s important that kref_get_unless_zero is enclosed in the same critical
section that finds the entry in the lookup table,
otherwise kref_get_unless_zero may reference already freed memory.
Note that it is illegal to use kref_get_unless_zero without checking its
return value. If you are sure (by already having a valid pointer) that
kref_get_unless_zero() will return true, then use kref_get() instead.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MhjY  hžhubeh}”(h]”Œ
kref-rules”ah ]”h"]”Œ
kref rules”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K3ubh¢)”}”(hhh]”(h§)”}”(hŒKrefs and RCU”h]”hŒKrefs and RCU”…””}”(hj(  hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj#  hžhhŸh¶h MubhØ)”}”(hŒnThe function kref_get_unless_zero also makes it possible to use rcu
locking for lookups in the above example::”h]”hŒmThe function kref_get_unless_zero also makes it possible to use rcu
locking for lookups in the above example:”…””}”(hŒmThe function kref_get_unless_zero also makes it possible to use rcu
locking for lookups in the above example:”hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhj#  hžhubjî  )”}”(hXE  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);
}”h]”hXE  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);
}”…””}”(hhhjC  ubah}”(h]”h ]”h"]”h$]”h&]”jý  jþ  uh1jí  hŸh¶h Mhj#  hžhubhØ)”}”(hXH  But note that the struct kref member needs to remain in valid memory for a
rcu grace period after release_entry_rcu was called. That can be accomplished
by using kfree_rcu(entry, rhead) as done above, or by calling synchronize_rcu()
before using kfree, but note that synchronize_rcu() may sleep for a
substantial amount of time.”h]”hXH  But note that the struct kref member needs to remain in valid memory for a
rcu grace period after release_entry_rcu was called. That can be accomplished
by using kfree_rcu(entry, rhead) as done above, or by calling synchronize_rcu()
before using kfree, but note that synchronize_rcu() may sleep for a
substantial amount of time.”…””}”(hjS  hjQ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M?hj#  hžhubeh}”(h]”Œkrefs-and-rcu”ah ]”h"]”Œkrefs and rcu”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Mubeh}”(h]”Œ1adding-reference-counters-krefs-to-kernel-objects”ah ]”h"]”Œ3adding reference counters (krefs) to kernel objects”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j’  Œerror_encoding”ŒUTF-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œembed_images”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jl  ji  j  j  jV  jS  j   j  jd  ja  uŒ	nametypes”}”(jl  Nj  NjV  Nj   Njd  Nuh}”(ji  h£j  j¿  jS  j  j  jY  ja  j#  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.