Category : Miscellaneous Language Source Code
Archive   : DINEROII.ZIP
Filename : DOC.H

/************************************************************************
**
** Dinero III Cache Simulator
** $Header: /var/home/markhill/DistributeDineroIII/RCS/doc.h,v 3.3 89/05/04 09:55:31 markhill Exp $
** Similar to Version 3.1, Released 8/7/85
**
** Mark D. Hill
** Computer Sciences Dept.
** Univ. of Wisconsin
** Madison, WI 53706
** [email protected]
**
** Developed DineroIII While Affiliated With:
**
** Computer Science Division
** University of California
** Berkeley, California 94720
**
** Source File: doc.h
**
************************************************************************/

/*
** Copyright 1985, 1989 Mark D. Hill
**
** Permission to use, copy, modify, and distribute this
** software and its documentation for any purpose and without
** fee is hereby granted, provided that the above copyright
** notice appear in all copies. Mark D. Hill makes no
** representations about the suitability of this software
** for any purpose. It is provided "as is" without expressed
** or implied warranty.
*/

/*
** INPUT FORMAT:
**
** Read in ASCII from standard input
** Expect ONE LABEL and ADDRESS in hex per line.
** Rest of data input line is ignored so it may
** be used for comments.
**
** LABEL = 0 read data
** 1 write data
** 2 instruction fetch
** 3 escape record (treated as unknown access type)
** 4 escape record (causes cache flush)
**
** 0x0 <= ADDRESS <= 0xffffffff
**
** E.G.:
** 0 0 read data from addr 0x0.
** 2 ffffffff instruction fetch from 0xffffffff.
** 4 12 flush cache and record miss type UNK
** 1 123
** 1 2
**
** NOT OK:
**
** 0x0 0x1
** 0
** 1 comment
**
** ------------------------------------------------------------
** WARNING: If more than one tuple is put on a line,
** all but the first tuple will be ignored.
** ------------------------------------------------------------
*/
/* **********************************************************************
**
** COMMAND LINE OPTIONS
**
** J + {0,1,2,...}
** J+ = {1,2,3,...}
** P+ = {2^x | x is an element of J}
**
**
** -x NAME VARIABLE OPTIONS(* ==> default)
** -------- -------- ----------------------
** -b blocksize cachep->blocksize J+ (no default)
** in bytes
**
** -S sub-block size cachep->subblocksize J (default: 0 (no sub-blocks))
** in bytes
**
** -u unified cache size cachep->Dsize J * blocksize (default: 0
** in bytes (no unifed cache))
**
** -d data cache size cachep->Dsize J * blocksize (default: 0
** in bytes (no data cache))
**
** -i instruction cache size cachep->Isize J * blocksize (default: 0
** in bytes (no instruction cache))
** Note either -u or both
** -i and -d must be positive.
**
** -a associativity cachep->assoc J+ (default: 1 (direct-mapped))
**
**-----------------------------------------------------------------------
**
** -r replacement policyp->replacement LRU* ('l'),
** FIFO ('f'),
** RANDOM ('r').
**
** -f fetch policyp->fetch DEMAND* ('d'),
** ALWAYSPREFETCH ('a'),
** MISSPREFETCH ('m'),
** TAGGEDPREFETCH ('t'),
** LOADFORWARDPREFETCH ('l'),
** (don't prefetch into next block)
** SUBBLOCKPREFETCH ('S'),
** (wrap around w/i current block)
**
**
** -p prefetch distance policyp->prefetchdist J+ (default: 1 (sub)-block)
** in (sub)-blocks
**
** -P abort prefetch policyp->abortprefetchpercent 0<= J <= 100
** percent (default: 0, no prefetches
** aborted)
**
** -w write policyp->write COPYBACK* ('c'),
** WRITETHROUGH ('w').
**
** -A writeallocate policyp->writeallocate WRITEALLOCATE* ('w'),
** NOWRITEALLOCATE ('n').
**
**-----------------------------------------------------------------------
**
** -D debug flag ctrlp->debug 0 ==> NODEBUG*,
** 1 ==> DEBUG1 (dumps stacks),
** 2 ==> DEBUG2 (dumps addrs,
** stacks, and metrics).
**
** -o output length ctrlp->output 0 ==> TERSE*,
** 1 ==> VERBOSE (dumps stats
** every 0.5M addrs),
** 2 ==> BUS (see below for
** documentation on bus records).
** 3 ==> BUS_SNOOP (see below for
** documentation on bus records).
**
** -Z skip count ctrlp->skipcount J (default: 0 ==> do not skip
** any addresses)
**
** -z maximum count ctrlp->maxcount J+ (default: 10**7)
**
** -Q mean inter-task ctrlp->Q J (default: 0 ==> no flushing)
** switch time for flush
**
** for 370 port:
370
370 Filename option for 370 only; Unix versions use stdin. We will
370 read in first word of file name and append "DIN." Thus "-F X"
370 will cause input to be read from "X DIN." Whereas "-F X DIN"
370 will abend because "DIN" is not a legal parameter.
370
** -F filename ctrlp->infilename 1 to 80 non-blank characters
** (default: TRACE)
**
** ******************************************************************* */






