Contents:
---------

1.> Disclaimer
2.> Application Notes
3.> Usage Notes
4.> Future Wish list, upgrades etc.

1.> Disclaimer
===============
        This Application comes with *NO WARRANTY* from the Author(s) and/or 
Maintainer(s). It is just a piece of useful C-code that we thought will be
useful to the NC users across the globe. Please feel free to send in your comments to the maintainer 
Srinivasan Venkataramanan @ srinivasan_vlsi@yahoo.co.in.NO_SPAM 
(Remove NO_SPAM).

  I sincerely thank Martyn Pollard of Cadence for helping me to get started on this valuable Application Note. I haven't done much improvements yet on this, but will try and do as and when possible. Please do send in your inputs/comments.


2.> Application Notes
=====================
This application implements a "spy" function as a foreign procedure in 
nc-vhdl.

usage: 
  my_spy_proc(":some:undriven:destination:signal",":then:some:source:signal");

  the application will setup a process which updates the value of the
  destination signal (first parameter) with the value of the source
  signal (second parameter).

  - both parameters are strings, and therefore must be enclosed in double
    quotes (").
  - hierarchy separator is the colon (:) and/or slash (/). If some other separator is required, please contact the maintainer Srinivasan Venkataramanan @ 
srinivasan_vlsi@yahoo.co.in.NO_SPAM (Remove NO_SPAM)

  - on either parameter, if the initial colon (:) is omitted, that parameter
    is assumed to be local to the existing scope.
  - the path may not include or traverse verilog.  if the design is mixed
    language, but there is no verilog in either path, this application will
    behave correctly.
  - escaped identifiers are not supported.
  - source and destination signals must be of same type and range.
  - the destination signal must be otherwise undriven.

the procedure should be declared as follows:

package my_spy is
  procedure my_spy_proc (
    destination : IN string;
    source      : IN string
  );
  attribute foreign of my_spy_proc : procedure is "spylib:spy_proc";
end;

it is a good idea to declare a package body which will report an error if
the foreign c library is not being used properly:

package body my_spy is
  procedure my_spy_proc (
    destination : IN string;
    source      : IN string
  ) is
  begin
    assert false
    report "ERROR: foreign subprogram my_spy_proc was not called"
    severity error;
  end;

3.> Usgae Notes
================
  A simple example is provided as a tar file, just download the tarred, gzipped file and do:

  a.> gunzip <file.tar.gz>
  b.> tar xvf <file.tar>
  c.> cd nc_my_spy
  d.> Please take a look at the simple run.ksh script, you may need to modify the CDS_INST_DIR variable etc.

  e.> If you are using Sun Solaris it should work just fine, other OS may need some fine tuning (like setting the proper ARCH variable etc.).

  f.> The example VHDL file example_spy.vhd shows two ways of "accessing" internal signals using two different hierarchy separators such as slash (/) and colon (:).

  g.> I am using gcc as C-compiler - you may wish to change it to cc, if so edit the Makefile provided.

4.> Future Wish list, upgrades etc.
===================================

  There are a few critical "improvements" that I personally feel are important in this valuable application such as

  a.> Range Checking, 
  b.> Type Checking etc.
  
  
Please do mail me @ srinivasan_vlsi@yahoo.co.in.NO_SPAM (Remove NO_SPAM) if you have any clever ideas/suggestions on top of these. Also any "upgrades" themselves are most Welcome :-) Since I am doing this in my free time I can't promise any due date for any of the above features.