1. DPACC API Guidelines
2019/10/12

2. Motivation One needs different g-API suite for different use-case
Specify generally applicable guidelines for DPACC g-API

3. Table of Contents Basic Types API Naming Convention
Variable Naming convention
Function Convention
Example

4. Basic Types
Linux type definitions shall be followed. For example int, u64, char etc. shall be used.
All the enum should be declared to support the binary compatibility.
For ex:
enum g_pdcp_sn_size {
G_PDCP_SN_SIZE_5=5,
G_PDCP_SN_SIZE_7=7,
G_PDCP_SN_SIZE_12=12,
G_PDCP_SN_SIZE_15=15, };

5. API Naming convention Structure
What needs to be conveyed in an API name?
API type: g-API? S-API? …
Acceleration Functionality: Crypto? IPSec? PDCP?
Acceleration Model: Lookaside? Inline? Data Path Offload?
Operation: Open? Close? Process?
Common operations: open? Close?
Specific operations: encap/decap/flush
Suffix
Common name: api_version
Specific name: sa for IPSec (g_ipsec_la_add_sa) sec for PDCP (g_pdcp_la_add_sec)
Proposal
apiname =
apitype ‘_’accfunc ‘_’accmodel ‘_’operation ‘_’ suffix
e.g. g_ipsec_la_get_api_version

6. API Naming convention Syntax
What could be filled with each elements in an API name?
API type: g-API? S-API?
Acceleration Functionality: Crypto? IPSec? PDCP?
Acceleration Model: Lookaside? Inline? Data Path Offload?
Operation: Open? Close? Process?
Common operations: open? Close?
Specific operations:
Suffix
Common name: api_version
Specific name:
Out of scope of this proposal
dpacc arch
dpacc usecase
dpacc usecase
Propose to be included in intended doc
Propose to be illustrated in intended doc

7. API Naming convention Operations
This operations can generic like Open, Close, Add, Del, Mod, Get ,Process.
It can be extended with specific operation names, based on the accelerator’s need.
For Ex:
flush, invoke, register, send, poll, etc .,
Examples:
g_ipsec_la_open
g_pdcp_la_close
g_ipsec_la_flush_sa
g_pdcp_la_poll
open opens the accelerator
close closes the accelerator
get gets the info
set sets the info
add adds the info
modify modifies the info
delete deletes the info
find finds the info
process processes the data
notify notification

8. API Naming convention Common names
api_version
open
close
Examples:
g_ipsec_la_get_api_version
g_pdcp_la_get_api_version

9. Variable Naming Convention
Naming convention for variables shall
follow Linux style,
readable and
separated by underscore, when necessary.

10. Function Convention Return Values
SUCCESS (0) or FAILURE (-1).
Can we go with –ve value for failure and +ve for success message.
For Ex:
G_XYZ_XYZ_GENERAL_SUCCESS 0
G_XYZ_XYZ_RECORD_ADD_SUCCESS 1
G_XYZ_XYZ_NO_DUPLICATE_RECORD_FOUND 2
G_XYZ_XYZ_GENERAL_FAILURE -1
G_XYZ_XYZ_MEMORY_ALLOC_FAIL -2
G_XYZ_XYZ_DUPLICATE_RECORD_FOUND -3
Do we need to reserve and common errcodes accelerator ?
ACCELERATOR_AVAILABLE 0
ACCELERATOR_NOT_AVAILABLE -1
RESERVED_ERROR_CODE_BASE
G_ACC_1_ERROR_CODE_START RESERVED_ERROR_CODE_BASE+1
G_ACC_1_ERROR_CODE_END RESERVED_ERROR_CODE_BASE+1024
G_ACC_2_ERROR_CODE_START G_ACC_1_ERROR_CODE_END +1
G_ACC_2_ERROR_CODE_END G_ACC_1_ERROR_CODE_END +1024

11. Function Convention Control Function Parameters
Int g_ipsec_la_add_sa( struct g_ipsec_la_handle *handle, /* Accelerator handle */ const struct g_ipsec_la_add_sa_inargs *in, /* Input */ enum g_ipsec_la_control_flags flags, /* API flags */ struct g_ipsec_la_add_sa_outargs *out, /* Output */ struct g_ipsec_la_resp_args resp /* response callback in case asynchronous mode with response flag is set */ ); Group the input and output values to an inargs/outarg structure.

12. Function Convention Data Processing Function Parameters
int32_t g_ipsec_la_packet_encap( struct g_ipsec_la_handle *handle, struct g_ipsec_la_control_flags flags, struct g_ipsec_la_sa_handle *handle; /* SA Handle */ uint32 num_sg_elem; /* num of Scatter Gather elements */ struct g_ipsec_la_data in_data[]; /* Array of data blocks */ struct g_ipsec_la_data out_data[]; /* Array of output data blocks */ struct g_api_resp_args resp )
For control or setup APIs that are used to setup states in the hardware accelerator it is preferable to use data structures to pass input and output parameters. While these setup or control functions do not come in the data path and hence do not impact performance, having parameters defined as structures enables extensibility in future without changing API prototypes. Structure introduced for passing in as parameters for functions shall have the function name as prefix and inargs/outargs as suffixes to indicate input and output arguments.
struct g_ipsec_la_data contains a ptr and length of the buffer. This method is used instead of buffer ptr itself to avoid using application specific buffers in the driver. This way, the driver independent of buffers used in SAL, which could be either skb in linux kernel, rte_mbuf in DPDK or odp_buffer in ODP.. Array is used to allow fragmented buffer.

13. Function Parameters Control Flags (An Example)
enum g_ipsec_la_control_flags { G_IPSEC_LA_CTRL_FLAG_ASYNC=1, /* If Set, API call be asynchronous. Otherwise, API call will be synchronous */ G_IPSEC_LA_CTRL_FLAG_NO_RESP_EXPECTED=2, /* If set, no response is expected for this API call */ };
Application can request the response to be returned synchronously or asynchronously (G_IPSEC_LA_CTRL_FLAG_ASYNC). If the response is requested asynchronously, then the application should provide a callback function pointer and callback argument.
Also, in some scenarios, the API layer may have to do additional operations to force a response from the backend. The flag G_IPSEC_LA_CTRL_FLAG_NO_RESP_EXPECTED can be used by application to indicate whether the application should force the response from the backend or not.

14. Function Parameters Response Args (An example)
struct g_ipsec_la_resp_args {
struct g_ipsec_la_resp_cbfn cb_fn;
/* Callback function if ASYNC flag is chosen */
void *cb_arg;
int32_t cb_arg_len; /* Callback argument length */ }

15. Example