V6evalTool(3)

NAME
V6evalTool - Perl interface to write sequence script for IPv6 evaluation.

SYNOPSIS
  use V6evalTool;

  vStop(Link0);
  vClear(Link0);
  vCapture(Link0);
  %ret= vSend(Link0, frameA, frameB, frameC );
  %ret= vRecv(Link0, 0, 0, 0, (frameX, frameY) );
  if( $ret{status}!=0 ){
        vLog(NG);
        exit 1;
  }
  %ret=vRemote(remote_file, options, args_list);
  vLog(OK);
  $error_message= vErrmsg(%ret);
  $val= vRoundoff(timeval);

ENVIRONMENT
Directory of IPv6 evaluation environment is set -vroot option. In -vroot option, first is option setting direcory, second environment variable "V6EVALROOT", third "/usr/local/v6eval". All commands are assumed to be located at <-vroot option directory>/bin directory. Otherwise, this routines will not work.

DESCRIPTION
These routines allow you to write sequence script for IPv6 evaluation. Only one sequence script can run at the same time. There is no assurance for the case that multiple script run at the same time.

This module tries to catch SIGCHLD to detect termination of pktbuf process. Since this handler calls wait() to get the process id of the terminated child here, $? value will be invalid in case the user use wait() outside. In this case, the user should get the staus by using getChildStatus() function instead of looking up $? value. Because of the same reason, if the user wants to get the process id of child calling wait(), the retruned value will be also invalid. For this case, user can use getChildPid() function after calling wait().

The name of the sequence script is assumed 'xxxx.seq', where xxxx represents the type of the evaluation test. 'xxxx.seq' may have the following keyword parameters, and these are checked by this module at the package initialization.

                                                    < default value >
                                                    ------------------
  -tn       TN(Testing Node) configuration file     <dir>/tn.def
  -nut      NUT(Node Under Test) configuration file <dir>/nut.def
  -pkt      Packet definition file                  <dir>/packet.def
  -ti       Test Title (text)                       <script>
  -log      Log file                                <dir>/<script>.log
  -l        Log Level (0,1,2...)                    1
  -h        Help                                    N/A
  -v        log file print to STDOUT                0
  -nostd    not include std.def                     0
  -vroot    v6eval directory                        /usr/local/v6eval
  -remote   options passed to a remote ctrl. file   N/A

  <dir>:       directory of the sequence script located
  <script>:    sequence script name without extntion

FILES
 TN(Testing Node) configuration file;
 NUT(Node Under Test) configuration file:
    These files read from
        First   fullname -tn option sets
                option setting file
        Second  only file name -tn option sets
                search paths order
                1 <dir>/xxxx
                2 current directory/xxxx
                3 <V6Root>/etc/xxxx
        Third   -tn option does not set
                search paths order
                1 <dir>/tn.def
                2 current direcrory/tn.def
                3 <V6Root>/etc/tn.def

 Packet definition file:
    If -pkt option does not set
        <dir>/packet.def
    is default file

 Standard Difinition file:
    If -nostd option does not set
        search paths order
        1 current directory/std.def
        2 <V6Root>/include/std.def

 Other include file:
    include order
        1 current directory
        2 <V6Root>/include/ directory

  <V6Root>: directory set by -vroot option
  <dir>:    directory of the sequence script located

SUPPORTED FUNCTIONS

