-
Notifications
You must be signed in to change notification settings - Fork 127
/
CHANGELOG
2971 lines (2519 loc) · 135 KB
/
CHANGELOG
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
== OpenDataPlane (1.18.0.0)
=== New Features
ODP v1.18.0.0 is Tiger Moth Release Candidate 2 (RC 2). It completes the new
APIs that are part of the Tiger Moth Long Term Support (LTS) release of ODP
as well as various performance refinements and bug fixes. As of RC2 the ODP
API is now frozen for the Tiger Moth development series.
==== APIs
The following new and changed APIs are included in this release:
===== Addition of Shared Memory (SHM) Initialization Parameters
The `odp_init_t` struct used as the argument to the `odp_init_global()` API
has been expanded to include a `max_memory` field that specifies the maximum
amount of shared memory (shm) that the application will use. This is to
better enable ODP implementations to optimize their use of shared memory in
support of the application. If left as (or defaulted) to 0, the implementation
may choose a default limit for the application.
===== Crypto Changes
A number of crypto refinements are included in this release:
* The single initialization vector (`iv`) in the `odp_crypto_session_param_t`
is replaced by a separate `cipher_iv` and `auth_iv` fields.
* The single initialization vector (`override_iv_ptr`) in the
`odp_crypto_op_param_t` is replaced by a separate `cipher_iv_ptr` and
`auth_iv_ptr` fields.
* The special nature of GCM and GMAC authenticated encryption modes is
clarified in that these ciphers always combine ciphering with authentication
and hence require both to be specified when used. This is simply a
documentation change as this requirement has always existed.
* Enumerations for AES_CCM (`ODP_CIPHER_ALG_AES_CCM` and
`ODP_AUTH_ALG_AES_CCM`) authenticated encryption modes are added.
* Enumeration for the AES_CMAC authenticated encryption mode
(`ODP_AUTH_ALG_AES_CMAC`) is added.
* Enumerations for the ChaCha20-Poly1305 (`ODP_CIPHER_ALG_CHACHA20_POLY1305`
and `ODP_AUTH_ALG_CHACHA20_POLY1305`) authenticated encryption modes are
added.
* Enumeration for the SHA-384 authentication algorithm
(`ODP_AUTH_ALG_SHA384_HMAC`) is added.
* Enumeration for the AES-XCBC-MAC authentication algorithm
(`ODP_AUTH_ALG_AES_XCBC_MAC`) is added.
===== Lock-free and block-free queues
The `odp_nonblocking_t` enums introduced in ODP v1.17.0.0 are now returned
as separate `odp_queue_capability()` limits for plain and scheduled queues. The
ODP reference implementations now support `ODP_NONBLOCKING_LF` queues.
===== User pointer initialized to NULL
The specification for `odp_packet_user_ptr()` is clarified that unless
overridden by `odp_packet_user_ptr_set()` the value of NULL will be returned.
===== Removal of `ODP_PKTIN_WAIT` option
The `ODP_PKTIN_WAIT` option on `odp_pktin_recv_tmo()` and
`odp_pktin_recv_mq_tmo()` is removed. Timeout options now consist of
`ODP_PKTIN_NO_WAIT` and a user-supplied timeout value. Since this timeout
value can be specified to be arbitrarily long, there is no need for an
indefinite wait capability as provision of such a capability proved
problematic for some ODP implementations.
===== Addition of packet protocol APIs
The APIs `odp_packet_l2_type()`, `odp_packet_l3_type()`, and
`odp_packet_l4_type()` are added to return the Layer 2, 3, and 4 protocols,
respectively, associated with packets that have been parsed to the
corresponding layer. If the packet was not parsed to the associated layer
these return `ODP_PROTO_Ln_TYPE_NONE`.
===== Packet addressability improvements
The documentation of `odp_packet_data()` is clarified to indicated when this
shortcut may be used safely and a new API, `odp_packet_data_seg_len()`, is
added that returns both the address of the start of packet data as well
as the number of bytes addressable from that pointer.
===== Asynchronous ordered locks
Two new APIs, `odp_schedule_order_lock_start()` and
`odp_schedule_order_lock_wait()` are added to allow for asynchronous
ordered lock acquisition in addition to the existing synchronous
`odp_schedule_order_lock()` API. In some implementations and applications,
there may be a performance advantage to indicating the intent to acquire an
ordered lock to allow the implementation to prepare for this while the
application continues parallel processing and then enter the critical section
protected by the ordered lock at a later time. In this case ordered lock
protection is not guaranteed until the `odp_schedule_order_lock_wait()` call
returns.
===== IPsec API miscellaneous changes and enhancements
IPsec support is further enhanced with the following:
* The `odp_ipsec_ipv4_param_t` and `odp_ipsec_ipv6_param_t` structures
are added to formalize the specification of IPv4 and IPv6 options in the
`odp_ipsec_tunnel_param_t` configuration.
* The `mode` field of the `odp_ipsec_out_t` is renamed to `frag_mode` for
better clarity. In addition the `flag.frag-mode` option bit in the
`odp_ipsec_out_opt_t` struct is defined to hold per-operation options for
the `odp_ipsec_out_param_t` struct.
* The `odp_ipsec_capability_t` struct returned by the `odp_ipsec_capability()`
API is expanded to include the `odp_proto_chksums_t` available on inbound
IPsec traffic. This indicates whether and how inbound packet checksums may
be validated for decrypted IPsec traffic.
===== IPsec Traffic Flow Confidentiality (TFC) support
Traffic Flow Confidentiality (TFC) allows applications to defend against
traffic analysis attacks by inserting dummy packets as well as add pad bytes
to packets traversing IPsec flows.
Dummy packets have an L3 type of `ODP_PROTO_L3_TYPE_NONE` in tunnel mode and
`ODP_PROTO_L4_TYPE_NO_NEXT` in transport mode. Padded packets have additional
data suffixed to them that extends beyond the L3 or L4 packet lengths.
For RX processing, inline dummy packets may or may not be dropped from the
inbound packet stream. For lookaside processing they are always visible. For TX
processing, the `odp_ipsec_out_opt_t` struct specifies the `tfc_pad` bit if
the packet is to be padded or the `tfc_dummy` bit if a dummy packet is to
be inserted. The dummy packet length is specified by the `tfc_pad_len` option.
=== Streamlined ABI Support
ABI support has been reorganized to make it more modular and to omit headers
and related ABI files when configure to disable this support.
=== Reference Implementation Fixes and Improvements
The ODP Reference Implementation corporates a number of improvements that
result in better code organization as well as improved processing efficiency.
==== Pktio null device support
In the LNG Reference Implemenations of ODP, the `odp_pktio_open()` API may now
specify devices of class `null` to indicate the PktIO is treated as a dummy
device. Null devices behave just like Linux `/dev/null` in that they never
receive packets and simply discard any packets sent to them.
Note that not all ODP implementations may support this device class. The
specific device classes supported by each ODP implementation may vary and are
listed in their own documentation.
==== Runtime Scheduler Selection
The ODP Reference Implementation offers both a default and a number of
alternate scheduler implementations. Previously these were selectable only at
`configure` time. They can now be dynamically selected at runtime by the use
of the `ODP_SCHEDULER` environment variable. If this environment variable is
not set, the default (basic) scheduler is used. It can be set to select
alternate schedulers:
* `ODP_SCHEDULER=basic` Explicitly selects the default scheduler
* `ODP_SCHEDULER=sp` Selects the strict priority scheduler
* `ODP_SCHEDULER=iquery` Selects the iQuery scheduler
* `ODP_SCHEDULER=scalable` Selects the scalable scheduler
==== Streamlined Queue Implementation
The ODP Reference Implementation now uses a ring model for implementing
ODP queues. This results in greatly improved efficiency for queue operations.
The default maximum queue depth used is 4096 elements, and this information is
returned via the `odp_queue_capability()` API.
==== Validation Test Simplification
The tests that are part of the validation test suite are reorganized and
simplified by having a single test file for each API rather than separate
CUnit driver files and test files.
=== Test/Example Improvements
==== Crypto Test Improvements
The `crypto` validation test suite now offers better information on which
crypto algorithms were skipped because they are not available. Testing of
full HMAC lengths is now added
==== ODP Generator Improvements
The `odp_generator` example now offers configurable RX burst size, selectable
packet handling (Direct I/O or Scheduled I/O), as well as streamlined packet
processing.
==== `l2fwd` Example Improvements
The `l2fwd` example offers improved efficiency via better cache usage.
=== Bug Fixes
==== https://bugs.linaro.org/show_bug.cgi?id=3517[Bug 3517]
timer test might fail
==== https://bugs.linaro.org/show_bug.cgi?id=3572[Bug 3572]
time_main test fails if run under heavy load
==== https://bugs.linaro.org/show_bug.cgi?id=3576[Bug 3576]
classification: CoS queues in invalid table index
==== https://bugs.linaro.org/show_bug.cgi?id=3577[Bug 3577]
classification: multiqueue CoS will always fail
==== https://bugs.linaro.org/show_bug.cgi?id=3578[Bug 3578]
classification: requested number of queues is ignored in multiqueue CoS
==== https://bugs.linaro.org/show_bug.cgi?id=3579[Bug 3579]
cls: capability to return max hash queues
==== https://bugs.linaro.org/show_bug.cgi?id=3581[Bug 3581]
classification: invalid memory access in RSS hash
==== https://bugs.linaro.org/show_bug.cgi?id=3582[Bug 3582]
classification: incorrect IPv6 RSS hash
==== https://bugs.linaro.org/show_bug.cgi?id=3594[Bug 3594]
IPsec SA may be used before fully initialized
==== https://bugs.linaro.org/show_bug.cgi?id=3595[Bug 3595]
IPsec SA lookup may leave extra SAs locked
==== https://bugs.linaro.org/show_bug.cgi?id=3597[Bug 3597]
new generator test assumes that null:0 pktio is always present
==== https://bugs.linaro.org/show_bug.cgi?id=3613[Bug 3613]
packet_main test can fail
==== https://bugs.linaro.org/show_bug.cgi?id=3611[Bug 3611]
ODP linux-generic fails on AArch64 in non-ABI-compat mode
==== https://bugs.linaro.org/show_bug.cgi?id=3618[Bug 3618]
DPDK pktio stops receiving packets if all configured RX queues are not used
==== https://bugs.linaro.org/show_bug.cgi?id=3628[Bug 3628]
Another timer_main failure
==== https://bugs.linaro.org/show_bug.cgi?id=3632[Bug 3632]
Creating a pool with total size over 4.29GB (UINT32_MAX) leads to
undefined behavior
=== Known Issues
==== https://bugs.linaro.org/show_bug.cgi?id=2988[Bug 2988]
ODP exposes symbols outside of odp*/_odp* namespace
== OpenDataPlane (1.17.0.0)
=== New Features
ODP v1.17.0.0 is Tiger Moth Release Candidate 1 (RC 1). It introduces
significant new API support as well as functional refinements that expand
ODP offload support to cover IPsec, as well as other improvements.
==== APIs
The following new and changed APIs are included in this release:
===== Event Extensions
The ODP event model has been expanded to include new types as well as event
subtypes. Subtypes are used to qualify an event by indicating that the event
carries additional metadata relating to specific usage or operations.
New event `ODP_EVENT_IPSEC_STATUS` (to be discussed
below) is added. The initial subtypes defined are: `ODP_EVENT_PACKET_BASIC`,
`ODP_EVENT_PACKET_CRYPTO`, `ODP_EVENT_PACKET_IPSEC`, and
`ODP_EVENT_NO_SUBTYPE`, which are also discussed below.
Associated with this support, new event APIs are added:
* `odp_event_subtype()` extracts the `odp_event_subtype_t` from an
`odp_event_t`.
* `odp_event_types()` returns the `odp_event_type_t` and `odp_event_subtype_t`
of an `odp_event_t` in a single call.
* `odp_event_type_multi()` scans a list of `odp_event_t` objects and returns
the number that share the same indicated `odp_event_type_t`. This allows
multiple events to be processed by groups of the same event type.
* `odp_event_filter_packet()` scans a list of `odp_event_t` objects and
partitions them into a returned array of `odp_packet_t` objects and a remaining
array of non-packet events.
* `odp_event_free_multi()` frees multiple events in a single call.
* `odp_event_free_sp()` frees multiple events originating from the same
pool in a single call. The caller must assure that the input events are from
the same pool.
===== IPsec support
ODP Tiger Moth introduces comprehensive protocol offload support for IPsec,
allowing applications to leverage the IPsec acceleration capabilities of many
SoCs. Support includes APIs for Security Association (SA) creation and
lifecycle management, as well as IPsec packet operations for inbound (RX) and
outbound (TX) processing. Packet operations are further divided into lookaside
and inline support.
====== Lookaside Support
Lookaside processing enables IPsec packets to be decrypted into plain packets
or plain packets to be encrypted into IPsec packets in a single operation under
explicit application control. This is useful for packets that need pre- or
post-processing, or to better fit with existing application design.
Two forms of lookaside processing are provided: the `odp_ipsec_in()` and
`odp_ipsec_out()` APIs provide synchronous decrypt and encrypt support,
respectively. The corresponding `odp_ipsec_in_enq()` and `odp_ipsec_out_enq()`
APIs provide these same services in asynchronous form where operations can be
launched and completed later.
====== Inline Support
In contrast to lookaside support, IPsec inline support permits applications to
fully leverage the offload capabilities found in many SoCs by allowing inbound
IPsec packets to be recognized and decrypted automatically before they are
presented to the application for processing. This is done by configuring a
Security Association (SA) and its associated PktIO to operate in inline mode.
Similarly, following output SA and PktIO configuration, the
`odp_ipsec_out_inline()` API permits a packet to be encrypted into an IPsec
packet and automatically scheduled for TX processing in a single
operation. Such "fire and forget" processing enables applications to leverage
IPsec HW support for such processing in a portable manner.
Applications using IPsec inline support need only "touch" a packet once
compared to three times when using lookaside processing, leading to greater
processing efficiency.
====== IPsec Events
New event types and subtypes are introduced to provide support for IPsec
processing. The `ODP_EVENT_PACKET` type has a new subtype:
`ODP_EVENT_PACKET_IPSEC` that provides extended metadata associated with
IPsec packets that have been processed. The new `ODP_EVENT_IPSEC_STATUS`
event, in turn, is used to report IPsec status events such as completion
notifications associated with `odp_ipsec_sa_disable()` calls.
The `odp_ipsec_result()` API is used to obtain IPsec result metadata from
a packet that has event subtype `ODP_EVENT_PACKET_IPSEC`, while the
`odp_ipsec_status()` API is used to obtain IPsec status metadata from an
`ODP_EVENT_IPSEC_STATUS` event.
===== Parser APIs
Packet parsing has been overhauled with the introduction of two new APIs:
* `odp_packet_parse()`
* `odp_packet_parse_multi()`
These use an `odp_packet_parse_param_t` struct to control the type and depth
of parsing to be performed. These routines are intended to be used to
process packets that have been decapsulated following IPsec decryption or other
tunneling or on IP fragments after they have been reassembled.
Associated with this improved parse support, the `odp_parser_layer_t` struct
is deprecated and replaced with a more general `odp_proto_layer_t` struct that
is used both in PktIO configuration as well as the new parser APIs.
===== Crypto AES-CTR and AES-GMAC Support
The ODP crypto APIs are extended to provide support for AES-CTR cipher and
AES-GMAC authentication modes, reflecting the growing availability of
accelerated support for these.
===== Crypto removal of DES-CBC
DES-CBC is no longer considered secure and support for it is removed in ODP.
===== Crypto move AAD length to sessions
The Additional Authentication Data (AAD) length is now part of the
`odp_crypto_session_t` rather than individual crypto operations. This provides
better compatibility with DPDK, which made a similar API adjustment in it's
17.08 release.
===== Crypto Packet APIs
While the `odp_crypto_operation()` API is retained for compatibility,
new packet-oriented variants are introduced that provide additional
capabilities and flexibility. These APIs are:
* `odp_crypto_op()` Performs synchronous crypto operations on one or more
input packets under the control of an associated `odp_crypto_packet_op_param_t`
struct.
* `odp_crypto_op_enq()` Performs asynchronous crypto operations on or or more
input packets under the control of an associated `odp_crypto_packet_op_param_t`
struct.
While `odp_crypto_operation()` calls result in `ODP_EVENT_CRYPTO_COMPL` events
for compatibility, the new packet-oriented APIs result in `ODP_EVENT_PACKET`
events that carry the new event subtype `ODP_EVENT_PACKET_CRYPTO`. These
packets contain additional metadata associated with the crypto operation.
New APIs added for manipulating this metadata include:
* `odp_crypto_packet_from_event()` converts an `odp_event_t` of type
`ODP_EVENT_PACKET` and subtype `ODP_EVENT_PACKET_CRYPTO` to an `odp_packet_t`.
* `odp_crypto_packet_to_event()` converts an `odp_packet_t` crypto packet
back into an `odp_event_t`.
* `odp_crypto_result()` extracts the `odp_crypto_packet_result_t` struct that
contains the crypto metadata associated with an `odp_packet_t` of event
subtype `ODP_EVENT_PACKET_CRYPTO`. This struct provides a summary bit that
says whether the operation completed successfully as well as
`odp_crypto_op_status_t` fields for the `cipher_status` and `auth_status` if a
problem was detected.
===== Classification Random Early Detection (RED) Support
Random Early Detection (RED) provides a means for input HW to ensure that
traffic is treated fairly under conditions of temporary resource overload due
to excessive inbound traffic. ODP RED support provides the ability to measure
and respond to resource pressure on either pools or queues, and only provides
flexibility in how such conditions are to be processed. They can result in
input packet drops or backpressure being indicated by transmitting pause
frames, depending on the underlying platform capabilities.
The `odp_cls_capability_t` struct returned by the `odp_cls_capability()` API
has been expanded to cover this support.
===== Time difference in nanoseconds
The new `odp_time_diff_ns()` API permits the delta between two `odp_time_t`
values to be computed in a single call.
===== PktIO API Changes
====== PktIO Maximum Frame Lengths
The `odp_pktio_mtu()` API is deprecated and replaced by two new APIs:
`odp_pktin_maxlen()` and `odp_pktout_maxlen()`. These return the maximum
sized packets that are supported for RX and TX processing,
respectively, on a given `odp_pktio_t`.
====== PktIO settable MAC address
The `odp_pktio_mac_addr_set()` API is added to allow setting of the MAC
address associated with an `odp_pktio_t`. The `odp_pktio_set_op_t` field of
the `odp_pktio_capability_t` returned by the `odp_pktio_capability()` API now
includes the `mac_addr`` field to indicate that this `odp_ptkio_t` supports
setting its MAC address.
====== Multiple loop devices
The reserved device name `loop` is now extended to `loopX` where X == integer
(_e.g.,_ `loop1`, `loop2`, etc.). For compatibility, `loop` is a synonym for
`loop0`.
===== Pool API Changes
====== Pool extent info
The `odp_pool_info()` API is extended to return the `min_data_addr` and
`max_data_addr` fields. These provide information about the minimum and maximum
application-visible addresses that may be seen in objects allocated from a
particular `odp_pool_t`. Some applications use this information to enable them
to store buffer addresses in compressed format. For example, if the
"span" of valid addresses is less than 4GB this allows a 64-bit buffer address
to be stored as a 32-bit offset.
Since this is purely informational, ODP implementations are under no constraint
as to what addresses may be returned for these fields. 0 and `UNINTPTR_MAX`
may be used if there are no limits on pool extents.
====== Pool subparameter support
The `odp_pool_param_t` structure has been expanded to provide more flexibility
to support platforms that are able to offer multiple segment sizes within a
single pool. This can lead to greater storage efficiency. These are called
subparameters and implementations supporting up to 7 of these are accommodated
with these extensions.
The `odp_pool_capability_t` structure is expanded to return the number of
subparameters supported by this implementation. The application, in turn,
specifies its expected packet size and number distribution in the
`odp_pool_pkt_subparam_t` structure that is part of the `odp_pool_param_t`
used to define the characteristics of `ODP_POOL_PACKET` pools.
This is fully compatible with previous packet pool support since ODP
implementations are under no obligation to support pool subparameters and
these, when present, are advisory in nature. They simply serve to allow the
application to better communicate its expected packet distribution within a
pool so that the ODP implementation may better optimize storage use in the
pool.
===== Checksum support
Checksum processing support has been formalized with the addition of APIs for
determining packet checksum status, controlling packet checksum processing,
retrieving partially computed checksums on packets, and computing checksum
partial sums for memory areas.
====== Checksum status
The APIs `odp_packet_l3_chksum_status()` and `odp_packet_l4_status()` are
added to allow the results of packet input checksum processing to be
queried. These APIs return an `odp_packet_chksum_status_t` enum that indicates
whether checksum validation processing was performed and if so whether the
layer 3 or 4 checksum was found to be valid. This is applicable to both
normal packet input as well as those processed via IPsec.
====== Checksum insertion
PktIOs output checksum processing is configured as part of the
`odp_pktout_config_opt_t` struct used as input to `odp_pktio_config()` API.
These control whether L3 and/or L4 checksums are to be inserted by default
as part of packet TX processing.
Individual packets may override these defaults via the new
`odp_packet_l3_chksum_insert()` and `odp_packet_l4_chksum_insert()` APIs. These
take precedence over the PktIO default, allowing checksums to be inserted
when the PktIO default is to not insert checksums or to suppress checksum
insertion if when the PktIO default is to insert checksums.
====== One's complement sums
Two new APIs: `odp_packet_ones_comp()` and `odp_chksum_ones_comp16()` are
added to assist in application-managed checksum processing. If an
implementation has computed a partial checksum as part of the receive
processing for an IP fragment, for example, then `odp_packet_ones_comp()` can
be used to retrieve this computed value, as well as the byte range over which
it was computed. The `odp_chksum_ones_comp16()` API, by contrast, allows the
application to perform a 16-bit ones-complement sum over a range of in-memory
bytes. Together these can be used to calculate IPv4, TCP, and UDP checksums.
===== Packet multi-event conversion and single pool support
New packet APIs have been added to streamline packet processing:
* `odp_packet_free_sp()` is the same as `odp_packet_free_multi()` except that
the application guarantees that all packets come from the same pool.
* `odp_packet_from_event_multi()` allows multiple events to be converted
from `odp_event_t` to `odp_packet_t` objects in a single call. The caller
guarantees that all input `odp_event_t` objects are of type `ODP_EVENT_PACKET`.
* `odp_packet_to_event_multi()` converts multiple `odp_packet_t` objects to
corresponding `odp_event_t` objects in a single call.
===== Shared Memory API changes
Several changes have been made to the ODP shared memory APIs:
* The `name` field used as input to `odp_shm_reserve()` is now optional.
If specified as `NULL` the shared memory area is anonymous and cannot be
looked up with `odp_shm_lookup()`. There is also no requirement that names be
unique. Duplicate names result in indeterminate output from `odp_shm_lookup()`.
* The `odp_shm_info_t` now includes the `page_size` of the shared memory block
and it's (optional) name.
* `odp_shm_print()` API is added to print implementation-defined information
associated with the `odp_shm_t` to the ODP log for diagnostic purposes.
===== Add support for non-blocking Queues
New queue attributes are introduced to characterize queue behavior as
blocking or non-blocking. A blocking queue may stall other threads if a thread
is interrupted or suspending during an enqueue or dequeue operation.
Nonblocking queues may be either lock free or wait free and provide
progress and fairness guarantees to all threads regardless of
interruptions or stalls on the part of threads performing queue operations.
The various `odp_nonblocking_t` attributes available are returned by the
`odp_queue_capability()` API for both plain and scheduled queues and are in
turn requested as part of the `odp_queue_param_t` struct passed to the
`odp_queue_create()` API. The intent is to allow applications that have
realtime response requirements to better express these needs and utilize
platform-specific capabilities in this area.
===== Scheduler ordered lock API changes
The following changes have been made to the scheduler APIs:
* Documentation clarifies that an ordered context may only hold one ordered
lock at a time. Results are undefined if a second ordered lock is attempted to
be acquired while already holding one.
* The `odp_schedule_order_unlock_lock()` API is added to permit an ordered
context to switch from one ordered lock to another in a single operation.
===== Timer Capabilities
The `odp_timer_capability()` API is added to return an `odp_timer_capability_t`
struct that details platform-specific timer capabilities for application use.
The only capability currently defined is `highest_res_ns`, which indicates the
highest supported resolution supported by a timer. This is the minimum valid
value for the `res_ns` timer pool parameter.
=== Scalable Scheduler
The `odp-linux` reference implementation adds a new _scalable scheduler_ to
the existing default, strict priority, and iquery schedulers. This is enabled
by:
`./configure --enable-schedule-scalable`
The scalable scheduler is designed to offer superior scalability in many core
environments, especially on AArch64 platforms.
=== Miscellaneous Fixes and Improvements
The following miscellaneous improvements have been made to the `linux-generic`
reference implementation of ODP.
==== Additional packet inline functions
When compiling with `--enable-abi-compat=no` the following additional packet
functions are inlined:
* `odp_packet_l2_offset()`
* `odp_packet_l2_ptr()`
* `odp_packet_l3_offset()`
* `odp_packet_l3_ptr()`
* `odp_packet_l4_offset()`
* `odp_packet_l4_ptr()`
==== Dependencies
The ODP test suite now automatically skips C++ tests if no C++ compiler
is available.
The odp_pktio_ordered tests are only performed if PCAP is available.
The DEPENDENCIES file has been updated to reflect build/test requirements for
running under Red Hat Linux distributions.
==== DPDK 17.08 Support
PktIO DPDK support has been upgraded to DPDK 17.08.
=== Test/Example improvements
=== l2fwd Example
A verbose option is added to provide more detail on test runs.
=== ODP generator
Numerous performance improvements have been made that results in significantly
better I/O rates. This includes a configuration option to control checksum
usage.
=== Bug Fixes
==== https://bugs.linaro.org/show_bug.cgi?id=3465[Bug 3465]
CID 1461688: odp_pool_create: Dereference before null check
==== https://bugs.linaro.org/show_bug.cgi?id=3466[Bug 3466]
CID 1396968: buggy check
==== https://bugs.linaro.org/show_bug.cgi?id=3491[Bug 3491]
l2fwd segfaults on api-next with dpdk checksum insertion override
=== Known Issues
==== https://bugs.linaro.org/show_bug.cgi?id=3210[Bug 3210]
packet header parsing routines should verify header checksums
==== https://bugs.linaro.org/show_bug.cgi?id=3517[Bug 3517]
timer test might fail
== OpenDataPlane (1.16.0.0)
=== New Features
ODP v1.16.0.0 is the final preview release before the official release of
Tiger Moth. It introduces new APIs and extensions, as well as bug fixes and
functional improvements.
==== APIs
The following new and changed APIs are included in this release:
===== Initialization Changes
The new `odp_feature_t` type is introduced that defines various feature bits
for ODP components. This is used in an expanded `odp_init_t` argument to
`odp_init_global()` to specify which ODP features are unused by the
application. For example, if the application knows it will not be making use
of crypto features or the classifier, this may permit the ODP implementation
to configure itself more efficiently. Results are undefined if an application
asserts that it will not be using a feature and it attempts to do so
afterwards.
Associated with this new support the `odp_init_param_init()` API is added
to initialize the `odp_init_t` struct to default values.
===== Packet API Changes
* The `odp_packet_unshared_len()` API is removed. Testing showed that this
API was non-essential and conflicted with the goal of implementation
efficiency.
* The `odp_print_packet_data()` API is added. This permits packet data to
be logged along with platform-defined metadata for debugging or diagnostic
purposes.
===== PktIO API Changes
* The `loop_supported` attribute of the `odp_pktio_capability_t` struct is
deprecated since this is redundant. The `enable_loop` field of the
`odp_pktio_config_t` struct (which is returned as part of the
`odp_packet_capability_t` struct) is the proper way to determine whether a
PktIO supports loopback mode.
===== System Info API Changes
* The documentation for the `odp_sys_huge_page_size()` API is updated to
clarify that a 0 return code indicates that huge pages are not supported by
this platform.
* The `odp_sys_huge_page_size_all()` API is added to return all
huge page sizes supported by this platform.
===== Timer API Changes
* The documentation for the various parameters contained in the
`odp_timer_pool_param_t` struct are expanded and clarified.
=== Miscellaneous Fixes and Improvements
==== Default Packet Headroom
The default packet headroom in `odp-linux` has been increased from 66 to
128 bytes for better compatibility with `odp-dpdk`.
==== Zero-copy Packet References
The `odp-linux` reference implementation now fully supports zero-copy
packet references. Previously these APIs were implemented via packet copies,
which while functionally correct, were not how these APIs are intended to
operate.
==== DPDK Zero-copy I/O support
The `--enable-dpdk-zero-copy` `configure` option is added to allow DPDK PktIO
devices to avoid data copies, leading to improved performance.
==== DPDK Checksum offload support
DPDK PktIO now makes use of RX and TX IP/UDP/TCP checksum offload.
==== Shared memory stored in /dev/shm
In the `odp-linux` reference implementation, shared memory is now backed to
`/dev/shm` rather than `/tmp` for better reliability and robustness. This may
be overridden as part of ODP build-time customization if desired.
==== IPC Improvements
PktIO IPC support has received improvements in both performance and
reliability and is now suitable for development use.
==== Netmap Improvements
The thread ID is now used to create unique vdev MAC addresses to avoid
conflicts with multiple ODP processes running on the same host system.
==== `drv` directory removed
The `include/odp/drv` directory and related files have been removed. Driver
support is moved to a follow-on ODP release, so removing these files avoids
confusion as they are still incomplete.
=== Dependency Changes
==== Dependency on autoconf-archive removed
Since some build environments do not supply autoconf-archive, this dependency
is removed.
==== DPDK support upgraded to 17.08 release
The ODP DPDK Packet I/O support has been upgraded to work with the DPDK 17.08
release.
==== Added support for OpenSSL 1.1.x releases
ODP use of OpenSSL for crypto processing has been upgraded to allow use of
OpenSSL 1.1.x.
=== Build System Restructure
The ODP build system has been overhauled to support more comprehensive and
efficient automated testing under Travis CI. Greater use of Autoconf is now
made to control ODP configuration and build options, permitting greater
environmental flexibility. This includes an expanded range of test coverage,
including cross-compilation support for ARMv8, MIPS,and Power architectures,
as well as testing under the latest levels of GCC and clang.
=== Arm Architecture Support Improvements
* ARMv8 generic timer support is now included
* Improved time efficiency and accuracy by using native ARMv8 time/clock
instructions.
==== Test Improvements
The `test` directory has been reorganized and streamlined. Platform-specific
tests are moved from `test/linux-generic` to
`platform/linux-generic/test/`. As a result, the `test/common_plat`
directory is deleted so that `test/validation`, `test/performance`, etc. are
now used for all platform-independent tests.
==== Examples Improvements
===== IPv4 Fragmentation Reassembly Example
The `ipfragreass` example program has been added to demonstrate IPv4 fragment
reassembly.
===== ODP Generator Improvements
The `odp_generator` example program now uses packet references for improved
performance in UDP and ICMP traffic. The program also now makes use of HW
checksum offload support, when available.
=== Documentation Improvements
* The ODP Users Guide has clarified usage information about the ODP time
APIs for better portability.
* A section has been added to the ODP Users Guide on API specification
principles. This clarifies expected behavior of ODP applications and
implementations and makes explicit what the specification means by "undefined
behavior".
* All Doxygen used in ODP is upgraded to conform to the stricter documentation
requirements introduced by Doxygen 1.8.13.
=== Bug Fixes
==== https://bugs.linaro.org/show_bug.cgi?id=2254[Bug 2254]
check-odp: valgrind generates "No rule to make target"
==== https://bugs.linaro.org/show_bug.cgi?id=2407[Bug 2407]
test odp_l2fwd_run.sh contains todo items
==== https://bugs.linaro.org/show_bug.cgi?id=2812[Bug 2812]
Helper/test/process fails on a single core system
==== https://bugs.linaro.org/show_bug.cgi?id=2861[Bug 2861]
Remove redundant loop_support parameter in pktio capability
==== https://bugs.linaro.org/show_bug.cgi?id=2938[Bug 2938]
Make file deps failure
==== https://bugs.linaro.org/show_bug.cgi?id=2976[Bug 2976]
IP headers checksum functions are incorrect
==== https://bugs.linaro.org/show_bug.cgi?id=3024[Bug 3024]
odp_traffic_mngr example is broken
==== https://bugs.linaro.org/show_bug.cgi?id=3026[Bug 3026]
pktio_ipc_run test can fail due to segfault
==== https://bugs.linaro.org/show_bug.cgi?id=3043[Bug 3043]
User guide error (packet diagram fix)
==== https://bugs.linaro.org/show_bug.cgi?id=3052[Bug 3052]
api-next out of tree build broken
==== https://bugs.linaro.org/show_bug.cgi?id=3066[Bug 3066]
Cross compile broken for ARMv8
==== https://bugs.linaro.org/show_bug.cgi?id=3126[Bug 3126]
IPC pktio test fails with taskset -c 1-2
==== https://bugs.linaro.org/show_bug.cgi?id=3177[Bug 3177]
Test case for classification enable
==== https://bugs.linaro.org/show_bug.cgi?id=3182[Bug 3182]
Memory allocation checks (in traffic manager)
==== https://bugs.linaro.org/show_bug.cgi?id=3216[Bug 3216]
Adding --enable-helper-linux configure flag breaks build
==== https://bugs.linaro.org/show_bug.cgi?id=3238[Bug 3238]
Doxygen warnings on helper header files
==== https://bugs.linaro.org/show_bug.cgi?id=3241[Bug 3241]
codecov: _odp_packet_cmp_data is not covered
==== https://bugs.linaro.org/show_bug.cgi?id=3242[Bug 3242]
setup_pktio_entry missing unlock
==== https://bugs.linaro.org/show_bug.cgi?id=3249[Bug 3249]
odp_cpu_hz() does not work on all Linux distros
==== https://bugs.linaro.org/show_bug.cgi?id=3262[Bug 3262]
Missing doxygen detected by Travis
==== https://bugs.linaro.org/show_bug.cgi?id=3289[Bug 3289]
'num_queues' isn't ignored when "classifier_enable" is enabled
==== https://bugs.linaro.org/show_bug.cgi?id=3300[Bug 3300]
Validation tests cannot be disabled after commit b4d17b1
==== https://bugs.linaro.org/show_bug.cgi?id=3411[Bug 3411]
wrong openssl_lock pointer type
=== Known Issues
==== https://bugs.linaro.org/show_bug.cgi?id=3245[Bug 3245]
Cannot run l2fwd application on Cavium ThunderX platform
== OpenDataPlane (1.15.0.0)
=== New Features
ODP v1.15.0.0 continues the preview of Tiger Moth, introducing new APIs and
extensions, as well as numerous bug fixes and functional improvements.
==== Deprecation Framework
To permit smoother evolution of the ODP API specification, a deprecation
framework is introduced to permit controlled deprecation.
When an ODP API or defined struct parameter is deprecated, ODP validation
tests will be updated to no longer use that API and instead use the
replacement API. By default, attempts to compile with the older API/feature
will fail and applications wishing to move to the new ODP release should be
updated to use the replacement API. To permit evaluation of new ODP
releases in advance of such updating, however, ODP supports the `configure`
option `--enable-deprecated`, which makes the obsolete APIs visible again.
This feature will be used on a case-by-case basis and documented in the
release notes for each release that introduces replacement API(s). In general
the deprecated forms will not be maintained for more than a single release
cycle. After that they will no longer be present in the API specification and
the replacement forms must be used to compile with that level of the API
specification.
==== APIs
A number of new and refined APIs are introduced in crypto, packet parsing,
and queue configuration:
===== Crypto Enhancements
The ODP crypto APIs receive several enhancements in this release:
====== New Authentication Algorithms
Additional enumerations added for HMAC-SHA-1 and HMAC-SHA-512 authentication.
====== Deprecated Cipher/Authentication Algorithms
The following cipher/authentication algorithms have been deprecated in favor
of newer replacement algorithms:
* `ODP_CIPHER_ALG_AES128_CBC` is replaced by `ODP_CIPHER_ALG_AES_CBC`
* `ODP_CIPHER_ALG_AES128_GCM` is replaced by `ODP_CIPHER_ALG_AES_GCM`
* `ODP_AUTH_ALG_MD5_96` is replaced by `ODP_AUTH_ALG_MD5_HMAC`
* `ODP_AUTH_ALG_SHA256_128` is replaced by `ODP_AUTH_ALG_SHA256_HMAC`
* `ODP_AUTH_ALG_AES128_GCM1 is replaced by `ODP_AUTH_ALG_AES_GCM`
====== Deprecated Name for Crypto Parameter struct
`odp_crypto_op_params_t` is deprecated in favor of `odp_crypto_op_param_t`
for consistency with other ODP `param` structs.
====== Digest Length Session Parameter
`odp_crypto_session_param_t` adds the field `auth_digest_len` to permit
specification of the authentication digest length to be used for this
session. The `odp_crypto_auth_capability()` API returns the list of
supported digest lengths.
====== Additional Authentication Data (AAD)
The `odp_crypto_op_param_t` struct adds an optional pointer and length for
AAD information. This allows applications to specify AAD information from
the list of supported lengths provided by `odp_crypto_auth_capability()`.
===== Packet Range Data
The former `odp_crypto_data_range_t` type is deprecated and renamed to
`odp_packet_data_range_t` since it can be used to specify ranges for other
than crypto purposes.
===== Parser Configuration
Applications may now specify the maximum packet layer of interest. For
example, a router may not care about anything beyond ISO Layer 3 in packets.
This can be used by ODP implementations to control the depth of packet
parsing needed by the application and may allow greater efficiency,
especially in software implementations.
This is controlled by a new `odp_pktio_parser_layer_t` enum that is
part of the new `odp_pktio_parser_config_t` struct that is added to the
`odp_pktio_config_t` struct used by the `odp_pktio_config()` API. The
supported parser layers are also returned in this struct as part of the
`odp_pktio_capability_t` struct returned by the `odp_pktio_capability()` API.
===== Queue Size Parameter
The `odp_queue_capability_t` struct returned by the `odp_queue_capability()`
API is enhanced as follows:
* The `max_queues` field is now defined to return the maximum number of event
queues of any type.
* New sub-structs (`plain` and `sched`) are added that detail the `max_num` of
queues of that type supported as well as the new field `max_size` that
specifies the maximum number of elements that each queue of this type can
store. A value of zero for `max_num` indicates no fixed limit.
In addition, the `odp_queue_param_t` passed to `odp_queue_create()` now adds
a `size` field to allow applications to specify the minimum number of events
that this queue should be able to store. A value of zero specified requests that
the implementation default limits be used.
The ODP examples have been updated to show this configuration, for example,
the `l2fwd_simple` example does Layer 2 forwarding and hence doesn't need
packets to be parsed beyond Layer 2. So prior to opening an interface via
`odp_pktio_open()` the configuration processing now includes code of the form:
[source,c]
-----
odp_pktio_config_init(&config);
config.parser.layer = ODP_PKTIO_PARSER_LAYER_L2;
odp_pktio_config(pktio, &config);
-----
This serves as a hint to the ODP implementation that parsing beyond Layer 2
is not required on this interface.
===== Removal of `odp_time_to_u64()` API
The `odp_time_to_u64()` API is removed without deprecation in this release.
This is redundant since the `odp_time_to_ns()` API already returns a `uint64_t`
value for `odp_time_t` and can be used for the same purpose.
===== New `odp_sys_info_print()` API
For debugging / diagnostic use, the `odp_sys_info_print()` API is added.
This prints implementation defined information about the system and ODP
environment and may contain information about CPUs, memory, and other
hardware configuration.
=== Helpers
==== Linux Helpers
ODP helper functions fall into two categories: system-independent, and those
that rely on Linux. For backwards compatibility, these have been
reorganized into a new `helper/linux` directory that is installed only when
the `--enable-helper-linux` `configure` option is specified.
=== `odp-linux` Performance
==== Scheduler Improvements
The default scheduler is streamlined by using precomputed weight tables and
separated priority queues for different scheduling groups. This improves
both latency and scalability.
Also included in this change, the default number of scheduling groups is
lowered from 256 to 32, which experience has shown is sufficient for most
applications.
The scheduler fairness checks are also enhanced to avoid low priority event
starvation if `CONFIG_BURST_SIZE` is set to 1.
=== `odp_linux` Crypto Improvements
* Errors in implicit packet copy operations performed during crypto operation
are now handled properly.
* If `odp_crypto_session_create()` fails, proper cleanup is now performed to
avoid memory leaks.
* The auth digest len is now used when calculating HMACs, and full-length
digests are now added to supported SHA capabilities.
* Numerous crypto functions have been rewritten to use the OpenSSL `EVP_`
functions for improved efficiency and accuracy.
=== `odp-linux` Packet Improvements
* The packet parser now recognizes ICMPv6 packets in addition to ICMPv4.
=== `odp-linux` PktIO Improvements
* The `ethtool` and `socket` drivers add additional initializations to avoid
valgrind warnings.
* The `dpdk` driver is upgraded to DPDK 17.02 and is now also built with the
`--whole-archive` option, which means that PMDs no longer need to be linked
individually but are automatically included in builds that make use of DPDK
pktio support.
=== `odp-linux` Time Improvements
* The ODP Time APIs are now more efficiently handled by replacing the previous
Linux timespec with simple nanoseconds (ns) and using native hardware time
counters in x86 and ARM environments, when available.
=== `odp-linux` Traffic Manager Improvements