RE: Version number macros

All,

Okay, so the duplicated set of definitions would be as follows:

namespace tlm
{
#define TLM_VERSION_MAJOR implementation_defined_number // For example, 2
#define TLM_VERSION_MINOR implementation_defined_number // 0
#define TLM_VERSION_PATCH implementation_defined_number // 1
#define TLM_VERSION_ORIGINATOR implementation_defined_string // "OSCI"
#define TLM_VERSION_RELEASE_DATE implementation_defined_date // "20090329"
#define TLM_VERSION_PRERELEASE implementation_defined_string // "beta"
#define TLM_IS_PRERELEASE implementation_defined_bool // TRUE
#define TLM_VERSION implementation_defined_string // "2.0.1_beta-OSCI"
#define TLM_COPYRIGHT implementation_defined_string

const unsigned int tlm_version_major;
const unsigned int tlm_version_minor;
const unsigned int tlm_version_patch;
const std::string tlm_version_originator;
const std::string tlm_version_release_date;
const std::string tlm_version_prerelease;
const bool tlm_is_prerelease;
const std::string tlm_version_string;
const std::string tlm_copyright_string;

inline const char* tlm_release();
inline const char* tlm_version();
inline const char* tlm_copyright();
} // namespace tlm

namespace sc_core
{
#define SC_VERSION_MAJOR implementation_defined_number // For example, 2
#define SC_VERSION_MINOR implementation_defined_number // 0
#define SC_VERSION_PATCH implementation_defined_number // 1
#define SC_VERSION_ORIGINATOR implementation_defined_string // "OSCI"
#define SC_VERSION_RELEASE_DATE implementation_defined_date // "20090329"
#define SC_VERSION_PRERELEASE implementation_defined_string // "beta"
#define SC_IS_PRERELEASE implementation_defined_bool // TRUE
#define SC_VERSION implementation_defined_string // "2.0.1_beta-OSCI"
#define SC_COPYRIGHT implementation_defined_string

const unsigned int sc_version_major;
const unsigned int sc_version_minor;
const unsigned int sc_version_patch;
const std::string sc_version_originator;
const std::string sc_version_release_date;
const std::string sc_version_prerelease;
const bool sc_is_prerelease;
const std::string sc_version_string;
const std::string sc_copyright_string;

inline const char* sc_release();
inline const char* sc_version();
inline const char* sc_copyright();
}

I propose we adopt the TLM-2.0 rules for SystemC, namely:

major, minor, and patch restricted to character set [0-9]
originator and prerelease in [A-Z][a-z][0-9]_

This is very nearly backward compatible with 1666, in which major, minor
and patch can be in the wider character set [A-Z][a-z][0-9]_

To answer Jerome, sure, the actual choice of version numbers is
implementation-defined. The standard only defines the formal structure.
The OSCI simulator follows a specific lineage of version numbering. Other
vendors may base their versions on the OSCI numbering or may do their own
thing. These strings relate to the implementation itself, NOT to the
version of the IEEE standard the implementation claims to support. That
would be presumptuous!

Does that work?

John A

From:
"Roesler, Eric E" <eric.e.roesler@intel.com>
To:
David C Black <dcblack@xtreme-eda.com>, "john.aynsley@doulos.com"
<john.aynsley@doulos.com>
Cc:
Jerome CORNET <jerome.cornet@st.com>, "systemc-p1666-technical@eda.org"
<systemc-p1666-technical@eda.org>
Date:
30/09/2010 18:39
Subject:
RE: Version number macros

I attempted to reply yesterday but the message never appeared, apologies
if you see a duplicate.
 
I agree with David, it would be very handy to have the ability to check
for API compatibility at compile time. With the TLM macros already in
existence, they seem like a good starting point.
 
