[Linuxconsole-commit]CVS: ruby/web/htdocs/fbdev/HOWTO 1.html,NONE,1.1 2.html,NONE,1.1 3.html,NONE,1.

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/linuxconsole/ruby/web/htdocs/fbdev/HOWTO
In directory usw-pr-cvs1:/tmp/cvs-serv21324

Added Files:
	1.html 2.html 3.html 4.html index.html 
Log Message:
Adding HOWTO to show how to create a framebuffer device with the new api. The stuff right now is based on my original ideas. So it needs to be updated.

--- NEW FILE: 1.html ---
<html>
<head>
<title>Linux Framebuffer Driver Writing HOWTO</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF">
<h2>1.  Introduction</h2>
<hr width="100%" size="2">
This is the Linux Framebuffer driver 
 HOWTO. It is intended as a quick reference covering everything you need to know 
 to write a framebuffer video driver under Linux. Frequently asked questions 
 about video mode setting under Linux are answered, and references are given 
 to some other sources of information on a variety of topics related to computer 
 graphics. Also, read this document not once, not twice but three times if you 
 are not familiar with video hardware.
The scope is limited to the aspects 
 of writing a mode setting video card framebuffer driver pertaining to Linux. 
 listed See the other documents in the References section for more general information 
 on how to setup framebuffer cards and setting up the XFB_Dev X server.
<h3>1.1.  Acknowledgments</h3>
Much of this information came from 
 the new framebuffer internal API being developed by me for the upcoming next 
 series of kernels. Originally, this was based on a patch by Fabrice Bellard. 
 I learned of this patch and was impressed by it. Later, I took over development 
 and improved it even more. Much thanks goes to Fabrice for getting the ball 
 rolling. This API is a natural extension of the original API developed by Martin 
 Schaller and now maintained by Geert Uytterhoeven (<a href="mailto:ge...@li...">ge...@li...</a>). 
 Thanks go to you and the many others who developed the Linux framebuffer system, 
 drivers and utilities. A great amount of thanks goes to Andreas Beck of the 
 GGI project for helping me write this document and teaching me about mode setting. 
 Thanks also go out to those who have supported my work. 
Thanks to the SGML Tools package, 
 this HOWTO is available in several formats, all generated from a common source 
 file.
<h3>1.2.  Revision History</h3>
Version 1.0
First version; posted to fbdev mailing 
 list only.
<h3>1.3.  New versions of this document</h3>
New versions of this document will 
 be periodically posted to the comp.os.linux.answers newsgroup. They will also 
 be uploaded to various anonymous ftp sites that archive such information including 
 <a href="ftp://metalabs.unc.edu/pub/Linux/docs/HOWTO/">ftp://metalabs.unc.edu/pub/Linux/docs/HOWTO/</a>&gt;. 
 Hypertext versions of this and other Linux HOWTOs are available on many World-Wide-Web 
 sites, including &lt;<a href="http://metalab.unc.edu/LDP/">http://metalab.unc.edu/LDP/</a>&gt;. 
 Most Linux CD-ROM distributions include the HOWTOs, often under the /usr/doc 
 directory, and you can also buy printed copies from several vendors. Sometimes 
 the HOWTOs available from CD-ROM vendors, ftp sites, and printed format are 
 out of date. If the date on this HOWTO is more than six months in the past, 
 then a newer copy is probably available on the Internet.
Most translations of this and other 
 Linux HOWTOs can also be found at &lt;<a
href="http://sunsite.unc.edu/pub/Linux/docs/HOWTO/translations/">http://sunsite.unc.edu/pub/Linux/docs/HOWTO/translations/</a>&gt; 
 and &lt;<a href="ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/translations/">ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/translations/</a>&gt;.
If you make a translation of this 
 document into another language, let me know and I'll include a reference to 
 it here. As of yet there are no translations.
<h3>1.4.  Feedback</h3>
I rely on you, the reader, to make 
 this HOWTO useful. If you have any suggestions, corrections, or comments, please 
 send them to me, &lt;<a
href="mailto:jsi...@ac...">jsi...@ac...</a>&gt;, and 
 I will try to incorporate them in the next revision.
I am also willing to answer general 
 questions on video cards and fbcon under Linux as best I can. Before doing so, 
 please read all of the information in this HOWTO and send me detailed information 
 about the problem. Please do not ask me about using framebuffer cards under 
 operating systems other than Linux.
If you publish this document on a 
 CD-ROM or in hardcopy form, a complimentary copy would be appreciated. Mail 
 me for my postal address. Also, consider making a donation to the Linux Documentation 
 Project to help support free documentation for Linux. Contact the Linux HOWTO 
 coordinator, Tim Bynum &lt;<a
href="mailto:lin...@su...">lin...@su...</a>&gt;, 
 for more information.
<h3>1.5.  Distribution Policy</h3>
Copyright (c) 1999 by James Simmons.  
 This document may be distributed under the terms set forth in the LDP license 
 at &lt;<a href="http://sunsite.unc.edu/LDP/COPYRIGHT.html">http://sunsite.unc.edu/LDP/COPYRIGHT.html</a>&gt;.
<a href="index.html">index</a> 
 <a href="2.html">forward</a>
</body>
</html>

--- NEW FILE: 2.html ---
<html>
<head>
<title>Linux Framebuffer Driver Writing HOWTO</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF">
<h2><font face="Arial, Helvetica, sans-serif">2.  Framebuffer Card Technology</font></h2>
<hr width="100%" size="2">
<p><font face="Arial, Helvetica, sans-serif">This section gives a very cursory 
  overview of graphics cards that have accessible framebuffer technology, in order 
  to help you understand the concepts used later in the document. If you are considering 
  writing a driver for a video card please contact the manufacturer for documentation 
  on the card. Also, please consider reading some books on video hardware in order 
  to learn more.   </font></p>
<p><font face="Arial, Helvetica, sans-serif">The way framebuffer devices behave 
  under Linux is something very similar to /dev/mem. /dev/fb is in fact viewed 
  as a memory device, except in this case the memory is video ram and is mmaped 
  to userspace for direct access. This model is, of course, simplified for the 
  purpose of making programming the frame buffer much easier as well as making 
  it device and platform independent. Since we are interested in building a driver, 
  we need to understand how exactly the video card itself works.</font></p>
