Re: [PATCH 3/7] crypto: doc - fix source comments for Sphinx

[Markus Heiser]

Am 16.10.2016 um 15:03 schrieb Stephan Mueller :

> Am Sonntag, 16. Oktober 2016, 14:56:49 CEST schrieb Markus Heiser:
> 
> Hi Markus,
> ...
> 
>> compared to DocBook, with sphinx you can use (have to use) the reST markup
>> in source code comments.
>> 
>> Here, the code example is just a (indented) float text and this is
>> why you have to quote the asterisk "\*req,".
> 
> Is there any preferred / suggested way whether to use literal or highlighted 
> (or even my approach on) formatting?

No. IMO the "::" markup for code blocks is a good compromise. It is not 
to verbose and prevents you quoting frequent asterisk in code examples.

--Markus--

> Ciao
> Stephan
> --
> 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

--
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

Re: [PATCH 3/7] crypto: doc - fix source comments for Sphinx

[Markus Heiser]

Am 16.10.2016 um 05:18 schrieb Stephan Mueller :

> Update comments to avoid any complaints from Sphinx during compilation.
> 
> Signed-off-by: Stephan Mueller 
> ---
> include/crypto/aead.h | 14 +++---
> include/crypto/hash.h |  2 +-
> include/crypto/skcipher.h |  4 ++--
> include/linux/crypto.h|  4 ++--
> 4 files changed, 12 insertions(+), 12 deletions(-)
> 
> diff --git a/include/crypto/aead.h b/include/crypto/aead.h
> index 12f8432..1bd3a2f 100644
> --- a/include/crypto/aead.h
> +++ b/include/crypto/aead.h
> @@ -55,14 +55,14 @@
> * The scatter list pointing to the input data must contain:
> *
> * * for RFC4106 ciphers, the concatenation of
> - * associated authentication data || IV || plaintext or ciphertext. Note, the
> - * same IV (buffer) is also set with the aead_request_set_crypt call. Note,
> - * the API call of aead_request_set_ad must provide the length of the AAD and
> - * the IV. The API call of aead_request_set_crypt only points to the size of
> - * the input plaintext or ciphertext.
> + *   associated authentication data || IV || plaintext or ciphertext. Note, 
> the
> + *   same IV (buffer) is also set with the aead_request_set_crypt call. Note,
> + *   the API call of aead_request_set_ad must provide the length of the AAD 
> and
> + *   the IV. The API call of aead_request_set_crypt only points to the size 
> of
> + *   the input plaintext or ciphertext.
> *
> * * for "normal" AEAD ciphers, the concatenation of
> - * associated authentication data || plaintext or ciphertext.
> + *   associated authentication data || plaintext or ciphertext.
> *
> * It is important to note that if multiple scatter gather list entries form
> * the input data mentioned above, the first entry must not point to a NULL
> @@ -454,7 +454,7 @@ static inline void aead_request_free(struct aead_request 
> *req)
> * The callback function is registered with the aead_request handle and
> * must comply with the following template
> *
> - *   void callback_function(struct crypto_async_request *req, int error)
> + *   void callback_function(struct crypto_async_request \*req, int error)

Hi Stephan,

compared to DocBook, with sphinx you can use (have to use) the reST markup
in source code comments.

Here, the code example is just a (indented) float text and this is 
why you have to quote the asterisk "\*req,". 

If you want a literal (pre-formatted) block, I recommend to use two colon
and an indented block:

* The callback function is registered with the aead_request handle and
* must comply with the following template::
*
*   void callback_function(struct crypto_async_request *req, int error)
*

If you want a *highlighted* code block, use the code-block directive, e.g:

* The callback function is registered with the aead_request handle and
* must comply with the following template:
*
* .. code-block: c
*
*void callback_function(struct crypto_async_request *req, int error)
*

-- Markus --


