diff options
Diffstat (limited to 'Documentation/fb')
| -rw-r--r-- | Documentation/fb/00-INDEX | 6 | ||||
| -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 | 2 | ||||
| -rw-r--r-- | Documentation/fb/sstfb.txt | 2 | ||||
| -rw-r--r-- | Documentation/fb/udlfb.txt | 39 | ||||
| -rw-r--r-- | Documentation/fb/uvesafb.txt | 16 | ||||
| -rw-r--r-- | Documentation/fb/viafb.modes | 2 | ||||
| -rw-r--r-- | Documentation/fb/viafb.txt | 2 |
14 files changed, 374 insertions, 38 deletions
diff --git a/Documentation/fb/00-INDEX b/Documentation/fb/00-INDEX index 30a70542e82..fe85e7c5907 100644 --- a/Documentation/fb/00-INDEX +++ b/Documentation/fb/00-INDEX @@ -5,6 +5,8 @@ please mail me. 00-INDEX - 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 @@ -51,12 +53,16 @@ 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. 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 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 index 8d17aebd264..187f3b3ccb6 100644 --- a/Documentation/fb/sm501.txt +++ b/Documentation/fb/sm501.txt @@ -3,7 +3,7 @@ Configuration: You can pass the following kernel command line options to sm501 videoframebuffer: sm501fb.bpp= SM501 Display driver: - Specifiy bits-per-pixel if not specified by 'mode' + Specify bits-per-pixel if not specified by 'mode' sm501fb.mode= SM501 Display driver: Specify resolution as 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 index 7fdde2a02a2..57d2f2908b1 100644 --- a/Documentation/fb/udlfb.txt +++ b/Documentation/fb/udlfb.txt @@ -87,23 +87,38 @@ Special configuration for udlfb is usually unnecessary. There are a few options, however. From the command line, pass options to modprobe -modprobe udlfb defio=1 console=1 +modprobe udlfb fb_defio=0 console=1 shadow=1 -Or for permanent option, create file like /etc/modprobe.d/options with text -options udlfb defio=1 console=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. -Accepted options: +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, may be able to work with this enabled. - Disabled by default because of overhead and other issues. - -console Allow fbcon to attach to udlfb provided framebuffers. This - is disabled by default because fbcon will aggressively consume - the first framebuffer it finds, which isn't usually what the - user wants in the case of USB displays. + 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 ================ 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 444e34b52ae..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 |