Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/ramoops.txt: convert it to ReST format
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
+47
-39
+47
-39
Documentation/ramoops.txt
+47
-39
Documentation/ramoops.txt
···
5
5
6
6
Updated: 17 November 2011
7
7
8
-
0. Introduction
8
+
Introduction
9
+
------------
9
10
10
11
Ramoops is an oops/panic logger that writes its logs to RAM before the system
11
12
crashes. It works by logging oopses and panics in a circular buffer. Ramoops
12
13
needs a system with persistent RAM so that the content of that area can
13
14
survive after a restart.
14
15
15
-
1. Ramoops concepts
16
+
Ramoops concepts
17
+
----------------
16
18
17
19
Ramoops uses a predefined memory area to store the dump. The start and size
18
20
and type of the memory area are set using three variables:
19
-
* "mem_address" for the start
20
-
* "mem_size" for the size. The memory size will be rounded down to a
21
-
power of two.
22
-
* "mem_type" to specifiy if the memory type (default is pgprot_writecombine).
23
21
24
-
Typically the default value of mem_type=0 should be used as that sets the pstore
25
-
mapping to pgprot_writecombine. Setting mem_type=1 attempts to use
26
-
pgprot_noncached, which only works on some platforms. This is because pstore
22
+
* ``mem_address`` for the start
23
+
* ``mem_size`` for the size. The memory size will be rounded down to a
24
+
power of two.
25
+
* ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine).
26
+
27
+
Typically the default value of ``mem_type=0`` should be used as that sets the pstore
28
+
mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use
29
+
``pgprot_noncached``, which only works on some platforms. This is because pstore
27
30
depends on atomic operations. At least on ARM, pgprot_noncached causes the
28
31
memory to be mapped strongly ordered, and atomic operations on strongly ordered
29
32
memory are implementation defined, and won't work on many ARMs such as omaps.
30
33
31
-
The memory area is divided into "record_size" chunks (also rounded down to
32
-
power of two) and each oops/panic writes a "record_size" chunk of
34
+
The memory area is divided into ``record_size`` chunks (also rounded down to
35
+
power of two) and each oops/panic writes a ``record_size`` chunk of
33
36
information.
34
37
35
-
Dumping both oopses and panics can be done by setting 1 in the "dump_oops"
38
+
Dumping both oopses and panics can be done by setting 1 in the ``dump_oops``
36
39
variable while setting 0 in that variable dumps only the panics.
37
40
38
41
The module uses a counter to record multiple dumps but the counter gets reset
···
46
43
to life (i.e. a watchdog triggered). In such cases, RAM may be somewhat
47
44
corrupt, but usually it is restorable.
48
45
49
-
2. Setting the parameters
46
+
Setting the parameters
47
+
----------------------
50
48
51
49
Setting the ramoops parameters can be done in several different manners:
52
50
···
56
52
boot and then use the reserved memory for ramoops. For example, assuming a
57
53
machine with > 128 MB of memory, the following kernel command line will tell
58
54
the kernel to use only the first 128 MB of memory, and place ECC-protected
59
-
ramoops region at 128 MB boundary:
60
-
"mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1"
55
+
ramoops region at 128 MB boundary::
56
+
57
+
mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1
61
58
62
59
B. Use Device Tree bindings, as described in
63
-
Documentation/device-tree/bindings/reserved-memory/ramoops.txt.
64
-
For example:
60
+
``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``.
61
+
For example::
65
62
66
63
reserved-memory {
67
64
#address-cells = <2>;
···
78
73
};
79
74
80
75
C. Use a platform device and set the platform data. The parameters can then
81
-
be set through that platform data. An example of doing that is:
76
+
be set through that platform data. An example of doing that is::
82
77
83
-
#include <linux/pstore_ram.h>
84
-
[...]
78
+
#include <linux/pstore_ram.h>
79
+
[...]
85
80
86
-
static struct ramoops_platform_data ramoops_data = {
81
+
static struct ramoops_platform_data ramoops_data = {
87
82
.mem_size = <...>,
88
83
.mem_address = <...>,
89
84
.mem_type = <...>,
90
85
.record_size = <...>,
91
86
.dump_oops = <...>,
92
87
.ecc = <...>,
93
-
};
88
+
};
94
89
95
-
static struct platform_device ramoops_dev = {
90
+
static struct platform_device ramoops_dev = {
96
91
.name = "ramoops",
97
92
.dev = {
98
93
.platform_data = &ramoops_data,
99
94
},
100
-
};
95
+
};
101
96
102
-
[... inside a function ...]
103
-
int ret;
97
+
[... inside a function ...]
98
+
int ret;
104
99
105
-
ret = platform_device_register(&ramoops_dev);
106
-
if (ret) {
100
+
ret = platform_device_register(&ramoops_dev);
101
+
if (ret) {
107
102
printk(KERN_ERR "unable to register platform device\n");
108
103
return ret;
109
-
}
104
+
}
110
105
111
106
You can specify either RAM memory or peripheral devices' memory. However, when
112
107
specifying RAM, be sure to reserve the memory by issuing memblock_reserve()
113
-
very early in the architecture code, e.g.:
108
+
very early in the architecture code, e.g.::
114
109
115
-
#include <linux/memblock.h>
110
+
#include <linux/memblock.h>
116
111
117
-
memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size);
112
+
memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size);
118
113
119
-
3. Dump format
114
+
Dump format
115
+
-----------
120
116
121
-
The data dump begins with a header, currently defined as "====" followed by a
117
+
The data dump begins with a header, currently defined as ``====`` followed by a
122
118
timestamp and a new line. The dump then continues with the actual data.
123
119
124
-
4. Reading the data
120
+
Reading the data
121
+
----------------
125
122
126
123
The dump data can be read from the pstore filesystem. The format for these
127
-
files is "dmesg-ramoops-N", where N is the record number in memory. To delete
124
+
files is ``dmesg-ramoops-N``, where N is the record number in memory. To delete
128
125
a stored record from RAM, simply unlink the respective pstore file.
129
126
130
-
5. Persistent function tracing
127
+
Persistent function tracing
128
+
---------------------------
131
129
132
130
Persistent function tracing might be useful for debugging software or hardware
133
-
related hangs. The functions call chain log is stored in a "ftrace-ramoops"
134
-
file. Here is an example of usage:
131
+
related hangs. The functions call chain log is stored in a ``ftrace-ramoops``
132
+
file. Here is an example of usage::
135
133
136
134
# mount -t debugfs debugfs /sys/kernel/debug/
137
135
# echo 1 > /sys/kernel/debug/pstore/record_ftrace