torsten
77c67c12ca
Entire-Metadata: .entire/metadata/fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Session: fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Strategy: manual-commit
183 lines
6.0 KiB
C
183 lines
6.0 KiB
C
/*
|
|
* (c) Copyright, Real-Time Innovations, 2002-2024.
|
|
* All rights reserved.
|
|
*
|
|
* No duplications, whole or partial, manual or electronic, may be made
|
|
* without express written permission. Any such copies, or
|
|
* revisions thereof, must display this notice unaltered.
|
|
* This code contains trade secrets of Real-Time Innovations, Inc.
|
|
*/
|
|
|
|
#ifndef osapi_alignment_h
|
|
#define osapi_alignment_h
|
|
|
|
#include "osapi/osapi_dll.h"
|
|
#include "osapi/osapi_type.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** @internal \file
|
|
* \brief Memory alignment utility functions
|
|
*/
|
|
|
|
/** @internal \defgroup RTIOsapiAlignmentClass RTIOsapiAlignment
|
|
* \ingroup RTIOsapiModule
|
|
* \brief Helps with architecture-specific alignment
|
|
*
|
|
* Note that alignment is necessary for the following reasons:
|
|
* <OL>
|
|
* <LI>Required alignment for certain datatypes: on certain architectures
|
|
* if certain types are not aligned correctly, there will be a bus-
|
|
* error; this is fatal.
|
|
* Typically the required alignment is 4 (int), 8 (double or
|
|
* void* on 64-bit architectures)
|
|
* <LI>Suggested alignment for certain types: on certain architectures,
|
|
* using data-types that are not properly aligned will lead to a
|
|
* large drop in performance (because e.g. several bus-accesses are
|
|
* needed)
|
|
* <LI>Compilers/architectures will pack and align C-structures in a way
|
|
* that solves problems 1 and 2 for all C-structures. The alignment
|
|
* is reflected in the behaviour of malloc()/calloc() and sizeof().
|
|
* The precise behaviour is complicated by the fact that many compilers
|
|
* can be coaxed into non-default behaviour through command-line
|
|
* options or instructions in the source (e.g. #pragma pack).
|
|
* The code in this module will only function correctly if all source
|
|
* is compiled with the same alignment; all bets are off in other
|
|
* cases.
|
|
* <LI>For certain applications, it makes sense to further align data
|
|
* to achieve better performance. Common use cases are:
|
|
* <UL>
|
|
* <LI>alignment on a cache-line boundary
|
|
* <LI>alignment on a page-boundary
|
|
* <LI>alignment for I/O access
|
|
* </UL>
|
|
* </OL>
|
|
*/
|
|
|
|
/** @internal \ingroup RTIOsapiAlignmentClass
|
|
@brief The RTIOsapiAlignment is the alignment in bytes; an address
|
|
is aligned when is a positive integer multiple of the alignment
|
|
*/
|
|
typedef int RTIOsapiAlignment;
|
|
|
|
/** @internal \ingroup RTIOsapiAlignmentClass
|
|
* @brief Certain methods allow a default alignment: this should
|
|
* be an alignment that follows the "malloc" alignment of
|
|
* the architecture (aligned sufficiently to store any C-structure
|
|
* efficiently).
|
|
*/
|
|
#define RTI_OSAPI_ALIGNMENT_DEFAULT (-1)
|
|
|
|
/** @internal \ingroup RTIOsapiAlignmentClass
|
|
* \brief Certain methods that return an alignment
|
|
* can indicate an error in this way.
|
|
*/
|
|
#define RTI_OSAPI_ALIGNMENT_ERROR (0)
|
|
|
|
/** @internal \ingroup RTIOsapiAlignmentClass
|
|
* @brief static method to get alignment that is sufficient to store
|
|
* a C-structure of ANY size: any C-structure in the architecture
|
|
* can start on a boundary that is a multiple of
|
|
* RTIOsapiAlignment_getDefaultAlignment().
|
|
*
|
|
* @return the returned alignment is > 0, power of 2
|
|
*/
|
|
extern RTIOsapiDllExport RTIOsapiAlignment
|
|
RTIOsapiAlignment_getDefaultAlignment(void);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiAlignmentClass
|
|
* @brief static method to get the first address >= location that has
|
|
* the given alignment.
|
|
*
|
|
* @param location \b In. Address
|
|
* @param alignment \b In. must be > 0 and a power of 2
|
|
* @return An address >= location with the specified alignment
|
|
*/
|
|
extern RTIOsapiDllExport void *RTIOsapiAlignment_alignAddressUp(
|
|
void *location,
|
|
RTIOsapiAlignment alignment);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiAlignmentClass
|
|
* @brief method to round a size up to the next alignment boundary (passed as
|
|
* a parameter).
|
|
*
|
|
* @param size \b In. Size
|
|
* @param alignment \b In. must be > 0
|
|
* @return A size >= initial size with the specified alignment
|
|
*/
|
|
extern RTIOsapiDllExport size_t
|
|
RTIOsapiAlignment_alignSizeUp(size_t size, RTIOsapiAlignment alignment);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiAlignmentClass
|
|
* @brief method to round an RTI_INT32 up to the next alignment boundary (passed
|
|
* as a parameter).
|
|
*
|
|
* @param size \b In. Size
|
|
* @param alignment \b In. must be > 0
|
|
* @return A size >= initial size with the specified alignment
|
|
*/
|
|
extern RTIOsapiDllExport RTI_INT32
|
|
RTIOsapiAlignment_alignInt32Up(RTI_INT32 size, RTIOsapiAlignment alignment);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiAlignmentClass
|
|
* @brief method to round an RTI_UINT32 up to the next alignment boundary
|
|
* (passed as a parameter).
|
|
*
|
|
* @param size \b In. Size
|
|
* @param alignment \b In. must be > 0
|
|
* @return A size >= initial size with the specified alignment
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT32
|
|
RTIOsapiAlignment_alignUInt32Up(RTI_UINT32 size, RTIOsapiAlignment alignment);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiAlignmentClass
|
|
* @brief method to round an RTI_INT64 up to the next alignment boundary (passed
|
|
* as a parameter).
|
|
*
|
|
* @param size \b In. Size
|
|
* @param alignment \b In. must be > 0
|
|
* @return A size >= initial size with the specified alignment
|
|
*/
|
|
extern RTIOsapiDllExport RTI_INT64
|
|
RTIOsapiAlignment_alignInt64Up(RTI_INT64 size, RTIOsapiAlignment alignment);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiAlignmentClass
|
|
* @brief method to round an RTI_UINT64 up to the next alignment boundary
|
|
* (passed as a parameter).
|
|
*
|
|
* @param size \b In. Size
|
|
* @param alignment \b In. must be > 0
|
|
* @return A size >= initial size with the specified alignment
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT64
|
|
RTIOsapiAlignment_alignUInt64Up(RTI_UINT64 size, RTIOsapiAlignment alignment);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiAlignmentClass
|
|
* @brief method to test if a memory address is aligned
|
|
*
|
|
* @param size \b In. Size
|
|
* @param alignment \b In. must be > 0
|
|
* @return A size >= initial size with the specified alignment
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiAlignment_isAligned(
|
|
void *location,
|
|
RTIOsapiAlignment alignment);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|
|
|
|
#include "osapi/osapi_alignment_impl.h"
|
|
|
|
#endif /* osapi_alignment_h */
|