-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
1524 lines (1185 loc) · 58.6 KB
/
README
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
#
# Copyright (c) 2015-2023 Cadence Design Systems, Inc.
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be included
# in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
======================================================================
Xtensa Audio Framework (XAF) - Hosted solution
======================================================================
======================================================================
Revision History
======================================================================
Version Hosted 1.0 API 3.3 : November 17, 2023
+ GA Release
+ Built and tested with RI.9 tools
+ [TENA-3231] FreeRTOS: updated commit ID which fixes tick-timer
update issue (2ca806e59d8eb2490726f2ce1460f256ab593cf3).
+ [TENA-4141] Testbench: Runtime disconnect-without-delete commands
are now processed on a separate thread.
+ [TENA-4150] Mixer class change to fix a corner case by reordering
input over and set input bytes API calls with related plugin
changes.
+ [TENA-4151] memset xf_g_dsp structure pointer to avoid fsanitize
warning.
+ [TENA-4152] Restrict Hosted IPC kernel driver to communicate with
only one application.
+ [TENA-4154] Testbench: Increased get_status_cid array size to fix
array overflow error.
+ [TENA-4156] Added NULL check in xaf_adev_set_priorities API call for
adev pointer.
+ [TENA-4158] Plugin: Compile fix in opus-decoder for shared memory
macro MEM_START_DATA
+ NOTES:
1. Hosted XAF tests require a XTSC subsystem to compile and
run, so they would not compile and run OOB. Refer to Programmer's
guide for steps to:
- Build the subsystem,
- Build and run Hosted XAF tests with the built subsystem.
2. Only tested for subsystems with 1 Host + up to 8 HiFi DSPs.
3. Any reference to 'hostless' in the package source files can
be ignored as the package is for hosted-XAF solution.
4. Limited testing is done with 64-bit version of Host OS.
+ KNOWN LIMITATIONS:
1. Package is available in TGZ format only.
2. The following features are not supported on 64-bit version of
Host Linux OS:
- Zero copy mode of xaf_comp_get_config_ext API
- Zero copy mode of xaf_comp_set_config_ext API
3. Multiple memory pool feature is only supported for
XAF_MEM_ID_COMP to XAF_MEM_ID_COMP_FAST type of memory amongst
enum XAF_MEM_ID.
4. MCPS, Memory numbers printed correspond to DSP which does not
include Host side info.
5. IPC shared-memory between host IPC-kernel and main DSP is
uncached.
----------------------------------------------------------------------
Version 0.9_Beta API 3.3 : August 18, 2023
+ Hosted XAF
+ Beta Release
+ Built and tested with RI.9 tools.
+ [TENA-3231] FreeRTOS timer interrupt issue is resolved and github
commit id is updated. This fix enables execution of
capturer/renderer based testbenches.
+ [TENA-3887] Changes in class-audio-codec and class-mixer to support
execution with partial input data.
+ [TENA-3970] FLUSH/INVALIDATE macro cleanup and consolidation done
in XAF library.
+ [TENA-4112] Free-up temporary output buffer if xaf_comp_delete is
called before component was initialized (class-audio-codec).
+ Enabled hosted execution with one host and multiple DSP cores.
+ Enabled two-way handshake between host IPC and DSP-IPC for initial
sync.
+ Ensured re-initialization of queues and indexes in Linux kernel
driver.
+ Added a mem_pool_type check in xf-mem.h for robustness.
+ Enabled xaf_set_config_ext and xaf_get_config_ext API support with
zero-copy and non-zero copy mode in 32-bit version of Host OS.
+ Made improvements in DSP-DSP synchronization mechanism by adding a
non-pattern store change before reset-sync procedure which uses
handshake with a fixed pattern.
+ Fix for a corner case DSP local memset which was affected by
Host-DSP interrupt, as interrupt-handler used a local memory
resource which was being memset, causing a freertos test to hang,
hence avoided the meset of this COMP_ID pool, to be done at the
component appropriately.
+ Changes to enable memory usage and MCPS prints after execution
for NCORES>1.
+ Reduced the memory delay values from 100 to 1 in XTSC simulation
command in cosim_launcher2.py file.
+ Added xaf-config-user.h for user configurable parameters such as
specifying the shared memory address. Made necessary changes in
hifi-dpf and xf_kernel_driver to use shared memory address from
xaf-config-user.h.
+ Fixed a pointer issue in xaf_get_mem_stats API in xaf-api.c causing
a segfault in 64-bit version of Host OS.
+ Testbench changes:
1. Changes to support multi-core build.
2. Runtime command line parsing changes for NCORES>1 in the
testbenches that support command line parsing.
3. Updated initialization logic for AAC testbench to fix a corner
case.
4. Corrected version prints during execution.
+ Plugin changes:
1. Necessary changes in mixer to support execution with partial
input data.
+ NOTES:
1. Hosted XAF tests require a XTSC subsystem to compile and
run, so they would not compile and run OOB. Refer to Programmer's
guide for steps to:
- Build the subsystem,
- Build and run Hosted XAF tests with the built subsystem.
2. Only tested for subsystems with 1 Host + up to 6 HiFi DSPs.
3. Any reference to 'hostless' in the package source files can
be ignored as the package is for hosted-XAF solution.
4. Limited testing is done with 64-bit version of Host OS.
5. Not tested with L32EX core config variants.
+ KNOWN LIMITATIONS:
1. Package is available in TGZ format only.
2. The following features are not supported on 64-bit version of
Host Linux OS:
- Zero copy mode of xaf_comp_get_config_ext API
- Zero copy mode of xaf_comp_set_config_ext API
3. Multiple memory pool feature is only supported for
XAF_MEM_ID_COMP to XAF_MEM_ID_COMP_FAST type of memory amongst
enum XAF_MEM_ID.
4. MCPS, Memory numbers printed correspond to DSP which does not
include Host side info.
5. IPC shared-memory between host IPC-kernel and main DSP is
uncached.
----------------------------------------------------------------------
Version 0.5_Alpha API 3.2 : April 14, 2023
+ Hosted XAF
+ Alpha Release
+ Built and tested with RI.9 tools
+ Programmers Guide not updated
+ The DSP Interface Layer is physically separated from the App
Interface Layer. The IPC abstractions consists of Linux kernel-IPC
at the host-AP that communicates with the HiFi DSP-IPC using
interrupts and shared-memory.
+ algo
1. Added xf-fio.c in host-apf/src and support files in
host-apf/include/sys/fio for application-to-kernel-IPC interface.
2. Modified xaf_get_mem_stats API to provide execution cycle info,
for MCPS calculation with the stream-duration info available at the
application.
+ build
1. Separated DSP binary build with required plugin support to
compile with Xtensa-Tools, plugin objects are linked to DSP binary.
2. Host-AP application binary compiles with gcc/gnu tools and the
plugin libraries are absent here.
+ test
1. Added xaf-dsp-test.c for DSP binary to run under XTSC.
+ IPC
1. Added xf_kernel_driver directory with source (xf-proxy.c) and
support files on the host-AP.
2. XTSC environment is used to execute DSP, LUA script interacting
via shared-memory and interrupt with linux-kernel-IPC layer
+ DOC:
HiFi-AF-Hosted-UserGuide.pdf contains steps and notes to use the
TGZ package.
+ NOTES:
1. Hosted XAF tests require a XTSC subsystem to compile and
run, so they would not compile and run OOB. Refer to the user guide
for steps to:
- Build the subsystem,
- Build and run Hosted XAF tests with the built subsystem.
2. Only tested for a subsystem with 1 Host + 1 HiFi DSP
3. Any reference to 'hostless' in the package source files can
be ignored as the package is for hosted-XAF solution.
4. Multicore XAF v3.5 GA release is the reference codebase. Hosted
XAF differs in IPC interfaces and application build segregation.
+ KNOWN LIMITATIONS:
1. Tested with XOS and Cache disabled.
2. DSP execution with FreeRTOS may not work as expected or hang for
applications that have Capturer and Renderer class of components
due to timer interrupts not getting generated by FreeRTOS library.
Limited testing is done with FreeRTOS.
3. Inconsistent cycle count is observed with XOS of RI-2022.9
Xtensa Tool chain which may lead to negative MCPS being logged.
4. Package is available in TGZ format only.
5. The following features are not supported:
- xaf_comp_get_config_ext API
- xaf_comp_set_config_ext API
- multiple memory-pools
----------------------------------------------------------------------
Version 3.5 API 3.2 : December 20, 2022
+ GA Release
+ Built and tested with RI.9 tools
+ [TENA-3271] Added compiler option '-ffunction-sections', linker
option '-Wl,-gc-sections' in library and testbench makefiles.
+ [TENA-3457]: Added short description comments for relevant
macros/defines used in testbench and plugins.
+ [TENA-3622] Robustness fixes, added attribute align changes to
packed structures with xf_msg_id_dtype, increased alignment for an
internal memory allocation ('Memory used by Framework' in test
application) for xaf_comp_t structure type.
+ [TENA-3681] The following miscellaneous updates are done:
1. Adjusted index of component memory in xaf_get_mem_stats to be
common to both NCORES=1 and NCORES>1 builds.
2. Added default init value for framework_local_buffer_size.
3. Removed unused macro XAF_SHMEM_STRUCT_SIZE from xaf-api.h.
4. Removed unused variable dsp_frmwk_buf_size_peak from
xaf_perf_stats_s structure.
5. Renamed dsp_xaf_buf_size_peak to
dsp_framework_local_buf_size_peak in struct xaf_perf_stats_s.
6. Added COMP_FAST and DEV_FAST memory pool for input and output
of mixer component.
+ [TENA-3689] Replaced strstr with strncmpr for component-type
matching.
+ [TENA-3690] Updated macro handling of force close on fatal error
in the testbench to wait for the completed, aborted threads to join
before returning from main thread gracefully.
+ [TENA-3694] Corrected testbench argument parsing logic to return
error if unsupported commands are provided in command-line.
+ [TENA-3702] Fixed a bug to allocate sufficient memory for DSP
side internal structure by using sizeof() instead of a fixed size.
Also added range checks for ID_DEV and ID_COMP memory pools and
the number of pools limited to a maximum of 8 each.
Note: This is not limitation of XAF library and is added to
prevent errors at test-application.
+ [TENA-3704] Fixed warnings observed with the compiler flags
'-Wimplicit-int-conversion', '-Wunused-macros', '-Wsign-compare'
and "-Wshadow" in XAF library.
+ [TENA-3712] Removed redundant exit code prints in thread join
messages from all testbenches.
+ [TENA-3713] Resolved subsystem import error due to tools version
mismatch in XWS package.
+ [FREERTOS] Updated to latest commit id on github that includes a
bug fix (0909de2bd46fbb9d9f7297e09c17186275dc446c).
+ Compile out option for the component classes (undefined by default):
XA_DISABLE_CLASS_AUDIO_CODEC, XA_DISABLE_CLASS_CAPTURER,
XA_DISABLE_CLASS_MIXER, XA_DISABLE_CLASS_MIMO_PROC,
XA_DISABLE_CLASS_RENDERER.
+ Testbench:
1. Increased a memory size (AUDIO_COMP_FAST_BUF_SIZE) to support
more testcases.
2. Added framework memory usage print for XAF_MEM_ID_DEV_FAST pool.
+ NOTES:
1. The release package can build and execute the single-core
XAF-hostless tests OOB.
2. Multicore XAF tests require a multicore-subsystem to compile and
run, so they would not compile and run OOB. Refer Programmer's Guide
for steps to:
- Build multicore-subsystem,
- Build and run multicore XAF tests with built subsystem.
3. Tested for a subsystem with a maximum of 8 Cores.
+ KNOWN LIMITATIONS:
1. XTSC supports simulation of up to a maximum of 16 cores.
2. With FreeRTOS, the renderer component, if created on a
worker-DSP, may not execute leading to pipeline hang, due to
timer-interrupts not generated by FreeRTOS library.
3. Inconsistent cycle count is observed on XOS with RI-2022.9
Xtensa tool chain which can lead to logging negative MCPS.
----------------------------------------------------------------------
Version 3.4_Alpha API 3.2 : September 16, 2022
+ Alpha release
+ Built and tested with RI.6 tools
+ Programmers Guide not updated
+ Scratch memory alignment changed from 8 to 16 bytes.
+ [J3278] Added support for non-component(ID_DEV) memory allocation
from different memory-pools.
Default mem_pool_types for edge component input/output buffers
XAF_MEM_POOL_TYPE_COMP_APP_INPUT, XAF_MEM_POOL_TYPE_COMP_APP_OUTPUT
is XAF_MEM_ID_DEV; others are of of type XAF_MEM_ID_COMP.
Notes: In the enum list of XAF_MEM_ID: XAF_MEM_ID_DEV,
XAF_MEM_ID_DEV_MAX, XAF_MEM_ID_COMP, XAF_MEM_ID_COMP_MAX and
XAF_MEM_ID_MAX are necessary. Additional pools can be inserted
between the above values (ex: XAF_MEM_ID_DEV_FAST between
XAF_MEM_ID_DEV and XAF_MEM_ID_DEV_MAX with XAF_MEM_ID_DEV_MAX being
the largest of ID_DEV type, similarly for ID_COMP)
Probe buffer pool type is same as that of output buffer to
application (XAF_MEM_POOL_TYPE_COMP_APP_OUTPUT).
+ Testbench:
Modified xaf-playback-usecase-test.c to show example usage of
XAF_MEM_ID_DEV_FAST memory pool set using mem_pool_type variable in
xaf_comp_config_t structure.
Removed the example of setting it with xaf_comp_set_config().
+ API:
1. Following are added in xaf-api.h:
-enum XAF_COMP_MEM_TYPE for component buffers and application
input/output buffers
-enum XAF_MEM_ID: XAF_MEM_ID_DEV_FAST, XAF_MEM_ID_DEV_MAX
2. Following are removed from xaf-api.h:
-xaf_adev_config_t: pshmem_frmwk
This pointer is same as paudio_framework_buffer after removal of
mem_malloc/mem_free references from library.
-xaf_comp_config_param: XAF_COMP_CONFIG_PARAM_MEM_POOL_TYPE
not required since mem_pool_type is passed via xaf_comp_config_t
-enum XAF_MEM_POOL_MASK_COMP
not required since mem_pool_type is passed via xaf_comp_config_t
3. Following are changed in xaf-api.h:
+ xaf_adev_config_t:
audio_framework_buffer_size as an array of length XAF_MEM_ID_MAX.
paudio_framework_buffer as an array of length XAF_MEM_ID_MAX.
+ xf_shared:
Increased the size of global shared memory buffer, passed as
paudio_framework_buffer pointers to the library from application.
+ NOTES:
1. The release package can build and execute the single-core
XAF-hostless tests OOB.
2. Multicore XAF tests require a multicore-subsystem to compile and
run, so they would not compile and run OOB. Refer Programmer's Guide
for steps to:
- Build multicore-subsystem,
- Build and run multicore XAF tests with built subsystem.
3. Tested for a subsystem with a maximum of 8 Cores.
+ KNOWN LIMITATIONS:
1. XTSC supports simulation of up to a maximum of 16 cores.
2. With FreeRTOS, the renderer component, if created on a
worker-DSP, may not execute leading to pipeline hang, due to
timer-interrupts not generated by FreeRTOS library.
----------------------------------------------------------------------
Version 3.3_Alpha API 3.1 : August 31, 2022
+ Alpha release
+ Built and tested with RI.6 tools
+ Programmers Guide not updated
+ [J3278] Added support for component memory allocation from
different memory-pools. A component's input, output, persistent and
scratch memory can be set to be allocated from required memory-pool
(with xaf_comp_set_config, parameter id
XAF_COMP_CONFIG_PARAM_MEM_POOL_TYPE and values from XAF_MEM_ID
shifted with appropriately according to XAF_MEM_POOL_MASK_COMP).
+ Modified xaf-playback-usecase-test.c to show example usage of
XAF_MEM_ID_COMP_FAST memory pool set with xaf_comp_set_config().
+ Following enums are added to xaf-api.h:
XAF_MEM_POOL_MASK_COMP
+ Following enums are updated in xaf-api.h:
1. XAF_MEM_ID
added additional memory type: XAF_MEM_ID_COMP_FAST
added max mem-pool markers XAF_MEM_ID_DEV_MAX, XAF_MEM_ID_COMP_MAX
2. xaf_comp_config_param
added XAF_COMP_CONFIG_PARAM_MEM_POOL_TYPE
+ Following structures are updated in xaf-api.h:
1. xaf_adev_config_t: Converted the following parameters to array
audio_component_buffer_size: component memory size
2. xaf_adev_config_t: Added the following parameters
paudio_component_buffer[XAF_MEM_ID_MAX]; (component mem pointer)
framework_local_buffer_size; (App i/f layer internal-use mem size)
pframework_local_buffer; (App i/f layer internal-use mem pointer)
proxy_thread_stack_size;
dsp_thread_stack_size;
worker_thread_stack_size[XAF_MAX_WORKER_THREADS];
3. xaf_adev_config_t: Removed the following parameters
xaf_mem_malloc_fxn_t *pmem_malloc;
xaf_mem_free_fxn_t *pmem_free;
4. xaf_perf_stats_s: Converted the following parameters to array
dsp_comp_buf_size_peak[XAF_MEM_ID_MAX]: peak component mem usage
+ Following definition is added in xaf-api.h:
XF_CFG_MAX_COMPS: Maximum number of components in the subsystem
(default 16).
NOTE: Part of "Local Memory used by Framework" or meminfo[2] can
vary depending on this parameter by ~1408 bytes (XOS) or ~896 bytes
(FreeRTOS). For 1 component, the minimum size of
frmwk_local_buffer_size is 24576 bytes (XOS), 4096 bytes(FreeRTOS).
+ Following types are removed from xaf-api.h
xaf_mem_malloc_fxn_t;
xaf_mem_free_fxn_t;
+ Removed mem_malloc, mem_free function calls from library.
Test application to provide appropriate size and pointer of each
memory type available in XAF_MEM_ID enum of xaf-api.h
+ Following file is moved:
algo/hifi-dpf/src/xf-msgq1.c -> algo/host-apf/src/xf-msgq1.c
+ Fixed "Local Memory used by Framework" or meminfo[2] where two
internal structures were added twice.
+ Added the following from v2.10p1 release
1. Added support for configurable stack size for DSP worker-threads.
NOTE: DSP worker-thread stack size should be more than the minimum
size required by the OS + maximum size required among all the
components on the thread (Default stack size for thread is 8KB).
2. Fixed buffer leakage issue of mimo-component with 0-output ports.
3. Fixed important Coverity warnings.
4. [J3497] Initialized error field of flush message to 0. Similarly,
added message error field reset for event between components and
component connect buffers.
5. Added changes to allow connect without initialization of source
component, hence support for decoder to be connected to the next
component without feeding input to the decoder.
6. Fixed renderer callback issue. In renderer-class, output ready
state is cleared only if the component has produced output.
7. Plugin fixes:
Added changes to support restarting PCM-Split(mimo-12) component.
8. FreeRTOS
version upgrade from v10.2.1-xaf to 10.4.4-stable
commit-ID: 1d9ea9fe58eadcdee62f1f068857052740eb8a34
(https://github.com/foss-xtensa/amazon-freertos)
+ NOTES:
1. The release package can build and execute the single-core
XAF-hostless tests OOB.
2. Multicore XAF tests require a multicore-subsystem to compile and
run, so they would not compile and run OOB. Refer Programmer's Guide
for steps to:
- Build multicore-subsystem,
- Build and run multicore XAF tests with built subsystem.
3. Tested for a subsystem with a maximum of 8 Cores.
+ KNOWN LIMITATIONS:
1. XTSC supports simulation of up to a maximum of 16 cores.
2. With FreeRTOS, the renderer component, if created on a
worker-DSP, may not execute leading to pipeline hang, due to
timer-interrupts not generated by FreeRTOS library.
----------------------------------------------------------------------
Version 3.2 API 3.0 : May 16, 2022
+ GA Release
+ Built with RI.6 tools
+ Compiled with xt-clang compiler
+ [J3184, J3284, J3273] Added time-out for IPC reset sync to avoid
subsystem hang on synchronization failure if adev_open/dsp_open
fail on any core.
+ [J3196] Robustness fix to save temporary output buffer size (
XAF_DECODER components), to be used during buffer free.
+ [J3202] Return fatal-error if XAF_COMP_CONFIG_PARAM_PRIORITY
set-config is attempted without creating worker threads (API
xaf_adev_set_priorities is not called).
+ [J3247] Added range checks for number of cores configured in the
subsystem. In xaf-pcm-gain-test.c, fix to pass XF_CORE_ID as 0
for NCORES=1.
+ [J3279] Pointer alignment fix for objects of structure xf_dsp_t,
xf_shmem_data_t (runtime errors of -fsanitize=undefined build).
+ [J3294] Return error if probe is enabled on an input port
configured to work in input-bypass mode.
+ Plugin changes:
[J3235] Renderer: Allow plugin to consume partial input if input
is over.
[J3241] PCM-split: Reset input-over state for input ports if the
component is re-started.
- Opus-decoder: Update the sample rate and num channels values
from the decoded stream info for correctness of get-config values.
+ xf_shared changes
[J3226, J3258, J3261] Increased size of shared-memory XF_SHMEM_SIZE
to support testing for more cores.
+ Testbench changes:
[J3332, J3227, J3228, J3256, J3203] Corrected MCPS calculation in
all testbenches, removed 'Gross Total MCPS' print. Total MCPS value
includes DSP MCPS and XAF MCPS of all the DSPs.
[J3203, J3236] Full Duplex Opus: added command option for raw-
stream input to decoder; Fix to check init status after declaring
input-over; Support for NUM_COMPS_IN_GRAPH=1 (encoder or decoder).
[J3257] Capturer-pcm-gain testbench: default value of sample-end
if "-samples:" is not provided as command line argument is set to 0.
- Removed debug print or multiple stream param prints.
- Fix return values on error to -1 in all testbenches.
- Added notes in help text updates in few testbenches.
+ Miscellaneous changes:
[J3237] Made vecselect=1 in .xtsys, Staticvector=1 in .yml to
avoid subsystem build warnings
[J3251] updated readme_tflm.txt for clarity
[J3272] Updated makefiles to support NCORES=1 build from shell env.
[J3252] url prefix changed to https:// in getFreeRTOS.sh, getTFLM.sh
+ NOTES:
1. The release package can build and execute the single-core
XAF-hostless tests OOB.
2. Multicore XAF tests require a multicore-subsystem to compile and
run, so they would not compile and run OOB. Refer Programmer's Guide
for steps to:
- Build multicore-subsystem,
- Build and run multicore XAF tests with built subsystem.
3. Tested for a subsystem with a maximum of 8 Cores.
+ KNOWN LIMITATIONS:
1. XTSC supports simulation of upto a maximum of 16 cores.
2. With FreeRTOS, the renderer component, if created on a
worker-DSP, may not execute leading to pipeline hang, due to
timer-interrupts not generated by FreeRTOS library.
----------------------------------------------------------------------
Version 3.1_Beta API 3.0 : February 28, 2022
+ Beta release
+ Built and tested with RI.6 tools and xt-clang compiler
+ Programmers Guide in draft format
[J3117] Fixed a buffer leakage issue on MIMO components with 0-output
ports.
+ Changes to have a common code-base which supports both XAF-hostless
and Multicore XAF solutions.
+ Extended multicore support upto 256 cores(8 bits of message-ID)
+ Following structures are updated:
1. xaf_adev_config_t: Added following parameters
cb_compute_cycles: call-back function to collect execution cycles
of worker DSPs.
cb_stats: shared object pointer passed to the call-back function
above.
+ Following shared structure is added in xaf-api.h:
xaf_perf_stats_s: consists of shared memory and execution cycle
variables for each worker DSP.
+ Following defines are renamed in xaf-api.h
INT_NUMBER to XA_EXTERNAL_INTERRUPT_NUMBER
+ Robustness Fixes:
Core:
1. Corrected core to core die message reply to be enqueued to
appropriate message pool. Also decrement "dst" variable only if
the opcode is XF_STOP.
2. Added DSP-worker thread cycle measurement hooks to collect the
stats before the threads are deleted.
3. Take out IPC_FLUSH of payload from xf_ipc_send2() and place it
outside the IPC layer, just before calling xf_ipc_send2().
4. Added invalidation after flush in msg_submit where the start-
buffer is dispatched to other cores from master-core.
Rbtree:
1. Added proper cache invalidations, removed redundant ones.
IPC:
1. Interrupt is disabled on xf_ipc_close().
2. Added support for level triggered interrupt.
3. Added support for global mutex locks using L32EX/S32EX
instructions when XCHAL_HAVE_EXCLUSIVE is set which is mutually
exclusive to the other type of instruction S32C1I.
4. Changed the lock in the global shared ipc-structure from object
to pointer type and it is initialized with the lock object during
xf_ipc_open().
5. Converted the XF_EXTERNAL_INTERRUPT_NUMBER for further use in the
library to XA_PROC_INTERRUPT_NUMBER.
Base-class:
1. While dynamically changing the priority of a component, sending
all messages meant for that component from its current priority
queue to newer priority queue.
2. Instead of accessing event buffer content to check for error
code, now error code is made available as part of the message's
error field for error event channels.
Audio-codec class:
1. Moved response of start buffer below deletion of temporary output
buffer required for initialization.
Proxy-MSGQ:
1. Added fix for 2nd synchronous command issued(set-config) before
the 1st one (unroute) completes as unroute may wait until next
component responds on the output buffer.
API:
1. Added core=XF_CORE_ID_MASTER in xaf_comp_config_default_init
2. Updated "xf_close()" and "xf_pool_free()" to return error and
updated return values of the caller of these functions.
3. Setting comp_state to XAF_COMP_RESET, after comp_delete attempt
in xaf_adev_close with XAF_ADEV_FORCE_CLOSE flag.
4. Added changes in xaf_adev_config structure for passing separate
shared memory pointers for framework buffers and dsp shared
buffers.
5. Changed XF_CFG_CODEC_SCRATCHMEM_SIZE to
worker_thread_scratch_size[0] for validating audio_comp_buf_size.
Plugins:
1. src-pp: Added the required RUNTIME_INIT for run-time scratch-
pointer change to take effect in the src-pp library.
2. renderer: Added check if component state is RUNNING, before
calling xf_timer_stop() during component delete(cleanup).
+ NOTES:
1. The release packages can build and execute the single-core
XAF-hostless tests OOB.
2. Multicore XAF tests require a multicore-subsystem to compile and
run, so they would not compile and run OOB. Refer document
doc/How-To-Guide-for-Multicore-XAF-Package.pdf for steps to:
build multicore-subsystem,
build and run multicore XAF tests with built subsystem.
+ KNOWN LIMITATIONS:
1. XTSC supports simulation of upto a maximum of 16 cores.
----------------------------------------------------------------------
Version 2.10 API 2.1 : November 24, 2021
+ GA Release
+ Built with RI.6 tools
+ Compiled with xt-clang compiler
+ [J3058] In AEC23 plugin, added changes to return non-fatal error if
both input ports have 0 length input data. Also non-fatal error is
returned during execution if the output buffer is NULL.
+ [J3066] Added checks to prevent the input buffer fill level from
going negative in xf_input_port_consume function if input-port
bypass is enabled and a corresponding CRITICAL trace print.
This could happen if the component plugin incorrectly reports
consumed bytes to be greater than the input bytes.
+ [J3070] Corrected components' default priority calculation logic to
ensure that the default priority remains the highest priority among
the DSP worker threads.
+ [J3077] Modified TIMEBASE_FREQ value to support 1 to 16 channels;
1,2,3 or 4 bytes per PCM-sample and commonly used sample rates
between 4000 to 192000 Hz. Also made changes in prepare_runtime
function of all the classes to support 8 bits per PCM-sample.
+ Compiler warning fixes:
Fixed two "comparison of integers of different signs" warnings
observed with -Wextra build option in xf-proxy.c.
+ Testbench changes:
Corrected the argument type of comp_cycles passed to
compute_comp_mcps function from 'int' to 'long long'.
----------------------------------------------------------------------
Version 2.9_Beta API 2.1 : September 24, 2021
+ Built with RI.6 tools
+ Compiled with xt-clang compiler
+ Programmers Guide not updated
+ [J2564] Reverted workaround code change to address XOS thread
abort issue, since the the fix is available in newer tools version
(RI.6 and above).
+ [J2928] Extended set/get config APIs are also enabled for MIMO, Mixer
and Renderer classes.
+ [J2970] Added changes for graceful handling of fatal errors from
message processing function xf_core_process_message().
+ [J2982] Corrected a condition check in "xf_worker_queue_purge"
function.
+ [J3023] Fix to avoid scheduling of components after a fatal error
has occured.
+ [J3025] Fixed validation of frame_size to be multiple of
codec->sample_size by using the input-buffer length (PCM) instead
of the output buffer length for encoder components.
+ [J3028] Added checks to avoid NULL pointer access after component
deletion in the local message submit logic(same thread components).
+ Optimization changes:
Optimized memory usage by removing base_cancel_pool related code
when preemption is active and decentralized scheduling is used.
+ Robustness fixes:
1. Replaced XF_CHK_ERR with condition check and to print appropriate
trace message with WARNING tag instead of ERROR tag in the function
xa_base_event_handler().
2. Corrected return value if the component's scheduled processing
occurs when it is in terminate state (all classes).
3. Corrected a trace print in xf_mm_alloc().
4. Fixed component state check in xaf_comp_get_status() API to
return the correct status to the application if the component delete
was already initiated.
+ Plugin changes:
1. Renamed opus encoder plugin directory from "opus" to "opus_enc".
2. Corrected mimo plugins' input and output buffer NULL check
error values.
+ Testbench changes:
1. The following new testbench is added:
- xaf-full-duplex-opus-test.c (Opus Full Duplex Pipeline).
2. The following testbeches are no longer packed:
- xaf-full-duplex-test.c
- xaf-aac-dec-test.c
- xaf-src-test.c
- xaf-vorbis-dec-test.c
- xaf-opus-enc-test.c
- xaf-opus-dec-test.c
3. Added 2 more MCPS prints after testbench execution
XAF MCPS and Total MCPS (DSP Component MCPS + Framework MCPS).
4. Fixed memory corruption in xa_app_receive_events_cb() due to
write event array index exceeding maximum value.
+ Packaging changes:
Added support for the following multiple testbench project in xws
package which can be built and run out-of-the-box(15 test projects)
- testxa_af_hostless
- testxa_af_mimo_mix
- testxa_af_gain_renderer
- testxa_af_capturer_gain
- testxa_af_renderer_ref_port
- testxa_af_dec*
- testxa_af_dec_mix*
- testxa_af_amr_wb_dec*
- testxa_af_mp3_dec_rend*
- testxa_af_capturer_mp3_enc*
- testxa_af_playback_usecase*
- testxa_af_full_duplex_opus*
- testxa_af_tflm_microspeech*
- testxa_af_tflm_pd*
- testxa_af_tflm_microspeech_pd*
The test projects with(*) require dependent libraries, header files
and Additional Liker path to be provided.
+ Notes:
1. xaf_comp_set_config_ext and xaf_comp_get_config_ext API usage is
now demonstrated in the functions opus_dec_setup() and
get_opus_dec_config() of the newly added Opus Full Duplex testbench
(xaf-full-duplex-opus-test.c).
2. testxa_af_hostless project has common test_inp and test_out
directory hosting input and output files of all the test projects in
the package. Hence user must import this project into the workspace.
3. For testxa_af_full_duplex_opus, xa_opus_codec.a of only one of
the opus_enc or opus_dec plugin needs to be provided for linking.
----------------------------------------------------------------------
Version 2.8_Alpha API 2.1 : August 11, 2021
+ Built with RI.6 tools
+ Programmers Guide not updated
+ [J2893] xaf_format_t type used by the application is moved from
xaf-api.h to xaf-utils-test.h.
+ [J2908] Fixed critical Coverity scan errors in xaf library, PCM-Gain
plugin and FreeRTOS.
+ [J2914] Enabled support for decoder initialization without input.
+ [J2928] Added support for extended get-config and set-config to
support more than 4 bytes of data per config parameter.
+ [J2942] Added support for input port bypass to avoid data copy at
input ports from connect buffers to input buffer of components.
+ [J2943] Added per-worker-thread de-centralized scheduler and
message queue for MCPS reduction.
+ [J2952] Corrected component ID of SRC component from
"audio-fx/src-pp" to "post-proc/src-pp".
+ [J2957] Corrected output buffer length adjustment in mimo-class and
mixer class fill-this-buffer functions.
+ [J2973] Reverted flexi-lock optimizations around sync-msg-queues
to ensure sync-msg-queues always have locked access.
+ [J2977] Enabled propagation of non-fatal error codes for synchronous
APIs through response message.
+ [J2979] Enabled CRITICAL trace prints with minimal increase in code
size (~2%).
+ [J2982] Fixed a memory corruption issue by responding to pending
worker queue messages during component deletion.
+ [J2985] Fixed potential buffer corruption due to concurrent
auxiliary buffer access.
+ [J2999] Added changes to avoid relax-schedule check for output port
readiness of MIMO components during initialization.
+ Added following new APIs:
1. xaf_comp_set_config_ext(pVOID comp_ptr, WORD32 num_param,
WORD32 *p_param);
Note: This API is not a replacement for existing API used for
component setup(xaf_comp_set_config) and it should not be used
until component setup is done.
2. xaf_comp_get_config_ext(pVOID comp_ptr, WORD32 num_param,
WORD32 *p_param);
+ Plugin changes:
1. Consumed bytes variable to consider any partial bytes less than
sample_size. This change is done in PCM-Gain, Mimo-mix, PCM-Split
and Mixer component plugins.
2. Updated Mixer plugin to avoid memset on the input buffer if
filled partially.
+ Robustness fixes:
1. Added component state check after xf_response_get() in
xaf_comp_get_status() API call. This prevents any buffer access
after the component gets deleted.
2. Corrected a condition check for xf_client_lookup() in
dsp_worker_entry().
+ Notes:
1. Input-port-bypass is activated if the plugin reports its input
buffer size as zero when queried with XA_API_CMD_GET_MEM_INFO_SIZE.
A usage is demonstarted in the plugin PCM-Gain(xa-pcm-gain.c) under
the disabled compile time option XA_INPORT_BYPASS_TEST.
2. xaf_comp_set_config_ext and xaf_comp_get_config_ext API usage is
demonstrated in the functions get_opus_dec_config() and
opus_dec_setup() of Opus decoder testbench(xaf-opus-dec-test.c)
and support a maximum of 8 configuation parameters per API call.
3. Usage of decoder component intialization without input data is
shown in the AMR decoder testbench(xaf-amr-wb-dec-test.c).
----------------------------------------------------------------------
Version 3.0_Alpha API 3.0 : July 16, 2021
+ Alpha release
+ Built and tested with RI.2 tools
+ Sanity tested with RI.6 tools
+ Programmers Guide not updated
+ Added multicore support in XAF so that DSP workload can be shared
among DSPs (2, 3 or 4) by creating components on respective DSPs.
+ Following existing APIs are updated:
1. adev_set_priority: to pass the following additional argument
core: corei-ID on which worker threads are to be created.
2. xaf_get_mem_stats: to pass the following additional argument
core: core-ID whose memory usage is required
+ Following new APIs are added:
1. xaf_dsp_open(VOID **, xaf_adev_config_t *)
creates the dsp-thread on the worker-core, returns the
worker-core handle.
2. xaf_dsp_close(VOID *)
closes the dsp-thread on worker core, frees memory.
+ Following structures are updated:
1. xaf_adev_config_t: Added following parameters
core: Master-DSP core-ID
pshmem: pointer to the shared memory used for inter-core IPC
audio_shmem_buffer_size: size of the shared memory
2. xaf_comp_config_t: Added following parameter
core: core-ID on which the component needs to be created
+ Following new defines are added in xaf-api.h:
1. XF_CFG_CORES_NUM: Number of cores in the system (2,3 or 4)
2. XF_CORE_ID_MASTER: core-ID of the master-DSP.
3. INT_NUMBER: IPC interrupt number
(BInterrupt/ProcInterrupt in xtsc/*.yml file)
+ Following new files are added for inter-core shared memory:
xf_shared/src/xf-shared.c
xf_shared/include/xf-shared.h
+ Following new file is added for inter-core mutex and interrupts:
include/sysdeps/mc_ipc/xf-mc-ipc.h
+ Following new files are added for inter-core IPC definition:
(Note, these files are internal to XAF and listed here for info)
algo/hifi-dpf/include/sys/xos-msgq/xf-ipc-if.h
algo/hifi-dpf/src/xf-ipc-if.c
+ NOTES:
1. Multicore XAF tests require a multicore-subsystem to compile and
run, so they would not compile and run OOB.
2. See doc/How-To-Guide-for-Multicore-XAF-tgz-Package.pdf for steps
to build multicore-subsystem (2, 3 or 4 cores).
3. See doc/How-To-Guide-for-Multicore-XAF-tgz-Package.pdf for steps
to build and run multicore XAF tests with built subsystem.
+ KNOWN LIMITATIONS:
1. Inter-core mutex definition uses Xtensa S32C1I (conditional
store) instruction. The definition should be updated if this
instruction is not available or better definition is available.
2. Memory and MCPS numbers: The numbers may not be accurate as the
shared memory and worker-core stats are not updated.
3. FreeRTOS: Some test cases may hang when runtime commands, resume