[PATCH v3 4/4] Documentation/workqueue.txt: convert to ReST markup
... and move to Documentation/core-api folder. Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com> --- Documentation/core-api/index.rst | 2 +- Documentation/core-api/workqueue.rst | 394 - Documentation/index.rst | 1 +- Documentation/workqueue.txt | 388 + MAINTAINERS | 2 +- include/linux/workqueue.h| 5 +- 6 files changed, 401 insertions(+), 391 deletions(-) create mode 100644 Documentation/core-api/workqueue.rst delete mode 100644 Documentation/workqueue.txt diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index ed3eb64..f7ef7fd 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -7,6 +7,8 @@ Kernel and driver related documentation. .. toctree:: :maxdepth: 1 + workqueue + .. only:: subproject Indices diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst new file mode 100644 index 000..ffdec94 --- /dev/null +++ b/Documentation/core-api/workqueue.rst @@ -0,0 +1,394 @@ + +Concurrency Managed Workqueue (cmwq) + + +:Date: September, 2010 +:Author: Tejun Heo <t...@kernel.org> +:Author: Florian Mickler <flor...@mickler.org> + + +Introduction + + +There are many cases where an asynchronous process execution context +is needed and the workqueue (wq) API is the most commonly used +mechanism for such cases. + +When such an asynchronous execution context is needed, a work item +describing which function to execute is put on a queue. An +independent thread serves as the asynchronous execution context. The +queue is called workqueue and the thread is called worker. + +While there are work items on the workqueue the worker executes the +functions associated with the work items one after the other. When +there is no work item left on the workqueue the worker becomes idle. +When a new work item gets queued, the worker begins executing again. + + +Why cmwq? += + +In the original wq implementation, a multi threaded (MT) wq had one +worker thread per CPU and a single threaded (ST) wq had one worker +thread system-wide. A single MT wq needed to keep around the same +number of workers as the number of CPUs. The kernel grew a lot of MT +wq users over the years and with the number of CPU cores continuously +rising, some systems saturated the default 32k PID space just booting +up. + +Although MT wq wasted a lot of resource, the level of concurrency +provided was unsatisfactory. The limitation was common to both ST and +MT wq albeit less severe on MT. Each wq maintained its own separate +worker pool. A MT wq could provide only one execution context per CPU +while a ST wq one for the whole system. Work items had to compete for +those very limited execution contexts leading to various problems +including proneness to deadlocks around the single execution context. + +The tension between the provided level of concurrency and resource +usage also forced its users to make unnecessary tradeoffs like libata +choosing to use ST wq for polling PIOs and accepting an unnecessary +limitation that no two polling PIOs can progress at the same time. As +MT wq don't provide much better concurrency, users which require +higher level of concurrency, like async or fscache, had to implement +their own thread pool. + +Concurrency Managed Workqueue (cmwq) is a reimplementation of wq with +focus on the following goals. + +* Maintain compatibility with the original workqueue API. + +* Use per-CPU unified worker pools shared by all wq to provide + flexible level of concurrency on demand without wasting a lot of + resource. + +* Automatically regulate worker pool and level of concurrency so that + the API users don't need to worry about such details. + + +The Design +== + +In order to ease the asynchronous execution of functions a new +abstraction, the work item, is introduced. + +A work item is a simple struct that holds a pointer to the function +that is to be executed asynchronously. Whenever a driver or subsystem +wants a function to be executed asynchronously it has to set up a work +item pointing to that function and queue that work item on a +workqueue. + +Special purpose threads, called worker threads, execute the functions +off of the queue, one after the other. If no work is queued, the +worker threads become idle. These worker threads are managed in so +called worker-pools. + +The cmwq design differentiates between the user-facing workqueues that +subsystems and drivers queue work items on and the backend mechanism +which manages worker-pools and processes the queued work items. + +There are two worker-pools, one for normal work items and the other +for high priority ones, for each possible CPU and some extra +worker-pools to serve work items queued on
[PATCH v3 3/4] Documentation/00-index: update for new core-api folder
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
Documentation/00-INDEX | 4 +++-
Documentation/core-api/conf.py | 5 +
Documentation/core-api/index.rst | 15 +++
Documentation/index.rst | 1 +
4 files changed, 24 insertions(+), 1 deletion(-)
create mode 100644 Documentation/core-api/conf.py
create mode 100644 Documentation/core-api/index.rst
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3acc4f1..6479b83 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -126,6 +126,8 @@ connector/
- docs on the netlink based userspace<->kernel space communication mod.
console/
- documentation on Linux console drivers.
+core-api/
+ - documentation on kernel core components.
cpu-freq/
- info on CPU frequency and voltage scaling.
cpu-hotplug.txt
@@ -474,7 +476,7 @@ watchdog/
- how to auto-reboot Linux if it has "fallen and can't get up". ;-)
wimax/
- directory with info about Intel Wireless Wimax Connections
-workqueue.txt
+core-api/workqueue.rst
- information on the Concurrency Managed Workqueue implementation
x86/x86_64/
- directory with info on Linux support for AMD x86-64 (Hammer) machines.
diff --git a/Documentation/core-api/conf.py b/Documentation/core-api/conf.py
new file mode 100644
index 000..fed87ab
--- /dev/null
+++ b/Documentation/core-api/conf.py
@@ -0,0 +1,5 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Core-API Documentation"
+
+tags.add("subproject")
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
new file mode 100644
index 000..ed3eb64
--- /dev/null
+++ b/Documentation/core-api/index.rst
@@ -0,0 +1,15 @@
+==
+Core-API Documentation
+==
+
+Kernel and driver related documentation.
+
+.. toctree::
+ :maxdepth: 1
+
+.. only:: subproject
+
+ Indices
+ ===
+
+ * :ref:`genindex`
diff --git a/Documentation/index.rst b/Documentation/index.rst
index c53d089..28a1ff6 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -15,6 +15,7 @@ Contents:
development-process/index
dev-tools/tools
driver-api/index
+ core-api/index
media/index
gpu/index
80211/index
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 2/4] workqueue: kerneldocify workqueue_attrs
Only formating changes.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
include/linux/workqueue.h | 30 +-
1 file changed, 21 insertions(+), 9 deletions(-)
diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h
index fc6e221..afc1d46 100644
--- a/include/linux/workqueue.h
+++ b/include/linux/workqueue.h
@@ -119,18 +119,30 @@ struct delayed_work {
int cpu;
};
-/*
- * A struct for workqueue attributes. This can be used to change
- * attributes of an unbound workqueue.
+/**
+ * struct workqueue_attrs - A struct for workqueue attributes.
*
- * Unlike other fields, ->no_numa isn't a property of a worker_pool. It
- * only modifies how apply_workqueue_attrs() select pools and thus doesn't
- * participate in pool hash calculations or equality comparisons.
+ * This can be used to change attributes of an unbound workqueue.
*/
struct workqueue_attrs {
- int nice; /* nice level */
- cpumask_var_t cpumask;/* allowed CPUs */
- boolno_numa;/* disable NUMA affinity */
+ /**
+* @nice: nice level
+*/
+ int nice;
+
+ /**
+* @cpumask: allowed CPUs
+*/
+ cpumask_var_t cpumask;
+
+ /**
+* @no_numa: disable NUMA affinity
+*
+* Unlike other fields, ``no_numa`` isn't a property of a worker_pool.
It
+* only modifies how :c:func:`apply_workqueue_attrs` select pools and
thus
+* doesn't participate in pool hash calculations or equality
comparisons.
+*/
+ bool no_numa;
};
static inline struct delayed_work *to_delayed_work(struct work_struct *work)
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 0/4] workqueue documentation reformatted
Hi, v2 -> v3: * Introduce a core-api folder * move workqueue.rst to core-api * reflect change in 00-index and workqueue.h v1 -> v2: * s/kernel-doc: $type_param takes care that this parameter is used for formatting too. * i/l/workqueue.h: inlining of documentation for workqueue_attrs struct members * D/workqueue.rst: Every author get a own :AUTHOR:-label * D/index.rst: add misc section and add link to workqueue documentation Best regards Silvio Silvio Fricke (4): kernel-doc: better parsing of named variable arguments workqueue: kerneldocify workqueue_attrs Documentation/00-index: update for new core-api folder Documentation/workqueue.txt: convert to ReST markup Documentation/00-INDEX | 4 +- Documentation/core-api/conf.py | 5 +- Documentation/core-api/index.rst | 17 +- Documentation/core-api/workqueue.rst | 394 - Documentation/index.rst | 2 +- Documentation/workqueue.txt | 388 + MAINTAINERS | 2 +- include/linux/workqueue.h| 35 +- scripts/kernel-doc | 8 +- 9 files changed, 452 insertions(+), 403 deletions(-) create mode 100644 Documentation/core-api/conf.py create mode 100644 Documentation/core-api/index.rst create mode 100644 Documentation/core-api/workqueue.rst delete mode 100644 Documentation/workqueue.txt base-commit: 07d9a380680d1c0eb51ef87ff2eab5c994949e69 -- git-series 0.8.10 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 1/4] kernel-doc: better parsing of named variable arguments
Without this patch we get warnings for named variable arguments.
warning: No description found for parameter '...'
warning: Excess function parameter 'args' description in
'alloc_ordered_workqueue'
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
Reviewed-by: Jani Nikula <jani.nik...@intel.com
---
scripts/kernel-doc | 8 ++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 93721f3..e10378f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -204,6 +204,7 @@ EOF
## init lots of data
+
my $errors = 0;
my $warnings = 0;
my $anon_struct_union = 0;
@@ -211,7 +212,7 @@ my $anon_struct_union = 0;
# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w+)';
+my $type_param = '\@(\w+(\.\.\.)?)';
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\((struct\s*)*[_\w]+)';
@@ -2353,7 +2354,10 @@ sub push_parameter($$$) {
if ($type eq "" && $param =~ /\.\.\.$/)
{
- $param = "...";
+ if (!$param =~ /\w\.\.\.$/) {
+ # handles unnamed variable parameters
+ $param = "...";
+ }
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq
"") {
$parameterdescs{$param} = "variable arguments";
}
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v4 4/4] Documentation/workqueue.txt: convert to ReST markup
... and move to Documentation/core-api folder. Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com> --- Documentation/core-api/index.rst | 2 +- Documentation/core-api/workqueue.rst | 394 - Documentation/workqueue.txt | 388 + MAINTAINERS | 2 +- include/linux/workqueue.h| 5 +- 5 files changed, 400 insertions(+), 391 deletions(-) create mode 100644 Documentation/core-api/workqueue.rst delete mode 100644 Documentation/workqueue.txt diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index ed3eb64..f7ef7fd 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -7,6 +7,8 @@ Kernel and driver related documentation. .. toctree:: :maxdepth: 1 + workqueue + .. only:: subproject Indices diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst new file mode 100644 index 000..ffdec94 --- /dev/null +++ b/Documentation/core-api/workqueue.rst @@ -0,0 +1,394 @@ + +Concurrency Managed Workqueue (cmwq) + + +:Date: September, 2010 +:Author: Tejun Heo <t...@kernel.org> +:Author: Florian Mickler <flor...@mickler.org> + + +Introduction + + +There are many cases where an asynchronous process execution context +is needed and the workqueue (wq) API is the most commonly used +mechanism for such cases. + +When such an asynchronous execution context is needed, a work item +describing which function to execute is put on a queue. An +independent thread serves as the asynchronous execution context. The +queue is called workqueue and the thread is called worker. + +While there are work items on the workqueue the worker executes the +functions associated with the work items one after the other. When +there is no work item left on the workqueue the worker becomes idle. +When a new work item gets queued, the worker begins executing again. + + +Why cmwq? += + +In the original wq implementation, a multi threaded (MT) wq had one +worker thread per CPU and a single threaded (ST) wq had one worker +thread system-wide. A single MT wq needed to keep around the same +number of workers as the number of CPUs. The kernel grew a lot of MT +wq users over the years and with the number of CPU cores continuously +rising, some systems saturated the default 32k PID space just booting +up. + +Although MT wq wasted a lot of resource, the level of concurrency +provided was unsatisfactory. The limitation was common to both ST and +MT wq albeit less severe on MT. Each wq maintained its own separate +worker pool. A MT wq could provide only one execution context per CPU +while a ST wq one for the whole system. Work items had to compete for +those very limited execution contexts leading to various problems +including proneness to deadlocks around the single execution context. + +The tension between the provided level of concurrency and resource +usage also forced its users to make unnecessary tradeoffs like libata +choosing to use ST wq for polling PIOs and accepting an unnecessary +limitation that no two polling PIOs can progress at the same time. As +MT wq don't provide much better concurrency, users which require +higher level of concurrency, like async or fscache, had to implement +their own thread pool. + +Concurrency Managed Workqueue (cmwq) is a reimplementation of wq with +focus on the following goals. + +* Maintain compatibility with the original workqueue API. + +* Use per-CPU unified worker pools shared by all wq to provide + flexible level of concurrency on demand without wasting a lot of + resource. + +* Automatically regulate worker pool and level of concurrency so that + the API users don't need to worry about such details. + + +The Design +== + +In order to ease the asynchronous execution of functions a new +abstraction, the work item, is introduced. + +A work item is a simple struct that holds a pointer to the function +that is to be executed asynchronously. Whenever a driver or subsystem +wants a function to be executed asynchronously it has to set up a work +item pointing to that function and queue that work item on a +workqueue. + +Special purpose threads, called worker threads, execute the functions +off of the queue, one after the other. If no work is queued, the +worker threads become idle. These worker threads are managed in so +called worker-pools. + +The cmwq design differentiates between the user-facing workqueues that +subsystems and drivers queue work items on and the backend mechanism +which manages worker-pools and processes the queued work items. + +There are two worker-pools, one for normal work items and the other +for high priority ones, for each possible CPU and some extra +worker-pools to serve work items queued on unbound workqueues - the +number of these backin
[PATCH v4 3/4] Documentation/00-index: update for new core-api folder
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
Documentation/00-INDEX | 4 +++-
Documentation/core-api/conf.py | 5 +
Documentation/core-api/index.rst | 15 +++
Documentation/index.rst | 1 +
4 files changed, 24 insertions(+), 1 deletion(-)
create mode 100644 Documentation/core-api/conf.py
create mode 100644 Documentation/core-api/index.rst
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3acc4f1..6479b83 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -126,6 +126,8 @@ connector/
- docs on the netlink based userspace<->kernel space communication mod.
console/
- documentation on Linux console drivers.
+core-api/
+ - documentation on kernel core components.
cpu-freq/
- info on CPU frequency and voltage scaling.
cpu-hotplug.txt
@@ -474,7 +476,7 @@ watchdog/
- how to auto-reboot Linux if it has "fallen and can't get up". ;-)
wimax/
- directory with info about Intel Wireless Wimax Connections
-workqueue.txt
+core-api/workqueue.rst
- information on the Concurrency Managed Workqueue implementation
x86/x86_64/
- directory with info on Linux support for AMD x86-64 (Hammer) machines.
diff --git a/Documentation/core-api/conf.py b/Documentation/core-api/conf.py
new file mode 100644
index 000..fed87ab
--- /dev/null
+++ b/Documentation/core-api/conf.py
@@ -0,0 +1,5 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Core-API Documentation"
+
+tags.add("subproject")
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
new file mode 100644
index 000..ed3eb64
--- /dev/null
+++ b/Documentation/core-api/index.rst
@@ -0,0 +1,15 @@
+==
+Core-API Documentation
+==
+
+Kernel and driver related documentation.
+
+.. toctree::
+ :maxdepth: 1
+
+.. only:: subproject
+
+ Indices
+ ===
+
+ * :ref:`genindex`
diff --git a/Documentation/index.rst b/Documentation/index.rst
index c53d089..28a1ff6 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -15,6 +15,7 @@ Contents:
development-process/index
dev-tools/tools
driver-api/index
+ core-api/index
media/index
gpu/index
80211/index
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v4 0/4] workqueue documentation reformatted
Hi, v3 -> v4: * The outdated misc reference in D/index.rst was not removed v2 -> v3: * Introduce a core-api folder * move workqueue.rst to core-api * reflect change in 00-index and workqueue.h v1 -> v2: * s/kernel-doc: $type_param takes care that this parameter is used for formatting too. * i/l/workqueue.h: inlining of documentation for workqueue_attrs struct members * D/workqueue.rst: Every author get a own :AUTHOR:-label * D/index.rst: add misc section and add link to workqueue documentation Best regards Silvio Silvio Fricke (4): kernel-doc: better parsing of named variable arguments workqueue: kerneldocify workqueue_attrs Documentation/00-index: update for new core-api folder Documentation/workqueue.txt: convert to ReST markup Documentation/00-INDEX | 4 +- Documentation/core-api/conf.py | 5 +- Documentation/core-api/index.rst | 17 +- Documentation/core-api/workqueue.rst | 394 - Documentation/index.rst | 1 +- Documentation/workqueue.txt | 388 + MAINTAINERS | 2 +- include/linux/workqueue.h| 35 +- scripts/kernel-doc | 8 +- 9 files changed, 451 insertions(+), 403 deletions(-) create mode 100644 Documentation/core-api/conf.py create mode 100644 Documentation/core-api/index.rst create mode 100644 Documentation/core-api/workqueue.rst delete mode 100644 Documentation/workqueue.txt base-commit: 07d9a380680d1c0eb51ef87ff2eab5c994949e69 -- git-series 0.8.10 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v4 2/4] workqueue: kerneldocify workqueue_attrs
Only formating changes.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
include/linux/workqueue.h | 30 +-
1 file changed, 21 insertions(+), 9 deletions(-)
diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h
index fc6e221..afc1d46 100644
--- a/include/linux/workqueue.h
+++ b/include/linux/workqueue.h
@@ -119,18 +119,30 @@ struct delayed_work {
int cpu;
};
-/*
- * A struct for workqueue attributes. This can be used to change
- * attributes of an unbound workqueue.
+/**
+ * struct workqueue_attrs - A struct for workqueue attributes.
*
- * Unlike other fields, ->no_numa isn't a property of a worker_pool. It
- * only modifies how apply_workqueue_attrs() select pools and thus doesn't
- * participate in pool hash calculations or equality comparisons.
+ * This can be used to change attributes of an unbound workqueue.
*/
struct workqueue_attrs {
- int nice; /* nice level */
- cpumask_var_t cpumask;/* allowed CPUs */
- boolno_numa;/* disable NUMA affinity */
+ /**
+* @nice: nice level
+*/
+ int nice;
+
+ /**
+* @cpumask: allowed CPUs
+*/
+ cpumask_var_t cpumask;
+
+ /**
+* @no_numa: disable NUMA affinity
+*
+* Unlike other fields, ``no_numa`` isn't a property of a worker_pool.
It
+* only modifies how :c:func:`apply_workqueue_attrs` select pools and
thus
+* doesn't participate in pool hash calculations or equality
comparisons.
+*/
+ bool no_numa;
};
static inline struct delayed_work *to_delayed_work(struct work_struct *work)
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v4 1/4] kernel-doc: better parsing of named variable arguments
Without this patch we get warnings for named variable arguments.
warning: No description found for parameter '...'
warning: Excess function parameter 'args' description in
'alloc_ordered_workqueue'
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
Reviewed-by: Jani Nikula <jani.nik...@intel.com
---
scripts/kernel-doc | 8 ++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 93721f3..e10378f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -204,6 +204,7 @@ EOF
## init lots of data
+
my $errors = 0;
my $warnings = 0;
my $anon_struct_union = 0;
@@ -211,7 +212,7 @@ my $anon_struct_union = 0;
# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w+)';
+my $type_param = '\@(\w+(\.\.\.)?)';
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\((struct\s*)*[_\w]+)';
@@ -2353,7 +2354,10 @@ sub push_parameter($$$) {
if ($type eq "" && $param =~ /\.\.\.$/)
{
- $param = "...";
+ if (!$param =~ /\w\.\.\.$/) {
+ # handles unnamed variable parameters
+ $param = "...";
+ }
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq
"") {
$parameterdescs{$param} = "variable arguments";
}
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 2/3] workqueue: kerneldocify workqueue_attrs
Only formating changes.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
include/linux/workqueue.h | 30 +-
1 file changed, 21 insertions(+), 9 deletions(-)
diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h
index fc6e221..afc1d46 100644
--- a/include/linux/workqueue.h
+++ b/include/linux/workqueue.h
@@ -119,18 +119,30 @@ struct delayed_work {
int cpu;
};
-/*
- * A struct for workqueue attributes. This can be used to change
- * attributes of an unbound workqueue.
+/**
+ * struct workqueue_attrs - A struct for workqueue attributes.
*
- * Unlike other fields, ->no_numa isn't a property of a worker_pool. It
- * only modifies how apply_workqueue_attrs() select pools and thus doesn't
- * participate in pool hash calculations or equality comparisons.
+ * This can be used to change attributes of an unbound workqueue.
*/
struct workqueue_attrs {
- int nice; /* nice level */
- cpumask_var_t cpumask;/* allowed CPUs */
- boolno_numa;/* disable NUMA affinity */
+ /**
+* @nice: nice level
+*/
+ int nice;
+
+ /**
+* @cpumask: allowed CPUs
+*/
+ cpumask_var_t cpumask;
+
+ /**
+* @no_numa: disable NUMA affinity
+*
+* Unlike other fields, ``no_numa`` isn't a property of a worker_pool.
It
+* only modifies how :c:func:`apply_workqueue_attrs` select pools and
thus
+* doesn't participate in pool hash calculations or equality
comparisons.
+*/
+ bool no_numa;
};
static inline struct delayed_work *to_delayed_work(struct work_struct *work)
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 0/3] workqueue documentation reformatted
Hi, Thanks Jani for reviewing of my first attempt. v1 -> v2: * s/kernel-doc: $type_param takes care that this parameter is used for formatting too. * i/l/workqueue.h: inlining of documentation for workqueue_attrs struct members * D/workqueue.rst: Every author get a own :AUTHOR:-label * D/index.rst: add misc section and add link to workqueue documentation Best regards Silvio Silvio Fricke (3): kernel-doc: better parsing of named variable arguments workqueue: kerneldocify workqueue_attrs Documentation/workqueue.txt: convert to ReST markup Documentation/index.rst | 1 +- Documentation/misc/conf.py | 5 +- Documentation/misc/index.rst | 17 ++- Documentation/workqueue.rst | 394 - Documentation/workqueue.txt | 388 +--- MAINTAINERS | 2 +- include/linux/workqueue.h| 34 ++- scripts/kernel-doc | 8 +- 8 files changed, 447 insertions(+), 402 deletions(-) create mode 100644 Documentation/misc/conf.py create mode 100644 Documentation/misc/index.rst create mode 100644 Documentation/workqueue.rst delete mode 100644 Documentation/workqueue.txt base-commit: 893e2c5c9fedeccf89653b0ad17df69e88dbd707 -- git-series 0.8.10 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 1/3] kernel-doc: better parsing of named variable arguments
Without this patch we get warnings for named variable arguments.
warning: No description found for parameter '...'
warning: Excess function parameter 'args' description in
'alloc_ordered_workqueue'
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
scripts/kernel-doc | 8 ++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 93721f3..e10378f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -204,6 +204,7 @@ EOF
## init lots of data
+
my $errors = 0;
my $warnings = 0;
my $anon_struct_union = 0;
@@ -211,7 +212,7 @@ my $anon_struct_union = 0;
# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w+)';
+my $type_param = '\@(\w+(\.\.\.)?)';
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\((struct\s*)*[_\w]+)';
@@ -2353,7 +2354,10 @@ sub push_parameter($$$) {
if ($type eq "" && $param =~ /\.\.\.$/)
{
- $param = "...";
+ if (!$param =~ /\w\.\.\.$/) {
+ # handles unnamed variable parameters
+ $param = "...";
+ }
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq
"") {
$parameterdescs{$param} = "variable arguments";
}
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 4/4] firmware: remove warning at documentation generation time
This patch removes following error at for `make htmldocs`. No functional change. ./drivers/base/firmware_class.c:1348: WARNING: Bullet list ends without a blank line; unexpected unindent. Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com> --- drivers/base/firmware_class.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/drivers/base/firmware_class.c b/drivers/base/firmware_class.c index 22d1760..37b0221 100644 --- a/drivers/base/firmware_class.c +++ b/drivers/base/firmware_class.c @@ -1345,9 +1345,9 @@ static void request_firmware_work_func(struct work_struct *work) * * Asynchronous variant of request_firmware() for user contexts: * - sleep for as small periods as possible since it may - * increase kernel boot time of built-in device drivers - * requesting firmware in their ->probe() methods, if - * @gfp is GFP_KERNEL. + * increase kernel boot time of built-in device drivers + * requesting firmware in their ->probe() methods, if + * @gfp is GFP_KERNEL. * * - can't sleep at all if @gfp is GFP_ATOMIC. **/ -- git-series 0.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup
... and move to core-api folder.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
Documentation/atomic_ops.txt => Documentation/core-api/atomic_ops.rst | 777
+---
Documentation/core-api/index.rst | 1 +-
Documentation/process/volatile-considered-harmful.rst | 3 +-
3 files changed, 404 insertions(+), 377 deletions(-)
diff --git a/Documentation/atomic_ops.txt
b/Documentation/core-api/atomic_ops.rst
similarity index 46%
rename from Documentation/atomic_ops.txt
rename to Documentation/core-api/atomic_ops.rst
index 6c5e8a9..6236951 100644
--- a/Documentation/atomic_ops.txt
+++ b/Documentation/core-api/atomic_ops.rst
@@ -1,204 +1,212 @@
- Semantics and Behavior of Atomic and
-Bitmask Operations
+===
+Semantics and Behavior of Atomic and Bitmask Operations
+===
- David S. Miller
+:Author: David S. Miller
- This document is intended to serve as a guide to Linux port
+This document is intended to serve as a guide to Linux port
maintainers on how to implement atomic counter, bitops, and spinlock
interfaces properly.
- The atomic_t type should be defined as a signed integer and
-the atomic_long_t type as a signed long integer. Also, they should
+Atomic Type And Operations
+==
+
+The ``atomic_t type`` should be defined as a signed integer and
+the ``atomic_long_t`` type as a signed long integer. Also, they should
be made opaque such that any kind of cast to a normal C integer type
-will fail. Something like the following should suffice:
+will fail. Something like the following should suffice::
- typedef struct { int counter; } atomic_t;
- typedef struct { long counter; } atomic_long_t;
+typedef struct { int counter; } atomic_t;
+typedef struct { long counter; } atomic_long_t;
Historically, counter has been declared volatile. This is now discouraged.
-See Documentation/process/volatile-considered-harmful.rst for the complete
rationale.
+See :ref:`Documentation/process/volatile-considered-harmful.rst
+` for the complete rationale.
-local_t is very similar to atomic_t. If the counter is per CPU and only
-updated by one CPU, local_t is probably more appropriate. Please see
-Documentation/local_ops.txt for the semantics of local_t.
+``local_t`` is very similar to ``atomic_t``. If the counter is per CPU and only
+updated by one CPU, ``local_t`` is probably more appropriate. Please see
+:ref:`Documentation/local_ops.txt ` for the semantics of
``local_t``.
-The first operations to implement for atomic_t's are the initializers and
-plain reads.
+The first operations to implement for ``atomic_t``'s are the initializers and
+plain reads::
- #define ATOMIC_INIT(i) { (i) }
- #define atomic_set(v, i)((v)->counter = (i))
+#define ATOMIC_INIT(i) { (i) }
+#define atomic_set(v, i)((v)->counter = (i))
-The first macro is used in definitions, such as:
+The first macro is used in definitions, such as::
-static atomic_t my_counter = ATOMIC_INIT(1);
+static atomic_t my_counter = ATOMIC_INIT(1);
The initializer is atomic in that the return values of the atomic operations
are guaranteed to be correct reflecting the initialized value if the
initializer is used before runtime. If the initializer is used at runtime, a
proper implicit or explicit read memory barrier is needed before reading the
-value with atomic_read from another thread.
+value with ``atomic_read`` from another thread.
-As with all of the atomic_ interfaces, replace the leading "atomic_"
-with "atomic_long_" to operate on atomic_long_t.
+As with all of the ``atomic_`` interfaces, replace the leading ``atomic_``
+with ``atomic_long_`` to operate on ``atomic_long_t``.
-The second interface can be used at runtime, as in:
+The second interface can be used at runtime, as in::
- struct foo { atomic_t counter; };
- ...
+struct foo { atomic_t counter; };
+...
- struct foo *k;
+struct foo *k;
- k = kmalloc(sizeof(*k), GFP_KERNEL);
- if (!k)
- return -ENOMEM;
- atomic_set(>counter, 0);
+k = kmalloc(sizeof(*k), GFP_KERNEL);
+if (!k)
+return -ENOMEM;
+atomic_set(>counter, 0);
The setting is atomic in that the return values of the atomic operations by
all threads are guaranteed to be correct reflecting either the value that has
been set with this operation or set with another operation. A proper implicit
or explicit memory barrier is needed before the value set with the operation
-is guaranteed to be readable with atomic_read from another thread.
+is guaranteed to be readable with ``atomic_rea
[PATCH v3 0/4] core-api ReST: assoc_array, atomic_ops, local_ops
Hi, Thanks Mauro and Jani for reviewing. Some more ReSTification of core-api's: assoc_array, atomic_ops and local_ops. A fourth patch removes a warning about a bullet list without ending at firmware_class.c v2 -> v3 * change ". ::" to "::" * replace all "code-blocks" with "::" * add two ".. notes" declaration in atomic_ops.rst v1 -> v2 * use format-patch with a rename_threshold of 10%, no other changes Thanks for review. BR Silvio Silvio Fricke (4): Documentation/assoc_array.txt: convert to ReST markup Documentation/atomic_ops.txt: convert to ReST markup Documentation/local_ops.txt: convert to ReST markup firmware: remove warning at documentation generation time Documentation/assoc_array.txt => Documentation/core-api/assoc_array.rst | 639 --- Documentation/atomic_ops.txt => Documentation/core-api/atomic_ops.rst | 777 +--- Documentation/core-api/index.rst| 3 +- Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 273 + Documentation/process/volatile-considered-harmful.rst | 3 +- drivers/base/firmware_class.c | 6 +- 6 files changed, 861 insertions(+), 840 deletions(-) base-commit: 9c240d757658a3ae9968dd309e674c61f07c7f48 -- git-series 0.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 4/4] firmware: remove warning at documentation generation time
This patch removes following error at for `make htmldocs`. No functional change. ./drivers/base/firmware_class.c:1348: WARNING: Bullet list ends without a blank line; unexpected unindent. Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com> --- drivers/base/firmware_class.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/drivers/base/firmware_class.c b/drivers/base/firmware_class.c index 22d1760..37b0221 100644 --- a/drivers/base/firmware_class.c +++ b/drivers/base/firmware_class.c @@ -1345,9 +1345,9 @@ static void request_firmware_work_func(struct work_struct *work) * * Asynchronous variant of request_firmware() for user contexts: * - sleep for as small periods as possible since it may - * increase kernel boot time of built-in device drivers - * requesting firmware in their ->probe() methods, if - * @gfp is GFP_KERNEL. + * increase kernel boot time of built-in device drivers + * requesting firmware in their ->probe() methods, if + * @gfp is GFP_KERNEL. * * - can't sleep at all if @gfp is GFP_ATOMIC. **/ -- git-series 0.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 1/4] Documentation/assoc_array.txt: convert to ReST markup
... and move to Documentation/core-api folder.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
Documentation/assoc_array.txt | 574 +--
Documentation/core-api/assoc_array.rst | 549 +-
Documentation/core-api/index.rst | 1 +-
3 files changed, 550 insertions(+), 574 deletions(-)
delete mode 100644 Documentation/assoc_array.txt
create mode 100644 Documentation/core-api/assoc_array.rst
diff --git a/Documentation/assoc_array.txt b/Documentation/assoc_array.txt
deleted file mode 100644
index 2f2c6cd..000
--- a/Documentation/assoc_array.txt
+++ /dev/null
@@ -1,574 +0,0 @@
-
- GENERIC ASSOCIATIVE ARRAY IMPLEMENTATION
-
-
-Contents:
-
- - Overview.
-
- - The public API.
- - Edit script.
- - Operations table.
- - Manipulation functions.
- - Access functions.
- - Index key form.
-
- - Internal workings.
- - Basic internal tree layout.
- - Shortcuts.
- - Splitting and collapsing nodes.
- - Non-recursive iteration.
- - Simultaneous alteration and iteration.
-
-
-
-OVERVIEW
-
-
-This associative array implementation is an object container with the following
-properties:
-
- (1) Objects are opaque pointers. The implementation does not care where they
- point (if anywhere) or what they point to (if anything).
-
- [!] NOTE: Pointers to objects _must_ be zero in the least significant bit.
-
- (2) Objects do not need to contain linkage blocks for use by the array. This
- permits an object to be located in multiple arrays simultaneously.
- Rather, the array is made up of metadata blocks that point to objects.
-
- (3) Objects require index keys to locate them within the array.
-
- (4) Index keys must be unique. Inserting an object with the same key as one
- already in the array will replace the old object.
-
- (5) Index keys can be of any length and can be of different lengths.
-
- (6) Index keys should encode the length early on, before any variation due to
- length is seen.
-
- (7) Index keys can include a hash to scatter objects throughout the array.
-
- (8) The array can iterated over. The objects will not necessarily come out in
- key order.
-
- (9) The array can be iterated over whilst it is being modified, provided the
- RCU readlock is being held by the iterator. Note, however, under these
- circumstances, some objects may be seen more than once. If this is a
- problem, the iterator should lock against modification. Objects will not
- be missed, however, unless deleted.
-
-(10) Objects in the array can be looked up by means of their index key.
-
-(11) Objects can be looked up whilst the array is being modified, provided the
- RCU readlock is being held by the thread doing the look up.
-
-The implementation uses a tree of 16-pointer nodes internally that are indexed
-on each level by nibbles from the index key in the same manner as in a radix
-tree. To improve memory efficiency, shortcuts can be emplaced to skip over
-what would otherwise be a series of single-occupancy nodes. Further, nodes
-pack leaf object pointers into spare space in the node rather than making an
-extra branch until as such time an object needs to be added to a full node.
-
-
-==
-THE PUBLIC API
-==
-
-The public API can be found in . The associative array is
-rooted on the following structure:
-
- struct assoc_array {
- ...
- };
-
-The code is selected by enabling CONFIG_ASSOCIATIVE_ARRAY.
-
-
-EDIT SCRIPT
-
-The insertion and deletion functions produce an 'edit script' that can later be
-applied to effect the changes without risking ENOMEM. This retains the
-preallocated metadata blocks that will be installed in the internal tree and
-keeps track of the metadata blocks that will be removed from the tree when the
-script is applied.
-
-This is also used to keep track of dead blocks and dead objects after the
-script has been applied so that they can be freed later. The freeing is done
-after an RCU grace period has passed - thus allowing access functions to
-proceed under the RCU read lock.
-
-The script appears as outside of the API as a pointer of the type:
-
- struct assoc_array_edit;
-
-There are two functions for dealing with the script:
-
- (1) Apply an edit script.
-
- void assoc_array_apply_edit(struct assoc_array_edit *edit);
-
- This will perform the edit functions, interpolating various write barriers
- to permit accesses under the RCU read lock to continue. The edit script
- will then be passed to call_rcu() to free it and any dead stuff it points
- to.
-
- (2) Cancel an edit script.
-
- void assoc_array_cancel_edit(struct assoc_array_edit *edit);
-
- This frees the edit script and all preallocated memory immed
[PATCH 3/4] Documentation/local_ops.txt: convert to ReST markup
... and move to core-api folder.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
Documentation/core-api/index.rst | 1 +-
Documentation/core-api/local_ops.rst | 208 -
Documentation/local_ops.txt | 191 +--
3 files changed, 209 insertions(+), 191 deletions(-)
create mode 100644 Documentation/core-api/local_ops.rst
delete mode 100644 Documentation/local_ops.txt
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index f3e5f5e..25b4e4a 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -9,6 +9,7 @@ Kernel and driver related documentation.
assoc_array
atomic_ops
+ local_ops
workqueue
.. only:: subproject
diff --git a/Documentation/core-api/local_ops.rst
b/Documentation/core-api/local_ops.rst
new file mode 100644
index 000..01f1880
--- /dev/null
+++ b/Documentation/core-api/local_ops.rst
@@ -0,0 +1,208 @@
+
+.. _local_ops:
+
+=
+Semantics and Behavior of Local Atomic Operations
+=
+
+:Author: Mathieu Desnoyers
+
+
+This document explains the purpose of the local atomic operations, how
+to implement them for any given architecture and shows how they can be used
+properly. It also stresses on the precautions that must be taken when reading
+those local variables across CPUs when the order of memory writes matters.
+
+.. note::
+
+Note that ``local_t`` based operations are not recommended for general
+kernel use. Please use the ``this_cpu`` operations instead unless there is
+really a special purpose. Most uses of ``local_t`` in the kernel have been
+replaced by ``this_cpu`` operations. ``this_cpu`` operations combine the
+relocation with the ``local_t`` like semantics in a single instruction and
+yield more compact and faster executing code.
+
+
+Purpose of local atomic operations
+==
+
+Local atomic operations are meant to provide fast and highly reentrant per CPU
+counters. They minimize the performance cost of standard atomic operations by
+removing the LOCK prefix and memory barriers normally required to synchronize
+across CPUs.
+
+Having fast per CPU atomic counters is interesting in many cases: it does not
+require disabling interrupts to protect from interrupt handlers and it permits
+coherent counters in NMI handlers. It is especially useful for tracing purposes
+and for various performance monitoring counters.
+
+Local atomic operations only guarantee variable modification atomicity wrt the
+CPU which owns the data. Therefore, care must taken to make sure that only one
+CPU writes to the ``local_t`` data. This is done by using per cpu data and
+making sure that we modify it from within a preemption safe context. It is
+however permitted to read ``local_t`` data from any CPU: it will then appear to
+be written out of order wrt other memory writes by the owner CPU.
+
+
+Implementation for a given architecture
+===
+
+It can be done by slightly modifying the standard atomic operations: only
+their UP variant must be kept. It typically means removing LOCK prefix (on
+i386 and x86_64) and any SMP synchronization barrier. If the architecture does
+not have a different behavior between SMP and UP, including
+``asm-generic/local.h`` in your architecture's ``local.h`` is sufficient.
+
+The ``local_t`` type is defined as an opaque ``signed long`` by embedding an
+``atomic_long_t`` inside a structure. This is made so a cast from this type to
+a ``long`` fails. The definition looks like::
+
+typedef struct { atomic_long_t a; } local_t;
+
+
+Rules to follow when using local atomic operations
+==
+
+* Variables touched by local ops must be per cpu variables.
+* *Only* the CPU owner of these variables must write to them.
+* This CPU can use local ops from any context (process, irq, softirq, nmi, ...)
+ to update its ``local_t`` variables.
+* Preemption (or interrupts) must be disabled when using local ops in
+ process context to make sure the process won't be migrated to a
+ different CPU between getting the per-cpu variable and doing the
+ actual local op.
+* When using local ops in interrupt context, no special care must be
+ taken on a mainline kernel, since they will run on the local CPU with
+ preemption already disabled. I suggest, however, to explicitly
+ disable preemption anyway to make sure it will still work correctly on
+ -rt kernels.
+* Reading the local cpu variable will provide the current copy of the
+ variable.
+* Reads of these variables can be done from any CPU, because updates to
+ "``long``", aligned, variables are always atomic. Since no memory
+ synchronization is done by the writer CPU, an outdated copy of the
+ variable can be read when reading some *other*
[PATCH 2/4] Documentation/atomic_ops.txt: convert to ReST markup
... and move to core-api folder.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
Documentation/atomic_ops.txt | 640 +---
Documentation/core-api/atomic_ops.rst | 669 +++-
Documentation/core-api/index.rst | 1 +-
Documentation/process/volatile-considered-harmful.rst | 3 +-
4 files changed, 673 insertions(+), 640 deletions(-)
delete mode 100644 Documentation/atomic_ops.txt
create mode 100644 Documentation/core-api/atomic_ops.rst
diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt
deleted file mode 100644
index 6c5e8a9..000
--- a/Documentation/atomic_ops.txt
+++ /dev/null
@@ -1,640 +0,0 @@
- Semantics and Behavior of Atomic and
-Bitmask Operations
-
- David S. Miller
-
- This document is intended to serve as a guide to Linux port
-maintainers on how to implement atomic counter, bitops, and spinlock
-interfaces properly.
-
- The atomic_t type should be defined as a signed integer and
-the atomic_long_t type as a signed long integer. Also, they should
-be made opaque such that any kind of cast to a normal C integer type
-will fail. Something like the following should suffice:
-
- typedef struct { int counter; } atomic_t;
- typedef struct { long counter; } atomic_long_t;
-
-Historically, counter has been declared volatile. This is now discouraged.
-See Documentation/process/volatile-considered-harmful.rst for the complete
rationale.
-
-local_t is very similar to atomic_t. If the counter is per CPU and only
-updated by one CPU, local_t is probably more appropriate. Please see
-Documentation/local_ops.txt for the semantics of local_t.
-
-The first operations to implement for atomic_t's are the initializers and
-plain reads.
-
- #define ATOMIC_INIT(i) { (i) }
- #define atomic_set(v, i)((v)->counter = (i))
-
-The first macro is used in definitions, such as:
-
-static atomic_t my_counter = ATOMIC_INIT(1);
-
-The initializer is atomic in that the return values of the atomic operations
-are guaranteed to be correct reflecting the initialized value if the
-initializer is used before runtime. If the initializer is used at runtime, a
-proper implicit or explicit read memory barrier is needed before reading the
-value with atomic_read from another thread.
-
-As with all of the atomic_ interfaces, replace the leading "atomic_"
-with "atomic_long_" to operate on atomic_long_t.
-
-The second interface can be used at runtime, as in:
-
- struct foo { atomic_t counter; };
- ...
-
- struct foo *k;
-
- k = kmalloc(sizeof(*k), GFP_KERNEL);
- if (!k)
- return -ENOMEM;
- atomic_set(>counter, 0);
-
-The setting is atomic in that the return values of the atomic operations by
-all threads are guaranteed to be correct reflecting either the value that has
-been set with this operation or set with another operation. A proper implicit
-or explicit memory barrier is needed before the value set with the operation
-is guaranteed to be readable with atomic_read from another thread.
-
-Next, we have:
-
- #define atomic_read(v) ((v)->counter)
-
-which simply reads the counter value currently visible to the calling thread.
-The read is atomic in that the return value is guaranteed to be one of the
-values initialized or modified with the interface operations if a proper
-implicit or explicit memory barrier is used after possible runtime
-initialization by any other thread and the value is modified only with the
-interface operations. atomic_read does not guarantee that the runtime
-initialization by any other thread is visible yet, so the user of the
-interface must take care of that with a proper implicit or explicit memory
-barrier.
-
-*** WARNING: atomic_read() and atomic_set() DO NOT IMPLY BARRIERS! ***
-
-Some architectures may choose to use the volatile keyword, barriers, or inline
-assembly to guarantee some degree of immediacy for atomic_read() and
-atomic_set(). This is not uniformly guaranteed, and may change in the future,
-so all users of atomic_t should treat atomic_read() and atomic_set() as simple
-C statements that may be reordered or optimized away entirely by the compiler
-or processor, and explicitly invoke the appropriate compiler and/or memory
-barrier for each use case. Failure to do so will result in code that may
-suddenly break when used with different architectures or compiler
-optimizations, or even changes in unrelated code which changes how the
-compiler optimizes the section accessing atomic_t variables.
-
-*** YOU HAVE BEEN WARNED! ***
-
-Properly aligned pointers, longs, ints, and chars (and unsigned
-equivalents) may be atomically loaded from and stored to in the same
-sense as described for atomic_read() and atomic_set(). The READ_ONCE()
-and WRITE_ONCE() macros sho
[PATCH 0/4] core-api ReST: assoc_array, atomic_ops, local_ops
Hi, Some more ReSTification of core-api's: assoc_array, atomic_ops and local_ops. A fourth patch removes a warning about a bullet list without ending at firmware_class.c Thanks for review. BR Silvio Silvio Fricke (4): Documentation/assoc_array.txt: convert to ReST markup Documentation/atomic_ops.txt: convert to ReST markup Documentation/local_ops.txt: convert to ReST markup firmware: remove warning at documentation generation time Documentation/assoc_array.txt | 574 +- Documentation/atomic_ops.txt | 640 +--- Documentation/core-api/assoc_array.rst| 549 +- Documentation/core-api/atomic_ops.rst | 669 +++- Documentation/core-api/index.rst | 3 +- Documentation/core-api/local_ops.rst | 208 +++- Documentation/local_ops.txt | 191 +--- Documentation/process/volatile-considered-harmful.rst | 3 +- drivers/base/firmware_class.c | 6 +- 9 files changed, 1435 insertions(+), 1408 deletions(-) delete mode 100644 Documentation/assoc_array.txt delete mode 100644 Documentation/atomic_ops.txt create mode 100644 Documentation/core-api/assoc_array.rst create mode 100644 Documentation/core-api/atomic_ops.rst create mode 100644 Documentation/core-api/local_ops.rst delete mode 100644 Documentation/local_ops.txt base-commit: 9c240d757658a3ae9968dd309e674c61f07c7f48 -- git-series 0.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 0/4] core-api ReST: assoc_array, atomic_ops, local_ops
Hi, Some more ReSTification of core-api's: assoc_array, atomic_ops and local_ops. A fourth patch removes a warning about a bullet list without ending at firmware_class.c v1 -> v2 * use format-patch with a rename_threshold of 10%, no other changes Thanks for review. BR Silvio Silvio Fricke (4): Documentation/assoc_array.txt: convert to ReST markup Documentation/atomic_ops.txt: convert to ReST markup Documentation/local_ops.txt: convert to ReST markup firmware: remove warning at documentation generation time Documentation/assoc_array.txt => Documentation/core-api/assoc_array.rst | 617 Documentation/atomic_ops.txt => Documentation/core-api/atomic_ops.rst | 745 +--- Documentation/core-api/index.rst| 3 +- Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 275 ++- Documentation/process/volatile-considered-harmful.rst | 3 +- drivers/base/firmware_class.c | 6 +- 6 files changed, 838 insertions(+), 811 deletions(-) base-commit: 9c240d757658a3ae9968dd309e674c61f07c7f48 -- git-series 0.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 3/4] Documentation/local_ops.txt: convert to ReST markup
... and move to core-api folder. Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com> --- Documentation/core-api/index.rst| 1 +- Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 275 +++ 2 files changed, 147 insertions(+), 129 deletions(-) diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index f3e5f5e..25b4e4a 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -9,6 +9,7 @@ Kernel and driver related documentation. assoc_array atomic_ops + local_ops workqueue .. only:: subproject diff --git a/Documentation/local_ops.txt b/Documentation/core-api/local_ops.rst similarity index 55% rename from Documentation/local_ops.txt rename to Documentation/core-api/local_ops.rst index 407576a..01f1880 100644 --- a/Documentation/local_ops.txt +++ b/Documentation/core-api/local_ops.rst @@ -1,191 +1,208 @@ -Semantics and Behavior of Local Atomic Operations - Mathieu Desnoyers +.. _local_ops: += +Semantics and Behavior of Local Atomic Operations += - This document explains the purpose of the local atomic operations, how +:Author: Mathieu Desnoyers + + +This document explains the purpose of the local atomic operations, how to implement them for any given architecture and shows how they can be used properly. It also stresses on the precautions that must be taken when reading those local variables across CPUs when the order of memory writes matters. -Note that local_t based operations are not recommended for general kernel use. -Please use the this_cpu operations instead unless there is really a special purpose. -Most uses of local_t in the kernel have been replaced by this_cpu operations. -this_cpu operations combine the relocation with the local_t like semantics in -a single instruction and yield more compact and faster executing code. +.. note:: +Note that ``local_t`` based operations are not recommended for general +kernel use. Please use the ``this_cpu`` operations instead unless there is +really a special purpose. Most uses of ``local_t`` in the kernel have been +replaced by ``this_cpu`` operations. ``this_cpu`` operations combine the +relocation with the ``local_t`` like semantics in a single instruction and +yield more compact and faster executing code. -* Purpose of local atomic operations + +Purpose of local atomic operations +== Local atomic operations are meant to provide fast and highly reentrant per CPU counters. They minimize the performance cost of standard atomic operations by removing the LOCK prefix and memory barriers normally required to synchronize across CPUs. -Having fast per CPU atomic counters is interesting in many cases : it does not +Having fast per CPU atomic counters is interesting in many cases: it does not require disabling interrupts to protect from interrupt handlers and it permits coherent counters in NMI handlers. It is especially useful for tracing purposes and for various performance monitoring counters. Local atomic operations only guarantee variable modification atomicity wrt the CPU which owns the data. Therefore, care must taken to make sure that only one -CPU writes to the local_t data. This is done by using per cpu data and making -sure that we modify it from within a preemption safe context. It is however -permitted to read local_t data from any CPU : it will then appear to be written -out of order wrt other memory writes by the owner CPU. +CPU writes to the ``local_t`` data. This is done by using per cpu data and +making sure that we modify it from within a preemption safe context. It is +however permitted to read ``local_t`` data from any CPU: it will then appear to +be written out of order wrt other memory writes by the owner CPU. -* Implementation for a given architecture +Implementation for a given architecture +=== -It can be done by slightly modifying the standard atomic operations : only +It can be done by slightly modifying the standard atomic operations: only their UP variant must be kept. It typically means removing LOCK prefix (on i386 and x86_64) and any SMP synchronization barrier. If the architecture does -not have a different behavior between SMP and UP, including asm-generic/local.h -in your architecture's local.h is sufficient. +not have a different behavior between SMP and UP, including +``asm-generic/local.h`` in your architecture's ``local.h`` is sufficient. -The local_t type is defined as an opaque signed long by embedding an -atomic_long_t inside a structure. This is made so a cast from this type to a -long fails. The definition looks like : +The ``local_t`` type is defined as an opaque ``signed long`` by embedding an +``atom
[PATCH v4 1/4] Documentation/assoc_array.txt: convert to ReST markup
... and move to Documentation/core-api folder. Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mche...@s-opensource.com> --- Documentation/assoc_array.txt => Documentation/core-api/assoc_array.rst | 639 ++-- Documentation/core-api/index.rst| 1 +- 2 files changed, 309 insertions(+), 331 deletions(-) diff --git a/Documentation/assoc_array.txt b/Documentation/core-api/assoc_array.rst similarity index 46% rename from Documentation/assoc_array.txt rename to Documentation/core-api/assoc_array.rst index 2f2c6cd..dcda7c6 100644 --- a/Documentation/assoc_array.txt +++ b/Documentation/core-api/assoc_array.rst @@ -1,67 +1,46 @@ - - GENERIC ASSOCIATIVE ARRAY IMPLEMENTATION - + +Generic Associative Array Implementation + -Contents: - - - Overview. - - - The public API. - - Edit script. - - Operations table. - - Manipulation functions. - - Access functions. - - Index key form. - - - Internal workings. - - Basic internal tree layout. - - Shortcuts. - - Splitting and collapsing nodes. - - Non-recursive iteration. - - Simultaneous alteration and iteration. - - - -OVERVIEW +Overview This associative array implementation is an object container with the following properties: - (1) Objects are opaque pointers. The implementation does not care where they - point (if anywhere) or what they point to (if anything). - - [!] NOTE: Pointers to objects _must_ be zero in the least significant bit. +1. Objects are opaque pointers. The implementation does not care where they + point (if anywhere) or what they point to (if anything). +.. note:: Pointers to objects _must_ be zero in the least significant bit.** - (2) Objects do not need to contain linkage blocks for use by the array. This - permits an object to be located in multiple arrays simultaneously. - Rather, the array is made up of metadata blocks that point to objects. +2. Objects do not need to contain linkage blocks for use by the array. This + permits an object to be located in multiple arrays simultaneously. + Rather, the array is made up of metadata blocks that point to objects. - (3) Objects require index keys to locate them within the array. +3. Objects require index keys to locate them within the array. - (4) Index keys must be unique. Inserting an object with the same key as one - already in the array will replace the old object. +4. Index keys must be unique. Inserting an object with the same key as one + already in the array will replace the old object. - (5) Index keys can be of any length and can be of different lengths. +5. Index keys can be of any length and can be of different lengths. - (6) Index keys should encode the length early on, before any variation due to - length is seen. +6. Index keys should encode the length early on, before any variation due to + length is seen. - (7) Index keys can include a hash to scatter objects throughout the array. +7. Index keys can include a hash to scatter objects throughout the array. - (8) The array can iterated over. The objects will not necessarily come out in - key order. +8. The array can iterated over. The objects will not necessarily come out in + key order. - (9) The array can be iterated over whilst it is being modified, provided the - RCU readlock is being held by the iterator. Note, however, under these - circumstances, some objects may be seen more than once. If this is a - problem, the iterator should lock against modification. Objects will not - be missed, however, unless deleted. +9. The array can be iterated over whilst it is being modified, provided the + RCU readlock is being held by the iterator. Note, however, under these + circumstances, some objects may be seen more than once. If this is a + problem, the iterator should lock against modification. Objects will not + be missed, however, unless deleted. -(10) Objects in the array can be looked up by means of their index key. +10. Objects in the array can be looked up by means of their index key. -(11) Objects can be looked up whilst the array is being modified, provided the - RCU readlock is being held by the thread doing the look up. +11. Objects can be looked up whilst the array is being modified, provided the +RCU readlock is being held by the thread doing the look up. The implementation uses a tree of 16-pointer nodes internally that are indexed on each level by nibbles from the index key in the same manner as in a radix @@ -71,25 +50,26 @@ pack leaf object pointers into spare space in the node rather than making a
[PATCH v4 0/4] core-api ReST: assoc_array, atomic_ops, local_ops
Hi, Some more ReSTification of core-api's: assoc_array, atomic_ops and local_ops. A fourth patch removes a warning about a bullet list without ending at firmware_class.c v3 -> v4 * add Review-by comments * rewrite atomic_ops.rst file with fewer inversive changes * reorder patch series old(1,2,3,4) new(1,3,2,4) v2 -> v3 * change ". ::" to "::" * replace all "code-blocks" with "::" * add two ".. notes" declaration in atomic_ops.rst v1 -> v2 * use format-patch with a rename_threshold of 10%, no other changes Thanks for review. BR Silvio Silvio Fricke (4): Documentation/assoc_array.txt: convert to ReST markup Documentation/local_ops.txt: convert to ReST markup Documentation/atomic_ops.txt: convert to ReST markup firmware: remove warning at documentation generation time Documentation/assoc_array.txt => Documentation/core-api/assoc_array.rst | 639 ++-- Documentation/atomic_ops.txt => Documentation/core-api/atomic_ops.rst | 324 +++-- Documentation/core-api/index.rst| 3 +- Documentation/local_ops.txt => Documentation/core-api/local_ops.rst | 273 --- Documentation/process/volatile-considered-harmful.rst | 3 +- drivers/base/firmware_class.c | 6 +- 6 files changed, 632 insertions(+), 616 deletions(-) base-commit: 9c240d757658a3ae9968dd309e674c61f07c7f48 -- git-series 0.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v5 4/4] Documentation/workqueue.txt: convert to ReST markup
... and move to Documentation/core-api folder. Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com> --- Documentation/core-api/index.rst | 2 +- Documentation/core-api/workqueue.rst | 394 - Documentation/workqueue.txt | 388 + MAINTAINERS | 2 +- 4 files changed, 397 insertions(+), 389 deletions(-) create mode 100644 Documentation/core-api/workqueue.rst delete mode 100644 Documentation/workqueue.txt diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index ed3eb64..f7ef7fd 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -7,6 +7,8 @@ Kernel and driver related documentation. .. toctree:: :maxdepth: 1 + workqueue + .. only:: subproject Indices diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst new file mode 100644 index 000..ffdec94 --- /dev/null +++ b/Documentation/core-api/workqueue.rst @@ -0,0 +1,394 @@ + +Concurrency Managed Workqueue (cmwq) + + +:Date: September, 2010 +:Author: Tejun Heo <t...@kernel.org> +:Author: Florian Mickler <flor...@mickler.org> + + +Introduction + + +There are many cases where an asynchronous process execution context +is needed and the workqueue (wq) API is the most commonly used +mechanism for such cases. + +When such an asynchronous execution context is needed, a work item +describing which function to execute is put on a queue. An +independent thread serves as the asynchronous execution context. The +queue is called workqueue and the thread is called worker. + +While there are work items on the workqueue the worker executes the +functions associated with the work items one after the other. When +there is no work item left on the workqueue the worker becomes idle. +When a new work item gets queued, the worker begins executing again. + + +Why cmwq? += + +In the original wq implementation, a multi threaded (MT) wq had one +worker thread per CPU and a single threaded (ST) wq had one worker +thread system-wide. A single MT wq needed to keep around the same +number of workers as the number of CPUs. The kernel grew a lot of MT +wq users over the years and with the number of CPU cores continuously +rising, some systems saturated the default 32k PID space just booting +up. + +Although MT wq wasted a lot of resource, the level of concurrency +provided was unsatisfactory. The limitation was common to both ST and +MT wq albeit less severe on MT. Each wq maintained its own separate +worker pool. A MT wq could provide only one execution context per CPU +while a ST wq one for the whole system. Work items had to compete for +those very limited execution contexts leading to various problems +including proneness to deadlocks around the single execution context. + +The tension between the provided level of concurrency and resource +usage also forced its users to make unnecessary tradeoffs like libata +choosing to use ST wq for polling PIOs and accepting an unnecessary +limitation that no two polling PIOs can progress at the same time. As +MT wq don't provide much better concurrency, users which require +higher level of concurrency, like async or fscache, had to implement +their own thread pool. + +Concurrency Managed Workqueue (cmwq) is a reimplementation of wq with +focus on the following goals. + +* Maintain compatibility with the original workqueue API. + +* Use per-CPU unified worker pools shared by all wq to provide + flexible level of concurrency on demand without wasting a lot of + resource. + +* Automatically regulate worker pool and level of concurrency so that + the API users don't need to worry about such details. + + +The Design +== + +In order to ease the asynchronous execution of functions a new +abstraction, the work item, is introduced. + +A work item is a simple struct that holds a pointer to the function +that is to be executed asynchronously. Whenever a driver or subsystem +wants a function to be executed asynchronously it has to set up a work +item pointing to that function and queue that work item on a +workqueue. + +Special purpose threads, called worker threads, execute the functions +off of the queue, one after the other. If no work is queued, the +worker threads become idle. These worker threads are managed in so +called worker-pools. + +The cmwq design differentiates between the user-facing workqueues that +subsystems and drivers queue work items on and the backend mechanism +which manages worker-pools and processes the queued work items. + +There are two worker-pools, one for normal work items and the other +for high priority ones, for each possible CPU and some extra +worker-pools to serve work items queued on unbound workqueues - the +number of these backing pools is dynamic. + +Subsystems and
[PATCH v5 2/4] workqueue: kerneldocify workqueue_attrs
Only formating changes.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
include/linux/workqueue.h | 35 ---
1 file changed, 24 insertions(+), 11 deletions(-)
diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h
index fc6e221..d4f16cf 100644
--- a/include/linux/workqueue.h
+++ b/include/linux/workqueue.h
@@ -119,18 +119,30 @@ struct delayed_work {
int cpu;
};
-/*
- * A struct for workqueue attributes. This can be used to change
- * attributes of an unbound workqueue.
+/**
+ * struct workqueue_attrs - A struct for workqueue attributes.
*
- * Unlike other fields, ->no_numa isn't a property of a worker_pool. It
- * only modifies how apply_workqueue_attrs() select pools and thus doesn't
- * participate in pool hash calculations or equality comparisons.
+ * This can be used to change attributes of an unbound workqueue.
*/
struct workqueue_attrs {
- int nice; /* nice level */
- cpumask_var_t cpumask;/* allowed CPUs */
- boolno_numa;/* disable NUMA affinity */
+ /**
+* @nice: nice level
+*/
+ int nice;
+
+ /**
+* @cpumask: allowed CPUs
+*/
+ cpumask_var_t cpumask;
+
+ /**
+* @no_numa: disable NUMA affinity
+*
+* Unlike other fields, ``no_numa`` isn't a property of a worker_pool.
It
+* only modifies how :c:func:`apply_workqueue_attrs` select pools and
thus
+* doesn't participate in pool hash calculations or equality
comparisons.
+*/
+ bool no_numa;
};
static inline struct delayed_work *to_delayed_work(struct work_struct *work)
@@ -272,7 +284,7 @@ static inline unsigned int work_static(struct work_struct
*work) { return 0; }
/*
* Workqueue flags and constants. For details, please refer to
- * Documentation/workqueue.txt.
+ * Documentation/core-api/workqueue.rst.
*/
enum {
WQ_UNBOUND = 1 << 1, /* not bound to any cpu */
@@ -370,7 +382,8 @@ __alloc_workqueue_key(const char *fmt, unsigned int flags,
int max_active,
* @args...: args for @fmt
*
* Allocate a workqueue with the specified parameters. For detailed
- * information on WQ_* flags, please refer to Documentation/workqueue.txt.
+ * information on WQ_* flags, please refer to
+ * Documentation/core-api/workqueue.rst.
*
* The __lock_name macro dance is to guarantee that single lock_class_key
* doesn't end up with different namesm, which isn't allowed by lockdep.
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v5 0/4] workqueue documentation reformatted
Hi Jon, > - I can't get it to apply; what kernel did you do this set against? > Can I get it done against docs-next, by any chance? I had it on origins/master. Now rebased to your next branch. > - Part 2 (the workqueue.h changes) are probably best routed through > Tejun's tree. They are independent of the rest anyway. > > - Don't forget to adjust MAINTAINERS for the new location for the > workqueue doc. The MAINTAINERS are already patched on P4. Should this get an own patch? Best regards Silvio v4 -> v5: * rebased from origin/master to linux-doc/docs-next * move workqueue.h changes from P4 to P2 v3 -> v4: * The outdated misc reference in D/index.rst was not removed v2 -> v3: * Introduce a core-api folder * move workqueue.rst to core-api * reflect change in 00-index and workqueue.h v1 -> v2: * s/kernel-doc: $type_param takes care that this parameter is used for formatting too. * i/l/workqueue.h: inlining of documentation for workqueue_attrs struct members * D/workqueue.rst: Every author get a own :AUTHOR:-label * D/index.rst: add misc section and add link to workqueue documentation Best regards Silvio Silvio Fricke (4): kernel-doc: better parsing of named variable arguments workqueue: kerneldocify workqueue_attrs Documentation/00-index: update for new core-api folder Documentation/workqueue.txt: convert to ReST markup Documentation/00-INDEX | 4 +- Documentation/core-api/conf.py | 5 +- Documentation/core-api/index.rst | 17 +- Documentation/core-api/workqueue.rst | 394 - Documentation/index.rst | 1 +- Documentation/workqueue.txt | 388 + MAINTAINERS | 2 +- include/linux/workqueue.h| 35 +- scripts/kernel-doc | 8 +- 9 files changed, 451 insertions(+), 403 deletions(-) create mode 100644 Documentation/core-api/conf.py create mode 100644 Documentation/core-api/index.rst create mode 100644 Documentation/core-api/workqueue.rst delete mode 100644 Documentation/workqueue.txt base-commit: 9d2cccdd6c226181c42a7bb0c5ede1583687b618 -- git-series 0.8.10 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v5 1/4] kernel-doc: better parsing of named variable arguments
Without this patch we get warnings for named variable arguments.
warning: No description found for parameter '...'
warning: Excess function parameter 'args' description in
'alloc_ordered_workqueue'
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
Reviewed-by: Jani Nikula <jani.nik...@intel.com
---
scripts/kernel-doc | 8 ++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 93721f3..e10378f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -204,6 +204,7 @@ EOF
## init lots of data
+
my $errors = 0;
my $warnings = 0;
my $anon_struct_union = 0;
@@ -211,7 +212,7 @@ my $anon_struct_union = 0;
# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w+)';
+my $type_param = '\@(\w+(\.\.\.)?)';
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\((struct\s*)*[_\w]+)';
@@ -2353,7 +2354,10 @@ sub push_parameter($$$) {
if ($type eq "" && $param =~ /\.\.\.$/)
{
- $param = "...";
+ if (!$param =~ /\w\.\.\.$/) {
+ # handles unnamed variable parameters
+ $param = "...";
+ }
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq
"") {
$parameterdescs{$param} = "variable arguments";
}
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v5 3/4] Documentation/00-index: update for new core-api folder
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
Documentation/00-INDEX | 4 +++-
Documentation/core-api/conf.py | 5 +
Documentation/core-api/index.rst | 15 +++
Documentation/index.rst | 1 +
4 files changed, 24 insertions(+), 1 deletion(-)
create mode 100644 Documentation/core-api/conf.py
create mode 100644 Documentation/core-api/index.rst
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 903ebc4..e2e7444 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -126,6 +126,8 @@ connector/
- docs on the netlink based userspace<->kernel space communication mod.
console/
- documentation on Linux console drivers.
+core-api/
+ - documentation on kernel core components.
cpu-freq/
- info on CPU frequency and voltage scaling.
cpu-hotplug.txt
@@ -470,7 +472,7 @@ watchdog/
- how to auto-reboot Linux if it has "fallen and can't get up". ;-)
wimax/
- directory with info about Intel Wireless Wimax Connections
-workqueue.txt
+core-api/workqueue.rst
- information on the Concurrency Managed Workqueue implementation
x86/x86_64/
- directory with info on Linux support for AMD x86-64 (Hammer) machines.
diff --git a/Documentation/core-api/conf.py b/Documentation/core-api/conf.py
new file mode 100644
index 000..fed87ab
--- /dev/null
+++ b/Documentation/core-api/conf.py
@@ -0,0 +1,5 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Core-API Documentation"
+
+tags.add("subproject")
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
new file mode 100644
index 000..ed3eb64
--- /dev/null
+++ b/Documentation/core-api/index.rst
@@ -0,0 +1,15 @@
+==
+Core-API Documentation
+==
+
+Kernel and driver related documentation.
+
+.. toctree::
+ :maxdepth: 1
+
+.. only:: subproject
+
+ Indices
+ ===
+
+ * :ref:`genindex`
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 85a6627..3bb82fb 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -53,6 +53,7 @@ needed).
:maxdepth: 2
driver-api/index
+ core-api/index
media/index
gpu/index
80211/index
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 2/3] workqueue: kerneldocify workqueue_attrs
Only formating changes.
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
include/linux/workqueue.h | 22 +-
1 file changed, 13 insertions(+), 9 deletions(-)
diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h
index fc6e221..8455869 100644
--- a/include/linux/workqueue.h
+++ b/include/linux/workqueue.h
@@ -119,18 +119,22 @@ struct delayed_work {
int cpu;
};
-/*
- * A struct for workqueue attributes. This can be used to change
- * attributes of an unbound workqueue.
+/**
+ * struct workqueue_attrs - A struct for workqueue attributes.
+ * @nice: nice level
+ * @cpumask: allowed CPUs
+ * @no_numa: disable NUMA affinity
+ *
+ * Unlike other fields, ``no_numa`` isn't a property of a worker_pool. It
+ * only modifies how :c:func:`apply_workqueue_attrs` select pools and thus
+ * doesn't participate in pool hash calculations or equality comparisons.
*
- * Unlike other fields, ->no_numa isn't a property of a worker_pool. It
- * only modifies how apply_workqueue_attrs() select pools and thus doesn't
- * participate in pool hash calculations or equality comparisons.
+ * This can be used to change attributes of an unbound workqueue.
*/
struct workqueue_attrs {
- int nice; /* nice level */
- cpumask_var_t cpumask;/* allowed CPUs */
- boolno_numa;/* disable NUMA affinity */
+ int nice;
+ cpumask_var_t cpumask;
+ boolno_numa;
};
static inline struct delayed_work *to_delayed_work(struct work_struct *work)
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 1/3] kernel-doc: better parsing of named variable arguments
Without this patch we get warnings for named variable arguments.
warning: No description found for parameter '...'
warning: Excess function parameter 'args' description in
'alloc_ordered_workqueue'
Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com>
---
scripts/kernel-doc | 9 +++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 93721f3..cd5d830 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -211,7 +211,7 @@ my $anon_struct_union = 0;
# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w+)';
+my $type_param = '\@(\w+\.{0,3})';
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\((struct\s*)*[_\w]+)';
@@ -2353,7 +2353,12 @@ sub push_parameter($$$) {
if ($type eq "" && $param =~ /\.\.\.$/)
{
- $param = "...";
+ if ($param =~ /\w\.\.\.$/) {
+ # handles ARGNAME... parameter
+ $param = $param;
+ } else {
+ $param = "...";
+ }
if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq
"") {
$parameterdescs{$param} = "variable arguments";
}
--
git-series 0.8.10
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 0/3] [RFC] workqueue documentation reformated
Hi, This is a RFC of a reformatting the workqueue documentation using rst. It's my first contribution to documentation section and I would like to know if these changes are in a acceptable state. Thanks for reviewing, Silvio Silvio Fricke (3): kernel-doc: better parsing of named variable arguments workqueue: kerneldocify workqueue_attrs kernel-doc: kerneldocify workqueue documentation Documentation/index.rst | 1 +- Documentation/workqueue.rst | 394 +- Documentation/workqueue.txt | 388 + MAINTAINERS | 2 +- include/linux/workqueue.h | 26 +- scripts/kernel-doc | 9 +- 6 files changed, 418 insertions(+), 402 deletions(-) create mode 100644 Documentation/workqueue.rst delete mode 100644 Documentation/workqueue.txt base-commit: 1001354ca34179f3db924eb66672442a173147dc -- git-series 0.8.10 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 3/3] kernel-doc: kerneldocify workqueue documentation
Only formating changes. Signed-off-by: Silvio Fricke <silvio.fri...@gmail.com> --- Documentation/index.rst | 1 +- Documentation/workqueue.rst | 394 +- Documentation/workqueue.txt | 388 + MAINTAINERS | 2 +- include/linux/workqueue.h | 4 +- 5 files changed, 398 insertions(+), 391 deletions(-) create mode 100644 Documentation/workqueue.rst delete mode 100644 Documentation/workqueue.txt diff --git a/Documentation/index.rst b/Documentation/index.rst index c53d089..f631655 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -18,6 +18,7 @@ Contents: media/index gpu/index 80211/index + workqueue Indices and tables == diff --git a/Documentation/workqueue.rst b/Documentation/workqueue.rst new file mode 100644 index 000..03ac70f --- /dev/null +++ b/Documentation/workqueue.rst @@ -0,0 +1,394 @@ + +Concurrency Managed Workqueue (cmwq) + + +:Date: September, 2010 +:Authors: * Tejun Heo <t...@kernel.org>; + * Florian Mickler <flor...@mickler.org>; + + +Introduction + + +There are many cases where an asynchronous process execution context +is needed and the workqueue (wq) API is the most commonly used +mechanism for such cases. + +When such an asynchronous execution context is needed, a work item +describing which function to execute is put on a queue. An +independent thread serves as the asynchronous execution context. The +queue is called workqueue and the thread is called worker. + +While there are work items on the workqueue the worker executes the +functions associated with the work items one after the other. When +there is no work item left on the workqueue the worker becomes idle. +When a new work item gets queued, the worker begins executing again. + + +Why cmwq? += + +In the original wq implementation, a multi threaded (MT) wq had one +worker thread per CPU and a single threaded (ST) wq had one worker +thread system-wide. A single MT wq needed to keep around the same +number of workers as the number of CPUs. The kernel grew a lot of MT +wq users over the years and with the number of CPU cores continuously +rising, some systems saturated the default 32k PID space just booting +up. + +Although MT wq wasted a lot of resource, the level of concurrency +provided was unsatisfactory. The limitation was common to both ST and +MT wq albeit less severe on MT. Each wq maintained its own separate +worker pool. A MT wq could provide only one execution context per CPU +while a ST wq one for the whole system. Work items had to compete for +those very limited execution contexts leading to various problems +including proneness to deadlocks around the single execution context. + +The tension between the provided level of concurrency and resource +usage also forced its users to make unnecessary tradeoffs like libata +choosing to use ST wq for polling PIOs and accepting an unnecessary +limitation that no two polling PIOs can progress at the same time. As +MT wq don't provide much better concurrency, users which require +higher level of concurrency, like async or fscache, had to implement +their own thread pool. + +Concurrency Managed Workqueue (cmwq) is a reimplementation of wq with +focus on the following goals. + +* Maintain compatibility with the original workqueue API. + +* Use per-CPU unified worker pools shared by all wq to provide + flexible level of concurrency on demand without wasting a lot of + resource. + +* Automatically regulate worker pool and level of concurrency so that + the API users don't need to worry about such details. + + +The Design +== + +In order to ease the asynchronous execution of functions a new +abstraction, the work item, is introduced. + +A work item is a simple struct that holds a pointer to the function +that is to be executed asynchronously. Whenever a driver or subsystem +wants a function to be executed asynchronously it has to set up a work +item pointing to that function and queue that work item on a +workqueue. + +Special purpose threads, called worker threads, execute the functions +off of the queue, one after the other. If no work is queued, the +worker threads become idle. These worker threads are managed in so +called worker-pools. + +The cmwq design differentiates between the user-facing workqueues that +subsystems and drivers queue work items on and the backend mechanism +which manages worker-pools and processes the queued work items. + +There are two worker-pools, one for normal work items and the other +for high priority ones, for each possible CPU and some extra +worker-pools to serve work items queued on unbound workqueues - the +number of these backing pools is dynamic. + +Subsystems and drivers can create and queue work items through special +workqueue API functions as they
