Studio:Scl msg
The scl_msg pragma
The scl_msg pragma allows the user to define a messaging interface. Messages are defined by combining a Unique 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.
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);
The STRIDE Message ID (SMID)
The SMID is a 32-bit structure consisting of a unique ID and a set of message attributes. The SCM defines the SUID portion as the first 24 bits of the SMID (bits 0 — 23), allowing unique identifiers up to 16,777,215. The message attributes use the highest 8 bits of the SMID (bits 24 — 31).
Each SCL-compliant message within the system must be assigned a unique message ID.
SMID Attributes
The attributes are used to declare the message type, describe how to send the option payload and indicate, if applicable, the pointer memory usage attribute for the payload. The attributes, shown below, are the message type (MT), send type for command (STc), send type for response (STr), pointer usage for command (PUc), pointer usage for response (PUr), and Access Class (AC).
Message Type (MT) Attributes
The Message Type (MT) attribute defines the type of message being used for communication between the owner and user. The following values are used for different message types:
| 00 | One-way command |
| 01 | One-way response |
| 10 | Two-way command-response |
| 11 | Broadcast message |
Send Type for Command (STc) Attributes
The Send Type (ST) attribute is used to indicate how to transmit the payload. There are two ways to send the payload: by value or by pointer. The STRIDE Runtime is required to use the ST attribute when determining whether to route locally or remotely across platform boundaries. The following tables describe the ST attribute settings:
| 0 | Pointer |
| 1 | Value |
Send Type for Response (STr) Attributes
| 0 | Pointer |
| 1 | Value |
Note: When a command or response does not contain a payload, the ST attribute is set to zero (0).
When a payload is passed by pointer, a Pointer Usage (PU) attribute is required. The PU attribute indicates if the payload is using pool memory or private memory. When the PU attribute indicates pool, the SCM requires that the memory be allocated from the common pool being used by the system. When the PU attribute indicates private, the STRIDE Runtime environment makes no assumptions on how the payload memory is being managed between the Owner and User when they are executing on the same target platform. If the payload crosses platform boundaries, however, the Runtime is required to dynamically allocate memory from the common pool. The temporary memory that is allocated is used to hold the payload, and the address of the memory is passed to the reader. Once the reader returns the message memory to the Runtime, the temporary memory is automatically freed. The original memory from the sender is not affected or synchronized with the other platform.
The PU attributes are listed below:
Pointer Usage for Command (PUc) Attribute
| 0 | Pool |
| 1 | Private |
Pointer Usage for Response (PUr) Attribute
| 0 | Pool |
| 1 | Private |
Access Class (AC) Attributes
The Access Class (AC) attribute ensures that the intercept module will not register each SUID, and function calls with no registered owner will be routed to the intercept module STID.
| 00 | Message |
| 01 | Function |
| 10 | Reserved |
| 11 | System/Application |
The following is an excerpt of the installed header file, sr.h, showing the definitions of the SMID attributes:
/* Message Types (MT) */ #define srMT_ONE_CMD 0x00000000 #define srMT_ONE_RSP 0x01000000 #define srMT_TWO 0x02000000 #define srMT_BRD 0x03000000 /* Abbreviations MT */ #define srMT_ONE srMT_ONE_CMD #define srMT_ONEc srMT_ONE_CMD #define srMT_ONEr srMT_ONE_RSP /* Send Type for Command (ST_CMD) */ #define srST_CMD_PTR 0x00000000 #define srST_CMD_VAL 0x04000000 /* Send Type for Response (ST_RSP) */ #define srST_RSP_PTR 0x00000000 #define srST_RSP_VAL 0x08000000 /* Pointer Usage for Command (PU_CMD) */ #define srPU_CMD_POL 0x00000000 #define srPU_CMD_PRI 0x10000000 /* Pointer Usage for Response (PU_RSP) */ #define srPU_RSP_POL 0x00000000 #define srPU_RSP_PRI 0x20000000 /* Access Class (AC) */ #define srAC_MSG 0x00000000 #define srAC_FUNCTION 0x40000000 #define srAC_SYS 0x80000000
Refer to the [STRIDE Runtime Developer's Guide] for additional information and usage of these definitions.
The STRIDE Unique ID (SUID)
The SUID is a unique 24-bit value used to identify interfaces such as remote function calls and messages. A SUID is required when using a two-way message in order to identify the message user and allow the response payload to be routed correctly. The message user provides this unique ID to the STRIDE Runtime, which in turn sends it to the message owner. The message owner is then required to supply this same unique ID when sending a response back to the STRIDE Runtime, so that the response payload can be routed correctly.
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(1) #pragma scl_msg(2) #pragma scl_msg(3) #pragma scl_msg(4)
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.