www.pudn.com > SobelEdge_all_2.rar > scom.h
/*
* Copyright 2003 by Texas Instruments Incorporated.
* All rights reserved. Property of Texas Instruments Incorporated.
* Restricted rights to use, duplicate or disclose this code are
* granted through contract.
*
*/
/* "@(#) ReferenceFrameworks 2.20.00.08 07-18-03 (swat-f02)" */
/*
* ======== scom.h ========
*
* Synchronized COMmunication module
*
* This module implements message passing between tasks. It lets the user
* create any number of named, synchronized queues, and put messages
* to such queues and receive messages from them. Messages are buffers
* of arbitrary sizes. The message structure's first field must be
* QUE_Elem. For example:
* struct MyMsg {
* QUE_Elem elem;
* Ptr buffer;
* }
*
* Usage example:
*
* 0. Tasks A and B agree that A sends messages of some type MyMsg to B,
* via an SCOM queue named "queueForB".
*
* 1. Some code (typically B's initialization part) creates the SCOM queue
* with a unique name:
* SCOM_Handle queueB = SCOM_create( "queueForB" );
*
* .---. .---.
* | A | ========> | B |
* `---' `---'
*
*
* 2. A gets the reference to the SCOM queue by supplying its name:
* SCOM_Handle queueB = SCOM_open( "queueForB" );
* B can do the same if it didn't remember it from the call to
* SCOM_create()
*
* .---. .---.
* | A | ========> | B |
* `---' : : `---'
* :...........: :......:
*
* 3. Someone, typically sender task A, allocates a buffer of type MyMsg:
* MyMsg * msg = MEM_alloc(someMemSegId, sizeof( MyMsg ), 0 );
* The msg could also be static.
*
* .---->[ ]
* |
* .--+. .---.
* |A *| ========> | B |
* `---' : : `---'
* :...........: :......:
*
* 4. A writes some information, p, into the message buffer:
*
* .---->[p ]
* |
* .--+. .---.
* |A *| ========> | B |
* `---' : : `---'
* :...........: :......:
*
* 5. A sends the message to B by doing SCOM_putMsg( queueB, msg );
* There can be an unlimited number of messages waiting on an SCOM queue.
*
* [p ]<--.
* |
* .---. | .---.
* | A | ===(*)==> | B |
* `---' : : `---'
* :...........: :......:
*
*
* 6. B receives the message by saying,
* MyMsg * msg = SCOM_getMsg( queueB, SYS_FOREVER ); SYS_FOREVER
* is a timeout value, indicating how long to wait until there's a message
* available on the SCOM queue. 0 as a timeout means "don't wait."
*
* [p ]<---------.
* |
* .---. .+--.
* | A | ========> |* B|
* `---' : : `---'
* :...........: :......:
*
* 7. If B wants to write something into the message buffer and send it back
* to A (i.e. if they want a two-way communication), we need an additional
* queue for A, symetrical to the one for B.
*/
#ifndef SCOM_
#define SCOM_
#ifdef __cplusplus
extern "C" {
#endif
/* SCOM object handle */
typedef struct SCOM_Obj SCOM_Obj, *SCOM_Handle;
/* SCOM object creation attributes */
typedef struct SCOM_Attrs {
Char dummy; /* no attributes at present */
} SCOM_Attrs;
/* default SCOM creation attributes */
extern SCOM_Attrs SCOM_ATTRS;
/*
* ======== SCOM_init ========
*
* Initialize the module.
*/
Void SCOM_init( Void );
/*
* ======== SCOM_exit ========
*
* Finalize the module.
*/
Void SCOM_exit( Void );
/*
* ======== SCOM_create ========
*
* Create a new SCOM queue under given name
*/
SCOM_Handle SCOM_create(
String queueName, /* ID (name) of the SCOM queue to be created */
SCOM_Attrs * attrs /* SCOM object attributes; only NULL supported */
);
/*
* ======== SCOM_open ========
*
* Get a reference to an existing SCOM queue by its name
*/
SCOM_Handle SCOM_open(
String queueName ); /* ID (name) of the SCOM queue to be found */
/*
* ======== SCOM_delete ========
*
* Delete the SCOM queue
*/
Bool SCOM_delete(
SCOM_Handle scomQueue /* handle of the SCOM queue to be deleted */
);
/*
* ======== SCOM_putMsg ========
*
* Place the message on a synchronized queue
*/
Void SCOM_putMsg(
SCOM_Handle scomQueue, /* SCOM queue to which message should be put */
Ptr msg /* message to be sent */
);
/*
* ======== SCOM_getMsg ========
*
* Receive a message from a synchronized queue
*/
Ptr SCOM_getMsg(
SCOM_Handle scomQueue, /* SCOM queue from which to take a message */
Uns timeout /* semaphore timeout */
);
#ifdef __cplusplus
}
#endif /* extern "C" */
#endif /* SCOM_ */