svgalib.faq(7)

NAME
svgalib.faq - frequently asked questions about svgalib

INTRODUCTION
List of (recently) frequently asked questions about svgalib. Esp. about it's status and future. Please note that as of now all answers are just written by me, Michael Weller <eowmob@exp-math.uni-essen.de>. I'd like this to change. So email your suggestion (best of all: question and the answer). Also, most questions deal with the status and future and my ideas about it. Necessarily they contain my own private opinions on this. People may disagree and I'm sure I don't have the best ideas about it or may even be completely wrong. I don't want to force anyone to agree with me. Also, I was asked about MY opinions, so I'm just presenting them here.

CONTENTS

Q 1)
    I want to write some svgalib application. Where is the documentation?

Q 2)
    My board is not supported. What now?

Q 3)
    I get: You must be the owner of the current console to use svgalib.
    Not running in a graphics capable console, and unable to find one. However, though logged in not directly from the linux console, I am the owner of the console.

Q 4)
    Is svgalib dead?

Q 5)
    There are so many Xfree drivers, why not just use them.

Q 6)
    Why not just use the VGA BIOS?.

Q 7)
    What about GGI?

Q 8)
    Why not just use X11?

Q 9)
    Now, again, what about the future of svgalib?

Q 10)
    Ok, just for completeness, what are your plans about svgalib anyway?

Q 11)
    Nice plan. But will it become true?

THE QUESTIONS

  Q 1)
I want to write some svgalib application. Where is the documentation?

  A a)
Well, did you really look at everything? The 0-README file in the top level directory contains all function prototypes and explanations on how to call them. Yes, the documentation is short and/or confusing. Sorry, English is not my native tongue. Many people complain and want to write some better documentation. You are welcome to do so! However, up to now, either people found the documentation sufficient once they looked at the correct files or they just gave up. At least, I never heard from these people again. Also, svgalib comes with source. If in doubt: read it. Finally: Linux distributions include svgalib, but not the source and README's (or hide them so good noone finds them). Well, no problem, get full svgalib source, demos, readme's from svgalib-*.tar.gz on any Linux FTP server in your vicinity. Even if you don't dare to install or compile it, it contains the readme's. Oh yes, there are some simple demos in the demos/ subdir. They should get you started. When someone writes man(1) manual pages, a distribution might just install them. Please do not complain, write them, mail them to me.

  A b)
Finally, I, Michael Weller wrote the manpages. Looking at svgalib(7) should get you started. Additions and corrections are still welcome, of course.

  Q 2)
My board is not supported. What now?

  A)
Simple:

a)  Contact the maintainers (see other README's) and check out if someone is working on a driver.

b)  If so, contact them if you like and announce you'd be willing to test things or even help coding.

c)  If not, write a driver. Get as many docs on your card as you can, then read and understand the internals of svgalib (again read the README's carefully!).

Please understand that this is a free project. I will not go and buy a similar card and write a driver for you. I already wrote support for the hardware I have! I just do this as a hobby. Because I don't get paid for this I can not just buy card & docu and spend much much time supporting whatever graphics card on earth exists. Also read below on the future of svgalib. If you don't feel able to write a driver for whatever reason, please do not complain if other people don't do it for you (because you are not better than they are).

  Q 3)
I get: You must be the owner of the current console to use svgalib.
Not running in a graphics capable console, and unable to find one. However, though logged in not directly from the linux console, I am the owner of the console.

  A)
Alas, some programs use their suid root priviledge and become a full root owned process. svgalib thinks they are run by root which does not own the current console. Defining ROOT_VC_SHORTCUT in Makefile.cfg and recompiling will allow svgalib to allocate a new VC. However, it will allow any person which is able to exec that program to start in on a new console. Even if not logged in from the console at all. Thus, for security, you need to explicitly enable that root feature.

  Q 4)
Is svgalib dead?

  A)
This question comes up frequently esp. in recent times. The answer is difficult indeed: Yes, svgalib has been developing slowly in recent times. Also, I must admit that I have much too little time and stomach to push svgalib further. In the .lsm file I still list myself as temporary maintainer. I did not write or invent svgalib at all. However, when Harm Hanemaayer had to stop working on it for a while, I agreed on collecting patches, enhancements, fixes in a single position and answering questions. Personally, I must admit that svgalib is not perfect as of now. Most of its code is a bit weird because it was developed over a long time by many different people. More drivers are needed. Better stability is required.

  Q 5)
