include/linux/pstore.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Persistent Storage - pstore.h
0004  *
0005  * Copyright (C) 2010 Intel Corporation <tony.luck@intel.com>
0006  *
0007  * This code is the generic layer to export data records from platform
0008  * level persistent storage via a file system.
0009  */
0010 #ifndef _LINUX_PSTORE_H
0011 #define _LINUX_PSTORE_H
0012
0013 #include <linux/compiler.h>
0014 #include <linux/errno.h>
0015 #include <linux/kmsg_dump.h>
0016 #include <linux/mutex.h>
0017 #include <linux/spinlock.h>
0018 #include <linux/time.h>
0019 #include <linux/types.h>
0020
0021 struct module;
0022
0023 /*
0024  * pstore record types (see fs/pstore/platform.c for pstore_type_names[])
0025  * These values may be written to storage (see EFI vars backend), so
0026  * they are kind of an ABI. Be careful changing the mappings.
0027  */
0028 enum pstore_type_id {
0029     /* Frontend storage types */
0030     PSTORE_TYPE_DMESG   = 0,
0031     PSTORE_TYPE_MCE     = 1,
0032     PSTORE_TYPE_CONSOLE = 2,
0033     PSTORE_TYPE_FTRACE  = 3,
0034
0035     /* PPC64-specific partition types */
0036     PSTORE_TYPE_PPC_RTAS    = 4,
0037     PSTORE_TYPE_PPC_OF  = 5,
0038     PSTORE_TYPE_PPC_COMMON  = 6,
0039     PSTORE_TYPE_PMSG    = 7,
0040     PSTORE_TYPE_PPC_OPAL    = 8,
0041
0042     /* End of the list */
0043     PSTORE_TYPE_MAX
0044 };
0045
0046 const char *pstore_type_to_name(enum pstore_type_id type);
0047 enum pstore_type_id pstore_name_to_type(const char *name);
0048
0049 struct pstore_info;
0050 /**
0051  * struct pstore_record - details of a pstore record entry
0052  * @psi:    pstore backend driver information
0053  * @type:   pstore record type
0054  * @id:     per-type unique identifier for record
0055  * @time:   timestamp of the record
0056  * @buf:    pointer to record contents
0057  * @size:   size of @buf
0058  * @ecc_notice_size:
0059  *      ECC information for @buf
0060  * @priv:   pointer for backend specific use, will be
0061  *      kfree()d by the pstore core if non-NULL
0062  *      when the record is freed.
0063  *
0064  * Valid for PSTORE_TYPE_DMESG @type:
0065  *
0066  * @count:  Oops count since boot
0067  * @reason: kdump reason for notification
0068  * @part:   position in a multipart record
0069  * @compressed: whether the buffer is compressed
0070  *
0071  */
0072 struct pstore_record {
0073     struct pstore_info  *psi;
0074     enum pstore_type_id type;
0075     u64         id;
0076     struct timespec64   time;
0077     char            *buf;
0078     ssize_t         size;
0079     ssize_t         ecc_notice_size;
0080     void            *priv;
0081
0082     int         count;
0083     enum kmsg_dump_reason   reason;
0084     unsigned int        part;
0085     bool            compressed;
0086 };
0087
0088 /**
0089  * struct pstore_info - backend pstore driver structure
0090  *
0091  * @owner:  module which is responsible for this backend driver
0092  * @name:   name of the backend driver
0093  *
0094  * @buf_lock:   spinlock to serialize access to @buf
0095  * @buf:    preallocated crash dump buffer
0096  * @bufsize:    size of @buf available for crash dump bytes (must match
0097  *      smallest number of bytes available for writing to a
0098  *      backend entry, since compressed bytes don't take kindly
0099  *      to being truncated)
0100  *
0101  * @read_mutex: serializes @open, @read, @close, and @erase callbacks
0102  * @flags:  bitfield of frontends the backend can accept writes for
0103  * @max_reason: Used when PSTORE_FLAGS_DMESG is set. Contains the
0104  *      kmsg_dump_reason enum value. KMSG_DUMP_UNDEF means
0105  *      "use existing kmsg_dump() filtering, based on the
0106  *      printk.always_kmsg_dump boot param" (which is either
0107  *      KMSG_DUMP_OOPS when false, or KMSG_DUMP_MAX when
0108  *      true); see printk.always_kmsg_dump for more details.
0109  * @data:   backend-private pointer passed back during callbacks
0110  *
0111  * Callbacks:
0112  *
0113  * @open:
0114  *  Notify backend that pstore is starting a full read of backend
0115  *  records. Followed by one or more @read calls, and a final @close.
0116  *
0117  *  @psi:   in: pointer to the struct pstore_info for the backend
0118  *
0119  *  Returns 0 on success, and non-zero on error.
0120  *
0121  * @close:
0122  *  Notify backend that pstore has finished a full read of backend
0123  *  records. Always preceded by an @open call and one or more @read
0124  *  calls.
0125  *
0126  *  @psi:   in: pointer to the struct pstore_info for the backend
0127  *
0128  *  Returns 0 on success, and non-zero on error. (Though pstore will
0129  *  ignore the error.)
0130  *
0131  * @read:
0132  *  Read next available backend record. Called after a successful
0133  *  @open.
0134  *
0135  *  @record:
0136  *      pointer to record to populate. @buf should be allocated
0137  *      by the backend and filled. At least @type and @id should
0138  *      be populated, since these are used when creating pstorefs
0139  *      file names.
0140  *
0141  *  Returns record size on success, zero when no more records are
0142  *  available, or negative on error.
0143  *
0144  * @write:
0145  *  A newly generated record needs to be written to backend storage.
0146  *
0147  *  @record:
0148  *      pointer to record metadata. When @type is PSTORE_TYPE_DMESG,
0149  *      @buf will be pointing to the preallocated @psi.buf, since
0150  *      memory allocation may be broken during an Oops. Regardless,
0151  *      @buf must be proccesed or copied before returning. The
0152  *      backend is also expected to write @id with something that
0153  *      can help identify this record to a future @erase callback.
0154  *      The @time field will be prepopulated with the current time,
0155  *      when available. The @size field will have the size of data
0156  *      in @buf.
0157  *
0158  *  Returns 0 on success, and non-zero on error.
0159  *
0160  * @write_user:
0161  *  Perform a frontend write to a backend record, using a specified
0162  *  buffer that is coming directly from userspace, instead of the
0163  *  @record @buf.
0164  *
0165  *  @record:    pointer to record metadata.
0166  *  @buf:       pointer to userspace contents to write to backend
0167  *
0168  *  Returns 0 on success, and non-zero on error.
0169  *
0170  * @erase:
0171  *  Delete a record from backend storage.  Different backends
0172  *  identify records differently, so entire original record is
0173  *  passed back to assist in identification of what the backend
0174  *  should remove from storage.
0175  *
0176  *  @record:    pointer to record metadata.
0177  *
0178  *  Returns 0 on success, and non-zero on error.
0179  *
0180  */
0181 struct pstore_info {
0182     struct module   *owner;
0183     const char  *name;
0184
0185     spinlock_t  buf_lock;
0186     char        *buf;
0187     size_t      bufsize;
0188
0189     struct mutex    read_mutex;
0190
0191     int     flags;
0192     int     max_reason;
0193     void        *data;
0194
0195     int     (*open)(struct pstore_info *psi);
0196     int     (*close)(struct pstore_info *psi);
0197     ssize_t     (*read)(struct pstore_record *record);
0198     int     (*write)(struct pstore_record *record);
0199     int     (*write_user)(struct pstore_record *record,
0200                       const char __user *buf);
0201     int     (*erase)(struct pstore_record *record);
0202 };
0203
0204 /* Supported frontends */
0205 #define PSTORE_FLAGS_DMESG  BIT(0)
0206 #define PSTORE_FLAGS_CONSOLE    BIT(1)
0207 #define PSTORE_FLAGS_FTRACE BIT(2)
0208 #define PSTORE_FLAGS_PMSG   BIT(3)
0209
0210 extern int pstore_register(struct pstore_info *);
0211 extern void pstore_unregister(struct pstore_info *);
0212
0213 struct pstore_ftrace_record {
0214     unsigned long ip;
0215     unsigned long parent_ip;
0216     u64 ts;
0217 };
0218
0219 /*
0220  * ftrace related stuff: Both backends and frontends need these so expose
0221  * them here.
0222  */
0223
0224 #if NR_CPUS <= 2 && defined(CONFIG_ARM_THUMB)
0225 #define PSTORE_CPU_IN_IP 0x1
0226 #elif NR_CPUS <= 4 && defined(CONFIG_ARM)
0227 #define PSTORE_CPU_IN_IP 0x3
0228 #endif
0229
0230 #define TS_CPU_SHIFT 8
0231 #define TS_CPU_MASK (BIT(TS_CPU_SHIFT) - 1)
0232
0233 /*
0234  * If CPU number can be stored in IP, store it there, otherwise store it in
0235  * the time stamp. This means more timestamp resolution is available when
0236  * the CPU can be stored in the IP.
0237  */
0238 #ifdef PSTORE_CPU_IN_IP
0239 static inline void
0240 pstore_ftrace_encode_cpu(struct pstore_ftrace_record *rec, unsigned int cpu)
0241 {
0242     rec->ip |= cpu;
0243 }
0244
0245 static inline unsigned int
0246 pstore_ftrace_decode_cpu(struct pstore_ftrace_record *rec)
0247 {
0248     return rec->ip & PSTORE_CPU_IN_IP;
0249 }
0250
0251 static inline u64
0252 pstore_ftrace_read_timestamp(struct pstore_ftrace_record *rec)
0253 {
0254     return rec->ts;
0255 }
0256
0257 static inline void
0258 pstore_ftrace_write_timestamp(struct pstore_ftrace_record *rec, u64 val)
0259 {
0260     rec->ts = val;
0261 }
0262 #else
0263 static inline void
0264 pstore_ftrace_encode_cpu(struct pstore_ftrace_record *rec, unsigned int cpu)
0265 {
0266     rec->ts &= ~(TS_CPU_MASK);
0267     rec->ts |= cpu;
0268 }
0269
0270 static inline unsigned int
0271 pstore_ftrace_decode_cpu(struct pstore_ftrace_record *rec)
0272 {
0273     return rec->ts & TS_CPU_MASK;
0274 }
0275
0276 static inline u64
0277 pstore_ftrace_read_timestamp(struct pstore_ftrace_record *rec)
0278 {
0279     return rec->ts >> TS_CPU_SHIFT;
0280 }
0281
0282 static inline void
0283 pstore_ftrace_write_timestamp(struct pstore_ftrace_record *rec, u64 val)
0284 {
0285     rec->ts = (rec->ts & TS_CPU_MASK) | (val << TS_CPU_SHIFT);
0286 }
0287 #endif
0288
0289 #endif /*_LINUX_PSTORE_H*/