N3_sub/modules/ChibiOS/os/hal/dox/hal_pal.dox

/*
    ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
*/

/**
 * @defgroup PAL PAL Driver
 * @brief   I/O Ports Abstraction Layer
 * @details This module defines an abstract interface for digital I/O ports.
 *          Note that most I/O ports functions are just macros. The macros
 *          have default software implementations that can be redefined in a
 *          PAL Low Level Driver if the target hardware supports special
 *          features like, for example, atomic bit set/reset/masking. Please
 *          refer to the ports specific documentation for details.<br>
 *          The @ref PAL driver has the advantage to make the access to the I/O
 *          ports platform independent and still be optimized for the specific
 *          architectures.<br>
 *          Note that the PAL Low Level Driver may also offer non standard
 *          macro and functions in order to support specific features but,
 *          of course, the use of such interfaces would not be portable.
 *          Such interfaces shall be marked with the architecture name inside
 *          the function names.
 * @pre     In order to use the PAL driver the @p HAL_USE_PAL option
 *          must be enabled in @p halconf.h.
 *
 * @section pal_1 Implementation Rules
 * In implementing a PAL Low Level Driver there are some rules/behaviors that
 * should be respected.
 *
 * @subsection pal_1_1 Writing on input pads
 * The behavior is not specified but there are implementations better than
 * others, this is the list of possible implementations, preferred options
 * are on top:
 * -# The written value is not actually output but latched, should the pads
 *    be reprogrammed as outputs the value would be in effect.
 * -# The write operation is ignored.
 * -# The write operation has side effects, as example disabling/enabling
 *    pull up/down resistors or changing the pad direction. This scenario is
 *    discouraged, please try to avoid this scenario.
 * .
 * @subsection pal_1_2 Reading from output pads
 * The behavior is not specified but there are implementations better than
 * others, this is the list of possible implementations, preferred options
 * are on top:
 * -# The actual pads states are read (not the output latch).
 * -# The output latch value is read (regardless of the actual pads states).
 * -# Unspecified, please try to avoid this scenario.
 * .
 * @subsection pal_1_3 Writing unused or unimplemented port bits
 * The behavior is not specified.
 *
 * @subsection pal_1_4 Reading from unused or unimplemented port bits
 * The behavior is not specified.
 *
 * @subsection pal_1_5 Reading or writing on pins associated to other functionalities
 * The behavior is not specified.
 *
 * @ingroup HAL_NORMAL_DRIVERS
 */