Re: [PATCH 00/18] Fix some build warnings/errors with Sphinx

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:36 -0300
Mauro Carvalho Chehab  wrote:

> I decided to give a try with Sphinx last stable version
> (1.17.4), and noticed several issues. The worse one was
> with the networking book: a non-standard footnote there
> with [*] instead of a number causes it to break PDF building.
> 
> So, I took some spare time to address some warnings all over
> the tree, and moved a few text documents to a book. 

OK, I've applied the ones that seem to make sense for me to take now.
There's comments on the firmware one, and I'd rather have Tejun's OK for
the cgroup one.  The code-comment changes should probably go via the
usual maintainers.

> I with
> I had more time to move the other ones and to solve other
> warnings.

You and me both - but each step helps!

Thanks,

jon

Re: [PATCH 03/18] docs: */index.rst: Add newer documents to their respective index.rst

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:39 -0300
Mauro Carvalho Chehab  wrote:

> A number of new docs were added, but they're currently not on
> the index.rst from the session they're supposed to be, causing
> Sphinx warnings.
> 
> Add them.
> 
> Signed-off-by: Mauro Carvalho Chehab 

I've applied this one, thanks.

jon

Re: [PATCH v6 1/5] lib: Update LZ4 compressor module

[Jonathan Corbet]

On Fri, 27 Jan 2017 23:02:00 +0100
Sven Schmidt <4ssch...@informatik.uni-hamburg.de> wrote:

I have one quick question...

>  /*
> + * LZ4_compress_default()
> + *   Compresses 'sourceSize' bytes from buffer 'source'
> + *   into already allocated 'dest' buffer of size 'maxOutputSize'.
> + *   Compression is guaranteed to succeed if
> + *   'maxOutputSize' >= LZ4_compressBound(inputSize).
> + *   It also runs faster, so it's a recommended setting.
> + *   If the function cannot compress 'source'
> + *   into a more limited 'dest' budget,
> + *   compression stops *immediately*,
> + *   and the function result is zero.
> + *   As a consequence, 'dest' content is not valid.
> + *
> + *   source   : source address of the original data
> + *   dest : output buffer address
> + * of the compressed data
> + *   inputSize: Max supported value is
> + * LZ4_MAX_INPUT_SIZE
> + *   maxOutputSize: full or partial size of buffer 'dest'
> + * (which must be already allocated)
> + *   workmem  : address of the working memory.
> + * This requires 'workmem' of size LZ4_MEM_COMPRESS.
> + *   return   : the number of bytes written into buffer 'dest'
> + *   (necessarily <= maxOutputSize) or 0 if compression fails
> + */
> +int LZ4_compress_default(const char *source, char *dest, int inputSize,
> + int maxOutputSize, void *wrkmem);

Is there any chance you could format these as kerneldoc comments?  You're
not too far from it now, and that would allow the LZ4 interface to be
pulled into the documentation.

Thanks,

jon

Re: [PATCH v2 0/8] Conversion crypto API documentation to Sphinx

[Jonathan Corbet]

On Tue, 13 Dec 2016 23:06:14 +0100
Stephan Müller  wrote:

> I am sorry, then I may have misunderstood you.
> 
> I would think that Herbert agreed that you push the entire patch set through 
> your tree, including the documentation changes to the crypto header files.
> 
> I just did a patch on the parts that touch the crypto header files. All apply 
> cleanly except patch 07/08 which has a 5 line hunk due to other changes, Is 
> that hunk ok for you, it would be great if you could take it. If you do not 
> like that hunk, we could push it through the cryptodev tree once rc-1 is out.

Clearly there was a bit of misunderstanding going around :)

I've applied the patch set to docs-next.  Oddly I had no trouble with #7,
but #2 was badly mailer-mangled and took some work.  

Anyway, it should make its way into linux-next; if there's no fireworks,
I'll endeavor to send it Linusward in time to avoid interfering with his
kitchen duties.

Sorry for the confusion,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-crypto" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/8] Conversion crypto API documentation to Sphinx

[Jonathan Corbet]

On Tue, 13 Dec 2016 22:25:07 +0100
Stephan Müller  wrote:

> Considering that a large batch of documentation updates just landed in Linus' 
> tree, I am wondering why the crypto API documentation update is not among it.

