Linux Framebuffer Driver for the 3Dlabs Permedia3 chipset.

News

pm3fb-1.4.11C has been included in linux kernel 2.4.26-pre2 and later 2.4.x releases.

pm3fb-1.4.11B has been included in linux kernel 2.4.19-pre1 and later 2.4.x releases. The first "official" release featuring pm3fb is 2.4.19, released 2002-08-03. The fbgen patch (see below) is also included in 2.4.x.

This version is not included in 2.5.y or 2.6.z, and will need to be rewritten for the newer console/framebuffer subsystem integrated as of 2.5.11.

Author

Romain Dolbeau

Call for memory timings reports

There's a known trouble with permedia3 board: if memory is accessed while the chip is not yet initialized, the board will cause a complete system lock-up. Usually the board is properly initialized by the firmware (OpenFirmware on PowerMacintoshes, BIOS on x86 PCs), but sometimes not (secondary boards or chips, x86 boards in non-x86 system, whatever). Unfortunately, there's no way to discover the proper parameters by software. So they have to be hard-coded in the driver, which in turn means you need to know them for all and every possible board on the market...

So to help me add the proper parameters, if pm3fb works for you, it would be nice to send me the parameters for you board. It's easy: use the printtimings option once (available in pm3fb-1.4.8 and later), and send me the result. There should be 6 lines (one with the subvendor and subdevice, plus five with the PM3LocalMem values). They are available at boot-time and via the dmesg(8) command-line tool. Please add the memory size of the board and its commercial name and vendor. Thanks for your help !

Status

This driver is still experimental, but should be fairly stable by now.

I'm looking for success/failure reports & beta-testers, please contact me if you have a permedia3 board (and linux of course)

it's known to work on the Formac ProFormance 3 board (on an Apple PowerMacintosh)
it has been well tested on this board on PowerPC.
it has been tested on the Appian Jeronimo 2000 on x86.
it has been tested on the 3Dlabs Oxygen VX1 on ARM.
it has not been tested at all on any other board ; you've been warned ! Any report on other boards (or even the same) is welcome.
it will works only for PCI (or AGP) boards, not for SBus, VME or whatever, sorry.
it seems to work fine side-by-side with the old CVS XFree86 driver ('glint'), and with regular XFree86 release (4.0.3, 4.1.0). It shouldn't cause problem with newer XFree86 release.
it seems to work with XFree86 'fbdev' driver.
it supports multiple boards. note: apparently fbgen is not multiboard-aware, you will have trouble when playing with virtual console - and multiboard support in all other parts of the framebuffer console layer isn't that good anyway.
it supports multiple chips per board (like Appian boards, the J2000 works).
fully accelerated (character drawing, erasing, moving, inverting). Hardware cursor is not and will likely not be supported.
it has been tested with linux-2.2.18, linux-2.2.19, and with numerous vanilla or ppc-patched linux-2.4.x. Note: 2.2.x support hasn't been tested in a while, it's deprecated.
it works OK with OpenFirmware (as implemented in linux & macintoshes) in 2.2.x (deprecated).
resolution & depth switching (via fbset) work.
Support 8, 16 and 32 bpp, using 8 (PseudoColor CI8, 256 cells colormap), 12 (TrueColor RGBA 4444), 15 (TrueColor RGBA 5551), 16 (TrueColor RGBA 5650) or 24 (TrueColor RGBA 8888) significant bits per pixels. 24bpp is not supported by the permedia3 hardware, use 32 bpp instead.
Support VESA power-saving feature. That means the screen goes to sleep after a while, nothing more :-)

How to use

You will need kernel version 2.2.18, 2.2.19, or a recent 2.4.x (likely >= 2.4.2, nothing earlier has been tested). 2.5.x support for the earlier 2.5.y (y < 11) has been added recently (thanks Sven !). Assuming LINUXSRC is the path to the top of your linux kernel source tree:

