1 .. SPDX-License-Identifier: GPL-2.0 2 3 pstore block oops/panic logger 4 ============================== 5 6 Introduction 7 ------------ 8 9 pstore block (pstore/blk) is an oops/panic logger that writes its logs to a 10 block device and non-block device before the system crashes. You can get 11 these log files by mounting pstore filesystem like:: 12 13 mount -t pstore pstore /sys/fs/pstore 14 15 16 pstore block concepts 17 --------------------- 18 19 pstore/blk provides efficient configuration method for pstore/blk, which 20 divides all configurations into two parts, configurations for user and 21 configurations for driver. 22 23 Configurations for user determine how pstore/blk works, such as pmsg_size, 24 kmsg_size and so on. All of them support both Kconfig and module parameters, 25 but module parameters have priority over Kconfig. 26 27 Configurations for driver are all about block device and non-block device, 28 such as total_size of block device and read/write operations. 29 30 Configurations for user 31 ----------------------- 32 33 All of these configurations support both Kconfig and module parameters, but 34 module parameters have priority over Kconfig. 35 36 Here is an example for module parameters:: 37 38 pstore_blk.blkdev=/dev/mmcblk0p7 pstore_blk.kmsg_size=64 best_effort=y 39 40 The detail of each configurations may be of interest to you. 41 42 blkdev 43 ~~~~~~ 44 45 The block device to use. Most of the time, it is a partition of block device. 46 It's required for pstore/blk. It is also used for MTD device. 47 48 When pstore/blk is built as a module, "blkdev" accepts the following variants: 49 50 1. /dev/<disk_name> represents the device number of disk 51 #. /dev/<disk_name><decimal> represents the device number of partition - device 52 number of disk plus the partition number 53 #. /dev/<disk_name>p<decimal> - same as the above; this form is used when disk 54 name of partitioned disk ends with a digit. 55 56 When pstore/blk is built into the kernel, "blkdev" accepts the following variants: 57 58 #. <hex_major><hex_minor> device number in hexadecimal representation, 59 with no leading 0x, for example b302. 60 #. PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF represents the unique id of 61 a partition if the partition table provides it. The UUID may be either an 62 EFI/GPT UUID, or refer to an MSDOS partition using the format SSSSSSSS-PP, 63 where SSSSSSSS is a zero-filled hex representation of the 32-bit 64 "NT disk signature", and PP is a zero-filled hex representation of the 65 1-based partition number. 66 #. PARTUUID=<UUID>/PARTNROFF=<int> to select a partition in relation to a 67 partition with a known unique id. 68 #. <major>:<minor> major and minor number of the device separated by a colon. 69 70 It accepts the following variants for MTD device: 71 72 1. <device name> MTD device name. "pstore" is recommended. 73 #. <device number> MTD device number. 74 75 kmsg_size 76 ~~~~~~~~~ 77 78 The chunk size in KB for oops/panic front-end. It **MUST** be a multiple of 4. 79 It's optional if you do not care about the oops/panic log. 80 81 There are multiple chunks for oops/panic front-end depending on the remaining 82 space except other pstore front-ends. 83 84 pstore/blk will log to oops/panic chunks one by one, and always overwrite the 85 oldest chunk if there is no more free chunk. 86 87 pmsg_size 88 ~~~~~~~~~ 89 90 The chunk size in KB for pmsg front-end. It **MUST** be a multiple of 4. 91 It's optional if you do not care about the pmsg log. 92 93 Unlike oops/panic front-end, there is only one chunk for pmsg front-end. 94 95 Pmsg is a user space accessible pstore object. Writes to */dev/pmsg0* are 96 appended to the chunk. On reboot the contents are available in 97 */sys/fs/pstore/pmsg-pstore-blk-0*. 98 99 console_size 100 ~~~~~~~~~~~~ 101 102 The chunk size in KB for console front-end. It **MUST** be a multiple of 4. 103 It's optional if you do not care about the console log. 104 105 Similar to pmsg front-end, there is only one chunk for console front-end. 106 107 All log of console will be appended to the chunk. On reboot the contents are 108 available in */sys/fs/pstore/console-pstore-blk-0*. 109 110 ftrace_size 111 ~~~~~~~~~~~ 112 113 The chunk size in KB for ftrace front-end. It **MUST** be a multiple of 4. 114 It's optional if you do not care about the ftrace log. 115 116 Similar to oops front-end, there are multiple chunks for ftrace front-end 117 depending on the count of cpu processors. Each chunk size is equal to 118 ftrace_size / processors_count. 119 120 All log of ftrace will be appended to the chunk. On reboot the contents are 121 combined and available in */sys/fs/pstore/ftrace-pstore-blk-0*. 122 123 Persistent function tracing might be useful for debugging software or hardware 124 related hangs. Here is an example of usage:: 125 126 # mount -t pstore pstore /sys/fs/pstore 127 # mount -t debugfs debugfs /sys/kernel/debug/ 128 # echo 1 > /sys/kernel/debug/pstore/record_ftrace 129 # reboot -f 130 [...] 131 # mount -t pstore pstore /sys/fs/pstore 132 # tail /sys/fs/pstore/ftrace-pstore-blk-0 133 CPU:0 ts:5914676 c0063828 c0063b94 call_cpuidle <- cpu_startup_entry+0x1b8/0x1e0 134 CPU:0 ts:5914678 c039ecdc c006385c cpuidle_enter_state <- call_cpuidle+0x44/0x48 135 CPU:0 ts:5914680 c039e9a0 c039ecf0 cpuidle_enter_freeze <- cpuidle_enter_state+0x304/0x314 136 CPU:0 ts:5914681 c0063870 c039ea30 sched_idle_set_state <- cpuidle_enter_state+0x44/0x314 137 CPU:1 ts:5916720 c0160f59 c015ee04 kernfs_unmap_bin_file <- __kernfs_remove+0x140/0x204 138 CPU:1 ts:5916721 c05ca625 c015ee0c __mutex_lock_slowpath <- __kernfs_remove+0x148/0x204 139 CPU:1 ts:5916723 c05c813d c05ca630 yield_to <- __mutex_lock_slowpath+0x314/0x358 140 CPU:1 ts:5916724 c05ca2d1 c05ca638 __ww_mutex_lock <- __mutex_lock_slowpath+0x31c/0x358 141 142 max_reason 143 ~~~~~~~~~~ 144 145 Limiting which kinds of kmsg dumps are stored can be controlled via 146 the ``max_reason`` value, as defined in include/linux/kmsg_dump.h's 147 ``enum kmsg_dump_reason``. For example, to store both Oopses and Panics, 148 ``max_reason`` should be set to 2 (KMSG_DUMP_OOPS), to store only Panics 149 ``max_reason`` should be set to 1 (KMSG_DUMP_PANIC). Setting this to 0 150 (KMSG_DUMP_UNDEF), means the reason filtering will be controlled by the 151 ``printk.always_kmsg_dump`` boot param: if unset, it'll be KMSG_DUMP_OOPS, 152 otherwise KMSG_DUMP_MAX. 153 154 Configurations for driver 155 ------------------------- 156 157 A device driver uses ``register_pstore_device`` with 158 ``struct pstore_device_info`` to register to pstore/blk. 159 160 .. kernel-doc:: fs/pstore/blk.c 161 :export: 162 163 Compression and header 164 ---------------------- 165 166 Block device is large enough for uncompressed oops data. Actually we do not 167 recommend data compression because pstore/blk will insert some information into 168 the first line of oops/panic data. For example:: 169 170 Panic: Total 16 times 171 172 It means that it's OOPS|Panic for the 16th time since the first booting. 173 Sometimes the number of occurrences of oops|panic since the first booting is 174 important to judge whether the system is stable. 175 176 The following line is inserted by pstore filesystem. For example:: 177 178 Oops#2 Part1 179 180 It means that it's OOPS for the 2nd time on the last boot. 181 182 Reading the data 183 ---------------- 184 185 The dump data can be read from the pstore filesystem. The format for these 186 files is ``dmesg-pstore-blk-[N]`` for oops/panic front-end, 187 ``pmsg-pstore-blk-0`` for pmsg front-end and so on. The timestamp of the 188 dump file records the trigger time. To delete a stored record from block 189 device, simply unlink the respective pstore file. 190 191 Attentions in panic read/write APIs 192 ----------------------------------- 193 194 If on panic, the kernel is not going to run for much longer, the tasks will not 195 be scheduled and most kernel resources will be out of service. It 196 looks like a single-threaded program running on a single-core computer. 197 198 The following points require special attention for panic read/write APIs: 199 200 1. Can **NOT** allocate any memory. 201 If you need memory, just allocate while the block driver is initializing 202 rather than waiting until the panic. 203 #. Must be polled, **NOT** interrupt driven. 204 No task schedule any more. The block driver should delay to ensure the write 205 succeeds, but NOT sleep. 206 #. Can **NOT** take any lock. 207 There is no other task, nor any shared resource; you are safe to break all 208 locks. 209 #. Just use CPU to transfer. 210 Do not use DMA to transfer unless you are sure that DMA will not keep lock. 211 #. Control registers directly. 212 Please control registers directly rather than use Linux kernel resources. 213 Do I/O map while initializing rather than wait until a panic occurs. 214 #. Reset your block device and controller if necessary. 215 If you are not sure of the state of your block device and controller when 216 a panic occurs, you are safe to stop and reset them. 217 218 pstore/blk supports psblk_blkdev_info(), which is defined in 219 *linux/pstore_blk.h*, to get information of using block device, such as the 220 device number, sector count and start sector of the whole disk. 221 222 pstore block internals 223 ---------------------- 224 225 For developer reference, here are all the important structures and APIs: 226 227 .. kernel-doc:: fs/pstore/zone.c 228 :internal: 229 230 .. kernel-doc:: include/linux/pstore_zone.h 231 :internal: 232 233 .. kernel-doc:: include/linux/pstore_blk.h 234 :internal:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.