Memento Documentation - Euresysdownloads.euresys.com/PackageFiles/MEMENTO/6.1.518/98064823… ·...

DOCUMENTATION

MementoMemento 6.1.1

© EURESYS s.a. 2016 - Document version 6.1.518 built on 2016-09-28

EURESYS s.a. shall retain all property rights, title and interest of the documentation of the hardware and the soware,and of the trademarks of EURESYS s.a. All the names of companies and products mentioned in the documentation maybe the trademarks of their respective owners. The licensing, use, leasing, loaning, translation, reproduction, copying ormodification of the hardware or the soware, brands or documentation of EURESYS s.a. contained in this book, is notallowed without prior notice. EURESYS s.a. may modify the product specification or change the information given in thisdocumentation at any time, at its discretion, and without prior notice. EURESYS s.a. shall not be liable for any loss of ordamage to revenues, profits, goodwill, data, information systems or other special, incidental, indirect, consequential orpunitive damages of any kind arising in connection with the use of the hardware or the soware of EURESYS s.a. or resultingof omissions or errors in this documentation.

Contents Memento 6.1.1 Documentation

Contents

About This Document.....................................................................................................................................................5Document History........................................................................................................................................................................5Document Structure.................................................................................................................................................................... 5

Memento Concepts...........................................................................................................................................................6Abstract........................................................................................................................................................................................ 6Block Diagram..............................................................................................................................................................................7Memento Contributors................................................................................................................................................................ 7Memento Messages..................................................................................................................................................................... 8

Message Body.......................................................................................................................................................................... 8Message Attributes.................................................................................................................................................................. 8

Memento Time Scale.................................................................................................................................................................11UTC vs. Memento Time......................................................................................................................................................... 11

Memento Driver......................................................................................................................................................................... 12Memento Ring Buffer............................................................................................................................................................ 12Ring Buffer Filter....................................................................................................................................................................13Ring Buffer Configuration..................................................................................................................................................... 14

Memento Application................................................................................................................................................................ 14Memento Viewer........................................................................................................................................................................ 15

Block Diagram........................................................................................................................................................................15Viewer Buffer..........................................................................................................................................................................16Verbosity Filter.......................................................................................................................................................................16Highlighting Filters................................................................................................................................................................ 17Message List........................................................................................................................................................................... 18

Memento Dump......................................................................................................................................................................... 19Data Selection........................................................................................................................................................................19Dump Files Management...................................................................................................................................................... 19

Memento User Guide................................................................................................................................................... 21Memento Installation................................................................................................................................................................ 21Memento Driver Setup.............................................................................................................................................................. 21

Changing the Configuration..................................................................................................................................................22Starting Memento GUI...............................................................................................................................................................22Main Window Layout.................................................................................................................................................................23

Controls Bar........................................................................................................................................................................... 23Activity Plot............................................................................................................................................................................30Message Plot.......................................................................................................................................................................... 30Message List........................................................................................................................................................................... 32Status Bar...............................................................................................................................................................................34

iii

Memento 6.1.1 Documentation Contents

Memento Reference...................................................................................................................................................... 35Memento Command Line......................................................................................................................................................... 35

COMMAND.............................................................................................................................................................................. 35OPTIONS.................................................................................................................................................................................36FILE......................................................................................................................................................................................... 39

Command Line Samples........................................................................................................................................................... 39

iv

About This Document Memento 6.1.1 Documentation

About This DocumentThis document gathers all the publicly available documentation of Memento.

Document HistoryDate Document

Version Description

2016-07-04 4.7 Memento 4.7 Documentation



2016-09-27 6.1

Memento 6.1.1 DocumentationDocument updates:

• Memento Contributors on page 7: Updated "User Application" section.• Memento Contributors on page 7: Added "EGrabber" section.• Kind Attribute on page 9: Updated list.

Document StructureThe main sections of this document are:

• Memento Concepts on page 6• Memento User Guide on page 21• Memento Reference on page 35

5

Memento 6.1.1 Documentation Memento Concepts

Memento ConceptsWhat is Memento?

Figure 1: Memento Logo

AbstractMemento is an advanced event message logging system that greatly facilitates the debugging of machine vision applicationsusing Euresys frame grabbers.Memento is a set of soware tools allowing:

• Kernel drivers and user space applications – Memento Contributors – to inject trace messages – Memento Messages –into a common memory area – the Memento Ring Buffer.

• Memento Contributors to time-stamp Memento messages using a common time scale – Memento Time Scale.• To view selected sets of recent- or past- Memento Messages using the Memento Viewer function• To dump Memento data from the Memento Ring Buffer to disk using the Memento Dump function

The Memento soware package has two main components:

• A kernel-mode driver: Memento Driver.• A user-mode application: Memento Application.

Related InformationBlock Diagram on page 7Memento Contributors on page 7Who generates Memento messages?

Memento Messages on page 8What does a Memento message contain?

Memento Ring Buffer on page 12Memento message store.

Memento Time Scale on page 11Common time scale for time-stamping Memento messages.

Memento Viewer on page 15Message viewing function of the Memento Application.

Memento Dump on page 19Messages data dump function of the Memento Application.

Memento Driver on page 12Kernel-mode driver managing the Memento Ring Buffer.

Memento Application on page 14

6

Memento Concepts Memento 6.1.1 Documentation

User-mode Memento application.

Block Diagram

Highlighting Filters

Viewer Buffer

Verbosity Filter

Memento Driver

Input Filter

Ring Buffer

Memento Application – GUI ModeContributors

Coaxlink driver & library

User application

Memento application

Display

Memento Configuration

Data Selection Filter

Memento Application – DUMP Mode

Disk


Viewer Buffer

Verbosity Filter

Memento Application – VIEW Mode

Console

Figure 2: Memento Function Blocks and Data Flow

Memento ContributorsWho generates Memento messages?

