# 4.1. Main Application

As mentioned in the section on scheduling, the main application consists of a portion of code that executes in `main()` and a portion that executes in the ADC ISR.

## 4.1.1. Implementation Notes

### 4.1.1.1. Modules

Module | Files | Description | Comments
--- | --- | --- | ---
`isr` | `isr.c` | Top-level ISR | The main control ISR function runs on a periodic basis. It is triggered at the completion of ADC sampling, which in turn is triggered once per PWM cycle, as mentioned in the Scheduling section. It contains profiling logic: generates a pulse on a GPIO pin that starts on ISR entry and ends on ISR exit capture of timer counter (see test harness) Various ISR subtasks are executed in rough order of priority (state machine tasks first, test harness and diagnostic tasks last). The actual name of the ADC ISR function is hardware-dependent and is encapsulated in the HAL by the `HAL_ADC1_ISR` macro.
`mcaf_main` | `mcaf_main.c` `mcaf_main.h` | Main MCAF entry points called from `main()` (initialization and main loop) |
`mcaf_traps` | `mcaf_traps.c` `mcaf_traps.h` | Trap interrupt handlers |
`system_init` | `system_init.c` `system_init.h` | System initialization | Initializes state variables and special function registers prior to the main loop (intended to be called in `MCAF_MainInit()`) `MCAF_SystemInit` — called at the beginning of `MCAF_MainInit()` to initialize certain SFRs and system-wide state variables as soon as possible. `MCAF_SystemStart` — called near the end of `MCAF_MainInit()` for deferred initialization. This includes code to enable interrupts, and therefore main-thread code that executes prior to `MCAF_SystemStart` is not prone to race conditions caused by conflicts with an ISR that has just been enabled.
`system_state` | `system_state.h` | System state variable type definitions | Defines the main `MCAF_MOTOR_DATA` and `MCAF_SYSTEM_DATA` structure types.

### 4.1.1.2. Trap-handler module

Hardware trap vectors in dsPIC® DSC devices contain handlers for events like a stack overflow, or an address alignment error. In the MCAF, these are located in the `traps` module. The normal handling logic is to signal a nonrecoverable error, by calling the `halt_on_error()` function, which records an error code and goes into an endless loop to flash the LEDs to indicate an error code via `MCAF_UiFlashErrorCodeForever()` as discussed in the UI module.

Two minor deviations from this behavior:

- DMA write collision: this occurs when the CPU and a DMA channel write to the same address (in which case the CPU “wins” and the DMA write is ignored). This condition is not considered an error in this application, and arises in rare cases for one variant of the diagnostic module which utilizes the DMA for reading and writing the UART. The DMA trap handler increments a counter for assessing the frequency of DMA write collisions.
- Stack overflow: a stack overflow is a nonrecoverable error, but is slightly different in that the stack pointer (W15 on dsPIC® DSC devices) may not be valid. In this condition, the MCAF takes extra care by using a small “failsafe stack”, which is a static area of memory reserved for this case, and is large enough to cover the stack requirements needed by the `MCAF_UiFlashErrorCodeForever()` function.

In addition to hardware traps, the `traps` module also includes logic to examine cause of reset, so that in the event of a watchdog reset, a nonrecoverable error can be signaled via `MCAF_UiFlashErrorCodeForever()`.