[PATCH] Documentation: pstore: add some information about interfacing with Linux

[PATCH] Documentation: pstore: add some information about interfacing with Linux

[Ahmad Fatoum]

The help text erroneously states that CONFIG_FS_PSTORE_RAMOOPS_RO
disables writing completely, but this is not correct: It merely stops
barebox from zapping log content previously written by Linux.

The Kconfig help text is correct, so adjust the documentation to reflect
that and while at it, add some more information about how to access
pstore in Linux.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/filesystems/pstore.rst | 29 +++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/Documentation/filesystems/pstore.rst b/Documentation/filesystems/pstore.rst
index b8c2cb825ced..e16c4f35e704 100644
--- a/Documentation/filesystems/pstore.rst
+++ b/Documentation/filesystems/pstore.rst
@@ -73,11 +73,30 @@ in the Barebox shell. The RAMOOPS area is listed as 'persistent ram':
     0x2fee4000 - 0x2fee7fff (size 0x00004000) ttb
     0x2fee8000 - 0x2feeffff (size 0x00008000) stack
 
-All pstore files that could be found are added to the /pstore directory. This is
-a read-only filesystem. If you disable the Kconfig option FS_PSTORE_RAMOOPS_RO,
-the RAMOOPS area is reset and its ECC recalculated. But that does not allow any
-writes from Barebox into that area.
-
 If the menu entry ``FS_PSTORE_CONSOLE`` is enabled, Barebox itself will add all
 its own console output to the *ramoops:console* part, which enables the regular
 userland later on to have access to the bootloaders output.
+
+All pstore files that could be found are added to the /pstore directory. This is
+a read-only filesystem with the only supported operation being unlinking:
+This resets (zaps) the RAMOOPS area and recalculates the ECC.
+
+Zapping is done automatically, if the menu entry ``FS_PSTORE_RAMOOPS_RO`` is
+disabled. In this case, only the barebox log will be available to the kernel
+and ramoops from previous boots will not survive.
+
+The usual setup is to not zap any buffers, i.e. ``CONFIG_FS_PSTORE_RAMOOPS_RO=y``
+and no manual unlinking of files in ``/pstore``.
+
+In Linux, the pstore file system is often mounted at ``/sys/fs/pstore``.
+This will often not contain older output as Linux frequently zaps ramoops
+buffers to conserve the limited space.
+
+To counteract this, userland needs to archive the pstore contents
+after booting into Linux and then clear pstore. Systemd has built-in support
+for this when compiled with ``-Dpstore=true``.
+
+Logs (including barebox log messages if enabled) will then be written to
+journal by default and are accessible via::
+
+  journalctl -b -o verbose -a -t systemd-pstore
-- 
2.39.2

Re: [PATCH] Documentation: pstore: add some information about interfacing with Linux

[Sascha Hauer]

On Wed, 15 May 2024 13:19:02 +0200, Ahmad Fatoum wrote:
> The help text erroneously states that CONFIG_FS_PSTORE_RAMOOPS_RO
> disables writing completely, but this is not correct: It merely stops
> barebox from zapping log content previously written by Linux.
> 
> The Kconfig help text is correct, so adjust the documentation to reflect
> that and while at it, add some more information about how to access
> pstore in Linux.
> 
> [...]

Applied, thanks!

[1/1] Documentation: pstore: add some information about interfacing with Linux
      https://git.pengutronix.de/cgit/barebox/commit/?id=7deedc63739d (link may not be stable)

Best regards,
-- 
Sascha Hauer <s.hauer@pengutronix.de>