Well, I'd asked if I could run the documentation-specific parts through
docs-next.  I guess I was waiting for a version of the patch set with just
that, rather than intermixed with a bunch of crypto-side changes.  Were
you expecting me to take the whole set?

I can still try to do that, I guess; let me know if I should try to set
the whole set upward.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-crypto" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/8] Conversion crypto API documentation to Sphinx

[Jonathan Corbet]

On Fri, 21 Oct 2016 04:53:45 +0200
Stephan Mueller  wrote:

> the attached patch set converts the existing crypto API documentation
> from DocBook to Sphinx.

This looks generally good to me - thanks for doing it!

Is there any chance of running the Documentation/ parts through the docs
tree?  Documentation/index.rst has become a bit of a conflict point
otherwise...

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-crypto" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: crypto: warning cleanup

[Jonathan Corbet]

On Mon, 24 Aug 2015 06:51:35 +0200
Stephan Mueller smuel...@chronox.de wrote:

 This one is already in the cryptodev-2.6 kernel.
 
 From now on, I will always CC the linux-doc mailing list on patches 
 pertaining 
 the crypto documentation so that you can see the patches too.

Ah, OK, I should have peeked at linux-next first.

 + * @base: Common crypto API algorithm data structure  
 
 I am wondering: does this really fix the issue? I tried it and it failed 
 (i.e. 
 still produced errors by the parser) due to the exotic definition in of this 
 variable in the C code.

It fixes part of the issue.  The other required a change to kernel-doc,
which I've posted separately to linux-doc and plan to put in for 4.3.

Thanks,

jon
--
To unsubscribe from this list: send the line unsubscribe linux-crypto in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] doc: crypto: warning cleanup

[Jonathan Corbet]

Fix up a missing field description and a misdirected doc inclusion to make
a couple of warnings go away.

Signed-off-by: Jonathan Corbet cor...@lwn.net
---
 Documentation/DocBook/crypto-API.tmpl | 2 +-
 include/crypto/aead.h | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/DocBook/crypto-API.tmpl 
b/Documentation/DocBook/crypto-API.tmpl
index 0992531ffefb..980bcc994913 100644
--- a/Documentation/DocBook/crypto-API.tmpl
+++ b/Documentation/DocBook/crypto-API.tmpl
@@ -1687,7 +1687,7 @@ read(opfd, out, outlen);
 !Pinclude/linux/crypto.h Block Cipher Algorithm Definitions
 !Finclude/linux/crypto.h crypto_alg
 !Finclude/linux/crypto.h ablkcipher_alg
-!Finclude/linux/crypto.h aead_alg
+!Finclude/crypto/aead.h aead_alg
 !Finclude/linux/crypto.h blkcipher_alg
 !Finclude/linux/crypto.h cipher_alg
 !Finclude/crypto/rng.h rng_alg
