.PU
.TH qbg22sim 1 "LLDPAD" "Revision: 0.4"
.SH NAME
qbg22sim \- EVB, ECP and VDP Protocol Test Program for LLDPAD
.SH SYNOPSIS
.ll +8
.br
.B qbg22sim
[\-d duration] [\-t timeout] [\-T timeout] [\-v] device [file]
.br
.ll -8
.SH DESCRIPTION
.B Qbg22sim
sends IEEE 802.1ad LLDP protocol messages which contain
an IEEE802.1Qbg EVB data unit TLV.
It also
sends IEEE 802.1Qbg ECP protocol messages which contain
an arbitrary data payload in TLV format.
It can automaticly send IEEE 802.1Qbg VDP protocol
acknowledgements with a given response code.
Only the IEEE 802.1Qbg Darft 2.2 (ratified on July 5th, 2012)
is supported.
.PP
The mandatory device parameter specifies
a network interface name.
This interface is opened in raw mode and
listens to LLDP messages (ethertype 0x88cc)
and ECP messages (ethertype 0x8890)
targeted
to multicast addresses for nearest bridge,
nearest customer bridge and nearest non two port MAC relay bridge.
The purpose of the low level test program is to test 
.BR lldpad (8)
EVB, ECP and VDP module interaction by sending EVB/ECP TLV data.
The data is read from one or more files,
the response received can be displayed on the screen and
optionally checked against an expected value.
If no input file is specified
.B qbg22sim
only listen but do not send any data units.
A dash stands for standard input.
The input files are preprocessed by 
.BR cpp (1).
All
.BR cpp (1)
features can be used, including comments, defines, include files.
.SS Event Handling
.B qbg22sim
use the select(2) system call to wait for a message and
a timer event.
The timer is a periodic timer and initially loaded
with the values specified with the options -t and -T.
The default value is one second and zero nano seconds.
Each time the timer expires
.B qbg22sim
checks for messages to send.
If the elapsed run time of the program is
larger or equal to the time specified in the first field
of the configuration file, those lines are transmitted.
Note that only one transmission per timer invocation
is capable to check optional replies for an expected TLV.
If more than one line have the same elapsed time, then only
the last line sent can have expected reply TLVs (see below).
.SS Input File Layout
The input file is read line by line.
Each line specifies a complete
entry, long lines can be split by a
trailing backslash newline combination.
Each line is divided by blanks or tabs into several fields.
.IP 1
The first field specifies the elapsed time in seconds
when the remaining data on the line will be sent.
.IP 2
The second field specifies the destination MAC address.
If the second field on one of the keywords
.I ecp
or
.I vdp
this entry specifies a command line.
Command lines alter the behavior of
.B qbg22sim
for the named protocol.
.RS
In this case the third and forth field
specify parameter and value.
At the time specified, the parameter for the
procotol is changed and applied until the
program terminates or the
parameter is changed again.
For the
.I ecp
protocol the valid parameters are
.IP ack
The forth field
specifies the time to wait in seconds until ECP
protocol
acknowledgement is sent. A value of 0 stands for
no delay at all. A value larger then 20 seconds
disables acknowledgements.
.IP seqno
The forth field
specifies the next sequence number to use when
a VDP protocol message triggers an ECP acknowledgement.
.PP
For the
.I vdp
protocol the valid parameters are
.IP ack
The forth field
specifies the time to wait in seconds until VDP
protocol
acknowledgement is sent. A value of 0 stands for
no delay at all. A value larger then 30 seconds
disables acknowledgements.
.IP error
The forth field
specifies the error number to be returned when
a VDP protocol message requesting an association
is received.
.RE
.IP 3
The third field specifies the sender's MAC address.
A dash ('-') will be replaced by the sender's MAC address on 
transmission.
.IP 4
The forth field specifies the ethertype variable.
For LLDP protocol this should be 88cc.
For ECP protocol this should be 8890 (in hex).
Any other protocols are not supported and the
program exits with an appropriate error message.
The value of this field determines the data layout
of the remaining fields.
.IP 5
The remaining fields specify the LLDP protocol TLVs
or the ECP protocol TLVs.
There is no check for consistency, but at least the 
mandatory LLDP protocol TLVs (which are
chassis identifier, port identifer, time to live (TTL), and
End) have to be listed.
To be useful an EVB TLV should be included.
The same is true for the ECP protocol. At least an
ECP protocol header has to be listed.
.IP 6
When a TLV is preceded by an at-sign ('@'), this TLV
is not
transmitted, but added to an expected reply list.
When the LLDP data unit is sent out, a possible
reply from
.BR lldpad (8)
is waited for and searched.
If the reply contains this TLV and they match, the program
continues. If they mismatch or the expected TLV is not
found in the reply,
.B qbg22sim
terminates.
If there is no reply at all
.B qbg22sim
issues a warning, discards the expected TLV list and continues.
Missing EVB protocol replies,
even when expected TLVs are specified, do not cause
.B qbg22sim
to terminate.
.B qbg22sim
waits for a possible reply up to the next timer expiration.
This simulates the LLDP TLV exchange mechanims as defined in the standard.
.PP
All fields represent byte streams.
Each byte is denoted by a two digit hexadecimal number.
Bytes are delimited by colon.
Little to no input file checking is done.
As an example the string 88:cc
is the ethertype field for LLDP data units.
.sp 1
Here is a sample input file with explanations.
.IP A.
The first line contains an EVP TLV and is sent after four seconds
program run time. The line expects a reply from 
.BR lldpad (8)
which contains the reply to the EVB TLV just sent out.
In this case
.BR lldpad (8)
is configured as station and does not request 
reflective-relay. Other values are defaults.
.IP B.
The second, third and forth line resend
the first line to simulate fast initialization.
Same replies are expected.
.IP C.
The last line is executed after 20 seconds program run time.
It sends a TTL TLV of value 0 and causes the EVB entry on the
remote side to be discarded.
.PP
.ne 20
.EX
.nf
/*
 * Startup the EVB negotiation
 */

