/* ?misc.h?-?miscellaneous?interfaces? */

/* ?SimpleScalar(TM)?Tool?Suite
?*?Copyright?(C)?1994-2003?by?Todd?M.?Austin,?Ph.D.?and?SimpleScalar,?LLC.
?*?All?Rights?Reserved.?
?*?
?*?THIS?IS?A?LEGAL?DOCUMENT,?BY?USING?SIMPLESCALAR,
?*?YOU?ARE?AGREEING?TO?THESE?TERMS?AND?CONDITIONS.
?*?
?*?No?portion?of?this?work?may?be?used?by?any?commercial?entity,?or?for?any
?*?commercial?purpose,?without?the?prior,?written?permission?of?SimpleScalar,
?*?LLC?(info@simplescalar.com).?Nonprofit?and?noncommercial?use?is?permitted
?*?as?described?below.
?*?
?*?1.?SimpleScalar?is?provided?AS?IS,?with?no?warranty?of?any?kind,?express
?*?or?implied.?The?user?of?the?program?accepts?full?responsibility?for?the
?*?application?of?the?program?and?the?use?of?any?results.
?*?
?*?2.?Nonprofit?and?noncommercial?use?is?encouraged.?SimpleScalar?may?be
?*?downloaded,?compiled,?executed,?copied,?and?modified?solely?for?nonprofit,
?*?educational,?noncommercial?research,?and?noncommercial?scholarship
?*?purposes?provided?that?this?notice?in?its?entirety?accompanies?all?copies.
?*?Copies?of?the?modified?software?can?be?delivered?to?persons?who?use?it
?*?solely?for?nonprofit,?educational,?noncommercial?research,?and
?*?noncommercial?scholarship?purposes?provided?that?this?notice?in?its
?*?entirety?accompanies?all?copies.
?*?
?*?3.?ALL?COMMERCIAL?USE,?AND?ALL?USE?BY?FOR?PROFIT?ENTITIES,?IS?EXPRESSLY
?*?PROHIBITED?WITHOUT?A?LICENSE?FROM?SIMPLESCALAR,?LLC?(info@simplescalar.com).
?*?
?*?4.?No?nonprofit?user?may?place?any?restrictions?on?the?use?of?this?software,
?*?including?as?modified?by?the?user,?by?any?other?authorized?user.
?*?
?*?5.?Noncommercial?and?nonprofit?users?may?distribute?copies?of?SimpleScalar
?*?in?compiled?or?executable?form?as?set?forth?in?Section?2,?provided?that
?*?either:?(A)?it?is?accompanied?by?the?corresponding?machine-readable?source
?*?code,?or?(B)?it?is?accompanied?by?a?written?offer,?with?no?time?limit,?to
?*?give?anyone?a?machine-readable?copy?of?the?corresponding?source?code?in
?*?return?for?reimbursement?of?the?cost?of?distribution.?This?written?offer
?*?must?permit?verbatim?duplication?by?anyone,?or?(C)?it?is?distributed?by
?*?someone?who?received?only?the?executable?form,?and?is?accompanied?by?a
?*?copy?of?the?written?offer?of?source?code.
?*?
?*?6.?SimpleScalar?was?developed?by?Todd?M.?Austin,?Ph.D.?The?tool?suite?is
?*?currently?maintained?by?SimpleScalar?LLC?(info@simplescalar.com).?US?Mail:
?*?2395?Timbercrest?Court,?Ann?Arbor,?MI?48105.
?*?
?*?Copyright?(C)?1994-2003?by?Todd?M.?Austin,?Ph.D.?and?SimpleScalar,?LLC.
? */

/* *
工具函數(shù)文件

這個文件定義了一些通用的工具函數(shù)

@file?misc.h
@author?www.simplescalar.com(編寫)
@author?xieyubo@gmail.com(中文注釋)
*/

#ifndef?MISC_H
#define ?MISC_H

#include? < stdio.h >
#include? < stdlib.h >
#include? < stdarg.h >
#include? < string .h >
#include? < sys / types.h >

/* ?boolean?value?defs? */
/// ?定義一些bool值
#ifndef?TRUE
#define ?TRUE?1
#endif
#ifndef?FALSE
#define ?FALSE?0
#endif

/* ?various?useful?macros? */
/// ?定義求最大數(shù)的宏
#ifndef?MAX
#define ?MAX(a,?b)????(((a)?<?(b))???(b)?:?(a))
#endif
/// ?定義求最小數(shù)的宏
#ifndef?MIN
#define ?MIN(a,?b)????(((a)?<?(b))???(a)?:?(b))
#endif

/* ?for?printing?out?"long?long"?vars? */
/// ?獲得long?long的高32位
#define ?LLHIGH(L)????????((int)(((L)>>32)?&?0xffffffff))
/// ?獲得long?long的低32位
#define ?LLLOW(L)????????((int)((L)?&?0xffffffff))

/* ?size?of?an?array,?in?elements? */
/// ?獲和數(shù)組中元素的個數(shù)
#define ?N_ELT(ARR)???(sizeof(ARR)/sizeof((ARR)[0]))

