accel: Refer to plugins as 'modules' instead of 'engines'

operations supported by the framework have a backing software implementation in

the event that no hardware accelerators have been enabled for that operation.

When multiple hardware engines are enabled the framework will assign each operation to

an engine based on the order in which it was initialized. So, for example if two modules are

enabled, IOAT and software, the software engine will be used for every operation except those

When multiple hardware modules are enabled the framework will assign each operation to

a module based on the order in which it was initialized. So, for example if two modules are

enabled, IOAT and software, the software module will be used for every operation except those

supported by IOAT.

## Acceleration Low Level Libraries {#accel_libs}

### IOAT Module {#accel_ioat}

To use the IOAT engine, use the RPC [`ioat_scan_accel_engine`](https://spdk.io/doc/jsonrpc.html) before starting the application.

To use the IOAT module, use the RPC [`ioat_scan_accel_module`](https://spdk.io/doc/jsonrpc.html) before starting the application.

### DSA Module {#accel_dsa}

The DSA module supports the DSA hardware and relies on the low level IDXD library.

To use the DSA engine, use the RPC

[`dsa_scan_accel_engine`](https://spdk.io/doc/jsonrpc.html). By default, this

To use the DSA module, use the RPC

[`dsa_scan_accel_module`](https://spdk.io/doc/jsonrpc.html). By default, this

will attempt to load the SPDK user-space idxd driver. To use the built-in

kernel driver on Linux, add the `-k` parameter. See the next section for

details on using the kernel driver.

### Software Module {#accel_sw}

The software module is enabled by default. If no hardware engine is explicitly

The software module is enabled by default. If no hardware module is explicitly

enabled via startup RPC as discussed earlier, the software module will use ISA-L

if available for functions such as CRC32C. Otherwise, standard glibc calls are

used to back the framework API.

### Engine to Operation Code Assignment {#accel_assignments}

### Module to Operation Code Assignment {#accel_assignments}

When multiple engines are initialized, the accel framework will assign op codes to

engines by first assigning all op codes to the Software Engine and then overriding

op code assignments to Hardware Engines in the order in which they were initialized.

When multiple modules are initialized, the accel framework will assign op codes to

modules by first assigning all op codes to the Software Module and then overriding

op code assignments to Hardware Modules in the order in which they were initialized.

The RPC `accel_get_opc_assignments` can be used at any time to see the current

assignment map including the names of valid operations.  The RPC `accel_assign_opc`

can be used after initializing the desired Hardware Engines but before starting the

can be used after initializing the desired Hardware Modules but before starting the

framework in the event that a specific override is desired.  Note that to start an

application and send startup RPC's use the `--wait-for-rpc` parameter and then use the

`framework_start_init` RPC to continue. For example, assume the DSA Engine is initialized

`framework_start_init` RPC to continue. For example, assume the DSA Module is initialized

but for some reason the desire is to have the Software Module handle copies instead.

The following RPCs would accomplish the copy override:

`./scripts/rpc.py dsa_scan_accel_engine

`./scripts/rpc.py dsa_scan_accel_module

./scripts/rpc.py accel_assign_opc -o copy -e software

./scripts/rpc.py framework_start_init

./scripts/rpc.py accel_get_opc_assignments

  "decompress": "software"

}`

To detemine the name of available engines and their supported operations use the

RPC `accel_get_engine_info`.

To detemine the name of available modules and their supported operations use the

RPC `accel_get_module_info`.

    "framework_monitor_context_switch",

    "spdk_kill_instance",

    "accel_get_opc_assignments",

    "ioat_scan_accel_engine",

    "dsa_scan_accel_engine",

    "ioat_scan_accel_module",

    "dsa_scan_accel_module",

    "bdev_virtio_attach_controller",

    "bdev_virtio_scsi_get_devices",

    "bdev_virtio_detach_controller",

## Acceleration Framework Layer {#jsonrpc_components_accel_fw}

### accel_get_engine_info {#accel_get_engine_info}

### accel_get_module_info {#accel_get_module_info}

Get a list of valid engine names and their supported operations.

Get a list of valid module names and their supported operations.

#### Parameters

~~~json

{

  "jsonrpc": "2.0",

  "method": "accel_get_engine_info",

  "method": "accel_get_module_info",

  "id": 1

}

~~~

~~~json

[

  {

    "engine": "software",

    "module": "software",

    "supported ops": [

      "copy",

      "fill",

    ]

  },

  {

    "engine": "dsa",

    "module": "dsa",

    "supported ops": [

      "copy",

      "fill",

### accel_assign_opc {#rpc_accel_assign_opc}

Manually assign an operation to an engine.

Manually assign an operation to a module.

#### Parameters

Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------------

opname                  | Required | string      | name of operation

engine                  | Required | string      | name of engine

module                  | Required | string      | name of module

#### Example

  "method": "accel_assign_opc",

  "id": 1,

  "params": {

    "opanme": "copy",

    "engine": "software"

    "opname": "copy",

    "module": "software"

  }

}

~~~

}

~~~

### dsa_scan_accel_engine {#rpc_dsa_scan_accel_engine}

### dsa_scan_accel_module {#rpc_dsa_scan_accel_module}

Set config and enable dsa accel engine offload.

Set config and enable dsa accel module offload.

This feature is considered as experimental.

#### Parameters

    "config_kernel_mode": false

  },

  "jsonrpc": "2.0",

  "method": "dsa_scan_accel_engine",

  "method": "dsa_scan_accel_module",

  "id": 1

}

~~~

}

~~~

### iaa_scan_accel_engine {#rpc_iaa_scan_accel_engine}

### iaa_scan_accel_module {#rpc_iaa_scan_accel_module}

Enable IAA accel engine offload.

Enable IAA accel module offload.

This feature is considered as experimental.

#### Parameters

~~~json

{

  "jsonrpc": "2.0",

  "method": "iaa_scan_accel_engine",

  "method": "iaa_scan_accel_module",

  "id": 1

}

~~~

}

~~~

### ioat_scan_accel_engine {#rpc_ioat_scan_accel_engine}

### ioat_scan_accel_module {#rpc_ioat_scan_accel_module}

Enable ioat accel engine offload.

Enable ioat accel module offload.

#### Parameters

~~~json

{

  "jsonrpc": "2.0",

  "method": "ioat_scan_accel_engine",

  "method": "ioat_scan_accel_module",

  "id": 1

}

~~~

static void

dump_user_config(void)

{

	const char *engine_name = NULL;

	const char *module_name = NULL;

	int rc;

	rc = spdk_accel_get_opc_engine_name(g_workload_selection, &engine_name);

	rc = spdk_accel_get_opc_module_name(g_workload_selection, &module_name);

	if (rc) {

		printf("error getting engine name (%d)\n", rc);

		printf("error getting module name (%d)\n", rc);

	}

	printf("\nSPDK Configuration:\n");

	} else {

		printf("Transfer size:  %u bytes\n", g_xfer_size_bytes);

	}

	printf("Engine:         %s\n", engine_name);

	printf("Module:         %s\n", module_name);

	printf("Queue depth:    %u\n", g_queue_depth);

	printf("Allocate depth: %u\n", g_allocate_depth);

	printf("# threads/core: %u\n", g_threads_per_core);

	int dst_buff_len = g_xfer_size_bytes;

	/* For dualcast, the DSA HW requires 4K alignment on destination addresses but

	 * we do this for all engines to keep it simple.

	 * we do this for all modules to keep it simple.

	 */

	if (g_workload_selection == ACCEL_OPC_DUALCAST) {

		align = ALIGN_4K;

		worker->injected_miscompares++;

		status = 0;

	} else if (status) {

		/* Expected to pass but the accel engine reported an error (ex: COMPARE operation). */

		/* Expected to pass but the accel module reported an error (ex: COMPARE operation). */

		worker->xfer_failed++;

	}

				 spdk_accel_completion_cb cb_fn, void *cb_arg);

/**

 * Return the name of the engine assigned to a specfic opcode.

 * Return the name of the module assigned to a specfic opcode.

 *

 * \param opcode Accel Framework Opcode enum value. Valid codes can be retrieved using

 * `accel_get_opc_assignments` or `spdk_accel_get_opc_name`.

 * \param engine_name Pointer to update with engine name.

 * \param module_name Pointer to update with module name.

 *

 * \return 0 if a valid engine name was provided. -EINVAL for invalid opcode

 *  or -ENOENT no engine was found at this time for the provided opcode.

 * \return 0 if a valid module name was provided. -EINVAL for invalid opcode

 *  or -ENOENT no module was found at this time for the provided opcode.

 */

int spdk_accel_get_opc_engine_name(enum accel_opcode opcode, const char **engine_name);

int spdk_accel_get_opc_module_name(enum accel_opcode opcode, const char **module_name);

/**

 * Override the assignment of an opcode to an engine.

 * Override the assignment of an opcode to an module.

 *

 * \param opcode Accel Framework Opcode enum value. Valid codes can be retrieved using

 * `accel_get_opc_assignments` or `spdk_accel_get_opc_name`.

 * \param name Name of the engine to assign. Valid engine names may be retrieved

 * with `spdk_accel_get_opc_engine_name`

 * \param name Name of the module to assign. Valid module names may be retrieved

 * with `spdk_accel_get_opc_module_name`

 *

 * \return 0 if a valid opcode name was provided. -EINVAL for invalid opcode

 *  or if the framework has started (cannot change engines after startup)

 *  or if the framework has started (cannot change modules after startup)

 */

int spdk_accel_assign_opc(enum accel_opcode opcode, const char *name);

 *   All rights reserved.

 */

#ifndef SPDK_INTERNAL_ACCEL_ENGINE_H

#define SPDK_INTERNAL_ACCEL_ENGINE_H

#ifndef SPDK_ACCEL_MODULE_H

#define SPDK_ACCEL_MODULE_H

#include "spdk/stdinc.h"