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

  • Fixed release

 The latest fixed release on the top level IP’s current workspace line

  • Moving alias

  • Workspace version still has the ALIAS set

The latest version on the top level IP’s current workspace line that has the ALIAS

  • Moving alias

  • Workspace version no longer has the alias set

  • Alias is set on another version on the current workspace line

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.

  • Moving alias

  • Workspace version no longer has the alias set

  • Alias is not set on any other version on the current workspace line

The latest fixed release on the top level IP’s current workspace line

  • Unique Alias

  • Workspace version still has the unique alias set

The top level IPV will be updated at the same workspace version, and the lower level aliases will be refreshed

  • Unique Alias

  • Workspace version no longer has the unique alias set

  • Unique alias moved to another IPV on a line of the IP

The version on whichever line on the top level IP that currently has the unique alias set

  • Unique alias

  • No version on any line of the IP still 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 DM types, in verbose update mode, files at IP@HEAD are always reported as up-to-date, unless the STATIC_HEAD caching mode is used. See STATIC_HEAD caching mode administration.

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.