-
Notifications
You must be signed in to change notification settings - Fork 41
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #523 from xmos/feature/xscope_fileio
xscope_fileio FreeRTOS example application
- Loading branch information
Showing
32 changed files
with
1,451 additions
and
35 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -16,3 +16,6 @@ | |
[submodule "frameworks/rtos"] | ||
path = modules/rtos | ||
url = [email protected]:xmos/fwk_rtos.git | ||
[submodule "modules/xscope_fileio/xscope_fileio"] | ||
path = modules/xscope_fileio/xscope_fileio | ||
url = [email protected]:xmos/xscope_fileio.git |
Binary file added
BIN
+139 KB
doc/tutorials/freertos/examples/images/xscope_fileio_functional_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
.. include:: ../../../../examples/freertos/xlink/README.rst |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
.. include:: ../../../../examples/freertos/xscope_fileio/README.rst |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,141 @@ | ||
############### | ||
XSCOPE File I/O | ||
############### | ||
|
||
This FreeRTOS example application reads a WAV file from the host over an XSCOPE server, propagates the data through multiple threads across both tiles, and then writes the output to a WAV file on the host PC, also over an XSCOPE server. | ||
|
||
.. image:: images/xscope_fileio_functional_diagram.png | ||
:align: left | ||
|
||
The 3-stage pipeline in the example covers both XCORE tiles. Stage #1 and Stage #2 run on tile[1], while Stage #3 runs on tile[0]. | ||
|
||
Stages #1 and #2 are implemented in the functions `stage_1` and `stage_2` which can be found in the file ``src\data_pipeline\src\data_pipeline_tile1.c``. In this example, both stages apply a fixed gain to the PCM audio samples. In `stage_1`, preemption is disabled with the `rtos_interrupt_mask_all()` function to insure the FreeRTOS kernel does not interrupt the task and perform a context switch during a performance critical code section. `stage_2` is a typical FreeRTOS task which can be preempted. However, this example is rather simple so, instead of leaving a context switch up to chance, the `stage_2` function periodically yields to the FreeRTOS kernel - emulating a context switch. | ||
|
||
Both the `stage_1` and `stage_2` functions have been instrumented with a stopwatch-like timer to measure the time spent applying the fixed gain. | ||
|
||
Stage #3 is implemented in the function `stage_3` which can be found in the file ``src\data_pipeline\src\data_pipeline_tile0.c``. In this example, Stage 3 does nothing. It is provided to demonstrate a multi-tile pipeline. | ||
|
||
The example application input file name is hard-coded to `in.wav` and the output file file name is hard-coded to `out.wav`. Running the application can be wrapped in a simple script if alternative file names are desired. Simply copy your file to `in.wav`, run the applications, then copy `out.wav` to you preferred output file name. | ||
|
||
The input file sample rate must be 16 KHz, 32 bits per sample. | ||
|
||
This example is already configured to link with the `XMOS vectorized math library <https://www.xmos.ai/documentation/XM-014660-LATEST/html/modules/core/modules/xs3_math/lib_xs3_math/doc/index.html>`_. Users wishing to take advantage of the vector processing unit (VPU) on the XMOS XS3 architecture can use this example application as a starting point. | ||
|
||
****************** | ||
Supported Hardware | ||
****************** | ||
|
||
This example is supported on the XCORE-AI-EXPLORER board. | ||
|
||
********************* | ||
Building the Firmware | ||
********************* | ||
|
||
Run the following commands in the root folder to build the embedded application using the XTC Toolchain: | ||
|
||
Linux or Mac | ||
------------ | ||
|
||
.. code-block:: console | ||
cmake -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake | ||
cd build | ||
make example_freertos_xscope_fileio | ||
Windows | ||
------- | ||
|
||
Before building the embedded application, you may need to add the path to nmake to your PATH variable. | ||
|
||
.. code-block:: console | ||
set PATH=%PATH%;<path-to-nmake> | ||
To build the embedded application: | ||
|
||
.. code-block:: console | ||
cmake -G "NMake Makefiles" -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake | ||
cd build | ||
nmake example_freertos_xscope_fileio | ||
********************* | ||
Building the Host App | ||
********************* | ||
|
||
Run the following commands in the root folder to build the host application using your native x86 Toolchain: | ||
|
||
.. note:: | ||
|
||
Permissions may be required to install the host applications. | ||
|
||
Linux or Mac | ||
------------ | ||
|
||
.. code-block:: console | ||
cmake -B build_host | ||
cd build_host | ||
make xscope_host_endpoint | ||
make install | ||
The host application, `xscope_host_endpoint`, will be installed at `/opt/xmos/SDK/<sdk version>/bin/`, and may be moved if desired. You may wish to add this directory to your `PATH` variable. | ||
|
||
Windows | ||
------- | ||
|
||
Before building the host application, you will need to add the path to the XTC Tools to your environment. | ||
|
||
.. code-block:: console | ||
set "XMOS_TOOL_PATH=<path-to-xtc-tools>" | ||
Then build the host application: | ||
|
||
.. code-block:: console | ||
cmake -G "NMake Makefiles" -B build_host | ||
cd build_host | ||
nmake xscope_host_endpoint | ||
nmake install | ||
The host application, `xscope_host_endpoint.exe`, will be install at `<USERPROFILE>\.xmos\SDK\<sdk version>\bin\`, and may be moved if desired. You may wish to add this directory to your `PATH` variable. | ||
|
||
******************** | ||
Running the Firmware | ||
******************** | ||
|
||
From the build folder run: | ||
|
||
Linux or Mac | ||
------------ | ||
|
||
.. code-block:: console | ||
make run_example_freertos_xscope_fileio | ||
In a second console, run the host xscope server: | ||
|
||
.. code-block:: console | ||
./xscope_host_endpoint 12345 | ||
Windows | ||
------- | ||
|
||
.. code-block:: console | ||
nmake run_example_freertos_xscope_fileio | ||
Before running the host application, you may need to add the location of the `xscope_endpoint.dll` to your PATH. | ||
|
||
.. code-block:: console | ||
set PATH=%PATH%;<path-to-xscope-endpoint-dll> | ||
In a second console, run the host xscope server: | ||
|
||
.. code-block:: console | ||
xscope_host_endpoint.exe 12345 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
<?xml version="1.0" encoding="UTF-8"?> | ||
<Network xmlns="http://www.xmos.com" | ||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
xsi:schemaLocation="http://www.xmos.com http://www.xmos.com"> | ||
<Type>Board</Type> | ||
<Name>xcore.ai Explorer Kit</Name> | ||
|
||
<Declarations> | ||
<Declaration>tileref tile[2]</Declaration> | ||
</Declarations> | ||
|
||
<Packages> | ||
<Package id="0" Type="XS3-UnA-1024-FB265"> | ||
<Nodes> | ||
<Node Id="0" InPackageId="0" Type="XS3-L16A-1024" Oscillator="24MHz" SystemFrequency="600MHz" ReferenceFrequency="100MHz"> | ||
<Boot> | ||
<Source Location="bootFlash"/> | ||
</Boot> | ||
<Extmem sizeMbit="1024" Frequency="100MHz"> | ||
<!-- Attributes for Padctrl and Lpddr XML elements are as per equivalently named 'Node Configuration' registers in datasheet --> | ||
|
||
<Padctrl clk="0x30" cke="0x30" cs_n="0x30" we_n="0x30" cas_n="0x30" ras_n="0x30" addr="0x30" ba="0x30" dq="0x31" dqs="0x31" dm="0x30"/> | ||
<!-- | ||
Attributes all have the same meaning, which is: | ||
[6] = Schmitt enable, [5] = Slew, [4:3] = drive strength, [2:1] = pull option, [0] = read enable | ||
Therefore: | ||
0x30: 8mA-drive, fast-slew output | ||
0x31: 8mA-drive, fast-slew bidir | ||
--> | ||
|
||
<Lpddr emr_opcode="0x20" protocol_engine_conf_0="0x2aa"/> | ||
<!-- | ||
Attributes have various meanings: | ||
emr_opcode[7:5] = LPDDR drive strength to xcore.ai | ||
protocol_engine_conf_0[23:21] = tWR clock count at the Extmem Frequency | ||
protocol_engine_conf_0[20:15] = tXSR clock count at the Extmem Frequency | ||
protocol_engine_conf_0[14:11] = tRAS clock count at the Extmem Frequency | ||
protocol_engine_conf_0[10:0] = tREFI clock count at the Extmem Frequency | ||
Therefore: | ||
0x20: Half drive strength | ||
0x2aa: tREFI 7.79us, tRAS 0us, tXSR 0us, tWR 0us | ||
--> | ||
</Extmem> | ||
<Tile Number="0" Reference="tile[0]"> | ||
<Port Location="XS1_PORT_1B" Name="PORT_SQI_CS"/> | ||
<Port Location="XS1_PORT_1C" Name="PORT_SQI_SCLK"/> | ||
<Port Location="XS1_PORT_4B" Name="PORT_SQI_SIO"/> | ||
|
||
<Port Location="XS1_PORT_1N" Name="PORT_I2C_SCL"/> | ||
<Port Location="XS1_PORT_1O" Name="PORT_I2C_SDA"/> | ||
|
||
<Port Location="XS1_PORT_4C" Name="PORT_LEDS"/> | ||
<Port Location="XS1_PORT_4D" Name="PORT_BUTTONS"/> | ||
|
||
<Port Location="XS1_PORT_1I" Name="WIFI_WIRQ"/> | ||
<Port Location="XS1_PORT_1J" Name="WIFI_MOSI"/> | ||
<Port Location="XS1_PORT_4E" Name="WIFI_WUP_RST_N"/> | ||
<Port Location="XS1_PORT_4F" Name="WIFI_CS_N"/> | ||
<Port Location="XS1_PORT_1L" Name="WIFI_CLK"/> | ||
<Port Location="XS1_PORT_1M" Name="WIFI_MISO"/> | ||
</Tile> | ||
<Tile Number="1" Reference="tile[1]"> | ||
<!-- Mic related ports --> | ||
<Port Location="XS1_PORT_1G" Name="PORT_PDM_CLK"/> | ||
<Port Location="XS1_PORT_1F" Name="PORT_PDM_DATA"/> | ||
|
||
<!-- Audio ports --> | ||
<Port Location="XS1_PORT_1D" Name="PORT_MCLK_IN"/> | ||
<Port Location="XS1_PORT_1C" Name="PORT_I2S_BCLK"/> | ||
<Port Location="XS1_PORT_1B" Name="PORT_I2S_LRCLK"/> | ||
<Port Location="XS1_PORT_1A" Name="PORT_I2S_DAC_DATA"/> | ||
<Port Location="XS1_PORT_1N" Name="PORT_I2S_ADC_DATA"/> | ||
<Port Location="XS1_PORT_4A" Name="PORT_CODEC_RST_N"/> | ||
</Tile> | ||
</Node> | ||
</Nodes> | ||
</Package> | ||
</Packages> | ||
<Nodes> | ||
<Node Id="2" Type="device:" RoutingId="0x8000"> | ||
<Service Id="0" Proto="xscope_host_data(chanend c);"> | ||
<Chanend Identifier="c" end="3"/> | ||
</Service> | ||
</Node> | ||
</Nodes> | ||
<Links> | ||
<Link Encoding="2wire" Delays="5clk" Flags="XSCOPE"> | ||
<LinkEndpoint NodeId="0" Link="XL0"/> | ||
<LinkEndpoint NodeId="2" Chanend="1"/> | ||
</Link> | ||
</Links> | ||
<ExternalDevices> | ||
<Device NodeId="0" Tile="0" Class="SQIFlash" Name="bootFlash" Type="S25FL116K" PageSize="256" SectorSize="4096" NumPages="16384"> | ||
<Attribute Name="PORT_SQI_CS" Value="PORT_SQI_CS"/> | ||
<Attribute Name="PORT_SQI_SCLK" Value="PORT_SQI_SCLK"/> | ||
<Attribute Name="PORT_SQI_SIO" Value="PORT_SQI_SIO"/> | ||
<Attribute Name="QE_REGISTER" Value="flash_qe_location_status_reg_0"/> | ||
<Attribute Name="QE_BIT" Value="flash_qe_bit_6"/> | ||
</Device> | ||
</ExternalDevices> | ||
<JTAGChain> | ||
<JTAGDevice NodeId="0"/> | ||
</JTAGChain> | ||
|
||
</Network> | ||
|
1 change: 1 addition & 0 deletions
1
examples/freertos/xscope_fileio/diagrams/functional_diagram.drawio
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
<mxfile host="app.diagrams.net" modified="2022-09-29T14:56:36.937Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" etag="k4k2H8g0jgsSFCdsdITm" version="20.3.7" type="device"><diagram id="HG_wOtk8IJbsn9-jQrfK" name="Page-1">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</diagram></mxfile> |
Binary file added
BIN
+139 KB
examples/freertos/xscope_fileio/images/xscope_fileio_functional_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Oops, something went wrong.