Fixed-Point Operator Code Replacement

If you have a Fixed-Point Designer™ license, you can define fixed-point operator code replacement entries to match:

A binary-point-only scaling combination on the operator inputs and output.
A slope bias scaling combination on the operator inputs and output.
Relative scaling or net slope between multiplication or division operator inputs and output. Use one of these methods to map a range of slope and bias values to a replacement function for multiplication or division.
Equal slope and zero net bias across addition or subtraction operator inputs and output. Use this method to disregard specific slope and bias values and map relative slope and bias values to a replacement function for addition or subtraction.

Common Ways to Match Fixed-Point Operator Entries

The following table maps common ways to match fixed-point operator code replacement entries with the associated fixed-point parameters that you specify in a code replacement table definition file.

Match	Create entry	Minimally specify parameters
A specific binary-point-only scaling combination on the operator inputs and output.	`RTW.TflCOperationEntry`	`createAndAddConceptualArg` function: `CheckSlope`: Specify the value `true`. `CheckBias`: Specify the value `true`. `DataTypeMode` (or `DataType`/`Scaling` equivalent): Specify fixed-point binary-point-only scaling. `FractionLength`: Specify a fraction length (for example, 3).
A specific slope bias scaling combination on the operator inputs and output.	`RTW.TflCOperationEntry`	`createAndAddConceptualArg` function: `CheckSlope`: Specify the value `true`. `CheckBias`: Specify the value `true`. `DataTypeMode` (or `DataType/Scaling` equivalent): Specify fixed-point [slope bias] scaling. `Slope` (or `SlopeAdjustmentFactor`/ `FixedExponent` equivalent): Specify a slope value (for example, `15`). `Bias`: Specify a bias value (for example, `2`).
Net slope between operator inputs and output (multiplication and division).	`RTW.TflCOperationEntryGenerator_NetSlope`	`setTflCOperationEntryParameters` function: `NetSlopeAdjustmentFactor`: Specify the slope adjustment factor (`F`) part of the net slope, `F2^E` (for example, `1.0`). `NetFixedExponent`: Specify the fixed exponent (`E`) part of the net slope, `F2^E` (for example, `-3.0`). `createAndAddConceptualArg` function: `CheckSlope`: Specify the value `false`. `CheckBias`: Specify the value `false`. `DataType`: Specify the value `'Fixed'`.
Relative scaling between operator inputs and output (multiplication and division).	`RTW.TflCOperationEntryGenerator`	`setTflCOperationEntryParameters` function: `RelativeScalingFactorF`: Specify the slope adjustment factor (`F`) part of the relative scaling factor, `F2^E` (for example, `1.0`). `RelativeScalingFactorE`: Specify the fixed exponent (`E`) part of the relative scaling factor, `F2^E` (for example, `-3.0`). `createAndAddConceptualArg` function: `CheckSlope`: Specify the value `false`. `CheckBias`: Specify the value `false`. `DataType`: Specify the value `'Fixed'`.
Equal slope and zero net bias across operator inputs and output (addition and subtraction).	`RTW.TflCOperationEntryGenerator`	`setTflCOperationEntryParameters` function: `SlopesMustBeTheSame`: Specify the value `true`. `MustHaveZeroNetBias`: Specify the value `true`. `createAndAddConceptualArg` function: `CheckSlope`: Specify the value `false`. `CheckBias`: Specify the value `false`.

Fixed-Point Numbers and Arithmetic

Fixed-point numbers use integers and integer arithmetic to represent real numbers and arithmetic with the following encoding scheme:

$V = \tilde{V} = S Q + B$

$V$ is an arbitrarily precise real-world value.
$\tilde{V}$ is the approximate real-world value that results from fixed-point representation.
$Q$ is an integer that encodes $\tilde{V}$ , referred to as the quantized integer.
$S$ is a coefficient of $Q$ , referred to as the slope.
$B$ is an additive correction, referred to as the bias.

The general equation for an operation between fixed-point operands is:

$(S_{O} Q_{O} + B_{O}) = (S_{1} Q_{1} + B_{1}) < o p > (S_{2} Q_{2} + B_{2})$

The objective of fixed-point operator replacement is to replace an operator that accepts and returns fixed-point or integer inputs and output with a function that accepts and returns built-in C numeric data types. The following sections provide additional programming information for each supported operator.

Addition

The operation V₀ = V₁ + V₂ implies that

$Q_{0} = (\frac{S_{1}}{S_{0}}) Q_{1} + (\frac{S_{2}}{S_{0}}) Q_{2} + (\frac{B_{1} + B_{2} - B_{0}}{S_{0}})$

If an addition replacement function is defined such that the scaling on the operands and sum are equal and the net bias

$(\frac{B_{1} + B_{2} - B_{0}}{S_{0}})$

is zero (for example, a function s8_add_s8_s8 that adds two signed 8-bit values and produces a signed 8-bit result), then the operator entry must set the operator entry parameters SlopesMustBeTheSame and MustHaveZeroNetBias to true. To match for replacement, the slopes must be the same for all addition conceptual arguments. (For parameter descriptions, see the reference page for the function setTflCOperationEntryParameters.)

Subtraction

The operation V₀ = V₁ − V₂ implies that

$Q_{0} = (\frac{S_{1}}{S_{0}}) Q_{1} - (\frac{S_{2}}{S_{0}}) Q_{2} + (\frac{B_{1} - B_{2} - B_{0}}{S_{0}})$

