blob: 2b948ea79245d68abaa861e82b601b8c808ab05e [file] [log] [blame]
/*
* Copyright 2019, 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 <sel4utils/gen_config.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);