                  Technical Stuff On OutBurST!
                      Copyright 1991-1992
                     Straight Edge Software

The following data is being made available to allow other developers
to write programs that support OutBurST!

After purchasing an HP Laser Jet IIIP printer and after reading about
the rate at which the printer could accept data (55 KBytes/sec) I
thought that maybe the system would run faster without a print
spooler.  So I wrote a little printer character output routine that
patches into the TRAP 13 vector to just output characters to the
printer port a bit more efficiently than TOS does.  After some testing
it is quite clear that printers that can accept data at a high rate do
indeed perform better with the patched program. Next thing I did was
to implement a routine that outputs a block of data directly to the
printer with one TOS call. This additional routine resulted in even
faster print times and is especially effective with large graphics
dumps to the printer. Programs such as Pagestream and Calamus can be
accelerated considerably.

Since this programs patches the standard TOS printer output routine it
will increase the print speed for any application you use that uses
the standard routine (should be most programs).  Of course, programs
that output using bit graphics (Pagestream, GDOS applications, etc.) 
will enjoy the largest improvement.

Any printer that is fast enough and attached to the parallel port
can be helped with OutBurST!.

BIOS Changes

OutBurST! patches the Bconout() function of the TOS BIOS. Bconout
sends a single character to the device number that is passed in the
call. The standard devices and their device numbers are:

        0 = Printer Port
        1 = RS-232 Serial Port
        2 = Video Screen
        3 = MIDI Output
        4 = Intelligent Keyboard

OutBurST! patches the Bconout function to allow a faster routine to
execute when used with the printer port.

In addition to the Bconout patch, several other funtions have been
implemented as extentions to TOS. These functions are added using a
new BIOS function number ($4F42). The routines are:

        00 = Check for OutBurST! and version number
        01 = Send a block of data to Printer port
        02 = Send a null terminated string to Printer port
        03 = Reserved
        04 = Reserved
        05 = Reserved
        06 = Reserved
        07 = Reserved
        08 = Reserved
        09 = Reserved
        10 = Reserved

The reserved sub-function numbers are for new features of OutBurST! to
be provided in future releases.

Below is the description of the 3 new functions and examples of how
to use them in C, assembler and GFA Basic. These functions are
available in OutBurST! versions 2.2 and up.


-- Obcheck()

This function is used to determine if OutBurST! is loaded into memory
and if it is, report the version number of OutBurST! in use.

C format

        long Obcheck()

Machine language format

        move.l  #$4F420000,-(sp)
        trap    #13
        addq.l  #4,sp

* Register d0 contains the return status        

GFA Basic

status%=BIOS(&H4F42,W:0)


Inputs

        none

Returns

status  long    If OutBurST! is present, returns the hex value
                for 'OBxx', where xx is the version number of
                OutBurST!  (Example: OutBurST! version 2.2 returns
                0x4F420220; 0x4F42 = 'OB' and 0x0220 for version
                2.2)

                If OutBurST! is not present, TOS 1.4 returns
		0x00004F42. Other versions have not been tested but
		should not return the value above.


-- Prtblock( )

This function send a block of data in memory to a printer connected
to the parallel port. The function takes as inputs the starting
address of the block and the length.

C format

long address, length;
        Prtblock(address,length);

Machine language format

        move.l  length,-(sp)
        move.l  address,-(sp)
        move.l  #$4F420001,-(sp)
        trap    #13
        addq.l  #12,sp

GFA Basic

~BIOS(&H4F42,W:1,L:address,L:length)


Inputs

address long    The address of the first byte of the block of
                memory to be sent to the printer.

length  long    The number of bytes in the block to be sent to the
                printer.




-- Prtstring( )

This function sends a C formatted string (null terminated) to a
printer connected to the parallel port. The function takes as input
the starting address of the string.

C format

long address;
        Prtstring(address);

Machine language format

        move.l  address,-(sp)
        move.l  #$4F420002,-(sp)
        trap    #13
        addq.l  #8,sp

GFA Basic

~BIOS(&H4F42,W:&2,L:address)


Inputs

address long    The address of the first byte of the null terminated
                string to be sent to the printer.



USING OUTBURST CALLS IN 'C'

In order to use OutBurST! with C, new bindings must be added to
include the calling code required for the new functions. In the case
of GNU C, the code below must be added (at the appropriate places) to
the OSBIND.H include file used with that compiler. If you have a
different compiler you must write your own bindings to add the
functions.

/* first section */

#define trap_13_wwll(n, a, b, c)                                                \
({                                                                      \
        register long retvalue __asm__("d0");                           \
        short _a = (short)(a);                                          \
        long  _b = (long) (b);                                          \
        long  _c = (long) (c);                                          \
                                                                        \
        __asm__ volatile                                                \
        ("\
                movl    %4,sp@-; \
                movl    %3,sp@-; \
                movw    %2,sp@-; \
                movw    %1,sp@-; \
                trap    #13;    \
                addw    #12,sp "                                        \
        : "=r"(retvalue)                        /* outputs */           \
        : "g"(n), "r"(_a), "r"(_b), "r"(_c)     /* inputs  */           \
        : "d0", "d1", "d2", "a0", "a1", "a2"    /* clobbered regs */    \
        );                                                              \
        retvalue;                                                       \
})

/* second section */

__EXTERN long trap_13_wwll __PROTO((short n, short a, long b, long c));

/* third section */

#define trap_13_wwll     bios

/* forth section */

#define        Obcheck()    \
       (long)trap13_ww((short)(0x4f42),(short)(0x00))
#define        Prtblock(addr,length)  \
       (long)trap_13_wwll((short)(0x04f42),(short)(0x01),(long)(addr),(long)(length))
#define        Prtstring(addr)  \
       (long)trap_13_wwl((short)(0x04f42),(short)(0x02),(long)(addr))


_________________

NOTE: These calls are valid as of OutBurST! version 2.2 and up!
_________________
The previous information is being made available to other developers
so that they may write programs that support the speedup that is
available with OutBurST!  All information is provided for use to
support OutBurST! only and may not be used to develop competing
programs. If you have an application and are interested in bundling
OutBurST! with it contact Frank Pawlowski of Straight Edge Software,
PO Box 6407, Nashua, N.H. 03061  Phone - (603)673-9087.
