// Copyright (c) 2016, 2020, 2022-2023 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.

/** @cond */
interface ISPCOM
{
/** @endcond */

  /**
   * @addtogroup ISPCOM
   * @{
   */

  /** @cond */
  /**
   * Maximum size (including null) for channel name.
   */
  const uint32 SPCOM_CHANNEL_NAME_SIZE = 32;

  /**
   * Request buffer size.
   * Any large data (multiply of 4KB) is provided by temp buffer in DDR.
   * Request shall provide the temp buffer physical address (align to 4KB).
   * Maximum request/response size of 268 is used to accommodate APDU size.
   */
  const uint32 SPCOM_MAX_REQUEST_SIZE = 268;

  /**
   * Response buffer size.
   * Any large data (multiply of 4KB) is provided by temp buffer in DDR.
   * Response shall provide the temp buffer physical address (align to 4KB).
   * Maximum request/response size of 268 is used to accommodate APDU size.
   */
  const uint32 SPCOM_MAX_RESPONSE_SIZE = 268;
  /** @endcond */
  
  /**
   * Error Codes
   */
   
  /*
   * Requested memory region size is invalid.
   */
  error ERROR_INVALID_SIZE;

  /**
    Registers client for communication channel.

    @param[in]  chName     Channel name string.
    @param[out] retHandle  Client handle.

    @return
    Object_OK on success. \n
    Object_ERROR or negative value on failure.
  */
  method register_client( in buffer chName,
                          out uint64 retHandle );

  /**
    Unregisters client for communication channel.

    @param[in] handle  Client handle.

    @return
    Object_OK on success. \n
    Object_ERROR or negative value on failure.
  */
  method unregister_client(in uint64 handle);

  /**
    Sends a request and receives a response.

    @param[in]  handle        Client handle.
    @param[in]  req_ptr       Request buffer.
    @param[in]  req_size      Request buffer size.
    @param[in]  resp_ptr      Response buffer.
    @param[in]  resp_size     Response buffer size (max response size).
    @param[in]  timeout_msec  Timeout in msec between command and response.\n
                              0=no timeout.
    @param[out] retRespSize   Actual response size.

    @return
    Object_OK on success. \n
    Object_ERROR or negative value on failure.
  */
  method client_send_message_sync(in uint64 handle,
                                  in buffer req_ptr,
                                  in uint32 req_size,
                                  in buffer resp_ptr,
                                  in uint32 resp_size,
                                  in uint32 timeout_msec,
                                  out uint32 retRespSize);

  /**
    - Checks if remote server is connected.
    - Checks that logical channel is fully connected between the TZ client and SP server.

    @param[in]  handle        Client handle.
    @param[out] is_connected  Boolean value indicates whether channel is connected.

    @return
    Object_OK on success. \n
    Object_ERROR or negative value on failure.
  */
  method client_is_server_connected(in uint64 handle,
                                    out uint32 is_connected);

  /**
    Check if SPSS link is up.

    @param[out] is_link_up  Boolean value indicates if link is up.

    @return
    Object_OK on success. \n
    Object_ERROR or negative value on failure.
  */
  method is_sp_subsystem_link_up(out uint32 is_link_up);

  /**
    - Sends reset command to secure processor.
    - Ask remote SP to reset itself. SP initiates a Watch-Dog-Bite.

    @return
    Object_OK on success. \n
    Object_ERROR or negative value on failure.
  */
  method reset_sp_subsystem();
  
  /**
   * Returns a shared memory region to be used with TZSPCOM.
   * 
   * Spcom Service returns returns a region that can be 
   * read or written by the TA and the memory range is guaranteed 
   * to only be read-write accessible to the SPSS and TZ domains 
   * for the duration of the lifetime of the memory object in the TA.
   *
   * Note: The memory range can be accessed by other TAs at the same 
   * time and the SPU has no way to tell which TA wrote what memory 
   * to the shared memory.
   * 
   * @param[in]  size   size of the buffer
   * @param[out] mem    shared memory region object
   * @param[out] phy_addr shared memory region physical address
   *
   * @return
   * Object_OK on success. \n
   * Object_ERROR or negative value on failure.
   */
  method get_shared_memory(in uint32 size,
                 out interface mem, out uint64 phy_addr);

  /**
   * Returns a shared memory region object.
   *
   * The memory passed for registration belongs to an area of memory
   * reserved for SP and TZ domains read-write access.
   *
   * Spcom Service returns a memory region object that can be
   * read or written by the TA and the memory range is guaranteed
   * to only be read-write accessible to the SPSS and TZ domains
   * for the duration of the lifetime of the memory object in the TA.
   *
   * Note: The memory range can be accessed by other TAs at the same
   * time and the SPU has no way to tell which TA wrote what memory
   * to the shared memory.
   *
     @param[in]  phy_addr physical address of the buffer.
   * @param[in]  size     size of the buffer
   * @param[out] mem      shared memory region object
   *
   * @return
   * Object_OK on success. \n
   * Object_ERROR or negative value on failure.
   */
  method register_shared_memory(in uint64 phy_addr,
         in uint32 size,
         out interface mem);
 
   /**
   * Returns a shared memory region object.
   *
   * The memory object passed for registration belongs to an area of memory
   * reserved for SP and TZ domains read-write access.
   *
   * Spcom Service returns a memory region object that can be
   * read or written by the TA and the memory range is guaranteed
   * to only be read-write accessible to the SPSS and TZ domains
   * for the duration of the lifetime of the memory object in the TA.
   *
   * Note: The memory range can be accessed by other TAs at the same
   * time and the SPU has no way to tell which TA wrote what memory
   * to the shared memory.
   *
   * @param[in] memObjIn     shared memory object of the buffer
   * @param[out] memObjOut      shared memory region object
   *
   * @return
   * Object_OK on success. \n
   * Object_ERROR or negative value on failure.
   */
  method register_shared_memory_from_obj(
         in interface memObjIn,
         out interface memObjOut);
  /* @} */ /* end_addtogroup ISPCOM */
};
