klipper-dgus/lib/pru_rpmsg/include/pru_virtqueue.h

/*
 * Copyright (C) 2016 Texas Instruments Incorporated - http://www.ti.com/
 *
 *
 * 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 Texas Instruments Incorporated 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
 * OWNER 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	:	pru_virtqueue.h
*
*  Summary	:	A virtual queue interface to simplify vring usage.
*
*  Notes	:
*  - This file implements the vring functions needed by the PRU core
*  - The PRU core is considered the slave and the ARM core is considered the
*    host
*  - The ARM host always adds *available* buffers to send/receive, while the
*    PRU slave always adds *used* buffers to send/receive.
*  - The logic for the PRU side is summarized below:
*
*    PRU Slave:
*    - To receive buffer from the ARM host:
*          virtqueue_getAvailBuf(vq_slave);
*              >> empty data from buf <<
*          virtqueue_addUsedBuf(vq_slave);
*          virtqueue_kick(vq_slave);
*    - To send buffer to the host:
*          virtqueue_getAvailBuf(vq_host);
*              >> copy data into buf <<
*          virtqueue_addUsedBuf(vq_host);
*          virtqueue_kick(vq_host);
*/

#ifndef _PRU_VIRTQUEUE_H_
#define _PRU_VIRTQUEUE_H_

#include <rsc_types.h>
#include <pru_virtio_ring.h>

/* Return value indicating no kick was sent */
#define PRU_VIRTQUEUE_NO_KICK			1
/* Return value indicating success */
#define PRU_VIRTQUEUE_SUCCESS			0
/* Return value indicating there were no available buffers */
#define PRU_VIRTQUEUE_NO_BUF_AVAILABLE		-1
/* Return value indicating that an invalid head index was given */
#define PRU_VIRTQUEUE_INVALID_HEAD		-2

/**
 * Summary	:	pru_virtqueue is a structure that encapsulates everything
 *			needed for a 'virtual queue'. This structure wraps a vring
 *			with extra information that is needed by the application
 *			in order to use the vring.
 *
 * Variables	:	id: The notification ID of the vring. 
 *			to_arm_event: The PRU-ICSS system event that signals the ARM.
 *			from_arm_event: The PRU-ICSS system event that the ARM uses to
 *					signal the PRU.
 *			last_avail_idx: A local running counter that is used by the
 *					PRU to determine whether or not a new
 *					available buffer has been added to the
 *					vring.
 *			vring: The underlying virtio structure that is being used
 *			       to pass buffers back and forth between the ARM and
 *			       PRU. See pru_virtio_ring.h.
 */
struct pru_virtqueue {
	uint32_t	id;
	uint32_t	to_arm_event;
	uint32_t	from_arm_event;
	uint16_t 	last_avail_idx;
	struct vring 	vring;
};

/**
* Summary	:	pru_virtqueue_init initializes the pru_virtqueue structure
*			with values from the resource table.
*
* Parameters	:	vq: a pointer to a pru_virtqueue structure that will be
*			    initialized
*			vring: a pointer to a vring that is populated and returned
*			       by the ARM host through the resource table (the id,
*			       number of descriptors, address of the vring, and
*			       alignment information are contained in this vring
*			       pointer's structure
*			to_arm_event: the PRU-ICSS system event to trigger in order to
*				      'kick' the ARM host when sending data
*			from_arm_event: the PRU-ICSS system event to check
*					for data arriving from the ARM host
*
* Description	:	This function initializes the pru_virtqueue (vq) with input
*			values from the vring in the resource table. This function
*			should be called once for each virtqueue/vring. After
*			initialization the pru_virtqueue pointer, vq, should be
*			passed to the other functions in this header file.
*
* Return Value	:	No return value.
*/
void pru_virtqueue_init(
	struct pru_virtqueue 		*vq,
	struct fw_rsc_vdev_vring 	*vring,
	uint32_t 			to_arm_event,
	uint32_t 			from_arm_event
);

/**
* Summary	:	pru_virtqueue_get_avail_buf - gets the next available
*			buffer from the pru_virtqueue specified in vq.
*
* Parameters	:	vq: pointer to the pru_virtqueue from which the available
*			    buffer should be retrieved
*			buf: pointer to be filled with the address of the available
*			     buffer
*			len: pointer to be filled with the length of the available
*			     buffer
*
* Description	:	This function compares our last_avail_idx running counter
*			against the vring.avail->idx value to see if there is a
*			buffer available that we have not used. If our last
*			available index running counter matches the vring.avail->idx
*			value then there have been no new available buffers added
*			by the host. If the two indices do not match then the host
*			has added new buffers and and we can set @buf to point to
*			the available buffer and @len to match the available buffers
*			length. If an available buffer is found we increment out
*			last_avail_idx to show that we used another buffer.
*
* Return Value	:	PRU_VIRTQUEUE_NO_BUF_AVAILABLE if no buffer available.
*			Returns the vring.desc index of the available buffer
*			otherwise.
*/
int16_t pru_virtqueue_get_avail_buf(
    struct pru_virtqueue	*vq,
    void			**buf,
    uint32_t			*len
);

/**
* Summary	:	pru_virtqueue_add_used_buf adds a used buffer to the
*			pru_virtqueue specified in vq.
*
* Parameters	:	vq: pointer to the pru_virtqueue where the used buffer
*			    should be added
*			head: vring.desc[] index of the used buffer
*			len: length of the used buffer being added
*
* Description	:	This function makes sure that the head vring.desc index
*			(head) is a valid index. If the index is valid, then the
*			buffer is added to the used list in the vring contained by
*			the pru_virtqueue (vq).
*
* Return Value	:	PRU_VIRTQUEUE_INVALID_HEAD if head is an invalid index for
*			the vring.desc array. Returns PRU_VIRTQUEUE_SUCCESS
*			otherwise.
*/
int16_t pru_virtqueue_add_used_buf(
    struct pru_virtqueue	*vq,
    int16_t			head,
    uint32_t			len
);

/**
* Summary	:	pru_virtqueue_kick sends a notification to the remote
*			processor that the PRU has added a buffer to the
*			pru_virtqueue.
*
* Parameters	:	vq: pointer to the pru_virtqueue that is to be kicked
*
* Description	:	This function is used by the PRU to notify the ARM host in
*			two situations:
*				1.	That the PRU has consumed a buffer that the ARM
*					host sent through the slave pru_virtqueue
*				2.	That the PRU has sent a buffer to the ARM through
*					the host pru_virtqueue
*			If the pru_virtqueue's VRING_AVAIL_F_NO_INTERRUPT flag is
*			set then the pru does not kick the pru_virtqueue.
*
* Return Value	:	PRU_VIRTQUEUE_NO_KICK if the VRING_AVAIL_F_NO_INTERRUPT
*			flag is set or PRU_VIRTQUEUE_SUCCESS otherwise.
*/
int16_t pru_virtqueue_kick(
    struct pru_virtqueue	*vq
);

#endif /* _PRU_VIRTQUEUE_H_ */