--- /dev/null
+/*
+ * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @file resm.h
+ * @brief \~english This file contains declaration of APIs for resm library
+ */
+
+/** @addtogroup BaseSystem
+ * @{
+ */
+/** @addtogroup system_service
+ * @ingroup BaseSystem
+ * @{
+ */
+/** @addtogroup resource_manager
+ * @ingroup system_service
+ * @{
+ */
+
+#ifndef RESOURCE_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_RESM_H_
+#define RESOURCE_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_RESM_H_
+
+#include "system_service/resm_type.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/////////////////////////////////////////////////////////////////////////////////////
+/// \ingroup RESM_Open
+/// \~english @par Summary
+/// Opens the session with resource manager.
+/// \~english @param [in] p_prim
+/// RESM_RSV_t* - Unused, NULL
+/// \~english @param [out] p_ssnId
+/// uint32_t* - Pointer to session ID
+/// \~english @par
+/// RESM_RSV_t Variables
+/// \~english @code
+/// #define RESM_RSV_t int32_t
+/// #define RESM_RSV_NULL (0x00) // NULL
+/// @endcode
+/// \~english @retval RESM_E_OK Succeeded
+/// \~english @retval RESM_E_PAR %Parameter error
+/// \~english @retval RESM_E_NG Unexpected error
+/// \~english @par Preconditions
+/// - Availability of ResourceManager must be TRUE.
+/// \~english @par Change of the internal state
+/// - The internal state is not changed.
+/// \~english @par Causes of failures
+/// - p_ssnId is NULL. [RESM_E_PAR]
+/// - The global variable for getting RPC_ID of program (rpcId) is NULL. [RESM_E_NG]
+/// - The area for RPC ID(rpcId) is not gotten. [RESM_E_NG]
+/// - The number of the thread able to register in a process exceeds limit. [RESM_E_NG]
+/// - It failed to get the area for thread information. [RESM_E_NG]
+/// - It failed to get the area for ID information storage. [RESM_E_NG]
+/// - It failed to generate the datagram socket for API request receiving. [RESM_E_NG]
+/// - It failed to bind a socket. [RESM_E_NG]
+/// - It failed to get a socket name. [RESM_E_NG]
+/// - The number of sessions exceeds the maximum value. [RESM_E_NG]
+/// - There is no space in the thread information area for event registration. [RESM_E_NG]
+/// - It failed to get the thread information area for event registration. [RESM_E_NG]
+/// - The file descriptor for getting an event is created. [RESM_E_NG]
+/// - The generated session ID exists (EEXIST error at ioctl). [RESM_E_NG]
+/// - Any error occurred during registering an event flag (EEXIST error at ioctl). [RESM_E_NG]
+/// - Any error occurred during processing poling setting (error at ioctl). [RESM_E_NG]
+/// \~english @par Classification
+/// Public
+/// \~english @par Type
+/// None
+/// \~english @par Detail
+/// Opens a session. \n
+/// An application can use another API by using the gotten ssnID.
+/// \~english @see RESM_Close
+////////////////////////////////////////////////////////////////////////////////////
+RESM_ERR_t RESM_Open(const RESM_RSV_t* p_prim, uint32_t* p_ssnld);
+
+/////////////////////////////////////////////////////////////////////////////////////
+/// \ingroup RESM_Close
+/// \~english @par Summary
+/// Closes the session with resource manager.
+/// \~english @param [in] ssnld
+/// uint32_t - Session ID
+/// \~english @retval RESM_E_OK Succeeded
+/// \~english @retval RESM_E_PAR %Parameter error
+/// \~english @par Preconditions
+/// - An application must finish getting a session ID by RESM_Open().
+/// \~english @par Change of the internal state
+/// - The internal state is not changed.
+/// \~english @par Causes of failures
+/// - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
+/// - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
+/// \~english @par Classification
+/// Public
+/// \~english @par Type
+/// None
+/// \~english @par Detail
+/// Closes a session.
+/// \~english @see RESM_Open
+////////////////////////////////////////////////////////////////////////////////////
+RESM_ERR_t RESM_Close(uint32_t ssnld);
+
+/////////////////////////////////////////////////////////////////////////////////////
+/// \ingroup RESM_ReqEvent
+/// \~english @par Summary
+/// Requests to issue an event.
+/// \~english @param [in] ssnld
+/// uint32_t - Session ID
+/// \~english @param [in] p_reqEvent
+/// RESM_REQ_EVENT_t* - Pointer to event
+/// \~english @par
+/// RESM_REQ_EVENT_t Structure
+/// \~english @code
+/// typedef struct {
+/// RESM_EV_t reqEvent; /* Event flag necessary to report */
+/// struct {
+/// uint32_t restMemThresh; /* Threshold of the remaining capacity of system memory */
+/// } prm;
+/// }RESM_REQ_EVENT_t;
+/// @endcode
+/// \~english @par
+/// RESM_EV_t Variables
+/// \~english @code
+/// #define RESM_EV_t uint32_t
+/// #define RESM_EV_NOP (0x00)
+/// #define RESM_EV_MEM (0x01)
+/// #define RESM_EV_NAND_STATUS (0x02)
+/// @endcode
+/// \~english @par
+/// - RESM_EV_NOP : No event notification
+/// - RESM_EV_MEM : Event notification for memory
+/// - RESM_EV_NAND_STATUS : Eventnotification for NAND state
+/// \~english @par
+/// Notes
+/// - restMemThresh is valid only when RESM_EV_MEM is set to reqEvent. \n
+/// ResourceManager issues RESM_EV_MEM event at the timing
+/// when the remaining capacity of system memory fell below the value (unit is BYTE)
+/// which an application specifies.
+/// \~english @retval RESM_E_OK Succeeded
+/// \~english @retval RESM_E_PAR %Parameter error
+/// \~english @par Preconditions
+/// - An application must finish getting a session ID by RESM_Open().
+/// \~english @par Change of the internal state
+/// - The internal state is not changed.
+/// \~english @par Causes of failures
+/// - p_reqEvent is NULL. [RESM_E_PAR]
+/// - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
+/// - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
+/// \~english @par Classification
+/// Public
+/// \~english @par Type
+/// None
+/// \~english @par Detail
+/// Requests to issue an event.
+/// This API is called from the RPC library.
+/// \~english @see RESM_GetEvent
+////////////////////////////////////////////////////////////////////////////////////
+RESM_ERR_t RESM_ReqEvent(uint32_t ssnld, const RESM_REQ_EVENT_t* p_reqEvent);
+
+/////////////////////////////////////////////////////////////////////////////////////
+/// \ingroup RESM_GetEventFd
+/// \~english @par Summary
+/// Gets FD of the event to receive from resource manager.
+/// \~english @param [in] ssnld
+/// uint32_t - Session ID
+/// \~english @param [out] p_fd
+/// int* - Pointer to file descriptor
+/// \~english @retval RESM_E_OK Succeeded
+/// \~english @retval RESM_E_PAR %Parameter error
+/// \~english @retval RESM_E_NG Unexpected error
+/// \~english @par Preconditions
+/// - An application must finish getting a session ID by RESM_Open().
+/// \~english @par Change of the internal state
+/// - The internal state is not changed.
+/// \~english @par Causes of failures
+/// - p_fd is NULL. [RESM_E_PAR]
+/// - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
+/// - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
+/// - ssnId rewrites bit for an event flag decision by invalid values. [RESM_E_NG]
+/// - The file descriptor corresponding to ssnId is not found. [RESM_E_NG]
+/// \~english @par Classification
+/// Public
+/// \~english @par Type
+/// None
+/// \~english @par Detail
+/// Gets FD of the event to receive from resource manager. \n
+/// An application can do simultaneous wait of other events with the event of ResourceManager
+/// by oversighting the gotten FD by select,poll etc.
+/// \~english @see None
+////////////////////////////////////////////////////////////////////////////////////
+RESM_ERR_t RESM_GetEventFd(uint32_t ssnld, int* p_fd);
+
+/////////////////////////////////////////////////////////////////////////////////////
+/// \ingroup RESM_GetEvent
+/// \~english @par Summary
+/// Gets the event from resource manager.
+/// \~english @param [in] ssnld
+/// uint32_t - Session ID
+/// \~english @param [out] p_evFlag
+/// RESM_EV_t* - Pointer to event
+/// \~english @par
+/// RESM_EV_t Variables
+/// \~english @code
+/// #define RESM_EV_t uint32_t
+/// #define RESM_EV_NOP (0x00)
+/// #define RESM_EV_MEM (0x01)
+/// #define RESM_EV_NAND_STATUS (0x02)
+/// @endcode
+/// \~english @par
+/// - RESM_EV_NOP : No event notification
+/// - RESM_EV_MEM : Event notification for memory
+/// - RESM_EV_NAND_STATUS : Event notification for NAND state
+/// \~english @retval RESM_E_OK Succeeded
+/// \~english @retval RESM_E_PAR %Parameter error
+/// \~english @retval RESM_E_NG Unexpected error
+/// \~english @par Preconditions
+/// - An application must finish getting a session ID by RESM_Open().
+/// \~english @par Change of the internal state
+/// - The internal state is not changed.
+/// \~english @par Causes of failures
+/// - p_evFlag is NULL. [RESM_E_PAR]
+/// - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
+/// - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
+/// - ssnId rewrites bit for an event flag decision by invalid values. [RESM_E_NG]
+/// - The file descriptor corresponding to ssnId is not found. [RESM_E_NG]
+/// - The flag of ssnId is not registered. (The returned value of ioctl is EOENT.) [RESM_E_NG]
+/// - Any interruption occurred during getting an event. (The returned value of ioctl is EINTR.) [RESM_E_NG]
+/// - Any error occurred during getting an event. (The returned value of ioctl is the error value
+/// except for EOENT and EINTR.) [RESM_E_NG]
+/// \~english @par Classification
+/// Public
+/// \~english @par Type
+/// None
+/// \~english @par Detail
+/// When an event flag is not set, this is blocked. \n
+/// If an event flag is set, this stores event contents to p_evFlag and this ends. \n
+/// If this ends, it clears all of event flags.
+/// \~english @see RESM_ReqEvent
+////////////////////////////////////////////////////////////////////////////////////
+RESM_ERR_t RESM_GetEvent(uint32_t ssnld, RESM_EV_t* p_evFlag);
+
+/////////////////////////////////////////////////////////////////////////////////////
+/// \ingroup RESM_GetStatus
+/// \~english @par Summary
+/// Gets system state.
+/// \~english @param [in] ssnld
+/// uint32_t - Session ID
+/// \~english @param [out] p_status
+/// RESM_STATUS_t* - Pointer to system state
+/// \~english @par
+/// RESM_STATUS_t Structure
+/// \~english @code
+/// typedef struct {
+/// uint32_t restMemSize; /* Remaining memory length (KB) */
+/// RESM_NAND_WRITE_STATUS_t nandWriteStatus; /* Access permission / Prohibition state to NAND flash */
+/// RESM_INET_STATUS_t inetStatus; /* Network IF statistical information after start */
+/// } RESM_STATUS_t;
+/// @endcode
+/// \~english @par
+/// enum RESM_NAND_WRITE_STATUS_t Variables
+/// - RESM_NAND_WRITE_ENABLE : NAND access permission
+/// - RESM_NAND_WRITE_DISABLE : NAND access prohibition
+/// \~english @par
+/// Notes
+/// - When system records in NAND flash and it influences the lifetime of a device,
+/// STATUS(nandWriteStatus) becomes RESM_NAND_WRITE_DISABLE. It is not in the state where WRITE fails. \n
+/// \~english @par
+/// RESM_INET_STATUS_t Structure
+/// \~english @code
+/// typedef struct {
+/// uint32_t ifNum; /* Valid array at the number of interface and ifInfo */
+/// struct {
+/// char name[64]; /* Interface name */
+/// uint64_t rxSize; /* Receiving data length (KiB) */
+/// uint64_t txSize; /* Transmission data length (KiB) */
+/// uint8_t hwaddr[HWADDR_LEN]; /* Hardware address (MAC address) */
+/// } ifInfo[RESM_INET_IF_MAX];
+/// }RESM_INET_STATUS_t;
+/// @endcode
+/// \~english @retval RESM_E_OK Succeeded
+/// \~english @retval RESM_E_PAR %Parameter error
+/// \~english @retval RESM_E_NG Unexpected error
+/// \~english @par Preconditions
+/// - An application must finish getting a session ID by RESM_Open().
+/// \~english @par Change of the internal state
+/// - The internal state is not changed.
+/// \~english @par Causes of failures
+/// - p_evFlag is NULL. [RESM_E_PAR]
+/// - ssnId exceeds the maximum value (EV_MAX_IDS_IN_THREAD). [RESM_E_PAR]
+/// - The in-use flag of a global variable (g_resmgr.ssnInfo[ssnId].useFlag) is FALSE. [RESM_E_PAR]
+/// - It failed to open the device file for network. [RESM_E_NG]
+/// - The number of the gotten network IF is 0. [RESM_E_NG]
+/// \~english @par Classification
+/// Public
+/// \~english @par Type
+/// None
+/// \~english @par Detail
+/// Gets system state.
+/// This API is called from the RPC library.
+/// \~english @see None
+////////////////////////////////////////////////////////////////////////////////////
+RESM_ERR_t RESM_GetStatus(uint32_t ssnld, RESM_STATUS_t* p_status);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // RESOURCE_MANAGER_SERVER_INCLUDE_SYSTEM_SERVICE_RESM_H_
+
+/** @}*/ // end of ResourceManager
+/** @}*/ // end of SystemService
+/** @}*/ // end of BaseSystem
Code Review / staging / basesystem.git / blobdiff