Application Note Citrix

TRACE32 Online Help

TRACE32 Directory
TRACE32 Index
TRACE32 Installation .......................................................................................................................

Citrix Application Note ..................................................................................................................

Application Note Citrix ...............................................................................................................

Introduction .............................................................................................................................

Intended Audience

Related Documents

Terms Glossary

Contacting Support

Standalone USB Configuration

Citrix USB Redirection

Citrix USB Virtual Channel Driver

Citrix Receiver Configuration .................................................................................................

Windows/32bit Registry Settings

Windows/64bit Registry Settings

11

ICA Client 9.x - module.ini settings

13

Installer-based Configuration - Algorithm

14

TRACE32 Citrix Virtual Channel Installer (NSIS)

15

Miscellaneous Information .....................................................................................................

1989-2016 Lauterbach GmbH

Application Note Citrix

18

Application Note Citrix

Version 24-May-2016

Introduction
This document explains how a TRACE32 GUI setup for a PowerDebug / USB device in a Citrix environment
differs from a normal (local) USB installation.
TRACE32 Citrix Virtual Channel communication is currently only available for Windows (32bit and 64bit).

NOTE:

Due to lack of testing facilities, we can currently not officially support TRACE32
Citrix Virtual Channel setups. All information about it and all setup files are provided
as-is, and may or may not work in your environment.

Intended Audience
Administrators and consultants who need to install and/or publish TRACE32 in a Citrix environment.

Related Documents
General TRACE32 installation options are covered in TRACE32 Installation Guide (installation.pdf).

1989-2016 Lauterbach GmbH

Application Note Citrix

Introduction

Terms Glossary
Citrix Client

Transports Keyboard and Mouse input from a client computer to

a remote server, and transports Video output from the remote
server back to the client for display

Citrix Receiver

Newer name for the Citrix Client (for XenApp and XenDesktop)

Citrix Server

Makes a single application (XenApp published application) or

a whole Operating System (XenDesktop or XenApp desktop)
appear on the client machine as if they were installed and run
locally

CPS

Citrix Presentation Server, former name of XenApp.

Citrix declared end-of-life for CPS 4.0 and CPS 4.5

ICA

Independent Computing Architecture. Also the name of a

communication protocol used by Citrix products

ICA Client

Name of Citrix Client (v9/v10), e.g. used with CPS

TRACE32 Virtual Channel Driver

Citrix Client plug-in component: forwards data between a

TRACE32 instance running on a Citrix Server, and the
TRACE32 PODBUS USB driver on a Citrix Client.
Implemented as 32bit Windows DLL t32ctxvc.dll.

USB redirection

USB devices connected to a Citrix Client appear to applications

running on a Citrix Server as if they were connected locally.
The TRACE32 PODBUS USB driver is installed on the Server.

Virtual Channel Driver,

VC-Driver, VCD, VD

Citrix Client plug-in compont: provides added functionality

between Citrix Client and Citrix Server.

Virtual Machine,
VM

Simulated computer, usually running its own operating system

(OS) and applications.
Multiple VMs can run on the same physical machine.

XenApp

Citrix Server type: applications from multiple users run on one,

shared Windows Server (64bit) machine and can be used on
the Citrix Client as if they were a locally installed application.

XenDesktop

Citrix Server type: the whole desktop from a VM running the

user application(s) is used on the Citrix Client, the user works
on the VM as if it was the local machine.

XenServer

Runs and controls multiple VMs with XenDesktop inside.

Citrix product names and terms, e.g. Citrix, CPS, ICA, Citrix Receiver, XenApp, XenDesktop, etc.
are registered trademarks of Citrix Systems, Inc. and its subsidiaries.

1989-2016 Lauterbach GmbH

Application Note Citrix

Introduction

Contacting Support
LAUTERBACH GmbH
Altlaufstrasse 40
85635 Hoehenkirchen-Siegertsbrunn
Germany
Phone

(+49) 8102-9876-555

