libdrm: man page infrastructure and a few sample man pages
authorJesse Barnes <jbarnes@virtuousgeek.org>
Thu, 6 Sep 2012 23:16:50 +0000 (16:16 -0700)
committerJesse Barnes <jbarnes@virtuousgeek.org>
Mon, 17 Sep 2012 15:07:04 +0000 (08:07 -0700)
Makefile.am
configure.ac
man/Makefile.am [new file with mode: 0644]
man/drmAvailable.man [new file with mode: 0644]
man/drmHandleEvent.man [new file with mode: 0644]
man/drmModeGetResources.man [new file with mode: 0644]

index 256a8cc9979cda4741bfb95803e823f4245a80c4..8ecd9d93cf462fb42b029f531ba9103eb6dbb6ad 100644 (file)
@@ -49,7 +49,7 @@ if HAVE_EXYNOS
 EXYNOS_SUBDIR = exynos
 endif
 
 EXYNOS_SUBDIR = exynos
 endif
 
-SUBDIRS = . $(LIBKMS_SUBDIR) $(INTEL_SUBDIR) $(NOUVEAU_SUBDIR) $(RADEON_SUBDIR) $(OMAP_SUBDIR) $(EXYNOS_SUBDIR) tests include
+SUBDIRS = . $(LIBKMS_SUBDIR) $(INTEL_SUBDIR) $(NOUVEAU_SUBDIR) $(RADEON_SUBDIR) $(OMAP_SUBDIR) $(EXYNOS_SUBDIR) tests include man
 
 libdrm_la_LTLIBRARIES = libdrm.la
 libdrm_ladir = $(libdir)
 
 libdrm_la_LTLIBRARIES = libdrm.la
 libdrm_ladir = $(libdir)
index 51c1d2c94e5c8b3f1b178900778913a6a64c9238..290362c468d4f05e7d0d58ec26355d32619df48a 100644 (file)
@@ -35,6 +35,27 @@ AM_MAINTAINER_MODE([enable])
 # Enable quiet compiles on automake 1.11.
 m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
 
 # Enable quiet compiles on automake 1.11.
 m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
 
+if test x$LIB_MAN_SUFFIX = x    ; then
+    LIB_MAN_SUFFIX=3
+fi
+if test x$LIB_MAN_DIR = x    ; then
+    LIB_MAN_DIR='$(mandir)/man$(LIB_MAN_SUFFIX)'
+fi
+AC_SUBST([LIB_MAN_SUFFIX])
+AC_SUBST([LIB_MAN_DIR])
+
+MAN_SUBSTS="\
+       -e 's|__vendorversion__|\"\$(PACKAGE_STRING)\" |' \
+       -e 's|__projectroot__|\$(prefix)|g' \
+       -e 's|__apploaddir__|\$(appdefaultdir)|g' \
+       -e 's|__appmansuffix__|\$(APP_MAN_SUFFIX)|g' \
+       -e 's|__drivermansuffix__|\$(DRIVER_MAN_SUFFIX)|g' \
+       -e 's|__adminmansuffix__|\$(ADMIN_MAN_SUFFIX)|g' \
+       -e 's|__libmansuffix__|\$(LIB_MAN_SUFFIX)|g' \
+       -e 's|__miscmansuffix__|\$(MISC_MAN_SUFFIX)|g' \
+       -e 's|__filemansuffix__|\$(FILE_MAN_SUFFIX)|g'"
+AC_SUBST([MAN_SUBSTS])
+
 # Check for programs
 AC_PROG_CC
 
 # Check for programs
 AC_PROG_CC
 
