1# Introduction
2
3The **hal_atmel** is a set of register definitions for Atmel SAM/SAM0 SoC's.
4The HAL is organized following the directory structure detailed below.
5
6## Directory Structure
7
8The 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
29Any contribution should follow the `How to submit code` using as premisses the
30[Zephyr Contribution Guidelines](https://docs.zephyrproject.org/latest/contribute/index.html).
31For 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
54The above are general guidelines and exceptions could happen. In this case, the
55exception should be addressed at review phase.
56
57## The standard API
58
59The SAM/SAM0 standard API define all information to access Atmel SoC's
60peripherals. This library does not have namespaces and prefixes which
61easily results in name collision with ZephyrRTOS core and libraries. To avoid
62that situation, macros, enum values and function names should follow two
63general 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_`.
68