code:
=======================
The Frame Buffer Device
=======================

Last revised: May 10, 2001

0. Introduction
---------------

The frame buffer device provides an abstraction for the graphics hardware. It
represents the frame buffer of some video hardware and allows application
software to access the graphics hardware through a well-defined interface, so
the software doesn't need to know anything about the low-level (hardware
register) stuff.

The device is accessed through special device nodes, usually located in the
/dev directory, i.e. /dev/fb*.

1. User's View of /dev/fb*
--------------------------

From the user's point of view, the frame buffer device looks just like any
other device in /dev. It's a character device using major 29; the minor
specifies the frame buffer number.

By convention, the following device nodes are used (numbers indicate the device
minor numbers)::

      0 = /dev/fb0	First frame buffer
      1 = /dev/fb1	Second frame buffer
	  ...
     31 = /dev/fb31	32nd frame buffer

For backwards compatibility, you may want to create the following symbolic
links::

    /dev/fb0current -> fb0
    /dev/fb1current -> fb1

and so on...

The frame buffer devices are also `normal` memory devices, this means, you can
read and write their contents. You can, for example, make a screen snapshot by::

  cp /dev/fb0 myfile

There also can be more than one frame buffer at a time, e.g. if you have a
graphics card in addition to the built-in hardware. The corresponding frame
buffer devices (/dev/fb0 and /dev/fb1 etc.) work independently.

Application software that uses the frame buffer device (e.g. the X server) will
use /dev/fb0 by default (older software uses /dev/fb0current). You can specify
an alternative frame buffer device by setting the environment variable
$FRAMEBUFFER to the path name of a frame buffer device, e.g. (for sh/bash
users)::

    export FRAMEBUFFER=/dev/fb1

or (for csh users)::

    setenv FRAMEBUFFER /dev/fb1

After this the X server will use the second frame buffer.

2. Programmer's View of /dev/fb*
--------------------------------

As you already know, a frame buffer device is a memory device like /dev/mem and
it has the same features. You can read it, write it, seek to some location in
it and mmap() it (the main usage). The difference is just that the memory that
appears in the special file is not the whole memory, but the frame buffer of
some video hardware.

/dev/fb* also allows several ioctls on it, by which lots of information about
the hardware can be queried and set. The color map handling works via ioctls,
too. Look into <linux/fb.h> for more information on what ioctls exist and on
which data structures they work. Here's just a brief overview:

  - You can request unchangeable information about the hardware, like name,
    organization of the screen memory (planes, packed pixels, ...) and address
    and length of the screen memory.

  - You can request and change variable information about the hardware, like
    visible and virtual geometry, depth, color map format, timing, and so on.
    If you try to change that information, the driver maybe will round up some
    values to meet the hardware's capabilities (or return EINVAL if that isn't
    possible).

  - You can get and set parts of the color map. Communication is done with 16
    bits per color part (red, green, blue, transparency) to support all
    existing hardware. The driver does all the computations needed to apply
    it to the hardware (round it down to less bits, maybe throw away
    transparency).

All this hardware abstraction makes the implementation of application programs
easier and more portable. E.g. the X server works completely on /dev/fb* and
thus doesn't need to know, for example, how the color registers of the concrete
hardware are organized. XF68_FBDev is a general X server for bitmapped,
unaccelerated video hardware. The only thing that has to be built into
application programs is the screen organization (bitplanes or chunky pixels
etc.), because it works on the frame buffer image data directly.

For the future it is planned that frame buffer drivers for graphics cards and
the like can be implemented as kernel modules that are loaded at runtime. Such
a driver just has to call register_framebuffer() and supply some functions.
Writing and distributing such drivers independently from the kernel will save
much trouble...

3. Frame Buffer Resolution Maintenance
--------------------------------------

Frame buffer resolutions are maintained using the utility `fbset`. It can
change the video mode properties of a frame buffer device. Its main usage is
to change the current video mode, e.g. during boot up in one of your `/etc/rc.*`
or `/etc/init.d/*` files.

Fbset uses a video mode database stored in a configuration file, so you can
easily add your own modes and refer to them with a simple identifier.

4. The X Server
---------------

The X server (XF68_FBDev) is the most notable application program for the frame
buffer device. Starting with XFree86 release 3.2, the X server is part of
XFree86 and has 2 modes:

  - If the `Display` subsection for the `fbdev` driver in the /etc/XF86Config
    file contains a::

	Modes "default"

    line, the X server will use the scheme discussed above, i.e. it will start
    up in the resolution determined by /dev/fb0 (or $FRAMEBUFFER, if set). You
    still have to specify the color depth (using the Depth keyword) and virtual
    resolution (using the Virtual keyword) though. This is the default for the
    configuration file supplied with XFree86. It's the most simple
    configuration, but it has some limitations.

  - Therefore it's also possible to specify resolutions in the /etc/XF86Config
    file. This allows for on-the-fly resolution switching while retaining the
    same virtual desktop size. The frame buffer device that's used is still
    /dev/fb0current (or $FRAMEBUFFER), but the available resolutions are
    defined by /etc/XF86Config now. The disadvantage is that you have to
    specify the timings in a different format (but `fbset -x` may help).

To tune a video mode, you can use fbset or xvidtune. Note that xvidtune doesn't
work 100% with XF68_FBDev: the reported clock values are always incorrect.

5. Video Mode Timings
---------------------

A monitor draws an image on the screen by using an electron beam (3 electron
beams for color models, 1 electron beam for monochrome monitors). The front of
the screen is covered by a pattern of colored phosphors (pixels). If a phosphor
is hit by an electron, it emits a photon and thus becomes visible.

The electron beam draws horizontal lines (scanlines) from left to right, and
from the top to the bottom of the screen. By modifying the intensity of the
electron beam, pixels with various colors and intensities can be shown.

After each scanline the electron beam has to move back to the left side of the
screen and to the next line: this is called the horizontal retrace. After the
whole screen (frame) was painted, the beam moves back to the upper left corner:
this is called the vertical retrace. During both the horizontal and vertical
retrace, the electron beam is turned off (blanked).

The speed at which the electron beam paints the pixels is determined by the
dotclock in the graphics board. For a dotclock of e.g. 28.37516 MHz (millions
of cycles per second), each pixel is 35242 ps (picoseconds) long::

    1/(28.37516E6 Hz) = 35.242E-9 s

If the screen resolution is 640x480, it will take::

    640*35.242E-9 s = 22.555E-6 s

to paint the 640 (xres) pixels on one scanline. But the horizontal retrace
also takes time (e.g. 272 `pixels`), so a full scanline takes::

    (640+272)*35.242E-9 s = 32.141E-6 s

We'll say that the horizontal scanrate is about 31 kHz::

    1/(32.141E-6 s) = 31.113E3 Hz

A full screen counts 480 (yres) lines, but we have to consider the vertical
retrace too (e.g. 49 `lines`). So a full screen will take::

    (480+49)*32.141E-6 s = 17.002E-3 s

The vertical scanrate is about 59 Hz::

    1/(17.002E-3 s) = 58.815 Hz

This means the screen data is refreshed about 59 times per second. To have a
stable picture without visible flicker, VESA recommends a vertical scanrate of
at least 72 Hz. But the perceived flicker is very human dependent: some people
can use 50 Hz without any trouble, while I'll notice if it's less than 80 Hz.

Since the monitor doesn't know when a new scanline starts, the graphics board
will supply a synchronization pulse (horizontal sync or hsync) for each
scanline.  Similarly it supplies a synchronization pulse (vertical sync or
vsync) for each new frame. The position of the image on the screen is
influenced by the moments at which the synchronization pulses occur.

The following picture summarizes all timings. The horizontal retrace time is
the sum of the left margin, the right margin and the hsync length, while the
vertical retrace time is the sum of the upper margin, the lower margin and the
vsync length::

  +----------+---------------------------------------------+----------+-------+
  |          |                ↑                            |          |       |
  |          |                |upper_margin                |          |       |
  |          |                ↓                            |          |       |
  +----------###############################################----------+-------+
  |          #                ↑                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |   left   #                |                            #  right   | hsync |
  |  margin  #                |       xres                 #  margin  |  len  |
  |<-------->#<---------------+--------------------------->#<-------->|<----->|
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |yres                        #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                |                            #          |       |
  |          #                ↓                            #          |       |
  +----------###############################################----------+-------+
  |          |                ↑                            |          |       |
  |          |                |lower_margin                |          |       |
  |          |                ↓                            |          |       |
  +----------+---------------------------------------------+----------+-------+
  |          |                ↑                            |          |       |
  |          |                |vsync_len                   |          |       |
  |          |                ↓                            |          |       |
  +----------+---------------------------------------------+----------+-------+

The frame buffer device expects all horizontal timings in number of dotclocks
(in picoseconds, 1E-12 s), and vertical timings in number of scanlines.

6. Converting XFree86 timing values info frame buffer device timings
--------------------------------------------------------------------

An XFree86 mode line consists of the following fields::

 "800x600"     50      800  856  976 1040    600  637  643  666
 < name >     DCF       HR  SH1  SH2  HFL     VR  SV1  SV2  VFL

The frame buffer device uses the following fields:

  - pixclock: pixel clock in ps (pico seconds)
  - left_margin: time from sync to picture
  - right_margin: time from picture to sync
  - upper_margin: time from sync to picture
  - lower_margin: time from picture to sync
  - hsync_len: length of horizontal sync
  - vsync_len: length of vertical sync

1) Pixelclock:

   xfree: in MHz

   fb: in picoseconds (ps)

   pixclock = 1000000 / DCF

2) horizontal timings:

   left_margin = HFL - SH2

   right_margin = SH1 - HR

   hsync_len = SH2 - SH1

3) vertical timings:

   upper_margin = VFL - SV2

   lower_margin = SV1 - VR

   vsync_len = SV2 - SV1

Good examples for VESA timings can be found in the XFree86 source tree,
under "xc/programs/Xserver/hw/xfree86/doc/modeDB.txt".

7. References
-------------

For more specific information about the frame buffer device and its
applications, please refer to the Linux-fbdev website:

    http://linux-fbdev.sourceforge.net/

and to the following documentation:

  - The manual pages for fbset: fbset(8), fb.modes(5)
  - The manual pages for XFree86: XF68_FBDev(1), XF86Config(4/5)
  - The mighty kernel sources:

      - linux/drivers/video/
      - linux/include/linux/fb.h
      - linux/include/video/

8. Mailing list
---------------

There is a frame buffer device related mailing list at kernel.org:
linux-fbdev@vger.kernel.org.

Point your web browser to http://sourceforge.net/projects/linux-fbdev/ for
subscription information and archive browsing.

9. Downloading
--------------

All necessary files can be found at

    ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/680x0/

and on its mirrors.

The latest version of fbset can be found at

    http://www.linux-fbdev.org/

10. Credits
-----------

This readme was written by Geert Uytterhoeven, partly based on the original
`X-framebuffer.README` by Roman Hodek and Martin Schaller. Section 6 was
provided by Frank Neumann.

The frame buffer device abstraction was designed by Martin Schaller.


code:
=============
What is gxfb?
=============

.. [This file is cloned from VesaFB/aty128fb]

This is a graphics framebuffer driver for AMD Geode GX2 based processors.

