include/ti_rpmsg_char.h

   1 /*
   2  * Copyright (c) 2020 Texas Instruments Incorporated - https://www.ti.com
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  *    Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  *
  11  *    Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  *    Neither the name of Texas Instruments Incorporated nor the names of
  16  *    its contributors may be used to endorse or promote products derived
  17  *    from this software without specific prior written permission.
  18  *
  19  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  *
  31  */
  32
  33 #ifndef __TI_RPMSG_CHAR_H__
  34 #define __TI_RPMSG_CHAR_H__
  35
  36 #include <rproc_id.h>
  37
  38 #if defined(__cplusplus)
  39 extern "C" {
  40 #endif
  41
  42 #define RPMSG_DEV_NAME_MAXLEN   32
  43
  44 /*!
  45  * @brief Structure returned during rpmsg_char_open
  46  *
  47  * @param fd Opened file descriptor for the local rpmsg endpoint device
  48  * @param endpt Local Endpoint address used for receiving messages
  49  */
  50 struct rpmsg_char_dev {
  51         int fd;
  52         int endpt;
  53 };
  54
  55 typedef struct rpmsg_char_dev rpmsg_char_dev_t;
  56
  57 /*!
  58  *  @brief      Function to create and access a rpmsg endpoint device for a
  59  *              given rpmsg device
  60  *
  61  *              This function is to be used to open a communication channel
  62  *              in a Linux application with any rpmsg device that is bound to
  63  *              the Linux kernel rpmsg_chrdev driver (rpmsg_char.ko module).
  64  *
  65  *              The function returns a pointer to a rpmsg_char_dev structure
  66  *              with the file descriptor and local end-point address filled in
  67  *              and usable by an application for a given remoteproc, rpmsg
  68  *              device (identified by published name from remote processor) and
  69  *              the remote end-point address used by the rpmsg device.
  70  *
  71  *              The opened file descriptor can be used with regular file
  72  *              operations such as select(), read() and write() functions to
  73  *              wait, receive and send messages to the rpmsg device on the
  74  *              remote processor. The messages are received on the local
  75  *              end-point address.
  76  *
  77  *  @param      rproc_id remoteproc enum value identifying a remote processor.
  78  *                       Value is a local id used by the library
  79  *
  80  *  @param      dev_name Name of the rpmsg device name to open. Passing NULL
  81  *                       will use a default name "rpmsg_chrdev" for the rpmsg
  82  *                       devices, and identified by remote_endpt. The maximum
  83  *                       length for the rpmsg device name is as per the virtio
  84  *                       rpmsg transport, RPMSG_DEV_NAME_MAXLEN (32 bytes)
  85  *
  86  *  @param      remote_endpt rpmsg remote end-point address for the rpmsg device
  87  *                           to open. Valid value is mandatory
  88  *
  89  *  @param      eptdev_name Name used to create and identify the local endpoint
  90  *                          device. Needs to be unique across all the Linux
  91  *                          applications. The maximum length for the
  92  *                          eptdev_name is RPMSG_DEV_NAME_MAXLEN (32 bytes)
  93  *
  94  *  @param      flags Flags used to open the local end-point device
  95  *
  96  *  @ret        A valid pointer to a rpmsg_char_dev_t on success, NULL on
  97  *              failures
  98  *
  99  *  @sa         rpmsg_char_close
 100  */
 101 rpmsg_char_dev_t *rpmsg_char_open(enum rproc_id id, char *dev_name,
 102                                   int remote_endpt, char *eptdev_name,
 103                                   int flags);
 104
 105 /*!
 106  *  @brief      Function to close and delete a previously created local endpoint
 107  *              device with rpmsg_char_open
 108  *
 109  *              Once this function is called, any regular file operations on the
 110  *              underlying fd cannot be used. The pointer value is not modified
 111  *              within the function, but is no longer valid after a successful
 112  *              return.
 113  *
 114  *  @param      rcdev  Pointer to the previously created rpmsg_char_dev_t. The
 115  *                     handle will be unusable with any of the regular file
 116  *                     operation functions after a success
 117  *
 118  *  @ret        0 on success, a negative value on failure
 119  *
 120  *  @sa         rpmsg_char_open
 121  */
 122 int rpmsg_char_close(rpmsg_char_dev_t *rcdev);
 123
 124 /*!
 125  *  @brief      Function to initialize the library
 126  *
 127  *              This function initializes the library after performing SoC
 128  *              detection and corresponding initialization. This needs to be
 129  *              invoked before being able to use any other function. This only
 130  *              needs to be invoked once in an application, there is no reference
 131  *              counting.
 132  *
 133  *  @param      soc_name  Name of the SoC family to be used for manual detection
 134  *                        if kernel doesn't support a socbus device for a
 135  *                        particular SoC and auto detection fails. Preferred
 136  *                        usage is just to pass NULL
 137  *
 138  *  @ret        0 on success, 1 if already invoked previously, and a negative
 139  *              value on failure
 140  *
 141  *  @sa         rpmsg_char_exit
 142  */
 143 int rpmsg_char_init(char *soc_name);
 144
 145 /*!
 146  *  @brief      Function to finalize the library
 147  *
 148  *              This function finalizes and performs all the de-initialization
 149  *              and any cleanup on the library. This is the last function that
 150  *              needs to be invoked after all usage is done as part of the
 151  *              application's cleanup. This only need to be invoked once in an
 152  *              application, there is no reference counting.
 153  *
 154  *  @ret        None
 155  *
 156  *  @sa         rpmsg_char_init
 157  */
 158 void rpmsg_char_exit(void);
 159
 160 #if defined(__cplusplus)
 161 }
 162 #endif
 163
 164 #endif /* __TI_RPMSG_CHAR_H__ */