1 #ifndef _PA_H
2 #define _PA_H
4 #ifdef __cplusplus
5 extern "C" {
6 #endif
8 /* System level header files */
9 #include <stdint.h>
10 #include <stdlib.h>
12 #include <ti/drv/pa/paver.h>
14 /* ============================================================= */
15 /**
16 * @file pa.h
17 *
18 * path ti/drv/pa/pa.h
19 *
20 * @brief Packet Accelerator (PA) sub-system LLD API and Data Definitions
21 *
22 * ============================================================================
23 * Copyright (c) Texas Instruments Incorporated 2009-2013
24 *
25 * Redistribution and use in source and binary forms, with or without
26 * modification, are permitted provided that the following conditions
27 * are met:
28 *
29 * Redistributions of source code must retain the above copyright
30 * notice, this list of conditions and the following disclaimer.
31 *
32 * Redistributions in binary form must reproduce the above copyright
33 * notice, this list of conditions and the following disclaimer in the
34 * documentation and/or other materials provided with the
35 * distribution.
36 *
37 * Neither the name of Texas Instruments Incorporated nor the names of
38 * its contributors may be used to endorse or promote products derived
39 * from this software without specific prior written permission.
40 *
41 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
42 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
43 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
44 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
45 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
47 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
48 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
49 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
50 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
51 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
52 *
53 */
55 /** @mainpage Packet Accelerator Low Level Driver
56 *
57 * \image html doxydoc.wmf
58 *
59 * @section intro Introduction
60 *
61 * The packet accelerator sub-system (PASS) is designed to provide the input packet classification, checksum/CRC
62 * verification and generation, data manipulation and etc. The PASS consists of the following resources
63 * - Six PDSPs for packet and command processing
64 * - Three 64-entry LUT1 (connected to PDSP0, PDSP1 and PDSP2) for Layer 2/3 or custom LUT1 lookup
65 * - One 8192-entry LUT2 (connected to PDSP3) for Layer 4/5 or custom LUT2 lookup
66 * - Six programmable CRC engines (connected to each PDSP respectively) for CRC computation and verification
67 * - Six 16-bit general purpose timers
68 *
69 * The packet accelerator low level driver (PA LLD) provides configuration and control of the packet accelerator
70 * sub-system (PASS). The sub-system provides from network packet classification and routing based on
71 * network header information (see @ref netlayers). The packet accelerator low level driver module
72 * (referred to as the module) provides APIs to configure the criteria used for from-network packet
73 * routing.
74 *
75 * The module attempts to abstract the operation of the PASS from the application. The module uses the following rules
76 * when configuring the PASS:
77 * - All received packets from Ethernet and/or SRIO are routed to PDSP0
78 * - PDSP0 does L0-L2 (MAC/SRIO) lookup using LUT1-0. If the packet is IP, it is forwarded to PDSP1
79 * - PDSP1 does the outer IP or Custom LUT1 lookup using LUT1-1
80 * - PDSP2 does any subsequent IP or Custom LUT1 lookup using LUT1-2
81 * - PDSP3 does all TCP/UDP and Custom LUT2 lookup using LUT2
82 * - PDSP4 is used for post-lookup processes such as checksum/CRC result verification.
83 * - PDSP4/5 can be used for pre-transmission operation such as transmit checksum generation.
84 *
85 * With the exception of some initial setup functions, the module does not communicate directly with
86 * the sub-system. The output of the module is a formatted data block along with a destination address.
87 * The module user must send the formatted data to the sub-system. This is typically done by linking the
88 * created data block to a host packet descriptor, and then using the addressing information to send
89 * the created packet to the sub-system through the queue manager and PKTDMA.
90 *
91 * For packets to the network, the sub-system provides ones complement checksum or CRC generation over
92 * a range provided by the module user. The range is not determined by sub-system by parsing the
93 * to-network packet, since it is assumed that the creator of the packet already has the start offset,
94 * length, initial checksum value and etc.
95 *
96 * The low level driver maintains two tables of layer 2 and layer 3 configuration information. The memory
97 * for these tables is provided by the module user at run time. The module maintains ownership of these
98 * tables and the module user must not write to the memory once provided to the module.
99 *
100 * In multi-core devices the module can be used in two different configurations. In independent core
101 * mode each core in a device has a unique set of tables. Although it is legal for any core to
102 * reference handles from other cores, this is not typically done. In this case cache coherency and
103 * cross core semaphores are not implemented by the module user. In common core mode there is only
104 * one set of tables and they are shared by all cores. Each core that uses the module must initialize
105 * it, but each core will provide the exact same buffers to the module. The module user will have
106 * the first core to initialize the module also initialize the table. Other cores will initialize their
107 * internal state but not initalize the table. In this mode @ref cache coherency and cross core @ref semaphores
108 * must be implemented by the module user to insure the integrity of the tables.
109 */
111 /* Define PALLD Module as a master group in Doxygen format and add all PA LLD API
112 definitions to this group. */
113 /** @defgroup palld_module PA LLD Module API
114 * @{
115 */
116 /** @} */
118 /** @defgroup palld_api_functions PA LLD Functions
119 * @ingroup palld_module
120 */
122 /** @defgroup palld_api_macros PA LLD Macros
123 * @ingroup palld_module
124 */
126 /** @defgroup palld_api_structures PA LLD Data Structures
127 * @ingroup palld_module
128 */
130 /** @defgroup palld_api_constants PA LLD Constants (enum's and define's)
131 * @ingroup palld_module
132 */
134 /**
135 * @def pa_PARAMS_NOT_SPECIFIED
136 * Used for unspecified classification parameters
137 */
138 #define pa_PARAMS_NOT_SPECIFIED 0xFFFF
140 /**
141 * @def pa_LUT_INST_NOT_SPECIFIED
142 * Used if LUT1(or LUT2) instance is not specified
143 * In the case, the PA LLD will decide which LUT instance to use based on the API type and the previous link information
144 */
145 #define pa_LUT_INST_NOT_SPECIFIED -1
147 /**
148 * @def pa_LUT1_INDEX_NOT_SPECIFIED
149 * Used if LUT1 index is not specified
150 * In the case, the PASS will use the first available entry
151 */
152 #define pa_LUT1_INDEX_NOT_SPECIFIED -1
154 /**
155 * @def pa_MAX_NUM_LUT1_ENTRIES
156 * The maximum number of LUT1 entries
157 *
158 */
159 #define pa_MAX_NUM_LUT1_ENTRIES 64
161 /**
162 * @defgroup ReturnValues Function Return Values
163 * @ingroup palld_api_constants
164 * @{
165 *
166 * @name PALLD Function Return Codes
167 *
168 * Error codes returned by PALLD API functions.
169 */
170 /*@{*/
171 /**
172 * @def pa_OK
173 * PA return code -- Function executed successfully
174 */
175 #define pa_OK 0
177 /**
178 * @def pa_ERR_CONFIG
179 * Invalid configuration provided to PA
180 */
181 #define pa_ERR_CONFIG -10
183 /**
184 * @def pa_INSUFFICIENT_CMD_BUFFER_SIZE
185 * The provided buffer was too small to hold the command
186 */
187 #define pa_INSUFFICIENT_CMD_BUFFER_SIZE -11
189 /**
190 * @def pa_INVALID_CMD_REPLY_DEST
191 * An invalid destination was provided for command replies
192 */
193 #define pa_INVALID_CMD_REPLY_DEST -12
195 /**
196 * @def pa_DUP_ENTRY
197 * A duplicate active entry was found in the L2/L3 table.
198 * If the module user intends to replace the associate routing
199 * information for the same entry, command packet should be
200 * delivered to the PASS via the PKTDMA sub-system
201 * Otherwise, module user may decide to drop the command packet and
202 * free the buffer.
203 */
204 #define pa_DUP_ENTRY -13
206 /**
207 * @def pa_INVALID_DUP_ENTRY
208 * A duplicate pending entry was found in the handle table
209 * This entry can not be handled until the pending entry
210 * becomes active
211 */
212 #define pa_INVALID_DUP_ENTRY -14
215 /**
216 * @def pa_INVALID_TABLE_MORE_SPECIFIC_ENTRY_PRESENT
217 * A more specific entry was found in the handle table
218 */
219 #define pa_INVALID_TABLE_MORE_SPECIFIC_ENTRY_PRESENT -15
221 /**
222 * @def pa_INVALID_MPLS_LABEL
223 * An MPLS label exceeded 20 bits
224 */
225 #define pa_INVALID_MPLS_LABEL -16
227 /**
228 * @def pa_HANDLE_TABLE_FULL
229 * No room for an entry in the L2 table
230 */
231 #define pa_HANDLE_TABLE_FULL -17
233 /**
234 * @def pa_INVALID_INPUT_HANDLE
235 * Invalid handle provided
236 */
237 #define pa_INVALID_INPUT_HANDLE -18
239 /**
240 * @def pa_HANDLE_INACTIVE
241 * Operation requested on an inactive handle
242 */
243 #define pa_HANDLE_INACTIVE -19
245 /**
246 * @def pa_INVALID_IP_FLOW
247 * A flow label exceeded 20 bits
248 */
249 #define pa_INVALID_IP_FLOW -20
251 /**
252 * @def pa_WARN_ACTIVE_HANDLE_ACKED
253 * Sub-system reported activation of a handle already marked active
254 */
255 #define pa_WARN_ACTIVE_HANDLE_ACKED -21
257 /**
258 * @def pa_LUT_ENTRY_FAILED
259 * Sub-system could not make an entry to the LUT1 table
260 */
261 #define pa_LUT_ENTRY_FAILED -22
264 /**
265 * @def pa_RESUBMIT_COMMAND
266 * Sub-system could not handle the command due to memory. Command must be resubmitted
267 */
268 #define pa_RESUBMIT_COMMAND -23
270 /**
271 * @def pa_SYSTEM_STATE_INVALID
272 * Tried to download an image to a running PDSP
273 */
274 #define pa_SYSTEM_STATE_INVALID -24
276 /**
277 * @def pa_INVALID_LUT1_INDEX
278 * LUT1 index exceeds the LUT1 table range
279 */
280 #define pa_INVALID_LUT1_INDEX -25
282 /**
283 * @def pa_WARN_LNK_CNT_UNSYNC
284 * Warning: Link counter out of sync
285 */
286 #define pa_WARN_LNK_CNT_UNSYNC -26
288 /**
289 * @def pa_CMDSET_TOO_BIG
290 * The total length of commads in the command set exceeds the limit
291 */
292 #define pa_CMDSET_TOO_BIG -27
294 /**
295 * @def pa_INVALID_LUT_INST
296 * The specified LUT1 or LUT2 instance does not exist
297 */
298 #define pa_INVALID_LUT_INST -28
301 /**
302 * @def pa_RESOURCE_INIT_DENIED
303 * The resource initialization permission denied
304 */
305 #define pa_RESOURCE_INIT_DENIED -29
307 /**
308 * @def pa_RESOURCE_USE_DENIED
309 * The resource usage permission denied
310 */
311 #define pa_RESOURCE_USE_DENIED -30
314 /**
315 * @def pa_RESOURCE_FREE_DENIED
316 * The resource free permission denied
317 */
318 #define pa_RESOURCE_FREE_DENIED -31
320 /**
321 * @def pa_FIRMWARE_REVISION_DIFFERENCE
322 * The firmware revision difference
323 */
324 #define pa_FIRMWARE_REVISION_DIFFERENCE -32
326 /**
327 * @def pa_VIRTUAL_LINK_TABLE_FULL
328 * Virtual link table is full
329 */
330 #define pa_VIRTUAL_LINK_TABLE_FULL -33
332 /*@}*/
333 /** @} */
336 /**
337 * @defgroup cmdMinBufSize Command buffer minimum size requirements
338 * @ingroup palld_api_constants
339 * @{
340 *
341 * @name Command buffer minimum sizes
342 *
343 * Define command buffer minimum size requirements.
344 */
345 /* @{ */
347 /**
348 * @def pa_ADD_LUT1_MIN_CMD_BUF_SIZE_BYTES
349 * The minimum command buffer size required when using the @ref Pa_addSrio and @ref Pa_addCustomLUT1 function
350 */
351 #define pa_ADD_LUT1_MIN_CMD_BUF_SIZE_BYTES 120
353 /**
354 * @def pa_ADD_MAC_MIN_CMD_BUF_SIZE_BYTES
355 * The minimum command buffer size required when using the @ref Pa_addMac and @ref Pa_addMac2 function
356 */
357 #define pa_ADD_MAC_MIN_CMD_BUF_SIZE_BYTES pa_ADD_LUT1_MIN_CMD_BUF_SIZE_BYTES
359 /**
360 * @def pa_DEL_HANDLE_MIN_CMD_BUF_SIZE_BYTES
361 * The minimum command buffer size required when using the @ref Pa_delHandle function
362 */
363 #define pa_DEL_HANDLE_MIN_CMD_BUF_SIZE_BYTES 20
365 /**
366 * @def pa_DEL_L4_HANDLE_MIN_CMD_BUF_SIZE_BYTES
367 * The minimum command buffer size required when using the @ref Pa_delL4Handle function
368 */
369 #define pa_DEL_L4_HANDLE_MIN_CMD_BUF_SIZE_BYTES 24
371 /**
372 * @def pa_ADD_IP_MIN_CMD_BUF_SIZE_BYTES
373 * The minimum command buffer size required when using the @ref Pa_addIp and @ref Pa_addIp2 functions
374 */
375 #define pa_ADD_IP_MIN_CMD_BUF_SIZE_BYTES pa_ADD_LUT1_MIN_CMD_BUF_SIZE_BYTES
377 /**
378 * @def pa_ADD_LUT2_MIN_CMD_BUF_SIZE_BYTES
379 * The minimum command buffer size required when using the @ref Pa_addCustomLUT2 function
380 */
381 #define pa_ADD_LUT2_MIN_CMD_BUF_SIZE_BYTES 44
383 /**
384 * @def pa_ADD_PORT_MIN_CMD_BUF_SIZE_BYTES
385 * The minimum command buffer size required when using the @ref Pa_addPort function
386 */
387 #define pa_ADD_PORT_MIN_CMD_BUF_SIZE_BYTES pa_ADD_LUT2_MIN_CMD_BUF_SIZE_BYTES
389 /**
390 * @def pa_CONFIG_EXCEPTION_ROUTE_MIN_CMD_BUF_SIZE_BYTES
391 * The minimum command buffer size required when using the @ref Pa_configExceptionRoute function
392 */
393 #define pa_CONFIG_EXCEPTION_ROUTE_MIN_CMD_BUF_SIZE_BYTES 520
395 /**
396 * @def pa_CONFIG_CRC_ENGINE_MIN_CMD_BUF_SIZE_BYTES
397 * The minimum command buffer size required when using the @ref Pa_configCrcEngine function
398 */
399 #define pa_CONFIG_CRC_ENGINE_MIN_CMD_BUF_SIZE_BYTES 88
401 /**
402 * @def pa_CONFIG_MULTI_ROUTE_MIN_CMD_BUF_SIZE_BYTES
403 * The minimum command buffer size required when using the @ref Pa_configMultiRoute function
404 */
405 #define pa_CONFIG_MULTI_ROUTE_MIN_CMD_BUF_SIZE_BYTES 84
407 /**
408 * @def pa_SET_CUSTOM_LUT1_MIN_CMD_BUF_SIZE_BYTES
409 * The minimum command buffer size required when using the @ref Pa_setCustomLUT1 function
410 */
411 #define pa_SET_CUSTOM_LUT1_MIN_CMD_BUF_SIZE_BYTES 60
413 /**
414 * @def pa_SET_CUSTOM_LUT2_MIN_CMD_BUF_SIZE_BYTES
415 * The minimum command buffer size required when using the @ref Pa_setCustomLUT2 function
416 */
417 #define pa_SET_CUSTOM_LUT2_MIN_CMD_BUF_SIZE_BYTES 36
419 /**
420 * @def pa_CONFIG_CMD_SET_MIN_CMD_BUF_SIZE_BYTES
421 * The minmium command buffer size allowed when using the @ref Pa_configCmdSet and @ref Pa_formatTxCmd function
422 */
423 #define pa_CONFIG_CMD_SET_MIN_CMD_BUF_SIZE_BYTES 144
425 /**
426 * @def pa_REQUEST_STATS_MIN_CMD_BUF_SIZE_BYTES
427 * The minimum command buffer size required when using the @ref Pa_requestStats and @ref Pa_requestUsrStats functions
428 */
429 #define pa_REQUEST_STATS_MIN_CMD_BUF_SIZE_BYTES 24
431 /**
432 * @def pa_CONFIG_USR_STATS_MIN_CMD_BUF_SIZE_BYTES
433 * The minmium command buffer size allowed when using the @ref Pa_configUsrStats function with the maximum number of
434 * user-defined statistics. The size of command packet is calculated as 20 + (number of statistic entries) * 4.
435 */
436 #define pa_CONFIG_USR_STATS_MIN_CMD_BUF_SIZE_BYTES 2068
438 /**
439 * @def pa_GLOBAL_CONFIG_MIN_CMD_BUF_SIZE_BYTES
440 * The minmium command buffer size allowed when using the @ref Pa_control (pa_CONTROL_SYS_CONFIG) function to perform PASS
441 * global configuration.
442 */
443 #define pa_GLOBAL_CONFIG_MIN_CMD_BUF_SIZE_BYTES 56
445 /**
446 * @def pa_802_1ag_DET_MIN_CMD_BUF_SIZE_BYTES
447 * The minmium command buffer size allowed when using the @ref Pa_control (pa_CONTROL_802_1ag_CONFIG) function to configure
448 * the 802.1ag packet detector.
449 */
450 #define pa_802_1ag_DET_MIN_CMD_BUF_SIZE_BYTES 24
452 /**
453 * @def pa_IPSEC_NAT_T_DET_MIN_CMD_BUF_SIZE_BYTES
454 * The minmium command buffer size allowed when using the @ref Pa_control (pa_CONTROL_IPSEC_NAT_T_CONFIG) function to configure
455 * the IPSEC NAT-T packet detector.
456 */
457 #define pa_IPSEC_NAT_T_DET_MIN_CMD_BUF_SIZE_BYTES 24
459 /**
460 * @def pa_GTPU_CONFIG_MIN_CMD_BUF_SIZE_BYTES
461 * The minmium command buffer size allowed when using the @ref Pa_control (pa_CONTROL_GTPU_CONFIG) function to configure
462 * the GTUP classification operation.
463 */
464 #define pa_GTPU_CONFIG_MIN_CMD_BUF_SIZE_BYTES 24
466 /**
467 * @def pa_MAX_CMD_BUF_SIZE_BYTES
468 * The maximum command buffer size requested when using any PA API call which generates command packet.
469 */
470 #define pa_MAX_CMD_BUF_SIZE_BYTES 2068
472 /* @} */
473 /** @} */
476 /**
477 * @ingroup palld_api_structures
478 * @brief MAC address specification
479 *
480 * @details This type is used to pass MAC addresses (see @ref netlayers) to the module. The most significant byte
481 * of the mac address is placed in array element 0.
482 */
483 #define pa_MAC_ADDR_SIZE 6
484 typedef unsigned char paMacAddr_t[pa_MAC_ADDR_SIZE];
486 /**
487 * @ingroup palld_api_structures
488 * @brief IPv4 address specification
489 *
490 * @details This type is used to pass IPv4 addresses (see @ref netlayers) to the module. The most significant byte
491 * of the IP address is placed in array element 0.
492 */
493 #define pa_IPV4_ADDR_SIZE 4
494 typedef unsigned char paIpv4Addr_t[pa_IPV4_ADDR_SIZE];
496 /**
497 * @ingroup palld_api_structures
498 * @brief IPv6 address specificiation
499 *
500 * @details This type is used to pass IPv6 addresses (see @ref netlayers) to the module. The most significant byte
501 * of the IP address is placed in array element 0.
502 */
503 #define pa_IPV6_ADDR_SIZE 16
504 typedef unsigned char paIpv6Addr_t[pa_IPV6_ADDR_SIZE];
506 /**
507 * @ingroup palld_api_structures
508 * @brief IP address specification
509 *
510 * @details This union is used to specify an IP address to the module. The type in the union is determined
511 * through other parameters passed to the module (see @ref IpValues).
512 */
513 typedef union {
515 paIpv6Addr_t ipv6; /**< IPv6 address */
516 paIpv4Addr_t ipv4; /**< IPv4 address */
518 } paIpAddr_t;
520 /**
521 * @defgroup IpValues IP types
522 * @ingroup palld_api_constants
523 * @{
524 *
525 * @name IP Values
526 * @brief Defines the IP version type used.
527 *
528 * @details The packet accelerator module parses both IPv4 and IPv6 network layer headers (see @ref netlayers).
529 * This group is used to distinguish which type of header will be used.
530 */
531 /* @{ */
532 /**
533 * @def pa_IPV4
534 * IPv4
535 */
536 #define pa_IPV4 4
538 /**
539 * @def pa_IPV6
540 * IPv6
541 */
542 #define pa_IPV6 6
544 /* @} */
545 /** @} */
548 /**
549 * @ingroup palld_api_structures
550 * @brief Specification of Pa_Handle
551 *
552 * The Pa_Handle is used to identify a PA LLD instance
553 */
554 typedef void* Pa_Handle;
556 /**
557 * @ingroup palld_api_structures
558 * @brief PA handle specification for L2 and L3 (LUT1) handles
559 *
560 * @details This type is used to reference L2 and L3 (LUT1) routing information (see @ref netlayers). The module
561 * user is responsible for storing the handle and using it to refer to routing information already
562 * created through calls to @ref Pa_addMac, @ref Pa_addSrio, @ref Pa_addCustomLUT1 and @ref Pa_addIp.
563 */
564 typedef void* paHandleL2L3_t;
566 /**
567 * @ingroup palld_api_structures
568 * @brief PA link handle specification for L2, L3 (LUT1) and virtual link handles
569 *
570 * @details This type is used to reference L2, L3 (LUT1) and virtual link information. The module
571 * user is responsible for storing the handle and using it to refer to L2/L3/Virtual link handle already
572 * created through calls to @ref Pa_addMac, @ref Pa_addSrio, @ref Pa_addCustomLUT1, @ref Pa_addIp and
573 * @ref Pa_addVirtualLink
574 */
575 typedef void* paLnkHandle_t;
577 /**
578 * @brief The un-linked inner IP handle
579 *
580 * @details This handle value is used to specify an inner IP (tunnel) which the application does not
581 * want to link to an outer IP address.
582 */
583 #define PA_LLD_HANDLE_IP_INNER ((paHandleL2L3_t)1)
585 /**
586 * @ingroup palld_api_structures
587 * @brief PA handle specification for L4 (LUT2) handles
588 *
589 * @details This type is used to reference L4 (LUT2) routing information (see @ref netlayers). The module user
590 * is responsible for storing the handle. It is used again only to delete a created route.
591 *
592 */
593 typedef uint32_t paHandleL4_t[2];
596 /**
597 * @ingroup palld_api_structures
598 * @brief A generic entry handle types
599 *
600 * @details The union of both entry handle types used by the module is used only in function @ref Pa_forwardResult.
601 * The function will return the corresponding entry type and its handle in the command response packets when a LUT1
602 * or LUT2 entry is added into the LUT1/LUT2 table successfully.
603 * The handle entry will be set to zero in all other cases
604 */
605 typedef union {
607 paHandleL2L3_t l2l3Handle; /**< Level 2 or level 3 handle created by @ref Pa_addMac @ref Pa_addSrio, @ref Pa_addCustomLUT1 or @ref Pa_addIp */
608 paHandleL4_t l4Handle; /**< Level 4 handle created by @ref Pa_addPort or @ref Pa_addCustomLUT2 */
610 } paEntryHandle_t;
612 /**
613 * @ingroup salld_api_constants
614 * @{
615 * @brief The number of bytes available for custom lookup
616 *
617 * @details Custom lookup sizes are fixed by hardware
618 */
619 #define pa_NUM_BYTES_CUSTOM_LUT1 32
620 #define pa_NUM_BYTES_CUSTOM_LUT2 4
621 /** @} */
623 /**
624 * @defgroup HandleTypes Handle Types
625 *
626 * @ingroup palld_api_constants
627 * @{
628 *
629 * @name Handle Types
630 *
631 * @brief These values are used to describe what type of handle is referenced.
632 *
633 * @details These values are used only for function @ref Pa_forwardResult. The function returns with a copy
634 * of the handle, which the module user should already have, along with the type of handle. The
635 * module user can use this information to verify that a particular handle has been fully activated
636 * and can be used for linking reference in calls to @ref Pa_addIp, @ref Pa_addCustomLUT1,
637 * @ref Pa_addCustomLUT2 or @ref Pa_addPort.
638 */
639 /* @{ */
640 /**
641 *
642 * @def pa_L2_HANDLE
643 * Level 2 (MAC/SRIO) handle
644 */
645 #define pa_L2_HANDLE 2
647 /**
648 * @def pa_L3_HANDLE
649 * Level 3 (IP, Custom LUT1) handle
650 */
651 #define pa_L3_HANDLE 3
653 /**
654 * @def pa_L4_HANDLE
655 * Level 4 (TCP/UDP/GTP-U/Custom LUT2) handle
656 */
657 #define pa_L4_HANDLE 4
659 /**
660 * @def pa_INVALID_HANDLE
661 * Invalid handle type
662 */
663 #define pa_INVALID_HANDLE -1
665 /* @} */
666 /** @} */
669 /**
670 * @defgroup ErouteTypes Exception Route Types
671 * @ingroup palld_api_constants
672 * @{
673 *
674 * @name Exception Route Types
675 *
676 * @brief These values are used to define exception route conditions.
677 *
678 * @details The exception route defines the global routing information when the exception condition such
679 * as LUT1 lookup failure, packet parsing failure, broadcast packet detection and etc. Multiple
680 * exception routes can be configured through @ref Pa_configExceptionRoute. All the exception
681 * routes are disabled by default.
682 */
683 /* @{ */
684 /**
685 *
686 * @def pa_EROUTE_L2L3_FAIL
687 * packet failed to match in L2/L3 (LUT1) table
688 */
689 #define pa_EROUTE_L2L3_FAIL 0
691 /**
692 * @def pa_EROUTE_VLAN_MAX_DEPTH
693 * packet exceeded maximum number of VLAN tags
694 */
695 #define pa_EROUTE_VLAN_MAX_DEPTH 1
697 /**
698 * @def pa_EROUTE_IP_MAX_DEPTH
699 * packet exceeded maximum number of IP headers
700 */
701 #define pa_EROUTE_IP_MAX_DEPTH 2
703 /**
704 * @def pa_EROUTE_MPLS_MAX_DEPTH
705 * packet exceeded maximum number of MPLS headers
706 */
707 #define pa_EROUTE_MPLS_MAX_DEPTH 3
709 /**
710 * @def pa_EROUTE_GRE_MAX_DEPTH
711 * packet exceeded maximum number of GRE headers
712 */
713 #define pa_EROUTE_GRE_MAX_DEPTH 4
715 /**
716 * @def pa_EROUTE_PARSE_FAIL
717 * packet failed to parse
718 */
719 #define pa_EROUTE_PARSE_FAIL 5
721 /**
722 * @def pa_EROUTE_L4_FAIL
723 * packet failed to match in L4 (LUT2) table
724 */
725 #define pa_EROUTE_L4_FAIL 6
727 /**
728 * @def pa_EROUTE_IP_FRAG
729 * IP fragmented packet
730 */
731 #define pa_EROUTE_IP_FRAG 7
733 /**
734 * @def pa_EROUTE_IPV6_OPT_FAIL
735 * Packet failed due to unsupported IPV6 option header
736 */
737 #define pa_EROUTE_IPV6_OPT_FAIL 8
739 /**
740 * @def pa_EROUTE_UDP_LITE_FAIL
741 * UDP lite packet had invalid checksum coverage
742 */
743 #define pa_EROUTE_UDP_LITE_FAIL 9
745 /**
746 * @def pa_EROUTE_ROUTE_OPTION
747 * IP routing had incomplete routes
748 */
749 #define pa_EROUTE_ROUTE_OPTION 10
751 /**
752 * @def pa_EROUTE_SYSTEM_FAIL
753 * Sub-system detected internal error
754 */
755 #define pa_EROUTE_SYSTEM_FAIL 11
757 /**
758 * @def pa_EROUTE_MAC_BROADCAST
759 * MAC broadcast packet which is not specified at the lookup table
760 */
761 #define pa_EROUTE_MAC_BROADCAST 12
763 /**
764 * @def pa_EROUTE_MAC_MULTICAST
765 * MAC multicast packet which is not specified at the lookup table
766 */
767 #define pa_EROUTE_MAC_MULTICAST 13
769 /**
770 * @def pa_EROUTE_IP_BROADCAST
771 * IP broadcast packet which is not specified at the lookup table
772 */
773 #define pa_EROUTE_IP_BROADCAST 14
775 /**
776 * @def pa_EROUTE_IP_MULTICAST
777 * IP multicast packet which is not specified at the lookup table
778 */
779 #define pa_EROUTE_IP_MULTICAST 15
781 /**
782 * @def pa_EROUTE_GTPU_MESSAGE_TYPE_1
783 * GTP-U PING Request packet
784 */
785 #define pa_EROUTE_GTPU_MESSAGE_TYPE_1 16
787 /**
788 * @def pa_EROUTE_GTPU_MESSAGE_TYPE_2
789 * GTP-U PING Response packet
790 */
791 #define pa_EROUTE_GTPU_MESSAGE_TYPE_2 17
793 /**
794 * @def pa_EROUTE_GTPU_MESSAGE_TYPE_26
795 * GTP-U Error Indication packet
796 */
797 #define pa_EROUTE_GTPU_MESSAGE_TYPE_26 18
799 /**
800 * @def pa_EROUTE_GTPU_MESSAGE_TYPE_31
801 * GTP-U Supported Header Notification packet
802 */
803 #define pa_EROUTE_GTPU_MESSAGE_TYPE_31 19
805 /**
806 * @def pa_EROUTE_GTPU_MESSAGE_TYPE_254
807 * GTP-U End Markr packet
808 */
809 #define pa_EROUTE_GTPU_MESSAGE_TYPE_254 20
811 /**
812 * @def pa_EROUTE_GTPU_FAIL
813 * Packet failed due to GTPU parsing error or unsupporte dmessage types
814 */
815 #define pa_EROUTE_GTPU_FAIL 21
817 /**
818 * @def pa_EROUTE_PPPoE_FAIL
819 * Packet failed due to PPPoE session packet parsing error
820 */
821 #define pa_EROUTE_PPPoE_FAIL 22
823 /**
824 * @def pa_EROUTE_PPPoE_CTRL
825 * PPPoE session stage non-IP packets
826 */
827 #define pa_EROUTE_PPPoE_CTRL 23
829 /**
830 * @def pa_EROUTE_802_1ag
831 * 802.1ag Packet
832 */
833 #define pa_EROUTE_802_1ag 24
835 /**
836 * @def pa_EROUTE_IP_FAIL
837 * Packet failed due to invalid IP header
838 */
839 #define pa_EROUTE_IP_FAIL 25
841 /**
842 * @def pa_EROUTE_NAT_T_KEEPALIVE
843 * NAT-T Keep Alive packet where UDP Length = 9, data = 0xFF
844 */
845 #define pa_EROUTE_NAT_T_KEEPALIVE 26
847 /**
848 * @def pa_EROUTE_NAT_T_CTRL
849 * NAT-T control packet where UDP Length > 12 and the first 4 payload bytes are equal to 0
850 */
851 #define pa_EROUTE_NAT_T_CTRL 27
853 /**
854 * @def pa_EROUTE_NAT_T_DATA
855 * NAT-T IPSEC ESP data packet where UDP Length > 12 and the first 4 payload bytes are not equal to 0
856 */
857 #define pa_EROUTE_NAT_T_DATA 28
859 /**
860 * @def pa_EROUTE_NAT_T_FAIL
861 * Invalid NAT-T packet
862 */
863 #define pa_EROUTE_NAT_T_FAIL 29
865 /**
866 * @def pa_EROUTE_GTPU_MATCH_FAIL
867 * GTPU match failed
868 */
869 #define pa_EROUTE_GTPU_MATCH_FAIL 30
871 /**
872 * @def pa_EROUTE_MAX
873 * The maximum number of global route types
874 */
875 #define pa_EROUTE_MAX 31
877 /* @} */
878 /** @} */
881 /**
882 * @defgroup NextHeaderTypes Next Header types
883 * @ingroup palld_api_constants
884 * @{
885 *
886 * @name Next Header types
887 *
888 * @brief These values are used to define the next header (protocol) types for continus parsing after the
889 * SRIO and custom parsing.
890 *
891 * @details The next header type can be derived from the upper layer header in a standard Ethernet packet.
892 * For SRIO and custom LUT1 lookup, the next header type should be provided by the user in function
893 * @ref Pa_setCustomLUT1 and @ref Pa_addSrio.
894 */
895 /* @{ */
896 /**
897 *
898 * @def pa_HDR_TYPE_MAC
899 * MAC header
900 */
901 #define pa_HDR_TYPE_MAC 0
903 /**
904 *
905 * @def pa_HDR_TYPE_IPV4
906 * IPv4 header
907 */
908 #define pa_HDR_TYPE_IPV4 1
911 /**
912 *
913 * @def pa_HDR_TYPE_IPV6
914 * IPv6 header
915 */
916 #define pa_HDR_TYPE_IPV6 2
918 /**
919 *
920 * @def pa_HDR_TYPE_CUSTOM_LUT1
921 * Custom LUT1 header
922 */
923 #define pa_HDR_TYPE_CUSTOM_LUT1 3
925 /**
926 *
927 * @def pa_HDR_TYPE_UDP
928 * UDP header
929 */
930 #define pa_HDR_TYPE_UDP 4
932 /**
933 *
934 * @def pa_HDR_TYPE_UDP_LITE
935 */
936 #define pa_HDR_TYPE_UDP_LITE 5
938 /**
939 *
940 * @def pa_HDR_TYPE_TCP
941 * TCP header
942 */
943 #define pa_HDR_TYPE_TCP 6
945 /**
946 *
947 * @def pa_HDR_TYPE_CUSTOM_LUT2
948 * Custom LUT2 header
949 */
950 #define pa_HDR_TYPE_CUSTOM_LUT2 7
952 /**
953 *
954 * @def pa_HDR_TYPE_UNKNOWN
955 * next header type is not specified
956 */
957 #define pa_HDR_TYPE_UNKNOWN 8
959 /* @} */
960 /** @} */
962 /**
963 * @ingroup palld_api_structures
964 * @brief pa RM Handle
965 */
966 typedef void * pa_RmHnd;
968 /**
969 * @ingroup palld_api_structures
970 * @brief PA start configuration structure
971 */
972 typedef struct
973 {
974 pa_RmHnd rmServiceHandle; /**< Resource Manager service handle */
975 uint32_t baseAddr; /**< Specify the PASS base address */
976 void* instPoolBaseAddr; /**< Base address of the global shared memory pool from which global
977 LLD instance & channel instance memory is allocated */
978 } paStartCfg_t;
980 /**
981 * @ingroup palld_api_structures
982 * @brief Pointer to the buffer where the PASS command is placed
983 *
984 * @details Functions in this module produce formatted commands that must be sent to the packet accelerator
985 * sub-system. These commands are always referred to through this type.
986 */
987 typedef void* paCmd_t;
990 /**
991 * @ingroup palld_api_structures
992 * @brief PA Size Configuration Structure
993 *
994 * @details The module is configured at run time with a maximum number of handles supported. The module
995 * maintains a set of handles and links between handles.
996 */
997 typedef struct {
999 int nMaxL2; /**< Maximum number of L2 handles supported */
1000 int nMaxL3; /**< Maximum number of L3 handles supported */
1001 int nUsrStats;/**< Maximum number of user-defined statistics supported (maximum: 512)*/
1002 int nVlnkMax; /**< Maximum number of virtual links supported */
1003 } paSizeInfo_t;
1005 /**
1006 * @ingroup palld_api_structures
1007 * @brief PA Initialization config structure
1008 *
1009 * @details The parameters in this structure are used to do initial setup
1010 * of the driver including its base address and other default settings.
1011 *
1012 * @note The stream interface switch controls the destination of the traffic
1013 * from the Ethernet switch. The default setting of the streaming
1014 * interface switch is to route all traffic to the host. However,
1015 * this module is designed to receive the incoming packets at the PDSP0.
1016 * If the initDeafultRoute is set to TRUE, this module will re-configure
1017 * the stream interface switch to route all traffic to PDSP0. Otherwise,
1018 * it is the module user's reponsibility to deliver incoming packets
1019 * to PDSP0 via the CPPI/QMSS interface.
1020 */
1021 typedef struct {
1022 uint16_t initTable; /**< If True then the L2/L3 tables are initialized */
1023 uint16_t initDefaultRoute; /**< If True then the switch default route is set to PASS PDSP0 */
1024 uint32_t baseAddr; /**< Specify the PASS base address */
1025 void* instPoolBaseAddr; /**< Base address of the global shared memory pool from which global
1026 LLD instance & channel instance memory is allocated */
1027 pa_RmHnd rmServiceHandle; /**< Resource Manager service handle */
1028 paSizeInfo_t* sizeCfg; /**< Pointer to the size configuration information */
1029 } paConfig_t;
1031 /**
1032 * @ingroup salld_api_constants
1033 * @{
1034 * @brief Protocol Limit related constant definitions
1035 */
1036 #define pa_PROTOCOL_LIMIT_NUM_VLANS_DEF 2 /**< Number of VLAN supported: default value */
1037 #define pa_PROTOCOL_LIMIT_NUM_IP_DEF 2 /**< Number of IP layers supported: default value */
1038 #define pa_PROTOCOL_LIMIT_NUM_GRE_DEF 2 /**< Number of GRE layers supported: default value */
1039 #define pa_PROTOCOL_LIMIT_NUM_VLANS_MAX 3 /**< Number of VLAN supported: maximum value */
1040 #define pa_PROTOCOL_LIMIT_NUM_IP_MAX 7 /**< Number of IP layers supported: maximum value */
1041 #define pa_PROTOCOL_LIMIT_NUM_GRE_MAX 7 /**< Number of GRE layers supported: maximum value */
1043 /** @} */
1045 /**
1046 * @ingroup palld_api_structures
1047 * @brief Protocol-specific Limitations.
1048 *
1049 * @details paProtocolLimit_t is used to defines the protocol-specific restrictions. For example,
1050 * it is necessary to limit the number of protocol layers such as GRE of the input packets
1051 * to prevent the irregular packets take too much processing time.
1052 * The PASS will detect the packets which violate the protocol-specific restrictions and either discard
1053 * or forward the packets to host queues which can be specified through API @ref Pa_configExceptionRoute.
1054 *
1055 * @note The PASS will work when non-default values are used. However, it may limit the supported packet rate
1056 * below wire rate.
1057 */
1058 typedef struct {
1060 uint8_t vlanMax; /**< Maximum number of VLANs supported, default = 2, maximum = 3 */
1061 uint8_t ipMax; /**< Maximum number of IP layers supported, default = 2, maximum = 7 */
1062 uint8_t greMax; /**< Maximum number of GRE layers supported, default = 2, maximum = 7 */
1064 } paProtocolLimit_t;
1066 /**
1067 * @ingroup palld_api_structures
1068 * @brief IP Reassembly Configuration Information.
1069 *
1070 * @details paIpReassmConfig_t is used to configure the PA-assisted IP reassembly operation. Two separate structures are used
1071 * for the outer IP and inner IP respectively. The IP reassembly assistance feature is disabled until
1072 * this information is provided. See section @ref appendix3 for deatiled description.
1073 * @note The maximum number of traffic flows is limited due to processing time and internal memory restriction.
1074 */
1075 typedef struct {
1077 uint8_t numTrafficFlow; /**< Maximum number of IP reassembly traffic flows supported, default = 0, maximum = 32 */
1078 uint8_t destFlowId; /**< CPPI flow which instructs how the link-buffer queues are used for forwarding packets */
1079 uint16_t destQueue; /**< Destination host queue where PASS will deliver the packets which require IP reassembly assistance */
1081 } paIpReassmConfig_t;
1083 /**
1084 * @ingroup palld_api_constants
1085 * @brief Define the maximum number of IP reassembly traffic flows
1086 *
1087 */
1088 #define pa_MAX_IP_REASM_TRAFFIC_FLOWS 32
1090 /**
1091 * @ingroup palld_api_structures
1092 * @brief Command Set Configuration Information.
1093 *
1094 * @details paCmdSetConfig_t defines command set configuration parameters such as the maximum number of command sets.
1095 * The PASS supports either 64 of 64-byte or 32 of 128-byte command sets. The number of command sets should
1096 * be configured at system startup.
1097 */
1098 typedef struct {
1100 uint8_t numCmdSets; /**< Number of command sets supported (32, 64), default = 64
1101 @note If the number of command sets is set to 64, then each command entry will be limited to 64 bytes.
1102 If the number of command sets is set to 32, then each command entry will be limited to 128 bytes */
1103 } paCmdSetConfig_t;
1105 /**
1106 * @ingroup palld_api_structures
1107 * @brief User-defined Statistics Configuration Information.
1108 *
1109 * @details paUsrStatsConfig_t defines the configuration parameters for multi-level hierarchical user-defined statistics
1110 * operation such as the number of user-defined counters. There are up to 512 user-defined statistics consisting of
1111 * some 64-bit counters and some 32-bit counters whereas the total size of all counters cannot exceed 2048 bytes.
1112 * The user-defined statistics feature is disabled until this configuration is invoked through API @ref Pa_control.
1113 *
1114 * - 64-bit Counters index: 0 - (num64bCounters - 1)
1115 * - 32-bit Counters index: num64bCounters - (numCounters - 1)
1116 */
1117 typedef struct {
1119 uint16_t numCounters; /**< Total number of user-defined counters, default = 0, maximum = 512 */
1120 uint16_t num64bCounters; /**< Number of 64-bit user-defined counters, default = 0, maximum = 256 */
1122 } paUsrStatsConfig_t;
1124 /**
1125 * @ingroup salld_api_constants
1126 * @brief Define the maximum number of user-defined statistics the module supports.
1127 *
1128 */
1129 #define pa_USR_STATS_MAX_COUNTERS 512
1131 /**
1132 * @ingroup salld_api_constants
1133 * @brief Define the maximum number of user-defined 64-bit statistics
1134 *
1135 */
1136 #define pa_USR_STATS_MAX_64B_COUNTERS (pa_USR_STATS_MAX_COUNTERS/2)
1137 /**
1138 * @ingroup salld_api_constants
1139 * @brief Define the maximum number of user-defined 32-bit statistics
1140 *
1141 */
1142 #define pa_USR_STATS_MAX_32B_COUNTERS pa_USR_STATS_MAX_COUNTERS
1144 /**
1145 * @defgroup paUsrStatsSizes PA User-defined Ststaistics Counter Sizes
1146 * @ingroup palld_api_constants
1147 * @{
1148 *
1149 * @name User-defined Ststaistics Counter Sizes
1150 *
1151 * Definition of Counter size of the User-defined Statistics
1152 */
1153 /** @ingroup paUsrStatsSizes */
1154 /*@{*/
1155 typedef enum {
1156 pa_USR_STATS_SIZE_32B = 0, /**< 32-bit Counter */
1157 pa_USR_STATS_SIZE_64B /**< 64-bit Counter */
1158 } paUsrStatsSizes_e;
1159 /*@}*/
1160 /** @} */
1163 /**
1164 * @ingroup palld_api_structures
1165 * @brief Queue Diversion Configuration Information.
1166 *
1167 * @details The PASS supports optional queue diversion operation per LUT2 entry replacement.
1168 * paQueueDivertConfigl_t contains configuration information for the atomic queue diversion operation.
1169 * The queue diversion feature is disabled until this configuration is invoked through API @ref Pa_control.
1170 *
1171 */
1172 typedef struct {
1174 uint16_t destQueue; /**< Destination queue where PASS will deliver the LUT2 response packet which contains the
1175 queue diversion information */
1176 uint8_t destFlowId; /**< CPPI flow which instructs how the link-buffer queues are used for forwarding
1177 the LUT2 response packets */
1178 } paQueueDivertConfig_t;
1181 /**
1182 * @defgroup pktControlInfo PA Packet Control Bit Definitions
1183 * @ingroup palld_api_constants
1184 * @{
1185 *
1186 * @name PA Packet Control Bit Definitions
1187 *
1188 * Bitmap definition of the ctrlBitMap in @ref paPacketControlConfig_t.
1189 *
1190 */
1191 /*@{*/
1192 /**
1193 * @def pa_PKT_CTRL_HDR_VERIFY_PPPoE
1194 * Control Info -- Set: Perform enhanced error check of the PPPoE header
1195 * Clear: Perform basic error check of the PPPoE header
1196 */
1197 #define pa_PKT_CTRL_HDR_VERIFY_PPPoE 0x0001
1198 /**
1199 * @def pa_PKT_CTRL_HDR_VERIFY_IP
1200 * Control Info -- Set: Perform enhanced error check of the IP header
1201 * Clear: Perform basic error check of the IP header
1202 */
1203 #define pa_PKT_CTRL_HDR_VERIFY_IP 0x0002
1204 /**
1205 * @def pa_PKT_CTRL_MAC_PADDING_CHK
1206 * Control Info -- Set: Perform MAC (802.3) padding check
1207 * The packet with illegal padding will be dropped
1208 * Clear: Do not perform MAC (802.3) padding check
1209 */
1210 #define pa_PKT_CTRL_MAC_PADDING_CHK 0x0004
1211 /**
1212 * @def pa_PKT_CTRL_IP_FRAGS_TO_EROUTE
1213 * Control Info -- Set: Forward IP Fragments through the exception route regardless of the routing destination
1214 * Clear: Forward IP Fragments through the exception route only if the routing destination is set to SASS or CONTINUE_PARSE
1215 */
1216 #define pa_PKT_CTRL_IP_FRAGS_TO_EROUTE 0x0008
1217 /**
1218 * @def pa_PKT_CTRL_L3OFFSET_TO_INNER_IP
1219 * Control Info -- Set: L3offset of the packet information points to the inner IP header prior to payload
1220 * Clear: L3offset of the packet information points to the outer IP header (default)
1221 */
1222 #define pa_PKT_CTRL_L3OFFSET_TO_INNER_IP 0x0010
1224 /*@}*/
1225 /** @} */
1227 /**
1228 * @ingroup palld_api_structures
1229 * @brief Packet Control Configuration Information.
1230 *
1231 * @details This data structure defines miscellaneous packet control information for some non-default PASS operations.
1232 * For example, PASS always performs basic protocol header verification to ensure that it can continue parsing the
1233 * current and next protocol header. The PASS will perform enhanced error check of protocol headers specified
1234 * by this configuration. For example,
1235 * PPPoE header in session mode:
1236 * - Version = 1
1237 * - Type = 1
1238 * - Code = 0
1239 *
1240 * IPv4 header:
1241 * - Header length >= 20
1242 * - Total length > 20
1243 * - Source address is not broadcast
1244 * - Destination address is not 0
1245 * - TTL is not 0
1246 *
1247 * @note refer to the @ref ErouteTypes for the corresponding exception routes.
1248 */
1249 typedef struct {
1251 uint16_t ctrlBitMap; /**< Packet control bit as defined at @ref pktControlInfo */
1252 uint16_t rxPaddingErrStatsIndex; /**< Specify the user statistics index of Rx padding error counter */
1253 uint16_t txPaddingStatsIndex; /**< Specify the user statistics index of Tx MAC padding counter */
1255 } paPacketControlConfig_t;
1257 /**
1258 * @ingroup palld_api_structures
1259 * @brief PA System Configuration Information structure
1260 *
1261 * @details paSysConfig_t contains pointers to the system-level configuration structures defined above. The null pointer
1262 * indicates the configuration of the corresponding sub-group is not required.
1263 */
1264 typedef struct {
1265 paProtocolLimit_t* pProtoLimit; /**< Pointer to the protocol limit configuration structure */
1266 paIpReassmConfig_t* pOutIpReassmConfig; /**< Pointer to the outer IP Reassembly configuration structure */
1267 paIpReassmConfig_t* pInIpReassmConfig; /**< Pointer to the inner IP Reassembly configuration structure */
1268 paCmdSetConfig_t* pCmdSetConfig; /**< Pointer to the command set configuration structure */
1269 paUsrStatsConfig_t* pUsrStatsConfig; /**< Pointer to the user-defined statistics configuration structure */
1270 paQueueDivertConfig_t* pQueueDivertConfig; /**< Pointer to the queue-diversion configuration structure */
1271 paPacketControlConfig_t* pPktControl; /**< Pointer to the packet control configuration structure */
1273 } paSysConfig_t;
1276 /**
1277 * @defgroup pa802p1agDetectInfo PA 802.1ag Detector Control Bit Definitions
1278 * @ingroup palld_api_constants
1279 * @{
1280 *
1281 * @name PA 802.1ag Detector Control Bit Definitions
1282 *
1283 * Bitmap definition of the ctrlBitMap in @ref pa802p1agDetConfig_t.
1284 *
1285 */
1286 /*@{*/
1287 /**
1288 * @def pa_802_1ag_DETECT_ENABLE
1289 * Control Info -- Set: Enable 802.1ag Detector
1290 * Clear: Disable 802.1ag Detector
1291 */
1292 #define pa_802_1ag_DETECT_ENABLE 0x0001
1293 /**
1294 * @def pa_802_1ag_DETECT_STANDARD
1295 * Control Info -- Set: Perform 802.1ag packet detection per 802.1ag formal standard
1296 * Clear: Perform 802.1ag packet detection per 802.1ag draft
1297 */
1298 #define pa_802_1ag_DETECT_STANDARD 0x0002
1299 /*@}*/
1300 /** @} */
1302 /**
1303 * @ingroup palld_api_structures
1304 * @brief 802.1ag Detection Configuration Information.
1305 *
1306 * @details The 802.1ag packet can be recognized with ether type equal to 0x8902 normally. However, the PASS can be
1307 * configured to further qualify the IEEE 802.1ag packet per one of the following criteria:
1308 * - 802.1ag standard: Destion MAC address = 01-80-c2-00-00-3x, Ether type = 0x8902
1309 * - 802.1ag draft: Destion MAC address = 01-80-c2-xx-xx-xx, Ether type = 0x8902
1310 *
1311 * @note The 802.1ag detector is disabled by default.
1312 * @note refer to the @ref ErouteTypes for the corresponding exception routes.
1313 *
1314 */
1315 typedef struct {
1316 uint16_t ctrlBitMap; /**< 802.1ag Detector control info as defined at @ref pa802p1agDetectInfo */
1317 } pa802p1agDetConfig_t;
1320 /**
1321 * @defgroup ipsecNatTCtrlInfo PA IPSEC NAT-T Control Bit Definitions
1322 * @ingroup palld_api_constants
1323 * @{
1324 *
1325 * @name PA IPSEC NAT-T Control Bit Definitions
1326 *
1327 * Bitmap definition of the ctrlBitMap in @ref paIpsecNatTConfig_t.
1328 *
1329 */
1330 /*@{*/
1331 /**
1332 * @def pa_IPSEC_NAT_T_CTRL_ENABLE
1333 * Control Info -- Set: Enable IPSEC NAT-T packet detection
1334 * Clear: Disable IPSEC NAT-T packet detection
1335 */
1336 #define pa_IPSEC_NAT_T_CTRL_ENABLE 0x0001
1337 /*@}*/
1338 /** @} */
1340 /**
1341 * @ingroup palld_api_structures
1342 * @brief IPSEC NAT-T Packet Detection Configuration Information.
1343 *
1344 * @details paIpsecNatTConfig_t is used to configure the IPSEC NAT-T packet detector which is disabled
1345 * until this configuration is invoked through API @ref Pa_control.
1346 *
1347 * @note The IPSEC NAT-T packet detector is disabled by default.
1348 * @note refer to the @ref ErouteTypes for the corresponding exception routes.
1349 *
1350 */
1351 typedef struct {
1353 uint16_t ctrlBitMap; /**< IPSEC NAT-T control info as defined at @ref ipsecNatTCtrlInfo */
1354 uint16_t udpPort; /**< Specify the UDP port number which uniquely identifies the IPSEC NAT-T packets */
1355 } paIpsecNatTConfig_t;
1357 /**
1358 * @defgroup paGtpuCtrlInfo PA GTPU Control Bit Definitions
1359 * @ingroup palld_api_constants
1360 * @{
1361 *
1362 * @name PA GTPU Control Bit Definitions
1363 *
1364 * Bitmap definition of the ctrlBitMap in @ref paGtpuConfig_t.
1365 *
1366 */
1367 /*@{*/
1368 /**
1369 * @def pa_GTPU_CTRL_USE_LINK
1370 * Control Info -- Set: GTU-U classification vector consists of the least significant 24-bit of tunnel ID and 8-bit link
1371 * of previous matching
1372 * Clear: GTU-U classification vector consists of the 32-bit of tunnel ID only (Default)
1373 */
1374 #define pa_GTPU_CTRL_USE_LINK 0x0001
1375 /*@}*/
1376 /** @} */
1378 /**
1379 * @ingroup palld_api_structures
1380 * @brief GTP-U Configuration Information.
1381 *
1382 * @details Due to the LUT2 engine using 32-bit matching parameter, the default GTP-U classification is solely based
1383 * on its 32-bit tunnel ID. However, it is desirable to match the GTP-U tunnel with both tunnel ID and
1384 * previous link information. This configuration can be used to modify GTP-U classification vector by
1385 * combining least significant 24-bit of tunnel ID and an 8-bit previous link. It should be passed to
1386 * @ref Pa_control() API at system startup.
1387 *
1388 * @note GTP-U configuration should be performed at system startup. PASS does not support GTP-U
1389 * reconfiguration at run time.
1390 *
1391 */
1392 typedef struct {
1393 uint16_t ctrlBitMap; /**< GTP-U configuration control info as defined at @ref paGtpuCtrlInfo */
1394 } paGtpuConfig_t;
1397 /**
1398 * @defgroup paCtrlCode PA Control Code
1399 * @ingroup palld_api_constants
1400 * @{
1401 *
1402 * @name PA Control Code
1403 *
1404 * @brief Define the PA LLD control code
1405 *
1406 */
1407 /** @ingroup paCtrlCode */
1408 /* @{ */
1409 /**
1410 * @def pa_CONTROL_SYS_CONFIG
1411 * system-level configuration
1412 */
1413 #define pa_CONTROL_SYS_CONFIG 0
1415 /**
1416 * @def pa_CONTROL_802_1ag_CONFIG
1417 * 802.1ag Detector configuration
1418 */
1419 #define pa_CONTROL_802_1ag_CONFIG 1
1421 /**
1422 * @def pa_CONTROL_IPSEC_NAT_T_CONFIG
1423 * IPSEC NAT-T Packet Detector configuration
1424 */
1425 #define pa_CONTROL_IPSEC_NAT_T_CONFIG 2
1427 /**
1428 * @def pa_CONTROL_GTPU_CONFIG
1429 * GTP-U configuration
1430 */
1431 #define pa_CONTROL_GTPU_CONFIG 3
1433 /* @} */
1434 /** @} */
1437 /**
1438 * @ingroup palld_api_structures
1439 * @brief PA Control Information structure
1440 *
1441 * @details Data structure defines PA control information used by API @ref Pa_control.
1442 *
1443 */
1444 typedef struct {
1445 uint16_t code; /**< Specify the PA control code as defined at @ref paCtrlCode */
1446 union {
1447 paSysConfig_t sysCfg; /**< Specify system-level configuration parameters */
1448 pa802p1agDetConfig_t pa802p1agDetCfg; /**< Specify 802.1ag Detector configuration parameters */
1449 paIpsecNatTConfig_t ipsecNatTDetCfg; /**< Specify IPSEC NAT-T Detector configuration parameters */
1450 paGtpuConfig_t gtpuCfg; /**< Specify GTP-U configuration parameters */
1451 }params; /**< Contain the control operation specific parameters */
1453 } paCtrlInfo_t;
1455 /**
1456 * @ingroup palld_api_structures
1457 * @brief The return type for module functions
1458 *
1459 * @details Function calls to this module return values used to determine if the command was successful or
1460 * the reason for failure (see @ref ReturnValues).
1461 */
1463 typedef int paReturn_t;
1465 /**
1466 * @ingroup palld_api_structures
1467 * @brief paCmdReply_t is used to specify command result (from PASS) routing information
1468 *
1469 * @details Commands sent to packet accelerator sub-system will generate replies. These replies
1470 * can be either discarded by the sub-system or routed to a queue. Command replies that
1471 * must be forwarded back to this module are detailed for each command. The module user
1472 * typically either selects a unique destination queue for command replies, or else supplies
1473 * a unique value for replyId. This value is placed into software info word 0 in the
1474 * packet descriptor for the returned command. The data in the returned packet is not
1475 * typically examined by the module user, but passed directly back to this module through
1476 * API function @ref Pa_forwardResult to examine the results of the command.
1477 */
1478 typedef struct {
1480 int dest; /**< Packet destination, must be pa_DEST_HOST or pa_DEST_DISCARD, see @ref pktDest */
1481 uint32_t replyId; /**< Value placed in swinfo0 in reply packet */
1482 uint16_t queue; /**< Destination queue for destination pa_DEST_HOST */
1483 uint8_t flowId; /**< Flow ID used on command reply from PASS */
1485 } paCmdReply_t;
1487 /**
1488 * @ingroup palld_api_constants
1489 * @brief Define the maximum number of buffers the module can request
1490 *
1491 */
1492 #define pa_N_BUFS 5
1494 /**
1495 * @defgroup paBufIndex PA Memory Buffer Index
1496 * @ingroup palld_api_constants
1497 * @{
1498 *
1499 * @name PA Memory Buffer Index
1500 * @brief Define the buffer inedex of the PA LLD memory blocks.
1501 *
1502 */
1503 /* @{ */
1504 /**
1505 * @def pa_BUF_INST
1506 * PA LLD instance buffer
1507 */
1508 #define pa_BUF_INST 0
1509 /**
1510 * @def pa_BUF_L2_TABLE
1511 * PA LLD match table of Layer 2 (MAC/SRIO) entries
1512 */
1513 #define pa_BUF_L2_TABLE 1
1514 /**
1515 * @def pa_BUF_L3_TABLE
1516 * PA LLD match table of Layer 3 (IP/CustomLUT1) entries
1517 */
1518 #define pa_BUF_L3_TABLE 2
1519 /**
1520 * @def pa_BUF_USR_STATS_TABLE
1521 * PA LLD link table of user-defined statistics
1522 */
1523 #define pa_BUF_USR_STATS_TABLE 3
1524 /**
1525 * @def pa_BUF_VLINK_TABLE
1526 * PA LLD match table of virtual link entries
1527 */
1528 #define pa_BUF_VLINK_TABLE 4
1530 /* @} */
1531 /** @} */
1534 /**
1535 * @ingroup palld_api_functions
1536 * @brief Pa_getBufferReq returns the memory requirements for the PA driver
1537 *
1538 * @details This function returns the memory buffer requirements in term
1539 * of the size and alignment array. The PA LLD requires up to
1540 * four memory blocks as described below:
1541 * - PA Instance: PA instance data
1542 * - L2 Table: Layer-2 (MAC/SRIO) entry information
1543 * - L3 Table: Layer-3 (IP/Custom LUT1) entry information
1544 * - User Statistics Link Table: User-defined Statistics entry information (Optional)
1545 *
1546 * @param[in] sizeCfg Size configuration information
1547 * @param[out] sizes Array of size requirements
1548 * @param[out] aligns Array of alignment requirements
1549 * @retval Value (@ref ReturnValues)
1550 *
1551 * @note This function specifies the minimum memory buffer requirements, it is up to the
1552 * module user to round up the buffer alignemnt and size to the cache line boundary
1553 * to ensure cache coherency if cacheable memory is used.
1554 */
1555 paReturn_t Pa_getBufferReq (paSizeInfo_t *sizeCfg, int sizes[], int aligns[]);
1557 /**
1558 * @ingroup palld_api_functions
1559 * @brief Pa_create creates the PA driver instance
1560 *
1561 * @details This function initializes the PA driver based on user configuration
1562 *
1563 * @param[in] cfg Configuration information
1564 * @param[in] bases Array of the memory buffer base addresses
1565 * @param[out] pHandle Instance handle. This is a pointer to an initialized
1566 * instance structure.
1567 * @retval Value (@ref ReturnValues)
1568 */
1569 paReturn_t Pa_create (paConfig_t *cfg, void* bases[], Pa_Handle *pHandle);
1571 /**
1572 * @ingroup palld_api_functions
1573 * @brief Pa_startCfg Adds PA configuration
1574 * @details This function needs to be called from all cores to initialize PA with
1575 * per core configurations
1576 *
1577 * @param[in] handle The PA LLD instance identifier
1578 * @param[in] startCfg PA start configuration
1579 * @retval None
1580 */
1581 void Pa_startCfg (Pa_Handle handle, paStartCfg_t *startCfg);
1583 /**
1584 * @ingroup palld_api_functions
1585 * @brief Pa_close decativates the PA driver instance
1586 *
1587 * @details This function deactivates the PA driver instance, all the associated
1588 * memory buffers can be freed after this call.
1589 *
1590 * @param[in] handle The PA LLD instance identifier
1591 * @param[out] bases Array of the memory buffer base addresses
1592 * @retval Value (@ref ReturnValues)
1593 */
1594 paReturn_t Pa_close (Pa_Handle handle, void* bases[]);
1596 /**
1597 * @ingroup palld_api_functions
1598 * @brief Pa_control performs system-level control and configuration
1599 *
1600 * @details This function performs PASS control operations including system-level figurations.
1601 * The system-level configurations are divided into several sub-groups which can be configured
1602 * independently. The default configuration will be used until this API is invoked.
1603 *
1604 * On return the command buffer (cmd) contains a formatted command for the sub-system when the cmdSize
1605 * is set to non-zero. The destination for the command is provided in cmdDest. The module user must send
1606 * the formatted command to the sub-system. The sub-system will generate a reply
1607 * and this reply must be sent back to this module through the @ref Pa_forwardResult API.
1608 *
1609 *
1610 * @param[in] handle The PA LLD instance identifier
1611 * @param[in] ctrl Control information
1612 * @param[out] cmd Where the created command is placed
1613 * @param[in,out] cmdSize Input the size of cmd buffer, on output the actual size used. @ref cmdMinBufSize
1614 * @param[in] reply Where the sub-system sends the command reply
1615 * @param[out] cmdDest Value (@ref cmdTxDest)
1616 * @retval Value (@ref ReturnValues)
1617 */
1618 paReturn_t Pa_control (Pa_Handle handle,
1619 paCtrlInfo_t *ctrl,
1620 paCmd_t cmd,
1621 uint16_t *cmdSize,
1622 paCmdReply_t *reply,
1623 int *cmdDest);
1626 /**
1627 * @defgroup pktDest Routed Packet Destinations
1628 * @ingroup palld_api_constants
1629 * @{
1630 *
1631 * @name Routed Packet Destinations
1632 *
1633 * @brief The module user specifies packet destinations for packets exiting the packet accelerator sub-system.
1634 *
1635 * @details The destination of packets that leave the packet accelerator sub-system
1636 * are provided to the module in the @ref paRouteInfo_t structure and passed
1637 * to the module through the @ref Pa_addMac, @ref Pa_addSrio, @ref Pa_addIp, @ref Pa_addCustomLUT1,
1638 * @ref Pa_addCustomLUT2 and @ref Pa_addPort functions
1639 */
1640 /** @ingroup pktDest */
1641 /* @{ */
1643 /**
1644 * @def pa_DEST_DISCARD
1645 * packet is discarded
1646 */
1647 #define pa_DEST_DISCARD 3 /**< Packet is discarded */
1649 /**
1650 * @def pa_DEST_CONTINUE_PARSE_LUT1
1651 * packet remains in PA sub-system for more parsing and LUT1 classification
1652 */
1653 #define pa_DEST_CONTINUE_PARSE_LUT1 4 /**< Packet remains in PA sub-system for more parsing and LUT1 classification */
1655 /**
1656 * @def pa_DEST_CONTINUE_PARSE_LUT2
1657 * packet remains in PA sub-system for more parsing and LUT2 classification.
1658 */
1659 #define pa_DEST_CONTINUE_PARSE_LUT2 5 /**< Packet remains in PA sub-system for more parsing and LUT2 classification */
1661 /**
1662 * @def pa_DEST_HOST
1663 * host thread
1664 */
1665 #define pa_DEST_HOST 6 /**< Packet is routed to host */
1667 /**
1668 * @def pa_DEST_EMAC
1669 * ethernet mac port (of the switch)
1670 */
1671 #define pa_DEST_EMAC 7 /**< Packet is routed to EMAC */
1673 /**
1674 * @def pa_DEST_SASS
1675 * security accelerator destination
1676 */
1677 #define pa_DEST_SASS 8 /**< Packet is routed to SA */
1679 /**
1680 * @def pa_DEST_SRIO
1681 * SRIO interface
1682 */
1683 #define pa_DEST_SRIO 9 /**< Packet is routed to SRIO */
1685 /**
1686 * @def pa_DEST_CASCADED_FORWARDING_LUT1
1687 * Cascaded forwarding packet remains in PA sub-system for next LUT1 (IP) parsing. Those packets are expected to
1688 * be delivered to QoS queues based on the VLAN/DSCP priority at the next stage so that some PASS actions such
1689 * as IP reassembly and IP fragment exception route will be disabled.
1690 */
1691 #define pa_DEST_CASCADED_FORWARDING_LUT1 10
1693 /* @} */
1694 /** @} */
1696 /**
1697 * @defgroup paEmacPort Ethernet MAC port
1698 * @ingroup palld_api_constants
1699 * @{
1700 *
1701 * @name Ethernet MAC port
1702 *
1703 * @brief The module user specifies the Ethernet MAC port of the ingress and egress packets.
1704 *
1705 * @details In the from-network direction, the module user can specify the input port as one of classification parameters.
1706 * In the to-network direction, the module user can force the egress packets to be sent over the specified
1707 * destination Ethernet MAC port of the switch regreless of its states or configurations.
1708 */
1709 /** @ingroup customType */
1710 /* @{ */
1711 /**
1712 * @def pa_EMAC_PORT_NOT_SPECIFIED
1713 * From-Netwprk: Don't care
1714 * To-Network: Use standard switch forwarding
1715 */
1716 #define pa_EMAC_PORT_NOT_SPECIFIED 0
1718 /* @def pa_EMAC_PORT_0
1719 * Use EMAC Port 0
1720 */
1721 #define pa_EMAC_PORT_0 1
1723 /* @def pa_EMAC_PORT_1
1724 * Use EMAC Port 1
1725 */
1726 #define pa_EMAC_PORT_1 2
1728 /* @} */
1729 /** @} */
1731 /**
1732 * @defgroup emcOutputCtrlBits Ethernet MAC Output Control Bit Definitions
1733 * @ingroup palld_api_constants
1734 * @{
1735 *
1736 * @name Ethernet MAC Output Control Bit Definition
1737 *
1738 * Bitmap definition of the emacCtrl at @ref paRouteInfo_t.
1739 *
1740 */
1741 /*@{*/
1742 /**
1743 * @def pa_EMAC_CTRL_PORT_MASK
1744 * Control Info -- EMAC port mask
1745 */
1746 #define pa_EMAC_CTRL_PORT_MASK 0x0F
1747 /**
1748 * @def pa_EMAC_CTRL_CRC_DISABLE
1749 * Control Info -- 0:EMAC port computes and inserts CRC
1750 * 1:EMAC port does not generate CRC
1751 */
1752 #define pa_EMAC_CTRL_CRC_DISABLE 0x80
1754 /* @} */
1755 /** @} */
1757 /**
1758 * @defgroup customType Custom Classification Types
1759 * @ingroup palld_api_constants
1760 * @{
1761 *
1762 * @name Custom Classification Types
1763 *
1764 * @brief The module user specifies the custom classification types.
1765 *
1766 * @details The optional custom classification rule may be used to further parse and calssify the incoming
1767 * packet.
1768 */
1769 /** @ingroup customType */
1770 /* @{ */
1771 /**
1772 * @def pa_CUSTOM_TYPE_NONE
1773 * Use standard classification
1774 */
1775 #define pa_CUSTOM_TYPE_NONE 0
1777 /* @def pa_CUSTOM_TYPE_LUT1
1778 * Custom classification with LUT1
1779 */
1780 #define pa_CUSTOM_TYPE_LUT1 1
1782 /* @def pa_CUSTOM_TYPE_LUT2
1783 * Custom classification with LUT2
1784 */
1785 #define pa_CUSTOM_TYPE_LUT2 2
1787 /* @} */
1788 /** @} */
1790 /**
1791 * @brief The maximum number of LUT1 Custom Types supported
1792 */
1793 #define pa_MAX_CUSTOM_TYPES_LUT1 4
1796 /**
1797 * @brief The maximum number of LUT2 Custom Types supported
1798 */
1799 #define pa_MAX_CUSTOM_TYPES_LUT2 16
1802 /**
1803 * @defgroup cmdTxDest Command/Transmit Packet Destinations
1804 * @ingroup palld_api_constants
1805 * @{
1806 *
1807 * @name Command/Transmit Packet Destinations
1808 *
1809 * @brief These values are used by the module user to deliver the configuration packets to the specific PDSP within PASS.
1810 */
1811 /* @{ */
1812 /**
1813 * @def pa_CMD_TX_DEST_0
1814 * Destination PDSP0
1815 */
1816 #define pa_CMD_TX_DEST_0 0 /**< Packet is sent to PDSP0 */
1818 /**
1819 * @def pa_CMD_TX_DEST_1
1820 * Destination PDSP1
1821 */
1822 #define pa_CMD_TX_DEST_1 1 /**< Packet is sent to PDSP1 */
1824 /**
1825 * @def pa_CMD_TX_DEST_2
1826 * Destination PDSP2
1827 */
1828 #define pa_CMD_TX_DEST_2 2 /**< Packet is sent to PDSP2 */
1830 /**
1831 * @def pa_CMD_TX_DEST_3
1832 * Destination PDSP3
1833 */
1834 #define pa_CMD_TX_DEST_3 3 /**< Packet is sent to PDSP3 */
1836 /**
1837 * @def pa_CMD_TX_DEST_4
1838 * Destination PDSP4
1839 */
1840 #define pa_CMD_TX_DEST_4 4 /**< Packet is sent to PDSP4 */
1842 /**
1843 * @def pa_CMD_TX_DEST_5
1844 * Destination PDSP5
1845 */
1846 #define pa_CMD_TX_DEST_5 5 /**< Packet is sent to PDSP5 */
1849 /* @} */
1850 /** @} */
1852 /**
1853 * @defgroup paLut1Inst PA LUT1 Instance Destinations
1854 * @ingroup palld_api_constants
1855 * @{
1856 *
1857 * @name PA LUT1 Instance Destinations
1858 *
1859 * @brief These values are used by the module user to specify the LUT1 table instance used by the specified IP or customLUT1 entry
1860 */
1861 /* @{ */
1862 /**
1863 * @def pa_LUT1_INST_0
1864 * LUT1 instance 0
1865 */
1866 #define pa_LUT1_INST_0 0 /**< LUT1 table connected to PDSP0 */
1868 /**
1869 * @def pa_LUT1_INST_1
1870 * LUT1 instance 1
1871 */
1872 #define pa_LUT1_INST_1 1 /**< LUT1 table connected to PDSP1 */
1874 /**
1875 * @def pa_LUT1_INST_2
1876 * LUT1 instance 2
1877 */
1878 #define pa_LUT1_INST_2 2 /**< LUT1 table connected to PDSP2 */
1880 /**
1881 * @def pa_LUT1_INST_MAX
1882 * Specify the maximum LUT1 instance
1883 */
1884 #define pa_LUT1_INST_MAX pa_LUT1_INST_2
1886 /* @} */
1887 /** @} */
1890 /**
1891 * @defgroup paCmdCode Command Code
1892 * @ingroup palld_api_constants
1893 * @{
1894 *
1895 * @name PA Command Codes
1896 *
1897 * @brief Define the commands which can be executed in PASS
1898 *
1899 * @details A single command or a set of commands can be executed to support fully-offloaded
1900 * data path in both the transmit (to network) and receive (from network) directions.
1901 * In the to-network direction, the list of commands formatted by the module should
1902 * be stored as the protocol-specific information at the packet descriptor with the
1903 * packet. The commands will be executed in order at PASS and the associated security
1904 * accelerator sub-system (SASS). The executed commands will be removed by PASS and
1905 * SASS so that the output packet will not contain any command.
1906 * In the from-network direction, the list of commands formatted by the module will
1907 * be stored at the PASS as a command set which can be referred to by the command set
1908 * index. A single command including a command set can be executed per the enhanced
1909 * routing information @ref paRouteInfo_t after a LUT1 or LUT2 matches.
1910 *
1911 * @note The packet offset specified at each command of the command list should be strictly
1912 * in ascending order becasue the PASS processes the list of commands in order and it
1913 * can not move backwards. The command violating the order requirement may be detected
1914 * and rejected by the API @ref Pa_formatTxCmd and @ref Pa_configCmdSet. In the case,
1915 * the order constraint can not be validated at the LLD, the violating command will
1916 * be ignored by the PASS.
1917 */
1918 /** @ingroup paCmdCode */
1919 /* @{ */
1920 /**
1921 * @def pa_CMD_NONE
1922 * End of commands
1923 */
1924 #define pa_CMD_NONE 0
1926 /* @def pa_CMD_NEXT_ROUTE
1927 * Specifies next route
1928 */
1929 #define pa_CMD_NEXT_ROUTE 1
1931 /* @def pa_CMD_CRC_OP
1932 * CRC generation or verification
1933 */
1934 #define pa_CMD_CRC_OP 2
1936 /* @def pa_CMD_COPY_DATA_TO_PSINFO
1937 * Copy Data from the packet to the PS Info Area in the packet descriptor
1938 */
1939 #define pa_CMD_COPY_DATA_TO_PSINFO 3
1941 /* @def pa_CMD_PATCH_DATA
1942 * Insert or patch packet data at the specific location
1943 */
1944 #define pa_CMD_PATCH_DATA 4
1946 /* @def pa_CMD_TX_CHECKSUM
1947 * Compute and insert checksum
1948 */
1949 #define pa_CMD_TX_CHECKSUM 5
1951 /* @def pa_CMD_MULTI_ROUTE
1952 * Duplicate packet to multiple destinations
1953 */
1954 #define pa_CMD_MULTI_ROUTE 6
1956 /* @def pa_CMD_REPORT_TX_TIMESTAMP
1957 * Report the tx packet exit time in term of PASS 48-bit timestamp
1958 */
1959 #define pa_CMD_REPORT_TX_TIMESTAMP 7
1961 /* @def pa_CMD_REMOVE_HEADER
1962 * Remove the parsed packet header
1963 * @note It should be the first command in the rx command set
1964 */
1965 #define pa_CMD_REMOVE_HEADER 8
1967 /* @def pa_CMD_REMOVE_TAIL
1968 * Remove the parsed packet tail
1969 *
1970 * @note It should be the last command next to the next route or multi-route command
1971 */
1972 #define pa_CMD_REMOVE_TAIL 9
1975 /* @def pa_CMD_CMDSET
1976 * Specify the command set to be executed
1977 */
1978 #define pa_CMD_CMDSET 10
1980 /* @def pa_CMD_SA_PAYLOAD
1981 * Specify the payload information required by SASS
1982 */
1983 #define pa_CMD_SA_PAYLOAD 11
1985 /* @def pa_CMD_IP_FRAGMENT
1986 * Perform IPv4 fragmentation
1987 */
1988 #define pa_CMD_IP_FRAGMENT 12
1990 /* @def pa_CMD_USR_STATS
1991 * Update the specified user-defined counter and the counters which are linked to this counter
1992 */
1993 #define pa_CMD_USR_STATS 13
1996 /* @def pa_CMD_CMDSET_AND_USR_STATS
1997 * Combination of the CMDSET and USR_STATS commands.
1998 * @note It is only used as a command executed after the last classification per the enhanced routing
1999 * information
2000 */
2001 #define pa_CMD_CMDSET_AND_USR_STATS 14
2003 /* @def pa_CMD_PATCH_MSG_LEN
2004 * Update the message length field within some L2 protocol header such as 802.3 and PPPoE after the
2005 * potential IP fragmentation operation
2006 * @note This command is only used in conjunction with the pa_CMD_IP_FRAGMENT command.
2007 */
2008 #define pa_CMD_PATCH_MSG_LEN 15
2010 /* @def pa_CMD_VERIFY_PKT_ERROR
2011 * Verify the packet error based on the CPPI error flags as specified at @ref Appendix2 and forward
2012 * the error packet to the specified destination
2013 * @note This packet error verification is not applicable to the CRC verification operation within the same
2014 * command set.
2015 * @note This command should be either the last command or the second last to the nextRoute command since
2016 * all commands following this operation will be ignored if packet error is found.
2017 */
2018 #define pa_CMD_VERIFY_PKT_ERROR 16
2021 /* @def pa_CMD_SPLIT
2022 * Split the packet into header and payload portion to be delivered to different queues with
2023 * different CPPI flows
2024 * @note This command is only supported in the from-network direction
2025 * @note This command should be placed ahead of any pa_CMD_PATCH command so that the header size can be adjusted accordingly
2026 * @note The first 8-byte of psInfo area is reserved for this operation, therefore, the destOffset of pa_CMD_COPY_DATA_TO_PSINFO
2027 * commands within the same command set should be 8 or larger.
2028 *
2029 */
2031 #define pa_CMD_SPLIT 17
2033 /* @} */
2034 /** @} */
2036 /**
2037 * @defgroup routeCtrlInfo PA Routing Control Info Bit Definitions
2038 * @ingroup palld_api_constants
2039 * @{
2040 *
2041 * @name PA Routing Control Info Bit Definitions
2042 *
2043 * Bitmap definition of the ctrlBitField in @ref paCmdNextRoute_t.
2044 */
2045 /*@{*/
2046 /**
2047 * @def pa_NEXT_ROUTE_PARAM_PRESENT
2048 * Control Info -- Set: Routing information such as flowId, queue are in command for egress packets
2049 * Clear: Routing information such as flowId, queue are in packet for ingress packets
2050 */
2051 #define pa_NEXT_ROUTE_PARAM_PRESENT 0x0001
2052 /**
2053 * @def pa_NEXT_ROUTE_PROC_NEXT_CMD
2054 * Control Info -- Set: Process the next command prior to forward the packet to its final destination
2055 * Clear: Forward the packet to the next destination without executing any more command
2056 * @note: The data patch command (pa_CMD_PATCH_DATA) is the only one which can follow the next route command.
2057 * @note: This option is only valid in the transmit (to-network) direction
2058 */
2059 #define pa_NEXT_ROUTE_PROC_NEXT_CMD 0x0002
2060 /**
2061 * @def pa_NEXT_ROUTE_PROC_MULTI_ROUTE
2062 * Control Info -- Set: Multi-route is valid, the packet should be forwarded and then perform multi-route
2063 * Clear: Multi-route is invalid
2064 * @note: This option is only valid in the receive (from-network) direction
2065 */
2066 #define pa_NEXT_ROUTE_PROC_MULTI_ROUTE 0x0004
2067 /**
2068 * @def pa_NEXT_ROUTE_TX_L2_PADDING
2069 * Control Info -- Set: Perform MAC padding for packet with size smaller than 60
2070 * Clear: Do not perform MAC padding
2071 * @note: This option is only valid in the transmit (to-network) direction
2072 */
2073 #define pa_NEXT_ROUTE_TX_L2_PADDING 0x0008
2074 /**
2075 * @def pa_NEXT_ROUTE_PROC_USR_STATS
2076 * Control Info -- Set: User-defined statistics index is valid, update the chain of user-defined statistics specified
2077 * by statsIndex
2078 * Clear: User-defined statistics index is invalid
2079 * @note: This option is only valid in the egress (to-network) direction
2080 */
2081 #define pa_NEXT_ROUTE_PROC_USR_STATS 0x0010
2083 /*@}*/
2084 /** @} */
2087 /**
2088 * @ingroup palld_api_structures
2089 * @brief Next Route Command
2090 *
2091 * @details paCmdNextRoute_t defines the final route information
2092 * The next route command can be used in both to-network and from-network directions.
2093 * In the to-network direction, it may be used multiple times to route traffic between PASS and SASS
2094 * before the packet is finally forwarded to the network. For example, the following steps show the
2095 * SRTP over IPSEC AH to-network traffic:
2096 * @verbatim
2097 1. Packet is delivered to SASS for SRTP operation
2098 2. Packet is delivered to PASS for UDP checksum operation
2099 3. Packet is delivered to SASS for IPSEC AH operation
2100 4. Packet is delivered to PASS for AH authentication tag insertion
2101 5. Packet is delivered to the network.
2102 @endverbatim
2103 * The next route commands are required for step 3 and 5. The complete routing information should be provided
2104 * in the to-network direction.
2105 *
2106 * In the from-network direction, the next route command is used only if the multiple routes are required or when
2107 * dest is set to EMAC to forward the ingress packets out to another EMAC port.
2108 * In this case, only the parameter "ctrlBitfield", "multiRouteIndex" and/or "dest" are valid. After all the
2109 * commands in the command set are executed, the PASS will deliver packets to their desired destination based
2110 * on the parameters specified at the routing information upon the LUT1/LUT2 matching.
2111 * If the next route command is specified, it must be the last command within a command set. The commands following
2112 * the next route command will not be executed.
2113 */
2115 typedef struct {
2117 uint16_t ctrlBitfield; /**< Routing control information as defined at @ref routeCtrlInfo */
2118 int dest; /**< Packet destination as defined at @ref pktDest */
2119 uint8_t pktType_emacCtrl;/**< For destination SRIO, specify the 5-bit packet type toward SRIO
2120 For destination HOST, EMAC, specify the EMAC control @ref emcOutputCtrlBits to the network */
2121 uint8_t flowId; /**< For host, SA or SRIO destinations, specifies return free descriptor setup */
2122 uint16_t queue; /**< For host, SA or SRIO destinations, specifies the dest queue */
2123 uint32_t swInfo0; /**< Placed in SwInfo0 for packets to host or SA; Placed in the PS Info for packets to SRIO*/
2124 uint32_t swInfo1; /**< Placed in SwInfo1 for packets to the SA; Placed in the PS Info for packets to SRIO */
2125 uint16_t multiRouteIndex; /**< Multi-route index. It is valid in the from-network direction only */
2126 uint16_t statsIndex; /**< Index of the first user-defined statistics to be updated.
2127 This optional parameter is valid in the to-network direction only */
2128 } paCmdNextRoute_t;
2130 /**
2131 * @defgroup crcFrameTypes CRC Frame types
2132 * @ingroup palld_api_constants
2133 * @{
2134 *
2135 * @name CRC Frame types
2136 *
2137 * @brief Define the frame types which are used to extract and derive the CRC operation parameters such as CRC starting
2138 * offset and CRC payload length from the frame header.
2139 *
2140 * @details Both the payload length and the byte location where CRC calculation begins may vary in some protocl
2141 * frame such as WCDMA FP HS-DSCH Data Frame type 2 and type 3. The CRC Frame type is used for PASS to
2142 * extract and/or derive the CRC starting offset and payload length.
2143 *
2144 * @note Only the following frame types are supported.
2145 */
2146 /* @{ */
2147 /**
2148 *
2149 * @def pa_CRC_OP_FRAME_TYPE_IUB_FP_HS_DSCH_TYPE2
2150 * WCDMA FP HS-DSCH Data Frame Type 2
2151 */
2152 #define pa_CRC_OP_FRAME_TYPE_IUB_FP_HS_DSCH_TYPE2 0
2154 /**
2155 *
2156 * @def pa_CRC_OP_FRAME_TYPE_IUB_FP_HS_DSCH_TYPE3
2157 * WCDMA FP HS-DSCH Data Frame Type 3
2158 */
2159 #define pa_CRC_OP_FRAME_TYPE_IUB_FP_HS_DSCH_TYPE3 1
2161 #define pa_CRC_OP_FRAME_TYPE_MAX pa_CRC_OP_FRAME_TYPE_IUB_FP_HS_DSCH_TYPE3
2164 /* @} */
2165 /** @} */
2168 /**
2169 * @defgroup crcOpCtrlInfo PA CRC Command Control Info Bit Definitions
2170 * @ingroup palld_api_constants
2171 * @{
2172 *
2173 * @name PA CRC Command Control Info Bit Definitions
2174 *
2175 * Bitmap definition of the ctrlBitField in @ref paCmdCrcOp_t.
2176 */
2177 /*@{*/
2178 /**
2179 * @def pa_CRC_OP_CRC_VALIDATE
2180 * Control Info -- Set: CRC Validate
2181 * Clear: CRC Computation
2182 */
2183 #define pa_CRC_OP_CRC_VALIDATE 0x0001
2184 /**
2185 * @def pa_CRC_OP_PAYLOAD_LENGTH_IN_HEADER
2186 * Control Info -- Set: CRC length field in the header
2187 * Clear: CRC length specified in command
2188 */
2189 #define pa_CRC_OP_PAYLOAD_LENGTH_IN_HEADER 0x0002
2190 /**
2191 * @def pa_CRC_OP_PAYLOAD_LENGTH_OFFSET_IS_NEGATIVE
2192 * Control Info -- Set: Payload length field resides prior to the parsed header offset
2193 * length field offset = offset from the current parsed header - lenOffset
2194 * Clear: Payload length field resides after the parsed header offset
2195 * length field offset = offset from the current parsed header + lenOffset
2196 */
2197 #define pa_CRC_OP_PAYLOAD_LENGTH_OFFSET_IS_NEGATIVE 0x0004
2198 /**
2199 * @def pa_CRC_OP_CRC_FRAME_TYPE
2200 * Control Info -- Set: Frame Type is specified
2201 * Clear: Frame Type is not specified, use offset
2202 * parameter
2203 */
2204 #define pa_CRC_OP_CRC_FRAME_TYPE 0x0008
2205 /**
2206 * @def pa_CRC_OP_CRC_RESULT_FOLLOW_PAYLOAD
2207 * Control Info -- Set: CRC field following payload
2208 * Clear: CRC offset specified in command
2209 */
2210 #define pa_CRC_OP_CRC_RESULT_FOLLOW_PAYLOAD 0x0010
2211 /*@}*/
2212 /** @} */
2214 /**
2215 * @ingroup palld_api_structures
2216 * @brief CRC Generation/Verification Command
2217 *
2218 * @details paCmdCrcOp_t is used to create CRC operation command instruct the PASS to
2219 * perform CRC operation in both to-network and from-network directions. The
2220 * module user is responsible for configuring the corresponding CRC engines
2221 * which are used for the specified CRC operation.
2222 *
2223 * In the to-network direction, the payload offset, payload length and CRC offset
2224 * should be available in the command. The generated CRC will be inserted into
2225 * the CRC location in the packet.
2226 *
2227 * In the from-network direction, the payload length is either a constant or
2228 * available in the custom header. The CRC verification will be performed by
2229 * the CRC engine connected to the PDSP where the CRC command is executed.
2230 * The CRC verification result will be indicated by the error flags within
2231 * the CPPI descriptor as described at section table @ref appendix2
2232 */
2234 typedef struct {
2236 uint16_t ctrlBitfield; /**< CRC operation control information as defined at @ref crcOpCtrlInfo */
2237 uint16_t startOffset; /**< Byte location, from SOP/Protocol Header, where the CRC computation begins
2238 if frame type is not specified
2239 Byte location, from SOP/Protocol header, where the specific frame header begins
2240 if frame type is specified
2241 In to-network direction: offset from SOP
2242 In from-network direction: offset from the current parsed header
2243 */
2244 uint16_t len; /**< Number of bytes covered by the CRC computation
2245 valid only if pa_CRC_OP_PAYLOAD_LENGTH_IN_HEADER is clear */
2246 uint16_t lenOffset; /**< Payload length field offset in the custom header */
2247 uint16_t lenMask; /**< Payload length field mask */
2248 uint16_t lenAdjust; /**< Payload length adjustment: valid only if pa_CRC_OP_PAYLOAD_LENGTH_IN_HEADER is set */
2249 uint16_t crcOffset; /**< Offset from SOP/Protocol Header to the CRC field
2250 In to-network direction: offset from SOP
2251 In from-network direction: offset from the current parsed header */
2252 uint16_t frameType; /**< Frame type @ref crcFrameTypes, vaild if pa_CRC_OP_CRC_FRAME_TYPE is set */
2253 } paCmdCrcOp_t;
2255 /**
2256 * @defgroup splitOpCtrlInfo PA SPLIT Command Control Info Bit Definitions
2257 * @ingroup palld_api_constants
2258 * @{
2259 *
2260 * @name PA SPLIT Command Control Info Bit Definitions
2261 *
2262 * Bitmap definition of the ctrlBitField in @ref paCmdSplitOp_t.
2263 */
2264 /*@{*/
2265 /**
2266 * @def pa_SPLIT_OP_FRAME_TYPE
2267 * Control Info -- Set: Frame Type is specified
2268 * Clear: Frame Type is not specified, use offset
2269 * parameter
2270 */
2271 #define pa_SPLIT_OP_FRAME_TYPE 0x0001
2272 /*@}*/
2273 /** @} */
2275 /**
2276 * @ingroup palld_api_structures
2277 * @brief Split Command
2278 *
2279 * @details paCmdSplitOp_t is used to create Split command to instruct the PASS to
2280 * divide the ingress packet into the header and payload portion and deliver them
2281 * to specified destination queues with specified CPPI flows respectively.
2282 * Where the destination information of the header packet is specified by the
2283 * classification routing information and the destination information of the payload
2284 * packet is specified in this structure.
2285 *
2286 */
2287 typedef struct {
2288 uint16_t ctrlBitfield; /**< Split operation control information as defined at @ref splitOpCtrlInfo */
2289 uint16_t startOffset; /**< Byte location, from Protocol Header, where the payload begins
2290 if frame type is not specified
2291 Byte location, from Protocol header, where the specific frame header begins
2292 if frame type is specified
2293 In from-network direction: offset from the current parsed header
2294 */
2295 uint16_t frameType; /**< Frame type @ref crcFrameTypes, vaild if pa_SPLIT_OP_FRAME_TYPE is set */
2296 uint16_t destQueue; /**< Host queue for the payload packet */
2297 uint16_t flowId; /**< CPPI flow which instructs how link-buffer queues are used for sending payload packets. */
2299 } paCmdSplitOp_t;
2301 /**
2302 * @ingroup palld_api_structures
2303 * @brief Transmit checksum configuration
2304 *
2305 * @details paTxChksum_t is used in the call to @ref Pa_formatTxRoute or @ref Pa_formatTxCmd to create a tx
2306 * command header that instructs the packet accelerator sub-system to generate ones' complement
2307 * checksums into network packets. The checksums are typically used for TCP and UDP payload checksums as
2308 * well as IPv4 header checksums. In the case of TCP and UDP payload checksums the psuedo header
2309 * checksum must be pre-calculated and provided, the sub-system does not calculate it.
2310 */
2311 typedef struct {
2313 uint16_t startOffset; /**< Byte location, from SOP, where the checksum calculation begins */
2314 uint16_t lengthBytes; /**< Number of bytes covered by the checksum. Must be even */
2315 uint16_t resultOffset; /**< Byte offset, from startOffset, to place the resulting checksum */
2316 uint16_t initialSum; /**< Initial value of the checksum */
2317 uint16_t negative0; /**< If TRUE, a computed value of 0 is written as -0 */
2319 } paTxChksum_t;
2322 /**
2323 * @defgroup copyCtrlInfo PA Copy Command Control Info Bit Definitions
2324 * @ingroup palld_api_constants
2325 * @{
2326 *
2327 * @name PA Copy Command Control Info Bit Definitions
2328 *
2329 * Bitmap definition of the ctrlBitField in @ref paCmdCopy_t.
2330 *
2331 */
2332 /*@{*/
2333 /**
2334 * @def pa_COPY_OP_FROM_END
2335 * Control Info -- Set: Copy data from the end of the payload
2336 * Clear: Copy data from the beginning of the payload
2337 */
2338 #define pa_COPY_OP_FROM_END 0x0001
2339 /*@}*/
2340 /** @} */
2342 /**
2343 * @ingroup palld_api_structures
2344 * @brief Copy Command
2345 *
2346 * @details paCmdCopy_t is used to define how to copy number of bytes from the data packet to
2347 * the descriptor. The copy command is used to instruct the PASS to copy up to 8 byte
2348 * from packet to the PS info section in the packet descriptor in the from-network direction.
2349 * If the desired copy area crosses over the packet boundary, then garbage data will be copied.
2350 *
2351 * @note: There are 20-byte packet information stored in the PS Info section. It is recommended to copy
2352 * packet data after the packet information area. Otherwise, the packet information will be
2353 * overwritten. There are upto 12 bytes can be copied with the packet information or upto
2354 * 32 bytes can be copied without the packet information.
2355 */
2357 typedef struct {
2359 uint16_t ctrlBitfield; /**< Copy operation control information as defined at @ref copyCtrlInfo */
2360 uint16_t srcOffset; /**< Offset from the start of current protocol header for the data copy to begin */
2361 uint16_t destOffset; /**< Offset from the top of the PSInfo for the data to be copied to */
2362 uint16_t numBytes; /**< Number of bytes to be copied */
2363 } paCmdCopy_t;
2366 /**
2367 * @ingroup palld_api_structures
2368 * @brief Multi-route Command
2369 *
2370 * @details paCmdMultiRoute_t is used to specify the desired PA multi-route set.
2371 * The multi-route command instructs the PASS to route the packets to multiple
2372 * destinations in the from-network direction only. It must be the last command
2373 * within a command set. The commands following the multi-route command will
2374 * not be executed.
2375 */
2376 typedef struct {
2378 uint16_t index; /**< Multi-route set Index */
2379 } paCmdMultiRoute_t;
2382 /**
2383 * @ingroup palld_api_constants
2384 * @def pa_MAX_CMD_SETS
2385 * The maximum number of command sets supported
2386 */
2387 #define pa_MAX_CMD_SETS 64
2389 /**
2390 * @ingroup palld_api_structures
2391 * @brief Command Set Command
2392 *
2393 * @details paCmdSet_t is used to specify the desired PA command set. The command set command
2394 * instructs the PASS to execute a list of commands after a LUT1 or LUT2 match occurs.
2395 * It is one of the command which can be embedded within the @ref paRouteInfo_t.
2396 */
2397 typedef struct {
2399 uint16_t index; /**< Command Set Index */
2400 } paCmdSet_t;
2402 /**
2403 * @ingroup palld_api_constants
2404 * @def pa_MAX_PATCH_BYTES
2405 * The maximum number of bytes that a patch command can accept
2406 */
2407 #define pa_MAX_PATCH_BYTES 16 /**< PATCH Command in to-netweok direction */
2408 #define pa_MAX_RX_PATCH_BYTES 32 /**< PATCH Command within a command set */
2410 /**
2411 * @defgroup patchCtrlInfo PA Patch Command Control Info Bit Definitions
2412 * @ingroup palld_api_constants
2413 * @{
2414 *
2415 * @name PA Patch Command Control Info Bit Definitions
2416 *
2417 * Bitmap definition of the ctrlBitField in @ref paPatchInfo_t.
2418 *
2419 */
2420 /*@{*/
2421 /**
2422 * @def pa_PATCH_OP_INSERT
2423 * Control Info -- Set: Insert data into the packet
2424 * Clear: Patch data replaces existing packet data
2425 */
2426 #define pa_PATCH_OP_INSERT 0x0001
2427 /**
2428 * @def pa_PATCH_OP_MAC_HDR
2429 * Control Info -- Set: Replace MAC header with patch data
2430 * Clear: Normal Patch/Insert operation
2431 */
2432 #define pa_PATCH_OP_MAC_HDR 0x0002
2433 /**
2434 * @def pa_PATCH_OP_DELETE
2435 * Control Info -- Set: Delete data in the packet
2436 * Clear: Normal Patch/Insert operation
2437 */
2438 #define pa_PATCH_OP_DELETE 0x0004
2439 /*@}*/
2440 /** @} */
2443 /**
2444 * @ingroup palld_api_structures
2445 * @brief Packet patching configuration
2446 *
2447 * @details paPatchInfo_t is used to create data patch command. The patch command is used to patch
2448 * existing data or insert data in the packet in both to-network and from-network directions.
2449 *
2450 * In the to-network direction, it can be used to patch the authentication tag provided by SASS
2451 * into the AH header within the packet. In this case, the patch data is not present at the command
2452 * when it is formatted and it is appended by the SASS. The @ref Pa_formatRoutePatch is used to create
2453 * a command block along with a packet routing command to forward the packet after the patch is complete
2454 *
2455 * In the from-network direction, it can be used to insert up to 32 bytes to the offset location
2456 * as part of the command set to be executed after a LUT1 or LUT2 match.
2457 * This command can be used to patch the entire MAC header for MAC router functionality. It may be further
2458 * enhanced and combined with other commands to support IP forwarding operation in the future.
2459 * A short version of the patch command can be used to insert up to 2 bytes into the current parsing
2460 * location of the packet after a LUT2 match.
2461 */
2463 typedef struct {
2465 uint16_t ctrlBitfield; /**< Patch operation control information as defined at @ref patchCtrlInfo */
2466 uint16_t nPatchBytes; /**< The number of bytes to be patched */
2467 uint16_t totalPatchSize; /**< The number of patch bytes in the patch command, must be >= to nPatchBytes and a multiple of 4 bytes */
2468 uint16_t offset; /**< Offset from the start of the packet for the patch to begin in the to-network direction
2469 Offset from the start of the current header for the patch to begin in the from-network direction */
2470 uint8_t *patchData; /**< Pointer to the patch data */
2472 } paPatchInfo_t;
2476 /**
2477 * @ingroup palld_api_structures
2478 * @brief paPayloadInfo_t defines the packet payload information in the short format.
2479 * It is required by the Security Accelerator sub-system (SASS)
2480 *
2481 * @details paPayloadInfo_t defines the packet parsing information in terms of
2482 * payload offset and payload length as described below
2483 * @li SRTP: offset to the RTP header; RTP payload length including ICV
2484 * @li IPSEC AH: offset to the Outer IP; IP payload length
2485 * @li IPSEC ESP: offset to the ESP header; ESP papload length including ICV
2486 */
2488 typedef struct {
2489 uint16_t offset; /**< The offset to where the SA packet parsing starts */
2490 uint16_t len; /**< The total length of the protocal payload to be processed by SA */
2491 uint32_t supData; /**< Optional supplement data such as the 32-bit CountC for some 3GPP operation modes */
2492 } paPayloadInfo_t;
2495 /**
2496 * @ingroup palld_api_structures
2497 * @brief Tx timestamp reporting information
2498 *
2499 * @details paCmdTxTimestamp_t specifies the tx timestamp reporting information. The report tx timestamp command is used to instruct
2500 * the PASS to report the PA timestamp when the packet is transmitting out of PASS in a return (null) packet to the specified
2501 * host queue. The transmit timestamp may be used for the Precision Timing Protocol (PTP). The reported tx timestamp will be
2502 * a 48 bit value, with the lower 32 bits stored in timestamp field, and the upper 16 bits stored in swInfo1.
2503 *
2504 * @pre API @ref Pa_configTimestamp() should be called to enable PASS system timestamp.
2505 */
2507 typedef struct {
2508 uint16_t destQueue; /**< Host queue for the tx timestamp reporting packet */
2509 uint16_t flowId; /**< CPPI flow which instructs how link-buffer queues are used for sending tx timestamp reporting packets. */
2510 uint32_t swInfo0; /**< lower 32 bit value returned in the descriptor as swInfo0 which can be used as event identifier */
2511 } paCmdTxTimestamp_t;
2513 /**
2514 * @ingroup palld_api_structures
2515 * @brief IP fragmentation information
2516 *
2517 * @details paCmdIpFrag_t is used to create the IPv4 fragment command. The IP fragment command is used to instruct the PASS to
2518 * perform IPv4 fragmentation operation. This operation can be applied to both inner IP prior to IPSEC encapsulation and
2519 * outer IP after IPSEC encapsulation. This command should go with a next route command which provides the destination
2520 * information prior to the fragmentation operation.
2521 *
2522 * For the inner IP fragmentation, follow the following procedure:
2523 * @li Host sends packets with the IP fragment command and the destination queue set to a host queue to PASS PDSP5
2524 * for IP fragmentation operation.
2525 * @li All fragments will be delivered to the specified host queue.
2526 * @li Host adds the outer MAC/IP header, invokes the SA LLD sendData function and then sends the fragments to the SA queue.
2527 * @li Each fragment will be encrypted, authenticated and forwarded to the final destination.
2528 *
2529 * For the outer IP fragmentation, the overall operation is stated below:
2530 * @li Packet is delivered to SASS for IPSEC operation
2531 * @li Packet is delivered to PASS for IP Fragmentation operation
2532 * @li The entire packet or its fragments are delivered to the network.
2533 *
2534 * @note the next route command is required for step 2
2535 * @note The IP fragment command can not be combined with some other tx commands such as checksum and CRC commands since
2536 * those commands may require the PASS operation across multiple fragments. The workaround is to break the tx commands into
2537 * two groups. The first group consists of the checksum, CRC, other commands and a next route command which routes the packet
2538 * back to the same PDSP to execute the second command group which consists of the IP fragment command and the next route
2539 * command which points to the final destination.
2540 *
2541 * The IP fragment command can be combined with a single blind patch command to support the IPSEC AH use case in which the SASS
2542 * passes the IPSEC AH packet with the blind patch command to the PASS so that the autentication tag can be inserted into the AH
2543 * header. The recommended order of the tx commands is as the followings:
2544 * - pa_CMD_IP_FRAGMENT
2545 * - pa_CMD_NEXT_ROUTE with flag pa_NEXT_ROUTE_PROC_NEXT_CMD set
2546 * - pa_CMD_PATCH_DATA
2547 *
2548 * The IP fragment command can be also combined with up to two message length patching commands to support the message length
2549 * field updating for each IP fragment. This operation is required for certain L2 header which contains a length field such as
2550 * 802.3 and PPPoE. The order of tx command is as the followings:
2551 * - pa_CMD_PATCH_MSG_LEN (optional)
2552 * - pa_CMD_PATCH_MSG_LEN (optional)
2553 * - pa_CMD_IP_FRAGMENT
2554 * - pa_CMD_NEXT_ROUTE
2555 */
2557 typedef struct {
2558 uint16_t ipOffset; /**< Offset to the IP header. */
2559 uint16_t mtuSize; /**< Size of the maximum transmission unit (>= 68) */
2560 } paCmdIpFrag_t;
2562 /**
2563 * @ingroup palld_api_structures
2564 * @brief Message length patching configuration
2565 *
2566 * @details paPatchMsgLenInfo_t is used to create message length patch command which is used in conjunction with
2567 * the Ip fragmentation command. This command instruct the PASS to update the message length field within
2568 * some L2 protocol header such as 802.3 and PPPoE after the potential IP fragmentation operation.
2569 *
2570 * The PASS support up to two message length patching operations per IP fragmentation command.
2571 */
2573 typedef struct {
2575 uint8_t msgLenSize; /**< Size of message length field in bytes (@note only 2-byte and 4=byte message length is supported) */
2576 uint8_t offset; /**< Offset from the start of the packet to the message length field */
2577 uint16_t msgLen; /**< Message length excluding the IP header and payload length */
2579 } paPatchMsgLenInfo_t;
2581 /**
2582 * @ingroup palld_api_structures
2583 * @brief User-defined Statistics Command
2584 *
2585 * @details paCmdUsrStats_t is used to specify the desired User-defined counter. The user stats command
2586 * instructs the PASS to update the specified user-defined counter and all the counters which are
2587 * linked to this counter
2588 * It is one of the command which can be embedded within the @ref paRouteInfo_t.
2589 */
2590 typedef struct {
2591 uint16_t index; /**< User-defined statistics index */
2592 } paCmdUsrStats_t;
2594 /**
2595 * @ingroup palld_api_structures
2596 * @brief Command Set plus User-defined Statistics Command
2597 *
2598 * @details paCmdSetUsrStats_t is used to specify the desired PA command set and User-defined counter. This command
2599 * provides the module user a mechanism to specify different user-defined counters with the same command set
2600 * for different LUT entries and vice versa.
2601 * This command instructs the PASS to update the specified user-defined counter and all the counters which are
2602 * linked to this counter and then execute the specified command set.
2603 * It is one of the command which can be embedded within the @ref paRouteInfo_t.
2604 */
2605 typedef struct {
2606 uint16_t setIndex; /**< Commad Set Index */
2607 uint16_t statsIndex; /**< User-defined statistics index */
2608 } paCmdSetUsrStats_t;
2611 /**
2612 * @defgroup pktErrInfo PA Packet Error Info Bit Definitions
2613 * @ingroup palld_api_constants
2614 * @{
2615 *
2616 * @name PA Packet Error Info Bit Definitions
2617 *
2618 * Bitmap definition of the errorBitfield in @ref paCmdVerifyPktErr_t.
2619 *
2620 */
2621 /*@{*/
2622 /**
2623 * @def pa_PKT_ERR_IP_CHECKSUM
2624 * Control Info -- Set: Re-direct packet if IP checksum error occurs
2625 * Clear: Ignore IP checksum Error
2626 */
2627 #define pa_PKT_ERR_IP_CHECKSUM 0x0001
2628 /**
2629 * @def pa_PKT_ERR_L4_CHECKSUM
2630 * Control Info -- Set: Re-direct packet if UDP/TCP checksum error occurs
2631 * Clear: Ignore UDP/TCP checksum Error
2632 */
2633 #define pa_PKT_ERR_L4_CHECKSUM 0x0002
2634 /**
2635 * @def pa_PKT_ERR_CRC
2636 * Control Info -- Set: Re-direct packet if CRC error occurs
2637 * Clear: Ignore CRC Error
2638 */
2639 #define pa_PKT_ERR_CRC 0x0004
2640 /*@}*/
2641 /** @} */
2643 /**
2644 * @ingroup palld_api_structures
2645 * @brief Verify Packet Error Command
2646 *
2647 * @details paCmdVerifyPktErr_t is used to construct the "Verify Packet Error" command. The
2648 * IPv4 header checksum, UDP/TCP checksum and SCTP CRC-32c checksum verification are performed by
2649 * the PASS autonomously while the CRC verification is performed per command. The corresponding error bit
2650 * in the CPPI descriptor will be set and can be verified by the application when packet is delivered
2651 * to the host. This command instructs PASS to examine the specified error flags and forward the error
2652 * packet accordingly.
2653 */
2655 typedef struct {
2657 uint16_t errorBitfield; /**< Packet Error information as defined at @ref pktErrInfo */
2658 uint8_t dest; /**< Packet destination as defined at @ref pktDest */
2659 uint8_t flowId; /**< For host destination, specifies CPPI flow which defines free queues are used for receiving packets */
2660 uint16_t queue; /**< For host destination, specifies the destination queue */
2661 uint32_t swInfo0; /**< Placed in SwInfo0 for packets to host */
2662 } paCmdVerifyPktErr_t;
2665 /**
2666 * @ingroup palld_api_structures
2667 * @brief PA Command Information structure
2668 *
2669 * @details Data structure defines PA commands. The PA command can be invoked by the @ref paRouteInfo_t as a simple command.
2670 * They are the building blocks for function @ref Pa_configCmdSet to create a list of commands refered as a command
2671 * set in the from-network direction. They can be used by the function @ref Pa_formatTxCmd to create or update the
2672 * list of tx commands.
2673 *
2674 */
2675 typedef struct {
2676 uint16_t cmd; /**< Specify the PA command code as defined at @ref paCmdCode */
2677 union {
2678 paCmdNextRoute_t route; /**< Specify nextRoute command specific parameters */
2679 paTxChksum_t chksum; /**< Specify Tx Checksum command specific parameters */
2680 paCmdCrcOp_t crcOp; /**< Specify CRC operation command specific parameters */
2681 paCmdCopy_t copy; /**< Specify Copy command specific parameters */
2682 paPatchInfo_t patch; /**< Specify Patch command specific parameters */
2683 paPayloadInfo_t payload; /**< Specify the payload information required by SA */
2684 paCmdSet_t cmdSet; /**< Specify Command Set command specific parameters */
2685 paCmdMultiRoute_t mRoute; /**< Specify Multi-route command specific parameters */
2686 paCmdTxTimestamp_t txTs; /**< Specify Report Tx Timestamp command specific parameters */
2687 paCmdIpFrag_t ipFrag; /**< Specify IP fragmentation command specific parameters */
2688 paCmdUsrStats_t usrStats; /**< Specify User-defined Statistics command specific parameters */
2689 paCmdSetUsrStats_t cmdSetUsrStats; /**< Specify Command Set and User-defined Statistics command specific parameters */
2690 paPatchMsgLenInfo_t patchMsgLen; /**< Specify Patch Message Length command specific parameters */
2691 paCmdVerifyPktErr_t verifyPktErr; /**< Specify Packet error Verification command specific parameters */
2692 paCmdSplitOp_t split; /**< Specify Split command sepcific parameters */
2693 }params; /**< Contain the command specific parameters */
2695 } paCmdInfo_t;
2697 /**
2698 * @ingroup palld_api_structures
2699 * @brief IP lookup information
2700 *
2701 * @details paIpInfo_t is used to specifiy the IPv4 or IPv6 parameters used in packet routing.
2702 * With the exception of parameter tos, a value of 0 in any parameter means that that
2703 * field is not used in packet routing. Since a value of 0 is valid for tos, the paramter
2704 * tosCare is used to indicate if the tos field (IPv4) or traffic class (Ipv6) is used
2705 * for packet routing.
2706 */
2707 typedef struct {
2709 paIpAddr_t src; /**< Source IP address */
2710 paIpAddr_t dst; /**< Destination IP address */
2711 uint32_t spi; /**< ESP or AH header Security Parameters Index */
2712 uint32_t flow; /**< IPv6 flow label in 20 lsbs */
2713 int ipType; /**< @ref IpValues */
2714 uint16_t greProto; /**< GRE protocol field */
2715 uint8_t proto; /**< IP Protocol (IPv4) / Next Header (IPv6) */
2716 uint8_t tos; /**< IP Type of Service (IPv4) / Traffic class (IPv6) */
2717 uint16_t tosCare; /**< TRUE if the tos value is used for matching */
2718 uint16_t sctpPort; /**< SCTP Destination Port */
2719 } paIpInfo_t;
2721 /**
2722 * @defgroup paIpInfoValidBits PA IP Info Valid Bit Definitions
2723 * @ingroup palld_api_constants
2724 * @{
2725 *
2726 * @name PA IP Info Valid Bit Definitions
2727 *
2728 * Bitmap definition of the validBitMap in @ref paIpInfo2_t.
2729 */
2730 /*@{*/
2731 /**
2732 * @def pa_IP_INFO_VALID_SRC
2733 * - Source IP address is present
2734 */
2735 #define pa_IP_INFO_VALID_SRC (1<<0)
2737 /**
2738 * @def pa_IP_INFO_VALID_DST
2739 * - Destination IP address is present
2740 */
2741 #define pa_IP_INFO_VALID_DST (1<<1)
2743 /**
2744 * @def pa_IP_INFO_VALID_SPI
2745 * - 32-bit Security Parameters Index of IPSEC ESP/AH is present
2746 */
2747 #define pa_IP_INFO_VALID_SPI (1<<2)
2749 /**
2750 * @def pa_IP_INFO_VALID_FLOW
2751 * - IPv6 flow label is present
2752 */
2753 #define pa_IP_INFO_VALID_FLOW (1<<3)
2755 /**
2756 * @def pa_IP_INFO_VALID_GREPROTO
2757 * - GRE protocol field is present
2758 */
2759 #define pa_IP_INFO_VALID_GREPROTO (1<<4)
2761 /**
2762 * @def pa_IP_INFO_VALID_PROTO
2763 * - IPv4 protocol or IPv6 next header is present
2764 */
2765 #define pa_IP_INFO_VALID_PROTO (1<<5)
2767 /**
2768 * @def pa_IP_INFO_VALID_TOS
2769 * - IPv4 type of service or IPv6 traffic class is present
2770 */
2771 #define pa_IP_INFO_VALID_TOS (1<<6)
2773 /**
2774 * @def pa_IP_INFO_VALID_SCTPPORT
2775 * - SCTP destination port is present
2776 */
2778 #define pa_IP_INFO_VALID_SCTPPORT (1<<7)
2780 /* @} */ /* ingroup */
2781 /** @} */
2783 /**
2784 * @ingroup palld_api_structures
2785 * @brief Enhanced IP lookup information
2786 *
2787 * @details paIpInfo2_t is the upgraded version of paIpInfo_t to support additional IP lookup
2788 * parameters over time while still maintaining backward compatibility. Future feature
2789 * enhancements will be supported through this API data structure only.
2790 *
2791 * Since not all fields are used all the time, validBitMap is used to specify which field
2792 * is used for packet classification.
2793 */
2794 typedef struct {
2795 uint32_t validBitMap;/**< 32-bit valid bitmap corresponding to each optional field as defined at @ref paIpInfoValidBits */
2796 paIpAddr_t src; /**< Source IP address */
2797 paIpAddr_t dst; /**< Destination IP address */
2798 uint32_t spi; /**< ESP or AH header Security Parameters Index */
2799 uint32_t flow; /**< IPv6 flow label in 20 lsbs */
2800 int ipType; /**< Mandatory if src or dst is valid @ref IpValues */
2801 uint16_t greProto; /**< GRE protocol field */
2802 uint8_t proto; /**< IP Protocol (IPv4) / Next Header (IPv6) */
2803 uint8_t tos; /**< IP Type of Service (IPv4) / Traffic class (IPv6) */
2804 uint16_t sctpPort; /**< SCTP Destination Port */
2805 } paIpInfo2_t;
2807 /**
2808 * @ingroup palld_api_structures
2809 * @brief MAC/Ethernet lookup information
2810 *
2811 * @details paEthInfo_t is used to specify the MAC/Ethernet parameters used in packet classification.
2812 * A value in 0 for any of the fields indicates that the field is not used for
2813 * packet classification.
2814 */
2815 typedef struct {
2816 paMacAddr_t src; /**< Source MAC addresss */
2817 paMacAddr_t dst; /**< Destination MAC address */
2818 uint16_t vlan; /**< VLAN tag VID field, 12 lsbs */
2819 uint16_t ethertype; /**< Ethertype field. */
2820 uint32_t mplsTag; /**< MPLS tag. Only the outer tag is examined */
2821 uint16_t inport; /**< Input EMAC port number as specified by @ref paEmacPort */
2822 } paEthInfo_t;
2824 /**
2825 * @defgroup paEthInfoValidBits PA ETH Info Valid Bit Definitions
2826 * @ingroup palld_api_constants
2827 * @{
2828 *
2829 * @name PA ETH Info Valid Bit Definitions
2830 *
2831 * Bitmap definition of the validBitMap in @ref paEthInfo2_t.
2832 */
2833 /*@{*/
2835 /**
2836 * @def pa_ETH_INFO_VALID_SRC
2837 * - Source MAC is present
2838 */
2839 #define pa_ETH_INFO_VALID_SRC (1<<0)
2841 /**
2842 * @def pa_ETH_INFO_VALID_DST
2843 * - Destination MAC is present
2844 */
2845 #define pa_ETH_INFO_VALID_DST (1<<1)
2847 /**
2848 * @def pa_ETH_INFO_VALID_VLAN
2849 * - VLAN ID is present
2850 */
2851 #define pa_ETH_INFO_VALID_VLAN (1<<2)
2853 /**
2854 * @def pa_ETH_INFO_VALID_ETHERTYPE
2855 * - Ether type is present
2856 */
2857 #define pa_ETH_INFO_VALID_ETHERTYPE (1<<3)
2859 /**
2860 * @def pa_ETH_INFO_VALID_MPLSTAG
2861 * - MPLS tag is present
2862 */
2863 #define pa_ETH_INFO_VALID_MPLSTAG (1<<4)
2865 /**
2866 * @def pa_ETH_INFO_VALID_INPORT
2867 * - Input EMAC port is present
2868 */
2869 #define pa_ETH_INFO_VALID_INPORT (1<<5)
2871 /* @} */ /* ingroup */
2872 /** @} */
2874 /**
2875 * @ingroup palld_api_structures
2876 * @brief Enhanced MAC/Ethernet lookup information
2877 *
2878 * @details paEthInfo2_t is the upgraded version of paEthInfo_t to support additional MAC lookup
2879 * parameters over time while still maintaining backward compatibility. Future feature
2880 * enhancements will be supported through this API data structure only.
2881 *
2882 * Since not all fields are used all the time, validBitMap is used to specify which field
2883 * is used for packet classification.
2884 *
2885 */
2886 typedef struct {
2887 uint32_t validBitMap; /**< 32-bit valid bitmap corresponding to each optional field as defined at @ref paEthInfoValidBits */
2888 paMacAddr_t src; /**< Source MAC addresss */
2889 paMacAddr_t dst; /**< Destination MAC address */
2890 uint16_t vlan; /**< VLAN tag VID field, 12 lsbs */
2891 uint16_t ethertype; /**< Ethertype field. */
2892 uint32_t mplsTag; /**< MPLS tag. Only the outer tag is examined */
2893 uint16_t inport; /**< Input EMAC port number as specified by @ref paEmacPort */
2894 } paEthInfo2_t;
2896 /**
2897 * @ingroup palld_api_structures
2898 * @brief SRIO Type11 header information
2899 *
2900 * @details The structure describes the SRIO type 11 specific Lo-L2 header information.
2901 */
2902 typedef struct paSrioType11Info_s
2903 {
2904 uint16_t mbox; /**< Mail Box */
2905 uint16_t letter; /**< Letter Identifier */
2906 } paSrioType11Info_t;
2908 /**
2909 * @ingroup palld_api_structures
2910 * @brief SRIO Type9 header information
2911 *
2912 * @details The structure describes the SRIO type 9 specific L0-L2 header information.
2913 */
2914 typedef struct paSrioType9Info_s
2915 {
2916 uint16_t streamId; /**< Stream identifier */
2917 uint16_t cos; /**< Class of service */
2918 } paSrioType9Info_t;
2921 /**
2922 * @ingroup palld_api_structures
2923 * @brief Srio message type specific header information
2924 *
2925 * @details This union is used to specify the SRIO type specific header information to the module.
2926 * The type in the union is determined through other parameters passed to the module
2927 * (see @ref srioMessageTypes).
2928 */
2929 typedef union {
2931 paSrioType9Info_t type9; /**< SRIO type 9 specific information */
2932 paSrioType11Info_t type11; /**< SRIO type 11 specific information */
2934 } paSrioTypeInfo_t;
2936 /**
2937 * @defgroup srioMessageTypes SRIO Message types
2938 * @ingroup palld_api_constants
2939 * @{
2940 *
2941 * @name SRIO Type Values
2942 * @brief Defines the SRIO message types.
2943 *
2944 * @details The packet accelerator sub-system parses both SRIO Type 9 and Type 11 message headers (see @ref netlayers).
2945 * This group is used to distinguish which type of header will be used.
2946 */
2947 /* @{ */
2948 /**
2949 * @def pa_SRIO_TYPE_9
2950 * SRIO Message Type 9
2951 */
2952 #define pa_SRIO_TYPE_9 9
2954 /**
2955 * @def pa_SRIO_TYPE_11
2956 * SRIO Message Type 11
2957 */
2958 #define pa_SRIO_TYPE_11 11
2960 /* @} */
2961 /** @} */
2963 /**
2964 * @defgroup srioTransportTypes SRIO Transport types
2965 * @ingroup palld_api_constants
2966 * @{
2967 *
2968 * @name SRIO Transport Type Values
2969 * @brief Defines the SRIO tansport types used.
2970 *
2971 */
2972 /* @{ */
2973 /**
2974 * @def pa_SRIO_TRANSPORT_TYPE_0
2975 * SRIO Transport type 0: 8 bit device identifiers
2976 */
2977 #define pa_SRIO_TRANSPORT_TYPE_0 0
2979 /**
2980 * @def pa_SRIO_TRANSPORT_TYPE_1
2981 * SRIO Transport type 1: 16 bit device identifiers
2982 */
2983 #define pa_SRIO_TRANSPORT_TYPE_1 1
2985 /* @} */
2986 /** @} */
2988 /**
2989 * @defgroup paSrioInfoValidBits PA SRIO Info Valid Bit Definitions
2990 * @ingroup palld_api_constants
2991 * @{
2992 *
2993 * @name PA SRIO Info Valid Bit Definitions
2994 *
2995 * Bitmap definition of the validBitMap in @ref paSrioInfo_t.
2996 */
2997 /*@{*/
2998 /**
2999 * @def pa_SRIO_INFO_VALID_SRC_ID
3000 * - srcId is present
3001 */
3002 #define pa_SRIO_INFO_VALID_SRC_ID 0x0001
3003 /**
3004 * @def pa_SRIO_INFO_VALID_DEST_ID
3005 * - destId is present
3006 */
3007 #define pa_SRIO_INFO_VALID_DEST_ID 0x0002
3008 /**
3009 * @def pa_SRIO_INFO_VALID_ID
3010 * - Id is present
3011 */
3012 #define pa_SRIO_INFO_VALID_ID (pa_SRIO_INFO_VALID_SRC_ID | pa_SRIO_INFO_VALID_DEST_ID)
3014 /**
3015 * @def pa_SRIO_INFO_VALID_CC
3016 * - cc is present
3017 */
3018 #define pa_SRIO_INFO_VALID_CC 0x0004
3019 /**
3020 * @def pa_SRIO_INFO_VALID_PRI
3021 * - pri is present
3022 */
3023 #define pa_SRIO_INFO_VALID_PRI 0x0008
3024 /**
3025 * @def pa_SRIO_INFO_VALID_TYPE_INFO_STREAMID
3026 * - typeInfo.type9.streamId is present
3027 */
3028 #define pa_SRIO_INFO_VALID_TYPE_INFO_STREAMID 0x0010
3029 /**
3030 * @def pa_SRIO_INFO_VALID_TYPE_INFO_COS
3031 * - typeInfo.type9.cos is present
3032 */
3033 #define pa_SRIO_INFO_VALID_TYPE_INFO_COS 0x0020
3034 /**
3035 * @def pa_SRIO_INFO_VALID_TYPE_INFO_MAILBOX
3036 * - typeInfo.type11.mbox is present
3037 */
3038 #define pa_SRIO_INFO_VALID_TYPE_INFO_MAILBOX 0x0010
3039 /**
3040 * @def pa_SRIO_INFO_VALID_TYPE_INFO_LETTER
3041 * - typeInfo.type11.letter is present
3042 */
3043 #define pa_SRIO_INFO_VALID_TYPE_INFO_LETTER 0x0020
3044 /**
3045 * @def pa_SRIO_INFO_VALID_TYPE_INFO
3046 * - typeInfo is present
3047 */
3048 #define pa_SRIO_INFO_VALID_TYPE_INFO (pa_SRIO_INFO_VALID_TYPE_INFO_COS | \
3049 pa_SRIO_INFO_VALID_TYPE_INFO_STREAMID | \
3050 pa_SRIO_INFO_VALID_TYPE_INFO_LETTER | \
3051 pa_SRIO_INFO_VALID_TYPE_INFO_MAILBOX )
3052 /* @} */ /* ingroup */
3053 /** @} */
3055 /**
3056 * @ingroup palld_api_structures
3057 * @brief SRIO lookup information
3058 *
3059 * @details srioIpInfo_t is used to specifiy the SRIO type 9 and type 11 L0-L2 parameters used in packet routing.
3060 * set the corresponding valid bit at validBitMap for the parameters required for SRIO message
3061 * classification.
3062 * Where tt should be provided if srcId or destId is required
3063 * msgType should be provided if typeInfo is required
3064 */
3065 typedef struct {
3067 uint16_t validBitMap; /**< Specify which parameters are valid as defined at @ref paSrioInfoValidBits */
3068 uint16_t srcId; /**< Source ID */
3069 uint16_t destId; /**< Destination ID */
3070 uint16_t tt; /**< Transport Type: 16 bit or 8 bit identifiers as defined at @ref srioTransportTypes */
3071 uint16_t cc; /**< Completion code */
3072 uint16_t pri; /**< 3-bit priority */
3073 uint16_t msgType; /**< Message type as defined at @ref srioMessageTypes */
3074 paSrioTypeInfo_t typeInfo; /**< Message Type specific parameters */
3075 } paSrioInfo_t;
3078 /**
3079 * @ingroup palld_api_structures
3080 * @brief Packet routing configuration
3081 *
3082 * @details paRouteInfo_t is used to specify the physical routing of packets out of the packet accelerator
3083 * sub-system. Not all fields are required for all destinations.
3084 * @li pa_DEST_DISCARD: none
3085 * @li pa_DEST_CONTINUE_PARSE_LUT1:
3086 * @li pa_DEST_CONTINUE_PARSE_LUT2: customType, customIndex
3087 * @li pa_DEST_HOST: flowId, queue, mRoutehandle, swInfo0, cmd
3088 * @li pa_DEST_SASS: flowId, queue, swInfo0, swInfo1, cmd
3089 * @li pa_DEST_ETH: emacCtrl
3090 * @li pa_DEST_SRIO: flowId, queue, swInfo0, swInfo2, pktType
3091 */
3092 typedef struct {
3094 int dest; /**< Packet destination as defined at @ref pktDest */
3095 uint8_t flowId; /**< For host, SA or SRIO destinations, specifies CPPI flow which defines free queues are used for receiving packets */
3096 uint16_t queue; /**< For host, SA or SRIO destinations, specifies the destination queue */
3097 int mRouteIndex; /**< For host, Multi-queue routing index (0 to (@ref pa_MAX_MULTI_ROUTE_SETS - 1))
3098 or @ref pa_NO_MULTI_ROUTE if multi routing not used */
3099 uint32_t swInfo0; /**< Placed in SwInfo0 for packets to host or SA; Placed in the PS Info for packets to SRIO */
3100 uint32_t swInfo1; /**< Placed in SwInfo1 for packets to the SA; Placed in the PS Info for packets to SRIO */
3101 int customType; /**< For CONTINUE_PARSE_LUT1/LUT2 only, specifies the custom type as defined at @ref customType */
3102 uint8_t customIndex; /**< For CONTINUE_PARSE_LUT1/LUT2 only, specifies the custom classification entry index */
3103 uint8_t pktType_emacCtrl; /**< For destination SRIO, specify the 5-bit packet type toward SRIO
3104 For destination HOST, EMAC, specify the EMAC control @ref emcOutputCtrlBits to the network */
3105 paCmdInfo_t *pCmd; /**< Pointer to the Command info to be executed prior to the packet forwarding.
3106 NULL: no commads
3107 @note only the following commands are supported within paRouteInfo_t
3108 - pa_CMD_PATCH_DATA (up to two bytes only) (LUT2 only)
3109 - pa_CMD_CMDSET
3110 - pa_CMD_USR_STATS
3111 - pa_CMD_CMDSET_AND_USR_STATS
3112 */
3113 } paRouteInfo_t;
3115 /**
3116 * @def pa_NO_MULTI_ROUTE
3117 * Multi Route not enabled in this route
3118 */
3119 #define pa_NO_MULTI_ROUTE -1
3121 /**
3122 * @def pa_MAX_MULTI_ROUTE_SETS
3123 * The maximum number of multi-route sets supported
3124 */
3125 #define pa_MAX_MULTI_ROUTE_SETS 32
3127 /**
3128 * @def pa_MAX_MULTI_ROUTE_ENTRIES
3129 * The maximum number of multi-route entries per muli-route set
3130 */
3131 #define pa_MAX_MULTI_ROUTE_ENTRIES 8
3133 /**
3134 @defgroup paPriIntfRouteMode Priority-based or Interface-based routing mode
3135 * @ingroup palld_api_constants
3136 * @{
3137 *
3138 * @name Priority-based or Interface-based routing mode
3139 *
3140 * paRoutePriIntf_e is used to specify the mode of priority-based
3141 * or interface-based routing.
3142 * PASS forwards the matched packets to the desired QoS queue which is equal
3143 * to the base queue plus an offset specified by the VLAN priority or DSCP value
3144 * in prority-based routing.
3145 * PASS forwards the matched packets to the desired host queue which is equal
3146 * to the base queue plus an offset as the EMAC port (interface) number with the CPPI
3147 * flow which is equal to the base flow number plus the EMAC port (interface) number
3148 * optionally in interface-based routing.
3149 *
3150 * @note: There is some use cases where output packets from QoS are delivered to
3151 * PASS for pre-routing operation such as tx timestamp report and both
3152 * egress and ingress forwarding packets go through the same QoS. To support
3153 * this use case, the PASS is enhanced to delay the post-classification command
3154 * set execution until the packets re-entering PASS from QoS if Priority-based
3155 * routing is selected.
3156 */
3157 /** @ingroup paPriIntfRouteMode */
3158 /*@{*/
3159 typedef enum {
3160 pa_ROUTE_PRIORITY_VLAN = 1, /**< Route by using VLAN bits as priority */
3161 pa_ROUTE_PRIORITY_DSCP, /**< Route by using DSCP bits as priority */
3162 pa_ROUTE_INTF, /**< Route by using EMAC port (interface) number as destination queue offset */
3163 pa_ROUTE_INTF_W_FLOW /**< Route by using EMAC port (interface) number as both
3164 destination queue and CPPI flow offset */
3165 } paRoutePriIntf_e;
3167 /*@}*/
3168 /** @} */
3170 /**
3171 * @defgroup paRouteInfoValidBits PA Route Info Valid Bit Definitions
3172 * @ingroup palld_api_constants
3173 * @{
3174 *
3175 * @name PA Route Info Valid Bit Definitions
3176 *
3177 * Bitmap definition of the validBitMap in @ref paRouteInfo2_t.
3178 */
3179 /*@{*/
3181 /**
3182 * @def pa_ROUTE_INFO_VALID_MROUTEINDEX
3183 * - Optional parameter mRouteIndex for Host routing is valid
3184 */
3185 #define pa_ROUTE_INFO_VALID_MROUTEINDEX (1<<0)
3187 /**
3188 * @def pa_ROUTE_INFO_VALID_PKTTYPE_EMAC
3189 * - Optional parameter pktType_emacCtrl for Host or EMAC routing is valid
3190 */
3191 #define pa_ROUTE_INFO_VALID_PKTTYPE_EMAC (1<<1)
3193 /**
3194 * @def pa_ROUTE_INFO_VALID_PCMD
3195 * - Optional parameter pCmd is valid
3196 */
3197 #define pa_ROUTE_INFO_VALID_PCMD (1<<2)
3199 /**
3200 * @def pa_ROUTE_INFO_VALID_PRIORITY_TYPE
3201 * - Optional parameter priorityType used for Priority-based or interface-based routing is valid
3202 */
3203 #define pa_ROUTE_INFO_VALID_PRIORITY_TYPE (1<<3)
3205 /* @} */ /* ingroup */
3206 /** @} */
3208 /**
3209 * @ingroup palld_api_structures
3210 * @brief Enhanced Packet routing configuration
3211 *
3212 * @details paRouteInfo2_t is the upgraded version of paRouteInfo_t to support additional routing
3213 * parameters over time while still maintaining backward compatibility. Future feature
3214 * enhancements will be supported through this API data structure only.
3215 *
3216 * The validBitMap is used to specify which field is used for packet routing.
3217 */
3218 typedef struct {
3219 uint32_t validBitMap; /**< 32-bit valid bitmap corresponding to each optional field as defined at @ref paRouteInfoValidBits */
3220 int dest; /**< Packet destination as defined at @ref pktDest */
3221 uint8_t flowId; /**< For host, SA or SRIO destinations, specifies CPPI flow which defines free queues are used for receiving packets */
3222 uint16_t queue; /**< For host, SA or SRIO destinations, specifies the destination queue */
3223 int mRouteIndex; /**< validBitMap[t0] For host, Multi-queue routing index (0 to (@ref pa_MAX_MULTI_ROUTE_SETS - 1) */
3224 uint32_t swInfo0; /**< For host, SA or SRIO destinations, placed in SwInfo0 for packets to host or SA; Placed in the PS Info for packets to SRIO */
3225 uint32_t swInfo1; /**< For host, SA or SRIO destinations, placed in SwInfo1 for packets to the SA; Placed in the PS Info for packets to SRIO */
3226 int customType; /**< For CONTINUE_PARSE_LUT1/LUT2 only, specifies the custom type as defined at @ref customType */
3227 uint8_t customIndex; /**< For CONTINUE_PARSE_LUT1/LUT2 only, specifies the custom classification entry index */
3228 uint8_t pktType_emacCtrl; /**< validBitMap[t1] For destination SRIO, specify the 5-bit packet type toward SRIO
3229 For destination HOST, EMAC, specify the EMAC control @ref emcOutputCtrlBits to the network */
3230 paCmdInfo_t *pCmd; /**< validBitMap[t2] Pointer to the Command info to be executed prior to the packet forwarding.
3231 NULL: no commads
3232 @note only the following commands are supported within paRouteInfo_t and paRouteInfo2_t
3233 for ingress packets
3234 - pa_CMD_PATCH_DATA (up to two bytes only) (LUT2 only)
3235 - pa_CMD_CMDSET
3236 - pa_CMD_USR_STATS
3237 - pa_CMD_CMDSET_AND_USR_STATS
3238 @note the post-classification commands specified by the command set will be executed when the packets re-entering PASS
3239 from the QoS queue if priority-based routing is selected
3240 */
3241 uint8_t priorityType; /**< validBitMap[t3]: For Host only, specify priority-based and/or interfcae-based routing mode as
3242 * defined at @ref paRoutePriIntf_e
3243 */
3244 } paRouteInfo2_t;
3246 /**
3247 * @defgroup mrEntryCtrlInfo Multiroute Entry Control Info Bit Definitions
3248 * @ingroup palld_api_constants
3249 * @{
3250 *
3251 * @name Multiroute Entry Control Info Bit Definitions
3252 *
3253 * Bitmap definition of the ctrlBitField in @ref paMultiRouteEntry_t.
3254 */
3255 /*@{*/
3256 /**
3257 * @def pa_MULTI_ROUTE_DESCRIPTOR_ONLY
3258 * Control Info -- Set: Send descriptor without packet to the destination
3259 * Clear: Send both descriptor and the packet to the destination
3260 *
3261 */
3262 #define pa_MULTI_ROUTE_DESCRIPTOR_ONLY 0x01
3263 /*@{*/
3264 /**
3265 * @def pa_MULTI_ROUTE_REPLACE_SWINFO
3266 * Control Info -- Set: Replace the swInfo0 with the value provided here
3267 * Clear: Keep the original swInfo0
3268 *
3269 */
3270 #define pa_MULTI_ROUTE_REPLACE_SWINFO 0x02
3271 /*@}*/
3272 /** @} */
3274 /**
3275 * @ingroup palld_api_structures
3276 * @brief Packet Multi-route entry configuration
3277 *
3278 * @details paMultiRouteEntry_t is used to specify the physical routing of packets per multi-route entry.
3279 * It is only a subset of the Routing information defined at @ref paRouteInfo_t because those common
3280 * parameters such as swInfo0, swInfo1 must be already present in the packet descriptor.
3281 * There is no restriction of the destination as long as it is accessible through PKTDMA queue.
3282 */
3283 typedef struct {
3285 uint8_t ctrlBitfield; /**< Multi-Routing control information as defined at @ref mrEntryCtrlInfo */
3286 uint8_t flowId; /**< For host, specifies the CPPI flow which defines the free queues are used for receiving packets */
3287 uint16_t queue; /**< For host, specifies the destination queue */
3288 uint32_t swInfo0; /**< Placed in SwInfo0 for packets to host */
3290 } paMultiRouteEntry_t;
3292 /**
3293 * @defgroup paMultiRouteModes Multi-route group configuration mode
3294 * @ingroup palld_api_constants
3295 * @{
3296 *
3297 * @name Multi-route group configuration mode
3298 *
3299 * Definition of Multi-route group configuration mode supported in PA sub-system
3300 */
3301 /** @ingroup paMultiRouteModes */
3302 /*@{*/
3303 typedef enum {
3304 pa_MULTI_ROUTE_MODE_CONFIG = 0, /**< Add or reconfigure the multi-route group */
3305 pa_MULTI_ROUTE_MODE_RESET /**< Delete the multi-route group */
3306 } paMultiRouteModes_e;
3307 /*@}*/
3308 /** @} */
3310 /**
3311 * @defgroup paCrcSizes PA CRC Sizes
3312 * @ingroup palld_api_constants
3313 * @{
3314 *
3315 * @name CRC Sizes
3316 *
3317 * Definition of CRC sizes supported in PA sub-system
3318 */
3319 /** @ingroup paCrcSizes */
3320 /*@{*/
3321 typedef enum {
3322 pa_CRC_SIZE_8 = 0, /**< 8-bit CRC */
3323 pa_CRC_SIZE_16, /**< 16-bit CRC */
3324 pa_CRC_SIZE_24, /**< 24-bit CRC */
3325 pa_CRC_SIZE_32 /**< 32-bit CRC */
3326 } paCrcSizes_e;
3327 /*@}*/
3328 /** @} */
3330 /**
3331 * @defgroup crcConfigCtrlInfo CRC Engine Configuration Control Info Bit Definitions
3332 * @ingroup palld_api_constants
3333 * @{
3334 *
3335 * @name CRC Engine Configuration Control Info Bit Definitions
3336 *
3337 * Bitmap definition of the ctrlBitField in @ref paCrcConfig_t.
3338 */
3339 /*@{*/
3340 /**
3341 * @def pa_CRC_CONFIG_RIGHT_SHIFT
3342 * Control Info -- Set: Right shift CRC (b0 to b7)
3343 * Clear: Left shift CRC (b7 to b0)
3344 */
3345 #define pa_CRC_CONFIG_RIGHT_SHIFT 0x0001
3346 /**
3347 * @def pa_CRC_CONFIG_INVERSE_RESULT
3348 * Control Info -- Set: a 'NOT' operation is applied to the final CRC result
3349 */
3350 #define pa_CRC_CONFIG_INVERSE_RESULT 0x0002
3351 /*@}*/
3352 /** @} */
3354 /**
3355 * @ingroup palld_api_structures
3356 * @brief CRC Engine configuration
3357 *
3358 * @details paCrcConfig_t is used to configure the CRC engines within the PA sub-system.
3359 * There is one CRC engine connected to each PDSP in the PA sub-system. It will
3360 * be used to perform CRC operation required by some network protocol such as
3361 * SCTP and/or the user-specified CRC command. It only supports one type of CRC
3362 * per configuration.
3363 *
3364 * @note Only one type of CRC calcualtion is supported by one CRC engine per configuration.
3365 * It is the responsibility of the module user to configure the specific CRC engine by
3366 * calling @ref Pa_configCrcEngine.
3367 */
3369 typedef struct {
3371 uint16_t ctrlBitfield; /**< CRC configuration control information as defined at @ref crcConfigCtrlInfo */
3372 paCrcSizes_e size; /**< CRC sizes as defined at @ref paCrcSizes_e */
3373 uint32_t polynomial; /**< Specify the CRC polynomial in the format of 0xabcdefgh. For example,
3374 x32+x28+x27+x26+x25+x23+x22+x20+x19+x18+x14+x13+x11+x10+x9+x8+x6+1
3375 ==> 0x1EDC6F41
3376 x16+x15+x2+1 ==>0x80050000 */
3377 uint32_t initValue; /**< CRC initial value */
3378 } paCrcConfig_t;
3381 /**
3382 * @defgroup timestampScalerFactor Timestamp Scaler Factor
3383 * @ingroup palld_api_constants
3384 * @{
3385 *
3386 * @name Timestamp Scaler Factor
3387 *
3388 * Definition of PA timestamp scaler factor supported in PA sub-system
3389 *
3390 * @note pa_TIMESTAMP_SCALER_FACTOR_1 is not supported. It is defined here
3391 * for reference purpose.
3392 */
3393 /** @ingroup timestampScalerFactor */
3394 /*@{*/
3395 typedef enum {
3396 pa_TIMESTAMP_SCALER_FACTOR_1 = -1,
3397 pa_TIMESTAMP_SCALER_FACTOR_2 = 0,
3398 pa_TIMESTAMP_SCALER_FACTOR_4,
3399 pa_TIMESTAMP_SCALER_FACTOR_8,
3400 pa_TIMESTAMP_SCALER_FACTOR_16,
3401 pa_TIMESTAMP_SCALER_FACTOR_32,
3402 pa_TIMESTAMP_SCALER_FACTOR_64,
3403 pa_TIMESTAMP_SCALER_FACTOR_128,
3404 pa_TIMESTAMP_SCALER_FACTOR_256,
3405 pa_TIMESTAMP_SCALER_FACTOR_512,
3406 pa_TIMESTAMP_SCALER_FACTOR_1024,
3407 pa_TIMESTAMP_SCALER_FACTOR_2048,
3408 pa_TIMESTAMP_SCALER_FACTOR_4096,
3409 pa_TIMESTAMP_SCALER_FACTOR_8192
3410 } paTimestampScalerFactor_e;
3411 /*@}*/
3412 /** @} */
3414 /**
3415 * @ingroup palld_api_structures
3416 * @brief Timestamp configuration
3417 *
3418 * @details paTimestampConfig_t is used to configure the timer which is used to generate timestamp in
3419 * the PA sub-system.
3420 * @verbatim
3421 The 16-bit timer connected to PDSP0 is reserved for timestamp generation.
3422 The timestamp will be 0 until the timer is enabled.
3423 The timestamp unit is equal to (the scaler factor)/350 us.
3424 @endverbatim
3425 *
3426 * @note: The PDSP timer does not support pa_TIMESTAMP_SCALER_FACTOR_1.
3427 * The timer will be disabled if unspported scaler factor is used.
3428 */
3430 typedef struct {
3431 uint16_t enable; /**< Enable/Disable(1/0) the timestamp generation */
3432 paTimestampScalerFactor_e factor; /**< Timestamp scaler factor as defined at @ref timestampScalerFactor */
3433 } paTimestampConfig_t;
3435 /**
3436 * @defgroup paUsrStatsTypes PA User-defined Ststaistics Counter Types
3437 * @ingroup palld_api_constants
3438 * @{
3439 *
3440 * @name User-defined Ststaistics Counter Types
3441 *
3442 * Definition of Counter types of the User-defined Statistics
3443 */
3444 /** @ingroup paUsrStatsTypes */
3445 /*@{*/
3446 typedef enum {
3447 pa_USR_STATS_TYPE_PACKET = 0, /**< Packet Counter */
3448 pa_USR_STATS_TYPE_BYTE, /**< Byte Counter */
3449 pa_USR_STATS_TYPE_DISABLE /**< Counter to be disabled */
3450 } paUsrStatsTypes_e;
3451 /*@}*/
3452 /** @} */
3455 /**
3456 * @ingroup palld_api_structures
3457 * @brief User-defined statistics counter entry configuration information
3458 *
3459 * @details paUsrStatsCounterEntryConfig_t defines the operation parameters of each user-defined statistics.
3460 */
3462 typedef struct {
3463 uint16_t cntIndex; /**< Index of the counter */
3464 uint16_t cntLnk; /**< Index of the next level counter. 0xFFFF: No linking counter */
3465 paUsrStatsTypes_e cntType; /**< Counter type (packet counter */
3466 } paUsrStatsCounterEntryConfig_t;
3468 /**
3469 * @def pa_USR_STATS_LNK_END
3470 * Indicate that there is no next layer counter
3471 */
3472 #define pa_USR_STATS_LNK_END 0xFFFF
3475 /**
3476 * @defgroup usrStatsCounterConfigCtrlInfo User-defined Statistics Counter Configuration Control Info Bit Definitions
3477 * @ingroup palld_api_constants
3478 * @{
3479 *
3480 * @name User-defined Statistics Counter Configuration Control Info Bit Definitions
3481 *
3482 * Bitmap definition of the ctrlBitField in @ref paUsrStatsCounterConfig_t
3483 */
3484 /*@{*/
3485 /**
3486 * @def pa_USR_STATS_CONFIG_RESET
3487 * Control Info -- Set: Reset all counter control blocks to its default setting (packet counter without link to the next layer)
3488 */
3489 #define pa_USR_STATS_CONFIG_RESET 0x0001
3490 /*@}*/
3491 /** @} */
3493 /**
3494 * @ingroup palld_api_structures
3495 * @brief User-defined statistics counter configuration information
3496 *
3497 * @details paUsrStatsCounterConfig_t contains an array of the entry configuration information.
3498 */
3500 typedef struct {
3501 uint16_t ctrlBitfield; /**< User-defined statistics counter configuration control information as defined at @ref usrStatsCounterConfigCtrlInfo */
3502 uint16_t numCnt; /**< Number of counters to be configured */
3503 paUsrStatsCounterEntryConfig_t* cntInfo; /**< Array of counter configuration as specified at @ref paUsrStatsCounterEntryConfig_t */
3504 } paUsrStatsCounterConfig_t;
3506 /**
3507 * @ingroup palld_api_structures
3508 * @brief User-defined statistics configuration information
3509 *
3510 * @details paUsrStatsConfigInfo_t is used to perform user-defined statistics related configuration. It is used by
3511 * API function @ref Pa_configUsrStats.
3512 */
3513 typedef struct {
3514 paUsrStatsCounterConfig_t* pCntCfg; /**< Pointer to the user-defined statistics counter configuration. */
3515 } paUsrStatsConfigInfo_t;
3517 /**
3518 * @defgroup usrStatsAllocCtrlInfo User-defined Statistics Allocation Control Info Bit Definitions
3519 * @ingroup palld_api_constants
3520 * @{
3521 *
3522 * @name User-defined Statistics Allocation Control Info Bit Definitions
3523 *
3524 * Bitmap definition of the ctrlBitField in @ref paUsrStatsAlloc_t
3525 */
3526 /*@{*/
3527 /**
3528 * @def pa_USR_STATS_ALLOC_64B_CNT
3529 * Control Info -- Set: Allocate a 64-bit counter
3530 * Clear: Allocate a 32-bit counter
3531 */
3532 #define pa_USR_STATS_ALLOC_64B_CNT 0x0001
3534 /**
3535 * @def pa_USR_STATS_ALLOC_CNT_PRESENT
3536 * Control Info -- Set: Counter index is provided. Need to verify whether the counter index is valid.
3537 * Clear: Counter index is not present. Need to allocate one.
3538 */
3539 #define pa_USR_STATS_ALLOC_CNT_PRESENT 0x0002
3541 /*@}*/
3542 /** @} */
3545 /**
3546 * @ingroup palld_api_structures
3547 * @brief User-defined statistics Allocation information
3548 *
3549 * @details paUsrStatsAlloc_t defines the user-defined statistic allocation parameters which are used to specify
3550 * the charistics of the counter to be allocated or verified.
3551 */
3553 typedef struct {
3554 uint16_t ctrlBitfield; /**< User-defined statistics allocation control information as defined at @ref usrStatsAllocCtrlInfo */
3555 uint16_t cntIndex; /**< Index of the counter */
3556 } paUsrStatsAlloc_t;
3559 /**
3560 * @defgroup paSubSysStates PA Sub-system Queries and States
3561 * @ingroup palld_api_constants
3562 * @{
3563 *
3564 * @name PA Sub-system Queries and States
3565 *
3566 * PA Sub-system reset state and query arguments used by API function @ref Pa_resetControl
3567 */
3568 /* @{ */
3569 /**
3570 * @def pa_STATE_RESET
3571 * The Sub-system is in reset
3572 */
3573 #define pa_STATE_RESET 0 /**< Sub-system state reset */
3575 /**
3576 * @def pa_STATE_ENABLE
3577 * The Sub-system state is enabled
3578 */
3579 #define pa_STATE_ENABLE 1 /**< Sub-system state enable */
3581 /**
3582 * @def pa_STATE_QUERY
3583 * Query the Sub-system state
3584 */
3585 #define pa_STATE_QUERY 2 /**< Query the Sub-system state */
3587 /**
3588 * @def pa_STATE_INCONSISTENT
3589 * The Sub-system state is partially enabled
3590 */
3591 #define pa_STATE_INCONSISTENT 3 /**< Sub-system is partially enabled */
3593 /**
3594 * @def pa_STATE_INVALID_REQUEST
3595 * Invalid state command to the Sub-system
3596 */
3597 #define pa_STATE_INVALID_REQUEST 4 /**< Invalid state command to the Sub-system */
3599 /**
3600 * @def pa_STATE_ENABLE_FAILED
3601 * The Sub-system did not respond after restart
3602 */
3603 #define pa_STATE_ENABLE_FAILED 5 /**< The Sub-system did not respond after restart */
3605 /**
3606 * @def pa_STATE_RESOURCE_USE_DENIED
3607 * Resource manager denied the firmware use
3608 */
3609 #define pa_STATE_RESOURCE_USE_DENIED 6 /**< Resource manager denied the firmware use */
3611 /* @} */
3612 /** @} */
3615 /**
3616 * @ingroup palld_api_structures
3617 * @brief paSState_t defines the operating state of the packet accelerator sub-system
3618 *
3619 * @details The values in @ref paSubSysStates are used both to set the state of the packet accelerator
3620 * sub-system (pa_STATE_RESET and pa_STATE_ENABLE) as well as show the current state
3621 * of the system (all values).
3622 */
3623 typedef int paSSstate_t;
3625 /**
3626 * @ingroup palld_api_structures
3627 * @brief PA Classify1 Statistics Structure
3628 *
3629 * @details This structures define the PA Classify1-specific statistics provided
3630 * with API function @ref Pa_formatStatsReply ().
3631 */
3632 typedef struct paClassify1Stats_s {
3634 uint32_t nPackets; /**< Number of packets entering Classify1 PDSPs */
3635 uint32_t nIpv4Packets; /**< Number of IPv4 packets */
3636 uint32_t nIpv4PacketsInner; /**< Number of Inner IPv4 packets */
3637 uint32_t nIpv6Packets; /**< Number of IPv6 packets */
3638 uint32_t nIpv6PacketsInner; /**< Number of Inner IPv6 packets */
3639 uint32_t nCustomPackets; /**< Number of custom LUT1 packets */
3640 uint32_t nSrioPackets; /**< Number of SRIO packets */
3641 uint32_t nLlcSnapFail; /**< Number of packets with corrupt LLC Snap */
3642 uint32_t nTableMatch; /**< Number of packets with table match found */
3643 uint32_t nNoTableMatch; /**< Number of packets without table match found */
3644 uint32_t nIpFrag; /**< Number of Ingress fragmented IP packets */
3645 uint32_t nIpDepthOverflow; /**< Number of packets with too many IP layers */
3646 uint32_t nVlanDepthOverflow; /**< Number of packets with too many VLANs */
3647 uint32_t nGreDepthOverflow; /**< Number of packets with too many GREs */
3648 uint32_t nMplsPackets; /**< Number of MPLS packets */
3649 uint32_t nParseFail; /**< Number of packets which can not be parsed */
3650 uint32_t nInvalidIPv6Opt; /**< Number of IPv6 packets which contains invalid IPv6 options */
3651 uint32_t nTxIpFrag; /**< Number of Egress fragmented IP packets */
3652 uint32_t nSilentDiscard; /**< Number of packets dropped */
3653 uint32_t nInvalidControl; /**< Number of packet received with invalid control information */
3654 uint32_t nInvalidState; /**< Number of times the PA detected an illegal state and recovered */
3655 uint32_t nSystemFail; /**< Number of times the PA detected an unrecoverable state and restarted */
3657 } paClassify1Stats_t;
3659 /**
3660 * @ingroup palld_api_structures
3661 * @brief PA Classify2 Statistics Structure
3662 *
3663 * @details This structures define the PA Classify2-specific statistics provided
3664 * with API function @ref Pa_formatStatsReply ().
3665 */
3666 typedef struct paClassify2Stats_s {
3668 uint32_t nPackets; /**< Number of packets entering Classify2 PDSP */
3669 uint32_t nUdp; /**< Number of UDP packets */
3670 uint32_t nTcp; /**< Number of TCP packets */
3671 uint32_t nCustom; /**< Number of custom LUT2 packets */
3672 uint32_t reserved3; /**< Reserved for future use */
3673 uint32_t reserved4; /**< Reserved for future use */
3674 uint32_t nSilentDiscard; /**< Number of packets dropped */
3675 uint32_t nInvalidControl; /**< Number of packet received with invalid control information */
3677 } paClassify2Stats_t;
3679 /**
3680 * @ingroup palld_api_structures
3681 * @brief PA Modifier Statistics Structure
3682 *
3683 * @details This structures define the PA Modifier-specific statistics provided
3684 * with API function @ref Pa_formatStatsReply ().
3685 */
3686 typedef struct paModifyStats_s {
3687 uint32_t nCommandFail; /**< Number of invalid commands */
3689 } paModifyStats_t;
3691 /**
3692 * @ingroup palld_api_structures
3693 * @brief PA Common Statistics Structure
3694 *
3695 * @details This structures define the PA Common statistics provided
3696 * with API function @ref Pa_formatStatsReply ().
3697 */
3698 typedef struct paCommonStats_s {
3700 uint32_t reserved5; /**< Reserved for future use */
3702 } paCommonStats_t;
3704 /**
3705 * @ingroup palld_api_structures
3706 * @brief PA System Statistics Structure
3707 *
3708 * @details This structures define the PA System statistics provided
3709 * with API function @ref Pa_formatStatsReply ().
3710 */
3712 typedef struct paSysStats_s {
3714 paClassify1Stats_t classify1; /**< Classify1-specific statistics */
3715 paClassify2Stats_t classify2; /**< Classify2-specific statistics */
3716 paModifyStats_t modify; /**< Modifier-specific statistics */
3717 paCommonStats_t common; /**< Common statistics */
3719 } paSysStats_t;
3721 /**
3722 * @ingroup palld_api_structures
3723 * @brief PA User-defined Statistics Structure
3724 *
3725 * @details This structures define the PA User-defined statistics provided
3726 * with API function @ref Pa_requestUsrStats ().
3727 */
3729 typedef struct paUsrStats_s {
3731 uint64_t count64[pa_USR_STATS_MAX_64B_COUNTERS]; /**< Array of general purpose 64-bit counters */
3732 uint32_t count32[pa_USR_STATS_MAX_32B_COUNTERS]; /**< Array of general purpose 32-bit counters */
3734 } paUsrStats_t;
3736 /**
3737 * @ingroup palld_api_structures
3738 * @brief PA Timestamp Structure
3739 *
3740 * This structure defines the 48-bit timestamp provided upon request with @ref Pa_getTimestamp ().
3741 */
3742 typedef struct {
3743 uint32_t hi; /**< Upper 32 bits of the 48-bit PASS timestamp */
3744 uint16_t lo; /**< Lower 16 bits of the 48-bit PASS timestamp */
3745 } paTimestamp_t;
3748 /**
3749 * @defgroup paApiParamValidBits PA API Parameter Valid Bit Definitions
3750 * @ingroup palld_api_constants
3751 * @{
3752 *
3753 * @name PA API Parameter Valid Bit Definitions
3754 *
3755 * Bitmap definition of the validBitMap in @ref paParamDesc.
3756 */
3757 /*@{*/
3759 /**
3760 * @def pa_PARAM_VALID_LUTINST
3761 * - Set: Application specifies the LUT1 instance
3762 * - Clear: LLD determines the LUT1 instance based on other input parameters
3763 */
3764 #define pa_PARAM_VALID_LUTINST (1<<0)
3766 /**
3767 * @def pa_PARAM_VALID_INDEX
3768 * - Set: Application specifies the LUT1 index to insert this entry
3769 * - Clear: PASS determines where in the LUT1 table to insert this entrry
3770 */
3771 #define pa_PARAM_VALID_INDEX (1<<1)
3773 /**
3774 * @def pa_PARAM_VALID_PREVLINK
3775 * - Set: Previous link is valid and it should be used as part of classification criteria
3776 * - Claer: Previous link is inavlid
3777 */
3778 #define pa_PARAM_VALID_PREVLINK (1<<2)
3780 /**
3781 * @def pa_PARAM_VALID_NEXTLINK
3782 * - Set: The specified virtual link in stead of the physical link should be used as part of
3783 * classification criteria at the next stage
3784 * - Clear: Use physical link at the next stage
3785 */
3786 #define pa_PARAM_VALID_NEXTLINK (1<<3)
3788 /* @} */ /* ingroup */
3789 /** @} */
3792 /**
3793 * @ingroup palld_api_structures
3794 * @brief PA API parameters structure
3795 *
3796 * @details This structure define the common parameters of the next generation APIs such as
3797 * @ref Pa_addMac2 and @ref Pa_addIp2. This structure includes a validBitMap of
3798 * optional parameters so that it can evolve while maintaining backward-compatibility.
3799 *
3800 * The parameter validBitMap specifies which optional parameters are valid
3801 * 1: used; 0: not used.
3802 *
3803 */
3804 typedef struct {
3805 uint32_t validBitMap; /**< 32-bit bitmap corresponding to usage of each optional field */
3806 int lutInst; /**< validBitMap[t0] Specify which LUT1 (0-2) should be used. */
3807 int index; /**< validBitMap[t1] Specify the index of the LUT1 entry (0-63).*/
3808 paLnkHandle_t prevLink; /**< validBitMap[t2] An optional L2 or L3 handle, or virtual link handle */
3809 paLnkHandle_t nextLink; /**< validBitMap[t3] An optional virtual link handle */
3810 paRouteInfo2_t *routeInfo; /**< Where to send a packet that matches */
3811 paRouteInfo2_t *nextRtFail; /**< Where to send a packet that matches, but fails to match any entry at the next classification stage */
3812 } paParamDesc;
3814 /**
3815 * @ingroup palld_api_functions
3816 * @brief Pa_addSrio adds a SRIO entry to the L2 table
3817 *
3818 * @details This function is used to add or replace an entry into the L2 table (see @ref netlayers).
3819 * A new entry is added if the SRIO configuration info is unique in the modules handle table.
3820 * If the value is not unique then the routing information for the existing entry is changed to
3821 * the values provided in the function.
3822 *
3823 * On return the command buffer (cmd) contains a formatted command for the sub-system. The
3824 * destination for the command is provided in cmdDest. The module user must send the formatted
3825 * command to the sub-system. The sub-system will generate a reply
3826 * and this reply must be sent back to this module through the API @ref Pa_forwardResult.
3827 *
3828 * This command as well as @ref Pa_addIp operate with a strong dependence on entry order.
3829 * See section table @ref order for a description on the operation of the sub-system and
3830 * table entry ordering.
3831 *
3832 * @param[in] iHandle The driver instance handle
3833 * @param[in] index Specify the index of the LUT1 entry (0-63). Set to pa_LUT1_INDEX_NOT_SPECIFIED if not specified
3834 * @param[in] srioInfo Value @ref paSrioInfo_t
3835 * @param[in] nextHdr The next header type to be parsed following the SRIO classification
3836 * Refer to @ref NextHeaderTypes for all supported protocols
3837 * Set to pa_HDR_TYPE_UNKNOWN if no further prasing is required
3838 * @param[in] nextHdrOffset Offset to the next header from the beginning of the packet
3839 * @param[in] routeInfo Match packet routing information
3840 * @param[in] nextRtFail Routing information for subsequent match failures
3841 * @param[out] handle Pointer to L2 Handle
3842 * @param[out] cmd Where the created command is placed
3843 * @param[in,out] cmdSize Input the size of cmd buffer, on output the actual size used. @ref cmdMinBufSize
3844 * @param[in] reply Where the sub-system sends the command reply
3845 * @param[out] cmdDest Value (@ref cmdTxDest)
3846 * @retval Value (@ref ReturnValues)
3847 * @pre A driver instance must be created and tables initialized
3848 *
3849 * @note No table entry validation will be proformed if the LUT1 index is specified at this function
3850 *
3851 */
3853 paReturn_t Pa_addSrio ( Pa_Handle iHandle,
3854 int index,
3855 paSrioInfo_t *srioInfo,
3856 uint16_t nextHdr,
3857 uint16_t nextHdrOffset,
3858 paRouteInfo_t *routeInfo,
3859 paRouteInfo_t *nextRtFail,
3860 paHandleL2L3_t *handle,
3861 paCmd_t cmd,
3862 uint16_t *cmdSize,
3863 paCmdReply_t *reply,
3864 int *cmdDest);
3866 /**
3867 * @ingroup palld_api_functions
3868 * @brief Pa_addMac adds a mac address to the L2 table
3869 *
3870 * @details This function is used to add or replace an entry into the L2 table (see @ref netlayers).
3871 * A new entry is added if the MAC configuration info is unique in the modules handle table. If
3872 * the value is not unique then the routing information for the existing entry is changed to
3873 * the values provided in the function.
3874 *
3875 * L2 values that are not to be used for packet routing are set to 0.
3876 *
3877 * On return the command buffer (cmd) contains a formatted command for the sub-system. The
3878 * destination for the command is provided in cmdDest. The module user must send the formatted
3879 * command to the sub-system. The sub-system will generate a reply
3880 * and this reply must be sent back to this module through the @ref Pa_forwardResult API.
3881 *
3882 * This command as well as @ref Pa_addIp operate with a strong dependence on entry order.
3883 * See section table @ref order for a description on the operation of the sub-system and
3884 * table entry ordering.
3885 *
3886 *
3887 * @param[in] iHandle The driver instance handle
3888 * @param[in] index Specify the index of the LUT1 entry (0-63). Set to pa_LUT1_INDEX_NOT_SPECIFIED if not specified
3889 * @param[in] ethInfo Value @ref paEthInfo_t
3890 * @param[in] routeInfo Match packet routing information
3891 * @param[in] nextRtFail Routing information for subsequent match failures
3892 * @param[out] handle Pointer to L2 Handle
3893 * @param[out] cmd Where the created command is placed
3894 * @param[in,out] cmdSize Input the size of cmd buffer, on output the actual size used. @ref cmdMinBufSize
3895 * @param[in] reply Where the sub-system sends the command reply
3896 * @param[out] cmdDest Value (@ref cmdTxDest)
3897 * @retval Value (@ref ReturnValues)
3898 * @pre A driver instance must be created and tables initialized
3899 *
3900 * @note No table entry validation will be proformed if the LUT1 index is specified at this function
3901 *
3902 */
3904 paReturn_t Pa_addMac ( Pa_Handle iHandle,
3905 int index,
3906 paEthInfo_t *ethInfo,
3907 paRouteInfo_t *routeInfo,
3908 paRouteInfo_t *nextRtFail,
3909 paHandleL2L3_t *handle,
3910 paCmd_t cmd,
3911 uint16_t *cmdSize,
3912 paCmdReply_t *reply,
3913 int *cmdDest);
3915 /**
3916 * @ingroup palld_api_functions
3917 * @brief Pa_addMac2 adds a mac address to the L2 table
3918 *
3919 * @details Pa_addMac2 is the next generation of API to replace @ref Pa_addMac eventually. This new API
3920 * covers the entire functionality of Pa_addMac and it is designed to support more features
3921 * while maintain backward-compatibility over time.
3922 *
3923 * @param[in] iHandle The driver instance handle
3924 * @param[in] ethInfo Value @ref paEthInfo2_t
3925 * @param[in] params Common API parameters @ref paParamDesc
3926 * @param[out] retHandle Pointer to L2 Handle
3927 * @param[out] cmd Where the created command is placed
3928 * @param[in,out] cmdSize Input the size of cmd buffer, on output the actual size used. @ref cmdMinBufSize
3929 * @param[in] reply Where the sub-system sends the command reply
3930 * @param[out] cmdDest Value (@ref cmdTxDest)
3931 * @retval Value (@ref ReturnValues)
3932 * @pre A driver instance must be created and tables initialized
3933 *
3934 */
3935 paReturn_t Pa_addMac2 ( Pa_Handle iHandle,
3936 paEthInfo2_t *ethInfo, /**< Value @ref paEthInfo2_t */
3937 paParamDesc *params,
3938 paLnkHandle_t *retHandle, /**< Pointer to the returned L2 handle */
3939 paCmd_t cmd,
3940 uint16_t *cmdSize,
3941 paCmdReply_t *reply,
3942 int *cmdDest
3943 );
3945 /**
3946 * @ingroup palld_api_functions
3947 * @brief Pa_delHandle deletes a MAC/SRIO or IP handle
3948 *
3949 * @details This function is used to remove an entry from the sub-system L2 or L3 (LUT1) lookup (see @ref netlayers).
3950 * When a handle is deleted it can create stale handles. For example, an L3 handle can reference
3951 * an L2 handle, and an L4 handle can reference an L3 handle. The module does not check for
3952 * references to a stale handle, the module user is responsible for maintaining reference coherency.
3953 * It is recommended that the handle should not be deleted if the API function @ref Pa_getHandleRefCount
3954 * returns non-zero reference count.
3955 *
3956 * @param[in] iHandle The driver instance handle
3957 * @param[in] handle Pointer to the l2/l3 handle to delete
3958 * @param[out] cmd Where the created command is placed
3959 * @param[in] cmdSize The size of the cmd buffer
3960 * @param[in] reply Where the sub-system sends the command reply
3961 * @param[out] cmdDest Value (@ref cmdTxDest)
3962 * @retval Value (@ref ReturnValues)
3963 * @pre A driver instance must be created and tables initialized
3964 */
3965 paReturn_t Pa_delHandle (Pa_Handle iHandle,
3966 paHandleL2L3_t *handle,
3967 paCmd_t cmd,
3968 uint16_t *cmdSize,
3969 paCmdReply_t *reply,
3970 int *cmdDest );
3972 /**
3973 * @ingroup palld_api_functions
3974 * @brief Pa_delL4Handle deletes a UDP/TCP/GTPU/CustomLUT2 handle
3975 *
3976 * @details This function is used to remove an entry from the sub-system L4 (LUT2) handle entry.
3977 *
3978 * @param[in] iHandle The driver instance handle
3979 * @param[in, out] handle Pointer to the L4 handle to delete
3980 * @param[out] cmd Where the created command is placed
3981 * @param[in] cmdSize The size of the cmd buffer
3982 * @param[in] reply Where the sub-system sends the reply
3983 * @param[out] cmdDest Value (@ref cmdTxDest)
3984 * @retval Value (@ref ReturnValues)
3985 * @pre A driver instance must be created and tables initialized
3986 */
3987 paReturn_t Pa_delL4Handle (Pa_Handle iHandle,
3988 paHandleL4_t handle,
3989 paCmd_t cmd,
3990 uint16_t *cmdSize,
3991 paCmdReply_t *reply,
3992 int *cmdDest );
3995 /**
3996 * @ingroup palld_api_functions
3997 * @brief Pa_addIp adds an IP address to the L3 table
3998 *
3999 * @details This function is used to add or replace an entry in the L3 table (see @ref netlayers).
4000 * A new entry is added if the IP configuration info is unique in the modules handle table.
4001 * If the value is not unique then the routing information for the existing entry is changed
4002 * to the values provided in the function.
4003 *
4004 * The LLD will determine where this entry is added based on following rules
4005 * - If there is no previous link or the previous link is a L2 (MAC/SRIO) entry, this entry will be
4006 * added into LUT1_1
4007 * - If the previous link is L3 (IP/Custom LUT1), this entry will be added into LUT1_2
4008 *
4009 * The module user can overwrite the default rules by specifying the desired LUT1 instance.
4010 *
4011 * The PASS will determine which entry of the specified LUT1 table is used for this entry based on
4012 * its internal algorithm if the module user does not specify the LUT1 index.
4013 *
4014 * L3 values that are used for packet routing should be set as described in @ref paIpInfo_t.
4015 *
4016 * The @ref paHandleL2L3_t prevLink is used to link this entry to an L2 or L3 entry already made
4017 * by a call to @ref Pa_addMac or Pa_addIp. If the link is enabled then a packet will match the IP
4018 * information provided in ipInfo only if the same packet has already matched at the L2 level as
4019 * described by prevLink. To disable linking the value of prevLink is set to NULL.
4020 *
4021 * On return the command buffer (cmd) contains a formatted command for the sub-system. The
4022 * destination for the command is provided in cmdDest. The module user must send the formatted
4023 * command to the sub-system. The sub-system will generate a reply and this reply must be
4024 * sent back to this module through the API @ref Pa_forwardResult.
4025 *
4026 * This command as well as @ref Pa_addMac operates with a strong dependence on entry order.
4027 * See section table @ref order for a description on the operation of the sub-system and
4028 * table entry ordering.
4029 *
4030 *
4031 *
4032 * @param[in] iHandle The driver instance handle
4033 * @param[in] lutInst Specify which LUT1 (0-2) should be used. Set to pa_LUT_INST_NOT_SPECIFIED if not specified
4034 * @param[in] index Specify the index of the LUT1 entry (0-63). Set to pa_LUT1_INDEX_NOT_SPECIFIED if not specified
4035 * @param[in] ipInfo Value @ref paIpInfo_t
4036 * @param[in] prevLink An optional L2 or L3 handle
4037 * @param[in] routeInfo Where to send a packet that matches
4038 * @param[in] nextRtFail Where to send a packet that matches, but later fails
4039 * @param[out] retHandle Pointer to the returned L3 handle
4040 * @param[out] cmd Buffer where the PASS command is created
4041 * @param[in] cmdSize The size of the cmd buffer
4042 * @param[in] reply Where the response to the PASS command is routed
4043 * @param[out] cmdDest Value (@ref cmdTxDest)
4044 * @retval Value (@ref ReturnValues)
4045 * @pre A driver instance must be created and tables initialized
4046 *
4047 * @note No table entry validation will be proformed if the LUT1 index is specified at this function
4048 *
4049 */
4050 paReturn_t Pa_addIp ( Pa_Handle iHandle,
4051 int lutInst,
4052 int index,
4053 paIpInfo_t *ipInfo,
4054 paHandleL2L3_t prevLink,
4055 paRouteInfo_t *routeInfo,
4056 paRouteInfo_t *nextRtFail,
4057 paHandleL2L3_t *retHandle,
4058 paCmd_t cmd,
4059 uint16_t *cmdSize,
4060 paCmdReply_t *reply,
4061 int *cmdDest );
4063 /**
4064 * @ingroup palld_api_functions
4065 * @brief Pa_addIp2 adds an IP address to the L3 table
4066 *
4067 * @details Pa_addIp2 is the next generation of API to replace @ref Pa_addIp eventually. This new API
4068 * covers the entire functionality of Pa_addIP and it is designed to support more features
4069 * while maintain backward-compatibility over time.
4070 *
4071 * @param[in] iHandle The driver instance handle
4072 * @param[in] ipInfo Value @ref paIpInfo2_t
4073 * @param[in] params Common API parameters @ref paParamDesc
4074 * @param[out] retHandle Pointer to L3 Handle
4075 * @param[out] cmd Where the created command is placed
4076 * @param[in,out] cmdSize Input the size of cmd buffer, on output the actual size used. @ref cmdMinBufSize
4077 * @param[in] reply Where the sub-system sends the command reply
4078 * @param[out] cmdDest Value (@ref cmdTxDest)
4079 * @retval Value (@ref ReturnValues)
4080 * @pre A driver instance must be created and tables initialized
4081 */
4082 paReturn_t Pa_addIp2 ( Pa_Handle iHandle,
4083 paIpInfo2_t *ipInfo,
4084 paParamDesc *params,
4085 paLnkHandle_t *retHandle,
4086 paCmd_t cmd,
4087 uint16_t *cmdSize,
4088 paCmdReply_t *reply,
4089 int *cmdDest
4090 );
4092 /**
4093 * @defgroup VirtualLnkType Virtual Link types
4094 * @ingroup palld_api_constants
4095 * @{
4096 *
4097 * @name VirtualLnkTypes
4098 * @brief Defines the virtual link destination type
4099 *
4100 * @note The packet accelerator module supports linking to
4101 * virtual links at OuterIp only at the moment.
4102 *
4103 */
4104 /* @{ */
4105 /**
4106 * @def pa_VIRTUAL_LNK_TYPE_MAC
4107 * MAC
4108 */
4109 #define pa_VIRTUAL_LNK_TYPE_MAC 0
4111 /**
4112 * @def pa_VIRTUAL_LNK_TYPE_OUTER_IP
4113 * Outer IP
4114 */
4115 #define pa_VIRTUAL_LNK_TYPE_OUTER_IP 1
4117 /**
4118 * @def pa_VIRTUAL_LNK_TYPE_INNER_IP
4119 * Inner IP
4120 */
4121 #define pa_VIRTUAL_LNK_TYPE_INNER_IP 2
4123 /* @} */
4124 /** @} */
4126 /**
4127 * @ingroup palld_api_functions
4128 * @brief Pa_addVirtualLink allocates a new virtual link within the PA instance
4129 *
4130 * @details This function is called to request a new virtual link
4131 *
4132 * @param[in] iHandle The driver instance handle
4133 * @param[in,out] vlinkHdl Pointer to virtual link handle
4134 * @param[in] lnkType Value (@ref VirtualLnkType)
4135 * @retval Value (@ref ReturnValues)
4136 * @pre A driver instance must be created and tables initialized
4137 *
4138 */
4139 paReturn_t Pa_addVirtualLink(Pa_Handle iHandle,
4140 paLnkHandle_t *vlinkHdl,
4141 int8_t lnkType
4142 );
4144 /**
4145 * @ingroup palld_api_functions
4146 * @brief Pa_delVirtualLink frees the specified virtual link within the PA instance
4147 *
4148 * @details This function is used to remove a virtual link
4149 *
4150 * @param[in] iHandle The driver instance handle
4151 * @param[in,out] vlinkHdl Pointer to virtual link handle
4152 * @retval Value (@ref ReturnValues)
4153 * @pre A driver instance must be created and tables initialized
4154 *
4155 */
4156 paReturn_t Pa_delVirtualLink(Pa_Handle iHandle,
4157 paLnkHandle_t *vlinkHdl
4158 );
4160 /**
4161 * @ingroup palld_api_functions
4162 * @brief Pa_allocUsrStats allocates or verifies a set of user-defined statistics
4163 *
4164 * @details This function is called to request or verify a number of user-defined statistics.
4165 * The return value pa_RESOURCE_USE_DENIED will be used if there are not enough user-defined
4166 * statistics available or one of the provided counter indexes is not valid.
4167 *
4168 * @param[in] iHandle The driver instance handle
4169 * @param[in, out] pNumCnt In:Number of user-defined statistics requested; Out: Number of user-defined statistics allocated
4170 * @param[in, out] cntList Array of user-defined statistics allocation parameters
4171 * @retval Value (@ref ReturnValues)
4172 * @pre A driver instance must be created and tables initialized
4173 *
4174 * @note: This function is optional when the application owns the entire set of user-defined statistics or uses a set of
4175 * pre-allocated user-defined statistics. However, the PASS will verify the user-defined statistics list and may
4176 * return error code pa_RESOURCE_USE_DENIED if RM is enabled when API @ref Pa_configUsrStats, @ref Pa_requestUsrStatsList
4177 * and etc are invoked.
4178 */
4179 paReturn_t Pa_allocUsrStats(Pa_Handle iHandle,
4180 int *pNumCnt,
4181 paUsrStatsAlloc_t *cntList
4182 );
4184 /**
4185 * @ingroup palld_api_functions
4186 * @brief Pa_freeUsrStats free a set of user-defined statistics
4187 *
4188 * @details This function is called to free a set of user-defined statistics.
4189 *
4190 *
4191 * @param[in] iHandle The driver instance handle
4192 * @param[in] numCnt Number of user-defined statistics to be freed
4193 * @param[in] cntList Pointer to list of user-defined statistics to be freed
4194 * @retval Value (@ref ReturnValues)
4195 * @pre A driver instance must be created and tables initialized
4196 *
4197 * @note: This function is optional when the application owns the entire set of user-defined statistics or uses a set of
4198 * pre-allocated user-defined statistics.
4199 */
4200 paReturn_t Pa_freeUsrStats(Pa_Handle iHandle,
4201 int numCnt,
4202 uint16_t *cntList
4203 );
4205 /**
4206 * @defgroup paLut2PortSize LUT2 Port Size Values
4207 * @ingroup palld_api_constants
4208 * @{
4209 *
4210 * @name LUT2 Port Size Values
4211 * @brief Defines the LUT2 port size supported by PA.
4212 *
4213 * @details The PA LUT2 supports both 16-bit and 32-bit entry matching. It can be used to classify
4214 * based on the UDP/IP 16-bit destination port with or without upper layer link or the GTP-U
4215 * 32-bit Tunnel ID. No other Layer 4 or Layer 5 protocol is supported.
4216 */
4217 /* @{ */
4218 /**
4219 * @def pa_LUT2_PORT_SIZE_16
4220 * 16-bit port number such as UDP/TCP port
4221 *
4222 */
4223 #define pa_LUT2_PORT_SIZE_16 0
4225 /**
4226 * @def pa_LUT2_PORT_SIZE_32
4227 * 32-bit port number such as GTP-U Tunnel ID
4228 */
4229 #define pa_LUT2_PORT_SIZE_32 1
4231 /* @} */
4232 /** @} */
4235 /**
4236 * @ingroup palld_api_functions
4237 * @brief Pa_addPort adds a destination port to the L4 (LUT2) table
4238 *
4239 * @details This function is used to add an entry to the L4 (LUT2) table (see @ref netlayers). Only the
4240 * destination port can be set, along with a link to previous L3 handle
4241 * (see @ref Pa_addIp) through linkHandle.
4242 *
4243 * This module does not keep track of the L4 handles, so calling the function
4244 * a second time with the same destination port and link handle will simply replace the
4245 * previous entry. It is recommended to set the replace flag to indicate that this entry is
4246 * already at the LUT2 table. This feature may be used to change the routing information without
4247 * deleting and adding the matching port.
4248 * This API also initiates the atomic queue diversion operation, which means that the QMSS moves
4249 * the entries in the diverted queue to the destination queue, if the divertQ is specified and
4250 * fReplace flag is set. In this case, the PASS will complete the LUT2 update, wait for the queue
4251 * diversion to be complete and then resume processing incoming packets.
4252 * Unlike entries in the L2 and L3 table, the order of entry is not important.
4253 *
4254 * The type of transport header (TCP/UDP) is not specified here. If the type of transport
4255 * is part of the packet routing criteria it is specified in the protocol type field
4256 * in @ref paIpInfo_t in the call to @ref Pa_addIp.
4257 *
4258 * This function supports both 16-bit and 32-bit port specified by the parameter portSize.
4259 * However, there are the following restrictions for 32-bit ports
4260 * @verbatim
4261 1. The link to the previous LUT1 match can not be used so that the destID
4262 should be unique regressless of the previous L3 adddreses
4263 2. The 32-bit LUT2 lookup can not be mixed with the other TCP/UDP or custom LUT2 lookup.
4264 @endverbatim
4265 *
4266 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4267 * The destination for the command is provided in cmdDest. The module user must send the
4268 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4269 * must be sent back to this module through the @ref Pa_forwardResult API.
4270 *
4271 * @param[in] iHandle The driver instance handle
4272 * @param[in] portSize The input port size (@ref paLut2PortSize)
4273 * @param[in] destPort The destination TCP/UDP port
4274 * @param[in] linkHandle An L3 handle that is linked to the destination port
4275 * @param[in] fReplace Flag to indicate whether the entry exists
4276 * @param[in] divertQ The source queue for atomic queue diversion with LUT2 update
4277 * Set to pa_PARAMS_NOT_SPECIFIED if not specified
4278 * @param[in] routeInfo Where to send a packet that matches
4279 * @param[out] retHandle A blank handle where the return handle is placed
4280 * @param[out] cmd Buffer where the PASS command is created
4281 * @param[in] cmdSize The size of the cmd buffer
4282 * @param[out] reply Where the response to the PASS command is routed
4283 * @param[out] cmdDest Value (@ref cmdTxDest)
4284 * @retval Value (@ref ReturnValues)
4285 * @pre A driver instance must be created and tables initialized
4286 *
4287 * @note The linkHandle is mandatory for 16-bit TCP/UDP port or 32-bit GTPU port when pa_GTPU_CTRL_USE_LINK is set.
4288 * The linkHandle will be ignored for 32-bit GTPU port when pa_GTPU_CTRL_USE_LINK is cleared
4289 *
4290 */
4291 paReturn_t Pa_addPort ( Pa_Handle iHandle,
4292 int portSize,
4293 uint32_t destPort,
4294 paHandleL2L3_t linkHandle,
4295 uint16_t fReplace,
4296 uint16_t divertQ,
4297 paRouteInfo_t *routeInfo,
4298 paHandleL4_t retHandle,
4299 paCmd_t cmd,
4300 uint16_t *cmdSize,
4301 paCmdReply_t *reply,
4302 int *cmdDest );
4305 /**
4306 * @ingroup palld_api_functions
4307 * @brief Pa_setCustomLUT1 performs the global configuration for level 3 (LUT1) custom lookups
4308 *
4309 * @details This command is typically issued once per system and is used to configure the
4310 * PA for performing network layer 3 (LUT1) custom lookups.
4311 * It specifies the offset and byte masks which the PA
4312 * subsystem uses for parsing a packet that has entered custom LUT1
4313 * classification directed from the previous match route.
4314 * It also specifies the next header type and offset to be used for continuous
4315 * parsing
4316 *
4317 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4318 * The destination for the command is provided in cmdDest. The module user must send the
4319 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4320 * must be sent back to this module through the @ref Pa_forwardResult API.
4321 *
4322 * @param[in] iHandle The driver instance handle
4323 * @param[in] custIndex The level 3 (LUT1) custom index
4324 * @param[in] parseByteOffset Where the PA begins custom match (relative to the L3 start)
4325 * @param[in] nextHdr The next header type to be parsed following the custom header
4326 * Refer to @ref NextHeaderTypes for all supported protocols
4327 * Set to pa_HDR_TYPE_UNKNOWN if no further prasing is required
4328 * @param[in] nextHdrOffset Offset to the next header from the beginning of the custom header
4329 * @param[in] byteMasks The bitmap of bits in the parse that matter
4330 * @param[out] cmd Buffer where the PASS command is created
4331 * @param[in] cmdSize On entry the size of the cmd buffer, on exit the size of the command
4332 * @param[in] reply Where the response to the PASS command is routed
4333 * @param[out] cmdDest Value (@ref cmdTxDest)
4334 * @retval Value (@ref ReturnValues)
4335 * @pre A driver instance must be created and tables initialized
4336 *
4337 * @note There is up to @ref pa_MAX_CUSTOM_TYPES_LUT1 LUT1 custom types supported by PASS.
4338 */
4339 paReturn_t Pa_setCustomLUT1 ( Pa_Handle iHandle,
4340 uint16_t custIndex,
4341 uint16_t parseByteOffset,
4342 uint16_t nextHdr,
4343 uint16_t nextHdrOffset,
4344 uint8_t byteMasks[pa_NUM_BYTES_CUSTOM_LUT1],
4345 paCmd_t cmd,
4346 uint16_t *cmdSize,
4347 paCmdReply_t *reply,
4348 int *cmdDest );
4350 /**
4351 * @ingroup palld_api_functions
4352 * @brief Pa_AddCustomLUT1 adds a custom lookup entry to the lookup tables (LUT1).
4353 *
4354 * @details This command is called to add a specific match entry to the L3 (LUT1) lookup table. This
4355 * function is called once per desired custom LUT1 match criteria.
4356 *
4357 * The LLD will determine where this entry is added based on following rules
4358 * - If there is no previous link or the previous link is a L2 (MAC/SRIO) entry, this entry will be
4359 * added into LUT1_1
4360 * - If the previous link is L3 (IP/Custom LUT1), this entry will be added into LUT1_2
4361 *
4362 * The module user can overwrite the default rules by specifying the desired LUT1 instance.
4363 *
4364 * The PASS will determine which entry of the specified LUT1 table is used for this entry based on
4365 * its internal algorithm if the module user does not specify the LUT1 index.
4366 *
4367 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4368 * The destination for the command is provided in cmdDest. The module user must send the
4369 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4370 * must be sent back to this module through the @ref Pa_forwardResult API.
4371 *
4372 * @param[in] iHandle The driver instance handle
4373 * @param[in] custIndex The level 3 (LUT1) custom index
4374 * @param[in] lutInst Specify which LUT1 (0-2) should be used. Set to pa_LUT_INST_NOT_SPECIFIED if not specified
4375 * @param[in] index Specify the index of the LUT1 entry (0-63). Set to pa_LUT1_INDEX_NOT_SPECIFIED if not specified
4376 * @param[in] match The byte values that describe the match entry
4377 * @param[in] prevLink An optional L2 or L3 handle that links to this lookup
4378 * @param[in] routeInfo Where to send a packet that matches
4379 * @param[in] nextRtFail Where to send a packet that matches here, but fails next parse level
4380 * @param[out] retHandle The returned L3 handle
4381 * @param[out] cmd Buffer where the command is created
4382 * @param[in] cmdSize On entry the size of the cmd buffer, on exit the size of the command
4383 * @param[in] reply Where the response to the PASS command is routed
4384 * @param[out] cmdDest Value (@ref cmdTxDest)
4385 * @retval Value (@ref ReturnValues)
4386 * @pre A driver instance must be created and tables initialized
4387 */
4388 paReturn_t Pa_addCustomLUT1 ( Pa_Handle iHandle,
4389 uint16_t custIndex,
4390 int lutInst,
4391 int index,
4392 uint8_t match[pa_NUM_BYTES_CUSTOM_LUT1],
4393 paHandleL2L3_t prevLink,
4394 paRouteInfo_t *routeInfo,
4395 paRouteInfo_t *nextRtFail,
4396 paHandleL2L3_t *retHandle,
4397 paCmd_t cmd,
4398 uint16_t *cmdSize,
4399 paCmdReply_t *reply,
4400 int *cmdDest );
4402 /**
4403 * @ingroup palld_api_functions
4404 * @brief Pa_setCustomLUT2 performs the global configuration for level 4 (LUT2) custom lookups
4405 *
4406 * @details This command is typically called once per system and is used to configure the
4407 * PA for performing network layer 4 (LUT2) custom lookups.
4408 * If handleLink is true then only 3 bytes and 3 offsets are available
4409 * for matching. The fourth one is used to store the previous match information.
4410 * In this case the first 3 values in the byteOffsets and byteMasks arrays are
4411 * valid.
4412 *
4413 * If setMask is non-zero, it will be ORed with the first byteMask and the match byte.
4414 * It is used to distinguish this custom LUT2 entry from other custom LUT2 and standard
4415 * LUT2 entries.
4416 *
4417 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4418 * The destination for the command is provided in cmdDest. The module user must send the
4419 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4420 * must be sent back to this module through the API @ref Pa_forwardResult.
4421 *
4422 * @param[in] iHandle Driver instance handle
4423 * @param[in] custIndex Level 4 (LUT2) custom index
4424 * @param[in] handleLink Set to TRUE to use one byte of the match to hold previous match info
4425 * @param[in] custHdrSize Size of fixed-length custom header in bytes, which is used to adjust
4426 * location of the next protocol header in case the packet needs to be
4427 * processed by another module such as SASS or host application. This
4428 * parameter should be set to zero for all other types of headers
4429 * @param[in] byteOffsets Array of offsets to the bytes to use in custom matching
4430 * @param[in] byteMasks Array of bits that are valid in the custom matching
4431 * @param[in] setMask Bits to be set at the first match byte
4432 * @param[out] cmd Buffer where the command is created
4433 * @param[in] cmdSize On entry the size of the cmd buffer, on exit the size of the command
4434 * @param[in] reply Where the response to the PASS command is routed
4435 * @param[out] cmdDest Value (@ref cmdTxDest)
4436 * @retval Value (@ref ReturnValues)
4437 * @pre A driver instance must be created and tables initialized
4438 *
4439 * @note There is up to @ref pa_MAX_CUSTOM_TYPES_LUT2 LUT2 custom types supported by PASS.
4440 */
4441 paReturn_t Pa_setCustomLUT2 ( Pa_Handle iHandle,
4442 uint16_t custIndex,
4443 uint16_t handleLink,
4444 uint16_t custHdrSize,
4445 uint16_t byteOffsets[pa_NUM_BYTES_CUSTOM_LUT2],
4446 uint8_t byteMasks[pa_NUM_BYTES_CUSTOM_LUT2],
4447 uint8_t setMask,
4448 paCmd_t cmd,
4449 uint16_t *cmdSize,
4450 paCmdReply_t *reply,
4451 int *cmdDest );
4453 /**
4454 * @ingroup palld_api_functions
4455 * @brief Pa_addCustomLUT2 adds a custom lookup to the LUT2 lookup tables
4456 *
4457 * @details This command is called to add a specific entry to the L4 (LUT2) lookup table. This
4458 * function is called once per desired custom LUT2 match criteria.
4459 * This API also initiates the atomic queue diversion operation, which means that the QMSS moves
4460 * the entries in the diverted queue to the destination queue, if the divertQ is specified and
4461 * fReplace flag is set. In this case, the PASS will complete the LUT2 update, wait for the queue
4462 * diversion to be complete and then resume processing incoming packets.
4463 *
4464 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4465 * The destination for the command is provided in cmdDest. The module user must send the
4466 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4467 * must be sent back to this module through the @ref Pa_forwardResult API.
4468 *
4469 * @param[in] iHandle The driver instance handle
4470 * @param[in] custIndex The level 4 (LUT2) custom index
4471 * @param[in] match The four match values, only 1st three valid if prevLink is non-NULL
4472 * @param[in] prevLink An optional L2 or L3 handle that links to this lookup
4473 * @param[in] divertQ The source queue for atomic queue diversion with LUT2 update
4474 * Set to pa_PARAMS_NOT_SPECIFIED if not specified
4475 * @param[in] fReplace Flag to indicate whether the entry exists
4476 * @param[in] routeInfo Where to send a packet that matches
4477 * @param[out] retHandle The returned L4 handle
4478 * @param[out] cmd The buffer where the command is created
4479 * @param[in] cmdSize On entry the size of the cmd buffer, on exit the size of the command
4480 * @param[in] reply Where the response to the PASS command is routed
4481 * @param[out] cmdDest Value (@ref cmdTxDest)
4482 * @retval Value (@ref ReturnValues)
4483 * @pre A driver instance must be created and tables initialized
4484 */
4485 paReturn_t Pa_addCustomLUT2 ( Pa_Handle iHandle,
4486 uint16_t custIndex,
4487 uint8_t match[pa_NUM_BYTES_CUSTOM_LUT2],
4488 paHandleL2L3_t prevLink,
4489 uint16_t fReplace,
4490 uint16_t divertQ,
4491 paRouteInfo_t *routeInfo,
4492 paHandleL4_t retHandle,
4493 paCmd_t cmd,
4494 uint16_t *cmdSize,
4495 paCmdReply_t *reply,
4496 int *cmdDest );
4498 /**
4499 * @ingroup palld_api_functions
4500 * @brief Pa_forwardResult examines the reply of the sub-system to a command
4501 *
4502 * @details This command is used to pass the sub-system generated replies to commands back to
4503 * this module. Functions @ref Pa_addMac, @ref Pa_addSrio, @ref Pa_addCustomLUT1 and
4504 * @ref Pa_addIp generate replies that must be
4505 * forwarded to this module, or else handle deletion and link are not possible. Other
4506 * commands generate replies that can be sent to this module which will return any
4507 * warnings detected in the sub-system.
4508 *
4509 * @param[in] iHandle The driver instance handle
4510 * @param[in] vresult The command reply packet from the sub-system
4511 * @param[out] retHandle Returns the handle associated with the command
4512 * @param[out] handleType Value @ref HandleTypes
4513 * @param[out] cmdDest Value (@ref cmdTxDest)
4514 * @retval Value (@ref ReturnValues)
4515 * @pre A driver instance must be created and tables initialized
4516 */
4517 paReturn_t Pa_forwardResult (Pa_Handle iHandle, void *vresult, paEntryHandle_t *retHandle, int *handleType, int *cmdDest);
4520 /**
4521 * @ingroup palld_api_functions
4522 * @brief Pa_configExceptionRoute configures the routing of packets based on a exception condition such as
4523 * MAC briadcast, multicast or error packet
4524 *
4525 * @details This function is used to configure the sub-system to route packets that satisfy an exception
4526 * rule or condition (see @ref ErouteTypes). For example,
4527 * - failure to table match
4528 * - parsing error i.e. the sub-system is not able to continuethe parse
4529 * - MAC broadcast packets
4530 * - IP multicast packets
4531 *
4532 * From one to @ref pa_EROUTE_MAX routes can be specified through a single call to this
4533 * function. Parameter nRoute is used to specify how many routes are contained in the
4534 * routeTypes and eRoutes arrays. A value of 0 nRoutes results in no action by the function.
4535 *
4536 * By default when each exception type is detected the packet is discarded silently. Once the
4537 * route is changed through a call to this function it remains in the new state until the
4538 * function is called again to explicitly change that route. The only way to revert back
4539 * to the default of silent discard is to call this function again.
4540 *
4541 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4542 * The destination for the command is provided in cmdDest. The module user must send the
4543 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4544 * must be sent back to this module through the API @ref Pa_forwardResult.
4545 *
4546 * @param[in] iHandle The driver instance handle
4547 * @param[in] nRoute The number of exception routes specified
4548 * @param[in] routeTypes Array of exception routing types (@ref ErouteTypes)
4549 * @param[in] eRoutes Array of exception packet routing configuration
4550 * @param[out] cmd Buffer where the sub-system command is created
4551 * @param[in] cmdSize The size of the passCmd buffer
4552 * @param[in] reply Where the response to the PASS command is routed
4553 * @param[out] cmdDest Value (@ref cmdTxDest)
4554 * @retval Value (@ref ReturnValues)
4555 * @pre A driver instance must be created and tables initialized
4556 */
4557 paReturn_t Pa_configExceptionRoute (Pa_Handle iHandle,
4558 int nRoute,
4559 int *routeTypes,
4560 paRouteInfo_t *eRoutes,
4561 paCmd_t cmd,
4562 uint16_t *cmdSize,
4563 paCmdReply_t *reply,
4564 int *cmdDest);
4566 /**
4567 * @ingroup palld_api_functions
4568 * @brief Pa_configExceptionRoute2 configures the routing of packets based on a exception condition such as
4569 * MAC briadcast, multicast or error packet
4570 *
4571 * @details Pa_configExceptionRoute2 is the next generation of API to replace @ref Pa_configExceptionRoute
4572 * eventually. This new API covers the entire functionality of Pa_configExceptionRoute and it is
4573 * designed to support more features with the more advnced routing information data structure
4574 * while maintain backward-compatibility over time.
4575 *
4576 * @param[in] iHandle The driver instance handle
4577 * @param[in] nRoute The number of exception routes specified
4578 * @param[in] routeTypes Array of exception routing types (@ref ErouteTypes)
4579 * @param[in] eRoutes Array of exception packet routing configuration
4580 * @param[out] cmd Buffer where the sub-system command is created
4581 * @param[in] cmdSize The size of the passCmd buffer
4582 * @param[in] reply Where the response to the PASS command is routed
4583 * @param[out] cmdDest Value (@ref cmdTxDest)
4584 * @retval Value (@ref ReturnValues)
4585 * @pre A driver instance must be created and tables initialized
4586 */
4587 paReturn_t Pa_configExceptionRoute2 (Pa_Handle iHandle,
4588 int nRoute,
4589 int *routeTypes,
4590 paRouteInfo2_t *eRoutes,
4591 paCmd_t cmd,
4592 uint16_t *cmdSize,
4593 paCmdReply_t *reply,
4594 int *cmdDest);
4596 /**
4597 * @ingroup palld_api_functions
4598 * @brief Pa_configCmdSet configures the command set which consists of a list of commands
4599 *
4600 * @details This function is used to configure the sub-system to format and store a list
4601 * of commands which are executed in order when a match occurs and the command set is
4602 * specified by the routing information.
4603 *
4604 * The command set is created and refered to based on the command set index.
4605 * Once the command set is created through a call to this function it remains effective
4606 * until the function is called again to explicitly overwrite its content. It is not
4607 * recommended to update a command set when it is still used by one or more packet
4608 * routes.
4609 * There are @ref pa_MAX_CMD_SETS of command sets supported by the sub-system
4610 *
4611 * The commands within the command set will be executed in order at PDSP4. The module user is
4612 * responsible for placing the commands in such ways that the packet offsets required by commands should
4613 * be in ascending order, otherwise, the unexecutable command will be ignored. The command set
4614 * should be terminated with a pa_CMD_NEXT_ROUTE or pa_CMD_MULTI_ROUTE command. If there is
4615 * no final route command specified, the PASS will use the default next route command. Please note
4616 * that all the commands following the pa_CMD_NEXT_ROUTE or pa_CMD_MULTI_ROUTE command will be ignored.
4617 *
4618 * This API supports the following commands (@ref paCmdCode)
4619 * @li pa_CMD_REMOVE_HEADER
4620 * @li pa_CMD_COPY_DATA_TO_PSINFO
4621 * @li pa_CMD_CRC_OP
4622 * @li pa_CMD_PATCH_DATA
4623 * @li pa_CMD_REMOVE_TAIL
4624 * @li pa_CMD_NEXT_ROUTE
4625 * @li pa_CMD_MULTI_ROUTE
4626 * @li pa_CMD_USR_STATS
4627 * @li pa_CMD_VERIFY_PKT_ERROR
4628 * @li pa_CMD_SPLIT
4629 *
4630 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4631 * The destination for the command is provided in cmdDest. The module user must send the
4632 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4633 * must be sent back to this module through the API @ref Pa_forwardResult.
4634 *
4635 * @param[in] iHandle The driver instance handle
4636 * @param[in] index The command set index
4637 * @param[in] nCmd The number of commands specified
4638 * @param[in] cmdInfo Array of command configuration information
4639 * @param[out] cmd Buffer where the sub-system command is created
4640 * @param[in] cmdSize The size of the passCmd buffer
4641 * @param[in] reply Where the response to the PASS command is routed
4642 * @param[out] cmdDest Value (@ref cmdTxDest)
4643 * @retval Value (@ref ReturnValues)
4644 * @pre A driver instance must be created and tables initialized
4645 */
4646 paReturn_t Pa_configCmdSet (Pa_Handle iHandle,
4647 uint16_t index,
4648 int nCmd,
4649 paCmdInfo_t *cmdInfo,
4650 paCmd_t cmd,
4651 uint16_t *cmdSize,
4652 paCmdReply_t *reply,
4653 int *cmdDest);
4655 /**
4656 * @ingroup palld_api_functions
4657 * @brief Pa_configMultiRouteSet configures the multi-route group which consists of packet multi-route
4658 * entries
4659 *
4660 * @details This function is used to configure the sub-system to format and store a multi-
4661 * route set which contains routing information for up to @ref pa_MAX_MULTI_ROUTE_ENTRIES
4662 * destinations.
4663 *
4664 * The multi-route group is created and refered to based on the multi-route index.
4665 * Once the multi-route group is created through a call to this function it remains effective
4666 * until the function is called again to explicitly overwrite its content. It is not
4667 * recommended to update a mult-route group when it is still used by one or more packet
4668 * routes.
4669 *
4670 * There are @ref pa_MAX_MULTI_ROUTE_SETS of multi-route sets supported by the sub-system
4671 *
4672 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4673 * The destination for the command is provided in cmdDest. The module user must send the
4674 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4675 * must be sent back to this module through the API @ref Pa_forwardResult.
4676 *
4677 * @param[in] iHandle The driver instance handle
4678 * @param[in] mode The operation mode (CONFIG or RESET) refer to @ref paMultiRouteModes_e
4679 * @param[in] index The multi-route index
4680 * @param[in] nRoute The number of routing entries specified
4681 * @param[in] routeEntry Array of routing configuration information
4682 * @param[out] cmd Buffer where the sub-system command is created
4683 * @param[in] cmdSize The size of the passCmd buffer
4684 * @param[in] reply Where the response to the PASS command is routed
4685 * @param[out] cmdDest Value (@ref cmdTxDest)
4686 * @retval Value (@ref ReturnValues)
4687 * @pre A driver instance must be created and tables initialized
4688 */
4689 paReturn_t Pa_configMultiRoute (Pa_Handle iHandle,
4690 paMultiRouteModes_e mode,
4691 uint16_t index,
4692 uint16_t nRoute,
4693 paMultiRouteEntry_t *routeEntry,
4694 paCmd_t cmd,
4695 uint16_t *cmdSize,
4696 paCmdReply_t *reply,
4697 int *cmdDest);
4699 /**
4700 * @ingroup palld_api_functions
4701 * @brief Pa_configCrcEngine configures the specified CRC engine
4702 *
4703 * @details This function is used to configure the specified CRC engine by formating the
4704 * CRC configuration command packet.
4705 *
4706 * There are 6 CRC engines in the PA sun-system. Each CRC engine is connected to its
4707 * corresponding PDSP. It performs CRC operation required by the some network protocol
4708 * such as SCTP and/or the user-specified CRC command for its corresponding PDSP.
4709 * Therefore, it is referred by the PDSP number.
4710 *
4711 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4712 * The destination for the command is provided in cmdDest. The module user must send the
4713 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4714 * must be sent back to this module through the @ref Pa_forwardResult API.
4715 *
4716 * @note Each CRC engine only supports one type of CRC per configuration.
4717 * It is up to the module user to configure and use the CRC engine by calling this function
4718 * for the specific use cases. For example, the CRC engine connected to PDSP2 should be
4719 * configured to perform CRC-32c checksum for SCTP over inner-IP use case.
4720 *
4721 * @param[in] iHandle The driver instance handle
4722 * @param[in] index The CRC engine index
4723 * @param[in] cfgInfo The CRC engine configuration information
4724 * @param[out] cmd Buffer where the sub-system command is created
4725 * @param[in] cmdSize The size of the passCmd buffer
4726 * @param[in] reply Where the response to the PASS command is routed
4727 * @param[out] cmdDest Value (@ref cmdTxDest)
4728 * @retval Value (@ref ReturnValues)
4729 * @pre A driver instance must be created and tables initialized
4730 */
4731 paReturn_t Pa_configCrcEngine (Pa_Handle iHandle,
4732 uint16_t index,
4733 paCrcConfig_t *cfgInfo,
4734 paCmd_t cmd,
4735 uint16_t *cmdSize,
4736 paCmdReply_t *reply,
4737 int *cmdDest);
4739 /**
4740 * @ingroup palld_api_functions
4741 * @brief Pa_configUsrStats configures the user-defined statistics operation
4742 *
4743 * @details This function performs the counter configuration for the multi-level hierarchical user-defined
4744 * statistics. Each counter can be linked to the next level counter. All counters in its linking
4745 * chain will be incremented when the lowest level counter is updated. The module user can specify
4746 * the type of each counter and how the counter is linked to the next level counter.
4747 * It is not recommended to re-configure the user-defined statistics when one or more counters are
4748 * still used by PASS. The command reply routing is optional because this command is always
4749 * processed by the PA sub-system.
4750 *
4751 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4752 * The destination for the command is provided in cmdDest. The module user must send the
4753 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4754 * must be sent back to this module through the @ref Pa_forwardResult API.
4755 *
4756 * @param[in] iHandle The driver instance handle
4757 * @param[in] cfgInfo The user-defined statistics configuration information
4758 * @param[out] cmd Buffer where the sub-system command is created
4759 * @param[in] cmdSize The size of the passCmd buffer
4760 * @param[in] reply Where the response to the PASS command is routed
4761 * @param[out] cmdDest Value (@ref cmdTxDest)
4762 * @retval Value (@ref ReturnValues)
4763 * @pre A driver instance must be created and tables initialized
4764 */
4765 paReturn_t Pa_configUsrStats (Pa_Handle iHandle,
4766 paUsrStatsConfigInfo_t *cfgInfo,
4767 paCmd_t cmd,
4768 uint16_t *cmdSize,
4769 paCmdReply_t *reply,
4770 int *cmdDest);
4771 /**
4772 * @ingroup palld_api_functions
4773 * @brief Pa_configTimestamp configures the PA timer which is used to generate 48-bit timestamp
4774 *
4775 * @details This function is used to configure the 16-bit timer reserved for the 48-bit system
4776 * timestamp. The lower 32-bit of the system timestamp will be inserted into the timestamp
4777 * field in the packet descriptor for all input packets. It can be also inserted into
4778 * the timestamp report packets triggered by the egress packets per tx command.
4779 * The 16-bit timer connected to PDSP0 is reserved for timestamp generation.
4780 *
4781 * @param[in] iHandle The driver instance handle
4782 * @param[in] cfgInfo The timestamp configuration information
4783 * @retval Value (@ref ReturnValues)
4784 * @pre A driver instance must be created and tables initialized
4785 *
4786 */
4787 paReturn_t Pa_configTimestamp (Pa_Handle iHandle,
4788 paTimestampConfig_t *cfgInfo);
4790 /**
4791 * @ingroup palld_api_functions
4792 * @brief Pa_getTimestamp returns the 48-bit system timestamp
4793 *
4794 * @details This function is called to retrieve the current value of 48-bit PASS system timestamp.
4795 *
4796 * @param[in] iHandle The driver instance handle
4797 * @param[out] pTimestamp Pointer to the 48-bit timestamp
4798 * @retval Value (@ref ReturnValues)
4799 * @pre A driver instance must be created and tables initialized
4800 *
4801 */
4802 paReturn_t Pa_getTimestamp (Pa_Handle iHandle,
4803 paTimestamp_t *pTimestamp);
4806 /**
4807 * @ingroup palld_api_functions
4808 * @brief Pa_requestStats requests sub-system statistics
4809 *
4810 * @details This function is used to request the operating statistics from the sub-system.
4811 * The statistics can be optionally cleared after reading through the doClear parameter.
4812 * The statistics apply to the entire sub-system, and are not core dependent on multi-core
4813 * devices.
4814 *
4815 * On return the command buffer (cmd) contains a formatted command for the sub-system.
4816 * The destination for the command is provided in cmdDest. The module user must send the
4817 * formatted command to the sub-system. The sub-system will generate a reply and this reply
4818 * must be sent back to this module through the API @ref Pa_formatStatsReply.
4819 *
4820 * @param[in] iHandle The driver instance handle
4821 * @param[in] doClear If TRUE then stats are cleared after being read
4822 * @param[out] cmd Buffer where the sub-system command is created
4823 * @param[in] cmdSize The size of the cmd buffer
4824 * @param[in] reply Where the response of the PASS command is routed
4825 * @param[out] cmdDest Value (@ref cmdTxDest)
4826 * @retval Value (@ref ReturnValues)
4827 * @pre A driver instance must be created and tables initialized
4828 */
4829 paReturn_t Pa_requestStats (Pa_Handle iHandle,
4830 uint16_t doClear,
4831 paCmd_t cmd,
4832 uint16_t *cmdSize,
4833 paCmdReply_t *reply,
4834 int *cmdDest);
4836 /**
4837 * @ingroup palld_api_functions
4838 * @brief Pa_formatStatsReply formats the stats reply from the PASS
4839 *
4840 * @details This function is used to convert the stats from the sub-system into a format
4841 * useful for the application
4842 *
4843 * @param[in] handle The driver instance handle
4844 * @param[in] cmd The buffer returned with the request stats response from PA
4845 * @retval A pointer to the formatted stats
4846 * @pre A call to @ref Pa_requestStats with output sent to PA and a
4847 * reply generated from PA.
4848 */
4849 paSysStats_t* Pa_formatStatsReply (Pa_Handle handle,
4850 paCmd_t cmd);
4852 /**
4853 * @ingroup palld_api_functions
4854 * @brief Pa_requestUsrStats requests user-defined statistics
4855 *
4856 * @details This function is used to request the user-defined statistics from the sub-system.
4857 * If the buffer pointer (pUsrStats) is provided, the statistics will be formatted and
4858 * copied to the buffer. However, the statistics will not be autonomous because some
4859 * related statistics may be updated by the PASS while LLD is reading other statistics.
4860 * To request autonomous statistics query, set the buffer pointer (pUsrStats) to NULL and
4861 * LLD will generate the statistics request command packet to be delivered to PASS regardless
4862 * of doClear setting.
4863 *
4864 * The sub-system statistics can be optionally cleared after query if doClear is set whether
4865 * or not the buffer pointer is provided.
4866 * The command buffer (cmd) contains a formatted command for the sub-system.
4867 * The destination for the command is provided in cmdDest. The module user must send the
4868 * formatted command to the sub-system.
4869 *
4870 * @param[in] iHandle The driver instance handle
4871 * @param[in] doClear If TRUE then stats are cleared after being read
4872 * @param[out] cmd Buffer where the sub-system command is created
4873 * @param[in] cmdSize The size of the cmd buffer
4874 * @param[in] reply Where the response of the PASS command is routed
4875 * @param[out] cmdDest Value (@ref cmdTxDest)
4876 * @param[out] pUsrStats Pointer to the usrStats buffer
4877 * @retval Value (@ref ReturnValues)
4878 * @pre A driver instance must be created and tables initialized
4879 *
4880 * @note This API may be depreciated in the future releases since it can be replaced by API @ref
4881 * Pa_requestUsrStatsList
4882 */
4883 paReturn_t Pa_requestUsrStats (Pa_Handle iHandle,
4884 uint16_t doClear,
4885 paCmd_t cmd,
4886 uint16_t *cmdSize,
4887 paCmdReply_t *reply,
4888 int *cmdDest,
4889 paUsrStats_t *pUsrStats);
4891 /**
4892 * @ingroup salld_api_constants
4893 * @{
4894 * @brief Indicate that the complete set of user-defined statistics should be leared
4895 */
4896 #define pa_USR_STATS_CLEAR_ALL 0 /**< This constant indicates that all user-defined statistics should be cleared */
4898 /**
4899 * @ingroup palld_api_functions
4900 * @brief Pa_requestUsrStatsList is an advanced version of API @ref Pa_requestUsrStats. It requests user-defined
4901 * statistics with option to clear entire or a subset of statistics.
4902 *
4903 * @details This function is used to request the user-defined statistics from the sub-system
4904 * with option to clear entire or a subset of statistics specified by the list of
4905 * counters.
4906 * If the buffer pointer (pUsrStats) is provided, the statistics will be formatted and
4907 * copied to the buffer. However, the statistics will not be autonomous because some
4908 * related statistics may be updated by the PASS while LLD is reading other statistics.
4909 * To request autonomous statistics query, set the buffer pointer (pUsrStats) to NULL and
4910 * LLD will generate the statistics request command packet to be delivered to PASS regardless
4911 * of doClear setting.
4912 *
4913 * The sub-system statistics can be optionally cleared after query if doClear is set. In
4914 * this case the formatted command packet will include the list of counters to be cleared.
4915 * The command buffer (cmd) contains a formatted command for the sub-system.
4916 * The destination for the command is provided in cmdDest. The module user must send the
4917 * formatted command to the sub-system.
4918 *
4919 * @note: This function always returns the entire user-defined statistics and it is up to the caller to pick
4920 * up the interesting ones.
4921 *
4922 * @param[in] iHandle The driver instance handle
4923 * @param[in] doClear If TRUE then stats are cleared after being read
4924 * @param[in] nCnt The number of counters to be cleared
4925 * @param[in] cntIndex Array of counter indexes to be cleared
4926 * @param[out] cmd Buffer where the sub-system command is created
4927 * @param[in] cmdSize The size of the cmd buffer
4928 * @param[in] reply Where the response of the PASS command is routed
4929 * @param[out] cmdDest Value (@ref cmdTxDest)
4930 * @param[out] pUsrStats Pointer to the usrStats buffer
4931 * @retval Value (@ref ReturnValues)
4932 * @pre A driver instance must be created and tables initialized
4933 */
4934 paReturn_t Pa_requestUsrStatsList (Pa_Handle iHandle,
4935 uint16_t doClear,
4936 uint16_t nCnt,
4937 uint16_t *cntIndex,
4938 paCmd_t cmd,
4939 uint16_t *cmdSize,
4940 paCmdReply_t *reply,
4941 int *cmdDest,
4942 paUsrStats_t *pUsrStats);
4944 /**
4945 * @ingroup palld_api_functions
4946 * @brief Pa_formatUsrStatsReply formats the user-defined statistics reply from the PASS
4947 *
4948 * @details This function is used to convert the stats from the sub-system into a format
4949 * useful for the application
4950 *
4951 * @param[in] handle The driver instance handle
4952 * @param[in] cmd The buffer returned with the request stats response from PA
4953 * @param[out] pUsrStats Pointer to the usrStats buffer
4954 * @retval Value (@ref ReturnValues)
4955 * @pre A call to @ref Pa_requestUsrStats or Pa_requestUsrStatsList with
4956 * buffer pointer pUsrStats set to NULL and output sent to PA and a
4957 * reply generated from PA.
4958 */
4959 paReturn_t Pa_formatUsrStatsReply (Pa_Handle handle,
4960 paCmd_t cmd,
4961 paUsrStats_t *pUsrStats);
4963 /**
4964 * @ingroup palld_api_functions
4965 * @brief Pa_formatTxRoute formats the commands to add checksums and route a Tx packet
4966 *
4967 * @details This function is used to create the command block which is used by the packet accelerator
4968 * sub-system to forward the packet with optional checksum generation.
4969 * The module user can combine this block with other command blocks that control the security
4970 * accelerator. The combined block is then provided for the transmitted packets in the Protocol
4971 * specific section of the packet descriptor. This API needs only to be called once, and the same
4972 * protocol specific section can be used for every packet in the channel. If the length of the
4973 * checksum area changes with each packet, update the command buffer with the macro
4974 * PASS_SET_TX_CHKSUM_LENGTH()
4975 *
4976 * @note The Tx commands can be executed at either PDSP4 or PDSP5. However, it is highly
4977 * recommended to use PDSP5 for load balance since PDSP4 will be used to execute
4978 * multi-routing and from-network command set.
4979 *
4980 * @param[in] chk0 Checksum 0 configuration. NULL if no checksum computation required
4981 * @param[in] chk1 Checksum 1 configuration. NULL if no checksum computation required
4982 * @param[in] route Next packet routing from sub-system
4983 * @param[out] cmdBuffer The routing command is formed in this buffer
4984 * @param[in] cmdSize On entry the size of cmdBuffer. On exit the size of the command
4985 * @retval Value (@ref ReturnValues)
4986 */
4987 paReturn_t Pa_formatTxRoute (paTxChksum_t *chk0,
4988 paTxChksum_t *chk1,
4989 paRouteInfo_t *route,
4990 void *cmdBuffer,
4991 uint16_t *cmdSize );
4993 /**
4994 * @ingroup palld_api_functions
4995 * @brief Pa_formatRoutePatch formats the commands to route a packet and blind patch
4996 *
4997 * @details This function is used to create the command block which is used by the packet accelerator
4998 * sub-system to perform blind patches on the packet. This function user optionally combines
4999 * the generated block with other blocks to create compound commands. The command blocks are
5000 * attached to data packets in the Protocol specific section of the packet descriptor.
5001 *
5002 * @note The Tx commands can be executed at either PDSP4 or PDSP5. However, it is highly
5003 * recommended to use PDSP5 for load balance since PDSP4 will be used to execute
5004 * multi-routing and from-network command set.
5005 *
5006 * @param[in] route Specifies where the packet is sent after the patch is complete
5007 * @param[in] patch The patch information
5008 * @param[out] cmdBuffer The routing command is formed in this buffer
5009 * @param[in] cmdSize On entry this size of cmdBuffer. On exit the amound of cmdBuffer used
5010 * @retval Value (@ref ReturnValues)
5011 */
5013 paReturn_t Pa_formatRoutePatch (paRouteInfo_t *route,
5014 paPatchInfo_t *patch,
5015 void *cmdBuffer,
5016 uint16_t *cmdSize);
5018 /**
5019 * @ingroup palld_api_functions
5020 * @brief Pa_formatTxCmd formats a list of commands to be executed on the packets to be transmitted
5021 * over the network
5022 *
5023 * @details This function is used to create, append and update the list of commands which will be
5024 * executed by the packet accelerator and security accelerator sub-systems to perform a sequence
5025 * of actions on the packet. The command block should be attached to data packets in the
5026 * protocol specific section of the packet descriptor.
5027 *
5028 * This API may be called multiple times to add or update the command block.
5029 * The same protocol specific section can be used for every packet in the channel after the
5030 * command list is constructed. Multiple MACROs may be used to update some parameters
5031 * such as packet length in the command buffer for each packet.
5032 *
5033 * This API supports the following commands (@ref paCmdCode):
5034 * @li pa_CMD_NEXT_ROUTE
5035 * @li pa_CMD_CRC_OP
5036 * @li pa_CMD_PATCH_DATA
5037 * @li pa_CMD_TX_CHECKSUM
5038 * @li pa_CMD_REPORT_TX_TIMESTAMP
5039 * @li pa_CMD_SA_PAYLOAD
5040 * @li pa_CMD_IP_FRAGMENT
5041 * @li pa_CMD_PATCH_MSG_LEN
5042 *
5043 * @note The Tx commands can be executed at either PDSP4 or PDSP5. However, it is highly
5044 * recommended to use PDSP5 for load balance since PDSP4 will be used to execute
5045 * multi-routing and from-network command set.
5046 *
5047 * @param[in] nCmd The number of commands specified
5048 * @param[in] cmdInfo Array of command configuration information
5049 * @param[in] offset The command buffer location where the new commands are inserted
5050 * @param[out] cmdBuffer Buffer where the sub-system command is created
5051 * @param[in] cmdSize On entry this size of cmdBuffer. On exit the amound of cmdBuffer used
5052 * @retval Value (@ref ReturnValues)
5053 *
5054 * @note The command buffer should be 4-byte aligned
5055 */
5057 paReturn_t Pa_formatTxCmd (int nCmd,
5058 paCmdInfo_t *cmdInfo,
5059 uint16_t offset,
5060 void *cmdBuffer,
5061 uint16_t *cmdSize);
5063 /**
5064 * @ingroup palld_api_functions
5065 * @brief Pa_resetControl controls the reset state of the Sub-system
5066 *
5067 * @details This function is used to assert or release reset for the sub-system. Asserting reset does not
5068 * reset any of the sub-system tables (L2, L3 or L4, see @ref netlayers), but only the packet
5069 * processing modules. To achieve a complete system reset the system level reset must be asserted
5070 * through the power controller.
5071 *
5072 * @param[in] iHandle The driver instance handle
5073 * @param[in] newState Value @ref paSubSysStates
5074 * @retval Value @ref paSubSysStates
5075 * @pre None
5076 *
5077 * @note This function will access the PA sub-system registers. It is up to the module user to provide critical
5078 * section protection so that only one core or task should use this function at a time.
5079 */
5080 paSSstate_t Pa_resetControl (Pa_Handle iHandle, paSSstate_t newState);
5083 /**
5084 * @ingroup palld_api_functions
5085 * @brief Pa_downloadImage downloads a PDSP image to a sub-system with the packet processing modules in reset.
5086 *
5087 * @details This function is used to download an executable PDSP image to the specific packet processing module.
5088 * See section table @ref appendix1 for a description of PDSP images provided by this module
5089 *
5090 * @param[in] iHandle The driver instance handle
5091 * @param[in] modId The PDSP number (0-5)
5092 * @param[in] image The image to download
5093 * @param[in] sizeBytes The size of the image
5094 * @retval Value (@ref ReturnValues)
5095 * @pre The packet processing modules must be in reset. See @ref Pa_resetControl.
5096 *
5097 * @note This function will access the PA sub-system registers. It is up to the module user to provide critical
5098 * section protection so that only one core or task should use this function at a time.
5099 */
5100 paReturn_t Pa_downloadImage (Pa_Handle iHandle, int modId, void* image, int sizeBytes);
5102 /**
5103 * @ingroup palld_api_functions
5104 * @brief Pa_getHandleRefCount returns the number of reference channels linked to the LUT1 handle
5105 *
5106 * @details The LLD maintains the reference counter for LUT1 handles: MAC/IP. Given a handle,
5107 * the LLD would return how many references are being used in next header entry by invoking
5108 * the function. For example, Query on MAC handle need to return how many IP handles are
5109 * referencing the MAC handles. Query on IP handle need to return how many next protocol
5110 * entries: IP/UDP are referencing to the IP handle.
5111 * Therefore this function can be used to verify whether the LUT1 entry associated with
5112 * the handle can be reomved.
5113 *
5114 * @param[in] iHandle The driver instance handle
5115 * @param[in] l2l3handle The L2 or L3 handle to be queryed
5116 * @param[out] refCount The number of reference channels
5117 * @retval Value (@ref ReturnValues)
5118 */
5119 paReturn_t Pa_getHandleRefCount ( Pa_Handle iHandle,
5120 paHandleL2L3_t l2l3handle,
5121 uint16_t *refCount );
5123 /**
5124 * @ingroup palld_api_functions
5125 * @brief Pa_getPDSPVersion returns the PA PDSP version information.
5126 *
5127 * @details This function is used to get the PA PDSP version information in 0xAABBCCDD format.
5128 * where Arch (AA); API Changes (BB); Major (CC); Minor (DD
5129 *
5130 * @param[in] iHandle The driver instance handle
5131 * @param[in] modId The PDSP number (0-5)
5132 * @param[out] pVersion The pointer to PDSP version number
5133 * @retval Value (@ref ReturnValues)
5134 * @pre The PDSP image should be downloaded successfully.
5135 *
5136 */
5137 paReturn_t Pa_getPDSPVersion (Pa_Handle iHandle, int modId, uint32_t *pVersion);
5140 /**
5141 * @ingroup palld_api_functions
5142 * @brief Pa_getVersion returns the PA LLD version information
5143 *
5144 * @details This function is used to get the version information of the PA LLD in 0xAABBCCDD format.
5145 * where Arch (AA); API Changes (BB); Major (CC); Minor (DD)
5146 *
5147 * @retval 32-bit version information
5148 */
5149 uint32_t Pa_getVersion (void);
5152 /**
5153 * @ingroup palld_api_functions
5154 * @brief Pa_getVersionStr returns the PA LLD version string
5155 *
5156 * @details This function is used to get the version string of the PA LLD.
5157 *
5158 * @retval Version string
5159 */
5160 const char* Pa_getVersionStr (void);
5162 /**
5163 * @ingroup palld_api_macros
5164 * @brief pa_RESET_SUBSYSTEM is used to reset the Sub-system
5165 *
5166 * @details This macro is used to put the packet processing sub-system into reset. It performs the same function
5167 * as @ref Pa_resetControl, but in macro form. The module user must define the macro SYSTEM_WRITE32.
5168 *
5169 * @pre The module user must define a macro called SYSTEM_WRITE32(address, value) which writes a 32 bit
5170 * value (value) to global address (address).
5171 *
5172 */
5173 #define pa_RESET_SUBSYSTEM() \
5174 { \
5175 CSL_Pa_ssRegs *passRegs = (CSL_Pa_ssRegs *)CSL_NETCP_CFG_REGS; \
5176 \
5177 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[0].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_SOFT_RST_N_MASK)); \
5178 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[1].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_SOFT_RST_N_MASK)); \
5179 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[2].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_SOFT_RST_N_MASK)); \
5180 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[3].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_SOFT_RST_N_MASK)); \
5181 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[4].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_SOFT_RST_N_MASK)); \
5182 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[5].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_SOFT_RST_N_MASK)); \
5183 SYSTEM_WRITE32(&(passRegs->PKT_ID.PKT_ID_SOFT_RESET, 1); \
5184 SYSTEM_WRITE32(&(passRegs->STATS.STATS_SOFT_RESET, 1); \
5185 SYSTEM_WRITE32(&(passRegs->PDSP_TIMER[0].TIMER_CNTRL_REG, 0); \
5186 SYSTEM_WRITE32(&(passRegs->PDSP_TIMER[1].TIMER_CNTRL_REG, 0); \
5187 SYSTEM_WRITE32(&(passRegs->PDSP_TIMER[2].TIMER_CNTRL_REG, 0); \
5188 SYSTEM_WRITE32(&(passRegs->PDSP_TIMER[3].TIMER_CNTRL_REG, 0); \
5189 SYSTEM_WRITE32(&(passRegs->PDSP_TIMER[4].TIMER_CNTRL_REG, 0); \
5190 SYSTEM_WRITE32(&(passRegs->PDSP_TIMER[5].TIMER_CNTRL_REG, 0); \
5191 }
5193 /**
5194 * @ingroup palld_api_macros
5195 * @brief pa_ENABLE_SUBSYSTEM enables the subsystem.
5196 *
5197 * @details This macro is used to release reset from the packet processing sub-system. It performs the same
5198 * function as @ref Pa_resetControl, but in macro from. The module user must define the macro SYSTEM_WRITE32
5199 * and SYSTEM_READ32.
5200 *
5201 * @pre The module user must define the macro SYSTEM_WRITE32(address, value) and SYSTEM_READ32 (address) which
5202 * read and write to global address (address).
5203 */
5204 #define pa_ENABLE_SUBSYSTEM() \
5205 { \
5206 CSL_Pa_ssRegs *passRegs = (CSL_Pa_ssRegs *)CSL_NETCP_CFG_REGS; \
5207 \
5208 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[0].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK)); \
5209 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[1].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK)); \
5210 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[2].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK)); \
5211 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[3].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK)); \
5212 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[4].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK)); \
5213 SYSTEM_WRITE32(&(passRegs->PDSP_CTLSTAT[5].PDSP_CONTROL), (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK)); \
5214 while (SYSTEM_READ32(&(passRegs->MAILBOX[0].MBOX_SLOT[0])) == 0); \
5215 while (SYSTEM_READ32(&(passRegs->MAILBOX[1].MBOX_SLOT[0])) == 0); \
5216 while (SYSTEM_READ32(&(passRegs->MAILBOX[2].MBOX_SLOT[0])) == 0); \
5217 while (SYSTEM_READ32(&(passRegs->MAILBOX[3].MBOX_SLOT[0])) == 0); \
5218 while (SYSTEM_READ32(&(passRegs->MAILBOX[4].MBOX_SLOT[0])) == 0); \
5219 while (SYSTEM_READ32(&(passRegs->MAILBOX[5].MBOX_SLOT[0])) == 0); \
5220 SYSTEM_WRITE32(&(passRegs->MAILBOX[0].MBOX_SLOT[1], 1); \
5221 SYSTEM_WRITE32(&(passRegs->MAILBOX[0].MBOX_SLOT[0], 0); \
5222 while (SYSTEM_READ32(&(passRegs->MAILBOX[0].MBOX_SLOT[1])) == 1); \
5223 SYSTEM_WRITE32(&(passRegs->MAILBOX[0].MBOX_SLOT[1], 0); \
5224 SYSTEM_WRITE32(&(passRegs->MAILBOX[0].MBOX_SLOT[2], 0); \
5225 SYSTEM_WRITE32(&(passRegs->MAILBOX[0].MBOX_SLOT[3], 0); \
5226 SYSTEM_WRITE32(&(passRegs->MAILBOX[0].MBOX_SLOT[4], 0); \
5227 SYSTEM_WRITE32(&(passRegs->MAILBOX[0].MBOX_SLOT[5], 0); \
5228 }
5231 /**
5232 * @ingroup palld_api_macros
5233 * @brief pa_DOWNLOAD_MODULE downloads an image
5234 *
5235 * @details This macro provides the same function as @ref Pa_downloadImage. A single image is downloaded to
5236 * one of the packet processing modules.
5237 *
5238 * @pre The module user must define macro SYSTEM_COPY(dest, src, sizeWords) which copies sizeWords from
5239 * address src to address dst. The packet processing module must have reset asserted.
5240 */
5241 #define pa_DOWNLOAD_MODULE(id,img,size) \
5242 { \
5243 CSL_Pa_ssRegs *passRegs = (CSL_Pa_ssRegs *)CSL_NETCP_CFG_REGS; \
5244 \
5245 SYSTEM_COPY(&(passRegs->PDSP_IRAM[id].PDSP_RAM[0]), img, size); \
5246 }
5248 /**
5249 * @ingroup palld_api_macros
5250 * @brief pa_GET_SYSETM_STATE returns the state of the subsystem
5251 *
5252 * @details This macro provides the same functionality as @ref Pa_resetControl and returns the
5253 * current state in the macro argument.
5254 */
5255 #define pa_GET_SYSTEM_STATE(x) \
5256 { int enable=0; int disable=0; \
5257 CSL_Pa_ssRegs *passRegs = (CSL_Pa_ssRegs *)CSL_NETCP_CFG_REGS; \
5258 if ( (SYSTEM_READ32(&(passRegs->PDSP_CTLSTAT[0].PDSP_CONTROL)) & CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) == \
5259 (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) ) \
5260 enable++; else disable++; \
5261 if ( (SYSTEM_READ32(&(passRegs->PDSP_CTLSTAT[1].PDSP_CONTROL)) & CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) == \
5262 (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) ) \
5263 enable++; else disable++; \
5264 if ( (SYSTEM_READ32(&(passRegs->PDSP_CTLSTAT[2].PDSP_CONTROL)) & CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) == \
5265 (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) ) \
5266 enable++; else disable++; \
5267 if ( (SYSTEM_READ32(&(passRegs->PDSP_CTLSTAT[3].PDSP_CONTROL)) & CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) == \
5268 (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) ) \
5269 enable++; else disable++; \
5270 if ( (SYSTEM_READ32(&(passRegs->PDSP_CTLSTAT[4].PDSP_CONTROL)) & CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) == \
5271 (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) ) \
5272 enable++; else disable++; \
5273 if ( (SYSTEM_READ32(&(passRegs->PDSP_CTLSTAT[5].PDSP_CONTROL)) & CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) == \
5274 (CSL_PA_SS_PDSP_CONTROL_PDSP_ENABLE_MASK) ) \
5275 enable++; else disable++; \
5276 if ( (enable > 0) && (disable > 0) ) (x) = pa_STATE_INCONSISTENT; \
5277 else if (enable > 0) (x) = pa_STATE_ENABLE; \
5278 else (x) = pa_STATE_RESET; \
5279 } (x) = (x)
5282 /**
5283 * @ingroup palld_api_macros
5284 * @brief pa_SET_TX_CHKSUM_LENGTH sets the tx checksum length in a tx route block
5285 *
5286 * @details This macro is used to modify the length of a checksum field in a command packet
5287 * created by a call to @ref Pa_formatTxRoute. In many cases packets in an outbound packet
5288 * stream will have the same source and destination information (see @ref netlayers) but
5289 * differ in the packet length. This macro will change the checksum calculation information
5290 * which is sent to the sub-system. The length fields in L2, L3 and L4 must be changed by
5291 * the module user before sending the packet, they are not changed by this macro. In the
5292 * case of IP L3 and TCP or UDP L4 the psuedo header checksum must also be changed
5293 * to reflect the change in packet length.
5294 */
5295 #define pa_SET_TX_CHKSUM_LENGTH(datap,cnum,len) \
5296 PASAHO_CHKCRC_SET_LEN ((&(((pasahoComChkCrc_t *)datap)[cnum])), len)
5298 /**
5299 * @ingroup palld_api_macros
5300 * @brief pa_SET_TX_INITVAL sets the initial value in a tx route block
5301 *
5302 * @details This macro is used to modify the initial value of a checksum field in a command packet
5303 * created by a call to @ref Pa_formatTxRoute. This macro is used when a single call
5304 * to @ref Pa_formatTxRoute is desired, The application typically follows this with an update
5305 * to the length fields in network headers, either directly or through a blind patch.
5306 * For updates with IPv4 or IPv6 the pseudo header checksum must be updated as well, and this
5307 * macro is used to update the value. Typically the pseudo header checksum will be computed
5308 * with all values except the length, and then updated for each packet with a single ones' complement add.
5309 */
5310 #define pa_SET_TX_CHKSUM_INITVAL(datap,cnum,val) \
5311 PASAHO_CHKCRC_SET_INITVAL ((&(((pasahoComChkCrc_t *)datap)[cnum])), val)
5313 /**
5314 * @page netlayers
5315 *
5316 * Network layers define a hierarchy of services delineated by functionality. Each layer can use the functionality
5317 * of the next layer below, and offers services to the next layer above. The packet accelerator sub-system examines
5318 * and routes packets based on fields in up to three layers of the Ethernet packets or L0-L2 header of the SRIO packets.
5319 *
5320 * In layer 2, the MAC (Media Access Control) layer,
5321 * the sub-system classifies IEEE 802.3 packets based on (optionally) the destination MAC, source MAC, Ethertype, and
5322 * VLAN tags.
5323 *
5324 * In Layer 3, the network layer, IPv4 (Internet Protocol Version 4) and IPv6 (Internet Protocol
5325 * Version 6) packets are routed based (optionally) on source IP address, destination IP address, IPv4 protocol,
5326 * IPv6 next header, IPv4 Type of Service (recently changed to IPv4 differentiated service in RFC 2474), IPv6
5327 * traffic class, and IPv6 flow label. For IP packets with security services the SPI (Security Parameters Index)
5328 * is also included in the classification information. For IP packets with SCTP (Stream Control Transmission Protocol)
5329 * the SCTP destination port is also included in the classification information.
5330 *
5331 * In layer 4, the transport layer, UDP (User Datagram Protocol) and TCP (Transmission Control Protocol) packets
5332 * are routed based on the destination port. However, the GTP-U (GPRS Tunnelling Protocol User Plane) over UDP packets
5333 * are routed based on its 32-bit TEID (Tunnel ID).
5334 *
5335 * For SRIO (Serial RapidIO), L0-L2 header information
5336 * the sub-system classifies SRIO packets based on (optional) the source ID, destination ID, transport type, priority,
5337 * message type, SRIO type 11 mailbox and letter, SRIO type 9 stream ID and class of service.
5338 *
5339 */
5342 /**
5343 * @page cache
5344 *
5345 * The packet accelerator low level driver module will make call backs to the module user when it
5346 * is about to read from one of the two tables provided by the module user. If the module user
5347 * is operating in a multi-core environment with a single set of tables shared by all the cores,
5348 * then this function is used to tell a local core that it must invalidate its cache, without writeback.
5349 * This is necessary if cross core cache coherency is not maintained by the hardware in the device.
5350 *
5351 * Without this it is possible for one core to be operating from a locally cached version of the
5352 * tables which does not reflect any additions or deletions done by other cores.
5353 *
5354 * An alternative is to place the tables into non-cached memory.
5355 *
5356 */
5358 /**
5359 * @page semaphores
5360 *
5361 * The packet accelerator low level driver module will make call backs to the module user when it
5362 * is about to modify from one of the two tables provided by the module user. If the module user
5363 * is operating in a multi-core environment with a single set of tables shared by all the cores,
5364 * then this function is used to tell the application to apply a cross core semaphore.
5365 *
5366 * When table modification is done the module will again make a call back to the module user
5367 * to inform it to release the semaphore.
5368 */
5371 /**
5372 * @page order
5373 *
5374 * The sub-system examines the L2 and L3 (LUT1) information (see @ref netlayers) in packets based on internal
5375 * table location. When function @ref Pa_addMac and @ref Pa_addIp are executed and the resulting packet
5376 * forwarded to the sub-system, the sub-system places the new entries at the highest free
5377 * table location. When incoming packets are examined, the table is searched from lowest entry location
5378 * to highest entry location until the first matching entry is found. That entry is used to route the
5379 * packet.
5380 *
5381 * Because of this it is required that entries into the table be made in order from the most general
5382 * to the most specific. For example, when adding a mac address it is common to want to route the following:
5383 * @li dest mac only - Forward packet to host
5384 * @li dest mac + ethertype - Continue parsing
5385 * @li dest mac + source mac + ethertype - Forward packet to host
5386 *
5387 * To get the desired routing the @ref Pa_addMac commands must be executed and the command packets forwarded
5388 * to the sub-system in the order shown above. If they are entered in the reverse order then every packet
5389 * which has the value dest MAC will be forwarded to the host since it matches the first entry in the list.
5390 *
5391 * The order dependency applies to calls to @ref Pa_addMac and @ref Pa_addIp, but not to calls between these functions.
5392 * So all MAC entries can be made followed by all IP entries, or in the reverse order (provided the IP entries
5393 * do not reference the MAC entries) without changing the operation of the sub-system.
5394 *
5395 */
5397 /**
5398 * @page appendix1 PDSP image
5399 *
5400 * The sub-sustem contains six PDSPs wihich perform the command and packet processing. There are three PDSP
5401 * images provided by the module under the pa/fw directory:
5402 * @li Packet Classifier 1 image: classify1_bin.c for PDSP0, PDSP1 and PDSP2
5403 * @li Packet Classifier 2 image: classify2_bin.c for PDSP3
5404 * @li Packet Modifier image: pam_bin.c for PDSP4 and PDSP5
5405 *
5406 * The PDSP executable images are provided to the module user as c-file contains the binary image. They should
5407 * be included by the application and loaded into the corresponding PASS PDSP by invoking the API
5408 * @ref Pa_downloadImage at system startup.
5409 *
5410 */
5413 /**
5414 * @page appendix2 CPPI Error Flags
5415 *
5416 * The sub-system performs IPv4 header checksum, UDP/TCP checksum and SCTP CRC-32c checksum autonomously.
5417 * The sub-system can also perform the CRC verification for incoming packet as one of the actions specified
5418 * by the post-classification command set.
5419 *
5420 * The checksum and CRC verification results are recorded at the 4-bit error flags in the CPPI packet descriptor
5421 * as described below:
5422 * @li bit 3: IPv4 header checksum error
5423 * @li bit 2: UDP/TCP or SCTP CRC-32c checksum error
5424 * @li bit 1: Custom CRC checksum error
5425 * @li bit 0: reserved
5426 *
5427 */
5429 /**
5430 * @page appendix3 PA-assisted IP Reassembly Operation
5431 *
5432 * The current version of PASS does not support IP reassembly, the IP fragments can be detected by PASS, forwarded to
5433 * and reassembled at host. The reassembled IP packet may be forwarded back to PASS for continuous classification.
5434 * The drawback of this approach is that the order of the incoming packets will not be maintained.
5435 *
5436 * To provide better support for IP reassembly, the PA-assisted IP Reassembly operation is introduced and summarized below:
5437 * @li Array of traffic flows which consist of source IP, destination IP, protocol and counter are maintained at PASS PDSP.
5438 * @li A traffic flow is activated by the PDSP when the first IP fragment with the source and destination IP and protocol is
5439 * detected and forwarded.
5440 * @li The traffic flow is freed when its packet count reaches 0
5441 * @li All packets belong to any active traffic flow will be forwarded to the host so the packet order will be maintained.
5442 * @li IP fragments should be forwarded to host with "not availeable" traffic flow id if no traffic flow is available.
5443 * In this case, the packet order is not guaranteed to be maintained.
5444 * @li PASS supports up to 32 active traffic flows for outer IP (PDSP1) and inner IP (PDSP2) respectively.
5445 * @li The PA-assisted IP Reassembly Operation will be enabled by invoking API @ref Pa_control with the IP reassembly
5446 * configuration @ref paIpReassmConfig_t.
5447 *
5448 * @note The minimum size packet wire rate throughput will not be guaranteed when this feature is enabled and there are active
5449 * traffic flows.
5450 *
5451 * The host IP reassembly module should interact with PASS and perform the full IP reassembly operation. The module user may choose
5452 * to implement a simplified version of IP reassembly algorithm to save CPU cycle in controlled IP environment. A sample reassembly
5453 * module is provided in the PA LLD release package, which demonstrates how to interact with the NetCP to perform the IP reassembly
5454 * operation.
5455 *
5456 * The sample code implements a simplified version of IP reassembly algorithm which supports non-overlapping segments only. The sample
5457 * code performs the following tasks:
5458 * @li Maintain the IP reassembly contexts consist of source IP, destination IP, IP identification, protocol, fragments count and the
5459 * corresponding traffic flow id.
5460 * @li Forward the non-fragmented IP packet with its flow id and count = 1 to PA PDSP queue. This avoids reordering the non-fragmented packets.
5461 * @li For IPSEC inner IP fragments, call SA LLD to perform the post-decryption operation including padding check and IPSEC header
5462 * and authentication tag removal.
5463 * @li Forward the reassembled IP packet with its flow id and fragments count to PA PDSP queue.
5464 * @li Send a null packet with its flow id and fragments count to PA PDSP queue if the fragments are discarded due to timeout or other error.
5465 *
5466 */
5469 #ifdef __cplusplus
5470 }
5471 #endif
5474 #endif /* _PA_H */