To the question of whether to combine or not ? I think you are going to
have to keep the TLM macros around for backward compatibility, but they
are specific to TLM, so you will in addition need macro for systemc in
general. So for now, I think you have to live with two separate sets of
macros. Perhaps you can deprecate the TLM macros in the near future, and
then remove them in a very future version.
 
EricR
 
 

From: owner-systemc-p1666-technical@eda.org [
mailto:owner-systemc-p1666-technical@eda.org] On Behalf Of David C Black
Sent: Tuesday, September 28, 2010 5:07 AM
To: john.aynsley@doulos.com
Cc: Jerome CORNET; systemc-p1666-technical@eda.org
Subject: Re: Version number macros
 
I would like to point out that the original SystemC API does not play well
with compile-time issues. With TLM it is quite nice to be able to detect
and deal with issues at compile-time. For example, when an incompatibility
arises due to versions. #if works nicely to prevent wasted compilation
cycles.
 
Also, this allows allows for writing code that is backward compatible,
which becomes an issue as ESL is now adopted in many places.
 
Back in May of 2008, Charles Wilson made several very reasoned comments on
this subject:
The issue I have with the SystemC version information is that is does not
provide a consistent, testable (compile time, run time) mechanism for
determining and extracting the version information.

I would assert that '20060505' is not the version, but rather the ISO 8601
date (YYYYMMDD) for the build. The version is '2.2.0'. SystemC version
strings are incorrectly implemented.

A developer implementing code that works with version of TLM should be
able to conditionally compile using standard practices

#if ( TLM_VERION_MAJOR < 2 ) <-- compile time

or

if ( tlm_version_major < 2 ) <-- run time

and not by elaborating each release date string.

Hence the choice of 'major.minor.patch[ (prerelease)]'.

where:

2.0.0 (DR1) indicates a developer release
2.0.0 indicates a public of 2.0
2.0.1 indicates a patch to 2.0
2.1.0 indicates an feature update to 2.0

I don't have an issue with including the build date in the string, with
the note that it should not be used except for public releases.

2.0.0 (20080614) indicating a public release of 2.0 on 14 June 2008.

-----------

references:

ISO 8601 <http://en.wikipedia.org/wiki/ISO_8601>
version numbering <http://apr.apache.org/versioning.html>
 
I think he made a very strong case for this approach. Also note his
reference to existing standards regarding both date formatting and
versioning.
 
So I am strongly in favor of the TLM style versioning.
 
------------------------------------------------------
David C Black, XtremeEDA ESL Practice Leader
http://www.Xtreme-EDA.com
(Consulting, Services & Training for all your ESL, verification and DFT
needs)
Voice: 512.850.4322 Skype:dcblack FAX: 888.467.4609
 
On Sep 28, 2010, at 6:16 AM, john.aynsley@doulos.com wrote:

Jerome, All,

Well, okay, but there is more to it than that. Here is the current SystemC
API. Note that there are no macros, but the release string has a formal
structure.

namespace sc_core {
const char* sc_copyright();
const char* sc_version();
const char* sc_release();
}

Function sc_release shall return an implementation-defined string of the
following form:
<major#>.<minor#>.<patch>-<originator>
where <major#> represents the major release number, <minor#> represents
the minor release
number, <patch> represents the patch level, and <originator> represents
the originator of the
SystemC implementation. The intent is that this string should be
machine-readable by any SystemC
application that has an interest in checking the version or release number
of the SystemC
implementation.
The character set for each of these four fields shall be as follows:
a)The lower-case letters a-z
b)The upper-case letters A-Z
c)The decimal digits 0-9
d)The underscore character _

and here is the equivalent for TLM-2.0 (taken from the OSCI LRM, not just
the implementation):

