Helpers for pointer tagging

Detailed Description

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

// 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);
}

Files

file  ptrtag.h
 Pointer Tagging Helpers.
 

Macros

#define PTRTAG   __attribute__((aligned(4)))
 Pointers to data marked with this attribute will be tag-able. More...
 

Functions

static void * ptrtag (void *ptr, uint8_t tag)
 Create a tagged pointer. More...
 
static void * ptrtag_ptr (void *tagged_ptr)
 Extract the original pointer from a tagged pointer. More...
 
static uint8_t ptrtag_tag (void *tagged_ptr)
 Extract the tag from a tagged pointer. More...
 

Macro Definition Documentation

◆ PTRTAG

#define PTRTAG   __attribute__((aligned(4)))

Pointers to data marked with this attribute will be tag-able.

This will ensure a minimum alignment of 4 bytes

Definition at line 77 of file ptrtag.h.

Function Documentation

◆ ptrtag()

static void* ptrtag ( void *  ptr,
uint8_t  tag 
)
inlinestatic

Create a tagged pointer.

Parameters
ptrPointer to tag
tagTag to add
Returns
Tagged pointer encoding both ptr and tag
Precondition
ptr points to data marked with PTRTAG
tag contains a two bit value (its numeric value 0, 1, 2, or 3)

Expect assertions blowing up when the preconditions are not met.

Definition at line 90 of file ptrtag.h.

◆ ptrtag_ptr()

static void* ptrtag_ptr ( void *  tagged_ptr)
inlinestatic

Extract the original pointer from a tagged pointer.

Parameters
tagged_ptrThe tagged pointer to extract the original pointer from
Returns
The original "un-tagged" pointer encoded in tagged_ptr

Definition at line 103 of file ptrtag.h.

◆ ptrtag_tag()

static uint8_t ptrtag_tag ( void *  tagged_ptr)
inlinestatic

Extract the tag from a tagged pointer.

Parameters
tagged_ptrThe tagged pointer to extract the original pointer from
Returns
The tag encoded into tagged_ptr

Definition at line 115 of file ptrtag.h.

ptrtag_tag
static uint8_t ptrtag_tag(void *tagged_ptr)
Extract the tag from a tagged pointer.
Definition: ptrtag.h:115
ptrtag_ptr
static void * ptrtag_ptr(void *tagged_ptr)
Extract the original pointer from a tagged pointer.
Definition: ptrtag.h:103
PTRTAG
#define PTRTAG
Pointers to data marked with this attribute will be tag-able.
Definition: ptrtag.h:77
ptrtag
static void * ptrtag(void *ptr, uint8_t tag)
Create a tagged pointer.
Definition: ptrtag.h:90