home *** CD-ROM | disk | FTP | other *** search
/ Enter 1999 April - Disc 1 / enter_04_1999_1.iso / OS2 / XFREE86 / XDOC.ZIP / XFree86 / lib / X11 / doc / README.fbdev < prev    next >
Encoding:
Text File  |  1999-01-09  |  16.3 KB  |  595 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                       The Linux/m68k Frame Buffer Device
  11.  
  12.            Geert Uytterhoeven (Geert.Uytterhoeven@cs.kuleuven.ac.be)
  13.  
  14.                                 7 November 1998
  15.  
  16.  
  17.  
  18. 1.  Introduction
  19.  
  20. The frame buffer device provides an abstraction for the graphics hardware. It
  21. represents the frame buffer of some video hardware and allows application soft-
  22. ware to access the graphics hardware through a well-defined interface, so the
  23. software doesn't need to know anything about the low-level (hardware register)
  24. stuff.
  25.  
  26. The device is accessed through special device nodes, usually located in the
  27. /dev directory, i.e. /dev/fb*.
  28.  
  29.  
  30. 2.  User's View of /dev/fb*
  31.  
  32. From the user's point of view, the frame buffer device looks just like any
  33. other device in /dev. It's a character device using major 29, the minor speci-
  34. fies the frame buffer number.
  35.  
  36. By convention, the following device nodes are used (numbers indicate the device
  37. minor numbers):
  38.  
  39.       0 = /dev/fb0
  40.             First frame buffer
  41.  
  42.       32 = /dev/fb1
  43.             Second frame buffer
  44.  
  45.       ...
  46.  
  47.       224 = /dev/fb7
  48.             8th frame buffer
  49.  
  50. For backwards compatibility, you may want to create a symbolic link from
  51. /dev/fb0current to fb0.
  52.  
  53. The frame buffer devices are also `normal' memory devices, this means, you can
  54. read and write their contents. You can, for example, make a screen snapshot by
  55.  
  56.          cp /dev/fb0 myfile
  57.  
  58.  
  59. There also can be more than one frame buffer at a time, e.g. if you have a
  60. graphics card in addition to the built-in hardware. The corresponding frame
  61. buffer devices (/dev/fb0 and /dev/fb1 etc.) work independently.
  62.  
  63.  
  64. The Linux/m68k Frame Buffer Device                                            1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. The Linux/m68k Frame Buffer Device                                            2
  71.  
  72.  
  73.  
  74. Application software that uses the frame buffer device (e.g. the X server) will
  75. use /dev/fb0 by default (older software uses /dev/fb0current). You can specify
  76. an alternative frame buffer device by setting the environment variable $FRAME-
  77. BUFFER to the path name of a frame buffer device, e.g. (for sh/bash users):
  78.  
  79.          export FRAMEBUFFER=/dev/fb1
  80.  
  81.  
  82. or (for csh users):
  83.  
  84.          setenv FRAMEBUFFER /dev/fb1
  85.  
  86.  
  87. After this the X server will use the second frame buffer.
  88.  
  89.  
  90. 3.  Programmer's View of /dev/fb*
  91.  
  92. As you already know, a frame buffer device is a memory device like /dev/mem and
  93. it has the same features. You can read it, write it, seek to some location in
  94. it and mmap() it (the main usage). The difference is just that the memory that
  95. appears in the special file is not the whole memory, but the frame buffer of
  96. some video hardware.
  97.  
  98. /dev/fb* also allows several ioctls on it, by which lots of information about
  99. the hardware can be queried and set. The color map handling works via ioctls,
  100. too. Look into <linux/fb.h> for more information on what ioctls exist and on
  101. which data structures they work. Here's just a brief overview:
  102.  
  103.    o You can request unchangeable information about the hardware, like name,
  104.      organization of the screen memory (planes, packed pixels, ...) and address
  105.      and length of the screen memory.
  106.  
  107.    o You can request and change variable information about the hardware, like
  108.      visible and virtual geometry, depth, color map format, timing, and so on.
  109.      If you try to change that informations, the driver maybe will round up
  110.      some values to meet the hardware's capabilities (or return EINVAL if that
  111.      isn't possible).
  112.  
  113.    o You can get and set parts of the color map. Communication is done with 16
  114.      bit per color part (red, green, blue, transparency) to support all exist-
  115.      ing hardware. The driver does all the computations needed to bring it into
  116.      the hardware (round it down to less bits, maybe throw away transparency).
  117.  
  118. All this hardware abstraction makes the implementation of application programs
  119. easier and more portable. E.g. the X server works completely on /dev/fb* and
  120. thus doesn't need to know, for example, how the color registers of the concrete
  121. hardware are organized. XF68_FBDev is a general X server for bitmapped, unac-
  122. celerated video hardware. The only thing that has to be built into application
  123. programs is the screen organization (bitplanes or chunky pixels etc.), because
  124. it works on the frame buffer image data directly.
  125.  
  126. For the future it is planned that frame buffer drivers for graphics cards and
  127. the like can be implemented as kernel modules that are loaded at runtime. Such
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. The Linux/m68k Frame Buffer Device                                            3
  137.  
  138.  
  139.  
  140. a driver just has to call register_framebuffer() and supply some functions.
  141. Writing and distributing such drivers independently from the kernel will save
  142. much trouble...
  143.  
  144.  
  145. 4.  Frame Buffer Resolution Maintenance
  146.  
  147. Frame buffer resolutions are maintained using the utility fbset. It can change
  148. the video mode properties of a frame buffer device. Its main usage is to change
  149. the current video mode, e.g. during boot up in one of your /etc/rc.* or
  150. /etc/init.d/* files.
  151.  
  152. Fbset uses a video mode database stored in a configuration file, so you can
  153. easily add your own modes and refer to them with a simple identifier.
  154.  
  155.  
  156. 5.  The X Server
  157.  
  158. The X server (XF68_FBDev) is the most notable application program for the frame
  159. buffer device. Starting with XFree86 release 3.2, the X server is part of
  160. XFree86 and has 2 modes:
  161.  
  162.    o If the Display subsection for the fbdev driver in the /etc/XF86Config file
  163.      contains a
  164.  
  165.  
  166.                   Modes "default"
  167.  
  168.  
  169.  
  170.  
  171.      line, the X server will use the scheme discussed above, i.e. it will start
  172.      up in the resolution determined by /dev/fb0 (or $FRAMEBUFFER, if set). You
  173.      still have to specify the color depth (using the Depth keyword) and vir-
  174.      tual resolution (using the Virtual keyword) though. This is the default
  175.      for the configuration file supplied with XFree86. It's the most simple
  176.      configuration, but it has some limitations.
  177.  
  178.    o Therefore it's also possible to specify resolutions in the /etc/XF86Config
  179.      file. This allows for on-the-fly resolution switching while retaining the
  180.      same virtual desktop size. The frame buffer device that's used is still
  181.      /dev/fb0 (or $FRAMEBUFFER), but the available resolutions are defined by
  182.      /etc/XF86Config now. The disadvantage is that you have to specify the tim-
  183.      ings in a different format (but fbset -x may help).
  184.  
  185. To tune a video mode, you can use fbset or xvidtune. Note that xvidtune doesn't
  186. work 100% with XF68_FBDev: the reported clock values are always incorrect.
  187.  
  188.  
  189. 6.  Video Mode Timings
  190.  
  191. A monitor draws an image on the screen by using an electron beam (3 electron
  192. beams for color models, 1 electron beam for monochrome monitors). The front of
  193. the screen is covered by a pattern of colored phosphors (pixels). If a phosphor
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. The Linux/m68k Frame Buffer Device                                            4
  203.  
  204.  
  205.  
  206. is hit by an electron, it emits a photon and thus becomes visible.
  207.  
  208. The electron beam draws horizontal lines (scanlines) from left to right, and
  209. from the top to the bottom of the screen. By modifying the intensity of the
  210. electron beam, pixels with various colors and intensities can be shown.
  211.  
  212. After each scanline the electron beam has to move back to the left side of the
  213. screen and to the next line: this is called the horizontal retrace. After the
  214. whole screen (frame) was painted, the beam moves back to the upper left corner:
  215. this is called the vertical retrace. During both the horizontal and vertical
  216. retrace, the electron beam is turned off (blanked).
  217.  
  218. The speed at which the electron beam paints the pixels is determined by the
  219. dotclock in the graphics board. For a dotclock of e.g. 28.37516 MHz (millions
  220. of cycles per second), each pixel is 35242 ps (picoseconds) long:
  221.  
  222.  
  223.  
  224.  
  225. 1/(28.37516E6 Hz) = 35.242E-9 s
  226.  
  227. If the screen resolution is 640x480, it will take
  228.  
  229.          640*35.242E-9 s = 22.555E-6 s
  230.  
  231.  
  232. to paint the 640 (xres) pixels on one scanline. But the horizontal retrace also
  233. takes time (e.g. 272 `pixels'), so a full scanline takes
  234.  
  235.          (640+272)*35.242E-9 s = 32.141E-6 s
  236.  
  237.  
  238. We'll say that the horizontal scanrate is about 31 kHz:
  239.  
  240.          1/(32.141E-6 s) = 31.113E3 Hz
  241.  
  242.  
  243. A full screen counts 480 (yres) lines, but we have to consider the vertical
  244. retrace too (e.g. 49 `pixels'). So a full screen will take
  245.  
  246.          (480+49)*32.141E-6 s = 17.002E-3 s
  247.  
  248.  
  249. The vertical scanrate is about 59 Hz:
  250.  
  251.          1/(17.002E-3 s) = 58.815 Hz
  252.  
  253.  
  254. This means the screen data is refreshed about 59 times per second. To have a
  255. stable picture without visible flicker, VESA recommends a vertical scanrate of
  256. at least 72 Hz. But the perceived flicker is very human dependent: some people
  257. can use 50 Hz without any trouble, while I'll notice if it's less than 80 Hz.
  258.  
  259. Since the monitor doesn't know when a new scanline starts, the graphics board
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. The Linux/m68k Frame Buffer Device                                            5
  269.  
  270.  
  271.  
  272. will supply a synchronization pulse (horizontal sync or hsync) for each scan-
  273. line.  Similarly it supplies a synchronization pulse (vertical sync or vsync)
  274. for each new frame. The position of the image on the screen is influenced by
  275. the moments at which the synchronization pulses occur.
  276.  
  277. The following picture summarizes all timings. The horizontal retrace time is
  278. the sum of the left margin, the right margin and the hsync length, while the
  279. vertical retrace time is the sum of the upper margin, the lower margin and the
  280. vsync length.
  281.  
  282.        +----------+---------------------------------------------+----------+-------+
  283.        |          |                x                            |          |       |
  284.        |          |                |upper_margin                |          |       |
  285.        |          |                x                            |          |       |
  286.        +----------###############################################----------+-------+
  287.        |          #                x                            #          |       |
  288.        |          #                |                            #          |       |
  289.        |          #                |                            #          |       |
  290.        |          #                |                            #          |       |
  291.        |   left   #                |                            #  right   | hsync |
  292.        |  margin  #                |       xres                 #  margin  |  len  |
  293.        |<-------->#<---------------+--------------------------->#<-------->|<----->|
  294.        |          #                |                            #          |       |
  295.        |          #                |                            #          |       |
  296.        |          #                |                            #          |       |
  297.        |          #                |yres                        #          |       |
  298.        |          #                |                            #          |       |
  299.        |          #                |                            #          |       |
  300.        |          #                |                            #          |       |
  301.        |          #                |                            #          |       |
  302.        |          #                |                            #          |       |
  303.        |          #                |                            #          |       |
  304.        |          #                |                            #          |       |
  305.        |          #                |                            #          |       |
  306.        |          #                x                            #          |       |
  307.        +----------###############################################----------+-------+
  308.        |          |                x                            |          |       |
  309.        |          |                |lower_margin                |          |       |
  310.        |          |                x                            |          |       |
  311.        +----------+---------------------------------------------+----------+-------+
  312.        |          |                x                            |          |       |
  313.        |          |                |vsync_len                   |          |       |
  314.        |          |                x                            |          |       |
  315.        +----------+---------------------------------------------+----------+-------+
  316.  
  317. The frame buffer device expects all horizontal timings in number of dotclocks
  318. (in picoseconds, 1E-12 s), and vertical timings in number of scanlines.
  319.  
  320.  
  321. 7.  Converting XFree86 timing values into frame buffer device timings
  322.  
  323. An XFree86 mode line consists of the following fields:
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. The Linux/m68k Frame Buffer Device                                            6
  335.  
  336.  
  337.  
  338.          "800x600"     50      800  856  976 1040    600  637  643  666
  339.          < name >     DCF       HR  SH1  SH2  HFL     VR  SV1  SV2  VFL
  340.  
  341.  
  342. The frame buffer device uses the following fields:
  343.  
  344.       pixclock
  345.             pixel clock in ps (pico seconds)
  346.  
  347.       left_margin
  348.             time from sync to picture
  349.  
  350.       right_margin
  351.             time from picture to sync
  352.  
  353.       upper_margin
  354.             time from sync to picture
  355.  
  356.       lower_margin
  357.             time from picture to sync
  358.  
  359.       hsync_len
  360.             length of horizontal sync
  361.  
  362.       vsync_len
  363.             length of vertical sync
  364.  
  365.       Pixelclock
  366.  
  367.                o xfree: in MHz
  368.  
  369.                o fb: In Picoseconds (ps)
  370.  
  371.                o pixclock = 1000000 / DCF
  372.  
  373.       Horizontal timings
  374.  
  375.                o left_margin = HFL - SH2
  376.  
  377.                o right_margin = SH1 - HR
  378.  
  379.                o hsync_len = SH2 - SH1
  380.  
  381.       Vertical timings
  382.  
  383.                o upper_margin = VFL - SV2
  384.  
  385.                o lower_margin = SV1 - VR
  386.  
  387.                o vsync_len = SV2 - SV1
  388.  
  389. Good examples for VESA timings can be found in the XFree86 source tree, under
  390. xc/programs/Xserver/hw/xfree86/doc/modeDB.txt.
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. The Linux/m68k Frame Buffer Device                                            7
  401.  
  402.  
  403.  
  404. 8.  References
  405.  
  406. For more specific information about the frame buffer device and its applica-
  407. tions, please refer to the following documentation:
  408.  
  409.    o The manual pages for fbset: fbset(8), fb.modes(5)
  410.  
  411.    o The manual pages for XFree86: XF68_FBDev(1), XF86Config(4/5)
  412.  
  413.    o The mighty kernel sources:
  414.  
  415.         o linux/drivers/video/
  416.  
  417.         o linux/include/linux/fb.h
  418.  
  419.         o linux/include/video/
  420.  
  421.  
  422. 9.  Downloading
  423.  
  424. All necessary files can be found at
  425.  
  426.          ftp://ftp.uni-erlangen.de/pub/Linux/LOCAL/680x0/
  427.  
  428.  
  429. and on its mirrors.
  430.  
  431.  
  432. 10.  Credits
  433.  
  434.  
  435. This readme was written by Geert Uytterhoeven, partly based on the original X-
  436. framebuffer.README by Roman Hodek and Martin Schaller. Section `Converting
  437. XFree86 timing values into frame buffer device timings' was provided by Frank
  438. Neumann.
  439.  
  440. The frame buffer device abstraction was designed by Martin Schaller.
  441.  
  442.      Generated from XFree86: xc/programs/Xserver/hw/xfree68/doc/sgml/fbdev.sgml,v 1.1.2.6 1998/11/08 09:06:32 dawes Exp $
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. The Linux/m68k Frame Buffer Device                                            8
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.                                    CONTENTS
  537.  
  538.  
  539.  
  540. 1.  Introduction ............................................................ 1
  541.  
  542. 2.  User's View of /dev/fb* ................................................. 1
  543.  
  544. 3.  Programmer's View of /dev/fb* ........................................... 2
  545.  
  546. 4.  Frame Buffer Resolution Maintenance ..................................... 3
  547.  
  548. 5.  The X Server ............................................................ 3
  549.  
  550. 6.  Video Mode Timings ...................................................... 3
  551.  
  552. 7.  Converting XFree86 timing values into frame buffer device timings ....... 5
  553.  
  554. 8.  References .............................................................. 7
  555.  
  556. 9.  Downloading ............................................................. 7
  557.  
  558. 10. Credits  ................................................................ 7
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                                        i
  593.  
  594.  
  595.