.. _transitioning:
Transitioning from older tools releases
=======================================
Users of tools releases prior to 15.0.1 will notice some changes. This page
intends to provide a rationale for those changes and help users move rapidly to
the 15.0.x series of tools.
Background
----------
The 15.0.x tools releases represent a change in direction for the tools. The new
direction is towards:
* Use of established, industry-standard tools and techniques where appropriate
* Preference of upstreamed changes to 3rd-party open source projects over
maintenance of custom versions of the same
* Conformance with widely used interfaces, formats and conventions such that
users can:
* Transition easily from other platforms to the XCore and its tools
* Use their own preferred 3rd-party tools
The principal aim is to leverage the very latest advances in toolchain
technology, whilst focussing XMOS effort where it can have the greatest impact.
The 15.0.x tools releases mark the beginning of this journey.
Programming language
--------------------
The most fundamental change within the 15.0.x tools is the move towards the use
of C/C++ instead of XC as the preferred programming language for the XCore. The
advantages of using C for XCore programming are:
* Less restrictive than XC; specifically, C allows pointers by default
* No ambiguity in semantics
* Plenty of online support
* Familiar to most embedded software developers
* Better 3rd-party tool support
There are no fundamental features of the XCore architecture that
demand a proprietary programming language.
Writing CSP-style tasks with their own private memory, like those used in XC,
remains an excellent approach to parallel programming and the same mental model
is recommended when programming in C. The move towards the use of C/C++ retains
access to all of the unique benefits of the xcore architecture alongside the
latest C and C++ features and fixes.
Existing code written in XC
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Existing XC source code does not need to be ported to C.
The XC compiler, accessed via the XCC compiler driver, will remain part of the
tools release. No date has been set for its removal.
Where a decision is made to port a library to C, users may consider porting
only the public API for expediency, rather than the entire library.
The XC compiler itself will be maintained for existing applications and
libraries. Feature requests or performance optimisations will not be considered.
For guidance on projects developed within older tools releases, see
:ref:`migrating_existing_projects`.
New code
^^^^^^^^
All new procedural code should be written in C.
Since the underlying hardware features of the XCore cannot be accessed directly
through the C language itself, a new system library :ref:`lib_xcore_api` is
provided. Use of the new library is introduced in the guide:
:ref:`lib_xcore_prog_guide`.
Where new C code is required to interact with existing XC code, existing
guidance should be followed. See :ref:`call_between_c_xc`.
Writing multi-tile applications currently still requires the writing of a
minimal declarative XC source file, often called :file:`mapfile.xc` as per the
examples: :ref:`multi_tile` and :ref:`switch_setup`. The file should not contain
any procedural code, and should contain only the bare minimum to:
* Declare a C entry point on each tile
* Bootstrap any subsequent inter-tile communications via the switch
Subsequent releases of the tools will provide alternative means of supplying the
declarative information and a corresponding C source code generator. Keeping the
content of the :samp:`mapfile.xc` purely declarative will ensure that any
migration is straightforward.
The C language does not include equivalents for XC's :samp:`[[combine]]` or
:samp:`[[combinable]]` keywords. Combining tasks onto a single logical core can
now be done manually using collaborative scheduling or, using the power and
functionality exposed by C and lib_xcore, even using an RTOS.
Similarly, the C language does not have an equivalent for XC interfaces which
are accessed via the :samp:`interface` keyword. Implementation of interfaces and
their underlying transport and protocol can now be performed by the application
developer, allowing greater scope for chosing an implementation appropriate to
the real-time requirements and any resource availabilty constraints.
Users who rely on the XC language protecting them against unsafe concurrent
access to shared memory should take appropriate care when programming in the C
language. Similarly, care should be taken to ensure that resources are correctly
allocated and deallocated before/after use, since such allocation is not handled
by the language itself. These are all normal considerations for a C programmer.
Experienced XC users transitioning to C/lib_xcore may find the following
resources useful:
.. raw:: html
The following bookmarks provide a convenient access into the video for later
reference:
* `Ports <#wistia_p90ovd97sj?time=111>`_
* `Timers <#wistia_p90ovd97sj?time=327>`_
* `Locks <#wistia_p90ovd97sj?time=471>`_
* `Par <#wistia_p90ovd97sj?time=548>`_
* `Channels <#wistia_p90ovd97sj?time=779>`_
* `Select <#wistia_p90ovd97sj?time=919>`_
* `Other features <#wistia_p90ovd97sj?time=1195>`_
* `Considerations <#wistia_p90ovd97sj?time=1604>`_
* `Automatic stack size calculation <#wistia_p90ovd97sj?time=1765>`_
* `Multi-tile applications <#wistia_p90ovd97sj?time=1998>`_
The presentation used in the video may be downloaded:
:download:`C_for_xCore_2021_02_08.pdf`
In addition, an :ref:`cheat` is provided.
Graphical IDE
-------------
The 15.0.x tools do not contain a graphical IDE within the installation package.
Instead, the tools are intended to be integrated with the user's favourite IDE
as per the examples in :ref:`config_ide`. This choice allows users to leverage
the very latest IDE technology.
Viewing of offline XSCOPE output is similarly delegated to the user's preferred
VCD viewer. Use of GTKWave is demonstrated in :ref:`fast_printf`, though
other viewers are available.
.. _migrating_existing_projects:
Migrating existing projects
---------------------------
Some very minor changes in configuration files and procedures are required when
using tools 15.0.x to develop existing projects whose life began under earlier
tools releases. This page collects useful pointers on making the changes.
Flash-related changes
^^^^^^^^^^^^^^^^^^^^^
Target XN file changes
""""""""""""""""""""""
Previous toolkit releases warned of an impending change to the schema for target
XN files. That change has now been made. Therefore, if a build error similar to
this is raised:
.. code-block:: text
.././src/core/xk-audio-216-mc.xn:86 Error: XN11052 Invalid or missing PageSize for device "bootFlash". Information: Device elements with attribute Class="SQIFlash" now also require PageSize, SectorSize & NumPages attributes to be set. Values for these are likely to be found in the datasheet for the chosen flash.
...then the project's target '.xn' file needs to be adjusted. At a minimum, the
:samp:`PageSize`, :samp:`SectorSize` and :samp:`NumPages` attributes must be
set. It is also likely that additional :samp:`Attribute` elements will be
required. The XCORE-200-EXPLORER.xn file below highlights the changes:
.. code-block:: xml
:emphasize-lines: 2,6-7
The :samp:`QE_REGISTER` and :samp:`QE_BIT` elements provide information about
where the Quad-enable bit can be found to shift a flash device from SPI to QSPI
mode. Information on this can be found in the datasheet for the required device,
though convention means that the required values will often be as above
(reg_1:bit_1) or reg_0:bit_6.
XFLASH option changes
"""""""""""""""""""""
The version of XFLASH supplied with tools 15.0.x no longer performs image
compression thus its default and only behaviour is to not compress the image.
The option :samp:`xflash --no-compression` is therefore no longer provided.
Simply do not supply the option.
XFLASH upgrade image guidance
"""""""""""""""""""""""""""""
If using tools 15.0.x release to produce a flash upgrade image for a factory
image created under earlier tools releases, be sure to supply the correct value
for the :option:`xflash --factory-version`.
XTAG-related changes
^^^^^^^^^^^^^^^^^^^^
The XTAG drivers have changed, and therefore an XTAG reboot will be necessary.