From patchwork Wed Aug 17 22:47:11 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 9286667 X-Patchwork-Delegate: herbert@gondor.apana.org.au Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 7755860839 for ; Wed, 17 Aug 2016 22:50:14 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 65C242933E for ; Wed, 17 Aug 2016 22:50:14 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 5570B29359; Wed, 17 Aug 2016 22:50:14 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.8 required=2.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, RCVD_IN_DNSWL_HI, T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id EA0262933E for ; Wed, 17 Aug 2016 22:50:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753582AbcHQWuM (ORCPT ); Wed, 17 Aug 2016 18:50:12 -0400 Received: from mail-pa0-f52.google.com ([209.85.220.52]:33538 "EHLO mail-pa0-f52.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753186AbcHQWuL (ORCPT ); Wed, 17 Aug 2016 18:50:11 -0400 Received: by mail-pa0-f52.google.com with SMTP id ti13so585825pac.0 for ; Wed, 17 Aug 2016 15:50:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=from:to:cc:subject:date:message-id; bh=nFWxlFzO1gVGgpf4rvbLyIZCZL+6ul/nHRd6N2htaiE=; b=QRJg6FLH/kq7eQbp37PGamRtceRigdW21uCIzmZAAd99WetVBKpvcX16Gw1cm9gigf KFdpv1ZFnWB4xaHh+JAl3mUfqMTQlHePFJd2GENGN8YfFDMD3LJySn/x6e0UB8HOsh5C 9UJpAeGsEVOz+aVl5PpmLh1FDs9edtOI63fpl4QQwBQPFl1OGXHcVpyHtIGsiK5eJN9D TjK4/7byB/04Ao6TP1QYRFt3ToWwimuZE8G3vEb3d7p8/jueutezOpdR9ZZa2+fQJc/q aaYj8B0nShDegCLa2QXPpBxxuSSCTXVjrqoYDwSaupPyYtBI0WPlGJk5QqcAWvl1V+Rc 5n/Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=nFWxlFzO1gVGgpf4rvbLyIZCZL+6ul/nHRd6N2htaiE=; b=DHWPZDBOpdYGHRusMHiTSdqg8U+kSsAoVs/os0eqzAIFiWW7FP26wl44CCXV8v6jDd Yq8/F1J8xdZy3qfig45myJcPYDQ2OsAmRruQPSiIMo8oE/cNAwtwLT7I3+JFHOX5WhSq hwIkFYuwKtiXhBsGZ0YlCrgmm14wfHOee/UD9MYdX26LqrmE4GYDwqsi0fz9DlKaDuTm Ha2FIAHBDXjg27xzwxSefQJtqCjKQnHwJTyo7h+h/pEsIC2SokZMHY4JlbJMPRcvlmRo LylYCGv8GMYcPLQUy5yXb6P7d+UOnKawOvlcSYGHySRXDXD5BHM1SKjObOVRL6G/T6E7 0UQQ== X-Gm-Message-State: AEkoouvM2f4Pn/MGtyUcZXqL0IdsRONXsIoqUm/n5UokDjqRbseKuEJ/ROpy3dV0oTrtJAl3 X-Received: by 10.66.248.165 with SMTP id yn5mr80014214pac.44.1471474210768; Wed, 17 Aug 2016 15:50:10 -0700 (PDT) Received: from ebiggers-linuxstation.kir.corp.google.com ([172.23.164.123]) by smtp.gmail.com with ESMTPSA id y6sm1164208pav.1.2016.08.17.15.50.06 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 17 Aug 2016 15:50:09 -0700 (PDT) From: Eric Biggers To: herbert@gondor.apana.org.au Cc: davem@davemloft.net, linux-crypto@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Eric Biggers Subject: [PATCH] crypto: doc - fix documentation for bulk registration functions Date: Wed, 17 Aug 2016 15:47:11 -0700 Message-Id: <1471474031-87352-1-git-send-email-ebiggers@google.com> X-Mailer: git-send-email 2.8.0.rc3.226.g39d4020 Sender: linux-crypto-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Update the documentation for crypto_register_algs() and crypto_unregister_algs() to match the actual behavior. Signed-off-by: Eric Biggers --- Documentation/DocBook/crypto-API.tmpl | 38 ++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl index fb2a152..088b79c 100644 --- a/Documentation/DocBook/crypto-API.tmpl +++ b/Documentation/DocBook/crypto-API.tmpl @@ -797,7 +797,8 @@ kernel crypto API | Caller include/linux/crypto.h and their definition can be seen below. The former function registers a single transformation, while the latter works on an array of transformation descriptions. - The latter is useful when registering transformations in bulk. + The latter is useful when registering transformations in bulk, + for example when a driver implements multiple transformations. @@ -822,18 +823,31 @@ kernel crypto API | Caller - The bulk registration / unregistration functions require - that struct crypto_alg is an array of count size. These - functions simply loop over that array and register / - unregister each individual algorithm. If an error occurs, - the loop is terminated at the offending algorithm definition. - That means, the algorithms prior to the offending algorithm - are successfully registered. Note, the caller has no way of - knowing which cipher implementations have successfully - registered. If this is important to know, the caller should - loop through the different implementations using the single - instance *_alg functions for each individual implementation. + The bulk registration/unregistration functions + register/unregister each transformation in the given array of + length count. They handle errors as follows: + + + + crypto_register_algs() succeeds if and only if it + successfully registers all the given transformations. If an + error occurs partway through, then it rolls back successful + registrations before returning the error code. Note that if + a driver needs to handle registration errors for individual + transformations, then it will need to use the non-bulk + function crypto_register_alg() instead. + + + + + crypto_unregister_algs() tries to unregister all the given + transformations, continuing on error. It logs errors and + always returns zero. + + + + Single-Block Symmetric Ciphers [CIPHER]