L4Re - L4 Runtime Environment
ipc.h
Go to the documentation of this file.
1 
6 /*
7  * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
8  * Alexander Warg <warg@os.inf.tu-dresden.de>,
9  * Björn Döbel <doebel@os.inf.tu-dresden.de>,
10  * Torsten Frenzel <frenzel@os.inf.tu-dresden.de>
11  * economic rights: Technische Universität Dresden (Germany)
12  *
13  * This file is part of TUD:OS and distributed under the terms of the
14  * GNU General Public License 2.
15  * Please see the COPYING-GPL-2 file for details.
16  *
17  * As a special exception, you may use this file as part of a free software
18  * library without restriction. Specifically, if other files instantiate
19  * templates or use macros or inline functions from this file, or you compile
20  * this file and link it with other files to produce an executable, this
21  * file does not by itself cause the resulting executable to be covered by
22  * the GNU General Public License. This exception does not however
23  * invalidate any other reasons why the executable file might be covered by
24  * the GNU General Public License.
25  */
26 #ifndef __L4SYS__INCLUDE__L4API_FIASCO__IPC_H__
27 #define __L4SYS__INCLUDE__L4API_FIASCO__IPC_H__
28 
29 #include <l4/sys/types.h>
30 #include <l4/sys/utcb.h>
31 #include <l4/sys/err.h>
32 
56 /*****************************************************************************
57  *** IPC result checking
58  *****************************************************************************/
59 
76 {
80  L4_IPC_ENOT_EXISTENT = 0x04,
83  L4_IPC_RETIMEOUT = 0x03,
86  L4_IPC_SETIMEOUT = 0x02,
89  L4_IPC_RECANCELED = 0x07,
92  L4_IPC_SECANCELED = 0x06,
95  L4_IPC_REMAPFAILED = 0x11,
99  L4_IPC_SEMAPFAILED = 0x10,
102  L4_IPC_RESNDPFTO = 0x0b,
106  L4_IPC_SESNDPFTO = 0x0a,
110  L4_IPC_RERCVPFTO = 0x0d,
114  L4_IPC_SERCVPFTO = 0x0c,
118  L4_IPC_REABORTED = 0x0f,
121  L4_IPC_SEABORTED = 0x0e,
124  L4_IPC_REMSGCUT = 0x09,
128  L4_IPC_SEMSGCUT = 0x08,
132 };
133 
134 
145 L4_INLINE l4_umword_t
147 
148 
158 L4_INLINE long
160 
161 L4_INLINE long
162 l4_error_u(l4_msgtag_t tag, l4_utcb_t *utcb) L4_NOTHROW;
163 
164 /*****************************************************************************
165  *** IPC results
166  *****************************************************************************/
167 
177 L4_INLINE int l4_ipc_is_snd_error(l4_utcb_t *utcb) L4_NOTHROW;
178 
188 L4_INLINE int l4_ipc_is_rcv_error(l4_utcb_t *utcb) L4_NOTHROW;
189 
199 L4_INLINE int l4_ipc_error_code(l4_utcb_t *utcb) L4_NOTHROW;
200 
207 L4_INLINE long l4_ipc_to_errno(unsigned long ipc_error_code) L4_NOTHROW;
208 
209 
210 /*****************************************************************************
211  *** IPC calls
212  *****************************************************************************/
213 
231 L4_INLINE l4_msgtag_t
233  l4_timeout_t timeout) L4_NOTHROW;
234 
235 
256 L4_INLINE l4_msgtag_t
257 l4_ipc_wait(l4_utcb_t *utcb, l4_umword_t *label,
258  l4_timeout_t timeout) L4_NOTHROW;
259 
260 
280 L4_INLINE l4_msgtag_t
282  l4_timeout_t timeout) L4_NOTHROW;
283 
300 L4_INLINE l4_msgtag_t
301 l4_ipc_call(l4_cap_idx_t object, l4_utcb_t *utcb, l4_msgtag_t tag,
302  l4_timeout_t timeout) L4_NOTHROW;
303 
304 
324 L4_INLINE l4_msgtag_t
326  l4_umword_t *label, l4_timeout_t timeout) L4_NOTHROW;
327 
347 L4_INLINE l4_msgtag_t
349  l4_umword_t *label, l4_timeout_t timeout) L4_NOTHROW;
350 
357 #if 0
358 
368 L4_INLINE l4_msgtag_t
369 l4_ipc_wait_next_period(l4_utcb_t *utcb,
370  l4_umword_t *label,
371  l4_timeout_t timeout);
372 
373 #endif
374 
390 l4_ipc(l4_cap_idx_t dest,
391  l4_utcb_t *utcb,
392  l4_umword_t flags,
393  l4_umword_t slabel,
394  l4_msgtag_t tag,
395  l4_umword_t *rlabel,
396  l4_timeout_t timeout) L4_NOTHROW;
397 
412 L4_INLINE l4_msgtag_t
414 
427 L4_INLINE int
428 l4_sndfpage_add(l4_fpage_t const snd_fpage, unsigned long snd_base,
429  l4_msgtag_t *tag) L4_NOTHROW;
430 
431 /*
432  * \internal
433  * \ingroup l4_ipc_api
434  */
435 L4_INLINE int
436 l4_sndfpage_add_u(l4_fpage_t const snd_fpage, unsigned long snd_base,
437  l4_msgtag_t *tag, l4_utcb_t *utcb) L4_NOTHROW;
438 
439 
440 /************************************************************************
441  * Implementations
442  **********************/
443 
444 L4_INLINE long l4_ipc_to_errno(unsigned long ipc_error_code) L4_NOTHROW
445 { return -(L4_EIPC_LO + ipc_error_code); }
446 
447 L4_INLINE l4_msgtag_t
449  l4_msgtag_t tag,
450  l4_timeout_t timeout) L4_NOTHROW
451 {
452  return l4_ipc(dest, utcb, L4_SYSF_CALL, 0, tag, 0, timeout);
453 }
454 
455 L4_INLINE l4_msgtag_t
457  l4_umword_t *label,
458  l4_timeout_t timeout) L4_NOTHROW
459 {
460  return l4_ipc(L4_INVALID_CAP, utcb, L4_SYSF_REPLY_AND_WAIT, 0, tag, label, timeout);
461 }
462 
463 L4_INLINE l4_msgtag_t
465  l4_msgtag_t tag,
466  l4_umword_t *src,
467  l4_timeout_t timeout) L4_NOTHROW
468 {
469  return l4_ipc(dest, utcb, L4_SYSF_SEND_AND_WAIT, 0, tag, src, timeout);
470 }
471 
472 L4_INLINE l4_msgtag_t
474  l4_msgtag_t tag,
475  l4_timeout_t timeout) L4_NOTHROW
476 {
477  return l4_ipc(dest, utcb, L4_SYSF_SEND, 0, tag, 0, timeout);
478 }
479 
480 L4_INLINE l4_msgtag_t
482  l4_timeout_t timeout) L4_NOTHROW
483 {
484  l4_msgtag_t t;
485  t.raw = 0;
486  return l4_ipc(L4_INVALID_CAP, utcb, L4_SYSF_WAIT, 0, t, src, timeout);
487 }
488 
489 L4_INLINE l4_msgtag_t
491  l4_timeout_t timeout) L4_NOTHROW
492 {
493  l4_msgtag_t t;
494  t.raw = 0;
495  return l4_ipc(src, utcb, L4_SYSF_RECV, 0, t, 0, timeout);
496 }
497 
498 L4_INLINE l4_msgtag_t
500 { return l4_ipc_receive(L4_INVALID_CAP, NULL, timeout); }
501 
502 L4_INLINE l4_umword_t
504 {
505  if (!l4_msgtag_has_error(tag))
506  return 0;
507  return l4_utcb_tcr_u(utcb)->error & L4_IPC_ERROR_MASK;
508 }
509 
510 L4_INLINE long
511 l4_error_u(l4_msgtag_t tag, l4_utcb_t *u) L4_NOTHROW
512 {
513  if (l4_msgtag_has_error(tag))
514  return l4_ipc_to_errno(l4_utcb_tcr_u(u)->error & L4_IPC_ERROR_MASK);
515 
516  return l4_msgtag_label(tag);
517 }
518 
519 L4_INLINE long
521 {
522  return l4_error_u(tag, l4_utcb());
523 }
524 
525 
527 { return (l4_utcb_tcr_u(u)->error & 1) != 0; }
528 
530 { return l4_utcb_tcr_u(u)->error & 1; }
531 
533 { return l4_utcb_tcr_u(u)->error & L4_IPC_ERROR_MASK; }
534 
535 
536 /*
537  * \internal
538  * \ingroup l4_ipc_api
539  */
540 L4_INLINE int
541 l4_sndfpage_add_u(l4_fpage_t const snd_fpage, unsigned long snd_base,
542  l4_msgtag_t *tag, l4_utcb_t *utcb) L4_NOTHROW
543 {
544  l4_msg_regs_t *v = l4_utcb_mr_u(utcb);
545  int i = l4_msgtag_words(*tag) + 2 * l4_msgtag_items(*tag);
546 
547  if (i >= L4_UTCB_GENERIC_DATA_SIZE - 1)
548  return -L4_ENOMEM;
549 
550  v->mr[i] = snd_base | L4_ITEM_MAP | L4_ITEM_CONT;
551  v->mr[i + 1] = snd_fpage.raw;
552 
553  *tag = l4_msgtag(l4_msgtag_label(*tag), l4_msgtag_words(*tag),
554  l4_msgtag_items(*tag) + 1, l4_msgtag_flags(*tag));
555  return 0;
556 }
557 
558 L4_INLINE int
559 l4_sndfpage_add(l4_fpage_t const snd_fpage, unsigned long snd_base,
560  l4_msgtag_t *tag) L4_NOTHROW
561 {
562  return l4_sndfpage_add_u(snd_fpage, snd_base, tag, l4_utcb());
563 }
564 
565 
566 #endif /* ! __L4SYS__INCLUDE__L4API_FIASCO__IPC_H__ */
L4_IPC_RESNDPFTO
@ L4_IPC_RESNDPFTO
Send-pagefault timeout in receive operation.
Definition: ipc.h:102
L4_SYSF_SEND_AND_WAIT
@ L4_SYSF_SEND_AND_WAIT
Send-and-wait flags.
Definition: consts.h:113
L4_NOTHROW
#define L4_NOTHROW
Mark a function declaration and definition as never throwing an exception.
Definition: compiler.h:186
L4_ENOMEM
@ L4_ENOMEM
No memory.
Definition: err.h:50
l4_utcb
l4_utcb_t * l4_utcb(void) L4_NOTHROW L4_PURE
Get the UTCB address.
Definition: utcb.h:340
L4_IPC_ERROR_MASK
@ L4_IPC_ERROR_MASK
Mask for error bits.
Definition: ipc.h:77
l4_cap_idx_t
unsigned long l4_cap_idx_t
L4 Capability selector Type.
Definition: types.h:342
l4_sndfpage_add
int l4_sndfpage_add(l4_fpage_t const snd_fpage, unsigned long snd_base, l4_msgtag_t *tag) L4_NOTHROW
Add a flex-page to be sent to the UTCB.
Definition: ipc.h:559
L4_IPC_SESNDPFTO
@ L4_IPC_SESNDPFTO
Send-pagefault timeout in send operation.
Definition: ipc.h:106
l4_ipc_reply_and_wait
l4_msgtag_t l4_ipc_reply_and_wait(l4_utcb_t *utcb, l4_msgtag_t tag, l4_umword_t *label, l4_timeout_t timeout) L4_NOTHROW
Reply and wait operation (uses the reply capability).
Definition: ipc.h:456
l4_msgtag_label
long l4_msgtag_label(l4_msgtag_t t) L4_NOTHROW
Get the protocol of tag.
Definition: types.h:420
L4_SYSF_RECV
@ L4_SYSF_RECV
Receive-phase flag.
Definition: consts.h:69
l4_msgtag_flags
l4_msgtag_flags
Flags for message tags.
Definition: types.h:96
l4_msgtag
l4_msgtag_t l4_msgtag(long label, unsigned words, unsigned items, unsigned flags) L4_NOTHROW
Create a message tag from the specified values.
Definition: types.h:408
l4_ipc_to_errno
long l4_ipc_to_errno(unsigned long ipc_error_code) L4_NOTHROW
Get a negative error code for the given IPC error code.
Definition: ipc.h:444
L4_ALWAYS_INLINE
#define L4_ALWAYS_INLINE
L4 Inline function attribute.
Definition: compiler.h:67
L4_EIPC_LO
@ L4_EIPC_LO
Communication error-range low.
Definition: err.h:70
L4_SYSF_REPLY_AND_WAIT
@ L4_SYSF_REPLY_AND_WAIT
Reply-and-wait flags.
Definition: consts.h:121
l4_msgtag_t::raw
l4_mword_t raw
raw value
Definition: types.h:161
l4_timeout_t
Timeout pair.
Definition: __timeout.h:59
l4_ipc_wait
l4_msgtag_t l4_ipc_wait(l4_utcb_t *utcb, l4_umword_t *label, l4_timeout_t timeout) L4_NOTHROW
Wait for an incoming message from any possible sender.
Definition: ipc.h:481
L4_IPC_RERCVPFTO
@ L4_IPC_RERCVPFTO
Receive-pagefault timeout in receive operation.
Definition: ipc.h:110
L4_IPC_SEMAPFAILED
@ L4_IPC_SEMAPFAILED
Map flexpage failed in send operation.
Definition: ipc.h:99
l4_ipc_error
l4_umword_t l4_ipc_error(l4_msgtag_t tag, l4_utcb_t *utcb) L4_NOTHROW
Get the error code for an object invocation.
Definition: ipc.h:503
L4_IPC_SND_ERR_MASK
@ L4_IPC_SND_ERR_MASK
Send error mask.
Definition: ipc.h:78
L4_INVALID_CAP
@ L4_INVALID_CAP
Invalid capability selector.
Definition: consts.h:141
l4_ipc_is_snd_error
int l4_ipc_is_snd_error(l4_utcb_t *utcb) L4_NOTHROW
Returns whether an error occurred in send phase of an invocation.
Definition: ipc.h:526
L4_IPC_SETIMEOUT
@ L4_IPC_SETIMEOUT
Timeout during send operation.
Definition: ipc.h:86
l4_ipc_send
l4_msgtag_t l4_ipc_send(l4_cap_idx_t dest, l4_utcb_t *utcb, l4_msgtag_t tag, l4_timeout_t timeout) L4_NOTHROW
Send a message to an object (do not wait for a reply).
Definition: ipc.h:473
l4_msg_regs_t
Encapsulation of the message-register block in the UTCB.
Definition: utcb.h:79
err.h
Error codes.
L4_IPC_RECANCELED
@ L4_IPC_RECANCELED
Receive operation canceled.
Definition: ipc.h:89
L4_SYSF_SEND
@ L4_SYSF_SEND
Send-phase flag.
Definition: consts.h:58
L4_SYSF_CALL
@ L4_SYSF_CALL
Call flags (combines send and receive).
Definition: consts.h:97
l4_msg_regs_t::mr
l4_umword_t mr[L4_UTCB_GENERIC_DATA_SIZE]
Message registers.
Definition: utcb.h:80
L4_IPC_REABORTED
@ L4_IPC_REABORTED
Receive operation aborted.
Definition: ipc.h:118
l4_fpage_t
L4 flexpage type.
Definition: __l4_fpage.h:83
l4_ipc_sleep
l4_msgtag_t l4_ipc_sleep(l4_timeout_t timeout) L4_NOTHROW
Sleep for an amount of time.
Definition: ipc.h:499
L4_IPC_SERCVPFTO
@ L4_IPC_SERCVPFTO
Receive-pagefault timeout in send operation.
Definition: ipc.h:114
L4_UTCB_GENERIC_DATA_SIZE
@ L4_UTCB_GENERIC_DATA_SIZE
Total number of message register (MRs) available.
Definition: utcb.h:47
L4_IPC_RETIMEOUT
@ L4_IPC_RETIMEOUT
Timeout during receive operation.
Definition: ipc.h:83
l4_ipc_send_and_wait
l4_msgtag_t l4_ipc_send_and_wait(l4_cap_idx_t dest, l4_utcb_t *utcb, l4_msgtag_t tag, l4_umword_t *label, l4_timeout_t timeout) L4_NOTHROW
Send a message and do an open wait.
Definition: ipc.h:464
l4_ipc
L4_ALWAYS_INLINE l4_msgtag_t l4_ipc(l4_cap_idx_t dest, l4_utcb_t *utcb, l4_umword_t flags, l4_umword_t slabel, l4_msgtag_t tag, l4_umword_t *rlabel, l4_timeout_t timeout) L4_NOTHROW
Generic L4 object invocation.
Definition: ipc.h:34
l4_msgtag_items
unsigned l4_msgtag_items(l4_msgtag_t t) L4_NOTHROW
Get the number of typed items.
Definition: types.h:428
L4_ITEM_CONT
@ L4_ITEM_CONT
Denote that the following item shall be put into the same receive item as this one.
Definition: consts.h:195
L4_IPC_SEABORTED
@ L4_IPC_SEABORTED
Send operation aborted.
Definition: ipc.h:121
L4_IPC_SECANCELED
@ L4_IPC_SECANCELED
Send operation canceled.
Definition: ipc.h:92
l4_ipc_tcr_error_t
l4_ipc_tcr_error_t
Error codes in the error TCR.
Definition: ipc.h:76
L4_IPC_REMSGCUT
@ L4_IPC_REMSGCUT
Cut receive message, due to message buffer is too small.
Definition: ipc.h:124
l4_ipc_call
l4_msgtag_t l4_ipc_call(l4_cap_idx_t object, l4_utcb_t *utcb, l4_msgtag_t tag, l4_timeout_t timeout) L4_NOTHROW
Object call (usual invocation).
Definition: ipc.h:448
l4_ipc_receive
l4_msgtag_t l4_ipc_receive(l4_cap_idx_t object, l4_utcb_t *utcb, l4_timeout_t timeout) L4_NOTHROW
Wait for a message from a specific source.
Definition: ipc.h:490
l4_ipc_error_code
int l4_ipc_error_code(l4_utcb_t *utcb) L4_NOTHROW
Get the error condition of the last invocation from the TCR.
Definition: ipc.h:532
L4_ITEM_MAP
@ L4_ITEM_MAP
Identify a message item as map item.
Definition: consts.h:189
L4_IPC_SEMSGCUT
@ L4_IPC_SEMSGCUT
Cut send message.
Definition: ipc.h:128
l4_ipc_is_rcv_error
int l4_ipc_is_rcv_error(l4_utcb_t *utcb) L4_NOTHROW
Returns whether an error occurred in receive phase of an invocation.
Definition: ipc.h:529
l4_utcb_t
struct l4_utcb_t l4_utcb_t
Opaque type for the UTCB.
Definition: utcb.h:67
L4_IPC_REMAPFAILED
@ L4_IPC_REMAPFAILED
Map flexpage failed in receive operation.
Definition: ipc.h:95
l4_msgtag_words
unsigned l4_msgtag_words(l4_msgtag_t t) L4_NOTHROW
Get the number of untyped words.
Definition: types.h:424
L4_SYSF_WAIT
@ L4_SYSF_WAIT
Wait flags (combines receive and open wait).
Definition: consts.h:105
l4_umword_t
unsigned long l4_umword_t
Unsigned machine word.
Definition: l4int.h:52
l4_thread_regs_t::error
l4_umword_t error
System call error codes.
Definition: utcb.h:113
L4_IPC_ENOT_EXISTENT
@ L4_IPC_ENOT_EXISTENT
Non-existing destination or source.
Definition: ipc.h:80
l4_msgtag_has_error
unsigned l4_msgtag_has_error(l4_msgtag_t t) L4_NOTHROW
Test for error indicator flag.
Definition: types.h:437
l4_msgtag_t
Message tag data structure.
Definition: types.h:160
types.h
Common L4 ABI Data Types.
l4_error
long l4_error(l4_msgtag_t tag) L4_NOTHROW
Return error code of a system call return message tag or the tag label.
Definition: ipc.h:520