Semaphore and Mutex Function Replacement

You can create a code replacement table for a custom target that supports concurrent execution. Create table entries that specify custom implementations of semaphore or mutex operations. The table must have four semaphore entries, four mutex entries, or both, and include the table in a custom code replacement library. (The semaphore or mutex entries are mutually dependent. Provide them in complete sets of four.)

Note

A custom target that supports concurrent multitasking must set the target configuration parameter ConcurrentExecutionCompliant. For more information, see Support Concurrent Execution of Multiple Tasks.

If the build process generates semaphore or mutex function calls for data transfer between tasks during code generation for a multicore target environment, use a custom library. The library can specify code replacements for custom semaphore or mutex implementations that are optimal for your target environment. Using the Code Replacement Tool (crtool) or equivalent code replacement functions, you can:

Configure code replacement table entries for custom semaphore or mutex functions. During system startup, execution of the code for data transfer between tasks, and system shutdown the generated code calls these functions.
Configure DWork arguments that represent global data, which the semaphore or mutex functions access. A DWork pointer is passed to the model entry functions.

Generated mutex and semaphore code typically consists of these elements:

Code	Generated Code
Model initialization	Initialization function call that creates a mutex or semaphore function to control entry to a critical section of code.
Model step	Before code for a data transfer between tasks enters the critical section, mutex lock or semaphore wait function calls reserve the critical section of code. After code for a data transfer between tasks finishes executing the critical section, mutex unlock or semaphore post function calls release the critical section of code.
Model termination	Optional destroy function call to delete the mutex or semaphore explicitly.

This example shows how to create code replacement table entries for a mutex replacement scenario. You configure a multicore target model for concurrent execution and for data transfer between tasks of differing rates, which Rate Transition blocks handle. In the generated code for the model, each Rate Transition block has a separate, unique mutex. Mutex lock and unlock operations within the Rate Transition block generated code share access to the same global data. They achieve this by using the unique mutex created for that Rate Transition block.

Open the Code Replacement Tool.
Create and open a new table.
Name the table crl_table_rt_mutex.
Create an entry for a mutex initialization function replacement.
1. Select File > New entry > Semaphore entry to open a new table entry for configuring a semaphore or mutex replacement.
2. In the Mapping Information tab, use the Function parameter to select Mutex Init. Initial default values for the table entry appear. In the Conceptual function section, typically you can leave the argument settings at their defaults.
3. In the DWork attributes section, the Allocate DWork option is selected. The dialog box provides a unique entry tag for the DWork argument d1.
  On the DWork attributes pane, configure a DWork argument to the replacement function. The DWork argument supports sharing of a semaphore or mutex between:
  - Code that creates the semaphore or mutex
  - Code that requests and relinquishes access
  - Code that deletes the semaphore or mutex
  In this example, the DWork argument for the Mutex Init function defines a unique entry tag, entry_25576. That function also defines DWork arguments for Mutex Lock, Mutex Unlock, and Mutex Destroy, which reference the entry tag to share the DWork data.
  The only data type supported for the DWork Data type parameter is void*.
4. In the Replacement function section, enter a function name in the Name field. This example uses myMutexCreate. In the list of Function arguments, leave the DWork argument d1 data type as void**.
  The C function signature preview is:
```
void myMutexCreate (void** d1);
```
5. In the Replacement function section, select Function modifies internal or global state. This option instructs the code generator not to optimize away the implementation function described by this entry because it accesses global memory values. Click Apply. Optionally, you can click Validate entry to validate the information entered in the Mapping Information tab.
  To create a sample table entry, configure the replacement function signature without the replacement function and its build information. If header and source files for these functions are available, select the Build Information table to specify them.
6. The Mutex Init table entry is complete. Optionally, you can save the table to a file, and inspect the MATLAB^® code created for the table definition so far.
Repeat the following sequence to create the table entries for the mutex lock, unlock, and destroy function replacements. Each table entry references the DWork unique tag entry, entry_25576, defined in the Mutex Init table entry.
1. Select File > New entry > Semaphore entry.
2. In the Mapping Information tab, use the Function parameter to select Mutex Lock, Mutex Unlock, or Mutex Destroy. Initial default values for the table entry appear. In the Conceptual function section, typically you can leave the argument settings at their defaults.
3. For a Rate Transition block mutex, the wait, post, and destroy functions operate on the DWork allocated at system startup by the mutex initialization function. In the DWork attributes section, verify that the Allocate DWork option is cleared. From the DWork Allocator entry drop-down list, select the entry tag matching the value in the Mutex Init table entry. In this example, the entry tag is entry_25576.
4. In the Replacement function section, Name field, enter a function name. This example uses myMutexLock, myMutexUnlock, and myMutexDelete. In the list of Function arguments, leave the DWork argument d1 data type as void*.
5. In the Implementation attributes section, select the option Function modifies internal or global state. This option instructs the code generator not to optimize away the implementation function described by this entry because it accesses global memory values.
6. Optionally, supply build information for the replacement function on the Build Information tab.
7. Click Apply. In the middle pane, right-click the table entry and select Validate entry(s).
When you have added the table entries for Mutex Lock, Mutex Unlock, and Mutex Destroy to the entry for Mutex Init, the rate transition mutex replacement table is complete. In the left-most pane, right-click the table name and select Validate table. Address errors and repeat the table validation.
Save the table to a MATLAB file in your working folder, for example, using File > Save table. The name of the saved file is the table name, crl_table_rt_mutex, with an .m extension. Optionally, you can open the saved file and examine the MATLAB code for the code replacement table definition.

To test this example:

Register the code replacement mapping.
Create a model that contains a rate transition for which the build process generates mutex function calls. For example:
Configure the model for a multicore target environment and the following settings:
- On the Solver pane, select a fixed-step solver.
- On the Code Generation pane, select an ERT-based system target file.
- On the Code Generation > Interface pane, select the code replacement library that contains your mutex entry.

Semaphore and Mutex Function Replacement

See Also

Topics