video_in_hal/can_hal/hal_api/can_hal.h

   1 /*
   2  * @copyright Copyright (c) 2017-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 #ifndef HAL_API_CAN_HAL_H_
  17 #define HAL_API_CAN_HAL_H_
  18 /**
  19  * @file can_hal.h
  20  */
  21
  22 /** @addtogroup communication
  23  *  @{
  24  */
  25 /** @addtogroup can_hal
  26  *  @ingroup communication
  27  *  @{
  28  */
  29
  30 #include <native_service/frameworkunified_types.h>
  31 #include <string>
  32
  33 /**
  34  * \~english Max data length of nomarl can send
  35  */
  36 #define CAN_NORMAL_MESSAGE_LEN (8)
  37
  38 /**
  39  * \~english Maximum data length
  40  */
  41 #define CAN_MESSAGE_LEN (2048)
  42
  43 /**
  44  * \~english  Maximum CAN_ID data length
  45  */
  46 #define CAN_NUM_MAX (125)
  47
  48 /**
  49  * l_eStatus = FrameworkUnifiedAttachCallbackToDispatcher(hApp, FRAMEWORKUNIFIED_ANY_SOURCE, CID_CANHAL_CMD_CAN_SEND_STATUS, CANHalSndStsProcess);
  50  *            @endcode
  51  * \~english  Command ID to send CAN data and get the send status
  52  */
  53 #define CID_CANHAL_CMD_CAN_SEND_STATUS (0x0A03)
  54
  55 /**
  56  * l_eStatus = FrameworkUnifiedAttachCallbackToDispatcher(hApp, FRAMEWORKUNIFIED_ANY_SOURCE, CID_CANHAL_CMD_CAN_RECV, CANHalRcvProcess);
  57  *            @endcode
  58  * \~english  Command ID to receive the CAN data
  59  */
  60 #define CID_CANHAL_CMD_CAN_RECV        (0x0A04)
  61
  62 /**
  63  * l_eStatus = FrameworkUnifiedAttachCallbackToDispatcher(hApp, FRAMEWORKUNIFIED_ANY_SOURCE, CID_CANHAL_CMD_CAN_READY, AnyCallback);
  64  *            @endcode
  65  * \~english  Command ID to receive Global CAN is ready.
  66  */
  67 #define CID_CANHAL_CMD_CAN_READY                 (0x0A0C)
  68
  69 /**
  70  * l_eStatus = FrameworkUnifiedAttachCallbackToDispatcher(hApp, FRAMEWORKUNIFIED_ANY_SOURCE, CID_CANHAL_CMD_ERROR_NOTIFY, AnyCallback);
  71  *            @endcode
  72  * \~english  Command ID to receive can hal error.
  73  */
  74 #define CID_CANHAL_CMD_ERROR_NOTIFY                 (0x0A10)
  75
  76 /**
  77  * \~english  No target address
  78  */
  79 #define CAN_NTA_NONE (0x00)
  80
  81 /**
  82  * \~english Size of error message.
  83  */
  84 #define CANHAL_ERROR_MESSAGE_LEN (2048)
  85
  86 /**
  87  * \~english  Return type of the API
  88  */
  89 enum CANHAL_RET_API {
  90   CANHAL_RET_NORMAL = 0,  //!< \~english API Success
  91   CANHAL_RET_ERR_ERR,     //!< \~english API Failed
  92   CANHAL_RET_ERR_PARAM,   //!< \~english Parameter error
  93   CANHAL_RET_ERR_STATE,  //!< \~english Uninitialized(not called CanOpen)
  94 };
  95
  96 /**
  97  * \~english  CAN type
  98  */
  99 enum CanHalType {
 100     CAN_HAL_TYPE_CAN = 0,  //!< \~english CAN
 101     NR_CAN_HAL_TYPES       //!< \~english Number of CAN type
 102 };
 103
 104 /**
 105  * \~english  device State
 106  */
 107 enum DEVICE_STATE {
 108   DEVICE_STATE_UNAVAILABLE,    //!< \~english device unavailable
 109   DEVICE_STATE_AVAILABLE,      //!< \~english device available
 110 };
 111
 112 /**
 113  * \~english  CAN Send Result
 114  */
 115 enum CAN_SEND_RESULT {
 116     CAN_SEND_RESULT_FAILURE = 0,     //!< \~english Send failure
 117     CAN_SEND_RESULT_SUCCESS,         //!< \~english Send success
 118 };
 119
 120 /**
 121  * \~english  structure of can data
 122  */
 123 typedef struct CanMessageT {
 124     uint32_t can_id;                 //!< \~english Target CAN ID
 125     uint32_t dlc;                    //!< \~english Data length(1~2048)
 126     uint8_t  rid;                    //!< \~english Replay ID
 127     uint8_t  data[CAN_MESSAGE_LEN];  //!< \~english Data buffer
 128 } CanMessage;
 129
 130 /**
 131  * \~english  structure of can send result
 132  */
 133 typedef struct CanSendResultT {
 134   uint32_t        can_id;               //!< \~english CAN ID
 135   uint8_t         rid;                  //!< \~english RID
 136   CAN_SEND_RESULT result;              //!< \~english Send result
 137 } CanSendResult;
 138
 139 #ifdef __cplusplus
 140 extern "C" {
 141 #endif
 142
 143 /**
 144  * \ingroup CanOpen
 145  * \~english @par Brief
 146  *        API to start the can_hal service
 147  * \~english @param [in] h_app
 148  *        HANDLE - Application handle
 149  * \~english @param [in] type
 150  *        CanHalType - CAN type
 151  * \~english @retval CANHAL_RET_NORMAL     :  API return OK
 152  * \~english @retval CANHAL_RET_ERR_PARAM  :  Paramter error
 153  * \~english @retval CANHAL_RET_ERR_ERR    :  Failed
 154  * \~english @par Prerequisite
 155  *        None
 156  * \~english @par Change of internal state
 157  *        - When calling of this API succeeds, the requested channel state is set to open.
 158  * \~english @par Conditions of processing failure
 159  *        - Input paramter is invalid.
 160  *        - Internal processing failure.
 161  * \~english @par Classification
 162  *        Public
 163  * \~english @par Type
 164  *        Method
 165  * \~english @par Detail
 166  *        - Perform device use preparation processing of the requested communication path.
 167  *        - Up to one process can use this library.
 168  * \~english @see
 169  *        Nothing
 170  */
 171 CANHAL_RET_API CanOpen(HANDLE h_app, CanHalType type);
 172
 173 /**
 174  * \ingroup CanClose
 175  * \~english @par Brief
 176  *        API to stop the can_hal service
 177  * \~english @param [in] h_app
 178  *        HANDLE - Application handle
 179  * \~english @param [in] type
 180  *        CanHalType - CAN type
 181  * \~english @retval CANHAL_RET_NORMAL      :  API return OK
 182  * \~english @retval CANHAL_RET_ERR_PARAM   :  Paramter error
 183  * \~english @retval CANHAL_RET_ERR_ERR     :  Failed
 184  * \~english @retval CANHAL_RET_ERR_STATE  :  Failed because CanOpen is not called
 185  * \~english @par Prerequisite
 186  *        Communication path status is open
 187  * \~english @par Change of internal state
 188  *        - In the case of normal termination, the requested channel state is close.
 189  * \~english @par Conditions of processing failure
 190  *        - CanOpen is not called.
 191  *        - Input paramter is invalid.
 192  *        - Internal processing failure.
 193  * \~english @par Classification
 194  *        Public
 195  * \~english @par Type
 196  *        Sync
 197  * \~english @par Detail
 198  *        - Perform device use finalize processing of the requested communication path.
 199  *        - Up to one process can use this library.
 200  * \~english @see
 201  *        None
 202  */
 203 CANHAL_RET_API CanClose(HANDLE h_app, CanHalType type);
 204
 205 /**
 206  * \ingroup CanSend
 207  * \~english @par Brief
 208  *        API to send the Can data
 209  * \~english @param [in] h_app
 210  *        HANDLE - Application handle
 211  * \~english @param [in] message
 212  *        const CanMessage * - Pointer to the structure of
 213  *                                    the data which is sent to the CAN
 214  * \~english @param [in] type
 215  *        CanHalType - CAN type
 216  * \~english @retval CANHAL_RET_NORMAL      :  API return OK
 217  * \~english @retval CANHAL_RET_ERR_ERR     :  Failed
 218  * \~english @retval CANHAL_RET_ERR_PARAM   :  Paramter error
 219  * \~english @retval CANHAL_RET_ERR_STATE  :  Failed because CanOpen is not called
 220  * \~english @par Prerequisite
 221  *        - can_hal start successfully
 222  * \~english @par Change of internal state
 223  *        - Change of internal state according to the API does not occur.
 224  * \~english @par Conditions of processing failure
 225  *        - Input paramter is invalid.
 226  *        - CanOpen is not called.
 227  *        - Send data to the sending thread failed.
 228  * \~english @par Classification
 229  *        Public
 230  * \~english @par Type
 231  *        Method
 232  * \~english @par Detail
 233  *        - Check the sending data, if data is valid, then send the data
 234  *            to the sending thread; If data if invalid, then return error.
 235  *        - The API can only be used by 1 process.
 236  * \~english @see
 237  *        \ref CanSendResult
 238  */
 239 CANHAL_RET_API CanSend(HANDLE h_app, const CanMessage *message, CanHalType type);
 240
 241 /**
 242  * \ingroup CanGetVersion
 243  * \~english @par Brief
 244  *        API to get the CAN micon version
 245  * \~english @param [in] h_app
 246  *        HANDLE - Application handle
 247  * \~english @param [out] p_version
 248  *        std::string * - Pointer to the version buffer
 249  * \~english @retval CANHAL_RET_NORMAL     : API return OK
 250  * \~english @retval CANHAL_RET_ERR_STATE : Failed because CanOpen is not called
 251  * \~english @retval CANHAL_RET_ERR_PARAM  : Paramter error
 252  * \~english @retval CANHAL_RET_ERR_ERR    : Failed
 253  * \~english @par Prerequisite
 254  *        - can_hal start successfully
 255  * \~english @par Change of internal state
 256  *        - Change of internal state according to the API does not occur.
 257  * \~english @par Conditions of processing failure
 258  *        - Input paramter is invalid.
 259  *        - CanOpen is not called.
 260  * \~english @par Classification
 261  *        Public
 262  * \~english @par Type
 263  *        Sync
 264  * \~english @par Detail
 265  *        - This API gets the CAN version.
 266  *        - The API can only be used by 1 process.
 267  *        - p_version detail\n
 268  *          Information on the following pink shaded part 4 BYTE in the version information \n
 269  *          of the CAN microcomputer is stored in string and returned.\n
 270  *          <table>
 271  *          <tr>
 272  *          <th></th><th>7bit-0bit</th>
 273  *          </tr>
 274  *          <tr>
 275  *          <td>1BYTE</td><td>7bit:M/S 6-0bit:Message kind</td>
 276  *          </tr>
 277  *          <tr>
 278  *          <td>2BYTE</td><td>7bit-0bit Operation Code</td>
 279  *          </tr>
 280  *          <tr>
 281  *          <td>3BYTE</td><td bgcolor="pink">7bit-0bit Software kind</td>
 282  *          </tr>
 283  *          <tr>
 284  *          <td>4BYTE</td><td bgcolor="pink">7bit-0bit version(Higher order)</td>
 285  *          </tr>
 286  *          <tr>
 287  *          <td>5BYTE</td><td bgcolor="pink">7bit-0bit version(middle order)</td>
 288  *          </tr>
 289  *          <tr>
 290  *          <td>6BYTE</td><td bgcolor="pink">7bit-0bit version(lower order)</td>
 291  *          </tr>
 292  *          </table>
 293  * \~english @see
 294  *        None
 295  */
 296 CANHAL_RET_API CanGetVersion(HANDLE h_app, std::string *p_version);
 297
 298 /** @}*/  // end of can_hal
 299 /** @}*/  // end of communication
 300 #ifdef __cplusplus
 301 }
 302 #endif
 303 #endif  // HAL_API_CAN_HAL_H_