There are so many Xfree drivers, why not just use them.

  A)
Well, actually much of the code in there is actually already used by svgalib. Xfree coders worked on svgalib and vice versa. But honestly, do not expect that a driver from Xfree can just be used for svgalib. The internal structures of Xfree and svgalib (and GGI) are just too different. As a source of knowledge and for one or the other subroutine, the Xfree sources are invaluable however.

  Q 6)
Why not just use the VGA BIOS?.

  A)
Actually, we do. There is now, thanks to Josh Vanderhoof, a VESA driver. The VESA driver does not work on all cards, even though it should. It does not even work on all cards where vbetest works. If vbetest does not work it means the bios writers assumed it would always run in DOS, and used tricks (for delay, etc.) that can't work under Linux. If vbetest works, but the VESA driver does not, I (Matan Ziv-Av) believe it is due to the following reason: The driver use VESA function 4 (save/restore video state). This function can't be used in a singletasking environment (DOS) and as such, some bios writers failed to implement it properly, and all the tests (which are run under DOS) failed to discover this. The VESA driver does work with many cards though.

  Q 7)
What about GGI?

  A)
Yes, GGI. Another long story. At first: Yes, I like the idea of an in kernel graphics driver. I like it very much. And, yes, this is a bit weird because I am the svgalib maintainer and a working GGI will make svgalib obsolete. Again, I already said above: I did not invent svgalib nor do I promote it as the solution (now compare this to GGI). It just does what it does and works for me and some other people. I liked this idea so much, I even started coding a frame buffer device once. After a short time, other people came out with the GGI idea. Right from their beginning they claimed to be the only source of wisdom. I tried to join our efforts, but failed. In general we have the same goals (read the GGI project pages for that). Anyhow, at that time a flame war started. I don't really know why. I don't see I did anything else than offering my opinions, work and experience. But that should be judged by others. Well, after some time I stopped bothering them. I was satisfied to learn later though that they actually came up with some conclusions I proposed first but weeks or months later. But let us leave the past alone.

When intending to contribute to svgalib, you should think about what you really want. I don't see that GGI is becoming available soon. GGI people told me the opposite again and again, ok, I still don't see it. Still out of a sudden, everything might be GGI infested, so you might consider contributing to GGI instead. With svgalib you might be able to use your fruits earlier. And anyone (with supported hardware) can just use it right away without reinstalling kernel/X11 what else (maybe being unable to use something he did before).

  Q 8)
Why not just use X11? Yes, this is what many people say. This is the common Unix way to do it. X does it. But X has some drawbacks:

i)  It uses many resources. Admittedly this is becoming of lesser importance now, where you can run a sensible X11 Linux system on 8MB (16 MB for heaven like performance) which is the absolute minimum to get a simple text editor running under M$ windows. Still, an advantage of Linux is the ability to use old hardware for mission critical background jobs on the net (servers/routers/firewalls) on low price or otherwise even unusable hardware.

ii) X has a nice API with draw commands for any kind of 'command oriented' screen output. I mean with that: Select a color, draw a line, polygon, etc. This imposes a bunch of overhead. If you just want access to the screen memory, it slows things down as hell. If you want just to use above's draw commands, it is ok!

iii)
    One can now circumvent the API restrictions by getting direct screen access using a special Xfree extension. Basically Xfree just setups the screen and gives you shared memory access to the screen memory. IMHO, this is not much different from the shared memory X11 extension by MIT (which is probably why it was added so easily). Still it needs quite some overhead, at least when the card does not allow for a linear frame buffer. However, you cannot change screen modes and rez as easily. This is IMHO THE drawback of X. For a picture viewer, you want 256 color high/true color modes on a per picture basis (also, insert any other application you like: movie viewers, a special game, a drawing program). Also, you want a small picture use a low rez s.t. it does not appear as a thumbnail, maybe use a high rez mode for a huge picture which you don't want to use on a permanent basis because it flickers like hell (and you don't want to use a panning virtual desktop too, I hated them at best). This latter restriction can of course be circumvented by enlarging the picture. But this will need much time for a picture viewer already and certainly too much for smooth video or game animations.

iv) Finally, the problem how X11 itself accesses the screen is not solved. Security is usually no concern because X11 does it, is a trusted executable and a firewall between applications and the hardware. Alas, there might be security holes, also the stability and performance issues (IRQ driven accelerator queue, CPU support for VGA memory paging) still exist, though one can expect an Xserver to be a generally well coded application.

  Q 9)