Advantages:

 * No need to use AMD's VSA code (or other VESA emulation layer) in the
   BIOS.
 * It provides a nice large console (128 cols + 48 lines with 1024x768)
   without using tiny, unreadable fonts.
 * You can run XF68_FBDev on top of /dev/fb0
 * Most important: boot logo :-)

Disadvantages:

 * graphic mode is slower than text mode...

How to use it?
==============

Switching modes is done using  gxfb.mode_option=<resolution>... boot
parameter or using `fbset` program.

See Documentation/fb/modedb.rst for more information on modedb
resolutions.

X11
===

XF68_FBDev should generally work fine, but it is non-accelerated.

Configuration
=============

You can pass kernel command line options to gxfb with gxfb.<option>.
For example, gxfb.mode_option=800x600@75.
Accepted options:

================ ==================================================
mode_option	 specify the video mode.  Of the form
		 <x>x<y>[-<bpp>][@<refresh>]
vram		 size of video ram (normally auto-detected)
vt_switch	 enable vt switching during suspend/resume.  The vt
		 switch is slow, but harmless.
================ ==================================================

Andres Salomon <dilinger@debian.org>

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

============
Frame Buffer
============

.. toctree::
    :maxdepth: 1

    api
    arkfb
    aty128fb
    cirrusfb
    cmap_xfbdev
    deferred_io
    efifb
    ep93xx-fb
    fbcon
    framebuffer
    gxfb
    intel810
    intelfb
    internals
    lxfb
    matroxfb
    metronomefb
    modedb
    pvr2fb
    pxafb
    s3fb
    sa1100fb
    sh7760fb
    sisfb
    sm501
    sm712fb
    sstfb
    tgafb
    tridentfb
    udlfb
    uvesafb
    vesafb
    viafb
    vt8623fb

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
================================
Intel 810/815 Framebuffer driver
================================

Tony Daplas <adaplas@pol.net>

http://i810fb.sourceforge.net

March 17, 2002

First Released: July 2001
Last Update:    September 12, 2005

A. Introduction
===============

	This is a framebuffer driver for various Intel 810/815 compatible
	graphics devices.  These include:

	- Intel 810
	- Intel 810E
	- Intel 810-DC100
	- Intel 815 Internal graphics only, 100Mhz FSB
	- Intel 815 Internal graphics only
	- Intel 815 Internal graphics and AGP

B.  Features
============

	- Choice of using Discrete Video Timings, VESA Generalized Timing
	  Formula, or a framebuffer specific database to set the video mode

	- Supports a variable range of horizontal and vertical resolution and
	  vertical refresh rates if the VESA Generalized Timing Formula is
	  enabled.

	- Supports color depths of 8, 16, 24 and 32 bits per pixel

	- Supports pseudocolor, directcolor, or truecolor visuals

	- Full and optimized hardware acceleration at 8, 16 and 24 bpp

	- Robust video state save and restore

	- MTRR support

	- Utilizes user-entered monitor specifications to automatically
	  calculate required video mode parameters.

	- Can concurrently run with xfree86 running with native i810 drivers

	- Hardware Cursor Support

	- Supports EDID probing either by DDC/I2C or through the BIOS

C.  List of available options
=============================

   a. "video=i810fb"
	enables the i810 driver

	Recommendation: required

   b. "xres:<value>"
	select horizontal resolution in pixels. (This parameter will be
	ignored if 'mode_option' is specified.  See 'o' below).

	Recommendation: user preference
	(default = 640)

   c. "yres:<value>"
	select vertical resolution in scanlines. If Discrete Video Timings
	is enabled, this will be ignored and computed as 3*xres/4.  (This
	parameter will be ignored if 'mode_option' is specified.  See 'o'
	below)

	Recommendation: user preference
	(default = 480)

   d. "vyres:<value>"
	select virtual vertical resolution in scanlines. If (0) or none
	is specified, this will be computed against maximum available memory.

	Recommendation: do not set
	(default = 480)

   e. "vram:<value>"
	select amount of system RAM in MB to allocate for the video memory

	Recommendation: 1 - 4 MB.
	(default = 4)

   f. "bpp:<value>"
	select desired pixel depth

	Recommendation: 8
	(default = 8)

   g. "hsync1/hsync2:<value>"
	select the minimum and maximum Horizontal Sync Frequency of the
	monitor in kHz.  If using a fixed frequency monitor, hsync1 must
	be equal to hsync2. If EDID probing is successful, these will be
	ignored and values will be taken from the EDID block.

	Recommendation: check monitor manual for correct values
	(default = 29/30)

   h. "vsync1/vsync2:<value>"
	select the minimum and maximum Vertical Sync Frequency of the monitor
	in Hz. You can also use this option to lock your monitor's refresh
	rate. If EDID probing is successful, these will be ignored and values
	will be taken from the EDID block.

	Recommendation: check monitor manual for correct values
	(default = 60/60)

	IMPORTANT:  If you need to clamp your timings, try to give some
	leeway for computational errors (over/underflows).  Example: if
	using vsync1/vsync2 = 60/60, make sure hsync1/hsync2 has at least
	a 1 unit difference, and vice versa.

   i. "voffset:<value>"
	select at what offset in MB of the logical memory to allocate the
	framebuffer memory.  The intent is to avoid the memory blocks
	used by standard graphics applications (XFree86).  The default
	offset (16 MB for a 64 MB aperture, 8 MB for a 32 MB aperture) will
	avoid XFree86's usage and allows up to 7 MB/15 MB of framebuffer
	memory.  Depending on your usage, adjust the value up or down
	(0 for maximum usage, 31/63 MB for the least amount).  Note, an
	arbitrary setting may conflict with XFree86.

	Recommendation: do not set
	(default = 8 or 16 MB)

   j. "accel"
	enable text acceleration.  This can be enabled/reenabled anytime
	by using 'fbset -accel true/false'.

	Recommendation: enable
	(default = not set)

   k. "mtrr"
	enable MTRR.  This allows data transfers to the framebuffer memory
	to occur in bursts which can significantly increase performance.
	Not very helpful with the i810/i815 because of 'shared memory'.

	Recommendation: do not set
	(default = not set)

   l. "extvga"
	if specified, secondary/external VGA output will always be enabled.
	Useful if the BIOS turns off the VGA port when no monitor is attached.
	The external VGA monitor can then be attached without rebooting.

	Recommendation: do not set
	(default = not set)

   m. "sync"
	Forces the hardware engine to do a "sync" or wait for the hardware
	to finish before starting another instruction. This will produce a
	more stable setup, but will be slower.

	Recommendation: do not set
	(default = not set)

   n. "dcolor"
	Use directcolor visual instead of truecolor for pixel depths greater
	than 8 bpp.  Useful for color tuning, such as gamma control.

	Recommendation: do not set
	(default = not set)

   o. <xres>x<yres>[-<bpp>][@<refresh>]
	The driver will now accept specification of boot mode option.  If this
	is specified, the options 'xres' and 'yres' will be ignored. See
	Documentation/fb/modedb.rst for usage.

D. Kernel booting
=================

Separate each option/option-pair by commas (,) and the option from its value
with a colon (:) as in the following::

	video=i810fb:option1,option2:value2

Sample Usage
------------

In /etc/lilo.conf, add the line::

  append="video=i810fb:vram:2,xres:1024,yres:768,bpp:8,hsync1:30,hsync2:55, \
	  vsync1:50,vsync2:85,accel,mtrr"

This will initialize the framebuffer to 1024x768 at 8bpp.  The framebuffer
will use 2 MB of System RAM. MTRR support will be enabled. The refresh rate
will be computed based on the hsync1/hsync2 and vsync1/vsync2 values.

IMPORTANT:
  You must include hsync1, hsync2, vsync1 and vsync2 to enable video modes
  better than 640x480 at 60Hz. HOWEVER, if your chipset/display combination
  supports I2C and has an EDID block, you can safely exclude hsync1, hsync2,
  vsync1 and vsync2 parameters.  These parameters will be taken from the EDID
  block.

E.  Module options
==================

The module parameters are essentially similar to the kernel
parameters. The main difference is that you need to include a Boolean value
(1 for TRUE, and 0 for FALSE) for those options which don't need a value.

Example, to enable MTRR, include "mtrr=1".

Sample Usage
------------

Using the same setup as described above, load the module like this::

	modprobe i810fb vram=2 xres=1024 bpp=8 hsync1=30 hsync2=55 vsync1=50 \
		 vsync2=85 accel=1 mtrr=1

Or just add the following to a configuration file in /etc/modprobe.d/::

	options i810fb vram=2 xres=1024 bpp=16 hsync1=30 hsync2=55 vsync1=50 \
	vsync2=85 accel=1 mtrr=1

and just do a::

	modprobe i810fb

