Release Notes for XTC Tools: 15.1.4 (build: 454-77dc314) ================================================================ Previous major release: 15.1.0 (build: 446-e647144) SUPPORTED HOST SYSTEMS ---------------------- This release of the XTC Tools can be installed on: * Windows 10 Pro (all releases) * Apple Mac: Intel and M1 architectures running macOS 10.15 (Catalina) and newer * Linux: CentOS 7.6, Ubuntu 18.04, Ubuntu 20.04 OVERVIEW OF CHANGES SINCE LAST MAJOR RELEASE -------------------------------------------- * Host support - Support the Apple Mac M1 host machine tpe. The Rosetta tool must be installed on the machine to run this release of the XTC Tools - This release of the tools is correctlty signed for both the Appple Mac M1 host architecture and Appple Mac Intel host architecture * Target board and device package support - Added support for QF60B xcore.ai package - Added support XK-EVK-XU316 xcore.ai Explorer board * xflash command line tool - Fix an issue where xflash crashes when looking up flash device ports that don't exist in the XN - Fix the a bug where OTP is not locked for read by an application executing in tile RAM - Fix xflash no longer resets the target after writing - Reinstate the xflash --loader option - Reinstate the xflash --idnum option - Reinstate the xflash --idstr option - Support the xflash --factory-version 15.1 option - Fix xflash help: --factory-version missing version 15 - Fix xflash to generate an identical binary each time it is invoked * libquadflash - Remove setting of the quad flash QE bit by the function fl_connect() * Bootloader - Perform secure checks in constant time * xcc - Reinstate pre-defined macros XCC_VERSION_MAJOR (with decimal value 1501) XCC_VERSION_MINOR (with value 1) XCC_VERSION_YEAR (with decimal value 15) XCC_VERSION_MONTH (with value 1) - Provide the macros __XMOS_XTC_VERSION_MAJOR__ (with decimal value 15) __XMOS_XTC_VERSION_MINOR__ (with value 1) __XMOS_XTC_VERSION_PATCH__ (with value 1) * xrun and xgdb - Fix an issue where xrun/xgdb failed to initialize the target's reference clock correctly - Fix xgdb to connect, load and run a program via JTAG when OTP is programmed - Fix help description for --jtag-speed - Upgrade XTAG4 firmware to improve reliability with certain hubs * xsim - Provide xcore.ai OTP write support - Redirect "unhandled exception" messages to stdout - Simulate xcore.ai USB functions * xscope - Remove warning messages when packets are received out of order from multiple tiles, which may swamp the console and impact target and xscope performance. Write packets to file in order with respect to their target-generated timestamp - Fix failure to handle xscope packets larger than 16384 bytes. * Documentation - Fixed sizing of certain images and visibility in dark mode - Updates to the XN specification - Added a new section on working with targets - Improved visibility of images in Windows Dark Mode Documentation rendering improvement for Windows in "Dark Mode" - Document xflash --quad-spi-clock missing --quad-spi-clock option in xflash online manual - Adds xflash documentation for the reinstated options: --loader, --idnum, --idstr KNOWN ISSUES ------------ * Linux Recent Linux distros such as Fedora and Ubuntu have dropped the required version of libtinfo. If the following error is shown when any of the XTC Tools are launched: error while loading shared libraries: libtinfo.so.5: cannot open shared object file: No such file or directory install the required library following the steps below. On Fedora based OS: yum install ncurses-compat-libs On a Ubuntu based OS: apt-get install libtinfo5 Release Notes for XTC Tools: 15.1.0 (build: 446-e647144) ================================================================ Previous major release: 14.4.1 (build: 235-acbb966) (rc3) OVERVIEW OF CHANGES SINCE LAST MAJOR RELEASE -------------------------------------------- * Added support for development using xcore.ai family of products - Compiler support for new architecture. In particular, new FPU instructions supported - Simulator support for architecture core and chip-level features, including use of external memory and "software memory" via the new minicache - Assembler support for writing VPU code and new instructions - Debugger support for new architecture - XTAG firmware support for JTAG interface - Support for XCORE-AI-EXPLORER board product - Continued support for existing xCORE-XS1 and xCORE-200 based products * Enhanced support for programming in C - Inclusion of the lib_xcore system library and headers marks a shift in emphasis towards programming the xcore in C, rather than XC - The lib_xcore system library allows equivalents of XC constructs including select{} and par{} to be written without leaving the C language - XC compiler still included, though it is recommended that new code be written in C * Removed xTIMEcomposer IDE - Marks a move towards allowing developers to partner the XMOS tools with a development environment of their choosing - Greater emphasis on command-line usage of the tools and the debugger * Removed xta static timing analysis tool - Internal and external surveys point to very low usage of this tool * xflash - Support for xcore.ai added - Now supports use of "software memory" * The discontinued xtag2 is now unsupported - Users should upgrade to the newer xtag3 or xtag4 KNOWN ISSUES ------------ * Linux - Recent Linux distros such as Fedora and Ubuntu have dropped the required version of libtinfo. If you see an error similar to: error while loading shared libraries: libtinfo.so.5: cannot open shared object file: No such file or directory ...you will need to install the required library: Fedora: yum install ncurses-compat-libs Ubuntu: apt-get install libtinfo5 * MacOS - This toolkit release is not properly signed, meaning that the stricter security rules on MacOS Catelina will cause security dialogs to be raised when the tools are run. This design advisory: https://www.xmos.ai/download/Design-Advisory---Running-xTIMEcomposer-on-MacOS-Catalina(10-January-2020).pdf) describes the workaround. SUMMARY OF CHANGES SINCE 15.0.6 (build: 445-3976dcf) ---------------------------------------------------- * Toolchain * XAS - Added `.asciz` directive equivalent to already-existing `.asciiz` directive. Makes XAS more compliant with other assemblers. * C/C++ compiler (specifically xcc2clang) - Existing C/C++ compiler now defines `__XMOS_LEGACY_C_CPP_COMPILER__` such that it can be distinguished from a forthcoming newer Clang-based compiler. * XMAP - Allow XS2 objects/libraries to be linked into XS3 applications using the XMAP's new `--target-mismatch` option (accessible via XCC using its `-Xmapper` option). Note: this option should be used with care - it is generally an error to mix ISA versions in a given application. * XOBJDUMP - Fixed minor mistakes in error messages * Libraries * lib_xcore - Exploit code-optimisations relating to the SELECT macro which are available when using the forthcoming newer Clang-based compiler. * Simulation - XSIM made more cycle-accurate, particularly w.r.t. behaviour of Ports. SUMMARY OF CHANGES SINCE 15.0.5 (build: 444-f265988) ---------------------------------------------------- * Toolchain * XAS - Modified rewrite of DWARF debug data to support upcoming rebased Clang-based compiler * Libraries * lib_otp - Made otp.h/otp3/h C-includable - Fix faults in libotp3.a discovered during xcore.ai OTP bring-up * libxs1/libxc - By default, no longer define `clock` for compatibility with the standard `time.h`. Instead, `xcore-clock_t` is the new correct type to use for a clock. `clock` is still defined unconditionally in XC mode. However, code which is intended to be shared between C and XC (e.g. headers) should use xcore_clock_t. Legacy code can be built by defining (preferably at build time, rather than in source) XCORE_USE_LEGACY_CLOCK_NAMING - this will define `clock` as a typedef of `xcore_clock_t`. * Documentation - Significant changes include: - Documented `config.xscope` approach for XSCOPE configuration; deprecated older `xscope_user_init()` approach - Added lib_xcore API documentation - Clarified other deprecation notices SUMMARY OF CHANGES SINCE 15.0.4 (build: 443-4ade02d) ---------------------------------------------------- * Installation - Changed brand name to "XTC Tools". Some corresponding path name changes - Individual tools now built independently. This means that build/version information provided by using the `--version` option of a given command line tool no longer identifies the toolkit build/version. Use `cat "$XMOS_TOOL_PATH"/doc/version.txt` instead. * Toolchain * XAS - Corrected expression evaluation in XAS (Bug 18470) * XSIM - Correct the reset value of the EXTMEM device size - Fix instability on Windows relating to minicache simulation (Bug 18499) * XGDB - There have been improvements to the xscope feature used to transport data between the target and the host machine, and improvements to hardware debugging features: - Improved reliability of data sent over xlink (via xscope API calls or printf + xscope_config_io(XSCOPE_IO_BASIC)). This includes fixing a specific scenario where xscope data may be lost when target program terminates (Bug 18494) - Fixed profiling tool which uses PC sampling. Tile 1 data was not captured correctly - Hardware breakpoint fix: The user may set only one (per tile). Report error when more than one is set - Watchpoints: Fixed watchpoint setup and handling. Implemented data access watchpoints * Libraries * lib_xcore - Optimised performance of `port_out_part_word()` on XS2 and beyond (Bug 18468) - Added missing cast within `local_thread_mode_get_bits()` (Bug 18485) - Corrected cast within `minicache_prefetch()` * Documentation - Significant changes include: - Added guides to integrating tools with Eclipse and VS Code - Added transitioning guide for users of older tools versions ("C for xCore" video, XC -> C cheatsheet & general transitioning guidance) SUMMARY OF CHANGES SINCE 15.0.2 (build: 439-2f21378) ---------------------------------------------------- * Installation - Windows installer is now XMOS-signed - Removed out-of-date "Community" branding from Windows and Mac installers (Bug 18447) - Simplified Windows and Mac installation down to a single command prompt icon - Added the version number to the Windows “Uninstall” option * Documentation - Added updated HTML documentation into $XMOS_TOOL_PATH/doc/html folder * Toolchain - XTAG/XGDB/XRUN - Provides XTAG4 support on all host operating systems - Fixed failure to reset the target after xflash writes the target’s flash memory (a regression vs. 14.4) - Provides workaround to allow executing firmware to reboot the target (a regression vs. 14.4) (Bug 18006) - Fixed failure to reset the target (via the JTAG TestMode register) for systems where srst is not connected between the XTAG and the target board - Fixed processing of xgdb “reset” command options so “nointerrupt” behaviour is invoked when additionally supplying “mode-pins”, “jtag” or no additional options * Linux - Improved setup_xmos_devices.sh and check_xmos_devices.sh scripts - Corrected generation of symlinks - Check script no longer requires user to be root - Updated technique for restarting udev service - Simplified user output - Improved xscope bandwidth on some Linux hosts (Bug 18451) * Mac - Fixed xrun/xgdb failure to detect XTAG on some Macbook hosts * Windows - New Microsoft-signed driver provided for XTAG3 and XTAG4 - A new Windows service is created by the installer to support XTAGs - On Windows XTAG adapter IDs are now reported by xrun -l in upper case but the user-supplied option to --adapter-id is case-insensitive - All support for debug adapters prior to XTAG3 has been removed - XCC - Prevented XCC placing C consts in a CP-relative section. This prevents some large constant arrays from causing an unresolvable relocation error at link time. (Bug 18441) - Prevented XCC passing/expecting non-copyable/non-movable class-type objects in registers. - Fixed an issue which prevented XCC from passing/expecting certain qualifying single-member class-type objects in registers. - XAS - Fixed a crash in XAS when no .debug_ranges is present. - Allowed XAS to rewrite .debug_info sections where the length word is provided as a label difference. * Libraries - lib_xcore - Added new functions to xcore/port.h: `port_sync()`, `port_set_shift_count()`, `port_out_part_word()` (Bug 18459) - Added missing volatile qualification to `port_peek()` (Bug 18458) - Added new function to xcore/thread.h: `thread_group_try_add()` - `xthread_alloc_and_start()` now returns 0 without leaking resources if allocation fails - Added new functions to xcore/thread.h: `local_thread_mode_set_bits()`, `local_thread_mode_get_bits()`, `local_thread_mode_clear_bits()` - lib_otp - Incorporated xcore.ai lib_otp changes to support OTP validation SUMMARY OF CHANGES SINCE 15.0.1 (build: 437-94d9a84) ---------------------------------------------------- * xscope and tracing - Fix various errors when the target application uses the xscope APIs and is running on xsim - Fix various errors when the target application uses IO (printf etc) via xscope and is running on xsim - Fix various failing xsim VCD tracing features (such as port tracing). (Includes Bug 18431) - Handle xscope probe names with spaces in them (by substituting spaces for underscores in the generated VCD file) * xflash & xburn - OTP library used by xburn has been updated after bring-up on xcore.ai - Removed version check from xburn and corresponding --no-version-check option (Bug 18415). - Removed compression facility from xflash and corresponding --no-compression option (Bug 18400) * Misc - Removed xtag1 FTDI support from xgdb (and corresponding openocd license statement) SUMMARY OF CHANGES SINCE 15.0.0 (build: 426-5e0576c) (rc4) ---------------------------------------------------------- * LPDDR and using larger address spaces - Improved LPDDR support on xcore.ai (Bug 18386): - Enabled automatic DLL calibration, which makes LPDDR reliable up to 100MHz - Changed order of LPDDR controller register setup - Fixed a compiler crash which occurred when deduplicating constant pool entries (Bug 18398) * FPU - Improved XS3 single-precision floating-point division and square root routines, making better use of the XS3 FPU (Bug 18384). - Corrected behaviour of xsim w.r.t. the FMAKE XS3 instruction. This bug did not affect XS3 hardware, where the instruction was already correctly implemented (Bug 18405). * xrun/xgdb/xscope - Conducted extensive testing of xTAG and target features such as connect, download, debug, xscope, normal termination, abnormal termination (such as the target being reset during a connection or the xgdb process being killed): - using Linux Centos 64-bit and Windows 10 Pro hosts - with xcore200 and xcore.ai targets - Support for xscope APIs and message printing from a hardware target has been largely restored to the level of functionality provided in the 14.4.1 tools. Note xscope and port tracing with xsim should not be used in this release. - xgdb will no longer attempt to access the XMOS website prior to connecting to a target via an XTAG - Improved reliability when using multiple xtags from a Windows host (Bug 18426) - Improved behaviour when debugging code using multiple HW threads (Bug 18336) - Added work-around for silicon bug present in xs2a and xcore.ai devices such that input clk can now be used from 8 to 30 MHz (previously the tools failed when the input clock was increased above 26 MHz). (Bug 17159). Also resulted in some improvements to JTAG "bypass" selection. - Stopped creation of extraneous xscope.xmt.gtkw, xscope.xmt.vcd and xscope.xmt files when --xscope options are used. (Bug 18353) - Text written to fd 1 or 2, or streams stdout or stderr from the target via the xscope transport now appear on the console when launched via either xrun or via xgdb (Bug 18350) - Fixed xrun such that output to stdout via the xscope stream appears on the host console just as it does when the app is launched via xgdb (Bug 18407) - xscope output data is now written to the .vcd file as it is generated (rather than at app termination or graceful xgdb exit) (Bug 18402) - Stopped writing of invalid data to TestMode register when connecting to a device via xtag. Instead use predefined reset values for xs2a and xs3a. (Bug 18401) - Improved reliability of xscope bi-directional operation by increasing internal USB timeout specifications. (Bug 18408) Note the user must still fragment their data in to a maximum of 256 bytes per upload transaction. Also note on Windows hosts the host-side application must be built in 32-bit mode. - Improved reliability of xgdb when stepping through code on the xcore.ai target (Bug 18424) - The low-level xgdb command "csr" now works when the target node id is non zero (Bug 18421) * Misc - Suppressed non-memory resource reporting by xMap when lib_xcore is used, as it is only appropriate to produce resource usage stats when programming in the XC language. - Replaced out-of-date releaseNotes.txt with simpler version.txt for identification of toolkit version. SUMMARY OF CHANGES SINCE 15.0.0 (build: 422-f8fb16a) (rc3) ---------------------------------------------------------- * xrun/xgdb - Better handling of xrun arguments 18382 - Fix xtag reboot following unexpected termination from target running xscope lossless stream - Tidy workaround to 18370 - Handle xgdb cases where command requires connection but there isn't one - Update to use XTAG FW #32-d54d758 (fixes crash when USB-reset sent from host) * Misc - Minor fixes to lib_xcore (missing instructions, more efficient) - Fixes to stack size calculation when using FPU on Phoenix 18381 - Pull in latest xflash which is able to load programs which use SW memory - Modifications to assembler xas such that it can handle assembly output from Clang 9