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