put the files pm3fb.h and pm3fb.c in $LINUXSRC/driver/video
patch linux-2.2.18 (or 2.2.19 or 2.4.x) with the included patch: cd $LINUXSRC ; patch -p1 < linux-2.2.18-pm3.patch or cd $LINUXSRC ; patch -p1 < linux-2.2.19-pm3.patch or cd $LINUXSRC ; patch -p1 < linux-2.4.x-pm3.patch
add the driver to your kernel (you'll need CONFIG_EXPERIMENTAL and CONFIG_PCI)
compile, install, reboot - and enjoy if hell doesn't break loose.

note: the patch linux-2.4.x-pm3.patch should work on all linux kernel 2.4.x up to 2.4.14, but with offset and fuzz. This is normal. non-vanilla kernel (such as PPC kernel from benH) might fail ; as long as the only hunk failing come from Documentation/Configure.help, it shouldn't matter.

For kernel 2.4.16 and above, please use linux-2.4.16-pm3.patch. This might also be useful for non-vanilla kernel based on 2.4.16 and above.

Depth, BitsPerPixel and `fbset`

There's a little bit of confusion on the proper use of some terms in this page and in the fbset software.

Depth should be the actual number of bits used for the color of the pixel (above, significants bits)
BitsPerPixel should be the actual number of bits used in the memory of the framebuffer per pixel, regardless of depth.

Unfortunately, fbset -depth X should really be fbset -bpp X as it means set the framebuffer to that number of bits per pixels in memory, or more . For TrueColor mode, there's an option -rgba R,G,B,A to give the number of significant bits for each color component. So to get Depth 15 in 16 BitsPerPixels, i.e 5 bits for each of red, green and blue plus a spare bit, one should use: fbset -depth 16 -rgba 5,5,5,1. Depth 12 in 16 bpp would be fbset -depth 16 -rgba 4,4,4,4

At the moment, if you use fbset -depth 15, pm3fb will also use RGB 5551 and 16bpp but I'm not sure it's the right behavior. fbset -depth 16 will default to RGB 565.

Also, see below bugs & workarounds concerning switching between the various depth in 16bpp

Options (kernel)

All options are of the form <option_name>:[<board_number>:]<options_parameters> Brackets mean the board number (internally used to represent each board, from 0 on) is "optional" Note that for PCIID the board number is mandatory (it defaults to 0 for all other options). Options are separated by a comma ","

exemple: video=pm3fb,mode:640x480-60,pciid:0:1:2:3 will use board at PCIID 1:2:3 with mode 640x480 @ 60 Hz as board #0

note: Apparently kernel 2.4.x need to use "video=pm3fb:" instead of "video=pm3fb," ; colons instead of comma.

mode:[Y:]XXXXX where XXXXX is one of the valid mode described in pm3fb.c (modebase) and Y an (optional) board number. Default is 800x600-75 w/o OpenFirmware, whatever was available upon boot with OF (kernel 2.2.x). example: video=pm3fb,mode:800x600-75 or video=pm3fb,mode:0:800x600-75. You can use current to keep an already-set mode (you still need to use option flatpanel: for flat-panel display). SGI1600SW will set the 1600x1024 mode this flat panel use (you still need to use option flatpanel: below for this).
pciid:X:B:S:F with X the board number (in the driver), B the Pci Bus number, S the Pci Slot number, and F the Pci Function number. example: video=pm3fb,pciid:0:0:14:0
off:[Y:] or disable:[Y:] (no parameter beyond optional board number Y) disable the board. The board will be allowed internally, but will not be either initialized or used. It's useful if you want to use another driver (offb, vesafb) or skip one board. warning: you should always use pciid and give explicit board number with this option, to make sure the right one is disabled. example: video=pm3fb,pciid:0:0:14:0,off:0:
off (all by itself): disable all boards. Effectively pm3fb will only go trough all PCI devices and do nothing.
font:[Y:]FONTNAME Board Y will default to font of name FONTNAME. example: video=pm3fb,font:VGA8x8
depth:Y:D where D is a valid depth (currently 8,15,16,32); will override depth for card number Y (board number required). example: video=pm3fb:depth:0:32 will force depth 32 for board 0.
flatpanel:[Y:] the monitor on board number Y is a flat panel (not using regular VGA connector). This is mostly untested yet.

Rarely used options:

noaccel:[Y:] (no parameter beyond optional board number Y) disable acceleration for board Y. As with off:, it's safer to explicitely give a board number. Not well-tested.
printtimings print the memory timings of the board(s) prior to initialization. Should only be used for debugging purpose. Symptom of bad memory timings is system hang at boot time, so please report those values in case pm3fb cause the system to hang.
forcesize:Y:S force board Y to use S megabytes of memory no matter how much is probed. should only be used if your board has known problems with memory timings and/or memory probing. Dangerous.

note: internal board number must be allocated in order, without hole ; card number #2 will be used only if card #0 and card #1 are.

note 2: Except for off, each option apply to one board ; for instance, pm3fb,font:VGA8x8 will change font for board 0 but not for board 1.

Options (module)

Options names are the same, but the syntax is different; you must use:

<option_name>=<value_board0>[,<value_board1>[,<value_board2>[...]]]

Options are separated by space. boolean option (noaccel, disable) use '0' (default) or '1' as value.

example: mode=800x600-75,640x480-60 disable=0,1 pciid=0:14:0,0:16:0 will use PCI:0:14:0 as enabled board 0 in 800x600-75, and PCI:0:16:0 as disabled board 1 in 640x480-60.

Known bugs, limitations & workarounds

The following bug isn't a pm3fb bug, but a bug in fbgen; the colormap isn't changed when the RGBA components change but not the depth. A fix is available here (should work with both kernel 2.4.x and 2.2.y).

The original description of this bug was:

There's another depth switching bug, this time concerning only 16bpp. If you use one of the 16bpp mode (depth 12, 15 or 16) and switch to a different one:

fbset -depth 16 will not set RGBA 565 but will keep the previous setting, as fbset will re-use the previous RGBA setting (either RGBA 5551 or RGBA 4444 at the moment).

After the switch, the colormap will be wrong. You need to switch to a non-16bpp depth and back. This can be done with fbset, or by switching back-and-forth to a virtual terminal in a different depth, or to XFree86.

Thanks to the help of Sven Luther, the original depth switching bug has been fixed. Depth switching between 8bpp and 16/32bpp now works.

The original description of this bug was:

The only known bug at the moment relate to depth switching: when going from an 8 bit VT to a 16 or 32 bit VT (using fbset -depth 32 on the current VT or switching among previously-set VT), the colormap is totally wrong. Colormap is restored by going back-and-forth to XFree86 4.x (when using the glint driver). A known workaround involve patching the kernel, but that may broke other fbgen-dependant video drivers:

In the file linux/drivers/video/fbgen.c, there is a function fbgen_switch(). You need to remove the call to fbgen_install_cmap() near the bottom of the function (second-to-last statement). This patch is not included in the distributed linux patch: as said before, it might break other video drivers.

Also, this fix does not work the first time if you boot in 8 bit depth, you need to use the XFree86 trick to get a first working 16/32 VT (if you boot in 16/32bpp this is OK by default).

Todo

more bugs fix

Tools

Warning: those are crude tools, to be used by programmer. If you don't know how to use the output they produce, don't use it. You could damage your board and/or your monitor by putting wrong values in the Permedia3 registers.

fbtimings2pm3-0.2, convert timings in /etc/fb.modes format to timings ready for use in pm3fb.c. Read stdin and give result on stdout. latest version.
xftimings2pm3-0.3, convert timings in XF86Config-4 (the Mode/EndMode in a Monitor section) or XF86Config-3 (i.e. Modeline) format to timings ready for use in pm3fb.c. Read stdin and give result on stdout. latest version.

Changelog

Wed Nov 13 11:19:34 MET 2002, v 1.4.11C: option flatpanel: wasn't available in module, fixed.

Mon Feb 11 10:35:48 MET 2002, v 1.4.11B: Cosmetic update.

Wed Jan 23 14:16:59 MET 2002, v 1.4.11: Preliminary 2.5.x support, patch for 2.5.2.

Wed Nov 28 11:08:29 MET 2001, v 1.4.10: potential bug fix for SDRAM-based board, patch for 2.4.16.

Thu Sep 20 10:24:42 MET DST 2001, v 1.4.9: sync bug fix, preliminary flatpanel support, better timings.

Tue Aug 28 10:13:01 MET DST 2001, v 1.4.8: memory timings check, minor bug fixes.

Wed Jul 18 19:06:14 CEST 2001, v 1.4.7: Mode fix (800x600-100, 1024x768-100 changed), using HW panning + accel bug fix.

Mon Jun 25 10:33:56 MET DST 2001, v 1.4.6: Depth 12 fix, chip reset ioctl, moved memory erase ioctl to DEBUG.

Wed Jun 20 11:13:08 MET DST 2001, v 1.4.5: Fixed missing blinking cursor in 8bpp, code cleaning, memory erase IOCTL.

Mon Jun 18 16:00:27 CEST 2001, v 1.4.4: Depth 12 (RGBA 4444) support, code cleaning.

Fri Jun 15 13:53:01 CEST 2001, v 1.4.3: Removed warnings, depth 15 support, add 'depth' option.

Thu Jun 14 10:13:52 MET DST 2001, v 1.4.2: Fixed depth switching bug, preliminary 15bpp (RGB5551) support.

Thu Apr 12 11:16:45 MET DST 2001, v 1.4.1B: Doc updates.

Fri Apr 6 11:12:53 MET DST 2001, v 1.4.1: Configure.help, minor cleanup

Thu Mar 29 10:56:50 MET DST 2001, v 1.4.0: Module & module options support (note: linux patch changed, 2.2.19 added).

Thu Mar 15 15:30:31 MET 2001, v 1.3.2: Fixed mirroring bug on little-endian.

Wed Mar 14 21:25:54 CET 2001, v 1.3.1: Fixed bug in BlockMove (_bmov).

Tue Mar 13 10:53:19 MET 2001, v 1.3.0: Character drawing hardware support (in all width between 1 and 16), fixes.

Thu Mar 8 10:20:16 MET 2001, v 1.2.2: Better J2000 support, "font:" option.

Tue Mar 6 21:25:04 CET 2001, v 1.2.1: Better acceleration support.

Mon Mar 5 21:54:17 CET 2001, v 1.2.0: Partial acceleration support (clear & bmove)

Mon Mar 5 12:52:15 CET 2001, v 1.1.3: Big pan_display fix.

Sun Mar 4 22:21:50 CET 2001, v 1.1.2: (numerous) bug fixes.

Fri Mar 2 15:54:07 CET 2001, v 1.1.1: Might have Appian J2000 support, resource mangement in 2.4

Wed Feb 28 18:21:35 CET 2001, v 1.1.0: Might have multiple boards support (added, but not yest tested)

Tue Feb 27 17:31:12 CET 2001, v 1.0.6: fixes boot-time mode select, add more default mode

Tue Feb 27 14:01:36 CET 2001, v 1.0.5: fixes (1.0.4 was broken for 2.2), cleaning up

Mon Feb 26 23:17:36 CET 2001, v 1.0.4: preliminary 2.4.x support, dropped (useless on pm3) partial product, more OF fix

Mon Feb 26 20:59:05 CET 2001, v 1.0.3: No more shadow register (and wasted memory), endianess fix, use OF-preset resolution by default

Wed Feb 21 22:09:30 CET 2001, v 1.0.2: Code cleaning for future multiboard support, better OF support, bugs fix

Wed Feb 21 19:58:56 CET 2001, v 1.0.1: OpenFirmware support, fixed memory detection, better debug support, code cleaning

Wed Feb 21 14:47:06 CET 2001, v 1.0.0: First working version

home