summaryrefslogtreecommitdiffstats
path: root/ucs2-lib/inc/ucs_nsm.h
blob: 7c2be23a3323f21c23c836162c29d18fe07a0cf1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
/*------------------------------------------------------------------------------------------------*/
/* UNICENS V2.1.0-3491                                                                            */
/* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG.                              */
/*                                                                                                */
/* This program is free software: you can redistribute it and/or modify                           */
/* it under the terms of the GNU General Public License as published by                           */
/* the Free Software Foundation, either version 2 of the License, or                              */
/* (at your option) any later version.                                                            */
/*                                                                                                */
/* This program is distributed in the hope that it will be useful,                                */
/* but WITHOUT ANY WARRANTY; without even the implied warranty of                                 */
/* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                                  */
/* GNU General Public License for more details.                                                   */
/*                                                                                                */
/* You should have received a copy of the GNU General Public License                              */
/* along with this program.  If not, see <http://www.gnu.org/licenses/>.                          */
/*                                                                                                */
/* You may also obtain this software under a propriety license from Microchip.                    */
/* Please contact Microchip for further information.                                              */
/*------------------------------------------------------------------------------------------------*/

/*!
 * \file
 * \brief Internal header file of the Node Scripting Management.
 *
 * \cond UCS_INTERNAL_DOC
 * \addtogroup G_NSM
 * @{
 */
#ifndef UCS_NSM_H
#define UCS_NSM_H

/*------------------------------------------------------------------------------------------------*/
/* Includes                                                                                       */
/*------------------------------------------------------------------------------------------------*/
#include "ucs_base.h"
#include "ucs_ret_pb.h"
#include "ucs_rsm.h"
#include "ucs_nsm_pb.h"

