# Introduction

The **hal_microchip** is a set of register definitions for Microchip PIC32C/PIC32M SoC's.
The HAL is organized following the directory structure detailed below.

## Directory Structure

The directory is composed by six parts:
```
.
├── pic32c
├── include
├── pinconfigs
├── README.md
├── scripts
└── zephyr
```

 - PIC32C SoC specific include libraries.
 - Includes specific for these platforms
   - devicetree bindings
 - [Pin definitions](pinconfigs/README.md)
 - [Scripts](scripts/README.md) used for code generation
 - ZephyrRTOS module directory (`zephyr`).
 - This README file.

# How to submit code

Any contribution should follow the `How to submit code` using as premisses the
[Zephyr Contribution Guidelines](https://docs.zephyrproject.org/latest/contribute/index.html).
For more information about External Modules see
[Modules Section](https://docs.zephyrproject.org/latest/develop/modules.html) in special
[Submitting Changes to Modules](https://docs.zephyrproject.org/latest/develop/modules.html#submitting-changes-to-modules)


## Repository specific guidelines

 - When submitting an updated firmware library version, it is important to make
   sure that the last firmware version will be merged. The library version is
   used to be checked at [Microchip packs download site](https://packs.download.microchip.com/).
 - When submitting an updated firmware library version the patchset already
   applied should be rebased on top of the newer version.
 - The patchset must be sent as an individual commit per SoC series to easy rebase.
 - This repository is managed mainly on Linux. This means that changes should
   be submitted using Linux LF format. Usually running a similar command to
   `find * type f -print0 | xargs -0 dos2unix -k` should be enough.
 - Make sure directory structure is respected.
 - The `pic32c/[pic32cxsg]/include/<soc>/README` file should be updated accordingly.
   If for some reason the file not exists it should be created.
 - Directory names should be converted to lowercase.
 - The recommendation is add **all fixups** in the `hal_microchip` instead on the
   ZephyrRTOS project.

The above are general guidelines and exceptions could happen. In this case, the
exception should be addressed at review phase.

## The standard API

The PIC32C/PIC32M standard API define all information to access Microchip SoC's
peripherals. This library does not have namespaces and prefixes which
easily results in name collision with ZephyrRTOS core and libraries. To avoid
that situation, macros, enum values and function names should follow two
general rules:

 - Public API functions must be prefixed with `pic32cxsg_` or .
 - Public defines and enum values must be uppercase and prefixed with `PIC32CXSG_`
   or .

The MEC1701 HAL was downloaded from:

https://github.com/MicrochipTech/Peripheral-mec1701

Massaged the file with :
sed -i -e 's/[ \t\r]*$//g' MCHP_MEC1701_bit_fields.h, then file was renamed
to MCHP_MEC1701.h

Field EOF was renamed to PEOF as it was collapsing with EOF defined in stdio.h

Microchip HAL contianing the above MEC1701 single header and the
MEC1501 component style is located at:

https://github.com/MicrochipTech/hal_microchip

Version: 1.2.1
Add missing eSPI Virtual Wires groups 8 - 10 GIRQ definitions.
Make sure all typedef's of structures are "typedef struct struct_name".
Remove non-printable character from SAF header
Add max name to GPIO ID enum
Rename the SPISLV to SPIP

Version: 1.2.1
Update eSPI definitions
Changed all hex upper case 'ABCDEF' to lower case
Changed all 'ul/UL' unsigned numeric suffix to 'u'


The Microchip Polarfire SOC HAL was downloaded from:

https://github.com/polarfire-soc/platform

Addditionally, the bare metal samples from https://github.com/polarfire-soc/polarfire-soc-bare-metal-examples
are required to extract the Icicle Kit bopard configuration files.

Both are from Tag 21.08

The following changes were made:

 - platform-2021.08 top folder renamed to mpfs and located at modules/hal/microchip
 - The applications/mpfs-pmp-demo/mpfs-pmp-app-u54-1/src/boards folder is copied to modules/hal/microchip/mpfs

========================================================================
Microchip MEC5 HAL for MEC1723, MEC1743 and MEC1753 CMSIS based headers
using common peripheral headers.
NOTE: Due to a legacy version of MEC172x with register files is in the
zephyr tree, MEC172x is named MECH172x in  the HAL.

Location:
https://github.com/MicrochipTech/hal_microchip

Refer to the mec5 subdirectory.

Initial version 0.1

------------------------------------------------
2024-10-01: Microchip MEC5 HAL version 0.3.0 release
Refer to the mec5 subdirectory.