/* 
 * create/destroy vcd context
 */
	struct vcd_context *	vcd_open(const char *name);
	int 			vcd_close(struct vcd_context *context);

Use these to open/close a VCD dumpfile.  As the library operates on
self-contained contexts, it is possible to write to multiple VCD files at once.


/*
 * scope manipulations..note that these (if present) are prepended
 * onto the names for add/alias
 */
	int		vcd_push_scope(struct vcd_context *context, 
					const char *name, int symtype);
	int		vcd_pop_scope(struct vcd_context *context);
	char *		vcd_query_scope(struct vcd_context *context);
	int		vcd_query_scope_depth(struct vcd_context *context);

These allow for Verilog variable scopes to be specified.  The value
symtype in vcd_push_scope() is one of VCD_SYM_MODULE, VCD_SYM_BEGIN,
VCD_SYM_TASK, VCD_SYM_FUNCTION, or VCD_SYM_FORK.  For vcd_query_scope(),
the pointer returned must be free()'d by the caller.

Nonzero/non-NULL return values indicate success.


/*
 * header maintenance
 */
	int		vcd_set_header_version_information(
				struct vcd_context *context, char *text);
	int		vcd_set_timebase(struct vcd_context *context, 
				int exponent);
	int		vcd_use_port_style_identifiers(
				struct vcd_context *context, int truth_value);

The text pointer in vcd_set_header_version_information() is used to
specify $version text in the VCD header.  

The exponent value for vcd_set_timebase() is one of VCD_TIMEBASE_S,
VCD_TIMEBASE_MS, VCD_TIMEBASE_US, VCD_TIMEBASE_NS, VCD_TIMEBASE_PS, or
VCD_TIMEBASE_FS.  Default is seconds.

vcd_use_port_style_identifiers() is used to specify either VCD (symbols)
when truth_value is zero or EVCD (<number) style identifiers when
truth_value is nonzero.


/*
 * symbol creation
 */
	int		vcd_symbol_add(struct vcd_context *context, 
				const char *name, int msb, int lsb, 
				int symtype);
	int		vcd_symbol_alias(struct vcd_context *context, 
				const char *name, int msb, int lsb, 
				int symtype, int old_vcdid);

vcd_symbol_add() returns a nonzero vcdid upon success.  The name value is
appended to any scope specified in vcd_push_scope() (if specified).  Note
that it is possible to mix hierarchical and "flat earth" (delimeted by
'.') style symbol definitions.  Allowable symbol types are VCD_SYM_EVENT,
VCD_SYM_PARAMETER, VCD_SYM_INTEGER, VCD_SYM_REAL, VCD_SYM_REG,
VCD_SYM_SUPPLY0, VCD_SYM_SUPPLY1, VCD_SYM_TRI, VCD_SYM_TRIAND,
VCD_SYM_TRIOR, VCD_SYM_TRIREG, VCD_SYM_TRI0, VCD_SYM_TRI1, VCD_SYM_WAND,
VCD_SYM_WIRE, VCD_SYM_WOR, and VCD_SYM_PORT.

vcd_symbol_alias() merely creates an alias to an existing vcdid.  It
returns nonzero upon success.  There is no checking performed to ensure
that the original symbol and its alias are of the same or sane types.  
However, width checking is performed.

For both functions, when msb and lsb are both -1, it indicates that the
symbol is unsubscripted.


/*
 * finalizer...once called, none of the above except for vcd_close() is useful
 */
	int		vcd_header_finalize(struct vcd_context *context);

When vcd_header_finalize() is called, no further header, scope, or symbol
manipulation function calls are possible for the given context.  This is
used to write the VCD header out to the VCD file.  This function returns
nonzero upon success.


/*
 * callable after vcd_header_finalize()
 */
	int		vcd_set_time(struct vcd_context *context, 
				long long timval);

This is used to update the "current simulation time" in the VCD file.

	int		vcd_emit_value_bit_string(struct vcd_context *context,
				int vcdid, const char *value);
	int		vcd_emit_value_integer(struct vcd_context *context, 
				int vcdid, int value);
	int		vcd_emit_value_port_string(struct vcd_context *context, 
				int vcdid, const char *value, 
				int str0, int str1);
	int		vcd_emit_value_real(struct vcd_context *context, 
				int vcdid, double value);

These four functions are used to dump value change data out to the VCD
file.  Note that vcd_emit_value_port_string() is only useful for symbols
defined as VCD_SYM_PORT.

	int		vcd_emit_arbitrary_string(struct vcd_context *context,
				char *string);
	int		vcd_emit_arbitrary_string_with_linefeed(
				struct vcd_context *context, char *string);

These two functions allow one to push arbitrary strings out to the VCD
file.  This is useful for extending VCD with nonstandard extensions.

	const char *	vcd_convert_vcdid(struct vcd_context *context, 
				int vcdid);

This returns the character string which represents a given vcdid.  This is
useful if extending VCD to handle your customized extensions and is used
in conjunction with the vcd_emit_arbitrary_string*() functions.

07apr02ajb