<h3><font face="Arial, Helvetica, sans-serif">2.1 Monitor</font></h3>
<p><font face="Arial, Helvetica, sans-serif">First, lets describe one of the biggest 
  but often overlooked components: the monitor. Today, there exist many types 
  of monitors. Flat screen to LED and so on. For all the many types, the basic 
  principle behind the monitor is the same. Basically, a monitor builds an image 
  sequentially from the data it gets on its input lines. To achieve this, a beam 
  scans over the screen in a kind of &quot;zig-zag&quot; pattern that covers the 
  whole visible part of the screen once per frame. It happens so fast the eye 
  can't see this happening (well, we hope). So which way does this beam go? All 
  monitors have chosen to always go left to right with a quick jump back to the 
  far left when we hit the right boundary of the monitor. Same goes for the top 
  to bottom approach, but at a much slower pace since most of our time is used 
  to move left to right for every single line. Obviously, the displayed data needs 
  to be synchronized with the current position of the beam to be able to build 
  a steady picture. This is what those HSYNC and VSYNC you see in your monitor 
  manual are for. These two lines that say, &quot;hey move the beam to the left 
  now&quot; and &quot;move the ray to the top now&quot;. Some systems encode this 
  information. For example, the green channel, which is called sync on green, 
  but that doesn't change the principle. All a monitor knows about a mode is what 
  it gets that's contained in the frequencies with which those signals return. 
  These frequencies are called the horizontal and vertical frequencies (aka refresh 
  rate), as they determine how often per second a whole image is drawn. A monitor 
  knows nothing about depth, clocks, and borders. If two modes have the same frequencies, 
  they will be the same to the monitor. This is why different centering data for 
  e.g. 640x480x16 and 640x480x32 are not stored in the monitor. The monitor can't 
  distinguish between those modes. Between two HSYNC we get the RGB signals.</font></p>
<table width="90%" border="0" cellspacing="0" cellpadding="0" align="center">
  <tr> 
    <td width="15%"><font face="Arial, Helvetica, sans-serif">HSYNC</font></td>
    <td width="2%">&nbsp;</td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">/</font></td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">-</font></td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">\</font></td>
    <td width="0%">&nbsp;</td>
    <td colspan="10"> 
      <hr width="100%" size="2">
    </td>
    <td width="0%">&nbsp;</td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">/</font></td>
    <td width="0%"><font face="Arial, Helvetica, sans-serif">--</font></td>
    <td width="5%"><font face="Arial, Helvetica, sans-serif">\</font></td>
  </tr>
  <tr> 
    <td width="15%"><font face="Arial, Helvetica, sans-serif">RGB</font></td>
    <td width="2%">&nbsp;</td>
    <td width="2%">&nbsp;</td>
    <td width="2%">&nbsp;</td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="0%">&nbsp;</td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="7%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="0%">&nbsp;</td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">data</font></td>
    <td width="0%">&nbsp;</td>
    <td width="5%">&nbsp;</td>
  </tr>
  <tr> 
    <td width="15%"><font face="Arial, Helvetica, sans-serif">time</font></td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">1</font></td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">2</font></td>
    <td width="2%">&nbsp;</td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">3</font></td>
    <td width="0%">&nbsp;</td>
    <td colspan="10"> 
      <hr width="100%" size="2">
    </td>
    <td width="0%">&nbsp;</td>
    <td width="2%"><font face="Arial, Helvetica, sans-serif">4</font></td>
    <td width="0%">&nbsp;</td>
    <td width="5%"><font face="Arial, Helvetica, sans-serif">5</font></td>
  </tr>
</table>
<p><font face="Arial, Helvetica, sans-serif">At 1, the HSYNC pulse gets raised. 
  The beam will now quickly move to the left. During that time, the RGB lines 
  should be black (ray off), otherwise it would leave a noticeable trace while 
  moving, which would look ugly. </font></p>
<p><font face="Arial, Helvetica, sans-serif">At 2, the HSYNC pulse ends. This 
  point isn't of much interest, as you cannot tell, if the ray is already at the 
  left edge. The only thing important about point 2 is, that the time between 
  point 1 and 2 must be sufficiently high for the monitor to detect the HSYNC 
  signal. Usually, the HSYNC pulse can be made very small.</font></p>
<p><font face="Arial, Helvetica, sans-serif">At some point after 1, the ray will 
  start flying to the right again. When point 3 comes, it will actually start 
  to display data. Point 3 can thus be adjusted to change the left border location. 
  If you wait longer before you start sending data, the left border will move 
  to the right.</font></p>
<p><font face="Arial, Helvetica, sans-serif">When you have sent all data, you 
  reach point 4. As a HSYNC pulse should then be sent to start a new line, we 
  set the RGB lines to black again. At point 5 we have completed a cycle and start 
  the next line.</font></p>
<h3><font face="Arial, Helvetica, sans-serif">2.2 Video card </font></h3>
<p><font face="Arial, Helvetica, sans-serif">Next, we look at the video card point 
  of view. The video card could send out a steady stream of data to the monitor 
  except for one thing. The monitor needs time for retracing so the video card 
  will be put into some &quot;delay&quot; at specific times. To be precise between 
  point 4 and point 1 on the NEXT line on the previous diagram. For the video 
  card, the &quot;natural&quot; coordinate system starts at point 3, when it starts 
  emitting data. This point usually causes some confusion with modeline calculation:</font></p>
<p><font face="Arial, Helvetica, sans-serif">HSYNC __/~~~\______________________________________________/~~~\___</font></p>
<p><font face="Arial, Helvetica, sans-serif">RGB   ___________datadatadatadatadatadatadatadatadatad_____________</font></p>
<p><font face="Arial, Helvetica, sans-serif">time    1   2    3                                    
  4    5   6</font></p>
<p><font face="Arial, Helvetica, sans-serif">grc     SS  SE   0                                    
  W    SS  SE</font></p>
<p><font face="Arial, Helvetica, sans-serif">From the graphics card point of view 
  (grc), a line starts at &quot;0&quot;. From that point onward, it will output 
  the data in its video ram. There is a counter that will limit the number of 
  pixels that are put on one line. This is what we call the width of the mode. 
  On a 640x480 standard VESA mode, this is 640 pixels. </font></p>