F.  Setup
=========

	a. Do your usual method of configuring the kernel

	   make menuconfig/xconfig/config

	b. Under "Code maturity level options" enable "Prompt for development
	   and/or incomplete code/drivers".

	c. Enable agpgart support for the Intel 810/815 on-board graphics.
	   This is required.  The option is under "Character Devices".

	d. Under "Graphics Support", select "Intel 810/815" either statically
	   or as a module.  Choose "use VESA Generalized Timing Formula" if
	   you need to maximize the capability of your display.  To be on the
	   safe side, you can leave this unselected.

	e. If you want support for DDC/I2C probing (Plug and Play Displays),
	   set 'Enable DDC Support' to 'y'. To make this option appear, set
	   'use VESA Generalized Timing Formula' to 'y'.

	f. If you want a framebuffer console, enable it under "Console
	   Drivers".

	g. Compile your kernel.

	h. Load the driver as described in sections D and E.

	i.  Try the DirectFB (http://www.directfb.org) + the i810 gfxdriver
	    patch to see the chipset in action (or inaction :-).

G.  Acknowledgment:
===================

	1.  Geert Uytterhoeven - his excellent howto and the virtual
	    framebuffer driver code made this possible.

	2.  Jeff Hartmann for his agpgart code.

	3.  The X developers.  Insights were provided just by reading the
	    XFree86 source code.

	4.  Intel(c).  For this value-oriented chipset driver and for
	    providing documentation.

	5. Matt Sottek.  His inputs and ideas  helped in making some
	   optimizations possible.

H.  Home Page:
==============

	A more complete, and probably updated information is provided at
	http://i810fb.sourceforge.net.

Tony


code:
=============================================================
Intel 830M/845G/852GM/855GM/865G/915G/945G Framebuffer driver
=============================================================

A. Introduction
===============

This is a framebuffer driver for various Intel 8xx/9xx compatible
graphics devices.  These would include:

	- Intel 830M
	- Intel 845G
	- Intel 852GM
	- Intel 855GM
	- Intel 865G
	- Intel 915G
	- Intel 915GM
	- Intel 945G
	- Intel 945GM
	- Intel 945GME
	- Intel 965G
	- Intel 965GM

B.  List of available options
=============================

   a. "video=intelfb"
	enables the intelfb driver

	Recommendation: required

   b. "mode=<xres>x<yres>[-<bpp>][@<refresh>]"
	select mode

	Recommendation: user preference
	(default = 1024x768-32@70)

   c. "vram=<value>"
	select amount of system RAM in MB to allocate for the video memory
	if not enough RAM was already allocated by the BIOS.

	Recommendation: 1 - 4 MB.
	(default = 4 MB)

   d. "voffset=<value>"
	select at what offset in MB of the logical memory to allocate the
	framebuffer memory.  The intent is to avoid the memory blocks
	used by standard graphics applications (XFree86). Depending on your
	usage, adjust the value up or down, (0 for maximum usage, 63/127 MB
	for the least amount).  Note, an arbitrary setting may conflict
	with XFree86.

	Recommendation: do not set
	(default = 48 MB)

   e. "accel"
	enable text acceleration.  This can be enabled/reenabled anytime
	by using 'fbset -accel true/false'.

	Recommendation: enable
	(default = set)

   f. "hwcursor"
	enable cursor acceleration.

	Recommendation: enable
	(default = set)

   g. "mtrr"
	enable MTRR.  This allows data transfers to the framebuffer memory
	to occur in bursts which can significantly increase performance.
	Not very helpful with the intel chips because of 'shared memory'.

	Recommendation: set
	(default = set)

   h. "fixed"
	disable mode switching.

	Recommendation: do not set
	(default = not set)

   The binary parameters can be unset with a "no" prefix, example "noaccel".
   The default parameter (not named) is the mode.

C. Kernel booting
=================

Separate each option/option-pair by commas (,) and the option from its value
with an equals sign (=) as in the following::

	video=intelfb:option1,option2=value2

Sample Usage
------------

In /etc/lilo.conf, add the line::

	append="video=intelfb:mode=800x600-32@75,accel,hwcursor,vram=8"

This will initialize the framebuffer to 800x600 at 32bpp and 75Hz. The
framebuffer will use 8 MB of System RAM. hw acceleration of text and cursor
will be enabled.

Remarks
-------

If setting this parameter doesn't work (you stay in a 80x25 text-mode),
you might need to set the "vga=<mode>" parameter too - see vesafb.txt
in this directory.

D.  Module options
==================

The module parameters are essentially similar to the kernel
parameters. The main difference is that you need to include a Boolean value
(1 for TRUE, and 0 for FALSE) for those options which don't need a value.

Example, to enable MTRR, include "mtrr=1".

Sample Usage
------------

Using the same setup as described above, load the module like this::

	modprobe intelfb mode=800x600-32@75 vram=8 accel=1 hwcursor=1

Or just add the following to a configuration file in /etc/modprobe.d/::

	options intelfb mode=800x600-32@75 vram=8 accel=1 hwcursor=1

and just do a::

	modprobe intelfb

E.  Acknowledgment:
===================

	1.  Geert Uytterhoeven - his excellent howto and the virtual
	    framebuffer driver code made this possible.

	2.  Jeff Hartmann for his agpgart code.

	3.  David Dawes for his original kernel 2.4 code.

	4.  The X developers.  Insights were provided just by reading the
	    XFree86 source code.

	5.  Antonino A. Daplas for his inspiring i810fb driver.

	6.  Andrew Morton for his kernel patches maintenance.

Sylvain


code:
=============================
Frame Buffer device internals
=============================

This is a first start for some documentation about frame buffer device
internals.

Authors:

- Geert Uytterhoeven <geert@linux-m68k.org>, 21 July 1998
- James Simmons <jsimmons@user.sf.net>, Nov 26 2002

--------------------------------------------------------------------------------

Structures used by the frame buffer device API
==============================================

The following structures play a role in the game of frame buffer devices. They
are defined in <linux/fb.h>.

1. Outside the kernel (user space)

  - struct fb_fix_screeninfo

    Device independent unchangeable information about a frame buffer device and
    a specific video mode. This can be obtained using the FBIOGET_FSCREENINFO
    ioctl.

  - struct fb_var_screeninfo

    Device independent changeable information about a frame buffer device and a
    specific video mode. This can be obtained using the FBIOGET_VSCREENINFO
    ioctl, and updated with the FBIOPUT_VSCREENINFO ioctl. If you want to pan
    the screen only, you can use the FBIOPAN_DISPLAY ioctl.

  - struct fb_cmap

    Device independent colormap information. You can get and set the colormap
    using the FBIOGETCMAP and FBIOPUTCMAP ioctls.

2. Inside the kernel

  - struct fb_info

    Generic information, API and low level information about a specific frame
    buffer device instance (slot number, board address, ...).

  - struct `par`

    Device dependent information that uniquely defines the video mode for this
    particular piece of hardware.

Visuals used by the frame buffer device API
===========================================

Monochrome (FB_VISUAL_MONO01 and FB_VISUAL_MONO10)
--------------------------------------------------
Each pixel is either black or white.

Pseudo color (FB_VISUAL_PSEUDOCOLOR and FB_VISUAL_STATIC_PSEUDOCOLOR)
---------------------------------------------------------------------
The whole pixel value is fed through a programmable lookup table that has one
color (including red, green, and blue intensities) for each possible pixel
value, and that color is displayed.

True color (FB_VISUAL_TRUECOLOR)
--------------------------------
The pixel value is broken up into red, green, and blue fields.

Direct color (FB_VISUAL_DIRECTCOLOR)
------------------------------------
The pixel value is broken up into red, green, and blue fields, each of which
are looked up in separate red, green, and blue lookup tables.

Grayscale displays
------------------
Grayscale and static grayscale are special variants of pseudo color and static
pseudo color, where the red, green and blue components are always equal to
each other.


code:
=============
What is lxfb?
=============

.. [This file is cloned from VesaFB/aty128fb]

This is a graphics framebuffer driver for AMD Geode LX based processors.

Advantages:

 * No need to use AMD's VSA code (or other VESA emulation layer) in the
   BIOS.
 * It provides a nice large console (128 cols + 48 lines with 1024x768)
   without using tiny, unreadable fonts.
 * You can run XF68_FBDev on top of /dev/fb0
 * Most important: boot logo :-)

Disadvantages:

 * graphic mode is slower than text mode...

How to use it?
==============

Switching modes is done using  lxfb.mode_option=<resolution>... boot
parameter or using `fbset` program.

See Documentation/fb/modedb.rst for more information on modedb
resolutions.

X11
===

XF68_FBDev should generally work fine, but it is non-accelerated.

Configuration
=============

You can pass kernel command line options to lxfb with lxfb.<option>.
For example, lxfb.mode_option=800x600@75.
Accepted options:

================ ==================================================
mode_option	 specify the video mode.  Of the form
		 <x>x<y>[-<bpp>][@<refresh>]
vram		 size of video ram (normally auto-detected)
vt_switch	 enable vt switching during suspend/resume.  The vt
		 switch is slow, but harmless.
================ ==================================================

Andres Salomon <dilinger@debian.org>


code:
=================
What is matroxfb?
=================

.. [This file is cloned from VesaFB. Thanks go to Gerd Knorr]

This is a driver for a graphic framebuffer for Matrox devices on
Alpha, Intel and PPC boxes.

Advantages:

 * It provides a nice large console (128 cols + 48 lines with 1024x768)
   without using tiny, unreadable fonts.
 * You can run XF{68,86}_FBDev or XFree86 fbdev driver on top of /dev/fb0
 * Most important: boot logo :-)

Disadvantages:

 * graphic mode is slower than text mode... but you should not notice
   if you use same resolution as you used in textmode.

How to use it?
==============

Switching modes is done using the video=matroxfb:vesa:... boot parameter
or using `fbset` program.

If you want, for example, enable a resolution of 1280x1024x24bpp you should
pass to the kernel this command line: "video=matroxfb:vesa:0x1BB".

You should compile in both vgacon (to boot if you remove you Matrox from
box) and matroxfb (for graphics mode). You should not compile-in vesafb
unless you have primary display on non-Matrox VBE2.0 device (see
Documentation/fb/vesafb.rst for details).

Currently supported video modes are (through vesa:... interface, PowerMac
has [as addon] compatibility code):

Graphic modes
-------------

===  =======  =======  =======  =======  =======
bpp  640x400  640x480  768x576  800x600  960x720
===  =======  =======  =======  =======  =======
  4             0x12             0x102
  8   0x100    0x101    0x180    0x103    0x188
 15            0x110    0x181    0x113    0x189
 16            0x111    0x182    0x114    0x18A
 24            0x1B2    0x184    0x1B5    0x18C
 32            0x112    0x183    0x115    0x18B
===  =======  =======  =======  =======  =======

Graphic modes (continued)
-------------------------

===  ======== ======== ========= ========= =========
bpp  1024x768 1152x864 1280x1024 1408x1056 1600x1200
===  ======== ======== ========= ========= =========
  4    0x104             0x106
  8    0x105    0x190    0x107     0x198     0x11C
 15    0x116    0x191    0x119     0x199     0x11D
 16    0x117    0x192    0x11A     0x19A     0x11E
 24    0x1B8    0x194    0x1BB     0x19C     0x1BF
 32    0x118    0x193    0x11B     0x19B
===  ======== ======== ========= ========= =========

Text modes
----------

==== =======  =======  ========  ========  ========
text 640x400  640x480  1056x344  1056x400  1056x480
==== =======  =======  ========  ========  ========
 8x8   0x1C0    0x108     0x10A     0x10B     0x10C
8x16 2, 3, 7                        0x109
==== =======  =======  ========  ========  ========

You can enter these number either hexadecimal (leading `0x`) or decimal
(0x100 = 256). You can also use value + 512 to achieve compatibility
with your old number passed to vesafb.

Non-listed number can be achieved by more complicated command-line, for
example 1600x1200x32bpp can be specified by `video=matroxfb:vesa:0x11C,depth:32`.

X11
===

XF{68,86}_FBDev should work just fine, but it is non-accelerated. On non-intel
architectures there are some glitches for 24bpp videomodes. 8, 16 and 32bpp
works fine.

Running another (accelerated) X-Server like XF86_SVGA works too. But (at least)
XFree servers have big troubles in multihead configurations (even on first
head, not even talking about second). Running XFree86 4.x accelerated mga
driver is possible, but you must not enable DRI - if you do, resolution and
color depth of your X desktop must match resolution and color depths of your
virtual consoles, otherwise X will corrupt accelerator settings.

SVGALib
=======

Driver contains SVGALib compatibility code. It is turned on by choosing textual
mode for console. You can do it at boot time by using videomode
2,3,7,0x108-0x10C or 0x1C0. At runtime, `fbset -depth 0` does this work.
Unfortunately, after SVGALib application exits, screen contents is corrupted.
Switching to another console and back fixes it. I hope that it is SVGALib's
problem and not mine, but I'm not sure.

Configuration
=============

You can pass kernel command line options to matroxfb with
`video=matroxfb:option1,option2:value2,option3` (multiple options should be
separated by comma, values are separated from options by `:`).
Accepted options:

============ ===================================================================
mem:X        size of memory (X can be in megabytes, kilobytes or bytes)
	     You can only decrease value determined by driver because of
	     it always probe for memory. Default is to use whole detected
	     memory usable for on-screen display (i.e. max. 8 MB).
disabled     do not load driver; you can use also `off`, but `disabled`
	     is here too.
enabled      load driver, if you have `video=matroxfb:disabled` in LILO
	     configuration, you can override it by this (you cannot override
	     `off`). It is default.
noaccel      do not use acceleration engine. It does not work on Alphas.
accel        use acceleration engine. It is default.
nopan        create initial consoles with vyres = yres, thus disabling virtual
	     scrolling.
pan          create initial consoles as tall as possible (vyres = memory/vxres).
	     It is default.
