diff options
Diffstat (limited to 'Documentation/fb')
| -rw-r--r-- | Documentation/fb/00-INDEX | 38 | ||||
| -rw-r--r-- | Documentation/fb/api.txt | 306 | ||||
| -rw-r--r-- | Documentation/fb/cirrusfb.txt | 2 | ||||
| -rw-r--r-- | Documentation/fb/fbcon.txt | 2 | ||||
| -rw-r--r-- | Documentation/fb/intel810.txt | 2 | ||||
| -rw-r--r-- | Documentation/fb/intelfb.txt | 2 | ||||
| -rw-r--r-- | Documentation/fb/matroxfb.txt | 8 | ||||
| -rw-r--r-- | Documentation/fb/modedb.txt | 21 | ||||
| -rw-r--r-- | Documentation/fb/sm501.txt | 10 | ||||
| -rw-r--r-- | Documentation/fb/sstfb.txt | 2 | ||||
| -rw-r--r-- | Documentation/fb/udlfb.txt | 159 | ||||
| -rw-r--r-- | Documentation/fb/uvesafb.txt | 16 | ||||
| -rw-r--r-- | Documentation/fb/viafb.modes | 2 | ||||
| -rw-r--r-- | Documentation/fb/viafb.txt | 6 |
14 files changed, 542 insertions, 34 deletions
diff --git a/Documentation/fb/00-INDEX b/Documentation/fb/00-INDEX index a618fd99c9f..fe85e7c5907 100644 --- a/Documentation/fb/00-INDEX +++ b/Documentation/fb/00-INDEX @@ -4,33 +4,43 @@ please mail me. Geert Uytterhoeven <geert@linux-m68k.org> 00-INDEX - - this file + - this file. +api.txt + - The frame buffer API between applications and buffer devices. arkfb.txt - info on the fbdev driver for ARK Logic chips. aty128fb.txt - info on the ATI Rage128 frame buffer driver. cirrusfb.txt - info on the driver for Cirrus Logic chipsets. +cmap_xfbdev.txt + - an introduction to fbdev's cmap structures. deferred_io.txt - an introduction to deferred IO. +efifb.txt + - info on the EFI platform driver for Intel based Apple computers. +ep93xx-fb.txt + - info on the driver for EP93xx LCD controller. fbcon.txt - intro to and usage guide for the framebuffer console (fbcon). framebuffer.txt - introduction to frame buffer devices. -imacfb.txt - - info on the generic EFI platform driver for Intel based Macs. +gxfb.txt + - info on the framebuffer driver for AMD Geode GX2 based processors. intel810.txt - documentation for the Intel 810/815 framebuffer driver. intelfb.txt - docs for Intel 830M/845G/852GM/855GM/865G/915G/945G fb driver. internals.txt - quick overview of frame buffer device internals. +lxfb.txt + - info on the framebuffer driver for AMD Geode LX based processors. matroxfb.txt - info on the Matrox framebuffer driver for Alpha, Intel and PPC. +metronomefb.txt + - info on the driver for the Metronome display controller. modedb.txt - info on the video mode database. -matroxfb.txt - - info on the Matrox frame buffer driver. pvr2fb.txt - info on the PowerVR 2 frame buffer driver. pxafb.txt @@ -39,13 +49,27 @@ s3fb.txt - info on the fbdev driver for S3 Trio/Virge chips. sa1100fb.txt - information about the driver for the SA-1100 LCD controller. +sh7760fb.txt + - info on the SH7760/SH7763 integrated LCDC Framebuffer driver. sisfb.txt - info on the framebuffer device driver for various SiS chips. +sm501.txt + - info on the framebuffer device driver for sm501 videoframebuffer. sstfb.txt - info on the frame buffer driver for 3dfx' Voodoo Graphics boards. tgafb.txt - - info on the TGA (DECChip 21030) frame buffer driver + - info on the TGA (DECChip 21030) frame buffer driver. +tridentfb.txt + info on the framebuffer driver for some Trident chip based cards. +udlfb.txt + - Driver for DisplayLink USB 2.0 chips. +uvesafb.txt + - info on the userspace VESA (VBE2+ compliant) frame buffer device. vesafb.txt - - info on the VESA frame buffer device + - info on the VESA frame buffer device. +viafb.modes + - list of modes for VIA Integration Graphic Chip. +viafb.txt + - info on the VIA Integration Graphic Chip console framebuffer driver. vt8623fb.txt - info on the fb driver for the graphics core in VIA VT8623 chipsets. diff --git a/Documentation/fb/api.txt b/Documentation/fb/api.txt new file mode 100644 index 00000000000..d4ff7de8570 --- /dev/null +++ b/Documentation/fb/api.txt @@ -0,0 +1,306 @@ + The Frame Buffer Device API + --------------------------- + +Last revised: June 21, 2011 + + +0. Introduction +--------------- + +This document describes the frame buffer API used by applications to interact +with frame buffer devices. In-kernel APIs between device drivers and the frame +buffer core are not described. + +Due to a lack of documentation in the original frame buffer API, drivers +behaviours differ in subtle (and not so subtle) ways. This document describes +the recommended API implementation, but applications should be prepared to +deal with different behaviours. + + +1. Capabilities +--------------- + +Device and driver capabilities are reported in the fixed screen information +capabilities field. + +struct fb_fix_screeninfo { + ... + __u16 capabilities; /* see FB_CAP_* */ + ... +}; + +Application should use those capabilities to find out what features they can +expect from the device and driver. + +- FB_CAP_FOURCC + +The driver supports the four character code (FOURCC) based format setting API. +When supported, formats are configured using a FOURCC instead of manually +specifying color components layout. + + +2. Types and visuals +-------------------- + +Pixels are stored in memory in hardware-dependent formats. Applications need +to be aware of the pixel storage format in order to write image data to the +frame buffer memory in the format expected by the hardware. + +Formats are described by frame buffer types and visuals. Some visuals require +additional information, which are stored in the variable screen information +bits_per_pixel, grayscale, red, green, blue and transp fields. + +Visuals describe how color information is encoded and assembled to create +macropixels. Types describe how macropixels are stored in memory. The following +types and visuals are supported. + +- FB_TYPE_PACKED_PIXELS + +Macropixels are stored contiguously in a single plane. If the number of bits +per macropixel is not a multiple of 8, whether macropixels are padded to the +next multiple of 8 bits or packed together into bytes depends on the visual. + +Padding at end of lines may be present and is then reported through the fixed +screen information line_length field. + +- FB_TYPE_PLANES + +Macropixels are split across multiple planes. The number of planes is equal to +the number of bits per macropixel, with plane i'th storing i'th bit from all +macropixels. + +Planes are located contiguously in memory. + +- FB_TYPE_INTERLEAVED_PLANES + +Macropixels are split across multiple planes. The number of planes is equal to +the number of bits per macropixel, with plane i'th storing i'th bit from all +macropixels. + +Planes are interleaved in memory. The interleave factor, defined as the +distance in bytes between the beginning of two consecutive interleaved blocks +belonging to different planes, is stored in the fixed screen information +type_aux field. + +- FB_TYPE_FOURCC + +Macropixels are stored in memory as described by the format FOURCC identifier +stored in the variable screen information grayscale field. + +- FB_VISUAL_MONO01 + +Pixels are black or white and stored on a number of bits (typically one) +specified by the variable screen information bpp field. + +Black pixels are represented by all bits set to 1 and white pixels by all bits +set to 0. When the number of bits per pixel is smaller than 8, several pixels +are packed together in a byte. + +FB_VISUAL_MONO01 is currently used with FB_TYPE_PACKED_PIXELS only. + +- FB_VISUAL_MONO10 + +Pixels are black or white and stored on a number of bits (typically one) +specified by the variable screen information bpp field. + +Black pixels are represented by all bits set to 0 and white pixels by all bits +set to 1. When the number of bits per pixel is smaller than 8, several pixels +are packed together in a byte. + +FB_VISUAL_MONO01 is currently used with FB_TYPE_PACKED_PIXELS only. + +- FB_VISUAL_TRUECOLOR + +Pixels are broken into red, green and blue components, and each component +indexes a read-only lookup table for the corresponding value. Lookup tables +are device-dependent, and provide linear or non-linear ramps. + +Each component is stored in a macropixel according to the variable screen +information red, green, blue and transp fields. + +- FB_VISUAL_PSEUDOCOLOR and FB_VISUAL_STATIC_PSEUDOCOLOR + +Pixel values are encoded as indices into a colormap that stores red, green and +blue components. The colormap is read-only for FB_VISUAL_STATIC_PSEUDOCOLOR +and read-write for FB_VISUAL_PSEUDOCOLOR. + +Each pixel value is stored in the number of bits reported by the variable +screen information bits_per_pixel field. + +- FB_VISUAL_DIRECTCOLOR + +Pixels are broken into red, green and blue components, and each component +indexes a programmable lookup table for the corresponding value. + +Each component is stored in a macropixel according to the variable screen +information red, green, blue and transp fields. + +- FB_VISUAL_FOURCC + +Pixels are encoded and interpreted as described by the format FOURCC +identifier stored in the variable screen information grayscale field. + + +3. Screen information +--------------------- + +Screen information are queried by applications using the FBIOGET_FSCREENINFO +and FBIOGET_VSCREENINFO ioctls. Those ioctls take a pointer to a +fb_fix_screeninfo and fb_var_screeninfo structure respectively. + +struct fb_fix_screeninfo stores device independent unchangeable information +about the frame buffer device and the current format. Those information can't +be directly modified by applications, but can be changed by the driver when an +application modifies the format. + +struct fb_fix_screeninfo { + char id[16]; /* identification string eg "TT Builtin" */ + unsigned long smem_start; /* Start of frame buffer mem */ + /* (physical address) */ + __u32 smem_len; /* Length of frame buffer mem */ + __u32 type; /* see FB_TYPE_* */ + __u32 type_aux; /* Interleave for interleaved Planes */ + __u32 visual; /* see FB_VISUAL_* */ + __u16 xpanstep; /* zero if no hardware panning */ + __u16 ypanstep; /* zero if no hardware panning */ + __u16 ywrapstep; /* zero if no hardware ywrap */ + __u32 line_length; /* length of a line in bytes */ + unsigned long mmio_start; /* Start of Memory Mapped I/O */ + /* (physical address) */ + __u32 mmio_len; /* Length of Memory Mapped I/O */ + __u32 accel; /* Indicate to driver which */ + /* specific chip/card we have */ + __u16 capabilities; /* see FB_CAP_* */ + __u16 reserved[2]; /* Reserved for future compatibility */ +}; + +struct fb_var_screeninfo stores device independent changeable information +about a frame buffer device, its current format and video mode, as well as +other miscellaneous parameters. + +struct fb_var_screeninfo { + __u32 xres; /* visible resolution */ + __u32 yres; + __u32 xres_virtual; /* virtual resolution */ + __u32 yres_virtual; + __u32 xoffset; /* offset from virtual to visible */ + __u32 yoffset; /* resolution */ + + __u32 bits_per_pixel; /* guess what */ + __u32 grayscale; /* 0 = color, 1 = grayscale, */ + /* >1 = FOURCC */ + struct fb_bitfield red; /* bitfield in fb mem if true color, */ + struct fb_bitfield green; /* else only length is significant */ + struct fb_bitfield blue; + struct fb_bitfield transp; /* transparency */ + + __u32 nonstd; /* != 0 Non standard pixel format */ + + __u32 activate; /* see FB_ACTIVATE_* */ + + __u32 height; /* height of picture in mm */ + __u32 width; /* width of picture in mm */ + + __u32 accel_flags; /* (OBSOLETE) see fb_info.flags */ + + /* Timing: All values in pixclocks, except pixclock (of course) */ + __u32 pixclock; /* pixel clock in ps (pico seconds) */ + __u32 left_margin; /* time from sync to picture */ + __u32 right_margin; /* time from picture to sync */ + __u32 upper_margin; /* time from sync to picture */ + __u32 lower_margin; + __u32 hsync_len; /* length of horizontal sync */ + __u32 vsync_len; /* length of vertical sync */ + __u32 sync; /* see FB_SYNC_* */ + __u32 vmode; /* see FB_VMODE_* */ + __u32 rotate; /* angle we rotate counter clockwise */ + __u32 colorspace; /* colorspace for FOURCC-based modes */ + __u32 reserved[4]; /* Reserved for future compatibility */ +}; + +To modify variable information, applications call the FBIOPUT_VSCREENINFO +ioctl with a pointer to a fb_var_screeninfo structure. If the call is +successful, the driver will update the fixed screen information accordingly. + +Instead of filling the complete fb_var_screeninfo structure manually, +applications should call the FBIOGET_VSCREENINFO ioctl and modify only the +fields they care about. + + +4. Format configuration +----------------------- + +Frame buffer devices offer two ways to configure the frame buffer format: the +legacy API and the FOURCC-based API. + + +The legacy API has been the only frame buffer format configuration API for a +long time and is thus widely used by application. It is the recommended API +for applications when using RGB and grayscale formats, as well as legacy +non-standard formats. + +To select a format, applications set the fb_var_screeninfo bits_per_pixel field +to the desired frame buffer depth. Values up to 8 will usually map to +monochrome, grayscale or pseudocolor visuals, although this is not required. + +- For grayscale formats, applications set the grayscale field to one. The red, + blue, green and transp fields must be set to 0 by applications and ignored by + drivers. Drivers must fill the red, blue and green offsets to 0 and lengths + to the bits_per_pixel value. + +- For pseudocolor formats, applications set the grayscale field to zero. The + red, blue, green and transp fields must be set to 0 by applications and + ignored by drivers. Drivers must fill the red, blue and green offsets to 0 + and lengths to the bits_per_pixel value. + +- For truecolor and directcolor formats, applications set the grayscale field + to zero, and the red, blue, green and transp fields to describe the layout of + color components in memory. + +struct fb_bitfield { + __u32 offset; /* beginning of bitfield */ + __u32 length; /* length of bitfield */ + __u32 msb_right; /* != 0 : Most significant bit is */ + /* right */ +}; + + Pixel values are bits_per_pixel wide and are split in non-overlapping red, + green, blue and alpha (transparency) components. Location and size of each + component in the pixel value are described by the fb_bitfield offset and + length fields. Offset are computed from the right. + + Pixels are always stored in an integer number of bytes. If the number of + bits per pixel is not a multiple of 8, pixel values are padded to the next + multiple of 8 bits. + +Upon successful format configuration, drivers update the fb_fix_screeninfo +type, visual and line_length fields depending on the selected format. + + +The FOURCC-based API replaces format descriptions by four character codes +(FOURCC). FOURCCs are abstract identifiers that uniquely define a format +without explicitly describing it. This is the only API that supports YUV +formats. Drivers are also encouraged to implement the FOURCC-based API for RGB +and grayscale formats. + +Drivers that support the FOURCC-based API report this capability by setting +the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field. + +FOURCC definitions are located in the linux/videodev2.h header. However, and +despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2 +and don't require usage of the V4L2 subsystem. FOURCC documentation is +available in Documentation/DocBook/v4l/pixfmt.xml. + +To select a format, applications set the grayscale field to the desired FOURCC. +For YUV formats, they should also select the appropriate colorspace by setting +the colorspace field to one of the colorspaces listed in linux/videodev2.h and +documented in Documentation/DocBook/v4l/colorspaces.xml. + +The red, green, blue and transp fields are not used with the FOURCC-based API. +For forward compatibility reasons applications must zero those fields, and +drivers must ignore them. Values other than 0 may get a meaning in future +extensions. + +Upon successful format configuration, drivers update the fb_fix_screeninfo +type, visual and line_length fields depending on the selected format. The type +and visual fields are set to FB_TYPE_FOURCC and FB_VISUAL_FOURCC respectively. diff --git a/Documentation/fb/cirrusfb.txt b/Documentation/fb/cirrusfb.txt index f9436843e99..f75950d330a 100644 --- a/Documentation/fb/cirrusfb.txt +++ b/Documentation/fb/cirrusfb.txt @@ -55,7 +55,7 @@ Version 1.9.4.4 * Overhaul color register routines. * Associated with the above, console colors are now obtained from a LUT called 'palette' instead of from the VGA registers. This code was - modeled after that in atyfb and matroxfb. + modelled after that in atyfb and matroxfb. * Code cleanup, add comments. * Overhaul SR07 handling. * Bug fixes. diff --git a/Documentation/fb/fbcon.txt b/Documentation/fb/fbcon.txt index 99ea58e65ef..4a9739abc86 100644 --- a/Documentation/fb/fbcon.txt +++ b/Documentation/fb/fbcon.txt @@ -150,7 +150,7 @@ C. Boot options C. Attaching, Detaching and Unloading -Before going on on how to attach, detach and unload the framebuffer console, an +Before going on how to attach, detach and unload the framebuffer console, an illustration of the dependencies may help. The console layer, as with most subsystems, needs a driver that interfaces with diff --git a/Documentation/fb/intel810.txt b/Documentation/fb/intel810.txt index be3e7836abe..a8e9f5bca6f 100644 --- a/Documentation/fb/intel810.txt +++ b/Documentation/fb/intel810.txt @@ -211,7 +211,7 @@ 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 /etc/modprobe.conf +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 diff --git a/Documentation/fb/intelfb.txt b/Documentation/fb/intelfb.txt index dd9e944ea62..feac4e4d696 100644 --- a/Documentation/fb/intelfb.txt +++ b/Documentation/fb/intelfb.txt @@ -120,7 +120,7 @@ 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 /etc/modprobe.conf +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 diff --git a/Documentation/fb/matroxfb.txt b/Documentation/fb/matroxfb.txt index e5ce8a1a978..b95f5bb522f 100644 --- a/Documentation/fb/matroxfb.txt +++ b/Documentation/fb/matroxfb.txt @@ -177,8 +177,8 @@ 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 Millenium and - Millenium II. Specify this if you see strange color shadows around +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) @@ -204,9 +204,9 @@ grayscale - enable grayscale summing. It works in PSEUDOCOLOR modes (text, can paint colors. nograyscale - disable grayscale summing. It is default. cross4MB - enables that pixel line can cross 4MB boundary. It is default for - non-Millenium. + non-Millennium. nocross4MB - pixel line must not cross 4MB boundary. It is default for - Millenium I or II, because of these devices have hardware + 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. diff --git a/Documentation/fb/modedb.txt b/Documentation/fb/modedb.txt index ec4dee75a35..16aa0845391 100644 --- a/Documentation/fb/modedb.txt +++ b/Documentation/fb/modedb.txt @@ -20,7 +20,7 @@ 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] + <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. @@ -36,6 +36,21 @@ 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 + ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** What is the VESA(TM) Coordinated Video Timings (CVT)? @@ -132,5 +147,5 @@ There may be more modes. tridentfb - Trident (Cyber)blade chipset frame buffer vt8623fb - VIA 8623 frame buffer -BTW, only a few drivers use this at the moment. Others are to follow -(feel free to send patches). +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. diff --git a/Documentation/fb/sm501.txt b/Documentation/fb/sm501.txt new file mode 100644 index 00000000000..187f3b3ccb6 --- /dev/null +++ b/Documentation/fb/sm501.txt @@ -0,0 +1,10 @@ +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>]" diff --git a/Documentation/fb/sstfb.txt b/Documentation/fb/sstfb.txt index 550ca775a4c..13db1075e4a 100644 --- a/Documentation/fb/sstfb.txt +++ b/Documentation/fb/sstfb.txt @@ -10,7 +10,7 @@ Introduction 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 useable + 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 diff --git a/Documentation/fb/udlfb.txt b/Documentation/fb/udlfb.txt new file mode 100644 index 00000000000..57d2f2908b1 --- /dev/null +++ b/Documentation/fb/udlfb.txt @@ -0,0 +1,159 @@ + +What is udlfb? +=============== + +This is a driver for DisplayLink USB 2.0 era graphics chips. + +DisplayLink chips provide simple hline/blit operations with some compression, +pairing that with a hardware framebuffer (16MB) on the other end of the +USB wire. That hardware framebuffer is able to drive the VGA, DVI, or HDMI +monitor with no CPU involvement until a pixel has to change. + +The CPU or other local resource does all the rendering; optinally compares the +result with a local shadow of the remote hardware framebuffer to identify +the minimal set of pixels that have changed; and compresses and sends those +pixels line-by-line via USB bulk transfers. + +Because of the efficiency of bulk transfers and a protocol on top that +does not require any acks - the effect is very low latency that +can support surprisingly high resolutions with good performance for +non-gaming and non-video applications. + +Mode setting, EDID read, etc are other bulk or control transfers. Mode +setting is very flexible - able to set nearly arbitrary modes from any timing. + +Advantages of USB graphics in general: + + * Ability to add a nearly arbitrary number of displays to any USB 2.0 + capable system. On Linux, number of displays is limited by fbdev interface + (FB_MAX is currently 32). Of course, all USB devices on the same + host controller share the same 480Mbs USB 2.0 interface. + +Advantages of supporting DisplayLink chips with kernel framebuffer interface: + + * The actual hardware functionality of DisplayLink chips matches nearly + one-to-one with the fbdev interface, making the driver quite small and + tight relative to the functionality it provides. + * X servers and other applications can use the standard fbdev interface + from user mode to talk to the device, without needing to know anything + about USB or DisplayLink's protocol at all. A "displaylink" X driver + and a slightly modified "fbdev" X driver are among those that already do. + +Disadvantages: + + * Fbdev's mmap interface assumes a real hardware framebuffer is mapped. + In the case of USB graphics, it is just an allocated (virtual) buffer. + Writes need to be detected and encoded into USB bulk transfers by the CPU. + Accurate damage/changed area notifications work around this problem. + In the future, hopefully fbdev will be enhanced with an small standard + interface to allow mmap clients to report damage, for the benefit + of virtual or remote framebuffers. + * Fbdev does not arbitrate client ownership of the framebuffer well. + * Fbcon assumes the first framebuffer it finds should be consumed for console. + * It's not clear what the future of fbdev is, given the rise of KMS/DRM. + +How to use it? +============== + +Udlfb, when loaded as a module, will match against all USB 2.0 generation +DisplayLink chips (Alex and Ollie family). It will then attempt to read the EDID +of the monitor, and set the best common mode between the DisplayLink device +and the monitor's capabilities. + +If the DisplayLink device is successful, it will paint a "green screen" which +means that from a hardware and fbdev software perspective, everything is good. + +At that point, a /dev/fb? interface will be present for user-mode applications +to open and begin writing to the framebuffer of the DisplayLink device using +standard fbdev calls. Note that if mmap() is used, by default the user mode +application must send down damage notifcations to trigger repaints of the +changed regions. Alternatively, udlfb can be recompiled with experimental +defio support enabled, to support a page-fault based detection mechanism +that can work without explicit notifcation. + +The most common client of udlfb is xf86-video-displaylink or a modified +xf86-video-fbdev X server. These servers have no real DisplayLink specific +code. They write to the standard framebuffer interface and rely on udlfb +to do its thing. The one extra feature they have is the ability to report +rectangles from the X DAMAGE protocol extension down to udlfb via udlfb's +damage interface (which will hopefully be standardized for all virtual +framebuffers that need damage info). These damage notifications allow +udlfb to efficiently process the changed pixels. + +Module Options +============== + +Special configuration for udlfb is usually unnecessary. There are a few +options, however. + +From the command line, pass options to modprobe +modprobe udlfb fb_defio=0 console=1 shadow=1 + +Or modify options on the fly at /sys/module/udlfb/parameters directory via +sudo nano fb_defio +change the parameter in place, and save the file. + +Unplug/replug USB device to apply with new settings + +Or for permanent option, create file like /etc/modprobe.d/udlfb.conf with text +options udlfb fb_defio=0 console=1 shadow=1 + +Accepted boolean options: + +fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel + module to track changed areas of the framebuffer by page faults. + Standard fbdev applications that use mmap but that do not + report damage, should be able to work with this enabled. + Disable when running with X server that supports reporting + changed regions via ioctl, as this method is simpler, + more stable, and higher performance. + default: fb_defio=1 + +console Allow fbcon to attach to udlfb provided framebuffers. + Can be disabled if fbcon and other clients + (e.g. X with --shared-vt) are in conflict. + default: console=1 + +shadow Allocate a 2nd framebuffer to shadow what's currently across + the USB bus in device memory. If any pixels are unchanged, + do not transmit. Spends host memory to save USB transfers. + Enabled by default. Only disable on very low memory systems. + default: shadow=1 + +Sysfs Attributes +================ + +Udlfb creates several files in /sys/class/graphics/fb? +Where ? is the sequential framebuffer id of the particular DisplayLink device + +edid If a valid EDID blob is written to this file (typically + by a udev rule), then udlfb will use this EDID as a + backup in case reading the actual EDID of the monitor + attached to the DisplayLink device fails. This is + especially useful for fixed panels, etc. that cannot + communicate their capabilities via EDID. Reading + this file returns the current EDID of the attached + monitor (or last backup value written). This is + useful to get the EDID of the attached monitor, + which can be passed to utilities like parse-edid. + +metrics_bytes_rendered 32-bit count of pixel bytes rendered + +metrics_bytes_identical 32-bit count of how many of those bytes were found to be + unchanged, based on a shadow framebuffer check + +metrics_bytes_sent 32-bit count of how many bytes were transferred over + USB to communicate the resulting changed pixels to the + hardware. Includes compression and protocol overhead + +metrics_cpu_kcycles_used 32-bit count of CPU cycles used in processing the + above pixels (in thousands of cycles). + +metrics_reset Write-only. Any write to this file resets all metrics + above to zero. Note that the 32-bit counters above + roll over very quickly. To get reliable results, design + performance tests to start and finish in a very short + period of time (one minute or less is safe). + +-- +Bernie Thompson <bernie@plugable.com> diff --git a/Documentation/fb/uvesafb.txt b/Documentation/fb/uvesafb.txt index eefdd91d298..f6362d88763 100644 --- a/Documentation/fb/uvesafb.txt +++ b/Documentation/fb/uvesafb.txt @@ -81,17 +81,11 @@ pmipal Use the protected mode interface for palette changes. mtrr:n Setup memory type range registers for the framebuffer where n: - 0 - disabled (equivalent to nomtrr) (default) - 1 - uncachable - 2 - write-back - 3 - write-combining - 4 - write-through - - If you see the following in dmesg, choose the type that matches - the old one. In this example, use "mtrr:2". -... -mtrr: type mismatch for e0000000,8000000 old: write-back new: write-combining -... + 0 - disabled (equivalent to nomtrr) + 3 - write-combining (default) + + Values other than 0 and 3 will result in a warning and will be + treated just like 3. nomtrr Do not use memory type range registers. diff --git a/Documentation/fb/viafb.modes b/Documentation/fb/viafb.modes index 02e5b487f00..2a547da2e5c 100644 --- a/Documentation/fb/viafb.modes +++ b/Documentation/fb/viafb.modes @@ -571,7 +571,7 @@ mode "640x480-60" # 160 chars 800 lines # Blank Time 4.798 us 0.564 ms # 50 chars 28 lines -# Polarity negtive positive +# Polarity negative positive # mode "1280x800-60" # D: 83.500 MHz, H: 49.702 kHz, V: 60.00 Hz diff --git a/Documentation/fb/viafb.txt b/Documentation/fb/viafb.txt index 1a2e8aa3fbb..1cb2462a71c 100644 --- a/Documentation/fb/viafb.txt +++ b/Documentation/fb/viafb.txt @@ -32,7 +32,7 @@ Start viafb with default settings: #modprobe viafb - Start viafb with with user options: + Start viafb with user options: #modprobe viafb viafb_mode=800x600 viafb_bpp=16 viafb_refresh=60 viafb_active_dev=CRT+DVI viafb_dvi_port=DVP1 viafb_mode1=1024x768 viafb_bpp=16 viafb_refresh1=60 @@ -204,7 +204,7 @@ Notes: supported_output_devices - This read-only file contains a full ',' seperated list containing all + This read-only file contains a full ',' separated list containing all output devices that could be available on your platform. It is likely that not all of those have a connector on your hardware but it should provide a good starting point to figure out which of those names match @@ -225,7 +225,7 @@ Notes: This can happen for example if only one (the other) iga is used. Writing to these files allows adjusting the output devices during runtime. One can add new devices, remove existing ones or switch - between igas. Essentially you can write a ',' seperated list of device + between igas. Essentially you can write a ',' separated list of device names (or a single one) in the same format as the output to those files. You can add a '+' or '-' as a prefix allowing simple addition and removal of devices. So a prefix '+' adds the devices from your list |