xsf-docs/howto/build-mesa.mdwn | 201 +++++++++++++++++++++++++++++++++++ xsf-docs/howto/configure-input.mdwn | 176 ++++++++++++++++++++++++++++++ xsf-docs/howto/report-bugs.mdwn | 35 ++++++ xsf-docs/howto/triage-bugs.mdwn | 93 ++++++++++++++++ xsf-docs/howto/use-gdb.mdwn | 102 +++++++++++++++++ xsf-docs/howto/use-xrandr.mdwn | 173 ++++++++++++++++++++++++++++++ xsf-docs/howtos | 1 xsf-docs/howtos/build-mesa.mdwn | 201 ----------------------------------- xsf-docs/howtos/configure-input.mdwn | 176 ------------------------------ xsf-docs/howtos/report-bugs.mdwn | 35 ------ xsf-docs/howtos/triage-bugs.mdwn | 93 ---------------- xsf-docs/howtos/use-gdb.mdwn | 102 ----------------- xsf-docs/howtos/use-xrandr.mdwn | 173 ------------------------------ xsf-docs/index.mdwn | 16 +- 14 files changed, 789 insertions(+), 788 deletions(-)
New commits: commit a6a400729c813eb8c2ce4b62b5bd022d889fd984 Author: Cyril Brulebois <[email protected]> Date: Tue Feb 15 22:09:35 2011 +0100 howtos: Rename to howto for consistency. We have faq/ and reference/ as singular. Keep a symlink for now since some mails to the BTS reference howtos/*. diff --git a/xsf-docs/howto/build-mesa.mdwn b/xsf-docs/howto/build-mesa.mdwn new file mode 100644 index 0000000..dc49cd9 --- /dev/null +++ b/xsf-docs/howto/build-mesa.mdwn @@ -0,0 +1,201 @@ +# How to build mesa + +Cyril Brulebois <[email protected]> + + +## Foreword + +Mesa is a special package since many flavours are built, which means +it takes quite some time to get all packages ready, as well as some +disc space (over 2GB for the `build/` directory alone). + +Also, trying to figure out whether latest `master` is also affected, +or backporting some bug fixes might lead to some painful I/O while +generating the `.deb` files, and then installing/unpacking them. This +is why this document was written: Helping users test other mesa +releases, branches, bug fixes without having to build full packages, +and without having to mess with their systems (*i.e.* no root access +is needed once the build dependencies are installed). + +We’ll focus on the DRI (Direct Rendering Infrastructure) flavour +(`libgl1-mesa-dri`), which is the most common. + +It might be possible to adapt the following steps to another flavour, +in which case the appropriate options to be passed to `./configure` +should be looked up in the `debian/rules` file of the Debian source +package. + +*Note:* Before reading further, be aware that `nouveau` is a bit + special. + + * It’s considered experimental, and shipped in the + `libgl1-mesa-dri-experimental` package accordingly. + * It may fail to build (both API and ABI are still changing). + * We’re not shipping `nouveau_vieux_dri.so` yet (for cards from NV04 + to NV2X; `nouveau_dri.so` is for NV30 and later). See the upstream + [FeatureMatrix](http://nouveau.freedesktop.org/wiki/FeatureMatrix) + page to determine a card’s series. + + +## Gathering information + +Get started by installing `mesa-utils`, which contains `glxinfo`. + + * *Is direct rendering enabled?* + + $ glxinfo | grep ^direct + direct rendering: Yes + + ↪ Yes. + + * *Is this the classic or + [Gallium](http://en.wikipedia.org/wiki/Gallium3D) driver?* + + $ glxinfo | grep 'renderer string' + OpenGL renderer string: Mesa DRI Intel(R) 945GM GEM 20100330 DEVELOPMENT + + ↪ No “Gallium” here, therefore: “classic”. + + * *Which driver is this, and where is it located?* + + $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$ + libGL: OpenDriver: trying /usr/lib/dri/tls/i915_dri.so + libGL: OpenDriver: trying /usr/lib/dri/i915_dri.so + + ↪ `i915`, from the system directory: `/usr/lib/dri` (likely + installed through a Debian package). + + * *How can I get more debugging information?* + + export LIBGL_DEBUG=verbose + export MESA_DEBUG=1 + export EGL_LOG_LEVEL=debug + + +## Preparing mesa sources + +To get started, installing all build dependencies of the `mesa` source +package should be sufficient, along with the essential build tools, +and `git`: + + $ sudo apt-get install build-essential git + $ sudo apt-get build-dep mesa + +If you’re on `squeeze` you may need to install a few more packages: +newer `libdrm-dev` (**FIXME:** talk about picking it from `wheezy`? or +about a local installation?), as well as `libxmu-dev`, `libxi-dev`. + +Make sure you have some disc space available, since the git repository +is over 120MB, and since the mesa directory is over 500MB after a +build. Once you’re ready, grab the upstream mesa sources: + + $ git clone git://anongit.freedesktop.org/mesa/mesa mesa.git + $ cd mesa.git + $ autoreconf -vfi + +Here’s what the `./configure` call will look like: + + $ ./configure --enable-driglx-direct \ + --enable-gallium \ + --enable-gles-overlay \ + --enable-gles1 \ + --enable-gles2 \ + --enable-glx-tls \ + --with-driver=dri \ + --with-dri-driverdir=/usr/lib/dri \ + --with-egl-platforms='drm x11' \ + --with-state-trackers=egl,glx,dri,vega \ + … + +Now, what are the parameters to replace “`…`” with? Basically, if +you determined an Intel driver (`i915` or `i965`), you want to use the +classic drivers and to disable the Gallium drivers. If you saw a +Radeon driver (`r300` or `r600`), you should prefer the Gallium +drivers. If you’re using `nouveau`, make sure you read the note in the +**Foreword**. The following assumes you’re using `nouveau_dri.so`. + + +Examples for common drivers: + + * For `i915`, you need: + + --with-dri-drivers=i915 + + * For `i965`, you need: + + --with-dri-drivers=i965 + + * For `nouveau`, you may want to try: + + --with-dri-drivers=nouveau --enable-gallium-nouveau + + * For `r300` (the options are named `radeon`), you need: + + --with-dri-drivers=radeon --enable-gallium-radeon + + * For `r600`, you need: + + --with-dri-drivers=r600 --enable-gallium-r600 + +Now, once you’ve run `./configure`, time for your favorite beverage: + + $ make + + +## Running the newly-built mesa libraries + +Shared libraries end up in the `lib/` directory. It contains the +classic drivers, while Gallium drivers end up under `lib/gallium`. If +you’re not an Intel user, overwrite the classic drivers with the +Gallium ones: + + $ mv lib/gallium/* lib/ + +Now, 3 variables need to be set, so that the locally-built libraries +are used. + + * To begin with, libGL itself and its drivers: + + $ export LIBGL_DRIVERS_PATH=lib + + *Did this work?* + + $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$ + libGL: OpenDriver: trying lib/tls/i915_dri.so + libGL: OpenDriver: trying lib/i915_dri.so + + ↪ Yes: No system directory, paths are relative to `lib/`. + + * Set `LD_LIBRARY_PATH` to make sure the locally-built libraries + (including those pulled through library dependencies) are used, + instead of system ones: + + $ export LD_LIBRARY_PATH=lib + + *Did this work?* + + $ ldd lib/libGLESv2.so | grep glapi + libglapi.so.0 => lib/libglapi.so.0 (0x00007fee3192e000) + + ↪ Yes: Path is relative to `lib`. + + * Set the EGL search path: + + $ export EGL_DRIVERS_PATH=lib/egl + + *Did this work?* + + **FIXME: We should be shipping EGL-aware applications through + `mesa-utils`.** + + $ EGL_LOG_LEVEL=debug test_application 2>&1 >/dev/null | grep '\.so' + libEGL debug: added lib/egl/egl_gallium.so to module array + libEGL debug: dlopen(lib/egl/egl_gallium.so) + libEGL debug: DRI2: dlopen(lib/i915_dri.so) + + ↪ Yes: No system directory, paths are relative to `lib/`. + + +### The end. + +Now you should be ready to test upstream’s suggestions! diff --git a/xsf-docs/howto/configure-input.mdwn b/xsf-docs/howto/configure-input.mdwn new file mode 100644 index 0000000..75ea3c3 --- /dev/null +++ b/xsf-docs/howto/configure-input.mdwn @@ -0,0 +1,176 @@ +# How to configure input + +Cyril Brulebois <[email protected]> + + +## General considerations + +### Foreword + +The Debian wiki also contains an +[inupt hotplug guide](http://wiki.debian.org/XStrikeForce/InputHotplugGuide) +which contains some context around X’s input subsystem. The present +document is meant to be an executive summary, and might miss some +bits. (**FIXME:** Merge those bits.) + + +### Rules of thumb + +In this documentation, only the last part of the driver’s name will be +mentioned, all of them are under the `xserver-xorg-input-*` namespace. + + * On Linux, `evdev` is used for both keyboard and mouse + input. + * On Linux as well, `synaptics` can be used to benefit from extra + features; it takes precedence over `evdev` automatically if both + are installed. + * On GNU/kFreeBSD and GNU/Hurd, `kbd` handles the keyboard and + `mouse` handles mice, unsurprisingly. + + +### Configuration snippets + +X can now be run without `xorg.conf`, but sometimes one has to +configure a few settings for this or that driver. Starting with +`squeeze`, that can be done by adding a file under +`/etc/X11/xorg.conf.d`, with a `.conf` suffix, as documented in the +`xorg.conf` manpage. + +Some packages ship a default configuration file under +`/usr/share/X11/xorg.conf.d` with general rules to match appropriate +hardware. The files under `/etc/X11/xorg.conf.d` take precedence, as +documented in the `xorg.conf` manpage. + +It’s probably mostly useful in the `synaptics` case, in case one wants +to change default settings on a system-wide fashion. See the **Pointer +configuration** section below for an example. + + +## Basic keyboard configuration + +The `keyboard-configuration` package ships `/etc/default/keyboard` +which can be used to set the following `xkb` items: model, layout, +variant, and options. Here’s an example: + + XKBMODEL="pc105" + XKBLAYOUT="fr" + XKBVARIANT="oss" + XKBOPTIONS="compose:menu,terminate:ctrl_alt_bksp" + +Quick words about the options: + + * They are comma-separated. + * The list of options and a short description for each can be found + in the `/usr/share/X11/xkb/rules/base.lst` file (shipped by the + `xkb-data` package). + * First option: `compose:menu`. This sets the `menu` key as the + Compose key. More information about it can be found in the + `Compose` manpage. + * Second option: `terminate:ctrl_alt_bksp`. By default, the X server + is no longer killed through `Ctrl+Alt+Backspace`. This option + restores the old behaviour. + +Two ways to change the configuration: + + * `dpkg-reconfigure keyboard-configuration` is going to ask questions + through debconf prompts. + * Manually editing `/etc/default/keyboard` also works. + +How does it propagate to X? + + * When HAL is used (that is: on GNU/kFreeBSD and GNU/Hurd), one has + to restart it: `invoke-rc.d hal restart` + * When udev is used (on GNU/Linux, starting with `squeeze`), one has + to tell udev to reload input-related configuration: + `udevadm trigger --subsystem-match=input --action=change` + (that can be found in `keyboard-configuration`’s `README.Debian` + file). Properties attached to the input devices are then updated, + and X uses those properties when it starts, as can be seen by + searching for `xkb_` in the X log. Please note that trying + `invoke-rc.d udev restart` changes nothing, one has to use + `udevadm`. Properties can be inspected through: + `/sbin/udevadm info --export-db` + + +## Pointer configuration + +### evdev configuration + +Available options are documented in the `evdev` manpage. Let’s check +what a configuration snippet (mentioned in **General considerations**) +would look like. Here is a fictional `/etc/X11/xorg.conf.d/42-evdev.conf`: + + Section "InputClass" + Identifier "evdev pointer tweaked catchall" + MatchIsPointer "on" + Driver "evdev" + Option "Emulate3Buttons" True" + Option "SwapAxes" "True" + EndSection + +Line by line walkthrough: + + * To avoid specifying any device under `/dev/input` (`event$N` might + change, remember it’s about hotplug support!), we use an + `InputClass`. + * We need an identifier, the actual name doesn’t matter. + * We match everything that looks like a touchpad. Meaning no generic + pointer, keyboard, or tablet. + * We specify the driver we want to use for the matched device(s). + * Finally the options we want to set. Here we enable the 3rd button + emulation (clicking left and right buttons at the same time then no + longer acts as if the middle button was clicked). Then we swap x + and y axes, just for the fun of it. + + +### synaptics configuration + +The `synaptics` driver comes with two tools. The more interesting one +is `synclient`, which can be used to list available options and +current settings: `synclient -l`. The documentation for each option +can be found in the `synaptics` manpage. + +`synclient` can also be used to set options. A common example is +enabling tapping (upstream kept it disabled by default, Debian won’t +deviate, no need to file bugs): `synclient TapButton1=1`; one can also +disable the touchpad temporarily: `synclient TouchpadOff=1` to +disable it, `synclient TouchpadOff=0` to enable it again. + +Let’s check what a configuration snippet (mentioned in **General +considerations**) would look like. Here is a fictional +`/etc/X11/xorg.conf.d/42-synaptics.conf`: + + Section "InputClass" + Identifier "touchpad tweaked catchall" + MatchIsTouchpad "on" + Driver "synaptics" + Option "TapButton1" "1" + Option "HorizEdgeScroll" "1" + EndSection + +Line by line walkthrough: + + * To avoid specifying any device under `/dev/input` (`event$N` might + change, remember it’s about hotplug support!), we use an + `InputClass`. + * We need an identifier, the actual name doesn’t matter. + * We match everything that looks like a touchpad. Meaning no generic + pointer, keyboard, or tablet. + * We specify the driver we want to use for the matched device(s). + * Finally the options we want to set. We enable tapping for the first + button. And we enable horizontal scrolling (by default, only + vertical scrolling is enabled). + +Settings can also be changed by various settings managers, like +Gnome’s or KDE’s. An example of a graphical user interface making it +possible to set options in a clicky way: `gpointing-device-settings`. + +There’s a palm detection setting but that relies on hardware/firmware +support for the touchpad. The other tool shipped with the `synaptics` +driver is `syndaemon`, which makes it trivial to disable the touchpad +temporarily, when the keyboard is being used. Here’s an example: +`syndaemon -d -i 0.5` makes `syndaemon` start in background (`-d` for +daemon mode), waiting 0.5 second before enabling the touchpad again +after the last keypress. Warning: it becomes quite difficult to use +things like `Ctrl+click` in a browser, or `Alt+drag` to move +windows. diff --git a/xsf-docs/howto/report-bugs.mdwn b/xsf-docs/howto/report-bugs.mdwn new file mode 100644 index 0000000..6fc7140 --- /dev/null +++ b/xsf-docs/howto/report-bugs.mdwn @@ -0,0 +1,35 @@ +# How to report bugs + +Cyril Brulebois <[email protected]> + + +## Simple as reportbug + +### Initial report + +Unless you know which package to report the bug against, you can +report the bug against the `xorg` metapackage: + + reportbug xorg + +Like most packages related to the X server, reporting a bug against +this package triggers a bug script which is going to collect X-related +information, be it installed packages, running kernel, X +configuration, X log, and so on. + +Note: In case this metapackage wasn’t used to install your X stack, +report a bug against `xserver-xorg` instead. And if that one isn’t +installed either, go for `xserver-xorg-core`. + + +### Follow-up with more info + +If you reported a bug against another package and if that bug was +reassigned to an X-related package, we might need more +information. You can run the bug script manually and attach its output +to your mail to the bug report: + + /usr/share/bug/xserver-xorg-core/script 3>/tmp/script.log + +Note: Make sure there’s no space between `3` and `>`, that’s a shell +redirection. diff --git a/xsf-docs/howto/triage-bugs.mdwn b/xsf-docs/howto/triage-bugs.mdwn new file mode 100644 index 0000000..e523584 --- /dev/null +++ b/xsf-docs/howto/triage-bugs.mdwn @@ -0,0 +1,93 @@ +# How to triage bugs + +Cyril Brulebois <[email protected]> + + +## Packaging bugs or upstream bugs? + +It’d be nice to get all upstream bugs tagged as such (`upstream` tag), +forwarded upstream (which means the bugzilla instance on +<http://bugs.freedesktop.org/> for most packages), and marked as such. + +A mail to `[email protected]` would look like: + + tag X upstream + forwarded X https://bugs.freedesktop.org/show_bug.cgi?id=Y + thanks + +Then [`bts-link`](http://bts-link.alioth.debian.org/) comes into play +and help us tracking upstream status, which is pretty nice to have. + + +## Usertags + +Another feature of the BTS is usertagging. That lets people keep track +of additional tags, “attached” to a given mail address. For XSF, +that’s `[email protected]`. + +The list of all usertagged bugs can be seen on the following page; the +list of all used usertags is at the bottom, in the form. +→ <http://bugs.debian.org/cgi-bin/[email protected]> + +Let’s give some examples: + + * `i810`, `i915`: helps triaging `-video-intel` bugs depending on the + chipset. + * `r200`, `r300`: ditto for `-video-ati`. + * `xset`, `xrandr`: helps triaging `x11-xserver-utils` bugs depending + on the affected tool (like other `x11-*` packages, that’s a bundle + of teeny tiny apps). + * `squeeze-candidate`: helps keeping a list of bugs we’d like to get + fixed in a point release (through a stable update). + * `needs-forwarding`: of course, it’d be nice to have all upstream + bugs reported upstream, but some might need special attention + (*e.g.* security bugs). + +Here’s an example of URL, for the last tags: +→ <http://bugs.debian.org/cgi-bin/[email protected]&tag=squeeze-candidate> +→ <http://bugs.debian.org/cgi-bin/[email protected]&tag=needs-forwarding> + +By the way one should keep an eye on the list of found/fixed +versions since those bugs are likely marked as resolved (in `unstable` +or `experimental`), but might still affect a stable release. Maybe we +just need to have both `squeeze-candidate` and `squeeze-accepted`, and +swap usertags when the stable upload happens. + + +## Categories + +The BTS has yet another feature which can help, categories. That’s +based on usertags as well, but one has to use the package address +(`[email protected]`), so that’s package-specific rather +than team-specific. + +Categories are +[documented on the wiki](http://wiki.debian.org/bugs.debian.org/usertags), +and they would probably be welcome in the `intel` and `ati` cases +above, as well as in the “multiple tools in a single bundle” +cases… An example of what we could achieve is the +[devscripts bug page](http://bugs.debian.org/devscripts) (it takes +some time to load, plenty of bugs). + +Needed steps for that to happen: + + * create usercategories. + * move usertags from `[email protected]` to + `[email protected]`, probably using the `bts select` + command to get the list over which to iterate. + * profit! + +To move the usertags, something like that should do the job: + + # Adding usertags: + user [email protected] + usertag X xset + usertag Y xrandr + user [email protected] + usertag Z i810 + + # Removing tags which are no longer needed: + user [email protected] + usertag X - xset + usertag Y - xrandr + usertag Z - i810 diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn new file mode 100644 index 0000000..df7152d --- /dev/null +++ b/xsf-docs/howto/use-gdb.mdwn @@ -0,0 +1,102 @@ +# How to use gdb + +Cyril Brulebois <[email protected]> + + +## Foreword + +One should note that X is responsible for VT switching, meaning +switching between an X session and console terminals. In other words, +`Ctrl+Alt+Fn` is handled by X. If X is stopped, for example because +it’s running under `gdb`, one can no longer switch to another +VT. That’s why we’re recommending using a second machine to debug +X. Nevertheless, here are some instructions to attempt debugging X +with a single machine. + +### One-machine approach + +From a console (let’s assume it’s `vt1`), open a `root` +terminal. Then, start a loop which will bring you back to this console +after a given delay (in the following example, every 60 seconds), just +in case. The ampersand (`&`) at the end makes it a background job. + + while :; do sleep 60; chvt 1; done & + +### Two-machine approach + +That’s simpler, but then you need a second machine. Just log into the +first machine from the second one, using `ssh`. + +### Needed packages + +Obviously, `gdb` is needed; `xserver-xorg-core-dbg` contains the +debugging symbols for the server itself. Other needed packages can be +determined by looking at the backtrace. **FIXME: More info about +that.** + +## Actual gdb work + +### Attaching X from gdb + +The way of starting X doesn’t really matter, as `gdb` makes it +possible to attach a running process. If there’s a single X instance +running, that will do the job: + + # gdb attach $(pidof X) + [---GDB starts---] + (gdb) handle SIGPIPE nostop + (gdb) cont + +If there are several instances, one can use `ps aux` to determine the +PID of the appropriate instance (2nd column → `$pid`), and then attach +it: + + # gdb attach $pid + [---GDB starts---] + (gdb) handle SIGPIPE nostop + (gdb) cont + +### Starting X from gdb + +In case X crashes at start-up, one can start X from `gdb` in the +following way. In this example, the only parameter is the display, but +more parameters can be added. + + # gdb --args Xorg :0 + [---GDB starts---] + (gdb) handle SIGPIPE nostop + (gdb) run + +### What is SIGPIPE? + +`SIGPIPE` is a signal that can reach the X server quite easily, +especially when performing a VT switch, or refreshing large parts of +the screen. That’s why we ask `gdb` not to stop when such a signal is +caught, thanks to the `handle SIGPIPE nostop` command. + +### How to display a backtrace? + +Once X is crashed, for example because it received a `SIGSEGV` +(segmentation fault, usually because of a NULL pointer dereference), +or a `SIGBUS`, one gets back to the `gdb` prompt. One can then request +a backtrace (`bt`) or a full backtrace (`bt full`). The latter is what +developers are usually interested in, because variable values are also +available. + + (gdb) bt + (gdb) bt full + +### How to save a backtrace? + +To save a recording of the gdb session to a file (`gdb.txt` by +default): + + (gdb) set logging on + +To save in a different file, use this instead: + + (gdb) set logging file my-file.txt + (gdb) set logging on + +Once logging is enabled, you can request a (full) backtrace using the +previous commands. diff --git a/xsf-docs/howto/use-xrandr.mdwn b/xsf-docs/howto/use-xrandr.mdwn new file mode 100644 index 0000000..a3293a0 --- /dev/null +++ b/xsf-docs/howto/use-xrandr.mdwn @@ -0,0 +1,173 @@ +# How to use xrandr + +Cyril Brulebois <[email protected]> + + +## Getting started + +### What is xrandr? + +`xrandr` is a command-line tool to interact with the X `RandR` +extension [see [x.org](http://www.x.org/wiki/Projects/XRandR), +[wikipedia](http://en.wikipedia.org/wiki/RandR)], which allows for +live (re)configuration of the X server (*i.e.* without restarting it): +It provides automatic discovery of modes (resolutions, refresh rates, +etc.) together with the ability to configure outputs dynamically +(resize, rotate, move, etc.). + +**FIXME: Status across drivers?** + +### What consequences for xorg.conf? + +Starting with `squeeze`, removing the `xorg.conf` configuration file +entirely should work well enough, but in case that doesn’t work out, +let’s document what can be removed from it from a `RandR` point of +view. + +With the driver detecting modes automatically, several configuration +options become useless most of the time in your configuration file +(xorg.conf). You might want to remove: + + * `HorizSync` and `VertRefresh` from the `Monitor` section. + * Modes from `Display` subsection in `Screen` section. + * `ModeLine` from the `Monitor` section. + +There’s also no need to keep static dual-head configuration. Some +suggestions to get a tiny `xorg.conf`: + + * Drop dual `Device`/`Screen`/`Monitor` sections, a single one is + needed. + * Drop `MonitorLayout` option and `Screen` lines from the remaining + `Device` section. + * Drop the `ServerLayout` section(s). + * Drop `RightOf`/`LeftOf` indication of the remaining `Screen` line + in `ServerLayout` section. + +## Basic xrandr usage + +Once the configuration file (`xorg.conf`) is removed or updated, +starting the server should enable some outputs by default. Their +top-left corners will be at the same part of the image, but their +modes will probably be different. + +All outputs may be configured through `xrandr`. To see the available +outputs, just run `xrandr`: + + $ xrandr + Screen 0: minimum 320 x 200, current 1280 x 800, maximum 4096 x 4096 + VGA1 disconnected (normal left inverted right x axis y axis) + LVDS1 connected 1280x800+0+0 inverted X and Y axis (normal left inverted right x axis y axis) 261mm x 163mm + 1280x800 59.8*+ + 1024x768 60.0 + 800x600 60.3 56.2 + 640x480 59.9 + DVI1 disconnected (normal left inverted right x axis y axis) + TV1 disconnected (normal left inverted right x axis y axis) + +Comments: + + * We see 4 outputs: `VGA1`, `LVDS1`, `DVI1`, `TV1`. + * Only the internal panel (`LVDS1`) is connected and it supports 4 + modes at 60 Hz, 1 mode at 56 Hz. + * The mode marked with a star (`*`) is the current mode. + * The one marked with a plus (`+`) is the preferred one. Most + monitors report a preferred mode to the driver. And the + server/driver will generally choose it by default. + +**FIXME: Mention output name conventions?** + +When manipulating `VGA1` output properties, you should use: + + $ xrandr --output VGA1 <options> + +### Adding/removing heads dynamically + +The old days where you had to restart X when plugging a new monitor +are gone. With `RandR` 1.2, you can plug/unplug monitors whenever you +want. Running the following line will query all outputs and enable +them with their default mode: + + $ xrandr --auto + +You may also disable one output using: + + $ xrandr --output LVDS1 --off + +This may be useful for some buggy application that don’t support +multiple outputs well. Also, due to CRTC limitations (see the Caveats +section below), it is often required to disable one output before +enabling another since most hardware only support 2 at the same time. + +### Changing the mode + +With the above `xrandr` output, you may change the `LVDS1` mode to +`1024x768` using: + + $ xrandr --output LVDS1 --mode 1024x768 + +The refresh rate may also be changed, either at the same time or +independently: + + $ xrandr --output LVDS1 --mode 1024x768 --rate 75 + $ xrandr --output LVDS1 --rate 75 + +To get back to the default mode: + + $ xrandr --output LVDS1 --auto + +## Placing outputs in a virtual screen + +### A bit of configuration for non-KMS setups: + +Let’s have a look at the maximal virtual screen size, we see +`4096x4096` in this example: + + $ xrandr|head -1 + Screen 0: minimum 320 x 200, current 1280 x 800, maximum 4096 x 4096 + +With KMS (**FIXME: Link to a page which explains what KMS is**), +there's no need to specify any `Virtual` option. With DRI and without +KMS, that might be needed. Indeed, drivers will often create a default +virtual screen with small dimensions, for instance `1600x1200`, to +reduce memory consumption. + +If you plan to use multiple outputs displaying different zones, you +should configure your `xorg.conf` by adding a `Virtual` line to the +`Display` subsection in the `Screen` section. + + Section "Screen" + ... + SubSection "Display" + Depth 24 + Virtual 3000 2000 + EndSubSection + EndSection + +### Place outputs + +Outputs are placed using the following options: +`--right-of`/`--left-of`/`--above`/`--below`. For instance, to place +the `VGA1` output virtually-right of the internal panel (`LVDS1`): + + $ xrandr --output VGA1 --right-of LVDS1 + +Note that hardware and memory limitations may severely restrict the +size of your virtual screen, see the Caveats section below. + +## Adding new modes + +Under some circumstances, some modes might be missing. For instance, +if the monitor does not report correct EDID information. Or if the +output didn't have a CRTC available at startup because another output +was using it and you disabled it in the meantime. + +If a mode exist, you may add it to one output with: + + $ xrandr --addmode VGA1 800x600 + +If the mode does not exist, you may first create it by passing a modeline: + + $ xrandr --newmode <ModeLine> + +You may create a modeline using the `gtf` or `cvt` tools (shipped in +the `xserver-xorg-core` package). diff --git a/xsf-docs/howtos b/xsf-docs/howtos new file mode 120000 index 0000000..c953de0 --- /dev/null +++ b/xsf-docs/howtos @@ -0,0 +1 @@ +howto \ No newline at end of file diff --git a/xsf-docs/howtos/build-mesa.mdwn b/xsf-docs/howtos/build-mesa.mdwn deleted file mode 100644 index dc49cd9..0000000 --- a/xsf-docs/howtos/build-mesa.mdwn +++ /dev/null @@ -1,201 +0,0 @@ -# How to build mesa - -Cyril Brulebois <[email protected]> - - -## Foreword - -Mesa is a special package since many flavours are built, which means -it takes quite some time to get all packages ready, as well as some -disc space (over 2GB for the `build/` directory alone). - -Also, trying to figure out whether latest `master` is also affected, -or backporting some bug fixes might lead to some painful I/O while -generating the `.deb` files, and then installing/unpacking them. This -is why this document was written: Helping users test other mesa -releases, branches, bug fixes without having to build full packages, -and without having to mess with their systems (*i.e.* no root access -is needed once the build dependencies are installed). - -We’ll focus on the DRI (Direct Rendering Infrastructure) flavour -(`libgl1-mesa-dri`), which is the most common. - -It might be possible to adapt the following steps to another flavour, -in which case the appropriate options to be passed to `./configure` -should be looked up in the `debian/rules` file of the Debian source -package. - -*Note:* Before reading further, be aware that `nouveau` is a bit - special. - - * It’s considered experimental, and shipped in the - `libgl1-mesa-dri-experimental` package accordingly. - * It may fail to build (both API and ABI are still changing). - * We’re not shipping `nouveau_vieux_dri.so` yet (for cards from NV04 - to NV2X; `nouveau_dri.so` is for NV30 and later). See the upstream - [FeatureMatrix](http://nouveau.freedesktop.org/wiki/FeatureMatrix) - page to determine a card’s series. - - -## Gathering information - -Get started by installing `mesa-utils`, which contains `glxinfo`. - - * *Is direct rendering enabled?* - - $ glxinfo | grep ^direct - direct rendering: Yes - - ↪ Yes. - - * *Is this the classic or - [Gallium](http://en.wikipedia.org/wiki/Gallium3D) driver?* - - $ glxinfo | grep 'renderer string' - OpenGL renderer string: Mesa DRI Intel(R) 945GM GEM 20100330 DEVELOPMENT - - ↪ No “Gallium” here, therefore: “classic”. - - * *Which driver is this, and where is it located?* - - $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$ - libGL: OpenDriver: trying /usr/lib/dri/tls/i915_dri.so - libGL: OpenDriver: trying /usr/lib/dri/i915_dri.so - - ↪ `i915`, from the system directory: `/usr/lib/dri` (likely - installed through a Debian package). - - * *How can I get more debugging information?* - - export LIBGL_DEBUG=verbose - export MESA_DEBUG=1 - export EGL_LOG_LEVEL=debug - - -## Preparing mesa sources - -To get started, installing all build dependencies of the `mesa` source -package should be sufficient, along with the essential build tools, -and `git`: - - $ sudo apt-get install build-essential git - $ sudo apt-get build-dep mesa - -If you’re on `squeeze` you may need to install a few more packages: -newer `libdrm-dev` (**FIXME:** talk about picking it from `wheezy`? or -about a local installation?), as well as `libxmu-dev`, `libxi-dev`. - -Make sure you have some disc space available, since the git repository -is over 120MB, and since the mesa directory is over 500MB after a -build. Once you’re ready, grab the upstream mesa sources: - - $ git clone git://anongit.freedesktop.org/mesa/mesa mesa.git - $ cd mesa.git - $ autoreconf -vfi - -Here’s what the `./configure` call will look like: - - $ ./configure --enable-driglx-direct \ - --enable-gallium \ - --enable-gles-overlay \ - --enable-gles1 \ - --enable-gles2 \ - --enable-glx-tls \ - --with-driver=dri \ - --with-dri-driverdir=/usr/lib/dri \ - --with-egl-platforms='drm x11' \ - --with-state-trackers=egl,glx,dri,vega \ - … - -Now, what are the parameters to replace “`…`” with? Basically, if -you determined an Intel driver (`i915` or `i965`), you want to use the -classic drivers and to disable the Gallium drivers. If you saw a -Radeon driver (`r300` or `r600`), you should prefer the Gallium -drivers. If you’re using `nouveau`, make sure you read the note in the -**Foreword**. The following assumes you’re using `nouveau_dri.so`. - - -Examples for common drivers: - - * For `i915`, you need: - - --with-dri-drivers=i915 - - * For `i965`, you need: - - --with-dri-drivers=i965 - - * For `nouveau`, you may want to try: - - --with-dri-drivers=nouveau --enable-gallium-nouveau - - * For `r300` (the options are named `radeon`), you need: - - --with-dri-drivers=radeon --enable-gallium-radeon - - * For `r600`, you need: - - --with-dri-drivers=r600 --enable-gallium-r600 - -Now, once you’ve run `./configure`, time for your favorite beverage: - - $ make - - -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/[email protected]
