sof/lib/ams.h

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright (c) 2023 Intel Corporation
 *
 * Author: Krzysztof Frydryk <krzysztofx.frydryk@intel.com>
 */

#ifndef __SOF_LIB_AMS_H__
#define __SOF_LIB_AMS_H__

#include <errno.h>
#include <rtos/task.h>
#include <ipc/topology.h>
#include <rtos/alloc.h>
#include <sof/coherent.h>
#include <sof/lib/uuid.h>

/* Reserved value "does not exist" or "unassigned" value for msg types */
#define AMS_INVALID_MSG_TYPE 0
/* Reserved value "does not exist" or "unassigned" value for slots */
#define AMS_INVALID_SLOT 0xFF
/* Wildcard for module_id and instance_id values */
#define AMS_ANY_ID 0xFFFF

/* max number of message UUIDs */
#define AMS_SERVICE_UUID_TABLE_SIZE 16
/* max number of async message routes */
#define AMS_ROUTING_TABLE_SIZE 16
/* Space allocated for async message content*/
#define AMS_MAX_MSG_SIZE 0x1000

/* Size of slots message, module id and instance id */
#define AMS_SLOT_SIZE(msg) (AMS_MESSAGE_SIZE(msg) + sizeof(uint16_t) * 2)
#define AMS_MESSAGE_SIZE(msg) (sizeof(*msg) - sizeof(char) + (sizeof(char) * (msg->message_length)))

/**
 * \brief IXC message payload
 *
 * ams_message_payload - contains the actual Async Msg payload
 */
struct ams_message_payload {
	/* Message IDs are assigned dynamically on new message entry creation
	 * For a new payload should be acquired by ams_get_message_type_id
	 */
	uint32_t message_type_id;
	/* Producers module ID */
	uint16_t producer_module_id;
	/* Producers instance ID */
	uint16_t producer_instance_id;
	/* Message length */
	uint32_t message_length;
	/* Message payload */
	uint8_t *message;
};

struct ams_slot {
	uint16_t module_id;
	uint16_t instance_id;
	union {
		struct ams_message_payload msg;
		uint8_t msg_raw[AMS_MAX_MSG_SIZE];
	} u;
	uint32_t __aligned(PLATFORM_DCACHE_ALIGN) pad[];
};

/**
 * \brief ams_msg_callback_fn
 *
 * Each subscriber provides this handler function for each message ID
 */
typedef void (*ams_msg_callback_fn)(const struct ams_message_payload *const ams_message_payload,
				    void *ctx);

/**
 * \brief Internal struct ams_consumer_entry
 *
 * Describes a single consumer's subscription to a single message.
 * Array of 'ams_consumer_entry' structs forms AsyncMessageService's routing
 * table which allows for message dispatch.
 */
struct ams_consumer_entry {
	/* Message ID that will be routed via this entry */
	uint32_t message_type_id;
	/* Callback provided by the subscribed consumer */
	ams_msg_callback_fn consumer_callback;
	/* Additional context for consumer_callback (optional) */
	void *ctx;
	/* Subscribed consumer's Module ID */
	uint16_t consumer_module_id;
	/* Subscribed consumer's Module Instance ID */
	uint8_t consumer_instance_id;
	/* Subscribed consumer's Module core id. Saved to speed up routing */
	uint8_t consumer_core_id;
};

struct ams_producer {
	/* Message ID that will be routed via this entry */
	uint32_t message_type_id;
	/* Subscribed producer's Module ID */
	uint16_t producer_module_id;
	/* Subscribed producer's Module Instance ID */
	uint8_t producer_instance_id;
};

struct uuid_idx {
	uint32_t message_type_id;
	uint8_t message_uuid[UUID_SIZE];
};

struct ams_shared_context {
	/* should be only used with ams_acquire/release function, not generic ones */
	struct coherent c;

	uint32_t last_used_msg_id;
	struct ams_consumer_entry rt_table[AMS_ROUTING_TABLE_SIZE];
	struct ams_producer producer_table[AMS_ROUTING_TABLE_SIZE];
	struct uuid_idx uuid_table[AMS_SERVICE_UUID_TABLE_SIZE];

	uint32_t slot_uses[CONFIG_CORE_COUNT];
	/* marks which core already processed slot */
	uint32_t slot_done[CONFIG_CORE_COUNT];

	struct ams_slot slots[CONFIG_CORE_COUNT];
};

struct ams_context {
	/* shared context must be always accessed with shared->c taken */
	struct ams_shared_context *shared;
};

struct ams_task {
	struct task ams_task;
	struct async_message_service *ams;
	uint32_t pending_slots;
};

struct async_message_service {
#if CONFIG_SMP
	struct ams_task ams_task;
#endif /* CONFIG_SMP */
	struct ams_context *ams_context;
};

#if CONFIG_AMS
int ams_init(void);

/**
 * \brief Get Message Type ID
 *
 * assigns and returns a message type ID for specified message UUID.
 * The value of message type ID is dynamically assigned and it will change between runs.
 *
 * \param[in] message_uuid UUID of message type
 * \param[in] message_type_id Unique message type ID assigned by AMS
 */
