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-FileThe Cookie JarThe '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).
StructureThe variable _p_cookies points to multiple COOKIEstructures 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 CookieThe 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 CookieOnly 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 CookiesAs of TOS 1.06, the operating system will place several cookies in the
cookie jar to inform applications of certain operating system and hardwarecapabilities 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 KeyboardProcessor. 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.