<p><font face="Arial, Helvetica, sans-serif">We will usually want a small right 
  border to allow the monitor to prepare for the following SYNC pulse we will 
  generate. The aforementioned counter will run on (but data output from video 
  RAM will be suppressed) until we reach the point SS (SyncStart). On a 640x480 
  standard VGA mode, this happens at 664 pixels. That is, we left a border of 
  24 pixels.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Now we raise the HSYNC to tell the 
  monitor to go left. This signal remains asserted until we reach the point SE 
  (SyncEnd). (760 pixels on VGA - i.e. 96 pixels of sync pulse. This is pretty 
  long, but VGA monitors weren't very quick.)</font></p>
<p><font face="Arial, Helvetica, sans-serif">We will also want some left border, 
  so we wait until we reach the next &quot;0&quot; point before starting to generate 
  a signal again. On standard VGA this happens at 800 pixels (40 pixels left border). 
  At that point, we reset the counter to 0 and start over. This point is usually 
  called the &quot;total&quot; for this reason.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Now let us look at how we can change 
  the picture's appearance by changing values in such a modeline.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Moving SE should not cause any difference 
  at all, except if you make the sync pulse too small for the monitor to recognize.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Moving SS and SE together will move 
  the location of the sync pulse within the picture. Let us assume we move them 
  both to the &quot;left&quot;, i.e. we decrease their startpoints. What happens 
  is, that we decrease the distance W-SS (which determines the right border) and 
  increase 0-SE (the left border). As a result, the picture moves to the right.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Now what happens, if you change W? 
  You get extra pixels at the right border. As usually borders are pretty large 
  for standard VGA modes, you can usually display something like 648x486 without 
  a problem on a standard VGA monitor. You will not be able to see the difference.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Of course, there are limits to this: 
  If you go too far, you will produce pixels beyond the visible area of the monitor 
  (which is useless), or interfere with the retrace, what gives ugly stripes from 
  the retracing CRT ray.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Now let's shed some light on a few 
  remaining terms:</font></p>
<p><font face="Arial, Helvetica, sans-serif">BlankStart BS and BlankEnd BE. Between 
  SE and 0, you can put a BE point on many graphics cards. At that point, the 
  RGB lines are no longer clamped to black (to avoid interfering with the retrace), 
  but can be programmed to a border color. The same goes for BS, which can be 
  placed between W and SS. Usually, one doesn't use that feature nowadays, as 
  we have tunable monitors that allow stretching the mode to the physical limits 
  of the monitor.</font></p>
<p><font face="Arial, Helvetica, sans-serif">On old monitors, one used large borders 
  to ensure the data was always visible. There, the border color made some sense 
  as kind of eye candy.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Pixelclock. That is the rate at which 
  pixels are output to the RGB lines. It is usually the basic unit for all timing 
  values in a graphics card.</font></p>
<p align="center"><font face="Arial, Helvetica, sans-serif"> <a href="index.html">index</a> 
  <a href="1.html">back</a> <a href="3.html">forward </a></font></p>
</body>
</html>

--- NEW FILE: 3.html ---
<html>
<head>
<title>Linux Framebuffer Driver Writing HOWTO</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF">
<h2><font face="Arial, Helvetica, sans-serif">3. Actually calculating a mode</font></h2>
<hr width="100%" size="2">
<p><font face="Arial, Helvetica, sans-serif">If you look at the fbdev driver you 
  think yikes. Yes, it's complex, but not as much as you think. A side note about 
  standard modes -- It's a common misconception that graphics cards cannot do 
  anything but the VGA/VESA induced &quot;standard&quot; modes like 640x480, 800x600, 
  1024x768, 1280x960, ... With most cards, about any resolution can be programmed, 
  though many accelerators have been optimized for the above mentioned modes, 
  so that it is usually NOT wise to use other widths, as one might need to turn 
  OFF accelerator support. So if you write a driver, don't cling to these modes. 
  If the card can handle it, allow any mode.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Here, the type of monitor has a big 
  impact on what kind of modes we can have. There are two basic types of monitors: 
  fixed frequency (they usually can do multiple vertical frequencies, though, 
  which are much less critical, as they are much lower) and multifrequency. </font></p>
<h3><font face="Arial, Helvetica, sans-serif">3.1 Fixed frequency monitors</font></h3>
<p><font face="Arial, Helvetica, sans-serif">The monitor manual says the horizontal 
  frequency (hfreq) is 31.5 kHz.</font></p>
<p><font face="Arial, Helvetica, sans-serif">We want to display a given mode, 
  say 640x480.</font></p>
<p><font face="Arial, Helvetica, sans-serif">We can now already determine the 
  absolute minimum dotclock we need, as</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">dotclock = horiz_total * 
    hfreq</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">and</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">horiz_total = width + right_border 
    + sync + left_border &gt; width</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">The minimum dotclock computes to 
  20.16 MHz. We will probably need something around 20% &quot;slack&quot; for 
  borders and sync, so let's say we need about a 24MHz clock. Now we look at the 
  next higher clock our card can handle, which is 25.175 MHz, as we assume we 
  have a VGA compatible card.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Now we can compute the horizontal 
  total:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">horiz_total = dotclock / 
    hfreq = 799.2</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">We can only program this as multiples 
  of 8, so we round to 800. Now, we still need to determine the length and placement 
  of the sync pulse, which will give all remaining parameters.</font></p>
<p><font face="Arial, Helvetica, sans-serif">There is no clean mathematical requirement 
  for those. Technically, the sync must be long enough to be detected, and placed 
  in a way that the mode is centered. The centering issue is not very pressing 
  anymore, as digitally controlled monitors are common, which allow to control 
  that externally. Generally, you should place the sync pulse early (i.e. keep 
  right_border small), as this will usually not cause artifacts that would arise 
  from turning on the output again too early when the sync pulse is placed too 
  late.</font></p>
<p><font face="Arial, Helvetica, sans-serif">So, if we as a &quot;rule-of-thumb&quot; 
  use a half of the blanking period for the sync and divide the rest as 1/3 right-border, 
  2/3 left border, we get a modeline of:</font></p>
<blockquote> 
  <p><font face="Arial, Helvetica, sans-serif">&quot;640x480&quot; 25.175   640 
    664 744 800  ??? ??? ??? ???</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">While this is not perfectly the same 
  as a standard VGA timing, it should run as well on VGA monitors. The sync is 
  a bit shorter, but that shouldn't be a real problem.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Now, for the vertical timing. At 
  480 lines, a VGA monitor uses 60Hz.</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">hfreq = vfreq * vert_total</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">This yields a vert_total=525. The 
  vertical timings usually use much less overhead than the horizontal ones, as 
  here we count whole lines. This means much longer delays than just pixels. 10% 
  overhead will suffice here and we again split the borders 1/3: 2/3, with only 
  a few lines (say 2) for the sync pulse, as this is already much longer than 
  a HSYNC and thus easily detectable.</font></p>
<blockquote> 
  <p><font face="Arial, Helvetica, sans-serif">&quot;640x480&quot; 25.175   640 
    664 744 800   480 495 497 525</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">Let us compare that to an XF86 modeline 
  that claims to be standard VGA:</font></p>
<blockquote> 
  <p><font face="Arial, Helvetica, sans-serif">Modeline &quot;640x480&quot;     
    25.175 640  664  760  800   480  491  493  525</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">Not much difference - right? They 
  should both work well, just a little shifted against each other vertically.</font></p>
<h3><font face="Arial, Helvetica, sans-serif">3.2 Multiscan monitor</font></h3>
<p><font face="Arial, Helvetica, sans-serif">Here we will consider a theoretical 
  monitor that can do hfreq 31-95kHz and vfreq 50-130Hz. Now, let's look at a 
  640x480 mode. Our heuristics say, that we will need about 768x528 (20% and 10% 
  more) for borders and sync. We want a maximum refresh rate, so let's look what 
  limits the mode:</font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">hfreq = vfreq * vtotal = 
    130 * 528 = 68.6 kHz</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">Oh - we cannot use the full hfreq 
  of our monitor... well no problem. What counts is the vfreq, as it determines 
  how much flicker we see.</font></p>
<p><font face="Arial, Helvetica, sans-serif">O.K. - what pixelclock will we need? 
  </font></p>
<blockquote> 
  <p><font face="Courier New, Courier, mono" size="2">pixclock = hfreq * htotal</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">The calculation yields 52.7MHz.  
  </font></p>
<p><font face="Arial, Helvetica, sans-serif">Now we look what the card can do. 
  Say we have a fixed set of clocks. We look what clocks we have close by. Assume 
  the card can do 50 and 60 MHz.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Now we have a choice: We can either 
  use a lower clock, thus scaling down the refresh rate a bit (by 5% ... so what...): 
  This is what one usually does.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Or we can use a higher clock, but 
  this would exceed the monitor specifications. That can be countered by adding 
  more border, but this is usually not done, as it is a waste of space on the 
  screen. However, keep it in mind as a trick for displaying 320x200, when you 
  do not have doubling features. It will display in a tiny window in the middle 
  of the screen, but it will display.</font></p>
<p><font face="Arial, Helvetica, sans-serif">O.K. - what will our calculation 
  yield?</font></p>
<blockquote> 
  <p><font face="Arial, Helvetica, sans-serif">&quot;640x480&quot;    50   640 
    664 728 768   480 496 498 528 <i># 65kHz 123Hz</i></font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">I just mentioned doubling features. 
  This is how VGA does 320x200. It displays each pixel twice in both directions. 
  Thus it effectively is a 640x400 mode. If this would not be done, you would 
  need a pixelclock of 12.59MHz and you would still have the problem of needing 
  a 140Hz refresh, if hsync should stay at 31.5kHz.</font></p>
<p><font face="Arial, Helvetica, sans-serif">A horizontal doubling feature allows 
  us to use the 25.175MHz clock intended for 640, and a line-doubling feature 
  keeps the vsync the same as 400 lines. Actually the line-doubler is programmable, 
  so you can as well use modes as sick as 640x50.</font></p>
<p><font face="Arial, Helvetica, sans-serif">O.K. - another example. Same monitor, 
  1280x1024.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Now we need about 1536x1126 total 
  (same rule of thumb). That yields 130Hz*1126lines = 146 kHz. We would exceed 
  the hfreq with that, so now the hfreq is the limit and we can only reach a refresh 
  rate of about (95kHz/1126) 84 Hz anymore.</font></p>
<p><font face="Arial, Helvetica, sans-serif">The required clock is now 146MHz. 
  That would yield:</font></p>
<blockquote> 
  <p><font face="Arial, Helvetica, sans-serif">&quot;1280x1024&quot;   146   1280 
    1320 1448 1536   1024 1058 1060 1126 <i># 95kHz 84Hz</i></font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">Now the clock might be programmable, 
  but keep in mind that there may be limits to the clock. <b>DO NOT OVERCLOCK</b> 
  a graphics card. This will result in the RAMDAC producing blurry images (as 
  it cannot cope with the high speed), and more importantly, the RAMDAC will OVERHEAT 
  and might be destroyed.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Another issue is memory bandwidth. 
  The video memory can only give a certain amount of data per time unit. This 
  often limits the maximum clock at modes with high color depth (i.e. much data 
  per pixel). In the case of my card, it limits the clock to 130MHz at 16-bit 
  depth, which would produce:</font></p>
<blockquote> 
  <p><font face="Arial, Helvetica, sans-serif">&quot;1280x1024&quot;   130   1280 
    1320 1448 1536   1024 1058 1060 1126 <i># 85kHz 75Hz</i></font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">This is pretty much what my monitor 
  shows now, if I ask it.</font></p>
<h3><font face="Arial, Helvetica, sans-serif">3.3 Recipe for multisync monitors</font></h3>
<p><font face="Arial, Helvetica, sans-serif">a) Determine the totals by calculating 
  htotal = width*1.2 and vtotal = height*1.1.</font></p>
