<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>

<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII">

<style type="text/css">

body {
  color: #000000;
  background-color: #FFFFFF;
}

del {
  text-decoration: line-through;
  color: #8B0040;
}
ins {
  text-decoration: underline;
  color: #005100;
}

p.example {
  margin: 2em;
}
pre.example {
  margin: 2em;
}
div.example {
  margin: 2em;
}

code.extract {
  background-color: #F5F6A2;
}
pre.extract {
  margin: 2em;
  background-color: #F5F6A2;
  border: 1px solid #E1E28E;
}

p.function {
}

p.attribute {
  text-indent: 3em;
}

blockquote.std {
  color: #000000;
  background-color: #F1F1F1;
  border: 1px solid #D1D1D1;
  padding: 0.5em;
}

blockquote.stddel {
  text-decoration: line-through;
  color: #000000;
  background-color: #FFEBFF;
  border: 1px solid #ECD7EC;
  padding: 0.5em;
}

blockquote.stdins {
  text-decoration: underline;
  color: #000000;
  background-color: #C8FFC8;
  border: 1px solid #B3EBB3;
  padding: 0.5em;
}

table {
  border: 1px solid black;
  border-spacing: 0px;
  border-collapse: collapse;
  margin-left: auto;
  margin-right: auto;
}
th {
  text-align: left;
  vertical-align: top;
  padding: 0.2em;
  border: 1px solid black;
}
td {
  text-align: left;
  vertical-align: top;
  padding: 0.2em;
  border: 1px solid black;
}

</style>


<title>Overflow-Detecting and Double-Wide Arithmetic Operations</title>
</head>
<body>
<h1>Overflow-Detecting and Double-Wide Arithmetic Operations</h1>

<p>
ISO/IEC JTC1 SC22 WG21 P0103R0 - 2015-09-27
</p>

<p>
Lawrence Crowl, Lawrence@Crowl.org
</p>

<p>
<a href="#Introduction">Introduction</a><br>
<a href="#Problem">Problem</a><br>
<a href="#Solution">Solution</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Notation">Notation</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Overflow">Overflow-Detecting Arithmetic</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Double">Double-Wide Arithmetic</a><br>
<a href="#Issues">Open Issues</a><br>
</p>


<h2><a name="Introduction">Introduction</a></h2>

<p>
Some integer arithmetic operations can overflow their representation.
Machine architectures generally provide mechanisms
to either detect or to construct larger representations in software.
</p>

<ul>

<li><p>
Machines commonly provide an overflow status,
which can be tested in a branch instruction.
</p></li>

<li><p>
Machines commonly provide a carry status,
which can be used with an "add with carry" instruction.
The "add with carry" instruction can help implement multi-word addition.
</p></li>

<li><p>
Machines may provide a double-wide multiply instruction,
which provides the upper and lower halves of a multiplication result
in separate words.
The double-wide multiply instruction
can help implement multi-word multiplication.
</p></li>

<li><p>
Machines may provide a double-wide divide instruction,
which provides a dividend twice as wide as the divisor.
These can vary in the length of the quotient
and whether they return a remainder.
The double-wide division instruction
can help implement multi-word division.
</p></li>

<li><p>
Machines may provide a double-wide shift instructions,
which provides a result twice as wide as the shifted value.
The double-wide shift instructions
can help implement scaling for fixed-point arithmetic.
</p></li>

</ul>


<h2><a name="Problem">Problem</a></h2>

<p>
C and C++ programmers have no standard mechanism
to access the machine mechanisms.
So, programmers coding within the standards
resort to argument pre-checking or subword-emulation.
Such code is difficult to get right and inefficient.
</p>

<p>
More perversely,
because C, C++, and Fortran do not provide the mechanisms,
machine architects are sometimes no longer including them,
which makes some problems difficult so solve efficiently.
</p>

<p>
Getting compiler support for generating the appropriate instruction sequences
is generally easier when the mechanisms span more than one language.
This observation means that both C and C++ should support the same mechanism.
</p>


<h2><a name="Solution">Solution</a></h2>

<p>
We propose a set of functions that provide the facilities.
We do <em>not</em> intend that these functions be end-user functions.
Our intent is that these functions be tools
for library authors to implement types more appropriate to end users.
</p>

<p>
With use limited to library authors,
the syntax can be somewhat more demanding,
which in turn means that a syntax suitable for both C and C++
is acceptable.
We rely on type-generic macros in C and overloading in C++.
Note however, that the operations are applicable beyond built-in types in C++.
For larger types, const reference parameters may be more appropriate.
</p>