int ams_get_message_type_id(const uint8_t *message_uuid,
			    uint32_t *message_type_id);

/**
 * \brief Producer Register
 *
 * registers a producer of asynchronous messages of given message type.
 * When a module instance calls this function,
 * it informs the Asynchronous Messaging Service that it will be sending asynchronous messages.
 *
 * \param[in] message_type_id unique message type ID assigned during ams_get_message_type_id
 * \param[in] module_id Module ID of module calling function
 * \param[in] instance_id Instance ID of module calling function
 */
int ams_register_producer(uint32_t message_type_id,
			  uint16_t module_id,
			  uint16_t instance_id);

/**
 * \brief Producer Unregister
 *
 * unregisters a producer of asynchronous messages of given type.
 * When a module instance calls this function,
 * it informs the Asynchronous Messaging Service
 * that it will not be sending asynchronous messages anymore.
 *
 * \param[in] message_type_id unique message type ID assigned during ams_get_message_type_id
 * \param[in] module_id Module ID of module calling function
 * \param[in] instance_id Instance ID of module calling function
 */
int ams_unregister_producer(uint32_t message_type_id,
			    uint16_t module_id,
			    uint16_t instance_id);

/**
 * \brief Register Consumer
 *
 * Registers a module instance as a consumer of specified message type.
 * When specified message type is sent,
 * a callback is called that was provided during registration process.
 *
 * The consumer callback is triggered when ams_send function was used to send a message
 * and/or when ams_send_mi function with consumer's module ID and instance ID was used
 * to send a message.
 *
 * \param[in] message_type_id unique message type ID assigned during ams_get_message_type_id
 * \param[in] module_id Module ID of module calling function
 * \param[in] instance_id Instance ID of module calling function
 * \param[in] function callback that should be called when message is received
 * \param[in] ctx Optional context that is passed to callback
 */
int ams_register_consumer(uint32_t message_type_id,
			  uint16_t module_id,
			  uint16_t instance_id,
			  ams_msg_callback_fn function,
			  void *ctx);

/**
 * \brief Unegister Consumer
 *
 * Unregisters a consumer of specified message type
 *
 * \param[in] message_type_id unique message type ID assigned during ams_get_message_type_id
 * \param[in] module_id Module ID of module calling function
 * \param[in] instance_id Instance ID of module calling function
 * \param[in] function callback that should be called when message is received
 */
int ams_unregister_consumer(uint32_t message_type_id,
			    uint16_t module_id,
			    uint16_t instance_id,
			    ams_msg_callback_fn function);

/**
 * \brief Message Send
 *
 * Sends asynchronous message to all registered consumers by registered producer.
 * The consumers registered on the same core may be called in context of a message producer
 *
 * \param[in] payload Message payload
 */
int ams_send(const struct ams_message_payload *payload);

/**
 * \brief Message Send to Module Instance
 *
 * Sends asynchronous message to specified module instance.
 * The consumer registered on the same core may be called in context of a message producer
 *
 * \param[in] payload Message payload
 * \param[in] module_id Module ID of consumer that messages is sent to
 * \param[in] instance_id Instance ID of consumer that messages is sent to
 */
int ams_send_mi(const struct ams_message_payload *payload,
		uint16_t module_id, uint16_t instance_id);

static inline struct ams_shared_context *ams_ctx_get(void)
{
	return sof_get()->ams_shared_ctx;
}
#else
static inline int ams_init(void) { return 0; }
static inline int ams_get_message_type_id(const uint8_t *message_uuid,
					  uint32_t *message_type_id) { return 0; }

static inline int ams_register_producer(uint32_t message_type_id,
					uint16_t module_id,
					uint16_t instance_id) { return 0; }

static inline int ams_unregister_producer(uint32_t message_type_id,
					  uint16_t module_id,
					  uint16_t instance_id) { return 0; }

static inline int ams_register_consumer(uint32_t message_type_id,
					uint16_t module_id,
					uint16_t instance_id,
					ams_msg_callback_fn function,
					void *ctx) { return 0; }

static inline int ams_unregister_consumer(uint32_t message_type_id,
					  uint16_t module_id,
					  uint16_t instance_id,
					  ams_msg_callback_fn function) { return 0; }

static inline int ams_send(const struct ams_message_payload *payload) { return 0; }

static inline int ams_send_mi(const struct ams_message_payload *payload, uint16_t module_id,
			      uint16_t instance_id) { return 0; }

static inline struct ams_shared_context *ams_ctx_get(void)
{
	return NULL;
}

#endif /* CONFIG_AMS */

#if CONFIG_SMP && CONFIG_AMS
int process_incoming_message(uint32_t slot);
#else
static inline int process_incoming_message(uint32_t slot) { return 0; }
#endif /* CONFIG_SMP && CONFIG_AMS */

struct async_message_service **arch_ams_get(void);

#endif /* __SOF_LIB_AMS_H__ */