Hardware Abstraction Layer
==========================

.. toctree::
    :hidden:

    hal_timer/hal_timer
    hal_gpio/hal_gpio
    hal_uart/hal_uart
    hal_spi/hal_spi
    hal_i2c/hal_i2c
    hal_flash/hal_flash
    hal_system/hal_system
    hal_watchdog/hal_watchdog
    hal_bsp/hal_bsp

Description
~~~~~~~~~~~

The Hardware Abstraction Layer (HAL) in Mynewt is a low-level, base
peripheral abstraction. HAL provides a core set of services that is
implemented for each MCU supported by Mynewt. Device drivers are
typically the software libraries that initialize the hardware and manage
access to the hardware by higher layers of software. In the Mynewt OS,
the layers can be depicted in the following manner.

::

    +———————————————————————————+
    |            app            |
    +———————————————————————————+
    |          (n)drivers       |
    +———————————————————————————+
    |     HAL     |     BSP     |
    +—————————————+—————————————+

-  The Board Support Package (BSP) abstracts board specific
   configurations e.g. CPU frequency, input voltage, LED pins, on-chip
   flash map etc.

-  The Hardware Abstraction Layer (HAL) abstracts architecture-specific
   functionality. It initializes and enables components within a master
   processor. It is designed to be portable across all the various MCUs
   supported in Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's
   MK64F12 etc.). It includes code that initializes and manages access
   to components of the board such as board buses (I2C, PCI, PCMCIA,
   etc.), off-chip memory (controllers, level 2+ cache, Flash, etc.),
   and off-chip I/O (Ethernet, RS-232, display, mouse, etc.)

-  The driver sits atop the BSP and HAL. It abstracts the common modes
   of operation for each peripheral device connected via the standard
   interfaces to the processor. There may be multiple driver
   implementations of differing complexities for a particular peripheral
   device. The drivers are the ones that register with the kernel’s
   power management APIs, and manage turning on and off peripherals and
   external chipsets, etc.

General design principles
~~~~~~~~~~~~~~~~~~~~~~~~~

-  The HAL API should be simple. It should be as easy to implement for
   hardware as possible. A simple HAL API makes it easy to bring up new
   MCUs quickly.

-  The HAL API should portable across all the various MCUs supported in
   Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's MK64F12 etc.).

Example
~~~~~~~

A Mynewt contributor might write a light-switch driver that provides the
functionality of an intelligent light switch. This might involve using a
timer, a General Purpose Output (GPO) to set the light to the on or off
state, and flash memory to log the times the lights were turned on or
off. The contributor would like this package to work with as many
different hardware platforms as possible, but can't possibly test across
the complete set of hardware supported by Mynewt.

**Solution**: The contributor uses the HAL APIs to control the
peripherals. The Mynewt team ensures that the underlying HAL devices all
work equivalently through the HAL APIs. The contributors library is
independent of the specifics of the hardware.

Dependency
~~~~~~~~~~

To include the HAL within your project, simply add it to your package
dependencies as follows:

.. code-block:: console

    pkg.deps:
        . . .
        hw/hal

Platform Support
~~~~~~~~~~~~~~~~

Not all platforms (MCU and BSP) support all HAL devices. Consult your
MCU or BSP documentation to find out if you have hardware support for
the peripherals you are interested in using. Once you verify support,
then consult the MCU implementation and see if the specific HAL
interface (xxxx) you are using is in the
``mcu/<mcu-name>/src/hal_xxxx.c`` implementation. Finally, you can build
your project and ensure that there are no unresolved hal\_xxxx
externals.