If a subtraction replacement function is defined such that the scaling on the operands and difference are equal and the net bias

$(\frac{B_{1} - B_{2} - B_{0}}{S_{0}})$

is zero (for example, a function s8_sub_s8_s8 that subtracts two signed 8-bit values and produces a signed 8-bit result), then the operator entry must set the operator entry parameters SlopesMustBeTheSame and MustHaveZeroNetBias to true. To match for replacement, the slopes must be the same for all subtraction conceptual arguments. (For parameter descriptions, see the reference page for the function setTflCOperationEntryParameters.)

Multiplication

There are different ways to specify multiplication replacements. The most direct way is to specify an exact match of the input and output types. This is feasible if a model contains only a few known slope and bias combinations. Use the TflCOperationEntry class and specify the exact values of slope and bias on each argument. For scenarios where there are numerous slope/bias combinations, it is not feasible to specify each value with a different entry. Use a net slope entry or create a custom entry.

The operation V₀ = V₁ * V₂ implies, for binary-point-only scaling, that

$\begin{array}{l} S_{0} Q_{0} = (S_{1} Q_{1}) (S_{2} Q_{2}) \\ Q_{0} = (\frac{S_{1} S_{2}}{S_{0}}) Q_{1} Q_{2} \\ Q_{0} = S_{n} Q_{1} Q_{2} \end{array}$

where S_n is the net slope.

It is common to replace all multiplication operations that have a net slope of 1.0 with a function that performs C-style multiplication. For example, to replace all signed 8-bit multiplications that have a net scaling of 1.0 with the s8_mul_s8_u8_ replacement function, the operator entry must define a net slope factor, F2^E. You specify the values for F and E using operator entry parameters NetSlopeAdjustmentFactor and NetFixedExponent. For the s8_mul_s8_u8 function, set NetSlopeAdjustmentFactor to 1 and NetFixedExponent to 0.0. Also, set the operator entry parameter SlopesMustBeTheSame to false and the parameter MustHaveZeroNetBias to true. To match for replacement, the biases must be zero for all multiplication conceptual arguments. (For parameter descriptions, see the reference page for the function setTflCOperationEntryParameters.)

Note

When an operator entry specifies NetSlopeAdjustmentFactor and NetFixedExponent, matching entries must have arguments with zero bias.

Division

There are different ways to specify division replacements. The most direct way is to specify an exact match of the input and output types. This is feasible if a model contains only a few known slope and bias combinations. Use the TflCOperationEntry class and specify the exact values of slope and bias on each argument. For scenarios where there are numerous slope/bias combinations, it is not feasible to specify each value with a different entry. Use a net slope entry or create a custom entry (see Customize Match and Replacement Process).

The operation V₀ = (V₁ / V₂) implies, for binary-point-only scaling, that

$\begin{array}{l} S_{0} Q_{0} = (\frac{S_{1} Q_{1}}{S_{2} Q_{2}}) \\ Q_{0} = S_{n} (\frac{Q_{1}}{Q_{2}}) \end{array}$

where S_n is the net slope.

It is common to replace all division operations that have a net slope of 1.0 with a function that performs C-style division. For example, to replace all signed 8-bit divisions that have a net scaling of 1.0 with the s16_netslope0p5_div_s16_s16 replacement function, the operator entry must define a net slope factor, F2^E. You specify the values for F and E using operator entry parameters NetSlopeAdjustmentFactor and NetFixedExponent. For the s16_netslope0p5_div_s16_s16 function, you would set NetSlopeAdjustmentFactor to 1 and NetFixedExponent to 0.0. Also, set the operator entry parameter SlopesMustBeTheSame to false and the parameter MustHaveZeroNetBias to true. To match for replacement, the biases must be zero for all division conceptual arguments. (For parameter descriptions, see the reference page for the function setTflCOperationEntryParameters.)

Note

When an operator entry specifies NetSlopeAdjustmentFactor and NetFixedExponent, matching entries must have arguments with zero bias.

Data Type Conversion (Cast)

The data type conversion operation V₀ = V₁ implies, for binary-point-only scaling, that

$\begin{array}{l} Q_{0} = (\frac{S_{1}}{S_{0}}) Q_{1} \\ Q_{0} = S_{n} Q_{1} \end{array}$

where S_n is the net slope. Set the operator entry parameter SlopesMustBeTheSame to false and the parameter MustHaveZeroNetBias to true. To match for replacement, the biases must be zero for all cast conceptual arguments. (For parameter descriptions, see the reference page for the function setTflCOperationEntryParameters.)

Shift

The shift left or shift right operation V₀ = (V₁ / 2ⁿ) implies, for binary-point-only scaling, that

$\begin{array}{l} S_{0} Q_{0} = (\frac{S_{1} Q_{1}}{2^{n}}) \\ Q_{0} = (\frac{S_{1}}{S_{0}}) (\frac{Q_{1}}{2^{n}}) \\ Q_{0} = S_{n} (\frac{Q_{1}}{2^{n}}) \end{array}$

where S_n is the net slope. Set the operator entry parameter SlopesMustBeTheSame to false and the parameter MustHaveZeroNetBias to true. To match for replacement, the biases must be zero for all shift conceptual arguments. (For parameter descriptions, see the reference page for the function setTflCOperationEntryParameters.)