xmos · xmos-jmccarthy · Sep 15, 2022 · Sep 6, 2022 · Sep 6, 2022 · Sep 9, 2022
diff --git a/examples/examples.cmake b/examples/examples.cmake
@@ -2,7 +2,7 @@
 if(${CMAKE_SYSTEM_NAME} STREQUAL XCORE_XS3A)
     ## Bare metal examples
     include(${CMAKE_CURRENT_LIST_DIR}/bare-metal/explorer_board/explorer_board.cmake)
-    #
+
     ## FreeRTOS examples
     include(${CMAKE_CURRENT_LIST_DIR}/freertos/device_control/device_control.cmake)
     include(${CMAKE_CURRENT_LIST_DIR}/freertos/dispatcher/dispatcher.cmake)
@@ -11,6 +11,7 @@ if(${CMAKE_SYSTEM_NAME} STREQUAL XCORE_XS3A)
     include(${CMAKE_CURRENT_LIST_DIR}/freertos/iot/iot.cmake)
     include(${CMAKE_CURRENT_LIST_DIR}/freertos/l2_cache/l2_cache.cmake)
     include(${CMAKE_CURRENT_LIST_DIR}/freertos/usb/usb.cmake)
+    include(${CMAKE_CURRENT_LIST_DIR}/freertos/xlink/xlink.cmake)
 else()
     add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/freertos/device_control/host)
 endif()
diff --git a/examples/freertos/xlink/README.rst b/examples/freertos/xlink/README.rst
@@ -0,0 +1,148 @@
+##############
+XLINK
+##############
+
+This example application demonstrates the `AN01024 <https://www.xmos.ai/file/an01024-xconnect-dynamic-configuration-demo-sw/>`_ application note in FreeRTOS on XCORE AI.
+
+**********************
+Preparing the hardware
+**********************
+
+This example requires 2 XCORE-AI-EXPLORER boards, and a user provided device to act as an I2C slave.
+
+To setup the board for testing, the following connections must be made:
+
+.. list-table:: XCORE-AI-EXPLORER to XCORE-AI-EXPLORER Connections 2 Wire
+   :widths: 50 50
+   :header-rows: 1
+   :align: left
+
+   * - BOARD 0
+     - BOARD 1
+   * - GND
+     - GND
+   * - X1D65
+     - X1D66
+   * - X1D66
+     - X1D65
+   * - X1D64
+     - X1D67
+   * - X1D67
+     - X1D64
+   * - X1D63
+     - X1D68
+   * - X1D68
+     - X1D63
+   * - X1D62
+     - X1D69
+   * - X1D69
+     - X1D62
+   * - X1D61
+     - X1D70
+   * - X1D70
+     - X1D61
+
+.. list-table:: XCORE-AI-EXPLORER to XCORE-AI-EXPLORER Connections 5 Wire Additions
+   :widths: 50 50
+   :header-rows: 1
+   :align: left
+
+   * - BOARD 0
+     - BOARD 1
+   * - X1D63
+     - X1D68
+   * - X1D68
+     - X1D63
+   * - X1D62
+     - X1D69
+   * - X1D69
+     - X1D62
+   * - X1D61
+     - X1D70
+   * - X1D70
+     - X1D61
+
+.. list-table:: XCORE-AI-EXPLORER Board 0 to Host Connections
+   :widths: 50 50
+   :header-rows: 1
+   :align: left
+
+   * - BOARD 0
+     - Host
+   * - GND
+     - Host GND
+   * - SCL
+     - Host SCL
+   * - SDA
+     - Host SDA
+
+*********************
+Building the firmware
+*********************
+
+Run the following commands in the xcore_sdk root folder to build the firmware:
+
+.. tab:: Linux and Mac
+
+    .. code-block:: console
+
+        cmake -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
+        cd build
+        make example_freertos_xlink_both
+
+.. tab:: Windows
+
+    .. code-block:: console
+
+        cmake -G "NMake Makefiles" -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
+        cd build
+        nmake example_freertos_xlink_both
+
+********************
+Running the firmware
+********************
+
+This application requires example_freertos_xlink_0.xe to be run on BOARD 0, IE, the board with a host I2C connection.
+
+Use the following command to determine available device:
+
+.. code-block:: console
+
+    xrun --list-devices
+
+From the xcore_sdk build folder run:
+
+.. code-block:: console
+
+    xrun --id 0 example_freertos_xlink_0.xe
+
+In another console, from the xcore_sdk build folder run:
+
+.. code-block:: console
+
+    xrun --id 1 example_freertos_xlink_1.xe
+
+BOARD 0 will send out status messages and communication details to slave address 0xC.
+
+The data will contain an ID, followed by a 4 byte payload.  The payload is an int32, sent least significant byte first.
+
+Payloads match to ID per the table below:
+
+.. list-table:: XCORE-AI-EXPLORER to XCORE-AI-EXPLORER Connections 2 Wire
+   :widths: 50 50
+   :header-rows: 1
+   :align: left
+
+   * - ID
+     - Payload
+   * - 0x01
+     - RX state
+   * - 0x82
+     - received data bytes in the last second
+   * - 0x83
+     - received control tokens in the last second
+   * - 0x84
+     - timeouts in the last second
+
+.. note::
+    Data rates are highly dependant on the electrical characteristics of the physical connection.  Refer to `xCONNECT Architecture <https://www.xmos.ai/file/xconnect-architecture/>`_ for more information.
diff --git a/examples/freertos/xlink/XCORE-AI-EXPLORER.xn b/examples/freertos/xlink/XCORE-AI-EXPLORER.xn
@@ -0,0 +1,131 @@
+<?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" RoutingId="0x0020">
+          <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>
+          <RoutingTable>
+            <Bits>
+              <Bit number="0" direction="1"/>
+              <Bit number="1" direction="1"/>
+              <Bit number="2" direction="1"/>
+              <Bit number="3" direction="1"/>
+              <Bit number="4" direction="1"/>
+              <Bit number="5" direction="1"/>
+              <Bit number="6" direction="1"/>
+              <Bit number="7" direction="1"/>
+              <Bit number="8" direction="1"/>
+              <Bit number="9" direction="1"/>
+              <Bit number="10" direction="1"/>
+              <Bit number="11" direction="1"/>
+              <Bit number="12" direction="1"/>
+              <Bit number="13" direction="1"/>
+              <Bit number="14" direction="1"/>
+              <Bit number="15" direction="0"/>
+            </Bits>
+            <Links>
+              <Link name="XL0" direction="0"/>
+            </Links>
+          </RoutingTable>          
+        </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>