The Memento Contributors are Euresys kernel drivers and Euresys or third-party user space applications embeddingMemento Traces at particular code locations.

Note: A Memento Trace is a non-blocking and lightweight software macro that, upon execution, builds up amessage and pushes it into the Memento Ring.

7


Coaxlink Driver & LibraryThe Coaxlink Driver soware package is a major message contributor. For instance, Coaxlink Driver 4.7 includes ~1,000distinct instances of Memento Traces!All the Coaxlink products implement Memento-in-hardware. This feature allows hardware events to be logged in Mementowith an accurate time attribute.

User ApplicationA user application may include Memento Traces capable of generating messages having a custom content and two attributes:kind and level.

New Any severity level can be assigned to the level attribute.New . Sixteen (16) distinct values are available for the kind attribute:user0, … user9, … userA, … userF.

Note: The value user is kept for backward capability; it is equivalent to user0.

EGrabber New

The EGrabber API layer generates Memento Traces with the Egrabber kind attribute.

Memento ApplicationThe Memento Application also acts as a message contributor since it may inject "UTC Time" messages.

Memento MessagesWhat does a Memento message contain?

A Memento message is composed of a message body and several message attributes.

Message BodyThe message body is a text string composed of a fixed frame and optional arguments. The arguments are used asplaceholders for variable context information.Message body examples:

• The following message body has no arguments:

GenICam module has been unloaded

• The following message body has two arguments, the date and the time:

Time: 2016-04-22 14:43:29.0493338 UTC

Message AttributesMessage attributes are used for qualifying the message body.

Mandatory AttributesThe Kind and Level attributes are mandatory.They must always be defined by the Memento Contributors.

8


Optional AttributesThe Time, Process ID, Thread ID, Card ID, and Connector ID attributes are optional.The Memento Contributors decide whether or not to use them.

Level AttributeThe Level attribute defines the severity level of the message on a scale having 7 steps:

Level Attribute Values

Value Severity Description

Critical Highest Unrecoverable error message

Error Higher Error message

Warning High Warning message

Notice Medium Notification message

Info Low Information message

Debug Lower Debug message

Verbose Lowest Nattering

Note: Debug and verbose levels are used for messages intended for Euresys engineering and technicalsupport.

Kind AttributeThe mandatory Kind attribute defines the kind, nature, origin … of the message:

Kind Attribute Values

Value Description

API API function calls.

Acquisition Messages related to image acquisition (e.g., data stream start/stop, start/end of scan).

CoaXPress Messages related to CoaXPress protocol (e.g., device discovery, control messages).

DMA Messages related to DMA (Direct Memory Access) transfers.

DPC Messages related to DPC (Deferred Procedure Calls) queued by the driver when it receives an interruptrequest.

Descriptors Messages related to DMA descriptors.

EEPROM Messages related to on-board EEPROM (where part number, serial number and OEM key are stored).

New Egrabber Messages produced by EGrabber.

Event Messages related to the event notification infrastructure.

9


Value Description

FPGA

Messages related to

• Firmware image.

• CIC (Camera and Illumination Controller).

Flash Messages related to the on-board flash memory (where the firmware image is stored).

GenAPI Messages related to Euresys GenApi implementation.

Hardware Messages emitted by the Coaxlink firmware.

I2C Messages related to the I2C communication between 2 components on the Coaxlink cards.

IOCTL Messages related to the communication between user-mode soware components and the Coaxlink kerneldriver.

IRQ Messages related to the interrupt requests received by the Coaxlink kernel driver.

Memento Messages related to Memento.

OperationM Messages related to an internal soware component (should not appear on customers machines).

PCI Express Messages related to the PCI Express configuration space (e.g., vendor and device IDs, capabilities).

PnP Messages related to the interaction between the Coaxlink driver and the Windows Plug and Play Manager.

Power Messages related to the interaction between the Coaxlink driver and the Windows Power Manager.

Profiling A small number of messages for doing profiling (IRQ counter, time spent with interrupts masked, DPCcounter, time spent in DPC, buffer push/pop and DMA transfer completion).

SPI Messages related to the SPI interface (used to access the on-board flash).

Script Messages related to the GenApi scripts.

Serial Line Messages related to the Camera Link serial communication.

Thread Messages related to worker threads used by the Coaxlink driver.

New Time Messages related to system data and time.

New User0 … User9,UserA ... UserF

Messages emitted by the user application.

Note: The above list is open; new values can be appended in future Memento releases.

Time AttributeFor all but the hardware kind of messages, the time attribute defines the time of occurrence on the Memento Time Scaleof the creation of the message by the contributor.For hardware kind of messages, the time attribute defines the time of occurrence on the Memento Time Scale of thehardware event that is at the origin of the message. These messages are prefixed by [ts:HARDWARE_TIMESTAMP] whereHARDWARE_TIMESTAMP is the time of occurrence on the card local time scale.

Note: The time of occurrence reported by the hardware using the card local time is converted to Mementotime.

10


Process ID & Thread ID AttributesThe Process ID attribute reports the process identifier of the process producing the message.The Thread ID attribute reports the thread identifier of the thread producing the message.

Card ID & Connector ID AttributesThe Card ID attribute reports the identifier of the frame grabber card the message belongs to.

Note: For Coaxlink cards, the Card ID is the zero-based GenTL Interface index.

The Connector ID attribute reports the identifier of the camera connector the message belongs to.

Note: For Coaxlink cards, the Connector ID is the ID (A, B, C, D) of the CoaXPress host interface connector.

Memento Time ScaleCommon time scale for time-stamping Memento messages.

The Memento Time Scale is a common time scale used for time-stamping all the Memento Messages produced by theMemento Contributors within a Host PC.

Note: Having a common time scale is a key feature of Memento since it allows messages from differentorigins to be time-coordinated!

The Memento Time Scale:

• Resets at the cold boot of the Host PC.• Increments by 1 every microsecond.• Never overflows thanks to a 64-bit quantification.

Note: Memento uses the Performance Counter of the Host PC to build the Memento Time Scale.Consequently, its accuracy and its stability are Host PC dependent!

Note: For Windows users only:The Memento Time Scale is not reset when Windows performs a Fast Boot,even after a Power Off! When the Fast Boot option is activated, the only way to reset the Memento TimeScale, is to perform a Windows Restart.

UTC vs. Memento TimeWhen a Coaxlink card is installed in the Host PC, the Coaxlink Driver generates every minute an UTC time message:

Time: 2016-04-22 14:43:29.0493338 UTC

Such message allows for establishing the relationship between the UTC (Coordinated Universal Time) and the MementoTime.The time reported in the above message is actually the Host PC time of the local time zone converted to the UTC time zone.

Note: The accuracy of the reported UTC time depends on the Host PC. When the Host PC implements asynchronization mechanism to Internet time servers, the UTC time accuracy is pretty good!

11


Memento DriverKernel-mode driver managing the Memento Ring Buffer.

The Memento Driver is responsible for managing the Memento Ring Buffer: a region of the Host PC memory where theMemento Contributors store the Memento Messages.The Coaxlink Driver automatically connects to the Memento Driver.Once the connection is established, the messages composed by the contributors are first screened by the Ring Buffer Filteraccording to the Ring Buffer Configuration settings.Only the messages that successfully pass through the Ring Buffer Filter filter are effectively written into the Memento RingBuffer.

Memento Ring BufferMemento message store.

The Memento Ring Buffer is an area of the Host PC memory where the Memento messages are written by the contributors.The Memento Ring Buffer:

• Has a fixed capacity of 524.288 (512 K) message slots of 64 bytes each.

• Is managed as a "ring buffer": A new message replaces the oldest one when it becomes full.

Message CompactingTo optimize the storage and the throughput efficiencies of the Memento Ring Buffer, Memento messages issued by EuresysDrivers or Libraries are stored in a compact form.A compacted message without arguments occupies only a single 64-byte memory slot in the Ring Buffer. When the messagehas arguments, it requires additional memory slots.The original messages are reconstructed by the Memento Viewer application.

Note: Messages issued by user applications are not compacted and thus, require more space in the MementoRing Buffer.

Sequential NumberThe Memento Driver assigns a sequential number to every message entering the Memento Ring Buffer.The sequential number is a 64-bit positive integer number that increments by 1 on every message input. The sequentialnumber is not reset every boot session.The sequential number unambiguously identifies a Memento message in the whole message history of a Host PC.

Ring Buffer Persistence (Windows only)The Memento Driver maintains a synchronized copy of the Memento Ring Buffer on disk.This allows the state and the content of the Memento Ring Buffer to be restored at the next boot session aer a shutdown.

12


Note: This mechanism operates correctly when the current session terminates normally.

Note: If the current session terminates with a "blue screen", or if the reset button is pushed, or if the powersupply is removed, the Memento Ring Buffer data is appended to the crash dump file.

Ring Buffer FilterA message filter – named input filter – is inserted in the message flow entering the Memento Ring Buffer.The input filter checks the level attribute of all the incoming messages against the input filter rules and decides if themessage has to be logged or not into the Memento Ring Buffer.

Input Filter RulesThe input filter rules set is composed with:

• One default rule.• Zero or more kind-specific rules.

Default RuleThe default rule has one argument: level.The default rule applies only to messages having a kind attribute that is NOT matching any kind-specific rule.Kind-specific RulesA kind-specific rule has two arguments: kind and level.The rule applies only to messages having the specified kind attribute.The kind-specific rules supersede the default rule.

Input Filter ActionAre logged into the Memento Ring Buffer:

• Any message having no matching kind-specific rule and having a severity level greater than or equal to the specified levelin the default rule.

• Any message having a matching kind-specific rule and having a severity level greater than or equal to the specified levelin the matching kind-specific rule.

The other messages are rejected and lost forever.

Level Filtering

Rule Level Accepted Message Levels

Critical Critical

Error Critical Error

Warning Critical Error Warning

Notice Critical Error Warning Notice

Info Critical Error Warning Notice Info

Debug Critical Error Warning Notice Info Debug

13


Rule Level Accepted Message Levels

Verbose Critical Error Warning Notice Info Debug Verbose

Ring Buffer ConfigurationThe Memento Configuration defines the input filter rules.

Memento Configuration ChangesThe Memento Configuration settings can be changed at any time and take effect immediately.

Memento Configuration Persistence (Windows only)The Memento Configuration settings are persistent. The settings are stored into a configuration file on disk and areautomatically restored at the next boot session.

Default Memento ConfigurationThe default Memento configuration defines a default rule for the input filter with the level argument set to info. This rulekeeps only the messages of any kind having a verbosity level info or higher.

Memento ApplicationUser-mode Memento application.

The Memento Application is a multi-mode application. Possible modes are:

Short Name Full Name & Description

gui

Graphical User Interface (Windows default mode)A single-window graphical user interface application to:

• Show/Change the Memento Configuration• Monitor graphically the input activity of the Memento Ring Buffer• View a selected set of messages of the Memento Ring Buffer• Control interactively the selection of messages to display• Dump the Memento Ring Buffer data to disk

Note: Windows default mode.

config

Console ConfiguratorA command prompt console application to:

• Show/Change the Memento Configuration

view

Console ViewerA command prompt console application to:

• View a selected set of messages of the Memento Ring Buffer

Note: Linux default mode.

dump

Console DumperA command prompt console application to:

• Dump the Memento Ring Buffer data to disk

14


Multiple instances of the Memento Application can run concurrently!

Memento ViewerMessage viewing function of the Memento Application.

Memento messages can be retrieved selectively from the Memento Ring Buffer and viewed using the Memento Viewerfunction of the Memento Application.The Memento Viewer function is available in the following two modes of Memento Application:

