coder.wref - Indicate write-only data to pass by reference - MATLAB (original) (raw)

Indicate write-only data to pass by reference

Syntax

Description

coder.wref([arg](#bvms7rl-arg)) indicates thatarg is a write-only expression or variable to pass by reference to an external C/C++ function. Use coder.wref only inside acoder.ceval call. This function enables the code generator to optimize the generated code by ignoring prior assignments to arg in your MATLAB® code, because the external function is assumed to not read from the data. Write to all the elements of arg in your external code to fully initialize the memory.

Note

The C/C++ function must fully initialize the memory referenced bycoder.wref(arg). Initialize the memory by assigning values to every element of arg in your C/C++ code. If the generated code tries to read from uninitialized memory, it can cause undefined run-time behavior.

Examples

Pass Array by Reference as Write-Only

Suppose that you have a C function init_array.

void init_array(double* array, int numel) { for(int i = 0; i < numel; i++) { array[i] = 42; } }

The C function defines the input variable array as a pointer to a double.

Call the C function init_array to initialize all elements of y to 42:

... Y = zeros(5, 10); coder.ceval('init_array', coder.wref(Y), int32(numel(Y))); ...

Pass Multiple Arguments as a Write-Only Reference

... U = zeros(5, 10); V = zeros(5, 10); coder.ceval('my_fcn', coder.wref(U), int32(numel(U)), coder.wref(V), int32(numel(V))); ...

Pass Class Property as a Write-Only Reference

... x = myClass; x.prop = 1; coder.ceval('foo', coder.wref(x.prop)); ...

Pass Structure as a Write-Only Reference

To indicate that the structure type is defined in a C header file, use coder.cstructname.

Suppose that you have the C function init_struct. This function writes to the input argument but does not read from it.

#include "MyStruct.h"

void init_struct(struct MyStruct *my_struct) { my_struct->f1 = 1; my_struct->f2 = 2; }

The C header file, MyStruct.h, defines a structure type namedMyStruct:

#ifndef MYSTRUCT #define MYSTRUCT

typedef struct MyStruct { double f1; double f2; } MyStruct;

void init_struct(struct MyStruct *my_struct);

#endif

In your MATLAB function, pass a structure as a write-only reference toinit_struct. Use coder.cstructname to indicate that the structure type for s has the nameMyStruct that is defined in the C header fileMyStruct.h.

function y = foo %#codegen y = 0; coder.updateBuildInfo('addSourceFiles','init_struct.c');

s = struct('f1',1,'f2',2); coder.cstructname(s,'MyStruct','extern','HeaderFile','MyStruct.h'); coder.ceval('init_struct', coder.wref(s));

To generate standalone library code, enter:

codegen -config:lib foo -report

Pass Structure Field as a Write-Only Reference

... s = struct('s1', struct('a', [0 1])); coder.ceval('foo', coder.wref(s.s1.a)); ...

You can also pass an element of an array of structures:

... c = repmat(struct('u',magic(2)),1,10); b = repmat(struct('c',c),3,6); a = struct('b',b); coder.ceval('foo', coder.wref(a.b(3,4).c(2).u)); ...

Input Arguments

collapse all

Argument to pass by reference to an external C/C++ function. The argument cannot be a class, a System object™, a cell array, or an index into a cell array.

Limitations

You cannot pass these data types by reference:
- Class or System object
- Cell array or index into a cell array
If a property has a get method, a set method, or validators, or is a System object property with certain attributes, then you cannot pass the property by reference to an external function. See Passing by Reference Not Supported for Some Properties.
You cannot use coder.wref to change the size of an array that is initialized in your MATLAB code.

Tips

If arg is an array, then coder.wref(arg) provides the address of the first element of the array. Thecoder.wref(arg) function does not contain information about the size of the array. If the C function must know the number of elements of your data, pass that information as a separate argument. For example:
coder.ceval('myFun',coder.wref(arg),int32(numel(arg));
When you pass a structure by reference to an external C/C++ function, use coder.cstructname to provide the name of a C structure type that is defined in a C header file.
In MATLAB, coder.wref results in an error. To parameterize your MATLAB code so that it can run in MATLAB and in generated code, use coder.target.
You can use coder.opaque to declare variables that you pass to and from an external C/C++ function.

Extended Capabilities

expand all

The coder.wref function support only MATLAB to High-Level Synthesis (HLS) workflow in HDL Coder™.

Version History

Introduced in R2011a