Re: [PATCH] char drivers: ramoops documentation

[Sergiu Iordache]

On Mon, Aug 1, 2011 at 3:05 PM, Randy Dunlap <rdunlap@xxxxxxxxxxxx> 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@xxxxxxxxxxxx>
>> ---
>>  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@xxxxxxxxxxxx>
>> +
>> +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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/