• Graphical User Interface

• Console Viewer

The Memento Viewer function allows to:

• View/change the verbosity level• View/change the message filter configuration• View the body text and the attributes of the selected messages• Manage the Message Viewer memory• Go back in Memento Ring Buffer history

Block DiagramThe following drawing shows the function blocks of the Memento Viewer.

Memento Application

Ring Buffer Read Control

Memento Ring Buffer Verbosity

FilterViewer Buffer


Highlighng Filters...

Run/Pause

Message List

Message xxMessage xxMessage xxMessage xxMessage xxMessage xx

Message xxMessage xx

Clear

Go Back ...

Message List Scroll Control

Following/Follow

xxxxxx

xxx

Figure 3: Memento Application – VIEW Mode Function Blocks and Data Flow

The Memento Viewer processes the messages as follows:

• Reads messages from the Memento Ring• Stores the messages satisfying the rules of the Verbosity Filter into the Viewer Buffer• Reads messages from the Viewer Buffer• Highlights the messages according to the settings of the Highlighting Filters• Displays the highlighted messages in the Message List Area of the Memento GUI or on the console.

15


Viewer BufferThe Viewer Buffer is a memory area where the Memento Viewer stores the messages to display.The Viewer Buffer is cleared at start-up of the Memento Application. Then, it accumulates all the incoming Ring Buffermessages that satisfy the rules of the Verbosity Filter.The Viewer Buffer has a capacity of 250,000 message slots. This can be modified with the command line argument "history",a higher value means a higher memory consumption.The Viewer Buffer can be cleared at any time by the user using the "Clear" control button of Memento GUI.

Buffer ControlsBy default, the Viewer Buffer is filled with the most recent messages of the Memento Ring Buffer.However, other options are available using the Run|Pause and the Go Back controls.Run/Pause ControlThe Run/Pause control allows to pause the extraction of the messages from the Memento Ring Buffer and the filling processof the Viewer Buffer.Aer a pause, the message extraction resumes.

Note: In the meantime messages can be lost if the ring capacity has been reached.

Go Back ControlThe Go Back control allows to reload the viewer buffer with older messages of the Memento Ring Buffer.

Verbosity FilterThe Verbosity Filter is inserted in the message path between the Memento Ring Buffer and the Viewer Buffer.The Verbosity Filter allows to display only the messages that have a severity level (level attribute) greater than- or equalto- the verbosity level.

Verbosity Level Accepted Message Severity Levels

Critical – Lowest verbosity Critical – Highest severity

Error Critical Error

Warning Critical Error Warning

Notice Critical Error Warning Notice

Info Critical Error Warning Notice Info

Debug Critical Error Warning Notice Info Debug

Verbose – Highest verbosity All levels accepted

Note: The default verbosity level is Info.

In Memento GUI, the Verbosity Filter is controlled by a slider. Moving the slider instantaneously adapts the filter rule andconsequently the message flow.

16


Highlighting FiltersSixteen Highlighting Filters can be inserted in the message path between the Viewer Buffer and the display output.Each highlighting filter has two user-defined controls:

• A filter rule that selects a specific class of message• A filter action that defines the highlighting action to be perform on the selected class of messages.

Filter RuleThe rule of an Highlighting Filter is defined using the following settings:

• An enable control• A polarity control• Six message attribute conditions• One message content condition

Enable ControlThe Enable Control allows to enable/disable each filter individually while keeping the other filter settings unchanged.When Enable Control is unchecked, the highlighting filter is bypassed!

Polarity ControlThe Polarity Control determines whether or not the action has to be executed when all the enabled conditions are True:

• When unchecked, the action is executed only when all the enabled conditions are True.• When checked, the action is always executed except when all the enabled conditions are True.

Attribute ConditionsThere is one condition for each of the following message attributes: Level, Kind, PID, TID, Card, Connector.Each condition has an enable control and a value.The condition is ignored when the enable control is unchecked.The attribute condition is evaluated to TRUE when the corresponding message attribute value is equal to the condition value.

Message Content ConditionThere is one message content condition. It is an enable control and a text string value.The condition is ignored when the enable control is unchecked.The message content condition is evaluated to TRUE when the message body contains the specified text.

Filter ActionThe action of an Highlighting Filter is defined using the following settings:

• A hide control• A background color selector• A font color selector

Hide ControlThe Hide Control determines whether or not messages of the selected class have to be hidden.When the Hide Control is checked, the messages of the selected class are hidden.

17


When the Hide Control is unchecked, the messages of the selected class are displayed using the selected font and backgroundcolors.The Hide Control is unchecked by default.

Background and Font Color SelectorsThe selector proposes a set of basic and custom colors.The default colors are:

• White background• Black font

Default SettingsBy default, the highlighting filters are configured as follows:

Filter # Filter Rule Filter Action

1 to 10 Disabled

10 Level=User Highlight – Green text | white background

11 Level=Error Highlight – Black text | red background

12 Level=Warning Highlight – Black text | orange background

13 Level=Notice Highlight – Green text | white background

14 Level=Info Highlight – Purple text | white background

15 Level=Debug Highlight – Grey text | white background

16 Level=Verbose Highlight – Light Grey text | white background

Message ListThe Memento Viewer composes the Message List with messages coming from the Viewer Buffer through the HighlightingFilters.The messages are sorted by increasing time order if the time attribute is available otherwise by sequential order of arrivalinto the Memento Ring.Messages being hidden by the Highlighting filter are not displayed in the message list.

Scroll ControlBy default the message list is updated as soon as a new message arrives in the Viewer Buffer: the message list follows theViewer Buffer. This mode of operation is named auto-scroll.This auto-scroll mode can be disabled to allow older messages of the Message List to be read.On Memento GUI, the Follow|Following toggle button enables or disables the auto-scroll.