Fax

(+49) 8102-9876-187

Internet

http://www.lauterbach.com/tsupport.html or http://www.lauterbach.com/report.html
Here youll find local and special support addresses.

E-mail

support@lauterbach.com
General support address where your request will be answered within a short time if it is
a basic support request or redirected to the appropriate address.

Be sure to include detailed system information about your TRACE32 configuration.

1.

To generate a system information report, choose TRACE32 > Help > Support > Systeminfo.

NOTE:

Please help to speed up processing of your support request. By filling out the
system information form completely and with correct data, you minimize the
number of additional questions and clarification request e-mails we need to
resolve your problem.

2.

Preferred: click Save to File, and send the system information as an attachment to your e-mail.

3.

Click Save to Clipboard, and then paste the system information into your e-mail.

TRACE32 configuration examples

1989-2016 Lauterbach GmbH

Application Note Citrix

Introduction

Standalone USB Configuration

Just for reference, this is how TRACE32 is normally installed for USB.
Standalone
- Windows 7 / 32bit

TRACE32 GUI
t32marm.exe (32bit)
//config.t32
PBI=
USB

t32usb.sys TRACE32 USB Driver

TRACE32
PowerDebug
USB 2.0

Here is an example of a TRACE32 configuration file (config.t32) for USB:

;Environment Variables
OS=
ID=T32_USB395
TMP=D:\T32\temp
SYS=D:\T32
HELP=D:\T32\pdf
;Connection to device
PBI=
USB
;Printer Settings:
PRINTER=WINDOWS

1989-2016 Lauterbach GmbH

Application Note Citrix

Introduction

Citrix USB Redirection

XenDesktop 5.x supports USB redirection.
For this, TRACE32 installation requires no change from a normal standalone USB setup.
Just install everything on the Server (instead of on the Client).
Citrix Server

Citrix Client

- XenDesktop 5.6
- Windows 7 / 32bit

- Receiver for Windows 3.4

- Windows 7 / 32bit
Citrix Receiver for Windows 3.4

TRACE32 GUI
t32marm.exe (32bit)
//config.t32
PBI=
USB
network
t32usb.sys TRACE32 USB Driver

XenDesktop 5.6 (VDA)

TRACE32
PowerDebug
USB 2.0

NOTE:

XenApp versions up to XenApp 6.5 do not support USB redirection.

1989-2016 Lauterbach GmbH

Application Note Citrix

Introduction

Citrix USB Virtual Channel Driver

Citrix Virtual Channel protocol support was built into TRACE32 in 2007Q1 (for CPS 4.x).
To enable this interface method, install TRACE32 on the server, configure it for PBI=\nCITRIX (i.e. PBI=,
new line, CITRIX), and make sure the Citrix WinFrame API file wfapi.dll is available and loaded by
TRACE32 on start-up. (The name is wfapi.dll for TRACE32/32bit, and wfapi64.dll for TRACE32/64bit.)
On the client computer, you need the TRACE32 PODBUS USB device driver, the TRACE32
Virtual Channel Driver plug-in (t32ctxvc.dll), and you need to configure Citrix Receiver to use it.
Citrix Server

Citrix Client

- XenApp 6.5
- Win 2008 Server R2 / 64bit

- Receiver for Windows 3.4

- Windows 7 / 32bit
Citrix Receiver for Windows 3.4

TRACE32 GUI
t32marm.exe (32bit)

configuration
(Registry)

//config.t32
PBI=
CITRIX

t32ctxvc.dll
Virtual Channel
Driver

network
wfapi.dll - Citrix Server API

XenApp 6.5

t32usb.sys TRACE32 USB Driver

TRACE32
PowerDebug
USB 2.0

Here is an example of a TRACE32 configuration file (config.t32) for use in a Citrix environment:
;Environment Variables
OS=
ID=T32_CTX438
TMP=D:\T32\temp
SYS=D:\T32
HELP=D:\T32\pdf
;Connection to device
PBI=
CITRIX
;Printer Settings:
PRINTER=WINDOWS

