diff options
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'. |