Add API documentation support
Subsystems (2)
PATCH 1/2 Add API documentation support
Add optional support for building API documentation using gtk-doc.
Signed-off-by Thomas Wood <[email protected]>
--- .gitignore | 3 + Makefile.am | 2 +- NEWS | 2 + autogen.sh | 7 ++ configure.ac | 12 +++ docs/Makefile.am | 1 + docs/reference/Makefile.am | 1 + docs/reference/intel-gpu-tools/.gitignore | 26 +++++ docs/reference/intel-gpu-tools/Makefile.am | 105 +++++++++++++++++++++ .../intel-gpu-tools/intel-gpu-tools-docs.xml | 40 ++++++++ docs/reference/intel-gpu-tools/version.xml.in | 1 + 11 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 docs/Makefile.am create mode 100644 docs/reference/Makefile.am create mode 100644 docs/reference/intel-gpu-tools/.gitignore create mode 100644 docs/reference/intel-gpu-tools/Makefile.am create mode 100644 docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml create mode 100644 docs/reference/intel-gpu-tools/version.xml.in
.gitignore +3 -0
@@ -83,3 +83,6 @@ TAGS build-aux/ __pycache__ version.h + +gtk-doc.make +gtk-doc.m4
Makefile.am +1 -1
@@ -21,7 +21,7 @@ ACLOCAL_AMFLAGS = ${ACLOCAL_FLAGS} -I m4 -SUBDIRS = lib man tools scripts benchmarks demos overlay +SUBDIRS = docs lib man tools scripts benchmarks demos overlay if BUILD_ASSEMBLER SUBDIRS += assembler
NEWS +2 -0
@@ -26,6 +26,8 @@ Release 1.6 (2014-XX-YY) - Broadwell support for intel_audio_dump (Mengdong Lin). +- API documentation support (Thomas) + Release 1.5 (2013-11-06) ------------------------
autogen.sh +7 -0
@@ -6,6 +6,13 @@ test -z "$srcdir" && srcdir=. ORIGDIR=`pwd` cd $srcdir +if ! type gtkdocize > /dev/null 2>&1; then + echo "EXTRA_DIST =" > gtk-doc.make + echo "CLEANFILES =" >> gtk-doc.make +else + gtkdocize || exit $? +fi + autoreconf -v --install || exit 1 cd $ORIGDIR || exit $?
configure.ac +12 -0
@@ -42,6 +42,14 @@ AC_PROG_CC AM_PROG_LEX AC_PROG_YACC +# check for gtk-doc +m4_ifdef([GTK_DOC_CHECK], [ +GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) +],[ +AM_CONDITIONAL([ENABLE_GTK_DOC], false) +]) + + # Checks for functions, headers, structures, etc. AC_HEADER_STDC AC_CHECK_HEADERS([termios.h])
@@ -192,6 +200,10 @@ AC_CONFIG_FILES([ Makefile benchmarks/Makefile demos/Makefile + docs/Makefile + docs/reference/Makefile + docs/reference/intel-gpu-tools/Makefile + docs/reference/intel-gpu-tools/version.xml lib/Makefile man/Makefile scripts/Makefile
docs/Makefile.am new file +1 -0
@@ -0,0 +1 @@ +SUBDIRS=reference
docs/reference/Makefile.am new file +1 -0
@@ -0,0 +1 @@ +SUBDIRS = intel-gpu-tools
docs/reference/intel-gpu-tools/.gitignore new file +26 -0
@@ -0,0 +1,26 @@ +/gtkdoc-check.log +/gtkdoc-check.trs +/html-build.stamp +/html.stamp +/html/ +/intel-gpu-tools-decl-list.txt +/intel-gpu-tools-decl.txt +/intel-gpu-tools-overrides.txt +/intel-gpu-tools-sections.txt +/intel-gpu-tools-undeclared.txt +/intel-gpu-tools-undocumented.txt +/intel-gpu-tools-unused.txt +/intel-gpu-tools.args +/intel-gpu-tools.hierarchy +/intel-gpu-tools.interfaces +/intel-gpu-tools.prerequisites +/intel-gpu-tools.signals +/intel-gpu-tools.types +/scan-build.stamp +/setup-build.stamp +/sgml-build.stamp +/sgml.stamp +/test-suite.log +/version.xml +/xml/ +
docs/reference/intel-gpu-tools/Makefile.am new file +105 -0
105 lines not on this page · raw message
docs/reference/intel-gpu-tools/intel-gpu-tools-docs.xml new file +40 -0
@@ -0,0 +1,40 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> + <!ENTITY version SYSTEM "version.xml"> +]> +<book id="index"> + <bookinfo> + <title>intel-gpu-tools Reference Manual</title> + <releaseinfo> + for intel-gpu-tools &version;. + </releaseinfo> + </bookinfo> + + <chapter> + <title>Intel GPU Tools</title> + <xi:include href="xml/debug.xml"/> + <xi:include href="xml/drmtest.xml"/> + <xi:include href="xml/igt_debugfs.xml"/> + <xi:include href="xml/igt_display.xml"/> + <xi:include href="xml/igt_kms.xml"/> + <xi:include href="xml/intel_batchbuffer.xml"/> + <xi:include href="xml/intel_chipset.xml"/> + <xi:include href="xml/intel_gpu_tools.xml"/> + <xi:include href="xml/media_fill.xml"/> + <xi:include href="xml/rendercopy.xml"/> + + </chapter> + <index id="api-index-full"> + <title>API Index</title> + <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include> + </index> + <index id="deprecated-api-index" role="deprecated"> + <title>Index of deprecated API</title> + <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include> + </index> + + <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> +</book>
docs/reference/intel-gpu-tools/version.xml.in new file +1 -0
@@ -0,0 +1 @@ +@PACKAGE_VERSION@
Signature · 1 line
1.8.5.3
PATCH 2/2 drmtest: reformat the API documentation
Make the existing documentation compatible with gtk-doc.
Signed-off-by Thomas Wood <[email protected]>
--- lib/drmtest.c | 19 ++++++++--------- lib/drmtest.h | 65 +++++++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 60 insertions(+), 24 deletions(-)
lib/drmtest.c +10 -9
@@ -176,9 +176,11 @@ void gem_quiescent_gpu(int fd) }/** -* drm_get_card() - get an intel card number for use in /dev or /sys +* drm_get_card: * -* returns -1 on error +* Get an intel card number for use in /dev or /sys +* +* Returns: -1 on error */ int drm_get_card (void ) {
@@ -1241,11 +1243,6 @@ bool __igt_fork_helper(struct igt_helper_process *proc) } -/** -* igt_waitchildren - wait for all children forked with igt_fork -* -* The magic here is that exit codes from children will be correctly propagated -*/ void igt_stop_helper (struct igt_helper_process *proc) {int status, ret;
@@ -1338,7 +1335,9 @@ bool __igt_fork(void) }/** -* igt_waitchildren - wait for all children forked with igt_fork +* igt_waitchildren: +* +* Wait for all children forked with igt_fork * * The magic here is that exit codes from children will be correctly propagated */
@@ -1394,7 +1393,9 @@ bool igt_run_in_simulation(void) }/** -* igt_skip_on_simulation - skip tests when INTEL_SIMULATION env war is set +* igt_skip_on_simulation: +* +* Skip tests when INTEL_SIMULATION env war is set * * Skip the test when running on simulation (and that's relevant only when * we're not in the mode where we list the subtests).
lib/drmtest.h +50 -15
152 lines not on this page · raw message
Signature · 1 line
1.8.5.3
Re: [PATCH i-g-t 2/2] drmtest: reformat the API documentation
Quoted 3 lines · Thomas Wood
Make the existing documentation compatible with gtk-doc.
Signed-off-by Thomas Wood <[email protected]>
Both patches merged, with a little patch on top to pimp the configure output and README.
Thanks, Daniel
Quoted 231 lines
--- lib/drmtest.c | 19 ++++++++--------- lib/drmtest.h | 65 +++++++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 60 insertions(+), 24 deletions(-)lib/drmtest.c +10
-9@@ -176,9 +176,11 @@ void gem_quiescent_gpu(int fd) }/** -* drm_get_card() - get an intel card number for use in /dev or /sys +* drm_get_card: * -* returns -1 on error +* Get an intel card number for use in /dev or /sys +* +* Returns: -1 on error */ int drm_get_card (void ) {@@ -1241,11 +1243,6 @@ bool __igt_fork_helper(struct igt_helper_process *proc) } -/** -* igt_waitchildren - wait for all children forked with igt_fork -* -* The magic here is that exit codes from children will be correctly propagated -*/ void igt_stop_helper (struct igt_helper_process *proc) {int status, ret;@@ -1338,7 +1335,9 @@ bool __igt_fork(void) }/** -* igt_waitchildren - wait for all children forked with igt_fork +* igt_waitchildren: +* +* Wait for all children forked with igt_fork * * The magic here is that exit codes from children will be correctly propagated */ @@ -1394,7 +1393,9 @@ bool igt_run_in_simulation(void) }/** -* igt_skip_on_simulation - skip tests when INTEL_SIMULATION env war is set +* igt_skip_on_simulation: +* +* Skip tests when INTEL_SIMULATION env war is set * * Skip the test when running on simulation (and that's relevant only when * we're not in the mode where we list the subtests). lib/drmtest.h +50
-15@@ -110,7 +110,11 @@ void igt_permute_array(void *array, unsigned size, unsigned j));void igt_progress (const char *header,uint64_t i,uint64_t total); -/* init for simple tests without subtests */ +/** +* igt_simple_init: +* +* Init for simple tests without subtests +*/ void igt_simple_init (void );#define igt_simple_main \ static void igt_tokencat(__real_main, __LINE__)(void); \@@ -133,7 +137,9 @@ int igt_subtest_init_parse_opts(int argc, char **argv, igt_opt_handler_t opt_handler);bool __igt_run_subtest (const char *subtest_name);/** -* igt_subtest/_f - Denote a subtest code block +* igt_subtest: +* +* Denote a subtest code block * * Magic control flow which denotes a subtest code block. Within that codeblock * igt_skip|success will only bail out of the subtest. The _f variant accepts a @@ -148,6 +154,15 @@ bool __igt_run_subtest(const char *subtest_name);__igt_run_subtest ( tmp ) && \ (setjmp (igt_subtest_jmpbuf) ==0 ); \ igt_success()) + +/** +* igt_subtest_f: +* @...: format string +* +* Denote a subtest code block +* +* Like #igt_subtest, but also accepts a printf format string +*/ #define igt_subtest_f(f...) \ __igt_subtest_f(igt_tokencat(__tmpchar, __LINE__), f)#define igt_subtest (name) for (; __igt_run_subtest((name)) && \@@ -165,27 +180,35 @@ const char *igt_subtest_name(void);/** -* igt_skip - subtest aware test skipping +* igt_skip: +* +* Subtest aware test skipping * * For tests with subtests this will either bail out of the current subtest or * mark all subsequent subtests as SKIP (in case some global setup code failed). * * For normal tests without subtest it will directly exit. */ -__attribute__((format (printf,1 ,2 )))void igt_skip (const char *f, ...) __attribute__((noreturn)); +__attribute__((format (printf,1 ,2 ))) +void igt_skip (const char *f, ...) __attribute__((noreturn)); __attribute__((format (printf,5 ,6 )))void __igt_skip_check (const char *file,const int line,const char *func,const char *check,const char *format, ...) __attribute__((noreturn));/** -* igt_success - complete a (subtest) as successfull +* igt_success: +* +* Complete a (subtest) as successfull * * This bails out of a subtests and marks it as successful. For global tests it * it won't bail out of anything. */ void igt_success (void ); +/** -* igt_fail - fail a testcase +* igt_fail: +* +* Fail a testcase * * For subtest it just bails out of the subtest, when run in global context it * will exit. Note that it won't attempt to keep on running further tests, @@ -198,7 +221,9 @@ void __igt_fail_assert(int exitcode, const char *file, const char *format, ...) __attribute__((noreturn));/** -* igt_exit - exit() for igts +* igt_exit: +* +* exit() for igts * * This will exit the test with the right exit code when subtests have been * skipped. For normal tests it exits with a successful exit code, presuming @@ -207,7 +232,9 @@ void __igt_fail_assert(int exitcode, const char *file,*/ void igt_exit (void ) __attribute__((noreturn));/** -* igt_assert - fails (sub-)test if a condition is not met +* igt_assert: +* +* Fails (sub-)test if a condition is not met * * Should be used everywhere where a test checks results. */ @@ -220,9 +247,9 @@ void igt_exit(void) __attribute__((noreturn)); __igt_fail_assert(99, __FILE__, __LINE__, __func__, #expr , f); \ }while (0 )/** -* igt_assert_cmptint +* igt_assert_cmptint: * -* Like igt_assert(), but displays the values being compared on failure. +* Like #igt_assert, but displays the values being compared on failure. */#define igt_assert_cmpint (n1, cmp, n2) \ do { \@@ -234,7 +261,9 @@ void igt_exit(void) __attribute__((noreturn)); }while (0 )/** -* igt_require - skip a (sub-)test if a condition is not met +* igt_require: +* +* Skip a (sub-)test if a condition is not met * * This is useful to streamline the skip logic since it allows for a more flat * code control flow. @@ -254,8 +283,10 @@ bool __igt_fixture(void);void __igt_fixture_complete (void );void __igt_fixture_end (void ) __attribute__((noreturn));/** -* igt_fixture - annote global test fixture code -* +* igt_fixture: +* +* Annotate global test fixture code +* * Testcase with subtests often need to set up a bunch of global state as the * common test fixture. To avoid such code interferring with the subtest * enumeration (e.g. when enumerating on systemes without an intel gpu) such @@ -270,10 +301,12 @@ void __igt_fixture_end(void) __attribute__((noreturn));bool __igt_fork (void );/** -* igt_fork - fork parallel test threads with fork() +* igt_fork: * @child: name of the int variable with the child number * @num_children: number of children to fork * +* Fork parallel test threads with fork() +* * Joining all test threads should be done with igt_waitchildren to ensure that * the exit codes of all children are properly reflected in the test status. */ @@ -349,7 +382,9 @@ static inline void gem_require_ring(int fd, int ring_id)bool igt_run_in_simulation (void );#define SLOW_QUICK (slow,quick) (igt_run_in_simulation() ? (quick) : (slow))/** -* igt_skip_on_simulation - skip tests when INTEL_SIMULATION env war is set +* igt_skip_on_simulation: +* +* Skip tests when INTEL_SIMULATION env war is set * * Skip the test when running on simulation (and that's relevant only when * we're not in the mode where we list the subtests). Signature · 6 lines
1.8.5.3 _______________________________________________ Intel-gfx mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Signature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch