diff options
Diffstat (limited to 'middleware/multicore/open-amp/rpmsg/rpmsg_rtos.h')
| -rw-r--r-- | middleware/multicore/open-amp/rpmsg/rpmsg_rtos.h | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/middleware/multicore/open-amp/rpmsg/rpmsg_rtos.h b/middleware/multicore/open-amp/rpmsg/rpmsg_rtos.h new file mode 100644 index 0000000..6a01d65 --- /dev/null +++ b/middleware/multicore/open-amp/rpmsg/rpmsg_rtos.h @@ -0,0 +1,254 @@ +/* + * Copyright (c) 2015 Freescale Semiconductor, Inc. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * 3. Neither the name of Freescale Semiconductor nor the names of its + * contributors may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + + /************************************************************************** + * FILE NAME + * + * rpmsg_rtos.h + * + * COMPONENT + * + * OpenAMP stack. + * + * DESCRIPTION + * + * This file provides RTOS adaptation layer that allows: + * - handling of received messages outside the interrupt context + * - the implementation of blocking API for the RPMsg receive side + * - provides zero-copy receive functionality + * - provides zero-copy send functionality + * + * DATA STRUCTURES + * + * none + * + * FUNCTIONS + * + * rpmsg_rtos_init + * rpmsg_rtos_deinit + * rpmsg_rtos_create_ept + * rpmsg_rtos_destroy_ept + * rpmsg_rtos_recv + * rpmsg_rtos_recv_nocopy + * rpmsg_rtos_recv_nocopy_free + * rpmsg_rtos_alloc_tx_buffer + * rpmsg_rtos_send + * rpmsg_rtos_send_nocopy + * + **************************************************************************/ +#ifndef __RPMSG_RTOS_H +#define __RPMSG_RTOS_H + +#include "../rpmsg/rpmsg.h" + +//! @addtogroup rpmsg_rtos +//! @{ + +/*! + * @brief + * This function allocates and initializes the rpmsg driver resources for + * given device ID (cpu id). The successful return from this function leaves + * fully enabled IPC link. RTOS aware version. + * + * @param[in] dev_id Remote device for which driver is to be initialized + * @param[out] rdev Pointer to newly created remote device + * @param[in] role Role of the other device, Master or Remote + * @param[out] def_chnl Pointer to rpmsg channel + * + * @return Status of function execution + * + * @see rpmsg_rtos_deinit + */ +int rpmsg_rtos_init(int dev_id, struct remote_device **rdev, int role, struct rpmsg_channel **def_chnl); + +/*! + * @brief + * This function frees rpmsg driver resources for given remote device. RTOS aware version. + * + * @param[in] rdev Pointer to device to de-init + * + * @see rpmsg_rtos_init + */ +void rpmsg_rtos_deinit(struct remote_device *rdev); + +/*! + * @brief + * This function creates rpmsg endpoint for the rpmsg channel. RTOS aware version. + * + * @param[in] rp_chnl Pointer to rpmsg channel + * @param[in] addr Endpoint src address + * + * @return Pointer to endpoint control block + * + * @see rpmsg_rtos_destroy_ept + */ +struct rpmsg_endpoint * rpmsg_rtos_create_ept(struct rpmsg_channel *rp_chnl, unsigned long addr); + +/*! + * @brief + * This function deletes rpmsg endpoint and performs cleanup. RTOS aware version. + * + * @param[in] rp_ept Pointer to endpoint to destroy + * + * @see rpmsg_rtos_create_ept + */ +void rpmsg_rtos_destroy_ept(struct rpmsg_endpoint *rp_ept); + +/*! + * @brief + * RTOS receive function - blocking version of the received function that can be called from an RTOS task. + * The data is copied from the receive buffer into the user supplied buffer. + * + * This is the "receive with copy" version of the RPMsg receive function. This version is simple + * to use but it requires copying data from shared memory into the user space buffer. + * The user has no obligation or burden to manage the shared memory buffers. + * + * @param[in] ept Pointer to the RPMsg endpoint on which data is received + * @param[in] data Pointer to the user buffer the received data are copied to + * @param[out] len Pointer to an int variable that will contain the number of bytes actually copied into the buffer + * @param[in] maxlen Maximum number of bytes to copy (received buffer size) + * @param[out] src Pointer to address of the endpoint from which data is received + * @param[in] timeout_ms Timeout, in milliseconds, to wait for a message. A value of 0 means don't wait (non-blocking call). + * A value of 0xffffffff means wait forever (blocking call). + * + * @return Status of function execution + * + * @see rpmsg_rtos_recv_nocopy + */ +int rpmsg_rtos_recv(struct rpmsg_endpoint *ept, void *data, int* len, int maxlen, unsigned long* src, int timeout_ms); + +/*! + * @brief + * RTOS receive function - blocking version of the received function that can be called from an RTOS task. + * The data is NOT copied into the user-app. buffer. + * + * This is the "zero-copy receive" version of the RPMsg receive function. No data is copied. + * Only the pointer to the data is returned. This version is fast, but it requires the user to manage + * buffer allocation. Specifically, the user must decide when a buffer is no longer in use and + * make the appropriate API call to free it, see rpmsg_rtos_recv_nocopy_free(). + * + * @param[in] ept Pointer to the RPMsg endpoint on which data is received + * @param[out] data Pointer to the RPMsg buffer of the shared memory where the received data is stored + * @param[out] len Pointer to an int variable that that will contain the number of valid bytes in the RPMsg buffer + * @param[out] src Pointer to address of the endpoint from which data is received + * @param[in] timeout_ms Timeout, in milliseconds, to wait for a message. A value of 0 means don't wait (non-blocking call). + * A value of 0xffffffff means wait forever (blocking call). + * + * @return Status of function execution + * + * @see rpmsg_rtos_recv_nocopy_free + * @see rpmsg_rtos_recv + */ +int rpmsg_rtos_recv_nocopy(struct rpmsg_endpoint *ept, void **data, int* len, unsigned long* src, int timeout_ms); + +/*! + * @brief This function frees a buffer previously returned by rpmsg_rtos_recv_nocopy(). + * + * Once the zero-copy mechanism of receiving data is used, this function + * has to be called to free a buffer and to make it available for the next data + * transfer. + * + * @param[in] ept Pointer to the RPMsg endpoint that has consumed received data + * @param[in] data Pointer to the RPMsg buffer of the shared memory that has to be freed + * + * @return Status of function execution + * + * @see rpmsg_rtos_recv_nocopy + */ +int rpmsg_rtos_recv_nocopy_free(struct rpmsg_endpoint *ept, void* data); + +/*! + * @brief Allocates the tx buffer for message payload. + * + * This API can only be called at process context to get the tx buffer in vring. By this way, the + * application can directly put its message into the vring tx buffer without copy from an application buffer. + * It is the application responsibility to correctly fill the allocated tx buffer by data and passing correct + * parameters to the rpmsg_rtos_send_nocopy() function to perform data no-copy-send mechanism. + * + * @param[in] ept Pointer to the RPMsg endpoint that requests tx buffer allocation + * @param[out] size Pointer to store tx buffer size + * + * @return The tx buffer address on success and NULL on failure + * + * @see rpmsg_rtos_send_nocopy + */ +void *rpmsg_rtos_alloc_tx_buffer(struct rpmsg_endpoint *ept, unsigned long *size); + +/*! + * @brief Sends a message across to the remote processor. + * + * This function sends data of length len to the remote dst address. + * In case there are no TX buffers available, the function will block until + * one becomes available, or a timeout of 15 seconds elapses. When the latter + * happens, -ERESTARTSYS is returned. + * + * @param[in] ept Pointer to the RPMsg endpoint + * @param[in] data Pointer to the application buffer containing data to be sent + * @param[in] len Size of the data, in bytes, to transmit + * @param[in] dst Destination address of the message + * + * @return 0 on success and an appropriate error value on failure + * + * @see rpmsg_rtos_send_nocopy + */ +int rpmsg_rtos_send(struct rpmsg_endpoint *ept, void *data, int len, unsigned long dst); + +/*! + * @brief Sends a message in tx buffer allocated by rpmsg_rtos_alloc_tx_buffer() + * to the remote processor. + * + * This function sends txbuf of length len to the remote dst address. + * The application has to take the responsibility for: + * 1. tx buffer allocation (rpmsg_rtos_alloc_tx_buffer() ) + * 2. filling the data to be sent into the pre-allocated tx buffer + * 3. not exceeding the buffer size when filling the data + * 4. data cache coherency + * + * After the rpmsg_rtos_send_nocopy() function is issued the tx buffer is no more owned + * by the sending task and must not be touched anymore unless the rpmsg_rtos_send_nocopy() + * function fails and returns an error. In that case the application should try + * to re-issue the rpmsg_rtos_send_nocopy() again and if it is still not possible to send + * the message and the application wants to give it up from whatever reasons + * the rpmsg_rtos_recv_nocopy_free function could be called, + * passing the pointer to the tx buffer to be released as a parameter. + * + * @param[in] ept Pointer to the RPMsg endpoint + * @param[in] txbuf Tx buffer with message filled + * @param[in] len Size of the data, in bytes, to transmit + * @param[in] dst Destination address of the message + * + * @return 0 on success and an appropriate error value on failure + * + * @see rpmsg_rtos_alloc_tx_buffer + * @see rpmsg_rtos_send + */ +int rpmsg_rtos_send_nocopy(struct rpmsg_endpoint *ept, void *txbuf, int len, unsigned long dst); + +//! @} + +#endif /* __RPMSG_RTOS_H */ |