(Page 1 of 1 in this chapter)

Chapter 4

agmon, the AG Loader/Monitor

4.1 Introduction

4.2 Command Line Use and Options

4.3 Board Configuration Summary File

4.4 Error Reporting

4.5 How agmon Finds Files

4.6 Running agmon as a Windows NT Service

: 4.6.1 Configuring and Installing the agmon Service
: 4.6.2 Changing the AG Configuration
: 4.6.3 Rebooting AG Boards
: 4.6.4 Removing the agmon Service
: 4.6.5 Debugging With the Windows NT agmon Service

4.7 The AGM Library

4.1 Introduction

This chapter provides detailed information about the AG loader/monitor, agmon. This utility performs the following functions: Downloads firmware to each AG board. Configures each AG board in a system. Monitors each AG board for errors detected by the driver(s) or firmware.
For UNIX, it performs the following additional functions: Creates and controls STREAMS links among the AG device drivers. Reports errors detected by the firmware and drivers. Note: For Windows NT: Leave agmon running in monitor mode whenever AG boards are being used so that low-level AG error messages are reported and recorded in a log file. For UnixWare and Solaris: agmon must be left running whenever AG boards are being used, because it controls the STREAMS links among the AG device drivers. To accommodate this requirement, invoke agmon in its own virtual terminal or as a daemon process. agmon is also necessary for reporting low-level errors.
Any CT Access applications using AG boards must be restarted if agmon is restarted. agmon cannot shutdown and start hardware drivers until all applications close connections to the drivers.

4.2 Command Line Use and Options

This section describes the agmon command line options for each operating system. Option Operating System Description -a All Parallel load. Loads all MVIP clock masters in parallel, then loads remaining boards in parallel. -b UnixWare Solaris Background. Executes agmon as a daemon process. This is useful when agmon is invoked during your system's initialization by the init process. -c UnixWare Solaris Check and configure AG device drivers. Checks the AG boards' hardware configuration as defined in the AG configuration file for: · Consistency with your UNIX system configuration. · Hardware conflicts with other devices configured in your system. agmon adds the AG device drivers to your UNIX system configuration if it finds that they are not a part of the system configuration. agmon also updates the drivers' configurations if an inconsistency with your UNIX system configuration is detected. The -c command line option must be specified when: · The AG device drivers are first added to your UNIX system configuration. · An AG board is added to your system. · An AG board is removed from your system. · The interrupt shared by the AG boards in your system is changed. · The I/O address of an AG board is changed. -d level All Diagnostic level. Defines the relative degree of diagnostics run when the boards are initialized. The -d command line option has precedence over the Diagnostics statement in your AG configuration file. level can be one of the following values: · 0 No diagnostics · 1 Minimal diagnostics · 2 Moderate diagnostics (default) · 3 Maximum diagnostics -e filename All Error log file. Specifies the file to which errors are logged. If a directory is not specified in filename, the current working directory is used. Errors that occur are displayed by agmon on the screen and appended to the error log file. The default error log file is: Windows NT: .\agerror.log UNIX: /var/opt/nms/ag/agerror.log -f filename All AG configuration file. Defines filename as the AG configuration file. · Windows NT: If a directory is not specified in filename, agmon searches for filename in the current working directory and then in the directories specified in the AGLOAD environment variable. The default AG configuration file is ag.cfg · UNIX: If a directory is not specified in filename, agmon searches for filename in the current working directory and then in the directory /opt/nms/ag/cfg. The default AG configuration file is/opt/nms/ag/cfg/ag.cfg. -l All Load only. agmon exits after checking the configuration and loading the AG boards. The exit code is 0 if all boards load successfully; otherwise, it is non-zero. -m All Monitor only. agmon does not attempt to reset or load any boards, but enters the monitor mode immediately. Any AG error messages that occur after agmon startup are displayed on the screen and written to the error log file. -r UnixWare Solaris Remove AG device drivers. Removes the AG device drivers from your UNIX system configuration. -s All Shutdown only. agmon shuts down another instance of the monitor if there is another running instance. agmon does not load or monitor the AG boards, but exits immediately. -z size UnixWare Solaris Coprocessor software download size. Defines how to partition the AG coprocessor software for downloading. The size of each partition is size bytes. The default partition size is 29952 bytes. -? All Help. Displays a summary of command line options.