Now, again, what about the future of svgalib? Honestly. I don't know... My major problem is that at least I am really lacking the time. I have a few ideas, but they'll need time. Time which I don't have. Also, implementing them will need much effort. More than a single person has. Applications need to be recoded. Device drivers need to be written (which is a) much work and b) an author with the hardware is always needed). Also, the future of svgalib is uncertain. Why develop a new API when noone will write applications for it? Why redesign the internals when noone will write a driver for it? For me the status quo right now is enough. I don't miss anything. I'd like to at least push svgalib into another direction, but I need people willing to contribute on the svgalib and application side.

  Q 10)
Ok, just for completeness, what are your plans about svgalib anyway? i) Similar to the GGI people, I think the kernel must become the major control instance for VC switching. Also it is bad that root privilege is required for screen access. Finally, it would be great if some memory paging could be used to automatically do VGA window paging as well as using interrupts for optimal usage of an accelerator queue WITHOUT any busy waiting. Honestly, the latter two things can be done WITHOUT kernel support. The memory paging can be performed with well thought over mmap/munmap calls (just mmap the currently visible VGA window, munmap the others; if an unmapped window is accessed you get a SIGSEGV. Within the handler you can use Linux specifics to get hold of the faulting address in the signal handler and do appropriate remaps; You might say that the many user/kernel space transitions will cost time. Yes, but the faults will only occur occasionally, and the port accesses to do the window change on the card are usually much slower anyway.) For the usage of interrupts, yes, you must be in kernel space to do it. But, a very simple device driver loadable module could just hook in an interrupt handler. An application registers with it and receives a signal when an interrupt occurs. I even think a beast like this already exists for dosemu. Simple thing, no main kernel changes are required. However, for this handler, irq response might be bad. I dunno, but should be worth a try. Unfortunately, doing this from user space does not interest me personally because I think its wrong. If you want to do it, go on though. I just don't feel like working on that myself. ii) However, other than GGI, I'd tend more to a less invasive solution. Acceptance for this project is low. The Unix way to do it is that you don't do it. X accesses the hardware directly and that's it. This has no such permission problems (as the X server is always trusted), for performance and mode selection limits, there is no way to solve them, and on the few commercial systems which allow several X servers up at the same time (used by other users or running in different resolutions), stability is low. Any such commercial system I saw can be easily screw the console till the next reboot by switching between X servers quickly. Thus, I'd propose to simply add a few hooks to the main kernel. The distributed kernel will not change in any respect, only gain a few K. It will just provide a means for a module to registers functions which will be called during certain console ioctl calls as well as during VC switches. Then a (loadable for those who want it) module will hook into this and provide secure grafix VC switching. Old applications (old svgalib, Xfree and X) will continue to work and coexist with new applications. Of course, they'll still suffer from the stability constraints of the old interface. As a more detailed proposal, look on the VC switching module functions in ALPHA/scrdrv/fb.10Jun95.0030.tar.gz at tsx-11.mit.edu and mirrors. I don't think the GGI way of declaring all other approaches as devil's work and replace everything as well as make any other application be forced to use their clean approach or not work is right. Live and let live. It is not sensible to assume that one is able to not use an Xfree or commercial Xserver and just stick to GGI applications right now. This bad attitude of the GGI people will finally kill their project, if it didn't already. This is a pity because the general idea and concept is good and needed. When there is not any grafix interface within Linux in the future it is IMHO their and their attitudes fault. This is a dead end in Linux's and general OS development. And GGI is guilty. iii) As kernel memory is not pageable and to reduce work in this critical area, only the absolute minimum code must go in the kernel memory. From my experience, all you need is a discrete set of modes to set from a table plus a flexible mmap() API and ioctl() calls to set a few basic things (video memory start offset, logical width, force a memory page offset to emulate vga_setpage in a svgalib emulation library) Someone (sorry, forgot the name), made a related proposal which made me come up with this idea: To support a certain grafix board, load a table into the kernel (could be either compiled into the module or loaded by a setup tool at system boot). The table will contain an entry for each port used by the card with the following data:

-   size of the port (8/16/32 bit).

-   a flag for memory mapped or i/o mapped (in/out asm instructions).

-   a memory or i/o address where to write data for the port.

-   a memory or i/o address where to read back that data from the port (or a flag indicating this is impossible/inefficient. The driver will then store any data written to the port in a shadow buffer where it can be queried).

