ARK-OS/arkos/kernel/drivers/accel/amdxdna/amdxdna_mailbox.h

/* SPDX-License-Identifier: GPL-2.0 */
/*
 * Copyright (C) 2022-2024, Advanced Micro Devices, Inc.
 */

#ifndef _AIE2_MAILBOX_H_
#define _AIE2_MAILBOX_H_

struct mailbox;
struct mailbox_channel;

/*
 * xdna_mailbox_msg - message struct
 *
 * @opcode:	opcode for firmware
 * @handle:	handle used for the notify callback
 * @notify_cb:  callback function to notify the sender when there is response
 * @send_data:	pointing to sending data
 * @send_size:	size of the sending data
 *
 * The mailbox will split the sending data in to multiple firmware message if
 * the size of the data is too big. This is transparent to the sender. The
 * sender will receive one notification.
 */
struct xdna_mailbox_msg {
	u32		opcode;
	void		*handle;
	int		(*notify_cb)(void *handle, void __iomem *data, size_t size);
	u8		*send_data;
	size_t		send_size;
};

/*
 * xdna_mailbox_res - mailbox hardware resource
 *
 * @ringbuf_base:	ring buffer base address
 * @ringbuf_size:	ring buffer size
 * @mbox_base:		mailbox base address
 * @mbox_size:		mailbox size
 */
struct xdna_mailbox_res {
	void __iomem	*ringbuf_base;
	size_t		ringbuf_size;
	void __iomem	*mbox_base;
	size_t		mbox_size;
	const char	*name;
};

/*
 * xdna_mailbox_chann_res - resources
 *
 * @rb_start_addr:	ring buffer start address
 * @rb_size:		ring buffer size
 * @mb_head_ptr_reg:	mailbox head pointer register
 * @mb_tail_ptr_reg:	mailbox tail pointer register
 */
struct xdna_mailbox_chann_res {
	u32 rb_start_addr;
	u32 rb_size;
	u32 mb_head_ptr_reg;
	u32 mb_tail_ptr_reg;
};

/*
 * xdna_mailbox_create() -- create mailbox subsystem and initialize
 *
 * @ddev: device pointer
 * @res: SRAM and mailbox resources
 *
 * Return: If success, return a handle of mailbox subsystem.
 * Otherwise, return NULL pointer.
 */
struct mailbox *xdnam_mailbox_create(struct drm_device *ddev,
				     const struct xdna_mailbox_res *res);

/*
 * xdna_mailbox_alloc_channel() -- alloc a mailbox channel
 *
 * @mb: mailbox handle
 */
struct mailbox_channel *xdna_mailbox_alloc_channel(struct mailbox *mb);

/*
 * xdna_mailbox_start_channel() -- start a mailbox channel instance
 *
 * @mb_chann: the handle return from xdna_mailbox_alloc_channel()
 * @x2i: host to firmware mailbox resources
 * @i2x: firmware to host mailbox resources
 * @xdna_mailbox_intr_reg: register addr of MSI-X interrupt
 * @mb_irq: Linux IRQ number associated with mailbox MSI-X interrupt vector index
 *
 * Return: If success, return a handle of mailbox channel. Otherwise, return NULL.
 */
int
xdna_mailbox_start_channel(struct mailbox_channel *mb_chann,
			   const struct xdna_mailbox_chann_res *x2i,
			   const struct xdna_mailbox_chann_res *i2x,
			   u32 xdna_mailbox_intr_reg,
			   int mb_irq);

/*
 * xdna_mailbox_free_channel() -- free mailbox channel
 *
 * @mailbox_chann: the handle return from xdna_mailbox_create_channel()
 */
void xdna_mailbox_free_channel(struct mailbox_channel *mailbox_chann);

/*
 * xdna_mailbox_stop_channel() -- stop mailbox channel
 *
 * @mailbox_chann: the handle return from xdna_mailbox_create_channel()
 */
void xdna_mailbox_stop_channel(struct mailbox_channel *mailbox_chann);

/*
 * xdna_mailbox_send_msg() -- Send a message
 *
 * @mailbox_chann: Mailbox channel handle
 * @msg: message struct for message information
 * @tx_timeout: the timeout value for sending the message in ms.
 *
 * Return: If success return 0, otherwise, return error code
 */
int xdna_mailbox_send_msg(struct mailbox_channel *mailbox_chann,
			  const struct xdna_mailbox_msg *msg, u64 tx_timeout);

#endif /* _AIE2_MAILBOX_ */