3. Terminology and conventions used in this standard

3.1 Terminology

3.1.1 Shall, should, may, can

See 1.3 for the usage conventions regarding the words shall, should, may, and can.

3.1.2 Application, implementation

The word application is used to mean a C++ program, written by an end user, that uses the SystemC Configuration class library; that is, uses classes, functions, or macros defined in this standard.

The word implementation is used to mean any specific implementation of the SystemC Configuration class library as defined in this standard, only the public interface of which need be exposed to the application.

3.1.3 Call, called from, derived from

The term call is taken to mean call directly or indirectly. Call indirectly means call an intermediate function that in turn calls the function in question, where the chain of function calls may be extended indefinitely.

Similarly, called from means called from directly or indirectly.

Except where explicitly qualified, the term derived from is taken to mean derived directly or indirectly from. Derived indirectly from means derived from one or more intermediate base classes.

3.1.4 Specific technical terms

The specific technical terms as defined in IEEE Std 1666-2011 generally apply for the SystemC Configuration standard. The term interface is an exception, used herein to indicate a generic software interface (or application programming interface) which does not require inheritance from sc_interface.

In addition, the following technical terms are defined:

A parameter is a class derived from the class cci::cci_param_if.

A broker is a class derived from the class cci::cci_broker_if.

3.2 Syntactical conventions

3.2.1 Implementation-defined

The italicized term implementation-defined is used where part of a C++ definition is omitted from this standard. In such cases, an implementation shall provide an appropriate definition that honors the semantics defined in this standard.

3.2.2 Ellipsis (…)

An ellipsis, which consists of three consecutive dots (…), is used to indicate that irrelevant or repetitive parts of a C++ code listing or example have been omitted for brevity.

3.2.3 Class names

Class names italicized and annotated with a superscript dagger (†) should not be used explicitly within an application. Moreover, an application shall not create an object of such a class. It is strongly recommended that the given class name be used in an implementation. However, an implementation may substitute an alternative class name in place of every occurrence of a particular daggered class name.

Only the class name is considered here. Whether any part of the definition of the class is implementation-defined is a separate issue.

The class names are the following:

• cci_value_cref^†
• cci_value_ref^†
• cci_value_list_cref^†
• cci_value_list_ref^†
• cci_value_map_cref^†
• *cci_value_map_ref^†
• cci_value_string_cref^†
• cci_value_string_ref^†

Public typedefs are provided for these classes to avoid the need to refer to them directly.

3.2.4 Configuration, Control and Inspection (CCI) naming patterns

The CCI interoperability interfaces are denoted with the prefix cci_ for classes, functions, global definitions and variables, and with the prefix CCI_ for macros and enumeration values.

An application shall not make use of these prefixes when defining classes, functions, global definitions, global variables, macros, and enumerations.

Class names ending in _if, such as cci_broker_if and cci_param_if, declare abstract C++ classes providing key interfaces which must be inherited and fully satisfied by every implementation of this standard.

3.3 Typographical conventions

The following typographical conventions are used in this standard:

1. The italic font is used for cross references to terms defined in 3.1, 3.2 and Annex B.
   For example: “Each parameter is registered during construction with a single broker.”

2. The bold constant-width (Courier) font is used for all reserved keywords of the SystemC Configuration standard as defined in namespaces, macros, constants, enum literals, classes, member functions, data members and types.
   For example: “Actual parameters are created as instances of cci_param_typed, which in concert with its base class cci_param_untyped implements the cci_param_if interface.”

3. The constant-width font is used for all other code; primarily:
   • SystemC Configuration class definitions including member functions, data members and data types
   • SystemC Configuration examples when the exact usage is depicted. For example: “cci_param<int> p("param", 17, "Demonstration parameter");“

The conventions listed herein are for ease of reading only. Editorial inconsistencies in the use of typography are unintentional and have no normative meaning in this standard.

3.4 Semantic conventions

3.4.1 Class definitions and the inheritance hierarchy

An implementation may differ from this standard in that an implementation may introduce additional base classes, class members, and friends to the classes defined in this standard. An implementation may modify the inheritance hierarchy by moving class members defined by this standard into base classes not defined by this standard. Such additions and modifications may be made as necessary in order to implement the semantics defined by this standard or in order to introduce additional functionality not defined by this standard.

3.4.2 Function definitions and side-effects

This standard explicitly defines the semantics of the C++ functions in the SystemC Configuration class library. Such functions shall not have any side-effects that would contradict the behavior explicitly mandated by this standard. In general, the reader should assume the common-sense rule that if it is explicitly stated that a function shall perform action A, that function shall not perform any action other than A, either directly or by calling another function defined in this standard. However, a function should perform any tasks necessary for resource management, performance optimization, or to support any ancillary features of an implementation. As an example of resource management, it is assumed that a destructor will perform any tasks necessary to release the resources allocated by the corresponding constructor.

3.4.3 Exceptions

Other than destructors and swap (see 5.5.2.3) or as explicitly noted in documentation, API functions should be presumed to have the potential to throw exceptions, either as the SC_THROW action from the sc_report_handler::report diagnostic or an explicit throw. Callback functions are also permitted to throw. Implementations shall ensure that class invariants are preserved in the case of exceptions from all sources. The utility function cci_handle_exception decodes CCI library exceptions using cci_param_failure enum values as described in 5.8.

3.4.4 Functions whose return type is a reference or a pointer

An object returned from a function by pointer or by reference is said to be valid during any period in which the object is not deleted and the value or behavior of the object remains accessible to the application. If an application refers to the returned object after it ceases to be valid, the behavior of the implementation shall be undefined.

3.4.5 Functions that return *this or a pass-by-reference argument

In certain cases, the object returned is either an object (*this) returned by reference from its own member function (for example, the assignment operators), or it is an object that was passed by reference as an argument to the function being called. In either case, the function call itself places no additional obligations on the implementation concerning the lifetime and validity of the object following return from the function call.

3.4.6 Functions that return const char*

Certain functions have the return type const char* indicating they return a pointer to a null-terminated character string. Such strings shall remain valid until returning from sc_main.

3.4.7 Non-compliant applications and errors

In the case where an application fails to meet an obligation imposed by this standard, the behavior of the implementation shall be undefined in general. When this results in the violation of a diagnosable rule of the C++ standard, the C++ implementation will issue a diagnostic message in conformance with the C++ standard.

When this standard explicitly states that the failure of an application to meet a specific obligation is an error or a warning, the implementation shall generate a diagnostic message by calling an appropriate function in cci_report_handler; for common CCI error types the specific diagnostics such as set_param_failed, and for other errors or warnings sc_report_handler::report. In the case of an error, the implementation shall call report with a severity of SC_ERROR. In the case of a warning, the implementation shall call report with a severity of SC_WARNING. See 5.8 for details of cci_report_handler.

An implementation or an application may choose to suppress run-time error checking and diagnostic messages because of considerations of efficiency or practicality. For example, an application may call member function set_actions of class sc_report_handler to take no action for certain categories of report. An application that fails to meet the obligations imposed by this standard remains in error.

There are cases where this standard states explicitly that a certain behavior or result is undefined. This standard places no obligations on the implementation in such a circumstance. In particular, such a circumstance may or may not result in an error or a warning.

3.4.8 Notes and examples

Notes appear at the end of certain subclauses, designated by the uppercase word NOTE. Notes often describe the consequences of rules defined elsewhere in this standard. Certain subclauses include examples consisting of fragments of C++ source code. Such notes and examples are informative to help the reader but are not an official part of this standard.