18


Memento DumpMessages data dump function of the Memento Application.

The Memento Ring Buffer data can be dumped to disk files using the Memento Dump function of the Memento Application.The Memento Viewer function is available in the following two modes of Memento Application:

• Graphical User Interface

• Console Dumper

Data SelectionBy default, the Memento Dump function dumps the next-to-come Memento Ring data.However, other options are available using the Rewind and the Boot Session options.

Dump Files ManagementDump File Name & LocationThe Memento Dump function stores the Memento data into a disk file.The default file name is dump.memento and the default file location is the Memento Application directory. %USERPROFILE%\memento\.The file name and the file location are user configurable using the File option.

Note: Euresys recommends to keep the suffix .memento.

Dump File Name RotationMemento Dump keeps previous dump files in the same directory by assigning a numerical suffix to their name. Forinstance, assuming the file name is set to dump.memento, older files are named dump.1.memento, dump.2.memento,dump.3.memento...Every time a new dump file is created, the Memento Dump function

• Increments the numerical suffix of all existing dump files (file name rotation)• Renames the previous dump file by adding the '.1' suffix

Dump File Size ControlBy default, the Memento Dump function uses a single file per dump session.Optionally, the user may split the dumped data over multiple files by specifying a size limit with the Split size option.

Dump File Count ControlBy default, the Memento Dump function keeps all the dump files.Optionally, the user may limit the number of dump files to keep using the Keep option.

Start/Stop ControlThe dump operation starts on a user action:

• Memento GUI: by clicking the Start Button in the Dump dialog box.• Command Line: by executing the Memento Application in the dump mode.

19


The dump operation stops:

• Memento GUI: by clicking the Stop Button in the Dump dialog box.• Memento GUI & Command Line: on application exit.

20

Memento User Guide Memento 6.1.1 Documentation

Memento User GuideHow to install Memento and use Memento Graphical User Interface?

Memento InstallationMemento installation procedure.

Important: For Linux users only! Memento must be installed prior to Coaxlink Driver! If the Coaxlink Driveris already installed, proceed as follows:

1. Uninstall Coaxlink Driver.2. Install Memento.3. Re-install Coaxlink Driver.

Memento is distributed on the support section of the Euresys website:http://www.euresys.com/support/.Select the Coaxlink product series to display the file list corresponding to the latest available Coaxlink Driver and Mementoreleases.Three Memento installation setup files are available:

• memento-win-<ma.mi.re.bu>.exe for Windows (32- and 64-bit)• memento-linux-x86-<ma.mi.re.bu>.exe for Linux (32-bit)• memento-linux-x86_64-<ma.mi.re.bu>.exe for Linux (64-bit)

Launch the installer tool to install the Memento Driver and the Memento Application files on your PC.It is not required to re-boot the PC aer installation!

Note: If you have an existing Memento already installed, the installer tool prompts you to uninstall it beforebeing able to continue. Otherwise, it prompts you for the selection of the destination folder. The defaultinstallation folder is

• C:\Program Files (x86)\Euresys\Memento for 64-bit Windows versions• C:\Program Files\Euresys\Memento for 32-bit Windows versions

Note: The Euresys website download area may require user authentication. The user ID and password arenot obtained, they are chosen by the user. Access is free and unrestricted.

Memento Driver SetupThe connection between the Coaxlink Driver and the Memento Driver is automatically established. The message recordingprocess automatically starts using the Default Memento Configuration.

Default Memento ConfigurationThe default Memento configuration defines a default rule for the input filter with the level argument set to info. This rulekeeps only the messages of any kind having a verbosity level info or higher.

21

http://www.euresys.com/support/

Memento 6.1.1 Documentation Memento User Guide

Changing the ConfigurationThe default configuration is adequate for most use cases.However, it can be changed at any time using Memento Application though a command line or the graphical user interface.This command line sets Memento to the highest verbosity level:

memento config --reset --verbosity=verbose

This command line resets Memento to the default settings:

memento config --reset

The configuration changes are persistent on Windows.

Important: For Linux users only! The configuration changes are not persistent. The Memento Configurationreverts to the default settings at every boot.

Starting Memento GUITo start Memento Application in GUI – Graphical User Interface – mode, click on the Memento icon or use the followingcommand line:

memento gui --hide-console

22


Main Window Layout

Activity Plot AreaMessage Plot Area

Message List Area

Controls Bar

Status Bar

Figure 4: Memento Application – GUI Mode – Main Window

The main window of the Memento Application is divided from top to bottom into 5 areas:

• The Controls Bar: a set of buttons, slider and text edit controls.• The Activity Plot Area: a first narrow area at the top just below the buttons.• The Message Plot Area: a second area about the same size of the activity plot area.• The Message List Area: the largest area.• The Status Bar.

Controls Bar

Figure 5: Memento Application – GUI Mode – Controls Bar

Starting from the le side, the Controls Bar contains the following controls:

• The Message Search edit box.• The Verbosity slider.

23


• The Ring Filters, Highlighting Filters, Follow|Following, Run|Pause, Clear, Go Back, and Dump buttons.

Message Search Edit BoxUse this control to search messages using a regular expression.

Verbosity SliderUse this control to change the verbosity level settings of the Viewer.Moving the slider to the right increases the verbosity. More messages are displayed.Moving the slider to the le decreases the verbosity. Less messages are displayed.

Ring Filters ButtonUse this control to view/change the settings of the verbosity filter of the Memento viewer.Clicking on the button displays the following dialog box:

Figure 6: Memento Application – GUI Mode – Ring Filters Dialog Box

The above snapshot shows the default configuration where only the messages having a severity level info or higher aremoved from the ring buffer to the viewer buffer.To customize the configuration, right-click and select "Add Kind" to add kind-specific filter rules.The following snapshot shows a customized filter with 2 kind-specific rules:

24


