* [PATCH] docs/zh_CN: add core api kref translation
@ 2021-09-10 6:42 Yanteng Si
2021-09-20 10:01 ` yanteng si
0 siblings, 1 reply; 3+ messages in thread
From: Yanteng Si @ 2021-09-10 6:42 UTC (permalink / raw)
To: corbet, alexs, seakeel
Cc: chenhuacai, jiaxun.yang, linux-doc, realpuyuwang, siyanteng01,
junhuahuangdream, cgel.zte, Yanteng Si
Translate Documentation/core-api/kref.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
.../translations/zh_CN/core-api/index.rst | 3 +-
.../translations/zh_CN/core-api/kref.rst | 311 ++++++++++++++++++
2 files changed, 313 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/core-api/kref.rst
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 72f0a36daa1c..8665df464efe 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -39,10 +39,11 @@
:maxdepth: 1
kobject
+ kref
Todolist:
- kref
+
assoc_array
xarray
idr
diff --git a/Documentation/translations/zh_CN/core-api/kref.rst b/Documentation/translations/zh_CN/core-api/kref.rst
new file mode 100644
index 000000000000..b9902af310c5
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/kref.rst
@@ -0,0 +1,311 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/kref.rst
+
+翻译:
+
+司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+校译：
+
+ <此处请校译员签名（自愿），我将在下一个版本添加>
+
+.. _cn_core_api_kref.rst:
+
+=================================
+为内核对象添加引用计数器（krefs）
+=================================
+
+:作者: Corey Minyard <minyard@acm.org>
+:作者: Thomas Hellstrom <thellstrom@vmware.com>
+
+其中很多内容都是从Greg Kroah-Hartman2004年关于krefs的OLS论文和演讲中摘
+录的，可以在以下网址找到:
+
+ - 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/
+
+简介
+====
+
+krefs允许你为你的对象添加引用计数器。如果你有在多个地方使用和传递的对象，
+而你没有refcounts，你的代码几乎肯定是坏的。如果你想要引用计数，krefs是个
+好办法。
+
+要使用kref，请在你的数据结构中添加一个，如::
+
+ struct my_data
+ {
+ .
+ .
+ struct kref refcount;
+ .
+ .
+ };
+
+kref可以出现在数据结构体中的任何地方。
+
+初始化
+======
+
+你必须在分配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，你必须遵循以下规则:
+
+1) 如果你对一个指针做了一个非临时性的拷贝，特别是如果它可以被传递给另一个执
+ 行线程，你必须在传递之前用kref_get()增加refcount::
+
+ kref_get(&data->refcount);
+
+ 如果你已经有了一个指向kref-ed结构体的有效指针（refcount不能为零），你
+ 可以在没有锁的情况下这样做。
+
+2) 当你完成对一个指针的处理时，你必须调用kref_put()::
+
+ kref_put(&data->refcount, data_release);
+
+ 如果这是对该指针的最后一次引用，释放程序将被调用。如果代码从来没有尝试过
+ 在没有已经持有有效指针的情况下获得一个kref-ed结构体的有效指针，那么在没
+ 有锁的情况下这样做是安全的。
+
+3) 如果代码试图获得对一个kref-ed结构体的引用，而不持有一个有效的指针，它必
+ 须按顺序访问，在kref_put()期间不能发生kref_get()，并且该结构体在kref_get()
+ 期间必须保持有效。
+
+例如，如果你分配了一些数据，然后将其传递给另一个线程来处理::
+
+ 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;
+ }
+
+这样，两个线程处理数据的顺序并不重要，kref_put()处理知道数据不再被引用并释
+放它。kref_get()不需要锁，因为我们已经有了一个有效的指针，我们拥有一个
+refcount。put不需要锁，因为没有任何东西试图在没有持有指针的情况下获取数据。
+
+在上面的例子中，kref_put()在成功和错误路径中都会被调用2次。这是必要的，因
+为引用计数被kref_init()和kref_get()递增了2次。
+
+请注意，规则1中的 "before "是非常重要的。你不应该做类似于::
+
+ task = kthread_run(more_data_handling, data, "more_data_handling");
+ if (task == ERR_PTR(-ENOMEM)) {
+ rv = -ENOMEM;
+ goto out;
+ } else
+ /* BAD BAD BAD - 在交接后得到 */
+ kref_get(&data->refcount);
+
+不要以为你知道自己在做什么而使用上述构造。首先，你可能不知道自己在做什么。
+其次，你可能知道自己在做什么（有些情况下涉及到锁，上述做法可能是合法的），
+但其他不知道自己在做什么的人可能会改变代码或复制代码。这是很危险的作风。请
+不要这样做。
+
+在有些情况下，你可以优化get和put。例如，如果你已经完成了一个对象，并且给其
+他对象排队，或者把它传递给其他对象，那么就没有理由先做一个get，然后再做一个
+put::
+
+ /* 糟糕的额外获取(get)和输出(put) */
+ kref_get(&obj->ref);
+ enqueue(obj);
+ kref_put(&obj->ref, obj_cleanup);
+
+只要做enqueue就可以了。 我们随时欢迎对这个问题的评论::
+
+ enqueue(obj);
+ /* 我们已经完成了对obj的处理，所以我们把我们的refcount传给了队列。
+ 在这之后不要再碰obj了! */
+
+最后一条规则（规则3）是最难处理的一条。例如，你有一个每个项目都被krefed的列表，
+而你希望得到第一个项目。你不能只是从列表中抽出第一个项目，然后kref_get()它。
+这违反了规则3，因为你还没有持有一个有效的指针。你必须添加一个mutex（或其他锁）。
+比如说::
+
+ 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()的返回值是有用的。假设你不想在
+上面的例子中在持有锁的情况下调用kfree()（因为这样做有点无意义）。你可以使用kref_put()，
+如下所示::
+
+ static void release_entry(struct kref *ref)
+ {
+ /* 所有的工作都是在从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);
+ }
+
+如果你必须调用其他程序作为释放操作的一部分，而这些程序可能需要很长的时间，或者可
+能要求相同的锁，那么这真的更有用。请注意，在释放例程中做所有的事情还是比较好的，
+因为它比较整洁。
+
+上面的例子也可以用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锁是很有用的，但是重要的是
+kref_get_unless_zero被封装在查找表中的同一关键部分，否则kref_get_unless_zero
+可能引用已经释放的内存。注意，在不检查其返回值的情况下使用kref_get_unless_zero
+是非法的。如果你确信（已经有了一个有效的指针）kref_get_unless_zero()会返回true，
+那么就用kref_get()代替。
+
+Krefs和RCU
+==========
+
+函数kref_get_unless_zero也使得在上述例子中使用rcu锁进行查找成为可能::
+
+ 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后，结构kref成员需要在有效内存中保留一个rcu
+宽限期。这可以通过使用上面的kfree_rcu(entry, rhead)来实现，或者在使用kfree之前
+调用synchronize_rcu()，但注意synchronize_rcu()可能会睡眠相当长的时间。
--
2.27.0
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] docs/zh_CN: add core api kref translation
2021-09-10 6:42 [PATCH] docs/zh_CN: add core api kref translation Yanteng Si
@ 2021-09-20 10:01 ` yanteng si
2021-09-23 3:49 ` Alex Shi
0 siblings, 1 reply; 3+ messages in thread
From: yanteng si @ 2021-09-20 10:01 UTC (permalink / raw)
To: Jonathan Corbet, Alex Shi, Alex Shi
Cc: Huacai Chen, Jiaxun Yang, linux-doc, Puyu Wang, junhuahuangdream,
cgel.zte, Yanteng Si
Yanteng Si <siyanteng01@gmail.com> 于2021年9月10日周五 下午2:44写道：
>
> Translate Documentation/core-api/kref.rst into Chinese.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
> .../translations/zh_CN/core-api/index.rst | 3 +-
> .../translations/zh_CN/core-api/kref.rst | 311 ++++++++++++++++++
> 2 files changed, 313 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/core-api/kref.rst
>
> diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> index 72f0a36daa1c..8665df464efe 100644
> --- a/Documentation/translations/zh_CN/core-api/index.rst
> +++ b/Documentation/translations/zh_CN/core-api/index.rst
> @@ -39,10 +39,11 @@
> :maxdepth: 1
>
> kobject
> + kref
>
> Todolist:
>
> - kref
> +
> assoc_array
> xarray
> idr
> diff --git a/Documentation/translations/zh_CN/core-api/kref.rst b/Documentation/translations/zh_CN/core-api/kref.rst
> new file mode 100644
> index 000000000000..b9902af310c5
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/kref.rst
> @@ -0,0 +1,311 @@
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/core-api/kref.rst
> +
> +翻译:
> +
> +司延腾 Yanteng Si <siyanteng@loongson.cn>
> +
> +校译：
> +
> + <此处请校译员签名（自愿），我将在下一个版本添加>
> +
> +.. _cn_core_api_kref.rst:
> +
> +=================================
> +为内核对象添加引用计数器（krefs）
> +=================================
> +
> +:作者: Corey Minyard <minyard@acm.org>
> +:作者: Thomas Hellstrom <thellstrom@vmware.com>
> +
> +其中很多内容都是从Greg Kroah-Hartman2004年关于krefs的OLS论文和演讲中摘
> +录的，可以在以下网址找到:
> +
> + - 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/
> +
> +简介
> +====
> +
> +krefs允许你为你的对象添加引用计数器。如果你有在多个地方使用和传递的对象，
> +而你没有refcounts，你的代码几乎肯定是坏的。如果你想要引用计数，krefs是个
> +好办法。
> +
> +要使用kref，请在你的数据结构中添加一个，如::
> +
> + struct my_data
> + {
> + .
> + .
> + struct kref refcount;
> + .
> + .
> + };
> +
> +kref可以出现在数据结构体中的任何地方。
> +
> +初始化
> +======
> +
> +你必须在分配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，你必须遵循以下规则:
> +
> +1) 如果你对一个指针做了一个非临时性的拷贝，特别是如果它可以被传递给另一个执
> + 行线程，你必须在传递之前用kref_get()增加refcount::
> +
> + kref_get(&data->refcount);
> +
> + 如果你已经有了一个指向kref-ed结构体的有效指针（refcount不能为零），你
> + 可以在没有锁的情况下这样做。
> +
> +2) 当你完成对一个指针的处理时，你必须调用kref_put()::
> +
> + kref_put(&data->refcount, data_release);
> +
> + 如果这是对该指针的最后一次引用，释放程序将被调用。如果代码从来没有尝试过
> + 在没有已经持有有效指针的情况下获得一个kref-ed结构体的有效指针，那么在没
> + 有锁的情况下这样做是安全的。
> +
> +3) 如果代码试图获得对一个kref-ed结构体的引用，而不持有一个有效的指针，它必
> + 须按顺序访问，在kref_put()期间不能发生kref_get()，并且该结构体在kref_get()
> + 期间必须保持有效。
> +
> +例如，如果你分配了一些数据，然后将其传递给另一个线程来处理::
> +
> + 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;
> + }
> +
> +这样，两个线程处理数据的顺序并不重要，kref_put()处理知道数据不再被引用并释
> +放它。kref_get()不需要锁，因为我们已经有了一个有效的指针，我们拥有一个
> +refcount。put不需要锁，因为没有任何东西试图在没有持有指针的情况下获取数据。
> +
> +在上面的例子中，kref_put()在成功和错误路径中都会被调用2次。这是必要的，因
> +为引用计数被kref_init()和kref_get()递增了2次。
> +
> +请注意，规则1中的 "before "是非常重要的。你不应该做类似于::
> +
> + task = kthread_run(more_data_handling, data, "more_data_handling");
> + if (task == ERR_PTR(-ENOMEM)) {
> + rv = -ENOMEM;
> + goto out;
> + } else
> + /* BAD BAD BAD - 在交接后得到 */
> + kref_get(&data->refcount);
> +
> +不要以为你知道自己在做什么而使用上述构造。首先，你可能不知道自己在做什么。
> +其次，你可能知道自己在做什么（有些情况下涉及到锁，上述做法可能是合法的），
> +但其他不知道自己在做什么的人可能会改变代码或复制代码。这是很危险的作风。请
> +不要这样做。
> +
> +在有些情况下，你可以优化get和put。例如，如果你已经完成了一个对象，并且给其
> +他对象排队，或者把它传递给其他对象，那么就没有理由先做一个get，然后再做一个
> +put::
> +
> + /* 糟糕的额外获取(get)和输出(put) */
> + kref_get(&obj->ref);
> + enqueue(obj);
> + kref_put(&obj->ref, obj_cleanup);
> +
> +只要做enqueue就可以了。 我们随时欢迎对这个问题的评论::
> +
> + enqueue(obj);
> + /* 我们已经完成了对obj的处理，所以我们把我们的refcount传给了队列。
> + 在这之后不要再碰obj了! */
> +
> +最后一条规则（规则3）是最难处理的一条。例如，你有一个每个项目都被krefed的列表，
> +而你希望得到第一个项目。你不能只是从列表中抽出第一个项目，然后kref_get()它。
> +这违反了规则3，因为你还没有持有一个有效的指针。你必须添加一个mutex（或其他锁）。
> +比如说::
> +
> + 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()的返回值是有用的。假设你不想在
> +上面的例子中在持有锁的情况下调用kfree()（因为这样做有点无意义）。你可以使用kref_put()，
> +如下所示::
> +
> + static void release_entry(struct kref *ref)
> + {
> + /* 所有的工作都是在从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);
> + }
> +
> +如果你必须调用其他程序作为释放操作的一部分，而这些程序可能需要很长的时间，或者可
> +能要求相同的锁，那么这真的更有用。请注意，在释放例程中做所有的事情还是比较好的，
> +因为它比较整洁。
> +
> +上面的例子也可以用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锁是很有用的，但是重要的是
> +kref_get_unless_zero被封装在查找表中的同一关键部分，否则kref_get_unless_zero
> +可能引用已经释放的内存。注意，在不检查其返回值的情况下使用kref_get_unless_zero
> +是非法的。如果你确信（已经有了一个有效的指针）kref_get_unless_zero()会返回true，
> +那么就用kref_get()代替。
> +
> +Krefs和RCU
> +==========
> +
> +函数kref_get_unless_zero也使得在上述例子中使用rcu锁进行查找成为可能::
> +
> + 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后，结构kref成员需要在有效内存中保留一个rcu
> +宽限期。这可以通过使用上面的kfree_rcu(entry, rhead)来实现，或者在使用kfree之前
> +调用synchronize_rcu()，但注意synchronize_rcu()可能会睡眠相当长的时间。
> --
> 2.27.0
>
CC Yang
Hi Yang and Junhua
As alex suggested, we can review each other. :)
Thanks,
Yanteng
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] docs/zh_CN: add core api kref translation
2021-09-20 10:01 ` yanteng si
@ 2021-09-23 3:49 ` Alex Shi
0 siblings, 0 replies; 3+ messages in thread
From: Alex Shi @ 2021-09-23 3:49 UTC (permalink / raw)
To: yanteng si
Cc: Jonathan Corbet, Alex Shi, Huacai Chen, Jiaxun Yang, linux-doc,
Puyu Wang, junhuahuangdream, cgel.zte, Yanteng Si
On Mon, Sep 20, 2021 at 6:01 PM yanteng si <siyanteng01@gmail.com> wrote:
>
> Yanteng Si <siyanteng01@gmail.com> 于2021年9月10日周五 下午2:44写道：
> >
> > Translate Documentation/core-api/kref.rst into Chinese.
> >
looks good for me.
Reviewed-by: Alex Shi <alexs@kernel.org>
> > Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > ---
> > .../translations/zh_CN/core-api/index.rst | 3 +-
> > .../translations/zh_CN/core-api/kref.rst | 311 ++++++++++++++++++
> > 2 files changed, 313 insertions(+), 1 deletion(-)
> > create mode 100644 Documentation/translations/zh_CN/core-api/kref.rst
> >
> > diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> > index 72f0a36daa1c..8665df464efe 100644
> > --- a/Documentation/translations/zh_CN/core-api/index.rst
> > +++ b/Documentation/translations/zh_CN/core-api/index.rst
> > @@ -39,10 +39,11 @@
> > :maxdepth: 1
> >
> > kobject
> > + kref
> >
> > Todolist:
> >
> > - kref
> > +
> > assoc_array
> > xarray
> > idr
> > diff --git a/Documentation/translations/zh_CN/core-api/kref.rst b/Documentation/translations/zh_CN/core-api/kref.rst
> > new file mode 100644
> > index 000000000000..b9902af310c5
> > --- /dev/null
> > +++ b/Documentation/translations/zh_CN/core-api/kref.rst
> > @@ -0,0 +1,311 @@
> > +.. include:: ../disclaimer-zh_CN.rst
> > +
> > +:Original: Documentation/core-api/kref.rst
> > +
> > +翻译:
> > +
> > +司延腾 Yanteng Si <siyanteng@loongson.cn>
> > +
> > +校译：
> > +
> > + <此处请校译员签名（自愿），我将在下一个版本添加>
> > +
> > +.. _cn_core_api_kref.rst:
> > +
> > +=================================
> > +为内核对象添加引用计数器（krefs）
> > +=================================
> > +
> > +:作者: Corey Minyard <minyard@acm.org>
> > +:作者: Thomas Hellstrom <thellstrom@vmware.com>
> > +
> > +其中很多内容都是从Greg Kroah-Hartman2004年关于krefs的OLS论文和演讲中摘
> > +录的，可以在以下网址找到:
> > +
> > + - 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/
> > +
> > +简介
> > +====
> > +
> > +krefs允许你为你的对象添加引用计数器。如果你有在多个地方使用和传递的对象，
> > +而你没有refcounts，你的代码几乎肯定是坏的。如果你想要引用计数，krefs是个
> > +好办法。
> > +
> > +要使用kref，请在你的数据结构中添加一个，如::
> > +
> > + struct my_data
> > + {
> > + .
> > + .
> > + struct kref refcount;
> > + .
> > + .
> > + };
> > +
> > +kref可以出现在数据结构体中的任何地方。
> > +
> > +初始化
> > +======
> > +
> > +你必须在分配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，你必须遵循以下规则:
> > +
> > +1) 如果你对一个指针做了一个非临时性的拷贝，特别是如果它可以被传递给另一个执
> > + 行线程，你必须在传递之前用kref_get()增加refcount::
> > +
> > + kref_get(&data->refcount);
> > +
> > + 如果你已经有了一个指向kref-ed结构体的有效指针（refcount不能为零），你
> > + 可以在没有锁的情况下这样做。
> > +
> > +2) 当你完成对一个指针的处理时，你必须调用kref_put()::
> > +
> > + kref_put(&data->refcount, data_release);
> > +
> > + 如果这是对该指针的最后一次引用，释放程序将被调用。如果代码从来没有尝试过
> > + 在没有已经持有有效指针的情况下获得一个kref-ed结构体的有效指针，那么在没
> > + 有锁的情况下这样做是安全的。
> > +
> > +3) 如果代码试图获得对一个kref-ed结构体的引用，而不持有一个有效的指针，它必
> > + 须按顺序访问，在kref_put()期间不能发生kref_get()，并且该结构体在kref_get()
> > + 期间必须保持有效。
> > +
> > +例如，如果你分配了一些数据，然后将其传递给另一个线程来处理::
> > +
> > + 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;
> > + }
> > +
> > +这样，两个线程处理数据的顺序并不重要，kref_put()处理知道数据不再被引用并释
> > +放它。kref_get()不需要锁，因为我们已经有了一个有效的指针，我们拥有一个
> > +refcount。put不需要锁，因为没有任何东西试图在没有持有指针的情况下获取数据。
> > +
> > +在上面的例子中，kref_put()在成功和错误路径中都会被调用2次。这是必要的，因
> > +为引用计数被kref_init()和kref_get()递增了2次。
> > +
> > +请注意，规则1中的 "before "是非常重要的。你不应该做类似于::
> > +
> > + task = kthread_run(more_data_handling, data, "more_data_handling");
> > + if (task == ERR_PTR(-ENOMEM)) {
> > + rv = -ENOMEM;
> > + goto out;
> > + } else
> > + /* BAD BAD BAD - 在交接后得到 */
> > + kref_get(&data->refcount);
> > +
> > +不要以为你知道自己在做什么而使用上述构造。首先，你可能不知道自己在做什么。
> > +其次，你可能知道自己在做什么（有些情况下涉及到锁，上述做法可能是合法的），
> > +但其他不知道自己在做什么的人可能会改变代码或复制代码。这是很危险的作风。请
> > +不要这样做。
> > +
> > +在有些情况下，你可以优化get和put。例如，如果你已经完成了一个对象，并且给其
> > +他对象排队，或者把它传递给其他对象，那么就没有理由先做一个get，然后再做一个
> > +put::
> > +
> > + /* 糟糕的额外获取(get)和输出(put) */
> > + kref_get(&obj->ref);
> > + enqueue(obj);
> > + kref_put(&obj->ref, obj_cleanup);
> > +
> > +只要做enqueue就可以了。 我们随时欢迎对这个问题的评论::
> > +
> > + enqueue(obj);
> > + /* 我们已经完成了对obj的处理，所以我们把我们的refcount传给了队列。
> > + 在这之后不要再碰obj了! */
> > +
> > +最后一条规则（规则3）是最难处理的一条。例如，你有一个每个项目都被krefed的列表，
> > +而你希望得到第一个项目。你不能只是从列表中抽出第一个项目，然后kref_get()它。
> > +这违反了规则3，因为你还没有持有一个有效的指针。你必须添加一个mutex（或其他锁）。
> > +比如说::
> > +
> > + 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()的返回值是有用的。假设你不想在
> > +上面的例子中在持有锁的情况下调用kfree()（因为这样做有点无意义）。你可以使用kref_put()，
> > +如下所示::
> > +
> > + static void release_entry(struct kref *ref)
> > + {
> > + /* 所有的工作都是在从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);
> > + }
> > +
> > +如果你必须调用其他程序作为释放操作的一部分，而这些程序可能需要很长的时间，或者可
> > +能要求相同的锁，那么这真的更有用。请注意，在释放例程中做所有的事情还是比较好的，
> > +因为它比较整洁。
> > +
> > +上面的例子也可以用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锁是很有用的，但是重要的是
> > +kref_get_unless_zero被封装在查找表中的同一关键部分，否则kref_get_unless_zero
> > +可能引用已经释放的内存。注意，在不检查其返回值的情况下使用kref_get_unless_zero
> > +是非法的。如果你确信（已经有了一个有效的指针）kref_get_unless_zero()会返回true，
> > +那么就用kref_get()代替。
> > +
> > +Krefs和RCU
> > +==========
> > +
> > +函数kref_get_unless_zero也使得在上述例子中使用rcu锁进行查找成为可能::
> > +
> > + 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后，结构kref成员需要在有效内存中保留一个rcu
> > +宽限期。这可以通过使用上面的kfree_rcu(entry, rhead)来实现，或者在使用kfree之前
> > +调用synchronize_rcu()，但注意synchronize_rcu()可能会睡眠相当长的时间。
> > --
> > 2.27.0
> >
>
> CC Yang
>
> Hi Yang and Junhua
>
> As alex suggested, we can review each other. :)
>
> Thanks,
>
> Yanteng
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2021-09-23 3:50 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-09-10 6:42 [PATCH] docs/zh_CN: add core api kref translation Yanteng Si
2021-09-20 10:01 ` yanteng si
2021-09-23 3:49 ` Alex Shi
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.