From 16217fa2ab81528062ca9bde0a139767eda96d34 Mon Sep 17 00:00:00 2001 From: Gordon Ross Date: Sun, 6 Nov 2016 15:13:42 -0500 Subject: Update the README for this project --- README | 120 ++++++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 82 insertions(+), 38 deletions(-) diff --git a/README b/README index 5af1b16..b5c0807 100644 --- a/README +++ b/README @@ -1,47 +1,91 @@ -This is a skeleton of an "ON" (illumos) build. - -You can use it to build drivers, libraries, and commands, -that you might plan to later integrate into illumos, but -don't want to wait for full illumos builds while you're -developing your code. - -As provided, this skeleton builds one driver, one library, -and one command, all named "foo". These are intentionally -trivial objects, just to demonstrate how it builds. - -The Makefile here is a wrappter to build the whole gate -in a few separate steps. All steps use the command: - bldenv myenv.sh "cd ...; make" -to setup the environment expected by the gate and -run make in the necessary places to build it all. -The rapper makefile supports three targets: +This is the "graphics/DRM" gate, in which we build the +DRM kernel modules and related DRM libraries. + + +Introduction: + +DRM stands for Direct Rendering Manager, which is a collection of +kernel modules and libraries that allow programs like the Xorg +server to operate hardware-accelerated graphics cards. This +software currently supports Intel (R) integrated graphics devices +with hardware acceleration, video memory management, Graphics +Execution Manager (GEM), and kernel modesetting (KMS). + + +How to build: + +Clone this repo. onto an OpenIndiana or similar build system +with the "build-essential" packages installed, then: + cd (top of clone) make install make package - make clean -Here is a list of all the places you might want to copy -to add another driver, library, or command: - uts/common/sys/foo.h - uts/common/io/foo/* - uts/common/Makefile.files (FOO_OBJS += foo.o) - uts/common/Makefile.rules (common/io/foo, two places) - uts/intel/Makefile.intel.shared (DRV_KMODS += foo) - uts/intel/foo/Makefile - uts/sparc/Makefile.sparc.shared (DRV_KMODS += foo) - uts/sparc/foo/Makefile +Overview: + +The major kernel components are: + + usr/src/uts/intel/io/i915 i915 driver + usr/src/uts/common/io/drm/ DRM "misc" support + usr/src/uts/intel/io/agpmaster AGP master support + usr/src/uts/intel/io/agpgart AGP GART, AGP target + + Dependendencies: + i915 -> drm + drm -> agpmaster, gfx_private + +The user-level libraries are: + + usr/src/lib/libdrm/ DRM driver + usr/src/lib/libdrm_* H/W-specific DRM support + usr/src/lib/libkms Kernel Mode Setting support + +Note that the source for those libraries is EXTERNAL, and +NOT checked into this gate. At build time, the library +sources are downloaded from: + http://dri.freedesktop.org/libdrm/ +and then unpacked and patched under: + usr/src/common/libdrm/ + +That makes this gate a little unusual, sort of a "hybrid" +between how illumos-gate does things and how the "userland" +gate does things. There are good reasons for this. + +The kernel code is very much operaging-system-specific, +and therefore can not simply track some "upstream" like +the user-level library code can. It's also a little +tricky to build kernel code "correctly", which is why +the kernel build parts of this gate are based on the +"ON skeleton" gate: https://github.com/gwr/on-skel + +The user-level libraries here are built with minimal +changes relatative to the upstream, and therefore can +use a strategy similar to that in the "userland" gate: + https://github.com/OpenIndiana/oi-userland + + +Development and testing: - lib/libfoo/Makefile - lib/libfoo/Makefile.com - lib/libfoo/*/Makefile - lib/libfoo/common/* +If you find you need to make changes to library code +(such as when updating to a new version) the easiest +way is to save a copy of the unpacked library source +before patching (use "make unpack"), then go ahead +and edit files as needed, and once you're happy with +the changes use "diff -u saved-lib edited-lib" to +update the files in the patches directory. Use: + usr/src/common/libdrm/Check-patches +to check that your patches are in sync with edits. - cmd/foo +When doing incremental work in the gate, i.e. fixing +compilation errors, it's handy to run an editor in a +"bldenv" environment, as follows: + bldenv -d myenv.sh - man/man1/foo.1 - man/man3x/libfoo.3x - man/man7/foo.7 +That gets you a new shell, in which you can run an +emacs if you like "meta-x compile", or whatever. +Just cd to where the top-level make had problems +and run make. Then fix bugs, open pull requests. -For more information about developing device drivers for illumos, please read this document: -https://illumos.org/books/wdd/eqbqn.html +Please run the tests before submitting pull requests. +They're installed as /opt/drm-test/* -- cgit v1.2.3