pager: doc: Add mention of the pager feature

Add a note about the pager to the console documentation, with some more
information in the developer section. Also include the pager API.

Series-to: concept
Cover-letter:
Introduce a pager for the console
Some U-Boot commands can produce a lot of output and this can run off
top of the display. This series introduces a simple pager feature, to
allow the output to be read, before pressing SPACE to continue.

A fixed buffer size (4K) is used, which sets a limit on the permmited
output before paging fails and the output is simply written all in one
lot. In most cases this is plenty, but 'env print' does print the whole
environment as one string, so if the legacy distro-boot scripts are used
it could happen.

The default number of visible lines is set with a Kconfig option. Where
a video terminal is being used, the page size is set to match that. In
general U-Boot cannot guess the number of visible lines, since a serial
terminal may be in use.

There is also a 'pager' environment variable which can override any
detected value.

This initial series only counts newlines. It has no support for counting
characters so the result will be sub-optimal if very long lines are
written. This could be addressed in a future patch.

Some effort is made to handle common cases correctly. For example, if
stdout is changed to a serial or vidconsole device, that is used to
determine the page length. When redirecting sandbox to a file, no
attempt is made.

Future work may detect the terminal size by sending an ANSI sequence.
END

Signed-off-by: Simon Glass <sjg@chromium.org>
Series-version: 2

doc/api/index.rst

@@ -20,6 +20,7 @@ U-Boot API documentation
    lmb
    logging
    nvmem
+   pager
    part
    pinctrl
    rng

doc/api/pager.rst

@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright Simon Glass <sjg@chromium.org>
+
+Console Pager
+=============
+
+See :doc:`/develop/console`.
+
+.. kernel-doc:: include/pager.h
+   :internal:

doc/develop/console.rst

@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
+
+=======
+Console
+=======
+
+
+Paging
+------
+
+See the user documentation at :doc:`/usage/console`. For the API, see
+:doc:`/api/pager`.
+
+The pager is implemented in `common/pager.c` and integrated into the console
+system via `console_puts()` in `common/console.c`. When output is sent to
+stdout:
+
+1. Text is passed to `pager_post()` which buffers it
+2. `pager_next()` returns portions of text up to the page limit
+3. When the page limit is reached, a prompt is displayed
+4. The system waits for user input (SPACE key) via `getchar()`
+5. After SPACE is pressed, the prompt is cleared and output continues
+
+The pager maintains state through the `struct pager` which tracks:
+
+- Current line count within the page
+- Page length setting
+- Text buffer and overflow handling
+- Current pager state (normal, waiting for user, clearing prompt)
+
+Bypass Mode
+~~~~~~~~~~~
+
+The pager can be put into bypass mode using `pager_set_bypass()`, which is
+useful for automated testing. In bypass mode, all text flows through without
+any paging interruptions.
+
+The pager automatically enters bypass mode when output is not connected to a
+terminal, preventing paging prompts from appearing in non-interactive
+environments like scripts or automated builds.

doc/develop/index.rst

@@ -35,6 +35,7 @@ Implementation
    ci_testing
    commands
    config_binding
+   console
    cyclic
    devicetree/index
    distro

doc/usage/console.rst

@@ -1,6 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0+
 .. sectionauthor:: Paolo Scaffardi, AIRVENT SAM s.p.a - RIMINI(ITALY), arsenio@tin.it
 ..  (C) Copyright 2000
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
 
 =======================
 U-Boot console handling
@@ -60,3 +61,47 @@ file ('stdin', 'stdout' or 'stderr')
 
 Remember that FILE-related functions CANNOT be used before U-Boot relocation,
 which is done in `board_init_r()`.
+
+Pager
+-----
+
+U-Boot has a simple pager feature, enabled with `CONFIG_CONSOLE_PAGER`. It is
+only available if `CONFIG_CONSOLE_MUX` is also enabled.
+
+When activated, the pager pauses at the end of each 'page' (screenful) of
+output, shows a prompt ": Press SPACE to continue" and lets the user read the
+output. To continue to the next page, press the SPACE key.
+
+Page Size Configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The number of lines per page is determined in the following order of priority:
+
+1. **Environment variable**: The `pager` environment variable (hex value)
+   takes highest priority. Set to 0 to disable paging.
+
+2. **Video console detection**: If no environment variable is set and a video
+   console is active, the pager uses the number of rows from the video console.
+
+3. **Serial TTY detection**: For serial consoles, the pager checks if the
+   output is connected to a terminal (TTY). If not connected to a TTY, paging
+   is disabled. This check works by sending a few special characters to the
+   terminal and (hopefully) receiving a reply. If you are logging the output of
+   U-Boot, you may see these characters in the log. Disable
+   `CONFIG_SERIAL_TERM_PRESENT` is this is unwanted.
+
+4. **Configuration default**: If none of the above apply, falls back to
+   `CONFIG_CONSOLE_PAGER_LINES`.
+
+Examples::
+
+    # Set page size to 30 lines (hex value 1e)
+    setenv pager 1e
+
+    # Set page size to 24 lines (hex value 18)  
+    setenv pager 18
+
+    # Disable paging
+    setenv pager 0
+
+For developer documentation, please see :doc:`/develop/console`.

doc/usage/environment.rst

@@ -337,6 +337,7 @@ netretry
 
 pager
     Decimal number of visible lines on the display, or serial console.
+    :doc:`/usage/console`.
 
 rng_seed_size
     Size of random value added to device-tree node /chosen/rng-seed.