Option	Operating System	Description
-`a`	All	Parallel load. Loads all MVIP clock masters in parallel, then loads remaining boards in parallel.
`-b`	UnixWare Solaris	Background. Executes `agmon` as a daemon process. This is useful when `agmon` is invoked during your system's initialization by the `init` process.
`-c`	UnixWare Solaris	Check and configure AG device drivers. Checks the AG boards' hardware configuration as defined in the AG configuration file for: · Consistency with your UNIX system configuration. · Hardware conflicts with other devices configured in your system. `agmon` adds the AG device drivers to your UNIX system configuration if it finds that they are not a part of the system configuration. `agmon` also updates the drivers' configurations if an inconsistency with your UNIX system configuration is detected. The `-c` command line option must be specified when: · The AG device drivers are first added to your UNIX system configuration. · An AG board is added to your system. · An AG board is removed from your system. · The interrupt shared by the AG boards in your system is changed. · The I/O address of an AG board is changed.
`-d` level	All	Diagnostic level. Defines the relative degree of diagnostics run when the boards are initialized. The `-d` command line option has precedence over the Diagnostics statement in your AG configuration file. level can be one of the following values: · 0 No diagnostics · 1 Minimal diagnostics · 2 Moderate diagnostics (default) · 3 Maximum diagnostics
`-e` filename	All	Error log file. Specifies the file to which errors are logged. If a directory is not specified in filename, the current working directory is used. Errors that occur are displayed by `agmon` on the screen and appended to the error log file. The default error log file is: Windows NT: `.\agerror.log` UNIX: `/var/opt/nms/ag/agerror.log`
`-f` filename	All	AG configuration file. Defines filename as the AG configuration file. · Windows NT: If a directory is not specified in filename, `agmon` searches for filename in the current working directory and then in the directories specified in the `AGLOAD` environment variable. The default AG configuration file is `ag.cfg` · UNIX: If a directory is not specified in filename, `agmon` searches for filename in the current working directory and then in the directory `/opt/nms/ag/cfg`. The default AG configuration file is`/opt/nms/ag/cfg/ag.cfg.`
`-l`	All	Load only. `agmon` exits after checking the configuration and loading the AG boards. The exit code is 0 if all boards load successfully; otherwise, it is non-zero.
`-m`	All	Monitor only. `agmon` does not attempt to reset or load any boards, but enters the monitor mode immediately. Any AG error messages that occur after `agmon` startup are displayed on the screen and written to the error log file.
`-r`	UnixWare Solaris	Remove AG device drivers. Removes the AG device drivers from your UNIX system configuration.
`-s`	All	Shutdown only. `agmon` shuts down another instance of the monitor if there is another running instance. `agmon` does not load or monitor the AG boards, but exits immediately.
`-z` size	UnixWare Solaris	Coprocessor software download size. Defines how to partition the AG coprocessor software for downloading. The size of each partition is size bytes. The default partition size is 29952 bytes.
`-?`	All	Help. Displays a summary of command line options.

4.3 Board Configuration Summary File

Each time it is run, agmon generates a summary of the AG boards' configurations, including the names of files downloaded, the AG hardware configurations, and any errors that occurred during loading. agmon, by default, creates or overwrites an output file to hold the configuration record each time it is run. An alternative output file can be specified with the AG configuration file ReportFile statement or with the -p option to agmon. The default output file is: Windows NT: .\ag.rpt UnixWare and Solaris: /var/opt/nms/ag/ag.rpt

4.4 Error Reporting

agmon displays errors to the screen and appends them to an error log file. The error log file remains open for one second after an error is written. An alternative error log file can be specified with the -e command line option to agmon. The default error log file is: Windows NT: .\agerror.log UnixWare and Solaris: /var/opt/nms/ag/agerror.log

4.5 How agmon Finds Files

The on-board software downloaded to the AG boards is specified by DSP_OS, AG2DSP_OS, DspFile, AG2DSPFile, LoadFile, RunFile, RunModule, and TCP statements in your AG configuration file. If the filename value specified in the statement contains a directory specification, agmon only looks for filename. Otherwise, agmon first looks in the current working directory. Windows NT: If the file does not exist in the current working directory, agmon looks in the directories specified by the AGLOAD environment variable. UnixWare and Solaris: If the file does not exist in the current working directory, agmon looks in /opt/nms/ag/load.

4.6 Running agmon as a Windows NT Service

agmon may be configured as a Windows NT service which can be started automatically when the system boots. Note: When using the Point-to-Point Switching service, agmon must be configured as a Windows NT service.
There are three utility programs which are used with the Windows NT agmon service: Utilities Description agcfg Configures the agmon Windows NT service and the AG drivers. agmsvc Provides the service, i.e., downloading and monitoring of AG boards. agreboot Reboots specified boards.

