1 /* 2 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef _HARDWARE_CLAIM_H 8 #define _HARDWARE_CLAIM_H 9 10 #include "pico.h" 11 #include "hardware/sync.h" 12 13 /** \file claim.h 14 * \defgroup hardware_claim hardware_claim 15 * 16 * Lightweight hardware resource management 17 * 18 * `hardware_claim` provides a simple API for management of hardware resources at runtime. 19 * 20 * This API is usually called by other hardware specific _claiming_ APIs and provides simple 21 * multi-core safe methods to manipulate compact bit-sets representing hardware resources. 22 * 23 * This API allows any other library to cooperatively participate in a scheme by which 24 * both compile time and runtime allocation of resources can co-exist, and conflicts 25 * can be avoided or detected (depending on the use case) without the libraries having 26 * any other knowledge of each other. 27 * 28 * Facilities are providing for: 29 * 30 * 1. Claiming resources (and asserting if they are already claimed) 31 * 2. Freeing (unclaiming) resources 32 * 3. Finding unused resources 33 */ 34 35 /*! \brief Atomically claim a resource, panicking if it is already in use 36 * \ingroup hardware_claim 37 * 38 * The resource ownership is indicated by the bit_index bit in an array of bits. 39 * 40 * \param bits pointer to an array of bits (8 bits per byte) 41 * \param bit_index resource to claim (bit index into array of bits) 42 * \param message string to display if the bit cannot be claimed; note this may have a single printf format "%d" for the bit 43 */ 44 void hw_claim_or_assert(uint8_t *bits, uint bit_index, const char *message); 45 46 /*! \brief Atomically claim one resource out of a range of resources, optionally asserting if none are free 47 * \ingroup hardware_claim 48 * 49 * \param bits pointer to an array of bits (8 bits per byte) 50 * \param required true if this method should panic if the resource is not free 51 * \param bit_lsb the lower bound (inclusive) of the resource range to claim from 52 * \param bit_msb the upper bound (inclusive) of the resource range to claim from 53 * \param message string to display if the bit cannot be claimed 54 * \return the bit index representing the claimed or -1 if none are available in the range, and required = false 55 */ 56 int hw_claim_unused_from_range(uint8_t *bits, bool required, uint bit_lsb, uint bit_msb, const char *message); 57 58 /*! \brief Determine if a resource is claimed at the time of the call 59 * \ingroup hardware_claim 60 * 61 * The resource ownership is indicated by the bit_index bit in an array of bits. 62 * 63 * \param bits pointer to an array of bits (8 bits per byte) 64 * \param bit_index resource to unclaim (bit index into array of bits) 65 * \return true if the resource is claimed 66 */ 67 bool hw_is_claimed(uint8_t *bits, uint bit_index); 68 69 /*! \brief Atomically unclaim a resource 70 * \ingroup hardware_claim 71 * 72 * The resource ownership is indicated by the bit_index bit in an array of bits. 73 * 74 * \param bits pointer to an array of bits (8 bits per byte) 75 * \param bit_index resource to unclaim (bit index into array of bits) 76 */ 77 void hw_claim_clear(uint8_t *bits, uint bit_index); 78 79 /*! \brief Acquire the runtime mutual exclusion lock provided by the `hardware_claim` library 80 * \ingroup hardware_claim 81 * 82 * This method is called automatically by the other `hw_claim_` methods, however it is provided as a convenience 83 * to code that might want to protect other hardware initialization code from concurrent use. 84 * 85 * \note hw_claim_lock() uses a spin lock internally, so disables interrupts on the calling core, and will deadlock 86 * if the calling core already owns the lock. 87 * 88 * \return a token to pass to hw_claim_unlock() 89 */ 90 uint32_t hw_claim_lock(void); 91 92 /*! \brief Release the runtime mutual exclusion lock provided by the `hardware_claim` library 93 * \ingroup hardware_claim 94 * 95 * \note This method MUST be called from the same core that call hw_claim_lock() 96 * 97 * \param token the token returned by the corresponding call to hw_claim_lock() 98 */ 99 void hw_claim_unlock(uint32_t token); 100 101 #endif 102