[continued on next page]

1989-2016 Lauterbach GmbH

Application Note Citrix

Introduction

You can start with a simple USB configuration, and just replace the USB keyword with CITRIX, but please
dont forget the USB device driver:

NOTE:

On the Citrix Client - additionally to the Virtual Channel Driver configuration and
the DLL - you also the TRACE32 Lauterbach PODBUS USB device driver
installed.
Our installer will automatically install it when you select USB or CITRIX.
For manual installation (eg. on a remote client), you have two options:

from the TRACE32 DVD, start

\files\bin\windows\drivers\dpinstselect.exe

download and execute

http://www.lauterbach.com/faq/t32usb_setup.exe

To make things more interesting, ...

1.

...for Citrix Receiver to load the plug-in DLL, it needs to be compiled with a specific Citrix Virtual
Channel SDK version. This is why Citrix Receiver for Windows 3.4 will not work with an old
t32ctxvc.dll (built 2007 with VCSDK 2.3). Citrix does not provide a compatibility list (e.g. in Virtual
Channel SDK, up to v13) to indicate which Receiver version matches to which VC SDK version.

2.

...on Windows/64bit, the Citrix Receiver (32bit) configuration location in the registry differs from
Windows/32bit. This is undocumented (e.g. in the Virtual Channel SDK, up to v13).

3.

...the TRACE32 Citrix Virtual Channel Driver could not be tested.

To ensure smooth operation and installation, you need to test the virtual channel - and its setup - with
several Citrix Server products, and also with different Citrix Client versions.
However, there is no Citrix infrastructure for remote virtual channel testing, and no local dummy
virtual channel test method. As installing your own Citrix Server infrastructure - for regular virtual
channel testing - is very difficult, time consuming, and expensive, we could not afford to do it.
Therefore TRACE32 Citrix Virtual Channel installations can not be officially supported.
Many thanks to the unnamed Citrix FAE who tried out several TRACE32 versions in a remote
XenApp setup session, and to the unnamed Citrix and Lauterbach customer who made this possible.

1989-2016 Lauterbach GmbH

Application Note Citrix

Introduction

Citrix Receiver Configuration

To load and use a Virtual Channel Driver, Citrix Receiver for Windows must be properly configured.
There are four ways to configure Citrix Receiver for Windows:
1.

With the Lauterbach TRACE32 installation program (setup.exe from DVD 2013Q2 and later).

2.

With Group Policy Editor (gpedit.msc), with an appropriate policy template file.

3.

With Registry Editor (regedt32.exe), manually making the required entries and changes.

4.

With the Lauterbach TRACE32 Citrix Virtual Channel Installer (t32vcd_setup.exe).

Windows/32bit Registry Settings

First you need to copy the TRACE32 Virtual Channel Driver DLL from
%TRACE32_DVD%\files\bin\citrix\vdt32_v13\t32ctxvc.dll
into the Citrix program directory, e.g.
%ProgramFiles%\Citrix\ICA Client
Info: The matching policy template for the registry keys is vdtrace32.adm.
Enable (Lockdown Profile Setting):
Registry Key:
HKLM
\Software
\Policies
\Citrix
\ICA Client
\Engine
\Lockdown Profiles
\All Regions
\Lockdown
\Virtual Channels
\Thirdparty
\TRACE32
REG_SZ Entry Name:

Value:

VCEnable

true,false

1989-2016 Lauterbach GmbH

Application Note Citrix

Citrix Receiver Configuration

This tells the ICA 3.0 client about TRACE32:

Registry Key:
HKLM
\Software
\Citrix
\ICA Client
\Engine
\Configuration
\Advanced
\Modules
\ICA 3.0
REG_SZ Entry Name:

Value:

VirtualDriverEx

TRACE32

And this tells the client about the DLL:

