docs: Improve documentation

The repository do not have a documentation entry point. This add
the missing documentation entry point with general guidelines. In
addition links the documentation on scripts and pinconfigs with
the main page.

Signed-off-by: Gerson Fernando Budke <nandojve@gmail.com>

README.md

@@ -0,0 +1,67 @@
+# Introduction
+
+The **hal_atmel** is a set of register definitions for Atmel SAM/SAM0 SoC's.
+The HAL is organized following the directory structure detailed below.
+
+## Directory Structure
+
+The directory is composed by six parts:
+```
+.
+├── asf
+├── include
+├── pinconfigs
+├── README.md
+├── scripts
+└── zephyr
+```
+
+ - Atmel Software Framework 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 [Atmel packs download site](http://packs.download.atmel.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 `asf/[sam|sam0]/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_atmel` 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 SAM/SAM0 standard API define all information to access Atmel 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 `sam_` or `sam0_`.
+ - Public defines and enum values must be uppercase and prefixed with `SAM_`
+   or `SAM0_`.

asf/sam/include/sam3x/README

@@ -0,0 +1,42 @@
+# Copyright (c) 2023 Gerson Fernando Budke
+# SPDX-License-Identifier: Apache-2.0
+
+Atmel SAM3X
+###########
+
+Origin:
+   Microchip Packs Repository
+   http://packs.download.atmel.com/
+
+   Atmel SAM4E Series Device Support (1.1.57)
+   http://packs.download.atmel.com/Atmel.SAM3X_DFP.1.0.50.atpack
+
+Status:
+   version 1.0.50
+
+Purpose:
+   Official package for SAM3X.
+
+Description:
+   Atmel Software Framework (ASF) provides a set of low-level
+   header files that give access to different hardware
+   peripherals of Atmel's ICs.
+
+URL:
+   http://packs.download.atmel.com/
+   http://packs.download.atmel.com/Atmel.SAM3X_DFP.1.0.50.atpack
+
+commit:
+   n/a
+
+Maintained-by:
+   External
+
+License:
+   SAM Software Package License
+
+License Link:
+   n/a
+
+Patch Lst:
+   * Fix TC registers macros

asf/sam/include/sam4e/README

@@ -1,3 +1,6 @@
+# Copyright (c) 2023 Gerson Fernando Budke
+# SPDX-License-Identifier: Apache-2.0
+
 Atmel SAM4E
 ###########
 
@@ -38,4 +41,9 @@ License Link:
 Patch Lst:
    * Add MPU peripheral in device file
    * Fix CHIPID_EXID for SAM4E8C and SAM4E16C
-
+   * Add SPI_CSR_BITS register macro
+   * Fix GMAC_UR_RMII register macro
+   * Fix PIO_PD6A_GRX1 register macro
+   * Add WDT_CR_KEY_PASSWD register macro
+   * Fix PMC registers macros
+   * Fix TC registers macros

asf/sam/include/sam4l/README

@@ -1,3 +1,6 @@
+# Copyright (c) 2023 Gerson Fernando Budke
+# SPDX-License-Identifier: Apache-2.0
+
 Atmel SAM4L
 ###########
 

asf/sam/include/sam4s/README

@@ -0,0 +1,42 @@
+# Copyright (c) 2023 Gerson Fernando Budke
+# SPDX-License-Identifier: Apache-2.0
+
+Atmel SAM4S
+###########
+
+Origin:
+   Microchip Packs Repository
+   http://packs.download.atmel.com/
+
+   Atmel SAM4E Series Device Support (1.1.56)
+   http://packs.download.atmel.com/Atmel.SAM4S_DFP.1.1.56.atpack
+
+Status:
+   version 1.1.56
+
+Purpose:
+   Official package for SAM4S.
+
+Description:
+   Atmel Software Framework (ASF) provides a set of low-level
+   header files that give access to different hardware
+   peripherals of Atmel's ICs.
+
+URL:
+   http://packs.download.atmel.com/
+   http://packs.download.atmel.com/Atmel.SAM4E_DFP.1.1.56.atpack
+
+commit:
+   n/a
+
+Maintained-by:
+   External
+
+License:
+   SAM Software Package License
+
+License Link:
+   n/a
+
+Patch Lst:
+   * Fix TC registers macros

asf/sam/include/same70/README

@@ -1,3 +1,6 @@
+# Copyright (c) 2023 Gerson Fernando Budke
+# SPDX-License-Identifier: Apache-2.0
+
 Atmel SAM E70
 #############
 

asf/sam/include/same70b/README

@@ -1,3 +1,6 @@
+# Copyright (c) 2023 Gerson Fernando Budke
+# SPDX-License-Identifier: Apache-2.0
+
 Atmel SAM E70B
 ##############
 

asf/sam/include/samv71/README

@@ -1,3 +1,6 @@
+# Copyright (c) 2023 Gerson Fernando Budke
+# SPDX-License-Identifier: Apache-2.0
+
 Atmel SAM V71
 #############
 

asf/sam/include/samv71b/README

@@ -1,3 +1,6 @@
+# Copyright (c) 2023 Gerson Fernando Budke
+# SPDX-License-Identifier: Apache-2.0
+
 Atmel SAM V71B
 ##############
 

pinconfigs/README.md

@@ -1,4 +1,4 @@
-# Atmel SAM pin configurations
+# Atmel SAM/SAM0 pin configurations
 
 This directory contains a set of files describing valid pin configurations for
 multiple Atmel Smart Arm MCUs (SAM) devices. This configuration files maps a

scripts/README.md

@@ -1,17 +1,17 @@
-# hal_atmel scripts
+# Atmel SAM/SAM0 scripts
 
 This folder contains `hal_atmel` scripts.
 
-# Dependencies
+## Dependencies
 
-Scripts require Python 3.6+ and the Python dependencies listed in
+Scripts require Python 3.7+ and the Python dependencies listed in
 `requirements.txt`. They can be installed by running:
 
 ```
 pip install -r scripts/requirements.txt
 ```
 
-# Lint
+## Lint
 
 Scripts should be formatted using `black` and linted using `flake8`.
 
@@ -21,7 +21,7 @@ Such development tools can be installed using:
 pip install -r scripts/requirements-dev.txt
 ```
 
-# Tests
+## Tests
 
 Before running tests make sure to have testing dependencies installed. They
 can be installed by running: