•  Back 
  •  BIOS 
  •  Index 
  •  Tree View 
  •  Cross references 
  •  %About 
  •  Show info about hypertext 
  •  View a new file 
Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                               The Cookie Jar


The 'Cookie Jar' is a structure in memory containing entries called
'cookies' which are placed in the 'jar' by the operating system or
Terminate and Stay Resident (TSRTermitate and Stay Resident programm
) applications. Applications can test for
the presence of a cookie to determine the presence of a hardware device or
system feature.

The location of the cookie jar is determined by the address contained in
the system variable _p_cookies ($5A0). If no cookie jar has been allocated
yet, this entry will contain NULL (0).

Structure

The variable _p_cookies points to multiple COOKIE structures as defined
below:

    typedef struct
    {
        LONG cookie;
        LONG value;
    } COOKIE;

The structure member cookie contains a value that hopefully uniquely
identifies the cookie. cookie values are 4-byte packed longword
identifiers (often a 4 letter ASCII code word). Entries with the high byte
equal to $5F, the underscore character, are reserved for use by Atari.

The structure member value may contain any value meaningful to an
application or no value at all. In some cases a cookie won't have
a meaningful value and its presence simply signals the existence of
another process or system feature. TSRTermitate and Stay Resident programm
's often use value to store
a pointer to an internal structure. The operating system uses cookies to
signal the availability of hardware devices or system features.

The end of the cookie jar is signaled with a final entry with the value
for cookie equaling NULL. The value entry for this final cookie contains
the number of entries possible without reallocating the jar.

Searching for a Cookie

The following code may be used to find a cookie in the cookie jar. It
returns 0 if an error occurred or 1 if successful. If p_value is non-NULL
on entry, the address it points to will be filled in with the value of the
cookie.

    WORD
    getcookie( target, p_value )
    LONG target;
    LONG *p_value;
    {
            char *oldssp;
            COOKIE *cookie_ptr;

            oldssp = (Super(SUP_INQUIRE) ? NULL : Super(1L));

            cookie_ptr = *(COOKIE **)0x5A0;

            if(oldssp)
                Super( oldssp );

            if(cookie_ptr != NULL)
            {
                do
                {
                    if(cookie_ptr->cookie == target)
                    {
                        if(p_value != NULL)
                            *p_value = cookie_ptr->value;

                        return 1;
                    }
                } while((cookie_ptr++)->cookie != 0L);
            }

            return 0;
    }

Placing a Cookie

Only TSRTermitate and Stay Resident programm
 programs should place cookies in the cookie jar. The cookie
these programs place should either signal a function provided by the TSRTermitate and Stay Resident programm

or the presence of an expansion device. A CPX, desk accessory, or standard
application should not place cookies in the jar.

To place a cookie, the TSRTermitate and Stay Resident programm
 must first locate the current location of the
cookie jar. It is possible that a cookie jar does not exist ( _p_cookies
== 0 ). In that case, a new jar should be allocated.

In most instances, the cookie jar should be allocated in increments of 8
slots (though it is not a requirement). In addition, if the process
installs a new cookie jar in a TOS version lower than 1.06 it is also the
processes responsibility to remove it upon a warm reset. Calling the
following code after installing the cookie jar for the first time will
ensure that the cookie jar pointer is properly reset on a warm boot.

    RESMAGIC        equ     $31415926
    _resvalid       equ     $426
    _resvector      equ     $42A
    _p_cookies      equ     $5A0

                    .globl  _unjar

    _unjar:         move.l  _resvalid,valsave
                    move.l  _resvector,vecsave
                    move.l  #reshand,_resvector
                    move.l  #RESMAGIC,_resvalid
                    rts

    reshand:        clr.l   _p_cookies
                    move.l  vecsave,_resvector
                    move.l  valsave,_resvalid
                    jmp     (a6)

                    .bss

    vecsave:        .ds.l       1
    valsave         .ds.l       1

After determining the location of the cookie jar, the application should
search for the first empty slot in the jar by looking for a NULL in the
cookie field of a slot. Next, the application must determine if this is
the last slot in the jar by comparing the entry in the value field of the
current cookie to the number of the actual slot you are comparing. For
instance, if you have found NULL as the value for cookie in slot 16 and
value is equal to 16, the jar is full and must be reallocated.

If the slot found is not the last one, the application can simply copy
the current slot to the next slot and insert its own cookie.

If the jar must be reallocated, you should allocate enough memory to
increase the size of the cookie jar, copy the old entries to the new jar,
insert your entry as the last cookie in the jar, and finally terminate the
jar with a cookie containing a NULL and the new number of slots you have
allocated.

Though not mentioned previously, it is also advisable to ensure that your
cookie isn't already in the jar before placing it to avoid two cookies for
multiple executions of the same application to appear.

System Cookies

As of TOS 1.06, the operating system will place several cookies in the
cookie jar to inform applications of certain operating system and hardware
capabilities as follows:

cookie  Value

