Pankaj Gupta | 95c7eee | 2020-12-09 14:02:39 +0530 | [diff] [blame] | 1 | /* |
Pankaj Gupta | 7834b46 | 2021-03-25 15:15:52 +0530 | [diff] [blame] | 2 | * Copyright 2017-2021 NXP |
Pankaj Gupta | 95c7eee | 2020-12-09 14:02:39 +0530 | [diff] [blame] | 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 |
Elyes Haouas | 2be03c0 | 2023-02-13 09:14:48 +0100 | [diff] [blame] | 60 | * function pointer which will be called by driver after receiving proccessed |
Pankaj Gupta | 95c7eee | 2020-12-09 14:02:39 +0530 | [diff] [blame] | 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_ */ |