namespace tlm
{
#define TLM_VERSION_MAJOR implementation_defined_number // For example, 2
#define TLM_VERSION_MINOR implementation_defined_number // 0
#define TLM_VERSION_PATCH implementation_defined_number // 1
#define TLM_VERSION_ORIGINATOR implementation_defined_string // "OSCI"
#define TLM_VERSION_RELEASE_DATE implementation_defined_date // "20090329"

#define TLM_VERSION_PRERELEASE implementation_defined_string // "beta"
#define TLM_IS_PRERELEASE implementation_defined_bool // TRUE
#define TLM_VERSION implementation_defined_string // "2.0.1_beta-OSCI"
#define TLM_COPYRIGHT implementation_defined_string

const unsigned int tlm_version_major;
const unsigned int tlm_version_minor;
const unsigned int tlm_version_patch;
const std::string tlm_version_originator;
const std::string tlm_version_release_date;
const std::string tlm_version_prerelease;
const bool tlm_is_prerelease;
const std::string tlm_version_string;
const std::string tlm_copyright_string;

inline const char* tlm_release();
inline const char* tlm_version();
inline const char* tlm_copyright();
} // namespace tlm

So the question is, do we want independent and parallel set of definitions
for SystemC and TLM-2.0 releases, or do we want to merge them to give a
single combined version? Having made that decision, do we want backward
compatibility with the current 1666 and TLM-2.0 definitions?

John A

From:
Jerome CORNET <jerome.cornet@st.com>
To:
"Philipp A. Hartmann" <philipp.hartmann@offis.de>
Cc:
john.aynsley@doulos.com, systemc-p1666-technical@eda.org
Date:
16/09/2010 13:59
Subject:
Re: Version number macros
 

  Philipp,

sorry for the delay in the answer: obviously you are right (I should
have read the C++ norm more
carefully).

Agreed with all you said.

Regards,

Jerome

On 9/15/2010 11:29 AM, Philipp A. Hartmann wrote:
> Jerome,
>
> according to the C++ standard (17.4.3.1.2 [lib.global.names]), "certain
> sets of names and function signatures are always reserved to the [C++]
> implementation":
>
> - Each name that contains a double underscore (__) or begins with an
> underscore followed by an upper-case letter (2.11) is reserved to
> the implementation for any use.
>
> So I would prefer to have a macro name like SYSTEMC_IEEE_VERSION, or
> SYSTEMC_IEEE_1666. SYSTEMC_VERSION should not be used, since this is
> already used in (some) existing implementations.
>
> Thanks,
> Philipp
>
> On 14/09/10 13:17, Jerome CORNET wrote:
>> On 9/10/2010 4:07 PM, john.aynsley@doulos.com wrote:
>>> Jerome,
>>>
>>> After process control extensions, the next priority on the list is
>>> version number macros.
>>>
>>> You wrote:
>>>
>>> "Speaking of macros, I don't know if this has been planned, but it
>>> would be great (and standard practice) to specify a way to retrieve
>>> the version number of the norm that an implementation is following.
>>> (In our case that would be either 2005 or 2010 for now).
>>> The ISO C standard defines a macro __STDC__VERSION__ whose value is
>>> 199901L (integer long) for C99.
>>> ISO C++ also defines a macro, __cplusplus with value 199711L."
>>>
>>> Would you like to make a specific proposal?
>>>
>> John, All, (sorry for the slight delay)
>>
>> to me the best way is to follow the other standards' previous decisions
>> unless
>> we've got strong reasons for changing.
>>
>> So I would propose a macro (to allow test in #if) like this:
>>
>> __SYSTEMC_IEEE_VERSION with value 201001L
>>
>>
>> with 2010 be for 1666-2010 and 01 being reserved for minor revisions
(as
>> it is used for c++).
>>
>> If someone prefer a variations in the name (__SYSTEM_VERSION or
>> whatever), this is obviously
>> also ok for us.
>>
>>
>> Jerome
>>
>>
>>
>

-- 
This message has been scanned for viruses and 
dangerous content by MailScanner, and is 
believed to be clean. 
 
-- 
This message has been scanned for viruses and 
dangerous content by MailScanner, and is 
believed to be clean. 
-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.