<p><font face="Arial, Helvetica, sans-serif">b) Check what limits the refresh 
  rate by calculating vfreq2 = hfreqmax/vtotal. If that exceeds vfreqmax, the 
  limit is on the vfreq side and we use vfre = vfreqmax and hfreq = vfreqmax*vtotal. 
  If it doesn't, the mode is limited by hfreq and we have to use vfreq = vfreq2. 
  Note, that if this is smaller than vfreqmin, the mode cannot be displayed. In 
  the vfreq-limited case, you might exceed hfreqmin, which can be countered by 
  using line doubling facilities, if available. You can also add extra blank lines 
  (increase vtotal) as a last-resort alternative.</font></p>
<p><font face="Arial, Helvetica, sans-serif">c) Now that you have hfreq and vfreq, 
  calculate the pixel clock using pixclock=hfreq*htotal. Use the next lower pixel 
  clock. If you are below the lowest clock, you might want to try horizontal doubling 
  features or you will have to pad the mode by increasing htotal.</font></p>
<p><font face="Arial, Helvetica, sans-serif">d) Again, check the monitor limits. 
  You might be violating lower bounds now... In that case you might need to resort 
  to choosing a higher clock and padding as well.</font></p>
<p><font face="Arial, Helvetica, sans-serif">e) You now have pixclock, width, 
  height, htotal and vtotal. Calculate the sync start positions: hss=width+(htotal-width)/2/3; 
  vss=height+(vtotal-height)/3. Make sure to properly align them as required by 
  the video card hardware. hss usually has to be a multiple of 8.</font></p>
<p><font face="Arial, Helvetica, sans-serif">f) SyncEnd is calculated similarly: 
  hse=hss+(htotal-width)/2 and vse=vss+2.</font></p>