> */
> static inline void aead_request_set_callback(struct aead_request *req,
>u32 flags,
> diff --git a/include/crypto/hash.h b/include/crypto/hash.h
> index 2660588..23f15d0 100644
> --- a/include/crypto/hash.h
> +++ b/include/crypto/hash.h
> @@ -607,7 +607,7 @@ static inline struct ahash_request *ahash_request_cast(
> * The callback function is registered with the _request handle and
> * must comply with the following template
> *
> - *   void callback_function(struct crypto_async_request *req, int error)
> + *   void callback_function(struct crypto_async_request \*req, int error)
> */
> static inline void ahash_request_set_callback(struct ahash_request *req,
> u32 flags,
> diff --git a/include/crypto/skcipher.h b/include/crypto/skcipher.h
> index cc4d98a..78a1de0 100644
> --- a/include/crypto/skcipher.h
> +++ b/include/crypto/skcipher.h
> @@ -516,7 +516,7 @@ static inline void skcipher_request_zero(struct 
> skcipher_request *req)
> * skcipher_request_set_callback() - set asynchronous callback function
> * @req: request handle
> * @flags: specify zero or an ORing of the flags
> - * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
> + *  CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
> *increase the wait queue beyond the initial maximum size;
> *CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
> * @compl: callback function pointer to be registered with the request handle
> @@ -535,7 +535,7 @@ static inline void skcipher_request_zero(struct 
> skcipher_request *req)
> * The callback function is registered with the skcipher_request handle and
> * must comply with the following template
> *
> - *   void callback_function(struct crypto_async_request *req, int error)
> + *   void callback_function(struct crypto_async_request \*req, int error)
> */
> static inline void skcipher_request_set_callback(struct skcipher_request 

Re: [PATCH 3/7] crypto: doc - fix source comments for Sphinx

[Stephan Mueller]

Am Sonntag, 16. Oktober 2016, 14:56:49 CEST schrieb Markus Heiser:

Hi Markus,
...

> compared to DocBook, with sphinx you can use (have to use) the reST markup
> in source code comments.
> 
> Here, the code example is just a (indented) float text and this is
> why you have to quote the asterisk "\*req,".

Is there any preferred / suggested way whether to use literal or highlighted 
(or even my approach on) formatting?

Ciao
Stephan
--
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

Re: [PATCH 7/7] crypto: doc - clarify AEAD memory structure

[Markus Heiser]

Am 16.10.2016 um 05:22 schrieb Stephan Mueller :

> The previous description have been misleading and partially incorrect.
> 
> Reported-by: Harsh Jain 
> Signed-off-by: Stephan Mueller 
> ---
> crypto/algif_aead.c   | 14 ++
> include/crypto/aead.h | 35 +++
> 2 files changed, 13 insertions(+), 36 deletions(-)
> 
> diff --git a/crypto/algif_aead.c b/crypto/algif_aead.c
> index 80a0f1a..a0d8377 100644
> --- a/crypto/algif_aead.c
> +++ b/crypto/algif_aead.c
> @@ -551,18 +551,8 @@ static int aead_recvmsg_sync(struct socket *sock, struct 
> msghdr *msg, int flags)
>   lock_sock(sk);
> 
>   /*
> -  * AEAD memory structure: For encryption, the tag is appended to the
> -  * ciphertext which implies that the memory allocated for the ciphertext
> -  * must be increased by the tag length. For decryption, the tag
> -  * is expected to be concatenated to the ciphertext. The plaintext
> -  * therefore has a memory size of the ciphertext minus the tag length.
> -  *
> -  * The memory structure for cipher operation has the following
> -  * structure:
> -  *  AEAD encryption input:  assoc data || plaintext
> -  *  AEAD encryption output: cipherntext || auth tag
> -  *  AEAD decryption input:  assoc data || ciphertext || auth tag
> -  *  AEAD decryption output: plaintext
> +  * Please see documentation of aead_request_set_crypt for the
> +  * description of the AEAD memory structure expected from the caller.
>*/
> 
>   if (ctx->more) {
> diff --git a/include/crypto/aead.h b/include/crypto/aead.h
> index 1bd3a2f..b7f3373 100644
> --- a/include/crypto/aead.h
> +++ b/include/crypto/aead.h
> @@ -483,30 +483,17 @@ static inline void aead_request_set_callback(struct 
> aead_request *req,
> * destination is the ciphertext. For a decryption operation, the use is
> * reversed - the source is the ciphertext and the destination is the 
> plaintext.
> *
> - * For both src/dst the layout is associated data, plain/cipher text,
> - * authentication tag.
> - *
> - * The content of the AD in the destination buffer after processing
> - * will either be untouched, or it will contain a copy of the AD
> - * from the source buffer.  In order to ensure that it always has
> - * a copy of the AD, the user must copy the AD over either before
> - * or after processing.  Of course this is not relevant if the user
> - * is doing in-place processing where src == dst.
> - *
> - * IMPORTANT NOTE AEAD requires an authentication tag (MAC). For decryption,
> - * the caller must concatenate the ciphertext followed by the
> - * authentication tag and provide the entire data stream to the
> - * decryption operation (i.e. the data length used for the
> - * initialization of the scatterlist and the data length for the
> - * decryption operation is identical). For encryption, however,
> - * the authentication tag is created while encrypting the data.
> - * The destination buffer must hold sufficient space for the
> - * ciphertext and the authentication tag while the encryption
> - * invocation must only point to the plaintext data size. The
> - * following code snippet illustrates the memory usage
> - * buffer = kmalloc(ptbuflen + (enc ? authsize : 0));
> - * sg_init_one(, buffer, ptbuflen + (enc ? authsize : 0));
> - * aead_request_set_crypt(req, , , ptbuflen, iv);
> + * The memory structure for cipher operation has the following structure:
> + *   AEAD encryption input:  assoc data || plaintext
> + *   AEAD encryption output: assoc data || cipherntext || auth tag
> + *   AEAD decryption input:  assoc data || ciphertext || auth tag
> + *   AEAD decryption output: assoc data || plaintext
> + *

Hi Stephan,

as I wrote before in 3/7, you can use the reST markup in source
code comments. If you want a list markup, I recommend to write:

* The memory structure for cipher operation has the following structure:
*
* - AEAD encryption input:  assoc data || plaintext
* - AEAD encryption output: assoc data || cipherntext || auth tag
* - AEAD decryption input:  assoc data || ciphertext || auth tag
* - AEAD decryption output: assoc data || plaintext
*

And if you want a inline literal you can use the backquotes

* - AEAD decryption output: ``assoc data || plaintext``

reST is a simple ASCII markup, I can't advice excessive markup
in source code, but simple inline- or block-markups like lists
and code-blocks are sometimes helpful. For this, the the first
half of the reST primer is advisable:

http://www.sphinx-doc.org/en/stable/rest.html 

These are only my 2cent in hope that helps ... there is no rule 
to use any special markup ... use markup as you prefer ;-)

--Markus --

> + * Albeit the kernel requires the presence 

Re: [PATCH 7/7] crypto: doc - clarify AEAD memory structure

[Stephan Mueller]

Am Sonntag, 16. Oktober 2016, 15:11:38 CEST schrieb Markus Heiser:

Hi Markus,

> These are only my 2cent in hope that helps ... there is no rule
> to use any special markup ... use markup as you prefer ;-)

Thanks for the pointers. I will release a new patch set following your 
suggestions after others had the chance to review and comment.

Thanks!

Ciao
Stephan
--
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

[Silvio Fricke]

Only formating changes.

Signed-off-by: Silvio Fricke 
---
 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

[Silvio Fricke]

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 
---
 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

[Silvio Fricke]

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

[Silvio Fricke]

Only formating changes.

Signed-off-by: Silvio Fricke 
---
 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 ;
+  * Florian Mickler ;
+
+
+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 see fit. They can 

[PATCH] mac80211_hwsim: suggest nl80211 instead of wext driver in documentation

[Linus Lüssing]

For mac80211_hwsim interfaces, suggest to use wpa_supplicant with the more
modern, netlink based driver instead of wext.

Signed-off-by: Linus Lüssing 
---

Actually, I wasn't even able to make a connection with the configuration
files and information provided in
Documentation/networking/mac80211_hwsim/{README,hostapd.conf/wpa_supplicant.conf}

Changing -Dwext to -Dnl80211 helped and made the WPA-PSK connection with
mac80211_hwsim interfaces work for me.
---
 Documentation/networking/mac80211_hwsim/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/networking/mac80211_hwsim/README 
b/Documentation/networking/mac80211_hwsim/README
index 24ac91d..3566a72 100644
--- a/Documentation/networking/mac80211_hwsim/README
+++ b/Documentation/networking/mac80211_hwsim/README
@@ -60,7 +60,7 @@ modprobe mac80211_hwsim
 hostapd hostapd.conf
 
 # Run wpa_supplicant (station) for wlan1
-wpa_supplicant -Dwext -iwlan1 -c wpa_supplicant.conf
+wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
 
 
 More test cases are available in hostap.git:
-- 
2.1.4

--
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