@@ -333,6 +354,7 @@ AC_CONFIG_FILES([
        tests/vbltest/Makefile
        include/Makefile
        include/drm/Makefile
        tests/vbltest/Makefile
        include/Makefile
        include/drm/Makefile
+       man/Makefile
        libdrm.pc])
 AC_OUTPUT
 
        libdrm.pc])
 AC_OUTPUT
 
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644 (file)
index 0000000..73068e6
--- /dev/null
@@ -0,0 +1,11 @@
+libmandir = $(LIB_MAN_DIR)
+libman_PRE = drmAvailable.man \
+       drmHandleEvent.man \
+       drmModeGetResources.man
+libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@)
+EXTRA_DIST = $(libman_PRE)
+CLEANFILE = $(libman_DATA)
+SUFFIXES = .$(LIB_MAN_SUFFIX) .man
+
+.man.$(LIB_MAN_SUFFIX):
+       $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
diff --git a/man/drmAvailable.man b/man/drmAvailable.man
new file mode 100644 (file)
index 0000000..e1bb8dc
--- /dev/null
@@ -0,0 +1,25 @@
+.\" shorthand for double quote that works everywhere.
+.ds q \N'34'
+.TH drmAvailable  __drivermansuffix__ __vendorversion__
+.SH NAME
+drmAvailable \- determine whether a DRM kernel driver has been loaded
+.SH SYNOPSIS
+.nf
+.B "#include <xf86drm.h>"
+
+.B "int drmAvailable(void);"
+.fi
+.SH DESCRIPTION
+This function allows the caller to determine whether a kernel DRM driver is
+loaded.
+
+.SH RETURN VALUE
+If a DRM driver is currently loaded, this function returns 1.  Otherwise 0
+is returned.
+
+.SH REPORTING BUGS
+Bugs in this function should be reported to http://bugs.freedesktop.org under
+the "Mesa" product, with "Other" or "libdrm" as the component.
+
+.SH "SEE ALSO"
+drmOpen(__libmansuffix__)
diff --git a/man/drmHandleEvent.man b/man/drmHandleEvent.man
new file mode 100644 (file)
index 0000000..b98f417
--- /dev/null
@@ -0,0 +1,45 @@
+.\" shorthand for double quote that works everywhere.
+.ds q \N'34'
+.TH drmHandleEvent  __drivermansuffix__ __vendorversion__
+.SH NAME
+drmHandleEvent \- read and process pending DRM events
+.SH SYNOPSIS
+.nf
+.B "#include <xf86drm.h>"
+
+.B "typedef struct _drmEventContext {"
+.BI "  int version;"
+.BI "  void (*vblank_handler)(int fd,"
+.BI "                         unsigned int sequence,"
+.BI "                         unsigned int tv_sec,"
+.BI "                         unsigned int tv_usec,"
+.BI "                         void *user_data);"
+.BI "  void (*page_flip_handler)(int fd,"
+.BI "                            unsigned int sequence,"
+.BI "                            unsigned int tv_sec,"
+.BI "                            unsigned int tv_usec,"
+.BI "                            void *user_data);"
+.B "} drmEventContext, *drmEventContextPtr;"
+
+.B "int drmHandleEvent(int fd, drmEventContextPtr evctx);"
+.fi
+.SH DESCRIPTION
+This function will process outstanding DRM events on
+.I fd
+, which must be an open DRM device.  This function should be called after
+the DRM file descriptor has polled readable; it will read the events and
+use the passed-in
+.I evctx
+structure to call function pointers with the parameters noted above.
+
+.SH RETURN VALUE
+Returns 0 on success, or if there is no data to read from the file descriptor.
+Returns -1 if the read on the file descriptor fails or returns less than a
+full event record.
+
+.SH REPORTING BUGS
+Bugs in this function should be reported to http://bugs.freedesktop.org under
+the "Mesa" product, with "Other" or "libdrm" as the component.
+
+.SH "SEE ALSO"
+drmModePageFlip(__libmansuffix__), drmWaitVBlank(__libmansuffix__)
diff --git a/man/drmModeGetResources.man b/man/drmModeGetResources.man
new file mode 100644 (file)
index 0000000..369bf7d
--- /dev/null
@@ -0,0 +1,79 @@
+.\" shorthand for double quote that works everywhere.
+.ds q \N'34'
+.TH drmModeGetResources  __drivermansuffix__ __vendorversion__
+.SH NAME
+drmModeGetResources \- retrieve current display configuration information
+.SH SYNOPSIS
+.nf
+.B "#include <xf86drmMode.h>"
+
+.BI "typedef struct _drmModeRes {"
+
+.BI "  int count_fbs;"
+.BI "  uint32_t *fbs;"
+
+.BI "  int count_crtcs;"
+.BI "  uint32_t *crtcs;"
+
+.BI "  int count_connectors;"
+.BI "  uint32_t *connectors;"
+
+.BI "  int count_encoders;"
+.BI "  uint32_t *encoders;"
+
+.BI "  uint32_t min_width, max_width;"
+.BI "  uint32_t min_height, max_height;"
+.B "} drmModeRes, *drmModeResPtr;"
+
+.B "drmModeResPtr drmModeGetResources(int fd);"
+.fi
+.SH DESCRIPTION
+This function will allocate, populate, and return a drmModeRes structure
+containing information about the current display configuration.
+
+The
+.I count_fbs
+and
+.I fbs
+fields indicate the number of currently allocated framebuffer objects (i.e.
+objects that can be attached to a given CRTC or sprite for display).
+
+The
+.I count_crtcs
+and
+.I crtcs
+fields list the available CRTCs in the configuration.  A CRTC is simply
+an object that can scan out a framebuffer to a display sink, and contains
+mode timing and relative position information.  CRTCs drive encoders, which
+are responsible for converting the pixel stream into a specific display
+protocol (e.g. MIPI or HDMI).
+
+The
+.I count_connectors
+and
+.I connectors
+fields list the available physical connectors on the system.  Note that
+some of these may not be exposed from the chassis (e.g. LVDS or eDP).
+Connectors are attached to encoders and contain information about the
+attached display sink (e.g. width and height in mm, subpixel ordering, and
+various other properties).
+
+The
+.I count_encoders
+and
+.I encoders
+fields list the available encoders on the device.  Each encoder may be
+associated with a CRTC, and may be used to drive a particular encoder.
+
+The min and max height fields indicate the maximum size of a framebuffer
+for this device (i.e. the scanout size limit).
+
+.SH RETURN VALUE
+Returns a drmModeRes structure pointer on success, 0 on failure.
+
+.SH REPORTING BUGS
+Bugs in this function should be reported to http://bugs.freedesktop.org under
+the "Mesa" product, with "Other" or "libdrm" as the component.
+
+.SH "SEE ALSO"
+drmModeGetFB(__libmansuffix__), drmModeAddFB(__libmansuffix__), drmModeAddFB2(__libmansuffix__), drmModeRmFB(__libmansuffix__), drmModeDirtyFB(__libmansuffix__), drmModeGetCrtc(__libmansuffix__), drmModeSetCrtc(__libmansuffix__), drmModeGetEncoder(__libmansuffix__), drmModeGetConnector(__libmansuffix__)