source: rtems/cpukit/score/include/rtems/score/mpci.h @ 2f1d801

4.104.114.95
Last change on this file since 2f1d801 was 976162a6, checked in by Joel Sherrill <joel.sherrill@…>, on 12/03/07 at 22:23:13

2007-12-03 Joel Sherrill <joel.sherrill@…>

  • libcsupport/src/malloc.c, libmisc/monitor/mon-command.c, posix/preinstall.am, posix/include/rtems/posix/cond.h, posix/include/rtems/posix/mqueue.h, posix/include/rtems/posix/mutex.h, posix/include/rtems/posix/pthread.h, posix/include/rtems/posix/semaphore.h, posix/src/conddestroy.c, posix/src/mutexdestroy.c, posix/src/mutexinit.c, posix/src/mutexsetprioceiling.c, posix/src/mutexunlock.c, sapi/include/confdefs.h, sapi/include/rtems/config.h, sapi/include/rtems/init.h, sapi/include/rtems/sptables.h, sapi/src/exinit.c, score/include/rtems/system.h, score/include/rtems/score/mpci.h, score/src/mpci.c, score/src/thread.c, score/src/threadcreateidle.c, score/src/threadstackallocate.c, score/src/threadstackfree.c, score/src/wkspace.c: Moved most of the remaining CPU Table fields to the Configuration Table. This included pretasking_hook, predriver_hook, postdriver_hook, idle_task, do_zero_of_workspace, extra_mpci_receive_server_stack, stack_allocate_hook, and stack_free_hook. As a side-effect of this effort some multiprocessing code was made conditional and some style clean up occurred.
  • Property mode set to 100644
