Monumental Inscription Index - Memento Mori · Monumental Inscription Index - Memento Mori
DOCUMENTATION Memento -...
Transcript of DOCUMENTATION Memento -...
MementoMemento 9.3.2
DOCUMENTATION
© EURESYS s.a. 2017 - Document version 9.3.2.2005 built on 2017-10-26
2
Terms of Use
EURESYS s.a. shall retain all property rights, title and interest of the documentation of the hardware and thesoftware, and of the trademarks of EURESYS s.a.
All the names of companies and products mentioned in the documentation may be the trademarks of theirrespective owners.
The licensing, use, leasing, loaning, translation, reproduction, copying or modification of the hardware or thesoftware, brands or documentation of EURESYS s.a. contained in this book, is not allowed without prior notice.
EURESYS s.a. may modify the product specification or change the information given in this documentation at anytime, at its discretion, and without prior notice.
EURESYS s.a. shall not be liable for any loss of or damage to revenues, profits, goodwill, data, information systems orother special, incidental, indirect, consequential or punitive damages of any kind arising in connection with the useof the hardware or the software of EURESYS s.a. or resulting of omissions or errors in this documentation.
This documentation is provided with Memento 9.3 (doc build 2017-10-26).© 2017 EURESYS s.a.
Memento Documentation
3
Contents
About This Document 5Document History 5Document Changes 6Document Structure 6
Memento Concepts 7Abstract 8Block Diagram 9Memento Contributors 10Memento Messages 11
Message Body 11Message Attributes 11
Memento Time Scale 15Driver 16
Memento Ring Buffer 17Ring Buffer Filter 18Ring Buffer Configuration 20
Memento Application 21Memento Viewer 22
Block Diagram 23Viewer Buffer 24Verbosity Filter 25Highlighting Filters 26Message List 29
Memento Dump 30
User Guide 32Memento Installation 33Memento Driver Setup 34Starting Memento GUI 35Main Window 36
Main Window Controls Bar 37Main Window Activity Plot Area 45Main Window Message Plot Area 47Main Window Message List Area 49Main Window Status Bar 53
Memento Documentation
4
Memento Reference 54Memento Command Line 55
COMMAND 56OPTIONS 57
Common Options 57GUI Options 57CONFIG Options 58VIEW Options 59DUMP Options 60XPERF Options 60
FILE 61
Command Line Samples 62
Memento Documentation
5
About This Document
Document History
Date Document Version Description
2016-07-04 4.7 Memento 4.7 Documentation
2016-07-07 5.1 Memento 5.1 Documentation
2016-08-01 6.0 Memento 6.0 Documentation
2016-09-27 6.1 Memento 6.1.1 Documentation
2016-12-16 6.2Memento 6.2 Documentation
▶ Add MultiCam as contributing driver and libraries
2017-10-25 9.3.2 Memento 9.3.2 Documentation
About This Document Memento Documentation
6
Document ChangesFROM VERSION 6.2 TO VERSION 9.3
The following topics were revised:
▶ "Main Window" on page 36
■ Add Tool-tip Area
▶ "Main Window Controls Bar" on page 37
■ Add Aa and RE check boxes, add Menu button
▶ "Main Window Message List Area" on page 49
■ Add Stream column to Memento Viewer
Document StructureThe main sections of this document are:
▶ "Memento Concepts" on the facing page
▶ "User Guide" on page 32
▶ "Memento Reference" on page 54
Memento Documentation About This Document
7
Memento Concepts
Abstract 8Block Diagram 9Memento Contributors 10Memento Messages 11Message Body 11Message Attributes 11
Memento Time Scale 15Driver 16Memento Ring Buffer 17Ring Buffer Filter 18Ring Buffer Configuration 20
Memento Application 21Memento Viewer 22Block Diagram 23Viewer Buffer 24Verbosity Filter 25Highlighting Filters 26Message List 29
Memento Dump 30
Memento Concepts Memento Documentation
8
Abstract
Memento Logo
Memento is an advanced event message logging system that greatly facilitates the debugging ofmachine vision applications using Euresys frame grabbers.
Memento is a set of software tools allowing:
▶ Kernel drivers and user space applications – Memento Contributors – to inject tracemessages – 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 Viewerfunction
▶ To dump Memento data from the Memento Ring Buffer to disk using the Memento Dumpfunction
The Memento software package has two main components:
▶ A kernel-mode driver: Memento Driver.
▶ A user-mode application: Memento Application.
Memento Documentation Memento Concepts
10
Memento ContributorsThe Memento Contributors are Euresys kernel drivers and Euresys or third-party user spaceapplications embedding Memento Traces at particular code locations.
A Memento Trace is a non-blocking and lightweight software macro that, upon execution,builds up a message and pushes it into the Memento Ring.
COAXLINK DRIVER & LIBRARY
The Coaxlink Driver software package is a major message contributor. For instance, CoaxlinkDriver 4.7 includes ~1,000 distinct instances of Memento Traces!
All the Coaxlink products implement Memento-in-hardware. This feature allows hardwareevents to be logged in Memento with an accurate time attribute.
MULTICAM DRIVER & LIBRARIES
The kernel-mode drivers for Grablink Base, Grablink DualBase, Grablink Full, and Grablink FullXR products as well as the MultiCam and clseremc libraries can also contribute to Memento.
USER APPLICATION
A user application may include Memento Traces capable of generating messages having acustom content and two attributes: kind and level.
Any severity level can be assigned to the level attribute.
Sixteen (16) distinct values are available for the kind attribute:user0, … user9, … userA, …userF.
The value user is kept for backward capability; it is equivalent to user0.
EGRABBER
The EGrabber API layer generates Memento Traces with the Egrabber kind attribute.
MEMENTO APPLICATION
The Memento Application also acts as a message contributor since it may inject "UTC Time"messages.
Memento Documentation Memento Concepts
11
Memento MessagesA 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. Thearguments are used as placeholders 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 ATTRIBUTES
The Kind and Level attributes are mandatory.
They must always be defined by the Memento Contributors.
OPTIONAL ATTRIBUTES
The Time, Process ID, Thread ID, Card ID, and Connector ID attributes are optional.
The Memento Contributors decide whether or not to use them.
LEVEL ATTRIBUTE
The 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
Memento Concepts Memento Documentation
12
Value Severity Description
Info Low Information message
Debug Lower Debug message
Verbose Lowest Nattering
Debug and verbose levels are used for messages intended for Euresys engineering andtechnical support.
KIND ATTRIBUTE
The mandatory Kind attribute defines the kind, nature, origin … of the message:
Kind Attribute Values
Value Description
API API function calls.
AcquisitionMessages related to image acquisition (e.g., data stream start/stop, start/endof scan).
CoaXPressMessages related to CoaXPress protocol (e.g., device discovery, controlmessages).
DMA Messages related to DMA (Direct Memory Access) transfers.
DPCMessages related to DPC (Deferred Procedure Calls) queued by the driver whenit receives an interrupt request.
Descriptors Messages related to DMA descriptors.
EEPROMMessages related to on-board EEPROM (where part number, serial number andOEM key are stored).
Egrabber Messages produced by EGrabber.
Event Messages related to the event notification infrastructure.
FPGA
Messages related to :
▶ Firmware image.
▶ CIC (Camera and Illumination Controller).
FlashMessages related to the on-board flash memory (where the firmware image isstored).
GenAPI Messages related to Euresys GenApi implementation.
Hardware Messages emitted by the frame grabber firmware.
I2CMessages related to the I2C communication between 2 frame grabbercomponents.
Memento Documentation Memento Concepts
13
Value Description
IOCTLMessages related to the communication between user-mode softwarecomponents and the kernel driver.
IRQ Messages related to the interrupt requests received by the kernel driver.
LUT Messages related to the look-up table processing.
Memento Messages related to Memento.
OperationMMessages related to an internal software component (should not appear oncustomers machines).
PCI ExpressMessages related to the PCI Express configuration space (e.g., vendor anddevice IDs, capabilities).
PnPMessages related to the interaction between the driver and the Windows Plugand Play Manager.
PowerMessages related to the interaction between the driver and the WindowsPower Manager.
ProfilingA small number of messages for doing profiling (IRQ counter, time spent withinterrupts masked, DPC counter, time spent in DPC, buffer push/pop and DMAtransfer 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 driver.
Time Messages related to system data and time.
Timer Messages related to operating system timers.
User0 …User9,UserA ...UserF
Messages emitted by the user application.
The above list is open; new values can be appended in future Memento releases.
TIME ATTRIBUTE
For all but the hardware kind of messages, the time attribute defines the time of occurrence onthe Memento Time Scale of the creation of the message by the contributor.
For hardware kind of messages, the time attribute defines the time of occurrence on theMemento Time Scale of the hardware event that is at the origin of the message. Thesemessages are prefixed by [ts:HARDWARE_TIMESTAMP] where HARDWARE_TIMESTAMP is thetime of occurrence on the card local time scale.
The time of occurrence reported by the hardware using the card local time is converted toMemento time.
Memento Concepts Memento Documentation
14
PROCESS ID & THREAD ID ATTRIBUTES
The 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 ATTRIBUTES
The Card ID attribute reports the identifier of the frame grabber card the message belongs to.This is a zero-based index assigned by the corresponding card driver.
The Card ID is global within a specific driver.
Grablink cards have a specific driver for each card type. If, for instance, a system has 2Grablink Base and 2 Grablink DualBase, there will be Memento traces related to GrablinkBase Card ID #0 and #1 as well as Grablink DualBase card ID #0 and #1.
Coaxlink cards have a unique driver for all types. If, for instance, a system has 1 CoaxlinkMono and 1 Coaxlink Duo, there will be Memento traces related to Coaxlink Card ID #0 and#1.
The Connector ID attribute reports the identifier of the camera connector the message belongsto.
For Coaxlink cards, the Connector ID is the ID (A, B, C, D) of the CoaXPress host interfaceconnector.
For Grablink cards, the Connector ID is the ID (M, A, B) of the Camera Link connector.
Memento Documentation Memento Concepts
15
Memento Time ScaleThe Memento Time Scale is a common time scale used for time-stamping all the MementoMessages produced by the Memento Contributors within a Host PC.
Having a common time scale is a key feature of Memento since it allows messages fromdifferent origins 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.
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!
For Windows users only: The Memento Time Scale is not reset when Windows performs aFast Boot, even after a Power Off! When the Fast Boot option is activated, the only way toreset the Memento Time Scale, is to perform a Windows Restart.
UTC VS. MEMENTO TIME
When a Coaxlink card is installed in the Host PC, the Coaxlink Driver generates every minute anUTC time message:
Time: 2016-04-22 14:43:29.0493338 UTC
Such message allows for establishing the relationship between the UTC (Coordinated UniversalTime) and the Memento Time.
The time reported in the above message is actually the Host PC time of the local time zoneconverted to the UTC time zone.
The accuracy of the reported UTC time depends on the Host PC. When the Host PCimplements a synchronization mechanism to Internet time servers, the UTC time accuracy ispretty good!
Memento Concepts Memento Documentation
16
DriverThe kernel-mode Memento Driver is responsible for managing the Memento Ring Buffer: aregion of the Host PC memory where the Memento Contributors store the Memento Messages.
The Coaxlink Driver and/or the MultiCam Driver automatically connects to the Memento Driver.
Once the connection is established, the messages composed by the contributors are firstscreened by the Ring Buffer Filter according to the Ring Buffer Configuration settings.
Only the messages that successfully pass through the Ring Buffer Filter filter are effectivelywritten into the Memento Ring Buffer.
Memento Ring Buffer 17Ring Buffer Filter 18Ring Buffer Configuration 20
Memento Documentation Memento Concepts
17
Memento Ring BufferThe Memento Ring Buffer is an area of the Host PC memory where the Memento messages arewritten 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 COMPACTING
To optimize the storage and the throughput efficiencies of the Memento Ring Buffer, Mementomessages issued by Euresys Drivers or Libraries are stored in a compact form.
A compacted message without arguments occupies only a single 64-byte memory slot in theRing Buffer. When the message has arguments, it requires additional memory slots.
The original messages are reconstructed by the Memento Viewer application.
Messages issued by user applications are not compacted and thus, require more space inthe Memento Ring Buffer.
SEQUENTIAL NUMBER
The Memento Driver assigns a sequential number to every message entering the Memento RingBuffer.
The sequential number is a 64-bit positive integer number that increments by 1 on everymessage input. The sequential number is not reset every boot session.
The sequential number unambiguously identifies a Memento message in the whole messagehistory 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 bootsession after a shutdown.
This mechanism operates correctly when the current session terminates normally.
If the current session terminates with a "blue screen", or if the reset button is pushed, or ifthe power supply is removed, the Memento Ring Buffer data is appended to the crash dumpfile.
Memento Concepts Memento Documentation
18
Ring Buffer FilterA message filter – named input filter – is inserted in the message flow entering the MementoRing Buffer.
The input filter checks the level attribute of all the incoming messages against the input filterrules and decides if the message has to be logged or not into the Memento Ring Buffer.
INPUT FILTER RULES
The input filter rules set is composed with:
▶ One default rule.
▶ Zero or more kind-specific rules.
DEFAULT RULE
The default rule has one argument: level.
The default rule applies only to messages having a kind attribute that is NOT matching anykind-specific rule.
KIND-SPECIFIC RULES
A 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 ACTION
Are logged into the Memento Ring Buffer:
▶ Any message having no matching kind-specific rule and having a severity level greater thanor equal to the specified level in the default rule.
▶ Any message having a matching kind-specific rule and having a severity level greater than orequal to the specified level in 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
Memento Documentation Memento Concepts
19
Rule Level Accepted Message Levels
Notice Critical Error Warning Notice
Info Critical Error Warning Notice Info
Debug Critical Error Warning Notice Info Debug
Verbose Critical Error Warning Notice Info Debug Verbose
Memento Concepts Memento Documentation
20
Ring Buffer ConfigurationThe Memento Configuration defines the input filter rules.
MEMENTO CONFIGURATION CHANGES
The 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 configurationfile on disk and are automatically restored at the next boot session.
DEFAULT MEMENTO CONFIGURATION
The default Memento configuration defines a default rule for the input filter with the levelargument set to info. This rule keeps only the messages of any kind having a verbosity levelinfo or higher.
Memento Documentation Memento Concepts
21
Memento ApplicationThe 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
Windows default mode.
config
Console Configurator
A 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
Linux default mode.
dump
Console DumperA command prompt console application to:
▶ Dump the Memento Ring Buffer data to disk
Multiple instances of the Memento Application can run concurrently!
Memento Concepts Memento Documentation
22
Memento ViewerMemento messages can be retrieved selectively from the Memento Ring Buffer and viewed usingthe Memento Viewer function 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 Diagram 23Viewer Buffer 24Verbosity Filter 25Highlighting Filters 26Message List 29
Memento Documentation Memento Concepts
23
Block DiagramThe following drawing shows the function blocks of the Memento Viewer.
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 theconsole.
Memento Concepts Memento Documentation
24
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 allthe incoming Ring Buffer messages that satisfy the rules of the Verbosity Filter.
The Viewer Buffer has a capacity of 250,000 message slots. This can be modified with thecommand 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 ofMemento GUI.
BUFFER CONTROLS
By 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 CONTROL
The Run/Pause control allows to pause the extraction of the messages from the Memento RingBuffer and the filling process of the Viewer Buffer.
After a pause, the message extraction resumes.
In the meantime messages can be lost if the ring capacity has been reached.
GO BACK CONTROL
The Go Back control allows to reload the viewer buffer with older messages of the MementoRing Buffer.
Memento Documentation Memento Concepts
25
Verbosity FilterThe Verbosity Filter is inserted in the message path between the Memento Ring Buffer and theViewer Buffer.
The Verbosity Filter allows to display only the messages that have a severity level (levelattribute) greater than- or equal to- the verbosity level.
Verbosity Levels
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
The default verbosity level is Info.
In Memento GUI, the Verbosity Filter is controlled by a slider. Moving the slider instantaneouslyadapts the filter rule and consequently the message flow.
Memento Concepts Memento Documentation
26
Highlighting FiltersSixteen Highlighting Filters can be inserted in the message path between the Viewer Buffer andthe 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 ofmessages.
FILTER RULE
The 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 CONTROL
The Enable Control allows to enable/disable each filter individually while keeping the otherfilter settings unchanged.
When Enable Control is unchecked, the highlighting filter is bypassed!
POLARITY CONTROL
The Polarity Control determines whether or not the action has to be executed when all theenabled 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 areTrue.
ATTRIBUTE CONDITIONS
There 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 isequal to the condition value.
Memento Documentation Memento Concepts
27
MESSAGE CONTENT CONDITION
There 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 thespecified text.
FILTER ACTION
The action of an Highlighting Filter is defined using the following settings:
▶ A hide control
▶ A background color selector
▶ A font color selector
HIDE CONTROL
The 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.
When the Hide Control is unchecked, the messages of the selected class are displayed using theselected font and background colors.
The Hide Control is unchecked by default.
BACKGROUND AND FONT COLOR SELECTORS
The selector proposes a set of basic and custom colors.
The default colors are:
▶ White background
▶ Black font
DEFAULT SETTINGS
By default, the highlighting filters are configured as follows:
Highlighting Filters Default Configuration
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
Memento Concepts Memento Documentation
28
Filter # Filter Rule Filter Action
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
Memento Documentation Memento Concepts
29
Message ListThe Memento Viewer composes the Message List with messages coming from the Viewer Bufferthrough the Highlighting Filters.
The messages are sorted by increasing time order if the time attribute is available otherwise bysequential order of arrival into the Memento Ring.
Messages being hidden by the Highlighting filter are not displayed in the message list.
SCROLL CONTROL
By default the message list is updated as soon as a new message arrives in the Viewer Buffer:the message list follows the Viewer 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.
Memento Concepts Memento Documentation
30
Memento DumpThe Memento Ring Buffer data can be dumped to disk files using the Memento Dump function ofthe Memento Application.
The Memento Viewer function is available in the following two modes of Memento Application:
▶ Graphical User Interface
▶ Console Dumper
DATA SELECTION
By 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 MANAGEMENT
DUMP FILE NAME & LOCATION
The 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 Applicationdirectory. %USERPROFILE%\memento\.
The file name and the file location are user configurable using the File option.
Euresys recommends to keep the suffix .memento.
DUMP FILE NAME ROTATION
Memento Dump keeps previous dump files in the same directory by assigning a numerical suffixto their name. For instance, assuming the file name is set to dump.memento, older files arenamed 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 CONTROL
By 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 withthe Split size option.
DUMP FILE COUNT CONTROL
By default, the Memento Dump function keeps all the dump files.
Memento Documentation Memento Concepts
31
Optionally, the user may limit the number of dump files to keep using the Keep option.
START/STOP CONTROL
The 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.
The dump operation stops:
▶ Memento GUI: by clicking the Stop Button in the Dump dialog box.
▶ Memento GUI & Command Line: on application exit.
Memento Concepts Memento Documentation
32
User Guide
Memento Installation 33Memento Driver Setup 34Starting Memento GUI 35Main Window 36Main Window Controls Bar 37Main Window Activity Plot Area 45Main Window Message Plot Area 47Main Window Message List Area 49Main Window Status Bar 53
Memento Documentation User Guide
33
Memento InstallationMemento is distributed on the support section of the Euresyswebsite:http://www.euresys.com/support/.
Select the Coaxlink product series to display the file list corresponding to the latest availableCoaxlink Driver and Memento releases.
Select the Grablink product series to display the file list corresponding to the latest availableMultiCam Driver and Memento releases.
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 onyour PC.
It is not required to re-boot the PC after installation!
If you have an existing Memento already installed, the installer tool prompts you touninstall it before being able to continue. Otherwise, it prompts you for the selection of thedestination folder. The default installation folder is
▶ C:\Program Files (x86)\Euresys\Memento for 64-bit Windows versions
▶ C:\Program Files\Euresys\Memento for 32-bit Windows versions
The Euresys website download area may require user authentication. The user ID andpassword are not obtained, they are chosen by the user. Access is free and unrestricted.
For Linux users only!Memento must be installed prior to Coaxlink or MultiCam Driver!If the Coaxlink or MultiCam Driver is already installed, proceed as follows:
1. Uninstall Coaxlink or MultiCam Driver.
2. Install Memento.
3. Re-install Coaxlink or MultiCam Driver.
User Guide Memento Documentation
34
Memento Driver SetupThe connection between the Coaxlink or MultiCam Driver and the Memento Driver isautomatically established. The message recording process automatically starts using theDefault Memento Configuration.
DEFAULT MEMENTO CONFIGURATION
The default Memento configuration defines a default rule for the input filter with the levelargument set to info. This rule keeps only the messages of any kind having a verbosity levelinfo or higher.
CHANGING THE CONFIGURATION
The default configuration is adequate for most use cases.
However, it can be changed at any time using Memento Application though a command line orthe 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. TheMemento Configuration reverts to the default settings at every boot.
Memento Documentation User Guide
35
Starting Memento GUITo start Memento Application in GUI – Graphical User Interface – mode, click on the Mementoicon or use the following command line:
memento gui --hide-console
User Guide Memento Documentation
36
Main Window
Memento Application – GUI Mode – Main Window
1. Controls Bar: a set of buttons, check-boxes, text and slider controls.
2. Activity Plot Area: a graphical area showing a time plot representation of the recentactivity.
3. Message Plot Area:a graphical area showing a time plot representation of a selected set ofmessages.
4. Tool-tip Area: a text area showing the selected message, possibly expanded with tool-tipdata.
5. Message List Area: a tabular text area showing a time-ordered list of a selected set ofmessages with their attributes.
6. Status Bar
Main Window Controls Bar 37Main Window Activity Plot Area 45Main Window Message Plot Area 47Main Window Message List Area 49Main Window Status Bar 53
Memento Documentation User Guide
37
Main Window Controls Bar
Memento Application – GUI Mode – Controls Bar
Starting from the left side, the Controls Bar contains the following controls:
MESSAGE SEARCH CONTROLS
Use this control to search messages according to the value entered in the Search field.
Aa check-box: When checked, the search operation is case sensitive. It follows exactly thecasing of the value entered in the Search field.
RE check-box : When checked, the value entered in the Search field uses the Perl-like regularexpressions syntax.
VERBOSITY SLIDER
Use 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 left decreases the verbosity. Less messages are displayed.
RING FILTERS BUTTON
Use this control to view or change the settings of the verbosity filter of the Memento viewer.
Clicking on the button displays the following dialog box:
User Guide Memento Documentation
38
Memento Application – GUI Mode – Ring Filters Dialog Box
The above snapshot shows the default configuration where only the messages having a severitylevel info or higher are moved 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:
Memento Application – GUI Mode – Customized Ring Filters Dialog Box
These settings affect the Memento viewer only. They have no effect on the messagerecording process into the Ring Buffer!
HIGHLIGHTING FILTERS BUTTON
Use this control to view/change the settings of the highlighting filters of the Memento viewer.
Clicking on the button displays the following dialog box:
Memento Documentation User Guide
39
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 16highlighting filters.
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:
1. Define a rule using any of the message attributes
2. Define a highlighting action
3. Possibly, invert the rule by checking the "Not" check-box.
4. Enable the rule by checking the "Enabled" check-box.
5. Click on the Apply button.
For instance, the following snapshot shows a customized configuration of the highlighting filter#1 to highlight in orange messages of CoaXPress kind having a severity level higher or equal todebug:
User Guide Memento Documentation
40
Memento Application – GUI Mode – Customized Highlighting Filter Dialog Box
FOLLOW | FOLLOWING BUTTON
|
Use 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 anew message arrives in the Viewer Buffer: the message list follows the Viewer Buffer.
Clicking on the Following Button disables the auto-scroll. This allows older messages to beread.
RUN | PAUSE BUTTON
|
Use 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 RingBuffer and the filling process of the Viewer Buffer.
Click on the Run button to resume message extraction.
Memento Documentation User Guide
41
CLEAR BUTTON
Use this button to clear the buffer of the Memento Viewer.
GO BACK BUTTON
Use 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:
Memento Application – GUI Mode – Go Back Dialog Box
GO BACK SETUP OPTIONS
REWIND OPTION
This option determines the number of positions to rewind the Memento Ring before starting toread data.
Possible values are:
Value Description
No No rewind, wait for new messages. Default setting.
As far as possibleRewind as far as possible within the data of the specified bootsession.
10, 100, 1000, 10000,100000
Rewind 10, 100, 1000, 10000, 100000 positions.
User Guide Memento Documentation
42
"LIMIT AMOUNT OF EXTRACTED TRACES" OPTION
This option specifies how many messages are to be extracted starting from the rewoundposition in the Memento Ring Buffer. By default, all traces of the specified boot session areextracted.
"BOOT SESSION" OPTION
This 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).
MENU BUTTON
Clicking on this button opens a dialog box providing the following functions:
▶ Clear Search History to clear the Message Search expressions history.
▶ Dump Memento data to file... to dump the content of the Ring Buffer to afile. Refer to"Dump Memento data to file ..." below
▶ Inject current time trace to inject a UTC time trace into the Memento Ring.
▶ About to view the version number of Memento.
DUMP MEMENTO DATA TO FILE ...
Use this button to setup and start a dump of all or a selection of the Memento Ring Buffer datato 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:
Memento Documentation User Guide
43
Memento Application – GUI Mode – Dump Dialog Box
DUMP SETUP OPTIONS
REWIND OPTION
The Rewind option determines the number of positions in the Memento Ring to rewind beforestarting to dump data.
Possible values are:
Value Description
No No rewind. Default setting.
As far as possibleRewind as far as possible within the data of the specified bootsession.
10, 100, 1000, 10000,100000
Rewind 10, 100, 1000, 10000, 100000 positions.
"BOOT SESSION" OPTION
The 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).
User Guide Memento Documentation
44
DUMP ROTATION SETUP OPTIONS
"SPLIT SIZE IN MB" OPTION
This 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,1024
Allows splitting the dump into multiple files having a maximum size ofrespectively 256, 512 or 1024 Megabytes
KEEP OPTION
This 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 OPTION
This 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\.
Euresys recommends to keep the filename suffix .memento.
Memento Documentation User Guide
45
Main Window Activity Plot Area
Memento Application – GUI Mode – Activity Plot Area
The Activity Plot area of the Memento GUI gives an idea of the recent activity of the messagelogging.
HORIZONTAL AXIS
The 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 labeled with the Memento time value expressed in minutes.
The activity plot shows the most recent time window: the rightmost end of the time scale is theactual time.
VERTICAL AXIS
The vertical axis of the Activity Plot represents the number of messages per second that areeffectively logged into the Memento 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 DOTS
The 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 thanwarning.
▶ 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 thanwarning.
ACTIVITY MONITORING CONTROL
The Activity Plot has two operation modes:
▶ Accurate Activity Monitoring Mode (Default mode)
▶ Fast Activity Monitoring mode
User Guide Memento Documentation
46
The activity plot area can be clicked to plot messages chronologically close to that point intime. This can be convenient to investigate about errors appearing in red in the activity plotarea.
Memento Documentation User Guide
47
Main Window Message Plot Area
Memento Application – GUI Mode – Message Plot Area
The Message Plot area of the Memento GUI gives a time plot representation of a selected set ofmessages.
HORIZONTAL AXIS
The horizontal axis of the Message Plot represents the time.
The axis has a variable scale with adaptive major and minor divisions. The current time scaleunit is displayed on the top left 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 left and the right bounds of the horizontal are controlled by selecting a message plotoption in the contextual menu of a message displayed in the Message List or by selecting arecent time position in the Activity Plot
VERTICAL AXIS
The vertical axis of the Trace Plot represents the severity level.
MESSAGE SYMBOLS
A message is represented by a '='' symbol.
The symbol color uses the highlighting background color settings defined into the view filters.
PAN / ZOOM CONTROL
The following methods are available:
▶ Hover mouse position in the Plot Area and use the mouse control wheel to zoom and the leftbutton 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 TOOL
The time interval between two messages can be measured using the shift-key in combinationwith the left-button of the mouse.
MESSAGE DATA
Hovering a message symbol shows up the message text and the corresponding time stamp.
User Guide Memento Documentation
48
CTRL-click on a message jumps to the message details in the Message List.
Memento Documentation User Guide
49
Main Window Message List Area
Memento Application – GUI Mode – Message List Area
The Message List area of the Memento GUI displays a time-ordered list of a selected set ofmessages.
The area has a tabular structure. There is one table row per message. There is one column permessage data field.
DATA FIELDS
The 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 MementoRing Buffer.
▶ Time: the Time attribute value assigned by the message contributor and expressed inseconds with 6 decimals.
▶ Delta: the time offset relative to the user-defined time reference; the value is expressed inseconds 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
▶ Stream: the Sream ID 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
User Guide Memento Documentation
50
▶ Trace: the text of the message body
▶ Comment: a user-editable data field
DATA FIELDS VISIBILITY SETTINGS
The user may display or hide each data-field column separately. The dialog box opens by right-clicking on the column headers.
The column order cannot be modified.
USER-DEFINED TIME REFERENCE
The user may use the time stamp of a message as the time-reference for the Delta data field.
This is achieved by right-clicking on a message to open a dialog box and then clicking on "Settime reference".
INJECTION OF CURRENT TIME
The user may request Memento to inject a message containing the UTC time and date in theMemento Ring.
This provides a sync point between the Memento time scale and the System time, itselfpossibly synchronized to an Internet Time Server.
This is achieved by right-clicking on a message to open a dialog box and then clicking on "InjectCurrent Time Trace".
RIGHT-CLICK MENU
The following pop-up menu appears when right-clicking in the message list:
Memento Application – GUI Mode – Message List Area Pop-up Menu
Possible actions are:
Memento Documentation User Guide
51
ROW RESIZING
To resize rows:
1. Select a row by clicking inside.
2. Adjust the row height by selecting top or bottom edge and dragging up or down the rowboundary.
3. Click on "Set current height to all rows" to uniformize the row height.
SET TIME REFERENCE
To define the time reference for the time shown in the "delta" column of the message list:
1. Select a row by clicking inside.
2. Click on "Set time reference".
INJECT CURRENT TIME TRACE
▶ Click on "Inject current time trace" insert a "UTC Time message" level in the Memento Ring.
COPY TO CLIPBOARD
To copy a selection of messages to the clipboard:
1. Select one message using the left click.
2. Optionally, select more messages using the shift-left click or the shit-right click.
3. Click on "Copy".
To copy all messages of the viewer buffer to the clipboard:
▶ Click on "Copy all".
PLOT FROM | PLOT TO | VIEW |ALL
To plot a set a messages in the message plot area:
1. Select the first message using the left click.
2. Click on "Plot from".
3. Select the last message using the left click.
4. Click on "Plot to".
The message plot area is resized to fit the messages set. The first message appears on the left-side and the last message appears 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".
User Guide Memento Documentation
52
AUTO-FOLLOW | NO AUTO-FOLLOW
To adjust automatically the left- and right-limits of the Message Plot to follow the arrival of newmessages:
▶ Click on "Auto-Follow".
To stop the automatic adjustment:
▶ Click on "No Auto-Follow".
Memento Documentation User Guide
53
Main Window Status Bar
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 ViewerBuffer.
▶ Traces: history # The number of Memento traces that are currently available in the ViewerBuffer.
▶ Delta time. The time difference between the selected message and the time reference. Thisvalue is also displayed in the delta column of the message list.
▶ Status. The operating status – Running – or – Suspended -- of the Memento Application.
User Guide Memento Documentation
54
Memento Reference
Memento Command Line 55COMMAND 56OPTIONS 57FILE 61
Command Line Samples 62
Memento Documentation Memento Reference
55
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 include:
▶ 0 or 1 COMMAND argument: gui, config, view, dump, xperf
▶ 0 or more OPTION flags
▶ 0 or 1 FILE argument
Memento Reference Memento Documentation
56
COMMANDThe COMMAND argument determines the operation mode of the Memento application.
Command Description
gui
Start Memento Graphical User Interface
This 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
config
Show/change Memento Configuration
Select this mode to show and possibly modify the Memento configuration using acommand line.
view
View Memento messages
Select this mode to view a selected set of messages of the Memento Ring Bufferusing a command line.
dump
Dump Memento data into file
Select this mode to dump Memento data from the Memento Ring Buffer to files ondisk using a command line.
xperf
Record Memento and XPerf data into file
Select this mode to record Memento and XPerf data to a disk file using a commandline.
The COMMAND argument is optional. When it is omitted, a default operation mode is selected:
▶ gui for Windows
▶ view for Linux
Memento Documentation Memento Reference
57
OPTIONS
Common Options
Option 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 Options
Option flags applicable when COMMAND=gui or when, for Windows only, theCOMMAND 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 after 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,Verbose
Default: Notice.
--history=INTNumber of history lines.
Default number: 250,000.
--duration=SEC Stop the application after the specified number of seconds.
Memento Reference Memento Documentation
58
Flag Description
--hide-console Don't show the application console.
--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 Options
Option flags applicable when COMMAND=config
Flag Description
--resetReset the Memento Configuration to default settings. This is performedbefore any other cation!
--verbosity=LEVEL
Set the verbosity level.
Possible values:None,Critical,Error,Warning,Notice,Info,Debug,Verbose
Default: Notice.
--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.
Memento Documentation Memento Reference
59
VIEW Options
Option flags applicable when COMMAND=view or when, for Linux only, theCOMMAND 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 after 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,Verbose
Default: Notice.
--colorEnable or disable colors.
Default: automatic detection.
--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
Memento Reference Memento Documentation
60
DUMP Options
Option 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.
--pastboot[=N]Go back N boot sessions in history.
Default: ignore past boot sessions.
--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 Options
Option 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 after the specified number of seconds
--group=GROUP|FLAGSXPerf group or flags
Default: DiagEasy
--show-in-explorer Show memento-xperf archive in Windows Explorer
--pause-on-error
Memento Documentation Memento Reference
61
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 anexisting dump file.
When it is omitted, the COMMAND is executed on the Memento Ring.
Memento Reference Memento Documentation
62
Command Line Samples
Starts 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
Memento Documentation Memento Reference