[Artwork] / [QisMLib]

QisMLog

QisMLib systemwide logging API

QisMLog C++ API (qismlog.h)

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>

• The topmost base class is version 1 (V1 implied)

• The cast returns NULL if a version number is not recognized/implemented

virtual void* QisMLogVector_cast(const int version) = 0;
virtual const void* QisMLogVector_cast(const int version) const = 0;
virtual int QisMLogVector_latest_version() const = 0;

Grid

Get the file grid (in terms of file units)

xxxxxxxxxx
virtual double Grid() const = 0;

Begin_cell

Begin a new cell definition for cellname

xxxxxxxxxx
virtual void Begin_cell(const char* cellname) = 0;

Boundary

BoundaryUU

Add a boundary to the vector log

• xy is the list of x,y co-ordinates in database-units (DBU) or user-units (UU)

  • A DBU of 1 is equivalent to the file grid in meters. A UU of 1.0 is equivalent to the file units in meters

• nv is the number of vertices (x,y pairs) in xy. Num. values in xy = nv*2

• l, d are the layer and datatype numbers respectively

• dx and dy are the offsets to the applied to xy in DBU or UU

• This call is thread-safe (protected by a mutex)

xxxxxxxxxx
virtual void Boundary(
  const int* xy, const int nv, const unsigned short l, const unsigned short d,
  const int dx = 0, const int dy = 0
  ) = 0;
virtual void BoundaryUU(
  const double* xy, const int nv, const unsigned short l, const unsigned short d,
  const double dx = 0.0, const double dy = 0.0
  ) = 0;

Path

PathUU

Add a path to the vector log

• xy is the list of x,y co-ordinates in database-units (DBU) or user-units (UU)

  • A DBU of 1 is equivalent to the file grid in meters. A UU of 1.0 is equivalent to the file units in meters

• nv is the number of vertices (x,y pairs) in xy. Num. values in xy = nv*2

• type can be R for round-ended, F for flush-ended or H for half-width extended paths

• width is the path width in DBU or UU

• l, d are the layer and datatype numbers respectively

• dx and dy are the offsets to the applied to xy in DBU or UU

• This call is thread-safe (protected by a mutex)

xxxxxxxxxx
virtual void Path(
  const int* xy, const int nv, const int width, const char type, const unsigned short l, const unsigned short d,
  const int dx = 0, const int dy = 0
  ) = 0;
virtual void PathUU(
  const double* xy, const int nv, const double width, const char type, const unsigned short l, const unsigned short d,
  const double dx = 0.0, const double dy = 0.0
  ) = 0;

Text

Add a text to the vector log

• text is the text string

• x and y represent the insertion point in DBU

• l, d are the layer and datatype numbers respectively

xxxxxxxxxx
virtual void Text(const char* text, const int x, const int y, const unsigned short l, const unsigned short d) = 0;

Sref

Add a single reference to a cell

• refname is the name of the cell to be referenced

• x and y represent the insertion point DBU

• scale, angle (degrees) and flip_y represent any scaling, rotation and mirroring respectively

xxxxxxxxxx
virtual void Sref(const char* refname, const int x, const int y, const double scale, const double angle, const bool flip_y) = 0;

Aref

Add an arrayed reference to a cell

• refname is the name of the cell to be referenced

• x and y represent the insertion point DBU

• col and row are the number of columns (nx) and rows (ny) respectively

• col_dx, col_dy, row_dx and row_dy are the column and row offsets (pitches) in DBU along X and Y

• scale, angle (degrees) and flip_y represent any scaling, rotation and mirroring respectively

xxxxxxxxxx
virtual void Aref(
  const char* refname, const int x, const int y, const int col, const int rows, 
  const int col_dx, const int col_dy, const int row_dx, const int row_dy, 
  const double scale, const double angle, const bool flip_y
  ) = 0;

End_cell

End the current cell definition

xxxxxxxxxx
virtual void End_cell() = 0;

QisMLogChannels

Represents a manager of log channels

• A channel is a logical grouping of log messages usually associated with a specific module or a component

• Channels can be registered (activated) via the environment variable ACS_VERBOSE_CH to a comma-separated list of names

• A log message directed to a channel is only sent if that particular channel is in the list of channels

xxxxxxxxxx
class QisMLogChannels { ... };

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>

• The topmost base class is version 1 (V1 implied)

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMLogChannels_cast(const int version) = 0;
virtual const void* QisMLogChannels_cast(const int version) const = 0;
virtual int QisMLogChannels_latest_version() const = 0;

Get_channel_onoff

Returns true if the specified channel is active and ON

xxxxxxxxxx
virtual bool Get_channel_onoff(const char* channel) const = 0;

Channel_msg

Send a message to a specific channel (cannot be NULL or empty)

• fmt is the format string (printf)

xxxxxxxxxx
virtual void Channel_msg(const char* channel, const char* fmt, ...) = 0;

Channel_str

Send a message to a specific channel (cannot be NULL or empty)

xxxxxxxxxx
virtual void Channel_str(const char* channel, const char* str) = 0;

QisMLogCb

