Re: Version number macros

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.