Workspaces and releases
This training page demonstrates how to load a new workspace from an IP release, make DM level changes to that IP, use Perforce IPLM to check what changes have been made versus the release, and to then capture those workspace changes to create a new Perforce IPLM release. For more information on Workspaces refer to the Loading a Workspace and Making Workspace Releases pages within the User Guide.
Creating an IP workspace
To see the IPs available in the system use the 'pi ip list' command:
> pi ip list ┌────────────────────────────────┬──────┬─────────────┬────────────┬───────────────────────────────┬─────────────────────┐ │ NAME │ DM │ ALIASES │ CREATED BY │ CREATED ON │ VERSION MESSAGE │ ╞════════════════════════════════╪══════╪═════════════╪════════════╪═══════════════════════════════╪═════════════════════╡ │ testlib.ip1@0.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:19:06 -0400 EDT │ First version │ │ tutorial.CADenv@3.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:37 -0400 EDT │ hier release │ │ tutorial.MS90G@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:44 -0400 EDT │ hier release │ │ tutorial.acells_tsmc18@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:40 -0400 EDT │ hier release │ │ tutorial.adc@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:48 -0400 EDT │ hier release │ │ tutorial.aes512@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:30 -0400 EDT │ hier release │ │ tutorial.analog_top@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:40 -0400 EDT │ analog_top release │ │ tutorial.bist_sram@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:02 -0400 EDT │ hier release │ │ tutorial.clk_mux@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:29 -0400 EDT │ hier release │ │ tutorial.clkgen@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:56 -0400 EDT │ hier release │ │ tutorial.cpu@2.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:46 -0400 EDT │ Initial version │ │ tutorial.dac@0.TRUNK │ CONT │ HEAD LATEST │ admin │ 2020-06-19 10:13:45 -0400 EDT │ Initial version │ │ tutorial.dbuf@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:27 -0400 EDT │ hier release │ │ tutorial.digital_top@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:44 -0400 EDT │ tutorial release │ │ tutorial.events_if@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:09 -0400 EDT │ hier release │ │ tutorial.flash@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:23 -0400 EDT │ hier release │ │ tutorial.flash_if@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:05 -0400 EDT │ hier release │ │ tutorial.gen_dig@2.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:46 -0400 EDT │ hier release │ │ tutorial.interface@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:18 -0400 EDT │ hier release │ │ tutorial.intf_ana@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:54 -0400 EDT │ hier release │ │ tutorial.io5v@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:34 -0400 EDT │ hier release │ │ tutorial.io_tsmc18@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:32 -0400 EDT │ hier release │ │ tutorial.laysc_tsmc18@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:42 -0400 EDT │ hier release │ │ tutorial.padring@1.L1 │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:50 -0400 EDT │ padring L1 release │ │ tutorial.padring@1.L2 │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:52 -0400 EDT │ padring L2 release │ │ tutorial.padring@1.L3 │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:54 -0400 EDT │ padring L3 release │ │ tutorial.padring@1.L4 │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:56 -0400 EDT │ padring L4 release │ │ tutorial.padring@5.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:47 -0400 EDT │ tutorial release │ │ tutorial.proj_tech@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:03 -0400 EDT │ hier release │ │ tutorial.pwr_mgmt_ana@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:58 -0400 EDT │ hier release │ │ tutorial.rx_channel@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:14 -0400 EDT │ hier release │ │ tutorial.rxtx@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:07 -0400 EDT │ hier release │ │ tutorial.stup_ana@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:50 -0400 EDT │ hier release │ │ tutorial.sys_bus@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:19 -0400 EDT │ hier release │ │ tutorial.t0@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:10 -0400 EDT │ hier release │ │ tutorial.t1@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:16 -0400 EDT │ hier release │ │ tutorial.timers@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:12 -0400 EDT │ hier release │ │ tutorial.trc@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:13:52 -0400 EDT │ hier release │ │ tutorial.tutorial@1.L1 │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:15:02 -0400 EDT │ tutorial L1 release │ │ tutorial.tutorial@1.L2 │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:15:06 -0400 EDT │ tutorial L2 release │ │ tutorial.tutorial@1.L3 │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:15:10 -0400 EDT │ tutorial L3 release │ │ tutorial.tutorial@1.L4 │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:15:13 -0400 EDT │ tutorial L4 release │ │ tutorial.tutorial@5.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:58 -0400 EDT │ tutorial release │ │ tutorial.verif_config@1.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:14:25 -0400 EDT │ hier release │ └────────────────────────────────┴──────┴─────────────┴────────────┴───────────────────────────────┴─────────────────────┘ Found 44 matching object(s).
To create a workspace out of one of the available IPs, point to the directory you want to make the workspace in and run the commands:
> cd /tmp > pi ip load tutorial.analog_top
The 'pi ip load' command will build a workspace from the IP called 'analog_top' in the library 'tutorial' in the directory '/tmp/tutorial.analog_top'. Optionally you can pass the 'pi ip load' command a workspace directory name, ie 'pi ip load tutorial.analog_top ws1' (refer to Loading a Workspace for more details).
> pi ip load tutorial.analog_top Loading IPV 'tutorial.analog_top@1.TRUNK' into Workspace '/tmp/tutorial.analog_top'. INFO:Waiting for 6 PiCache jobs ... INFO:Waiting for 4 PiCache jobs ... INFO:Waiting for 2 PiCache jobs ... INFO:Waiting for 1 PiCache job ... ┌────────────────────────┬─────────────────┬───────────┬──────────────────────┐ │ NAME │ VERSION │ MODE │ RELATIVE PATH │ ╞════════════════════════╪═════════════════╪═══════════╪══════════════════════╡ │ tutorial.analog_top │ 1.TRUNK │ Refer │ blocks/analog_top │ │ tutorial.MS90G │ 1.TRUNK │ Refer │ blocks/MS90G │ │ tutorial.acells_tsmc18 │ 1.TRUNK │ Refer │ blocks/acells_tsmc18 │ │ tutorial.adc │ HEAD.TRUNK [@1] │ Refer │ blocks/adc │ │ tutorial.clkgen │ HEAD.TRUNK [@1] │ Refer │ blocks/clkgen │ │ tutorial.dac │ HEAD.TRUNK [@0] │ Container │ │ │ tutorial.intf_ana │ HEAD.TRUNK [@1] │ Refer │ blocks/intf_ana │ │ tutorial.laysc_tsmc18 │ 1.TRUNK │ Refer │ blocks/laysc_tsmc18 │ │ tutorial.pwr_mgmt_ana │ HEAD.TRUNK [@1] │ Refer │ blocks/pwr_mgmt_ana │ │ tutorial.stup_ana │ HEAD.TRUNK [@1] │ Refer │ blocks/stup_ana │ │ tutorial.trc │ HEAD.TRUNK [@1] │ Refer │ blocks/trc │ └────────────────────────┴─────────────────┴───────────┴──────────────────────┘
The 'Waiting for X PiCache jobs' output will only appear if PiCache is enabled in your environment. A number of IPs in the analog_top hierarchy are being included at the @HEAD alias and these are being refreshed in the cache.
Checking the Status of the Workspace
To get some more details on the state of the workspace cd into it:
> cd tutorial.analog_top
Run the 'pi workspace status' command in the workspace:
> pi ws st Workspace ID : 615c6c28-00b0-4212-a6fa-f73dc3484db7 Directory : /tmp/tutorial.analog_top IP : tutorial.analog_top@1.TRUNK Workspace is up-to-date.
By default the workspace status command only shows IPs in the workspace that differ from the server definition (are modified). Run a pi workspace status in verbose mode on the workspace to get information on all IPs:
> pi ws st -v Workspace ID : 615c6c28-00b0-4212-a6fa-f73dc3484db7 Directory : /tmp/tutorial.analog_top IP : tutorial.analog_top@1.TRUNK Resources : ┌────────────────────────┬──────────────────┬─────────────────┬───────────┬───────────────┬───────────┐ │ NAME │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │ MODE │ ╞════════════════════════╪══════════════════╪═════════════════╪═══════════╪═══════════════╪═══════════╡ │ tutorial.analog_top │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.MS90G │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.acells_tsmc18 │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.adc │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.clkgen │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.dac │ HEAD.TRUNK [@0] │ HEAD.TRUNK [@0] │ OK │ OK │ Container │ │ tutorial.intf_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.laysc_tsmc18 │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.pwr_mgmt_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.stup_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.trc │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ └────────────────────────┴──────────────────┴─────────────────┴───────────┴───────────────┴───────────┘
Here we can see the various IPs that were loaded into the workspace as resources (and resources of resources) of the 'tutorial.analog_top' IP. There is a column for what the Expected Version is (the versions specified in the resource lists of the various parent IPs on up to 'tutorial.analog_top') and the Local Version of each IP present in the workspace. As we just loaded the workspace based on the tutorial.analog_top@1 release specification there are no differences between the Local (workspace) Version and the Expected Version.
Making Workspace Changes
To generate a new release of the IP, we need to make changes to one (or more) of the files or IP resources in the workspace. Let's modify a file in one of the IPs and commit the changes to the DM system.
Before we can make changes we need to make the IP local, ie: populate the files for the IP over to the workspace. This is done using the pi ip local command:
> pi ip local analog_top Switching 'tutorial.analog_top@1.TRUNK' to local mode Successfully switched 'tutorial.analog_top@1.TRUNK' to local mode
which removes the symbolic link to the analog_top block in the workspace and populates its files
> ls -al blocks/ total 12 drwxr-xr-x 3 mdx mdx 4096 Jun 19 10:32 . drwxr-xr-x 5 mdx mdx 4096 Jun 19 10:24 .. lrwxrwxrwx 1 mdx mdx 44 Jun 19 10:24 acells_tsmc18 -> /picache-root/tutorial/acells_tsmc18/TRUNK/1 lrwxrwxrwx 1 mdx mdx 37 Jun 19 10:24 adc -> /picache-root/tutorial/adc/TRUNK/HEAD drwxr-xr-x 6 mdx mdx 4096 Jun 19 10:32 analog_top lrwxrwxrwx 1 mdx mdx 40 Jun 19 10:24 clkgen -> /picache-root/tutorial/clkgen/TRUNK/HEAD lrwxrwxrwx 1 mdx mdx 42 Jun 19 10:24 intf_ana -> /picache-root/tutorial/intf_ana/TRUNK/HEAD lrwxrwxrwx 1 mdx mdx 43 Jun 19 10:24 laysc_tsmc18 -> /picache-root/tutorial/laysc_tsmc18/TRUNK/1 lrwxrwxrwx 1 mdx mdx 36 Jun 19 10:24 MS90G -> /picache-root/tutorial/MS90G/TRUNK/1 lrwxrwxrwx 1 mdx mdx 46 Jun 19 10:24 pwr_mgmt_ana -> /picache-root/tutorial/pwr_mgmt_ana/TRUNK/HEAD lrwxrwxrwx 1 mdx mdx 42 Jun 19 10:24 stup_ana -> /picache-root/tutorial/stup_ana/TRUNK/HEAD lrwxrwxrwx 1 mdx mdx 37 Jun 19 10:24 trc -> /picache-root/tutorial/trc/TRUNK/HEAD
When modifying files in the workspace we are operating at the DM level, so we use DM commands. In the case of Perforce IPs for example:
> cd blocks/analog_top/ > touch README > p4 add README //mdx_test/tutorial/analog_top/TRUNK/README#1 - opened for add /tmp/tutorial.analog_top/blocks/analog_top/README - empty, assuming text (+Fl). > p4 submit -d 'added changes to a file' Submitting change 2. Locking 1 files ... add //mdx_test/tutorial/analog_top/TRUNK/README#1 Change 2 submitted.
Displaying workspace changes
If we now look at the workspace status:
> pi ws st -v Workspace ID : 615c6c28-00b0-4212-a6fa-f73dc3484db7 Directory : /tmp/tutorial.analog_top IP : tutorial.analog_top@1.TRUNK Resources : ┌────────────────────────┬──────────────────┬─────────────────┬───────────┬───────────────┬───────────┐ │ NAME │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │ MODE │ ╞════════════════════════╪══════════════════╪═════════════════╪═══════════╪═══════════════╪═══════════╡ │ tutorial.analog_top │ 1.TRUNK │ 1.TRUNK │ Modified │ OK │ Local │ │ tutorial.MS90G │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.acells_tsmc18 │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.adc │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.clkgen │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.dac │ HEAD.TRUNK [@0] │ HEAD.TRUNK [@0] │ OK │ OK │ Container │ │ tutorial.intf_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.laysc_tsmc18 │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.pwr_mgmt_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.stup_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.trc │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ └────────────────────────┴──────────────────┴─────────────────┴───────────┴───────────────┴───────────┘
The status now shows that we still have Local Version 1.TRUNK of tutorial.analog_top in the workspace, but that now the IP has modifications, as shown by the 'Modified' text under 'WS STATUS'.
To get additional details on why a particular IP is showing a 'Modified' state we can use the 'pi ip diff' command:
> pi ip diff analog_top tutorial.analog_top@1.TRUNK on the server and tutorial.analog_top@1.TRUNK in the Workspace differ. ┌────────┬─────────────────────────────┬───────────┐ │ FILES │ tutorial.analog_top@1.TRUNK │ Workspace │ ╞════════╪═════════════════════════════╪═══════════╡ │ README │ │ 1 │ └────────┴─────────────────────────────┴───────────┘
We see that the 'Modified' state is the result of our added README file. The empty 'tutorial.analog_top@1.TRUNK' column indicates the README file isn't part of the @1 release captured by Perforce IPLM. The '1' in the 'Workspace' column indicates that the README is loaded at Perforce version 1 in the workspace.
Making a workspace release
We can now release a new version of the analog_top incorporating our change. Note that all changed/opened files should be submitted into perforce before you can release the new version of the IP. Also note that the 'pi release' command must be run from somewhere within the hierarchy under the top level of the workspace.
> pi release tutorial.analog_top -m "another release"Successfully created 'tutorial.analog_top@2.TRUNK'
We can again run 'pi ws status' to check what happened:
> pi ws st -v Workspace ID : 615c6c28-00b0-4212-a6fa-f73dc3484db7 Directory : /tmp/tutorial.analog_top IP : tutorial.analog_top@2.TRUNK Resources : ┌────────────────────────┬──────────────────┬─────────────────┬───────────┬───────────────┬───────────┐ │ NAME │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │ MODE │ ╞════════════════════════╪══════════════════╪═════════════════╪═══════════╪═══════════════╪═══════════╡ │ tutorial.analog_top │ 2.TRUNK │ 2.TRUNK │ OK │ OK │ Local │ │ tutorial.MS90G │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.acells_tsmc18 │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.adc │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.clkgen │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.dac │ HEAD.TRUNK [@0] │ HEAD.TRUNK [@0] │ OK │ OK │ Container │ │ tutorial.intf_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.laysc_tsmc18 │ 1.TRUNK │ 1.TRUNK │ OK │ OK │ Refer │ │ tutorial.pwr_mgmt_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.stup_ana │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ │ tutorial.trc │ HEAD.TRUNK [@1] │ HEAD.TRUNK [@1] │ OK │ OK │ Refer │ └────────────────────────┴──────────────────┴─────────────────┴───────────┴───────────────┴───────────┘
Both the 'EXPECTED VERSION' and 'LOCAL VERSION' of 'tutorial.analog_top' are now shown to be '2.TRUNK'. 'WS STATUS' shows OK. We created 2.TRUNK out of the p4 modifications in our workspace, and as 'tutorial.analog_top' is the top level IP of our workspace we now expect to see 2.TRUNK, and there are no Modifications from that 2.TRUNK expected version. If we had released a lower level IP the situation would be a little different, more on that later.
We can also use the 'pi ip diff' command to check the differences between any two versions of an IP, in order to ensure that the release captured all the changes made to the IP. For example, since we added a new file called 'README' between version 1 and version 2 of the IP, the following output is generated:
> pi ip diff -v tutorial.analog_top@1 tutorial.analog_top@2 tutorial.analog_top@1.TRUNK and tutorial.analog_top@2.TRUNK differ on the server. ┌────────┬─────────────────────────────┬─────────────────────────────┐ │ FILES │ tutorial.analog_top@1.TRUNK │ tutorial.analog_top@2.TRUNK │ ╞════════╪═════════════════════════════╪═════════════════════════════╡ │ README │ │ 1 │ └────────┴─────────────────────────────┴─────────────────────────────┘
Perforce Version #1 of the README file exists in tutorial.analog_top@2.TRUNK, but is absent from tutorial.analog.top@1.TRUNK.
You may add, delete, or edit any number of files, and then do another release to test how the 'pi release' and 'pi ip diff' commands work.
After the release, the latest version of the IP will show up in the output of the 'pi ip list' command:
> pi ip list tutorial.analog_top ┌─────────────────────────────┬────┬─────────────┬────────────┬───────────────────────────────┬─────────────────┐ │ NAME │ DM │ ALIASES │ CREATED BY │ CREATED ON │ VERSION MESSAGE │ ╞═════════════════════════════╪════╪═════════════╪════════════╪═══════════════════════════════╪═════════════════╡ │ tutorial.analog_top@2.TRUNK │ P4 │ HEAD LATEST │ admin │ 2020-06-19 10:44:07 -0400 EDT │ another release │ └─────────────────────────────┴────┴─────────────┴────────────┴───────────────────────────────┴─────────────────┘ Found 1 matching object(s).
More information on IP releases can be found on the Making Workspace Releases and IP Versions (Releases) pages in the User Guide.
Updating a workspace
When a new version of the top IP, which includes a new resource, has been created, the new version is brought into the workspace by running the 'pi update' command. You will then see the new resource IP in your workspace. The tutorial section for updating your workspace can be found on the Updating a workspace tutorial page.