1/* SPDX-License-Identifier: BSD-3-Clause */
2/* Copyright(c) 2007-2022 Intel Corporation */
3/**
4 * @file icp_qat_fw_pke.h
5 * @defgroup icp_qat_fw_pke ICP QAT FW PKE Processing Definitions
6 * @ingroup icp_qat_fw
7 * $Revision: 0.1 $
8 * @brief
9 *      This file documents the external interfaces that the QAT FW running
10 *      on the QAT Acceleration Engine provides to clients wanting to
11 *      accelerate crypto assymetric applications
12 */
13
14#ifndef _ICP_QAT_FW_PKE_
15#define _ICP_QAT_FW_PKE_
16
17/*
18****************************************************************************
19* Include local header files
20****************************************************************************
21*/
22#include "icp_qat_fw.h"
23
24/**
25 *****************************************************************************
26 *
27 * @ingroup icp_qat_fw_pke
28 *
29 * @brief
30 *      PKE response status field structure contained
31 *      within LW1, comprising the common error codes and
32 *      the response flags.
33 *
34 *****************************************************************************/
35typedef struct icp_qat_fw_pke_resp_status_s {
36	uint8_t comn_err_code;
37	/**< 8 bit common error code */
38
39	uint8_t pke_resp_flags;
40	/**< 8-bit PKE response flags  */
41
42} icp_qat_fw_pke_resp_status_t;
43
44/**
45 *****************************************************************************
46 * @ingroup icp_qat_fw_pke
47 *      Definition of the QAT FW PKE request header pars field.
48 *      Structure differs from the DH895xxCC common base header structure, hence
49 *      redefined here.
50 * @description
51 *      PKE request message header pars structure
52 *
53 *****************************************************************************/
54typedef struct icp_qat_fw_req_hdr_pke_cd_pars_s {
55	/**< LWs 2-3 */
56	uint64_t content_desc_addr;
57	/**< Content descriptor pointer */
58
59	/**< LW 4 */
60	uint32_t content_desc_resrvd;
61	/**< Content descriptor reserved field */
62
63	/**< LW 5 */
64	uint32_t func_id;
65	/**< MMP functionality Id */
66
67} icp_qat_fw_req_hdr_pke_cd_pars_t;
68
69/**
70 *****************************************************************************
71 * @ingroup icp_qat_fw_pke
72 *      Definition of the QAT FW PKE request header mid section.
73 *      Structure differs from the DH895xxCC common base header structure,
74 *      instead following the DH89xxCC format, hence redefined here.
75 * @description
76 *      PKE request message header middle structure
77 *
78 *****************************************************************************/
79typedef struct icp_qat_fw_req_pke_mid_s {
80	/**< LWs 6-11 */
81	uint64_t opaque_data;
82	/**< Opaque data passed unmodified from the request to response messages
83	 * by
84	 * firmware (fw) */
85
86	uint64_t src_data_addr;
87	/**< Generic definition of the source data supplied to the QAT AE. The
88	 * common flags are used to further describe the attributes of this
89	 * field */
90
91	uint64_t dest_data_addr;
92	/**< Generic definition of the destination data supplied to the QAT AE.
93	 * The
94	 * common flags are used to further describe the attributes of this
95	 * field */
96
97	/**< Following DH89xxCC structure format - footer is excluded */
98
99} icp_qat_fw_req_pke_mid_t;
100
101/**
102 *****************************************************************************
103 * @ingroup icp_qat_fw_pke
104 *      Definition of the QAT FW PKE request header.
105 *      Structure differs from the DH895xxCC common base header structure,
106 *      instead following the DH89xxCC format, hence redefined here.
107 * @description
108 *      PKE request message header structure
109 *
110 *****************************************************************************/
111typedef struct icp_qat_fw_req_pke_hdr_s {
112	/**< LW0 */
113	uint8_t resrvd1;
114	/**< reserved field */
115
116	uint8_t resrvd2;
117	/**< reserved field */
118
119	uint8_t service_type;
120	/**< Service type */
121
122	uint8_t hdr_flags;
123	/**< This represents a flags field for the Service Request.
124	 * The most significant bit is the 'valid' flag and the only
125	 * one used. All remaining bit positions are unused and
126	 * are therefore reserved and need to be set to 0. */
127
128	/**< LW1 */
129	icp_qat_fw_comn_flags comn_req_flags;
130	/**< Common Request flags must indicate flat buffer (as per DH89xxCC)
131	 * Common Request flags - PKE slice flags no longer used - slice
132	 * allocated to a threadstrand.*/
133
134	uint16_t resrvd4;
135	/**< (DH89xxCC) CD Header Size and CD Params Size unused. Set to zero.
136	 */
137
138	/**< LWs 2-5 */
139	icp_qat_fw_req_hdr_pke_cd_pars_t cd_pars;
140	/**< PKE request message header pars structure - this differs
141	 * from the DH895xxCC common base structure */
142
143} icp_qat_fw_req_pke_hdr_t;
144
145/**
146 ***************************************************************************
147 *
148 * @ingroup icp_qat_fw_pke
149 *
150 * @brief
151 *      PKE request message structure (64 bytes)
152 *
153 *****************************************************************************/
154typedef struct icp_qat_fw_pke_request_s {
155	/**< LWs 0-5 */
156	icp_qat_fw_req_pke_hdr_t pke_hdr;
157	/**< Request header for PKE - CD Header/Param size
158	 * must be zero */
159
160	/**< LWs 6-11 (same as DH89xxCC) */
161	icp_qat_fw_req_pke_mid_t pke_mid;
162	/**< Request middle section for PKE */
163
164	/**< LW 12 */
165	uint8_t output_param_count;
166	/**< Number of output large integers
167	 * for request */
168
169	uint8_t input_param_count;
170	/**< Number of input large integers
171	 * for request */
172
173	uint16_t resrvd1;
174	/** Reserved **/
175
176	/**< LW 13 */
177	uint32_t resrvd2;
178	/**< Reserved */
179
180	/**< LWs 14-15 */
181	uint64_t next_req_adr;
182	/** < PKE - next request address */
183
184} icp_qat_fw_pke_request_t;
185
186/**
187 *****************************************************************************
188 *
189 * @ingroup icp_qat_fw_pke
190 *
191 * @brief
192 *      PKE response message header structure
193 *
194 *****************************************************************************/
195typedef struct icp_qat_fw_resp_pke_hdr_s {
196	/**< LW0 */
197	uint8_t resrvd1;
198	/**< The Response Destination Id has been removed
199	 * from first QWord */
200
201	uint8_t resrvd2;
202	/**< Response Pipe Id field is unused (reserved)
203	 * - Functionality within DH895xxCC uses arbiter instead */
204
205	uint8_t response_type;
206	/**< Response type - copied from the request to
207	 * the response message */
208
209	uint8_t hdr_flags;
210	/**< This represents a flags field for the Response.
211	 * The most significant bit is the 'valid' flag and the only
212	 * one used. All remaining bit positions are unused and
213	 * are therefore reserved */
214
215	/**< LW1 */
216	icp_qat_fw_pke_resp_status_t resp_status;
217
218	uint16_t resrvd4;
219	/**< (DH89xxCC) CD Header Size and CD Params Size fields unused.
220	 * Set to zero. */
221
222} icp_qat_fw_resp_pke_hdr_t;
223
224/**
225 *****************************************************************************
226 *
227 * @ingroup icp_qat_fw_pke
228 *
229 * @brief
230 *      PKE response message structure (32 bytes)
231 *
232 *****************************************************************************/
233typedef struct icp_qat_fw_pke_resp_s {
234	/**< LWs 0-1 */
235	icp_qat_fw_resp_pke_hdr_t pke_resp_hdr;
236	/**< Response header for PKE */
237
238	/**< LWs 2-3 */
239	uint64_t opaque_data;
240	/**< Opaque data passed from the request to the response message */
241
242	/**< LWs 4-5 */
243	uint64_t src_data_addr;
244	/**< Generic definition of the source data supplied to the QAT AE. The
245	 * common flags are used to further describe the attributes of this
246	 * field */
247
248	/**< LWs 6-7 */
249	uint64_t dest_data_addr;
250	/**< Generic definition of the destination data supplied to the QAT AE.
251	 * The
252	 * common flags are used to further describe the attributes of this
253	 * field */
254
255} icp_qat_fw_pke_resp_t;
256
257/* ========================================================================= */
258/*                           MACRO DEFINITIONS                               */
259/* ========================================================================= */
260
261/**< @ingroup icp_qat_fw_pke
262 * Macro defining the bit position and mask of the 'valid' flag, within the
263 * hdr_flags field of LW0 (service request and response) of the PKE request */
264#define ICP_QAT_FW_PKE_HDR_VALID_FLAG_BITPOS 7
265#define ICP_QAT_FW_PKE_HDR_VALID_FLAG_MASK 0x1
266
267/**< @ingroup icp_qat_fw_pke
268 * Macro defining the bit position and mask of the PKE status flag, within the
269 * status field LW1 of a PKE response message */
270#define QAT_COMN_RESP_PKE_STATUS_BITPOS 6
271/**< @ingroup icp_qat_fw_pke
272 * Starting bit position indicating the PKE status flag within the PKE response
273 * pke_resp_flags byte.  */
274
275#define QAT_COMN_RESP_PKE_STATUS_MASK 0x1
276/**< @ingroup icp_qat_fw_pke
277 * One bit mask used to determine PKE status mask */
278
279/*
280 *  < @ingroup icp_qat_fw_pke
281 *  *** PKE Response Status Field Definition ***
282 *  The PKE response follows the CPM 1.5 message format. The status field is 16 bits
283 *  wide, where the status flags are contained within the most significant byte of the
284 *  icp_qat_fw_pke_resp_status_t structure. The lower 8 bits of this word now contain
285 *  the common error codes, which are defined in the common header file(*).
286 */
287/*  + ===== + ----- + ---- + ----- + ----- + ----- + ----- + ----- + ----- + ----------------------- +
288 *  |  Bit  |  15   |  14  |  13   |  12   |  11   |  10   |   9   |   8   |        [7....0]         |
289 *  + ===== + ----- + ---- + ----- + ----- + ----- + ----- + ----- + ----- + ----------------------- +
290 *  | Flags | Rsrvd | Pke  | Rsrvd | Rsrvd | Rsrvd | Rsrvd | Rsrvd | Rsrvd |   Common error codes(*) |
291 *  + ===== + ----- + ---- + ----- + ----- + ----- + ----- + ----- + ----- + ----------------------- +
292 */
293
294/**
295 ******************************************************************************
296 * @ingroup icp_qat_fw_pke
297 *
298 * @description
299 *      Macro for extraction of the PKE bit from the 16-bit status field
300 *      particular to a PKE response. The status flags are contained within
301 *      the most significant byte of the word. The lower 8 bits of this status
302 *      word now contain the common error codes, which are defined in the common
303 *      header file. The appropriate macro definition to extract the PKE status
304 *      flag from the PKE response assumes that a single byte i.e.
305 *pke_resp_flags
306 *      is passed to the macro.
307 *
308 * @param status
309 *      Status to extract the PKE status bit
310 *
311 *****************************************************************************/
312#define ICP_QAT_FW_PKE_RESP_PKE_STAT_GET(flags)                                \
313	QAT_FIELD_GET((flags),                                                 \
314		      QAT_COMN_RESP_PKE_STATUS_BITPOS,                         \
315		      QAT_COMN_RESP_PKE_STATUS_MASK)
316
317/**
318 ******************************************************************************
319 * @ingroup icp_qat_fw_pke
320 *
321 * @description
322 *      Extract the valid flag from the PKE Request's header flags. Note that
323 *      this invokes the common macro which may be used by either the request
324 *      or the response.
325 *
326 * @param icp_qat_fw_req_pke_hdr_t  Structure passed to extract the valid bit
327 *                                  from the 'hdr_flags' field.
328 *
329 *****************************************************************************/
330#define ICP_QAT_FW_PKE_RQ_VALID_FLAG_GET(icp_qat_fw_req_pke_hdr_t)             \
331	ICP_QAT_FW_PKE_HDR_VALID_FLAG_GET(icp_qat_fw_req_pke_hdr_t)
332
333/**
334 ******************************************************************************
335 * @ingroup icp_qat_fw_pke
336 *
337 * @description
338 *      Set the valid bit in the PKE Request's header flags. Note that
339 *      this invokes the common macro which may be used by either the request
340 *      or the response.
341 *
342 * @param icp_qat_fw_req_pke_hdr_t  Structure passed to set the valid bit.
343 * @param val    Value of the valid bit flag.
344 *
345 *****************************************************************************/
346#define ICP_QAT_FW_PKE_RQ_VALID_FLAG_SET(icp_qat_fw_req_pke_hdr_t, val)        \
347	ICP_QAT_FW_PKE_HDR_VALID_FLAG_SET(icp_qat_fw_req_pke_hdr_t, val)
348
349/**
350 ******************************************************************************
351 * @ingroup icp_qat_fw_pke
352 *
353 * @description
354 *      Extract the valid flag from the PKE Response's header flags. Note that
355 *      invokes the common macro which may be used by either the request
356 *      or the response.
357 *
358 * @param icp_qat_fw_resp_pke_hdr_t  Structure to extract the valid bit
359 *                                    from the 'hdr_flags' field.
360 *
361 *****************************************************************************/
362#define ICP_QAT_FW_PKE_RESP_VALID_FLAG_GET(icp_qat_fw_resp_pke_hdr_t)          \
363	ICP_QAT_FW_PKE_HDR_VALID_FLAG_GET(icp_qat_fw_resp_pke_hdr_t)
364
365/**
366 ******************************************************************************
367 * @ingroup icp_qat_fw_pke
368 *
369 * @description
370 *      Set the valid bit in the PKE Response's header flags. Note that
371 *      this invokes the common macro which may be used by either the
372 *      request or the response.
373 *
374 * @param icp_qat_fw_resp_pke_hdr_t  Structure to set the valid bit
375 * @param val    Value of the valid bit flag.
376 *
377 *****************************************************************************/
378#define ICP_QAT_FW_PKE_RESP_VALID_FLAG_SET(icp_qat_fw_resp_pke_hdr_t, val)     \
379	ICP_QAT_FW_PKE_HDR_VALID_FLAG_SET(icp_qat_fw_resp_pke_hdr_t, val)
380
381/**
382 ******************************************************************************
383 * @ingroup icp_qat_fw_pke
384 *
385 * @description
386 *      Common macro to extract the valid flag from the header flags field
387 *      within the header structure (request or response).
388 *
389 * @param hdr_t  Structure (request or response) to extract the
390 *               valid bit from the 'hdr_flags' field.
391 *
392 *****************************************************************************/
393#define ICP_QAT_FW_PKE_HDR_VALID_FLAG_GET(hdr_t)                               \
394	QAT_FIELD_GET(hdr_t.hdr_flags,                                         \
395		      ICP_QAT_FW_PKE_HDR_VALID_FLAG_BITPOS,                    \
396		      ICP_QAT_FW_PKE_HDR_VALID_FLAG_MASK)
397
398/**
399 ******************************************************************************
400 * @ingroup icp_qat_fw_pke
401 *
402 * @description
403 *      Common macro to set the valid bit in the header flags field within
404 *      the header structure (request or response).
405 *
406 * @param hdr_t  Structure (request or response) containing the header
407 *               flags field, to allow the valid bit to be set.
408 * @param val    Value of the valid bit flag.
409 *
410 *****************************************************************************/
411#define ICP_QAT_FW_PKE_HDR_VALID_FLAG_SET(hdr_t, val)                          \
412	QAT_FIELD_SET((hdr_t.hdr_flags),                                       \
413		      (val),                                                   \
414		      ICP_QAT_FW_PKE_HDR_VALID_FLAG_BITPOS,                    \
415		      ICP_QAT_FW_PKE_HDR_VALID_FLAG_MASK)
416
417#endif /* _ICP_QAT_FW_PKE_ */
418