Registry Key:
HKLM
\Software
\Citrix
\ICA Client
\Engine
\Configuration
\Advanced
\Modules
\TRACE32
REG_SZ Entry Name:

Value:

DriverName

Unsupported

DriverNameWin16

Unsupported

DriverNameWin32

t32ctxvc.dll

To disable the Virtual Channel Driver, just set VirtualDriverEx to an empty string.

1989-2016 Lauterbach GmbH

Application Note Citrix

10

Citrix Receiver Configuration

Windows/64bit Registry Settings

Citrix Receiver for Windows 3.4 is a 32bit program. This has the advantage that it can load the 32bit Virtual
Channel Driver DLL, but unfortunately 64bit Windows redirects any 32bit registry settings.

NOTE:

The official Citrix Virtual Channel SDK (Version 13 was current in 2013Q1) does
not mention the Citrix Client installation on Windows/64bit.

First you need to copy the TRACE32 Virtual Channel Driver DLL from
%TRACE32_DVD%\files\bin\citrix\vdt32_v13\t32ctxvc.dll
into the Citrix (32bit!) program directory, e.g.
%ProgramFiles(x86)%\Citrix\ICA Client
Info: The matching policy template for the registry keys is vdtrace32-win64.adm.
Enable (Lockdown Profile Setting):
Registry Key:
HKLM
\Software
\Wow6432Node
\Policies
\Citrix
\ICA Client
\Engine
\Lockdown Profiles
\All Regions
\Lockdown
\Virtual Channels
\Thirdparty
\TRACE32
REG_SZ Entry Name:

Value:

VCEnable

true,false

1989-2016 Lauterbach GmbH

Application Note Citrix

11

Citrix Receiver Configuration

This tells the ICA 3.0 client about TRACE32:

Registry Key:
HKLM
\Software
\Wow6432Node
\Citrix
\ICA Client
\Engine
\Configuration
\Advanced
\Modules
\ICA 3.0
REG_SZ Entry Name:

Value:

VirtualDriverEx

TRACE32

And this tells the client about the DLL:

Registry Key:
HKLM
\Software
\Wow6432Node
\Citrix
\ICA Client
\Engine
\Configuration
\Advanced
\Modules
\TRACE32
REG_SZ Entry Name:

Value:

DriverName

Unsupported

DriverNameWin16

Unsupported

DriverNameWin32

t32ctxvc.dll

To disable the Virtual Channel Driver, just set VirtualDriverEx to an empty string.

1989-2016 Lauterbach GmbH

Application Note Citrix

12

Citrix Receiver Configuration

ICA Client 9.x - module.ini settings

This method is deprecated with ICA Client 10.x and later. It is only listed here for completeness.
1.

Copy \files\bin\citrix\vdt32_v10\t32ctxvc.dll from the TRACE32 DVD into the

Citrix program directory (default is %ProgramFiles%\Citrix\ICA Client).

2.

In the ICA Client "module.ini" file (in the Citrix program directory), add the VC driver module:
a. In the section "[ICA 3.0]", in the line "VirtualDriver=", append ",Trace32" at the end
b. In the section "[VirtualDriver]", add a line with value "Trace32 ="
c. Add this new section to "module.ini":
;***********************************************
;** Lauterbach Trace32 USB Virtual Driver (VD)
;***********************************************
[Trace32]
DriverName
= Unsupported
DriverNameWin16
= Unsupported
DriverNameWin32
= T32CTXVC.DLL
;***end***

To disable the Virtual Channel Driver, just remove ,TRACE32 from the end of VirtualDriver=.

1989-2016 Lauterbach GmbH

Application Note Citrix

13

Citrix Receiver Configuration

Installer-based Configuration - Algorithm

This is the algorithm used by the TRACE32 DVD installer (setup.exe, 2013Q2 and later):
1.

Set variable [CITRIXBASE] to key HKLM\SOFTWARE\Win6432Node\Citrix.

Check registry if [CITRIXBASE] exists: if yes, continue with #4