<h3><font face="Arial, Helvetica, sans-serif">3.4 Recipe for Monosync</font></h3>
<p><font face="Arial, Helvetica, sans-serif">a) Calculate the number of lines. 
  As hfreq and vfreq are given, vtotal is fixed: vtotal=hfreq/vfreq. If there 
  are multiple vfreqs allowed, choose them according to your desired vtotal (i.e. 
  one that gives the lowest vtotal above what you really need).</font></p>
<p><font face="Arial, Helvetica, sans-serif">b) Calculate the pixelclock. pixclock=hfreq*htotal. 
  htotal starts at the same estimate (width*1.2) we used above.</font></p>
<p><font face="Arial, Helvetica, sans-serif">c) Adjust the pixelclock to hardware-limits. 
  Adjust <b>UP</b>. Now recalculate the htotal=pixclock/hfreq.</font></p>
<p><font face="Arial, Helvetica, sans-serif">d) Go to 3.3. </font></p>
<p><font face="Arial, Helvetica, sans-serif">An important final word. Most video 
  card documentations give you the exact equations needed to set a mode. Here, 
  we give approached values. Use the exact values given in the documents.</font></p>
<h3><font face="Arial, Helvetica, sans-serif">3.5 Colors</font></h3>
<p><font face="Arial, Helvetica, sans-serif">There exist an endless number of 
  colors, but colors have a special property. If you take two colors and mix them 
  together you get a different color. There exist many models to represent colors, 
  but fbdev is based on what is known as the RGB color model. Out of all the colors, 
  there exist three colors in this model which when mixed in different amounts 
  can produce any color. These colors are known as primary colors. There does 
  exist a physical limit to mixing colors. If you take and mix red, green, and 
  blue in equal amounts you get gray. Now if you make each color component equally 
  brighter, the final color will become white. Now their reaches a point when 
  making each component brighter and brighter you will still end up with white. 
  You can increase the intensity of a color component by any amount from some 
  initial value up to this physical limit. This is where the image depth comes 
  in. As you know, on most cards you can have an image depth from one bit to 32 
  bits. Image depth is independent of the mapping from the pixel to the color 
  components. It is also independent of the memory layout to pixel mapping. Note 
  that some cards have a complex mapping from the pixel values to the color components 
  (red, blue, green) as well as video memory to pixel mapping. If this is the 
  case, you will have to consult your documentation on your video card to see 
  what the mapping exactly is. Here are the mappings defined from top to bottom 
  in fbdev starting with the value of the color components:</font></p>
<table width="151" border="0" cellpadding="0" cellspacing="0" align="center">
  <tr align="center"> 
    <td><font face="Courier New, Courier, mono" size="2"> {red, blue, green}</font></td>
  </tr>
  <tr align="center"> 
    <td><font face="Courier New, Courier, mono" size="2"> |</font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_VISUAL_MONO01</i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_VISUAL_MONO10</i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_VISUAL_TRUECOLOR 
      </i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_VISUAL_PSEUDOCOLOR 
      </i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_VISUAL_DIRECTCOLOR 
      </i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_VISUAL_STATIC_PSEUDOCOLOR</i></font></td>
  </tr>
  <tr align="center"> 
    <td><font face="Courier New, Courier, mono" size="2"> |</font></td>
  </tr>
  <tr align="center"> 
    <td><font face="Courier New, Courier, mono" size="2"> pixel value</font></td>
  </tr>
  <tr align="center"> 
    <td height="21"> <font face="Courier New, Courier, mono" size="2"><i>FB_TYPE_PACKED_PIXELS</i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_TYPE_PLANES</i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_TYPE_INTERLEAVED_PLANES</i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_TYPE_TEXT</i></font></td>
  </tr>
  <tr align="center"> 
    <td> <font face="Courier New, Courier, mono" size="2"><i>FB_TYPE_VGA_PLANES</i></font></td>
  </tr>
  <tr align="center"> 
    <td><font face="Courier New, Courier, mono" size="2"> |</font></td>
  </tr>
  <tr align="center"> 
    <td><font face="Courier New, Courier, mono" size="2"> value in video memory</font></td>
  </tr>
</table>
<p><font face="Arial, Helvetica, sans-serif">The way fbdev tells what this video 
  memory to pixel mapping is, is with the type field in </font><i><font face="Courier New, Courier, mono" size="2">fb_fix_screeninfo</font></i><font face="Arial, Helvetica, sans-serif">. 
  Here, I'm going to describe the </font><i><font face="Courier New, Courier, mono" size="2">FB_TYPE_PACKED_PIXELS</font></i><font face="Arial, Helvetica, sans-serif"> 
  layout since it is the most common. Here, there exists a direct mapping from 
  video memory to a pixel value. If you place a 5 in video memory then the pixel 
  value at that position will be 5. This is important when you have memory mapped 
  the video memory to userland. Next, we consider the mapping from a pixel value 
  to the colors. This is represented in the fbdev API by the visual field in </font><i><font face="Courier New, Courier, mono" size="2">fb_fix_screeninfo</font></i><font face="Arial, Helvetica, sans-serif">. 
  As you can see from the above diagram, this mapping is independent from the 
  mapping from video memory to pixel value. This means that </font><i><font face="Courier New, Courier, mono" size="2">FB_TYPE_PLANES</font></i><font face="Arial, Helvetica, sans-serif"><i> 
  </i>could have<i> </i></font><i><font face="Courier New, Courier, mono" size="2">FB_VISUAL_MONO01</font></i> 
  <font face="Arial, Helvetica, sans-serif">just like </font><i><font face="Courier New, Courier, mono" size="2">FB_TYPE_PACKED_PIXELS</font></i><font face="Arial, Helvetica, sans-serif"> 
  can.</font></p>
<p><font face="Arial, Helvetica, sans-serif">To understand visuals, we have to 
  go back to the first types of video hardware. In the beginning there was just 
  monochrome monitors. Here we could only display 2 colors: the foreground and 
  background color. Traditionally, these colors are black and white, but if you 
  are old enough, you would remember the old green monitors. In the fbdev API, 
  we define two types of monochrome modes. The difference between the two is that 
  the foreground and background colors are swapped.</font></p>
<p><font face="Arial, Helvetica, sans-serif">Then computers began to support color. 
  The only problem was they could only display a small number of colors at one 
  time. What if you wanted to have an application display a certain set of colors. 
  Well, the way that was developed to get around this was the idea of a color 
  map. A color map translated a pixel value to the colors needed. If your application 
  needs a specific set of colors it would switch the color maps and you would 
  get the needed colors. Of course, this also switches the other colors in the 
  applications. That was the trade off. This became what is known as pseudocolor 
  mode. In the fbdev API, there exist two types of pseudocolor mappings -- A static 
  one and a dynamic one. </font></p>