/* ?rounding?macros,?assumes?ALIGN?is?a?power?of?two? */
/// ?向上取整
#define ?ROUND_UP(N,ALIGN)????(((N)?+?((ALIGN)-1))?&?~((ALIGN)-1))
/// ?向下取整
#define ?ROUND_DOWN(N,ALIGN)????((N)?&?~((ALIGN)-1))

/* ?verbose?output?flag? */
/// ?詳細信息輸出標志
extern ? int ?verbose;

#ifdef?DEBUG
/* ?active?debug?flag? */
/// ?調(diào)試標志
extern ? int ?debugging;
#endif ?/*?DEBUG?*/

/* ?register?a?function?to?be?called?when?an?error?is?detected? */
/// ?注冊一個出錯處理函數(shù)
void
fatal_hook( void ?( * hook_fn)(FILE? * stream));???? /* ?fatal?hook?function? */

#ifdef?__GNUC__
/* ?declare?a?fatal?run-time?error,?calls?fatal?hook?function? */
/// ?定義錯誤處理的宏
#define ?fatal(fmt,?args)????\
??_fatal(__FILE__,?__FUNCTION__,?__LINE__,?fmt,?##?args)

void
_fatal( char ? * file,? char ? * func,? int ?line,? char ? * fmt,?)
__attribute__?((noreturn));
#else ?/*?!__GNUC__?*/
void
fatal( char ? * fmt,?);
#endif ?/*?!__GNUC__?*/

#ifdef?__GNUC__
/* ?declare?a?panic?situation,?dumps?core? */
/// ?定義一個錯誤處理函數(shù),?會直接調(diào)用abort()終止程序
#define ?panic(fmt,?args)????\
??_panic(__FILE__,?__FUNCTION__,?__LINE__,?fmt,?##?args)

void
_panic( char ? * file,? char ? * func,? int ?line,? char ? * fmt,?)
__attribute__?((noreturn));
#else ?/*?!__GNUC__?*/
void
panic( char ? * fmt,?);
#endif ?/*?!__GNUC__?*/

#ifdef?__GNUC__
/* ?declare?a?warning? */
/// ?定義一個警告函數(shù)
#define ?warn(fmt,?args)????\
??_warn(__FILE__,?__FUNCTION__,?__LINE__,?fmt,?##?args)

void
_warn( char ? * file,? char ? * func,? int ?line,? char ? * fmt,?);
#else ?/*?!__GNUC__?*/
void
warn( char ? * fmt,?);
#endif ?/*?!__GNUC__?*/

#ifdef?__GNUC__
/* ?print?general?information? */
/// ?打印通用的信息
#define ?info(fmt,?args)????\
??_info(__FILE__,?__FUNCTION__,?__LINE__,?fmt,?##?args)

void
_info( char ? * file,? char ? * func,? int ?line,? char ? * fmt,?);
#else ?/*?!__GNUC__?*/
void
info( char ? * fmt,?);
#endif ?/*?!__GNUC__?*/

#ifdef?DEBUG

#ifdef?__GNUC__
/* ?print?a?debugging?message? */
/// ?打印調(diào)試信息
#define ?debug(fmt,?args)????\
???? do ?{????????????????????????\
???????? if ?(debugging)?????????????\
????????????_debug(__FILE__,?__FUNCTION__,?__LINE__,?fmt,?##?args);?\
????}? while ( 0 )

void
_debug( char ? * file,? char ? * func,? int ?line,? char ? * fmt,?);
#else ?/*?!__GNUC__?*/
void
debug( char ? * fmt,?);
#endif ?/*?!__GNUC__?*/

#else ?/*?!DEBUG?*/

#ifdef?__GNUC__
#define ?debug(fmt,?args)
#else ?/*?!__GNUC__?*/
/* ?the?optimizer?should?eliminate?this?call!? */
static ? void ?debug( char ? * fmt,?)?{}
#endif ?/*?!__GNUC__?*/

#endif ?/*?!DEBUG?*/

/* ?seed?the?random?number?generator? */
/// ?設(shè)定隨機數(shù)種子
void
mysrand(unsigned? int ?seed);???? /* ?random?number?generator?seed? */

/* ?get?a?random?number? */
/// ?產(chǎn)生一個隨機數(shù)
int ?myrand( void );???????? /* ?returns?random?number? */

/* ?copy?a?string?to?a?new?storage?allocation?(NOTE:?many?machines?are?missing
???this?trivial?function,?so?I?funcdup()?it?here)? */
/* *
復制一個新的字符串

@param[in]?s?待復制的字符串
@return?返回復制的字符串指針
*/
char ? * ???????????????? /* ?duplicated?string? */
mystrdup( char ? * s);???????? /* ?string?to?duplicate?to?heap?storage? */

/* ?find?the?last?occurrence?of?a?character?in?a?string? */
/* *
查找一個字符在字符串中最后出現(xiàn)的位置

@param[in]?s?原字符串
@param[in]?c?待查找的字符
@return?指向待查找字符位置的字符串指針
*/
char ? *
mystrrchr( char ? * s,? char ?c);

/* ?case?insensitive?string?compare?(NOTE:?many?machines?are?missing?this
???trivial?function,?so?I?funcdup()?it?here)? */
/* *
對兩個字符串進行大小寫無關(guān)的比較

@param[in]?s1?待比較的字符串1
@param[in]?s2?待比較的字符串2
@retval?<0?s1小于s2
@retval?=0?s1等于s2
@retval?>0?s1大于s2
*/
int ???????????????? /* ?compare?result,?see?strcmp()? */
mystricmp( char ? * s1,? char ? * s2);???? /* ?strings?to?compare,?case?insensitive? */

/* ?allocate?some?core,?this?memory?has?overhead?no?larger?than?a?page
???in?size?and?it?cannot?be?released.?the?storage?is?returned?cleared? */
/* *
分配指定大小的內(nèi)存

@param[in]?nbytes?指定的字節(jié)數(shù)
@return?分配的內(nèi)存的指針
*/
void ? * getcore( int ?nbytes);

/* ?return?log?of?a?number?to?the?base?2? */
/* *
計算log2
*/
int ?log_base2( int ?n);

/* ?return?string?describing?elapsed?time,?passed?in?SEC?in?seconds? */
/* *
構(gòu)造一個描述耗時多少的字符串
*/
char ? * elapsed_time( long ?sec);

/* *
從指定的32位的數(shù)中截取出指定長度的位數(shù)

@param[in]?word?指定的32位數(shù)
@param[in]?pos?開始截中的位置
@param[in]?num?指定的長度
@return?返回所截取出來的位數(shù)
*/
/* ?assume?bit?positions?numbered?31?to?0?(31?high?order?bit),?extract?num?bits
???from?word?starting?at?position?pos?(with?pos?as?the?high?order?bit?of?those
???to?be?extracted),?result?is?right?justified?and?zero?filled?to?high?order
???bit,?for?example,?extractl(word,?6,?3)?w/?8?bit?word?=?01101011?returns
???00000110? */
unsigned? int
extractl( int ?word,???????? /* ?the?word?from?which?to?extract? */
????????? int ?pos,???????? /* ?bit?positions?31?to?0? */
????????? int ?num);???????? /* ?number?of?bits?to?extract? */

#if ?defined(sparc)?&&?!defined(__svr4__)
#define ?strtoul?strtol
#endif

/* ?portable?64-bit?I/O?package? */

/* ?portable?vsprintf?with?qword?support,?returns?end?pointer? */
/* *
輸出格式化字符串到緩沖區(qū)中

@param[in]?obuf?緩沖區(qū)
@param[in]?format?格式
@param[in]?v?參數(shù)
@return?緩沖區(qū)中字符串結(jié)束的指針
*/ ?
char ? * myvsprintf( char ? * obuf,? char ? * format,?va_list?v);

/* ?portable?sprintf?with?qword?support,?returns?end?pointer? */
/* *
輸出格式化字符串到緩沖區(qū)中

@param[in]?obuf?緩沖區(qū)
@param[in]?format?格式
@param[in]??參數(shù)
@return?緩沖區(qū)中字符串結(jié)束的指針
*/
char ? * mysprintf( char ? * obuf,? char ? * format,?);

/* ?portable?vfprintf?with?qword?support,?returns?end?pointer? */
/* *
輸出格式化字符串到文件中

@param[in]?stream?文件指針
@param[in]?format?格式
@param[in]?v?參數(shù)
*/
void ?myvfprintf(FILE? * stream,? char ? * format,?va_list?v);

/* ?portable?fprintf?with?qword?support,?returns?end?pointer? */
/* *
輸出格式化字符串到文件中

@param[in]?stream?文件指針
@param[in]?format?格式
@param[in]??參數(shù)
*/
void ?myfprintf(FILE? * stream,? char ? * format,?);

#ifdef?HOST_HAS_QWORD

/* ?convert?a?string?to?a?signed?result? */
sqword_t?myatosq( char ? * nptr,? char ? ** endp,? int ? base );

/* ?convert?a?string?to?a?unsigned?result? */
qword_t?myatoq( char ? * nptr,? char ? ** endp,? int ? base );

#endif ?/*?HOST_HAS_QWORD?*/

/* ?same?semantics?as?fopen()?except?that?filenames?ending?with?a?".gz"?or?".Z"
???will?be?automagically?get?compressed? */
/* *
打開文件

如果文件以".gz"或".Z"結(jié)尾,?則其中自解壓功能

@param[in]?fname?待打開的文件名
@param[in]?type?打開方式
@return?打開后的文件指針
*/
FILE? * gzopen( char ? * fname,? char ? * type);

/* ?close?compressed?stream? */
/* *
關(guān)閉文件

@param[in]?fd?待關(guān)閉的文件指針
*/
void ?gzclose(FILE? * fd);

/* ?update?the?CRC?on?the?data?block?one?byte?at?a?time? */
/* *
對數(shù)據(jù)塊進行CRC效驗

其中word_t被定義為了unsigned?int
*/
word_t?crc(word_t?crc_accum,?word_t?data);

#endif ?/*?MISC_H?*/