Re: Version number macros

David,

you're right. I'm in favour of adding the numeric constants (defines).
 For the strings, I would at least prefer to have the 'const
std::string' objects to be 'extern', so that they are not added to each
and every translation unit, even if they are not used.

Thanks,
Philipp

On 05/10/10 01:28, David C Black wrote:
> Philipp,
>
> To summarize a lot of what you said (correct me if I'm wrong): You're mostly OK with the numeric values, but you don't see a purpose to the strings. I think the original thought behind those strings was to coax implementations to provide each of those bits of information to be used when displaying version information. By separating release date from originator in strings is compels the implementation to identify its origin. This could also by used by an IP implementor if for example, you found a short-coming in the environment, that would allow the IP to print out a message explaining that SC_VERSION_ORIGINATOR version XYZ had a bug and therefor some feature would not be supported for this run. This would of course be a run-time check (probably early in elaboration), but it could help IP developers. True you cannot use these macros during pre-compile. I've actually written code that I wanted supported under several EDA vendor implementations and found they had each done som
e
> unique things which needed work-arounds. Being able to identify the vendor this way would have been nice. Use of std::string makes comparison more straightforward, and it's only done prior to simulation typically, when efficiency is not quite the issue.
>
> Anyhow, I could probably be talked into either approach.
>
> On Oct 4, 2010, at 2:02 PM, Philipp A. Hartmann wrote:
>
>> John,
>>
>> please find some comments below.
>>
>> On 04/10/10 18:13, john.aynsley@doulos.com wrote:
>>>
>>> Okay, so the duplicated set of definitions would be as follows:
>> [snip tlm definitions]
>>
>> TLM is (usually) implemented as header-only library. Since SystemC
>> already requires separate linking, I think the rules can be different.
>>
>>> 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
>>
>> +1 on these. They are definitely useful at compile-time.
>>
>>> #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"
>>
>> Do we need these #defines? For what purpose? We can't do much with
>> them during preprocessing (except for string token concatenation).
>>
>>> #define SC_IS_PRERELEASE implementation_defined_bool // TRUE
>>
>> +1 on this.
>>
>>> #define SC_VERSION implementation_defined_string // "2.0.1_beta-OSCI"
>>> #define SC_COPYRIGHT implementation_defined_string
>>
>> Similar as above. I don't see the need for these symbols.
>>
>>> const unsigned int sc_version_major;
>>> const unsigned int sc_version_minor;
>>> const unsigned int sc_version_patch;
>>
>> I'm fine with these.
>>
>>> const std::string sc_version_originator;
>>> const std::string sc_version_release_date;
>>> const std::string sc_version_prerelease;
>>
>> I'm not sure, whether compilers are allowed to drop these constants, if
>> they are not used in a translation unit. Otherwise, having duplicate
>> definitions in each object file feels ... inefficient.
>>
>>> const bool sc_is_prerelease;
>>
>> +1.
>>
>>> const std::string sc_version_string;
>>> const std::string sc_copyright_string;
>>
>> As with the other string constants.
>>
>>> inline const char* sc_release();
>>> inline const char* sc_version();
>>> inline const char* sc_copyright();
>>
>> These should probably not be inline. As said above: We already have a
>> SystemC library to link against.
>>
>>> }
>>>
>> [snip char sets]
>>
>>>
>>> To answer Jerome, sure, the actual choice of version numbers is
>>> implementation-defined. The standard only defines the formal structure.
>>
>> IIUIC, that's exactly the motivation for having a compile-time symbol
>> for detecting the available structure. e.g. in cases of something like
>>
>> #if defined(SYSTEMC_IEEE_VERSION) && (SYSTEMC_IEEE_VERSION+0 >= 201001L)
>> // cleanup for process control extensions
>> catch ( sc_unwind_exception const & ) {
>> // ...
>> }
>> #endif
>>
>> Makes sense?
>>
>> Thanks,
>> Philipp
>>
>>> 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
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>>
>>>
>>>
>>
>>
>> --
>> Philipp A. Hartmann
>> Hardware/Software Design Methodology Group
>>
>> OFFIS Institute for Information Technology
>> R&D Division Transportation · FuE-Bereich Verkehr
>> Escherweg 2 · 26121 Oldenburg · Germany
>> Phone/Fax: +49-441-9722-420/282 · PGP: 0x9161A5C0 · http://www.offis.de/
>>
>>
>> --
>> This message has been scanned for viruses and
>> dangerous content by MailScanner, and is
>> believed to be clean.
>>
>>
>>
>
>

-- 
Philipp A. Hartmann
Hardware/Software Design Methodology Group
OFFIS Institute for Information Technology
R&D Division Transportation · FuE-Bereich Verkehr
Escherweg 2 · 26121 Oldenburg · Germany
Phone/Fax: +49-441-9722-420/282 · PGP: 0x9161A5C0 · http://www.offis.de/
-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.