/*
 * Copyright 2017, Data61
 * Commonwealth Scientific and Industrial Research Organisation (CSIRO)
 * ABN 41 687 119 230.
 *
 * This software may be distributed and modified according to the terms of
 * the BSD 2-Clause license. Note that NO WARRANTY is provided.
 * See "LICENSE_BSD2.txt" for details.
 *
 * @TAG(DATA61_BSD)
 */

/**
 * The IRQ server helps to manage the IRQs in a system. There are 2 API levels
 * in the design:
 *   1. [irq server thread] An IRQ server node is a standalone thread which waits
 *                          for the arrival of any IRQ that is being managed by a
 *                          particular irq server node. When an IRQ is received,
 *                          the irq server thread will either forward the irq
 *                          information to a registered synchronous endpoint, or
 *                          call the appropriate handler function directly.
 *   2. [irq server]        A dynamic collection of server threads. When
 *                          registering an IRQ call back function, the irq server
 *                          will attempt to deligate the IRQ to an irq server node
 *                          that has not yet reached capacity. If no node can accept
 *                          the IRQ, it will alert the user that a new irq server
 *                          thread needs to be created to support the additional demand.
 *
 * ++ Special notes ++
 *
 * Performance
 *   The application can achieve greater performance by configuring the irq
 *   server, or irq server threads, to call the IRQ handler functions directly.
 *   This is done by not providing an endpoint in the creation of an irq server
 *   interface. The application must take care to ensure that all concurrency
 *   issues are addressed.
 *
 * Resource availability
 *   The irq server API family accept resource allocators as arguments to some
 *   function calls. These resource allocators
 *   must be kept available indefinitely.
 */

#pragma once

#include <autoconf.h>

#include <sel4/sel4.h>
#include <vspace/vspace.h>
#include <vka/vka.h>
#include <simple/simple.h>
#include <platsupport/io.h>
#include <platsupport/irq.h>
#include <sel4platsupport/irq.h>

typedef struct irq_server irq_server_t;

typedef int thread_id_t;

/**
 * Initialises an IRQ server. The server will manage threads that are
 * explicitly created by the user to handle incoming IRQs. The server
 * delegates most of the IRQ cap creation and pairing to the IRQ interface in
 * libsel4platsupport.
 * @param[in] vspace            The current vspace
 * @param[in] vka               Allocator for creating kernel objects
 * @param[in] priority          The priority of spawned threads
 * @param[in] simple            A simple interface for creating IRQ caps
 * @param[in] cspace            The cspace of the current thread
 * @param[in] delivery_ep       The endpoint to send alerts about IRQ's to
 * @param[in] label             A label to use when sending to an IPC to an endpoint
 * @param[in] nirqs             The maximum number of irqs to support
 * @return                      A valid pointer to an irq_server_t instance, otherwise NULL
 */
irq_server_t *irq_server_new(vspace_t *vspace, vka_t *vka, seL4_Word priority,
                             simple_t *simple, seL4_CPtr cspace, seL4_CPtr delivery_ep,
                             seL4_Word label, size_t num_irqs, ps_malloc_ops_t *malloc_ops);

/**
 * Creates a new thread to wait on IRQs.
 * Upon receiving a signal that an IRQ has arrived, the thread will send an IPC message
 * through to the endpoint that was registered with the IRQ server, if any. Otherwise,
 * it will call 'irq_server_handle_irq_ipc' to handle the interrupt.
 *
 * The user can provide a notification for the thread to use, and can mark which bits
 * of the badge that the thread can use for IRQs. If a null cap was provided,
 * the IRQ server can create a notification cap on behalf of the user, the 'usable_mask'
 * parameter will be ignored in this case.
 *
 * A ID will be assigned to this thread and
 * returned to the user, but the user can provide a 'hint' to IRQ server. The server will
 * attempt to assign an ID with the same value as the hint.
 * @param[in] irq_server        A handle to the IRQ server
 * @param[in] provided_ntfn     Notification cap to be provided to thread, can be
 *                              'seL4_CapNull'
 * @param[in] usable_mask       Mask of bits indicating which bits of the badge space
 *                              the thread can use, will be ignore if 'provided_ntfn' is
 *                              'null'
 * @param[in] id_hint           'Hint' to be passed to the IRQ server when assigning an
 *                              ID, >= 0 for a valid hint, -1 otherwise
 */
thread_id_t irq_server_thread_new(irq_server_t *irq_server, seL4_CPtr provided_ntfn,
                                  seL4_Word usable_mask, thread_id_t id_hint);

/**
 * Enable an IRQ and register a callback function. This functionality is
 * delegated to the IRQ interface in libplatsupport.
 * @param[in] irq_server        The IRQ server which shall be responsible for the IRQ
 * @param[in] irq               Information about the IRQ that will be registered
 * @param[in] callback          A callback function to call when the requested IRQ arrives
 * @param[in] callback_data     Client data which should be passed to the registered call
 *                              back function
 * @return                      On success, returns an ID for the IRQ that was assigned by
 *                              the IRQ interface in libsel4platsuport. Otherwise, returns
 *                              an error code
 */
irq_id_t irq_server_register_irq(irq_server_t *irq_server, ps_irq_t irq,
                                 irq_callback_fn_t callback, void *callback_data);

/**
 * Redirects control to the IRQ subsystem to process an arriving IRQ.  The
 * server will read the appropriate message registers to retrieve the
 * information that it needs. This should be called only when an IPC message
 * with the designated label was received on an endpoint that was given to an
 * IRQ server instance.
 * @param[in] irq_server   The IRQ server which is responsible for the received IRQ
 * @param[in] msginfo      An IPC message info header of an IPC message received on
 *                         an endpoint registered with an IRQ server
 */
void irq_server_handle_irq_ipc(irq_server_t *irq_server, seL4_MessageInfo_t msginfo);

/**
 * Waits on the IRQ delivery endpoint for the next IRQ. If an IPC is received, but the
 * label does not match that which was assigned to the IRQ server, the message info and
 * badge are returned to the caller, much like seL4_Recv(...). If the label does match,
 * irq_server_handle_irq_ipc(...) will be called before returning.
 *
 * If an endpoint was not registered with the IRQ server that is passed in, this function
 * is essentially a no-op.
 * @param[in]  irq_server  A handle to the IRQ server
 * @param[out] ret_badge   If badge_ret is not NULL, the received badge will be
 *                         written to badge_ret.
 * @return                 The seL4_MessageInfo_t structure as provided by the
 *                         seL4 kernel in response to a seL4_Recv call. The
 *                         caller may check that the label matches that which
 *                         was registered for the IRQ server in order to
 *                         determine if the received event was destined for the
 *                         IRQ server or if the thread was activated by some
 *                         other IPC event.
 *                         On the error case where the IRQ server passed
 *                         in does not have an endpoint passed in, an empty
 *                         seL4_MessageInfo_t struct will be returned.
 */
seL4_MessageInfo_t irq_server_wait_for_irq(irq_server_t *irq_server, seL4_Word *ret_badge);