-   a bitmap of the bits which may be modified in that register.

The advantages are obvious: From this card specific table, generic routines can be written to

1)  get the current card's status, store it somewhere and set the card back to this state (note: the order in which the port table is setup may be of relevance).

2)  Write an interpreter for a simple control language. Unfortunately 256 such port definitions will be too restrictive for some cards, so we need to allow for at least 65536 such entries. The byte machine, should have a few (4 or 8 or something) registers and and should allow for commands to get a VGA card reg #n (in the table) in such a register, store a register value to a VGA card reg., do basic logic operations (and, or, xor, left right shift) with the registers. The mode tables to setup a certain mode on the card are then stored by a bunch of byte code for this machine. Together with a few more tiny commands (say: 'return OK if non-zero', 'return FAIL if non-zero', 'set' (set a register to a value (maybe just -1) in case it is non-zero in any bit)) it would even be possible to add some detection code which will ensure the selected card is really there. YES, this will add overhead and slow things down. But you gain much by means of portability, the access of the card's ports is slow anyway and will certainly outweigh anything here. Also, it is only used for mode setup which is slow anyway.

3)  A utility, a mode compiler, can be written. It will work as follows: Detect any supported hardware from usermode. Read a nice written config file of mode timings, compile above byte code and store it into the kernel at system boot time. All this is done from usermode. The kernel will just keep the byte code for EXACTLY your setup. The utility could be enhanced to allow for interactive mode setup and fine tuning. Once set, the data is stored into a nice config file. That utility will be required to be run by root. But this is no problem. It is just used during installation/boot time. That utility would be the almost sole place for card specific code.

4)  Utilities either for Dos or Dosemu can be written. In a basic way, dosemu already supports this technique. For a new card of unknown type, simply ask the BIOS to setup the corresponding graphics mode. As well, ask the BIOS to do a page flip. The utility will report all i/o port accesses done by the BIOS. This info can be used to write a basic driver. Probably you'll just need a data file to do it. With the right utilities, Joe blow user can support his board in a basic fashion. iv) For the VC switching under kernel control, a major objection against it is that it will need much in kernel memory. And yes, VC switching is done in an interrupt handler and to store/restore grafix screen you need to copy it to memory. Alas, you cannot access an application's memory because it might be paged away and Linux can page it back in from the irq handler environment. Also, even when executing a kernel call, application A cannot read application B's memory if it is not accidently in memory (because it can not page back in any of B's memory). I found the following work around: We do NOT store/restore grafix screen in the IRQ. Instead, we only store the single 64K page which the kernel uses for its text console. Also, we only need one such 64K for all possible grafix VC's. We'd also need to store any other per application stats (accelerator state, color lookup table) but this will again only be a few K. Don't worry about that. For each Textconsole the kernel already allocates several K for the screen contents. Now, during a VC switch when a grafix console is active, the kernel stores these 64K away and sets the card back to textmode. Then operation continues as usual. Actually the rest of the screen contents just remains in VGA memory and is not copied ANYWHERE! In case another (old style) grafix application acquires the card in grafix by an ioctl() or a (new style) grafix application gets a page fault by accessing some vga memory or makes an ioctl to access the card, we allocate new memory pages for the screen contents, copy them and put them into the memory tables of the application which actually owns this grafix console. We cannot reliably access pageable memory of another application, but we can give new pageable memory to another application! To speedup the grafix display of a switched to application if it does not make any screen accesses, we send it a signal. In response it shall make some dummy call. In a future version one could actually add a hook to schedule which will make an update next time the application is scheduled. The worst thing that will happen for an application blocked in an uninteruptible I/O operation or simply crashed is that the grafix VC of this application will NOT be displayed (instead you see it's ASCII VC). As the application is broken this seems ok to me. Any other application is NOT affected at all. I had this basically running in that fb snapshot above. Alas, I never did come to a non Mach32 driver for it. (Because I only have a mach32, and a vga driver is boring anyway because you only have one 64K page there anyway). Nevertheless, you might the find source interesting. The next applies more or less to both a newer user mode svgalib or some in kernel stuff: v) For the accelerator, all discussions with people using other cards yielded the following results:

1)  The accelerators have a bunch of registers storing current fg, bg color, maybe even a current x/y pos on the screen.

2)  Apart from ports to which to write these values, there are ports to write commands to which are then executed (draw line to x,y, fill rectangle, etc.)

