Release Notes for Development Tools: Community_13.0.0 (build: 8511)
============================================================

Previous release: 12.0

NEW FEATURE ENHANCEMENTS
------------------------

* Highlights
	* This release adds new multicore extensions to C (xC 2.0). Features include:
		- Interface types provide a way to structure how communication happens between tasks.
		- Combinable and distributable tasks let you easily combine multiple tasks so they run on a single logical core.
		- Safe pointers add C style pointers with usage rules that maintain memory safety and freedom from data races.
	* Version 2 of xSCOPE device API introduced.
		- Supports collection and recording of char, short, int, long long, float and double types.
		- Supports collection and recording of byte arrays of a user specfied length.
	* Support for manually specify routing IDs of nodes in an .xn file, letting you target multi-node systems with non-hypercube and non-line network topologies.
	* Support for the xCORE-Analog series (A-Series).
	* Support for memory overlays. Memory overlays let you load code and data on demand at runtime, reducing the memory requirements of your application.
	* Support for transfer of data to the target via xSCOPE making it bi-directional.
	* Support for xSCOPE configuration files allowing registration and I/O setup.
	* Support for custom xSCOPE host applications for data processing.
	* Support for external github applications via the xTIMEcomposer community tab.

* xC compilation

	* The [[bidirectional]] attribute can be used to disable warnings on a declaration of a bidirectional buffered port.
	* Optimize the input and output of structures over a channel.
	* Support case replicators in select functions.
	* Add support for arrays with zero elements.
	* Support variables of nullable tileref type.
	* Allow sizeof on resource types.
	* Don't warn about unused static inline functions.
	* Support empty selects statements. An empty select statement causes the current task to pause indefinitely.
	* Add support for extern "C" blocks for better C interoperability.
	* Allow variable declarations anywhere in the code.
	* Add support for pattern variables (e.g. case c[int i] :> int x) for selecting over an entire array of resources.
	* Support structures containing nullable ports / clocks / timers.
	* Support local declarations of reference variables.
	* Support passing arrays where the size is specified as another parameter (e.g. void f(char buf[n], int n); ). Typically the compiler is able to optimize away more array bounds check when this form is used.
	* The number of timer variables is no longer limited by the number of hardware timers available. The tools now allocate a single timer per logical core that is reused as required.

* xmapper/linker

	* Extend --report to display the amount of memory reserved for loading overlays.

* c libraries

	* Make more functions from the C standard library available in xC, including string handling functions (e.g. memset(), strcpy()), and functions that operate on files (e.g. fopen(), fputs()).

* debugger

	* Add support for the plugins system call.
	* Add support for xTAG-PRO debug adapter.

* board support

	* Support networks with lines of more than 16 nodes.

* xSCOPE

	* xSCOPE offline view now shows zero line.
	* xSCOPE now supports bi-directional data transfer
	* xSCOPE now supports 64 bit data types.
	* xSCOPE now supports being enabled and disabled from the target application.
	* Add support for non-standard (i.e. non 100MHz) reference frequencies.
	* xSCOPE now outputs system wide timestamp for start of trace collection.
	* xSCOPE now provides a macro to check for enabled probe event

* simulation

	* xSCOPE tracing/IO can now be used in conjunction with the simulator.

* board support

	* Add support for the xCORE-USB sliceKIT development board.
	* Added support for A16 sliceKIT
	* Add support for startKIT development board.

* other

	* Add xntools command line tool. This can be used to annotate an .xn file with routing ID / routing information using the default routing algorithm or routing algorithm from the previous tools version.
	* Add xgprof command line tool.

* xTIMEcomposer Studio

	* The realtime xscope view can now accept input from an external process
	* xTIMEcomposer project include directories are now synchronised on build.
	* XMOS makefile build configurations are now automatically mirrored in xTIMEcomposer projects..
	* Add xSIM trace viewing capability.
	* SSL certificate checking can now be disabled via an xTIMEcomposer preference.
	* Check for newer versions of available board support packages at startup.
	* In project generation, any unassigned ports will now be left unassigned in the generated code (i.e. no default mapping is chosen).
	* Add option to create projects based on existing XMOS applications/modules.
	* Now have the ability to start a simulation with tracing on but disabled, when running via the GUI
	* The xTIMEcomposer studio now contains a separate community browser view
	* Streamlined the notifications mechanism
	* External support can now be found via an addition to xTIMEcomposer studio's top level toolbar/menu.
	* Add support for using xSCOPE in debug configurations.

* XCC frontend

	* Warnings implied by the -Wall option are now on by default. Use -Wno-all to disable these warnings.
	* Provide port defines when platform.h is included from an assembly file.

