# 4.9. Hardware Abstraction Layer (HAL)

The HAL is used by the MCAF to decouple all knowledge of device-specific hardware registers, via well-known function calls. At this time of writing, the HAL is hand-coded to work with the dsPICDEM® MCLV‑2 Development Board, dsPICDEM® MCHV‑2 Development Board, and dsPICDEM® MCHV‑3 Development Board, but future versions are intended to utilize Microchip’s MPLAB® Code Configurator and MPLAB® Harmony Configurator.

As long as the HAL function names and semantics are preserved, the HAL component can be swapped out and replaced with an alternative implementation.

More information is available in the HAL documentation.

## 4.9.1. Hardware-related behavior

Certain aspects of the MCAF utilize the functions provided by the HAL, but the choice of behavior lies within the MCAF.

### 4.9.1.1. PWM outputs

PWM outputs for the three-phase bridge are set in one of three modes:

- off — at device reset, and during severe faults, the bridge is turned off completely

- “minimal impact” — when not applying voltage across the motor terminals (in certain states of the state machine), the upper transistors are turned off completely, but the lower transistors are turned on at a low duty cycle (typically 1-3%), to maintain charge in bootstrap gate drive capacitors. See `MCAF_SetPwmMinimalImpact()` in the state_machine module.
- normal — when applying voltage across the motor terminals, all 6 of the transistors are switching, in three complementary pairs, one for each phase. Each phase has a dead-time between turn-off of one transistor and turn-on of the complementary transistor, to avoid shoot-through.

### 4.9.1.2. Board service module

The board service module in the MCAF works with Hardware Access Functions (HAF) in the HAL in order to provide the MCAF with board-level functionality. It provides two main board-related features: a board handler and a PWM bootstrap charging routine.

#### 4.9.1.2.1. Board handler

The board handler includes interfaces to configure and execute a board service process from within the HAL. While the board configuration process momentarily uses a device timer during the configuration process, the board service process generates its own timing reference based on the ADC ISR used in the MCAF. Working with appropriate HAL interfaces, the board handler provides services to operate LEDs, push buttons and configurable PWM drivers (if available).

#### 4.9.1.2.2. PWM bootstrap charging routine

The PWM bootstrap charging routine includes interfaces to initialize and execute the PWM bootstrap charging process. During the PWM bootstrap charging process, PWM bootstrap capacitors are sequentially charged up at a controlled rate. (see errata)

## 4.9.2. Implementation

### 4.9.2.1. MCC integration

Prior to MCAF R3, generated code was not integrated with MCC; MCAF provided its own HAL completely.

#### 4.9.2.1.1. MCAF R3

In MCAF R3, the following items have been removed from MCAF and made the responsibility of MCC:

- Configuration bits
- Oscillator setup

Some aspects of the MCC system module are still present in MCAF. Both MCC and MCAF code executes; the MCAF code runs later and overrides any settings from MCC. The following areas are handled both by MCC and MCAF:

- GPIO configuration
- Interrupt initialization
- CORCON initialization

This overlap is temporary, and these areas are planned to be shifted fully to MCC.

Other modules such as ADC and PWM are configured solely by MCAF, and will be shifted to MCC in a future version of MCAF.

#### 4.9.2.1.2. MCAF R4

In MCAF R4, the following items have been removed from MCAF and made the responsibility of MCC:

- GPIO configuration
- Interrupt module
- CORCON initialization
- PWM module
- ADC module
- Timer module
- UART module
- DMA module
- Watchdog module
- LEDs module
- Switches module
- Pin Management (partially)

MCC handles all peripheral initialization, pin initialization, pin management, and is the base layer for interacting with hardware. Currently, because MCC does not yet support QEI, pin management cannot be fully handled by MCC alone. First, the MCC system module configures all peripherals including device pin management. Then, after the MCC system module is done with configuration, MCAF pin management is run as well to initialize QEI pins. The QEI module is fully handled by MCAF and will be shifted to MCC when QEI support is available in MCC for 16-bit devices.

Most hardware access actions occur through the HAF layer but a few calls to the MCC peripheral layer are made directly from the MCAF application. In the future, all hardware access will be delegated to the HAF layer. This is to avoid coupling between the MCAF application and MCC.

`HAL_InterruptVectorNumberGet()` is a function that has been added to the HAF layer. This function retrieves the interrupt vector number, and does not directly go through MCC to do so.

More information about MCC configuration in MCAF is available in the MCC Peripheral documentation.

### 4.9.2.2. HAL errata

- `MCAF_BootstrapChargeExecute()` includes a soft-start sequence intended to slowly turn on duty cycle and reduce gate drive power supply loading in order to charge up bootstrap capacitors. This sequence starts with duty cycles that are too low, and may produce runt pulses with certain gate drivers. (DB_MC-978; Applicability: MCAF R2, R3, R4.)