Studio:SCL Samples

Introduction

The following content relates to the sample files and workspace installed in %STRIDE_DIR%\Samples\SCL. This sample consists of several header files containing examples of STRIDE Communication Language (SCL) source code, and a STRIDE workspace that includes these source files for compilation.

Prerequisites

Before starting, some prerequisites must be satisfied. For details and instructions, see Studio:Desktop Installation.

Specifically:

• STRIDE must be installed on the Windows PC to be used in the training, and any required licenses must be present.

Sample Files

Begin by opening the SCL.ssw sample workspace and compiling the SCL sample code it contains. Next, examine the Source Files workspace folder (in the Files tab). It contains the sub-folders and header files that provide examples of SCL usage. Some of these files have sections that provide source code that can be used with the SCL Wizard. Refer to the SCL Wizard Examples section below for details.

This section provides a brief description for each of the sample categories.

Capture

This folder contains the following header files that demonstrate how to use SCL to identify and define interfaces on the target.

Functions.h

This header file demonstrates the usage of the scl_func and scl_function SCL pragmas.

Messages.h

This header file demonstrates the usage of the scl_msg pragma to define several different types of interfaces: one way command, one way response, two way, and broadcast messages.

TestUnits.h

This header file demonstrates the usage of the scl_test_class, scl_test_cclass, scl_test_flist, scl_test_setup, and scl_test_teardown SCL pragmas to define test unit interfaces.

Qualification

This folder contains the following header files that demonstrate how to use SCL to annotate or markup interface payloads for communication with the target.

Casting.h

This header file demonstrates the usage of the scl_cast pragma. One example shows how to use SCL to cast an integer field to an enumerated type, effectively constraining the values that may be allowed for that field. Another example shows how to use the scl_cast pragma to cast an integer pointer to a pointer to enumerated type, constraining the values that that field may point to.

FunctionCallbacks.h

This header file demonstrates how to use the scl_ptr_flist pragma to identify functions that may be associated with a function pointer field in a payload. This illustrates a concept where callback functions may be communicated between user and owner. Examples include using a form of the pragma to declare an anonymous function interface (the "default function"), and using the pragma to associate previously captured functions with the function pointer field.

Pointers.h

This header file demonstrates the use of the scl_ptr, scl_ptr_opaque, and scl_ptr_sized pragmas.
In the scl_ptr examples, it is shown how to apply the pragma to pointer fields within structure types. The effect is that these pragmas are implicitly applied to the interface payloads that use these structure types. Then it is shown how to override the pragma settings by explicitly setting pointer attributes to individual interface payload fields. The sample code shows how to apply the "OUT" and "INOUT" directional attributes to payload fields, in order for the user to receive data back from the owner when the interface call is made.
The scl_ptr_opaque example shows how to apply the pragma to a pointer type field, as well as an individual payload field.
The scl_ptr_sized examples show how to use the pragma to associate a size field with a pointer field to indicate the number of elements allocated to the pointer. The first pragma sample shows a pointer in the command payload qualified as a sized pointer, and the second sample shows the function return value qualified as a sized pointer.

Strings.h

This header file demonstrates the use of the scl_string pragma. The sample shows how to specify a pointer to short (Unicode) as a string, and an array of char as a string.

Unions.h

This header file demonstrates the use of the scl_union, and scl_union_activate pragmas. The sample shows a form of the pragma that designates a fixed active member, one that designates a discriminant with default mapping, and one that designates a discriminant with explicit mapping, using the scl_union_activate pragmas as additive specifications to the union.

Values.h

This header file demonstrates the use of the scl_values pragma to constrain the allowable values for a payload field. The sample shows a form of the pragma that specifies a list of values, and a form that specifies an enumerated type.

Advanced

This folder contains the following header files that demonstrate advanced techniques where SCL is used in a way that solves difficult customer issues.

Ioctl.h

The SCL pattern presented in the Ioctl.h header file represents an I/O Control system call. The single interface provides access for several different messages exchanged with the target. The dwCode parameter switches the structure of the input and output buffers that accompany the call. The pBufIn and pBufOut parameters are cast to unions of pointers to send/receive variable data blocks, yet the size of the payload remains constant.

The f_io_control interface is captured and its parameters qualified:

• Using the scl_values pragma, the dwCode parameter is constrained to allow only the values of the e_discriminant_codes enumerated type, as these values determine the structure of the remaining parameters.
• The pBufIn pointer parameter is cast with scl_cast to a union of pointers, the ioctl_buf_in_t type.
• The casted input union (pBufIn) is then qualified with the scl_union pragma. The input union discriminant is set to the dwCode parameter, whose value controls the active member of the input union. These members are pointers to various structures that contain send data, e.g. register ids, phone numbers, etc.
• The input union's members are then mapped to activate values in the e_discriminant_codes enumerated type - the ones that regulate input messages.
  
• The pBufOut pointer parameter is cast with scl_cast to a union of pointers, the ioctl_buf_out_t type. This union type has pointer members that have been qualified as OUT direction.
• The casted output union (pBufOut) is then qualified with the scl_union pragma.
• The output union discriminant is set to the dwCode parameter.
• The members of the output union are mapped to activate values in the e_discriminant_codes enumerated type - the ones that regulate output results. This is done with the scl_union_activate pragmas.
  
• The pdwActualOut parameter is qualified to the OUT direction, to receive read messages as a result of a READMSG system call.

VariantMessage.h

Like the pattern in Ioctl.h, the Variant Message pattern is a message call where the parameter represents varying information, controlled by a discriminant field. However, in this case the payload varies in size based on the discriminant value.

The f_send_variant_msg interface is captured and its parameters are qualified:

