src/main/inc/freeEMS.h

   1 /* FreeEMS - the open source engine management system
   2  *
   3  * Copyright 2008-2012 Fred Cooke
   4  *
   5  * This file is part of the FreeEMS project.
   6  *
   7  * FreeEMS software is free software: you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation, either version 3 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * FreeEMS software is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with any FreeEMS software.  If not, see http://www.gnu.org/licenses/
  19  *
  20  * We ask that if you make any changes to this file you email them upstream to
  21  * us at admin(at)diyefi(dot)org or, even better, fork the code on github.com!
  22  *
  23  * Thank you for choosing FreeEMS to run your engine!
  24  */
  25
  26
  27 /** @file
  28  *
  29  * @ingroup allHeaders
  30  * @ingroup globalHeaders
  31  *
  32  * @brief The main project header file
  33  *
  34  * The central header for all source files to include. This pulls in the
  35  * device header, all other shared headers, all global defines, all global
  36  * constant declarations, all type definitions and all global variables. Other
  37  * variables that are actually in global space but only shared between a few
  38  * select files should be placed in the header for the main file that uses them.
  39  */
  40
  41
  42 /* Header file multiple inclusion protection courtesy eclipse Header Template */
  43 /* and http://gcc.gnu.org/onlinedocs/gcc-3.1.1/cpp/ C pre processor manual    */
  44 #ifndef FILE_FREEEMS_H_SEEN
  45 #define FILE_FREEEMS_H_SEEN
  46
  47
  48 /* Include top level files that everything else relies on */
  49 #include "memory.h"
  50 #include "9S12XDP512.h"
  51 #include "flashGlobals.h" /// @todo TODO For Sean to integrate back in
  52 ///include "registerMasks.h @todo TODO we should define the register masks that we use in one place, but probably not in the main device header.
  53
  54 /* Include define files at the top here as other includes use them */
  55 #include "systemConfig.h"
  56 #include "errorDefines.h"
  57 #include "globalDefines.h"
  58 #include "scalerDefines.h"
  59 #include "constantsLibrary.h"
  60 #include "9S12XDP512flags.h"
  61
  62 /* Include data types at the top as other includes use them */
  63 #include "generalTypes.h"
  64 #include "counterTypes.h"
  65 #include "containerTypes.h"
  66 #include "tableTypes.h"
  67 #include "FixedConfigs.h"
  68 #include "TunableConfigs.h"
  69
  70 /* Run size checks on all of the key struct types! */
  71 #include "typeChecks.h"
  72
  73 /* Global constant declarations */
  74 #include "globalConstants.h"
  75
  76
  77 /* Where extern is used instead of EXTERN it indicates that    */
  78 /* the variable is initialised in staticInit.c, if someone     */
  79 /* attempts to use extern and doesn't initialise the variable  */
  80 /* statically then the linker should error on undefined symbol */
  81
  82
  83 #ifdef EXTERN
  84 #warning "EXTERN already defined by another header, please sort it out!"
  85 #undef EXTERN /* If fail on warning is off, remove the definition such that we can redefine correctly. */
  86 #endif
  87
  88
  89 #ifdef FREEEMS_C
  90 #define EXTERN
  91 #else
  92 #define EXTERN extern
  93 #endif
  94
  95
  96 /* Types summary
  97  *
  98  * BEWARE : Be explicit!!
  99  *
 100  * char        8 bit (defaults to unsigned, but always specify signed/unsigned anyway)
 101  * short      16 bit (defaults to signed, but always specify signed/unsigned anyway)
 102  * int        16 bit DO NOT USE! (current compile flags make this 16 bits, but a change of flags could will change your program if you use this because they will all be 32 bit all of a sudden)
 103  * long       32 bit (defaults to signed, but always specify signed/unsigned anyway)
 104  * long long  64 bit (inefficient, avoid these, if using : defaults to signed, but always specify signed/unsigned anyway)
 105  * float      32 bit IEEE floating point numbers (inefficient, avoid these, used fixed point math)
 106  * double     64 bit IEEE floating point numbers (inefficient, avoid these, used fixed point math)
 107  */
 108
 109
 110 /* GLOBAL Variables */
 111 // TODO change any of these that need it to volatile!!!
 112
 113
 114 // temporary test vars
 115 EXTERN unsigned char portHDebounce;
 116
 117
 118 /* Declare instances of variable structs for use */
 119 EXTERN Clock Clocks;                  ///< Timer Clocks for various functions.
 120 EXTERN Counter Counters;              ///< Execution count for various blocks of code.
 121 EXTERN KeyUserDebug KeyUserDebugs;    ///< Formalised key logging vars in one place.
 122 EXTERN Flaggable Flaggables;          ///< The single instance of our flaggable struct.
 123
 124 /** @page bankedRunningVariables Banked Running Variables
 125  *
 126  * This page is to document and explain the operation of the banked running variable system and structure.
 127  *
 128  * The program running variables are divided into three broad groups: inputs, working
 129  * and outputs. For both the input and output groups there are two copies of each set
 130  * of variables, whereas there is only one copy of each set in the working group. This
 131  * is required to allow both the inputs and outputs to be safely written and read at
 132  * the same time. To facilitate this all sets of variables within the input and output
 133  * groups are referenced with two pointers each. For the input group, the copy pointed
 134  * to is swapped when fresh data is both available to and required by the mathematics
 135  * function. For the output group the copy pointed to is swapped when the mathematics
 136  * function has produced new output data. The input data is supplied by the engine
 137  * position interrupt service routines as ADC readings and RPM values. The output data
 138  * consists of pulse widths, timing angles, dwell periods and scheduling information.
 139  *
 140  * Accessory functions (Idle, Boost, etc)
 141  *
 142  * In order to achieve minimal latency and maximum frequency of execution of the
 143  * main mathematics code the accessory functions must run asynchronously. Although
 144  * we can guarantee that these functions will base their calculations on a matched
 145  * set of data, we can not guarantee that it will be the same set of data presented
 146  * along side the accessory data in the data log. Thus, where it is required to see
 147  * the inputs that an accessory functions calculations were based on, those values
 148  * should be cached for logging on a per function basis.
 149  *
 150  * Although it seems like a lot of trouble to go to, it is critical to transient
 151  * performance that the environmental conditions the engine is operating under are
 152  * tracked and reacted to as quickly as possible. Having the less important stuff
 153  * run asynchronously will result in an order of magnitude improvement of parameter
 154  * tracking and is well worth the extra memory expense and complication.
 155  */
 156
 157 EXTERN CoreVar* CoreVars; /** Pointer to the core running variables */
 158 EXTERN CoreVar CoreVars0; /** Bank 0 core running variables */
 159 /* If we move to xgate or isr driven logging, add bank 1 back in */
 160
 161 EXTERN DerivedVar* DerivedVars; /** Pointer to the secondary running variables */
 162 EXTERN DerivedVar DerivedVars0; /** Bank 0 secondary running variables */
 163 /* If we move to xgate or isr driven logging, add bank 1 back in */
 164
 165 EXTERN ADCBuffer* ADCBuffers;       /** main adc storage area for syncronous sampling in the engine position ISR or injection ISR or ignition ISR etc. */
 166 EXTERN ADCBuffer* ADCBuffersRecord; /** main adc storage area for syncronous sampling in the engine position ISR or injection ISR or ignition ISR etc. */
 167 EXTERN ADCBuffer ADCBuffers0;       /** main adc storage area for syncronous sampling in the engine position ISR or injection ISR or ignition ISR etc. */
 168 EXTERN ADCBuffer ADCBuffers1;       /** main adc storage area for syncronous sampling in the engine position ISR or injection ISR or ignition ISR etc. */
 169
 170 /*break this on purpose so i fix it later
 171 #define VETablereference (*((volatile mainTable*)(0x1000)))
 172 EXTERN const mainTable *VETableRef;
 173 PLUS
 174 const volatile mainTable *VETableRef = (volatile mainTable*)0x1000;
 175 broken too, need to research how to do this.
 176
 177 see line 80 or so from inc/injectorISR.c for array of pointer use. the above may not be possible... TODO */
 178
 179
 180 /* Potentially pointers for data in RAM depending on how it gets implemented */
 181 // volatile ??
 182 //EXTERN tunableConfig tunableConfigs;
 183
 184 /* Layout the tunable copies and buffers in RAM space */
 185
 186
 187
 188 /* TODO explanation of paged RAM operation Unions for paged large table access using RPAGE */
 189 typedef union {
 190         mainTable VETableMain;
 191         mainTable IgnitionAdvanceTableMain;
 192         SmallTables1 SmallTablesA;
 193 } Tables1;
 194
 195 typedef union {
 196         mainTable VETableSecondary;
 197         mainTable IgnitionAdvanceTableSecondary;
 198         SmallTables2 SmallTablesB;
 199 } Tables2;
 200
 201 typedef union {
 202         mainTable VETableMainTertiary;
 203         mainTable InjectionAdvanceTableMain;
 204         SmallTables3 SmallTablesC;
 205 } Tables3;
 206
 207 typedef union {
 208         mainTable LambdaTable;
 209         mainTable InjectionAdvanceTableSecondary;
 210         SmallTables4 SmallTablesD;
 211 } Tables4;
 212
 213
 214 /* Large blocks */
 215 EXTERN unsigned char TXBuffer[TX_BUFFER_SIZE] TXBUF;
 216 EXTERN unsigned char RXBuffer[RX_BUFFER_SIZE] RXBUF;
 217 EXTERN Tables1 TablesA RWINDOW;
 218 EXTERN Tables2 TablesB RWINDOW;
 219 EXTERN Tables3 TablesC RWINDOW;
 220 EXTERN Tables4 TablesD RWINDOW;
 221
 222
 223 /* RAM page variables */
 224 EXTERN unsigned char currentFuelRPage;
 225 EXTERN unsigned char currentTuneRPage;
 226 EXTERN unsigned char currentTimeRPage;
 227
 228
 229 /* These are inited once and remain the same, rpage switches change meaning. */
 230
 231 ///* Pointers to main tables to aid readability */
 232 //EXTERN mainTable* VETableMain;
 233 //EXTERN mainTable* VETableSecondary;
 234 //EXTERN mainTable* VETableTertiary;
 235 //EXTERN mainTable* LambdaTable;
 236 //
 237 //EXTERN mainTable* IgnitionAdvanceTableMain;
 238 //EXTERN mainTable* IgnitionAdvanceTableSecondary;
 239 //EXTERN mainTable* InjectionAdvanceTableMain;
 240 //EXTERN mainTable* InjectionAdvanceTableSecondary;
 241 //
 242 ///* Pointers to SmallTablesA */
 243 //EXTERN twoDTableUS* dwellDesiredVersusVoltageTable;
 244 //EXTERN twoDTableUS* injectorDeadTimeTable;
 245 //EXTERN twoDTableUS* postStartEnrichmentTable;
 246 //EXTERN twoDTableUS* engineTempEnrichmentTableFixed;
 247 //EXTERN twoDTableUS* primingVolumeTable;
 248 //EXTERN twoDTableUS* engineTempEnrichmentTablePercent;
 249 //EXTERN twoDTableUS* dwellVersusRPMTable;
 250 /* Pointers to SmallTablesB */
 251 /* Pointers to SmallTablesC */
 252 /* Pointers to SmallTablesD */
 253
 254
 255 /* Output variables (init not required) TODO ditch this in favour of the real vars in the calcs function and struct */
 256 extern unsigned short masterPulseWidth;
 257 EXTERN unsigned long bootFuelConst;  /* constant derived from configurable constants */
 258 EXTERN unsigned short TPSADCRange;   /* The ADC range used to generate TPS percentage */
 259
 260
 261 /* ALL STATUS STUFF HERE */
 262
 263 /* State variables : 0 = false (don't forget to change the init mask to suit!) */
 264 EXTERN unsigned char coreStatusA;       /* Each bit represents the state of some core parameter, masks below */
 265 /* Bit masks for coreStatusA */ // TODO needs a rename as does coresetingsA
 266 #define FUEL_PUMP_PRIME BIT0 /* 0 */
 267 #define STAGED_REQUIRED BIT1 /* 1 Fire the staged injectors */
 268 #define CALC_FUEL_IGN   BIT2 /* 2 Fuel and ignition require calculation (i.e. variables have been updated) */
 269 #define FORCE_READING   BIT3 /* 3 Flag to force ADC sampling at low rpm/stall */
 270 #define BENCH_TEST_ON   BIT4 /* 4 Bench test running TEMPORARY */
 271 #define COREA05         BIT5 /* 5 */
 272 #define COREA06         BIT6 /* 6 */
 273 #define COREA07         BIT7 /* 7 */
 274
 275
 276 #define CLEAR_FUEL_PUMP_PRIME NBIT0 /* */
 277 #define STAGED_NOT_REQUIRED   NBIT1 /*  9 Do not fire the staged injectors */
 278 #define CLEAR_CALC_FUEL_IGN   NBIT2 /* 10 Fuel and ignition don't require calculation */
 279 #define CLEAR_FORCE_READING   NBIT3 /* 11 Clear flag to force ADC sampling at low rpm/stall */
 280 #define CLEAR_BENCH_TEST_ON   NBIT4
 281
 282 //TODO make this volatile?
 283 /* ECT IC extension variable (init not required, don't care where it is, only differences between figures) */
 284 unsigned short timerExtensionClock; /* Increment for each overflow of the main timer, allows finer resolution and longer time period */
 285 /* section 10.3.5 page 290 68hc11 reference manual e.g. groups.csail.mit.edu/drl/courses/cs54-2001s/pdf/M68HC11RM.pdf */
 286
 287
 288 // Default to off
 289 #ifndef DECODER_BENCHMARKS
 290 #define DECODER_BENCHMARKS FALSE
 291 #else
 292 #undef DECODER_BENCHMARKS
 293 #define DECODER_BENCHMARKS TRUE
 294 #endif
 295
 296
 297 /** This macro turns a pin ON based on an enable flag, a port address and a pin
 298  * mask for that port. It is used to keep the code clean and free from ifdefs
 299  * whilst allowing a developer to turn on benchmarking outputs very easily. Note
 300  * that it gets optimised out due to the constant literal conditional required.
 301  */
 302 #define DEBUG_TURN_PIN_ON(BENCHMARK_ENABLED, PIN_ON_MASK, PORT_ADDRESS)   \
 303 if(BENCHMARK_ENABLED){                                                    \
 304         PORT_ADDRESS |= PIN_ON_MASK;                                          \
 305 }                                                                         // End macro
 306
 307
 308 /** This macro turns a pin OFF based on an enable flag, a port address and a pin
 309  * mask for that port. It is used to keep the code clean and free from ifdefs
 310  * whilst allowing a developer to turn on benchmarking outputs very easily. Note
 311  * that it gets optimised out due to the constant literal conditional required.
 312  */
 313 #define DEBUG_TURN_PIN_OFF(BENCHMARK_ENABLED, PIN_OFF_MASK, PORT_ADDRESS) \
 314 if(BENCHMARK_ENABLED){                                                    \
 315         PORT_ADDRESS &= PIN_OFF_MASK;                                         \
 316 }                                                                         // End macro
 317
 318
 319 /* For extracting 32 bit long time stamps from the overflow counter and timer registers */
 320 typedef union { /* Declare Union http://www.esacademy.com/faq/docs/cpointers/structures.htm */
 321         unsigned long timeLong;
 322         unsigned short timeShorts[2];
 323 } LongTime;
 324
 325
 326 #ifdef XGATE
 327 #include "xgateGlobals.h"
 328 #endif
 329
 330
 331 #undef EXTERN
 332
 333
 334 #else
 335         /* let us know if we are being untidy with headers */
 336         #warning "Header file FREEEMS_H seen before, sort it out!"
 337 /* end of the wrapper ifdef from the very top */
 338 #endif