                Release Notes for SystemC Release 2.2.0
                =======================================

CONTENTS
========

  1) What's new in this release?

  2) Bug fixes and enhancements

  3) New features

  4) Incompatibitilies with previous releases

  5) Fixes to match the IEEE 1666 SystemC Language Reference Manual

  6) Beta features

  7) Deprecated features

  8) Known problems

  9) Fixed-point library


1) What's new in this release?
==============================

Compared to the 04feb06_beta release, this release has the following
new items:

  - Changed sc_event usage in signals to be dynamically allocated instead
    of statically being part of signal storage to save space.
  - Changed name of sc_get_current_process_base() function to be 
    sc_get_current_process_b() since it returns an sc_process_b.
  - Changed the type of m_writer field in sc_signal to be an sc_object
    rather than an sc_process_b for more opaqness.
  - Added declarations for functions in scx_rep.h, sc_signed.h, sc_unsigned.h,
    sc_process.h, sc_simcontext.cpp to keep gcc 4.x happy
  - Hid the definitions of the sc_cthread_process, sc_method_process,
    and sc_thread_process classes from the user. That is, the files
    containing these classes do not get copied into the include directory
    when an install occurs. The specific changes are:
    a) Three new methods were added to sc_simcontext to create processes:
         o create_cthread_process()
         o create_method_process()
         o create_thread_process()
       These all return an sc_process_handle. These methods are now
       called by the process macros, e.g., SC_CTHREAD, and by sc_spawn()
       when processes are created.
    b) Three methods were removed from sc_simcontext that were previously
       used to register processes:
         o register_cthread_process()
         o register_method_process()
         o register_thread_process()
       These are no longer called, since you cannot create a process 
       without calling one of the three new create_XXXX_process methods.
    c) A new << operator was added to sc_sensitive, sc_sensitive_neg,
       and sc_sensitive_pos classes:
         o operator << ( sc_process_handle )
       This new operator is now used to set the process in the SC_METHOD,
       SC_CTHREAD, and SC_THREAD macros.
    d) The << operators for process handles have been removed from the
       sc_sensitive, sc_sensitive_neg, and sc_sensitive_pos classes:
         o operator << ( sc_cthread_handle )
         o operator << ( sc_module_handle )
         o operator << ( sc_thread_handle )
       These are no longer needed since one can use an sc_process_handle
       instance to set the process.
       
  - Bug fixes, see next section.
     

2) Bug fixes and enhancements
=============================

Following is the list of bug fixes and enhancements for this release:

    - Fixed a bug when an exception is thrown in
      sc_module::sc_module() for a dynamically allocated sc_module
      object. We were calling sc_module::end_module() on a module that has
      already been deleted. The scenario runs like this:
  
      a) the sc_module constructor is entered
      b) the exception is thrown
      c) the exception processor deletes the storage for the sc_module
      d) the stack is unrolled causing the sc_module_name instance to be deleted   
      e) ~sc_module_name() calls end_module() with its pointer to the sc_module
      f) because the sc_module has been deleted its storage is corrupted,
         either by linking it to a free space chain, or by reuse of some sort
      g) the m_simc field is garbage
      h) the m_object_manager field is also garbage
      i) an exception occurs

      This does not happen for automatic sc_module instances since the
      ~sc_module_name() will no longer call sc_module::end_module() 
      if the sc_module instance has been deleted. This caused an
      exception on certain Linux platforms.


3) New features
===============

Here is an overview of changes in 2.2.0 compared to 2.1.v1:

    - SUPPORT FOR 64-BIT LINUX

        64-bit native mode for Linux is now a beta SystemC platform. The
        implementation uses Posix threads for thread support. The major
        code change is the use of the sc_digit data type to represent
        values that were previously unsigned long. These occurred in 
        the concatenation code and the internal representations for
        sc_signed, sc_unsigned, bit classes, and some fixed point classes.


4) Incompatibilities with previous releases
===========================================

