readme: add NXP iMX8X to supported platforms
[barrelfish] / doc / 006-routing / api.h
1
2 /* ------------------------ Defines ---------------------------*/
3
4 /// Node id of a node in an application group
5 typedef uint32_t route_nodeid_t;
6
7 /// ID of an application group
8 typedef uint32_t route_group_id_t;
9
10 /// ID of a multicast group within an application group
11 typedef uint32_t route_multicast_id_t;
12
13 /// ID of a application group broadcast
14 typedef uint32_t route_group_bcast_id_t;
15
16 /// ID of the destination of the message
17 typedef uint32_t route_destination_id_t;
18
19 /// Which set of semantics should the routing library provide
20 enum route_semantics {
21     ROUTE_SEMANTICS_SSF, ///< Reliable and single source FIFO delivery
22     ROUTE_SEMANTICS_CO,  ///< Reliable and causal order delivery
23     ROUTE_SEMANTICS_TO,  ///< Reliable and total order delivery
24 };
25
26 /* ------------------------ Callbacks ---------------------------*/
27
28 /**
29  * \brief Called to deliver a message to the application layer
30  *
31  * \param st         The state user associated with the routing layer
32  * \param id         The associated application group
33  * \param entry      The entry to which the message was sent.
34  * \param sender_id  Id of the sender of the message
35  * \param payload    The payload
36  */
37 typedef void (*route_recv_fn)(void *st, route_group_id_t id,
38                                   route_destination_id_t entry,
39                                   route_nodeid_t sender_id, uint8_t *payload,
40                                   size_t length);
41
42 /**
43  * \brief Called when joining an application group is done
44  *
45  * \param st         The state user associated with the routing layer
46  * \param id         ID of the application group
47  */
48 typedef void (*route_join_group_fn)(void *st, route_group_id_t id);
49
50 /**
51  * \brief Called when leaving an application group is done
52  *
53  * \param st         The state user associated with the routing layer
54  * \param id         ID of the application group
55  */
56 typedef void (*route_leave_group_fn)(void *st, route_group_id_t id);
57
58 /**
59  * \brief Called when joining a multicast group is done
60  *
61  * \param st         The state user associated with the routing layer
62  * \param group_id   ID of the application group
63  * \param id         The multicast group that was joined
64  */
65 typedef void (*route_join_multicast_group_fn)(void *st,
66                           route_group_id_t group_id, route_multicast_id_t id);
67
68 /**
69  * \brief Called when leave a multicast group is done
70  *
71  * \param st         The state user associated with the routing layer
72  * \param group_id   ID of the application group
73  * \param id         The multicast group that was joined
74  */
75 typedef void (*route_leave_multicast_group_fn)(void *st,
76                           route_group_id_t group_id, route_multicast_id_t id);
77
78 struct route_cb_vtbl {
79     route_recv_fn recv;
80     route_join_group_fn join_group;
81     route_leave_group_fn leave_group;
82     route_join_multicast_group_fn join_multicast_group;
83     route_leave_multicast_group_fn leave_multicast_group;
84 };
85
86 /**
87  * \brief Called when the routing library has initialized
88  *
89  * \param st   State provided by the user
90  */
91 typedef void (*route_init_fn)(void *st);
92
93 /**
94  * \brief Called when the previous send finishes
95  *
96  * \param st         The state user associated with the routing layer
97  * \param id         The instance of the routing library
98  * \param entry      Entry to which the message was sent
99  */
100 typedef void (*route_cont_fn)(void *st, route_group_id_t id,
101                                   route_destination_id_t entry);
102
103 /* ------------------------ API ---------------------------*/
104
105 /**
106  * \brief Initialize the routing library.
107  * This must be called on each dispatcher before they can use the routing library
108  *
109  * \param cb  Callback for when the library is done initializing
110  * \param st  User state to associate with the callback function
111  */
112 errval_t route_init(route_init_callback cb, void *st);
113
114 /**
115  * \brief Create a new application group
116  *
117  * \param semantics Which semantics the routing library should provide
118  * \param id        Return the id of the newly created application group
119  *
120  * For a group this is called just once.
121  * The caller should propagate the id to other dispatcher
122  * and call #route_join_group
123  */
124 errval_t route_new_group(enum route_semantics semantics, route_group_id_t *id);
125
126 /**
127  * \brief Join an application group
128  *
129  * \param id    Id of the group to join
130  * \param st    State to associate with the group
131  * \param vtbl  Callback handlers to associate with the group
132  *
133  * When join is complete #route_join_group_fn will be called.
134  */
135 errval_t route_join_group(route_group_id_t id, void *st,
136                           struct route_cb_vtbl vtbl);
137
138 /**
139  * \brief Leave an application group
140  *
141  * \param id    Id of the group to leave
142  *
143  * When leave is complete #route_leave_group_fn will be called.
144  */
145 errval_t route_leave_group(route_group_id_t id);
146
147 /**
148  * \brief Setup a new multicast group
149  *
150  * \param group_id  Group id identifies the instance of the routing library
151  * \param id    Return the id of the newly created multicast group
152  *
153  * For a group this is called just once.
154  * The caller should propagate the id to other nodes and call
155  * #route_join_multicast_group.
156  */
157 errval_t route_new_multicast_group(route_multicast_id_t *id);
158
159 /**
160  * \brief Join a multicast group
161  *
162  * \param group_id    Id of the application group
163  * \param id          Id of the multicast group to join
164  *
165  * Join a multicast group within a application group specified by #group_id
166  * When join is complete, #route_join_multicast_group_fn will be called.
167  */
168 errval_t route_join_multicast_group(route_group_id_t group_id,
169                                     route_multicast_id_t id);
170
171 /**
172  * \brief Leave a multicast group
173  *
174  * \param group_id    Id of the application group
175  * \param id          Id of the multicast group to leave
176  *
177  * Leave a multicast group within a application group specified by #group_id
178  * When leave is complete, #route_leave_multicast_group_fn will be called.
179  */
180 errval_t route_leave_multicast_group(route_group_id_t group_id,
181                                      route_multicast_id_t id);
182
183 /**
184  * \brief Send a message over the routing layer
185  *
186  * \param cont     If set, will be called when the send finishes
187  * \param id       The application group over which the message should be sent
188  * \param dest     The forwarding table entry to which to send the message
189  * \param payload  The payload
190  */
191 errval_t route_send(route_cont_fn cont, route_group_id_t id,
192                     route_destination_id_t dest,
193                     uint8_t *payload, size_t length);
194
195 /**
196  * \brief Check if can send a message
197  *
198  * \param id    The application group on which to check
199  * \param entry The entry on which to check
200  */
201 bool route_can_send(route_group_id_t id, route_destination_id_t entry);