|
| 1 | +# Introduction |
| 2 | + |
| 3 | +The **hal_atmel** is a set of register definitions for Atmel SAM/SAM0 SoC's. |
| 4 | +The HAL is organized following the directory structure detailed below. |
| 5 | + |
| 6 | +## Directory Structure |
| 7 | + |
| 8 | +The directory is composed by six parts: |
| 9 | +``` |
| 10 | +. |
| 11 | +├── asf |
| 12 | +├── include |
| 13 | +├── pinconfigs |
| 14 | +├── README.md |
| 15 | +├── scripts |
| 16 | +└── zephyr |
| 17 | +``` |
| 18 | + |
| 19 | + - Atmel Software Framework SoC specific include libraries. |
| 20 | + - Includes specific for these platforms |
| 21 | + - devicetree bindings |
| 22 | + - [Pin definitions](pinconfigs/README.md) |
| 23 | + - [Scripts](scripts/README.md) used for code generation |
| 24 | + - ZephyrRTOS module directory (`zephyr`). |
| 25 | + - This README file. |
| 26 | + |
| 27 | +# How to submit code |
| 28 | + |
| 29 | +Any contribution should follow the `How to submit code` using as premisses the |
| 30 | +[Zephyr Contribution Guidelines](https://docs.zephyrproject.org/latest/contribute/index.html). |
| 31 | +For more information about External Modules see |
| 32 | +[Modules Section](https://docs.zephyrproject.org/latest/develop/modules.html) in special |
| 33 | +[Submitting Changes to Modules](https://docs.zephyrproject.org/latest/develop/modules.html#submitting-changes-to-modules) |
| 34 | + |
| 35 | + |
| 36 | +## Repository specific guidelines |
| 37 | + |
| 38 | + - When submitting an updated firmware library version, it is important to make |
| 39 | + sure that the last firmware version will be merged. The library version is |
| 40 | + used to be checked at [Atmel packs download site](http://packs.download.atmel.com/). |
| 41 | + - When submitting an updated firmware library version the patchset already |
| 42 | + applied should be rebased on top of the newer version. |
| 43 | + - The patchset must be sent as an individual commit per SoC series to easy rebase. |
| 44 | + - This repository is managed mainly on Linux. This means that changes should |
| 45 | + be submitted using Linux LF format. Usually running a similar command to |
| 46 | + `find * type f -print0 | xargs -0 dos2unix -k` should be enough. |
| 47 | + - Make sure directory structure is respected. |
| 48 | + - The `asf/[sam|sam0]/include/<soc>/README` file should be updated accordingly. |
| 49 | + If for some reason the file not exists it should be created. |
| 50 | + - Directory names should be converted to lowercase. |
| 51 | + - The recommendation is add **all fixups** in the `hal_atmel` instead on the |
| 52 | + ZephyrRTOS project. |
| 53 | + |
| 54 | +The above are general guidelines and exceptions could happen. In this case, the |
| 55 | +exception should be addressed at review phase. |
| 56 | + |
| 57 | +## The standard API |
| 58 | + |
| 59 | +The SAM/SAM0 standard API define all information to access Atmel SoC's |
| 60 | +peripherals. This library does not have namespaces and prefixes which |
| 61 | +easily results in name collision with ZephyrRTOS core and libraries. To avoid |
| 62 | +that situation, macros, enum values and function names should follow two |
| 63 | +general rules: |
| 64 | + |
| 65 | + - Public API functions must be prefixed with `sam_` or `sam0_`. |
| 66 | + - Public defines and enum values must be uppercase and prefixed with `SAM_` |
| 67 | + or `SAM0_`. |
0 commit comments