service/system/resource_manager/server/include/system_service/resm.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 /**
  17  * @file resm.h
  18  * @brief \~english This file contains declaration of APIs for resm library
  19  */
  20
  21 /** @addtogroup BaseSystem
  22  *  @{
  23  */
  24 /** @addtogroup system_service
  25  *  @ingroup BaseSystem
  26  *  @{
  27  */
  28 /** @addtogroup resource_manager
  29  *  @ingroup system_service
  30  *  @{
  31  */
  32
  33 #ifndef RESOURCE_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_RESM_H_
  34 #define RESOURCE_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_RESM_H_
  35
  36 #include "system_service/resm_type.h"
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 /////////////////////////////////////////////////////////////////////////////////////
  43 /// \ingroup RESM_Open
  44 /// \~english @par Summary
  45 ///      Opens the session with resource manager.
  46 /// \~english @param [in] p_prim
  47 ///       RESM_RSV_t* - Unused, NULL
  48 /// \~english @param [out] p_ssnId
  49 ///       uint32_t*  - Pointer to session ID
  50 /// \~english @par
  51 ///       RESM_RSV_t Variables
  52 /// \~english @code
  53 ///            #define RESM_RSV_t        int32_t
  54 ///            #define RESM_RSV_NULL     (0x00)  // NULL
  55 ///            @endcode
  56 /// \~english @retval RESM_E_OK Succeeded
  57 /// \~english @retval RESM_E_PAR %Parameter error
  58 /// \~english @retval RESM_E_NG Unexpected error
  59 /// \~english @par Preconditions
  60 ///       - Availability of ResourceManager must be TRUE.
  61 /// \~english @par Change of the internal state
  62 ///       - The internal state is not changed.
  63 /// \~english @par Causes of failures
  64 ///       - p_ssnId is NULL. [RESM_E_PAR]
  65 ///       - The global variable for getting RPC_ID of program (rpcId) is NULL. [RESM_E_NG]
  66 ///       - The area for RPC ID(rpcId) is not gotten. [RESM_E_NG]
  67 ///       - The number of the thread able to register in a process exceeds limit. [RESM_E_NG]
  68 ///       - It failed to get the area for thread information. [RESM_E_NG]
  69 ///       - It failed to get the area for ID information storage. [RESM_E_NG]
  70 ///       - It failed to generate the datagram socket for API request receiving. [RESM_E_NG]
  71 ///       - It failed to bind a socket. [RESM_E_NG]
  72 ///       - It failed to get a socket name. [RESM_E_NG]
  73 ///       - The number of sessions exceeds the maximum value. [RESM_E_NG]
  74 ///       - There is no space in the thread information area for event registration. [RESM_E_NG]
  75 ///       - It failed to get the thread information area for event registration. [RESM_E_NG]
  76 ///       - The file descriptor for getting an event is created. [RESM_E_NG]
  77 ///       - The generated session ID exists (EEXIST error at ioctl). [RESM_E_NG]
  78 ///       - Any error occurred during registering an event flag (EEXIST error at ioctl). [RESM_E_NG]
  79 ///       - Any error occurred during processing poling setting (error at ioctl). [RESM_E_NG]
  80 /// \~english @par Classification
  81 ///       Public
  82 /// \~english @par Type
  83 ///       None
  84 /// \~english @par Detail
  85 ///      Opens a session. \n
  86 ///      An application can use another API by using the gotten ssnID.
  87 /// \~english @see RESM_Close
  88 ////////////////////////////////////////////////////////////////////////////////////
  89 RESM_ERR_t RESM_Open(const RESM_RSV_t* p_prim, uint32_t* p_ssnld);
  90
  91 /////////////////////////////////////////////////////////////////////////////////////
  92 /// \ingroup RESM_Close
  93 /// \~english @par Summary
  94 ///     Closes the session with resource manager.
  95 /// \~english @param [in] ssnld
  96 ///       uint32_t  - Session ID
  97 /// \~english @retval RESM_E_OK Succeeded
  98 /// \~english @retval RESM_E_PAR %Parameter error
  99 /// \~english @par Preconditions
 100 ///       - An application must finish getting a session ID by RESM_Open().
 101 /// \~english @par Change of the internal state
 102 ///       - The internal state is not changed.
 103 /// \~english @par Causes of failures
 104 ///       - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
 105 ///       - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
 106 /// \~english @par Classification
 107 ///       Public
 108 /// \~english @par Type
 109 ///       None
 110 /// \~english @par Detail
 111 ///      Closes a session.
 112 /// \~english @see RESM_Open
 113 ////////////////////////////////////////////////////////////////////////////////////
 114 RESM_ERR_t RESM_Close(uint32_t ssnld);
 115
 116 /////////////////////////////////////////////////////////////////////////////////////
 117 /// \ingroup RESM_ReqEvent
 118 /// \~english @par Summary
 119 ///      Requests to issue an event.
 120 /// \~english @param [in] ssnld
 121 ///       uint32_t  - Session ID
 122 /// \~english @param [in] p_reqEvent
 123 ///       RESM_REQ_EVENT_t*  - Pointer to event
 124 /// \~english @par
 125 ///       RESM_REQ_EVENT_t Structure
 126 /// \~english @code
 127 ///            typedef struct {
 128 ///                RESM_EV_t reqEvent;          /* Event flag necessary to report */
 129 ///                struct {
 130 ///                    uint32_t restMemThresh;  /* Threshold of the remaining capacity of system memory */
 131 ///                } prm;
 132 ///            }RESM_REQ_EVENT_t;
 133 ///            @endcode
 134 /// \~english @par
 135 ///       RESM_EV_t Variables
 136 /// \~english @code
 137 ///            #define RESM_EV_t           uint32_t
 138 ///            #define RESM_EV_NOP         (0x00)
 139 ///            #define RESM_EV_MEM         (0x01)
 140 ///            #define RESM_EV_NAND_STATUS (0x02)
 141 ///            @endcode
 142 /// \~english @par
 143 ///       - RESM_EV_NOP : No event notification
 144 ///       - RESM_EV_MEM : Event notification for memory
 145 ///       - RESM_EV_NAND_STATUS : Eventnotification for NAND state
 146 /// \~english @par
 147 ///       Notes
 148 ///       - restMemThresh is valid only when RESM_EV_MEM is set to reqEvent. \n
 149 ///         ResourceManager issues RESM_EV_MEM event at the timing
 150 ///         when the remaining capacity of system memory fell below the value (unit is BYTE)
 151 ///         which an application specifies.
 152 /// \~english @retval RESM_E_OK Succeeded
 153 /// \~english @retval RESM_E_PAR %Parameter error
 154 /// \~english @par Preconditions
 155 ///       - An application must finish getting a session ID by RESM_Open().
 156 /// \~english @par Change of the internal state
 157 ///       - The internal state is not changed.
 158 /// \~english @par Causes of failures
 159 ///       - p_reqEvent is NULL. [RESM_E_PAR]
 160 ///       - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
 161 ///       - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
 162 /// \~english @par Classification
 163 ///       Public
 164 /// \~english @par Type
 165 ///       None
 166 /// \~english @par Detail
 167 ///      Requests to issue an event.
 168 ///      This API is called from the RPC library.
 169 /// \~english @see RESM_GetEvent
 170 ////////////////////////////////////////////////////////////////////////////////////
 171 RESM_ERR_t RESM_ReqEvent(uint32_t ssnld, const RESM_REQ_EVENT_t* p_reqEvent);
 172
 173 /////////////////////////////////////////////////////////////////////////////////////
 174 /// \ingroup RESM_GetEventFd
 175 /// \~english @par Summary
 176 ///      Gets FD of the event to receive from resource manager.
 177 /// \~english @param [in] ssnld
 178 ///       uint32_t - Session ID
 179 /// \~english @param [out] p_fd
 180 ///       int*  - Pointer to file descriptor
 181 /// \~english @retval RESM_E_OK Succeeded
 182 /// \~english @retval RESM_E_PAR %Parameter error
 183 /// \~english @retval RESM_E_NG Unexpected error
 184 /// \~english @par Preconditions
 185 ///       - An application must finish getting a session ID by RESM_Open().
 186 /// \~english @par Change of the internal state
 187 ///       - The internal state is not changed.
 188 /// \~english @par Causes of failures
 189 ///       - p_fd is NULL. [RESM_E_PAR]
 190 ///       - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
 191 ///       - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
 192 ///       - ssnId rewrites bit for an event flag decision by invalid values. [RESM_E_NG]
 193 ///       - The file descriptor corresponding to ssnId is not found. [RESM_E_NG]
 194 /// \~english @par Classification
 195 ///       Public
 196 /// \~english @par Type
 197 ///       None
 198 /// \~english @par Detail
 199 ///      Gets FD of the event to receive from resource manager. \n
 200 ///      An application can do simultaneous wait of other events with the event of ResourceManager
 201 ///      by oversighting the gotten FD by select,poll etc.
 202 /// \~english @see None
 203 ////////////////////////////////////////////////////////////////////////////////////
 204 RESM_ERR_t RESM_GetEventFd(uint32_t ssnld, int* p_fd);
 205
 206 /////////////////////////////////////////////////////////////////////////////////////
 207 /// \ingroup RESM_GetEvent
 208 /// \~english @par Summary
 209 ///      Gets the event from resource manager.
 210 /// \~english @param [in] ssnld
 211 ///       uint32_t - Session ID
 212 /// \~english @param [out] p_evFlag
 213 ///       RESM_EV_t*  - Pointer to event
 214 /// \~english @par
 215 ///       RESM_EV_t Variables
 216 /// \~english @code
 217 ///            #define RESM_EV_t           uint32_t
 218 ///            #define RESM_EV_NOP         (0x00)
 219 ///            #define RESM_EV_MEM         (0x01)
 220 ///            #define RESM_EV_NAND_STATUS (0x02)
 221 ///            @endcode
 222 /// \~english @par
 223 ///       - RESM_EV_NOP : No event notification
 224 ///       - RESM_EV_MEM : Event notification for memory
 225 ///       - RESM_EV_NAND_STATUS : Event notification for NAND state
 226 /// \~english @retval RESM_E_OK Succeeded
 227 /// \~english @retval RESM_E_PAR %Parameter error
 228 /// \~english @retval RESM_E_NG Unexpected error
 229 /// \~english @par Preconditions
 230 ///       - An application must finish getting a session ID by RESM_Open().
 231 /// \~english @par Change of the internal state
 232 ///       - The internal state is not changed.
 233 /// \~english @par Causes of failures
 234 ///       - p_evFlag is NULL. [RESM_E_PAR]
 235 ///       - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
 236 ///       - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
 237 ///       - ssnId rewrites bit for an event flag decision by invalid values. [RESM_E_NG]
 238 ///       - The file descriptor corresponding to ssnId is not found. [RESM_E_NG]
 239 ///       - The flag of ssnId is not registered. (The returned value of ioctl is EOENT.) [RESM_E_NG]
 240 ///       - Any interruption occurred during getting an event. (The returned value of ioctl is EINTR.) [RESM_E_NG]
 241 ///       - Any error occurred during getting an event. (The returned value of ioctl is the error value
 242 ///         except for EOENT and EINTR.) [RESM_E_NG]
 243 /// \~english @par Classification
 244 ///       Public
 245 /// \~english @par Type
 246 ///       None
 247 /// \~english @par Detail
 248 ///      When an event flag is not set, this is blocked. \n
 249 ///      If an event flag is set, this stores event contents to p_evFlag and this ends. \n
 250 ///      If this ends, it clears all of event flags.
 251 /// \~english @see RESM_ReqEvent
 252 ////////////////////////////////////////////////////////////////////////////////////
 253 RESM_ERR_t RESM_GetEvent(uint32_t ssnld, RESM_EV_t* p_evFlag);
 254
 255 /////////////////////////////////////////////////////////////////////////////////////
 256 /// \ingroup RESM_GetStatus
 257 /// \~english @par Summary
 258 ///      Gets system state.
 259 /// \~english @param [in] ssnld
 260 ///       uint32_t - Session ID
 261 /// \~english @param [out] p_status
 262 ///       RESM_STATUS_t*  - Pointer to system state
 263 /// \~english @par
 264 ///       RESM_STATUS_t Structure
 265 /// \~english @code
 266 ///            typedef struct {
 267 ///                uint32_t restMemSize;                       /* Remaining memory length (KB)                       */
 268 ///                RESM_NAND_WRITE_STATUS_t  nandWriteStatus;  /* Access permission / Prohibition state to NAND flash */
 269 ///                RESM_INET_STATUS_t        inetStatus;       /* Network IF statistical information after start    */
 270 ///            } RESM_STATUS_t;
 271 ///            @endcode
 272 /// \~english @par
 273 ///       enum RESM_NAND_WRITE_STATUS_t Variables
 274 ///       - RESM_NAND_WRITE_ENABLE : NAND access permission
 275 ///       - RESM_NAND_WRITE_DISABLE : NAND access prohibition
 276 /// \~english @par
 277 ///       Notes
 278 ///       - When system records in NAND flash and it influences the lifetime of a device,
 279 ///         STATUS(nandWriteStatus) becomes RESM_NAND_WRITE_DISABLE. It is not in the state where WRITE fails. \n
 280 /// \~english @par
 281 ///       RESM_INET_STATUS_t Structure
 282 /// \~english @code
 283 ///            typedef struct {
 284 ///                uint32_t ifNum;                    /* Valid array at the number of interface and ifInfo */
 285 ///                struct {
 286 ///                    char    name[64];              /* Interface name                             */
 287 ///                    uint64_t  rxSize;              /* Receiving data length (KiB)                   */
 288 ///                    uint64_t  txSize;              /* Transmission data length (KiB)                */
 289 ///                    uint8_t   hwaddr[HWADDR_LEN];  /* Hardware address (MAC address)         */
 290 ///                } ifInfo[RESM_INET_IF_MAX];
 291 ///            }RESM_INET_STATUS_t;
 292 ///            @endcode
 293 /// \~english @retval RESM_E_OK Succeeded
 294 /// \~english @retval RESM_E_PAR %Parameter error
 295 /// \~english @retval RESM_E_NG Unexpected error
 296 /// \~english @par Preconditions
 297 ///       - An application must finish getting a session ID by RESM_Open().
 298 /// \~english @par Change of the internal state
 299 ///       - The internal state is not changed.
 300 /// \~english @par Causes of failures
 301 ///       - p_evFlag is NULL. [RESM_E_PAR]
 302 ///       - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
 303 ///       - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
 304 ///       - It failed to open the device file for network. [RESM_E_NG]
 305 ///       - The number of the gotten network IF is 0. [RESM_E_NG]
 306 /// \~english @par Classification
 307 ///       Public
 308 /// \~english @par Type
 309 ///       None
 310 /// \~english @par Detail
 311 ///      Gets system state.
 312 ///      This API is called from the RPC library.
 313 /// \~english @see None
 314 ////////////////////////////////////////////////////////////////////////////////////
 315 RESM_ERR_t RESM_GetStatus(uint32_t ssnld, RESM_STATUS_t* p_status);
 316
 317 #ifdef __cplusplus
 318 }
 319 #endif
 320
 321 #endif  // RESOURCE_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_RESM_H_
 322
 323 /** @}*/  // end of ResourceManager
 324 /** @}*/  // end of SystemService
 325 /** @}*/  // end of BaseSystem