/* message.h * * This include file contains all the constants and structures associated * with the Message Queue Manager. This manager provides a mechanism for * communication and synchronization between tasks using messages. * * Directives provided are: * * + create a queue * + get ID of a queue * + delete a queue * + put a message at the rear of a queue * + put a message at the front of a queue * + broadcast N messages to a queue * + receive message from a queue * + flush all messages on a queue * * * COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994. * On-Line Applications Research Corporation (OAR). * All rights assigned to U.S. Government, 1994. * * This material may be reproduced by or for the U.S. Government pursuant * to the copyright license under the clause at DFARS 252.227-7013. This * notice must appear in all copies of this file and its derivatives. * * $Id$ */ #ifndef __RTEMS_MESSAGE_QUEUE_h #define __RTEMS_MESSAGE_QUEUE_h #ifdef __cplusplus extern "C" { #endif #include #include #include /* * The following defines the data types needed to manipulate * the contents of message buffers. * Since msgs are variable length we just make a ptr to 1. */ typedef struct { unsigned32 size; #ifndef __cplusplus /* NOTE: [0] is gcc specific, * but specifically disallowed by ANSI STD C++ * g++ warns about it, so we #ifdef it out to * get rid of warnings when compiled by g++. */ unsigned32 buffer[0]; #endif } Message_queue_Buffer; /* * The following records define the organization of a message * buffer. */ typedef struct { Chain_Node Node; Message_queue_Buffer Contents; } Message_queue_Buffer_control; /* * The following records define the control block used to manage * each message queue. */ typedef struct { Objects_Control Object; Thread_queue_Control Wait_queue; rtems_attribute attribute_set; unsigned32 maximum_pending_messages; unsigned32 number_of_pending_messages; unsigned32 maximum_message_size; Chain_Control Pending_messages; Message_queue_Buffer *message_buffers; Chain_Control Inactive_messages; } Message_queue_Control; /* * The following defines the information control block used to * manage this class of objects. */ EXTERN Objects_Information _Message_queue_Information; /* * The following enumerated type details the modes in which a message * may be submitted to a message queue. The message may be posted * in a send or urgent fashion. */ typedef enum { MESSAGE_QUEUE_SEND_REQUEST = 0, MESSAGE_QUEUE_URGENT_REQUEST = 1 } Message_queue_Submit_types; /* * _Message_queue_Manager_initialization * * DESCRIPTION: * * This routine performs the initialization necessary for this manager. */ void _Message_queue_Manager_initialization( unsigned32 maximum_message_queues ); /* * rtems_message_queue_create * * DESCRIPTION: * * This routine implements the rtems_message_queue_create directive. The * message queue will have the name name. If the attribute_set indicates * that the message queue is to be limited in the number of messages * that can be outstanding, then count indicates the maximum number of * messages that will be held. It returns the id of the created * message queue in ID. */ rtems_status_code rtems_message_queue_create( Objects_Name name, unsigned32 count, unsigned32 max_message_size, rtems_attribute attribute_set, Objects_Id *id ); /* * rtems_message_queue_ident * * DESCRIPTION: * * This routine implements the rtems_message_queue_ident directive. * This directive returns the message queue ID associated with NAME. * If more than one message queue is named name, then the message * queue to which the ID belongs is arbitrary. node indicates the * extent of the search for the ID of the message queue named name. * The search can be limited to a particular node or allowed to * encompass all nodes. */ rtems_status_code rtems_message_queue_ident( Objects_Name name, unsigned32 node, Objects_Id *id ); /* * rtems_message_queue_delete * * DESCRIPTION: * * This routine implements the rtems_message_queue_delete directive. The * message queue indicated by ID is deleted. */ rtems_status_code rtems_message_queue_delete( Objects_Id id ); /* * rtems_message_queue_send * * DESCRIPTION: * * This routine implements the rtems_message_queue_send directive. * This directive sends the message buffer to the message queue * indicated by ID. If one or more tasks is blocked waiting * to receive a message from this message queue, then one will * receive the message. The task selected to receive the * message is based on the task queue discipline algorithm in * use by this particular message queue. If no tasks are waiting, * then the message buffer will be placed at the rear of the * chain of pending messages for this message queue. */ rtems_status_code rtems_message_queue_send( Objects_Id id, void *buffer, unsigned32 size ); /* * rtems_message_queue_urgent * * DESCRIPTION: * * This routine implements the rtems_message_queue_send directive. * This directive sends the message buffer to the message queue * indicated by ID. If one or more tasks is blocked waiting * to receive a message from this message queue, then one will * receive the message. The task selected to receive the * message is based on the task queue discipline algorithm in * use by this particular message queue. If no tasks are waiting, * then the message buffer will be placed at the rear of the * chain of pending messages for this message queue. */ rtems_status_code rtems_message_queue_urgent( Objects_Id id, void *buffer, unsigned32 size ); /* * rtems_message_queue_broadcast * * DESCRIPTION: * * This routine implements the rtems_message_queue_send directive. * This directive sends the message buffer to the message queue * indicated by ID. If one or more tasks is blocked waiting * to receive a message from this message queue, then one will * receive the message. The task selected to receive the * message is based on the task queue discipline algorithm in * use by this particular message queue. If no tasks are waiting, * then the message buffer will be placed at the rear of the * chain of pending messages for this message queue. */ rtems_status_code rtems_message_queue_broadcast( Objects_Id id, void *buffer, unsigned32 size, unsigned32 *count ); /* * rtems_message_queue_receive * * DESCRIPTION: * * This routine implements the rtems_message_queue_receive directive. * This directive is invoked when the calling task wishes to receive * a message from the message queue indicated by ID. The received * message is to be placed in buffer. If no messages are outstanding * and the option_set indicates that the task is willing to block, * then the task will be blocked until a message arrives or until, * optionally, timeout clock ticks have passed. */ rtems_status_code rtems_message_queue_receive( Objects_Id id, void *buffer, unsigned32 *size_p, unsigned32 option_set, rtems_interval timeout ); /* * rtems_message_queue_flush * * DESCRIPTION: * * This routine implements the rtems_message_queue_flush directive. * This directive takes all outstanding messages for the message * queue indicated by ID and returns them to the inactive message * chain. The number of messages flushed is returned in COUNT. */ rtems_status_code rtems_message_queue_flush( Objects_Id id, unsigned32 *count ); /* * _Message_queue_Copy_buffer * * DESCRIPTION: * * This routine copies the contents of the source message buffer * to the destination message buffer. */ STATIC INLINE void _Message_queue_Copy_buffer ( void *source, void *destination, unsigned32 size ); /* * _Message_queue_Seize * * DESCRIPTION: * * This routine attempts to receive a message from the_message_queue. * If a message is available or if the RTEMS_NO_WAIT option is enabled in * option_set, then the routine returns. Otherwise, the calling task * is blocked until a message is available. If a message is returned * to the task, then buffer will contain its contents. */ boolean _Message_queue_Seize( Message_queue_Control *the_message_queue, unsigned32 option_set, void *buffer, unsigned32 *size_p ); /* * _Message_queue_Flush_support * * DESCRIPTION: * * This routine flushes all outstanding messages and returns * them to the inactive message chain. */ unsigned32 _Message_queue_Flush_support( Message_queue_Control *the_message_queue ); /* * _Message_queue_Submit * * DESCRIPTION: * * This routine provides the common foundation for the * rtems_message_queue_send and rtems_message_queue_urgent directives. */ rtems_status_code _Message_queue_Submit( Objects_Id id, void *buffer, unsigned32 size, Message_queue_Submit_types submit_type ); /* * _Message_queue_Allocate_message_buffer * * DESCRIPTION: * * This function allocates a message buffer from the inactive * message buffer chain. */ STATIC INLINE Message_queue_Buffer_control * _Message_queue_Allocate_message_buffer ( Message_queue_Control *the_message_queue ); /* * _Message_queue_Free_message_buffer * * DESCRIPTION: * * This routine frees a message buffer to the inactive * message buffer chain. */ STATIC INLINE void _Message_queue_Free_message_buffer ( Message_queue_Control *the_message_queue, Message_queue_Buffer_control *the_message ); /* * _Message_queue_Get_pending_message * * DESCRIPTION: * * This function removes the first message from the_message_queue * and returns a pointer to it. */ STATIC INLINE Message_queue_Buffer_control *_Message_queue_Get_pending_message ( Message_queue_Control *the_message_queue ); /* * _Message_queue_Append * * DESCRIPTION: * * This routine places the_message at the rear of the outstanding * messages on the_message_queue. */ STATIC INLINE void _Message_queue_Append ( Message_queue_Control *the_message_queue, Message_queue_Buffer_control *the_message ); /* * _Message_queue_Prepend * * DESCRIPTION: * * This routine places the_message at the rear of the outstanding * messages on the_message_queue. */ STATIC INLINE void _Message_queue_Prepend ( Message_queue_Control *the_message_queue, Message_queue_Buffer_control *the_message ); /* * _Message_queue_Is_null * * DESCRIPTION: * * This function places the_message at the rear of the outstanding * messages on the_message_queue. */ STATIC INLINE boolean _Message_queue_Is_null ( Message_queue_Control *the_message_queue ); /* * _Message_queue_Allocate * * DESCRIPTION: * * This function allocates a message queue control block from * the inactive chain of free message queue control blocks. */ Message_queue_Control *_Message_queue_Allocate ( unsigned32 count, unsigned32 max_message_size ); /* * _Message_queue_Free * * DESCRIPTION: * * This routine deallocates a message queue control block into * the inactive chain of free message queue control blocks. */ STATIC INLINE void _Message_queue_Free ( Message_queue_Control *the_message_queue ); /* * _Message_queue_Get * * DESCRIPTION: * * This function maps message queue IDs to message queue control * blocks. If ID corresponds to a local message queue, then it * returns the_message_queue control pointer which maps to ID * and location is set to OBJECTS_LOCAL. If the message queue ID is * global and resides on a remote node, then location is set * to OBJECTS_REMOTE, and the_message_queue is undefined. * Otherwise, location is set to OBJECTS_ERROR and * the_message_queue is undefined. */ STATIC INLINE Message_queue_Control *_Message_queue_Get ( Objects_Id id, Objects_Locations *location ); #include #include #ifdef __cplusplus } #endif #endif /* end of include file */