Here is a list of known incompatibilities between this release and 2.1.v1:

  - Lambda expressions, and the functions and methods associated with
    them, have been removed to comply with the SystemC standard. 
    
      o The deferred() method has been removed from the signal and port
        classes that took bool or sc_logic templates. The deferred()
        method was used to generate lambda expressions and so is 
        obsolete.

      o The watching() function has been removed. The major use of the
        watching() function was to provide reset semantics for 
        SC_CTHREAD instances. This is accomplished in SystemC 2.2.0 by 
        using the reset_signal_is() method of the sc_module class. 

      o The wait_until() function has been removed. Calls to wait_until() 
        can be replaced by a do-while loop. Given a wait_until() call like
            wait_until( valid.deferred() == true );
        replace it with
            do { wait(); } while ( !(valid == true) );
        Note the removal of the deferred() invocation and the reversal
        of the sense of the expression. The general algorithm for 
        converting a wait_until call: wait_until(expr) is:
          o Remove the deferred() method calls in the expression, leaving
            the ports and signals the calls were for.
          o Replace the wait_until text with 
                do { wait(); } while
          o Reverse the sense of the expression:
                do { wait(); } while ( !(expr) );

  - The check for multiple writers of a signal now defaults on rather than
    off. This means that if two separate processes write to a signal an 
    error will be reported. To turn off the check, reverting to the
    behavior of previous releases, one needs set an environment variable:
        setenv SC_SIGNAL_WRITE_CHECK DISABLE
    When set SystemC programs will not perform the write check.
    
  - The signature for the find_event() virutal method in sc_event_finder
    has changed. An additional optional sc_interface pointer has been
    added as an argument. So the signature is now:

    virtual sc_event& find_event( sc_interface* p = 0 ) const;

    The additional argument is used to specify the interface to return
    the sc_event instance for when using multi-interface ports.

  - The function for setting the time unit associated with a trace file
    has changed. It now has the signature:
       void set_time_unit( double v, sc_time_unit tu )
    rather than
       void set_time_unit( int exponent10_seconds )

    To map an old-style call into a new one use the following table:

       Old New v New tu | Old New v New tu | Old New v New tu
       --- ----- ------ | --- ----- ------ | --- ----- ------
       -15    1.0 SC_FS |  -9   1.0 SC_NS  |  -3   1.0 SC_MS
       -14   10.0 SC_FS |  -8  10.0 SC_NS  |  -2  10.0 SC_MS
       -13  100.0 SC_FS |  -7 100.0 SC_NS  |  -1 100.0 SC_MS
       -12    1.0 SC_PS |  -6   1.0 SC_US  |   0   1.0 SC_SEC
       -11   10.0 SC_PS |  -5  10.0 SC_US  |   1  10.0 SC_SEC
       -10  100.0 SC_PS |  -4 100.0 SC_US  |   2 100.0 SC_SEC

  - Three methods were removed from sc_simcontext that were previously
     used to register processes:
       o register_cthread_process()
       o register_method_process()
       o register_thread_process()
     These are no longer called, since you cannot create a process 
     without calling one of the three new create_XXXX_process methods.

  - The << operators for process handles have been removed from the
    sc_sensitive, sc_sensitive_neg, and sc_sensitive_pos classes:
      o operator << ( sc_cthread_handle )
      o operator << ( sc_module_handle )
      o operator << ( sc_thread_handle )
    These are no longer needed since one can use an sc_process_handle
    instance to set the process.

5) Fixes to match with the IEEE 1666 SystemC Language Reference Manual
======================================================================

- The OSCI SystemC 2.2.0 open-source proof-of-concept implementation is 
  now compliant with the IEEE 1666 SystemC Language Reference Manual(LRM)
  in a number of areas that SystemC 2.1.v1 was not. 
  
  The IEEE 1666 LRM is the official standard for the SystemC language. 
  It is a very useful reference document for all SystemC users, and it 
  can be freely downloaded it at the URL below:
  
      http://standards.ieee.org/getieee/1666/index.html
  