#ifdef __cplusplus
extern "C"
{
#endif

/*------------------------------------------------------------------------------------------------*/
/* Enumerators                                                                                    */
/*------------------------------------------------------------------------------------------------*/
/*! \brief This enumerator specifies the kind of result - Target or Transmission. */
typedef enum Ns_ResultType_
{
    /*!< \brief Specifies the result of the scripting from target device (typically INIC function-specific error) */
    NS_RESULT_TYPE_TGT_SCRIPT  = 0x00U,
    /*!< \brief Specifies the result of the remote synchronization from target device (typically INIC function-specific error) */
    NS_RESULT_TYPE_TGT_SYNC    = 0x01U,
    /*!< \brief Specifies the transmission error information that occurred on the MOST network. */
    NS_RESULT_TYPE_TX          = 0x02U      

} Ns_ResultType_t;

/*------------------------------------------------------------------------------------------------*/
/* Structures                                                                                     */
/*------------------------------------------------------------------------------------------------*/
/*! \brief Detailed information used for I2C results. */
typedef struct Nsm_ResultDetails_
{
    /*! \brief Specifies the type of the current asynchronous result.
     *  \details The following briefly describes the different types of results available:
     *              - \b NS_RESULT_TYPE_TGT: target results, typically INIC function-specific error found on target device. \n Refer to \em inic_result to get the detailed information.
     *              - \b NS_RESULT_TYPE_TX:  transmission results, typically transmission error on the MOST network. \n Refer to \em tx_result to get the transmission information.
     */
    Ns_ResultType_t result_type;
    /*! \brief Holds the status of the transmission. */
    Ucs_MsgTxStatus_t tx_result;
    /*! \brief Holds the results of the target device. */
    Ucs_StdResult_t inic_result;

} Nsm_ResultDetails_t;
    
/*! \brief  Stores the NodeScript result for internal use. */
typedef struct Nsm_Result_
{
    /*! \brief Result code. */
    Ucs_Ns_ResultCode_t code;  
    /*! \brief Detailed information on the returned result. */
    Nsm_ResultDetails_t details;

} Nsm_Result_t;

/*! \brief  Stores data required by NSM during initialization. */
typedef struct Nsm_InitData_
{
    CBase *base_ptr;                    /*!< \brief Reference to base instance */
    CTransceiver * rcm_ptr;             /*!< \brief Reference to RCM transceiver instance */
    CRemoteSyncManagement * rsm_ptr;    /*!< \brief Reference to RSM instance */

} Nsm_InitData_t;

/*! \brief Structure holds parameters for API locking */
typedef struct Script_ApiLock_
{
    /*! \brief Flag to lock the API */
    bool api;
    /*! \brief API locking instance for Scripting function */
    CApiLocking     rcm_api;
    /*! \brief Observer used for locking timeouts for Scripting function */
    CSingleObserver observer;

} Script_ApiLock_t;

/*------------------------------------------------------------------------------------------------*/
/* Type definitions                                                                               */
/*------------------------------------------------------------------------------------------------*/
/*! \brief  Function signature used for the results of the Scripting Manager.
 *  \param  user_ptr     Reference to the called user instance.
 *  \param  result       Result of the scripting operation.
 */
typedef void (*Nsm_ResultCb_t)(void * user_ptr, Nsm_Result_t result);

/*! \brief  Function signature used for the results of the Scripting Manager.
 *  \param  tel_ptr          Reference to the message object.
 *  \param  user_ptr         Reference to the user argument.
 *  \return  Returns \c true to discard the message and free it to the pool (no-pass). Otherwise, returns 
 *           \c false (pass).
 */
typedef bool (*Nsm_RxFilterCb_t)(Msg_MostTel_t *tel_ptr, void *user_ptr);

/*------------------------------------------------------------------------------------------------*/
/* Structures                                                                                     */
/*------------------------------------------------------------------------------------------------*/
/*! \brief  Class structure of the Node Scripting Management. */
typedef struct CNodeScriptManagement_
{
    /*!< \brief Reference to a base instance */
    CBase *base_ptr;
    /*!< \brief Reference to RCM instance */
    CTransceiver * rcm_ptr;
    /*!< \brief Reference to RSM instance */
    CRemoteSyncManagement * rsm_ptr;
    /*!< \brief Reference to the timer management */ 
    CTimerManagement * tm_ptr;
    /*!< \brief Timer for pausing script */
    CTimer script_pause;
    /*!< \brief Service instance for the scheduler */
    CService nsm_srv;
    /*!< \brief Observer used to monitor UCS initialization result */
    CMaskedObserver ucsinit_observer;
    /*!< \brief Observer used to monitor UCS termination event */
    CMaskedObserver ucstermination_observer;
    /*!< \brief Flag to lock the API */
    Script_ApiLock_t lock;
    /*!< \brief Current reference to the script table */
    Ucs_Ns_Script_t * curr_sript_ptr;
    /*!< \brief Current result for internal use */
    Nsm_Result_t curr_internal_result;
    /*!< \brief Current script size */
    uint8_t curr_sript_size;
    /*!< \brief Current script pause */
    uint16_t curr_pause;
    /*!< \brief Flag to determine whether the private api is used or not */
    bool is_private_api_used;
    /*!< \brief Reference to the user instance */
    void * curr_user_ptr;
    /*!< \brief RX filter callback function */
    Nsm_RxFilterCb_t curr_rxfilter_fptr;
    /*!< \brief Private result callback function pointer for current script */
    Nsm_ResultCb_t curr_pv_result_fptr;
    /*!< \brief Current reference to the Node used in public API */
    Ucs_Rm_Node_t * curr_node_ptr;
    /*!< \brief Public result callback function pointer for current script */
    Ucs_Ns_ResultCb_t curr_pb_result_fptr;
    /*!< \brief Target address of the device to be looked for */
    uint16_t target_address;

} CNodeScriptManagement;

/*------------------------------------------------------------------------------------------------*/
/* Prototypes of class CRemoteSyncManagement                                                      */
/*------------------------------------------------------------------------------------------------*/
extern void Nsm_Ctor(CNodeScriptManagement * self, Nsm_InitData_t * init_ptr);
extern Ucs_Return_t Nsm_Run_Pb(CNodeScriptManagement * self, Ucs_Rm_Node_t * node_ptr, Ucs_Ns_ResultCb_t pb_result_fptr);
extern Ucs_Return_t Nsm_Run_Pv(CNodeScriptManagement * self, Ucs_Ns_Script_t * script, uint8_t size, void * user_ptr, Nsm_RxFilterCb_t rx_filter_fptr, Nsm_ResultCb_t result_fptr);
extern bool Nsm_OnRcmRxFilter(void *self, Msg_MostTel_t *tel_ptr);
extern bool Nsm_IsLocked(CNodeScriptManagement * self);

#ifdef __cplusplus
}   /* extern "C" */
#endif

#endif /* #ifndef UCS_NSM_H */

/*!
 * @}
 * \endcond
 */

/*------------------------------------------------------------------------------------------------*/
/* End of file                                                                                    */
/*------------------------------------------------------------------------------------------------*/