rtems/score/address.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreAddress
0007  *
0008  * @brief This header file provides the interfaces of the
0009  *   @ref RTEMSScoreAddress.
0010  */
0011
0012 /*
0013  *  COPYRIGHT (c) 1989-2006.
0014  *  On-Line Applications Research Corporation (OAR).
0015  *
0016  * Redistribution and use in source and binary forms, with or without
0017  * modification, are permitted provided that the following conditions
0018  * are met:
0019  * 1. Redistributions of source code must retain the above copyright
0020  *    notice, this list of conditions and the following disclaimer.
0021  * 2. Redistributions in binary form must reproduce the above copyright
0022  *    notice, this list of conditions and the following disclaimer in the
0023  *    documentation and/or other materials provided with the distribution.
0024  *
0025  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0026  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0027  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0028  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0029  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0030  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0031  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0032  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0033  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0034  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0035  * POSSIBILITY OF SUCH DAMAGE.
0036  */
0037
0038 #ifndef _RTEMS_SCORE_ADDRESS_H
0039 #define _RTEMS_SCORE_ADDRESS_H
0040
0041 #include <rtems/score/cpu.h>
0042
0043 #ifdef __cplusplus
0044 extern "C" {
0045 #endif
0046
0047 /**
0048  * @defgroup RTEMSScoreAddress Address Handler
0049  *
0050  * @ingroup RTEMSScore
0051  *
0052  * @brief This group contains the Address Handler implementation.
0053  *
0054  * This handler encapsulates functionality which abstracts address
0055  * manipulation in a portable manner.
0056  *
0057  * @{
0058  */
0059
0060 /**
0061  * @brief Adds offset to an address.
0062  *
0063  * This function is used to add an @a offset to a @a base address.
0064  * It returns the resulting address.  This address is typically
0065  * converted to an access type before being used further.
0066  *
0067  * @param base The base address to add the offset to.
0068  * @param offset The offset to add to @a base.
0069  *
0070  * @return This method returns the resulting address.
0071  */
0072 static inline void *_Addresses_Add_offset (
0073   const void *base,
0074   uintptr_t   offset
0075 )
0076 {
0077   return (void *)((uintptr_t)base + offset);
0078 }
0079
0080 /**
0081  * @brief Subtracts offset from an address.
0082  *
0083  * This function is used to subtract an @a offset from a @a base
0084  * address.  It returns the resulting address.  This address is
0085  * typically converted to an access type before being used further.
0086  *
0087  * @param base The base address to subtract the offset from.
0088  * @param offset The offset to subtract from @a base.
0089  *
0090  * @return This method returns the resulting address.
0091  */
0092
0093 static inline void *_Addresses_Subtract_offset (
0094   const void *base,
0095   uintptr_t   offset
0096 )
0097 {
0098   return (void *)((uintptr_t)base - offset);
0099 }
0100
0101 /**
0102  * @brief Subtracts two addresses.
0103  *
0104  * This function is used to subtract two addresses.  It returns the
0105  * resulting offset.
0106  *
0107  * @param left The address on the left hand side of the subtraction.
0108  * @param right The address on the right hand side of the subtraction.
0109  *
0110  * @return This method returns the resulting address.
0111  */
0112 static inline intptr_t _Addresses_Subtract(
0113   const void *left,
0114   const void *right
0115 )
0116 {
0117   return (intptr_t) ( (const char *) left - (const char *) right );
0118 }
0119
0120 /**
0121  * @brief Checks if address is aligned.
0122  *
0123  * This function returns true if the given address is correctly
0124  * aligned for this processor and false otherwise.  Proper alignment
0125  * is based on correctness and efficiency.
0126  *
0127  * @param address The address being checked for alignment.
0128  *
0129  * @retval true The @a address is aligned.
0130  * @retval false The @a address is not aligned.
0131  */
0132 static inline bool _Addresses_Is_aligned(
0133   const void *address
0134 )
0135 {
0136   return ( (uintptr_t) address % CPU_ALIGNMENT ) == 0;
0137 }
0138
0139 /**
0140  * @brief Checks if address is in range.
0141  *
0142  * This function returns true if the given address is within the
0143  * memory range specified and false otherwise.  @a base is the address
0144  * of the first byte in the memory range and @a limit is the address
0145  * of the last byte in the memory range.  The base address is
0146  * assumed to be lower than the limit address.
0147  *
0148  * @param address The address to check if it is in the given range.
0149  * @param base The lowest address of the range to check against.
0150  * @param limit The highest address of the range to check against.
0151  *
0152  * @retval true The @a address is within the memory range specified
0153  * @retval false The @a address is not within the memory range specified.
0154  */
0155 static inline bool _Addresses_Is_in_range (
0156   const void *address,
0157   const void *base,
0158   const void *limit
0159 )
0160 {
0161   return (address >= base && address <= limit);
0162 }
0163
0164 /**
0165  * @brief Aligns address to nearest multiple of alignment, rounding up.
0166  *
0167  * This function returns the given address aligned to the given alignment.
0168  * If the address already is aligned, or if alignment is 0, the address is
0169  * returned as is. The returned address is greater than or equal to the
0170  * given address.
0171  *
0172  * @param address The address to align to the given alignment.
0173  * @param alignment The desired alignment for the address. It must be a power of two.
0174  *
0175  * @return Returns the aligned address.
0176  */
0177 static inline void *_Addresses_Align_up(
0178   void *address,
0179   size_t alignment
0180 )
0181 {
0182   uintptr_t mask = alignment - (uintptr_t)1;
0183   return (void*)(((uintptr_t)address + mask) & ~mask);
0184 }
0185
0186 /**
0187  * @brief Aligns address to nearest multiple of alignment, truncating.
0188  *
0189  * This function returns the given address aligned to the given alignment.
0190  * If the address already is aligned, or if alignment is 0, the address is
0191  * returned as is. The returned address is less than or equal to the
0192  * given address.
0193  *
0194  * @param address The address to align to the given alignment.
0195  * @param alignment The desired alignment for the address. It must be a power of two.
0196  *
0197  * @return Returns the aligned address.
0198  */
0199 static inline void *_Addresses_Align_down(
0200   void *address,
0201   size_t alignment
0202 )
0203 {
0204   uintptr_t mask = alignment - (uintptr_t)1;
0205   return (void*)((uintptr_t)address & ~mask);
0206 }
0207
0208 /** @} */
0209
0210 #ifdef __cplusplus
0211 }
0212 #endif
0213
0214 #endif
0215 /* end of include file */