FreeEMS  0.2.0-SNAPSHOT-285-g028e24c
freeEMS.h
Go to the documentation of this file.
1 /* FreeEMS - the open source engine management system
2  *
3  * Copyright 2008-2013 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 EXTERN Flaggable2 Flaggables2; ///< The single instance of our flaggable2 struct.
124 
125 /** @page bankedRunningVariables Banked Running Variables
126  *
127  * This page is to document and explain the operation of the banked running variable system and structure.
128  *
129  * The program running variables are divided into three broad groups: inputs, working
130  * and outputs. For both the input and output groups there are two copies of each set
131  * of variables, whereas there is only one copy of each set in the working group. This
132  * is required to allow both the inputs and outputs to be safely written and read at
133  * the same time. To facilitate this all sets of variables within the input and output
134  * groups are referenced with two pointers each. For the input group, the copy pointed
135  * to is swapped when fresh data is both available to and required by the mathematics
136  * function. For the output group the copy pointed to is swapped when the mathematics
137  * function has produced new output data. The input data is supplied by the engine
138  * position interrupt service routines as ADC readings and RPM values. The output data
139  * consists of pulse widths, timing angles, dwell periods and scheduling information.
140  *
141  * Accessory functions (Idle, Boost, etc)
142  *
143  * In order to achieve minimal latency and maximum frequency of execution of the
144  * main mathematics code the accessory functions must run asynchronously. Although
145  * we can guarantee that these functions will base their calculations on a matched
146  * set of data, we can not guarantee that it will be the same set of data presented
147  * along side the accessory data in the data log. Thus, where it is required to see
148  * the inputs that an accessory functions calculations were based on, those values
149  * should be cached for logging on a per function basis.
150  *
151  * Although it seems like a lot of trouble to go to, it is critical to transient
152  * performance that the environmental conditions the engine is operating under are
153  * tracked and reacted to as quickly as possible. Having the less important stuff
154  * run asynchronously will result in an order of magnitude improvement of parameter
155  * tracking and is well worth the extra memory expense and complication.
156  */
157 
158 EXTERN CoreVar* CoreVars; /** Pointer to the core running variables */
159 EXTERN CoreVar CoreVars0; /** Bank 0 core running variables */
160 /* If we move to xgate or isr driven logging, add bank 1 back in */
161 
162 EXTERN DerivedVar* DerivedVars; /** Pointer to the secondary running variables */
163 EXTERN DerivedVar DerivedVars0; /** Bank 0 secondary running variables */
164 /* If we move to xgate or isr driven logging, add bank 1 back in */
165 
166 EXTERN ADCBuffer* ADCBuffers; /** main adc storage area for syncronous sampling in the engine position ISR or injection ISR or ignition ISR etc. */
167 EXTERN ADCBuffer* ADCBuffersRecord; /** main adc storage area for syncronous sampling in the engine position ISR or injection ISR or ignition ISR etc. */
168 EXTERN ADCBuffer ADCBuffers0; /** main adc storage area for syncronous sampling in the engine position ISR or injection ISR or ignition ISR etc. */
169 EXTERN ADCBuffer ADCBuffers1; /** main adc storage area for syncronous sampling in the engine position ISR or injection ISR or ignition ISR etc. */
170 
171 /*break this on purpose so i fix it later
172 #define VETablereference (*((volatile mainTable*)(0x1000)))
173 EXTERN const mainTable *VETableRef;
174 PLUS
175 const volatile mainTable *VETableRef = (volatile mainTable*)0x1000;
176 broken too, need to research how to do this.
177 
178 see line 80 or so from inc/injectorISR.c for array of pointer use. the above may not be possible... TODO */
179 
180 
181 /* Potentially pointers for data in RAM depending on how it gets implemented */
182 // volatile ??
183 //EXTERN tunableConfig tunableConfigs;
184 
185 /* Layout the tunable copies and buffers in RAM space */
186 
187 
188 
189 /* TODO explanation of paged RAM operation Unions for paged large table access using RPAGE */
190 typedef union {
194 } Tables1;
195 
196 typedef union {
200 } Tables2;
201 
202 typedef union {
206 } Tables3;
207 
208 typedef union {
212 } Tables4;
213 
214 
215 /* Large blocks */
216 EXTERN unsigned char TXBuffer[TX_BUFFER_SIZE] TXBUF;
217 EXTERN unsigned char RXBuffer[RX_BUFFER_SIZE] RXBUF;
219 EXTERN Tables2 TablesB RWINDOW;
220 EXTERN Tables3 TablesC RWINDOW;
221 EXTERN Tables4 TablesD RWINDOW;
222 
223 
224 /* RAM page variables */
225 EXTERN unsigned char currentFuelRPage;
226 EXTERN unsigned char currentTuneRPage;
227 EXTERN unsigned char currentTimeRPage;
228 
229 
230 /* These are inited once and remain the same, rpage switches change meaning. */
231 
232 ///* Pointers to main tables to aid readability */
233 //EXTERN mainTable* VETableMain;
234 //EXTERN mainTable* VETableSecondary;
235 //EXTERN mainTable* AirflowTable;
236 //EXTERN mainTable* LambdaTable;
237 //
238 //EXTERN mainTable* IgnitionAdvanceTableMain;
239 //EXTERN mainTable* IgnitionAdvanceTableSecondary;
240 //EXTERN mainTable* InjectionAdvanceTableMain;
241 //EXTERN mainTable* InjectionAdvanceTableSecondary;
242 //
243 ///* Pointers to SmallTablesA */
244 //EXTERN twoDTableUS* dwellDesiredVersusVoltageTable;
245 //EXTERN twoDTableUS* injectorDeadTimeTable;
246 //EXTERN twoDTableUS* postStartEnrichmentTable;
247 //EXTERN twoDTableUS* engineTempEnrichmentTableFixed;
248 //EXTERN twoDTableUS* primingVolumeTable;
249 //EXTERN twoDTableUS* engineTempEnrichmentTablePercent;
250 //EXTERN twoDTableUS* dwellVersusRPMTable;
251 /* Pointers to SmallTablesB */
252 /* Pointers to SmallTablesC */
253 /* Pointers to SmallTablesD */
254 
255 
256 /* Output variables (init not required) TODO ditch this in favour of the real vars in the calcs function and struct */
257 extern unsigned short masterPulseWidth;
258 EXTERN unsigned long bootFuelConst; /* constant derived from configurable constants */
259 EXTERN unsigned short TPSADCRange; /* The ADC range used to generate TPS percentage */
260 
261 
262 /* ALL STATUS STUFF HERE */
263 
264 /* State variables : 0 = false (don't forget to change the init mask to suit!) */
265 EXTERN unsigned char coreStatusA; /* Each bit represents the state of some core parameter, masks below */
266 /* Bit masks for coreStatusA */ // TODO needs a rename as does coresetingsA
267 #define FUEL_PUMP_PRIME BIT0 /* 0 */
268 #define STAGED_REQUIRED BIT1 /* 1 Fire the staged injectors */
269 #define CALC_FUEL_IGN BIT2 /* 2 Fuel and ignition require calculation (i.e. variables have been updated) */
270 #define FORCE_READING BIT3 /* 3 Flag to force ADC sampling at low rpm/stall */
271 #define BENCH_TEST_ON BIT4 /* 4 Bench test running TEMPORARY */
272 #define COREA05 BIT5 /* 5 */
273 #define COREA06 BIT6 /* 6 */
274 #define COREA07 BIT7 /* 7 */
275 
276 
277 #define CLEAR_FUEL_PUMP_PRIME NBIT0 /* */
278 #define STAGED_NOT_REQUIRED NBIT1 /* 9 Do not fire the staged injectors */
279 #define CLEAR_CALC_FUEL_IGN NBIT2 /* 10 Fuel and ignition don't require calculation */
280 #define CLEAR_FORCE_READING NBIT3 /* 11 Clear flag to force ADC sampling at low rpm/stall */
281 #define CLEAR_BENCH_TEST_ON NBIT4
282 
283 //TODO make this volatile?
284 /* ECT IC extension variable (init not required, don't care where it is, only differences between figures) */
285 unsigned short timerExtensionClock; /* Increment for each overflow of the main timer, allows finer resolution and longer time period */
286 /* section 10.3.5 page 290 68hc11 reference manual e.g. groups.csail.mit.edu/drl/courses/cs54-2001s/pdf/M68HC11RM.pdf */
287 
288 
289 // Default to off
290 #ifndef DECODER_BENCHMARKS
291 #define DECODER_BENCHMARKS FALSE
292 #else
293 #undef DECODER_BENCHMARKS
294 #define DECODER_BENCHMARKS TRUE
295 #endif
296 
297 
298 /** This macro turns a pin ON based on an enable flag, a port address and a pin
299  * mask for that port. It is used to keep the code clean and free from ifdefs
300  * whilst allowing a developer to turn on benchmarking outputs very easily. Note
301  * that it gets optimised out due to the constant literal conditional required.
302  */
303 #define DEBUG_TURN_PIN_ON(BENCHMARK_ENABLED, PIN_ON_MASK, PORT_ADDRESS) \
304 if(BENCHMARK_ENABLED){ \
305  PORT_ADDRESS |= PIN_ON_MASK; \
306 } // End macro
307 
308 
309 /** This macro turns a pin OFF based on an enable flag, a port address and a pin
310  * mask for that port. It is used to keep the code clean and free from ifdefs
311  * whilst allowing a developer to turn on benchmarking outputs very easily. Note
312  * that it gets optimised out due to the constant literal conditional required.
313  */
314 #define DEBUG_TURN_PIN_OFF(BENCHMARK_ENABLED, PIN_OFF_MASK, PORT_ADDRESS) \
315 if(BENCHMARK_ENABLED){ \
316  PORT_ADDRESS &= PIN_OFF_MASK; \
317 } // End macro
318 
319 
320 /* For extracting 32 bit long time stamps from the overflow counter and timer registers */
321 typedef union { /* Declare Union http://www.esacademy.com/faq/docs/cpointers/structures.htm */
322  unsigned long timeLong;
323  unsigned short timeShorts[2];
324 } LongTime;
325 
326 
327 #ifdef XGATE
328 #include "xgateGlobals.h"
329 #endif
330 
331 
332 #undef EXTERN
333 
334 
335 #else
336  /* let us know if we are being untidy with headers */
337  #warning "Header file FREEEMS_H seen before, sort it out!"
338 /* end of the wrapper ifdef from the very top */
339 #endif