* xC libraries

	* Add typedefs for buffered ports to xccompat.h that can be used from C and xC.
	* Add array bound parameters to xC library functions where appropriate.
	* get_local_tile_id() no longer allocates a channel end resource, reducing resource usage.
	* Add get_tile_id() function to <xs1.h> to get the routing ID of the specified tile (e.g. get_tile_id(tile[0])).
	* Add hwtimer_t type to <hwtimer.h>. Declaring a variable of type hwtimer_t provides access to a dedicated timer resource.
	* Add macros CLIENT_INTERFACE, SERVER_INTERFACE to xccompat.h for passing interface ends between C and xC.
	* Add functions delay_seconds(), delay_milliseconds(), delay_microseconds() and delay_ticks() to timer.h
	* Add reconfigure_port macro (defined in xs1.h) which lets you dynamically reconfigure the type of a port.

* compilation

	* Word align functions by default unless -Os is specified.
	* Basic block tail merging is now performed at -O1 and above. This reduces code size by merging multiple blocks that end with the same common sequence of instructions.
	* Improve optimization of loops containing partial port inputs or outputs.

COMPATIBILITY CHANGES TO PREVIOUS RELEASE
-----------------------------------------

* system requirements
	* OS X 10.6 or later is now required to run the tools on an Apple Mac.

* debugger
	* xgdb now reads configuration options from .xgdbinit instead of .gdbinit.

* xC compilation
	* The timed-from (@+) modifier on port inputs and outputs has been removed, use the pinseq_at() or pinsneq_at() predicate functions in <xs1.h> instead.
	* xC 2.0 adds the following new keywords / reserved words:
		- client
		- server
		- interface
		- movable
		- unsafe
		- alias
		- noalias
		- shared
		- forward
		- extends
	  For backwards compatibility you can still declare variables with these names (with a warning) but support for this will be removed in future releases.
	* The ABI for timers has changed. Passing timers into libraries built with previous tools versions will not work. This can be fixed by recompiling the library.
	* For backwards compatibility a parameter declaration such a int ?a[] is interpreted as a nullable reference to an array ints instead of an reference to an array of nullable ints. In future you will be required to declare the parameter as int (?a)[].

* xC libraries
	* start_streaming_slave(), stop_streaming_slave(), start_streaming_master() and stop_streaming_master() have been removed.
	  These functions were unsafe to use across tiles due to possible deadlock issues.

* xflash
	* XFLASH no longer supports creating upgrade images compatibile with the factory images written by the 9.9.2 tools (previously this required passing the --992compat option).
        * The format of upgrade images has changed in this tool release, and the new format cannot be read by factory images writting using previous version of XFLASH. Use --factory-version 12 to create upgrade images that are compatibile with old factory images.

* xmap
	* When xmap assigns routing IDs to nodes at link time, it may pick different routing IDs to the ones chosen by previous tools releases. Any applications that rely on a specific routing ID being chosen should manually specify the required routing IDs in the .xn file for the target.

* xSCOPE
	* Version 1 of the xSCOPE device API is depreacted and will be removed in future release.
	* Binaries compiled with version 12 of the tools that use xSCOPE cannot be run in version 13 of the tools. This can be fixed by recompiling the code.

RESOLVED ISSUES
---------------

* xC compilation

	* Cannot set debug breakpoints on lines within a multi-tile main.
	* Incorrect resource usage reported for select function cases.
	* Compiler does not error on converting a resource type to a non-resource type in a reinterpret cast.

* OTP programming

	* xburn reports "unexpected error locking device" if the boot mode pins are not set to boot mode JTAG, even if writing the OTP succeeded.

* XMOS build system

	* Build errors on duplicate header detection if paths have parentheses in them.
	* Build fails when module directories are accidentally included under a doc/ directory within an eclipse workspace.
	* Makefiles do not pass in target option when building dependencies.

* xobjdump

	* Error showing mixed source / disassembly of multi-node binary.
	* xobjdump -d sometimes performs slowly on large executables.

* xSCOPE

	* Incorrect handling of large (>2GB) files in the offline xSCOPE viewer.
	* xSCOPE sometimes hangs in multi-tile startup.
	* xSCOPE now streams to file in offline mode rather than buffering until the end of run
	* xSCOPE now correctly warns about unregistered probes.
	* xSCOPE limit option now correctly limits trace output.
	* Number of channel ends used by an application is reported as unknown when the xSCOPE library is linked in.

* simulation

	* --dump-machine and --restore-machine do not work as expected

* XCC frontend

	* Input assembly file (.S) is overwritten when -save-temps is specified on OS X.

* xSOFTip Explorer

	* Can't assign values to arrays of ports in the generate project wizard.

* xmapper/linker

	* Don't warn about the use of ports that are partially pinned out.
	* Alias checks sometimes do not catch aliases in arguments to inlined functions.
	* Application compiled for XMP-64 fails to boot into application code.

* other

	* xmake -jN is now disabled on Windows since using make to build in parallel is not supported on this platform.

* debugger

	* With 2 XTAG-2 adaptors, if one is communicating with a device and the other is unplugged the connected device may fail.

