From patchwork Mon Mar 6 21:55:19 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kees Cook X-Patchwork-Id: 9607779 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 9E423604DD for ; Mon, 6 Mar 2017 22:27:55 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id E7D6B2793B for ; Mon, 6 Mar 2017 22:27:55 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id DC9472846C; Mon, 6 Mar 2017 22:27:55 +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.3 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI, RCVD_IN_SORBS_SPAM, T_DKIM_INVALID autolearn=unavailable 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 61E722815E for ; Mon, 6 Mar 2017 22:27:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932169AbdCFW1y (ORCPT ); Mon, 6 Mar 2017 17:27:54 -0500 Received: from mail-pf0-f174.google.com ([209.85.192.174]:34066 "EHLO mail-pf0-f174.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754364AbdCFW1r (ORCPT ); Mon, 6 Mar 2017 17:27:47 -0500 Received: by mail-pf0-f174.google.com with SMTP id v190so29033943pfb.1 for ; Mon, 06 Mar 2017 14:27:06 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=m4IG+VsSTrGlNkn89+eTchEEBx6KtRB1qOG4wQhvYss=; b=i4BPpHZCIahyUganCUAfHmgWgOpOsZn/teOAukwxr2X1m5zhfJi/ozhDKubRUiMTRN 0/frUWmHUnmmG4B2/0dl/hq6xPFQSg5vkzy22NbCglfSD/HgrQVWMg4hoYsRHbrII+DV mJxjozJles0HsxzMQuYI+BtO1dX0yfnd5n+O8= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=m4IG+VsSTrGlNkn89+eTchEEBx6KtRB1qOG4wQhvYss=; b=m5Ez/imZfDNQEqWi85rcNwxsH2HSbg6dJZbyDDqsIROL2DvJBenS4WfKIoenIaHTr2 Dxn/xHJcdwFPuWQzXeVvw+KYCANp/Bi0r2DnNH4njckAKPVsNuw7p14WutdVt4B3O9iz 3My3E0Zpaj+q7dz2hkglPXlJfgJQF74JOrS2LMOcxMQzLCBbB2LxE98RttA3VDUJgKh6 e4FN1DxV21wPVPVp2HCMhgnhEDG1TtVF9/gF4GWdLlg23PCaPCwgK3pQOkbF655q7kqd md9NAVzqsiOLAVqV3oVZNKBMr9rIKGgycMjirwFfw8SvWsKd3ydib/TP8k/fXY+GvcNa 5mOA== X-Gm-Message-State: AMke39lRjBaAIhCgfqUbgVwWvT2qpZ7nWC953GFEQEc+JG5LTkJi/c3ufFEPg5FDJW8OLj5U X-Received: by 10.98.112.134 with SMTP id l128mr23870255pfc.81.1488837340425; Mon, 06 Mar 2017 13:55:40 -0800 (PST) Received: from www.outflux.net ([2002:ada4:7085:0:205a:2b55:4e6d:7d63]) by smtp.gmail.com with ESMTPSA id 90sm29006612pfl.24.2017.03.06.13.55.37 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 06 Mar 2017 13:55:38 -0800 (PST) From: Kees Cook To: linux-kernel@vger.kernel.org Cc: Kees Cook , Nobuhiro Iwamatsu , Qiuxu Zhuo , Ard Biesheuvel , Anton Vorontsov , Colin Cross , Tony Luck , Benjamin Herrenschmidt , Paul Mackerras , Michael Ellerman , "Rafael J. Wysocki" , Len Brown , Matt Fleming , Nathan Fontenot , Pan Xinhui , Daniel Axtens , Paul Gortmaker , Geliang Tang , linuxppc-dev@lists.ozlabs.org, linux-acpi@vger.kernel.org, linux-efi@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 05/18] pstore: Add kernel-doc for struct pstore_info Date: Mon, 6 Mar 2017 13:55:19 -0800 Message-Id: <1488837332-71582-6-git-send-email-keescook@chromium.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1488837332-71582-1-git-send-email-keescook@chromium.org> References: <1488837332-71582-1-git-send-email-keescook@chromium.org> Sender: linux-acpi-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-acpi@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This adds documentation for struct pstore_info, which also includes the basic API the backends need to implement. Signed-off-by: Kees Cook --- include/linux/pstore.h | 133 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 128 insertions(+), 5 deletions(-) diff --git a/include/linux/pstore.h b/include/linux/pstore.h index 0da29cae009b..083b10bacd4a 100644 --- a/include/linux/pstore.h +++ b/include/linux/pstore.h @@ -30,7 +30,7 @@ #include #include -/* types */ +/* pstore record types (see fs/pstore/inode.c for filename templates) */ enum pstore_type_id { PSTORE_TYPE_DMESG = 0, PSTORE_TYPE_MCE = 1, @@ -47,14 +47,138 @@ enum pstore_type_id { struct module; +/** + * struct pstore_info - backend pstore driver structure + * + * @owner: module which is repsonsible for this backend driver + * @name: name of the backend driver + * + * @buf_lock: spinlock to serialize access to @buf + * @buf: preallocated crash dump buffer + * @bufsize: size of @buf available for crash dump writes + * + * @read_mutex: mutex to serialize @open, @read, and @close callbacks + * @flags: bitfield of frontends the backend can accept writes for + * @data: backend-private pointer passed back during callbacks + * + * Callbacks: + * + * @open: + * Notify backend that pstore is starting a full read of backend + * records. Followed by one or more @read calls, and a final @close. + * + * @psi: in: pointer to the struct pstore_info for the backend + * + * Returns 0 on success, and non-zero on error. + * + * @close: + * Notify backend that pstore has finished a full read of backend + * records. Always preceded by an @open call and one or more @read + * calls. + * + * @psi: in: pointer to the struct pstore_info for the backend + * + * Returns 0 on success, and non-zero on error. (Though pstore will + * ignore the error.) + * + * @read: + * Read next available backend record. Called after a successful + * @open. + * + * @id: out: unique identifier for the record + * @type: out: pstore record type + * @count: out: for PSTORE_TYPE_DMESG, the Oops count. + * @time: out: timestamp for the record + * @buf: out: kmalloc copy of record contents, to be freed by pstore + * @compressed: + * out: if the record contents are compressed + * @ecc_notice_size: + * out: ECC information + * @psi: in: pointer to the struct pstore_info for the backend + * + * Returns record size on success, zero when no more records are + * available, or negative on error. + * + * @write: + * Perform a frontend notification of a write to a backend record. The + * data to be stored has already been written to the registered @buf + * of the @psi structure. + * + * @type: in: pstore record type to write + * @reason: + * in: pstore write reason + * @id: out: unique identifier for the record + * @part: in: position in a multipart write + * @count: in: increasing from 0 since boot, the number of this Oops + * @compressed: + * in: if the record is compressed + * @size: in: size of the write + * @psi: in: pointer to the struct pstore_info for the backend + * + * Returns 0 on success, and non-zero on error. + * + * @write_buf: + * Perform a frontend write to a backend record, using a specified + * buffer. Unlike @write, this does not use the @psi @buf. + * + * @type: in: pstore record type to write + * @reason: + * in: pstore write reason + * @id: out: unique identifier for the record + * @part: in: position in a multipart write + * @buf: in: pointer to contents to write to backend record + * @compressed: + * in: if the record is compressed + * @size: in: size of the write + * @psi: in: pointer to the struct pstore_info for the backend + * + * Returns 0 on success, and non-zero on error. + * + * @write_buf_user: + * Perform a frontend write to a backend record, using a specified + * buffer that is coming directly from userspace. + * + * @type: in: pstore record type to write + * @reason: + * in: pstore write reason + * @id: out: unique identifier for the record + * @part: in: position in a multipart write + * @buf: in: pointer to userspace contents to write to backend record + * @compressed: + * in: if the record is compressed + * @size: in: size of the write + * @psi: in: pointer to the struct pstore_info for the backend + * + * Returns 0 on success, and non-zero on error. + * + * @erase: + * Delete a record from backend storage. Different backends + * identify records differently, so all possible methods of + * identification are included to help the backend locate the + * record to remove. + * + * @type: in: pstore record type to write + * @id: in: per-type unique identifier for the record + * @count: in: Oops count + * @time: in: timestamp for the record + * @psi: in: pointer to the struct pstore_info for the backend + * + * Returns 0 on success, and non-zero on error. + * + */ struct pstore_info { struct module *owner; char *name; - spinlock_t buf_lock; /* serialize access to 'buf' */ + + spinlock_t buf_lock; char *buf; size_t bufsize; - struct mutex read_mutex; /* serialize open/read/close */ + + struct mutex read_mutex; + int flags; + void *data; + int (*open)(struct pstore_info *psi); int (*close)(struct pstore_info *psi); ssize_t (*read)(u64 *id, enum pstore_type_id *type, @@ -76,11 +200,10 @@ struct pstore_info { int (*erase)(enum pstore_type_id type, u64 id, int count, struct timespec time, struct pstore_info *psi); - void *data; }; +/* Supported frontends */ #define PSTORE_FLAGS_DMESG (1 << 0) -#define PSTORE_FLAGS_FRAGILE PSTORE_FLAGS_DMESG #define PSTORE_FLAGS_CONSOLE (1 << 1) #define PSTORE_FLAGS_FTRACE (1 << 2) #define PSTORE_FLAGS_PMSG (1 << 3)