<h3><a name="Notation">Notation</a></h3>

<p>
We use the following operation codes as components of function names.
</p>

<table>

<tr><th>code</th>
<th>meaning</th></tr>

<tr><td><code>cvt</code></td>
<td>The value converted to the result type.</td></tr>

<tr><td><code>neg</code></td>
<td>The negative of the value.</td></tr>

<tr><td><code>add</code></td>
<td>The sum of the augend and addend.</td></tr>

<tr><td><code>add2</code></td>
<td>The sum of the augend and two addends.
This operation is useful in multiword addition.</td></tr>

<tr><td><code>sub</code></td>
<td>The difference of minuend and subtrahend.</td></tr>

<tr><td><code>sub2</code></td>
<td>The difference of the minuend and two subtrahends.
This operation is useful in multiword subtraction.</td></tr>

<tr><td><code>lsh</code></td>
<td>The multiplicand shifted left by the count,
i.e. the product of the multiplicand and 2<sup>count</sup>.
The behavior is undefined
if the count is less than 0
or if the count greater than or equal to
the number of bits in the value type.</td></tr>

<tr><td><code>lshadd</code></td>
<td>The sum of the multiplicand shifted left by the count and the addend.
i.e. the sum of (the product of the multiplicand and 2<sup>count</sup>)
and the addend.
The first value shifted left by the count
and then sumed with the second value.
The behavior is undefined
if the count is less than 0
or if the count greater than or equal to the number of bits in the value type.
This operation is useful with multiword scaled addition.</td></tr>

<tr><td><code>mul</code></td>
<td>The product of the multiplier and multiplicand.</td></tr>

<tr><td><code>muladd</code></td>
<td>The sum of (the product of the multiplicand and the multiplier)
and the addend.
The behavior is undefined
if both the first two values are two's complement minimums.
This operation is useful with multiword multiplication.</td></tr>

<tr><td><code>muladd2</code></td>
<td>The sum of (the product of the multiplicand and the multiplier)
and the two addends.
The behavior is undefined
if either the first two values are two's complement minimums.
This operation is useful with multiword multiplication.</td></tr>

<tr><td><code>mulsub</code></td>
<td>The difference of (the product of the multiplicand and the multiplier)
and the subtrahend.
The behavior is undefined
if both the first two values are two's complement minimums.</td></tr>

<tr><td><code>mulsub2</code></td>
<td>The difference of (the product of the multiplicand and the multiplier)
and the two subtrahend.
The behavior is undefined
if either the first two values are two's complement minimums.</td></tr>

<tr><td><code>divn</code></td>
<td>The narrow quotient of the dividend and divisor.
The behavior is undefined if the divisor is zero.</td></tr>

<tr><td><code>divw</code></td>
<td>The wide quotient of the dividend and divisor,
The behavior is undefined if the divisor is zero.</td></tr>

<tr><td><code>divnrem</code></td>
<td>As with <code>divn</code>
except also computing a remainder with the sign of the divisor.</td></tr>

<tr><td><code>divwrem</code></td>
<td>As with <code>divw</code>
except also computing a remainder with the sign of the divisor.</td></tr>

</table>


<h3><a name="Overflow">Overflow-Detecting Arithmetic</a></h3>

<p>
The overflow-detecting functions
return a boolean true when the operation overflows,
and a boolean false when the operation does not overflow.
Compilers may assume that a true result is rare.
When the return is false,
the function writes the operation result through the given pointer.
When the return is true,
the pointer is not used and no write occurs.
</p>

<p>
The following functions are available.
Within these prototypes
<code>T</code> and <code>C</code> are any integer type.
However, <code>C</code> is useful only when
it does not have values that <code>T</code> has.
</p>

<blockquote>
<pre>
<code>bool overflow_cvt( C* result, T value );
bool overflow_neg( T* result, T value );
bool overflow_lsh( T* product, T multiplicand, int count );
bool overflow_add( T* summand, T augend, T addend );
bool overflow_sub( T* difference, T minuend, T subtrahend );
bool overflow_mul( T* product, T multiplicand, T multiplier );</code>
</pre>
</blockquote>


<h3><a name="Double">Double-Wide Arithmetic</a></h3>

<p>
There are two classes of functions,
those that provide a result in a single double-wide type
and those that provide a result split into two single-wide types.
</p>