2.

Set variable [CITRIXBASE] to key HKLM\SOFTWARE\Citrix.

Check registry if [CITRIXBASE] exists: if yes, continue with #4

3.

Prompt user Could not find Citrix Receiver installation. For more information, see
<DVD>\files\bin\app_citrix.pdf and END_CITRIX_PHASE

4.

Get REG_DWORD value [CITRIXBASE]\ICA Client\Engine\Configuration\Version Maximum.

If (value does not exist) or (the value is below 10000 (0x2710)), continue with #3

5.

Get registry key [CITRIXBASE]\Install\ICA Client. Read REG_SZ value InstallFolder and set
variable [CITRIXDIR] to it. If the key or the directory [CITRIXDIR] do not exist, continue with #3

6.

Copy <DVD>\files\bin\citrix\vdt32_v13\t32ctxvc.dll to [CITRIXDIR]

7.

Create registry key

HKLM\SOFTWARE\Policies\Citrix\ICA Client\Engine\Lockdown Profiles\All Regions\Lockdown\
Virtual Channels\Thirdparty\TRACE32
and create a REG_SZ entry with name VCEnable" and value true,false

8.

Create registry key

[CITRIXBASE]\ICA Client\Engine\Configuration\Advanced\Modules\TRACE32
and create three entries in it:

9.

create REG_SZ entry with name DriverName and value Unsupported

10.

create REG_SZ entry with name DriverNameWin16 and value Unsupported

11.

create REG_SZ entry with name DriverNameWin32 and value t32ctxcv.dll

12.

Get registry key

[CITRIXBASE]\ICA Client\Engine\Configuration\Advanced\Modules\ICA 3.0
and set REG_SZ entry name VirtualDriverEx to value TRACE32

13.

END_CITRIX_PHASE

NOTE:

This is only the required minimum. Additional checks may be helpful (e.g. for file
copy success or failure, or if another pre-existing third-party Virtual Channel would
be disabled).

1989-2016 Lauterbach GmbH

Application Note Citrix

14

Citrix Receiver Configuration

TRACE32 Citrix Virtual Channel Installer (NSIS)

To make installation easier for our customers, we experimented with the Nullsoft Scriptable Install System to
create a Lauterbach TRACE32 Citrix Virtual Channel Installer:

The name of the executable is t32vcd_setup.exe (Windows 32bit executable).

The installer contains a manifest to request admin rights for installation, and is MS AuthentiCodesigned with our Class-3 Code Signing Certificate.

This installer only installs the Virtual Channel Driver, the TRACE32 PODBUS USB driver for our
USB devices needs to be installed separately. (Either from DVD, or you can download an installer
from our Lauterbach website.)

The next sections show the relevant NSIS script elements. For sake of brevity, part of the error reporting and
the uninstaller installation (and removal) are omitted.

NOTE:

The NSIS scripting language allows to define the Registry View (32bit or 64bit) for
the installer. If this is defined as SetRegView 32, when installing on
Windows 64bit, all registry settings in HKLM\SOFTWARE are redirected to
HKLM\SOFTWARE\Wow6432Node, making it unnecessary to distinguish between
Windows 32bit/64bit variants.

Preamble and setup

# Nullsoft Scriptable Install System (NSIS) script
# for Lauterbach TRACE32 CITRIX Virtual Channel Driver
# Copyright Lauterbach GmbH, written by Hagen Patzke
Name "TRACE32 Virtual Channel Driver"
BrandingText "Lauterbach TRACE32"
OutFile t32vcd_setup.exe
RequestExecutionLevel admin
InstalLDir $TEMP
InstallDirRegKey HKLM "SOFTWARE\Citrix\Install\ICA Client"
"InstallFolder"
Icon t32ctxvc.ico
UninstallIcon t32ctxvc.ico
CRCCheck force
InstallColors /windows
XPStyle on
# Add version information to installer executable [REMOVED]

