Menu ▾ ▴

Usage

Claudio Scordino Ida Savino

Usage of SC-REX

This Section explains how to use SC_REX, assuming it has been already configured as explained in Section [Configuration].

Starting the supervisor

The Supervisor can be run in two modes:

Normal mode

In this mode, the Supervisor communicates with the kernel driver to interact with the devices specified by the /etc/screx/architecture.xml file.

The Supervisor can be run with two different goals: one goal tries to reduce the energy consumption, and the other goal tries to maximize the performance.

To run the supervisor with the goal of optimizing power consumption, type

screx --energy

on a console.

Instead, to run the supervisor with the goal of optimizing performance, type

screx --performance

on a console.

Simulation mode

In this mode, the Supervisor simulates the kernel driver and uses the dummy files specified by the /etc/screx/architecture-simulation.xml file.

The Supervisor can be run with two different goals: one goal tries to reduce the energy consumption, and the other goal tries to maximize the performance.

To run the supervisor with the goal of optimizing power consumption, type

screx --simulate --energy

on a console.

Instead, to run the supervisor with the goal of optimizing performance, type

screx --simulate --performance

on a console.

API (usage from application)

To be able of using the supervisor, each application must:

  1. Include the following files:

    #include "reconfiguration-api.h
#include "rpc-api.h

  2. Be linked against the screxruntime library:

    gcc ... -lscrexruntime

The API provided by the Run-Time Library is similar to the one available for the Cell processor.
The API allows to:

RUN A TASK

This function runs a task on a reconfigurable processor by providing the type of the reconfigurable processor and the configuration table for the device.

Function:

vproc_t run_task (const char* processor_type,
        const char* program_file,
        const char* data_file,
        const struct task_arg* in, 
        const struct task_arg* out,
        enum queue_t queue,
        const char* reconftable_file,
        unsigned int priority);

where

struct task_arg {
    /// Pointer to data (either on host or on reconf. processor)
    void* ptr;
    /// Size of data
    size_t size;
};

Arguments:

  • processor_type: type of reconfigurable processor requested. It must be a \'\0\'-terminated string. For example "mycpu\0".
  • program_file: Absolute path on the filesystem of the file containing the program binary
  • data_file: Absolute path of the file on the filesystem containing data program file
  • in: Pointer to data structure containing pointer and size of the input arguments
  • out: Pointer to data structure containing pointer and size of the output arguments (i.e., result of the computation)
  • queue If we should queue the request in case a processor is not available. Possible values are QUEUE and NOQUEUE.
  • reconftable_file Absolute path on the filessytem of the XML file containing the reconfiguration table
  • priority Priority of the request.

Return values:

  • The ID of the virtual processor (AKA "vproc") that will handle the request in case of success;
  • -1 in case of error
  • -2 in case of processor not available and NOQUEUE has been specified

Example:

int ret;
struct task_arg in, out;
in.size = 0;
out.ptr = (void*) &ret;
out.size = sizeof(ret);
vproc_t vproc = run_task("mycpu\0", "/absolute/path/program_binary",
                "/absolute/path/program_data", &in, &out, NOQUEUE,
                "/etc/screx/default_configuration.xml\0", 1);
RETRIEVE RESULT OF COMPUTATION

This function gets the result of a computation performed on a reconfigurable processor.

Function:

int get_result(vproc_t vproc,
               enum block_t block,
               const struct task_arg* out);

Arguments:

  • vproc: processor that performed the computation. It is the return value run_task()
  • block: if blocking in case of result not yet available; this argument can be BLOCK or NOBLOCK.
  • out: pointer to data structure containing pointer and size where result must be stored

Return values:

  • 0 in case of success
  • -1 in case of error

Example:

get_result(vproc, BLOCK, &out);
SINGLE FUNCTION TO RUN A TASK AND GET THE RESULT

This command allows to run a task and retrieve the result with a single (blocking) function call.

Function:

int exec_task (const char* processor_type,
            const char* program_file,
            const char* data_file,
            const struct task_arg* in,
            const struct task_arg* out,
            const char* reconftable_file,
            unsigned int priority);

Arguments:

  • processor_type: type of reconfigurable processor requested. It must be a \'\0\'-terminated string. For example "mycpu\0".
  • program_file: Absolute path of the file on the filesystem containing the program binary
  • data_file: Absolute path on the filesystem of the file containing program data
  • in: Pointer to data structure containing pointer and size of the input arguments
  • out: Pointer to data structure containing pointer and size of the output arguments (i.e., result of the computation)
  • reconftable_file Absolute path on the filesystem of the XML file containing the reconfiguration table
  • priority Priority of the request.

Return values:

  • 0 in case of success
  • -1 in case of error

Example:

int ret;
struct task_arg in, out;
in.size = 0;
out.ptr = (void*) &ret;
out.size = sizeof(ret);
int success = exec_task("mycpu\0", "/absolute/path/program_binary",
                "/absolute/path/program_data", &in, &out,
                "/etc/screx/default_configuration.xml\0", 1);
START PHASE

This function communicates information about a new phase valid for all reconfigurable processors used by the application.

Function:

START_PHASE (phase_qos_t qos, phase_type_t type)

Arguments:

  • qos: value of QoS. One of the following values:
    • PHASE_QOS_SMALL
    • PHASE_QOS_MEDIUM
    • PHASE_QOS_HIGH
  • type: Type of the phase. It can be either PHASE_NOTYPE or one or more flags (i.e., OR-ed) among the following ones:
    • PHASE_PARALLEL
    • PHASE_STRIDED
    • PHASE_MANY_REFS
    • PHASE_LOOP

Return values:

  • -1 in case of error
  • 0 in case of success

Example:

START_PHASE(PHASE_QOS_HIGH, PHASE_MANY_REFS|PHASE_PARALLEL)
START PHASE WITH DEADLINE

This function starts a new phase specifying the expected duration of the execution, valid for all reconfigurable processors used by the application

Function:

START_PHASE_DURATION (phase_qos_t qos, phase_type_t type, phase_deadline_t deadline_usec)

Arguments:

  • qos: value of QoS. One of the following values:
    • PHASE_QOS_SMALL
    • PHASE_QOS_MEDIUM
    • PHASE_QOS_HIGH
  • type: Type of the phase. It can be either PHASE_NOTYPE or one or more flags (i.e., OR-ed) among the following ones:
    • PHASE_PARALLEL
    • PHASE_STRIDED
    • PHASE_MANY_REFS
    • PHASE_LOOP
  • deadline_usec: deadline, expressed in microseconds. Can be 0 in case we don't want to express a deadline.

Return values:

  • -1 in case of error
  • 0 in case of success

Example:

START_PHASE_DURATION(PHASE_QOS_MEDIUM, PHASE_LOOP, 1000000)
END PHASE

This function explicitly ends a phase for all reconfigurable processors used by the application

Function: 

END_PHASE()

Return values:

  • -1 in case of error (e.g., wrong descriptor)
  • 0 in case of success

Note: this can be avoided if a new phase is started

START PHASE FOR A SPECIFIC DEVICE

This function starts a new phase for a specific reconfigurable processor

Function: 

int start_phase (vproc_t vproc, phase_qos_t qos, phase_type_t type)

Arguments:

  • vproc: return value of run_task()
  • qos: value of QoS. One of the following values:
    • PHASE_QOS_SMALL
    • PHASE_QOS_MEDIUM
    • PHASE_QOS_HIGH
  • type: Type of the phase. It can be either PHASE_NOTYPE or one or more flags (i.e., OR-ed) among the following ones:
    • PHASE_PARALLEL
    • PHASE_STRIDED
    • PHASE_MANY_REFS
    • PHASE_LOOP

Return values:

  • -1 in case of error
  • 0 in case of success
START PHASE WITH A DEADLINE FOR A SPECIFIC DEVICE

This function starts a new phase specifying the expected duration of the execution, for a specific reconfigurable processor.

Function: 

int start_phase_with_deadline (vproc_t vproc, phase_qos_t qos, phase_type_t type, phase_deadline_t deadline_usec)

Arguments:

  • vproc : return value of run_task()
  • qos: value of QoS. One of the following values:
    • PHASE_QOS_SMALL
    • PHASE_QOS_MEDIUM
    • PHASE_QOS_HIGH
  • type: Type of the phase. It can be either PHASE_NOTYPE or one or more flags (i.e., OR-ed) among the following ones:
    • PHASE_PARALLEL
    • PHASE_STRIDED
    • PHASE_MANY_REFS
    • PHASE_LOOP
  • deadline_usec: deadline, expressed in microseconds. Can be 0 in case we don't want to express a deadline.

Return values:

  • -1 in case of error
  • 0 in case of success
END PHASE FOR A SPECIFIC DEVICE

This function explicitly ends a phase for a specific reconfigurable processor

Function: 

int end_phase (vproc_t vproc)

Arguments:

  • vproc: return value of run_task()

Return values:

  • -1 in case of error (e.g., wrong descriptor)
  • 0 in case of success

Note: this can be avoided if a new phase is started

Related

Wiki: Configuration
Wiki: Design
Wiki: Home