source: mainline/kernel/generic/include/ipc/sysipc_ops.h

Last change on this file was 174156fd, checked in by Jakub Jermar <jakub@…>, 7 years ago

Disambiguate doxygroup generic*
  • Property mode set to 100644
File size: 5.1 KB
Line 
1/*
2 * Copyright (c) 2012 Jakub Jermar
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/** @addtogroup kernel_generic_ipc
30 * @{
31 */
32/** @file
33 */
34
35#ifndef KERN_SYSIPC_OPS_H_
36#define KERN_SYSIPC_OPS_H_
37
38#include <ipc/ipc.h>
39
40#define SYSIPC_OP(op, call, ...) \
41 ({ \
42 sysipc_ops_t *ops = sysipc_ops_get((call)->request_method); \
43 assert(ops->op); \
44 ops->op((call), ##__VA_ARGS__); \
45 })
46
47/**
48 * This header declares the per-method IPC callbacks. Using these callbacks,
49 * each IPC method (but system methods in particular), can define actions that
50 * will be called at specific moments in the call life-cycle.
51 *
52 * Normally, the kernel will attempt to invoke the following callbacks in the
53 * following order on each call:
54 *
55 * request_preprocess()
56 * request_process()
57 * answer_preprocess()
58 * answer_process()
59 *
60 * This callback invocation sequence is a natural order of processing. Note,
61 * however, that due to various special circumstances, callbacks may be called
62 * also in a different than natural order of processing. This means that some
63 * callbacks may be skipped and some others may be called instead.
64 *
65 * The additional callbacks that may be called are as follows:
66 *
67 * request_forget()
68 * answer_cleanup()
69 *
70 * There are several notable scenarios in which some callbacks of the natural
71 * order of processing will be skipped.
72 *
73 * The request_process(), answer_preprocess() and answer_process() callbacks
74 * will be skipped if the call cannot be delivered to the callee. This may
75 * happen when e.g. the request_preprocess() callback fails or the connection
76 * to the callee is not functional. The next callback that will be invoked on
77 * the call is request_forget().
78 *
79 * The comments for each callback type describe the specifics of each callback
80 * such as the context in which it is invoked and various constraints.
81 */
82
83typedef struct {
84 /**
85 * This callback is called from request_preprocess().
86 *
87 * Context: caller
88 * Caller alive: guaranteed
89 * Races with: N/A
90 * Invoked on: all calls
91 */
92 errno_t (*request_preprocess)(call_t *, phone_t *);
93
94 /**
95 * This callback is called when the IPC cleanup code wins the race to
96 * forget the call.
97 *
98 * Context: caller
99 * Caller alive: guaranteed
100 * Races with: request_process(), answer_cleanup(),
101 * _ipc_answer_free_call()
102 * Invoked on: all forgotten calls
103 */
104 errno_t (*request_forget)(call_t *);
105
106 /**
107 * This callback is called from process_request().
108 *
109 * Context: callee
110 * Caller alive: no guarantee
111 * Races with: request_forget()
112 * Invoked on: all calls delivered to the callee
113 */
114 int (*request_process)(call_t *, answerbox_t *);
115
116 /**
117 * This callback is called when answer_preprocess() loses the race to
118 * answer the call.
119 *
120 * Context: callee
121 * Caller alive: no guarantee
122 * Races with: request_forget()
123 * Invoked on: all forgotten calls
124 */
125 errno_t (*answer_cleanup)(call_t *, ipc_data_t *);
126
127 /**
128 * This callback is called when answer_preprocess() wins the race to
129 * answer the call.
130 *
131 * Context: callee
132 * Caller alive: guaranteed
133 * Races with: N/A
134 * Invoked on: all answered calls
135 */
136 errno_t (*answer_preprocess)(call_t *, ipc_data_t *);
137
138 /**
139 * This callback is called from process_answer().
140 *
141 * Context: caller
142 * Caller alive: guaranteed
143 * Races with: N/A
144 * Invoked on: all answered calls
145 */
146 errno_t (*answer_process)(call_t *);
147} sysipc_ops_t;
148
149extern sysipc_ops_t *sysipc_ops_get(sysarg_t);
150
151extern errno_t null_request_preprocess(call_t *, phone_t *);
152extern errno_t null_request_forget(call_t *);
153extern int null_request_process(call_t *, answerbox_t *);
154extern errno_t null_answer_cleanup(call_t *, ipc_data_t *);
155extern errno_t null_answer_preprocess(call_t *, ipc_data_t *);
156extern errno_t null_answer_process(call_t *);
157
158#endif
159
160/** @}
161 */
Note: See TracBrowser for help on using the repository browser.