diff options
Diffstat (limited to 'include/drivers/nxp/crypto/caam/sec_jr_driver.h')
| -rw-r--r-- | include/drivers/nxp/crypto/caam/sec_jr_driver.h | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/include/drivers/nxp/crypto/caam/sec_jr_driver.h b/include/drivers/nxp/crypto/caam/sec_jr_driver.h new file mode 100644 index 000000000..57e0fa0ee --- /dev/null +++ b/include/drivers/nxp/crypto/caam/sec_jr_driver.h @@ -0,0 +1,178 @@ +/* + * Copyright 2017-2021 NXP + * + * SPDX-License-Identifier: BSD-3-Clause + * + */ + +#ifndef _JR_DRIVER_H_ +#define _JR_DRIVER_H_ + +#include "jr_driver_config.h" + +/* The maximum size of a SEC descriptor, in WORDs (32 bits). */ +#define MAX_DESC_SIZE_WORDS 64 + +#define CAAM_TIMEOUT 200000 /* ms */ + +/* Return codes for JR user space driver APIs */ +typedef enum sec_return_code_e { + SEC_SUCCESS = 0, + SEC_INVALID_INPUT_PARAM, + SEC_OUT_OF_MEMORY, + SEC_DESCRIPTOR_IN_FLIGHT, + SEC_LAST_DESCRIPTOR_IN_FLIGHT, + SEC_PROCESSING_ERROR, + SEC_DESC_PROCESSING_ERROR, + SEC_JR_IS_FULL, + SEC_DRIVER_RELEASE_IN_PROGRESS, + SEC_DRIVER_ALREADY_INITIALIZED, + SEC_DRIVER_NOT_INITIALIZED, + SEC_JOB_RING_RESET_IN_PROGRESS, + SEC_RESET_ENGINE_FAILED, + SEC_ENABLE_IRQS_FAILED, + SEC_DISABLE_IRQS_FAILED, + SEC_RETURN_CODE_MAX_VALUE, +} sec_return_code_t; + +/* STRUCTURES AND OTHER TYPEDEFS */ + +/* + * @brief Function called by JR User Space driver to notify every processed + * descriptor. + * + * Callback provided by the User Application. + * Callback is invoked by JR User Space driver for each descriptor processed by + * SEC + * @param [in] status Status word indicating processing result for + * this descriptor. + * @param [in] arg Opaque data passed by User Application + * It is opaque from JR driver's point of view. + * @param [in] job_ring The job ring handle on which the processed + * descriptor word was enqueued + */ +typedef void (*user_callback) (uint32_t *desc, uint32_t status, + void *arg, void *job_ring); + +/* + * Structure encompassing a job descriptor which is to be processed + * by SEC. User should also initialise this structure with the callback + * function pointer which will be called by driver after recieving proccessed + * descriptor from SEC. User data is also passed in this data structure which + * will be sent as an argument to the user callback function. + */ +struct job_descriptor { + uint32_t desc[MAX_DESC_SIZE_WORDS]; + void *arg; + user_callback callback; +}; + +/* + * @brief Initialize the JR User Space driver. + * This function will handle initialization of sec library + * along with registering platform specific callbacks, + * as well as local data initialization. + * Call once during application startup. + * @note Global SEC initialization is done in SEC kernel driver. + * @note The hardware IDs of the initialized Job Rings are opaque to the UA. + * The exact Job Rings used by this library are decided between SEC user + * space driver and SEC kernel driver. A static partitioning of Job Rings is + * assumed, configured in DTS(device tree specification) file. + * @param [in] platform_cb Registering the platform specific + * callbacks with driver + * @retval ::0 for successful execution + * @retval ::-1 failure + */ +int sec_jr_lib_init(void); + +/* + * @brief Initialize the software and hardware resources tied to a job ring. + * @param [in] jr_mode; Model to be used by SEC Driver to receive + * notifications from SEC. Can be either + * SEC_NOTIFICATION_TYPE_IRQ or + * SEC_NOTIFICATION_TYPE_POLL + * @param [in] irq_coalescing_timer This value determines the maximum + * amount of time after processing a + * descriptor before raising an interrupt. + * @param [in] irq_coalescing_count This value determines how many + * descriptors are completed before + * raising an interrupt. + * @param [in] reg_base_addr The job ring base address register + * @param [in] irq_id The job ring interrupt identification number. + * @retval job_ring_handle for successful job ring configuration + * @retval NULL on error + */ +void *init_job_ring(uint8_t jr_mode, + uint16_t irq_coalescing_timer, + uint8_t irq_coalescing_count, + void *reg_base_addr, uint32_t irq_id); + +/* + * @brief Release the resources used by the JR User Space driver. + * Reset and release SEC's job rings indicated by the User Application at + * init_job_ring() and free any memory allocated internally. + * Call once during application tear down. + * @note In case there are any descriptors in-flight (descriptors received by + * JR driver for processing and for which no response was yet provided to UA), + * the descriptors are discarded without any notifications to User Application. + * @retval ::0 is returned for a successful execution + * @retval ::-1 is returned if JR driver release is in progress + */ +int sec_release(void); + +/* + * @brief Submit a descriptor for SEC processing. + * This function creates a "job" which is meant to instruct SEC HW + * to perform the processing on the input buffer. The "job" is enqueued + * in the Job Ring associated. The function will return after the "job" + * enqueue is finished. The function will not wait for SEC to + * start or/and finish the "job" processing. + * After the processing is finished the SEC HW writes the processing result + * to the provided output buffer. + * The Caller must poll JR driver using jr_dequeue() + * to receive notifications of the processing completion + * status. The notifications are received by caller by means of callback + * (see ::user_callback). + * @param [in] job_ring_handle The handle of the job ring on which + * descriptor is to be enqueued + * @param [in] job_descriptor The job descriptor structure of type + * struct job_descriptor. This structure + * should be filled with job descriptor along + * with callback function to be called after + * processing of descriptor and some + * opaque data passed to be passed to the + * callback function + * + * @retval ::0 is returned for successful execution + * @retval ::-1 is returned if there is some enqueue failure + */ +int enq_jr_desc(void *job_ring_handle, struct job_descriptor *jobdescr); + +/* + * @brief Polls for available descriptors processed by SEC on a specific + * Job Ring + * This function polls the SEC Job Rings and delivers processed descriptors + * Each processed descriptor has a user_callback registered. + * This user_callback is invoked for each processed descriptor. + * The polling is stopped when "limit" descriptors are notified or when + * there are no more descriptors to notify. + * @note The dequeue_jr() API cannot be called from within a user_callback + * function + * @param [in] job_ring_handle The Job Ring handle. + * @param [in] limit This value represents the maximum number + * of processed descriptors that can be + * notified API call on this Job Ring. + * Note that fewer descriptors may be notified + * if enough processed descriptors are not + * available. + * If limit has a negative value, then all + * ready descriptors will be notified. + * + * @retval :: >=0 is returned where retval is the total + * Number of descriptors notified + * during this function call. + * @retval :: -1 is returned in case of some error + */ +int dequeue_jr(void *job_ring_handle, int32_t limit); + +#endif /* _JR_DRIVER_H_ */ |