_CPU    The low WORD of the CPU cookie contains a number representing the
        processor installed in the system as follows:

        Value  Processor

          0      68000
         10      68010
         20      68020
         30      68030

_VDO    This cookie represents the revision of the video shifter present.
        The low WORD represents the minor revision number and the high
        WORD represents the major revision number. Currently valid values
        are:

        Major  Minor  Shifter

          0      0    ST
          1      0    STe
          2      0    TT030
          3      0    Falcon030

_FPU    This cookie identifies the presence of floating-point math
        capabilities in the system. A non-zero low WORD indicates the
        presence of software floating point support (no specific values
        have yet been assigned). The high WORD indicates the type of
        coprocessor currently connected to the system as follows:

        Value  Meaning

          0    No FPU is installed.
          1    SFP004
          2    68881 or 68882
          3    68881 or 68882 and SFP004
          4    68881
          5    68881 and SFP004
          6    68882
          7    68882 and SFP004
          8    68040 Internal
          9    68040 Internal and SFP004

_FDC    This cookie indicates the capability of the currently connected
        floppy drive. The lowest three bytes is a code indicating the
        origin of the unit ('ATC' is an Atari unit). The upper byte is
        a value indicating the highest density floppy present as follows:

        Value  Density

          0    360 Kb/ 720 Kb
          1    1.44 Mb
          2    2.88 Mb

_SND    This cookie contains a bitmap of sound features available to the
        system as follows:

        Bit  Feature

         0   GI Sound Chip (PSG)
         1   Stereo 8-bit Playback
         2   16-bit CODEC
         3   DSP
         4   Falcon030 Sound matrix
         5   Extensions (MilanBlaster, GSXB, etc.)

_MCH    This cookie indicates the machine type with the major revision
        number in the high WORD and the minor revision number in the low
        WORD as follows:

        Major  Minor  Shifter

          0      0    ST
          1      0    STe
          1      8    ST Book
          1     16    Mega STe
          2      0    TT030
          3      0    Falcon030
          4      0    Milan

        Note:
          The Hades machines have either ST or TT030 _MCH cookie contents.

hade    The Hades machine detection cookie.

_SWI    On machines that contain internal configuration dip switches, this
        value specifies their positions as a bitmap. Dip switches are
        generally used to indicate the presence of additional hardware
        which will be represented by other cookies.

_FRB    This cookie is present when alternative RAM is present. It points
        to a 64k buffer that may be used by DMA device drivers to transfer
        memory between alternative RAM and ST RAM for DMA operations.

_FLK    The presence of this cookie indicates that file and record locking
        extensions to GEMDOS exist. The value field is a version number
        currently undefined.

_NET    This cookie indicates the presence of networking software. The
        cookie value points to a structure which gives manufacturer and
        version information as follows:

        struct netinfo
        {
         LONG publisher;
         LONG version;
        };

_IDT    This cookie defines the currently configured date and time format,
        Bits #0-7 contain the ASCII code of the date separator. Bits #8-11
        contain a value indicating the date display format as follows:

        Value  Meaning

          0    MM-DD-YY
          1    DD-MM-YY
          2    YY-MM-DD
          3    YY-DD-MMBits

        #12-15 contain a value indicating the time format as follows:

        Value  Meaning

          0    12 hour
          1    24 hour

        Note: The value of this cookie does not affect any of
        the internal time functions. It is intended for informational use
        by applications only.

_AKP    This cookie indicates the presence of an Advanced Keyboard
        Processor. The high word of this cookie is currently reserved. The
        low word indicates the language currently used by TOS for keyboard
        interpretation and alerts. See the explanation for the country
        code in the OS header earlier in this chapter for valid values.
        If this cookie is present on TOS 5.0 and higher then the system
        supports soft-loaded keyboard tables.

FSMC    This cookie indicates the presence of FSM or SpeedoGDOS. Its value
        field is a pointer to a structure as follows:

        typedef struct
        {
          LONG  gdos_type;
          UWORD gdos_version;
          WORD  gdos_quality;
        } GDOS_INFO;

        The gdos_type field determines the variety of GDOS. '_FSM'
        represents Imagen font-based FSM whereas '_SPD' represents Bitstream
        font-based FSM. gdos_version specifies the current GDOS version with
        the major version number being in the high byte and the minor
        version being in the low byte.

        gdos_quality determines the output quality of v_updwk(). The default
        setting is QUAL_DEFAULT (0xFFFF) which causes the driver to use the
        setting last set in the driver configuration accessory or CPX.
        This default setting may be overridden by placing a value of
        QUAL_DRAFT (0x0000) or QUAL_FINAL (0x0001) at this location.
        The quality setting should be restored to QUAL_DEFAULT at the end
        of each print job.

SAM\0   This cookie indicates the presence of System Audio Manager and the
        XBIOS extensions it provides. The value field is currently reserved
        for internal use.

MiNT    This cookie indicates the presence of MiNT (MultiTOS) and its value
        field is the current version number (ex: MiNT 1.02 has a value field
        of 0x00000102).

MagX    This cookie indicates the presence the MagiC, third-party OS.