LCOV - code coverage report
Current view: top level - home/jason/ncs-2.0.0/modules/hal/nordic/nrfx/drivers - nrfx_common.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 2 2 100.0 %
Date: 2022-08-18 11:36:24 Functions: 1 1 100.0 %
Legend: Lines: hit not hit | Branches: + taken - not taken # not executed Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : /*
       2                 :            :  * Copyright (c) 2017 - 2022, Nordic Semiconductor ASA
       3                 :            :  * All rights reserved.
       4                 :            :  *
       5                 :            :  * SPDX-License-Identifier: BSD-3-Clause
       6                 :            :  *
       7                 :            :  * Redistribution and use in source and binary forms, with or without
       8                 :            :  * modification, are permitted provided that the following conditions are met:
       9                 :            :  *
      10                 :            :  * 1. Redistributions of source code must retain the above copyright notice, this
      11                 :            :  *    list of conditions and the following disclaimer.
      12                 :            :  *
      13                 :            :  * 2. Redistributions in binary form must reproduce the above copyright
      14                 :            :  *    notice, this list of conditions and the following disclaimer in the
      15                 :            :  *    documentation and/or other materials provided with the distribution.
      16                 :            :  *
      17                 :            :  * 3. Neither the name of the copyright holder nor the names of its
      18                 :            :  *    contributors may be used to endorse or promote products derived from this
      19                 :            :  *    software without specific prior written permission.
      20                 :            :  *
      21                 :            :  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
      22                 :            :  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
      23                 :            :  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
      24                 :            :  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
      25                 :            :  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
      26                 :            :  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
      27                 :            :  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
      28                 :            :  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
      29                 :            :  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
      30                 :            :  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
      31                 :            :  * POSSIBILITY OF SUCH DAMAGE.
      32                 :            :  */
      33                 :            : 
      34                 :            : #ifndef NRFX_COMMON_H__
      35                 :            : #define NRFX_COMMON_H__
      36                 :            : 
      37                 :            : #include <stdint.h>
      38                 :            : #include <stddef.h>
      39                 :            : #include <stdbool.h>
      40                 :            : 
      41                 :            : #include <nrf.h>
      42                 :            : #include <nrf_peripherals.h>
      43                 :            : 
      44                 :            : #ifdef __cplusplus
      45                 :            : extern "C" {
      46                 :            : #endif
      47                 :            : 
      48                 :            : #ifndef NRFX_STATIC_INLINE
      49                 :            : #ifdef NRFX_DECLARE_ONLY
      50                 :            : #define NRFX_STATIC_INLINE
      51                 :            : #else
      52                 :            : #define NRFX_STATIC_INLINE __STATIC_INLINE
      53                 :            : #endif
      54                 :            : #endif // NRFX_STATIC_INLINE
      55                 :            : 
      56                 :            : #ifndef NRF_STATIC_INLINE
      57                 :            : #ifdef NRF_DECLARE_ONLY
      58                 :            : #define NRF_STATIC_INLINE
      59                 :            : #else
      60                 :            : #define NRF_STATIC_INLINE __STATIC_INLINE
      61                 :            : #endif
      62                 :            : #endif // NRF_STATIC_INLINE
      63                 :            : 
      64                 :            : /**
      65                 :            :  * @defgroup nrfx_common Common module
      66                 :            :  * @{
      67                 :            :  * @ingroup nrfx
      68                 :            :  * @brief Common module.
      69                 :            :  */
      70                 :            : 
      71                 :            : /**
      72                 :            :  * @brief Macro for checking if the specified identifier is defined and it has
      73                 :            :  *        a non-zero value.
      74                 :            :  *
      75                 :            :  * Normally, preprocessors treat all undefined identifiers as having the value
      76                 :            :  * zero. However, some tools, like static code analyzers, can issue a warning
      77                 :            :  * when such identifier is evaluated. This macro gives the possibility to suppress
      78                 :            :  * such warnings only in places where this macro is used for evaluation, not in
      79                 :            :  * the whole analyzed code.
      80                 :            :  */
      81                 :            : #define NRFX_CHECK(module_enabled)  (module_enabled)
      82                 :            : 
      83                 :            : /**
      84                 :            :  * @brief Macro for creating unsigned integer with bit position @p x set.
      85                 :            :  *
      86                 :            :  * @param[in] x Bit position to be set.
      87                 :            :  *
      88                 :            :  * @return Unsigned integer with requested bit position set.
      89                 :            :  */
      90                 :            : #define NRFX_BIT(x) (1UL << (x))
      91                 :            : 
      92                 :            : /**
      93                 :            :  * @brief Macro for returning bit mask or 0 if @p x is 0.
      94                 :            :  *
      95                 :            :  * @param[in] x Bit mask size. Bit mask has bits 0 through x-1 (inclusive) set.
      96                 :            :  *
      97                 :            :  * @return Bit mask.
      98                 :            :  */
      99                 :            : #define NRFX_BIT_MASK(x) (NRFX_BIT(x) - 1UL)
     100                 :            : 
     101                 :            : /**
     102                 :            :  * @brief Macro for concatenating two tokens in macro expansion.
     103                 :            :  *
     104                 :            :  * @note This macro is expanded in two steps so that tokens given as macros
     105                 :            :  *       themselves are fully expanded before they are merged.
     106                 :            :  *
     107                 :            :  * @param[in] p1 First token.
     108                 :            :  * @param[in] p2 Second token.
     109                 :            :  *
     110                 :            :  * @return The two tokens merged into one, unless they cannot together form
     111                 :            :  *         a valid token (in such case, the preprocessor issues a warning and
     112                 :            :  *         does not perform the concatenation).
     113                 :            :  *
     114                 :            :  * @sa NRFX_CONCAT_3
     115                 :            :  */
     116                 :            : #define NRFX_CONCAT_2(p1, p2)       NRFX_CONCAT_2_(p1, p2)
     117                 :            : 
     118                 :            : /** @brief Internal macro used by @ref NRFX_CONCAT_2 to perform the expansion in two steps. */
     119                 :            : #define NRFX_CONCAT_2_(p1, p2)      p1 ## p2
     120                 :            : 
     121                 :            : /**
     122                 :            :  * @brief Macro for concatenating three tokens in macro expansion.
     123                 :            :  *
     124                 :            :  * @note This macro is expanded in two steps so that tokens given as macros
     125                 :            :  *       themselves are fully expanded before they are merged.
     126                 :            :  *
     127                 :            :  * @param[in] p1 First token.
     128                 :            :  * @param[in] p2 Second token.
     129                 :            :  * @param[in] p3 Third token.
     130                 :            :  *
     131                 :            :  * @return The three tokens merged into one, unless they cannot together form
     132                 :            :  *         a valid token (in such case, the preprocessor issues a warning and
     133                 :            :  *         does not perform the concatenation).
     134                 :            :  *
     135                 :            :  * @sa NRFX_CONCAT_2
     136                 :            :  */
     137                 :            : #define NRFX_CONCAT_3(p1, p2, p3)   NRFX_CONCAT_3_(p1, p2, p3)
     138                 :            : 
     139                 :            : /** @brief Internal macro used by @ref NRFX_CONCAT_3 to perform the expansion in two steps. */
     140                 :            : #define NRFX_CONCAT_3_(p1, p2, p3)  p1 ## p2 ## p3
     141                 :            : 
     142                 :            : /**
     143                 :            :  * @brief Macro for performing rounded integer division (as opposed to
     144                 :            :  *        truncating the result).
     145                 :            :  *
     146                 :            :  * @param[in] a Numerator.
     147                 :            :  * @param[in] b Denominator.
     148                 :            :  *
     149                 :            :  * @return Rounded (integer) result of dividing @c a by @c b.
     150                 :            :  */
     151                 :            : #define NRFX_ROUNDED_DIV(a, b)  (((a) + ((b) / 2)) / (b))
     152                 :            : 
     153                 :            : /**
     154                 :            :  * @brief Macro for performing integer division, making sure the result is rounded up.
     155                 :            :  *
     156                 :            :  * @details A typical use case for this macro is to compute the number of objects
     157                 :            :  *          with size @c b required to hold @c a number of bytes.
     158                 :            :  *
     159                 :            :  * @param[in] a Numerator.
     160                 :            :  * @param[in] b Denominator.
     161                 :            :  *
     162                 :            :  * @return Integer result of dividing @c a by @c b, rounded up.
     163                 :            :  */
     164                 :            : #define NRFX_CEIL_DIV(a, b)  ((((a) - 1) / (b)) + 1)
     165                 :            : 
     166                 :            : /**
     167                 :            :  * @brief Macro for getting the number of elements in an array.
     168                 :            :  *
     169                 :            :  * @param[in] array Name of the array.
     170                 :            :  *
     171                 :            :  * @return Array element count.
     172                 :            :  */
     173                 :            : #define NRFX_ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
     174                 :            : 
     175                 :            : /**
     176                 :            :  * @brief Macro for getting the offset (in bytes) from the beginning of a structure
     177                 :            :  *        of the specified type to its specified member.
     178                 :            :  *
     179                 :            :  * @param[in] type   Structure type.
     180                 :            :  * @param[in] member Structure member whose offset is searched for.
     181                 :            :  *
     182                 :            :  * @return Member offset in bytes.
     183                 :            :  */
     184                 :            : #define NRFX_OFFSETOF(type, member)  ((size_t)&(((type *)0)->member))
     185                 :            : 
     186                 :            : /**@brief Macro for checking if given lengths of EasyDMA transfers do not exceed
     187                 :            :  *        the limit of the specified peripheral.
     188                 :            :  *
     189                 :            :  * @param[in] peripheral Peripheral to check the lengths against.
     190                 :            :  * @param[in] length1    First length to be checked.
     191                 :            :  * @param[in] length2    Second length to be checked (pass 0 if not needed).
     192                 :            :  *
     193                 :            :  * @retval true  The length of buffers does not exceed the limit of the specified peripheral.
     194                 :            :  * @retval false The length of buffers exceeds the limit of the specified peripheral.
     195                 :            :  */
     196                 :            : #define NRFX_EASYDMA_LENGTH_VALIDATE(peripheral, length1, length2)            \
     197                 :            :     (((length1) < (1U << NRFX_CONCAT_2(peripheral, _EASYDMA_MAXCNT_SIZE))) && \
     198                 :            :      ((length2) < (1U << NRFX_CONCAT_2(peripheral, _EASYDMA_MAXCNT_SIZE))))
     199                 :            : 
     200                 :            : /**
     201                 :            :  * @brief Macro for waiting until condition is met.
     202                 :            :  *
     203                 :            :  * @param[in]  condition Condition to meet.
     204                 :            :  * @param[in]  attempts  Maximum number of condition checks. Must not be 0.
     205                 :            :  * @param[in]  delay_us  Delay between consecutive checks, in microseconds.
     206                 :            :  * @param[out] result    Boolean variable to store the result of the wait process.
     207                 :            :  *                       Set to true if the condition is met or false otherwise.
     208                 :            :  */
     209                 :            : #define NRFX_WAIT_FOR(condition, attempts, delay_us, result) \
     210                 :            : do {                                                         \
     211                 :            :     result =  false;                                         \
     212                 :            :     uint32_t remaining_attempts = (attempts);                \
     213                 :            :     do {                                                     \
     214                 :            :            if (condition)                                    \
     215                 :            :            {                                                 \
     216                 :            :                result =  true;                               \
     217                 :            :                break;                                        \
     218                 :            :            }                                                 \
     219                 :            :            NRFX_DELAY_US(delay_us);                          \
     220                 :            :     } while (--remaining_attempts);                          \
     221                 :            : } while(0)
     222                 :            : 
     223                 :            : /**
     224                 :            :  * @brief Macro for getting the ID number of the specified peripheral.
     225                 :            :  *
     226                 :            :  * For peripherals in Nordic SoCs, there is a direct relationship between their
     227                 :            :  * ID numbers and their base addresses. See the chapter "Peripheral interface"
     228                 :            :  * (section "Peripheral ID") in the Product Specification.
     229                 :            :  *
     230                 :            :  * @param[in] base_addr Peripheral base address or pointer.
     231                 :            :  *
     232                 :            :  * @return ID number associated with the specified peripheral.
     233                 :            :  */
     234                 :            : #define NRFX_PERIPHERAL_ID_GET(base_addr)  (uint8_t)((uint32_t)(base_addr) >> 12)
     235                 :            : 
     236                 :            : /**
     237                 :            :  * @brief Macro for getting the interrupt number assigned to a specific
     238                 :            :  *        peripheral.
     239                 :            :  *
     240                 :            :  * For peripherals in Nordic SoCs, the IRQ number assigned to a peripheral is
     241                 :            :  * equal to its ID number. See the chapter "Peripheral interface" (sections
     242                 :            :  * "Peripheral ID" and "Interrupts") in the Product Specification.
     243                 :            :  *
     244                 :            :  * @param[in] base_addr Peripheral base address or pointer.
     245                 :            :  *
     246                 :            :  * @return Interrupt number associated with the specified peripheral.
     247                 :            :  */
     248                 :            : #define NRFX_IRQ_NUMBER_GET(base_addr)  NRFX_PERIPHERAL_ID_GET(base_addr)
     249                 :            : 
     250                 :            : /** @brief IRQ handler type. */
     251                 :            : typedef void (* nrfx_irq_handler_t)(void);
     252                 :            : 
     253                 :            : /** @brief Driver state. */
     254                 :            : typedef enum
     255                 :            : {
     256                 :            :     NRFX_DRV_STATE_UNINITIALIZED, ///< Uninitialized.
     257                 :            :     NRFX_DRV_STATE_INITIALIZED,   ///< Initialized but powered off.
     258                 :            :     NRFX_DRV_STATE_POWERED_ON,    ///< Initialized and powered on.
     259                 :            : } nrfx_drv_state_t;
     260                 :            : 
     261                 :            : 
     262                 :            : /**
     263                 :            :  * @brief Function for checking if an object is placed in the Data RAM region.
     264                 :            :  *
     265                 :            :  * Several peripherals (the ones using EasyDMA) require the transfer buffers
     266                 :            :  * to be placed in the Data RAM region. This function can be used to check if
     267                 :            :  * this condition is met.
     268                 :            :  *
     269                 :            :  * @param[in] p_object Pointer to an object whose location is to be checked.
     270                 :            :  *
     271                 :            :  * @retval true  The pointed object is located in the Data RAM region.
     272                 :            :  * @retval false The pointed object is not located in the Data RAM region.
     273                 :            :  */
     274                 :            : NRF_STATIC_INLINE bool nrfx_is_in_ram(void const * p_object);
     275                 :            : 
     276                 :            : /**
     277                 :            :  * @brief Function for checking if an object is aligned to a 32-bit word
     278                 :            :  *
     279                 :            :  * Several peripherals (the ones using EasyDMA) require the transfer buffers
     280                 :            :  * to be aligned to a 32-bit word. This function can be used to check if
     281                 :            :  * this condition is met.
     282                 :            :  *
     283                 :            :  * @param[in] p_object  Pointer to an object whose location is to be checked.
     284                 :            :  *
     285                 :            :  * @retval true  The pointed object is aligned to a 32-bit word.
     286                 :            :  * @retval false The pointed object is not aligned to a 32-bit word.
     287                 :            :  */
     288                 :            : NRF_STATIC_INLINE bool nrfx_is_word_aligned(void const * p_object);
     289                 :            : 
     290                 :            : /**
     291                 :            :  * @brief Function for getting the interrupt number for the specified peripheral.
     292                 :            :  *
     293                 :            :  * @param[in] p_reg Peripheral base pointer.
     294                 :            :  *
     295                 :            :  * @return Interrupt number associated with the pointed peripheral.
     296                 :            :  */
     297                 :            : NRF_STATIC_INLINE IRQn_Type nrfx_get_irq_number(void const * p_reg);
     298                 :            : 
     299                 :            : /**
     300                 :            :  * @brief Function for converting an INTEN register bit position to the
     301                 :            :  *        corresponding event identifier.
     302                 :            :  *
     303                 :            :  * The event identifier is the offset between the event register address and
     304                 :            :  * the peripheral base address, and is equal (thus, can be directly cast) to
     305                 :            :  * the corresponding value of the enumerated type from HAL (nrf_*_event_t).
     306                 :            :  *
     307                 :            :  * @param[in] bit INTEN register bit position.
     308                 :            :  *
     309                 :            :  * @return Event identifier.
     310                 :            :  *
     311                 :            :  * @sa nrfx_event_to_bitpos
     312                 :            :  */
     313                 :            : NRF_STATIC_INLINE uint32_t nrfx_bitpos_to_event(uint32_t bit);
     314                 :            : 
     315                 :            : /**
     316                 :            :  * @brief Function for converting an event identifier to the corresponding
     317                 :            :  *        INTEN register bit position.
     318                 :            :  *
     319                 :            :  * The event identifier is the offset between the event register address and
     320                 :            :  * the peripheral base address, and is equal (thus, can be directly cast) to
     321                 :            :  * the corresponding value of the enumerated type from HAL (nrf_*_event_t).
     322                 :            :  *
     323                 :            :  * @param[in] event Event identifier.
     324                 :            :  *
     325                 :            :  * @return INTEN register bit position.
     326                 :            :  *
     327                 :            :  * @sa nrfx_bitpos_to_event
     328                 :            :  */
     329                 :            : NRF_STATIC_INLINE uint32_t nrfx_event_to_bitpos(uint32_t event);
     330                 :            : 
     331                 :            : 
     332                 :            : #ifndef NRF_DECLARE_ONLY
     333                 :            : 
     334                 :            : NRF_STATIC_INLINE bool nrfx_is_in_ram(void const * p_object)
     335                 :            : {
     336                 :            :     return ((((uint32_t)p_object) & 0xE0000000u) == 0x20000000u);
     337                 :            : }
     338                 :            : 
     339                 :            : NRF_STATIC_INLINE bool nrfx_is_word_aligned(void const * p_object)
     340                 :            : {
     341                 :            :     return ((((uint32_t)p_object) & 0x3u) == 0u);
     342                 :            : }
     343                 :            : 
     344                 :          3 : NRF_STATIC_INLINE IRQn_Type nrfx_get_irq_number(void const * p_reg)
     345                 :            : {
     346                 :          3 :     return (IRQn_Type)NRFX_IRQ_NUMBER_GET(p_reg);
     347                 :            : }
     348                 :            : 
     349                 :            : NRF_STATIC_INLINE uint32_t nrfx_bitpos_to_event(uint32_t bit)
     350                 :            : {
     351                 :            :     static const uint32_t event_reg_offset = 0x100u;
     352                 :            :     return event_reg_offset + (bit * sizeof(uint32_t));
     353                 :            : }
     354                 :            : 
     355                 :            : NRF_STATIC_INLINE uint32_t nrfx_event_to_bitpos(uint32_t event)
     356                 :            : {
     357                 :            :     static const uint32_t event_reg_offset = 0x100u;
     358                 :            :     return (event - event_reg_offset) / sizeof(uint32_t);
     359                 :            : }
     360                 :            : 
     361                 :            : #endif // NRF_DECLARE_ONLY
     362                 :            : 
     363                 :            : /** @} */
     364                 :            : 
     365                 :            : #ifdef __cplusplus
     366                 :            : }
     367                 :            : #endif
     368                 :            : 
     369                 :            : #endif // NRFX_COMMON_H__

Generated by: LCOV version 1.14