Utilities	Description
`agcfg`	Configures the `agmon` Windows NT service and the AG drivers.
`agmsvc`	Provides the service, i.e., downloading and monitoring of AG boards.
`agreboot`	Reboots specified boards.

4.6.1 Configuring and Installing the agmon Service

The agcfg utility installs (i.e., registers and configures) the service.
To install the Windows NT agmon service enter:
agcfg -install
The agmon service is initially configured for manual startup. It can be started and stopped via:

The Control Panel's Services applet

The NET command

The SC service controller utility provided with the Win32 SDK

An application via StartService()

Another NT service that lists the agmon service as one of its dependencies
The Windows NT agmon service can be configured to automatically start after a system reboot via the Control Panel's Services applet.
agcfg install options: Option Description -f<file> -e<file> -p<file> -l -m -q -d<val> -x<val> -v<val> -z<bytes> -N<dir> -I<file> -V<val> AG Configuration file. Default: <NMS dir>\ag\cfg\ag.cfg Error log file. Default: <NMS dir>\ag\agerror.log Report file. Default: <NMS dir>\ag\ag.rpt Load only: exit after booting boards. Monitor only: don't boot any boards. Quiet: do not display board printfs. A diagnostic level or bitmask. A tracing bitmask, cf. agtrace. Like -x, but does not take effect until board is booted. Block size for downloads. Default: 0x7500 NMS installation directory. Default: c:\nms Image path for the service. Default: c:\nms\bin\agmsvc.exe A verbosity level (1-3). Default: 0.

Option	Description
`-f`<file> `-e`<file> `-p`<file> `-l` `-m` `-q` `-d`<val> `-x`<val> `-v`<val> `-z`<bytes> `-N`<dir> `-I`<file> `-V`<val>	AG Configuration file. Default: <NMS dir>`\ag\cfg\ag.cfg` Error log file. Default: <NMS dir>`\ag\agerror.log` Report file. Default: <NMS dir>`\ag\ag.rpt` Load only: exit after booting boards. Monitor only: don't boot any boards. Quiet: do not display board printfs. A diagnostic level or bitmask. A tracing bitmask, cf. agtrace. Like `-x`, but does not take effect until board is booted. Block size for downloads. Default: 0x7500 NMS installation directory. Default: `c:\nms` Image path for the service. Default: `c:\nms\bin\agmsvc.exe` A verbosity level (1-3). Default: 0.

4.6.2 Changing the AG Configuration

The configuration of the AG drivers records some parts of the AG configuration (including interrupts and board addresses) in the Windows NT registry. Other parts (such as what files to download) are not stored in the registry, but are read from the configuration file each time the agmon service is started. For some changes, but not for all, it is sufficient to stop and restart the service.
To change the AG configuration:

Select Services from the Control Panel.

Highlight AGMON.

Select Stop to stop the agmon service.

Make the changes to the AG configuration file.

Reconfigure the service by entering:

agcfg -reconfig

Restart the agmon service by selecting Services from the Control Panel, highlighting AGMON, and selecting Start.

4.6.3 Rebooting AG Boards

Once the agmon service is running, the agreboot utility can be used to selectively reboot boards. For example, to reboot boards 1 and 5:
agreboot 1 5

4.6.4 Removing the agmon Service

If you remove CT Access, you must first remove the agmon service.
To remove the agmon service:
agcfg -remove

4.6.5 Debugging With the Windows NT agmon Service

The agmon service reports system errors, warnings, and informational messages to the Event Logging service (where they can be viewed with the Event Viewer from the Administrative Tools menu). More detailed information and AG messages are recorded in the error log file.
The agmon service is normally run directly by the Service Control Manager (SCM) and not from the command line. However, for debugging, it can be run as a console application by entering:
agmsvc -debug

4.7 The AGM Library

The AGM library provides an application programming interface (API) for initialization and monitoring AG boards.
With the AGM library you can create a program that: Reads the AG configuration file. Installs the device drivers. Boots the boards. Downloads files to the boards.
agmon is built using this library.
See the AGM Library Developer's Reference Manual for a list of the AGM library functions. Note: In CT Access 2.1, agmon is updated to support Hot Swap boards. Hot Swap applications which use the AGM library to initialize boards need to include Hot Swap support. See the Hot Swap Manager Developer's Reference Manual for details.

(Page 1 of 1 in this chapter)

tech_support@nmss.com