1: /* In this file you will find everything you will ever need to know
     2:    about the usage of exMARS. I have tried to make it as useable as
     3:    possible.
     4:   
     5:    Here is a quick and simple example how exMARS is used:
     6:   
     7:      mars_t* mars = exmars_new_94nop(2);
     8: 	 warrior_t* w1 = exmars_parse(mars, "reepicheep.red");
     9: 	 warrior_t* w2 = exmars_parse(mars, "imp.red");
    10: 	 exmars_simulate(mars, w1, w2);
    11: 	 printf("%s", exmars_resultstr(mars));
    12: 	 exmars_free_mars(mars);
    13: 	 exmars_free_warrior(w1);
    14: 	 exmars_free_warrior(w2);
    15: 
    16:    To find out the real power of exMARS, read through this file.
    17:  */
    18: #include "exhaust.h" 
    19: 
    20: 
    21: /** 1. MARS creation *********************************************************/
    22: /* create a new mars simulator */
    23: mars_t* exmars_new(int warriorCount,
    24: 				   field_t coreSize,
    25: 				   u32_t cycles,
    26: 				   u32_t maxProcesses,
    27: 				   u32_t maxWarriorLen,
    28: 				   u32_t minWarriorDist);
    29: 
    30: /* other, more convenient mars creation functions */
    31: mars_t* exmars_new_94nop(int warriorCount);
    32: mars_t* exmars_new_tiny(int warrriorCount);
    33: 
    34: 
    35: 
    36: /** 2. Warrior loading *******************************************************/
    37: /* read in and return a warrior */
    38: warrior_t* exmars_parse(mars_t* mars, char* inputFileName);
    39: 
    40: 
    41: 
    42: /** 3. Fight simulation ******************************************************/
    43: /* simulate all specified warriors */
    44: void exmars_simulate(mars_t* mars, warrior_t** warriorArray);
    45: 
    46: 
    47: 
    48: /** 4. Find out simulation results *******************************************/
    49: /* print results in KotH format */
    50: char* exmars_resultstr(warrior_t** warriorArray);
    51: 
    52: /* you can write your own score formula, e.g like this:
    53:  *
    54:  *   // W=wins, S=survivors
    55:  *   int my_own_score_formula(int W, int S) { 
    56:  *     return (W*W-1)/S;
    57:  *   }
    58:  *   // register score formula
    59:  *   exmars_score_formula(mars, my_own_score_formula);
    60:  *
    61:  *   // get score of warrior
    62:  *   int score = exmars_score(mars, warrior);
    63:  */
    64: void exmars_set_score_formula(int (*scoreFormula)(int warriorCount, int survivorCount));
    65: int exmars_last_score(mars_t* mars, warrior_t* warrior);
    66: int exmars_total_score(mars_t* mars, warrior_t* warrior);
    67: 
    68: 
    69: 
    70: /** 5. Free resources ********************************************************/
    71: void exmars_free_mars(mars_t* mars);
    72: void exmars_free_warrior(warrior_t* warrior);
    73: 
    74: 
    75: 
    76: /** Appendix A: Other more or less useful functions **************************/
    77: /* get mars settings */
    78: u32_t exmars_get_rounds(mars_t* mars);
    79: u32_t exmars_get_coresize(mars_t* mars);
    80: u32_t exmars_get_cycles(mars_t* mars);
    81: u32_t exmars_get_max_processes(mars_t* mars);
    82: u32_t exmars_get_max_length(mars_t* mars);
    83: u32_t exmars_get_min_distance(mars_t* mars);
    84: u32_t exmars_get_warriors(mars_t* mars);
    85: 
    86: /* some settings can be changed without creating a new mars */
    87: void exmars_set_rounds(mars_t* mars, u32_t newRounds);
    88: void exmars_set_cycles(mars_t* mars, u32_t newCycles);
    89: 
    90: 
    91: 
    92: /** Appendix B: Warrior and Instruction structures ***************************/
    93: 
    94: /*
    95:  * Encodings for various fields of the `in' field.
    96:  * 
    97:  */
    98: enum emars_opcode {
    99:     DAT, SPL, MOV, DJN, ADD,
   100:     JMZ, SUB, SEQ, SNE, SLT,
   101:     JMN, JMP, NOP, MUL, MODM,
   102:     DIV, LDP, STP, 	
   103: 	EXMARS_OP_COUNT /* 18 */
   104: };
   105: 
   106: enum exmars_modifier {
   107:     mF, mA, mB, mAB, mBA,
   108: 	mX, mI,
   109: 	EXMARS_MODIFIER_COUNT /* 7 */
   110: };
   111: 
   112: enum exmars_addrmode {
   113:     DIRECT,    /* $ */
   114:     IMMEDIATE, /* # */
   115:     BINDIRECT, /* @ */
   116:     BPREDEC,   /* < */
   117:     BPOSTINC,  /* > */
   118:     AINDIRECT, /* * */
   119:     APREDEC,   /* { */
   120:     APOSTINC,  /* } */ 
   121: 	EXMARS_ADDRMODE_COUNT /* 8 */
   122: };
   123: 
   124: typedef struct exmars_ins
   125: {
   126:     enum exmars_opcode opcode;
   127:     enum exmars_modifier modifier;
   128:     enum exmars_addrmode addrmode_a;
   129:     long val_a;
   130:     enum exmars_addrmode addrmode_b;
   131: 	long val_b;
   132: } exmars_ins;
   133: 
   134: 
   135: typedef struct exmars_warrior 
   136: {
   137:     u32_t length;
   138:     u32_t startOffset; /* offset specified by 'ORG' or 'END' */
   139: 
   140:     exmars_ins* code;
   141: 
   142:     /* The indexer specifies the nr. of survivors.
   143: 	
   144: 	   e.g. 1-on-1 fights:
   145:           w->lastWins[0]:  nr of wins of warrior w
   146:           w->lastWins[1]:  nr of ties of warrior w
   147:           
   148:        e.g 4 warriors (muliwarrior)
   149:           w->lastWins[0]: nr. of times this warrior was last man standing
   150:           w->lastWins[1]: nr. of times this warrior and a second one survived
   151:           w->lastWins[2]: nr. of times this and 2 other warriors survived
   152:           w->lastWins[3]: nr. of times no warrior died
   153:     */
   154:     u32_t* lastWins;
   155: 	/* nr of times warrior has not survived */
   156:     u32_t lastLosses;
   157: 
   158: 	/* scores adds up after every simulation */
   159:     u32_t* totalWins;
   160:     u32_t totalLosses;    
   161: 
   162:     char* name;
   163:     char* version;
   164:     char* date;
   165:     char* fileName;
   166:     char* authorName;
   167: } exmars_warrior;
   168: 
   169: 
   170: 
   171: /* If you find anything unclear, or have have any questions or
   172:  * suggestion, please tell me!  <martinankerl at eml dot cc> */
   173: