Software APIs
Macros | Functions
memory.h File Reference

(937cb67)

OpenTitan Device Memory Library. More...

#include <stdalign.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "sw/device/lib/base/macros.h"

Go to the source code of this file.

Macros

#define OT_PREFIX_IF_NOT_RV32(name)   ot_##name
 

Functions

OT_WARN_UNUSED_RESULT ptrdiff_t misalignment32_of (uintptr_t addr)
 Computes how many bytes addr is ahead of the previous 32-bit word alignment boundary.
 
OT_WARN_UNUSED_RESULT uint32_t read_32 (const void *ptr)
 Load a word from memory directly, bypassing aliasing rules. More...
 
OT_WARN_UNUSED_RESULT uint64_t read_64 (const void *ptr)
 Load a 64-bit word from memory directly, bypassing aliasing rules. More...
 
void write_32 (uint32_t value, void *ptr)
 Store a word to memory directly, bypassing aliasing rules. More...
 
void write_64 (uint64_t value, void *ptr)
 Store a 64-bit word to memory directly, bypassing aliasing rules. More...
 
void *OT_PREFIX_IF_NOT_RV32() memcpy (void *OT_RESTRICT dest, const void *OT_RESTRICT src, size_t len)
 Copy memory between non-overlapping regions. More...
 
void *OT_PREFIX_IF_NOT_RV32() memset (void *dest, int value, size_t len)
 Set a region of memory to a particular byte value. More...
 
int OT_PREFIX_IF_NOT_RV32() memcmp (const void *lhs, const void *rhs, size_t len)
 Compare two (potentially overlapping) regions of memory for byte-wise lexicographic order. More...
 
