Snapshots
This training page describes creating workspace Snapshots, listing Snapshots, and recreating the original workspace state by loading Snapshots.
Snapshot Overview
Snapshots can be understood as server side captures (snapshots) of workspaces. Snapshots capture modified workspace states, including resources that have been moved versus their expected release version, and files that have changed. Snapshots are also capable of capturing a workspace that exactly matches a release.
The format of a snapshot name is:
LIBRARY.IP@VERSION#SNAPSHOT.LINE eg tutorial.padring@3#5.TRUNK
The snapshot is associated with the top level IPV in the workspace at the time the snapshot is created. 'tutorial.padring@3#5.TRUNK' indicates the fifth snapshot of the third release of the padring.
Snapshots can be loaded into a new workspace, which will be fully functional and just like the workspace the snapshot was originally captured from.
Snapshots allow users to save the state of their workspaces for later retrieval, or share their workspace state with other users. Snapshots can be used for verification/simulation runs, workspaces can be built from them and sims run, prior to making a full release. They can be used to provide test cases to IP providers, and for technical support.
Full details on Snapshots is available on the Capturing the Workspace State with Snapshots page in the User Guide.
Creating a Snapshot
Build a workspace, make some modifications at the file and resource levels, and use the 'pi snap add' command to create a snapshot of the workspace.
> pi ip load tutorial.tutorial Loading IPV 'tutorial.tutorial@5.TRUNK' into Workspace '/tmp/tutorial.tutorial'. INFO:Waiting for 34 PiCache jobs ... INFO:Waiting for 26 PiCache jobs ... INFO:Waiting for 15 PiCache jobs ... INFO:Waiting for 7 PiCache jobs ... INFO:Waiting for 3 PiCache jobs ... INFO:Waiting for 1 PiCache job ... ┌────────────────────────┬───────────────────┬───────────┬──────────────────────┬──────────────────────────┐ │ NAME │ VERSION │ MODE │ RELATIVE PATH │ CONFLICTS │ ╞════════════════════════╪═══════════════════╪═══════════╪══════════════════════╪══════════════════════════╡ │ tutorial.tutorial │ 5.TRUNK │ Refer │ blocks/tutorial │ │ │ tutorial.CADenv │ GOLD.TRUNK [@1] │ Refer │ blocks/CADenv │ │ │ tutorial.MS90G │ 1.TRUNK │ Refer │ blocks/MS90G │ │ │ tutorial.acells_tsmc18 │ 1.TRUNK │ Refer │ blocks/acells_tsmc18 │ │ │ tutorial.adc │ HEAD.TRUNK [@2] │ Refer │ blocks/adc │ │ │ tutorial.aes512 │ 1.TRUNK │ Refer │ blocks/aes512 │ │ │ tutorial.analog_top │ HEAD.TRUNK [@2] │ Refer │ blocks/analog_top │ │ │ tutorial.bist_sram │ 1.TRUNK │ Refer │ blocks/bist_sram │ │ │ tutorial.clk_mux │ 1.TRUNK │ Refer │ blocks/clk_mux │ │ │ tutorial.clkgen │ HEAD.TRUNK [@1] │ Refer │ blocks/clkgen │ │ │ tutorial.cpu │ LATEST.TRUNK [@2] │ Refer │ blocks/cpu │ │ │ tutorial.dac │ HEAD.TRUNK [@0] │ Container │ │ │ │ tutorial.dbuf │ 1.TRUNK │ Refer │ blocks/dbuf │ │ │ tutorial.digital_top │ 1.TRUNK │ Refer │ blocks/digital_top │ │ │ tutorial.events_if │ 1.TRUNK │ Refer │ blocks/events_if │ │ │ tutorial.flash │ 1.TRUNK │ Refer │ blocks/flash │ │ │ tutorial.flash_if │ 1.TRUNK │ Refer │ blocks/flash_if │ │ │ tutorial.gen_dig │ LATEST.TRUNK [@2] │ Refer │ blocks/gen_dig │ tutorial.gen_dig@1.TRUNK │ │ tutorial.interface │ 1.TRUNK │ Refer │ blocks/interface │ │ │ tutorial.intf_ana │ HEAD.TRUNK [@2] │ Refer │ blocks/intf_ana │ │ │ tutorial.io5v │ 1.TRUNK │ Refer │ blocks/io5v │ │ │ tutorial.io_tsmc18 │ 1.TRUNK │ Refer │ blocks/io_tsmc18 │ │ │ tutorial.laysc_tsmc18 │ 1.TRUNK │ Refer │ blocks/laysc_tsmc18 │ │ │ tutorial.padring │ 1.TRUNK │ Refer │ blocks/padring │ │ │ tutorial.proj_tech │ 1.TRUNK │ Refer │ blocks/proj_tech │ │ │ tutorial.pwr_mgmt_ana │ HEAD.TRUNK [@1] │ Refer │ blocks/pwr_mgmt_ana │ │ │ tutorial.rx_channel │ 1.TRUNK │ Refer │ blocks/rx_channel │ │ │ tutorial.rxtx │ 1.TRUNK │ Refer │ blocks/rxtx │ │ │ tutorial.stup_ana │ HEAD.TRUNK [@1] │ Refer │ blocks/stup_ana │ │ │ tutorial.sys_bus │ 1.TRUNK │ Refer │ blocks/sys_bus │ │ │ tutorial.t0 │ 1.TRUNK │ Refer │ blocks/t0 │ │ │ tutorial.t1 │ 1.TRUNK │ Refer │ blocks/t1 │ │ │ tutorial.timers │ 1.TRUNK │ Refer │ blocks/timers │ │ │ tutorial.trc │ HEAD.TRUNK [@1] │ Refer │ blocks/trc │ │ │ tutorial.verif_config │ 1.TRUNK │ Refer │ blocks/verif_config │ │ └────────────────────────┴───────────────────┴───────────┴──────────────────────┴──────────────────────────┘ > cd tutorial.tutorial/ > pi ip local padring Switching 'tutorial.padring@1.TRUNK' to local mode. Successfully switched 'tutorial.padring@1.TRUNK' to local mode. > cd blocks/padring/hw_code/test/ > pi up padring Updating Workspace. For large IP this could take a while. ┌──────────────────┬─────────────┬─────────────┬───────┬────────────────┐ │ NAME │ OLD VERSION │ NEW VERSION │ MODE │ PATH │ ╞══════════════════╪═════════════╪═════════════╪═══════╪════════════════╡ │ tutorial.padring │ 1.TRUNK │ 6.TRUNK │ Local │ blocks/padring │ └──────────────────┴─────────────┴─────────────┴───────┴────────────────┘ > p4 edit test.v //mdx_test/tutorial/padring/TRUNK/hw_code/test/test.v#3 - opened for edit > echo test >> test.v > p4 submit -d test Submitting change 7. Locking 1 files ... edit //mdx_test/tutorial/padring/TRUNK/hw_code/test/test.v#4 Change 7 submitted. > pi snap add -d 'new tutorial snapshot' Successfully created Snapshot 'tutorial.tutorial@5#1.TRUNK'.
Listing a Snapshot
We can now list the snapshot:
> pi snap list tutorial.tutorial ┌─────────────────────────────┬───────────────────────────┬────────────────────────┬───────────────────────────────┐ │ SNAPSHOT │ TOP-IPV │ PARENT │ DATE │ ╞═════════════════════════════╪═══════════════════════════╪════════════════════════╪═══════════════════════════════╡ │ tutorial.tutorial@5#1.TRUNK │ tutorial.tutorial@5.TRUNK │ /tmp/tutorial.tutorial │ 2020-06-23 16:42:49 -0400 EDT │ └─────────────────────────────┴───────────────────────────┴────────────────────────┴───────────────────────────────┘ Found 1 matching object(s).
To see what is captured in the snapshot we supply the –contents flag:
> pi snap list tutorial.tutorial --contents
Snapshot tutorial.tutorial@5#1.TRUNK:
Description - new tutorial snapshot
Top IPV - tutorial.tutorial@5.TRUNK
Resources - tutorial.CADenv@GOLD.TRUNK [@1]
tutorial.MS90G@1.TRUNK
tutorial.acells_tsmc18@1.TRUNK
tutorial.adc@HEAD.TRUNK [@2]
tutorial.aes512@1.TRUNK
tutorial.analog_top@HEAD.TRUNK [@2]
tutorial.bist_sram@1.TRUNK
tutorial.clk_mux@1.TRUNK
tutorial.clkgen@HEAD.TRUNK [@1]
tutorial.cpu@LATEST.TRUNK [@2]
tutorial.dac@HEAD.TRUNK [@0]
tutorial.dbuf@1.TRUNK
tutorial.digital_top@1.TRUNK
tutorial.events_if@1.TRUNK
tutorial.flash@1.TRUNK
tutorial.flash_if@1.TRUNK
tutorial.gen_dig@LATEST.TRUNK [@2]
tutorial.interface@1.TRUNK
tutorial.intf_ana@HEAD.TRUNK [@2]
tutorial.io5v@1.TRUNK
tutorial.io_tsmc18@1.TRUNK
tutorial.laysc_tsmc18@1.TRUNK
tutorial.padring@6.TRUNK
tutorial.proj_tech@1.TRUNK
tutorial.pwr_mgmt_ana@HEAD.TRUNK [@1]
tutorial.rx_channel@1.TRUNK
tutorial.rxtx@1.TRUNK
tutorial.stup_ana@HEAD.TRUNK [@1]
tutorial.sys_bus@1.TRUNK
tutorial.t0@1.TRUNK
tutorial.t1@1.TRUNK
tutorial.timers@1.TRUNK
tutorial.trc@HEAD.TRUNK [@1]
tutorial.verif_config@1.TRUNK
Owner - admin
Created on - 2020-06-23 16:42:49 -0400 EDT
Workspace - /tmp/tutorial.tutorial
Changed resources in Snapshot:
┌───────────────────────┬─────────┬───┬──────────────┐
│ RESOURCES │ PARENTS │ │ SNAPSHOT │
╞═══════════════════════╪═════════╪═══╪══════════════╡
│ tutorial.CADenv │ 1.TRUNK │ ← │ GOLD.TRUNK │
│ tutorial.adc │ 2.TRUNK │ ← │ HEAD.TRUNK │
│ tutorial.analog_top │ 2.TRUNK │ ← │ HEAD.TRUNK │
│ tutorial.clkgen │ 1.TRUNK │ ← │ HEAD.TRUNK │
│ tutorial.cpu │ 2.TRUNK │ ← │ LATEST.TRUNK │
│ tutorial.dac │ 0.TRUNK │ ← │ HEAD.TRUNK │
│ tutorial.gen_dig │ 1.TRUNK │ → │ LATEST.TRUNK │
│ tutorial.gen_dig │ 2.TRUNK │ - │ │
│ tutorial.intf_ana │ 2.TRUNK │ ← │ HEAD.TRUNK │
│ tutorial.padring │ 1.TRUNK │ → │ 6.TRUNK │
│ tutorial.pwr_mgmt_ana │ 1.TRUNK │ ← │ HEAD.TRUNK │
│ tutorial.stup_ana │ 1.TRUNK │ ← │ HEAD.TRUNK │
│ tutorial.trc │ 1.TRUNK │ ← │ HEAD.TRUNK │
└───────────────────────┴─────────┴───┴──────────────┘
Changed files in Snapshot resources:
┌──────────────────────────┬──────────┬───┬──────────┐
│ FILES │ RESOURCE │ │ SNAPSHOT │
╞══════════════════════════╪══════════╪═══╪══════════╡
│ tutorial.padring@6.TRUNK │ │ │ │
│ hw_code/test/test.v │ 1 │ → │ 4 │
└──────────────────────────┴──────────┴───┴──────────┘
Found 1 matching object(s).
Snapshots capture the changes versus the release associated with the snapshot. From the 'pi snap list --contents' output we can see from the 'Changed resources in Snapshot' section we see both the padring resource has been moved from @1 to @6 and a list of all the aliased resources in the workspace at the time the snapshot was created. Snapshots will restore aliased resources to the underlying fixed release (but still at the alias), this enables a true reproduction of the original workspace state.
The modified file is likewise noted in the 'Changed files in Snapshot resources' output.
Loading a Snapshot
To create a workspace out of one of the available snapshots, change to the directory you want to make the workspace in and run the pi snapshot load command:
> pi snap load tutorial.tutorial@5#1.TRUNK ws_snap Loading Snapshot 'tutorial.tutorial@5#1.TRUNK' into Workspace '/tmp/ws_snap'. Ignoring --local for 'tutorial.dac@HEAD.TRUNK' because Container IP can't be local. ┌────────────────────────┬───────────────────┬───────────┬──────────────────────┐ │ NAME │ VERSION │ MODE │ RELATIVE PATH │ ╞════════════════════════╪═══════════════════╪═══════════╪══════════════════════╡ │ tutorial.tutorial │ 5.TRUNK │ Refer │ blocks/tutorial │ │ tutorial.CADenv │ GOLD.TRUNK [@1] │ Refer │ blocks/CADenv │ │ tutorial.MS90G │ 1.TRUNK │ Refer │ blocks/MS90G │ │ tutorial.acells_tsmc18 │ 1.TRUNK │ Refer │ blocks/acells_tsmc18 │ │ tutorial.adc │ HEAD.TRUNK [@2] │ Local │ blocks/adc │ │ tutorial.aes512 │ 1.TRUNK │ Refer │ blocks/aes512 │ │ tutorial.analog_top │ HEAD.TRUNK [@2] │ Local │ blocks/analog_top │ │ tutorial.bist_sram │ 1.TRUNK │ Refer │ blocks/bist_sram │ │ tutorial.clk_mux │ 1.TRUNK │ Refer │ blocks/clk_mux │ │ tutorial.clkgen │ HEAD.TRUNK [@1] │ Local │ blocks/clkgen │ │ tutorial.cpu │ LATEST.TRUNK [@2] │ Refer │ blocks/cpu │ │ tutorial.dac │ HEAD.TRUNK [@0] │ Container │ │ │ tutorial.dbuf │ 1.TRUNK │ Refer │ blocks/dbuf │ │ tutorial.digital_top │ 1.TRUNK │ Refer │ blocks/digital_top │ │ tutorial.events_if │ 1.TRUNK │ Refer │ blocks/events_if │ │ tutorial.flash │ 1.TRUNK │ Refer │ blocks/flash │ │ tutorial.flash_if │ 1.TRUNK │ Refer │ blocks/flash_if │ │ tutorial.gen_dig │ LATEST.TRUNK [@2] │ Refer │ blocks/gen_dig │ │ tutorial.interface │ 1.TRUNK │ Refer │ blocks/interface │ │ tutorial.intf_ana │ HEAD.TRUNK [@2] │ Local │ blocks/intf_ana │ │ tutorial.io5v │ 1.TRUNK │ Refer │ blocks/io5v │ │ tutorial.io_tsmc18 │ 1.TRUNK │ Refer │ blocks/io_tsmc18 │ │ tutorial.laysc_tsmc18 │ 1.TRUNK │ Refer │ blocks/laysc_tsmc18 │ │ tutorial.padring │ 6.TRUNK │ Local │ blocks/padring │ │ tutorial.proj_tech │ 1.TRUNK │ Refer │ blocks/proj_tech │ │ tutorial.pwr_mgmt_ana │ HEAD.TRUNK [@1] │ Local │ blocks/pwr_mgmt_ana │ │ tutorial.rx_channel │ 1.TRUNK │ Refer │ blocks/rx_channel │ │ tutorial.rxtx │ 1.TRUNK │ Refer │ blocks/rxtx │ │ tutorial.stup_ana │ HEAD.TRUNK [@1] │ Local │ blocks/stup_ana │ │ tutorial.sys_bus │ 1.TRUNK │ Refer │ blocks/sys_bus │ │ tutorial.t0 │ 1.TRUNK │ Refer │ blocks/t0 │ │ tutorial.t1 │ 1.TRUNK │ Refer │ blocks/t1 │ │ tutorial.timers │ 1.TRUNK │ Refer │ blocks/timers │ │ tutorial.trc │ HEAD.TRUNK [@1] │ Local │ blocks/trc │ │ tutorial.verif_config │ 1.TRUNK │ Refer │ blocks/verif_config │ └────────────────────────┴───────────────────┴───────────┴──────────────────────┘
Note that the padring IP is brought in at version @6 as was captured in the workspace.
If we run a 'pi ip diff' on the padring and on the tutorial in the new workspace we see:
> pi ip diff padring tutorial.padring@6.TRUNK on the server and tutorial.padring@6.TRUNK in the Workspace differ. ┌─────────────────────┬──────────────────────────┬───────────┐ │ FILES │ tutorial.padring@6.TRUNK │ Workspace │ ╞═════════════════════╪══════════════════════════╪═══════════╡ │ hw_code/test/test.v │ 1 │ 4 │ └─────────────────────┴──────────────────────────┴───────────┘ > pi ip diff tutorial tutorial.tutorial@5.TRUNK on the server and tutorial.tutorial@5.TRUNK in the Workspace differ. ┌──────────────────┬───────────────────────────┬───┬───────────┐ │ RESOURCES │ tutorial.tutorial@5.TRUNK │ │ Workspace │ ╞══════════════════╪═══════════════════════════╪═══╪═══════════╡ │ tutorial.padring │ 1.TRUNK │ → │ 6.TRUNK │ └──────────────────┴───────────────────────────┴───┴───────────┘
The new workspace has been created in the identical state as the original snapshotted workspace.