#define	dst_mac		01:80:c2:00:00:0e
#define	lldp_type	88:cc
#define	chassis_tlv	02:07:06:64:75:6d:6d:79:00
#define	port_tlv		04:05:05:65:74:68:30
#define	ttl_tlv120	06:02:00:78
#define	ttl_tlv0		06:02:00:00
#define	end_tlv		00:00

#define	evbhead		fe:09:00:80:c2:0d
/* No Reflective Relay on bridge */
#define	evb_norr		evbhead:00:00:00:40:00
#define	evb_norr_ack	evbhead:00:00:68:88:08

4	dst_mac - lldp_type chassis_tlv port_tlv ttl_tlv120 \\
		evb_norr end_tlv @evb_norr_ack
5	dst_mac - lldp_type chassis_tlv port_tlv ttl_tlv120 \\
		evb_norr end_tlv @evb_norr_ack
6	dst_mac - lldp_type chassis_tlv port_tlv ttl_tlv120 \\
		evb_norr end_tlv @evb_norr_ack
7	dst_mac - lldp_type chassis_tlv port_tlv ttl_tlv120 \\
		evb_norr end_tlv @evb_norr_ack
20	dst_mac - lldp_type chassis_tlv port_tlv ttl_tlv0 end_tlv
.fi
.EE
.PP
Now following is an example file for ECP protocol negotiation:
.IP A.
The first line contains an ECP TLV and is sent after 18 seconds.
It consists of the ECP header with version, operation and subtype.
The next field contains the sequence number followed by
a 4 byte payload data and the END TLV.
.IP B.
The second and third line send the same data, only the sequence
number is incremented.
No reply is expected.
.PP
.ne 20
.EX
.nf
/*
 * ECP Protocol test data. Define a complete ECP DU in hex. One complete set
 * is needed for each transmission.
 */
#define	lldpad_mac	01:80:c2:00:00:00
#define	end_tlv		00:00
#define	ecp_type	88:90

#include	"defines.ecp"

18	lldpad_mac - ecp_type 10:01 12:24 0a:0b:0c:0d end_tlv
21	lldpad_mac - ecp_type 10:01 12:25 0a:0b:0c:0d end_tlv
24	lldpad_mac - ecp_type 10:01 12:26 0a:0b:0c:0d end_tlv
.EE
.SH OPTIONS
.TP
.B "\-v"
Enables verbose mode. This option can be applied more
than once.
Each time specified, the output is more verbose.
If set once, 
.B qbg22sim
displays the progress of sent and received messages.
If set twice,
the message contents is also displayed.
If set three times,
the event wait time is also displayed.
.TP
.B "\-d\fIduration\fP"
Specifies the number in seconds the program will run.
Defaults to 120 seconds of total run time.
.TP
.B "\-t\fItimeout\fP"
Specifies the time (seconds portion) to wait for an event.
Default is one.
.TP
.B "\-T\fItimeout\fP"
Specifies the time (nano-seconds portion) to wait for an event.
Default is zero.
.SH "ENVIRONMENT"
Linux and virtual machines connected with a virtual bridge.
Requires Linux kernel 3.2 or later.
Disable stp on the virtual bridge to forward mutlicast mac addresses
01:80:C2:00:00:00!
.SH "SEE ALSO"
lldpad(8), lldptool(8)
.SH DIAGNOSTICS
Exit status is zero on success and non zero on failure or mismatch.
.SH AUTHOR
Thomas Richter, IBM Research and Development GmbH, Germany.
