From 2426a6a7112ae62755408a371831eddbe2d89d99 Mon Sep 17 00:00:00 2001 From: Jesse Barnes Date: Thu, 6 Sep 2012 16:16:50 -0700 Subject: libdrm: man page infrastructure and a few sample man pages --- Makefile.am | 2 +- configure.ac | 22 +++++++++++++ man/Makefile.am | 11 +++++++ man/drmAvailable.man | 25 ++++++++++++++ man/drmHandleEvent.man | 45 ++++++++++++++++++++++++++ man/drmModeGetResources.man | 79 +++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 183 insertions(+), 1 deletion(-) create mode 100644 man/Makefile.am create mode 100644 man/drmAvailable.man create mode 100644 man/drmHandleEvent.man create mode 100644 man/drmModeGetResources.man diff --git a/Makefile.am b/Makefile.am index 256a8cc9..8ecd9d93 100644 --- a/Makefile.am +++ b/Makefile.am @@ -49,7 +49,7 @@ if HAVE_EXYNOS 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) diff --git a/configure.ac b/configure.ac index 51c1d2c9..290362c4 100644 --- a/configure.ac +++ b/configure.ac @@ -35,6 +35,27 @@ AM_MAINTAINER_MODE([enable]) # 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 @@ -333,6 +354,7 @@ AC_CONFIG_FILES([ tests/vbltest/Makefile include/Makefile include/drm/Makefile + man/Makefile libdrm.pc]) AC_OUTPUT diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 00000000..73068e68 --- /dev/null +++ b/man/Makefile.am @@ -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 index 00000000..e1bb8dc8 --- /dev/null +++ b/man/drmAvailable.man @@ -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 " + +.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 index 00000000..b98f417d --- /dev/null +++ b/man/drmHandleEvent.man @@ -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 " + +.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 index 00000000..369bf7d8 --- /dev/null +++ b/man/drmModeGetResources.man @@ -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 " + +.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__) -- cgit v1.2.3