<p>
We expect programmers to use type names from <code>&lt;cstdin&gt;</code> or
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0102r0.html">P0102R0
C++ Parametric Number Type Aliases</a>.
Hence, we do not need to provide a means to infer one type size from the other.
Within this section, we name these types as follows.
</p>
<table>
<tr><td><code>S</code></td>
<td>is a signed integer type.</td></tr>
<tr><td><code>U</code></td>
<td>is an unsigned integer type.</td></tr>
<tr><td><code>DS</code></td>
<td>is a signed integer type
that is double the width of the <code>S</code> type.</td></tr>
<tr><td><code>DU</code></td>
<td>is an unsigned integer type
that is double the width of the <code>U</code> type.</td></tr>
</table>

<p>
We need a mechanism to specify the largest supported type
for various combinations of function category and operation category.
To that end, we propose macros as follows.
</p>

<table>

<tr>
<th>macro name</th>
<th>result category</th>
<th>operation category</th>
</tr>

<tr>
<td><code>LARGEST_DOUBLE_WIDE_ADD</code>
<td>double-wide</td>
<td><code>add</code>, <code>add2</code>,
<code>sub</code>, <code>sub2</code></td>
</tr>

<tr>
<td><code>LARGEST_DOUBLE_WIDE_LSH</code>
<td>double-wide</td>
<td><code>lsh</code>, <code>lshadd</code></td>
</tr>

<tr>
<td><code>LARGEST_DOUBLE_WIDE_MUL</code>
<td>double-wide</td>
<td><code>mul</code>, <code>muladd</code>, <code>muladd2</code>,
<code>mulsub</code>, <code>mulsub2</code></td>
</tr>

<tr>
<td><code>LARGEST_DOUBLE_WIDE_DIV</code>
<td>double-wide</td>
<td><code>divn</code>, <code>divw</code>,
<code>divnrem</code>, <code>divwrem</code></td>
</tr>

<tr>
<td><code>LARGEST_DOUBLE_WIDE_ALL</code>
<td>double-wide</td>
<td>the minimum size of the four macros above</td>
</tr>

<tr>
<td><code>LARGEST_SINGLE_WIDE_ADD</code>
<td>single-wide</td>
<td><code>add</code>, <code>add2</code>,
<code>sub</code>, <code>sub2</code></td>
</tr>

<tr>
<td><code>LARGEST_SINGLE_WIDE_LSH</code>
<td>single-wide</td>
<td><code>lsh</code>, <code>lshadd</code></td>
</tr>

<tr>
<td><code>LARGEST_SINGLE_WIDE_MUL</code>
<td>single-wide</td>
<td><code>mul</code>, <code>muladd</code>, <code>muladd2</code>,
<code>mulsub</code>, <code>mulsub2</code></td>
</tr>

<tr>
<td><code>LARGEST_SINGLE_WIDE_DIV</code>
<td>single-wide</td>
<td><code>divn</code>, <code>divw</code>,
<code>divnrem</code>, <code>divwrem</code></td>
</tr>

<tr>
<td><code>LARGEST_SINGLE_WIDE_ALL</code>
<td>double-wide</td>
<td>the minimum size of the four macros above</td>
</tr>

</table>

<p>
We need a mechanism to build and split double-wide types.
The lower part of the split is always an unsigned type.
</p>
<pre>
<code>S split_upper( DS value );
U split_lower( DS value );
DS wide_build( S upper, U lower );</code>

<code>U split_upper( DU value );
U split_lower( DU value );
DU wide_build( U upper, U lower );</code>
</pre>

<p>
The arithmetic functions with an double-wide result are as follows.
This category seems less important than the next category.
</p>
<pre>
<code>DS wide_lsh( S multiplicand, int count );
DS wide_add( S augend, S addend );
DS wide_sub( S minuend, S subtrahend );
DS wide_mul( S multiplicand, S multiplier );
DS wide_add2( S augend, S addend1, S addend2 );
DS wide_sub2( S minuend, S subtrahend1, S subtrahend2 );
DS wide_lshadd( S multiplicand, int count, S addend );
DS wide_lshsub( S multiplicand, int count, S subtrahend );
DS wide_muladd( S multiplicand, S multiplier, S addend );
DS wide_mulsub( S multiplicand, S multiplier, S subtrahend );
DS wide_muladd2( S multiplicand, S multiplier, S addend1, S addend2 );
DS wide_mulsub2( S multiplicand, S multiplier, S subtrahend1, S subtrahend2 );
S wide_divn( DS dividend, S divisor );
DS wide_divw( DS dividend, S divisor );
S wide_divnrem( S* remainder, DS dividend, S divisor );
DS wide_divnrem( S* remainder, DS dividend, S divisor );</code>

<code>DU wide_lsh( U multiplicand, int count );
DU wide_add( U augend, U addend );
DU wide_sub( U minuend, U subtrahend );
DU wide_mul( U multiplicand, U multiplier );
DU wide_add2( U augend, U addend1, U addend2 );
DU wide_sub2( U minuend, U subtrahend1, U subtrahend2 );
DU wide_lshadd( U multiplicand, int count, U addend );
DU wide_lshsub( U multiplicand, int count, U subtrahend );
DU wide_muladd( U multiplicand, U multiplier, U addend );
DU wide_mulsub( U multiplicand, U multiplier, U subtrahend );
DU wide_muladd2( U multiplicand, U multiplier, U addend1, U addend2 );
DU wide_mulsub2( U multiplicand, U multiplier, U subtrahend1, U subtrahend2 );
U wide_divn( DU dividend, U divisor );
DU wide_divw( DU dividend, U divisor );
U wide_divnrem( U* remainder, DU dividend, U divisor );
DU wide_divnrem( U* remainder, DU dividend, U divisor );</code>
</pre>

<p>
The arithmetic functions with a split result are as follows.
The lower part of the result is always an unsigned type.
The lower part is returned through a pointer
while the upper part is returned as the function result.
The intent is that in loops,
the lower part is written once to memory
while the upper part is carried between iterations in a local variable.
</p>
<pre>
<code>S split_lsh( U* product, S multiplicand, int count );
S split_add( U* summand, S augend, S addend );
S split_sub( U* difference, S minuend, S subtrahend );
S split_mul( U* product, S multiplicand, S multiplier );
S split_add2( U* summand, S value1, S addend1, S addend2 );
S split_sub2( U* difference, S minuend, S subtrahend1, S subtrahend2 );
S split_lshadd( U* product, S multiplicand, int count, S addend );
S split_lshsub( U* product, S multiplicand, int count, S subtrahend );
S split_muladd( U* product, S multiplicand, S addend1, S addend );
S split_mulsub( U* product, S multiplicand, S subtrahend1, S subtrahend2 );
S split_muladd2( U* product, S multiplicand, S multiplier, S addend1, S addend2 );
S split_mulsub2( U* product, S multiplicand, S multiplier, S subtrahend1, S subtrahend2 );
S split_divn( S dividend_upper, U dividend_lower, S divisor );
DS split_divw( S dividend_upper, U dividend_lower, S divisor );
S split_divnrem( S* remainder, S dividend_upper, U dividend_lower, S divisor );
DS split_divwrem( S* remainder, S dividend_upper, U dividend_lower, S divisor );</code>

<code>U split_lsh( U* product, U multiplicand, int count );
U split_add( U* summand, U value1, U addend );
U split_sub( U* difference, U minuend, U subtrahend );
U split_mul( U* product, U multiplicand, U multiplier );
U split_add2( U* summand, U value1, U addend1, U addend2 );
U split_sub2( U* difference, U minuend, U subtrahend1, U subtrahend2 );
U split_lshadd( U* product, U multiplicand, int count, U addend );
U split_lshsub( U* product, U multiplicand, int count, U subtrahend );
U split_muladd( U* product, U multiplicand, U multiplier, U addend );
U split_mulsub( U* product, U multiplicand, U multiplier, U subtrahend );
U split_muladd2( U* product, U multiplicand, U multiplier, U addend1, U addend2 );
U split_mulsub2( U* product, U multiplicand, U multiplier, U subtrahend1, U subtrahend2 );
U split_divn( U dividend_upper, U dividend_lower, U divisor );
DU split_divw( U dividend_upper, U dividend_lower, U divisor );
U split_divnrem( U* remainder, U dividend_upper, U dividend_lower, U divisor );
DU split_divwrem( U* remainder, U dividend_upper, U dividend_lower, U divisor );</code>
</pre>


<h2><a name="Issues">Open Issues</a></h2>

<p>
There is more than one possible definition of the sign of the remainder.
Can we get by with the one defined above?
</p>

<p>
Do we want to support all built-in types with these operations,
or only the <code>LARGEST</code>...<code>ALL</code>
plus each of the other <code>LARGEST</code> for each operation?
</p>

</body>
</html>