<p><i><font face="Courier New, Courier, mono" size="2">FB_VISUAL_STATIC_PSEUDOCOLOR</font></i><font face="Arial, Helvetica, sans-serif"> 
  defines a video card that has a non-programmable color map. What colors you 
  get are what you are stuck with. The other type of color map can be changed.</font></p>
<p><font face="Arial, Helvetica, sans-serif">In time, video cards started to support 
  more colors but this required having a larger color map. Also, video memory 
  prices started to drop and video cards began to sell with more of it. To properly 
  support 256 color intensity levels for each color component, you would need 
  a color map of 16 million colors. New mappings where developed in which specific 
  fields of a pixel where directly proportional to the intensity of a color component. 
  Two types of mappings were developed -- One being truecolor and the other directcolor. 
  </font></p>
<p><font face="Arial, Helvetica, sans-serif">In truecolor, you cannot change the 
  mappings from the pixel value to color intensities. Setting a value of 64 to 
  the red component of the pixel will result in a red intensity of 64. How bright 
  of a red this is depends on the image depth. For directcolor, you can control 
  this. You could make a pixel value in the red field of 64 equal 128 for the 
  intensity. Also some cards support an alpha value, which is used in higher graphics, 
  which for fbdev is of little importance. It should always be set to the highest 
  value it can have. For most cards, alpha shows up for 15-bit modes where each 
  color component can have up to 32 intensity levels (2^5) and one bit represents 
  the alpha component. It also shows up for 32-bit modes where each component 
  red, blue, green, and alpha are given 256 intensity levels (2^8). 24-bit mode 
  is like 32-bit mode except it lacks the alpha component. An important note is 
  that some cards only support 24-bit mode on certain architectures.</font></p>
<p align="center"><a href="index.html"><font face="Arial, Helvetica, sans-serif">index</font></a> 
  <a href="2.html"><font face="Arial, Helvetica, sans-serif">back</font></a> <a href="4.html"><font face="Arial, Helvetica, sans-serif">forward</font></a></p>
</body>
</html>

--- NEW FILE: 4.html ---
<html>
<head>
<title>Linux Framebuffer Driver Writing HOWTO</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF">
<h2>4.  Framebuffer internal API</h2>
<hr width="100%" size="2">
Now that we understand the basic 
 ideas behind video card technology and mode setting, we can now look at how 
 the framebuffer devices abstract them. Also, we will see that fbdev actually 
 handles most of the mode setting issues for you to make life much easier. In 
 the older API, the console code was heavily linked to the framebuffer devices. 
 The newer API has now moved nearly all console handling code into fbcon itself. 
 Now, fbcon is a true wrapper around the video card&#146;s abilities. This allows 
 for massive code reduction and easier driver development. A good example of 
 a framebuffer driver is the virtual framebuffer (vfb). The vfb driver is not 
 a true framebuffer driver. All it does is map a chunk of memory to userspace. 
 It's used for demonstration purposes and testing.
<h3>4.1 Data Structures</h3>
The framebuffer drivers depend heavily 
 on four data structures. These structures are declared in fb.h. They are fb_var_screeninfo, 
 fb_fix_screeninfo, fb_monospecs, 
 and fb_info. The first 
 three can be made available to and from userland. First let me describe what 
 each means and how they are used.
fb_var_screeninfo 
 is used to describe the features of a video card you normally can set. With 
 fb_var_screeninfo, you 
 can define such things as depth and the resolution you want.
The next structure is fb_fix_screeninfo. 
 This defines the properties of a card that are created when you set a mode and 
 can't be changed otherwise. A good example is the start of the framebuffer memory. 
 This can depend on what mode is set. Now while using that mode, you don't want 
 to have the memory position change on you. In this case, the video hardware 
 tells you the memory location and you have no say about it.
The third structure is fb_monospecs. 
 In the old API, the importance of fb_monospecs 
 was very little. This allowed for forbidden things such as setting a mode of 
 800x600 on a fix frequency monitor. With the new API, fb_monospecs 
 prevents such things, and if used correctly, can prevent a monitor from being 
 cooked.
The final data structure is fb_info. 
 This defines the current state of the video card. fb_info 
 is only visible from the kernel. Inside of fb_info, 
 there exist a fb_ops which 
 is a collection of needed functions to make fbdev and fbcon work.
<h3>4.2 Driver layout</h3>
Here I describe a clean way to code 
 your drivers. A good example of the basic layout is vfb.c. In the example driver, 
 we first present our data structures in the beginning of the file. Note that 
 there is no fb_monospecs 
 since this is handled by code in fbmon.c. This can be done since monitors are 
 independent in behavior from video cards. First, we define our three basic data 
 structures. For all the data structures I defined them static and declare the 
 default values. The reason I do this is because it's less memory intensive than 
 to allocate a piece of memory and filling in the default values. Note that drivers 
 that support multihead (multiple video cards) of the same card, then the fb_info 
 should be dynamically allocated for each card present. For fb_var_screeninfo 
 and fb_fix_screeninfo, 
 they still are declared static since all the cards can be set to the same mode.
<h3>4.3 Initialization and boot time 
 parameter handling</h3>
There are two functions that handle 
 the video card at boot time:
<blockquote> 
 <pre>int xxfb_init(void);
int xxfb_setup(char*);</pre>
</blockquote>
In the example driver as with most 
 drivers, these functions are placed at the end of the driver. Both are very 
 card specific. In order to link your driver directly into the kernel, both of 
 these functions must add the above definition with extern in front to fbmem.c. 
 Add these functions to the following in fbmem.c:
