# VCD file I/O

Initially there is one vcd defined called "vcd[0]" (or just "vcd"). You can create an additional vcds with "set hw vcd[0] new id" and configure it with "set hw vcd[id] ..." commands ("id" must be an integer).

## Output (event logging)

The vcd module creates VCD files compatible with industry standards and readable with open source tools such as gtkwave and sigrok/pulseview.

(N.B. sigrok/pulseview only supports VCD files containing events that are 1 bit wide only.)

1. Specify output file

                 0> set hw vcd[0] output "name.vcd"

   Alternatively specify no, or an empty, output file or use the "view" command and the simulator will attempt to invoke gtkwave directly.

                 0> set hw vcd[0] output ""
                 0> set hw vcd[0] view

2. Add locations to dump

                 0> set hw vcd[0] add pc_odr
                 0> set hw vcd[0] add rom[0x500a].3

   You can set the name of the module if you want (set hw vcd[0] module name), it will be ucsim_vcd_0 by default.
3. Check the configuration

                 0> info hw vcd[0]
                 vcd[0] value change dump
                   Module:      ucsim_vcd_0
                   Started:    no
                   Paused:     no
                   File:       name.vcd
                   Mode:       output
                   Time scale: auto set on start
                   Start time: 0.000000000000000 s
                   Last event: 0.000000000000000 s
                   Simul time: 0.000000000000000 s
                   Variables:
                     Address           Symbol
                     rom[0x0500a][7:0] pc_odr
                     rom[0x0500a].3

4. Start recording

                 0> set hw vcd[0] start

5. Run the program
6. You can pause/resume recording

                 0> set hw vcd[0] pause
                 0> set hw vcd[0] restart

   While the vcd is paused no changes are recorded in the output and values will show as unknown when the VCD is viewed by something such as gtkwave.

   If you set pausetime then the time recorded as unknown will be limited to the specified time and time beyond that will simply not exist as far as the VCD is concerned. This may be used to compress pause gaps in the VCD for the sake of viewers which are not able to do this themselves.

                 0> set hw vcd[0] pausetime 300 ns

7. Stop recording and close the VCD file

                 0> set hw vcd[0] stop

## Input (event replay)

1. Define any variables used by the input file

                 0> var loc1 rom[0x5001]

2. Specify input file

                 0> set hw vcd[0] input "name.vcd"

3. Adjust the base time
   By default time 0 in the VCD file corresponds to the simulator time when the vcd is started. You can adjust this by setting the start time of the vcd. For instance, to move the VCD events 750 ns into the future you would use

                 0> set hw vcd[0] starttime 750 ns

   This can be done at any time, regardless of whether the vcd is started, paused or even part way through.

   Note that the argument to starttime is the amount to add or subtract from the current start time not an absolute time.

4. Start the replay

                 0> set hw vcd[0] start

5. Check the configuration
   N.B. The VCD file's header is only parsed when the vcd is started. Until then the configuration details are unknown.

                 0> info hw vcd[0]
                 vcd[0] value change dump
                   Module:      ucsim_vcd_0
                   Started:    YES
                   Paused:     no
                   File:       name.vcd
                   Mode:       input
                   Break:      disabled
                   Time scale: 1 ns
                   Start time: 0.000000000000000 s
                   Next event: 0.000000000000000 s
                   Simul time: 0.000000000000000 s
                   Variables:
                     Address           Symbol
                     rom[0x0500a]      pc_odr
                     rom[0x0500a].3

6. Run the program
7. Pause/resume replay

                 0> set hw vcd[0] pause
                 0> set hw vcd[0] restart

   While the replay is paused any cycles used by the simulator are ignored by vcd and do NOT advance you towards the next event.

8. Toggle the break flag as required

                 0> set hw vcd[0] break

   The break flag causes vcd to generate a break each an event is replayed giving you the opportunity to check that your program responds to it correctly.

9. Stop the replay and close the VCD file

                 0> set hw vcd[0] stop