Figure 7: Memento Application – GUI Mode – Customized Ring Filters Dialog Box

Notice: These settings affect the Memento viewer only. They have no effect on the message recordingprocess into the Ring Buffer!

Highlighting Filters ButtonUse this control to view/change the settings of the highlighting filters of the Memento viewer.Clicking on the button displays the following dialog box:

Figure 8: Memento Application – GUI Mode – Highlighting Filters Dialog Box

The above snapshot shows the default configuration of the highlighting filter #1.To view the settings of the other filters, use the "Filter" drop-down box to select any of the 16 highlighting filters.

25


By default:

• Filters 1 to 8 are disabled.• Filters 9 to 16 are enabled and implement the default highlighting scheme.

To customize the highlighting scheme, configure one or more filters as follows:

• Define a rule using any of the message attributes• Define a highlighting action• Possibly, invert the rule by checking the "Not" check-box.• Enable the rule by checking the "Enabled" check-box.• Click on the Apply button.

For instance, the following snapshot shows a customized configuration of the highlighting filter #1 to highlight in orangemessages of CoaXPress kind having a severity level higher or equal to debug:

Figure 9: Memento Application – GUI Mode – Customized Highlighting Filter Dialog Box

Follow|Following ButtonUse this toggle button to control the auto-scroll of the message list.Clicking on the Follow button enables the auto-scroll. The message list is updated as soon as a new message arrives in theViewer Buffer: the message list follows the Viewer Buffer.Clicking on the Following Button disables the auto-scroll. This allows older messages to be read.

26


Run|Pause ButtonUse this toggle button to control the filling of the Memento Viewer buffer.Clicking on the Pause button pauses the extraction of the messages from the Memento Ring Buffer and the filling processof the Viewer Buffer.Click on the Run button to resume message extraction.

Clear ButtonUse this button to clear the buffer of the Memento Viewer.

Go Back ButtonUse this button to reload the viewer buffer with older messages of the Memento Ring Buffer.To setup and start a "go back":

• Click on the Go Back Button.• Select the Go Back Setup options.• Click on the OK button.

Clicking on the Go Back button opens the following dialog box:

Figure 10: Memento Application – GUI Mode – Go Back Dialog Box

Go Back Setup Options

Rewind OptionThis option determines the number of positions to rewind the Memento Ring before starting to read data.Possible values are:

Value Description

No No rewind, wait for new messages. Default setting.

As far as possible Rewind as far as possible within the data of the specified boot session.

10, 100, 1000, 10000, 100000 Rewind 10, 100, 1000, 10000, 100000 positions.

27


"Limit amount of extracted traces" OptionThis option specifies how many messages are to be extracted starting from the rewound position in the Memento Ring Buffer.By default, all traces of the specified boot session are extracted.

"Boot session" OptionThis option specifies the number of boot sessions to rewind to.Possible values are:

Value Description

0 Current Boot Session Default setting.

1, 2, 3 … Previous boot sessions (if available).

Dump ButtonUse this button to setup and start a dump of all or a selection of the Memento Ring Buffer data to disk files.To setup and start a "dump":

• Click on the Dump Button.• Setup Dump, Dump Rotation, and File options.• Click on the Start button to start the dump.

The "dump" stops when exiting the Memento Application.To stop the "dump" without exiting the Memento Application, click on the Stop button.Clicking on the Dump button opens the following dialog box:

Figure 11: Memento Application – GUI Mode – Dump Dialog Box

Dump Setup Options

Rewind OptionThe Rewind option determines the number of positions in the Memento Ring to rewind before starting to dump data.

28


Possible values are:

Value Description

No No rewind. Default setting.

As far as possible Rewind as far as possible within the data of the specified boot session.

10, 100, 1000, 10000, 100000 Rewind 10, 100, 1000, 10000, 100000 positions.

"Boot session" OptionThe Boot session option specifies the number of boot sessions to rewind to.Possible values are:

Value Description

0 Current Boot Session Default setting.

1, 2, 3 … Previous boot sessions (if available).

Dump Rotation Setup Options

"Split size in MB" OptionThis option allows to split the dumped data over multiples files by specifying a size limit.Possible values are:

Value Description

No Split One file per dump session. Default setting.

256, 512, 1024Allows splitting the dump into multiple files having a maximum size ofrespectively 256, 512 or 1024 Megabytes

Keep OptionThis option allows to limit the number of dump files to keep.Possible values are:

Value Description

All Keeps all the dump files. Default setting.

10 Keeps only the 10 most recent dump files.

File Setup OptionThis option allows to select another file name and location.The default file name is: dump.memento.The default file location is the Memento Application directory. %USERPROFILE%\memento\dump.memento\.

Note: Euresys recommends to keep the filename suffix .memento.

29


Activity Plot

Figure 12: Memento Application – GUI Mode – Activity Plot Area

The Activity Plot area of the Memento GUI gives an idea of the recent activity of the message logging.

Horizontal AxisThe horizontal axis of the Activity Plot represents the time.The axis has a fixed scale with major divisions of 1 minute and minor divisions of 2.5 seconds. The major divisions are labeledwith the Memento time value expressed in minutes.The activity plot shows the most recent time window: the rightmost end of the time scale is the actual time.

Vertical AxisThe vertical axis of the Activity Plot represents the number of messages per second that are effectively logged into theMemento Ring Buffer.The axis is a logarithmic scale covering five decades:

• The first horizontal grid line is at 10 events per second• The second horizontal grid line is at 100 events per second• …

Trace DotsThe trace is composed of trace dots.The dot color reflects the severity level of the logged messages:

• The green color means that the highest severity level of the logged messages is lower than warning.• The orange color means that the highest severity level of the logged messages is warning.• The red color means that the highest severity level of the logged messages is greater than warning.

Activity Monitoring ControlThe Activity Plot has two operation modes:

• Accurate Activity Monitoring Mode (Default mode)• Fast Activity Monitoring mode