nopciretry   disable PCI retries. It is needed for some broken chipsets,
	     it is autodetected for intel's 82437. In this case device does
	     not comply to PCI 2.1 specs (it will not guarantee that every
	     transaction terminate with success or retry in 32 PCLK).
pciretry     enable PCI retries. It is default, except for intel's 82437.
novga        disables VGA I/O ports. It is default if BIOS did not enable
	     device. You should not use this option, some boards then do not
	     restart without power off.
vga          preserve state of VGA I/O ports. It is default. Driver does not
	     enable VGA I/O if BIOS did not it (it is not safe to enable it in
	     most cases).
nobios       disables BIOS ROM. It is default if BIOS did not enable BIOS
	     itself. You should not use this option, some boards then do not
	     restart without power off.
bios         preserve state of BIOS ROM. It is default. Driver does not enable
	     BIOS if BIOS was not enabled before.
noinit       tells driver, that devices were already initialized. You should use
	     it if you have G100 and/or if driver cannot detect memory, you see
	     strange pattern on screen and so on. Devices not enabled by BIOS
	     are still initialized. It is default.
init         driver initializes every device it knows about.
memtype      specifies memory type, implies 'init'. This is valid only for G200
	     and G400 and has following meaning:

	       G200:
		 -  0 -> 2x128Kx32 chips, 2MB onboard, probably sgram
		 -  1 -> 2x128Kx32 chips, 4MB onboard, probably sgram
		 -  2 -> 2x256Kx32 chips, 4MB onboard, probably sgram
		 -  3 -> 2x256Kx32 chips, 8MB onboard, probably sgram
		 -  4 -> 2x512Kx16 chips, 8/16MB onboard, probably sdram only
		 -  5 -> same as above
		 -  6 -> 4x128Kx32 chips, 4MB onboard, probably sgram
		 -  7 -> 4x128Kx32 chips, 8MB onboard, probably sgram
	       G400:
		 -  0 -> 2x512Kx16 SDRAM, 16/32MB
		 -	 2x512Kx32 SGRAM, 16/32MB
		 -  1 -> 2x256Kx32 SGRAM, 8/16MB
		 -  2 -> 4x128Kx32 SGRAM, 8/16MB
		 -  3 -> 4x512Kx32 SDRAM, 32MB
		 -  4 -> 4x256Kx32 SGRAM, 16/32MB
		 -  5 -> 2x1Mx32 SDRAM, 32MB
		 -  6 -> reserved
		 -  7 -> reserved

	     You should use sdram or sgram parameter in addition to memtype
	     parameter.
nomtrr       disables write combining on frame buffer. This slows down driver
	     but there is reported minor incompatibility between GUS DMA and
	     XFree under high loads if write combining is enabled (sound
	     dropouts).
mtrr         enables write combining on frame buffer. It speeds up video
	     accesses much. It is default. You must have MTRR support enabled
	     in kernel and your CPU must have MTRR (f.e. Pentium II have them).
sgram        tells to driver that you have Gxx0 with SGRAM memory. It has no
	     effect without `init`.
sdram        tells to driver that you have Gxx0 with SDRAM memory.
	     It is a default.
inv24        change timings parameters for 24bpp modes on Millennium and
	     Millennium II. Specify this if you see strange color shadows
	     around  characters.
noinv24      use standard timings. It is the default.
inverse      invert colors on screen (for LCD displays)
noinverse    show true colors on screen. It is default.
dev:X        bind driver to device X. Driver numbers device from 0 up to N,
	     where device 0 is first `known` device found, 1 second and so on.
	     lspci lists devices in this order.
	     Default is `every` known device.
nohwcursor   disables hardware cursor (use software cursor instead).
hwcursor     enables hardware cursor. It is default. If you are using
	     non-accelerated mode (`noaccel` or `fbset -accel false`), software
	     cursor is used (except for text mode).
noblink      disables cursor blinking. Cursor in text mode always blinks (hw
	     limitation).
blink        enables cursor blinking. It is default.
nofastfont   disables fastfont feature. It is default.
fastfont:X   enables fastfont feature. X specifies size of memory reserved for
	     font data, it must be >= (fontwidth*fontheight*chars_in_font)/8.
	     It is faster on Gx00 series, but slower on older cards.
grayscale    enable grayscale summing. It works in PSEUDOCOLOR modes (text,
	     4bpp, 8bpp). In DIRECTCOLOR modes it is limited to characters
	     displayed through putc/putcs. Direct accesses to framebuffer
	     can paint colors.
nograyscale  disable grayscale summing. It is default.
cross4MB     enables that pixel line can cross 4MB boundary. It is default for
	     non-Millennium.
nocross4MB   pixel line must not cross 4MB boundary. It is default for
	     Millennium I or II, because of these devices have hardware
	     limitations which do not allow this. But this option is
	     incompatible with some (if not all yet released) versions of
	     XF86_FBDev.
dfp          enables digital flat panel interface. This option is incompatible
	     with secondary (TV) output - if DFP is active, TV output must be
	     inactive and vice versa. DFP always uses same timing as primary
	     (monitor) output.
dfp:X        use settings X for digital flat panel interface. X is number from
	     0 to 0xFF, and meaning of each individual bit is described in
	     G400 manual, in description of DAC register 0x1F. For normal
	     operation you should set all bits to zero, except lowest bit. This
	     lowest bit selects who is source of display clocks, whether G400,
	     or panel. Default value is now read back from hardware - so you
	     should specify this value only if you are also using `init`
	     parameter.
outputs:XYZ  set mapping between CRTC and outputs. Each letter can have value
	     of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter
	     corresponds to primary analog output, second letter to the
	     secondary analog output and third letter to the DVI output.
	     Default setting is 100 for cards below G400 or G400 without DFP,
	     101 for G400 with DFP, and 111 for G450 and G550. You can set
	     mapping only on first card, use matroxset for setting up other
	     devices.
vesa:X       selects startup videomode. X is number from 0 to 0x1FF, see table
	     above for detailed explanation. Default is 640x480x8bpp if driver
	     has 8bpp support. Otherwise first available of 640x350x4bpp,
	     640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text
	     (80x25 text is always available).
============ ===================================================================

If you are not satisfied with videomode selected by `vesa` option, you
can modify it with these options:

============ ===================================================================
xres:X       horizontal resolution, in pixels. Default is derived from `vesa`
	     option.
yres:X       vertical resolution, in pixel lines. Default is derived from `vesa`
	     option.
upper:X      top boundary: lines between end of VSYNC pulse and start of first
	     pixel line of picture. Default is derived from `vesa` option.
lower:X      bottom boundary: lines between end of picture and start of VSYNC
	     pulse. Default is derived from `vesa` option.
vslen:X      length of VSYNC pulse, in lines. Default is derived from `vesa`
	     option.
left:X       left boundary: pixels between end of HSYNC pulse and first pixel.
	     Default is derived from `vesa` option.
right:X      right boundary: pixels between end of picture and start of HSYNC
	     pulse. Default is derived from `vesa` option.
hslen:X      length of HSYNC pulse, in pixels. Default is derived from `vesa`
	     option.
pixclock:X   dotclocks, in ps (picoseconds). Default is derived from `vesa`
	     option and from `fh` and `fv` options.
sync:X       sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity.
	     If bit 3 (value 0x08) is set, composite sync instead of HSYNC is
	     generated. If bit 5 (value 0x20) is set, sync on green is turned
	     on. Do not forget that if you want sync on green, you also probably
	     want composite sync.
	     Default depends on `vesa`.
depth:X      Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on
	     `vesa`.
============ ===================================================================

If you know capabilities of your monitor, you can specify some (or all) of
`maxclk`, `fh` and `fv`. In this case, `pixclock` is computed so that
pixclock <= maxclk, real_fh <= fh and real_fv <= fv.

============ ==================================================================
maxclk:X     maximum dotclock. X can be specified in MHz, kHz or Hz. Default is
	     `don`t care`.
fh:X         maximum horizontal synchronization frequency. X can be specified
	     in kHz or Hz. Default is `don't care`.
fv:X         maximum vertical frequency. X must be specified in Hz. Default is
	     70 for modes derived from `vesa` with yres <= 400, 60Hz for
	     yres > 400.
============ ==================================================================

Limitations
===========

There are known and unknown bugs, features and misfeatures.
Currently there are following known bugs:

 - SVGALib does not restore screen on exit
 - generic fbcon-cfbX procedures do not work on Alphas. Due to this,
   `noaccel` (and cfb4 accel) driver does not work on Alpha. So everyone
   with access to `/dev/fb*` on Alpha can hang machine (you should restrict
   access to `/dev/fb*` - everyone with access to this device can destroy
   your monitor, believe me...).
 - 24bpp does not support correctly XF-FBDev on big-endian architectures.
 - interlaced text mode is not supported; it looks like hardware limitation,
   but I'm not sure.
 - Gxx0 SGRAM/SDRAM is not autodetected.
 - maybe more...

And following misfeatures:

 - SVGALib does not restore screen on exit.
 - pixclock for text modes is limited by hardware to

    - 83 MHz on G200
    - 66 MHz on Millennium I
    - 60 MHz on Millennium II

   Because I have no access to other devices, I do not know specific
   frequencies for them. So driver does not check this and allows you to
   set frequency higher that this. It causes sparks, black holes and other
   pretty effects on screen. Device was not destroyed during tests. :-)
 - my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
   (and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)).
   But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe
   them (maybe that chip overheats, but it has a very big cooler (G100 has
   none), so it should work).
 - special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
   G16V16 are not supported
 - color keying is not supported
 - feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
   by BIOS)
 - DDC (monitor detection) is supported through dualhead driver
 - some check for input values are not so strict how it should be (you can
   specify vslen=4000 and so on).
 - maybe more...

And following features:

 - 4bpp is available only on Millennium I and Millennium II. It is hardware
   limitation.
 - selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba
   option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything
   else selects 5:6:5 mode.
 - text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
   instead of one of 16M colors). It is due to hardware limitation of
   Millennium I/II and SVGALib compatibility.

Benchmarks
==========
It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is
time for draw 6144000 characters on screen through /dev/vcsa
(for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in
16 seconds, i.e. 187 MBps).
Times were obtained from one older version of driver, now they are about 3%
faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz
PCI slot, G200 in AGP 2x slot. I did not test vgacon::

  NOACCEL
	8x16                 12x22
	Millennium I  G200   Millennium I  G200
  8bpp    16.42         9.54   12.33         9.13
  16bpp   21.00        15.70   19.11        15.02
  24bpp   36.66        36.66   35.00        35.00
  32bpp   35.00        30.00   33.85        28.66

  ACCEL, nofastfont
	8x16                 12x22                6x11
	Millennium I  G200   Millennium I  G200   Millennium I  G200
  8bpp     7.79         7.24   13.55         7.78   30.00        21.01
  16bpp    9.13         7.78   16.16         7.78   30.00        21.01
  24bpp   14.17        10.72   18.69        10.24   34.99        21.01
  32bpp   16.15	     16.16   18.73        13.09   34.99        21.01

  ACCEL, fastfont
	8x16                 12x22                6x11
	Millennium I  G200   Millennium I  G200   Millennium I  G200
  8bpp     8.41         6.01    6.54         4.37   16.00        10.51
  16bpp    9.54         9.12    8.76         6.17   17.52        14.01
  24bpp   15.00        12.36   11.67        10.00   22.01        18.32
  32bpp   16.18        18.29*  12.71        12.74   24.44        21.00

  TEXT
	8x16
	Millennium I  G200
  TEXT     3.29         1.50

  * Yes, it is slower than Millennium I.

