1 /*
2 * \brief Protection domain (PD) session interface
3 * \author Christian Helmuth
4 * \author Norman Feske
5 * \date 2006-06-27
6 *
7 * A pd session represents the protection domain of a program.
8 */
9
10 /*
11 * Copyright (C) 2006-2013 Genode Labs GmbH
12 *
13 * This file is part of the Genode OS framework, which is distributed
14 * under the terms of the GNU General Public License version 2.
15 */
16
17 #ifndef _INCLUDE__PD_SESSION__PD_SESSION_H_
18 #define _INCLUDE__PD_SESSION__PD_SESSION_H_
19
20 #include <base/exception.h>
21 #include <thread/capability.h>
22 #include <session/session.h>
23 #include <signal_source/signal_source.h>
24
25 namespace Genode {
26
27 struct Pd_session;
28 struct Parent;
29 struct Signal_context;
30 }
31
32
33 struct Genode::Pd_session : Session
34 {
35 static const char *service_name() { return "PD"}
36
37 virtual ~Pd_session() { }
38
39 /**
40 * Bind thread to protection domain
41 *
42 * \param thread capability of thread to bind
43 *
44 * \return 0 on success or negative error code
45 *
46 * After successful bind, the thread will execute inside this
47 * protection domain when started.
48 */
49 virtual int bind_thread(Thread_capability thread) = 0
50
51 /**
52 * Assign parent to protection domain
53 *
54 * \param parent capability of parent interface
55 * \return 0 on success, or negative error code
56 */
57 virtual int assign_parent(Capability<Parent>parent) = 0
58
59 /**
60 * Assign PCI device to PD
61 *
62 * The specified address has to refer to the locally mapped PCI
63 * configuration space of the device.
64 *
65 * This function is solely used on the NOVA kernel.
66 */
67 virtual bool assign_pci(addr_t pci_config_memory_address, uint16_t bdf) = 0
68
69
70 /********************************
71 ** Support for the signal API **
72 ********************************/
73
74 typedef Capability<Signal_source>Signal_source_capability;
75
76 class Out_of_metadata : public Exception{ }
77 class Invalid_signal_source : public Exception{ }
78
79 /**
80 * Create a new signal source
81 *
82 * \return a cap that acts as reference to the created source
83 *
84 * The signal source provides an interface to wait for incoming signals.
85 *
86 * \throw Out_of_metadata
87 */
88 virtual Signal_source_capability alloc_signal_source() = 0
89
90 /**
91 * Free a signal source
92 *
93 * \param cap capability of the signal source to destroy
94 */
95 virtual void free_signal_source(Signal_source_capability cap) = 0
96
97 /**
98 * Allocate signal context
99 *
100 * \param source signal source that shall provide the new context
101 *
102 *
103 * \param imprint opaque value that gets delivered with signals
104 * originating from the allocated signal-context capability
105 * \return new signal-context capability
106 *
107 * \throw Out_of_metadata
108 * \throw Invalid_signal_source
109 */
110 virtual Capability<Signal_context>
111 alloc_context(Signal_source_capability source, unsigned long imprint) = 0
112
113 /**
114 * Free signal-context
115 *
116 * \param cap capability of signal-context to release
117 */
118 virtual void free_context(Capability<Signal_context>cap) = 0
119
120 /**
121 * Submit signals to the specified signal context
122 *
123 * \param context signal destination
124 * \param cnt number of signals to submit at once
125 *
126 * The `context` argument does not necessarily belong to this PD session.
127 * Normally, it is a capability obtained from a potentially untrusted
128 * component. Because we cannot trust this capability, signals are not
129 * submitted by invoking `cap` directly but by using it as argument to our
130 * trusted PD-session interface. Otherwise, a potential signal receiver
131 * could supply a capability with a blocking interface to compromise the
132 * nonblocking behaviour of the signal submission.
133 */
134 virtual void submit(Capability<Signal_context>context, unsigned cnt = 1) = 0
135
136
137 /***********************************
138 ** Support for the RPC framework **
139 ***********************************/
140
141 /**
142 * Allocate new RPC-object capability
143 *
144 * \param ep entry point that will use this capability
145 *
146 * \throw Out_of_metadata if meta-data backing store is exhausted
147 *
148 * \return new RPC capability
149 */
150 virtual Native_capability alloc_rpc_cap(Native_capability ep) = 0
151
152 /**
153 * Free RPC-object capability
154 *
155 * \param cap capability to free
156 */
157 virtual void free_rpc_cap(Native_capability cap) = 0
158
159
160 /*****************************************
161 ** Access to kernel-specific interface **
162 *****************************************/
163
164 /**
165 * Common base class of kernel-specific PD interfaces
166 */
167 struct Native_pd { }
168
169 /**
170 * Return capability to kernel-specific PD operations
171 */
172 virtual Capability<Native_pd>native_pd() = 0
173
174
175 /*********************
176 ** RPC declaration **
177 *********************/
178
179 GENODE_RPC(Rpc_bind_thread, int, bind_thread, Thread_capability)
180 GENODE_RPC(Rpc_assign_parent, int, assign_parent, Capability<Parent>)
181 GENODE_RPC(Rpc_assign_pci, bool, assign_pci, addr_t, uint16_t)
182
183 GENODE_RPC_THROW(Rpc_alloc_signal_source, Signal_source_capability,
184 alloc_signal_source, GENODE_TYPE_LIST(Out_of_metadata))
185
186 GENODE_RPC(Rpc_free_signal_source, void, free_signal_source, Signal_source_capability)
187
188 GENODE_RPC_THROW(Rpc_alloc_context, Capability<Signal_context>, alloc_context,
189 GENODE_TYPE_LIST(Out_of_metadata, Invalid_signal_source),
190 Signal_source_capability, unsigned long)
191
192 GENODE_RPC(Rpc_free_context, void, free_context,
193 Capability<Signal_context>)
194
195 GENODE_RPC(Rpc_submit, void, submit, Capability<Signal_context>, unsigned)
196
197 GENODE_RPC_THROW(Rpc_alloc_rpc_cap, Native_capability, alloc_rpc_cap,
198 GENODE_TYPE_LIST(Out_of_metadata), Native_capability)
199
200 GENODE_RPC(Rpc_free_rpc_cap, void, free_rpc_cap, Native_capability)
201
202 GENODE_RPC(Rpc_native_pd, Capability<Native_pd>, native_pd)
203
204 /*
205 * Manual definition of `Rpc_functions`, see the comment in cpu_session.h.
206 */
207 typedef Meta::Type_tuple<Rpc_bind_thread,
208 Meta::Type_tuple<Rpc_assign_parent,
209 Meta::Type_tuple<Rpc_assign_pci,
210 Meta::Type_tuple<Rpc_alloc_signal_source,
211 Meta::Type_tuple<Rpc_free_signal_source,
212 Meta::Type_tuple<Rpc_alloc_context,
213 Meta::Type_tuple<Rpc_free_context,
214 Meta::Type_tuple<Rpc_submit,
215 Meta::Type_tuple<Rpc_alloc_rpc_cap,
216 Meta::Type_tuple<Rpc_free_rpc_cap,
217 Meta::Type_tuple<Rpc_native_pd,
218 Meta::Empty>
219 >>>>>>>>>>Rpc_functions;
220 }
221
222 #endif /* _INCLUDE__PD_SESSION__PD_SESSION_H_ */