<blockquote> 
 <pre>static struct {
     const char *name;

</i></font><font face="Courier New, Courier, mono"><i>     int (*init)(void);
</i></font><font face="Courier New, Courier, mono"><i>     int (*setup)(char*);</i></font></pre>
  <pre><font face="Courier New, Courier, mono"><i>} fb_drivers[] __initdata = {
</i></font><font face="Courier New, Courier, mono"><i>#ifdef CONFIG_FB_YOURCARD
</i></font><font face="Courier New, Courier, mono"><i>     { &quot;driver_name&quot;, xxxfb_init, xxxfb_setup },
</i></font><font face="Courier New, Courier, mono"><i>#endif</i></font></pre>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">Setup is used to pass card specific 
  options from the boot prompt of your favorite boot loader. A good example is:</font></p>
<blockquote> 
  <p><font face="Arial, Helvetica, sans-serif">boot: video=matrox: vesa: 443</font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">The basic setup function is:</font></p>
<blockquote> 
  <pre><font face="Courier New, Courier, mono"><i>int __init xxxfb_setup(char *options)
</i></font><font face="Courier New, Courier, mono"><i>{
    </i></font><font face="Courier New, Courier, mono"><i>char *this_opt;

    </i></font><font face="Courier New, Courier, mono"><i>if (!options || !*options)
        </i></font><font face="Courier New, Courier, mono"><i>return 0;</i></font></pre>
  <pre><font face="Courier New, Courier, mono"><i>    for (this_opt = strtok(options, &quot;,&quot;); this_opt;
        </i></font><font face="Courier New, Courier, mono"><i>this_opt = strtok(NULL,      &quot;,&quot;))</i></font></pre>
  <pre><font face="Courier New, Courier, mono"><i>        if (!strcmp(this_opt, &quot;my_option&quot;)) {
        </i></font><font face="Courier New, Courier, mono"><i>/* Do your stuff. Usually set some static flags that the driver later uses */</i></font></pre>
  <pre><font face="Courier New, Courier, mono"><i>        } else if (!strncmp(this_opt, &quot;Other_option:&quot;, 5))
            </i></font><font face="Courier New, Courier, mono"><i>strcpy(some_flag_driver_uses, this_opt+5);
        </i></font><font face="Courier New, Courier, mono"><i>} else ....
    }
</i></font><font face="Courier New, Courier, mono"><i>}</i></font></pre>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">The <i>xxfb_init</i> function sets 
  the initial state of the video card. This function has to consider bus and platform 
  handling since today most cards can exist on many platforms. For bus types we 
  have to deal with, there are PCI, ISA, and zorro. Also, some platforms offer 
  firmware that returns information about the video card. In this case, we often 
  don't need to deal with the bus unless we need more control over the card. Let 
  us look at Open Firmware that&#146;s available on PowerPCs. If you are going 
  to use Open Firmware to initialize your card, you need to add the following 
  to offb.c.</font></p>
<blockquote> 
  <pre><font face="Courier New, Courier, mono"><i>#ifdef CONFIG_FB_YOUR_CARD
</i></font><font face="Courier New, Courier, mono"><i>extern void xxxfb_of_init(struct device_node *dp);
</i></font><font face="Courier New, Courier, mono"><i>#endif /* CONFIG_FB_YOUR_CARD */</i></font></pre>
  <pre><font face="Courier New, Courier, mono"><i>Then in the function offb_init_driver, you add something similar to the following:</i></font></pre>
  <pre><font face="Courier New, Courier, mono"><i>#ifdef CONFIG_FB_YOUR_CARD
</i></font><font face="Courier New, Courier, mono"><i>if (!strncmp(dp-&gt;name,&quot;Open Firmware number of your card &quot;, size_of_name)) {
    </i></font><font face="Courier New, Courier, mono"><i>xxxfb_of_init(dp);
    </i></font><font face="Courier New, Courier, mono"><i>return 1;
</i></font><font face="Courier New, Courier, mono"><i>}
</i></font><font face="Courier New, Courier, mono"><i>#endif /* CONFIG_FB_YOUR_CARD */</i></font></pre>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif">If Open Firmware doesn't detect your 
  card, Open Firmware sets up a generic video mode for you. Now in your driver 
  you really need two initialization functions. </font></p>
<p><font face="Arial, Helvetica, sans-serif">The next major part of the driver 
  is declaring the functions of <i><font face="Courier New, Courier, mono">fb_ops</font></i> 
  that are declared in <i><font face="Courier New, Courier, mono">fb_info</font></i><font face="Courier New, Courier, mono"> 
  </font>for the driver. </font></p>
<p><font face="Arial, Helvetica, sans-serif">The first two functions,<i> <font face="Courier New, Courier, mono">xxfb_open</font></i> 
  and <i><font face="Courier New, Courier, mono">xxfb_release</font></i>, can 
  be called from both fbcon and fbdev. In fact, that's the use of the user flag. 
  If user equals zero then fbcon wants to access this device, else it's an explicit 
  open of the framebuffer device. This way, you can handle the framebuffer device 
  for the console in a special way for a particular video card. For most drivers, 
  this function just does a <i><font face="Courier New, Courier, mono">MOD_INC_USE_COUNT</font></i> 
  or <i><font face="Courier New, Courier, mono">MOD_DEC_USE_COUNT</font></i>.</font></p>
<p><font face="Arial, Helvetica, sans-serif">These are the functions that are 
  at the heart of mode setting. There do exist a few cards that don't support 
  mode changing. For these we have this function return an -EINVAL to let the 
  user know he/she can't set the mode. Actually, set_var does more than just set 
  modes. It can check them as well. In <i><font face="Courier New, Courier, mono">fb_var_screeninfo</font></i>, 
  there exists a flag called activate. This flag can take on the following values: 
  <i><font face="Courier New, Courier, mono">FB_ACTIVATE_NOW</font></i>, <i><font face="Courier New, Courier, mono">FB_ACTIVATE_NXTOPEN</font></i>, 
  and <i><font face="Courier New, Courier, mono">FB_ACTIVATE_TEST</font></i>. 
  </font></p>
<p><font face="Arial, Helvetica, sans-serif"><i><font face="Courier New, Courier, mono">FB_ACTIVATE_TEST</font></i> 
  tells us if the hardware can handle what the user requested. <i><font face="Courier New, Courier, mono">FB_ACTIVATE_NXTOPEN</font></i> 
  sets the values wanted on the next explicit open of fbdev. The final one <i><font face="Courier New, Courier, mono">FB_ACTIVATE_NOW</font></i><font face="Courier New, Courier, mono"> 
  </font>checks the mode to see if it can be done and then sets the mode. You 
  MUST check the mode before all things. Note that this function is very card 
  specific, but I will attempt to give you the most general layout. The basic 
  layout then for <font face="Courier New, Courier, mono">xxxfb_set_var</font> 
  is:</font></p>
<blockquote> 
  <pre><font face="Courier New, Courier, mono"><i>static int vfb_set_var(struct fb_var_screeninfo *var, struct fb_info *info)