1989-2016 Lauterbach GmbH

Application Note Citrix

15

Citrix Receiver Configuration

Install section
Section "Install"
StrCpy $R9 "SOFTWARE\Citrix\ICA Client\Engine\Configuration"
SetRegView 32 # set 32bit view for Windows/64bit systems
# read client max version entry
ClearErrors
ReadRegDWORD $R0 HKLM "$R9" "Version Maximum"
IfErrors 0 lbl_found # if key not found -> error
lbl_version:
DetailPrint "ERROR: Citrix Receiver Installation not found"
lbl_abort:
SetDetailsView show
Abort "ERROR: installation failed"
Goto lbl_done
lbl_found:
IntCmp $R0 10000 0 lbl_version 0 # if Client older than v10.0 -> error
# Install file(s)
SetOutPath $INSTDIR
File t32ctxvc.dll
# Register Virtual Channel Driver in Citrix Configuration Store
StrCpy $R1 $R9 "\Advanced\Modules\TRACE32"
WriteRegStr
HKLM "$R1" "DriverNameWin"
"Unsupported"
WriteRegStr
HKLM "$R1" "DriverNameWin16" "Unsupported"
WriteRegStr
HKLM "$R1" "DriverNameWin32" "t32ctxvc.dll"
StrCpy $R2 $R9 "\Advanced\Modules\ICA 3.0"
WriteRegStr
HKLM "$R2" "VirtualDriverEx" "TRACE32"
# Set Lockdown Policy
WriteRegStr
HKLM "SOFTWARE\Policies\Citrix\ICA
Client\Engine\Lockdown Profiles\All Regions\Lockdown\Virtual
Channels\Thirdparty\TRACE32" "VCEnable" "true,false"
IfErrors 0 lbl_unin
DetailPrint "ERROR: Can't write registry entries"
Goto lbl_abort
lbl_unin: # Install the Uninstaller [REMOVED]
lbl_done:
SectionEnd

1989-2016 Lauterbach GmbH

Application Note Citrix

16

Citrix Receiver Configuration

Uninstall section
Section "Uninstall"
SetRegView 32 # set 32bit view for Windows/64bit systems
Delete "$INSTDIR\t32ctxvc.dll"
WriteRegStr
HKLM "SOFTWARE\Citrix\ICA
Client\Engine\Configuration\Advanced\Modules\ICA 3.0" "VirtualDriverEx"
""
DeleteRegKey HKLM "SOFTWARE\Citrix\ICA
Client\Engine\Configuration\Advanced\Modules\TRACE32"
DeleteRegKey HKLM "SOFTWARE\Policies\Citrix\ICA
Client\Engine\Lockdown Profiles\All Regions\Lockdown\Virtual
Channels\Thirdparty\TRACE32"
# Uninstall the Uninstaller[REMOVED]
SectionEnd

Silent Installation
The command line parameter /S switches to silent installation mode:
C:\TEST> t32vcd_setup.exe /S

In silent mode, there will be no output, but these Error Levels are set:

0 - Normal execution (installation successfull)

2 - Installation aborted by script (ERROR: installation failed)

Please note:

The installer contains a manifest to request admin rights for installation, and is MS AuthentiCodesigned with our Class-3 Code Signing Certificate. It might be useful to add the Lauterbach
Certificate to the Trusted Publishers Certificate Store and distribute this to your clients.

The TRACE32 PODBUS USB driver for our USB devices needs to be installed separately.
(The necessary files are on our DVD, or can be downloaded from our website.)

1989-2016 Lauterbach GmbH

Application Note Citrix

17

Citrix Receiver Configuration

Miscellaneous Information
The upcoming XenApp 7.0 release (codename Excalibur) will reportedly support USB redirection.
Using a debugger over a high-latency connection can result in severe performance degradation. If you plan
to use such a setup, please contact support for advice.

1989-2016 Lauterbach GmbH

Application Note Citrix

18

Miscellaneous Information