Dualhead G400
=============
Driver supports dualhead G400 with some limitations:
 + secondary head shares videomemory with primary head. It is not problem
   if you have 32MB of videoram, but if you have only 16MB, you may have
   to think twice before choosing videomode (for example twice 1880x1440x32bpp
   is not possible).
 + due to hardware limitation, secondary head can use only 16 and 32bpp
   videomodes.
 + secondary head is not accelerated. There were bad problems with accelerated
   XFree when secondary head used to use acceleration.
 + secondary head always powerups in 640x480@60-32 videomode. You have to use
   fbset to change this mode.
 + secondary head always powerups in monitor mode. You have to use fbmatroxset
   to change it to TV mode. Also, you must select at least 525 lines for
   NTSC output and 625 lines for PAL output.
 + kernel is not fully multihead ready. So some things are impossible to do.
 + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
   and matroxfb_crtc2 into kernel.

Dualhead G450
=============
Driver supports dualhead G450 with some limitations:
 + secondary head shares videomemory with primary head. It is not problem
   if you have 32MB of videoram, but if you have only 16MB, you may have
   to think twice before choosing videomode.
 + due to hardware limitation, secondary head can use only 16 and 32bpp
   videomodes.
 + secondary head is not accelerated.
 + secondary head always powerups in 640x480@60-32 videomode. You have to use
   fbset to change this mode.
 + TV output is not supported
 + kernel is not fully multihead ready, so some things are impossible to do.
 + if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2
   into kernel.

Petr Vandrovec <vandrove@vc.cvut.cz>


code:
===========
Metronomefb
===========

Maintained by Jaya Kumar <jayakumar.lkml.gmail.com>

Last revised: Mar 10, 2008

Metronomefb is a driver for the Metronome display controller. The controller
is from E-Ink Corporation. It is intended to be used to drive the E-Ink
Vizplex display media. E-Ink hosts some details of this controller and the
display media here http://www.e-ink.com/products/matrix/metronome.html .

Metronome is interfaced to the host CPU through the AMLCD interface. The
host CPU generates the control information and the image in a framebuffer
which is then delivered to the AMLCD interface by a host specific method.
The display and error status are each pulled through individual GPIOs.

Metronomefb is platform independent and depends on a board specific driver
to do all physical IO work. Currently, an example is implemented for the
PXA board used in the AM-200 EPD devkit. This example is am200epd.c

Metronomefb requires waveform information which is delivered via the AMLCD
interface to the metronome controller. The waveform information is expected to
be delivered from userspace via the firmware class interface. The waveform file
can be compressed as long as your udev or hotplug script is aware of the need
to uncompress it before delivering it. metronomefb will ask for metronome.wbf
which would typically go into /lib/firmware/metronome.wbf depending on your
udev/hotplug setup. I have only tested with a single waveform file which was
originally labeled 23P01201_60_WT0107_MTC. I do not know what it stands for.
Caution should be exercised when manipulating the waveform as there may be
a possibility that it could have some permanent effects on the display media.
I neither have access to nor know exactly what the waveform does in terms of
the physical media.

Metronomefb uses the deferred IO interface so that it can provide a memory
mappable frame buffer. It has been tested with tinyx (Xfbdev). It is known
to work at this time with xeyes, xclock, xloadimage, xpdf.


code:
=================================
modedb default video mode support
=================================

Currently all frame buffer device drivers have their own video mode databases,
which is a mess and a waste of resources. The main idea of modedb is to have

  - one routine to probe for video modes, which can be used by all frame buffer
    devices
  - one generic video mode database with a fair amount of standard videomodes
    (taken from XFree86)
  - the possibility to supply your own mode database for graphics hardware that
    needs non-standard modes, like amifb and Mac frame buffer drivers (which
    use macmodes.c)

When a frame buffer device receives a video= option it doesn't know, it should
consider that to be a video mode option. If no frame buffer device is specified
in a video= option, fbmem considers that to be a global video mode option.

Valid mode specifiers (mode_option argument)::

    <xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]
    <name>[-<bpp>][@<refresh>]

with <xres>, <yres>, <bpp> and <refresh> decimal numbers and <name> a string.
Things between square brackets are optional.

Valid names are::

  - NSTC: 480i output, with the CCIR System-M TV mode and NTSC color encoding
  - PAL: 576i output, with the CCIR System-B TV mode and PAL color encoding

If 'M' is specified in the mode_option argument (after <yres> and before
<bpp> and <refresh>, if specified) the timings will be calculated using
VESA(TM) Coordinated Video Timings instead of looking up the mode from a table.
If 'R' is specified, do a 'reduced blanking' calculation for digital displays.
If 'i' is specified, calculate for an interlaced mode.  And if 'm' is
specified, add margins to the calculation (1.8% of xres rounded down to 8
pixels and 1.8% of yres).

       Sample usage: 1024x768M@60m - CVT timing with margins

DRM drivers also add options to enable or disable outputs:

'e' will force the display to be enabled, i.e. it will override the detection
if a display is connected. 'D' will force the display to be enabled and use
digital output. This is useful for outputs that have both analog and digital
signals (e.g. HDMI and DVI-I). For other outputs it behaves like 'e'. If 'd'
is specified the output is disabled.

You can additionally specify which output the options matches to.
To force the VGA output to be enabled and drive a specific mode say::

    video=VGA-1:1280x1024@60me

Specifying the option multiple times for different ports is possible, e.g.::

    video=LVDS-1:d video=HDMI-1:D

Options can also be passed after the mode, using commas as separator.

       Sample usage: 720x480,rotate=180 - 720x480 mode, rotated by 180 degrees

Valid options are::

  - margin_top, margin_bottom, margin_left, margin_right (integer):
    Number of pixels in the margins, typically to deal with overscan on TVs
  - reflect_x (boolean): Perform an axial symmetry on the X axis
  - reflect_y (boolean): Perform an axial symmetry on the Y axis
  - rotate (integer): Rotate the initial framebuffer by x
    degrees. Valid values are 0, 90, 180 and 270.
  - panel_orientation, one of "normal", "upside_down", "left_side_up", or
    "right_side_up". For KMS drivers only, this sets the "panel orientation"
    property on the kms connector as hint for kms users.

-----------------------------------------------------------------------------

What is the VESA(TM) Coordinated Video Timings (CVT)?
=====================================================

From the VESA(TM) Website:

     "The purpose of CVT is to provide a method for generating a consistent
      and coordinated set of standard formats, display refresh rates, and
      timing specifications for computer display products, both those
      employing CRTs, and those using other display technologies. The
      intention of CVT is to give both source and display manufacturers a
      common set of tools to enable new timings to be developed in a
      consistent manner that ensures greater compatibility."

This is the third standard approved by VESA(TM) concerning video timings.  The
first was the Discrete Video Timings (DVT) which is  a collection of
pre-defined modes approved by VESA(TM).  The second is the Generalized Timing
Formula (GTF) which is an algorithm to calculate the timings, given the
pixelclock, the horizontal sync frequency, or the vertical refresh rate.

The GTF is limited by the fact that it is designed mainly for CRT displays.
It artificially increases the pixelclock because of its high blanking
requirement. This is inappropriate for digital display interface with its high
data rate which requires that it conserves the pixelclock as much as possible.
Also, GTF does not take into account the aspect ratio of the display.

The CVT addresses these limitations.  If used with CRT's, the formula used
is a derivation of GTF with a few modifications.  If used with digital
displays, the "reduced blanking" calculation can be used.

From the framebuffer subsystem perspective, new formats need not be added
to the global mode database whenever a new mode is released by display
manufacturers. Specifying for CVT will work for most, if not all, relatively
new CRT displays and probably with most flatpanels, if 'reduced blanking'
calculation is specified.  (The CVT compatibility of the display can be
determined from its EDID. The version 1.3 of the EDID has extra 128-byte
blocks where additional timing information is placed.  As of this time, there
is no support yet in the layer to parse this additional blocks.)

CVT also introduced a new naming convention (should be seen from dmesg output)::

    <pix>M<a>[-R]

    where: pix = total amount of pixels in MB (xres x yres)
	   M   = always present
	   a   = aspect ratio (3 - 4:3; 4 - 5:4; 9 - 15:9, 16:9; A - 16:10)
	  -R   = reduced blanking

	  example:  .48M3-R - 800x600 with reduced blanking

Note: VESA(TM) has restrictions on what is a standard CVT timing:

      - aspect ratio can only be one of the above values
      - acceptable refresh rates are 50, 60, 70 or 85 Hz only
      - if reduced blanking, the refresh rate must be at 60Hz

If one of the above are not satisfied, the kernel will print a warning but the
timings will still be calculated.

-----------------------------------------------------------------------------

To find a suitable video mode, you just call::

  int __init fb_find_mode(struct fb_var_screeninfo *var,
			  struct fb_info *info, const char *mode_option,
			  const struct fb_videomode *db, unsigned int dbsize,
			  const struct fb_videomode *default_mode,
			  unsigned int default_bpp)

with db/dbsize your non-standard video mode database, or NULL to use the
standard video mode database.

fb_find_mode() first tries the specified video mode (or any mode that matches,
e.g. there can be multiple 640x480 modes, each of them is tried). If that
fails, the default mode is tried. If that fails, it walks over all modes.

To specify a video mode at bootup, use the following boot options::

    video=<driver>:<xres>x<yres>[-<bpp>][@refresh]

where <driver> is a name from the table below.  Valid default modes can be
found in drivers/video/fbdev/core/modedb.c.  Check your driver's documentation.
There may be more modes::

    Drivers that support modedb boot options
    Boot Name	  Cards Supported

    amifb	- Amiga chipset frame buffer
    aty128fb	- ATI Rage128 / Pro frame buffer
    atyfb	- ATI Mach64 frame buffer
    pm2fb	- Permedia 2/2V frame buffer
    pm3fb	- Permedia 3 frame buffer
    sstfb	- Voodoo 1/2 (SST1) chipset frame buffer
    tdfxfb	- 3D Fx frame buffer
    tridentfb	- Trident (Cyber)blade chipset frame buffer
    vt8623fb	- VIA 8623 frame buffer

BTW, only a few fb drivers use this at the moment. Others are to follow
(feel free to send patches). The DRM drivers also support this.


code:
===============
What is pvr2fb?
===============

This is a driver for PowerVR 2 based graphics frame buffers, such as the
one found in the Dreamcast.

Advantages:

 * It provides a nice large console (128 cols + 48 lines with 1024x768)
   without using tiny, unreadable fonts (NOT on the Dreamcast)
 * You can run XF86_FBDev on top of /dev/fb0
 * Most important: boot logo :-)

Disadvantages:

 * Driver is largely untested on non-Dreamcast systems.

Configuration
=============

You can pass kernel command line options to pvr2fb with
`video=pvr2fb:option1,option2:value2,option3` (multiple options should be
separated by comma, values are separated from options by `:`).

Accepted options:

==========  ==================================================================
font:X      default font to use. All fonts are supported, including the
	    SUN12x22 font which is very nice at high resolutions.

