[Skiboot] [PATCH v7 18/22] fadump: Add documentation

[Nicholas Piggin]

Vasant Hegde's on April 13, 2019 7:15 pm:
> diff --git a/doc/opal-api/opal-fadump-manage-173.rst b/doc/opal-api/opal-fadump-manage-173.rst
> new file mode 100644
> index 000000000..916167503
> --- /dev/null
> +++ b/doc/opal-api/opal-fadump-manage-173.rst
> @@ -0,0 +1,73 @@
> +.. _opal-api-fadump-manage:
> +
> +OPAL fadump manage call
> +=======================
> +::
> +
> +   #define OPAL_FADUMP_MANAGE                      173
> +
> +This call is used to manage FADUMP (aka MPIPL) on OPAL platform.
> +Linux kernel will use this call to register/unregister FADUMP.
> +
> +Parameters
> +----------
> +::
> +
> +   uint64_t     command
> +   void         *data
> +   uint64_t     dsize
> +
> +``command``
> +   ``command`` parameter supports below values:
> +
> +::
> +
> +      0x01 - Register for fadump
> +      0x02 - Unregister fadump
> +      0x03 - Invalidate existing fadump
> +
> +``data``
> +   ``data`` is valid when ``command`` is 0x01 (registration).
> +   We use fadump structure (see below) to pass Linux kernel
> +   memory reservation details.
> +
> +::
> +
> +
> +   struct fadump_section {
> +	u8	source_type;
> +	u8	reserved[7];
> +	u64	source_addr;
> +	u64	source_size;
> +	u64	dest_addr;
> +	u64	dest_size;
> +   } __packed;
> +
> +   struct fadump {
> +	u16	fadump_section_size;
> +	u16	section_count;
> +	u32	crashing_cpu;
> +	u64	reserved;
> +	struct	fadump_section section[];
> +   };

This API seems quite complicated. The kernel wants to tell firmware to
preserve some ranges of memory in case of reboot, and to have those
ranges advertised to the reboot kernel.

Why not just an API which can add a range, and delete a range, and
that's it? Range would just be physical start, end, plus an arbitrary
tag (which caller can use to retrieve metadata that is used to
decipher the dump).

Reboot type would be a preserve-memory type, which describes what it
does.

Thanks,
Nick