.TH DINEROIV 3.UC 4.SH NAMEdineroIV \- fourth generation cache simulator library.SH SYNOPSIS.B "#include <d4.h>".br.BR "typedef struct { " ". . ." " } d4cache".br.BR "typedef " ". . ." " d4addr".br.BR "typedef " ". . ." " d4memref".sp.BI "d4cache *d4new (d4cache *" larger ")".br.BI "int d4setup(void)".br.BI "void d4ref (d4cache *" c ", d4memref " m ")".SH DESCRIPTIONThe Dinero IV library offers an easy-to-use subroutine interfacefor a flexible simulator of multilevel cache memories.The simulator reads memory reference information from standard input,and writes statistical dataabout the simulated cache performance to standard output.Dinero IV is not a timing or functional simulator,therefore neither temporal information norsimulated memory contents are relevant..PPThe header file,.BR d4.h ,defines several types and functions,with the ones indicated in the SYNOPSIS, above,being the most significant..PPBasic usage is simple:.IP 1. 4nUsing.BR "d4new(NULL)" ,create a degenerate form of simulated ``cache'' to represent memory,the bottom level of a simulated memory hierarchy.The return value must be saved, to use as the argument to another call to.BR d4new .Each call to.B "d4new(NULL)"creates the base of a new, independent, simulated memory hierarchy..IP 2. 4nUsing one or more calls to.BI "d4new(" larger )\c\&, where.I largeris the return value from an earlier call to.BR d4new ,create additional cache levels in a ``bottom up'' fashion,starting close to the memory and ending close to the processor..IP 3. 4nSpecify simulation parameters for each cache by directly assigningvalues to various fields within each.B d4cachestructure.See.BR "D4CACHE PARAMETER FIELDS" ,below, for a description of the various fieldsand how they can be used..IP 4. 4nComplete initialization of the simulator by calling.BR d4setup() .The return value is nonzero if there are problems with the simulated cacheconfiguration.After calling.BR d4setup() ,further direct modification of.B d4cachecontents is generally erroneous..IP 5. 4nSimulate each memory reference by calling.BI d4ref( c , m )\c\&,where.I cis a pointer to a top-level cache and.I mdescribes the memory reference(see.BR "MEMORY REFERENCES" ,below, for a description of.B d4memrefstructures).The reference is propagated to other caches automatically, as needed,in accordance with specified cache properties..IP 6. 4nExtract cache performance statistics by directly accessing.B d4cachestructures.The fields to use are described below, in.BR "D4CACHE RESULT FIELDS" ..SH "MEMORY REFERENCES"A memory reference is described by a.B d4memrefstructure, which contains three integral fields:.IP \f3address\fP 12nthe address referenced.The type of this field is.BR d4addr ..IP \f3size\fP 12nthe number of bytes affected..IP \f3accesstype\fP 12none of the following values:.RS.IP \f3D4XREAD\fP 14na data load..IP \f3D4XWRITE\fP 14na data store..IP \f3D4XINSTRN\fP 14nan instruction fetch..IP \f3D4XMISC\fP 14na miscellaneous reference, treated as a data loadbut without the possibility of generating any prefetch references..IP \f3D4XCOPYB\fP 14nnot a real memory reference, but a command to the cacheto copy back dirty cache block(s), as applicable.The operation refers to the whole cache if.B sizeis 0.This operation does not imply invalidation of cache block(s), however..IP \f3D4XINVAL\fP 14nnot a real memory reference, but a command to the cacheto invalidate cache block(s), as applicable.The operation refers to the whole cache if.B sizeis 0.This operation does not imply copying back dirty data, however..RE.PPThere are no internal restrictions on what constitutes a valid address,except that the type and size of an address is platform-dependent(generally 32 bits or more).Dinero IV imposes no size or alignment restrictions on memory references;they may span multiple sub-blocks or blocks..SH "D4CACHE PARAMETER FIELDS"The following fields within each.B d4cachestructure must generally be directly initializedby users of the Dinero IV librarybefore calling.BR d4setup .Initialization is not required for fields of ``memory'' cache structures(those created by calling.BR d4new(NULL) )..IP \f3name\fP 15nThe user may set this to point to a stringused to identify the cache for certain error messages.A default value will be set automatically if.B nameis.B NULLwhen.B d4setupis called..IP \f3flags\fP 15nThis integer field contains bits that can be used to specify optionalbehavior for Dinero IV.The currently defined user-settable flags are.RS.IP \f3D4F_CCC\fP 10nCauses misses to be categorized as compulsory, capacity, conflict misses.The computed results are available in the fields.BR comp_miss ,.BR comp_blockmiss ,.BR cap_miss ,.BR cap_blockmiss ,.BR conf_miss ,and.BR conf_blockmiss ,described more fully in.BR "D4CACHE RESULT FIELDS" ,below..IP \f3D4F_RO\fP 10nStates that the cache is read-only, e.g., an instruction cache.This assertion is checked if Dinero IV is configured with debugging enabled.In a customized version, a read-only cache is slightly more efficientthan another cache without the.B D4F_ROflag, because certain run-time checks for writes can be avoided..PPOther flag values may be defined in future revisions of Dinero IV.User-written policy functions may also use flags in this field;the value.B D4F_USERFLAG1is the smallest such flag:it and all larger ones are available for use for any purpose..RE.IP \f3lg2blocksize\fP 15nMust be set to the log of the block size for the cache..IP \f3lg2subblocksize\fP 15nMust be set to the log of the sub-block size for the cache.If sub-blocks are not to be used,this field should be given the same value as.BR lg2blocksize ..IP \f3lg2size\fP 15nMust be set to the log of the total size of the cache..IP \f3assoc\fP 15nMust be set to the associativity of the cache..IP \f3replacementf\fP 15nThis is a function pointer to define the replacement policy for the cache.Any suitable user-written function may be used,or one of several standard functions provided by Dinero IV (and declared in.BR d4.h )may be used:.RS.IP \f3d4rep_lru\fP 15nThe Least Recently Used policy..IP \f3d4rep_fifo\fP 15nThe First In/First Out policy..IP \f3d4rep_random\fP 15nThe random replacement policy..RE.IP \f3prefetchf\fP 15nThis is a function pointer to define the prefetch policy for the cache.Any suitable user-written function may be used,or one of several standard functions provided by Dinero IV (and declared in.BR d4.h )may be used:.RS.IP \f3d4prefetch_none\fP 20nNo prefetching at all..IP \f3d4prefetch_always\fP 20nAlways initiate a prefetch after every non-prefetch reference,except for access type.BR D4XMISC ..IP \f3d4prefetch_loadforw\fP 20nThe ``load forward'' prefetch policy:don't prefetch into the next cache block..IP \f3d4prefetch_subblock\fP 20nThe ``sub-block'' prefetch policy:don't prefetch into the next cache block,wrap around within the referenced block instead..IP \f3d4prefetch_miss\fP 20nThe ``miss'' prefetch policy:prefetch only on cache misses..IP \f3d4prefetch_tagged\fP 20nThe ``tagged'' prefetch policy:initiate a prefetch on the first demand reference to a (sub)-block.Thus, a prefetch is initiated on a demand miss or the first demandreference to a (sub)-block that was brought into the cache by a prefetch..PPThe standard prefetch policy functions (except for.BR d4prefetch_none )also make use of the following two fields:.RE.IP \f3prefetch_distance\fP 15nThe prefetch distance in sub-blocks.A value of 1 means that the next sequential sub-block isthe potential target of a prefetch..IP \f3prefetch_abortpercent\fP 15nThe percentage of prefetches that are aborted.This can be used to examine the effects of data referencesblocking prefetch references from reaching a shared cache..IP \f3wallocf\fP 15nThis is a function pointer to define the write allocate policy for the cache.The write allocate policy determineswhether a (sub-)block is allocated on a write miss.Any suitable user-written function may be used,or one of several standard functions provided by Dinero IV (and declared in.BR d4.h )may be used:.RS.IP \f3d4walloc_always\fP 20nAllocate on every write miss..IP \f3d4walloc_never\fP 20nNever allocate on any write miss (i.e., this is a non-write-allocate policy)..IP \f3d4walloc_nofetch\fP 20nAllocate on a write miss as long as no fetch is required.A fetch would be requiredif the write was not for an integral number of sub-blocks..IP \f3d4walloc_impossible\fP 20nThis ``policy'' prints an error message and terminates the program;it is for use only on read-only caches (e.g., instruction caches)..RE.IP \f3wbackf\fP 15nThis is a function pointer to define the write back policy for the cache.The write back policy determineswhen the (sub-)block is allowed to have dirty data.Any suitable user-written function may be used,or one of several standard functions provided by Dinero IV (and declared in.BR d4.h )may be used: