1.3.1. Nanos++ Instrumentation API¶

The following sections list and summarize the Nanos++ Instrumentation API relevant for the FPGA tasks.

1.3.1.1. nanos_instrument_register_key_with_key¶

Register an event key.

Arguments:

event_key: Integer event identifier. It should be the same passed to calls inside the FPGA task. The event key can be any positive integer value greater then or equal to 1000. Events in the 0-999 range are reserved.
key: An string identifying the event or value, it is used by the nanos instrumentation API to reference an event or a value.
description: The description string that will be visualized in a trace.
abort_when_registered: Indicates if the runtime should abort when registering an event or value with a key that has been already registered,

Return value:

NANOS_OK on success, NANOS_ERROR on error.

nanos_err_t nanos_instrument_register_key_with_key(
    nanos_event_key_t event_key,
    const char* key,
    const char* description,
    bool abort_when registered
);

1.3.1.2. nanos_instrument_register_value_with_val¶

Register a value Registering a value is optional. Usually it’s only useful if the event has an enumerated value, such a set of states.

Arguments:

val: Integer value. It should be the same passed to calls inside the FPGA task.
key: String identifier for the event used in nanos_instrument_register_key_with_key call.
value: An string identifying the event value to be registered.
description: The description string that will be visualized in a trace.
abort_when_registered: Indicates if the runtime should abort when registering an event or value with a key that has been already registered,

Return value:

NANOS_OK on success, NANOS_ERROR on error.

nanos_err_t nanos_instrument_register_value_with_val(
    nanos_event_value_t val,
    const char* key,
    const char *value,
    const char* description,
    bool abort_when registered
);

1.3.1.3. nanos_instrument_burst_begin¶

This Nanos++ API can be called inside an FPGA task.

nanos_err_t nanos_instrument_burst_begin(
    nanos_event_key_t event,
    nanos_event_value_t value
);

1.3.1.4. nanos_instrument_burst_end¶

This Nanos++ API can be called inside an FPGA task.

nanos_err_t nanos_instrument_burst_end(
    nanos_event_key_t event,
    nanos_event_value_t value
);

1.3.1.5. nanos_instrument_point_event¶

This Nanos++ API can be called inside an FPGA task.

nanos_err_t nanos_instrument_point_event(
    nanos_event_key_t event,
    nanos_event_value_t value
);

1.3.1.6. Full example¶

const unsigned int BSIZE = 256;
const nanos_event_key_t DOT_COMPUTATION = 1000;
const nanos_event_key_t DOT_ITERATION = 1001;

#pragma omp target device(fpga)
#pragma omp task in([BSIZE]v1, [BSIZE]v2) inout([1]result)
void dotProduct(float *v1, float *v2, float *result) {
  nanos_instrument_burst_begin(DOT_COMPUTATION, 1);
  int resultLocal = result[0];
  for (unsigned int i = 0; i < BSIZE; ++i) {
    nanos_instrument_point_event(DOT_ITERATION, i);
    resultLocal += v1[i]*v2[i];
  }
  result[0] = resultLocal;
  nanos_instrument_burst_end(DOT_COMPUTATION, 1);
}

int main() {
  ...
  //register fpga events
  nanos_instrument_register_key_with_key(DOT_COMPUTATION, "dotProduct_computation", "dot product computation", true);
  nanos_instrument_register_key_with_key(DOT_ITERATION, "dotProduct_iteration", "dot product main loop iteration", true);

  for (unsigned int i = 0; i < vecSize; i += BSIZE) {
    dotProduct(v1+i, v2+i, &result);
  }
  #pragma omp taskwait
  ...
}

1.3.2. Nanos++ FPGA Architecture API¶

The following sections list and summarize the Nanos++ FPGA Architecture API. The documentation is for the version 10.

1.3.2.1. Memory Management¶

1.3.2.1.1. nanos_fpga_malloc¶

Allocates memory in the FPGA address space and returns a pointer valid for the FPGA tasks. The returned pointer cannot be dereferenced in the host code.

Arguments:

len: Length in bytes to allocate.

Return value:

Pointer to the allocated region in the FPGA address space.

void * nanos_fpga_malloc(
    size_t len
);

1.3.2.1.2. nanos_fpga_free¶

void nanos_fpga_free(
    void * fpgaPtr
);

1.3.2.1.3. nanos_fpga_memcpy¶

typedef enum {
    NANOS_COPY_HOST_TO_FPGA,
    NANOS_COPY_FPGA_TO_HOST
} nanos_fpga_memcpy_kind_t;

void nanos_fpga_memcpy(
    void * fpgaPtr,
    void * hostPtr,
    size_t len,
    nanos_fpga_memcpy_kind_t kind
);

1.3.2.2. Periodic tasks¶

1.3.2.2.1. nanos_get_periodic_task_repetition_num¶

This Nanos++ API can be called inside an FPGA task.

Returns the current repetition number inside a periodic task. First execution in the repetition 1. It will return a 0 if called outside a periodic task.

unsigned int nanos_get_periodic_task_repetition_num();

1.3.2.2.2. nanos_cancel_periodic_task¶

This Nanos++ API can be called inside an FPGA task.

Aborts the remaining repetitions of a periodic task and finishes it at the end of task code.

void nanos_cancel_periodic_task();