man: add man page for intel_reg in reStructured text format
PATCH v2 1/1 man: add man page for intel_reg in reStructured text format
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.
--- 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
README +1 -0
@@ -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
configure.ac +3 -0
@@ -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
man/Makefile.am +12 -0
@@ -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 < $< > $@
man/intel_reg.rst new file +229 -0
229 lines not on this page · raw message
Signature · 6 lines
2.1.4 _______________________________________________ Intel-gfx mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Quoted 7 lines · Jani Nikula
Produce the
intel_regman 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 <[email protected]>
Just curiosity, but should we convert the existing manpages to rst too? rst is so much nicer ...
-Daniel
Quoted 303 lines
--- 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.rstREADME +1
-0@@ -150,6 +150,7 @@ everything (package names may vary): libpciaccess-dev libpython3.3-dev libunwind-dev + python-docutils swig2.0 x11proto-dri2-dev xutils-devconfigure.ac +3
-0@@ -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_STDCman/Makefile.am +12
-0@@ -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 < $< > $@man/intel_reg.rst new file +229
-0@@ -0,0 +1,229 @@ +========= +intel_reg +========= + +--------------------------------- +Intel graphics register multitool +--------------------------------- + +:Author: Jani Nikula <[email protected]> +: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.Signature · 6 lines
2.1.4 _______________________________________________ Intel-gfx mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ Intel-gfx mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Quoted 11 lines · Daniel Vetter
Quoted 7 lines · Jani Nikula
Produce the
intel_regman 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 <[email protected]>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.
Quoted 310 lines
-Daniel
Quoted 303 lines
--- 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.rstREADME +1
-0@@ -150,6 +150,7 @@ everything (package names may vary): libpciaccess-dev libpython3.3-dev libunwind-dev + python-docutils swig2.0 x11proto-dri2-dev xutils-devconfigure.ac +3
-0@@ -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_STDCman/Makefile.am +12
-0@@ -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 < $< > $@man/intel_reg.rst new file +229
-0@@ -0,0 +1,229 @@ +========= +intel_reg +========= + +--------------------------------- +Intel graphics register multitool +--------------------------------- + +:Author: Jani Nikula <[email protected]> +: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.Signature · 6 lines
2.1.4 _______________________________________________ Intel-gfx mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/intel-gfxSignature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
Signature · 5 lines
Jani Nikula, Intel Open Source Technology Center _______________________________________________ Intel-gfx mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/intel-gfx