Nordic Semiconductor / nRF51822

Nordic stack and drivers for the mbed BLE API

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate writable_gatt ... more

TARGET_MCU_NRF51822/sdk/source/libraries/util/sdk_mapped_flags.h@638:c90ae1400bf2, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:39:43 2016 +0100
Revision:
638:c90ae1400bf2
Sync with bdab10dc0f90748b6989c8b577771bb403ca6bd8 from ARMmbed/mbed-os.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Vincent Coubard 638:c90ae1400bf2 1 /*
Vincent Coubard 638:c90ae1400bf2 2 * Copyright (c) Nordic Semiconductor ASA
Vincent Coubard 638:c90ae1400bf2 3 * All rights reserved.
Vincent Coubard 638:c90ae1400bf2 4 *
Vincent Coubard 638:c90ae1400bf2 5 * Redistribution and use in source and binary forms, with or without modification,
Vincent Coubard 638:c90ae1400bf2 6 * are permitted provided that the following conditions are met:
Vincent Coubard 638:c90ae1400bf2 7 *
Vincent Coubard 638:c90ae1400bf2 8 * 1. Redistributions of source code must retain the above copyright notice, this
Vincent Coubard 638:c90ae1400bf2 9 * list of conditions and the following disclaimer.
Vincent Coubard 638:c90ae1400bf2 10 *
Vincent Coubard 638:c90ae1400bf2 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
Vincent Coubard 638:c90ae1400bf2 12 * list of conditions and the following disclaimer in the documentation and/or
Vincent Coubard 638:c90ae1400bf2 13 * other materials provided with the distribution.
Vincent Coubard 638:c90ae1400bf2 14 *
Vincent Coubard 638:c90ae1400bf2 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
Vincent Coubard 638:c90ae1400bf2 16 * contributors to this software may be used to endorse or promote products
Vincent Coubard 638:c90ae1400bf2 17 * derived from this software without specific prior written permission.
Vincent Coubard 638:c90ae1400bf2 18 *
Vincent Coubard 638:c90ae1400bf2 19 *
Vincent Coubard 638:c90ae1400bf2 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
Vincent Coubard 638:c90ae1400bf2 21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
Vincent Coubard 638:c90ae1400bf2 22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
Vincent Coubard 638:c90ae1400bf2 23 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
Vincent Coubard 638:c90ae1400bf2 24 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
Vincent Coubard 638:c90ae1400bf2 25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
Vincent Coubard 638:c90ae1400bf2 26 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
Vincent Coubard 638:c90ae1400bf2 27 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
Vincent Coubard 638:c90ae1400bf2 28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
Vincent Coubard 638:c90ae1400bf2 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Vincent Coubard 638:c90ae1400bf2 30 *
Vincent Coubard 638:c90ae1400bf2 31 */
Vincent Coubard 638:c90ae1400bf2 32
Vincent Coubard 638:c90ae1400bf2 33 #ifndef SDK_MAPPED_FLAGS_H__
Vincent Coubard 638:c90ae1400bf2 34 #define SDK_MAPPED_FLAGS_H__
Vincent Coubard 638:c90ae1400bf2 35
Vincent Coubard 638:c90ae1400bf2 36 #include <stdint.h>
Vincent Coubard 638:c90ae1400bf2 37 #include <stdbool.h>
Vincent Coubard 638:c90ae1400bf2 38 #include "app_util.h"
Vincent Coubard 638:c90ae1400bf2 39 #include "compiler_abstraction.h"
Vincent Coubard 638:c90ae1400bf2 40
Vincent Coubard 638:c90ae1400bf2 41 /**
Vincent Coubard 638:c90ae1400bf2 42 * @file
Vincent Coubard 638:c90ae1400bf2 43 * @defgroup sdk_mapped_flags Mapped flags
Vincent Coubard 638:c90ae1400bf2 44 * @ingroup app_common
Vincent Coubard 638:c90ae1400bf2 45 * @{
Vincent Coubard 638:c90ae1400bf2 46 * @brief Module for writing and reading flags that are associated
Vincent Coubard 638:c90ae1400bf2 47 * with keys.
Vincent Coubard 638:c90ae1400bf2 48 *
Vincent Coubard 638:c90ae1400bf2 49 * @details The flags are represented as bits in a bitmap called a <i>flag collection</i>. The keys
Vincent Coubard 638:c90ae1400bf2 50 * are uint16_t. Each flag collection contains all flags of the same type, one flag for
Vincent Coubard 638:c90ae1400bf2 51 * each key.
Vincent Coubard 638:c90ae1400bf2 52 *
Vincent Coubard 638:c90ae1400bf2 53 * The mapped flags module does not keep the flag states, nor the list of keys. These are
Vincent Coubard 638:c90ae1400bf2 54 * provided in the API calls. A key's index in the key list determines which bit in the
Vincent Coubard 638:c90ae1400bf2 55 * flag collection is associated with it. This module does not ever edit the key list, and
Vincent Coubard 638:c90ae1400bf2 56 * does not edit flags except in function calls that take the flag collection as a pointer.
Vincent Coubard 638:c90ae1400bf2 57 *
Vincent Coubard 638:c90ae1400bf2 58 */
Vincent Coubard 638:c90ae1400bf2 59
Vincent Coubard 638:c90ae1400bf2 60 #define SDK_MAPPED_FLAGS_N_KEYS 8 /**< The number of keys to keep flags for. This is also the number of flags in a flag collection. If changing this value, you might also need change the width of the sdk_mapped_flags_t type. */
Vincent Coubard 638:c90ae1400bf2 61 #define SDK_MAPPED_FLAGS_N_KEYS_PER_BYTE 8 /**< The number of flags that fit in one byte. */
Vincent Coubard 638:c90ae1400bf2 62 #define SDK_MAPPED_FLAGS_INVALID_INDEX 0xFFFF /**< A flag index guaranteed to be invalid. */
Vincent Coubard 638:c90ae1400bf2 63
Vincent Coubard 638:c90ae1400bf2 64 typedef uint8_t sdk_mapped_flags_t; /**< The bitmap to hold flags. Each flag is one bit, and each bit represents the flag state associated with one key. */
Vincent Coubard 638:c90ae1400bf2 65
Vincent Coubard 638:c90ae1400bf2 66
Vincent Coubard 638:c90ae1400bf2 67 // Test whether the flag collection type is large enough to hold all the flags. If this fails,
Vincent Coubard 638:c90ae1400bf2 68 // reduce SDK_MAPPED_FLAGS_N_KEYS or increase the size of sdk_mapped_flags_t.
Vincent Coubard 638:c90ae1400bf2 69 STATIC_ASSERT((
Vincent Coubard 638:c90ae1400bf2 70 sizeof(sdk_mapped_flags_t)*SDK_MAPPED_FLAGS_N_KEYS_PER_BYTE) >= SDK_MAPPED_FLAGS_N_KEYS);
Vincent Coubard 638:c90ae1400bf2 71
Vincent Coubard 638:c90ae1400bf2 72
Vincent Coubard 638:c90ae1400bf2 73 /**@brief Type used to present a subset of the registered keys.
Vincent Coubard 638:c90ae1400bf2 74 */
Vincent Coubard 638:c90ae1400bf2 75 typedef struct
Vincent Coubard 638:c90ae1400bf2 76 {
Vincent Coubard 638:c90ae1400bf2 77 uint32_t len; /**< The length of the list. */
Vincent Coubard 638:c90ae1400bf2 78 uint16_t flag_keys[SDK_MAPPED_FLAGS_N_KEYS]; /**< The list of keys. */
Vincent Coubard 638:c90ae1400bf2 79 } sdk_mapped_flags_key_list_t;
Vincent Coubard 638:c90ae1400bf2 80
Vincent Coubard 638:c90ae1400bf2 81
Vincent Coubard 638:c90ae1400bf2 82 /**@brief Function for getting the first index at which the flag is true in the provided
Vincent Coubard 638:c90ae1400bf2 83 * collection.
Vincent Coubard 638:c90ae1400bf2 84 *
Vincent Coubard 638:c90ae1400bf2 85 * @param[in] flags The flag collection to search for a flag set to true.
Vincent Coubard 638:c90ae1400bf2 86 *
Vincent Coubard 638:c90ae1400bf2 87 * @return The first index that has its flag set to true. If none were found, the
Vincent Coubard 638:c90ae1400bf2 88 * function returns @ref SDK_MAPPED_FLAGS_INVALID_INDEX.
Vincent Coubard 638:c90ae1400bf2 89 */
Vincent Coubard 638:c90ae1400bf2 90 uint16_t sdk_mapped_flags_first_key_index_get(sdk_mapped_flags_t flags);
Vincent Coubard 638:c90ae1400bf2 91
Vincent Coubard 638:c90ae1400bf2 92
Vincent Coubard 638:c90ae1400bf2 93 /**@brief Function for updating the state of a flag.
Vincent Coubard 638:c90ae1400bf2 94 *
Vincent Coubard 638:c90ae1400bf2 95 * @param[in] p_keys The list of associated keys (assumed to have a length of
Vincent Coubard 638:c90ae1400bf2 96 * @ref SDK_MAPPED_FLAGS_N_KEYS).
Vincent Coubard 638:c90ae1400bf2 97 * @param[out] p_flags The flag collection to modify.
Vincent Coubard 638:c90ae1400bf2 98 * @param[in] key The key to modify the flag of.
Vincent Coubard 638:c90ae1400bf2 99 * @param[in] value The state to set the flag to.
Vincent Coubard 638:c90ae1400bf2 100 */
Vincent Coubard 638:c90ae1400bf2 101 void sdk_mapped_flags_update_by_key(uint16_t * p_keys,
Vincent Coubard 638:c90ae1400bf2 102 sdk_mapped_flags_t * p_flags,
Vincent Coubard 638:c90ae1400bf2 103 uint16_t key,
Vincent Coubard 638:c90ae1400bf2 104 bool value);
Vincent Coubard 638:c90ae1400bf2 105
Vincent Coubard 638:c90ae1400bf2 106
Vincent Coubard 638:c90ae1400bf2 107 /**@brief Function for updating the state of the same flag in multiple flag collections.
Vincent Coubard 638:c90ae1400bf2 108 *
Vincent Coubard 638:c90ae1400bf2 109 * @details The key and value are the same for all flag collections in the p_flags array.
Vincent Coubard 638:c90ae1400bf2 110 *
Vincent Coubard 638:c90ae1400bf2 111 * @param[in] p_keys The list of associated keys (assumed to have a length of
Vincent Coubard 638:c90ae1400bf2 112 * @ref SDK_MAPPED_FLAGS_N_KEYS).
Vincent Coubard 638:c90ae1400bf2 113 * @param[out] p_flags The flag collections to modify.
Vincent Coubard 638:c90ae1400bf2 114 * @param[out] n_flag_collections The number of flag collections in p_flags.
Vincent Coubard 638:c90ae1400bf2 115 * @param[in] key The key to modify the flag of.
Vincent Coubard 638:c90ae1400bf2 116 * @param[in] value The state to set the flag to.
Vincent Coubard 638:c90ae1400bf2 117 */
Vincent Coubard 638:c90ae1400bf2 118 void sdk_mapped_flags_bulk_update_by_key(uint16_t * p_keys,
Vincent Coubard 638:c90ae1400bf2 119 sdk_mapped_flags_t * p_flags,
Vincent Coubard 638:c90ae1400bf2 120 uint32_t n_flag_collections,
Vincent Coubard 638:c90ae1400bf2 121 uint16_t key,
Vincent Coubard 638:c90ae1400bf2 122 bool value);
Vincent Coubard 638:c90ae1400bf2 123
Vincent Coubard 638:c90ae1400bf2 124
Vincent Coubard 638:c90ae1400bf2 125 /**@brief Function for getting the state of a specific flag.
Vincent Coubard 638:c90ae1400bf2 126 *
Vincent Coubard 638:c90ae1400bf2 127 * @param[in] p_keys The list of associated keys (assumed to have a length of
Vincent Coubard 638:c90ae1400bf2 128 * @ref SDK_MAPPED_FLAGS_N_KEYS).
Vincent Coubard 638:c90ae1400bf2 129 * @param[in] flags The flag collection to read from.
Vincent Coubard 638:c90ae1400bf2 130 * @param[in] key The key to get the flag for.
Vincent Coubard 638:c90ae1400bf2 131 *
Vincent Coubard 638:c90ae1400bf2 132 * @return The state of the flag.
Vincent Coubard 638:c90ae1400bf2 133 */
Vincent Coubard 638:c90ae1400bf2 134 bool sdk_mapped_flags_get_by_key(uint16_t * p_keys, sdk_mapped_flags_t flags, uint16_t key);
Vincent Coubard 638:c90ae1400bf2 135
Vincent Coubard 638:c90ae1400bf2 136
Vincent Coubard 638:c90ae1400bf2 137 /**@brief Function for getting a list of all keys that have a specific flag set to true.
Vincent Coubard 638:c90ae1400bf2 138 *
Vincent Coubard 638:c90ae1400bf2 139 * @param[in] p_keys The list of associated keys (assumed to have a length of
Vincent Coubard 638:c90ae1400bf2 140 * @ref SDK_MAPPED_FLAGS_N_KEYS).
Vincent Coubard 638:c90ae1400bf2 141 * @param[in] flags The flag collection to search.
Vincent Coubard 638:c90ae1400bf2 142 *
Vincent Coubard 638:c90ae1400bf2 143 * @return The list of keys.
Vincent Coubard 638:c90ae1400bf2 144 */
Vincent Coubard 638:c90ae1400bf2 145 sdk_mapped_flags_key_list_t sdk_mapped_flags_key_list_get(uint16_t * p_keys,
Vincent Coubard 638:c90ae1400bf2 146 sdk_mapped_flags_t flags);
Vincent Coubard 638:c90ae1400bf2 147
Vincent Coubard 638:c90ae1400bf2 148
Vincent Coubard 638:c90ae1400bf2 149 /**@brief Function for getting the number of keys that have a specific flag set to true.
Vincent Coubard 638:c90ae1400bf2 150 *
Vincent Coubard 638:c90ae1400bf2 151 * @param[in] flags The flag collection to search.
Vincent Coubard 638:c90ae1400bf2 152 *
Vincent Coubard 638:c90ae1400bf2 153 * @return The number of keys.
Vincent Coubard 638:c90ae1400bf2 154 */
Vincent Coubard 638:c90ae1400bf2 155 uint32_t sdk_mapped_flags_n_flags_set(sdk_mapped_flags_t flags);
Vincent Coubard 638:c90ae1400bf2 156
Vincent Coubard 638:c90ae1400bf2 157
Vincent Coubard 638:c90ae1400bf2 158 /**@brief Function for querying whether any flags in the collection are set.
Vincent Coubard 638:c90ae1400bf2 159 *
Vincent Coubard 638:c90ae1400bf2 160 * @param[in] flags The flag collection to query.
Vincent Coubard 638:c90ae1400bf2 161 *
Vincent Coubard 638:c90ae1400bf2 162 * @retval true If one or more flags are set to true.
Vincent Coubard 638:c90ae1400bf2 163 * @retval false Otherwise.
Vincent Coubard 638:c90ae1400bf2 164 */
Vincent Coubard 638:c90ae1400bf2 165 static __INLINE bool sdk_mapped_flags_any_set(sdk_mapped_flags_t flags)
Vincent Coubard 638:c90ae1400bf2 166 {
Vincent Coubard 638:c90ae1400bf2 167 return (flags != 0);
Vincent Coubard 638:c90ae1400bf2 168 }
Vincent Coubard 638:c90ae1400bf2 169
Vincent Coubard 638:c90ae1400bf2 170
Vincent Coubard 638:c90ae1400bf2 171 /** @} */
Vincent Coubard 638:c90ae1400bf2 172
Vincent Coubard 638:c90ae1400bf2 173 #endif /* SDK_MAPPED_FLAGS_H__ */