</i></font><font face="Courier New, Courier, mono"><i>{
    int line_length;</i></font></pre>
  <blockquote> 
    <pre><font face="Courier New, Courier, mono"><i>/* Basic setup test. Here we look at what the user passed in that he/she wants.
   For example to test the fb_var_screeninfo field vmode like its done in vfb.c.
   Here we see if the user has FB_VMODE_YWARP. Also we should look to see if
   the user tried to pass in invalid values like 17 bpp (bits per pixel) */</i></font></pre>
    <pre><font face="Courier New, Courier, mono"><i>/* Remember the above discussion on how monitors see a mode. They don't care
   about bit depth.  So you can divide the checking into two parts. One is to
   see if the user changed a mode from say 640x480 at 8 bpp to 640x480 at 32 bpp.
   Remember the var in fb_info represents the current video mode. Before we
   actually change any resolutions we have to make sure the card has enough 
   memory for the new mode. Discovering how much memory a video card has varies
   from card to card.  Also finding out how much memory we have is done in
   xxxfb_init since this never changes unless you add more memory to your card,
   which requires a reboot of the machine anyway. You might have to do other
   tests depending on make of your card. Note the par filed in fb_info. This
   is used to store card specific data. This data can affect set_var. Also it
   is present to allow other possible drivers that could effect the framebuffer
   device such as a special driver for an accel engine or memory mapping the
   Z buffer on a card */</i></font></pre>
    <pre><font face="Courier New, Courier, mono"><i>/* Summary. First look at any var fields to see if they are valid. Next test
   hardware with these fields without setting the hardware. An example of one
   is to find what the line_length would be for the new mode. Then test the
   following: */</i></font></pre>
  </blockquote>
  <pre><font face="Courier New, Courier, mono"><i>     if ((line_length * var-&gt;yres_virtual) &gt; info-&gt;fix.smem_len)
        return -ENOMEM; </i></font></pre>
  <pre><font face="Courier New, Courier, mono"><i>    if (info-&gt;var.xres != var-&gt;xres || info-&gt;var.yres != var-&gt;yres ||
        info-&gt;var.xres_virtual != var-&gt;xres_virtual ||
        info-&gt;var.yres_vitual != var-&gt;yres_virtual) {

        /* Resolution changed !!! */

        /* Next you must check to see if the monitor can handle this mode. Don't
           want to fry your monitor or mess up the display really badly */</i></font></pre>
  <pre><font face="Courier New, Courier, mono"><i>        if (fbmon_valid_timings(u_int pixclock, u_int htotal, u_int vtotal,
                                              const struct fb_info *fb_info))
    </i></font><font face="Courier New, Courier, mono"><i>   /* Can't handle these timings. */
           </i></font><font face="Courier New, Courier, mono"><i>return -EINVAL;</i></font></pre>
  <blockquote> 
    <pre><font face="Courier New, Courier, mono"><i>    /* Timings are okay. Next we see if we really want to change this mode */
    </i></font><font face="Courier New, Courier, mono"><i>if ((activate &amp; FB_ACTIVATE_MASK) == FB_ACTIVATE_NOW) {

        </i></font><font face="Courier New, Courier, mono"><i>/* Now lets program the clocks on this card. Here the code is
           very card specific. Remember to change any fields for fix in
           info that might be affected by the changing of the resolution. */
        </i></font><font face="Courier New, Courier, mono"><i>info-&gt;fix.line_length      = line_length;</i></font></pre>
  </blockquote>
  <blockquote> 
    <pre><font face="Courier New, Courier, mono"><i>        /* Now that we have dealt with the possible changing resolutions lets
           handle a possible change of bit depth. */
        </i></font><font face="Courier New, Courier, mono"><i>if (info-&gt;var.bits_per_pixel != var-&gt;bits_per_pixel) {
            </i></font><font face="Courier New, Courier, mono"><i>if ((err = fb_alloc_cmap(&amp;info-&gt;cmap, 0, 0)))
                </i></font><font face="Courier New, Courier, mono"><i>return err;
        </i></font><font face="Courier New, Courier, mono"><i>}
    </i></font><font face="Courier New, Courier, mono"><i>}</i></font></pre>
  </blockquote>
  <blockquote> 
    <pre><font face="Courier New, Courier, mono"><i>    /* We have shown that the monitor and video card can handle this mode or
       have actually set the mode.  Next the fb_bitfield structure in
       fb_var_screeninfo is filled in. Even if you don't set the mode you get
       a feel of the mode before you really set it. These are typical values
       but may be different for your card. For truecolor modes all the fields
       matter. For pseudocolor modes only the length matters.  Thus all the
       lengths should be the same (=bpp). */
    </i></font><font face="Courier New, Courier, mono"><i>switch (var-&gt;bits_per_pixel) {
        </i></font><font face="Courier New, Courier, mono"><i>case 1:
        </i></font><font face="Courier New, Courier, mono"><i>case 8:
        </i></font><font face="Courier New, Courier, mono"><i>    /* Pseudocolor mode example */
        </i></font><font face="Courier New, Courier, mono"><i>    var-&gt;red.offset    = 0;
        </i></font><font face="Courier New, Courier, mono"><i>    var-&gt;red.length    = 8;
</i></font><font face="Courier New, Courier, mono"><i>            var-&gt;green.offset  = 0;
</i></font><font face="Courier New, Courier, mono"><i>            var-&gt;green.length  = 8;
</i></font><font face="Courier New, Courier, mono"><i>            var-&gt;blue.offset   = 0;
</i></font><font face="Courier New, Courier, mono"><i>            var-&gt;blue.length   = 8;
</i></font><font face="Courier New, Courier, mono"><i>            var-&gt;transp.offset = 0;
</i></font><font face="Courier New, Courier, mono"><i>            var-&gt;transp.length = 0;
</i></font><font face="Courier New, Courier, mono"><i>            break;
        </i></font><font face="Courier New, Courier, mono"><i>case 16:        /* RGB 565 */
            </i></font><font face="Courier New, Courier, mono"><i>var-&gt;red.offset    = 0;
 </i></font><font face="Courier New, Courier, mono"><i>           var-&gt;red.length    = 5;
 </i></font><font face="Courier New, Courier, mono"><i>           var-&gt;green.offset  = 5;
 </i></font><font face="Courier New, Courier, mono"><i>           var-&gt;green.length  = 6;
 </i></font><font face="Courier New, Couri...

[truncated message content]

[Linuxconsole-commit]CVS: ruby/web/htdocs/fbdev/HOWTO 1.html,NONE,1.1 2.html,NONE,1.1 3.html,NONE,1.

[Linuxconsole-commit]CVS: ruby/web/htdocs/fbdev/HOWTO 1.html,NONE,1.1 2.html,NONE,1.1 3.html,NONE,1.1 4.html,NONE,1.1 index.html,NONE,1.1