The activity plot area can be clicked to plot messages chronologically close to that point in time. This can be convenient toinvestigate about errors appearing in red in the activity plot area.

Message Plot

Figure 13: Memento Application – GUI Mode – Message Plot Area

The Message Plot area of the Memento GUI gives a time plot representation of a selected set of messages.

Horizontal AxisThe horizontal axis of the Message Plot represents the time.

30


The axis has a variable scale with adaptive major and minor divisions. The current time scale unit is displayed on the tople corner of the plot area:

• The first line declares the time unit for the major divisions• The second line shows the number of display points in 1 major division

The le and the right bounds of the horizontal are controlled by selecting a message plot option in the contextual menu ofa message displayed in the Message List or by selecting a recent time position in the Activity Plot

Vertical AxisThe vertical axis of the Trace Plot represents the severity level.

Message SymbolsA message is represented by a '='' symbol.The symbol color uses the highlighting background color settings defined into the view filters.

Pan / Zoom ControlThe following methods are available:

• Hover mouse position in the Plot Area and use the mouse control wheel to zoom and the le button to pan.

• Right-click on a selected a message in the Message List Area and select a plot option (from, to, view, all).

Time Measurement ToolThe time interval between two messages can be measured using the shi-key in combination with the le-button of themouse.

Message DataHovering a message symbol shows up the message text and the corresponding time stamp.CTRL-click on a message jumps to the message details in the Message List.

31


Message List

Figure 14: Memento Application – GUI Mode – Message List Area

The Message List area of the Memento GUI displays a time-ordered list of a selected set of messages.The area has a tabular structure. There is one table row per message. There is one column per message data field.

Data FieldsThe following data fields area available for display into in the Message List:

• Seq: the Sequential Number assigned by Memento when a message is entering the Memento Ring Buffer.• Time: the Time attribute value assigned by the message contributor and expressed in seconds with 6 decimals.• Delta: the time offset relative to the user-defined time reference; the value is expressed in seconds with 6 decimals.• PID: the Process ID attribute value optionally assigned by the message contributor• TID: theThread ID attribute value optionally assigned by the message contributor• Card: theCard ID attribute value optionally assigned by the message contributor• Connector: theConnector ID attribute value optionally assigned by the message contributor• Level: the Level attribute value assigned by the message contributor• Kind:the Kind attribute value assigned by the message contributor• Trace: the text of the message body• Comment: a user-editable data field

Data Fields Visibility SettingsThe user may display or hide each data-field column separately. The dialog box opens by right-clicking on the columnheaders.

Note: The column order cannot be modified.

User-defined Time ReferenceThe user may use the time stamp of a message as the time-reference for the Delta data field.

32


This is achieved by right-clicking on a message to open a dialog box and then clicking on "Set time reference".

Injection of Current TimeThe user may request Memento to inject a message containing the UTC time and date in the Memento Ring.

Note: This provides a sync point between the Memento time scale and the System time, itself possiblysynchronized to an Internet Time Server.

This is achieved by right-clicking on a message to open a dialog box and then clicking on "Inject Current Time Trace".

Right-click MenuThe following pop-up menu appears when right-clicking in the message list:

Figure 15: Memento Application – GUI Mode – Message List Area Pop-up Menu

Possible actions are:

Row resizingTo resize rows:

• Select a row by clicking inside.• Adjust the row height by selecting top or bottom edge and dragging up or down the row boundary.• Click on "Set current height to all rows" to uniformize the row height.

Set time referenceTo define the time reference for the time shown in the "delta" column of the message list:

• Select a row by clicking inside.• Click on "Set time reference".

Inject current time traceClick on "Inject current time trace" insert a "UTC Time message" level in the Memento Ring.

Copy to clipboardTo copy a selection of messages to the clipboard:

• Select one message using the le click.• Optionally, select more messages using the shi-le click or the shit-right click.• Click on "Copy".

33


To copy all messages of the viewer buffer to the clipboard:

• Click on "Copy all".

Plot From | Plot To | View |AllTo plot a set a messages in the message plot area:

• Select the first message using the le click.• Click on "Plot from".• Select the last message using the le click.• Click on "Plot to".

The message plot area is resized to fit the messages set. The first message appears on the le-side and the last messageappears on the right-side of the message plot area.To plot the messages that are currently displayed in the Message List:

• Click on "Plot View".

To plot the messages that are stored in the Viewer Buffer:

• Click on "Plot All".

Auto-Follow | No Auto-FollowTo adjust automatically the le- and right-limits of the Message Plot to follow the arrival of new messages:

• Click on "Auto-Follow".

To stop the automatic adjustment:

• Click on "No Auto-Follow".

Status Bar

Figure 16: Memento Application – GUI Mode – Status Bar

The Status Bar area of the Memento GUI displays:

• Traces: total #. The total number of Memento traces that have been recorded in the Viewer Buffer.• Traces: history # The number of Memento traces that are currently available in the Viewer Buffer.• Delta time. The time difference between the selected message and the time reference. This value is also displayed in the

delta column of the message list.• Status. The operating status – Running – or – Suspended -- of the Memento Application.

34

Memento Reference Memento 6.1.1 Documentation

Memento ReferenceReference manual of the Memento command line interface.

Memento Command LineMemento is a multi-mode application program that can be invoked using a command line.

memento [COMMAND] ... [OPTIONS]memento gui [OPTIONS] [FILE]memento config [OPTIONS] [FILE]memento view [OPTIONS] [FILE]memento dump [OPTIONS] [FILE]memento xperf [OPTIONS]

The command line may includes

• 0 or 1 COMMAND argument: gui, config, view, dump, xperf• 0 or more OPTION flags• 0 or 1 FILE argument

COMMANDThe COMMAND argument determines the operation mode of the Memento application.

Command Description

gui

