examples: Add rpmsg_char_simple example
[rpmsg/ti-rpmsg-char.git] / 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  */
33 #ifndef __TI_RPMSG_CHAR_H__
34 #define __TI_RPMSG_CHAR_H__
36 #include <rproc_id.h>
38 #if defined(__cplusplus)
39 extern "C" {
40 #endif
42 #define RPMSG_DEV_NAME_MAXLEN   32
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 };
55 typedef struct rpmsg_char_dev rpmsg_char_dev_t;
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);
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);
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);
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);
160 #if defined(__cplusplus)
162 #endif
164 #endif /* __TI_RPMSG_CHAR_H__ */