Line data    Source code

       1           0 : /*
       2             :  * Copyright (c) 2021 Carlo Caione <ccaione@baylibre.com>
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : #ifndef ZEPHYR_INCLUDE_IPC_SERVICE_IPC_RPMSG_H_
       8             : #define ZEPHYR_INCLUDE_IPC_SERVICE_IPC_RPMSG_H_
       9             : 
      10             : #include <zephyr/ipc/ipc_service.h>
      11             : #include <openamp/open_amp.h>
      12             : #include <metal/device.h>
      13             : 
      14             : #ifdef __cplusplus
      15             : extern "C" {
      16             : #endif
      17             : 
      18             : /**
      19             :  * @brief IPC service RPMsg API
      20             :  * @defgroup ipc_service_rpmsg_api IPC service RPMsg API
      21             :  * @ingroup ipc
      22             :  * @{
      23             :  */
      24             : 
      25             : /** Number of endpoints. */
      26           1 : #define NUM_ENDPOINTS   CONFIG_IPC_SERVICE_BACKEND_RPMSG_NUM_ENDPOINTS_PER_INSTANCE
      27             : 
      28             : struct ipc_rpmsg_ept;
      29             : 
      30             : /**
      31             :  * @typedef rpmsg_ept_bound_cb
      32             :  * @brief Define the bound callback.
      33             :  *
      34             :  * This callback is defined at instance level and it is called when an endpoint
      35             :  * of the instance is bound.
      36             :  *
      37             :  * @param ept Endpoint of the instance just bound.
      38             :  */
      39           1 : typedef void (*rpmsg_ept_bound_cb)(struct ipc_rpmsg_ept *ept);
      40             : 
      41             : /** @brief Endpoint structure.
      42             :  *
      43             :  *  Used to define an endpoint to be encapsulated in an RPMsg instance.
      44             :  */
      45           1 : struct ipc_rpmsg_ept {
      46             :         /** RPMsg endpoint. */
      47           1 :         struct rpmsg_endpoint ep;
      48             : 
      49             :         /** Name of the endpoint. */
      50           1 :         char name[RPMSG_NAME_SIZE];
      51             : 
      52             :         /** Destination endpoint. */
      53           1 :         uint32_t dest;
      54             : 
      55             :         /** Bound flag. */
      56           1 :         volatile bool bound;
      57             : 
      58             :         /** Callbacks. */
      59           1 :         const struct ipc_service_cb *cb;
      60             : 
      61             :         /** Private data to be passed to the endpoint callbacks. */
      62           1 :         void *priv;
      63             : };
      64             : 
      65             : /** @brief RPMsg instance structure.
      66             :  *
      67             :  *  Struct representation of an RPMsg instance.
      68             :  */
      69           1 : struct ipc_rpmsg_instance {
      70             :         /** Endpoints in the instance. */
      71           1 :         struct ipc_rpmsg_ept endpoint[NUM_ENDPOINTS];
      72             : 
      73             :         /** RPMsg virtIO device. */
      74           1 :         struct rpmsg_virtio_device rvdev;
      75             : 
      76             :         /** SHM pool. */
      77           1 :         struct rpmsg_virtio_shm_pool shm_pool;
      78             : 
      79             :         /** EPT (instance) bound callback. */
      80           1 :         rpmsg_ept_bound_cb bound_cb;
      81             : 
      82             :         /** EPT (instance) callback. */
      83           1 :         rpmsg_ept_cb cb;
      84             : 
      85             :         /** Mutex for the instance. */
      86           1 :         struct k_mutex mtx;
      87             : };
      88             : 
      89             : /** @brief Init an RPMsg instance.
      90             :  *
      91             :  *  Init an RPMsg instance.
      92             :  *
      93             :  *  @param instance Pointer to the RPMsg instance struct.
      94             :  *  @param role Host / Remote role.
      95             :  *  @param buffer_size Size of the buffer used to send data between host and remote.
      96             :  *  @param shm_io SHM IO region pointer.
      97             :  *  @param vdev VirtIO device pointer.
      98             :  *  @param shb Shared memory region pointer.
      99             :  *  @param size Size of the shared memory region.
     100             :  *  @param ns_bind_cb callback handler for name service announcement without
     101             :  *                    local endpoints waiting to bind. If NULL the
     102             :  *                    implementation falls back to the internal implementation.
     103             :  *
     104             :  *  @retval -EINVAL When some parameter is missing.
     105             :  *  @retval 0 If successful.
     106             :  *  @retval Other errno codes depending on the OpenAMP implementation.
     107             :  */
     108           1 : int ipc_rpmsg_init(struct ipc_rpmsg_instance *instance,
     109             :                    unsigned int role,
     110             :                    unsigned int buffer_size,
     111             :                    struct metal_io_region *shm_io,
     112             :                    struct virtio_device *vdev,
     113             :                    void *shb, size_t size,
     114             :                    rpmsg_ns_bind_cb ns_bind_cb);
     115             : 
     116             : 
     117             : /** @brief
     118             :  *
     119             :  * Deinit an RPMsg instance
     120             :  *
     121             :  * @param instance Pointer to the RPMsg instance struct.
     122             :  * @param role Host / Remote role.
     123             :  *
     124             :  * @retval -EINVAL When some parameter is missing
     125             :  * @retval 0 If successful
     126             :  */
     127           1 : int ipc_rpmsg_deinit(struct ipc_rpmsg_instance *instance,
     128             :                    unsigned int role);
     129             : 
     130             : /** @brief Register an endpoint.
     131             :  *
     132             :  *  Register an endpoint to a provided RPMsg instance.
     133             :  *
     134             :  *  @param instance Pointer to the RPMsg instance struct.
     135             :  *  @param role Host / Remote role.
     136             :  *  @param ept Endpoint to register.
     137             :  *
     138             :  *  @retval -EINVAL When some parameter is missing.
     139             :  *  @retval 0 If successful.
     140             :  *  @retval Other errno codes depending on the OpenAMP implementation.
     141             :  */
     142           1 : int ipc_rpmsg_register_ept(struct ipc_rpmsg_instance *instance, unsigned int role,
     143             :                            struct ipc_rpmsg_ept *ept);
     144             : 
     145             : /**
     146             :  * @}
     147             :  */
     148             : 
     149             : #ifdef __cplusplus
     150             : }
     151             : #endif
     152             : 
     153             : #endif /* ZEPHYR_INCLUDE_IPC_SERVICE_IPC_RPMSG_H_ */