Distribution to Ux Binary Data

Introduction

Embedded systems like the Signaloid C0-microSD can not output Ux Data in an ASCII-formatted version (e.g., they do not support the printf family of functions). For such cases, the UxHw API allows you to output the Ux Binary, i.e., the binary representation of the distributional information associated with a source-code variable.

The format of Ux Data: Ux Binary

Ux Binary data is little-endian. The layout is the following.

Field	Size	Type
Particle value	8 bytes	double
Format marker	3 bytes	The literal bytes 0xF0 0x00 0x00
Representation type	1 byte	uint8
Number of samples	8 bytes	uint64
Mean value of the distribution	8 bytes	double
Number of non-zero mass Dirac deltas	4 bytes	uint32
Support position and probability mass, one pair per Dirac delta	4 or 8 bytes, then 8 bytes	float or double, then uint64

The support position is the only field whose width depends on the underlying data type. It is 4 bytes when the representation uses single-precision floating-point values and 8 bytes when it uses double-precision floating-point values. Every other field keeps the width above in both cases. See Single-Precision and Double-Precision Representations.

Name

UxHwDoubleDistributionToByteArray, UxHwFloatDistributionToByteArray — Convert a distributional value to an array of bytes.

Synopsis

#include <stddef.h>
#include <uxhw.h>

ssize_t	UxHwDoubleDistributionToByteArray(double value, uint8_t *  destByteBuffer, size_t destByteBufferSizeInBytes);
ssize_t	UxHwFloatDistributionToByteArray(float value, uint8_t *  destByteBuffer, size_t destByteBufferSizeInBytes);

Description

On architectures that associate distributional information with floating-point values, the UxHwDoubleDistributionToByteArray() function stores the Ux Binary data associated with source variable value in the destByteBuffer unsigned byte array. The destByteBufferSizeInBytes source parameter is the size of the destByteBuffer in bytes and the UxHw API uses it to determine if there is enough space in destByteBuffer for safe storage of the Ux Binary data associated with value. For determining the minimum required size of destByteBuffer for being able to store the distribution associated with value you can use the UxHwDoubleGetSizeOfDistributionByteArrayInBytes function. The returned value of the function is the number of bytes written in destByteBuffer.

Parameters

• value — The distributional value whose Ux Binary data will be exported.
• destByteBuffer — The destination array of unsigned bytes that the Ux Binary data of value will be stored in.
• destByteBufferSizeInBytes — The size of destByteBuffer in bytes.

Return values

The UxHwDoubleDistributionToByteArray() function returns the amount of data written in destByteBuffer or -1 in case of failure.

✏️   Examples

#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <uxhw.h>

int
main(void)
{
  /*
   *	Example where we initialize `value` as a Uniform distribution.
   *	The same steps apply for any distribution associated with `value`,
   *	whether parametric or empirical.
   */
  double		value = UxHwDoubleUniformDist(0.1, 1.0);
  /*
   *	Get the minimum number of bytes that you need to store the Ux Binary
   *	data of `value`.
   */
  size_t		destByteBufferSizeInBytes = UxHwDoubleGetSizeOfDistributionByteArrayInBytes(value);
  uint8_t *	destByteBuffer;
  ssize_t		destByteBufferWrittenInBytes;

  destByteBuffer = (uint8_t *) calloc(destByteBufferSizeInBytes, sizeof(uint8_t));
  if (destByteBuffer == NULL)
  {
    printf("Memory allocation for `destByteBuffer` failed. Exiting.\n");

    return 1;
  }

  destByteBufferWrittenInBytes = UxHwDoubleDistributionToByteArray(value, destByteBuffer, destByteBufferSizeInBytes);

  if (destByteBufferWrittenInBytes < 0)
  {
    printf("Writing to destination byte buffer failed.\n");
    free(destByteBuffer);

    return 1;
  }

  printf("Wrote %zd bytes of Ux Binary data of `value` in `destByteBuffer`.\n", destByteBufferWrittenInBytes);

  free(destByteBuffer);

  return 0;
}