DPACC API Guidelines 2019/10/12

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

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

Basic Types Linux type definitions shall be followed. For example int, u64, char etc. shall be used. https://www.kernel.org/doc/Documentation/CodingStyle http://www.gnu.org/prep/standards/standards.html 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, };

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

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: SA@IPSec 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

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

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

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

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 1024 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

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.

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.

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.

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 */ }

Example