# 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. The HAL is made up of two layers: MPLAB® Code Configurator (MCC) layer and HAF layer. The MCC layer is the base layer where device-specific hardware registers are abstracted out into a series of peripheral driver APIs. The HAF layer then calls functions in the MCC layer to abstract out device specific functionality, enabling the higher level MCAF layers to be device independent.

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

## 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. Some of these choices have been made to facilitate portability between devices that have different underlying peripheral mechanisms.

Note: this portability comes at a cost — each series of microcontrollers has certain peripheral usage patterns that are optimal but which may not translate well across different series.

Customers for whom CPU or peripheral performance is a severe constraint that takes precedence over portability and maintainability, should consider modifying the HAL as necessary to meet those constraints. Microchip does not recommend this approach unless absolutely necessary.

### 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. Overcurrent fault detection and clearing

MCAF requires a two phase fault clearing scheme to reset the latch circuitry. In order to clear the fault in Latched mode in dsPIC33EP devices, it is necessary to clear the interrupt flag and enable the fault mode at the next PWM cycle. Please refer to DS70645C p.14-101 for additional information.

Phase 1 occurs at current PWM cycle

- 33EP: Disable the fault latch mode
- 33CK: Clear the fault latch

Phase 2 occurs at the next PWM cycle

- 33CK & 33EP: Clear the fault interrupt flag
- 33EP: Enable the fault latch

### 4.9.1.3. Analog-to-digital conversion

Some of the ADC inputs have strict timing requirements, as shown in Table 4.7.

(At present, MCAF requires a fixed \(f_{PW\!M}\) = 20 kHz.)

Table 4.7 Sampling requirements for MCAF
Analog input | Sampling frequency | Timing requirements
--- | --- | ---
Motor currents (A,B,Sum) | \(f_{PW\!M}/K\) | Sample near the center of the PWM cycle(typically the start of center-aligned cycle). All samples should be complete within some small time Tskew. (Typically 1 μs or less)
DC link voltage | \(f_{PW\!M}/K\) | K=1 or K=2 typical. (Minimizing K is preferred.) Otherwise, no strict timing requirements
Potentiometer | \(f_{PW\!M}/K\) | Depends on the application; MCAF uses K=2. Otherwise, no strict timing requirements

Given the above constraints, multiple ADC sample scheduling schemes can be used. The timing diagrams below show the sampling schedules of motor phase currents, DC link voltage, and potentiometer in both 33CK and 33EP.

Figure 4.10 Suggested ADC Timing on dsPIC33CK devices (horizontal axis not to scale)

Figure 4.10 shows an example of dsPIC33CK256MP508 sampling motor currents phase A and B simultaneously at the beginning of the center-aligned PWM cycle. After motor current phase B, with less than 1 μs between samples, the shared core sequentially samples the DC link voltage, and potentiometer, followed by the end of conversion of the potentiometer which triggers the ADC ISR.

Figure 4.11 Suggested ADC Timing on dsPIC33EP devices (horizontal axis not to scale)

Figure 4.11 shows an example of dsPIC33EP256MC506 sampling all analog inputs simultaneously at the beginning of the center-aligned PWM cycle, with the exception of the potentiometer input. After analog inputs have been sampled and converted this triggers the beginning of the ADC ISR. At the next center-aligned PWM cycle the shared ADC core is switched from sensing DC link voltage to sensing the potentiometer input. At the next PWM boundary this cycle repeats.

### 4.9.1.4. 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.4.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.4.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.1.3. MCAF R5

- Added support for dsPIC33CK256MP508.
- All peripheral and hardware related functions called by MCAF are made through the Hardware Access Functions layer.
- MCAF requires certain instances of peripherals. Required instances are: PWM, ADC1, TMR1, SCCP1-TMR/TMR2, UART1 and QEI1
- MCC handles most peripheral generated code except for QEI and clearing of the fault interrupt status bits.

### 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 – R5.)