Updating the workspace
Once a workspace is built and development has begun it is often necessary to update the workspace with new releases that have been captured in other workspaces or on the Helix IPLM server. DM file level updates happen on an ongoing basis through DM level commands.
Helix IPLM updates bring in new IPVs and their resources, along with their associated files.
Workspaces update overview
Helix IPLM workspace updates bring in new IPV releases in a controlled and traceable manner. Workspace Update modes, which can preserve local modifications a user has made to their workspace while bringing in new data, are a key element of workspace updates.
Workspaces can be updated at the file level as needed through DM level commands, Helix IPLM updates are based on IPV releases, and can bring in both resource IPV updates, and the file level updates that go along with the IPV updates.
Updating the top level workspace IPV
The 'Top Level' workspace IPV is the IPV that was loaded to create the workspace a part of the 'pi ip load' command. Updates to the top level workspace IPV can move the IPV to a new version on the same Line or move the IPV to a different line, but the top level workspace IP never changes; only its version or line (+version). If there are resource changes on the new version of the top level IPV versus the old one, or if some of the IPVs in the workspace are aliased and those aliases have been applied to new versions on the IPV's lines, then updating the top level IPV will also result in other IPV changes in the workspace. Some resources may have version changes, other resources may be added or removed from the workspace, depending on whether they were present in the original workspace hierarchy versus the new workspace hierarchy.
Updating workspace resources
Resource IPVs at lower levels of the workspace hierarchy can also be be updated directly. This process works in the same way that updating the top level workspace IPV works, a given resource can be updated to a new IPV on the same line or to an IPV on a different line, but the workspace target IP remains in the workspace. If there are resource changes brought in by the incoming IPV, these will be applied, which means IPVs may change version, be removed, or be added depending on the incoming IPV and update modes. Post-update, all IPVs in the workspace have a hierarchical relationship back up to the top level IPV in the workspace, though because resource updates are possible the hierarchical relationship doesn't have to match any existing server side release regarding the specific IP Versions or Lines in the workspace. Once a new (possibly hierarchical) release is made in the workspace the new hierarchy is captured in a new release of the released IPV.
Updates and modified files
If an update would cause an IP to be removed from (or moved within) the workspace, for instance because it's parent no longer includes it as a resource or if the update will bring in a new --path definition, it cannot have any modified files, else the update will fail. In the case of Perforce type IPs, open but not modified files will be automatically reverted.
Hierarchical workspace update details
The workspace update algorithm consists of three phases.
Phase 1: Update aliased IPVs using the existing workspace contents.
Any aliased IPVs in the workspace are updated starting from the top level IPV of the workspace down the existing workspace hierarchy. Each aliased resource is updated to the latest version on the line that has that alias. This means that any modified IPVs under an aliased resource for which there is a new version available will be removed, with the hierarchy set to exactly that of the new aliased release.
Phase 2: Reconcile the incoming tree
The incoming tree is reconciled using automatic reconciliation methods and any reconcile statements that are present on the top level or leaf nodes of the IP Hierarchy. Once complete, the incoming tree will not have any conflicts.
Phase 3: Apply the incoming tree to the workspace
The algorithm steps through the hierarchy from the top down, choosing between the incoming and the workspace tree at each level, using the requested update mode (default is promote mode).
Command line
The 'pi update' command is used to update the workspace.
Unload mode is a perforce IP specific function, the unload mode is specified as a number 0-2, with lower mode numbers resulting in higher performance, and higher unload mode numbers resulting in more careful and conservative checking and preservation of file modifications when an IP is unloaded from the workspace.
| Unload Mode | Default | Description |
| 0 | Y | Block IP unload for p4 open files. This is a server only check and the quickest unload option. |
| 1 | N | Block IP unload open and modified files. Requires on disk checks so is slower, auto reverts open but unmodified files automatically. |
| 2 | N | Same as 1 but unopened modified files (edited without p4 edit) will be backed up to BACKUP_DIR piclient.conf directory. |
pi update command
> pi update -h
Usage: pi update [-h] [--wsdir WSDIR] [--args ARGS]
[--force | --keep-local | --promote] [--dry-run]
[--verbose] [ip]
Description: Update a Workspace. This can be used to update any or all of the
resources in the current Workspace.
Positional arguments:
ip The IP Version to update. By default, the top IP
Version of the Workspace will be used.
Optional arguments:
--args ARGS Arguments passed to the hooks.
--dry-run, -n Report on updates that would result, without actually
making any changes to the Workspace.
--force, -f Update a Workspace to precisely reflect a release. All
resources are updated to the version in the release.
--keep-local, -k Update the Workspace to a release, while retaining
local changes made to files and resources.
--promote, -p Update the Workspace to a release, while retaining
local changes made to files and resources, unless a
released version of a file or resource is greater than
the version in the Workspace. In that case, use the
released version of the file or resource. This is the
default behavior.
--unload MODE Specify handling of IPVs that will be unloaded from the workspace.
MODE is integer 0-2:
0 (default) - block unload for open files,
1 - block unload for open+modified files (unmodified files will be reverted),
2 - same as 1 but unopened modified files will be backed up to BACKUP_DIR.
Higher mode number gives lower performance.
--verbose, -v Display file version level changes resulting from the workspace update.
--wsdir WSDIR, -ws WSDIR
The Workspace directory. If not specified, the current
directory should be a Workspace directory.
-h, --help Show this help message and exit
IPV target definition
The optional 'ip' argument utilizes the IP Naming and Filtering functionality described in detail in the Listing IPs in the Catalog section. If an 'ip' argument is provided with the full definition of the target IP, version, and line (eg 'pi up IP@VER.LINE') that IP in the workspace is then updated to that specific version and line, and its resources and files are updated according to the provided update mode.
The IP that gets updated is determined by the IP name (and Library name if provided) supplied as the target. The target IP name provided must match an IP that is currently in the workspace. If there is some confusion on which IP is meant (because two IPs with the same name are coming from two different Libraries) then the Library must also be specified. Either the top level IP or one of the resources of the workspace can be updated based on the IP name provided. To add or remove IPVs to or from a workspace use the pi ws edit command.
If an 'ip' argument is provided with the full definition of the target IP, version, and line (for example, pi up IP@VER.LINE) that IP in the workspace (whether it is the top level or a resource) is updated to that specific version and line, and its resources and files are updated according to the provided update mode.
If the line is omitted from the target (for example, pi up IP@VER) the current line of the IP in the workspace is assumed, and if the version is omitted (for example, pi up IP@.TRUNK or pi up IP) the latest release on the current line is assumed.
Updating the top level workspace IPV without a FQN target
If the 'ip' argument is entirely omitted (for example, pi up) IPLM assumes that you want to update the top level IP in the workspace. The version (fixed or alias) and line the top level IP gets updated to are dependent on the version the top level IPV was most recently updated to (or loaded at in the case of workspace creation).
Tip: The output of pi ws status reports the default pi up target currently in effect.
| Last update or load target | pi up assumed top level IPV target |
|---|---|
|
The latest fixed release on the top level IP’s current workspace line |
|
The latest version on the top level IP’s current workspace line that has the ALIAS |
|
The latest version on the top level IP’s current workspace line that has the ALIAS The latest aliased version may be an earlier or later version than the current workspace version. |
|
The latest fixed release on the top level IP’s current workspace line |
|
The top level IPV will be updated at the same workspace version, and the lower level aliases will be refreshed |
|
The version on whichever line on the top level IP that currently has the unique alias set |
|
The latest fixed release on the top level IP’s current workspace line |
Hook/DM handler arguments
The –args option passes argument values to any hook scripts that may be defined on the IP or to the DM Handler update payload, if the IP is defined via the DM Handler system.
| Command option | Description |
|---|---|
| --args | Arguments passed in to client side hooks or to the DM Handler (if the IP is a DM Handler). Format is: --args="-arg1 value1 -arg2 value2 -arg3" |
Dry run mode
The result of an update can be previewed with the --dry-run option.
| Command option | Description |
|---|---|
--dry-run, -n |
Report on the updates that would occur, but does not make any changes in the workspace. Can be combined with the –verbose option. |
Verbose mode
Any file level changes that are made (or would be made in –dry-run mode) by the update are displayed.
Note: For P4
Important: p4 and svn type IPs currently support verbose mode.
| Command option | Description |
|---|---|
| --verbose, -v | Report file level changes made by the workspace update. Can be combined with the –dry-run option. |
Update mode options
Update modes control how (or if) local changes in the workspace are retained via a workspace update. See more at Update modes.
Note: The default is --promote mode.
| Command Option | Description |
|---|---|
| --force, -f | Force mode. Updates the workspace to precisely reflect the release, local changes are not retained. |
| --keep-local, -k | Keep Local mode. Retain any local changes in the workspace, disregarding whether the new file or resource versions of the incoming IPV are at an earlier or later version than the current versions in the workspace. |
| --promote, -p | Promote mode. Retain local changes in the workspace only if they are at later resource or file versions than those of the incoming IPV, otherwise update them. |
Specifying the workspace directory
| Command Option | Description |
|---|---|
| --wsdir WSDIR | By default the workspace from which the command is run will be used, if this option is supplied update the specified workspace directory |
Workspace update examples
Running Workspace status shows the current releases of the various resource IPs.
Workspace status
> pi ws st -v Workspace ID : 83eb3626-b085-457e-ba5c-f8f59425a8b5 Directory : /home/bob/workspaces/ws1 IP : coco.CPU@24.TRUNK Resources : ┌──────────────────────────────────────────┬───────────────────┬───────────────────┬───────────┬───────────────┬───────┐ │ NAME │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │ MODE │ ╞══════════════════════════════════════════╪═══════════════════╪═══════════════════╪═══════════╪═══════════════╪═══════╡ │ coco.CPU │ 24.TRUNK │ 24.TRUNK │ OK │ OK │ Local │ │ IEC_ARM_coco.SY750 │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ Memories_TSMC_coco.CS-DTI-TS28N-GS-1PSRM │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ MemoryControllers_TSMC_coco.dwc_comp_ts2 │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ 8nih41p11sadrl128s │ │ │ │ │ │ │ StandardCells_TSMC_coco.CS-DTI-TS28N-GS- │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ SCDEN_DO │ │ │ │ │ │ │ StandardCells_TSMC_coco.CS-DTI-TS28N-GS- │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ SCPER_PO │ │ │ │ │ │ │ coco.CPU_Cache │ 6.TRUNK │ 6.TRUNK │ OK │ OK │ Refer │ │ coco.CPU_Core │ 6.TRUNK │ 6.TRUNK │ OK │ OK │ Refer │ │ coco.CPU_Logic │ LATEST.TRUNK [@6] │ LATEST.TRUNK [@6] │ OK │ OK │ Refer │ └──────────────────────────────────────────┴───────────────────┴───────────────────┴───────────┴───────────────┴───────┘
Users can update a specific resource within the workspace. By specifying the resource to update (along with an optional '@REL' release number), PI updates only that resource in the workspace. In the example below, the CPU_Core resource is being updated to release '5'.
Note: One of the Core's resources (SYS750) is removed from the workspace because it is not used by CPU_Core@5.
Specific resource targeting
> pi update coco.CPU_Core@5.TRUNK Updating workspace. For large IP this could take a while. ┌────────────────────┬─────────────┬─────────────┬───────┬───────────────┐ │ NAME │ OLD VERSION │ NEW VERSION │ MODE │ RELATIVE PATH │ ╞════════════════════╪═════════════╪═════════════╪═══════╪═══════════════╡ │ IEC_ARM_coco.SY750 │ 5.TRUNK │ │ │ │ │ coco.CPU_Core │ 6.TRUNK │ 5.TRUNK │ Refer │ coco.CPU_Core │ └────────────────────┴─────────────┴─────────────┴───────┴───────────────┘
The workspace status now shows that the resource is updated to a different version, while the top level resource is listed as 'Modified' due to the fact that the resource list for the top level resource at release '24' expects CPU_Core to be at release '6'. The 'pi ip diff' command can be used to confirm the cause of the modified state, ie 'pi ip diff CPU'.
Workspace lookup
> pi ws st -v Workspace ID : ca2d5445-a416-4c4c-acd6-1a735ee272ae Directory : /home/bob/temp/ws1 IP : coco.CPU@24.TRUNK Resources : ┌──────────────────────────────────────────┬───────────────────┬───────────────────┬───────────┬───────────────┬───────┐ │ NAME │ EXPECTED VERSION │ LOCAL VERSION │ WS STATUS │ SERVER STATUS │ MODE │ ╞══════════════════════════════════════════╪═══════════════════╪═══════════════════╪═══════════╪═══════════════╪═══════╡ │ coco.CPU │ 24.TRUNK │ 24.TRUNK │ Modified │ OK │ Local │ │ Memories_TSMC_coco.CS-DTI-TS28N-GS-1PSRM │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ MemoryControllers_TSMC_coco.dwc_comp_ts2 │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ 8nih41p11sadrl128s │ │ │ │ │ │ │ StandardCells_TSMC_coco.CS-DTI-TS28N-GS- │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ SCDEN_DO │ │ │ │ │ │ │ StandardCells_TSMC_coco.CS-DTI-TS28N-GS- │ 5.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ SCPER_PO │ │ │ │ │ │ │ coco.CPU_Cache │ 6.TRUNK │ 6.TRUNK │ OK │ OK │ Refer │ │ coco.CPU_Core │ 6.TRUNK │ 5.TRUNK │ OK │ OK │ Refer │ │ coco.CPU_Logic │ LATEST.TRUNK [@6] │ LATEST.TRUNK [@6] │ OK │ OK │ Refer │ └──────────────────────────────────────────┴───────────────────┴───────────────────┴───────────┴───────────────┴───────┘
Updating IPs @HEAD
Updates of IPs on the @HEAD alias are handled differently than updates for other IP aliases (ie @LATEST or @ALIAS) in order to facilitate standard flows around @HEAD IPs. Typically when IPs are loaded @HEAD in workspaces the intent is to keep them @HEAD until explicitly moving them to a new alias or to a fixed release. For the purposes of workspace updates the @HEAD alias is considered to be a version in advance of the latest Helix IPLM release, this allows the use of the commands 'pi up lib.ip' or 'pi up lib.ip@.LINE' to update the contents of these IPs, while leaving them @HEAD in the workspace.
Note: If the @HEAD alias is already present in the workspace underneath another aliased IPV further up in the hierarchy and that other aliased IPV is updated in the first phase of the workspace update (see above) the @HEAD aliased IPV may be removed if the incoming alias doesn’t have the @HEAD IPV as a resource.
Updating IPs @HEAD
> pi up tutorial.padring@HEAD Updating Workspace to Alias 'HEAD'. For large IP this could take a while. ┌──────────────────┬─────────────┬─────────────────┬───────┬────────────────┐ │ NAME │ OLD VERSION │ NEW VERSION │ MODE │ PATH │ ╞══════════════════╪═════════════╪═════════════════╪═══════╪════════════════╡ │ tutorial.padring │ 6.TRUNK │ HEAD.TRUNK [@6] │ Local │ blocks/padring │ └──────────────────┴─────────────┴─────────────────┴───────┴────────────────┘ > pi up tutorial.padring Updating Workspace to Alias 'HEAD'. For large IP this could take a while. Workspace is up-to-date. > pi up tutorial.padring@.TRUNK Updating Workspace to Alias 'HEAD'. For large IP this could take a while. Workspace is up-to-date.
In both cases the tutorial.padring IP is left @HEAD and updated to include the latest HEAD revisions, rather than being updated to a fixed release. In order to move the IP to a new release a full FQN including version/alias must be used, ie:
Full FQN
> pi up tutorial.padring@6.TRUNK Updating Workspace. For large IP this could take a while. ┌──────────────────┬─────────────────┬─────────────┬───────┬────────────────┐ │ NAME │ OLD VERSION │ NEW VERSION │ MODE │ PATH │ ╞══════════════════╪═════════════════╪═════════════╪═══════╪════════════════╡ │ tutorial.padring │ HEAD.TRUNK [@6] │ 6.TRUNK │ Local │ blocks/padring │ └──────────────────┴─────────────────┴─────────────┴───────┴────────────────┘
Finding new available versions
Helix IPLM provides a way to find IP Versions if a particular IP Hierarchy is out of date. The command used is 'pi ip tree --list-new <top_level_IP>':
> pi ip tree --list-new tutorial.tutorial tutorial.tutorial@8.TRUNK ├─ ARM.cortex@1.TRUNK → @5 [GOLD], @9 [LATEST] ├─ tutorial.CADenv@GOLD.TRUNK [@1] → @3 [LATEST] ├─ tutorial.digital_top@2.TRUNK │ ├─ tutorial.clk_mux@1.TRUNK │ │ └─ tutorial.rxtx@1.TRUNK │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.cpu@LATEST.TRUNK [@2] │ │ └─ tutorial.bist_sram@1.TRUNK │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.dbuf@1.TRUNK │ │ ├─ tutorial.bist_sram@1.TRUNK │ │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.events_if@1.TRUNK │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.flash@1.TRUNK │ │ ├─ tutorial.flash_if@1.TRUNK │ │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.interface@1.TRUNK → @3 [LATEST] │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.rx_channel@1.TRUNK │ │ ├─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ │ └─ tutorial.rxtx@1.TRUNK │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.rxtx@1.TRUNK │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.sys_bus@1.TRUNK │ │ ├─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ │ └─ tutorial.rxtx@1.TRUNK │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.t0@1.TRUNK │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ ├─ tutorial.t1@1.TRUNK → @3 [LATEST] │ │ ├─ tutorial.bist_sram@1.TRUNK │ │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] │ └─ tutorial.timers@1.TRUNK │ └─ tutorial.gen_dig@1.TRUNK → @2 [LATEST] ├─ tutorial.padring@1.TRUNK → @2 [GOLD], @11 [LATEST] │ ├─ tutorial.io5v@1.TRUNK → @5 [LATEST] │ └─ tutorial.io_tsmc18@1.TRUNK → @3 [LATEST] └─ tutorial.verif_config@1.TRUNK → @3 [LATEST]
The output is a sparse version of the standard 'pi ip tree' format output, with the addition of text showing the latest release of each IP that has an ALIAS applied. As an example see the following ARM.cortex entry:
ARM.Cortex entry
├─ ARM.cortex@1.TRUNK → @5 [GOLD], @9 [LATEST]
The ARM.cortex is included in the hierarchy at static version @1. The --list-new output shows us that there is a newer version with the @LATEST alias (the newest release in an IP Line always has the @LATEST built in alias applied), @9. It also shows us that the latest IPV in the line that has the @GOLD alias applied is ARM.cortex@5.
For each alias that exists on the line 'pi ip tree --list-new' shows the latest IP Version that has that alias attached (assuming the latest version of each alias is not already in the tree). This information can be used to update workspaces, or the IP Hierarchy itself to incorporate new resource IP versions.