diff --git a/include/crypto/aead.h b/include/crypto/aead.h
index 7169ad04acc0..88c6cdf3a886 100644
--- a/include/crypto/aead.h
+++ b/include/crypto/aead.h
@@ -120,6 +120,7 @@ struct aead_givcrypt_request {
  * @exit: Deinitialize the cryptographic transformation object. This is a
  *   counterpart to @init, used to remove various changes set in
  *   @init.
+ * @base: Common crypto API algorithm data structure
  *
  * All fields except @ivsize is mandatory and must be filled.
  */
-- 
2.4.3

--
To unsubscribe from this list: send the line unsubscribe linux-crypto in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec

[Jonathan Corbet]

On Sun, 02 Nov 2014 21:35:11 +0100
Stephan Mueller smuel...@chronox.de wrote:

 The design of the kernel crypto API as well as hints to program with
 the kernel crypto API are given.

Cool to see this, thanks.  Please forgive me if I go into full grumpy
editor mode here.  There's a lot of good information here, but I think it
could be made better with a bit of effort...

 diff --git a/Documentation/crypto/crypto-API-spec.txt 
 b/Documentation/crypto/crypto-API-spec.txt
 new file mode 100644
 index 000..8a24c98
 --- /dev/null
 +++ b/Documentation/crypto/crypto-API-spec.txt
 @@ -0,0 +1,721 @@
 +Kernel Crypto API Interface Specification
 +=
 +
 +The kernel crypto API offers a rich set of cryptographic ciphers as well as
 +other data transformation mechanisms and methods to invoke these. This 
 document
 +contains a description of the API and provides example code.
 +
 +To understand and properly use the kernel crypto API a brief explanation of 
 its
 +structure is given. Based on the architecture, the API can be separated into
 +different components. Following the architecture specification, hints to
 +developers of ciphers are provided. Pointers to the API function call
 +documentation are given at the end.
 +
 +The kernel crypto API refers to all algorithms as transformation. 
 Therefore, a

transformation*s*

 +cipher handle variable usually has the name tfm. Besides cryptographic
 +operations, the kernel crypto API also knows compression transforms and 
 handles
 +them the same way as ciphers.

Should that be s/transforms/transformations/ to keep the terminology
consistent? 

 +The kernel crypto API serves the following entity types:
 +
 + * consumers requesting cryptographic services
 +
 + * data transformation implementations (typically ciphers) that
 +   can be called by consumers using the kernel crypto API
 +
 +This specification is intended for consumers of the kernel crypto API as well
 +as for developers implementing ciphers. This API specification, however, does
 +not discusses all API calls available to data transformation implementations
 +((i.e. implementations of ciphers and other transformations (such as CRC or
 +even compression algorithms) that can register with the kernel crypto API).
 +
 +Note: The terms transformation and cipher algorithm are used 
 interchangably.
 +
 +
 +Terminology
 +---
 +
 +The transformation implementation is an actual code or interface to hardware
 +which implements a certain transformation with precisely defined behavior.
 +
 +The transformation object (TFM) is an instance of a transformation
 +implementation. There can be multiple transformation objects associated with
 +a single transformation implementation. Each of those transformation objects
 +is held by a crypto API consumer or another transformation. Transformation
 +object is allocated when a crypto API consumer requests a transformation
 +implementation. The consumer is then provided with a structure, which 
 contains
 +a transformation object (TFM).

It seems like it would be good to show what this object is and how to
allocate it here, rather than just teasing the reader saying it's possible? 

 +The transformation context is private data associated with the transformation
 +object.
 +
 +
 +Kernel Crypto API Architecture
 +==
 +
 +Cipher algorithm types
 +--
 +
 +The kernel crypto API provides different API calls for the following cipher
 +types:
 +
 + * Symmetric ciphers
 +
 + * AEAD ciphers
 +
 + * Message digest, including keyed message digest
 +
 + * Random number generation
 +
 + * User space interface
 +
 +
 +Ciphers and Templates
 +-
 +
 +The kernel crypto API provides implementations of single block ciphers and
 +message digests. In addition, the kernel crypto API provides numerous
 +templates that can be used in conjunction with the single block ciphers and
 +message digests. Templates include all types of block chaining mode, the HMAC
 +mechanism, etc.
 +
 +Single block ciphers and message digests can either be directly used by a
 +caller or invoked together with a template to form multi-block ciphers or 
 keyed
 +message digests.
 +
 +A single block cipher may even be called with multiple templates. However,
 +templates cannot be used without a single cipher.
 +
 +
 +Synchronous and asynchronous operation
 +--
 +
 +The kernel crypto API provides synchronous and asynchronous API operations.
 +
 +When using the synchronous API operation, the caller invokes a cipher 
 operation
 +which is performed synchronously by the kernel crypto API. That means, the
 +caller waits until the cipher operation completes. Therefore, the kernel 
 crypto
 +API calls work like regular function calls. For synchronous operation, the 
 set
 +of API calls is small and conceptually similar to any other crypto library.
 +
 

Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec

[Jonathan Corbet]

On Mon, 03 Nov 2014 15:18:29 +0100
Stephan Mueller smuel...@chronox.de wrote:

  These are all useful.  But I wonder if it would be worth the effort to turn
  this inti a proper docbook document that automatically has everything
  together in one place?  
 
 How do you suggest that is done?

See Documentation/kernel-doc-nano-HOWTO.txt for an introduction to the
process.  This documentation hasn't seen a lot of maintenance recently,
but I don't think things have changed too much.  Should check that when I
get a chance...

Thanks,

jon
--
To unsubscribe from this list: send the line unsubscribe linux-crypto in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html