mode:X      default video mode with format [xres]x[yres]-<bpp>@<refresh rate>
	    The following video modes are supported:
	    640x640-16@60, 640x480-24@60, 640x480-32@60. The Dreamcast
	    defaults to 640x480-16@60. At the time of writing the
	    24bpp and 32bpp modes function poorly. Work to fix that is
	    ongoing

	    Note: the 640x240 mode is currently broken, and should not be
	    used for any reason. It is only mentioned here as a reference.

inverse     invert colors on screen (for LCD displays)

nomtrr      disables write combining on frame buffer. This slows down driver
	    but there is reported minor incompatibility between GUS DMA and
	    XFree under high loads if write combining is enabled (sound
	    dropouts). MTRR is enabled by default on systems that have it
	    configured and that support it.

cable:X     cable type. This can be any of the following: vga, rgb, and
	    composite. If none is specified, we guess.

output:X    output type. This can be any of the following: pal, ntsc, and
	    vga. If none is specified, we guess.
==========  ==================================================================

X11
===

XF86_FBDev has been shown to work on the Dreamcast in the past - though not yet
on any 2.6 series kernel.

Paul Mundt <lethal@linuxdc.org>

Updated by Adrian McMenamin <adrian@mcmen.demon.co.uk>


code:
================================
Driver for PXA25x LCD controller
================================

The driver supports the following options, either via
options=<OPTIONS> when modular or video=pxafb:<OPTIONS> when built in.

For example::

	modprobe pxafb options=vmem:2M,mode:640x480-8,passive

or on the kernel command line::

	video=pxafb:vmem:2M,mode:640x480-8,passive

vmem: VIDEO_MEM_SIZE

	Amount of video memory to allocate (can be suffixed with K or M
	for kilobytes or megabytes)

mode:XRESxYRES[-BPP]

	XRES == LCCR1_PPL + 1

	YRES == LLCR2_LPP + 1

		The resolution of the display in pixels

	BPP == The bit depth. Valid values are 1, 2, 4, 8 and 16.

pixclock:PIXCLOCK

	Pixel clock in picoseconds

left:LEFT == LCCR1_BLW + 1

right:RIGHT == LCCR1_ELW + 1

hsynclen:HSYNC == LCCR1_HSW + 1

upper:UPPER == LCCR2_BFW

lower:LOWER == LCCR2_EFR

vsynclen:VSYNC == LCCR2_VSW + 1

	Display margins and sync times

color | mono => LCCR0_CMS

	umm...

active | passive => LCCR0_PAS

	Active (TFT) or Passive (STN) display

single | dual => LCCR0_SDS

	Single or dual panel passive display

4pix | 8pix => LCCR0_DPD

	4 or 8 pixel monochrome single panel data

hsync:HSYNC, vsync:VSYNC

	Horizontal and vertical sync. 0 => active low, 1 => active
	high.

dpc:DPC

	Double pixel clock. 1=>true, 0=>false

outputen:POLARITY

	Output Enable Polarity. 0 => active low, 1 => active high

pixclockpol:POLARITY

	pixel clock polarity
	0 => falling edge, 1 => rising edge

Overlay Support for PXA27x and later LCD controllers
====================================================

  PXA27x and later processors support overlay1 and overlay2 on-top of the
  base framebuffer (although under-neath the base is also possible). They
  support palette and no-palette RGB formats, as well as YUV formats (only
  available on overlay2). These overlays have dedicated DMA channels and
  behave in a similar way as a framebuffer.

  However, there are some differences between these overlay framebuffers
  and normal framebuffers, as listed below:

  1. overlay can start at a 32-bit word aligned position within the base
     framebuffer, which means they have a start (x, y). This information
     is encoded into var->nonstd (no, var->xoffset and var->yoffset are
     not for such purpose).

  2. overlay framebuffer is allocated dynamically according to specified
     'struct fb_var_screeninfo', the amount is decided by::

	var->xres_virtual * var->yres_virtual * bpp

     bpp = 16 -- for RGB565 or RGBT555

     bpp = 24 -- for YUV444 packed

     bpp = 24 -- for YUV444 planar

     bpp = 16 -- for YUV422 planar (1 pixel = 1 Y + 1/2 Cb + 1/2 Cr)

     bpp = 12 -- for YUV420 planar (1 pixel = 1 Y + 1/4 Cb + 1/4 Cr)

     NOTE:

     a. overlay does not support panning in x-direction, thus
	var->xres_virtual will always be equal to var->xres

     b. line length of overlay(s) must be on a 32-bit word boundary,
	for YUV planar modes, it is a requirement for the component
	with minimum bits per pixel,  e.g. for YUV420, Cr component
	for one pixel is actually 2-bits, it means the line length
	should be a multiple of 16-pixels

     c. starting horizontal position (XPOS) should start on a 32-bit
	word boundary, otherwise the fb_check_var() will just fail.

     d. the rectangle of the overlay should be within the base plane,
	otherwise fail

     Applications should follow the sequence below to operate an overlay
     framebuffer:

	 a. open("/dev/fb[1-2]", ...)
	 b. ioctl(fd, FBIOGET_VSCREENINFO, ...)
	 c. modify 'var' with desired parameters:

	    1) var->xres and var->yres
	    2) larger var->yres_virtual if more memory is required,
	       usually for double-buffering
	    3) var->nonstd for starting (x, y) and color format
	    4) var->{red, green, blue, transp} if RGB mode is to be used

	 d. ioctl(fd, FBIOPUT_VSCREENINFO, ...)
	 e. ioctl(fd, FBIOGET_FSCREENINFO, ...)
	 f. mmap
	 g. ...

  3. for YUV planar formats, these are actually not supported within the
     framebuffer framework, application has to take care of the offsets
     and lengths of each component within the framebuffer.

  4. var->nonstd is used to pass starting (x, y) position and color format,
     the detailed bit fields are shown below::

      31                23  20         10          0
       +-----------------+---+----------+----------+
       |  ... unused ... |FOR|   XPOS   |   YPOS   |
       +-----------------+---+----------+----------+

     FOR  - color format, as defined by OVERLAY_FORMAT_* in pxafb.h

	  - 0 - RGB
	  - 1 - YUV444 PACKED
	  - 2 - YUV444 PLANAR
	  - 3 - YUV422 PLANAR
	  - 4 - YUR420 PLANAR

     XPOS - starting horizontal position

     YPOS - starting vertical position


code:
===========================================
s3fb - fbdev driver for S3 Trio/Virge chips
===========================================

Supported Hardware
==================

	S3 Trio32
	S3 Trio64 (and variants V+, UV+, V2/DX, V2/GX)
	S3 Virge  (and variants VX, DX, GX and GX2+)
	S3 Plato/PX		(completely untested)
	S3 Aurora64V+		(completely untested)

	- only PCI bus supported
	- only BIOS initialized VGA devices supported
	- probably not working on big endian

I tested s3fb on Trio64 (plain, V+ and V2/DX) and Virge (plain, VX, DX),
all on i386.

Supported Features
==================

	*  4 bpp pseudocolor modes (with 18bit palette, two variants)
	*  8 bpp pseudocolor mode (with 18bit palette)
	* 16 bpp truecolor modes (RGB 555 and RGB 565)
	* 24 bpp truecolor mode (RGB 888) on (only on Virge VX)
	* 32 bpp truecolor mode (RGB 888) on (not on Virge VX)
	* text mode (activated by bpp = 0)
	* interlaced mode variant (not available in text mode)
	* doublescan mode variant (not available in text mode)
	* panning in both directions
	* suspend/resume support
	* DPMS support

Text mode is supported even in higher resolutions, but there is limitation to
lower pixclocks (maximum usually between 50-60 MHz, depending on specific
hardware, i get best results from plain S3 Trio32 card - about 75 MHz). This
limitation is not enforced by driver. Text mode supports 8bit wide fonts only
(hardware limitation) and 16bit tall fonts (driver limitation). Text mode
support is broken on S3 Trio64 V2/DX.

There are two 4 bpp modes. First mode (selected if nonstd == 0) is mode with
packed pixels, high nibble first. Second mode (selected if nonstd == 1) is mode
with interleaved planes (1 byte interleave), MSB first. Both modes support
8bit wide fonts only (driver limitation).

Suspend/resume works on systems that initialize video card during resume and
if device is active (for example used by fbcon).

Missing Features
================
(alias TODO list)

	* secondary (not initialized by BIOS) device support
	* big endian support
	* Zorro bus support
	* MMIO support
	* 24 bpp mode support on more cards
	* support for fontwidths != 8 in 4 bpp modes
	* support for fontheight != 16 in text mode
	* composite and external sync (is anyone able to test this?)
	* hardware cursor
	* video overlay support
	* vsync synchronization
	* feature connector support
	* acceleration support (8514-like 2D, Virge 3D, busmaster transfers)
	* better values for some magic registers (performance issues)

Known bugs
==========

	* cursor disable in text mode doesn't work
	* text mode broken on S3 Trio64 V2/DX

--
Ondrej Zajicek <santiago@crfreenet.org>


code:
=================
What is sa1100fb?
=================

.. [This file is cloned from VesaFB/matroxfb]

This is a driver for a graphic framebuffer for the SA-1100 LCD
controller.

Configuration
==============

For most common passive displays, giving the option::

  video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value>

on the kernel command line should be enough to configure the
controller. The bits per pixel (bpp) value should be 4, 8, 12, or
16. LCCR values are display-specific and should be computed as
documented in the SA-1100 Developer's Manual, Section 11.7. Dual-panel
displays are supported as long as the SDS bit is set in LCCR0; GPIO<9:2>
are used for the lower panel.

For active displays or displays requiring additional configuration
(controlling backlights, powering on the LCD, etc.), the command line
options may not be enough to configure the display. Adding sections to
sa1100fb_init_fbinfo(), sa1100fb_activate_var(),
sa1100fb_disable_lcd_controller(), and sa1100fb_enable_lcd_controller()
will probably be necessary.

Accepted options::

	bpp:<value>	Configure for <value> bits per pixel
	lccr0:<value>	Configure LCD control register 0 (11.7.3)
	lccr1:<value>	Configure LCD control register 1 (11.7.4)
	lccr2:<value>	Configure LCD control register 2 (11.7.5)
	lccr3:<value>	Configure LCD control register 3 (11.7.6)

Mark Huang <mhuang@livetoy.com>


code:
================================================
SH7760/SH7763 integrated LCDC Framebuffer driver
================================================

0. Overview
-----------
The SH7760/SH7763 have an integrated LCD Display controller (LCDC) which
supports (in theory) resolutions ranging from 1x1 to 1024x1024,
with color depths ranging from 1 to 16 bits, on STN, DSTN and TFT Panels.

Caveats:

* Framebuffer memory must be a large chunk allocated at the top
  of Area3 (HW requirement). Because of this requirement you should NOT
  make the driver a module since at runtime it may become impossible to
  get a large enough contiguous chunk of memory.

* The driver does not support changing resolution while loaded
  (displays aren't hotpluggable anyway)

* Heavy flickering may be observed
  a) if you're using 15/16bit color modes at >= 640x480 px resolutions,
  b) during PCMCIA (or any other slow bus) activity.

* Rotation works only 90degress clockwise, and only if horizontal
  resolution is <= 320 pixels.

Files:
	- drivers/video/sh7760fb.c
	- include/asm-sh/sh7760fb.h
	- Documentation/fb/sh7760fb.rst

