mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
127 lines
3.6 KiB
C
127 lines
3.6 KiB
C
/*
|
|
* Copyright (C) 2020 Otto-von-Guericke-Universität Magdeburg
|
|
*
|
|
* This file is subject to the terms and conditions of the GNU Lesser General
|
|
* Public License v2.1. See the file LICENSE in the top level directory for more
|
|
* details.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup sys_ptrtag Helpers for pointer tagging
|
|
* @ingroup sys
|
|
*
|
|
* # Concept
|
|
*
|
|
* Data structures are often aligned in memory to the word size. On 32 bit
|
|
* machines, this often results in the two least significant bits containing no
|
|
* information (as they have to be zero, due to this alignment). In many cases
|
|
* gaining two bits of information storage in RAM is all you need. In these
|
|
* case, pointer tagging can come in handy.
|
|
*
|
|
* The tricky part is however to get this working portable on all architectures,
|
|
* possibly even on 8 bit machines that have no alignment requirements. This
|
|
* utility provides helpers to enforce alignment requirements for all platforms,
|
|
* so that pointer tagging can be used everywhere.
|
|
*
|
|
* # Usage
|
|
*
|
|
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
|
|
* // Use the PTRTAG attribute to ensure that pointers to this structure can
|
|
* // be tagged, even if structure would not have a suitable alignment
|
|
* // otherwise
|
|
* typedef struct PTRTAG {
|
|
* uint32_t bar;
|
|
* } foo_t;
|
|
*
|
|
* void isr_callback(void *data) {
|
|
* // extract pointer
|
|
* struct foo *ptr = ptrtag_ptr(data);
|
|
* // extract tag
|
|
* uint8_t tag = ptrtag_tag(data);
|
|
* work_on_data(ptr, tag);
|
|
* }
|
|
*
|
|
* int main(void) {
|
|
* foo_t data;
|
|
* uint8_t tag = 3;
|
|
* // pack pointer and tag into tagged pointer
|
|
* void *ptr_and_tag = ptrtag(&data, tag);
|
|
* init_isr(params, isr_callback, ptr_and_tag);
|
|
* }
|
|
*
|
|
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
*
|
|
* @{
|
|
*
|
|
* @file
|
|
* @brief Pointer Tagging Helpers
|
|
* @author Marian Buschsieweke <marian.buschsieweke@ovgu.de>
|
|
*/
|
|
|
|
#ifndef PTRTAG_H
|
|
#define PTRTAG_H
|
|
|
|
#include <assert.h>
|
|
#include <inttypes.h>
|
|
#include <stdint.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Pointers to data marked with this attribute will be tag-able.
|
|
*
|
|
* @details This will ensure a minimum alignment of 4 bytes
|
|
*/
|
|
#define PTRTAG __attribute__((aligned(4)))
|
|
|
|
/**
|
|
* @brief Create a tagged pointer
|
|
* @param ptr Pointer to tag
|
|
* @param tag Tag to add
|
|
* @return Tagged pointer encoding both @p ptr and @p tag
|
|
*
|
|
* @pre @p ptr points to data marked with @ref PTRTAG
|
|
* @pre @p tag contains a two bit value (its numeric value 0, 1, 2, or 3)
|
|
*
|
|
* Expect assertions blowing up when the preconditions are not met.
|
|
*/
|
|
static inline void * ptrtag(void *ptr, uint8_t tag)
|
|
{
|
|
uintptr_t tmp = (uintptr_t)ptr;
|
|
/* ensure ptr is aligned to four bytes and tag fits in two bits */
|
|
assert((tag < 4) && !(tmp & 0x3));
|
|
return (void *)(tmp | tag);
|
|
}
|
|
|
|
/**
|
|
* @brief Extract the original pointer from a tagged pointer
|
|
* @param tagged_ptr The tagged pointer to extract the original pointer from
|
|
* @return The original "un-tagged" pointer encoded in @p tagged_ptr
|
|
*/
|
|
static inline void * ptrtag_ptr(void *tagged_ptr)
|
|
{
|
|
uintptr_t tagged = (uintptr_t)tagged_ptr;
|
|
const uintptr_t mask = 0x3;
|
|
return (void *)(tagged & (~mask));
|
|
}
|
|
|
|
/**
|
|
* @brief Extract the tag from a tagged pointer
|
|
* @param tagged_ptr The tagged pointer to extract the original pointer from
|
|
* @return The tag encoded into @p tagged_ptr
|
|
*/
|
|
static inline uint8_t ptrtag_tag(void *tagged_ptr)
|
|
{
|
|
uintptr_t tagged = (uintptr_t)tagged_ptr;
|
|
return tagged & 0x3;
|
|
}
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* PTRTAG_H */
|
|
/** @} */
|