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