* flash programming

	* XFLASH may hit a size limit and fail when creating an flash image for a target with a large number of tiles are booted from one flash.
	* Unrecoverable error creating encrypted, multi-node upgrade image.
	* Boot from flash hangs on a multi-node, multi-flash system when there are multiple parallel links between nodes.

* board support

	* XK-1A target does not include xSCOPE link information.

* c/c++ compilation

	* No array bound supplied when an xC function with structure argument is called from C++, resulting in runtime trap.

* timing analysis

	* Fixed issue with the setting of XTA endpoint via the UI.

* xTIMEcomposer Studio

	* Line numbers and XTA endpoint markers do not move with the text when scrolling the editor window on Mac OS X 10.8.
	* Changing the target in one run configuration affects other existing run configurations.
	* Fixed issue causing gprof to work when using multi-stage boot binaries.
	* Lots of bug fixes to xTIMEcomposer studio's parsing of xC code.
	* The xTIMEcomposer will now not cache downloaded but corrupt software zip files.
	* The XMOS makefile editor now correctly identifies makefile containing conditionals, and acts accordingly
	* New configurations in XMOS makefiles will now contain the correct system include paths.
	* Fixed issue in the saving and restoring of an xSOFTip explorer system
	* Offline xSCOPE now displays the Y-axis values in units of the last selected probe
	* Fixed a number of issues related to debugging multi-tile programs in the xTIMEcomposer studio.
	* When an xSOFTip explorer system is loaded from a file, it is not being displayed correctly.
	* Invalid makefiles being created for module based projects
	* Incorrectly displaying the size of functions in the binary viewer when nstackwords is not specified
	* Disassembly view does not show correct information with multiple tiles
	* Memory view for multi-tile case does not work correctly

* xC libraries

	* Incorrect stack usage information for write_periph_8() results in stack corruption
	* The ADC functions in <xs1_su.h> (e.g. enable_xs1_su_adc_input) don't work for any ADC channel apart from channel 0.

* compilation

	* The compiler now errors on a declaration of an stack variable with aligned attribute of greater than 4 bytes. Previously this case was sliently miscompiled.

KNOWN ISSUES
------------

* xC compilation

	* XTA label pragmas placed after break/continue/return may be added to unexpected places in output.
	* Breakpoints in multicore main need to be placed on last line of statements rather than first.
	* In DWARF line number information the directory of an included file is set to the same directory as the compilation directory even if it was included from a subdirectory.
	* Internal compiler error when boolean guard is used with select function.

* XMOS build system

	* Build system does not recognize C++ files unless the extension is .cpp
	* Build system does not build projects consisting of a single .s file.
	* Makefiles without XCC_FLAGS defined do not work.
	* Using LIBRARY instead of LIBRARIES in library build makefiles does not work in some cases

* runner

	* Cannot ctrl-c from 'ERROR : Cannot collect xSCOPE data from device'
	* stdout is printed to stderr.

* xas assembler

	* xas sometimes doesn't respond correctly to ctrl-c.

* simulation

	* xsim's handling of xlinks without credit doesn't match the hardware.

* XCC frontend

	* Compilation fails if the path contains non ASCII characters.
	* Use of -save-temps causes a compilation failure when two identically named files in different directories are compiled.

* flash library

	* Flash library data functions do not work unless program image is stored on flash.
	* Flash writing to device AMIC_A25L40PUM fails.

* xmapper/linker

	* xmap sometimes doesn't respond to ctrl-c.
	* No error about port used on the wrong tile when function is inlined
	* An erroneous reference to a static port from a different core is not reported at compile time (traps at run time).

* debugger

	* Attaching to a running system which has taken an exception does not allow automatic backtrace
	* Watchpoints set before application load are applied to the incorrect tile
	* Step-through to logical core 0 not working

* flash programming

	* xflash may include flash images for cores which are not bootees of a flash boot site when booting from multiple flashes
	* xflash may create a flash image which is too large and overwrites part of the stage 2 loader

* timing analysis

	* Timing of code using overlays is not supported
	* Endpoint annotations are not shown in header files
	* Sometimes the tool will not allow the setting of an endpoint, even though the gui implies that this should be possible.
	* Cannot load file from unicode path.
	* Script editor doesn't update syntax highlighting after edit.
	* XTA doesn't support timing across select functions.

* c/c++ compilation

	* Error initialising wchar_t array with wide string (c++)

* xTIMEcomposer Studio

	* Unable to disable a watchpoint once set.
	* Switching workspace in OSX can cause a second xTIMEcomposer dock icon to appear
	* If there are multiple files with the same name, it possible that a breakpoint set on one can be reported as hit in another.
	* Auto-completion not enabled for interface calls
	* Cannot open a new xTIMEcomposer studio from a previously running instance
	* refactor->rename functionality not working in xC code
	* Run does not build if there are no existing binaries.
	* When creating new source file, if a file of the same name already exists, it is overwritten.

* xC libraries

	* The clock type defined in xs1.h clashes with the clock() function in clock.h if both headers are included.