1 /* 2 * Copyright 2017-2021 NXP 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 #ifndef _JR_DRIVER_H_ 9 #define _JR_DRIVER_H_ 10 11 #include "jr_driver_config.h" 12 13 /* The maximum size of a SEC descriptor, in WORDs (32 bits). */ 14 #define MAX_DESC_SIZE_WORDS 64 15 16 #define CAAM_TIMEOUT 200000 /* ms */ 17 18 /* Return codes for JR user space driver APIs */ 19 typedef enum sec_return_code_e { 20 SEC_SUCCESS = 0, 21 SEC_INVALID_INPUT_PARAM, 22 SEC_OUT_OF_MEMORY, 23 SEC_DESCRIPTOR_IN_FLIGHT, 24 SEC_LAST_DESCRIPTOR_IN_FLIGHT, 25 SEC_PROCESSING_ERROR, 26 SEC_DESC_PROCESSING_ERROR, 27 SEC_JR_IS_FULL, 28 SEC_DRIVER_RELEASE_IN_PROGRESS, 29 SEC_DRIVER_ALREADY_INITIALIZED, 30 SEC_DRIVER_NOT_INITIALIZED, 31 SEC_JOB_RING_RESET_IN_PROGRESS, 32 SEC_RESET_ENGINE_FAILED, 33 SEC_ENABLE_IRQS_FAILED, 34 SEC_DISABLE_IRQS_FAILED, 35 SEC_RETURN_CODE_MAX_VALUE, 36 } sec_return_code_t; 37 38 /* STRUCTURES AND OTHER TYPEDEFS */ 39 40 /* 41 * @brief Function called by JR User Space driver to notify every processed 42 * descriptor. 43 * 44 * Callback provided by the User Application. 45 * Callback is invoked by JR User Space driver for each descriptor processed by 46 * SEC 47 * @param [in] status Status word indicating processing result for 48 * this descriptor. 49 * @param [in] arg Opaque data passed by User Application 50 * It is opaque from JR driver's point of view. 51 * @param [in] job_ring The job ring handle on which the processed 52 * descriptor word was enqueued 53 */ 54 typedef void (*user_callback) (uint32_t *desc, uint32_t status, 55 void *arg, void *job_ring); 56 57 /* 58 * Structure encompassing a job descriptor which is to be processed 59 * by SEC. User should also initialise this structure with the callback 60 * function pointer which will be called by driver after recieving proccessed 61 * descriptor from SEC. User data is also passed in this data structure which 62 * will be sent as an argument to the user callback function. 63 */ 64 struct job_descriptor { 65 uint32_t desc[MAX_DESC_SIZE_WORDS]; 66 void *arg; 67 user_callback callback; 68 }; 69 70 /* 71 * @brief Initialize the JR User Space driver. 72 * This function will handle initialization of sec library 73 * along with registering platform specific callbacks, 74 * as well as local data initialization. 75 * Call once during application startup. 76 * @note Global SEC initialization is done in SEC kernel driver. 77 * @note The hardware IDs of the initialized Job Rings are opaque to the UA. 78 * The exact Job Rings used by this library are decided between SEC user 79 * space driver and SEC kernel driver. A static partitioning of Job Rings is 80 * assumed, configured in DTS(device tree specification) file. 81 * @param [in] platform_cb Registering the platform specific 82 * callbacks with driver 83 * @retval ::0 for successful execution 84 * @retval ::-1 failure 85 */ 86 int sec_jr_lib_init(void); 87 88 /* 89 * @brief Initialize the software and hardware resources tied to a job ring. 90 * @param [in] jr_mode; Model to be used by SEC Driver to receive 91 * notifications from SEC. Can be either 92 * SEC_NOTIFICATION_TYPE_IRQ or 93 * SEC_NOTIFICATION_TYPE_POLL 94 * @param [in] irq_coalescing_timer This value determines the maximum 95 * amount of time after processing a 96 * descriptor before raising an interrupt. 97 * @param [in] irq_coalescing_count This value determines how many 98 * descriptors are completed before 99 * raising an interrupt. 100 * @param [in] reg_base_addr The job ring base address register 101 * @param [in] irq_id The job ring interrupt identification number. 102 * @retval job_ring_handle for successful job ring configuration 103 * @retval NULL on error 104 */ 105 void *init_job_ring(uint8_t jr_mode, 106 uint16_t irq_coalescing_timer, 107 uint8_t irq_coalescing_count, 108 void *reg_base_addr, uint32_t irq_id); 109 110 /* 111 * @brief Release the resources used by the JR User Space driver. 112 * Reset and release SEC's job rings indicated by the User Application at 113 * init_job_ring() and free any memory allocated internally. 114 * Call once during application tear down. 115 * @note In case there are any descriptors in-flight (descriptors received by 116 * JR driver for processing and for which no response was yet provided to UA), 117 * the descriptors are discarded without any notifications to User Application. 118 * @retval ::0 is returned for a successful execution 119 * @retval ::-1 is returned if JR driver release is in progress 120 */ 121 int sec_release(void); 122 123 /* 124 * @brief Submit a descriptor for SEC processing. 125 * This function creates a "job" which is meant to instruct SEC HW 126 * to perform the processing on the input buffer. The "job" is enqueued 127 * in the Job Ring associated. The function will return after the "job" 128 * enqueue is finished. The function will not wait for SEC to 129 * start or/and finish the "job" processing. 130 * After the processing is finished the SEC HW writes the processing result 131 * to the provided output buffer. 132 * The Caller must poll JR driver using jr_dequeue() 133 * to receive notifications of the processing completion 134 * status. The notifications are received by caller by means of callback 135 * (see ::user_callback). 136 * @param [in] job_ring_handle The handle of the job ring on which 137 * descriptor is to be enqueued 138 * @param [in] job_descriptor The job descriptor structure of type 139 * struct job_descriptor. This structure 140 * should be filled with job descriptor along 141 * with callback function to be called after 142 * processing of descriptor and some 143 * opaque data passed to be passed to the 144 * callback function 145 * 146 * @retval ::0 is returned for successful execution 147 * @retval ::-1 is returned if there is some enqueue failure 148 */ 149 int enq_jr_desc(void *job_ring_handle, struct job_descriptor *jobdescr); 150 151 /* 152 * @brief Polls for available descriptors processed by SEC on a specific 153 * Job Ring 154 * This function polls the SEC Job Rings and delivers processed descriptors 155 * Each processed descriptor has a user_callback registered. 156 * This user_callback is invoked for each processed descriptor. 157 * The polling is stopped when "limit" descriptors are notified or when 158 * there are no more descriptors to notify. 159 * @note The dequeue_jr() API cannot be called from within a user_callback 160 * function 161 * @param [in] job_ring_handle The Job Ring handle. 162 * @param [in] limit This value represents the maximum number 163 * of processed descriptors that can be 164 * notified API call on this Job Ring. 165 * Note that fewer descriptors may be notified 166 * if enough processed descriptors are not 167 * available. 168 * If limit has a negative value, then all 169 * ready descriptors will be notified. 170 * 171 * @retval :: >=0 is returned where retval is the total 172 * Number of descriptors notified 173 * during this function call. 174 * @retval :: -1 is returned in case of some error 175 */ 176 int dequeue_jr(void *job_ring_handle, int32_t limit); 177 178 #endif /* _JR_DRIVER_H_ */ 179