Fixed spacing for pkg config example.
[ikiwiki.git] / docs / developer / GEMdrmKMS / index.mdwn
index 63fac2a..0221295 100644 (file)
@@ -1,26 +1,76 @@
 # Port of GEM and KMS
 
-## Status
+A [Google Summer of Code 2010](http://socghop.appspot.com/gsoc/program/list_projects/google/gsoc2010) project.
 
-The latest drm code from FreeBSD 9.x current has been successfully ported to DragonFly BSD, [patch](http://leaf.dragonflybsd.org/~davshao/r600fbsd.diff) and git branch **r600fbsd** git://leaf.dragonflybsd.org/~davshao/dragonfly.git, and tested with a Radeon HD 4550 on an x86_64 machine (Shuttle SG45H7).  However it must be remembered that testing has only been done with this one graphics card and it is completely unknown whether say an Intel machine will lock up solid.  Also nothing was done to port the extensive Via drivers FreeBSD has already ported.
+Student: David Shao
+
+Mentor: Matthew Dillon
 
-## Introduction or what the heck is being talked about
+## Introduction
 
-We are talking about modern graphics card drivers that have already or are in the process of being written for Linux.  Fortunately for the BSDs the source code that is the basis of these drivers, part hosted in git repositories accessible from [freedesktop.org](http://cgit.freedesktop.org/), and even the part that is now residing in the Linux kernel, is mostly licensed under terms compatible with the [MIT X License](http://www.opensource.org/licenses/mit-license.php), and therefore can be directly ported to DragonFly.
+We port to the BSDs modern graphics card drivers that have already or are in the process of being written for Linux.  Fortunately for the BSDs the source code that is the basis of these drivers, userland hosted in git repositories accessible from [freedesktop.org](http://cgit.freedesktop.org/), and even the part that is now residing in the Linux kernel, is mostly licensed under terms compatible with the [MIT X License](http://www.opensource.org/licenses/mit-license.php), and therefore can be directly ported to the BSDs
+without licensing issues.
 
 When we refer to DRM, we are referring to the [Direct Render Manager](http://dri.freedesktop.org/wiki/DRM) that is a kernel module arbitrating requests for various graphics related services.  Because of this acronym, the source code for DragonFly's DRM module can be found in directory **sys/dev/drm**, while the source code for Linux'd DRM module has been split into **include/drm** hosting common header files and **drivers/gpu/drm**.  Furthermore the Linux files have had vendor specific code split off into their own separate directories, a change the BSDs should consider since having all files in one directory is becoming rather unwieldy.
 
-## Previous work makes the port possible
+We feel the fastest path to porting is through the DragonFly BSD project, but we intend for our code to be the basis for
+ports to all the BSDs.
+
+## Acknowledgment to the FreeBSD Project
+
+We must acknowledge the hard work that previous porters of DRM such as Robert Noland of the FreeBSD project have already
+accomplished in translating much of earlier DRM to BSD kernel semantics.  Simply take a diff of the FreeBSD and DragonFlyBSD
+versions of DRM and one can readily see that the hard work of translating the semantics of the locking for the Linux drivers
+has mostly been done, and better still can be done almost automatically.  Furthermore the FreeBSD port has translated calls
+to manipulating hardware devices such as for AGP.
+
+## Goal
+
+We intend to write a portability layer that will allow the BSDs to use as much of the Linux drm code as possible.
+The developers of X.org / freedesktop.org related graphics drivers have their current efforts focused on Linux
+because they have to get something working anywhere as fast as possible.  It is the BSDs responsibility to keep
+up with these efforts and to contribute back to these developers to justify the developers continuing
+to generously license their drm code under terms compatible with those of the BSD licenses.
+
+It is especially vital for Linux drm GEM, TTM, KMS code to be ported immediately to the BSDs because developers
+are in the process of removing userland modesetting code from current graphics drivers.  To paraphrase what
+we have been told by freedesktop.org developers, if we do not port this code, very shortly the BSDs will be
+left only using the simplest VESA driver at 1024 x 768 resolution with no hardware acceleration.
+
+We believe that limiting divergence from Linux's drm code is the clearest path for the BSDs to be able
+to follow the latest drm developments.
 
-Simply take a diff of the FreeBSD and DragonFlyBSD versions of DRM and one can readily see that the hard work of translating the semantics of the locking for the Linux drivers has mostly been done, and better still can be done almost automatically.  The FreeBSD port represents the limits of what can be ported having worked out exclusive access mechanisms, but not having completely worked out equivalents of other Linux APIs such as **idr**, small integer ID management.
+## Disclaimer
 
-## What has been done and should be done
+Code that is uploaded to the experimental git branches has been verified to work for at most
+two graphics cards only, both Radeon-compatible cards.  It is highly likely that systems exist
+where replacing kernel code using the experimental git branches will leave one's system unable
+to use software based on X.org.  In particular nothing is known about systems with graphics
+hardware from other vendors such as Intel or Nvidia.
 
-The software used for graphics whether the kernel or Mesa is surprisingly resilient.  As long as it compiles it will try and find a way with dealing with other mismatched components by falling back on default behavior.  Working on a fast x86_64 machine, it is easy to be lulled into a false sense that things are working properly unless one checks the logs.
+We have experienced from ill-fated experiments forced rebooting with corruption of a ufs2 root filesystem;
+therefore, the same could well happen to you.  Only use this code on a system with no valuable or
+irreplaceable data.  We disclaim any warranty or fitness of code.
 
-### **dmesg* output
+## Test Machines
 
-Here the proper kernel module appears to be loaded.  I wasted quite a bit of time earlier this week not realizing an error that led to the kernel module not being loaded at all that appeared from the messages to be a device non-existence problem.
+Our test machines both use Radeon-compatible graphics hardware: an
+older Radeon 9200-compatible card (r200) on an Asus P4B266 32-bit i386
+machine and a Radeon HD 4550 (r600) on a Shuttle SG45H7 64-bit x86_64 machine.
+
+We develop on the x86_64 machine then push our changes to the git experimental branch
+**gsocdrmalpha** at
+
+git://leaf.dragonflybsd.org/~davshao/dragonfly.git
+
+We then pull the changes to the i386 machine to test build and compatibility.
+
+
+### Sample **dmesg* output
+
+The software used for graphics whether the kernel or userland Mesa is surprisingly resilient.  As long as it compiles it will try and find a way with dealing with other mismatched components by falling back on default behavior.  Working on a fast x86_64 machine, it is easy to be lulled into a false sense that things are working properly unless one checks the logs.
+
+Here the proper kernel module appears to be loaded for the x86_64 machine.  We have on previous occasions not realized an error that led to the kernel module not being loaded at all that appeared from the messages to be a device non-existence problem.
 
     drm0: <ATI Radeon HD 4550> on vgapci0
     vgapci0: child drm0 requested pci_enable_busmaster
@@ -30,11 +80,21 @@ Here the proper kernel module appears to be loaded.  I wasted quite a bit of tim
     info: [drm] Resetting GPU
     info: [drm] writeback test succeeded in 1 usecs
 
+Similarly for the Radeon 9200-compatible i386 machine:
+
+    drm0: <ATI Radeon If RV250 9000> on vgapci0
+    vgapci0: child drm0 requested pci_enable_busmaster
+    info::[drm] AGP at 0xf8000000 64MB
+    info::[drm] Initialized radeon 1.31.0 20080613
+    info::[drm] Setting GART location based on new memory map
+    info::[drm] Loading R200 Microcode
+    info::[drm] writeback test succeeded in 1 usecs
+
 ### **var/log/Xorg.0.log** output
 
 Somewhere on one's system are the logs of the latest startup of the X server and the modules it finds.  There can be an alternate place if one installs a second X.org, say at */opt/xtest*, in which case instead of **/var/log/Xorg.0.log** one will look in **/opt/xtest/var/log/Xorg.0.log**.
 
-Here's a case of a failure where things are fine: I am composing this wiki from within Firefox 3.6.3 on a system where the proper module fails to load and yet where because of the machine's speed there is no discernible problem.
+Here's a case of a failure on the fast x86_64 machine where things appeared to be fine: we were composing this wiki from within Firefox 3.6.3 on a system where the proper module failed to load and yet where because of the machine's speed there was no discernible problem for this application.
 
     drmOpenDevice: node name is /dev/dri/card0
     drmOpenDevice: open result is 10, (OK)
@@ -47,9 +107,9 @@ Here's a case of a failure where things are fine: I am composing this wiki from
     (EE) AIGLX: reverting to software rendering
     (II) AIGLX: Loaded and initialized /usr/pkg/lib/dri/swrast_dri.so
 
-The Mesa 7.4.x series simply didn't *have* an r600_drv.so driver so of course it can't be found.  Mesa happily falls back to using software rendering and nothing seems greatly wrong.
+The Mesa 7.4.x series simply does not *have* a r600_drv.so driver so of course it can't be found.  Mesa happily falls back to using software rendering and nothing seems greatly wrong.
 
-Now here is an example using latest Mesa and everything else from git where the driver is found:
+Now here is an example using latest Mesa and everything else from git on the x86_64 machine where the driver is found on the x86_64 machine:
 
     [    95.404] drmOpenDevice: node name is /dev/dri/card0
     [    95.405] drmOpenDevice: open result is 11, (OK)
@@ -65,229 +125,72 @@ Now here is an example using latest Mesa and everything else from git where the
     [    95.507] (II) GLX: Initialized DRI GL provider for screen 0
     [    95.508] (II) RADEON(0): Setting screen physical size to 508 x 285
 
-Ironically I knew I was on the right track porting the latest git versions of the X.org stack when I succeeded in locking up hard my machine.  That meant a real hardware acceleration module was being loaded by that the previous kernel could not handle it, which was why the latest drm from FreeBSD had to be imported for Radeon r600.
-
-## Installing from pkgsrc
-
-### GNU m4 1.4.14 and bison 2.4.2
+Pkgsrc on the i386 r200 machine does have a supporting driver; therefore, we obtain from its log:
 
-Patch both *devel/m4* and *devel/bison* using the patch idea from:
-<http://www.netbsd.org/cgi-bin/query-pr-single.pl?number=43098>
-
-Unfortunately the problems are in the *work* directories so that one needs the knowledge from
-<http://www.netbsd.org/docs/pkgsrc/components.html>
-to even get the patches to be applied.
+    drmOpenDevice: node name is /dev/dri/card0
+    drmOpenDevice: open result is 10, (OK)
+    drmOpenByBusid: Searching for BusID pci:0000:01:00.0
+    drmOpenDevice: node name is /dev/dri/card0
+    drmOpenDevice: open result is 10, (OK)
+    drmOpenByBusid: drmOpenMinor returns 10
+    drmOpenByBusid: drmGetBusid reports pci:0000:01:00.0
+    (II) AIGLX: enabled GLX_MESA_copy_sub_buffer
+    (II) AIGLX: enabled GLX_SGI_make_current_read
+    (II) AIGLX: enabled GLX_SGI_swap_control and GLX_MESA_swap_control
+    (II) AIGLX: enabled GLX_texture_from_pixmap with driver support
+    (II) AIGLX: Loaded and initialized /usr/pkg/lib/dri/r200_dri.so
+    (II) GLX: Initialized DRI GL provider for screen 0
+    (II) RADEON(0): Setting screen physical size to 510 x 290
 
-Install *pkgtools/pkgdiff*.
+Ironically we knew we were on the right track porting the latest git versions of the X.org stack when we succeeded in locking up hard our machine.  That meant a real hardware acceleration module was being loaded that the previous kernel could not handle, which was why the latest drm from FreeBSD had to be imported.
 
-### gstreamer 0.10
 
-As of 2010-05-09, I find it necessary on x86_64 to use the following patch for
-pkgsrc gstreamer0.10, an eventual dependency of the full xfce desktop:
+## Status
 
-    --- pkgsrc/multimedia/gstreamer0.10/Makefile.orig       2010-03-29 16:04:23 -0700
-    +++ pkgsrc/multimedia/gstreamer0.10/Makefile    2010-03-29 16:09:04 -0700
-    @@ -44,6 +44,11 @@
-     .include "../../mk/bsd.prefs.mk"
-    +# __udivti3 error otherwise
-    +.if ${OPSYS} == "DragonFly" && ${MACHINE_ARCH} == "x86_64"
-    +MAKEFLAGS+=    CCVER=gcc44
-    +.endif
-    +
-     .if ${OPSYS} == "NetBSD"
-     # We must have a glib2 compiled with the RTLD_GLOBAL fix; if not, plugins
-     # won't work at all.
-
-See for example the following bug report for more details:
-<http://mail-index.netbsd.org/pkgsrc-bugs/2010/03/30/msg037304.html>
-
-## Building a separate version of X.org
-
-We try something **ill-advised**, we build a separate version of X.org in another directory, say */opt/xbeta*,
-on the same machine where we have installed the latext pkgsrc.  We do this because we have no choice but to
-use the graphics hardware on this machine, but the risk is that it is very easy to link the wrong libraries
-from pkgsrc.
-
-### expat and gettext
-
-We start with installing into */opt/xbeta* [expat 2.0.1](http://sourceforge.net/projects/expat/)
-and [gettext 0.17](http://www.gnu.org/software/gettext/).
-
-### Git repository for most of X.org
-
-We use the following listing:
-
-[freedesktop.org git repository browser](http://cgit.freedesktop.org/)
-
-One can easily script getting, updating, and building the projects listed on that page.
-
-### Example of using ldd
-
-    $ ldd ./libXau.so.6          
-    ./libXau.so.6:
-       libc.so.7 => /usr/lib/libc.so.7 (0x800640000)
-    $ ldd ./libXdmcp.so.6        
-    ./libXdmcp.so.6:
-        libc.so.7 => /usr/lib/libc.so.7 (0x800640000)
-
-### libxcb problem with Python 2.6 cElementTree
-
-Library *xcb/libxcb* unfortunately needs to be built early and there is a catch for
-using pkgsrc Python 2.6.  Unfortunately at the current time not all of
-*cElementTree* appears to be functional; therefore, one needs a patch similar to
-
-    diff --git a/src/c_client.py b/src/c_client.py
-    index d86d05e..36a7039 100755
-    --- a/src/c_client.py
-    +++ b/src/c_client.py
-    @@ -1,5 +1,5 @@
-     #!/usr/bin/env python
-    -from xml.etree.cElementTree import *
-    +from xml.etree.ElementTree import *
-     from os.path import basename
-     import getopt
-     import sys
-
-As of May 20, 2010, the situation for libxcb seems to be more complicated.  The latest *xcb/proto* needs
-to be installed.  If one does not wish to install on top of one's current Python modules,
-define
-
-    export PYTHONPATH=${PREFIX}/lib/python2.6/site-packages
-
-and apply a patch similar to below to change from using Python 2.6's *cElementTree* to *ElementTree*
-
-    diff --git a/xcbgen/matcher.py b/xcbgen/matcher.py
-    index e7958fa..16e8273 100644
-    --- a/xcbgen/matcher.py
-    +++ b/xcbgen/matcher.py
-    @@ -7,7 +7,7 @@ we do not create a new type object, we just record the existing one under a new
-     '''
-
-     from os.path import join
-    -from xml.etree.cElementTree import parse
-    +from xml.etree.ElementTree import parse
-
-     import state
-     from xtypes import *
-    diff --git a/xcbgen/state.py b/xcbgen/state.py
-    index 51efc94..e72dc3e 100644
-    --- a/xcbgen/state.py
-    +++ b/xcbgen/state.py
-    @@ -2,7 +2,7 @@
-     This module contains the namespace class and the singleton module class.
-     '''
-     from os.path import dirname, basename
-    -from xml.etree.cElementTree import parse
-    +from xml.etree.ElementTree import parse
-
-     import matcher
-     from error import *
-
-### libXext
-
-      CCLD   libXext.la
-    /usr/libexec/binutils217/elf/ld: .libs/extutil.o: relocation R_X86_64_PC32 against `xgeExtRegister' can not be used when making a shared   object; recompile with -fPIC
-    /usr/libexec/binutils217/elf/ld: final link failed: Bad value
-
-Use the following patch from <http://lists.x.org/archives/xorg-devel/2009-November/003724.html>
-
-    diff --git a/src/Xge.c b/src/Xge.c
-    index 7a583e5..2ea5d27 100644
-    --- a/src/Xge.c
-    +++ b/src/Xge.c
-    @@ -294,7 +294,7 @@ _xgeEventToWire(Display* dpy, XEvent* re, xEvent* event)
-     /*
-      * Extensions need to register callbacks for their events.
-      */
-    -Bool
-    +_X_HIDDEN Bool
-     xgeExtRegister(Display* dpy, int offset, XExtensionHooks* callbacks)
-     {
-         XGEExtNode* newExt;
-
-### FreeType 2
-
-We install [FreeType 2.3.12](http://www.freetype.org/).  It appears that *GNUMAKE=gmake* is required.
-Most of the X.org projects use *autogen.sh*, but here we use a standard call to *configure* somewhat
-similar to:
-
-        export ACLOCAL="aclocal -I ${PREFIX}/share/aclocal"
-        export PKG_CONFIG_PATH="${PREFIX}/lib/pkgconfig"
-        GNUMAKE=gmake ./configure --prefix=${PREFIX} CPPFLAGS="-I${PREFIX}/include -I${PREFIX}/X11/include" LDFLAGS="-L${PREFIX}/lib -Wl,-rpath -Wl,${PREFIX}/lib -L${PREFIX}/X11/lib -Wl,-rpath -Wl,${PREFIX}/lib/X11"
-
-where *$PREFIX* is where we install X.org, say */opt/xbeta*,
-the first two exports of *ACLOCAL* and *PKG_CONFIG_PATH* occur for most X.org projects,
-*CPPFLAGS* and *LDFLAGS* ensure that the *$PREFIX* include directories and library paths
-are used, and *-Wl,-rpath ...* is an incantation that ensures that previous built
-*libtool* libraries can be used.
-
-### libXfont
-
-*autogen.sh* script seems to build easier with
-    --without-xmlto
-option.
-
-### Mesa
-
-As of 2010-05-09, known problem with GNU m4 pkgsrc on DragonFly
-
-    /usr/pkg/bin/gm4: m4_esyscmd subprocess failed: Operation not permitted
-    /usr/pkg/bin/gm4:configure.ac:8: cannot run command `${MAKE-make} -s -f bin/version.mk version | tr -d '\n'': Operation not permitted
-    configure.ac:8: error: Failed to get the Mesa version from `make -f bin/version.mk version`
-
-For now just manually run command
-    $ make -f bin/version.mk version
-    7.9.0
-and substitute it using a patch similar to
-
-    diff --git a/configure.ac b/configure.ac
-    index c40c842..224a858 100644
-    --- a/configure.ac
-    +++ b/configure.ac
-    @@ -4,7 +4,7 @@ AC_PREREQ([2.59])
-     dnl Versioning - scrape the version from configs/default
-     m4_define([mesa_version],
-    -    [m4_esyscmd([${MAKE-make} -s -f bin/version.mk version | tr -d '\n'])])
-    +    [7.9.0])])
-     m4_ifval(mesa_version,,
-         [m4_fatal([Failed to get the Mesa version from `make -f bin/version.mk version`])])
+The latest drm code from FreeBSD 9.x current has been successfully ported to DragonFly BSD, [patch](http://leaf.dragonflybsd.org/~davshao/r600fbsd.diff) and git branch **r600fbsd** git://leaf.dragonflybsd.org/~davshao/dragonfly.git, and tested with a Radeon HD 4550 on an x86_64 machine (Shuttle SG45H7).  However it must be remembered that testing has only been done with this one graphics card and it is completely unknown whether say an Intel machine will lock up solid.  Also nothing was done to port the extensive Via drivers FreeBSD has already ported.
 
-#### C99 fpclassify()
+## Current Progress for Google Summer of Code 2010
 
-    diff --git a/src/mesa/main/querymatrix.c b/src/mesa/main/querymatrix.c
-    index ca292aa..a0969f6 100644
-    --- a/src/mesa/main/querymatrix.c
-    +++ b/src/mesa/main/querymatrix.c
-    @@ -71,7 +71,7 @@ fpclassify(double x)
-     }
+Current work on porting the Linux drm to DragonFly BSD can be found in
+git branch **gsocdrmalpha** git://leaf.dragonflybsd.org/~davshao/dragonfly.git
 
-     #elif defined(__APPLE__) || defined(__CYGWIN__) || defined(__FreeBSD__) || \
-    -     (defined(__sun) && defined(__C99FEATURES__))
-    +     defined(__DragonFly__) || (defined(__sun) && defined(__C99FEATURES__))
+As of Friday, July 16, 2010, weeks of work have brought us to where many good things are on the cusp of happening.
 
-     /* fpclassify is available. */
+### Data structures for minors and masters ported
 
-### xserver
+Linux drm has data structures for representing different devices, say */dev/dri/card0*, which are analogous to device minors,
+and for representing a current master process that has authentication for using such a device.  These data structures
+have now been ported to the latest DragonFly BSD port of drm.  The minors allow the possibility of eventually using
+dual-headed cards, and also there is a concept of a legacy minor and a control minor.  However, Linux has code for
+what it calls the VGA arbiter for which the BSDs may not have an equivalent.
 
-If one uses the patches alluded to in the pkgsrc section, one can avoid the following build error:
+### Locking porting almost done
 
-      YACC   parser.c
-    bison: m4 subprocess failed: Operation not permitted
-    gmake[3]: *** [parser.c] Error 1
+The legacy BSD code was using an equivalent of one global lock for a drm device and the Linux code had
+moved on to use many more locks, as well as using a different global lock for a drm device.  The bulk of
+porting time has been spent carefully changing locking to fit the Linux model while having all machines
+continue to function, a process of locking up a test machine and then figuring how to fix the lockup.
+As of July 16, we are very close to basically using the Linux drm locks, translated in DragonFly BSD terms
+simply using *lockmgr*.  We are well aware that on DragonFly BSD in particular there are much better
+alternatives, but we are for now using a lowest common denominator just to get things working in some
+fashion.
 
-Developer documentation appears to now be enabled by default; therefore, if one is bootstrapping
-a new tree, one might want to use the option to *autogen.sh* to not build developer documentation:
+The combination of porting the minor/master data structures and the Linux drm locking means that 
+DragonFly BSD is very close to speaking the same language as Linux drm.
 
-I experienced the following build error:
+## Next steps
 
-      GEN    Xserver-spec.txt
-    No way to convert HTML to text found.
+### Equivalent of *struct page*
 
-Corrected using the *autogen.sh* flag:
+Every operating system will have an abstraction for virtual memory pages that can have a variety of
+mappings, but Linux's appears to have a concept allowing mapping more than the virtual memory space allocated
+in the upper half of virtual memory on 32-bit machines, about 1 GB.  We are investigating what will be
+the best translation to DragonFly BSD--if worse comes to worse perhaps only cards of lower graphics memory
+capacity can be supported.
 
-    --disable-devel-docs
+### i2c support for user modesetting
 
+Thanks to fellow DragonFly BSD developers the i2c bus API has been updated to reflect later work from
+FreeBSD.  We anticipate being able to map the Linux drm i2c callbacks directly to this API.