git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Demo/FreeRTOS_Plus_POSIX_with_actor_Windows_Simulator/lib/include/FreeRTOS_POSIX/utils.h

   1 /*\r
   2  * Amazon FreeRTOS POSIX V1.1.0\r
   3  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file utils.h\r
  28  * @brief Utility functions used by FreeRTOS+POSIX.\r
  29  */\r
  30 \r
  31 #ifndef _FREERTOS_POSIX_UTILS_\r
  32 #define _FREERTOS_POSIX_UTILS_\r
  33 \r
  34 /* C standard library includes. */\r
  35 #include <stdbool.h>\r
  36 #include <stdint.h>\r
  37 \r
  38 /* FreeRTOS+POSIX includes. */\r
  39 #include "FreeRTOS_POSIX/time.h"\r
  40 \r
  41 /**\r
  42  * @brief Calculates the length of pcString, up to xMaxLength.\r
  43  *\r
  44  * @param[in] pcString The string to find the length of.\r
  45  * @param[in] xMaxLength The limit when searching for the end of pcString.\r
  46  *\r
  47  * @return 0 if pcString is NULL; otherwise, the length of pcString or xMaxLength,\r
  48  * whichever is smaller.\r
  49  */\r
  50 size_t UTILS_strnlen( const char * const pcString,\r
  51                       size_t xMaxLength );\r
  52 \r
  53 /**\r
  54  * @brief Calculates the number of ticks between now and a given timespec.\r
  55  *\r
  56  * @param[in] pxAbsoluteTime A time in the future, specified as seconds and\r
  57  * nanoseconds since CLOCK_REALTIME's 0.\r
  58  * @param[in] pxCurrentTime current time, specified as seconds and\r
  59  * nanoseconds.\r
  60  * @param[out] pxResult Where the result of the conversion is stored. The result\r
  61  * is rounded up for fractional ticks.\r
  62  *\r
  63  * @return 0 on success. Otherwise, ETIMEDOUT if pxAbsoluteTime is in the past,\r
  64  * or EINVAL for invalid parameters.\r
  65  */\r
  66 int UTILS_AbsoluteTimespecToDeltaTicks( const struct timespec * const pxAbsoluteTime,\r
  67                                         const struct timespec * const pxCurrentTime,\r
  68                                         TickType_t * const pxResult );\r
  69 \r
  70 /**\r
  71  * @brief Converts a struct timespec to FreeRTOS ticks.\r
  72  *\r
  73  * @param[in] pxTimespec The timespec to convert.\r
  74  * @param[out] Where the result of the conversion is stored. The result is rounded\r
  75  * up for fractional ticks.\r
  76  *\r
  77  * @return 0 on success. Otherwise, EINVAL for invalid parameters.\r
  78  */\r
  79 int UTILS_TimespecToTicks( const struct timespec * const pxTimespec,\r
  80                            TickType_t * const pxResult );\r
  81 \r
  82 /**\r
  83  * @brief Converts an integer value to a timespec.\r
  84  *\r
  85  * @param[in] llSource The value to convert.\r
  86  * @param[out] pxDestination Where to store the converted value.\r
  87  *\r
  88  * @return No return value.\r
  89  */\r
  90 void UTILS_NanosecondsToTimespec( int64_t llSource,\r
  91                                   struct timespec * const pxDestination );\r
  92 \r
  93 /**\r
  94  * @brief Calculates pxResult = x + y.\r
  95  *\r
  96  * @param[in] x The first argument for addition.\r
  97  * @param[in] y The second argument for addition.\r
  98  * @param[out] pxResult Where the result of the calculation is stored.\r
  99  *\r
 100  * @return -1 if any argument was NULL; 1 if result is negative (overflow); otherwise, 0.\r
 101  */\r
 102 int UTILS_TimespecAdd( const struct timespec * const x,\r
 103                        const struct timespec * const y,\r
 104                        struct timespec * const pxResult );\r
 105 \r
 106 /**\r
 107  * @brief Calculates pxResult = x + ( struct timespec ) nanosec.\r
 108  *\r
 109  * @param[in] x The first argument for addition.\r
 110  * @param[in] llNanoseconds The second argument for addition.\r
 111  * @param[out] pxResult Where the result of the calculation is stored.\r
 112  *\r
 113  * @return -1 if pxResult or x was NULL; 1 if result is negative; otherwise, 0.\r
 114  */\r
 115 int UTILS_TimespecAddNanoseconds( const struct timespec * const x,\r
 116                                   int64_t llNanoseconds,\r
 117                                   struct timespec * const pxResult );\r
 118 \r
 119 /**\r
 120  * @brief Calculates pxResult = x - y. If the result is negative contents of\r
 121  * pResult are undefined\r
 122  *\r
 123  * @param[in] x The first argument for subtraction.\r
 124  * @param[in] y The second argument for subtraction.\r
 125  * @param[out] pxResult Where the result of the calculation is stored.\r
 126  *\r
 127  * @return -1 if any argument was NULL; 1 if result is negative; otherwise, 0.\r
 128  */\r
 129 int UTILS_TimespecSubtract( const struct timespec * const x,\r
 130                             const struct timespec * const y,\r
 131                             struct timespec * const pxResult );\r
 132 \r
 133 /**\r
 134  * @brief Compare  x == y.\r
 135  *\r
 136  * @param[in] x The first argument for comparison.\r
 137  * @param[in] y The second argument for comparison.\r
 138  *\r
 139  * @return 0 if x == y; 1 if x > y; -1 if x < y or any argument was NULL\r
 140  */\r
 141 int UTILS_TimespecCompare( const struct timespec * const x,\r
 142                            const struct timespec * const y );\r
 143 \r
 144 /**\r
 145  * @brief Checks that a timespec conforms to POSIX.\r
 146  *\r
 147  * A valid timespec must have 0 <= tv_nsec < 1000000000.\r
 148  *\r
 149  * @param[in] pxTimespec The timespec to validate.\r
 150  *\r
 151  * @return true if the pxTimespec is valid, false otherwise.\r
 152  */\r
 153 bool UTILS_ValidateTimespec( const struct timespec * const pxTimespec );\r
 154 \r
 155 #endif /* ifndef _FREERTOS_POSIX_UTILS_ */\r