ucs2-lib/inc/ucs_exc.h

   1 /*------------------------------------------------------------------------------------------------*/
   2 /* UNICENS V2.1.0-3491                                                                            */
   3 /* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG.                              */
   4 /*                                                                                                */
   5 /* This program is free software: you can redistribute it and/or modify                           */
   6 /* it under the terms of the GNU General Public License as published by                           */
   7 /* the Free Software Foundation, either version 2 of the License, or                              */
   8 /* (at your option) any later version.                                                            */
   9 /*                                                                                                */
  10 /* This program is distributed in the hope that it will be useful,                                */
  11 /* but WITHOUT ANY WARRANTY; without even the implied warranty of                                 */
  12 /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                                  */
  13 /* GNU General Public License for more details.                                                   */
  14 /*                                                                                                */
  15 /* You should have received a copy of the GNU General Public License                              */
  16 /* along with this program.  If not, see <http://www.gnu.org/licenses/>.                          */
  17 /*                                                                                                */
  18 /* You may also obtain this software under a propriety license from Microchip.                    */
  19 /* Please contact Microchip for further information.                                              */
  20 /*------------------------------------------------------------------------------------------------*/
  21
  22 /*!
  23  * \file
  24  * \brief Internal header file of class CExc.
  25  *
  26  * \cond UCS_INTERNAL_DOC
  27  * \addtogroup G_EXC
  28  * @{
  29  */
  30
  31 #ifndef UCS_EXC_H
  32 #define UCS_EXC_H
  33
  34 /*------------------------------------------------------------------------------------------------*/
  35 /* Includes                                                                                       */
  36 /*------------------------------------------------------------------------------------------------*/
  37 #include "ucs_inic_pb.h"
  38 #include "ucs_obs.h"
  39 #include "ucs_fsm.h"
  40 #include "ucs_dec.h"
  41 #include "ucs_base.h"
  42 #include "ucs_inic.h"
  43
  44
  45
  46 #ifdef __cplusplus
  47 extern "C"
  48 {
  49 #endif
  50
  51 /*------------------------------------------------------------------------------------------------*/
  52 /* Macros                                                                                         */
  53 /*------------------------------------------------------------------------------------------------*/
  54
  55
  56
  57 #define EXC_FID_HELLO               0x200U
  58 #define EXC_FID_WELCOME             0x201U
  59 #define EXC_FID_SIGNATURE           0x202U
  60 #define EXC_FID_DEVICE_INIT         0x203U
  61 #define EXC_FID_ENABLEPORT          0x210U
  62 #define EXC_FID_CABLE_LINK_DIAG     0x211U
  63 #define EXC_FID_PHY_LAY_TEST        0x220U
  64 #define EXC_FID_PHY_LAY_TEST_RES    0x221U
  65 #define EXC_FID_BC_DIAG             0x222U
  66 #define EXC_FID_BC_ENABLE_TX        0x223U
  67 #define EXC_FID_MEM_SESSION_OPEN    0x300U
  68 #define EXC_FID_MEM_SESSION_CLOSE   0x301U
  69 #define EXC_FID_MEMORY_READ         0x302U
  70 #define EXC_FID_MEMORY_WRITE        0x303U
  71
  72
  73
  74 #define EXC_WELCOME_SUCCESS              0U    /*!< \brief Welcome.Result reports success */
  75
  76
  77
  78
  79
  80
  81 /*------------------------------------------------------------------------------------------------*/
  82 /* Structures                                                                                     */
  83 /*------------------------------------------------------------------------------------------------*/
  84 /*! \brief Structure holds parameters for API locking */
  85 typedef struct Exc_ApiLock_
  86 {
  87     /*! \brief API locking instance for EXC functions */
  88     CApiLocking     api;
  89     /*! \brief Observer used for locking timeouts for EXC functions */
  90     CSingleObserver observer;
  91
  92 } Exc_ApiLock_t;
  93
  94 /*! \brief   Structure ExcSingleSubjects */
  95 typedef struct Exc_Ssubjects_
  96 {
  97     CSingleSubject hello;               /*!< \brief Subject for the Hello.Status and Hello.Error messages */
  98     CSingleSubject welcome;             /*!< \brief Subject for the Welcome.ResultAck and Welcome.ErrorAck messages */
  99     CSingleSubject signature;           /*!< \brief Subject for the Signature.Status and Signature.Error messages */
 100     CSingleSubject deviceinit;          /*!< \brief Subject for the DeviceInit.Error message */
 101     CSingleSubject enableport;          /*!< \brief Subject for the EnablePort.ResultAck  and EnablePort.ErrorAck messages */
 102     CSingleSubject cablelinkdiag;       /*!< \brief Subject for the CableLinkDiagnosis.ResultAck and CableLinkDiagnosis.ErrorAck messages */
 103     CSingleSubject phylaytest;          /*!< \brief Subject for the PhysicalLayerTestResult.Status and PhysicalLayerTest.Error messages */
 104     CSingleSubject phylaytestresult;    /*!< \brief Subject for the PhysicalLayerTestResult.Status and PhysicalLayerTestResult.Error messages */
 105     CSingleSubject memsessionopen;      /*!< \brief Subject for the MemorySessionOpen.Result and MemorySessionOpen.Error messages */
 106     CSingleSubject memsessionclose;     /*!< \brief Subject for the MemorySessionClose.Result and MemorySessionClose.Error messages */
 107     CSingleSubject memoryread;          /*!< \brief Subject for the MemoryRead.Result and MemoryRead.Error messages */
 108     CSingleSubject memorywrite;         /*!< \brief Subject for the MemoryWrite.Result and MemoryWrite.Error messages */
 109     CSingleSubject bcdiag;              /*!< \brief Subject for the BCdiag.Result and Error messages */
 110     CSingleSubject enabletx;            /*!< \brief Subject for the BC_EnableTx.Status and Error messages  */
 111 } Exc_Ssubjects_t;
 112
 113
 114
 115
 116 /*! \brief   Structure of class CExc. */
 117 typedef struct CExc_
 118 {
 119     /*! \brief pointer to the FktID/OPType list */
 120     Dec_FktOpIsh_t const *fkt_op_list_ptr;
 121
 122     /*! \brief Subjects for single-observer */
 123     Exc_Ssubjects_t       ssubs;
 124
 125     /*! \brief Parameters for API locking */
 126     Exc_ApiLock_t         lock;
 127
 128     /*! \brief Reference to base instance */
 129     CBase *base_ptr;
 130
 131     /*! \brief Reference to a Transceiver instance */
 132     CTransceiver         *xcvr_ptr;
 133
 134 } CExc;
 135
 136 /*! \brief   Structure used for returning method results/errors
 137  *
 138  *  Either the data_info or the error part of the structure contain the information.
 139  *  In case an error happened, data_info will be NULL. If no error happened,
 140  *  error.code is 0 and error.info is NULL.
 141 */
 142 typedef struct Exc_StdResult_
 143 {
 144     Ucs_StdResult_t  result;    /*!< \brief Result code and info byte stream */
 145     void            *data_info; /*!< \brief Reference to result values */
 146
 147 } Exc_StdResult_t;
 148
 149
 150 /*! \brief   This structure provides information on the Physical layer test result */
 151 typedef struct Exc_PhyTestResult_
 152 {
 153     uint8_t   port_number;      /*!< \brief Port Number */
 154     bool      lock_status;      /*!< \brief Lock status */
 155     uint16_t  err_count;        /*!< \brief Number of Coding Errors */
 156
 157 } Exc_PhyTestResult_t;
 158
 159
 160 /*! \brief  Result values of the BCDiag command*/
 161 typedef enum Exc_BCDiagResValue_
 162 {
 163     DUT_SLAVE       = 0x01U,     /*!< \brief Slave answered. No break on this segment. */
 164     DUT_MASTER      = 0x02U,     /*!< \brief TimingMaster answered: ring is closed. */
 165     DUT_NO_ANSWER   = 0x03U,     /*!< \brief Ring break found. */
 166     DUT_TIMEOUT     = 0x04U      /*!< \brief No answer on back channel */
 167
 168 } Exc_BCDiagResValue;
 169
 170 /*! \brief  Provides BackChannel Diagnosis result */
 171 typedef struct Exc_BCDiagResult_
 172 {
 173     Exc_BCDiagResValue  diag_result;
 174     uint16_t            admin_addr;
 175 } Exc_BCDiagResult;
 176
 177
 178 /*! \brief   This structure provides information on the Coax Diagnosis */
 179 typedef struct Exc_CableLinkDiagResult_
 180 {
 181     uint8_t  port_number;
 182     uint8_t  result;
 183
 184 } Exc_CableLinkDiagResult_t;
 185
 186
 187 /*! \brief   This structure provides information on the Hello.Status message */
 188 typedef struct Exc_HelloStatus_t_
 189 {
 190     uint8_t version;
 191     Ucs_Signature_t signature;
 192
 193 } Exc_HelloStatus_t;
 194
 195 /*! \brief   This structure provides information on the Welcome.Result message */
 196 typedef struct Exc_WelcomeResult_t_
 197 {
 198     uint8_t res;
 199     uint8_t version;
 200     Ucs_Signature_t signature;
 201
 202 } Exc_WelcomeResult_t;
 203
 204 /*! \brief   This structure provides information on the Signature.Status message */
 205 typedef struct Exc_SignatureStatus_t_
 206 {
 207     uint8_t version;
 208     Ucs_Signature_t signature;
 209
 210 } Exc_SignatureStatus_t;
 211
 212 /*! \brief   This structure provides information on the MemoryRead.Result message */
 213 typedef struct Exc_MemReadResult_
 214 {
 215     uint16_t session_handle;
 216     uint8_t  mem_id;
 217     uint32_t address;
 218     uint8_t  unit_len;
 219     uint8_t  unit_data[18];
 220
 221 } Exc_MemReadResult_t;
 222
 223 /*! \brief   This structure provides information on the MemoryWrite.Result message */
 224 typedef struct Exc_MemWriteResult_
 225 {
 226     uint16_t session_handle;
 227     uint8_t  mem_id;
 228
 229 } Exc_MemWriteResult_t;
 230
 231
 232 /*------------------------------------------------------------------------------------------------*/
 233 /* Prototypes                                                                                     */
 234 /*------------------------------------------------------------------------------------------------*/
 235 extern void Exc_Ctor(CExc *self, CBase *base_ptr, CTransceiver *rcm_ptr);
 236 extern void Exc_OnRcmRxFilter(void *self, Msg_MostTel_t *tel_ptr);
 237
 238 extern Ucs_Return_t Exc_Hello_Get(CExc *self,
 239                                   uint16_t target_address,
 240                                   uint8_t version_limit,
 241                                   CSingleObserver *obs_ptr);
 242 extern Ucs_Return_t Exc_Welcome_Sr(CExc *self,
 243                                    uint16_t target_address,
 244                                    uint16_t admin_node_address,
 245                                    uint8_t version,
 246                                    Ucs_Signature_t signature,
 247                                    CSingleObserver *obs_ptr);
 248 extern Ucs_Return_t Exc_Signature_Get(CExc *self,
 249                                       uint16_t target_address,
 250                                       uint8_t version_limit,
 251                                       CSingleObserver *obs_ptr);
 252 extern Ucs_Return_t Exc_DeviceInit_Start(CExc *self,
 253                                   uint16_t target_address,
 254                                   CSingleObserver *obs_ptr);
 255 extern Ucs_Return_t Exc_EnablePort_Sr(CExc *self,
 256                                       uint16_t target_address,
 257                                       uint8_t port_number,
 258                                       bool enabled,
 259                                       CSingleObserver *obs_ptr);
 260 extern Ucs_Return_t Exc_CableLinkDiagnosis_Start (CExc *self,
 261                                                   uint16_t target_address,
 262                                                   uint8_t port_number,
 263                                                   CSingleObserver *obs_ptr);
 264 extern Ucs_Return_t Exc_PhyTest_Start(CExc *self,
 265                                       uint8_t port_number,
 266                                       Ucs_Diag_PhyTest_Type_t type,
 267                                       uint16_t lead_in,
 268                                       uint32_t duration,
 269                                       uint16_t lead_out,
 270                                       CSingleObserver *obs_ptr);
 271 extern Ucs_Return_t  Exc_PhyTestResult_Get(CExc *self,
 272                                            CSingleObserver *obs_ptr);
 273 extern Ucs_Return_t Exc_BCDiag_Start(CExc *self,
 274                                      uint8_t position,
 275                                      uint16_t admin_na,
 276                                      uint16_t t_send,
 277                                      uint16_t t_wait4dut,
 278                                      uint16_t t_switch,
 279                                      uint16_t t_back,
 280                                      bool     autoback,
 281                                      CSingleObserver *obs_ptr);
 282 extern Ucs_Return_t Exc_BCEnableTx_StartResult(CExc *self,
 283                                                uint8_t port,
 284                                                CSingleObserver *obs_ptr);
 285 extern Ucs_Return_t Exc_MemSessionOpen_Sr(CExc *self,
 286                                           uint16_t target_address,
 287                                           uint8_t session_type,
 288                                           CSingleObserver *obs_ptr);
 289 extern Ucs_Return_t Exc_MemSessionClose_Sr(CExc *self,
 290                                            uint16_t target_address,
 291                                            uint16_t session_handle,
 292                                            CSingleObserver *obs_ptr);
 293 extern Ucs_Return_t Exc_MemoryRead_Sr(CExc *self,
 294                                       uint16_t target_address,
 295                                       uint16_t session_handle,
 296                                       uint8_t  mem_id,
 297                                       uint32_t address,
 298                                       uint8_t  unit_len,
 299                                       CSingleObserver *obs_ptr);
 300 extern Ucs_Return_t Exc_MemoryWrite_Sr(CExc *self,
 301                                        uint16_t target_address,
 302                                        uint16_t session_handle,
 303                                        uint8_t  mem_id,
 304                                        uint32_t address,
 305                                        uint8_t  unit_len,
 306                                        uint8_t  unit_data[],
 307                                        CSingleObserver *obs_ptr);
 308
 309 #ifdef __cplusplus
 310 }   /* extern "C" */
 311 #endif
 312
 313 #endif  /* #ifndef UCS_EXC_H */
 314
 315 /*!
 316  * @}
 317  * \endcond
 318  */
 319
 320 /*------------------------------------------------------------------------------------------------*/
 321 /* End of file                                                                                    */
 322 /*------------------------------------------------------------------------------------------------*/
 323