/*
 * Copyright (C) 2022 Apple Inc. All rights reserved.
 *
 * This document is the property of Apple Inc.
 * It is considered confidential and proprietary.
 *
 * This document may not be reproduced or transmitted in any form,
 * in whole or in part, without the express written permission of
 * Apple Inc.
 */

#pragma once

#if defined(KERNEL) || defined(XRT_HOSTED_INCLUDE)

#include <stddef.h>
#include <stdbool.h>
#include <xrt_hosted_types/messages.h>
#include <xrt_hosted_types/structures.h>

/**
 * @brief Initialise with the shared region
 * @param version Current version of the host
 * @param base Virtual address at which shared physical base is mapped
 * @param[out] error State in which to store error information (optional)
 * @returns whether validation passed and library initialised
 */
typedef bool
XrtHosted_init_f(
    XrtHosted_Version_t version,
    uintptr_t base,
    XrtHosted_Error_t * _Nullable error
);

/** @brief Get the number of frames described by the root */
typedef size_t
XrtHosted_frames_f(void);

/** @brief Get the number of cores described by the root */
typedef size_t
XrtHosted_cores_f(void);

/**
 * @brief Get the physical address of the subsequent shared memory frame
 * @param mapped Virtually mapped page to read from (must be exactly 1 page)
 * @param[in,out] index Index of frame in shared region
 * @param next Physical address of following page
 * @param[out] error State in which to store error information (optional)
 */
typedef bool
XrtHosted_nextPhys_f(
    XrtHosted_Mapped_t * _Nonnull mapped,
    size_t * _Nonnull index,
    XrtHosted_Phys_t * _Nonnull next,
    XrtHosted_Error_t * _Nullable error
);

/** @brief Initialise references to mapped structures */
typedef void
XrtHosted_setMapping_f(XrtHosted_Region_t region);

/** @brief The global shared region data */
typedef XrtHosted_Global_t * _Nonnull
XrtHosted_global_f(void);

/** @brief The state for a particular core */
typedef XrtHosted_Core_t * _Nonnull
XrtHosted_core_f(size_t core);

/** @brief The request buffer for a particular core */
typedef XrtHosted_Buffer_t * _Nonnull
XrtHosted_Core_request_f(size_t core);

/** @brief The response buffer for a particular core */
typedef XrtHosted_Buffer_t * _Nonnull
XrtHosted_Core_response_f(size_t core);

/** @section Version support querying */

/** @brief The version at which a given request tag was introduced */
typedef XrtHosted_Version_t XrtHosted_AttrConst
XrtHosted_Request_introduced_f(XrtHosted_Request_Tag_t tag);

/** @brief The version at which a given response tag was introduced */
typedef XrtHosted_Version_t XrtHosted_AttrConst
XrtHosted_Response_introduced_f(XrtHosted_Response_Tag_t tag);

/** @section Callback structure */

typedef struct XrtHosted_Callbacks {
    /** @brief Callbacks introduced up to version 1*/
    struct {
        XrtHosted_init_f * _Nonnull init;
        XrtHosted_frames_f * _Nonnull frames;
        XrtHosted_cores_f * _Nonnull cores;
        XrtHosted_nextPhys_f * _Nonnull nextPhys;
        XrtHosted_setMapping_f * _Nonnull setMapping;
        XrtHosted_global_f * _Nonnull global;
        XrtHosted_core_f * _Nonnull core;
        struct {
            XrtHosted_Core_request_f * _Nonnull request;
            XrtHosted_Core_response_f * _Nonnull response;
        } Core;
        struct {
            XrtHosted_Message_introduced_f * _Nonnull introduced;
        } Message;
        struct {
            XrtHosted_Request_toMessageTag_f * _Nonnull toMessageTag;
            XrtHosted_Request_introduced_f * _Nonnull introduced;
            XrtHosted_Request_encode_f * _Nonnull encode;
            XrtHosted_Request_decode_f * _Nonnull decode;
        } Request;
        struct {
            XrtHosted_Response_toMessageTag_f * _Nonnull toMessageTag;
            XrtHosted_Response_introduced_f * _Nonnull introduced;
            XrtHosted_Response_encode_f * _Nonnull encode;
            XrtHosted_Response_decode_f * _Nonnull decode;
        } Response;
    } v1;
} XrtHosted_Callbacks_t;

/** @section Inline functions */

/** @brief Get the epoch counter ID for a given queue */
XrtHosted_AttrUnsafePerformance
static inline XrtHosted_Counter_t
XrtHosted_Counter_fromQueueId(XrtHosted_Word_t queueId)
{
    return queueId % XrtHosted_Counter_limit;
}

/** @brief Get the epoch counter ID for a given thread */
XrtHosted_AttrUnsafePerformance
static inline XrtHosted_Counter_t
XrtHosted_Counter_fromThreadId(XrtHosted_Word_t threadId)
{
    return threadId % XrtHosted_Counter_limit;
}

#endif /* defined(KERNEL) || defined(XRT_HOSTED_INCLUDE) */