vSend
    Send frame to the interface.

     sub vSend($@) { my (

            $ifname,        # target interface name
            @frames         # frame names to send
     ) = @_;

    Returns hash value, and its information can be accessed by the following keys;

status
     =0:    normal
     >0:    error

sentTimeN
    Time of the specified N'th frame pushed to the specified interface for sending. For example, the time for the 1st frame will be referenced by $retval{'sentTime1'}. The value format is as follows;
     %ld[=epochtime].%06d[=microsecond]

vRecv
Receive frame from the interface.

 sub vRecv($$$$@) { my (
        $ifname,        # target interface name
        $timeout,       # expire time(second)
                        #       -1: No limitation
        $seektime,      # seek to the packet at the time(%ld.%06d)
                        #       0: seek from the beginning
                        #          of the captured buffer
                        #       You may use $retval{'sentTime(n)'}
                        #       returned by vSend().
        $count,         # How many frames to wait
                        #       0: No limitation
        @frames         # frame names to send
 ) = @_;

Returns hash value, and its information can be accessed by the following keys;

status:
     =0:     normal
      1:     receive time  exceeded
      2:     receive count exceeded
     >3:     error

recvCount;
    The number of frame received while calling this subroutine.

recvTime(N):
    Time of the specified N'th frame received from the specified interface. For example, the time for the 1st frame will be referenced by $retval{"recvTime1"}. The value format is as follows;
     %ld[=epochtime].%06d[=microsecond]

recvFrame:
    The name of the frame This will be normally one of the name in the frames specified in the argument. Otherwise, undef value in case of receive time or count exceeded.

vCapture
Start frame capture for the interface.

 sub vCapture($) { my (
        $ifname,        # target interface name
 ) = @_;

vCapture returns scaler value which represents the status
 =0: normal (even if already capturing)
 >0: error

vStop
Stop frame capture for the interface.

 sub vStop($) { my (
        $ifname,        # target interface name
 ) = @_;

Returns returns scaler value which represents the status
 =0: normal ( even if already stopped )
 >0: error

vClear
Clear captured buffer for the interface.

 sub vClear($) { my (
        $ifname,        # target interface name
 ) = @_;

Returns scaler value which represents the status
 =0: normal ( even if already cleared)
 >0: error

vSleep
suspend process execution for interval of seconds

 sub vSleep($;$) { my (
        $sec,
        $mesg
 ) = @_;

vRemote
Execute a remote control program.

 sub vRemote($;$@) { my (
        $remtoe_file    # A file name of remote control program.
        $options        # Options that pass to the program directly.
                        # See i/f of the remote control program.
        @argv           # Args that pass to the program directly
                        # that depends on the remote control program.
 ) = @_;

Returns exit value that the remote control program shows.
 =0:    noral
 >0:    error (that depend on the remote control program)

FILE SEARCH PATH
     A remote control program is searched as the following directories:
       1. The current directory.
       2. $V6EVALROOT/bin if defined.
          Or /usr/local/v6eval/bin if $V6EVALROOT is not defined.

EVALUATING THE OPTIONS
     The options are evaluated the following order:
       1. The definitions in TN.def or NUT.def
       2. -remote="..." options.
       3. vRemote(, "...", ) options.

THE RELATION TO TN/NUT DIFINITION FILES
     A TN.def VS. a remote control program options:
     ---------------+-----------------------
     TN.def
     Entries         Mapped options
     ---------------+-----------------------
     RemoteDevice    -d
     RemoteDebug     -v
     RemoteIntDebug  -i
     RemoteLog       -o
     RemoteSpeed     -s
     ---------------+-----------------------

     A NUT.def VS. a remote control program optons:
     ---------------+-----------------------
     NUT.def
     Entries         Mapped optons
     ---------------+-----------------------
     System          -t
     User            -u
     Password        -p
     ---------------+-----------------------

SEE ALSO
     V6evalRemote.pm (perldoc V6evalRemote)

vRemoteAsync
Asynchronous execution of a remote control program.

 sub vRemoteAsync($;$@) { my (
        $remtoe_file    # A file name of remote control program.
        $options        # Options that pass to the program directly.
                        # See i/f of the remote control program.
        @argv           # Args that pass to the program directly
                        # that depends on the remote control program.
 ) = @_;

Returns scaler value which represents the status
 =0:    normal
 >0:    error

This function forks and executes remote control program. Main sequence program can wait and synchronize the executing remote control program by vRemoteAsyncWait() function. Multiple vRemoteAsync() execution is unavailable. Executing vRemote() between vRemoteAsync() and vRemoteAsyncWait() is also unavailable. Details of other specification are same as vRemote().

vRemoteAsyncWait
Wait for an asynchronous remote control program executed by vRemoteAsync().

 sub vRemoteAsyncWait()

Returns exit value that the remote control program shows.
 =0:    normal
 >0:    error (that depend on the remote control program)

vLog
Output message to the log file

 sub vLog($) { my (
        $message,       # message to be logged
 ) = @_;

Returns nothing.

vErrmsg
Return error messages.

sub vErrmsg(%) { my (
    %stat    # return status
    ) = @_;

vRoundoff
Return time value that is rounded off to one decimal place

sub vRoundoff($) { my (
    $timeval    # sec.usec
    ) = @_;

vStatus
Get the status of packet buffering process.

 sub vStatus() { my (

        $ifname,        # target interface name
        @frames         # frame names to send
 ) = @_;

Returns hash value, and its information can be accessed by the following keys;

status
     =0:    normal
     >0:    error

XXXX
    not yet fiexed.

vMAC2LLAddr
create link local address from MAC address

sub vMAC2LLAddr(%) { my (

        $MACaddr        # MAC address
    ) = @_;

SEQUENCE SCRIPT EXAMPLE
  #!/usr/bin/perl

  use V6evalTool;

  #--------------------------------------------
  # Setup test environment
  #--------------------------------------------
  vStop(Link0);
  vClear(Link0);
  vCapture(Link0);

  #--------------------------------------------
  # Send frame
  #--------------------------------------------
  %sret= vSend(Link0, frame1, frame2 );
  if( $sret{status}!=0 ){
        vLog(NG);
        exit 1;
  }
  print "sentTime1:\t$sret{sentTime1}\n";
  print "sentTime2:\t$sret{sentTime2}\n";

  #--------------------------------------------
  # log some site specific messages
  #--------------------------------------------
  vLog("Something you need" );

  #--------------------------------------------
  # Receive frame
  #--------------------------------------------
  %rret= vRecv(Link0, 10, $sret{sentTime1}, 5,(frame1,frame2) );
  if( $rret{status}!=0 ){
        vLog(NG);
        exit 1;
  }
  print "recvFrame:\t$rret{recvFrame}\n";

  #--------------------------------------------
  # Post process
  #--------------------------------------------
  vLog(OK);