• The msg parameter is cast from the varmsg_t structure type to the varmsg_cast_t structure, which overlays the same msg_id and body_len members that the original structure had, but the last member of the original structure, the single element char array, is replaced by a varmsg_union_t union member. This is a union of structures that is discriminated by the set of values that will be assigned to the msg_id member. The body_len field will contain the final payload size, which can be initialized by using the f_get_dial_params_size, f_get_register_params_size, f_get_sendmsg_params_size, and f_get_sendmsgack_params_size utilities.
• The msg_id member is constrained to a subset of the message code enumerations defined in the e_discriminant_codes type in the included types.h file. This is done with the scl_values pragma.
• The casted union member is then qualified with the scl_union pragma. The union discriminant is set to the msg_id member.
• The members of the union are mapped to activate values that have been constrained to the msg_id member earlier. This is done with the scl_union_activate pragmas.
  

SCL Wizard Examples

The SCL Wizard streamlines and simplifies working with SCL by allowing you to quickly capture interfaces and accurately qualify payloads and types. Refer to the SCL Wizard section of the STRIDE Online Help for information on how to access the SCL Wizard dialogs within the Studio user interface.

The following sections provide training exercises for different categories of SCL generation.

Capturing Functions

1. Navigate to the Interfaces tab in the Workspace Pane.

2. Expand the Workspace tree so that the Type Info | Global Functions folder is visible. Expand the folder so that the functions contained in the Functions.h file folder is visible.
3. Select/highlight and capture the f_sclwiz_capture_ex function (use the right-click menu or Alt+C).
4. Compile the workspace.

Type Casting

1. Navigate to the Interfaces tab in the Workspace Pane.
2. Navigate to the f_sclwiz_cast_ex interface in the Casting.h folder, under the Interfaces folder. Expand the parameter tree completely.
3. Use the SCL Cast Wizard to cast the pcast integer pointer field in the payload. Click browse button and set the Cast To Type to the enum_types enum type, located under the Enums folder in the data type browser tree. Type a pointer designator ("*") after the enum_types string in the Cast To Type field in the wizard. Click the Finish button.
4. Compile the workspace.

Function Callbacks

1. Navigate to the f_sclwiz_funcptr_ex_1 interface in the FunctionCallbacks.h folder, under the Interfaces folder. Expand the ParameterList tree completely.
2. Use the SCL Function Pointer Wizard (click on the Specify Function Candidates item in the context menu, or use Alt+F) to specify an anonymous callback for the pFunc1 field in the parameter list.
   • Click on the Candidate's list box.
   • Name the anonymous callback "MyCallback1".
   • Click the Finish button.

1. Navigate to the f_sclwiz_funcptr_ex_2 interface in the FunctionCallbacks.h folder, under the Interfaces folder. Expand the parameter tree completely.
2. Use the SCL Function Pointer Wizard to specify a named callback list of candidates for the pFunc2 field in the parameter list.
   • Click the browse button in the Candidate's list box and specify the f_candidate_1, f_candidate_2, f_candidate_3, f_candidate_4, and f_candidate_5 candidate functions.
   • Click the Finish button.
3. Compile the workspace.

Sized Pointers

1. Navigate to the f_sclwiz_sizedptr_ex interface in the Pointers.h folder, under the Interfaces folder. Expand the parameter tree completely.
2. Use the SCL Pointer Wizard to specify a sized pointer for the pstr field in the payload (select the field and click on the Qualify Pointer item in the context menu, or use Alt+Q).
   • Specify a sized pointer type, PRIVATE usage, and IN direction. Click the Next button.
   • Specify a variable type size field. Click the browse button to the right of the variable size field. Select the size field in the interface payload as the size variable. Click the OK button on the browser dialog.
   • Click the browse button to the right of the Maximum Size field. Select the MAX_SIZE symbol and click the OK button on the browser dialog.
   • Click the Finish button.
3. Compile the workspace.

Strings

1. Navigate to the f_sclwiz_string_ex interface in the Strings.h folder, under the Interfaces folder. Expand the parameter tree completely.
2. Use the SCL String Wizard to qualify the pstr field in the payload as an SCL string (select the field and click on the Qualify Pointer as String item in the context menu, or use Alt+S).
   • Click the browse button to the right of the Maximum Size field. Select the MAX_STRING_SIZE symbol and click the OK button on the browser dialog.
   • Click the Finish button.
3. Compile the workspace.

Unions

1. Navigate to the f_sclwiz_union_ex interface in the Unions.h folder, under the Interfaces folder. Expand the parameter tree completely.
2. Use the SCL Union Wizard to qualify the u field in the payload as an SCL union (select the field and click on the Qualify Union item in the context menu, or use Alt+Q).
   • Specify a discriminant field for the union. Click the browse button to the right of the Discriminant Field. Select the disc field in the interface payload as the union discriminant. Click the OK button on the browser dialog.
   • Check the Map Members to Values check box.
   • Select the m_intptr union member in the Members list box. Click the Add button. Select the UNION_DISC_INTPTR symbol and click the OK button on the browser dialog.
   • Repeat the previous step to map the m_charptr union member to the UNION_DISC_CHARPTR value, and the m_floatptr union member to the UNION_DISC_FLOATPTR value.
   • Click the Finish button.
3. Compile the workspace.

Constraining Values

1. Navigate to the f_sclwiz_values_ex interface in the Values.h folder, under the Interfaces folder. Expand the parameter tree completely.
2. Use the SCL Values Wizard to constrain the val field in the payload to a set of values (select the field and click on the Specify Values item in the context menu, or use Alt+V).
   • Select the Specify Values List radio button and click the browse button in the Values list box. Select the HDR_10 through HDR_15 symbols and click the OK button to exit the browser dialog.
   • Click the Finish button.
3. Compile the workspace.