Client interface to receive log messages as callbacks (see QISM_ARG_LOGCB

xxxxxxxxxx
class QisMLogCb { ... };

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>

• The topmost base class is version 1 (V1 implied)

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMLogCb_cast(const int version) = 0;
virtual const void* QisMLogCb_cast(const int version) const = 0;
virtual int QisMLogCb_latest_version() const = 0;

On_qismlog_msg

Callback for a single log message in response to QisMLog::Log_msg or QisMLog::Verbose_msg

xxxxxxxxxx
virtual int On_qismlog_msg(const char* msg, const bool infoOrWarning) { 
  return 0; 
}

QisMLog

API to write log messages (to stdout/stderr or a log file) throughout the QisMLib system.

• This API can be used internally by QisMLib components, as well as externally by QisMLib extensions and clients.

• In order for messages to appear on the console or in a file, the appropriate options QISM_ARG_NEWLOG, QISM_ARG_APNDLOG or QISM_ARG_STDLOG must be specified to ::QisMLib_initialize_once

• This API can be accessed via the QisMLib::Get_extension_api method in QisMLib 3.10+

xxxxxxxxxx
class QisMLog: public QisMExtensionAPI { ... };

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived)

• Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>

• The topmost base class is version 1 (V1 implied)

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMLog_cast(const int version) = 0;
virtual const void* QisMLog_cast(const int version) const = 0;
virtual int QisMLog_latest_version() const = 0;

Log_msg

Write a message to screen (if enabled) and log file (if enabled) (multi-thread-safe)

• err : if true, write to stderr. Otherwise, write to stdout

• fmt : Format of the message as used by printf class of functions

xxxxxxxxxx
virtual void Log_msg(const bool err, const char* fmt, ...) = 0;

Screen_msg

Write a message only to screen (if enabled) (multi-thread-safe)

• err : if true, write to stderr. Otherwise, write to stdout

• fmt : Format of the message as used by printf class of functions

xxxxxxxxxx
virtual void Screen_msg(const bool err, const char* fmt, ...) = 0;

Verbose_msg

Write a message to screen (if enabled) and log file (if enabled) only if the environment variable ACS_VERBOSE is set to ON (multi-thread-safe)

• err : if true, write to stderr. Otherwise, write to stdout

• fmt : Format of the message as used by printf class of functions

xxxxxxxxxx
virtual void Verbose_msg(const bool err, const char* fmt, ...) = 0;

QisMLogV2

xxxxxxxxxx
class QisMLogV2: public QisMLog { ... };

Unlink_log

Un-link/release the log. Any subsequent log messages will be ignored

xxxxxxxxxx
virtual void Unlink_log() = 0;

Relink_log_file_path

Relink_log_file_ptr

Relink_log_client

Relink_stdout

Re-link the log with a file,file handle,client or stdout

xxxxxxxxxx
virtual bool Relink_log_file_path(const char* file_path) = 0;
virtual void Relink_log_file_ptr(FILE* file_ptr) = 0;
virtual void Relink_log_client(QisMLogCb* handle) = 0;
virtual void Relink_stdout(const bool onoff) = 0;

Set_verbose_level

Verbose_msg_level

Write a log message if the verbose level is >= specified level

• ACS_VERBOSE can be set to the following:

  • ON (verbose level = 1)

  • OFF (verbose level = 0) (default)

  • ALL (verbose level = 32768)

  • {level} where 0 <= level < 32768

• The verbose level can also be changed in code using Set_verbose_level

xxxxxxxxxx
virtual void Set_verbose_level(const int level) = 0;
virtual void Verbose_msg_level(const bool err, const int level, const char* fmt, ...) = 0;

Log_str

Screen_str

Verbose_str

Write a pre-formatted string (msg) to the log

xxxxxxxxxx
virtual void Log_str(const bool err, const char* msg) = 0;
virtual void Screen_str(const bool err, const char* msg) = 0;
virtual void Verbose_str(const bool err, const int level, const char* msg) = 0;

QisMLogV3

xxxxxxxxxx
class QisMLogV3: public QisMLogV2 { ... };

Channels

Get access to channel logs (if enabled by the env. var ACS_VERBOSE_CH)

xxxxxxxxxx
virtual QisMLogChannels* Channels() = 0;
virtual const QisMLogChannels* Channels() const = 0;

QisMLogV4

xxxxxxxxxx
class QisMLogV4: public QisMLogV3 { ... };

Open_vector_log

Close_vector_log

Create/Destroy a log file (GDSII) to write vectors

• name is the log directory + name. Extension .gds is automatically added

• units_m and grid_m are the units and grid in meters

• On success, returns a handle to the log writer. It MUST be eventually closed to avoid resource leak

xxxxxxxxxx
virtual QisMLogVector* Open_vector_log(const char* name, const double units_m, const double grid_m) = 0;
virtual void Close_vector_log(QisMLogVector* handle) = 0;

QisMLog_debug_msg

Print messages to stderr ONLY from those compilation units where ACS_ASSERT_ON is defined

• This should be used for debugging and diagnostic messages that are enabled/disabled at compile time

• This should be disabled in production binaries

xxxxxxxxxx
#ifdef ACS_DEBUG_ON
#define QisMLog_debug_msg(qismlog, fmt, ...) if(qismlog && fmt && fmt[0]) qismlog->Log_msg(false, "[dbg] " fmt, __VA_ARGS__)
#else
#define QisMLog_debug_msg
#endif