int memrcmp (const void *lhs, const void *rhs, size_t len)
 Compare two (potentially overlapping) regions of memory for reverse byte-wise lexicographic order (i.e. More...
 
void *OT_PREFIX_IF_NOT_RV32() memchr (const void *ptr, int value, size_t len)
 Search a region of memory for the first occurrence of a particular byte value. More...
 
void *OT_PREFIX_IF_NOT_RV32() memrchr (const void *ptr, int value, size_t len)
 Search a region of memory for the last occurrence of a particular byte value. More...
 

Detailed Description

OpenTitan Device Memory Library.

This library provides memory functions for aligned word accesses, and some useful functions from the C library's <string.h>.

Definition in file memory.h.

Function Documentation

◆ memchr()

void* OT_PREFIX_IF_NOT_RV32() memchr ( const void *  ptr,
int  value,
size_t  len 
)

Search a region of memory for the first occurrence of a particular byte value.

This function conforms to the semantics defined in ISO C11 S7.24.5.1.

Since libbase does not provide a strlen() function, this function can be used as an approximation: memchr(my_str, 0, SIZE_MAX) - my_str.

This function will be provided by the platform's libc implementation for host builds.

Parameters
ptrthe region to search.
valuethe value, converted to a byte, to search for.
lenthe length of the region, in bytes.
Returns
a pointer to the found value, or NULL.

Definition at line 190 of file memory.c.

◆ memcmp()

int OT_PREFIX_IF_NOT_RV32() memcmp ( const void *  lhs,
const void *  rhs,
size_t  len 
)

Compare two (potentially overlapping) regions of memory for byte-wise lexicographic order.

This function conforms to the semantics defined in ISO C11 S7.24.4.1.

This function will be provided by the platform's libc implementation for host builds.

Parameters
lhsthe left-hand-side of the comparison.
rhsthe right-hand-side of the comparison.
lenthe length of both regions, in bytes.
Returns
a zero, positive, or negative integer, corresponding to the contingencies of lhs == rhs, lhs > rhs, and lhs < rhs (as buffers, not pointers), respectively.

Definition at line 110 of file memory.c.

◆ memcpy()

void* OT_PREFIX_IF_NOT_RV32() memcpy ( void *OT_RESTRICT  dest,
const void *OT_RESTRICT  src,
size_t  len 
)

Copy memory between non-overlapping regions.

This function conforms to the semantics defined in ISO C11 S7.23.2.1.

This function will be provided by the platform's libc implementation for host builds.

Parameters
destthe region to copy to.
srcthe region to copy from.
lenthe number of bytes to copy.
Returns
the value of dest.

◆ memrchr()

void* OT_PREFIX_IF_NOT_RV32() memrchr ( const void *  ptr,
int  value,
size_t  len 
)

Search a region of memory for the last occurrence of a particular byte value.

This function is not specified by C11, but is named for a well-known glibc extension.

Parameters
ptrthe region to search.
valuethe value, converted to a byte, to search for.
lenthe length of the region, in bytes.
Returns
a pointer to the found value, or NULL.

Definition at line 229 of file memory.c.

◆ memrcmp()

int memrcmp ( const void *  lhs,
const void *  rhs,
size_t  len 
)

Compare two (potentially overlapping) regions of memory for reverse byte-wise lexicographic order (i.e.

the same as memcmp, but starting from the end of the memory regions).

Can be used for arithmetic comparison of little-endian buffers.

This function is provided by OpenTitan in host builds, not by the platform's libc implementation.

Parameters
lhsthe left-hand-side of the comparison.
rhsthe right-hand-side of the comparison.
lenthe length of both regions, in bytes.
Returns
a zero, positive, or negative integer, corresponding to the contingencies of lhs == rhs, lhs > rhs, and lhs < rhs (as buffers, not pointers), respectively.

Definition at line 149 of file memory.c.

◆ memset()

void* OT_PREFIX_IF_NOT_RV32() memset ( void *  dest,
int  value,
size_t  len 
)

Set a region of memory to a particular byte value.

This function conforms to the semantics defined in ISO C11 S7.23.6.1.

This function will be provided by the platform's libc implementation for host builds.

Parameters
destthe region to write to.
valuethe value, converted to a byte, to write to each byte cell.
lenthe number of bytes to write.
Returns
the value of dest.

Definition at line 84 of file memory.c.

◆ read_32()

OT_WARN_UNUSED_RESULT uint32_t read_32 ( const void *  ptr)
inline

Load a word from memory directly, bypassing aliasing rules.

ISO C forbids, in general, casting a pointer to non-character types and reading them, though it is frequently necessary to read exactly one word out of a void *. This function performs that action in a manner which is well-defined.

Of course, ptr must point to word-aligned memory that is at least one word wide. To do otherwise is Undefined Behavior. It goes without saying that the memory this function intents to read must be initialized.

This function has reordering properties as weak as a normal, non-atomic, non-volatile load.

Parameters
ptra word-aligned pointer pointed to at least four bytes of memory.
Returns
the word ptr points to.

Definition at line 80 of file memory.h.

◆ read_64()

OT_WARN_UNUSED_RESULT uint64_t read_64 ( const void *  ptr)
inline

Load a 64-bit word from memory directly, bypassing aliasing rules.

ISO C forbids, in general, casting a pointer to non-character types and reading them, though it is frequently necessary to read exactly one 64-bit word out of a void *. This function performs that action in a manner which is well-defined.

Of course, ptr must point to word-aligned memory that is at least one 64-bit word wide. To do otherwise is Undefined Behavior. It goes without saying that the memory this function intents to read must be initialized.

This function has reordering properties as weak as a normal, non-atomic, non-volatile load.

Parameters
ptra word-aligned pointer pointed to at least four bytes of memory.
Returns
the word ptr points to.

Definition at line 113 of file memory.h.

◆ write_32()

void write_32 ( uint32_t  value,
void *  ptr 
)
inline

Store a word to memory directly, bypassing aliasing rules.

ISO C forbids, in general, casting a pointer to non-character types and reading them, though it is frequently necessary to write exactly one word to a void *. This function performs that action in a manner which is well-defined.

Of course, ptr must point to word-aligned memory that is at least one word wide. To do otherwise is Undefined Behavior.

This function has reordering properties as weak as a normal, non-atomic, non-volatile load.

Parameters
valuethe value to store.
ptra word-aligned pointer pointed to at least four bytes of memory.

Definition at line 144 of file memory.h.

◆ write_64()

void write_64 ( uint64_t  value,
void *  ptr 
)
inline

Store a 64-bit word to memory directly, bypassing aliasing rules.

ISO C forbids, in general, casting a pointer to non-character types and reading them, though it is frequently necessary to write exactly one 64-bit word to a void *. This function performs that action in a manner which is well-defined.

Of course, ptr must point to word-aligned memory that is at least one 64-bit word wide. To do otherwise is Undefined Behavior.

This function has reordering properties as weak as a normal, non-atomic, non-volatile load.

Parameters
valuethe value to store.
ptra word-aligned pointer pointed to at least four bytes of memory.

Definition at line 170 of file memory.h.