Start Memento Graphical User InterfaceThis single-window graphical user interface application allows to:

• Show/change the Memento Configuration• Monitor graphically the input activity of the Memento Ring Buffer• View a selected set of messages of the Memento Ring Buffer• Control interactively the selection of messages to display• Dump the Memento Ring Buffer data to disk

configShow/change Memento ConfigurationSelect this mode to show and possibly modify the Memento configuration using a command line.

viewView Memento messagesSelect this mode to view a selected set of messages of the Memento Ring Buffer using a commandline.

dumpDump Memento data into fileSelect this mode to dump Memento data from the Memento Ring Buffer to files on disk using acommand line.

xperfRecord Memento and XPerf data into fileSelect this mode to record Memento and XPerf data to a disk file using a command line.

The COMMAND argument is optional. When it is omitted, a default operation mode is selected:

35

Memento 6.1.1 Documentation Memento Reference

• gui for Windows• view for Linux

OPTIONS

Common OptionsOption flags applicable to all COMMAND values.

Flag Description

-h or --help Display the help message

-V or --version Display the version information

--numeric-version Display just the version number

GUI OptionsOption flags applicable when COMMAND=gui or when, for Windows only, the COMMAND argument is missing.

Flag Description

--dir=DIRPath to the trace definition directory.Default directory :Public Documents\Euresys\Memento

--goback[=N]Go back N messages in history.Default: ignore past messages.

--limit[=N]Stop aer N messages.Default: don't stop.

--pastboot[=N]Go back N boot sessions in history.Default: ignore past boot sessions.

--verbosity=LEVEL

Set the verbosity level.Possible values: None,Critical,Error,Warning,Notice,Info,Debug,VerboseDefault: Notice.

--history=INTNumber of history lines.Default number: 250,000.

--duration=SEC Stop the application aer the specified number of seconds.

--hide-console Don't show the application console.

36


Flag Description

--filter=FILTER

Define filters with the following BNF syntax:<FILTER> ::= <CARD> | ':'<CONNECTORS> | <CARD>':'<CONNECTORS>

where<CARD> ::= <INTEGER> | '+',<CONNECTORS> ::= <LETTER> | <LETTER><CONNECTORS> | '+',<LETTER> ::= 'A'|'B'|'C'|'D'

with '+' to match empty card or connector information

CONFIG OptionsOption flags applicable when COMMAND=config.

Flag Description

--resetReset the Memento Configuration to default settings. This is performed before any othercation!

--verbosity=LEVEL


--kind=KIND

Show/change configuration of one of the following kind: API, Acquisition, CoaXPress, DMA,DPC, Descriptors, EEPROM, Event, FPGA, Flash, GenAPI, Hardware, I2C, IOCTL, IRQ, Memento,OperationM, PCIExpress, PnP, Power, Profiling, SPI, Script, Serial Line, Thread, Unknown,User

--header Show Memento header including main and kind configurations.

VIEW OptionsOption flags applicable when COMMAND=view or when, for Linux only, the COMMAND argument is missing.

Flag Description

--dir=DIRPath to the trace definition directory.Default directory :Public Documents\Euresys\Memento

--goback[=N]Go back N messages in history.By default, past messages are ignored.

--limit[=N]Stop aer N messages.Default: don't stop.


--verbosity=LEVEL


--colorEnable or disable colors.Default: automatic detection.

37

Memento 6.1.1 Documentation Memento Reference

Flag Description

--latency=LChronologically sort traces using a sliding window of L seconds.Default: 0.5 second.

--buffering=BLimit internal buffering of traces to B seconds.Default: 0.6 second.

--filter=FILTER

Define filters with the following BNF syntax:<FILTER> ::= <CARD> | ':'<CONNECTORS> | <CARD>':'<CONNECTORS>

where<CARD> ::= <INTEGER> | '+',<CONNECTORS> ::= <LETTER> | <LETTER><CONNECTORS> | '+',<LETTER> ::= 'A'|'B'|'C'|'D'

with '+' to match empty card or connector information

DUMP OptionsOption flags applicable when COMMAND=dump.

Flag Description

-o --output=FILEOutput file name. Existing files are rotated if necessary.Default: memento.out.

--goback[=N]Go back N messages in history.Default: ignore past messages.


--split[=MB]Split dump into several files, rotating files as necessary.Default: dump all messages to a single file.

--keep=NKeep the N most recent dump files and delete the others.Default: keep all files.

--follow Wait for new messages

XPERF OptionsOption flags applicable when COMMAND=xperf.

Flag Description

-o --output=FILEOutput file name. Existing files are rotated if necessary.Default: memento-xperf.zip.

--keep=NKeep the N most recent dump files and delete the others.Default: keep all files.

--duration=SEC Stop the application aer the specified number of seconds

38


Flag Description

--group=GROUP|FLAGSXPerf group or flagsDefault: DiagEasy

--show-in-explorer Show memento-xperf archive in Windows Explorer

--pause-on-error

FILEThe FILE argument specifies the file name and the file path of a Memento dump file.The FILE argument is optional. It is required only when the COMMAND has to be executed on an existing dump file.When it is omitted, the COMMAND is executed on the Memento Ring.

Command Line SamplesStarts the Memento Graphical User Interface

memento gui --hide-console

Reset Memento to Default Verbosity Level

memento config --reset

Set Memento to Highest Verbosity Level

memento config --reset --verbosity=verbose

Start Memento Logging

memento --goback --follow --split=100 --keep=20

Record Memento and XPerf traces

memento xperf --output="%USERPROFILE%\memento\memento-xperf.zip" --keep=20 --show-in-explorer

39

Memento Documentation - Euresysdownloads.euresys.com/PackageFiles/MEMENTO/6.1.518/98064823… ·...

Documents

Transcript of Memento Documentation - Euresysdownloads.euresys.com/PackageFiles/MEMENTO/6.1.518/98064823… ·...