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

[Jani Nikula <jani.nikula@intel.com>]

On Mon, 04 May 2015, Daniel Vetter <daniel@ffwll.ch> wrote:
> 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@intel.com>
>
> Just curiosity, but should we convert the existing manpages to rst too?
> rst is so much nicer ...

I guess I could do some of it on the side... however we'd need to settle
what to do with the $(SED) $(MAN_SUBSTS) part that replaces certain tags
in .man to produce the .1. MAN_SUBST comes from "xorg-macros.m4 via
configure" per man/Makefile.am. It doesn't really work on .rst or the
rst2man result, already tried that.

rst and rst2man do support metadata in the .rst, see what I added to
intel_reg.rst for example. It's just a question of what to put there and
how.

Thomas, ideas?


BR,
Jani.


> -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@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@lists.freedesktop.org
>> http://lists.freedesktop.org/mailman/listinfo/intel-gfx
>
> -- 
> Daniel Vetter
> Software Engineer, Intel Corporation
> http://blog.ffwll.ch

-- 
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx