Rounding and Saturation Modes - 2022.2 English

AI Engine Kernel and Graph Programming Guide (UG1079)

Document ID
UG1079
Release Date
2022-10-19
Version
2022.2 English

The aie::set_rounding() and aie::set_saturation() APIs are used to set the rounding and saturation modes of the to_vector operation.

The aie::rounding_mode includes:
  • floor - No rounding - Truncate LSB, always round down (towards negative infinity).
  • ceil - No rounding - Always round up (towards positive infinity).
  • positive_inf - Rounds halfway towards positive infinity.
  • negative_inf - Rounds halfway towards negative infinity.
  • symmetric_inf - Rounds halfway towards infinity (away from zero).
  • symmetric_zero - Rounds halfway towards zero (away from infinity).
  • conv_even - Rounds halfway towards nearest even number.
  • conv_odd - Rounds halfway towards nearest odd number.
The aie::saturation_mode includes:
  • none - No saturation is performed and the value is truncated on the MSB side.
  • saturate - Controls saturation. Saturation rounds an n-bit signed value in the range [- ( 2^(n-1) ) : +2^(n-1) - 1 ]. For example if n=8, the range would be [-128:127].
  • symmetric - Controls symmetric saturation. Symmetric saturation rounds an n-bit signed value in the range [- ( 2^(n-1) -1 ) : +2^(n-1) - 1 ]. For example if n=8, the range would be [-127:127].

The rounding and saturation settings are applied on the AI Engine tile. The aie::get_rounding and aie::get_saturation methods can be used to get the current AI Engine tile rounding and saturation modes.

Following are some example codes setting and getting rounding and saturation modes:
aie::set_rounding(aie::rounding_mode::ceil);
aie::set_saturation(aie::saturation_mode::saturate);
aie::rounding_mode current_rnd=aie::get_rounding();
aie::saturation_mode current_sat=aie::get_saturation();
...
aie::set_rounding(aie::rounding_mode::floor);
aie::set_saturation(aie::saturation_mode::none);
Note: Rounding and saturation settings are sticky. This means that the AI Engine tile maintains the mode until it is changed. If a kernel has a runtime ratio of less than one such that it can share a tile with other kernels, and if the rounding and saturation modes matter to the kernel operation, then the kernel must set these modes in the kernel code rather than in a constructor or initialization function. This will ensure that the rounding and saturation modes are guaranteed in the case that another kernel on the same tile uses different rounding or saturation mode values.