diff options
author | Matthias Jung <jungma@eit.uni-kl.de> | 2017-03-01 18:39:56 +0100 |
---|---|---|
committer | Matthias Jung <jungma@eit.uni-kl.de> | 2017-05-18 08:36:56 +0000 |
commit | aa651c7f8321bf96fc88f9a17285225000a753ec (patch) | |
tree | b13240008c970b47bd74a5007e68136155d272fc /ext/systemc/RELEASENOTES | |
parent | 595e692de09e1b7cbc5f57ac01da299afc066fdd (diff) | |
download | gem5-aa651c7f8321bf96fc88f9a17285225000a753ec.tar.xz |
ext: Include SystemC 2.3.1 into gem5
In the past it happened several times that some changes in gem5 broke the
SystemC coupling. Recently Accelera has changed the licence for SystemC
from their own licence to Apache2.0, which is compatible with gem5.
However, SystemC usually relies on the Boost library, but I was able to
exchange the boost calls by c++11 alternatives. The recent SystemC version
is placed into /ext and is integrated into gem5's build system. The goal is
to integrate some SystemC tests for the CI in some following patches.
Change-Id: I4b66ec806b5e3cffc1d7c85d3735ff4fa5b31fd0
Reviewed-on: https://gem5-review.googlesource.com/2240
Reviewed-by: Andreas Sandberg <andreas.sandberg@arm.com>
Maintainer: Andreas Sandberg <andreas.sandberg@arm.com>
Diffstat (limited to 'ext/systemc/RELEASENOTES')
-rw-r--r-- | ext/systemc/RELEASENOTES | 685 |
1 files changed, 685 insertions, 0 deletions
diff --git a/ext/systemc/RELEASENOTES b/ext/systemc/RELEASENOTES new file mode 100644 index 000000000..2dd93b34c --- /dev/null +++ b/ext/systemc/RELEASENOTES @@ -0,0 +1,685 @@ + Release Notes for SystemC 2.3.1 + =============================== + + Andrew C. Goodrich, Forte Design Systems + Philipp A. Hartmann, OFFIS Institute for Information Technology + +CONTENTS +======== + + 1) What's new in this release? + + 2) Bug fixes and enhancements + + 3) New features + + 4) Incompatibitilies with previous releases + + 5) Expanded dynamic process support + + 6) Experimental features + + 7) Known problems + + 8) Fixed-point library + + 9) TLM Release Notes + + +1) What's new in this release? +============================== + +This version of SystemC contains the "Proof of Concept" simulator +for the IEEE 1666-2011 SystemC standard. Please consult the IEEE Std +1666-2011 SystemC Language Reference Manual for details about the +current SystemC standard. + +TLM-2.0 is merged into the main SystemC release since 2.3.0. +Please see section 9) below for more details related to TLM. + +Compared to the 2.3.0, this release has the following new items: + + - New features, partly beyond the current IEEE 1666-2011 standard, + see section 3. + + - Experimental features (disabled by default), see section 5. + Testing and feedback welcome via the Accellera SystemC forums + at http://forums.accellera.org/forum/9-systemc/. + + - Bug fixes, see section 2. + + - Expanded platform support, see the README. + + + +2) Bug fixes and enhancements +============================= + +Following is the list of bug fixes and enhancements for this release: + + - For fixes and enhancements of the embedded TLM-2.0 implementation, + please see section 9. + + - Additional changes and cleanups leading to incompatibilities with + previous versions of SystemC are described in section 4. + + - Fix nested SC_METHOD preemptions caused by resetting a method, which + throws an exception in a thread process. The control now correctly + goes back to the throwing method. + + - Handle the case of a suppressed multiple-writer error in sc_signal + (and related channels) consistently with SystemC 2.2.0 again. + + - The 'sc_buffer<bool>' and 'sc_buffer<sc_logic>' channels now correctly + notify their (pos|neg)edge_events, if someone is waiting on them. + + - Cleanup the renaming of the internal Boost namespaces. The embedded + Boost implementation resides in the (renamed) top-level namespaces + - sc_boost + - sc_unnamed (for placeholders, part of IEEE 1666-2011) + - sc_mpl_ (internal ADL barrier) + + - Minor fixes in sc_vector-related classes + - correctly determine instantiation context + - sc_vector_iter: addition/substraction operators fixed + - sc_vector_assembly: add swap, fix missing return statement in + assignment + + - WIF tracing of 64-bit integers: fix widths and masks on some + 64-bit platforms. + + - Suppressed a warning in case of calling sc_start in case of pending + delta notifications without any pending (or resulting) process + activations afterwards (1666-2011 compatbility). + + - Fix sc_string_old implementation to handle very long strings (>1024) + (known issue in <=2.3.0). Note, that sc_string_old is no longer + included by default, see section 4. + + - Add "risc_cpu" example to Automake build system ("make check"). + + - Add missing files to the MS Visual C++ SystemC.vcproj project file. + + - Add a missing "break" statement to "scfx_utils.h" in the "SC_CSD" + format parsing logic. + + - Fix several integer conversion warnings raised by some compilers + throughout the SystemC implementation. + + - Fixed incorrect GCC i386/x86_64 function call stack alignment when + using the QuickThreads/WinFiber-based process implementations (16-byte + boundary). This avoids segmentation faults in some cases where the + stricter stack requirement is implicitly assumed by the compiler. + + - The default stack size for threads, SC_DEFAULT_STACK_SIZE, has been + increased on 64-bit platforms and is overridable at library build + time (see INSTALL). + + - The sc_report implementation now correctly handles empty and NULL + message type arguments (avoiding a segmentation fault in these cases). + The sc_report default constructor is made private to follow IEEE 1666. + + - Missing namespace qualifiers added to all reporting macros, namely + - SC_DEFAULT_*_ACTIONS + - SC_REPORT_INFO_VERB + to make them usable again while including <systemc> instead of + <systemc.h> + + - VCD/WIF tracing: fix support for very long values + + The sc_(un)signed and sc_fxnum(_fast) data types can potentially hold + longer values than 1000 bit, which used to be the fixed size of the + intermediate buffers in sc_(vcd,wif)_trace for these types. + + - Cleanup systemc.h + + - Drop any in-library dependencies on the old 'sc_string' class, + removing the need to provide the corresponding header externally + (see section 4). + - Drop explicit in-header dependencies on <windows.h> on Windows + platforms, removing the automatic inclusion from <systemc[.h]> + (see section 4). + - Drop inclusion of 'strstream' by default on some platforms + (see section 4) + - assume working C++ standard library on all platforms + - assume working argument-dependent lookup on MSVC + (which should be working since MSVC 2003 already) + - see section 4 and INSTALL file + + - Improved compile/runtime check of the SystemC library config + + Some preprocessor switches need to be consistent between the application + and the library (e.g. if sizes of classes are affected or other parts of + the ABI are affected). These can now be checked at link-time. + + Secondly, some preprocessor switches need to be consistent between + different translation units of an application, which is checked at + runtime startup. + + - sc_context: avoid reinterpret_cast from integer to pointer + + - The SC_VERSION_ORIGINATOR has been renamed from "ASI" to "Accellera" + to follow the naming policies of the Accellera Systems Initiative. + + - Cleanups of the VCD/WIF tracing implementation + + - Removal of internal files from the public headers (see section 4) + - Report any information (infos, warnings, errors) via the SystemC + reporting mechanism instead of directl printing to std::cout/cerr + - Automatically unregister trace updates when closing a trace file + during the simulation + + - Drop the 'register' storage class specifier, which has been + deprecated in the C++11 standard (and therefore might cause warnings + on some compilers). + + - Expanded naming of traced objects in VCD traces to use 5 characters + rather than 3 to accommodate more signals (incomplete in 2.3.0). + + - Fix sc_signed/sc_unsigned conversion bug on GCC 4.8 or later, coming + from its aggressive optimization in case of integer over/underflows + (by avoiding the C++ undefined behaviour in the implementation). + + - An output stream operator<< for sc_status is added to enable + pretty-printing of sc_status values (and bitwise combinations of + such values). + + - Various minor code cleanups and compiler warning fixes + - removal of some workarounds for very old versions of some + compilers (e.g. MSVC < 8.0). + - removal of unused variables and macros + - some deduplication of redundant code paths + + +3) New features +=============== + +Here is an overview of changes in 2.3.1 compared to 2.3.0. + +Note: These features partly add functionality beyond the current + IEEE Std. 1666-2011. + + + - Major rewrite of the Autoconf/Automake build system + - better control of the installation directories + - improved libtool library dependency detection, especially + in cross-compilation scenarios (--host=...) + - support for pkg-config for SystemC and TLM + (see http://www.freedesktop.org/wiki/Software/pkg-config/) + - accept arbitrary GCC-compatible compilers + (e.g. Clang, Intel compiler, compiler-wrappers like scan-build) + - avoid deprecation warnings, cleanup implementation + - less recursive build, silent rules by default + - improved "make check" test handling + + + - Updated MS Visual C++ project and solution files to include + support for Visual Studio 2012 and 64-bit builds on Windows + platforms. + + + - Improved conversion between the underlying integral time + representation and sc_time objects: + + - Add a nested typedef "value_type" to sc_time to enable an + implementation-independent use of the underlying integral + time representation (see IEEE 1666-2011, 5.11.1). + + - Adding an inverse to the 'sc_time::value()' function to + convert a plain value back to an sc_time object: + static sc_time sc_time::from_value( value_type t ); + + - Adding modulus operators (%, %=) to compute time offsets from + clock or quantum boundaries: + + sc_time operator%(const sc_time& lhs, const sc_time& rhs); + + sc_time& sc_time::operator%=(); + + Note: These operators are missing from IEEE 1666-2011, which + make e.g. the tlm_global_quantum implementation nearly + impossible within the limits of the SystemC standard. + + + - Add function to determine the current object hierarchy: + + sc_object* sc_core::sc_get_current_object() + + Returns a pointer to the sc_object instance (or NULL) that would + currently become the parent object of a newly created sc_object + instance (i.e. the current module during elaboration, and the + currently active process during simulation). + + + - Add compile-time configurable default signal writer policy + (see INSTALL). + + Defining SC_DEFAULT_WRITER_POLICY to one of the sc_writer_policy + values before including systemc(.h) allows application-wide selection + of the default sc_writer_policy used for signals. + + Defining SC_NO_WRITE_CHECK is equivalent to + SC_DEFAULT WRITER_POLICY=SC_UNCHECKED_WRITERS + + By default, the writer policy still disallows multiple + writers (SC_ONE_WRITER). + + + - Add an sc_signal initialization which does not create an event + via newly provided constructors to the signal classes: + + sc_signal<T>::sc_signal( const char* name + , const T& initial_value ); + + (similarly for sc_buffer and sc_signal_resolved) + + Compared to calling the "write()" function on a signal during + the elaboration, these constructors will set the initial value + of the signal without triggering an event at the beginning of the + simulation (and therefore may avoid triggering sensitive processes). + + + - Add a static function to sc_report_handler to query the current + report handler function: + + static sc_report_handler_proc sc_report_handler::get_handler(); + + Additionally, sc_report_handler::set_handler() now returns the + previously set handler (c.f. sc_report_handler::set_actions). + + + - Improved conversion from bitvector element references to bool + + As it is surprising to the user that a reference to an explicit + element of a sc_bv could not be used in a boolean context, a safe + conversion has been added to this release. + + This enables the following coding style: + + sc_bv<8> mybits; + // ... + if( mybits[0] ) // no longer a compiler error here! + /* do something */ ; + + Note: For logic vectors, the bit-references still need to be + converted to bool explicitly (e.g. via the "to_bool()" + function. + + + +4) Incompatibilities with previous releases +=========================================== + +Here is a list of known incompatibilities between this release and +2.3.0 (or earlier): + + - The non-standard sc_time constructors + - sc_time( uint64, bool scale ) + - sc_time( double, bool scale ) + have been deprecated and issue a warning when being used. + Use the new 'sc_time::from_value' function instead (see section 3). + + - The non-standard function 'sc_object::get_parent()' has been + deprecated, use 'sc_object::get_parent_object()' instead. + + - The non-standard function 'sc_signal::get_new_value()' has been + deprecated (as required by IEEE 1666-2011). + + - The non-standard implementation classes for the VCD and WIF tracing + (vcd_trace_file, wif_trace_file) are now hidden from an application + and no longer part of the public headers. + Use the IEEE 1666-2011 functions + - sc_trace + - sc_create_[vcd|wif]_trace_file + - sc_close_[vcd|wif]_trace_file + - sc_trace_file::set_time_unit + to set up the tracing in your application. + + - The non-standard header 'src/sysc/communication/sc_reset.h' is + no longer part of the public headers. + + - The 'sc_string_old' class is no longer available by default. + Define 'SC_USE_SC_STRING_OLD' before including "systemc.h", + see INSTALL. + + - The implicit inclusion of the system-headers "windows.h" (on Windows) + and (deprecated) "strstream" have been removed. See INSTALL. + + - The incomplete implementation of old "W_*" watching macros and the + non-standard struct sc_watch have been removed. + +Here is a list of known incompatibilities between this release and 2.2.0: + + - The order that processes (SC_METHODs and SC_THREADs) are dispatched + for execution may be different than the order with SystemC 2.2.0 for + some SystemC programs. This is related to the new starvation policy + support for the sc_start() function introduced with IEEE 1666_2011. + + - The various bind() functions for ports and exports are "virtual" as + of IEEE 1666-2011. This leads to an incompatibility with the + TLM 2.0.x release. To use SystemC 2.3 together with TLM 2.0.{0,1}, + define SC_DISABLE_VIRTUAL_BIND during the build of the simulator and + before including systemc.h (see INSTALL). + + +5) Expanded Dynamic Process Support +=================================== + +This version implements the dynamic process extensions described in the +IEEE Std 1666-2011 Language Reference Manual. + +Compared to SystemC 2.3.0, some bugs in corner cases of the +specification have been fixed (see section 2). + + +6) Experimental features +======================== + +In this section the experimental features of this release are listed. + +Note: These features are not enabled in the default library + configuration and need to be explicitly activated during at + library build time. See INSTALL file. + + + - Extended Simulation Phase Callbacks + + This release adds an optional mechanism to register callbacks + to several simulation phases. This can be used to integrate + custom introspection techniques in a non-invasive manner. + + New phases are added to the sc_status enumeration: + + SC_END_OF_INITIALIZATION, + SC_END_OF_UPDATE, + SC_BEFORE_TIMESTEP + + to enable a more fine-grained view to the SystemC simulation phases. + + When the phase callback mechanism is activated (see the INSTALL file), + any sc_object can subscribe to a (set of) elaboration/simulation phases + for dynamic callbacks explicitly: + + // trigger current object before updating the simulation time + this->register_simulation_phase_callback( SC_BEFORE_TIMESTEP ); + + // trigger current object before returning to "sc_start" + this->register_simulation_phase_callback( SC_PAUSED | SC_STOPPED ); + + Unsubscribing from any simulation phase is possible via the corresponding + unregister_simulation_phase_callback( phase_cb_mask ) + function. + + Both functions return the effective mask after the requested callback mask + update. Therefore, querying the currently active mask can be achieved by + calling the (un)registration functions with an empty mask: + + sc_object::phase_cb_mask current_cb_mask = + this->register_simulation_phase_callback( 0u ); + + To enable the external (un)registration of callbacks for a user-defined + sc_object class, the (un)registration functions can be made public by + adding the following using directives to a 'public:' section of the + class definition: + + using sc_core::sc_object::register_simulation_phase_callback; + using sc_core::sc_object::unregister_simulation_phase_callback; + + When the simulation passes a phase where dynamic callbacks are registered, + the subscribed objects are triggered via the function: + + virtual void sc_object::simulation_phase_callback(); + + which should then be implemented by the subscribing object's class. + + Within a simulation callback, the triggering phase can be determined + via the IEEE 1666-2011 'sc_get_status()' function: + + void simulation_phase_callback() { + std::cout << sc_core::sc_get_status() << std::endl; + } + + A related feature is the triggering of sc_trace updates via these + simulation phase callbacks instead of the hard-coded calls in various + places of the simulation loop. This feature has to be enabled separately, + see INSTALL file. + + + - Allow creation of sc_max_time() objects before fixing the sc_time + resolution + + Currently. IEEE 1666-2011 requires that any call to + + sc_core::sc_set_time_resolution( double, sc_time_unit ) + + happens before the construction of the first non-SC_ZERO_TIME + sc_time object. + + This can be inconvenient in cases, where an "uninitialized sc_time value" + is needed, which needs to be separate from SC_ZERO_TIME in some cases. + + A relaxation of the strict sc_time construction rules wrt. to + the simulation time resolution can be optionally enabled via the + preprocessor switch SC_ENABLE_EARLY_MAXTIME_CREATION (see INSTALL). + + When this option is enabled, the creation of time objects with the + values SC_ZERO_TIME and 'sc_max_time()' are allowed before fixing the + time resolution. The resolution is still fixed once the actual + relationship between the internal time representation and the physical + time units (SC_FS, SC_PS, ...) is used or observed by the application. + + + + +7) Known Problems +================= + + - When building the SystemC library with QuickThreads support, the + resulting shared library is marked as requiring an executable stack + by certain compilers/assemblers (or rather not marked as not needing + one). As a result, some system security systems (like SELinux) might + refuse to load the library. As a workaround for GNU (compatible) + assemblers, pass the assembler flags variable with the option + CCASFLAGS="-Wa,--noexecstack" + to the `configure' script call before building the SystemC library. + + + - IEEE 1666-2011 does not explicitly define the behaviour in the corner + cases of attempting to create sc_time objects smaller than the time + resolution or bigger than sc_max_time(). This implementation currently + truncates "small" sc_time objects to SC_ZERO_TIME, while "too big" + objects wrap-around sc_max_time() and lead to a value modulo the + maximum time. In both cases, no warning is generated. + + + - The sign-extension of mixed-signedness logic expressions (&,|) + involving one sc_bigint<> operand and C++ builtin integral types + (int, short, etc.) is inconsistent between 32-bit and 64-bit + platforms in some cases. Convert both operands to sc_bigint<> first. + + + - The definition of sc_dt::(u)int64 differs from std::(u)int64_t types + on some platforms. This may lead to problems with function overloads + and/or format-string placeholders. As a workaround, convert these + values explicitly to the correct type before passing them to functions + expecting one of these types. For sc_time, use the new nested type + sc_time::value_type to hold values of the underlying representation. + + + - Bit/logic-vector reductions (or_reduce, and_reduce, etc.) return an + 'sc_logic_value_t' enum value, instead of a bool or sc_logic (as required + by IEEE 1666-2011). Using the return value of these functions in a + boolean context, e.g. + if( lv.or_reduce() ) { /* ... */ } + might lead to wrong results in case of 'X' or 'Z' bits in the vector. + Avoid this by converting the result to an 'sc_logic' first and perform + a safe conversion to bool: + if( sc_logic( lv.or_reduce() ).to_bool() ) { /* ... */ } + + + - The use of the DEBUG_SYSTEMC macro does not work properly with certain + compilers (e.g., gcc 2.95.x) if it was not also specified when the + SystemC library was built. The problem is caused by the use of the + library compiled version of some inline methods. This problem does not + appear to be present in the gcc 3.3, Solaris, and aCC compilers. + The work-around is to specify DEBUG_SYSTEMC when the SystemC library + is built. + + + - On some recent compilers (e.g. Clang, Solaris Studio), warnings are + generated about the "hidden overloaded virtual function" bind of the + sc_port(_b) class templates in the 'specialized_signals' example. + These warnings are caused by the introduction of the virtual bind + implementation in IEEE 1666-2011. + As a workaround, check your compiler documentation how to suppress + the warning (e.g. 'CXXFLAGS=-Wno-overloaded-virtual') or mark + the SystemC include directory as "system directory" by using + '-isystem ${SYSTEMC_HOME}/include' (or equivalent) instead of + the usual '-I'. + + This also affects the TLM-2.0 sockets, see Section 9.3. + + + - Some paths in this release are longer than the historical 99 character + limit of tar archives, and several Windows archivers (e.g. WinZip) + have been reported to trip over this. The open source archiver 7-zip + (http://7-zip.org) is known to work. + + +8) Fixed-point library +====================== + +SystemC contains a fixed-point datatypes package. + +Changes compared to SystemC 2.0.1 + + - support for explicit construction from "float" values + + - removing a conversion ambiguity by marking some constructors of + sc_fxval[_fast] classes as 'explicit' + +Compile-time macro SC_INCLUDE_FX must be defined in order to build +applications that use fixed point types. You can specify a compiler +flag, e.g., g++ -DSC_INCLUDE_FX ... or use a define statement before +you include systemc.h, e.g.: + + #define SC_INCLUDE_FX + #include "systemc.h" + +Due to the large size of the fixed-point datatypes header files, +compilation can take considerably more time. + +If you want to use the fixed-point data types only (i.e., not data- +types sc_int, sc_uint, sc_bigint, sc_biguint), compilation time can be +reduced by defining compile-time macro SC_FX_EXCLUDE_OTHER (in addition +to SC_INCLUDE_FX). + + +9) TLM Release Notes +==================== + +CONTENTS +======== + + 1) Supported SystemC versions + 2) What's changed in this kit? + 3) Known issues + + +9.1) Supported SystemC versions +=============================== + +SystemC 2.2.0 and 2.3.x are supported and have been tested. +SystemC 2.1.v1 is still supported in principle, but has not +been tested extensively. + + +9.2) What's changed in this kit? +================================ + +Compared to TLM 2.0.2 kit (part of SystemC 2.3.0), the following has changed: + + + - The tlm_utils headers have been cleaned up to include <tlm>, + instead of <tlm.h> + + + - The convenience sockets with base-protocol NB/B conversion support + now automatically define the required SC_INCLUDE_DYNAMIC_PROCESSES, + if not already provided by the user (since the B/NB conversion + depends on the SystemC dynamic process support). + + + - Improve the NB/B conversion in the simple_target_socket to avoid + the dynamic allocation (and deletion) of sc_event instances in the + use of the spawned helper processes for the converesion. + + + - Fix a bug in the same simple_target_socket NB/B conversion thread, + where the target socket may not detect the early completion of the + response phase via a "TLM_UPDATED" return value and a "TLM_END_RESP" + phase (base protocol violation). + + + - Fix the "get_base_interface()" implementation provided by the + multi_passthrough_target_socket. Prior to this release, a + dummy interface object has been used as a return value in case + of a hierarchical bind. Return the first bound interface instead. + + + - Fixed missing initialization of some member variables in the + callback_binder_fw|bw implementations, that caused segfaults + in some cases. + + + - The implementation-defined tlm::circular_buffer class has been + updated with the following changes + - now provides a "clear()" member function to drop the current + contents, + - fix a segmentation fault due to freeing invalid memory in + "resize()", which could happen in some cases, + - work around a parsing error on some EDG-based C++ frontends. + + + - tlm_global_quantum: use sc_time::operator% + + Instead of relying on a manual remainder calculation based on + sc_time::value and the non-standard backwards conversion, the new + sc_time::operator% is used to compute the remaining time in the + current quantum (see section 3). + + + - The internal tlm_array class (to hold payload extensions) has been + reimplemented based on std::vector (fixes copy constructor bug). + + + - The TLM_VERSION_ORIGINATOR has been renamed from "ASI" to "Accellera" + to follow the naming policies of the Accellera Systems Initiative. + + + + +9.3) Known issues +================= + +a. The tlm_simple_target_socket in tlm_utils does not obey the END_REQ rule + when only an nb_ call is registered, an b_ call is being handled in the + socket and there is an nb_ call coming in at the same time. In this case + the incoming nb_ call will be forwarded to the registered nb_ call without + checking whether the earlier b_ call has passed the END_REQ timing point. + +b. The implementation of the PEQ 'peq_with_get' in tlm_utils does not properly + distinguish between immediate notifications and delta notifications. In the + case that a immediate and delta notification happen at the same simulation + time both types of notifications emerge from the PEQ in the same evaluation + phase. This is wrong immediate notifications should overtake delta + notifications. + +c. On some recent compilers (e.g. Clang, Solaris Studio), warnings are generated + about the "hidden overloaded virtual function" bind of the sc_port(_b) + class templates when using the TLM-2.0 sockets. These warnings are caused by + the introduction of the virtual bind implementation in IEEE 1666-2011. + As a workaround in your application, check your compiler documentation how to + suppress the warning (e.g. adding the flag -Wno-overloaded-virtual), or mark + the SystemC include directory as "system directory" by using + '-isystem ${SYSTEMC_HOME}/include' (or equivalent) instead of the usual '-I'. |