F003 Hello flux

Hello flux

Example 1 creates the simple uncompressed trace and writes it into a file.

Preparing the memory

The first step in setting up a flux trace is calculating the required memory. The core of flux does not use any c-library methods. The required memories for buffers and tables need to be passed as arguments to the flxCreateXXXXBuffer and flxCreateTrace methods. In this example (and most others) we use the macros FLX_BUFFER_BYTES and FLX_TRACE_BYTES to calculate the memory size for buffer and trace and define static memory chunks.

Createing buffers and trace objects

In this example,  we use a simple flat buffer, created by the method flxCreateFixedBuffer. The third and fourth arguments are the 'write to file' handler and the file object. For the trace creation we need the following arguments:

  • the traceId,
  • the max itemId,
  • the maxEntrySize value,
  • the trace object memory and size (this is for trace handling, not for the trace data itself)
  • and the initial buffer (may be changed later) to store the trace data. 
#define MAX_ITEM_ID 2 // maximum id of scope/signal
#define MAX_ENTRY_SIZE 4096

	// output file
	FILE *out = fopen("flux.example.recTr", "wb");

	// calculate required memory for trace and buffers
	unsigned bufferSize = FLX_BUFFER_BYTES(MAX_ENTRY_SIZE);
	unsigned traceSize = FLX_TRACE_BYTES(0, MAX_ITEM_ID);

	// static memory
	unsigned char memoryBuffer[bufferSize];
	unsigned char memoryTrace[traceSize];

	// buffer
	flxBuffer buffer = flxCreateFixedBuffer(memoryBuffer, bufferSize,
			flxWriteToFile, out);

	// trace
	flxTrace trace = flxCreateTrace(0, MAX_ITEM_ID, MAX_ENTRY_SIZE, memoryTrace,
			traceSize, buffer);

Adding items

The trace object is prepared and we can start to add content. With flxAddHead we start the trace with a label and description of the following trace. The method flxAddSignal adds a signal to the trace. The arguments are:

  • the trace object,
  • itemId for the signal,
  • parentId, here 0 for the root scope,
  • a name and description (2 arguments),
  • the type of the signal
  • and a signal descriptor (not used in this example)

Open and close

With flxOpen we start a trace sequence and finalize it with flxClose. Both methods are used to define the domain range and the process. The parameters of flxOpen are:
  • the trace object,
  • itemId to be opened (0 == root; we open all items)
  • domainBase ("ns": the smallest delta between two samples is 1 ns )
  • start position (0ns)
  • sample rate (0: discrete process)
And flxClose has:
  • the trace object,
  • itemId to be opened (0 == root; we close all items)
  • end position (50000 * 10 ns)
To open an item id != 0, you need to offer a larger memory space to the trace object (more complex handling). You do this by setting the first argument of FLX_TRACE_BYTES to 1.
	// head
	flxAddHead(trace, "example", "flux example");

	// add signals
	// parent 0 is root
	flxAddSignal(trace, 1, 0, "integer", "an integer", FLX_TYPE_INTEGER, 0);
	flxAddSignal(trace, 2, 0, "float", "a float", FLX_TYPE_FLOAT, 0);

	// open
	flxOpen(trace, 0, "ns", 0, 0);
	// generate example trace
	for (n = 0; n < 500000; n++) {

		// time in ns
		flxdomain current = n * 10;

		// integer
		iVal = n % 444;
		flxWriteIntAt(trace, 1, 0, current, 0, &iVal, sizeof(int), 0);

		// float - same time - use domain=0; isDelta=1
		fVal = sin(n / 1000.0);
		flxWriteFloatAt(trace, 2, 0, 0, 1, &fVal, sizeof(float));

	// close
	flxClose(trace, 0, n * 10);

The flxWriteXXXAt methods are intended to add events and value changes to a signal. The domain position (e.g. when a change occurs) can be given absolute or relative. If you choose an absolute domain position, the value must to be equal or larger than the one used in a previous write (and larger than the open position). A relative domain position (means relative to a previous write) must be larger or equal to 0. The parameters:

  • the trace object,
  • itemId of the signal,
  • the conflict flag (samples with enabled conflict flags are painted red in impulse),
  • domain position,
  • isRelative flag (1: relative, 0:absolute),
  • pointer to the value,
  • and finally the size of the value in bytes.


technical software and tooling


Contact Us

This email address is being protected from spambots. You need JavaScript enabled to view it.