/* ******************************************************************* **
**
** BUS RECORD format generated by output option 2 or 3 (-o2 or -o3)
** used by packbus.c and other programs (ascii, all numbers in hex).
**
** BUS2 Access Size Address Rcount Icount
**
** where:
**
** BUS2 is a literal character string; all lines that do not
** start with BUS2 are ignored.
**
** Access is a access code (r==BUSREAD, w==BUSWRITE, p==BUSPREFETCH,
** and s==BUSSNOOP (-o3 only)).
**
** In COPYBACK, misses can cause dirty blocks to be written
** back. When this happens, a bus read followed by a bus
** write is reported (as if the cache has write buffers).
** The bus write follows the bus read with a Rcount and
** an Icount of 0.
**
** Address (hex) is address of bus transfer (0 <= Address <= 0xffffffff).
**
** Size (deciaml) is the transfer size in bytes.
**
** Rcount (decimal) is count of all references since the last miss
** including the current reference. E.g., the second of
** two consecutive misses will have an Rcount of 1.
**
** Icount (decimal) is count of instruction fetches since the last miss
** including the current reference. E.g., the second of
** two consecutive instruction fetch misses will have an
** Icount of 1.
**
** ******************************************************************* */



/* END OF USER DOCUMENTATION */




















/* *******************************************************************

File Hierarchy:


doc.h main.c global.h
|
|
+---------------+---------+---------+---------------+
| | | |
init.c fetch.c state.c output.c
|
|
cmdargs.c



******************************************************************* */





/* *******************************************************************

Cross Reference:


doc.h Global documentation

global.h Type and constant definitions

main.c Executive and main loop
main, mainloop

init.c Initialize
init, initmisc, initstacks, initmetric

cmdargs.c Process command line
getcmdargs, errormessage, echocmdargs

fetch.c Get next addresses; organize prefetch
fetch, prefetch, readfrominputstream, breakupaddr, flushcache,
init_addrstack, push_addrstack, pop_addrstack, print_addrstack,
sscanxx

state.c Manage priority stacks
update, stackupdate, push, remove, movetotop, swap, find,
findnth, putonfreelist, makenode, copybackstack, busupdate,
replacesubblocks, bustraffic

output.c All output routines
outputmetric, dumpaddr, dumpstate, dumpmetric

******************************************************************* */

/* *******************************************************************

Organizational Chart:

main
|
+--------------------+----+-----------------+
| | |
init mainloop outputmetric
| |
+----+-+---+ +-------+------+---+-----------------+
| | | | | | |
echocmdargs, | | fetch | update dumpaddr,
initmetric, | | | | | dumpstate
initstacks | | ++-+--+ | |
| | | | | | +-------+----+-----------+----+
getcmdargs | | | flushcache | | | | |
| | | | | stackupdate | prefetch findnth |
errormessage | | | [1] | | | |
| | | makenode, | push_addrstack find
initmisc | breakupaddr movetotop, | |
| | | push,swap | +-[1]-+ |
init_addrstack | | | | | |
| | busupdate copybackstack | |
readfrominputstream | | | | | |
| | | replacesubblocks | | |
pop_addrstack sscanxx | | | | |
+---------+---------+ | |
| | |
bustraffic putonfreelist


******************************************************************* */

/* *******************************************************************

Porting Information:

DineroIII runs on Unix 4.2 BSD systems. I have used it on the
VAX and SUN-1 architectures. DineroIII runs with some modifications
on CMS system with the Waterloo CMS/VM C Compiler. Setting "IBM370"
and resetting "NOTIBM370" in file global.h will cause "ifdef's" to
make changes necessary for CMS/VM port.

DineroIII uses a fast C-function called "sscanxx" to interpret
input characters instead of the library function "sscanf"
because a profile showed that dineroIII was spending 35% to 50%
of this time in sscanf. The function "sscanxx" runs about 6
times faster than "sscanf." The function "sscanxx" is selected
by the compile-time flag FAST_BUT_DANGEROUS_INPUT in global.h.
DineroIII with sscanxx should run in 60 to 70% of the time of
dineroIII with sscanf.

******************************************************************* */