BIOS graphics for MINIX part 4/4

[ma...@levels.unisa.edu.au]

#!/bin/sh
# This is part 04 of a multipart archive
# ============= grafx10/sysdoc.txt ==============
if test ! -d 'grafx10'; then
echo 'x - creating directory grafx10'
mkdir 'grafx10'
fi
if test -f 'grafx10/sysdoc.txt' -a X"$1" != X"-c"; then
echo 'x - skipping grafx10/sysdoc.txt (File already exists)'
else
echo 'x - extracting grafx10/sysdoc.txt (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'grafx10/sysdoc.txt' &&
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X University of South Australia
X
X School of Mathematics and Computer Studies
X
X
X Computing Project
X
X
X
X GRAFX 1.0
X
X A Graphics Device for MINIX
X
X System Documentation
X
X
X
X
X
X
X
X 14 February 1992
X
X
X By David Gardiner
X
X Supervisor: Bob Buckley
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X
X Table of Contents
X
X 1. Overview of System . . . . . . . . . . . . . . . . . . 1
X
X 2. Overview Of All Programs/Modules . . . . . . . . . . . 2
X
X 3. File Descriptions . . . . . . . . . . . . . . . . . . 4
X
X 4. Screen Specifications . . . . . . . . . . . . . . . . 6
X
X 5. Current Limitations . . . . . . . . . . . . . . . . . 7
X
X 6. Guide to Future Developments . . . . . . . . . . . . . 8
X
X 7. Known System Errors . . . . . . . . . . . . . . . . . 10
X
X 8. Project Development Estimates . . . . . . . . . . . . 11
X
X 9. Log of Events . . . . . . . . . . . . . . . . . . . . 12
X
X Appendix A. Source Listings . . . . . . . . . . . . . . . 14
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Readers Note
X Throughout this document, words may be seen to be
X suffixed by and index surrounded by parentheses. eg plot(1G)
X This refers to a UNIX feature of that name, with the index
X referring to the section of the UNIX on-line manual under
X which the feature would be found.
X
X
X UNIX is a registered trademark of AT&T.
X MS-DOS is a registered trademark of Microsoft
X Corporation.
X IBM-PC is a registered trademark of International
X Business Machines Corporation.
X i
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X
X 1. Overview of System
X
X This system involves the support of a graphics device for
X the MINIX operating system. The device (named /dev/grafx) can
X be opened in a similar way to other files and devices in a
X UNIX environment. You could even write to and read from the
X device (though this would be unusual), which would allow you
X to directly access the screen memory that the device is mapped
X onto. The main graphical qualities of the device are accessed
X through ioctl calls to the device.
X
X The device was written to provide MINIX with the ability
X to execute and display programs which require some graphics
X output.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 1
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 2. Overview Of All Programs/Modules
X
X
X Kernel Image
X
X The main program that the system deals with is the
X operating system's kernel. This is done by adding to the
X contents of the memory device driver, to include code for
X handling graphics functions.
X
X The graphics device driver is mapped into screen memory,
X in a similar way to the other memory device drivers. Added to
X this is the number of ioctl calls that may be made to the
X device, which perform specific functions on screen memory.
X
X
X The original Minix 1.5 kernel is as follows:
X
X $ size kernel
X [size(1) output of kernel file]
X
X The Grafx kernel is as follows:
X
X $ size kernel
X [size(1) output of grafx kernel]
X
X This is an increase of xxxx bytes in the kernel size.
X
X
X
X
X Plot Library
X
X The graphics device is supported at a higher level by the
X implementation of a plot library. This library is compatible
X with the standard UNIX Plot library. It includes an additional
X command to change colours.
X
X The plot library can work with user programs in a couple
X of ways, depending on which library variant is used.
X
X The generic plot library (libplot.a) is linked with the
X user program, but does not directly produce graphics. Its
X output conforms to the plot(5) file format, which may then be
X piped to the plot(1G) filter program which then turns the
X codes into graphics output on the screen.
X
X Alternatively, a plot library for a specific graphics
X screen type (eg. libplotibm.a) may be linked to the user
X program. This library directly generates the graphics, without
X the need for a filter program.
X
X Memory.c
X It is in memory.c that the main Grafx device driver
X
X 2
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X resides. The driver code was put here, as in many ways it is a
X memory device driver - video memory. The majority of accesses
X to the device will be through ioctl calls to the device. In
X this respect, the driver could have been put elsewhere, or
X even in its own file, but it is easier to add to an existing
X device family than create a whole new task for a new device.
X
X The driver, as far as Minix is concerned, is just another
X memory device (like /dev/ram etc). The use of ioctl(3) calls
X to this device were already in use for initalising the size of
X the ram disk at system boot time. The code which handled the
X ioctl(3) call was extended to detect if the call referred to
X the Grafx device. In this case, the execution of Grafx
X functions was possible. Otherwise, the ioctl handler behaves
X exactly as before.
X
X The ioctl(3) function dispatcher is more similar to the
X ioctl(3) handler in tty.c - the terminal device driver. This
X was previously the only device driver that properly supported
X ioctl(3) access (the ioctl(3) call to the ram disk is meant
X for internal use).
X
X Part of the implementation of the driver was the mapping
X of the video memory to a virtual device. Having the memory
X addresses correct is critical if the device is to work
X correctly.
X
X The driver includes internal variables for the current
X colour, graphic state, and current point (graphic cursor).
X
X Because a few of the ioctl(3) need to set pixels, a
X function was included which sets a single pixel.
X
X The driver also includes a function to draw lines. This
X function is based on Bresenham's line-drawing algorithm. It is
X quite efficient, using integer addition.
X
X Ioctl.c
X
X Changes were necessary to the source code of the
X ioctl(3). It was found that the original ioctl(3) source code
X allowed for only 4 functions - those for the tty driver. This
X limiation is unacceptable for the Grafx driver, which requires
X at least 9 functions. It was also restricting the data
X structures that could be passed with the *args parameter of
X the ioctl(3) call. Ultimately, this function (and the tty
X driver) should be overhauled to eliminate this problem
X completely.
X
X Because of time restrictions it was necessary to make
X only minor changes to the code. These changes allowed
X additional function calls, whilst retaining the old tty code.
X They also allow additional data to be passed to the device
X driver. This is not ideal, but it works.
X
X 3
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 3. File Descriptions
X
X Following is a list of files that the system deals with.
X Some of these files exist as context-diffs (cdiffs) that must
X be patched to the original source files to obtain the updated
X version.
X
X Devices
X
X grafx - Device that handles graphics (usually named
X /dev/grafx). This device needs to be created
X for the system to work correctly. This is done
X by the mknod(8) command.
X
X
X Main Files
X
X memory.c - Kernel sources for the ram disk and memory
X devices, and for our interest, the graphics
X device (video ram).
X
X ggtty.h - Standard header file for programs using
X /dev/grafx ioctl calls.
X
X
X C Library Files
X
X ioctl.c - C library source for the ioctl(3) function
X call, replaces old ioctl.c in libc.a. This new
X source adds the ability to call ioctl(3) with
X functions in addition to those for the tty
X device. It does not change the use of the tty
X functions.
X
X Plot Library Files
X
X libplot.a - Plot library, linked to applications which
X can then pipe output to the plot.c executable.
X
X libplotibm.a - C Plot library, linked to applications to
X directly drive the graphics device.
X
X libplot.h - Standard header file for all library source
X files.
X
X openpl.c - Library source for initialising graphics
X device.
X closepl.c - Library source for closing graphics device.
X colour.c - Library source for setting current colour.
X label.c - Library source for displaying text.
X line.c - Library source for drawing lines.
X point.c - Library source for setting a single pixel.
X move.c - Library source for moving the graphics
X cursor.
X
X 4
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X arc.c - Library source for drawing arcs.
X circle.c - Library source for drawing circles.
X cont.c - Library source for drawing line from last
X move.
X space.c - Library source for zooming rectangle to
X screen.
X erase.c - Library source for erasing screen.
X linemod.c - Library source for modifying line style.
X
X plot.c C command source for plot(1G) filter.
X
X File Formats
X
X plot(5) - Produced by device-independant plot(3X)
X library. Read by plot(1G) filter.
X
X The file is a continuous stream of commands that are
X interpreted by the plot(1G) filter. Each of these commands
X consists of an ASCII character code followed by a specific
X number of parameters (bytes) of binary information.
X
X 4 bytes usually refers to 2 16-bit numbers. See
X associated source file from the libplot.a library for more
X detailed information.
X
X
X Name Code Parameters
X Move m + 4 bytes of new current point
X Cont n + 4 bytes of end of line
X Point p + 4 bytes of point
X Line l + 4 bytes of start, + 4 bytes of end
X Label t + NEWLINE terminated string of characters
X Arc a + 4 bytes of centre, + 4 bytes of start, + 4
X bytes of end
X Circle c + 4 bytes of centre, + 2 bytes of radius
X Erase e None
X Linemod f + NEWLINE terminated string of command
X Space s + 4 bytes of lower left, + 4 bytes of upper
X right
X Colour k + 2 bytes of colour
X
X Test Programs
X
X lowtst.c - Tests the graphics device directly through
X ioctl(3) calls.
X
X plottst.c - test graphics device and the plot package
X through the plot library.
X
X
X
X
X
X
X
X 5
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 4. Screen Specifications
X
X The system, with minor modifications should work on any
X type of video card that supports graphics on the IBM-PC. By
X default, the system uses standard VGA. All accesses to the
X screen are done through the BIOS, so the system is really only
X limited by what the BIOS supports.
X
X The system has been tested successfully in CGA, EGA and
X VGA modes.
X
X It should work any machine whose BIOS knows about the
X video graphics modes. This would preclude early Hercules video
X adaptors which didn't come with BIOS support.
X
X The BIOS display interrupt 0x10 (16 dec) is used by the
X graphics device. The particular functions of this interrupt
X utilised are as follows (refer to source code listings for
X exact uses):
X
X
X Function Description
X
X 0x00 Set video mode - text or graphics (graphics
X resolution)
X
X 0x02 Move text cursor to (x,y - text coordinates)
X
X 0x0C Set pixel at (x,y - graphics coordinates)
X
X 0x0E Write character, tty style
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 6
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 5. Current Limitations
X
X The system as it stands, depends on the BIOS to access
X the graphics mode of the video adaptor. Because of the fact
X that the BIOS may not be used in protected mode on the 80286
X (or above), MINIX must run in Real mode. This limits the
X amount of memory that MINIX can address.
X
X The system is dependent on IBM-PC compatible hardware,
X and will not run on any other hardware platform. This is true
X for the kernel modifications only.
X
X Certain functions in the plot library have not been
X implemented in full. Calling these functions will not result
X in a compilation error, rather nothing will happen when they
X are executed. The particular functions affected are circle,
X arc, space.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 7
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 6. Guide to Future Developments
X
X 6.1 Overcoming System Limitations
X
X BIOS Dependency
X
X The removal of the dependence of the device driver on the
X BIOS would be a valuable improvement. It could improve
X performance, and allow MINIX to run in protected mode
X (assuming no other code also used the BIOS).
X
X Basically, all of the functions that the BIOS performs
X would have to be done from within the kernel. This does have
X the effect of reducing the portability of the system.
X
X Currently the BIOS is used to perform 4 functions (see
X page 6). These would have to be replaced with kernel functions
X that do the following (function names are suggested only):
X
X int videomode(int m);
X - Set video adaptor display mode to (m).
X - Returns false if mode is invalid.
X
X void setpixel(int x,y; int c);
X - Set pixel at (x,y) to colour (c).
X
X void writetextat(int x,y; char *s);
X - Write text (*s) to screen at (x,y).
X - (x,y) could be text coordinates eg. (80x25), but
X graphics coordinates would allow text to be displayed on
X the screen with greater precision.
X
X Compatibility With Multiple Hardware Platforms
X
X This issue is solved by hardware-specific code being
X written for each platform. It may be that the kernel code
X could be re-written in a more general way, allowing the
X specific code to be limited to just a few functions.
X
X This system was written for IBM-PC MINIX, so does not
X attempt to support other machines.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 8
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X Completing the Plot Library
X
X Although all the plot functions exist in the plot
X library, not all are fully implemented. Those that are only
X code stubs include:
X
X arc.c
X circle.c
X space.c
X linemod.c
X
X The implementations of these functions should conform to
X the specifications of the plot library.
X
X
X
X 6.2 How to add to the System
X
X Here are some hints and tips on extending and improving
X the package. This includes both the low-level /dev/grafx
X interface routines, and also the PLOT(3) library routines.
X
X Implementing New Functions
X
X Depending on how much a new function will be used, will
X probably decide where its code is put. As a rule, it is best
X to keep most code in a library, and out of the kernel. As an
X example, I felt that the gain in speed for the line drawing
X would be sufficient to warrant it be put directly in the
X kernel.
X
X A hint which may seem obvious to some, is when you are
X coding a new function, if possible test the code with a
X separate program before putting it in the kernel.
X
X eg. You are attempting to code a fill-area function.
X First of all, instead of writing this code directly into the
X kernel, write a stand-alone program that calls any other
X graphics primitives (eg. point, line etc), and debug this
X program until your algorithm works. Then, and only then,
X insert your code into the kernel (if that is where you want to
X put it), and test it further. This saves a lot of re-boots,
X which you would otherwise have to do when you debug your
X function.
X
X If your code ends up in the kernel, call any other
X primitives from within (see the line-drawing implementation in
X memory.c, which calls putpixel() ). It is excessive (and
X probably illegal) to call ioctl(3) from within the kernel.
X
X Writing Your Own Graphics Kernel
X
X There are a few things you will need to do to port the
X hardware-dependent code across.
X
X 9
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 6.3 You should not have to modify any of the PLOT
X sources. Only the kernel sources will need to be
X modified.
X
X 6.4 Firstly, edit the standard header ggtty.h and
X add/modify your specific hardware parameters. Things
X like the video mode, screen size, number of colours.
X Follow the comments in ggtty.h for more information.
X
X 6.5 Next, you will probably have to make some reasonable
X modifications to memory.c. These will be specific
X for your machine, so in keeping with tradition, put
X #defines around your code so that the same source
X can support multiple hardware platforms.
X
X Your hardware configuration, and possible variations on
X the hardware will decide how you address screen memory. For
X speed, direct access is the obvious alternative. But some
X platforms may require you to go through a BIOS of some
X description. The Macintosh with its Quickdraw chip might be
X one of these cases.
X
X I chose to go through the BIOS on the PC, as it made
X things a lot easier to code. I didn't have to worry about
X addressing pixels in different modes - the BIOS does it all
X for you. Certainly, if any major graphics applications were to
X use the BIOS their performance would be quite slow, but for
X general purpose pictures and graphs, the current methods seem
X sufficient. Having a 33Mhz 386DX probably helps too!
X
X
X 7. Known System Errors
X
X No errors are known at this time, besides the following
X specific problem.
X
X If the device is read or written like a file, and is done
X so beyond the end of the video memory mapping, then the
X process is stopped and cannot be exited.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 10
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 8. Project Development Estimates
X
X Original Project Estimates
X
X 4/3 Initial Meeting
X
X 11/3 Project starts
X
X Draft Documentation and Design
X
X 25/4 Character device working
X
X IOCTL Calls
X . switch modes
X . draw pixels
X . line drawing, arcs
X . bit blit
X
X Graphic device working
X
X Improvements
X
X 15/11 Project submitted
X
X
X Final Project Estimates
X
X 4/3 Initial Meeting on project
X
X 11/3 Projects officially start
X
X Draft Documentation and Design
X
X 25/4 Character based device working
X
X 10/5 Character based device working. Documentation -
X (Requirement, How and Character Description)
X
X 26/8 Dumb graphics device working (just like char device,
X only crunchy)
X
X 2/9 IOCTL calls defined and documented.
X 1. switch modes and simple test.
X 2. draw pixels.
X 3. line draw
X
X Testing
X
X Graphic based device working
X
X Testing and Final Documentation
X
X 15/11 Project submitted
X
X
X 11
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 9. Log of Events
X
X 1991
X
X 4/3 Initial meeting.
X
X 11/3 Projects officially commence.
X
X 25/3 Look at console.c, IOCTL, Check scrolling.
X
X 15/4 Prepare some documentation, Check bios_wini.c.
X
X 10/5 Character device starts to work.
X
X 28/5 Fixed seek problem with character device, device
X tested for this stage.
X
X 5/8 Can't use protected mode, soft scroll hard-coded,
X wini.c protected mode patch implemented.
X
X 14/8 Littered kernel with pop-up message to trace where
X ioctl calls go. Used code from tty.c. Problem still
X with ioctl calls.
X
X 26/8 Hassles with turning graphics mode on - causing kernel
X panic. Solved problem by saving old int 010H vector
X and re-using it. Can now turn on graphics mode.
X
X 2/9 Ioctl calls work good enough to turn device on and
X off. Discuss making device PLOT compatible. Tested
X BIOS text printing function calls successfully.
X
X 6/9 Problem passing integers to a pixel setting routine.
X Got plot(x,y) to work only with 8-bit coordinates.
X Suggested that BIOS is causing this limit.
X
X 9/9 Implemented BIOS text printing
X
X 11/9 Discovered that ioctl.c (library source) is brain-
X dead. It contains a nasty hack that only allowed the
X tty ioctl calls. Added my own quick hack, to allow
X other calls besides tty.
X
X 16/9 Further patches to ioctl.c made start on 16-bit
X coordinates.
X
X 17/9 Tested BIOS graphics using a DOS program which showed
X BIOS is ok. Further patches added ability to pass 16-
X bit data via ioctl. Using VGA hi-res (nice!).
X
X 18/9 Investigated Super-VGA modes. Decided to live with
X standard VGA.
X
X 23/9 Initial line drawing algorithm written in Turbo-C,
X
X 12
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X first port to Minix.
X
X 25/9 Line drawing bugs fixed, 2nd port to Minix.
X Investigated passing string of text to device, idea
X dismissed as too hard.
X
X 7/10 Set colours. PLOT library development has begun.
X Suggest that add colour to PLOT library.
X
X 19/10 Wrote plot.c filter in Turbo-C, ported to Minix.
X
X 21/10 Changed the way libplot.a is generated, from one
X source, to many separate sources.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 13
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X Appendix A. Source Listings
X
X Table of Listings
X
X
X plot.c
X libplot.h
X libsources
X
X memory.c.cdiff
X ioctl.c.cdiff
X
X ggtty.h
X
X com.h.cdiff
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 14
X
X
X
X
X
X
SHAR_EOF
chmod 0700 grafx10/sysdoc.txt ||
echo 'restore of grafx10/sysdoc.txt failed'
Wc_c="`wc -c < 'grafx10/sysdoc.txt'`"
test 28207 -eq "$Wc_c" ||
echo 'grafx10/sysdoc.txt: original size 28207, current size' "$Wc_c"
fi
# ============= grafx10/tst/tst_plt.c ==============
if test ! -d 'grafx10/tst'; then
echo 'x - creating directory grafx10/tst'
mkdir 'grafx10/tst'
fi
if test -f 'grafx10/tst/tst_plt.c' -a X"$1" != X"-c"; then
echo 'x - skipping grafx10/tst/tst_plt.c (File already exists)'
else
echo 'x - extracting grafx10/tst/tst_plt.c (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'grafx10/tst/tst_plt.c' &&
#include <stdio.h>
#include <ggtty.h>
#include <sys/types.h>
#include <fcntl.h>
X
void main()
{
X int fd;
X int i;
X gmess *args;
X
X args = (gmess *) malloc(sizeof(gmess));
X
X fd = open("/dev/grafx",O_RDWR);
X
/*
X ioctl(fd,GIOCENTER,args);
*/
X args->GRAFX_X = 300;
X args->GRAFX_Y = 100;
X
X printf("args %x %x %x %x\n",args->gm2_b1,
X args->gm2_b2,args->gm2_b3,args->gm2_b4);
X
X ioctl(fd,GIOCPLOT,args);
X
X (void) getchar();
X ioctl(fd,GIOCRETURN,args);
X
X close(fd);
}
SHAR_EOF
chmod 0600 grafx10/tst/tst_plt.c ||
echo 'restore of grafx10/tst/tst_plt.c failed'
Wc_c="`wc -c < 'grafx10/tst/tst_plt.c'`"
test 465 -eq "$Wc_c" ||
echo 'grafx10/tst/tst_plt.c: original size 465, current size' "$Wc_c"
fi
# ============= grafx10/tst/tst_plt.c ==============
if test -f 'grafx10/tst/tst_plt.c' -a X"$1" != X"-c"; then
echo 'x - skipping grafx10/tst/tst_plt.c (File already exists)'
else
echo 'x - extracting grafx10/tst/tst_plt.c (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'grafx10/tst/tst_plt.c' &&
#include <stdio.h>
#include <ggtty.h>
#include <sys/types.h>
#include <fcntl.h>
X
void main()
{
X int fd;
X int i;
X gmess *args;
X
X args = (gmess *) malloc(sizeof(gmess));
X
X fd = open("/dev/grafx",O_RDWR);
X
/*
X ioctl(fd,GIOCENTER,args);
*/
X args->GRAFX_X = 300;
X args->GRAFX_Y = 100;
X
X printf("args %x %x %x %x\n",args->gm2_b1,
X args->gm2_b2,args->gm2_b3,args->gm2_b4);
X
X ioctl(fd,GIOCPLOT,args);
X
X (void) getchar();
X ioctl(fd,GIOCRETURN,args);
X
X close(fd);
}
SHAR_EOF
chmod 0600 grafx10/tst/tst_plt.c ||
echo 'restore of grafx10/tst/tst_plt.c failed'
Wc_c="`wc -c < 'grafx10/tst/tst_plt.c'`"
test 465 -eq "$Wc_c" ||
echo 'grafx10/tst/tst_plt.c: original size 465, current size' "$Wc_c"
fi
# ============= grafx10/usrdoc.txt ==============
if test -f 'grafx10/usrdoc.txt' -a X"$1" != X"-c"; then
echo 'x - skipping grafx10/usrdoc.txt (File already exists)'
else
echo 'x - extracting grafx10/usrdoc.txt (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'grafx10/usrdoc.txt' &&
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X University of South Australia
X
X School of Mathematics and Computer Studies
X
X
X Computing Project
X
X
X
X GRAFX 1.0
X
X A Graphics Device for MINIX
X
X User Documentation
X
X
X
X
X
X 14 February 1992
X
X
X By David Gardiner
X
X Supervisor: Bob Buckley
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X
X Table of Contents
X
X 1. Introduction . . . . . . . . . . . . . . . . . . . . . 1
X Software
X Hardware
X
X 2. Installation . . . . . . . . . . . . . . . . . . . . . 2
X
X 3. High Level Usage - Libraries . . . . . . . . . . . . . 5
X Plot(3X) Library Usage
X
X 4. Low Level Usage - Ioctl Calls . . . . . . . . . . . . 7
X
X Appendix A. Programmers Reference . . . . . . . . . . . . 9
X Types
X Defines for gmess
X Defines for the Terminal
X Defines for Ioctl(3) Functions
X Plot(3X) Library Functions
X
X Appendix B. Error Messages . . . . . . . . . . . . . . . 12
X
X Appendix C. Glossary . . . . . . . . . . . . . . . . . . 13
X
X
X
X Readers Note
X Throughout this document, words may be seen to be
X suffixed by an index surrounded by parentheses. eg plot(1G)
X This refers to a UNIX feature of that name, with the index
X referring to the section of the UNIX on-line manual under
X which the feature would be found.
X
X
X UNIX is a registered trademark of AT&T.
X MS-DOS is a registered trademark of Microsoft
X Corporation.
X IBM-PC is a registered trademark of International
X Business Machines Corporation.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X i
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X
X 1. Introduction
X
X The Grafx package gives MINIX the ability to display
X graphical output. It also partially implements the UNIX
X plot(3X) library.
X
X To function correctly, at least the following hardware
X and software is required:
X
X Software
X
X MINIX 1.5 for the IBM-PC.
X Grafx 1.0
X
X Hardware
X
X IBM-PC or 100% compatible (including PC-AT)
X Graphics Adaptor - CGA, EGA, VGA, (Hercules untested)
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 1
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 2. Installation
X
X There are a number of steps in installing the Grafx
X system. This guide assumes that you have MINIX 1.5 up and
X running on your PC. Instruction for doing so is given within
X the MINIX documentation in the box MINIX came in, and is not
X repeated here.
X
X Step 1. Create New Directory
X
X Copy the Grafx package into a sub-directory. From this
X sub-directory, all the changes to MINIX can be applied and
X tested.
X
X Assuming package is distributed in one file (tar
X and compressed), and you are logged in as root.
X
X $ mkdir /usr/src/grafx
X $ mv grafx.tar.Z /usr/src/grafx
X $ cd /usr/src/grafx
X
X De-compress archive file.
X
X $ compress -d grafx.tar.Z
X
X Now run tar, to extract files from tar archive.
X
X $ tar -xv grafx.tar
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 2
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X Step 2. Copy Original Sources
X
X Now if you list the directory, it should look similar to
X the following.
X
X A listing of the directory, some file sizes and
X dates may be different.
X
X $ ls -alF
X
X total 3
X drwxrwxrwx 2 root 64
X drwxrwxrwx 25 bin 592 Nov 6 15:35..
X -rw-r--r-- 1 root 64
X kernel/
X -rw-r--r-- 1 root 64
X lib/
X -rw-r--r-- 1 root 64
X tst/
X -rw-r--r-- 1 root 64
X plot/
X -rw-r--r-- 1 root 300 Nov 6 15:36
X Readme
X
X
X
X
X
X One of the directories is named 'kernel'. It is in this
X sub-directory that the new kernel will be built. To do this,
X we must copy all of the files from the original kernel source
X directory into our new directory. There are also some other
X files from other places that we also need copies of. That way,
X only our copy will get changed, and the originals will remain
X untouched.
X
X Assuming that the original kernel sources are in
X /usr/src/kernel, and that our current directory
X is /usr/src/grafx
X
X $ cp /usr/src/kernel/* kernel
X $ cp /usr/src/lib/other/ioctl.c lib
X
X We can also copy some files to their new
X locations. If your include directory is
X different, then use the correct path for your
X machine.
X
X $ cp include/ggtty.h /usr/include
X
X
X
X
X
X
X 3
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X
X Step 3.
X
X We have to apply the changes that the Grafx package makes
X to the kernel. These changes are stored in files called
X context-diff's (or cdiff's for short), and are applied to the
X old source file to create the new updated source file. This is
X done using the patch(1) program.
X
X Run patch(1) for all cdif files. Do not type the
X '$' or '>', these are prompts.
X
X $ for i in *.cd*
X > do
X > patch <$i
X > done
X
X
X
X
X These changes must be compiled. The existing Makefile
X should be sufficent.
X
X Run make(1) to re-compile modified files
X
X $ make
X
X
X
X
X If no compilation errors occurred, then a new 'kernel'
X file should now exist. Booting from this kernel now depends on
X what method you use to boot Minix.
X
X If you use shoelace(8), then you can copy it to
X /etc/system on your boot partition.
X
X If you use a standard Minix boot disk then it is just a
X matter of re-building the Minix 'image' file with the new
X kernel instead of the old.
X
X Step 4.
X
X The Grafx device must have a logical name so that it can
X be opened and accessed. This is done as follows:
X
X The following creates the Grafx device, as a
X character device, major device number 1, minor
X device number 5.
X
X $ mknod /dev/grafx c 1 5
X
X
X
X
X 4
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 3. High Level Usage - Libraries
X
X The Grafx package is relatively simple to use. There are
X two ways that a programmer can use the package. The first is
X to use the plot(3X) library, and the second is by calling the
X device directly through ioctl(3) calls.
X
X Plot(3X) Library Usage
X
X Like this package, there are also a couple of ways that
X you can use the plot(3X) libraries. This stems from the fact
X that the Grafx package creates two possible libraries to
X choose from.
X
X The first, named 'libplot.a' is a device-independent
X library, which does not actually produce any graphics by
X itself. The output of the graphics functions in a program
X linked to this library are a series of codes. These codes
X conform to the plot(5) file format.
X
X This output can be piped to a filter plot(1) which
X interprets these codes, and displays the corresponding
X graphics on the screen.
X
X First link library to user program 'foo.c'
X
X $ cc -lplot foo.c
X
X Now run executable, and pipe output to plot(1)
X
X $ a.out | plot
X
X
X
X
X The other option, is to link to a library named
X 'libplotibm.a'. This library is similar to 'libplot.a', except
X that the output does not need to be piped to plot(1). Instead,
X this library will directly create the graphics output on the
X screen. It is possible for there to be many of these
X libraries, each for a specific type of computer and display.
X
X
X First link library to user program 'foo.c'
X
X $ cc -lplotibm foo.c
X
X Now run executable
X
X $ a.out
X
X
X
X
X
X 5
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X Here is some example code that can be compiled and linked
X to either of the previously mentioned libraries.
X
X #include <stdio.h>
X
X void main()
X {
X int i;
X
X openpl(); /* Open device */
X for (i = 0; i < 20; i++) {
X line(1, 1, 100, i * 2);
X move(i * 3, 150);
X label("!");
X }
X (void) getchar(); /* Wait for key press
X */
X closepl(); /* Close device */
X }
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 6
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X 4. Low Level Usage - Ioctl Calls
X
X The lowest level of access to the grafx device is through
X ioctl(3) calls.
X
X Ioctl(3) calls are of the form:
X
X int result = ioctl(int fd, int function, char
X *args);
X
X Where:
X result = 0 if error occurred.
X fd = open file-descriptor.
X function = function code.
X args = pointer to structure to pass to
X driver.
X
X
X
X
X The use of ioctl(3) calls is generally only needed for
X specialised applications, where the plot(3X) library is
X unsuitable. The plot(3X) library uses these calls, but it
X needn't if there was some other access available.
X
X See the Programmers Reference for a list of valid
X function calls to the grafx device ioctl handler.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 7
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X
X Here is an example of the use of some of the ioctl
X functions. Note that you must always turn on graphics mode
X before executing other graphics functions. It is also a very
X good idea to return to text mode at the end of your program.
X
X #include <stdio.h>
X #include <ggtty.h>
X #include <fcntl.h>
X
X void main()
X {
X int fd;
X gmess *args;
X
X args = (gmess *) malloc(sizeof(gmess));
X
X /* Open file descriptor with grafx device
X */
X if ((fd = open("/dev/grafx",O_RDWR)) == -1)
X {
X printf("Error opening Grafx device
X \n");
X exit(1);
X }
X
X ioctl(fd,GIOCENTER,args); /* Enter
X graphics mode */
X
X ioctl(fd,GIOCTEST,args); /* internal
X test function */
X
X args->GRAFX_COLOUR = 15; /* set colour
X */
X ioctl(fd,GIOCCOLOUR,args);
X
X args->GRAFX_CHAR = 'C'; /* text
X function */
X ioctl(fd,GIOCTEXT,args);
X
X (void) getchar(); /* Wait
X for keypress */
X
X ioctl(fd,GIOCRETURN,args); /* Back
X to text mode */
X close(fd); /* Close
X file-descriptor */
X }
X
X
X
X
X
X
X
X 8
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X
X Appendix A. Programmers Reference
X
X This list includes descriptions of data structures and
X definitions found in 'ggtty.h' (/usr/include/ggtty.h). Only
X items that are of use to the user are included. Other items
X that appear in 'ggtty.h' may be assumed to be for internal use
X only, and of no relevance to the user.
X
X Types
X
X Name Use
X
X coord To store values which are used for coordinates.
X
X spectrum To store values which represent colours.
X
X gmess As the type for the args parameter of the
X ioctl(3) call. Information in this structure is
X passed to and from device.
X
X Defines for gmess
X
X Not all these defines may be used at once. Their use is
X dependant on the particular function that ioctl(3) is called
X with.
X
X Name Use
X
X GRAFX_X The position where the 'x' coordinate is put.
X
X GRAFX_Y The position where the 'y' coordinate is put.
X
X GRAFX_X2 The position where the 'x2' coordinate is put.
X
X GRAFX_Y2 The position where the 'y2' coordinate is put.
X
X GRAFX_COLOUR The position where the colour (of type
X spectrum) is put.
X
X GRAFX_CHAR The position where an ASCII character may be
X put.
X
X Defines for the Terminal
X
X G_COLOURS Maximum number of colours that can actually be
X displayed in graphics mode.
X
X G_MAX_X Maximum 'x' coordinate of the graphics mode.
X
X G_MAX_Y Maximum 'y' coordinate of the graphics mode.
X
X Defines for Ioctl(3) Functions
X
X
X 9
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X GIOCENTER Enter graphics mode.
X
X GIOCRETURN Return to text mode.
X
X GIOCTEST Run a simple graphics test.
X
X GIOCPLOT Set a pixel on the display.
X
X GIOCCOLOUR Set the colour to use for drawing.
X
X GIOCTEXT Display a character at the current position.
X
X GIOCMOVE Move the current position.
X
X GIOCLINE Draw a line.
X
X
X Plot(3X) Library Functions
X
X Some of these functions depend on a 'current point'. This
X is equivalent to the last point of a line(), move(), cont() or
X point().
X
X openpl() Turn on graphics mode.
X
X erase() Clear graphics screen.
X
X label(s) Write the string 's' at the current point.
X
X line(x1,y1,x2,y2) Draw a line from (x1,y1) to (x2,y2).
X
X circle(x,y,r) Draw a circle with centre (x,y) and radius (r).
X
X arc(x,y,x0,y0,x1,y1) Draw an arc with centre (x,y), in an
X anti-clockwise direction from (x0,y0) to
X (x1,y1).
X
X move(x,y) Move the current point to (x,y).
X
X cont(x,y) Draw a line from the current point to (x,y).
X
X point(x,y) Set the pixel at (x,y)
X
X linemod(s) Change the line style. (s) is a string equal to
X one of 'dotted', 'solid', 'longdashed',
X 'shortdashed', 'dotdashed'.
X
X space(x0,y0,x1,y1) Expand or contract the rectangle(x0,y0) -
X (x1,y1) to fit the whole display.
X
X colour(c) Set the current drawing colour.
X
X closepl() Return to text mode.
X
X
X 10
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X Appendix B. Error Messages
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 11
X
X
X
X
X
X
X
X
X
X
X
X
X Graphics Device for MINIX System Documentation
X
X
X Appendix C. Glossary
X
X cdiff(1) Program which creates cdiff(5) files.
X
X cdiff(5) A file that contains only the changes from one
X version of a file to the next.
X
X IO Input/Output
X
X ioctl(3) UNIX function that allows programs to control
X IO devices.
X
X patch(1) Program which creates a new version of a file
X from the old version + the cdiff(5) file.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X 12
X
X
X
X
X
X
SHAR_EOF
chmod 0700 grafx10/usrdoc.txt ||
echo 'restore of grafx10/usrdoc.txt failed'
Wc_c="`wc -c < 'grafx10/usrdoc.txt'`"
test 19184 -eq "$Wc_c" ||
echo 'grafx10/usrdoc.txt: original size 19184, current size' "$Wc_c"
fi
exit 0