1. Platform setup
-----------------
SH7760:
 Video data is fetched via the DMABRG DMA engine, so you have to
 configure the SH DMAC for DMABRG mode (write 0x94808080 to the
 DMARSRA register somewhere at boot).

 PFC registers PCCR and PCDR must be set to peripheral mode.
 (write zeros to both).

The driver does NOT do the above for you since board setup is, well, job
of the board setup code.

2. Panel definitions
--------------------
The LCDC must explicitly be told about the type of LCD panel
attached.  Data must be wrapped in a "struct sh7760fb_platdata" and
passed to the driver as platform_data.

Suggest you take a closer look at the SH7760 Manual, Section 30.
(http://documentation.renesas.com/eng/products/mpumcu/e602291_sh7760.pdf)

The following code illustrates what needs to be done to
get the framebuffer working on a 640x480 TFT::

  #include <linux/fb.h>
  #include <asm/sh7760fb.h>

  /*
   * NEC NL6440bc26-01 640x480 TFT
   * dotclock 25175 kHz
   * Xres                640     Yres            480
   * Htotal      800     Vtotal          525
   * HsynStart   656     VsynStart       490
   * HsynLenn    30      VsynLenn        2
   *
   * The linux framebuffer layer does not use the syncstart/synclen
   * values but right/left/upper/lower margin values. The comments
   * for the x_margin explain how to calculate those from given
   * panel sync timings.
   */
  static struct fb_videomode nl6448bc26 = {
         .name           = "NL6448BC26",
         .refresh        = 60,
         .xres           = 640,
         .yres           = 480,
         .pixclock       = 39683,        /* in picoseconds! */
         .hsync_len      = 30,
         .vsync_len      = 2,
         .left_margin    = 114,  /* HTOT - (HSYNSLEN + HSYNSTART) */
         .right_margin   = 16,   /* HSYNSTART - XRES */
         .upper_margin   = 33,   /* VTOT - (VSYNLEN + VSYNSTART) */
         .lower_margin   = 10,   /* VSYNSTART - YRES */
         .sync           = FB_SYNC_HOR_HIGH_ACT | FB_SYNC_VERT_HIGH_ACT,
         .vmode          = FB_VMODE_NONINTERLACED,
         .flag           = 0,
  };

  static struct sh7760fb_platdata sh7760fb_nl6448 = {
         .def_mode       = &nl6448bc26,
         .ldmtr          = LDMTR_TFT_COLOR_16,   /* 16bit TFT panel */
         .lddfr          = LDDFR_8BPP,           /* we want 8bit output */
         .ldpmmr         = 0x0070,
         .ldpspr         = 0x0500,
         .ldaclnr        = 0,
         .ldickr         = LDICKR_CLKSRC(LCDC_CLKSRC_EXTERNAL) |
			 LDICKR_CLKDIV(1),
         .rotate         = 0,
         .novsync        = 1,
         .blank          = NULL,
  };

  /* SH7760:
   * 0xFE300800: 256 * 4byte xRGB palette ram
   * 0xFE300C00: 42 bytes ctrl registers
   */
  static struct resource sh7760_lcdc_res[] = {
         [0] = {
	       .start  = 0xFE300800,
	       .end    = 0xFE300CFF,
	       .flags  = IORESOURCE_MEM,
         },
         [1] = {
	       .start  = 65,
	       .end    = 65,
	       .flags  = IORESOURCE_IRQ,
         },
  };

  static struct platform_device sh7760_lcdc_dev = {
         .dev    = {
	       .platform_data = &sh7760fb_nl6448,
         },
         .name           = "sh7760-lcdc",
         .id             = -1,
         .resource       = sh7760_lcdc_res,
         .num_resources  = ARRAY_SIZE(sh7760_lcdc_res),
  };


code:
==============
What is sisfb?
==============

sisfb is a framebuffer device driver for SiS (Silicon Integrated Systems)
graphics chips. Supported are:

- SiS 300 series: SiS 300/305, 540, 630(S), 730(S)
- SiS 315 series: SiS 315/H/PRO, 55x, (M)65x, 740, (M)661(F/M)X, (M)741(GX)
- SiS 330 series: SiS 330 ("Xabre"), (M)760

Why do I need a framebuffer driver?
===================================

sisfb is eg. useful if you want a high-resolution text console. Besides that,
sisfb is required to run DirectFB (which comes with an additional, dedicated
driver for the 315 series).

On the 300 series, sisfb on kernels older than 2.6.3 furthermore plays an
important role in connection with DRM/DRI: Sisfb manages the memory heap
used by DRM/DRI for 3D texture and other data. This memory management is
required for using DRI/DRM.

Kernels >= around 2.6.3 do not need sisfb any longer for DRI/DRM memory
management. The SiS DRM driver has been updated and features a memory manager
of its own (which will be used if sisfb is not compiled). So unless you want
a graphical console, you don't need sisfb on kernels >=2.6.3.

Sidenote: Since this seems to be a commonly made mistake: sisfb and vesafb
cannot be active at the same time! Do only select one of them in your kernel
configuration.

How are parameters passed to sisfb?
===================================

Well, it depends: If compiled statically into the kernel, use lilo's append
statement to add the parameters to the kernel command line. Please see lilo's
(or GRUB's) documentation for more information. If sisfb is a kernel module,
parameters are given with the modprobe (or insmod) command.

Example for sisfb as part of the static kernel: Add the following line to your
lilo.conf::

     append="video=sisfb:mode:1024x768x16,mem:12288,rate:75"

Example for sisfb as a module: Start sisfb by typing::

     modprobe sisfb mode=1024x768x16 rate=75 mem=12288

A common mistake is that folks use a wrong parameter format when using the
driver compiled into the kernel. Please note: If compiled into the kernel,
the parameter format is video=sisfb:mode:none or video=sisfb:mode:1024x768x16
(or whatever mode you want to use, alternatively using any other format
described above or the vesa keyword instead of mode). If compiled as a module,
the parameter format reads mode=none or mode=1024x768x16 (or whatever mode you
want to use). Using a "=" for a ":" (and vice versa) is a huge difference!
Additionally: If you give more than one argument to the in-kernel sisfb, the
arguments are separated with ",". For example::

   video=sisfb:mode:1024x768x16,rate:75,mem:12288

How do I use it?
================

Preface statement: This file only covers very little of the driver's
capabilities and features. Please refer to the author's and maintainer's
website at http://www.winischhofer.net/linuxsisvga.shtml for more
information. Additionally, "modinfo sisfb" gives an overview over all
supported options including some explanation.

The desired display mode can be specified using the keyword "mode" with
a parameter in one of the following formats:

  - XxYxDepth or
  - XxY-Depth or
  - XxY-Depth@Rate or
  - XxY
  - or simply use the VESA mode number in hexadecimal or decimal.

For example: 1024x768x16, 1024x768-16@75, 1280x1024-16. If no depth is
specified, it defaults to 8. If no rate is given, it defaults to 60Hz. Depth 32
means 24bit color depth (but 32 bit framebuffer depth, which is not relevant
to the user).

Additionally, sisfb understands the keyword "vesa" followed by a VESA mode
number in decimal or hexadecimal. For example: vesa=791 or vesa=0x117. Please
use either "mode" or "vesa" but not both.

Linux 2.4 only: If no mode is given, sisfb defaults to "no mode" (mode=none) if
compiled as a module; if sisfb is statically compiled into the kernel, it
defaults to 800x600x8 unless CRT2 type is LCD, in which case the LCD's native
resolution is used. If you want to switch to a different mode, use the fbset
shell command.

Linux 2.6 only: If no mode is given, sisfb defaults to 800x600x8 unless CRT2
type is LCD, in which case it defaults to the LCD's native resolution. If
you want to switch to another mode, use the stty shell command.

You should compile in both vgacon (to boot if you remove you SiS card from
your system) and sisfb (for graphics mode). Under Linux 2.6, also "Framebuffer
console support" (fbcon) is needed for a graphical console.

You should *not* compile-in vesafb. And please do not use the "vga=" keyword
in lilo's or grub's configuration file; mode selection is done using the
"mode" or "vesa" keywords as a parameter. See above and below.

X11
===

If using XFree86 or X.org, it is recommended that you don't use the "fbdev"
driver but the dedicated "sis" X driver. The "sis" X driver and sisfb are
developed by the same person (Thomas Winischhofer) and cooperate well with
each other.

SVGALib
=======

SVGALib, if directly accessing the hardware, never restores the screen
correctly, especially on laptops or if the output devices are LCD or TV.
Therefore, use the chipset "FBDEV" in SVGALib configuration. This will make
SVGALib use the framebuffer device for mode switches and restoration.

Configuration
=============

(Some) accepted options:

=========  ==================================================================
off        Disable sisfb. This option is only understood if sisfb is
	   in-kernel, not a module.
mem:X      size of memory for the console, rest will be used for DRI/DRM. X
	   is in kilobytes. On 300 series, the default is 4096, 8192 or
	   16384 (each in kilobyte) depending on how much video ram the card
	   has. On 315/330 series, the default is the maximum available ram
	   (since DRI/DRM is not supported for these chipsets).
noaccel    do not use 2D acceleration engine. (Default: use acceleration)
noypan     disable y-panning and scroll by redrawing the entire screen.
	   This is much slower than y-panning. (Default: use y-panning)
vesa:X     selects startup videomode. X is number from 0 to 0x1FF and
	   represents the VESA mode number (can be given in decimal or
	   hexadecimal form, the latter prefixed with "0x").
mode:X     selects startup videomode. Please see above for the format of
	   "X".
=========  ==================================================================

Boolean options such as "noaccel" or "noypan" are to be given without a
parameter if sisfb is in-kernel (for example "video=sisfb:noypan). If
sisfb is a module, these are to be set to 1 (for example "modprobe sisfb
noypan=1").

Thomas Winischhofer <thomas@winischhofer.net>

May 27, 2004


code:
=======
sm501fb
=======

Configuration:

You can pass the following kernel command line options to sm501
videoframebuffer::

	sm501fb.bpp=	SM501 Display driver:
			Specify bits-per-pixel if not specified by 'mode'

	sm501fb.mode=	SM501 Display driver:
			Specify resolution as
			"<xres>x<yres>[-<bpp>][@<refresh>]"


code:
================
What is sm712fb?
================

This is a graphics framebuffer driver for Silicon Motion SM712 based processors.

How to use it?
==============

Switching modes is done using the video=sm712fb:... boot parameter.

If you want, for example, enable a resolution of 1280x1024x24bpp you should
pass to the kernel this command line: "video=sm712fb:0x31B".

You should not compile-in vesafb.

Currently supported video modes are:

Graphic modes
-------------

===  =======  =======  ========  =========
bpp  640x480  800x600  1024x768  1280x1024
===  =======  =======  ========  =========
  8  0x301    0x303    0x305     0x307
 16  0x311    0x314    0x317     0x31A
 24  0x312    0x315    0x318     0x31B
===  =======  =======  ========  =========

Missing Features
================
(alias TODO list)

	* 2D acceleratrion
	* dual-head support


code:
=====
sstfb
=====

Introduction
============

This is a frame buffer device driver for 3dfx' Voodoo Graphics
(aka voodoo 1, aka sst1) and Voodoo² (aka Voodoo 2, aka CVG) based
video boards. It's highly experimental code, but is guaranteed to work
on my computer, with my "Maxi Gamer 3D" and "Maxi Gamer 3d²" boards,
and with me "between chair and keyboard". Some people tested other
combinations and it seems that it works.
The main page is located at <http://sstfb.sourceforge.net>, and if
you want the latest version, check out the CVS, as the driver is a work
in progress, I feel uncomfortable with releasing tarballs of something
not completely working...Don't worry, it's still more than usable
(I eat my own dog food)

Please read the Bug section, and report any success or failure to me
(Ghozlane Toumi <gtoumi@laposte.net>).
BTW, If you have only one monitor , and you don't feel like playing
with the vga passthrou cable, I can only suggest borrowing a screen
somewhere...

Installation
============

This driver (should) work on ix86, with "late" 2.2.x kernel (tested
with x = 19) and "recent" 2.4.x kernel, as a module or compiled in.
It has been included in mainstream kernel since the infamous 2.4.10.
You can apply the patches found in `sstfb/kernel/*-2.{2|4}.x.patch`,
and copy sstfb.c to linux/drivers/video/, or apply a single patch,
`sstfb/patch-2.{2|4}.x-sstfb-yymmdd` to your linux source tree.

Then configure your kernel as usual: choose "m" or "y" to 3Dfx Voodoo
Graphics in section "console". Compile, install, have fun... and please
drop me a report :)

Module Usage
============

.. warning::

       #. You should read completely this section before issuing any command.

       #. If you have only one monitor to play with, once you insmod the
	  module, the 3dfx takes control of the output, so you'll have to
	  plug the monitor to the "normal" video board in order to issue
	  the commands, or you can blindly use sst_dbg_vgapass
	  in the tools directory (See Tools). The latest solution is pass the
	  parameter vgapass=1 when insmodding the driver. (See Kernel/Modules
	  Options)

Module insertion
----------------

       #. insmod sstfb.o

	  you should see some strange output from the board:
	  a big blue square, a green and a red small squares and a vertical
	  white rectangle. why? the function's name is self-explanatory:
	  "sstfb_test()"...
	  (if you don't have a second monitor, you'll have to plug your monitor
	  directly to the 2D videocard to see what you're typing)

       #. con2fb /dev/fbx /dev/ttyx

	  bind a tty to the new frame buffer. if you already have a frame
	  buffer driver, the voodoo fb will likely be /dev/fb1. if not,
	  the device will be /dev/fb0. You can check this by doing a
	  cat /proc/fb. You can find a copy of con2fb in tools/ directory.
	  if you don't have another fb device, this step is superfluous,
	  as the console subsystem automagicaly binds ttys to the fb.
       #. switch to the virtual console you just mapped. "tadaaa" ...

Module removal
--------------

       #. con2fb /dev/fbx /dev/ttyx

	  bind the tty to the old frame buffer so the module can be removed.
	  (how does it work with vgacon ? short answer : it doesn't work)

       #. rmmod sstfb

Kernel/Modules Options
----------------------

You can pass some options to the sstfb module, and via the kernel
command line when the driver is compiled in:
for module : insmod sstfb.o option1=value1 option2=value2 ...
in kernel :  video=sstfb:option1,option2:value2,option3 ...

sstfb supports the following options:

=============== =============== ===============================================
Module		Kernel		Description
=============== =============== ===============================================
vgapass=0	vganopass	Enable or disable VGA passthrou cable.
vgapass=1	vgapass		When enabled, the monitor will get the signal
				from the VGA board and not from the voodoo.

				Default: nopass

mem=x		mem:x		Force frame buffer memory in MiB
				allowed values: 0, 1, 2, 4.

				Default: 0 (= autodetect)

inverse=1	inverse		Supposed to enable inverse console.
				doesn't work yet...

clipping=1	clipping	Enable or disable clipping.
clipping=0	noclipping	With clipping enabled, all offscreen
				reads and writes are discarded.

				Default: enable clipping.

gfxclk=x	gfxclk:x	Force graphic clock frequency (in MHz).
				Be careful with this option, it may be
				DANGEROUS.

				Default: auto

					- 50Mhz for Voodoo 1,
					- 75MHz for Voodoo 2.

slowpci=1	fastpci		Enable or disable fast PCI read/writes.
slowpci=1	slowpci		Default : fastpci

dev=x		dev:x		Attach the driver to device number x.
				0 is the first compatible board (in
				lspci order)
=============== =============== ===============================================

Tools
=====

These tools are mostly for debugging purposes, but you can
find some of these interesting:

- `con2fb`, maps a tty to a fbramebuffer::

	con2fb /dev/fb1 /dev/tty5

- `sst_dbg_vgapass`, changes vga passthrou. You have to recompile the
  driver with SST_DEBUG and SST_DEBUG_IOCTL set to 1::

	sst_dbg_vgapass /dev/fb1 1 (enables vga cable)
	sst_dbg_vgapass /dev/fb1 0 (disables vga cable)

- `glide_reset`, resets the voodoo using glide
  use this after rmmoding sstfb, if the module refuses to
  reinsert.

Bugs
====

- DO NOT use glide while the sstfb module is in, you'll most likely
  hang your computer.
- If you see some artefacts (pixels not cleaning and stuff like that),
  try turning off clipping (clipping=0), and/or using slowpci
- the driver don't detect the 4Mb frame buffer voodoos, it seems that
  the 2 last Mbs wrap around. looking into that .
- The driver is 16 bpp only, 24/32 won't work.
- The driver is not your_favorite_toy-safe. this includes SMP...

	[Actually from inspection it seems to be safe - Alan]

- When using XFree86 FBdev (X over fbdev) you may see strange color
  patterns at the border of your windows (the pixels lose the lowest
  byte -> basically the blue component and some of the green). I'm unable
  to reproduce this with XFree86-3.3, but one of the testers has this
  problem with XFree86-4. Apparently recent Xfree86-4.x solve this
  problem.
- I didn't really test changing the palette, so you may find some weird
  things when playing with that.
- Sometimes the driver will not recognise the DAC, and the
  initialisation will fail. This is specifically true for
  voodoo 2 boards, but it should be solved in recent versions. Please
  contact me.
- The 24/32 is not likely to work anytime soon, knowing that the
  hardware does ... unusual things in 24/32 bpp.

Todo
====

- Get rid of the previous paragraph.
- Buy more coffee.
- test/port to other arch.
- try to add panning using tweeks with front and back buffer .
- try to implement accel on voodoo2, this board can actually do a
  lot in 2D even if it was sold as a 3D only board ...

Ghozlane Toumi <gtoumi@laposte.net>

Date: 2002/05/09 20:11:45

http://sstfb.sourceforge.net/README


code:
==============
What is tgafb?
==============

This is a driver for DECChip 21030 based graphics framebuffers, a.k.a. TGA
cards, which are usually found in older Digital Alpha systems. The
following models are supported:

- ZLxP-E1 (8bpp, 2 MB VRAM)
- ZLxP-E2 (32bpp, 8 MB VRAM)
- ZLxP-E3 (32bpp, 16 MB VRAM, Zbuffer)

This version is an almost complete rewrite of the code written by Geert
Uytterhoeven, which was based on the original TGA console code written by
Jay Estabrook.

Major new features since Linux 2.0.x:

 * Support for multiple resolutions
 * Support for fixed-frequency and other oddball monitors
   (by allowing the video mode to be set at boot time)

User-visible changes since Linux 2.2.x:

 * Sync-on-green is now handled properly
 * More useful information is printed on bootup
   (this helps if people run into problems)

This driver does not (yet) support the TGA2 family of framebuffers, so the
PowerStorm 3D30/4D20 (also known as PBXGB) cards are not supported. These
can however be used with the standard VGA Text Console driver.

Configuration
=============

You can pass kernel command line options to tgafb with
`video=tgafb:option1,option2:value2,option3` (multiple options should be
separated by comma, values are separated from options by `:`).

Accepted options:

==========  ============================================================
font:X      default font to use. All fonts are supported, including the
	    SUN12x22 font which is very nice at high resolutions.

mode:X      default video mode. The following video modes are supported:
	    640x480-60, 800x600-56, 640x480-72, 800x600-60, 800x600-72,
	    1024x768-60, 1152x864-60, 1024x768-70, 1024x768-76,
	    1152x864-70, 1280x1024-61, 1024x768-85, 1280x1024-70,
	    1152x864-84, 1280x1024-76, 1280x1024-85
==========  ============================================================

Known Issues
============

The XFree86 FBDev server has been reported not to work, since tgafb doesn't do
mmap(). Running the standard XF86_TGA server from XFree86 3.3.x works fine for
me, however this server does not do acceleration, which make certain operations
quite slow. Support for acceleration is being progressively integrated in
XFree86 4.x.

When running tgafb in resolutions higher than 640x480, on switching VCs from
tgafb to XF86_TGA 3.3.x, the entire screen is not re-drawn and must be manually
refreshed. This is an X server problem, not a tgafb problem, and is fixed in
XFree86 4.0.

Enjoy!

Martin Lucina <mato@kotelna.sk>


code:
=========
Tridentfb
=========

Tridentfb is a framebuffer driver for some Trident chip based cards.

The following list of chips is thought to be supported although not all are
tested:

those from the TGUI series 9440/96XX and with Cyber in their names
those from the Image series and with Cyber in their names
those with Blade in their names (Blade3D,CyberBlade...)
the newer CyberBladeXP family

All families are accelerated. Only PCI/AGP based cards are supported,
none of the older Tridents.
The driver supports 8, 16 and 32 bits per pixel depths.
The TGUI family requires a line length to be power of 2 if acceleration
is enabled. This means that range of possible resolutions and bpp is
limited comparing to the range if acceleration is disabled (see list
of parameters below).

Known bugs:

1. The driver randomly locks up on 3DImage975 chip with acceleration
   enabled. The same happens in X11 (Xorg).
2. The ramdac speeds require some more fine tuning. It is possible to
   switch resolution which the chip does not support at some depths for
   older chips.

How to use it?
==============

When booting you can pass the video parameter::

	video=tridentfb

The parameters for tridentfb are concatenated with a ':' as in this example::

	video=tridentfb:800x600-16@75,noaccel

The second level parameters that tridentfb understands are:

========  =====================================================================
noaccel   turns off acceleration (when it doesn't work for your card)

fp	  use flat panel related stuff
crt 	  assume monitor is present instead of fp

center 	  for flat panels and resolutions smaller than native size center the
	  image, otherwise use
stretch

memsize   integer value in KB, use if your card's memory size is misdetected.
	  look at the driver output to see what it says when initializing.

memdiff   integer value in KB, should be nonzero if your card reports
	  more memory than it actually has. For instance mine is 192K less than
	  detection says in all three BIOS selectable situations 2M, 4M, 8M.
	  Only use if your video memory is taken from main memory hence of
	  configurable size. Otherwise use memsize.
	  If in some modes which barely fit the memory you see garbage
	  at the bottom this might help by not letting change to that mode
	  anymore.

nativex   the width in pixels of the flat panel.If you know it (usually 1024
	  800 or 1280) and it is not what the driver seems to detect use it.

bpp	  bits per pixel (8,16 or 32)
mode	  a mode name like 800x600-8@75 as described in
	  Documentation/fb/modedb.rst
========  =====================================================================

Using insane values for the above parameters will probably result in driver
misbehaviour so take care(for instance memsize=12345678 or memdiff=23784 or
nativex=93)

Contact: jani@astechnix.ro