[PATCH] char drivers: ramoops documentation

[PATCH] char drivers: ramoops documentation

[Sergiu Iordache]

Add a documentation file describing the usage of Ramoops

Change-Id: I9dab9c4b9e4921b220574470372e330d32f9c63b
Signed-off-by: Sergiu Iordache <sergiu@chromium.org>
---
 Documentation/ramoops.txt |   67 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 67 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ramoops.txt

diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt
new file mode 100644
index 0000000..ef606de
--- /dev/null
+++ b/Documentation/ramoops.txt
@@ -0,0 +1,67 @@
+Ramoops oops/panic logger
+=========================
+
+Sergiu Iordache <sergiu@chromium.org>
+
+Updated: 1 August 2011
+
+0. Introduction
+
+Ramoops is an oops/panic logger in RAM. It works by logging oopses and panics
+in a circular buffer. In order to work it needs a system with persistent RAM
+so that the content of that area can survive after a restart.
+
+1. Ramoops concepts
+
+Ramoops uses a predefined memory area to store the dump. The start and size of
+the memory area are set using two variables: "mem_address" for the start and
+"mem_size" for the size. Memory size will be rounded to a multiple of two.
+This memory area is divided into "record_size" chunks (also rounded to
+multiple of two) and each oops/panic writes a "record_size" chunk of
+information. Dumping both oopses and panics can be done by setting 1 in the
+"dump_oops" variable while setting 0 in that variable dumps only the panics.
+
+2. Setting the parameters
+
+Setting the ramoops parameters can be done in 2 different manners:
+ 1. Use the module parameters (which have the names of the variables described
+ as before).
+ 2. Use a platform device and set the platform data. The parameters can then
+ be set through that platform data. An example of doing that is:
+
+#include <linux/ramoops.h>
+[...]
+
+static struct ramoops_platform_data ramoops_data = {
+        .mem_size               = <...>,
+        .mem_address            = <...>,
+        .record_size            = <...>,
+        .dump_oops              = <...>,
+};
+
+static struct platform_device ramoops_dev = {
+        .name = "ramoops",
+        .dev = {
+                .platform_data = &ramoops_data,
+        },
+};
+
+[... inside a function ...]
+int ret;
+
+ret = platform_device_register(&ramoops_dev);
+if (ret) {
+	printk(KERN_ERR "unable to register platform device\n");
+	return ret;
+}
+
+3. Dump format
+
+The data dump begins with a header, currently defined at "====" followed by a
+timestamp and then continues with the actual dump data.
+
+4. Reading the data
+
+The dump data can be read from memory (through /dev/mem or other means).
+Getting the module parameters, which are needed in order to parse the data can
+be done through /sys/module/ramoops/parameters/* .
-- 
1.7.2.3

Re: [PATCH] char drivers: ramoops documentation

[Randy Dunlap]

On Mon,  1 Aug 2011 14:26:50 -0700 Sergiu Iordache wrote:

> Add a documentation file describing the usage of Ramoops
> 
> Change-Id: I9dab9c4b9e4921b220574470372e330d32f9c63b

eh?

> Signed-off-by: Sergiu Iordache <sergiu@chromium.org>
> ---
>  Documentation/ramoops.txt |   67 +++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 67 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/ramoops.txt
> 
> diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt
> new file mode 100644
> index 0000000..ef606de
> --- /dev/null
> +++ b/Documentation/ramoops.txt
> @@ -0,0 +1,67 @@
> +Ramoops oops/panic logger
> +=========================
> +
> +Sergiu Iordache <sergiu@chromium.org>
> +
> +Updated: 1 August 2011
> +
> +0. Introduction
> +
> +Ramoops is an oops/panic logger in RAM. It works by logging oopses and panics

The logger lives in RAM or the log lives in RAM?

How about:

Ramoops is an oops/panic logger that writes its logs to RAM.

> +in a circular buffer. In order to work it needs a system with persistent RAM
> +so that the content of that area can survive after a restart.
> +
> +1. Ramoops concepts
> +
> +Ramoops uses a predefined memory area to store the dump. The start and size of
> +the memory area are set using two variables: "mem_address" for the start and
> +"mem_size" for the size. Memory size will be rounded to a multiple of two.

                                                rounded down to a power of two.

> +This memory area is divided into "record_size" chunks (also rounded to

                                                          also rounded down to
a power of two)

> +multiple of two) and each oops/panic writes a "record_size" chunk of
> +information. Dumping both oopses and panics can be done by setting 1 in the
> +"dump_oops" variable while setting 0 in that variable dumps only the panics.
> +
> +2. Setting the parameters
> +
> +Setting the ramoops parameters can be done in 2 different manners:
> + 1. Use the module parameters (which have the names of the variables described
> + as before).
> + 2. Use a platform device and set the platform data. The parameters can then
> + be set through that platform data. An example of doing that is:
> +
> +#include <linux/ramoops.h>
> +[...]
> +
> +static struct ramoops_platform_data ramoops_data = {
> +        .mem_size               = <...>,
> +        .mem_address            = <...>,
> +        .record_size            = <...>,
> +        .dump_oops              = <...>,
> +};
> +
> +static struct platform_device ramoops_dev = {
> +        .name = "ramoops",
> +        .dev = {
> +                .platform_data = &ramoops_data,
> +        },
> +};
> +
> +[... inside a function ...]
> +int ret;
> +
> +ret = platform_device_register(&ramoops_dev);
> +if (ret) {
> +	printk(KERN_ERR "unable to register platform device\n");
> +	return ret;
> +}
> +
> +3. Dump format
> +
> +The data dump begins with a header, currently defined at "====" followed by a

                                                         as "=====",

> +timestamp and then continues with the actual dump data.
> +
> +4. Reading the data
> +
> +The dump data can be read from memory (through /dev/mem or other means).
> +Getting the module parameters, which are needed in order to parse the data can

                                                               parse the data, can

> +be done through /sys/module/ramoops/parameters/* .
> -- 



---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] char drivers: ramoops documentation

[Sergiu Iordache]

On Mon, Aug 1, 2011 at 3:05 PM, Randy Dunlap <rdunlap@xenotime.net> wrote:
> On Mon,  1 Aug 2011 14:26:50 -0700 Sergiu Iordache wrote:
>
>> Add a documentation file describing the usage of Ramoops
>>
>> Change-Id: I9dab9c4b9e4921b220574470372e330d32f9c63b
>
> eh?
Sorry, was it the commit message you did not like or something else?

>> Signed-off-by: Sergiu Iordache <sergiu@chromium.org>
>> ---
>>  Documentation/ramoops.txt |   67 +++++++++++++++++++++++++++++++++++++++++++++
>>  1 files changed, 67 insertions(+), 0 deletions(-)
>>  create mode 100644 Documentation/ramoops.txt
>>
>> diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt
>> new file mode 100644
>> index 0000000..ef606de
>> --- /dev/null
>> +++ b/Documentation/ramoops.txt
>> @@ -0,0 +1,67 @@
>> +Ramoops oops/panic logger
>> +=========================
>> +
>> +Sergiu Iordache <sergiu@chromium.org>
>> +
>> +Updated: 1 August 2011
>> +
>> +0. Introduction
>> +
>> +Ramoops is an oops/panic logger in RAM. It works by logging oopses and panics
>
> The logger lives in RAM or the log lives in RAM?
>
> How about:
>
> Ramoops is an oops/panic logger that writes its logs to RAM.
>
>> +in a circular buffer. In order to work it needs a system with persistent RAM
>> +so that the content of that area can survive after a restart.
>> +
>> +1. Ramoops concepts
>> +
>> +Ramoops uses a predefined memory area to store the dump. The start and size of
>> +the memory area are set using two variables: "mem_address" for the start and
>> +"mem_size" for the size. Memory size will be rounded to a multiple of two.
>
>                                                rounded down to a power of two.
>
>> +This memory area is divided into "record_size" chunks (also rounded to
>
>                                                          also rounded down to
> a power of two)
>
>> +multiple of two) and each oops/panic writes a "record_size" chunk of
>> +information. Dumping both oopses and panics can be done by setting 1 in the
>> +"dump_oops" variable while setting 0 in that variable dumps only the panics.
>> +
>> +2. Setting the parameters
>> +
>> +Setting the ramoops parameters can be done in 2 different manners:
>> + 1. Use the module parameters (which have the names of the variables described
>> + as before).
>> + 2. Use a platform device and set the platform data. The parameters can then
>> + be set through that platform data. An example of doing that is:
>> +
>> +#include <linux/ramoops.h>
>> +[...]
>> +
>> +static struct ramoops_platform_data ramoops_data = {
>> +        .mem_size               = <...>,
>> +        .mem_address            = <...>,
>> +        .record_size            = <...>,
>> +        .dump_oops              = <...>,
>> +};
>> +
>> +static struct platform_device ramoops_dev = {
>> +        .name = "ramoops",
>> +        .dev = {
>> +                .platform_data = &ramoops_data,
>> +        },
>> +};
>> +
>> +[... inside a function ...]
>> +int ret;
>> +
>> +ret = platform_device_register(&ramoops_dev);
>> +if (ret) {
>> +     printk(KERN_ERR "unable to register platform device\n");
>> +     return ret;
>> +}
>> +
>> +3. Dump format
>> +
>> +The data dump begins with a header, currently defined at "====" followed by a
>
>                                                         as "=====",
>
>> +timestamp and then continues with the actual dump data.
>> +
>> +4. Reading the data
>> +
>> +The dump data can be read from memory (through /dev/mem or other means).
>> +Getting the module parameters, which are needed in order to parse the data can
>
>                                                               parse the data, can
>
>> +be done through /sys/module/ramoops/parameters/* .

Thanks, I've updated the doc using your feedback. I have also
rearranged the "1. Ramoops concepts" part to make it look better I
think. I'll wait a bit for some more comments and then resubmit the
new version of the patch.

Thanks,
Sergiu

Re: [PATCH] char drivers: ramoops documentation

[Randy Dunlap]

On Mon, 1 Aug 2011 15:37:49 -0700 Sergiu Iordache wrote:

> On Mon, Aug 1, 2011 at 3:05 PM, Randy Dunlap <rdunlap@xenotime.net> wrote:
> > On Mon,  1 Aug 2011 14:26:50 -0700 Sergiu Iordache wrote:
> >
> >> Add a documentation file describing the usage of Ramoops
> >>
> >> Change-Id: I9dab9c4b9e4921b220574470372e330d32f9c63b
> >
> > eh?
> Sorry, was it the commit message you did not like or something else?

The "Change-Id:" line.
There was a discussion that began with a July 14 patch from Mike Waychison
<mikew@google.com>:
Subject: [PATCH 1/2] Kconfig:  Allow disabling of CONFIG_DEVPORT

that included the line:
Google-Bug-Id: 3177114

Basically we don't want umpteen zillion different such tags in commit
messages.  I posted a patch last Friday:
Subject: [PATCH] Documentation: add Internal-reference-ID: patch tag

that allows people who want to track their internal references in commit
messages to use a common tag label/format:

Internal-reference-ID: <text>

<text> should not be a private (internal) URL.


> Thanks, I've updated the doc using your feedback. I have also
> rearranged the "1. Ramoops concepts" part to make it look better I
> think. I'll wait a bit for some more comments and then resubmit the
> new version of the patch.

Thanks.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] char drivers: ramoops documentation

[Randy Dunlap]

On Fri,  5 Aug 2011 16:33:49 -0700 Sergiu Iordache wrote:

> Add a documentation file describing the usage of Ramoops
> 
> Signed-off-by: Sergiu Iordache <sergiu@chromium.org>
> ---
>  Documentation/ramoops.txt |   73 +++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 73 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/ramoops.txt
> 
> diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt
> new file mode 100644
> index 0000000..0575177
> --- /dev/null
> +++ b/Documentation/ramoops.txt
> @@ -0,0 +1,73 @@
> +Ramoops oops/panic logger
> +=========================
> +
> +Sergiu Iordache <sergiu@chromium.org>
> +
> +Updated: 5 August 2011
> +
> +0. Introduction
> +
> +Ramoops is an oops/panic logger that writes its logs to RAM before the system
> +crashes. It works by logging oopses and panics in a circular buffer. Ramoops
> +needs a system with persistent RAM so that the content of that area can
> +survive after a restart.
> +
> +1. Ramoops concepts
> +
> +Ramoops uses a predefined memory area to store the dump. The start and size of
> +the memory area are set using two variables:
> +  * "mem_address" for the start
> +  * "mem_size" for the size. The memory size will be rounded down to a
> +  multiple of two.

     power of two.

> +
> +The memory area is divided into "record_size" chunks (also rounded down to
> +multiple of two) and each oops/panic writes a "record_size" chunk of

   power of two)

> +information.
> +
> +Dumping both oopses and panics can be done by setting 1 in the "dump_oops"
> +variable while setting 0 in that variable dumps only the panics.
> +
> +2. Setting the parameters
> +
> +Setting the ramoops parameters can be done in 2 different manners:
> + 1. Use the module parameters (which have the names of the variables described
> + as before).
> + 2. Use a platform device and set the platform data. The parameters can then
> + be set through that platform data. An example of doing that is:
> +
> +#include <linux/ramoops.h>
> +[...]
> +
> +static struct ramoops_platform_data ramoops_data = {
> +        .mem_size               = <...>,
> +        .mem_address            = <...>,
> +        .record_size            = <...>,
> +        .dump_oops              = <...>,
> +};
> +
> +static struct platform_device ramoops_dev = {
> +        .name = "ramoops",
> +        .dev = {
> +                .platform_data = &ramoops_data,
> +        },
> +};
> +
> +[... inside a function ...]
> +int ret;
> +
> +ret = platform_device_register(&ramoops_dev);
> +if (ret) {
> +	printk(KERN_ERR "unable to register platform device\n");
> +	return ret;
> +}
> +
> +3. Dump format
> +
> +The data dump begins with a header, currently defined as "====" followed by a
> +timestamp and then continues with the actual dump data.
> +
> +4. Reading the data
> +
> +The dump data can be read from memory (through /dev/mem or other means).
> +Getting the module parameters, which are needed in order to parse the data, can
> +be done through /sys/module/ramoops/parameters/* .
> -- 

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

[PATCH] char drivers: ramoops documentation

[Sergiu Iordache]

Add a documentation file describing the usage of Ramoops

Signed-off-by: Sergiu Iordache <sergiu@chromium.org>
---
 Documentation/ramoops.txt |   73 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 73 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ramoops.txt

diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt
new file mode 100644
index 0000000..0575177
--- /dev/null
+++ b/Documentation/ramoops.txt
@@ -0,0 +1,73 @@
+Ramoops oops/panic logger
+=========================
+
+Sergiu Iordache <sergiu@chromium.org>
+
+Updated: 5 August 2011
+
+0. Introduction
+
+Ramoops is an oops/panic logger that writes its logs to RAM before the system
+crashes. It works by logging oopses and panics in a circular buffer. Ramoops
+needs a system with persistent RAM so that the content of that area can
+survive after a restart.
+
+1. Ramoops concepts
+
+Ramoops uses a predefined memory area to store the dump. The start and size of
+the memory area are set using two variables:
+  * "mem_address" for the start
+  * "mem_size" for the size. The memory size will be rounded down to a
+  multiple of two.
+
+The memory area is divided into "record_size" chunks (also rounded down to
+multiple of two) and each oops/panic writes a "record_size" chunk of
+information.
+
+Dumping both oopses and panics can be done by setting 1 in the "dump_oops"
+variable while setting 0 in that variable dumps only the panics.
+
+2. Setting the parameters
+
+Setting the ramoops parameters can be done in 2 different manners:
+ 1. Use the module parameters (which have the names of the variables described
+ as before).
+ 2. Use a platform device and set the platform data. The parameters can then
+ be set through that platform data. An example of doing that is:
+
+#include <linux/ramoops.h>
+[...]
+
+static struct ramoops_platform_data ramoops_data = {
+        .mem_size               = <...>,
+        .mem_address            = <...>,
+        .record_size            = <...>,
+        .dump_oops              = <...>,
+};
+
+static struct platform_device ramoops_dev = {
+        .name = "ramoops",
+        .dev = {
+                .platform_data = &ramoops_data,
+        },
+};
+
+[... inside a function ...]
+int ret;
+
+ret = platform_device_register(&ramoops_dev);
+if (ret) {
+	printk(KERN_ERR "unable to register platform device\n");
+	return ret;
+}
+
+3. Dump format
+
+The data dump begins with a header, currently defined as "====" followed by a
+timestamp and then continues with the actual dump data.
+
+4. Reading the data
+
+The dump data can be read from memory (through /dev/mem or other means).
+Getting the module parameters, which are needed in order to parse the data, can
+be done through /sys/module/ramoops/parameters/* .
-- 
1.7.2.3