File size: 12.4 KB
Line 
1/**
2 *  @file  rtems/score/mpci.h
3 *
4 *  This include file contains all the constants and structures associated
5 *  with the MPCI layer.  It provides mechanisms to utilize packets.
6 */
7
8/*
9 *  COPYRIGHT (c) 1989-2006.
10 *  On-Line Applications Research Corporation (OAR).
11 *
12 *  The license and distribution terms for this file may be
13 *  found in the file LICENSE in this distribution or at
14 *  http://www.rtems.com/license/LICENSE.
15 *
16 *  $Id$
17 */
18
19#ifndef _RTEMS_SCORE_MPCI_H
20#define _RTEMS_SCORE_MPCI_H
21
22/**
23 *  @defgroup ScoreMPCI MPCI Handler
24 *
25 *  The MPCI Handler encapsulates functionality which is related to the
26 *  generation, receipt, and processing of remote operations in a
27 *  multiprocessor system.  This handler contains the message passing
28 *  support for making remote service calls as well as the server thread
29 *  which processes requests from remote nodes.
30*/
31/**@{*/
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37#include <rtems/score/mppkt.h>
38#include <rtems/score/states.h>
39#include <rtems/score/thread.h>
40#include <rtems/score/threadq.h>
41#include <rtems/score/tqdata.h>
42#include <rtems/score/watchdog.h>
43#include <rtems/score/coresem.h>
44
45/**
46 *  The following defines the node number used when a broadcast is desired.
47 */
48#define MPCI_ALL_NODES 0
49
50/**
51 *  For packets associated with requests that don't already have a timeout,
52 *  use the one specified by this MPCI driver.  The value specified by
53 *   the MPCI driver sets an upper limit on how long a remote request
54 *   should take to complete.
55 */
56#define MPCI_DEFAULT_TIMEOUT    0xFFFFFFFF
57
58/**
59 *  This type is returned by all user provided MPCI routines.
60 */
61typedef void MPCI_Entry;
62
63/**
64 *  This type defines the prototype for the initization entry point
65 *  in an Multiprocessor Communications Interface.
66 */
67typedef MPCI_Entry ( *MPCI_initialization_entry )( void );
68
69/**
70 *  This type defines the prototype for the get packet entry point
71 *  in an Multiprocessor Communications Interface.  The single
72 *  parameter will point to the packet allocated.
73 */
74typedef MPCI_Entry ( *MPCI_get_packet_entry )(
75                     MP_packet_Prefix **
76                   );
77
78/**
79 *  This type defines the prototype for the return packet entry point
80 *  in an Multiprocessor Communications Interface.  The single
81 *  parameter will point to a packet previously allocated by the
82 *  get packet MPCI entry.
83 */
84typedef MPCI_Entry ( *MPCI_return_packet_entry )(
85                     MP_packet_Prefix *
86                   );
87
88/**
89 *  This type defines the prototype for send get packet entry point
90 *  in an Multiprocessor Communications Interface.  The single
91 *  parameter will point to a packet previously allocated by the
92 *  get packet entry point that has been filled in by the caller.
93 */
94typedef MPCI_Entry ( *MPCI_send_entry )(
95                     uint32_t,
96                     MP_packet_Prefix *
97                   );
98
99/**
100 *  This type defines the prototype for the receive packet entry point
101 *  in an Multiprocessor Communications Interface.  The single
102 *  parameter will point to a packet allocated and filled in by the
103 *  receive packet handler.  The caller will block until a packet is
104 *  received.
105 */
106typedef MPCI_Entry ( *MPCI_receive_entry )(
107                     MP_packet_Prefix **
108                   );
109
110/**
111 *  This type defines the Multiprocessor Communications
112 *  Interface (MPCI) Table.  This table defines the user-provided
113 *  MPCI which is a required part of a multiprocessor system.
114 *
115 *  For non-blocking local operations that become remote operations,
116 *  we need a timeout.  This is a per-driver timeout: default_timeout
117 */
118typedef struct {
119  /** This fields contains the timeout for MPCI operations in ticks. */
120  uint32_t                   default_timeout;
121  /** This field contains the maximum size of a packet supported by this
122   *  MPCI layer.  This size places a limit on the size of a message
123   *  which can be transmitted over this interface.
124   **/
125  uint32_t                   maximum_packet_size;
126  /** This field points to the MPCI initialization entry point. */
127  MPCI_initialization_entry  initialization;
128  /** This field points to the MPCI get packet entry point. */
129  MPCI_get_packet_entry      get_packet;
130  /** This field points to the MPCI return packet entry point. */
131  MPCI_return_packet_entry   return_packet;
132  /** This field points to the MPCI send packet entry point. */
133  MPCI_send_entry            send_packet;
134  /** This field points to the MPCI receive packet entry point. */
135  MPCI_receive_entry         receive_packet;
136} MPCI_Control;
137
138/**
139 *  The following defines the type for packet processing routines
140 *  invoked by the MPCI Receive server.
141 */
142typedef void (*MPCI_Packet_processor)( MP_packet_Prefix * );
143
144/**
145 *  The following enumerated type defines the list of
146 *  internal MP operations.
147 */
148typedef enum {
149  MPCI_PACKETS_SYSTEM_VERIFY  =  0
150}   MPCI_Internal_Remote_operations;
151
152/**
153 *  The following data structure defines the packet used to perform
154 *  remote event operations.
155 */
156typedef struct {
157  /** This field is the general header for all packets. */
158  MP_packet_Prefix                 Prefix;
159  /** This value specifies the operation. */
160  MPCI_Internal_Remote_operations  operation;
161  /** This is the maximum number of nodes in the system. It must agree
162   *  on all nodes.
163   */
164  uint32_t                         maximum_nodes;
165  /** This field is the maximum number of concurrently existent
166   *  globally offered objects.
167   */
168  uint32_t                         maximum_global_objects;
169}    MPCI_Internal_packet;
170
171/**
172 *  This is the core semaphore which the MPCI Receive Server blocks on.
173 */
174SCORE_EXTERN CORE_semaphore_Control _MPCI_Semaphore;
175
176/**
177 *  The following thread queue is used to maintain a list of tasks
178 *  which currently have outstanding remote requests.
179 */
180SCORE_EXTERN Thread_queue_Control _MPCI_Remote_blocked_threads;
181
182/**
183 *  The following define the internal pointers to the user's
184 *  configuration information.
185 */
186SCORE_EXTERN MPCI_Control *_MPCI_table;
187
188/** @brief Pointer to MP Thread Control Block
189 *
190 *  The following is used to determine when the multiprocessing receive
191 *  thread is executing so that a proxy can be allocated instead of
192 *  blocking the multiprocessing receive thread.
193 */
194SCORE_EXTERN Thread_Control *_MPCI_Receive_server_tcb;
195
196/**
197 *  The following table contains the process packet routines provided
198 *  by each object that supports MP operations.
199 */
200SCORE_EXTERN MPCI_Packet_processor
201               _MPCI_Packet_processors[MP_PACKET_CLASSES_LAST+1];
202
203/**
204 *  This routine performs the initialization necessary for this handler.
205 *
206 *  @param[in] users_mpci_table is a pointer to the application configured
207 *             MPCI Table.  This table contains pointers to the MPCI Layers
208 *             entry points.
209 *  @param[in] timeout_status is the value which should be returned to
210 *             blocking threads when they timeout on a remote operation.
211 */
212void _MPCI_Handler_initialization(
213  MPCI_Control            *users_mpci_table,
214  uint32_t                 timeout_status
215);
216
217/**
218 *  This routine creates the packet receive server used in MP systems.
219 */
220void _MPCI_Create_server( void );
221
222/**
223 *  This routine initializes the MPCI driver by
224 *  invoking the user provided MPCI initialization callout.
225 */
226void _MPCI_Initialization ( void );
227
228/**
229 *  This routine registers the MPCI packet processor for the
230 *  designated object class.
231 *
232 *  @param[in] the_class is the class indicator for packets which will
233 *             be processed by @a the_packet_processor method.
234 *  @param[in] the_packet_processor is a pointer to a method which is
235 *             invoked when packets with @a the_class are received.
236 */
237void _MPCI_Register_packet_processor(
238  MP_packet_Classes      the_class,
239  MPCI_Packet_processor  the_packet_processor
240
241);
242
243/**
244 *  This function obtains a packet by invoking the user provided
245 *  MPCI get packet callout.
246 *
247 *  @return This method returns a pointer to a MPCI packet which can be
248 *          filled in by the caller and used to perform a subsequent
249 *          remote operation.
250 */
251MP_packet_Prefix *_MPCI_Get_packet ( void );
252
253/**
254 *  This routine deallocates a packet by invoking the user provided
255 *  MPCI return packet callout.
256 *
257 *  @param[in] the_packet is the MP packet to deallocate.
258 */
259void _MPCI_Return_packet (
260  MP_packet_Prefix *the_packet
261);
262
263/**
264 *  This routine sends a process packet by invoking the user provided
265 *  MPCI send callout.
266 *
267 *  @param[in] destination is the node which should receive this packet.
268 *  @param[in] the_packet is the packet to be sent.
269 */
270void _MPCI_Send_process_packet (
271  uint32_t          destination,
272  MP_packet_Prefix *the_packet
273);
274
275/**
276 *  This routine sends a request packet by invoking the user provided
277 *  MPCI send callout.
278 *
279 *  @param[in] destination is the node which should receive this packet.
280 *  @param[in] the_packet is the packet to be sent.
281 *  @param[in] extra_state is the extra thread state bits which should be
282 *             set in addition to the remote operation pending state.  It
283 *             may indicate the caller is blocking on a message queue
284 *             operation.
285 *
286 *  @return This method returns the operation status from the remote node.
287 */
288uint32_t _MPCI_Send_request_packet (
289  uint32_t           destination,
290  MP_packet_Prefix  *the_packet,
291  States_Control     extra_state
292);
293
294/**
295 *  This routine sends a response packet by invoking the user provided
296 *  MPCI send callout.
297 *
298 *  @param[in] destination is the node which should receive this packet.
299 *  @param[in] the_packet is the packet to be sent.
300 */
301void _MPCI_Send_response_packet (
302  uint32_t          destination,
303  MP_packet_Prefix *the_packet
304);
305
306/**
307 *  This routine receives a packet by invoking the user provided
308 *  MPCI receive callout.
309 *
310 *  @return This method returns the packet received.
311 */
312MP_packet_Prefix  *_MPCI_Receive_packet ( void );
313
314/**
315 *  This routine is responsible for passing @a the_packet to the thread
316 *  waiting on the remote operation to complete.  The unblocked thread is
317 *  responsible for eventually freeing @a the_packet.
318 *
319 *  @param[in] the_packet is the response packet to be processed.
320 *
321 *  @return This method returns a pointer to the thread which was if unblocked
322 *          or NULL if the waiting thread no longer exists.
323 */
324Thread_Control *_MPCI_Process_response (
325  MP_packet_Prefix *the_packet
326);
327
328/**
329 *  This is the server thread which receives and processes all MCPI packets.
330 *
331 *  @param[in] ignored is the thread argument.  It is not used.
332 */
333Thread _MPCI_Receive_server(
334  uint32_t   ignored
335);
336
337/**
338 *  This routine informs RTEMS of the availability of an MPCI packet.
339 */
340void _MPCI_Announce ( void );
341
342/**
343 *  This routine performs a remote procedure call so that a
344 *  process operation can be performed on another node.
345 *
346 *  @param[in] operation is the remote operation to perform.
347 */
348void _MPCI_Internal_packets_Send_process_packet (
349   MPCI_Internal_Remote_operations operation
350);
351
352/**
353 *  _MPCI_Internal_packets_Send_request_packet
354 *
355 *  This routine performs a remote procedure call so that a
356 *  directive operation can be initiated on another node.
357 *
358 *  This routine is not needed since there are no request
359 *  packets to be sent by this manager.
360 */
361
362/**
363 *  _MPCI_Internal_packets_Send_response_packet
364 *
365 *  This routine performs a remote procedure call so that a
366 *  directive can be performed on another node.
367 *
368 *  This routine is not needed since there are no response
369 *  packets to be sent by this manager.
370 */
371
372/**
373 *  This routine performs the actions specific to this package for
374 *  the request from another node.
375 */
376void _MPCI_Internal_packets_Process_packet (
377  MP_packet_Prefix *the_packet_prefix
378);
379
380/**
381 *  _MPCI_Internal_packets_Send_object_was_deleted
382 *
383 *  This routine is invoked indirectly by the thread queue
384 *  when a proxy has been removed from the thread queue and
385 *  the remote node must be informed of this.
386 *
387 *  This routine is not needed since there are no objects
388 *  deleted by this manager.
389 */
390
391/**
392 *  _MPCI_Internal_packets_Send_extract_proxy
393 *
394 *  This routine is invoked when a task is deleted and it
395 *  has a proxy which must be removed from a thread queue and
396 *  the remote node must be informed of this.
397 *
398 *  This routine is not needed since there are no objects
399 *  deleted by this manager.
400 */
401
402/**
403 *  This routine is used to obtain a internal threads mp packet.
404 */
405MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
406
407#ifdef __cplusplus
408}
409#endif
410
411/**@}*/
412
413#endif
414/* end of include file */
Note: See TracBrowser for help on using the repository browser.