Introduction¶

pstore block (pstore/blk) is an oops/panic logger that writes its logs to ablock device and non-block device before the system crashes. You can getthese log files by mounting pstore filesystem like:

mount -t pstore pstore /sys/fs/pstore

pstore block concepts¶

pstore/blk provides efficient configuration method for pstore/blk, whichdivides all configurations into two parts, configurations for user andconfigurations for driver.

Configurations for user determine how pstore/blk works, such as pmsg_size,kmsg_size and so on. All of them support both Kconfig and module parameters,but module parameters have priority over Kconfig.

Configurations for driver are all about block device and non-block device,such as total_size of block device and read/write operations.

Configurations for user¶

All of these configurations support both Kconfig and module parameters, butmodule parameters have priority over Kconfig.

Here is an example for module parameters:

pstore_blk.blkdev=/dev/mmcblk0p7 pstore_blk.kmsg_size=64 best_effort=y

The detail of each configurations may be of interest to you.

# mount -t pstore pstore /sys/fs/pstore# mount -t debugfs debugfs /sys/kernel/debug/# echo 1 > /sys/kernel/debug/pstore/record_ftrace# reboot -f[...]# mount -t pstore pstore /sys/fs/pstore# tail /sys/fs/pstore/ftrace-pstore-blk-0CPU:0 ts:5914676 c0063828  c0063b94  call_cpuidle <- cpu_startup_entry+0x1b8/0x1e0CPU:0 ts:5914678 c039ecdc  c006385c  cpuidle_enter_state <- call_cpuidle+0x44/0x48CPU:0 ts:5914680 c039e9a0  c039ecf0  cpuidle_enter_freeze <- cpuidle_enter_state+0x304/0x314CPU:0 ts:5914681 c0063870  c039ea30  sched_idle_set_state <- cpuidle_enter_state+0x44/0x314CPU:1 ts:5916720 c0160f59  c015ee04  kernfs_unmap_bin_file <- __kernfs_remove+0x140/0x204CPU:1 ts:5916721 c05ca625  c015ee0c  __mutex_lock_slowpath <- __kernfs_remove+0x148/0x204CPU:1 ts:5916723 c05c813d  c05ca630  yield_to <- __mutex_lock_slowpath+0x314/0x358CPU:1 ts:5916724 c05ca2d1  c05ca638  __ww_mutex_lock <- __mutex_lock_slowpath+0x31c/0x358

Configurations for driver¶

A device driver usesregister_pstore_device withstructpstore_device_info to register to pstore/blk.

intregister_pstore_device(structpstore_device_info*dev)¶

register non-block device to pstore/blk

voidunregister_pstore_device(structpstore_device_info*dev)¶

unregister non-block device from pstore/blk

Compression and header¶

Block device is large enough for uncompressed oops data. Actually we do notrecommend data compression because pstore/blk will insert some information intothe first line of oops/panic data. For example:

Panic: Total 16 times

It means that it’s OOPS|Panic for the 16th time since the first booting.Sometimes the number of occurrences of oops|panic since the first booting isimportant to judge whether the system is stable.

The following line is inserted by pstore filesystem. For example:

Oops#2 Part1

It means that it’s OOPS for the 2nd time on the last boot.

Reading the data¶

The dump data can be read from the pstore filesystem. The format for thesefiles isdmesg-pstore-blk-[N] for oops/panic front-end,pmsg-pstore-blk-0 for pmsg front-end and so on. The timestamp of thedump file records the trigger time. To delete a stored record from blockdevice, simply unlink the respective pstore file.

Attentions in panic read/write APIs¶

If on panic, the kernel is not going to run for much longer, the tasks will notbe scheduled and most kernel resources will be out of service. Itlooks like a single-threaded program running on a single-core computer.

The following points require special attention for panic read/write APIs:

1. CanNOT allocate any memory.If you need memory, just allocate while the block driver is initializingrather than waiting until the panic.

2. Must be polled,NOT interrupt driven.No task schedule any more. The block driver should delay to ensure the writesucceeds, but NOT sleep.

3. CanNOT take any lock.There is no other task, nor any shared resource; you are safe to break alllocks.

4. Just use CPU to transfer.Do not use DMA to transfer unless you are sure that DMA will not keep lock.

5. Control registers directly.Please control registers directly rather than use Linux kernel resources.Do I/O map while initializing rather than wait until a panic occurs.

6. Reset your block device and controller if necessary.If you are not sure of the state of your block device and controller whena panic occurs, you are safe to stop and reset them.

pstore/blk supportspsblk_blkdev_info(), which is defined inlinux/pstore_blk.h, to get information of using block device, such as thedevice number, sector count and start sector of the whole disk.

pstore block internals¶

For developer reference, here are all the important structures and APIs:

structpsz_buffer¶

header of zone to flush to storage

struct psz_buffer {#define PSZ_SIG (0x43474244);    uint32_t sig;    atomic_t datalen;    atomic_t start;    uint8_t data[];};

structpsz_kmsg_header¶

kmsg dump-specific header to flush to storage

struct psz_kmsg_header {#define PSTORE_KMSG_HEADER_MAGIC 0x4dfc3ae5;    uint32_t magic;    struct timespec64 time;    bool compressed;    uint32_t counter;    enum kmsg_dump_reason reason;    uint8_t data[];};

Description

This is a sub-header for a kmsg dump, trailing afterpsz_buffer.

structpstore_zone¶

single stored buffer

struct pstore_zone {    loff_t off;    const char *name;    enum pstore_type_id type;    struct psz_buffer *buffer;    struct psz_buffer *oldbuf;    size_t buffer_size;    bool should_recover;    atomic_t dirty;};

Description

zone structure in memory.

structpsz_context¶

all about running state of pstore/zone

struct psz_context {    struct pstore_zone **kpszs;    struct pstore_zone *ppsz;    struct pstore_zone *cpsz;    struct pstore_zone **fpszs;    unsigned int kmsg_max_cnt;    unsigned int kmsg_read_cnt;    unsigned int kmsg_write_cnt;    unsigned int pmsg_read_cnt;    unsigned int console_read_cnt;    unsigned int ftrace_max_cnt;    unsigned int ftrace_read_cnt;    unsigned int oops_counter;    unsigned int panic_counter;    atomic_t recovered;    atomic_t on_panic;    struct mutex pstore_zone_info_lock;    struct pstore_zone_info *pstore_zone_info;    struct pstore_info pstore;};

enumpsz_flush_mode¶

flush mode forpsz_zone_write()

intpsz_recovery(structpsz_context*cxt)¶

recover data from storage

structpstore_zone_info¶

pstore/zone back-end driver structure

struct pstore_zone_info {    struct module *owner;    const char *name;    unsigned long total_size;    unsigned long kmsg_size;    int max_reason;    unsigned long pmsg_size;    unsigned long console_size;    unsigned long ftrace_size;    pstore_zone_read_op read;    pstore_zone_write_op write;    pstore_zone_erase_op erase;    pstore_zone_write_op panic_write;};

structpstore_device_info¶

back-end pstore/blk driver structure.

struct pstore_device_info {    unsigned int flags;    struct pstore_zone_info zone;};

structpstore_blk_config¶

the pstore_blk backend configuration

struct pstore_blk_config {    char device[80];    enum kmsg_dump_reason max_reason;    unsigned long kmsg_size;    unsigned long pmsg_size;    unsigned long console_size;    unsigned long ftrace_size;};

intpstore_blk_get_config(structpstore_blk_config*info)¶

get a copy of the pstore_blk backend configuration