- The changes from 2.1.v1 
  are:

- 2.2.0 does implement the pure virtual function 
  set_time_unit of class sc_trace_file that replaces the member 
  functions sc_set_vcd_time_unit and sc_set_wif_time_unit of 
  classes vcd_trace_file and wif_trace_file, respectively. 

- 2.2.0 does implement the valid, name, proc_kind, 
  get_child_object, get_parent_object, dynamic, 
  terminated_event, operator==, operator!= members of the 
  class sc_process_handle. 

- 2.2.0 has removed member function wait() from class 
  sc_process_handle. 

- 2.2.0 has implemented the sc_get_current_process_handle 
  function. 

- 2.2.0 has implemented the kind member function of class 
  sc_event_queue and has changed the default constructor name 
  seed to "event_queue". 

- 2.2.0 has implemented the get_parent_object and 
  get_child_objects member functions of class sc_object 

- 2.2.0 has implemented the the behavior of sc_object 
  constructors and sc_gen_unique_name such that every sc_object 
  is registered in the object hierarchy and has a unique 
  hierarchical name of the form seed_N. 

- 2.2.0 has implemented the sc_find_object function and 
  sc_get_top_level_objects. 

- 2.2.0 has removed the constructors of class sc_export that 
  bind the export at the time of construction. 

- 2.2.0 has made constructor sc_export( const char* ) 
  explicit. 

- In 2.2.0 a call to function sc_spawn during what would have 
  been the final update phase causes the spawned process to run 
  in the next evaluation phase, potentially causing simulation to 
  continue. 

- 2.2.0 has changed the type of the first parameter to 
  functions sc_stop_here and sc_interrupt_here from int to const 
  char*. 

- 2.2.0 has removed the initialize and release member 
  functions of class sc_report_handler. 



6) Dynamic Process Support
==========================

SystemC 2.2.0 contains support for dynamic processes, allowing users 
to spawn processes during the execution of a SystemC model. To enable
dynamic process support one must define the following symbol before
including systemc.h:

    #define SC_INCLUDE_DYNAMIC_PROCESSES

An example of dynamic process use is contained in the directory
examples/2.1/sysc/forkjoin.

7) Beta features
================

In this section the beta features of this release are listed.

  - a new class scx_barrier has been added to provide barrier 
    synchronization for dynamic processes. The header defining
    it and an example of its use appear in the directory
    examples/sysc/2.1/scx_barrier.

  - specialized versions of signals and ports for SystemC integer
    datatypes, e.g., sc_int<W>, sc_biguint<W>, has been added for
    experimental use. The headers and source defining this support,
    and an example of its use appear in the examples directory under
    examples/sysc/2.1/specialized_signals.

  - a new class scx_mutex_w_policy has been added to provide mutex 
    support for random arbitration policies when more than one
    process is contending to use a mutex. The header defining this
    support, and an example, in the examples directory under
    examples/sysc/2.1/scx_mutex_w_policy.

8) Deprecated features
======================

In this section the deprecated features of this release compared with 
2.1.v1 are listed.

  - Lambda expressions and watching() and wait_until() have been removed.
    See section 4 above for details.

  - There are now warning messages for the many of the deprecated features 
    in Annex C of the IEEE 1666 SystemC Language Reference Manual (see
    docs/LRM.pdf). These messages may be turned off in two ways:
    
    (1) Setting the environment variable SC_DEPRECATION_WARNINGS to DISABLE:
    
        setenv SC_DEPRECATION_WARNINGS DISABLE
        
    (2) By using the following call as the first line of sc_main:

            sc_report_handler::set_actions("/IEEE_Std_1666/deprecated", 
                SC_DO_NOTHING);


9) Known Problems       
=================

  - 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.


10) Fixed-point library
=======================

(No change from 2.0.1 Production.)

SystemC contains a fixed-point datatypes package.

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).
