1.. _xtensa_developer_guide:
2
3Xtensa Developer Guide
4######################
5
6Overview
7********
8
9This page contains information on certain aspects when developing for
10Xtensa-based platforms.
11
12HiFi Audio Engine DSP
13*********************
14
15The kernel allows threads to use the HiFi Audio Engine DSP registers on boards
16that support these registers. The kernel only supports the use of the HiFi
17registers by threads and not ISRs.
18
19.. note::
20    Presently, only the Intel ADSP ACE hardware platforms are configured for
21    HiFi support by default.
22
23Concepts
24========
25
26The kernel can be configured for an application to leverage the services
27provided by the Xtensa HiFi Audio Engine DSP. Three modes of operation are
28supported, which are described below.
29
30No HiFi registers mode
31----------------------
32
33This mode is used when the application has no threads that use the HiFi
34registers. It is the kernel's default HiFi services mode.
35
36Unshared HiFi registers mode
37----------------------------
38
39This mode is used when the application has only a single thread that uses the
40HiFi registers. The HiFi registers are left unchanged whenever a context
41switch occurs.
42
43.. note::
44    The behavior is undefined, if two or more threads attempt to use
45    the HiFi registers, as the kernel does not attempt to detect
46    (nor prevent) multiple threads from using these registers.
47
48Shared HiFi registers mode
49--------------------------
50
51This mode is used when the application has two or more threads that use HiFi
52registers. When enabled, the kernel automatically allows all threads to use the
53HiFi registers. During each thread context switch, the kernel saves the outgoing
54thread's HiFi registers and loads the incoming thread's HiFi registers,
55regardless of whether the thread utilizes them or not.
56
57Additional stack space may be required for each thread to account for the extra
58registers that must be saved.
59
60Configuration Options
61=====================
62
63The unshared HiFi registers mode is selected when configuration option
64:kconfig:option:`CONFIG_XTENSA_HIFI_SHARING` is disabled but configuration
65options :kconfig:option:`CONFIG_XTENSA_HIFI3` and/or
66:kconfig:option:`CONFIG_XTENSA_HIFI4` are enabled.
67
68The shared HiFi registers mode is selected when the configuration option
69:kconfig:option:`CONFIG_XTENSA_HIFI_SHARING` is enabled in addition to
70configuration options :kconfig:option:`CONFIG_XTENSA_HIFI3` and/or
71:kconfig:option:`CONFIG_XTENSA_HIFI4`. Threads must have sufficient
72stack space for saving the HiFi register values during context switches
73as described above.
74