source: rtems/cpukit/include/rtems/score/mpciimpl.h @ 57cd05cf

Last change on this file since 57cd05cf was 57cd05cf, checked in by Andreas Dachsberger <andreas.dachsberger@…>, on Apr 10, 2019 at 5:50:15 AM

doxygen: score: adjust doc in mpciimpl.h to doxygen guidelines

Update #3706.

  • Property mode set to 100644
File size: 8.8 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup RTEMSScoreMPCI
5 *
6 * @brief MPCI Layer Implementation
7 */
8
9/*
10 *  COPYRIGHT (c) 1989-2009.
11 *  On-Line Applications Research Corporation (OAR).
12 *
13 *  The license and distribution terms for this file may be
14 *  found in the file LICENSE in this distribution or at
15 *  http://www.rtems.org/license/LICENSE.
16 */
17
18#ifndef _RTEMS_SCORE_MPCIIMPL_H
19#define _RTEMS_SCORE_MPCIIMPL_H
20
21#include <rtems/score/mpci.h>
22#include <rtems/score/status.h>
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28/**
29 * @addtogroup RTEMSScoreMPCI
30 *
31 * @{
32 */
33
34/**
35 *  For packets associated with requests that don't already have a timeout,
36 *  use the one specified by this MPCI driver.  The value specified by
37 *   the MPCI driver sets an upper limit on how long a remote request
38 *   should take to complete.
39 */
40#define MPCI_DEFAULT_TIMEOUT    0xFFFFFFFF
41
42/**
43 *  The following defines the type for packet processing routines
44 *  invoked by the MPCI Receive server.
45 */
46typedef void (*MPCI_Packet_processor)( MP_packet_Prefix * );
47
48/**
49 *  The following enumerated type defines the list of
50 *  internal MP operations.
51 */
52typedef enum {
53  MPCI_PACKETS_SYSTEM_VERIFY  =  0
54}   MPCI_Internal_Remote_operations;
55
56/**
57 *  The following data structure defines the packet used to perform
58 *  remote event operations.
59 */
60typedef struct {
61  /** This field is the general header for all packets. */
62  MP_packet_Prefix                 Prefix;
63  /** This value specifies the operation. */
64  MPCI_Internal_Remote_operations  operation;
65  /** This is the maximum number of nodes in the system. It must agree
66   *  on all nodes.
67   */
68  uint32_t                         maximum_nodes;
69  /** This field is the maximum number of concurrently existent
70   *  globally offered objects.
71   */
72  uint32_t                         maximum_global_objects;
73}    MPCI_Internal_packet;
74
75/**
76 *  The following thread queue is used to maintain a list of tasks
77 *  which currently have outstanding remote requests.
78 */
79extern Thread_queue_Control _MPCI_Remote_blocked_threads;
80
81/**
82 *  The following define the internal pointers to the user's
83 *  configuration information.
84 */
85extern MPCI_Control *_MPCI_table;
86
87/**
88 *  @brief Pointer to MP thread control block.
89 *
90 *  The following is used to determine when the multiprocessing receive
91 *  thread is executing so that a proxy can be allocated instead of
92 *  blocking the multiprocessing receive thread.
93 */
94extern Thread_Control *_MPCI_Receive_server_tcb;
95
96/**
97 *  The following table contains the process packet routines provided
98 *  by each object that supports MP operations.
99 */
100extern MPCI_Packet_processor
101_MPCI_Packet_processors[ MP_PACKET_CLASSES_LAST + 1 ];
102
103/**
104 * @brief Registers the MPCI packet processor for the designated object class.
105 *
106 * @param the_class The class indicator for packets which will
107 *            be processed by @a the_packet_processor method.
108 * @param the_packet_processor Pointer to a method which is
109 *            invoked when packets with @a the_class are received.
110 */
111void _MPCI_Register_packet_processor(
112  MP_packet_Classes      the_class,
113  MPCI_Packet_processor  the_packet_processor
114
115);
116
117/**
118 * @brief Obtains a packet by invoking the user provided
119 *          MPCI get packet callout.
120 *
121 * @return Returns a pointer to a MPCI packet which can be
122 *          filled in by the caller and used to perform a subsequent
123 *          remote operation.
124 */
125MP_packet_Prefix *_MPCI_Get_packet ( void );
126
127/**
128 * @brief Deallocates a packet.
129 *
130 * This routine deallocates a packet by invoking the user provided
131 * MPCI return packet callout.
132 *
133 * @param[out] the_packet The MP packet to deallocate.
134 */
135void _MPCI_Return_packet (
136  MP_packet_Prefix *the_packet
137);
138
139/**
140 * @brief Sends a process packet.
141 *
142 * This routine sends a process packet by invoking the user provided
143 * MPCI send callout.
144 *
145 * @param destination The node which should receive this packet.
146 * @param the_packet The packet to be sent.
147 */
148void _MPCI_Send_process_packet (
149  uint32_t          destination,
150  MP_packet_Prefix *the_packet
151);
152
153/**
154 * @brief Sends a request packet.
155 *
156 * This routine sends a request packet by invoking the user provided
157 * MPCI send callout.
158 *
159 * @param destination The node which should receive this packet.
160 * @param the_packet The packet to be sent.
161 * @param extra_state The extra thread state bits which should be
162 *            set in addition to the remote operation pending state.  It
163 *            may indicate the caller is blocking on a message queue
164 *            operation.
165 *
166 * @ret This method returns the operation status from the remote node.
167 */
168Status_Control _MPCI_Send_request_packet(
169  uint32_t          destination,
170  MP_packet_Prefix *the_packet,
171  States_Control    extra_state
172);
173
174/**
175 * @brief Sends a response packet.
176 *
177 * This routine sends a response packet by invoking the user provided
178 * MPCI send callout.
179 *
180 * @param destination The node which should receive this packet.
181 * @param the_packet The packet to be sent.
182 */
183void _MPCI_Send_response_packet (
184  uint32_t          destination,
185  MP_packet_Prefix *the_packet
186);
187
188/**
189 * @brief Receives a packet.
190 *
191 * This routine receives a packet by invoking the user provided
192 * MPCI receive callout.
193 *
194 * @return This method returns the packet received.
195 */
196MP_packet_Prefix  *_MPCI_Receive_packet ( void );
197
198/**
199 * @brief Passes a packet to the thread.
200 *
201 * This routine is responsible for passing @a the_packet to the thread
202 * waiting on the remote operation to complete.  The unblocked thread is
203 * responsible for eventually freeing @a the_packet.
204 *
205 * @param the_packet is the response packet to be processed.
206 *
207 * @retval pointer This method returns a pointer to the thread which was unblocked
208 * @retval NULL The waiting thread no longer exists.
209 */
210Thread_Control *_MPCI_Process_response (
211  MP_packet_Prefix *the_packet
212);
213
214/**
215 * @brief Receives and processes all packets.
216 *
217 * This is the server thread which receives and processes all MCPI packets.
218 *
219 * @param ignored The thread argument.  It is not used.
220 */
221void _MPCI_Receive_server(
222  Thread_Entry_numeric_type ignored
223);
224
225/**
226 * @brief Announces the availability of a packet.
227 *
228 * This routine informs RTEMS of the availability of an MPCI packet.
229 */
230void _MPCI_Announce ( void );
231
232/**
233 * @brief Performs a process on another node.
234 *
235 * This routine performs a remote procedure call so that a
236 * process operation can be performed on another node.
237 *
238 * @param operation The remote operation to perform.
239 */
240void _MPCI_Internal_packets_Send_process_packet (
241   MPCI_Internal_Remote_operations operation
242);
243
244/**
245 *  _MPCI_Internal_packets_Send_request_packet
246 *
247 *  This routine performs a remote procedure call so that a
248 *  directive operation can be initiated on another node.
249 *
250 *  This routine is not needed since there are no request
251 *  packets to be sent by this manager.
252 */
253
254/**
255 *  _MPCI_Internal_packets_Send_response_packet
256 *
257 *  This routine performs a remote procedure call so that a
258 *  directive can be performed on another node.
259 *
260 *  This routine is not needed since there are no response
261 *  packets to be sent by this manager.
262 */
263
264/**
265 * @brief Performs requested action from another node.
266 *
267 * This routine performs the actions specific to this package for
268 * the request from another node.
269 *
270 * @param the_packet_prefix The packet prefix for this method.
271 */
272void _MPCI_Internal_packets_Process_packet (
273  MP_packet_Prefix *the_packet_prefix
274);
275
276/**
277 *  _MPCI_Internal_packets_Send_object_was_deleted
278 *
279 *  This routine is invoked indirectly by the thread queue
280 *  when a proxy has been removed from the thread queue and
281 *  the remote node must be informed of this.
282 *
283 *  This routine is not needed since there are no objects
284 *  deleted by this manager.
285 */
286
287/**
288 *  _MPCI_Internal_packets_Send_extract_proxy
289 *
290 *  This routine is invoked when a task is deleted and it
291 *  has a proxy which must be removed from a thread queue and
292 *  the remote node must be informed of this.
293 *
294 *  This routine is not needed since there are no objects
295 *  deleted by this manager.
296 */
297
298/**
299 * @brief Obtains an internal thread.
300 *
301 * This routine is used to obtain an internal threads MP packet.
302 *
303 * @retval pointer The pointer to the obtained packet.
304 * @retval NULL Something went wrong.
305 */
306MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
307
308/**
309 * @brief Checks if the packet class is valid.
310 *
311 * @param the_packet_class The packet class to perform the validation on.
312 *
313 * @retval true @a the_packet_class is valid.
314 * @retval false @a the_packet_class is not valid.
315 *
316 * @note Check for lower bounds (MP_PACKET_CLASSES_FIRST ) is unnecessary
317 *       because this enum starts at lower bound of zero.
318 */
319
320RTEMS_INLINE_ROUTINE bool _Mp_packet_Is_valid_packet_class (
321  MP_packet_Classes the_packet_class
322)
323{
324  return ( the_packet_class <= MP_PACKET_CLASSES_LAST );
325}
326
327/** @} */
328
329#ifdef __cplusplus
330}
331#endif
332
333#endif
334/* end of include file */
Note: See TracBrowser for help on using the repository browser.