1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/libipc/include/ipc/server.h Wed Aug 25 01:28:08 2021 +0200
1.3 @@ -0,0 +1,150 @@
1.4 +/*
1.5 + * Server binding/registration.
1.6 + *
1.7 + * Copyright (C) 2018, 2019, 2020, 2021 Paul Boddie <paul@boddie.org.uk>
1.8 + *
1.9 + * This program is free software; you can redistribute it and/or
1.10 + * modify it under the terms of the GNU General Public License as
1.11 + * published by the Free Software Foundation; either version 2 of
1.12 + * the License, or (at your option) any later version.
1.13 + *
1.14 + * This program is distributed in the hope that it will be useful,
1.15 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.16 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.17 + * GNU General Public License for more details.
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License
1.20 + * along with this program; if not, write to the Free Software
1.21 + * Foundation, Inc., 51 Franklin Street, Fifth Floor,
1.22 + * Boston, MA 02110-1301, USA
1.23 + */
1.24 +
1.25 +#pragma once
1.26 +
1.27 +#include <l4/sys/types.h>
1.28 +
1.29 +#include <ipc/message.h>
1.30 +
1.31 +EXTERN_C_BEGIN
1.32 +
1.33 +/* A convenience macro for invoking the server mainloop. */
1.34 +
1.35 +#define ipc_server_loop_for(TYPE, POINTER) \
1.36 + ipc_server_loop(TYPE##_expected_items, (TYPE *) POINTER, \
1.37 + (ipc_server_handler_type) handle_##TYPE)
1.38 +
1.39 +/* A handler function type. */
1.40 +
1.41 +typedef void (*ipc_server_handler_type)(ipc_message_t *, void *);
1.42 +
1.43 +/* A finaliser function type. */
1.44 +
1.45 +struct ipc_server_config_type;
1.46 +
1.47 +typedef void (*ipc_server_finaliser_type)(struct ipc_server_config_type *);
1.48 +
1.49 +/* A server configuration type. */
1.50 +
1.51 +typedef struct ipc_server_config_type
1.52 +{
1.53 + /* Component object references. C++ objects may provide different references
1.54 + for the handler (providing access to the exposed interface) and the
1.55 + finaliser (providing access to a distinct control interface). */
1.56 +
1.57 + void *handler_obj;
1.58 + void *finaliser_obj;
1.59 +
1.60 + /* Expected capability item limit for incoming messages. */
1.61 +
1.62 + int expected_items;
1.63 +
1.64 + /* Handler for incoming messages and finaliser upon deletion. */
1.65 +
1.66 + ipc_server_handler_type handler;
1.67 + ipc_server_finaliser_type finaliser;
1.68 +
1.69 + /* Create a new thread. */
1.70 +
1.71 + int new_thread;
1.72 +
1.73 + /* Thread and IPC capabilities. */
1.74 +
1.75 + l4_cap_idx_t thread;
1.76 + l4_cap_idx_t server;
1.77 +
1.78 + /* Receive deletion notifications via an IRQ. */
1.79 +
1.80 + int notifications;
1.81 + l4_cap_idx_t irq;
1.82 +
1.83 +} ipc_server_config_type;
1.84 +
1.85 +
1.86 +
1.87 +/* Associate a notification IRQ with an IPC gate in the main thread. */
1.88 +
1.89 +long ipc_server_apply_irq(l4_cap_idx_t cap, l4_cap_idx_t *irq);
1.90 +
1.91 +/* Associate a notification IRQ with an IPC gate in the given thread. */
1.92 +
1.93 +long ipc_server_apply_irq_for_thread(l4_cap_idx_t cap, l4_cap_idx_t *irq, l4_cap_idx_t thread);
1.94 +
1.95 +/* Bind the main thread to a named IPC gate capability. */
1.96 +
1.97 +long ipc_server_bind(const char *name, l4_umword_t id, l4_cap_idx_t *server);
1.98 +
1.99 +/* Create a new IPC gate for the main thread. */
1.100 +
1.101 +long ipc_server_new(l4_cap_idx_t *cap, void *obj);
1.102 +
1.103 +/* Create a new IPC gate for the given thread. */
1.104 +
1.105 +long ipc_server_new_for_thread(l4_cap_idx_t *cap, void *obj, l4_cap_idx_t thread);
1.106 +
1.107 +/* Create an IPC gate for the main thread. */
1.108 +
1.109 +long ipc_server_new_gate(l4_cap_idx_t *ref, l4_umword_t id);
1.110 +
1.111 +/* Create an IPC gate for the indicated thread. */
1.112 +
1.113 +long ipc_server_new_gate_for_thread(l4_cap_idx_t *ref, l4_cap_idx_t thread, l4_umword_t id);
1.114 +
1.115 +
1.116 +
1.117 +/* Handle incoming messages for a server. */
1.118 +
1.119 +long ipc_server_loop(int expected_items, void *obj,
1.120 + ipc_server_handler_type handler);
1.121 +
1.122 +/* Handle incoming messages and IRQ notifications for a server. */
1.123 +
1.124 +long ipc_server_managed_loop(int expected_items, void *obj, l4_cap_idx_t irq,
1.125 + ipc_server_handler_type handler);
1.126 +
1.127 +/* A pthread-compatible mainloop initiation function. */
1.128 +
1.129 +void *ipc_server_start_mainloop(void *data);
1.130 +
1.131 +/* Wait for an incoming message via a dedicated IPC gate for a thread. */
1.132 +
1.133 +l4_msgtag_t ipc_server_wait(l4_umword_t id);
1.134 +
1.135 +
1.136 +
1.137 +/* Finalise a server configuration. */
1.138 +
1.139 +void ipc_server_finalise_config(ipc_server_config_type *config);
1.140 +
1.141 +/* Discard any thread created but not initiated. */
1.142 +
1.143 +void ipc_server_discard_thread(ipc_server_config_type *config);
1.144 +
1.145 +/* Initialise a server configuration. */
1.146 +
1.147 +void ipc_server_init_config(ipc_server_config_type *config);
1.148 +
1.149 +/* Initialise and start a server using the given configuration. */
1.150 +
1.151 +long ipc_server_start_config(ipc_server_config_type *config);
1.152 +
1.153 +EXTERN_C_END