Studio:Scl msg: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
m (Text replace - 'Category: Messages' to 'Category:Studio:Messages') |
||
(14 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
= The scl_msg pragma = | = The scl_msg pragma = | ||
The scl_msg pragma allows the user to define a messaging interface. Messages are defined by combining a Unique [[#The_STRIDE_Unique_ID_.28SUID.29|STRIDE Identifier (SUID)]] with message attributes to create a STRIDE Message Id (SMID). The SMID is then associated with command and/or response payload type definitions. | The scl_msg pragma allows the user to define a messaging interface. Messages are defined by combining a Unique [[SCL_Structure#The_STRIDE_Unique_ID_.28SUID.29|STRIDE Unique Identifier (SUID)]] with message attributes to create a [[SCL_Structure#The_STRIDE_Message_ID_.28SMID.29|STRIDE Message Id (SMID)]]. The SMID is then associated with command and/or response payload type definitions. | ||
== Syntax == | == Syntax == | ||
Line 40: | Line 40: | ||
|- | |- | ||
| ''void'' | | ''void'' | ||
| | | | ||
| This is a special parameter which can only be used if the message is a command/response and there is only a response payload (i.e., no command payload). | | This is a special parameter which can only be used if the message is a command/response and there is only a response payload (i.e., no command payload). | ||
|} | |} | ||
Line 50: | Line 50: | ||
#pragma scl_msg (TWO_WAY_CMD_SMID, void, TResponse); | #pragma scl_msg (TWO_WAY_CMD_SMID, void, TResponse); | ||
== Examples == | == Examples == | ||
Line 194: | Line 62: | ||
=== Example 1 === | === Example 1 === | ||
<source lang=c> | |||
/* STRIDE Message IDs (SMIDs) defining messages without payloads */ | |||
/* SUID = 1, Message Type = One-way Command */ | |||
#define OneWayCmd 1 | srMT_ONEc | |||
/* SUID = 2, Message Type = One-way Response */ | |||
#define OneWayRsp 2 | srMT_ONEr | |||
/* SUID = 3, Message Type = Two-way Command/Response */ | |||
#define TwoWayMsg 3 | srMT_TWO | |||
/* SUID = 4, Message Type = Broadcast Response */ | |||
#define BrdCstRsp 4 | srMT_BRD | |||
/* Use the scl_msg pragma to identify the four messages without payloads */ | |||
#pragma scl_msg(OneWayCmd) | |||
#pragma scl_msg(OneWayRsp) | |||
#pragma scl_msg(TwoWayMsg) | |||
#pragma scl_msg(BrdCstRsp) | |||
</source> | |||
=== Example 2 === | === Example 2 === | ||
<source lang=c> | |||
/* STRIDE Message IDs (SMIDs) defining messages with command payloads. */ | |||
/* SUID = 1, Message Type = One-way Command, */ | |||
/* Command Send Type = By Pointer, Pointer Memory Usage = Private */ | |||
#define OneWayCmd 1 | srMT_ONEc | srST_CMD_PTR | srPU_CMD_PRI | |||
/* SUID = 2, Message Type = Two-way Command/Response, */ | |||
/* Command Send Type = By Value */ | |||
#define TwoWayMsg 2 | srMT_TWO | srST_CMD_VAL | |||
/* Structure defining the command payload used with both messages */ | |||
typedef struct { | |||
int f1; | |||
char f2; | |||
} CmdPayload_t; | |||
/* Use the scl_msg pragma to associate the command payload with both SMIDs */ | |||
#pragma scl_msg(OneWayCmd, CmdPayload_t) | |||
#pragma scl_msg(TwoWayMsg, CmdPayload_t) | |||
</source> | |||
=== Example 3 === | === Example 3 === | ||
<source lang=c> | |||
/* STRIDE Message IDs (SMIDs) defining messages with response payloads. */ | |||
/* SUID = 1, Message Type = One-way Response, */ | |||
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */ | |||
#define OneWayRsp 1 | srMT_ONEr | srST_RSP_PTR | srPU_RSP_POL | |||
/* SUID = 2, Message Type = Two-way Command/Response, */ | |||
/* Command Send Type = No Payload, Response Send Type = By Value */ | |||
#define TwoWayMsg 2 | srMT_TWO | srST_RSP_VAL | |||
/* SUID = 3, Message Type = Broadcast Response, */ | |||
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */ | |||
#define BrdCstRsp 3 | srMT_BRD | srST_RSP_PTR | srPU_RSP_POL | |||
/* Structure defining the response payload used with the messages */ | |||
typedef struct { | |||
int f1; | |||
char f2; | |||
} RspPayload_t; | |||
/* Use the scl_msg pragma to associate the payload with each of the SMIDs */ | |||
#pragma scl_msg( OneWayRsp, RspPayload_t ) | |||
#pragma scl_msg( TwoWayMsg, RspPayload_t ) | |||
#pragma scl_msg( BrdCstRsp, RspPayload_t ) | |||
</source> | |||
=== Example 4 === | === Example 4 === | ||
<source lang=c> | |||
#include <sr.h> | |||
/* STRIDE Message ID (SMID) defining a two-way message with */ | |||
/* with a command and a response payload. */ | |||
/* SUID = 1, Message Type = Two-way Command/Response, */ | |||
/* Command Send Type = By Value, Response Send Type = By Value */ | |||
#define TwoWayMsg 1 | srMT_TWO | srST_CMD_VAL | srST_RSP_VAL | |||
/* Structure defining the command payload for the message */ | |||
typedef struct { | |||
int f1; | |||
char f2; | |||
} CmdPayload_p; | |||
/* Structure defining the response payload for the message */ | |||
typedef struct { | |||
short f1; | |||
float f2; | |||
} RspPayload_r; | |||
/* Use the scl_msg pragma to associate both payloads with the SMID */ | |||
#pragma scl_msg ( TwoWayMsg, CmdPayload_p, RspPayload_r ) | |||
</source> | |||
=== Example 5 === | === Example 5 === | ||
<source lang=c> | |||
#include <sr.h> | |||
/* STRIDE Message ID (SMID) defining a two-way message with */ | |||
/* with no command payload and a response payload. */ | |||
/* SUID = 1, Message Type = Two-way Command/Response, */ | |||
/* Command Send Type = By Value, Response Send Type = By Value */ | |||
#define TwoWayMsg 1 | srMT_TWO | srST_RSP_VAL | |||
/* Structure defining the response payload for the message */ | |||
typedef struct { | |||
short f1; | |||
float f2; | |||
} RspPayload_r; | |||
/* Use the scl_msg pragma to associate both payloads with the SMID */ | |||
#pragma scl_msg ( TwoWayMsg, void, RspPayload_r ) | |||
</source> | |||
== See Also == | == See Also == | ||
* The [[SCL_Structure|SCL Structure]] page for more information on the format of the STRIDE Unique ID (SUID), and SMIDs. | * The [[SCL_Structure|SCL Structure]] page for more information on the format of the STRIDE Unique ID (SUID), and SMIDs. | ||
* For additional information on scl_msg, including constraints, refer to the section on scl_msg in the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]]. | |||
[[Category: | [[Category:Studio:Messages]] | ||
[[Category:Studio:SCL]] |
Latest revision as of 00:44, 21 August 2009
The scl_msg pragma
The scl_msg pragma allows the user to define a messaging interface. Messages are defined by combining a Unique STRIDE Unique Identifier (SUID) with message attributes to create a STRIDE Message Id (SMID). The SMID is then associated with command and/or response payload type definitions.
Syntax
#pragma scl_msg(SMID) #pragma scl_msg(SMID, cmd-payload) #pragma scl_msg(SMID, rsp-payload) #pragma scl_msg(SMID, cmd-payload, rsp-payload) #pragma scl_msg(SMID, void, rsp-payload)
Parameters | Type | Description |
SMID | Integer | SUID + attributes from which the message type and other properties are determined |
cmd-payload | Integer | Optional name of the data type for the command payload. If omitted, then: The message is a one-way command or a two-way message, and the User sends an empty payload to the Owner, |
rsp-payload | Integer | Optional name of the data type for the response payload. If omitted then: The message is a one-way response or a two-way message, and the Owner is responding with an empty payload to the User, |
void | This is a special parameter which can only be used if the message is a command/response and there is only a response payload (i.e., no command payload). |
Notes
- The SMID must be a non-parameterized macro name that resolves to an integer constant expression. The macro name will become the name of the message and cannot collide with the name of any other name or function.
- The SMID, cmd-payload, rsp-payload, and cmd-payload rsp-payload must all be integer constant expressions that evaluate to a number in the range of 0 — 232 - 1 and follow the rules for a SMID.
- In order to describe a two-way message with only a return payload, the type void is allowed only in the command position in a two-way message:
#pragma scl_msg (TWO_WAY_CMD_SMID, void, TResponse);
Examples
Five examples of the scl_msg pragma are shown below:
- The first example uses the scl_msg pragma to define a set of messages without payloads.
- The second example uses the scl_msg pragma to define a one-way command and a two-way command/response. Both messages are defined with a command payload.
- The third example uses the scl_msg pragma to define a one-way-response, a two-way command/response and a broadcast response; all with message payloads.
- The fourth example uses the scl_msg pragma to define a two-way command/response with associated payloads.
- The fifth example uses the scl_msg pragma and the void parameter to define a two-way command/response with a response payload and an empty command payload.
Example 1
/* STRIDE Message IDs (SMIDs) defining messages without payloads */
/* SUID = 1, Message Type = One-way Command */
#define OneWayCmd 1 | srMT_ONEc
/* SUID = 2, Message Type = One-way Response */
#define OneWayRsp 2 | srMT_ONEr
/* SUID = 3, Message Type = Two-way Command/Response */
#define TwoWayMsg 3 | srMT_TWO
/* SUID = 4, Message Type = Broadcast Response */
#define BrdCstRsp 4 | srMT_BRD
/* Use the scl_msg pragma to identify the four messages without payloads */
#pragma scl_msg(OneWayCmd)
#pragma scl_msg(OneWayRsp)
#pragma scl_msg(TwoWayMsg)
#pragma scl_msg(BrdCstRsp)
Example 2
/* STRIDE Message IDs (SMIDs) defining messages with command payloads. */
/* SUID = 1, Message Type = One-way Command, */
/* Command Send Type = By Pointer, Pointer Memory Usage = Private */
#define OneWayCmd 1 | srMT_ONEc | srST_CMD_PTR | srPU_CMD_PRI
/* SUID = 2, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value */
#define TwoWayMsg 2 | srMT_TWO | srST_CMD_VAL
/* Structure defining the command payload used with both messages */
typedef struct {
int f1;
char f2;
} CmdPayload_t;
/* Use the scl_msg pragma to associate the command payload with both SMIDs */
#pragma scl_msg(OneWayCmd, CmdPayload_t)
#pragma scl_msg(TwoWayMsg, CmdPayload_t)
Example 3
/* STRIDE Message IDs (SMIDs) defining messages with response payloads. */
/* SUID = 1, Message Type = One-way Response, */
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */
#define OneWayRsp 1 | srMT_ONEr | srST_RSP_PTR | srPU_RSP_POL
/* SUID = 2, Message Type = Two-way Command/Response, */
/* Command Send Type = No Payload, Response Send Type = By Value */
#define TwoWayMsg 2 | srMT_TWO | srST_RSP_VAL
/* SUID = 3, Message Type = Broadcast Response, */
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */
#define BrdCstRsp 3 | srMT_BRD | srST_RSP_PTR | srPU_RSP_POL
/* Structure defining the response payload used with the messages */
typedef struct {
int f1;
char f2;
} RspPayload_t;
/* Use the scl_msg pragma to associate the payload with each of the SMIDs */
#pragma scl_msg( OneWayRsp, RspPayload_t )
#pragma scl_msg( TwoWayMsg, RspPayload_t )
#pragma scl_msg( BrdCstRsp, RspPayload_t )
Example 4
#include <sr.h>
/* STRIDE Message ID (SMID) defining a two-way message with */
/* with a command and a response payload. */
/* SUID = 1, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value, Response Send Type = By Value */
#define TwoWayMsg 1 | srMT_TWO | srST_CMD_VAL | srST_RSP_VAL
/* Structure defining the command payload for the message */
typedef struct {
int f1;
char f2;
} CmdPayload_p;
/* Structure defining the response payload for the message */
typedef struct {
short f1;
float f2;
} RspPayload_r;
/* Use the scl_msg pragma to associate both payloads with the SMID */
#pragma scl_msg ( TwoWayMsg, CmdPayload_p, RspPayload_r )
Example 5
#include <sr.h>
/* STRIDE Message ID (SMID) defining a two-way message with */
/* with no command payload and a response payload. */
/* SUID = 1, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value, Response Send Type = By Value */
#define TwoWayMsg 1 | srMT_TWO | srST_RSP_VAL
/* Structure defining the response payload for the message */
typedef struct {
short f1;
float f2;
} RspPayload_r;
/* Use the scl_msg pragma to associate both payloads with the SMID */
#pragma scl_msg ( TwoWayMsg, void, RspPayload_r )
See Also
- The SCL Structure page for more information on the format of the STRIDE Unique ID (SUID), and SMIDs.
- For additional information on scl_msg, including constraints, refer to the section on scl_msg in the SCL Reference Guide.