From: Kees Cook <keescook@chromium.org>
To: linux-kernel@vger.kernel.org
Cc: Kees Cook <keescook@chromium.org>,
Nobuhiro Iwamatsu <nobuhiro.iwamatsu.kw@hitachi.com>,
Qiuxu Zhuo <qiuxu.zhuo@intel.com>,
Ard Biesheuvel <ard.biesheuvel@linaro.org>,
Anton Vorontsov <anton@enomsg.org>,
Colin Cross <ccross@android.com>, Tony Luck <tony.luck@intel.com>,
Benjamin Herrenschmidt <benh@kernel.crashing.org>,
Paul Mackerras <paulus@samba.org>,
Michael Ellerman <mpe@ellerman.id.au>,
"Rafael J. Wysocki" <rjw@rjwysocki.net>,
Len Brown <lenb@kernel.org>,
Matt Fleming <matt@codeblueprint.co.uk>,
Nathan Fontenot <nfont@linux.vnet.ibm.com>,
Pan Xinhui <xinhui.pan@linux.vnet.ibm.com>,
Daniel Axtens <dja@axtens.net>,
Paul Gortmaker <paul.gortmaker@windriver.com>,
Geliang Tang <geliangtang@163.com>,
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 [thread overview]
Message-ID: <1488837332-71582-6-git-send-email-keescook@chromium.org> (raw)
In-Reply-To: <1488837332-71582-1-git-send-email-keescook@chromium.org>
This adds documentation for struct pstore_info, which also includes
the basic API the backends need to implement.
Signed-off-by: Kees Cook <keescook@chromium.org>
---
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 <linux/time.h>
#include <linux/types.h>
-/* 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)
--
2.7.4
next prev parent reply other threads:[~2017-03-06 21:55 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-03-06 21:55 [PATCH 00/18] pstore: refactor internal APIs Kees Cook
2017-03-06 21:55 ` [PATCH 01/18] pstore: Use dynamic spinlock initializer Kees Cook
2017-03-06 21:55 ` [PATCH 02/18] pstore: Shut down worker when unregistering Kees Cook
2017-03-06 21:55 ` [PATCH 03/18] pstore: Avoid race in module unloading Kees Cook
2017-03-07 16:16 ` Namhyung Kim
2017-03-07 16:18 ` Kees Cook
2017-03-06 21:55 ` [PATCH 04/18] pstore: Improve register_pstore() error reporting Kees Cook
2017-03-06 21:55 ` Kees Cook [this message]
2017-03-06 21:55 ` [PATCH 06/18] pstore: Extract common arguments into structure Kees Cook
2017-03-07 16:22 ` Namhyung Kim
2017-03-07 19:31 ` Kees Cook
2017-03-06 21:55 ` [PATCH 07/18] pstore: Move record decompression to function Kees Cook
2017-03-06 21:55 ` [PATCH 08/18] pstore: Switch pstore_mkfile to pass record Kees Cook
2017-03-06 21:55 ` [PATCH 09/18] pstore: Replace arguments for read() API Kees Cook
2017-03-06 21:55 ` [PATCH 10/18] pstore: Replace arguments for write() API Kees Cook
2017-03-06 21:55 ` [PATCH 11/18] pstore: Always allocate buffer for decompression Kees Cook
2017-03-06 21:55 ` [PATCH 12/18] pstore: Pass record contents instead of copying Kees Cook
2017-03-06 21:55 ` [PATCH 13/18] pstore: Allocate records on heap instead of stack Kees Cook
2017-03-06 21:55 ` [PATCH 14/18] pstore: Do not duplicate record metadata Kees Cook
2017-03-06 21:55 ` [PATCH 15/18] pstore: Replace arguments for erase() API Kees Cook
2017-03-06 21:55 ` [PATCH 16/18] pstore: Replace arguments for write_buf() API Kees Cook
2017-03-06 21:55 ` [PATCH 17/18] pstore: Replace arguments for write_buf_user() API Kees Cook
2017-03-06 21:55 ` [PATCH 18/18] pstore: Remove write_buf() callback Kees Cook
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1488837332-71582-6-git-send-email-keescook@chromium.org \
--to=keescook@chromium.org \
--cc=anton@enomsg.org \
--cc=ard.biesheuvel@linaro.org \
--cc=benh@kernel.crashing.org \
--cc=ccross@android.com \
--cc=dja@axtens.net \
--cc=geliangtang@163.com \
--cc=lenb@kernel.org \
--cc=linux-acpi@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-efi@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linuxppc-dev@lists.ozlabs.org \
--cc=matt@codeblueprint.co.uk \
--cc=mpe@ellerman.id.au \
--cc=nfont@linux.vnet.ibm.com \
--cc=nobuhiro.iwamatsu.kw@hitachi.com \
--cc=paul.gortmaker@windriver.com \
--cc=paulus@samba.org \
--cc=qiuxu.zhuo@intel.com \
--cc=rjw@rjwysocki.net \
--cc=tony.luck@intel.com \
--cc=xinhui.pan@linux.vnet.ibm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).