deck_hal/hal_api/deck_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
  17 /*!-----------------------------------------------------------------------------
  18  * @file    deck_hal.h
  19  * @~english
  20  * @brief   deck_hal API head
  21  *
  22  */
  23
  24 #ifndef HAL_API_DECK_HAL_H_
  25 #define HAL_API_DECK_HAL_H_
  26
  27 #include <native_service/frameworkunified_types.h>
  28
  29 /**
  30  * @file deck_hal.h
  31  */
  32
  33 /** @addtogroup interface_unified
  34  *  @{
  35  */
  36 /** @addtogroup deck_hal
  37  *  @ingroup interface_unified
  38  *  @{
  39  */
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif /*__cplusplus*/
  43
  44 /*! @~english Maximum length of command data division */
  45 #define DECK_CMD_SIZE_CMDDATA_MAX  252
  46 /*! @~english Maximum length of notification destination */
  47 #define NOTIFY_NAME_MAX_SIZE 15
  48
  49 // CID_DECK_SYS_DELIVERY is for deck_hal to report correspinding message to vehicle,
  50 // the value 0x40 can be changed in the future
  51 /**
  52  * \~english @brief  DECK SYS Command-Delivery Notification
  53  * \~english @brief  If you want to receive this DECK SYS command-delivery notification, use the NSFW IF as follows:
  54  * \~english @code
  55  * l_eStatus = FrameworkunifiedAttachCallbackToDispatcher(hApp, DECKHAL_THREAD, CID_DECK_SYS_DELIVERY, LineSensDrvRcvDeckHal);
  56  *            @endcode
  57  */
  58 #define CID_DECK_SYS_DELIVERY 0x40
  59
  60 /*!
  61  * @~english
  62  * @brief Disc eject mode
  63 */
  64 typedef enum {
  65   /*! @~english  normal eject   */
  66   DECK_EJECT_NORMAL,
  67   /*! @~english  forced eject   */
  68   DECK_EJECT_FORCED
  69 } DeckEjectMode;
  70
  71 /*!
  72  * @~english
  73  * @brief Disc mode
  74 */
  75 typedef enum {
  76   /*! @~english  CD    */
  77   DECK_KIND_CD,
  78   /*! @~english  DVD    */
  79   DECK_KIND_DVD,
  80   /*! @~english  Blue-lay disc    */
  81   DECK_KIND_BD
  82 } DeckKind;
  83
  84 /*------------------------------------------------------------------------------
  85  * typedefs
  86  *----------------------------------------------------------------------------*/
  87 /**
  88  * \~english  Deck-Sys command header structure
  89  */
  90 typedef struct {
  91   /*! @~english Source logical address  */
  92   uint8_t  lgadr_from;
  93   /*! @~english Forwarding destination logical address  */
  94   uint8_t  lgadr_to;
  95   /*! @~english OP code  */
  96   uint8_t  opc;
  97   /*! @~english Reserve  */
  98   uint8_t  reserve;
  99 } DeckCmdhdr;
 100
 101 /**
 102  * \~english  Deck-Sys command body structure
 103  */
 104 typedef struct DeckCmd {
 105   /*! @~english Deck-Sys command header  */
 106     DeckCmdhdr cmdhdr;
 107   /*! @~english Data length  */
 108     uint16_t data_length;
 109   /*! @~english Reserve  */
 110     uint16_t reserve;
 111   /*! @~english Command data  */
 112     uint8_t data[DECK_CMD_SIZE_CMDDATA_MAX];
 113 } DeckCmd;
 114
 115 /*!
 116  * @~english
 117  * @brief Structure for message header
 118  */
 119 typedef struct {
 120   uint16_t replyid;      //!< \~english Send Result ID
 121   uint16_t sndpno;       //!< \~english Send process No
 122   uint16_t respno;       //!< \~english Response No
 123   uint16_t cid;          //!< \~english Command ID
 124   uint16_t msgbodysize;  //!< \~english Message body size
 125   uint8_t rid;           //!< \~english Resource ID
 126   uint8_t reserve;       //!< \~english Reserve
 127   uint8_t filler[2];     //!< \~english filler
 128 } DECK_HEADER_COMM;
 129
 130 /*!
 131  * @~english
 132  * @brief Structure for buffer message header
 133  */
 134 typedef struct {
 135   uint32_t signo;            //!< \~english Signal No
 136   DECK_HEADER_COMM hdr;  //!< \~english Message Header
 137 } DECK_MSGBUF_HEADER_COMM;
 138
 139 /**
 140  * \~english Delivery message structure
 141  */
 142 typedef struct {
 143   /*! @~english Header part  */
 144   DECK_MSGBUF_HEADER_COMM hdr;
 145   /*! @~english Physical address  */
 146   uint16_t phyadr_from;
 147   /*! @~english Communication type  */
 148   uint8_t service_type;
 149   /*! @~english Reserve    */
 150   uint8_t reserve;
 151   /*! @~english Data section  */
 152   DeckCmd cmd;
 153 } DECK_MSG_DELIVERY;
 154
 155 /*!
 156  * @~english
 157  * @brief Structure for send command data
 158  */
 159 typedef struct {
 160   /*! @~english Physical address */
 161   uint16_t  phyadr_from;
 162   /*! @~english Communication type */
 163   uint8_t   service_type;
 164   /*! @~english Forwarding former logic address */
 165   uint8_t   lgadr_from;
 166   /*! @~english Forwarding site logic address */
 167   uint8_t   lgadr_to;
 168   /*! @~english Operation code */
 169   uint8_t   opc;
 170   /*! @~english Data length (size in command data */
 171   uint8_t   d_length;
 172   /*! @~english Command data */
 173   uint8_t   data[DECK_CMD_SIZE_CMDDATA_MAX];
 174   /*! @~english reserve */
 175   uint8_t   reserve;
 176 } DECK_CMD_DATA;
 177
 178 /*!
 179  * @~english
 180  * @brief Structure for send command
 181  */
 182 typedef struct {
 183   /*! @~english Command information */
 184   DECK_CMD_DATA   cmd_data;
 185 } DECK_CMD;
 186
 187 /*------------------------------------------------------------------------------
 188  * function declaration
 189  *----------------------------------------------------------------------------*/
 190 ////////////////////////////////////////////////////////////////////////////////////////////
 191 /// \ingroup StopDiscRotation
 192 /// \~english @par Brief
 193 ///        Stop disc rotation
 194 /// \~english @param [in] -
 195 /// \~english @param [out] -
 196 /// \~english @retval eFrameworkunifiedStatusOK OK
 197 /// \~english @retval eFrameworkunifiedStatusFail Abnormal Error
 198 /// \~english @par Prerequisite
 199 ///       - Disc was inserted
 200 /// \~english @par Change of internal state
 201 ///       - Change of internal state according to the API does not occur.
 202 /// \~english @par Conditions of processing failure
 203 ///       - Error occurs when call open or ioctl function.[eFrameworkunifiedStatusFail]
 204 /// \~english @par Classification
 205 ///         Public
 206 /// \~english @par Type
 207 ///         Sync
 208 /// \~english @par Detail
 209 ///       - Stop disc rotation
 210 ///       - Whatever disc is rotating or stoped, return successed.
 211 ///       - The API can be used by multi-process.
 212 /// \~english @see None
 213 ////////////////////////////////////////////////////////////////////////////////////////////
 214
 215 EFrameworkunifiedStatus StopDiscRotation();
 216
 217 ////////////////////////////////////////////////////////////////////////////////////////////
 218 /// \ingroup EjectDisc
 219 /// \~english @par Brief
 220 ///        Eject disc
 221 /// \~english @param [in]  kind
 222 ///       DeckKind       - kind of deck.
 223 /// \~english @param [in]  mode
 224 ///       DeckEjectMode       - eject mode(normal/forcedly)
 225 /// \~english @param [out] -
 226 /// \~english @retval eFrameworkunifiedStatusOK OK
 227 /// \~english @retval eFrameworkunifiedStatusFail Abnormal Error
 228 /// \~english @par Prerequisite
 229 ///       - None
 230 /// \~english @par Change of internal state
 231 ///       - Change of internal state according to the API does not occur.
 232 /// \~english @par Conditions of processing failure
 233 ///       - Error occurs when call open or ioctl function.[eFrameworkunifiedStatusFail]
 234 /// \~english @par Classification
 235 ///         Public
 236 /// \~english @par Type
 237 ///         Sync
 238 /// \~english @par Detail
 239 ///       - Eject disc
 240 ///       - Whatever disc is Ejecting or Unejected, return successed.
 241 ///       - The API can be used by multi-process.
 242 /// \~english @see None
 243 ////////////////////////////////////////////////////////////////////////////////////////////
 244 EFrameworkunifiedStatus EjectDisc(DeckKind kind, DeckEjectMode mode);
 245
 246 ////////////////////////////////////////////////////////////////////////////////////////////
 247 /// \ingroup DeckHalSysSend
 248 /// \~english @par Brief
 249 ///        Send Disc Sys-Command to MICON
 250 /// \~english @param [in] h_app
 251 ///        HANDLE   - Handle of caller (Handle to get in Dispatcher generation
 252 ///                  (FrameworkunifiedCreateDispatcherWithoutLoop etc.))
 253 /// \~english @param [in] name
 254 ///        PCSTR    - Name to notification of send result destination thread name
 255 /// \~english @param [in] cmd
 256 ///        DECK_CMD - Send command pointer
 257 /// \~english @param [in] req_id
 258 ///        uint8_t - Resource ID
 259 /// \~english @param [out] -
 260 /// \~english @retval eFrameworkunifiedStatusOK Normal termination
 261 /// \~english @retval eFrameworkunifiedStatusInvldParam Abnormal parameter
 262 /// \~english @par Prerequisite
 263 ///       - None
 264 /// \~english @par Change of internal state
 265 ///       - Change of internal state according to the API does not occur.
 266 /// \~english @par Conditions of processing failure
 267 ///       - h_app is NULL.[eFrameworkunifiedStatusInvldParam]
 268 ///       - name is NULL or the length of name is longer than 15 bytes.
 269 ///         [eFrameworkunifiedStatusInvldParam]
 270 ///       - Send command pointer(cmd) is null.[eFrameworkunifiedStatusInvldParam]
 271 /// \~english @par Classification
 272 ///         Public
 273 /// \~english @par Type
 274 ///         Sync
 275 /// \~english @par Detail
 276 ///       - Send SYS command to MICON
 277 ///       - Now only usb disc exists,MICON disc is stub now.
 278 ///       - The API can only be used by 1 process.
 279 /// \~english @see None
 280 ////////////////////////////////////////////////////////////////////////////////////////////
 281 EFrameworkunifiedStatus DeckHalSysSend(HANDLE h_app, PCSTR name, const DECK_CMD* cmd, uint8_t req_id);
 282
 283 ////////////////////////////////////////////////////////////////////////////////////////////
 284 /// \ingroup DeckHalRegister
 285 /// \~english @par Brief
 286 ///        Register the deck_hal command to receive from MICON
 287 /// \~english @param [in] h_app
 288 ///        HANDLE   - Handle of caller (Handle to get in Dispatcher generation
 289 ///                  (FrameworkunifiedCreateDispatcherWithoutLoop etc.))
 290 /// \~english @param [in] notify_name
 291 ///        PCSTR    - Name to notification destination thread name
 292 /// \~english @param [out] -
 293 /// \~english @retval eFrameworkunifiedStatusOK Normal termination
 294 /// \~english @retval eFrameworkunifiedStatusInvldParam Abnormal parameter
 295 /// \~english @par Prerequisite
 296 ///       - None
 297 /// \~english @par Change of internal state
 298 ///       - Change of internal state according to the API does not occur.
 299 /// \~english @par Conditions of processing failure
 300 ///       - h_app is NULL.[eFrameworkunifiedStatusInvldParam]
 301 ///       - notify_name is NULL or the length of notify_name is longer than 15 bytes.
 302 ///         [eFrameworkunifiedStatusInvldParam]
 303 /// \~english @par Classification
 304 ///         Public
 305 /// \~english @par Type
 306 ///         Sync
 307 /// \~english @par Detail
 308 ///       - After call this API, the user can received dech_hal command from MICON.
 309 ///       - Now MICON is stub,so that deck_hal won't register to MICON.
 310 ///       - The API can only be used by 1 process.
 311 /// \~english @see None
 312 ////////////////////////////////////////////////////////////////////////////////////////////
 313 EFrameworkunifiedStatus DeckHalRegister(HANDLE h_app, PCSTR notify_name);
 314
 315 #ifdef __cplusplus
 316 }
 317 #endif /*__cplusplus  */
 318
 319 /** @}*/  // end of deck_hal
 320 /** @}*/  // end of interface_unified
 321
 322 #endif  // HAL_API_DECK_HAL_H_