[Intel-gfx] [PATCH 2/2] man: add man page for intel_reg in rst format

[Thomas Wood]

On 15 April 2015 at 11:15, Jani Nikula <jani.nikula at intel.com> wrote:
> Produce the man page from rst using rst2man.
>
> FIXME: configure support for checking rst2man.

I think this can be done with a fairly straightforward AC_CHECK_PROG
and AM_CONDITIONAL in configure.ac:

AC_CHECK_PROG(RST2MAN, rst2man, yes, no)
AM_CONDITIONAL(HAVE_RST2MAN, [test "x$RST2MAN" = xyes])

and then surround the relevant parts in Makefile.am with: if
HAVE_RST2MAN … endif.


>
> Signed-off-by: Jani Nikula <jani.nikula at intel.com>
> ---
>  man/Makefile.am   |  12 ++-
>  man/intel_reg.rst | 229 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 240 insertions(+), 1 deletion(-)
>  create mode 100644 man/intel_reg.rst
>
> diff --git a/man/Makefile.am b/man/Makefile.am
> index dcd79528f17b..548e966ba77a 100644
> --- a/man/Makefile.am
> +++ b/man/Makefile.am
> @@ -19,7 +19,12 @@ appman_PRE =                                 \
>         intel_upload_blit_large_map.man \
>         intel_upload_blit_small.man
>
> -appman_DATA = $(appman_PRE:man=$(APP_MAN_SUFFIX))
> +appman_RST =                           \
> +       intel_reg.rst
> +
> +appman_DATA =                                  \
> +       $(appman_PRE:man=$(APP_MAN_SUFFIX))     \
> +       $(appman_RST:rst=$(APP_MAN_SUFFIX))
>
>  EXTRA_DIST = $(appman_PRE)
>  CLEANFILES = $(appman_DATA)
> @@ -29,3 +34,8 @@ SUFFIXES = .$(APP_MAN_SUFFIX) .man
>
>  .man.$(APP_MAN_SUFFIX):
>         $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
> +
> +# FIXME: check for rst2man in configure.ac
> +# FIXME: handle MAN_SUBST in rst
> +.rst.$(APP_MAN_SUFFIX):
> +       $(AM_V_GEN)rst2man < $< > $@
> diff --git a/man/intel_reg.rst b/man/intel_reg.rst
> new file mode 100644
> index 000000000000..c6e2feadeab2
> --- /dev/null
> +++ b/man/intel_reg.rst
> @@ -0,0 +1,229 @@
> +=========
> +intel_reg
> +=========
> +
> +---------------------------------
> +Intel graphics register multitool
> +---------------------------------
> +
> +:Author: Jani Nikula <jani.nikula at intel.com>
> +:Date: 2015-04-14
> +:Version: intel-gpu-tools
> +:Copyright: 2015 Intel Corporation
> +:Manual section: 1
> +:Manual group: General Commands Manual
> +
> +SYNOPSIS
> +========
> +
> +**intel_reg** [*option* ...] *command*
> +
> +DESCRIPTION
> +===========
> +
> +Intel graphics register multitool. Read, write, dump, and decode Intel graphics
> +MMIO and sideband registers, and more.
> +
> +OPTIONS
> +=======
> +
> +Some options are global, and some specific to commands.
> +
> +--verbose
> +---------
> +
> +Increase verbosity.
> +
> +--quiet
> +-------
> +
> +Decrease verbosity.
> +
> +--count=N
> +---------
> +
> +Read N registers.
> +
> +--binary
> +--------
> +
> +Output binary values.
> +
> +--all
> +-----
> +
> +Decode registers for all known platforms.
> +
> +--mmio=FILE
> +-----------
> +
> +Use MMIO bar from FILE.
> +
> +--devid=DEVID
> +-------------
> +
> +Pretend to be PCI ID DEVID. Useful with MMIO bar snapshots from other machines.
> +
> +--spec=PATH
> +-----------
> +
> +Read register spec from directory or file specified by PATH; see REGISTER SPEC
> +DEFINITIONS below for details.
> +
> +--help
> +------
> +
> +Show brief help.
> +
> +COMMANDS
> +========
> +
> +See REGISTER REFERENCES below on how to describe registers for the commands.
> +
> +read [--count=N] REGISTER [...]
> +-------------------------------
> +
> +Dump each specified REGISTER, or N registers starting from each REGISTER.
> +
> +write REGISTER VALUE [REGISTER VALUE ...]
> +-----------------------------------------
> +
> +Write each VALUE to corresponding REGISTER.
> +
> +dump [--mmio=FILE --devid=DEVID]
> +--------------------------------
> +
> +Dump all registers specified in the register spec.
> +
> +decode REGISTER VALUE
> +---------------------
> +
> +Decode REGISTER VALUE.
> +
> +snapshot
> +--------
> +
> +Output the MMIO bar to stdout. The output can be used for a later invocation of
> +dump or read with the --mmio=FILE and --devid=DEVID parameters.
> +
> +list
> +----
> +
> +List the known registers.
> +
> +help
> +----
> +
> +Display brief help.
> +
> +
> +REGISTER REFERENCES
> +===================
> +
> +Registers are defined as [(PORTNAME|PORTNUM|MMIO-OFFSET):](REGNAME|REGADDR).
> +
> +PORTNAME
> +--------
> +
> +The register access method, most often MMIO, which is the default. The methods
> +supported on all platforms are "mmio", "portio-vga", and "mmio-vga".
> +
> +On BYT and CHV, the sideband ports "bunit", "punit", "nc", "dpio", "gpio-nc",
> +"cck", "ccu", "dpio2", and "flisdsi" are also supported.
> +
> +PORTNUM
> +-------
> +
> +Port number for the sideband ports supported on BYT and CHV. Only numbers mapped
> +to the supported ports are allowed, arbitrary numbers are not accepted.
> +
> +Numbers above 0xff are automatically interpreted as MMIO offsets, not port
> +numbers.
> +
> +MMIO-OFFSET
> +-----------
> +
> +Use MMIO, and add this offset to the register address.
> +
> +Numbers equal to or below 0xff are automatically interpreted as port numbers,
> +not MMIO offsets.
> +
> +REGNAME
> +-------
> +
> +Name of the register as defined in the register spec.
> +
> +If MMIO offset is not specified, it is picked up from the register
> +spec. However, ports are not; the port is a namespace for the register names.
> +
> +REGADDR
> +-------
> +
> +Register address. The corresponding register name need not be specified in the
> +register spec.
> +
> +ENVIRONMENT
> +===========
> +
> +INTEL_REG_SPEC
> +--------------
> +
> +Path to a directory or a file containing register spec definitions.
> +
> +REGISTER SPEC DEFINITIONS
> +=========================
> +
> +A register spec associates register names with addresses. The spec is searched
> +for in this order:
> +
> +#. Directory or file specified by the --spec option.
> +
> +#. Directory or file specified by the INTEL_REG_SPEC environment variable.
> +
> +#. Builtin register spec. Also used as fallback with a warning if the above are
> +   used but fail.
> +
> +If a directory is specified using --spec option or INTEL_REG_SPEC environment
> +variable, the directory is scanned for a spec file in this order:
> +
> +#. File named after the PCI device id. For example, "0412".
> +
> +#. File named after the code name in lowercase, without punctuation. For
> +   example, "valleyview".
> +
> +#. File named after generation. For example, "gen7" (note that this matches
> +   valleyview, ivybridge and haswell!).
> +
> +Register Spec File Format
> +-------------------------
> +
> +The register spec format is compatible with the quick_dump.py format, briefly
> +described below:
> +
> +* Empty lines and lines beginning with "#", ";", or "//" are ignored.
> +
> +* Lines *not* beginning with "(" are interpreted as file names, absolute or
> +  relative, to be included.
> +
> +* Lines beginning with "(" are interpreted as register definitions.
> +
> +Registers are defined as tuples ('REGNAME', 'REGADDR',
> +'PORTNAME|PORTNUM|MMIO-OFFSET'), as in REGISTER REFERENCES above. The port
> +description may also be an empty string to denote MMIO.
> +
> +Examples:
> +
> +* # this is a comment, below is an include
> +
> +* vlv_pipe_a.txt
> +
> +* ('GEN6_PMINTRMSK', '0x0000a168', '')
> +
> +* ('MIPIA_PORT_CTRL', '0x61190', '0x180000')
> +
> +* ('PLL1_DW0', '0x8000', 'DPIO')
> +
> +BUGS
> +====
> +
> +Reading some registers may hang the GPU or the machine.
> --
> 2.1.4
>