3)  Most such engines are pixel oriented, so the commands should work that way. For those which are byte oriented, it is easy to convert pixels to bytes (but not vice versa).

4)  For an in kernel driver, think about the above port table. Now add another one for the accelerator registers, which only contains those bits an application can modify WITHOUT doing any hardware or other applications harm. It may garble the vga memory contents or hang the accelerator (which the screen driver will reset after a short timeout). The application can then push above mentioned byte machine commands to write data to the accel registers in a write() system call. The system will only write() up to a given amount (say 64K) in one go. It will be stored in an unpageable kernel driver, and be handled in an interrupt driven fashion, if the card supports it (or a simple reschedule if busy and look again after some time way). It is guaranteed by the kernel that no VC switch will be done during this. The kernel will timeout such a 64K bunch after some time and reset the card s.t. the application cannot block the console with such a command for more then a second or something. In that case the accelerator will get confused (or at least in another state than the application expects it). Again, it is the application's bug. We don't care. But any other application gets a freshly reset accelerator. The ordinary Unix API (select, fcntl) can be used to block for completion of certain grafix commands and such. Standard libc API (fwrite, fput etc..) can be used to maintain a long queue in the application and not bother the kernel with tiny accel calls. A user space library will be required to hide the hardware differences of the cards from the applications.

5)  The new style accel interface of Cirrus, already goes in that direction (and yes it is due to some ideas of mine). Alas, it needs more work. vi) One might write a new API. But beware, we do NOT want to reinvent X11. IMHO we need a list of modes, a call to set such a mode, a way to find out details about modes, and get direct screen access. Then provide an API to the accelerator. (like I said above, set fg/bg draw polylines, etc..) Make it simple. We can add convenience functions to draw certain arcs, triangles and such. (esp. to allow progs to use them and make that newer svgalib see if they work on that card or not). But nothing more. If we make a full featured API it will also end up adding much overhead. Then one could just use X. We do not want that. An svgalib application doesn't do much line grafix. Then you could just use X. It sets a mode and gets direct screen access. Maybe uses the accelerator for a few basic screen blits. If a complex API is designed nevertheless, it should be compatible to something. Apart from an obvious binary compatible svgalib API emulator for old apps. I'd suggest Open/GL. It is THE standard. The world does not need yet another graphics API. But when Open/GL apps run out of the box we can only benefit. Also talk to people writing commercial games and ask what they want. I already heard that Win's Games API (DirectX) sucks. We should do better, so ask people what they need.

  Q 11)
Nice plan. But will it become true?

  A)
I don't know. I lack time to realize it. Also, if noone wants it or helps realizing it, I don't feel like doing so. Also people, I'm sorry to say, but talking and talking about it doesn't help either. I know, you read about suggestions and want to send me your comments, but just discussing doesn't help. And if you don't want to code anything and never coded something, your opinions are easily wrong and it just wastes time to read them and esp. answering or discussing them because it yields nothing. It just reminds me of the endless GGI discussions about how a system call to draw a filled polygon might look when there was no working GGI at all and not even a concept to talk to an accelerator, nor anyone knowing the singlest bit about a graphics accelerator. Still, everyone thought he knew how the syscall must look for optimal performance (easy implementation) & best use to the application. Oh, this was now two years ago. GGI still does not support a call to draw a filled polygon using the accelerator, BTW. Great! Also, people may not like it, because it is common for Unix to say that just X is it. I don't like to code things for the waste basket or to get yelled at as being a jerk for coding it. On the other hand, now writing this down did again interest me in it, I might just go and start writing it again as my time permits. Just to show myself it will work, and then give it to the public. Maybe someone likes it, maybe not. After all, if Linus announced what Linux is now when he wrote that first multitasking kernel which printed A's in one and B's in the other task, people would have put him in a padded cell too. He just liked to play around with it and to show that it could be done maybe. This is what Linux is: Playing around and showing it can be done. Not install a CD and flood the internet with wisdom how it could be improved without ever coding a line or just yell at each other. And actually, reapplied on this FAQ it makes itself pointless. I'm sorry for that, but I get these questions asked again and again. So, I'll stop blathering here. This is all I had to say. Linux, just do it.

SEE ALSO
svgalib(7), libvga.config(5).

AUTHOR
This file was written by Michael Weller <eowmob@exp-math.uni-essen.de>. Please note that it contains my private opinions.