diff options
Diffstat (limited to 'arch/arm/mach-tegra/include/nvrm_transport.h')
-rw-r--r-- | arch/arm/mach-tegra/include/nvrm_transport.h | 361 |
1 files changed, 361 insertions, 0 deletions
diff --git a/arch/arm/mach-tegra/include/nvrm_transport.h b/arch/arm/mach-tegra/include/nvrm_transport.h new file mode 100644 index 000000000000..179f63223ed5 --- /dev/null +++ b/arch/arm/mach-tegra/include/nvrm_transport.h @@ -0,0 +1,361 @@ +/* + * Copyright (c) 2010 NVIDIA Corporation. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * + * 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. + * + * Neither the name of the NVIDIA Corporation 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. + * + */ + +#ifndef INCLUDED_nvrm_transport_H +#define INCLUDED_nvrm_transport_H + + +#if defined(__cplusplus) +extern "C" +{ +#endif + +#include "nvrm_module.h" +#include "nvrm_init.h" + +/** @file + * @brief <b>NVIDIA Driver Development Kit: + * Resource Manager Transport APIs</b> + * + * @b Description: This is the Transport API, which defines a simple means to + * pass messages across a lower level connection (generally between + * processors). + * + */ + +/** @defgroup nvrm_transport RM Transport API + * + * The Transport API defines a simple protocol through which clients and + * services may connect and communicate--normally, though not necessarily, + * across separate processors. Clients to this interface mostly include + * audio-visual applications whose code may reside on either the MPCore or AVP + * processors. These applications (and there could be many concurrently) may + * utilize this transport API to synchronize their operations. How the + * Transport API shepherds messages through these connections is not visible to + * the client. + * + * To setup a new connection, both the client and the service must open a port + * (whose name is agreed upon before compile-time). The service waits for a + * client to connect; this "handshake" allows a connection to be established. + * Once a client has established a connection with the service, they may send + * and receive messages. + * + * @ingroup nvddk_rm + * @{ + */ + +#include "nvos.h" + +/** + * A type-safe handle for the transport connection. + */ + +typedef struct NvRmTransportRec *NvRmTransportHandle; + +/** + * Creates one end of a transport connection. Both the service and client + * to the service must call this API to create each endpoint of the connection + * through a specified port (whose name is agreed upon before compile-time). + * A connection is not established between the service and client until a + * handshake is completed (via calls to NvRmTransportWaitForConnect() and + * NvRmTransportConnect() respectively). + * + * Assert in debug mode encountered if PortName is too long or does not exist + * + * @see NvRmTransportWaitForConnect() + * @see NvRmTransportConnect() + * @see NvRmTransportClose() + * + * @param hRmDevice Handle to RM device + * @param pPortName A character string that identifies the name of the port. + * This value must be 16 bytes or less, otherwise the caller receives an error. + * You can optionally pass NULL for this parameter, in which case a unique + * name will be assigned. And you can call NvRmTransporGetPortName to retrieve + * the name. + * @param RecvMessageSemaphore The externally created semaphore that the + * transport connection will signal upon receipt of a message. + * @param phTransport Points to the location where the transport handle shall + * be stored + * + * @retval NvSuccess Transport endpoint successfully allocated + * @retval NvError_InsufficientMemory Not enough memory to allocate endpoint + * @retval NvError_MutexCreateFailed Creaion of mutex failed. + * @retval NvError_SemaphoreCreateFailed Creaion of semaphore failed. + * @retval NvError_SharedMemAllocFailed Creaion of shared memory allocation + * failed. + * @retval NvError_NotInitialized The transport is not able to initialzed the + * threads. + */ + + NvError NvRmTransportOpen( + NvRmDeviceHandle hRmDevice, + char * pPortName, + NvOsSemaphoreHandle RecvMessageSemaphore, + NvRmTransportHandle * phTransport ); + +/** + * Retrieve the name associated with a port. + * + * Assert in debug mode encountered if PortName is too long or does not exist + * + * @see NvRmTransportOpen() + * + * @param hTransport Handle to the port that you want the name of. + * @param PortName A character string that identifies the name of the port. + * @param PortNameSize Length of the PortName buffer. + * + */ + + void NvRmTransportGetPortName( + NvRmTransportHandle hTransport, + NvU8 * PortName, + NvU32 PortNameSize ); + +/** + * Closes a transport connection. Proper closure of this connection requires + * that both the client and service call this API. Therefore, it is expected + * that the client and service message one another to coordinate the close. + * + * @see NvRmTransportOpen() + * + * @param hTransport Specifies the transport connection to close. If hTransport + * is NULL, this API does nothing. + */ + + void NvRmTransportClose( + NvRmTransportHandle hTransport ); + +/** + * Initializes the transport. + * + * @param hRmDevice Handle to RM device + * + */ + + NvError NvRmTransportInit( + NvRmDeviceHandle hRmDevice ); + +/** + * Deinitializes the transport. + * + * @param hRmDevice Handle to RM device + * + */ + + void NvRmTransportDeInit( + NvRmDeviceHandle hRmDevice ); + +/** + * This handshake API is called by the service, which waits for a client to + * establish a connection via a call to NvRmTransportConnect(). Messages + * cannot be sent and received until this handshake is completed. + * + * To ensure a client has sufficient opportunity to establish a connection + * from the other end, a large timeout value (such as NV_WAIT_INFINITE) is + * recommended here. + * + * @see NvRmTransportConnect() + * + * @param hTransport Specifies the transport connection + * @param TimeoutMS Specifies the amount of time (in milliseconds) to wait for + * connection to be established. A value of NV_WAIT_INFINITE means "wait + * indefinitely." A value of zero (0) will timeout immediately, which is + * not recommended for this function call. + * + * @retval NvSuccess Service is waiting to receive a "connect" from client + * @retval NvError_NotInitialized hTransport is not open + * @retval NvError_Timeout Timed out waiting for service to respond + */ + + NvError NvRmTransportWaitForConnect( + NvRmTransportHandle hTransport, + NvU32 TimeoutMS ); + +/** + * This blocking handshake API is called by the client, which seeks a + * service (as specified by a handle) to establish a connection. Messages + * cannot be sent and received until this handshake is completed. + * + * @see NvRmTransportWaitForConnect() + * + * @param hTransport Specifies the transport connection + * @param TimeoutMS Specifies the amount of time (in milliseconds) to wait for + * connection to be established. A value of NV_WAIT_INFINITE means "wait + * indefinitely." A value of zero (0) will timeout immediately, but + * this function will at least take time to check if the port is open and + * waiting for a connection--if so, a connection will be established. + * + * @retval NvSuccess Transport connection successfully established + * @retval NvError_NotInitialized hTransport is not open + * @retval NvError_Timeout Timed out waiting for service to respond. + */ + + NvError NvRmTransportConnect( + NvRmTransportHandle hTransport, + NvU32 TimeoutMS ); + +/** + * Set the max size of the message queue (FIFO) deptha nd length which can be + * send and receive from this port. The programmer must decide the + * queue depth that's appropriate for their design. If this function is not + * called, the queue depth is set to one (1) and message size is 256 bytes. + * + * + * @see NvRmTransportSendMsg() + * @see NvRmTransportRecvMsg() + * + * @param hTransport Specifies the transport connection + * @param MaxQueueDepth The maximum number of message which can be queued for + * this port for receiving and sending. The receive message can queue message + * till this count for this port. If receive queue is full for this port and + * if other port send the message to this port then receive queue error status + * will turn as overrun and ignore the incoming message. + * If send message queue is full and client request to send message then he + * will wait for time provided by the parameter. + * @param MaxMessageSize Specifies the maximum size of the message in bytes + * which client can receive and transmit through this port. + * + * @retval NvSuccess New queue depth is set + * @retval NvError_NotInitialized hTransport is not open. + * @retval NvError_BadValue The parameter passed is not correct. There is + * limitation for maximum message q and message length from the driver and if + * this parameter is larger than those value then it returns this error. + * + */ + + NvError NvRmTransportSetQueueDepth( + NvRmTransportHandle hTransport, + NvU32 MaxQueueDepth, + NvU32 MaxMessageSize ); + +/** + * Sends a message to the other port which is connected to this port. + * This will use the copy method to copy the client buffer message to + * transport message buffer. This function queue the message to the transmit + * queue. the data will be send later based on the physical transfer channel + * availablity. + * + * @see NvRmTransportOpen() + * @see NvRmTransportSetQueueDepth() + * @see NvRmTransportRecvMsg() + * + * @param hTransport Specifies the transport connection + * @param pMessageBuffer The pointer to the message buffer where message which + * need to be send is available. + * @param MessageSize Specifies the size of the message. + * @param TimeoutMS Specifies the amount of time (in milliseconds) to wait for + * sent message to be queued for the transfer. If the transmit queue if full + * then this function will block the client till maximum of timeout to queue + * this message. If meesage queue is available before timeout then it will + * queue the message and comeout. If message queue is full and timeout happen + * the it will return the timeout error. + * if zero timeout is selecetd and the message queue is full then it will be + * return NvError_TransportMessageBoxFull error. + * Avalue of NV_WAIT_INFINITE means "wait indefinitely" for queueing the + * message. + * + * @retval NvSuccess Message is queued successfully. + * @retval NvError_NotInitialized hTransport is not open. + * @retval NvError_BadValue The parameter passed is not valid. + * @retval NvError_InvalidState The port is not connected to the other port and + * it is not ready for sending the message. + * @retval NvError_Timeout Timed out waiting for message to be queue if send + * message queue. + * @retval NvError_TransportMessageBoxFull Message box is full and it is not + * able to queue the message. + */ + + NvError NvRmTransportSendMsg( + NvRmTransportHandle hTransport, + void* pMessageBuffer, + NvU32 MessageSize, + NvU32 TimeoutMS ); + +/** + * Sends a message to the other port which is connected to this port. + * This function is to be used ONLY when we're about to enter LP0! + * There is no synchronization in this function as only one person + * should be talking to the AVP at the time of LP0. The message is sent + * on the RPC_AVP_PORT. In the future, there might be instances where + * we need to talk on a different port in LP0. + * + * @retval NvSuccess Message is queued successfully. + * @retval NvError_TransportMessageBoxFull Message box is full and it is not + * able to queue the message. + */ + + NvError NvRmTransportSendMsgInLP0( + NvRmTransportHandle hPort, + void* message, + NvU32 MessageSize ); + +/** + * Receive the message from the port. This will read the message if it is + * available for this port otherwise it will return the + * NvError_TransportMessageBoxEmpty error. + * + * @see NvRmTransportOpen() + * @see NvRmTransportSetQueueDepth() + * @see NvRmTransportSendMsg() + * + * @param hTransport Specifies the transport connection + * @param pMessageBuffer The pointer to the receive message buffer where the + * received message will be copied. + * @param MaxSize The maximum size in bytes that may be copied to the buffer + * @param pMessageSize Pointer to the variable where the length of the message + * will be stored. + * + * @retval NvSuccess Message received successfully. + * @retval NvError_NotInitialized hTransport is not open. + * @retval NvError_InvalidState The port is not connection state. + * @retval NvError_TransportMessageBoxEmpty The message box empty and not able + * to receive the message. + * @retval NvError_TransportIncompleteMessage The received message for this + * port is longer than the configured message length for this port. It copied + * the maximm size of the configured length of the message for this port and + * return the incomplete message buffer. + * @retval NvError_TransportMessageOverflow The port receives the message more + * than the configured queue depth count for this port and hence message + * overflow has been ocuured. + */ + + NvError NvRmTransportRecvMsg( + NvRmTransportHandle hTransport, + void* pMessageBuffer, + NvU32 MaxSize, + NvU32 * pMessageSize ); + +#if defined(__cplusplus) +} +#endif + +#endif |