#define CORE_HEADER_FILE

/ Copyright (c) 2018-2020 Silex Insight sa Copyright (c) 2014-2020 Beerten Engineering scs SPDX-License-Identifier: BSD-3-Clause

#define SX_PK_OP_DEFAULT_ENDIANNESS 1

0: little endian 1: big endian

typedef struct sx_pk_accel sx_pk_accel;

@addtogroup SX_PK_CORE

@{

typedef struct sx_pk_accel sx_pk_accel;

/ SilexPK and hardware constraints /
struct sx_pk_constraints {
    / Maximum simultaneous requests any application can configure. /
    int maxpending;
};

A public key operation for offload on a hardware accelerator

typedef struct sx_pk_constraints (FUNC_SX_PK_LIST_CONSTRAINTS)(int index, int usermemsz);
#define SX_PK_LIST_CONSTRAINTS ((FUNC_SX_PK_LIST_CONSTRAINTS)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_LIST_CONSTRAINTS)))

If maxpending in sx_pk_constraints is 0, than SilexPK cannot be used with the given environment.

index Index should always be 0

usermemsz User memory size provided in bytes. Should be non zero for BA414 AHBMaster and BA414 baremetal with no static memory @return Constraints of SilexPK

typedef const struct sx_pk_capabilities (FUNC_SX_PK_FETCH_CAPABILITIES)(struct sx_pk_cnx cnx);
#define SX_PK_FETCH_CAPABILITIES ((FUNC_SX_PK_FETCH_CAPABILITIES)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_FETCH_CAPABILITIES)))

cnx Connection structure obtained through SX_PK_OPEN() at startup @return NULL on failure @return Capabilities of the accelerator on success

typedef struct sx_pk_cnx (FUNC_SX_PK_OPEN)(struct sx_pk_config cfg);
#define SX_PK_OPEN ((FUNC_SX_PK_OPEN)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_OPEN)))

cfg Configuration to customize SilexPK to application specific needs. @return NULL on failure @return Connection structure for future SilexPK calls on success. Can be used with SilexPK functions to run operations. @see SX_PK_CLOSE()

typedef void (FUNC_SX_PK_CLOSE)(struct sx_pk_cnx cnx);
#define SX_PK_CLOSE ((FUNC_SX_PK_CLOSE)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_CLOSE)))

No other hardware acceleration function can be called after this.

cnx Connection structure obtained through SX_PK_OPEN() at startup

typedef struct sx_pk_dreq (FUNC_SX_PK_ACQUIRE_REQ)(struct sx_pk_cnx cnx, const struct sx_pk_cmd_def cmd);
#define SX_PK_ACQUIRE_REQ ((FUNC_SX_PK_ACQUIRE_REQ)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_ACQUIRE_REQ)))

The returned sx_pk_dreq structure contains a status and a pointer to a reserved hardware accelerator instance. That pointer is only valid and usable if status is non-zero.

cnx Connection structure obtained through SX_PK_OPEN() at startup

cmd The command definition (for example ::SX_PK_CMD_MOD_EXP) @return The acquired acceleration request for this operation @see SX_PK_RELEASE_REQ()

#define PK_OP_FLAGS_EDDSA_RX_LSB (1 << 30)

typedef unsigned int (FUNC_SX_PK_GET_REQ_ID)(sx_pk_accel req);

#define SX_PK_GET_REQ_ID ((FUNC_SX_PK_GET_REQ_ID)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_GET_REQ_ID)))

req The acceleration request obtained through SX_PK_ACQUIRE_REQ() @return instance number of the hardware accelerator for this request

typedef void (FUNC_SX_PK_SET_USER_CONTEXT)(sx_pk_accel req, void context);

#define SX_PK_SET_USER_CONTEXT ((FUNC_SX_PK_SET_USER_CONTEXT)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_SET_USER_CONTEXT)))

The attached pointer can be retrieved by SX_PK_GET_USER_CONTEXT(). After SX_PK_RELEASE_REQ(), the context pointer is not available anymore.

The context can represent any content the user may associate with the PK request.

req The acquired acceleration request

context Pointer to context @see SX_PK_GET_USER_CONTEXT()

typedef void (FUNC_SX_PK_GET_USER_CONTEXT)(sx_pk_accel req);

#define SX_PK_GET_USER_CONTEXT ((FUNC_SX_PK_GET_USER_CONTEXT)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_GET_USER_CONTEXT)))

req The acquired acceleration request @return Context pointer from an acceleration request @see SX_PK_SET_USER_CONTEXT()

typedef int (FUNC_SX_PK_GET_OPSIZE)(sx_pk_accel req);

#define SX_PK_GET_OPSIZE ((FUNC_SX_PK_GET_OPSIZE)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_GET_OPSIZE)))

req The acquired acceleration request @return Operand size for the request

typedef int (FUNC_SX_PK_LIST_ECC_INSLOTS)(sx_pk_accel req, const struct sx_pk_ecurve curve, int flags, struct sx_pk_slot inputs);
#define SX_PK_LIST_ECC_INSLOTS ((FUNC_SX_PK_LIST_ECC_INSLOTS)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_LIST_ECC_INSLOTS)))

Once the function completes with ::SX_OK, write each operand to the address found in the corresponding slot.

That applies to all ECC operations.

req The acceleration request obtained through SX_PK_ACQUIRE_REQ()

curve The curve used for that ECC operation

flags Operation specific flags

inputs List of input slots that will be filled in. See inputslots.h for predefined lists of input slots per operation. @return ::SX_OK @return ::SX_ERR_OPERAND_TOO_LARGE @return ::SX_ERR_BUSY

typedef int (FUNC_SX_PK_LIST_GFP_INSLOTS)(sx_pk_accel req, const int opsizes, struct sx_pk_slot inputs);
#define SX_PK_LIST_GFP_INSLOTS ((FUNC_SX_PK_LIST_GFP_INSLOTS)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_LIST_GFP_INSLOTS)))

Once the function completes with ::SX_OK, write each operands to the address found in the corresponding slot.

That applies to all operations except ECC.

req The acceleration request obtained through SX_PK_ACQUIRE_REQ()

opsizes List of operand sizes in bytes

inputs List of input slots that will be filled in. See inputslots.h for predefined lists of input slots per operation. @return ::SX_OK @return ::SX_ERR_OPERAND_TOO_LARGE @return ::SX_ERR_BUSY

typedef void (FUNC_SX_PK_RUN)(sx_pk_accel req);

#define SX_PK_RUN ((FUNC_SX_PK_RUN)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_RUN)))

@pre To be called after all operands have been written in the slots obtainded with SX_PK_LIST_ECC_INSLOTS() or SX_PK_LIST_GFP_INSLOTS(). After that the acceleration request is pending.

@post The caller should wait until the operation finishes with SX_PK_WAIT() or do polling by using sx_pk_has_finished().

req The acceleration request obtained through SX_PK_ACQUIRE_REQ()

typedef int (FUNC_SX_PK_GET_STATUS)(sx_pk_accel req);

#define SX_PK_GET_STATUS ((FUNC_SX_PK_GET_STATUS)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_GET_STATUS)))

Read the status of a request. When the accelerator is still busy, return ::SX_ERR_BUSY. When the accelerator finished, return ::SX_OK. May only be called after SX_PK_RUN(). May not be called after sx_pk_has_finished() or other functions like SX_PK_WAIT() reported that the operation finished.

req The acceleration request obtained through SX_PK_ACQUIRE_REQ() @return Any \ref SX_PK_STATUS "status code"

typedef int (FUNC_SX_PK_WAIT)(sx_pk_accel req);

#define SX_PK_WAIT ((FUNC_SX_PK_WAIT)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_WAIT)))

After the operation finishes, return the operation status code.

req The acceleration request obtained through SX_PK_ACQUIRE_REQ() @return Any \ref SX_PK_STATUS "status code"

typedef void (FUNC_SX_PK_CLEAR_IRQ)(void);

#define SX_PK_CLEARIRQ ((FUNC_SX_PK_CLEAR_IRQ)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_CLEARIRQ)))

Clear the IRQ request signal

typedef sx_pk_accel (FUNC_SX_PK_POP_FINISHED_REQ)(struct sx_pk_cnx cnx);
#define SX_PK_POP_FINISHED_REQ ((FUNC_SX_PK_POP_FINISHED_REQ)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_POP_FINISHED_REQ)))

If no public key accelerator finished or none has an operation, return NULL. The results from the returned sx_pk_accel should be used as soon as possible and the instances given back with SX_PK_RELEASE_REQ().

cnx Connection structure obtained through SX_PK_OPEN() at startup @return NULL when no public key accelerator finished or none has an operation @return The acceleration request which finished its operation

typedef int (FUNC_SX_PK_GET_GLOBAL_NOTIFICATION_ID)(struct sx_pk_cnx cnx);
#define SX_PK_GET_GLOBAL_NOTIFICATION_ID ((FUNC_SX_PK_GET_GLOBAL_NOTIFICATION_ID)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_GET_GLOBAL_NOTIFICATION_ID)))

The platform notification id is:

• -1 if not available

• a fd on POSIX systems

• an interrupt line number

When a request completes the notification will activate. The fd will become readable and the interrupt line will generate an interrupt. The returned platform notification can be used once. After the platform notification or after SX_PK_POP_FINISHED_REQ(), the notification id shall not be used anymore.

May not be used in combination with SX_PK_WAIT().

cnx Connection structure obtained through SX_PK_OPEN() at startup @return platform notification id

typedef int (FUNC_SX_PK_GET_REQ_COMPLETION_ID)(sx_pk_accel req);

#define SX_PK_GET_REQ_COMPLETION_ID ((FUNC_SX_PK_GET_REQ_COMPLETION_ID)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_GET_REQ_COMPLETION_ID)))

The platform notification id is:

• -1 if not available

• a fd on POSIX systems

• an interrupt line number

When the request completes the notification will activate. The fd will become readable and the interrupt line will generate an interrupt. After it was used or after SX_PK_POP_FINISHED_REQ(), the fd or interrupt line shall not be used anymore.

May not be used in combination with SX_PK_WAIT().

req The acceleration request obtained through SX_PK_ACQUIRE_REQ() @return platform notification id

typedef const char (FUNC_SX_PK_GET_OUTPUT_OPS)(sx_pk_accel req);

#define SX_PK_GET_OUTPUT_OPS ((FUNC_SX_PK_GET_OUTPUT_OPS)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_GET_OUTPUT_OPS)))

req The acceleration request obtained through SX_PK_ACQUIRE_REQ() @return Array of addresses to output operands

typedef void (FUNC_SX_PK_RELEASE_REQ)(sx_pk_accel req);

#define SX_PK_RELEASE_REQ ((FUNC_SX_PK_RELEASE_REQ)((uint32_t )(API_TABLE_BASE_ADDRESS + ATO_SX_PK_RELEASE_REQ)))

Release the reserved resources

@pre SX_PK_ACQUIRE_REQ() should have been called before this function is called and not being in use by the hardware

req The acceleration request obtained through SX_PK_ACQUIRE_REQ() operation has finished