[Intel-gfx] [PATCH i-g-t v2] man: add man page for intel_reg in reStructured text format

[Daniel Vetter]

On Tue, Apr 28, 2015 at 03:30:54PM +0300, Jani Nikula wrote:
> Produce the intel_reg man page from rst using rst2man. Also facilitate
> writing any man page in reStructured text, as long as rst2man is
> available.
> 
> v2: configure check for rst2man, credits to Thomas Wood for that.
> 
> Signed-off-by: Jani Nikula <jani.nikula at intel.com>

Just curiosity, but should we convert the existing manpages to rst too?
rst is so much nicer ...
-Daniel

> ---
>  README            |   1 +
>  configure.ac      |   3 +
>  man/Makefile.am   |  12 +++
>  man/intel_reg.rst | 229 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  4 files changed, 245 insertions(+)
>  create mode 100644 man/intel_reg.rst
> 
> diff --git a/README b/README
> index 6f1ac8622881..ac9f8ad5662e 100644
> --- a/README
> +++ b/README
> @@ -150,6 +150,7 @@ everything (package names may vary):
>  	libpciaccess-dev
>  	libpython3.3-dev
>  	libunwind-dev
> +	python-docutils
>  	swig2.0
>  	x11proto-dri2-dev
>  	xutils-dev
> diff --git a/configure.ac b/configure.ac
> index 51595ade7b0e..5ae1e9f4a658 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -50,6 +50,9 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false)
>  enable_gtk_doc=no
>  ])
>  
> +# check for rst2man for generating man pages
> +AC_CHECK_PROG(RST2MAN, rst2man, yes, no)
> +AM_CONDITIONAL(HAVE_RST2MAN, [test "x$RST2MAN" = xyes])
>  
>  # Checks for functions, headers, structures, etc.
>  AC_HEADER_STDC
> diff --git a/man/Makefile.am b/man/Makefile.am
> index dcd79528f17b..ee09156c934e 100644
> --- a/man/Makefile.am
> +++ b/man/Makefile.am
> @@ -21,6 +21,14 @@ appman_PRE = 				\
>  
>  appman_DATA = $(appman_PRE:man=$(APP_MAN_SUFFIX))
>  
> +# man pages in rst, only used if we have rst2man
> +appman_RST =				\
> +	intel_reg.rst
> +
> +if HAVE_RST2MAN
> +appman_DATA += $(appman_RST:rst=$(APP_MAN_SUFFIX))
> +endif
> +
>  EXTRA_DIST = $(appman_PRE)
>  CLEANFILES = $(appman_DATA)
>  
> @@ -29,3 +37,7 @@ SUFFIXES = .$(APP_MAN_SUFFIX) .man
>  
>  .man.$(APP_MAN_SUFFIX):
>  	$(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
> +
> +# 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
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch