Skip to content

S
Software for White Rabbit PTP Core
Commit 02459900 authored by Adam Wujek's avatar Adam Wujek 💬
Browse files
Options

doc: add the documentation of SNMP 

Signed-off-by: Adam Wujek's avatarAdam Wujek <adam.wujek@cern.ch>
parent 4f8af252
Hide whitespace changes
Inline Side-by-side
Showing with 409 additions and 1 deletion
doc/wrpc.in
View file @ 02459900
......@@ -701,6 +701,414 @@ signal on the LEMO connector No. 1. Please remember to use oscilloscope cables
of the same length and type (with the same delay), or take their delay
difference into account in your measurements.
@c ==========================================================================
@node Diagnostics via SNMP
@section Diagnostics via SNMP
Up to the version 3.1 of @sc{wrpc} the only way to perform diagnostics
of the @t{wrpc-sw} was to use serial console with tools like @i{gui}, @i{stat},
etc. For some set-ups, like standalone node, it is very inconvenient to use
external console for diagnostics.
From the version 3.1 of @sc{wrpc} it is possible to include the @i{Mini
SNMP responder}, which allows to perform remote diagnostics using @i{SNMP} via
a port connected to the @i{Write Rabbit} network.
The configuration file of @sc{wrpc} contains the following
SNMP-related options:
@itemize
@item @t{CONFIG_SNMP} -- include the @i{Mini SNMP responder} into @sc{wrpc}
@item @t{CONFIG_SNMP_SET} -- enable the support of SNMP @i{SET} packets
@item @t{CONFIG_SNMP_VERBOSE} -- enable verbose output from the @i{Mini SNMP
responder} on the @sc{wrpc}'s console
@end itemize
The MIB file describing @sc{wrpc}'s OIDs can be found in the @t{lib} directory
of the @t{wrpc-sw} repo.
So far, the @i{Mini SNMP responder} supports version 1 and a subset of version
2c of the SNMP protocol.
The following types of requests are supported:
@itemize @bullet
@item GET -- get value of a given OID
@item GETNEXT -- get value of a next OID after the given OID (this is used
for @t{snmpwalk}s)
@item SET -- change the value of a given OID (so far used only for adding
SFP's to the database and PTP restarts)
@end itemize
The @i{Mini SNMP responder} does not support:
@itemize @bullet
@item bulk requests packets (GETBULK)
@item more than one OID in the request packet
@item @t{trap} and @t{inform} packets
@item encryption
@item authentication
@item SNMPv2c return error types; all returned error types follows SNMPv1
@end itemize
To make examples more readable, listings below use @t{SNMP_OPT} environment
variable. Make sure you set it properly in your shell.
@example
$ SNMP_OPT="-c public -v 2c -m WR-WRPC-MIB -M +/var/lib/mibs/ietf:lib \
192.168.1.20"
@end example
where:
@itemize @bullet
@item @t{-c public} -- sets SNMP community as "@i{public}"
@item @t{-v 2c} -- specifies SNMP version
@item @t{-m WR-WRPC-MIB} -- specifies MIBs to be loaded
@item @t{-M +/var/lib/mibs/ietf:lib} -- contains path to MIBs in the host
system (@t{/var/lib/mibs/ietf}) and path to @t{WR-WRPC-MIB} (@t{lib});
on Debian-like systems default MIBs can be downloaded using
@t{download-mibs} command (package @t{snmp-mibs-downloader}); on
CentOS and RedHat MIBs are included in the @t{libsmi} package
@item @t{192.168.1.20} -- the IP address of the target board
@end itemize
For example, to get the system uptime please execute the @t{snmpget} command:
@example
$ snmpget $SNMP_OPT wrpcTimeSystemUptime.0
@end example
To get dump of all available OIDs please execute the @t{snmpwalk} command:
@example
$ snmpwalk $SNMP_OPT wrpcCore
@end example
Part of the @t{snmpwalk}'s output:
@example
WR-WRPC-MIB::wrpcVersionHwType.0 = STRING: spec
WR-WRPC-MIB::wrpcVersionSwVersion.0 = STRING: wrpc-v3.0-251-g14e952e
WR-WRPC-MIB::wrpcVersionSwBuildBy.0 = STRING: Adam Wujek
WR-WRPC-MIB::wrpcVersionSwBuildDate.0 = STRING: Jun 7 2016 18:12:24
WR-WRPC-MIB::wrpcTimeTAI.0 = Counter64: 1465375022
WR-WRPC-MIB::wrpcTimeTAIString.0 = STRING: 2016-06-08-08:37:02
WR-WRPC-MIB::wrpcTimeSystemUptime.0 = Timeticks: (18186) 0:03:01.86
WR-WRPC-MIB::wrpcTemperatureName.1 = STRING: pcb
WR-WRPC-MIB::wrpcTemperatureValue.1 = STRING: 38.5625
WR-WRPC-MIB::wrpcSpllMode.0 = INTEGER: slave(3)
WR-WRPC-MIB::wrpcSpllIrqCnt.0 = Counter32: 1259605
[...]
WR-WRPC-MIB::wrpcPortSfpInDB.0 = INTEGER: inDataBase(2)
WR-WRPC-MIB::wrpcPortInternalTx.0 = Counter32: 452
WR-WRPC-MIB::wrpcPortInternalRx.0 = Counter32: 869
WR-WRPC-MIB::wrpcSfpPn.1 = STRING: AXGE-1254-0531
WR-WRPC-MIB::wrpcSfpDeltaTx.1 = INTEGER: 180625
WR-WRPC-MIB::wrpcSfpDeltaRx.1 = INTEGER: 148451
WR-WRPC-MIB::wrpcSfpAlpha.1 = INTEGER: 72169888
End of MIB
@end example
It is recommended to use SNMP v2c for communication with the @sc{wrpc}.
Please note that when the version 1 of SNMP is used, 64 bit counters are not
supported. This makes it impossible to read some @sc{wrpc}'s objects with
SNMPv1.
@c --------------------------------------------------------------------------
@node Managing SFP database via SNMP
@subsection Managing SFP database via SNMP
The SFPs database can be displayed using the @t{sfp show} command from
the @sc{wrpc}'s console:
@example
wrc# sfp show
1: PN:AXGE-1254-0531 dTx: 180625 dRx: 148451 alpha: 72169888
2: PN:AXGE-3454-0531 dTx: 180625 dRx: 148451 alpha: -73685416
@end example
The same data is exported by the @i{Mini SNMP responder} via the table
@t{wrpcSfpTable}:
@example
$ snmpwalk $SNMP_OPT wrpcSfpTable
WR-WRPC-MIB::wrpcSfpPn.1 = STRING: AXGE-1254-0531
WR-WRPC-MIB::wrpcSfpPn.2 = STRING: AXGE-3454-0531
WR-WRPC-MIB::wrpcSfpDeltaTx.1 = INTEGER: 180625
WR-WRPC-MIB::wrpcSfpDeltaTx.2 = INTEGER: 180625
WR-WRPC-MIB::wrpcSfpDeltaRx.1 = INTEGER: 148451
WR-WRPC-MIB::wrpcSfpDeltaRx.2 = INTEGER: 148451
WR-WRPC-MIB::wrpcSfpAlpha.1 = INTEGER: 72169888
WR-WRPC-MIB::wrpcSfpAlpha.2 = INTEGER: -73685416
End of MIB
@end example
When the SET support is compiled into the @i{Mini SNMP responder}, it is
possible to erase or add/replace SFP entires to the SFPs database via SNMP.
Addition (or modification) of one SFP to the database can done by a row of
SNMP SETs. Firstly, please set the delta Tx (@t{wrpcPtpConfigDeltaTx.0}), the
delta Rx (@t{wrpcPtpConfigDeltaRx.0}) and the alpha (@t{wrpcPtpConfigAlpha.0})
with new values.
Then, to commit the change to the SFP database, perform the SNMP SET on
the @t{wrpcPtpConfigApply.0} with the value @t{writeToFlashCurrentSfp}. It will
add/update values for the currently plugged SFP.
To add/update entries for different SFPs, please set deltas and alpha like
above, then set PN of an SFP to the @t{wrpcPtpConfigSfpPn.0} and commit
the change by setting @t{writeToFlashGivenSfp} to the @t{wrpcPtpConfigApply.0}.
It is also possible to update values in the memory for the current SFP.
For that, please set delta Tx, delta Rx and alpha as described above,
then set @t{writeToMemoryCurrentSfp} to the @t{wrpcPtpConfigApply.0}
Please be aware that these changes will be lost after a power cycle of a board,
soft reset of @sc{wrpc} or unplug/plug of a fiber/SFP.
Currently, after the update of SFP values in the memory, PTP is restarted.
Such restart is necessary because PTP does not support on-the-fly changes of
deltas nor alpha. It is expected that this behavior will change in the future.
If a database entry of the SFP, which is currently used was updated, it is
necessary to perform a restart of the PTP daemon
(set @t{wrpcPtpConfigRestart.0} with the value @t{restartPtp}).
Each SNMP SET of @t{wrpcPtpConfigApply.0} or @t{wrpcPtpConfigRestart.0} returns
the status of a performed action. For details please check @t{WR-WRPC-MIB}
file.
Commands below add an SFP with PN as "@t{NEW-SFP}", delta Tx "@t{1111}",
delta Rx "@t{2222}" and alpha "@t{3333}".
@example
$ snmpset $SNMP_OPT wrpcPtpConfigDeltaTx.0 = 1111
WR-WRPC-MIB::wrpcPtpConfigDeltaTx.0 = INTEGER: 1111
$ snmpset $SNMP_OPT wrpcPtpConfigDeltaRx.0 = 2222
WR-WRPC-MIB::wrpcPtpConfigDeltaRx.0 = INTEGER: 2222
$ snmpset $SNMP_OPT wrpcPtpConfigAlpha.0 = 3333
WR-WRPC-MIB::wrpcPtpConfigAlpha.0 = INTEGER: 3333
$ snmpset $SNMP_OPT wrpcPtpConfigSfpPn.0 = NEW-SFP
WR-WRPC-MIB::wrpcPtpConfigSfpPn.0 = STRING: "NEW-SFP"
$ snmpset $SNMP_OPT wrpcPtpConfigApply.0 = writeToFlashGivenSfp
WR-WRPC-MIB::wrpcPtpConfigApply.0 = INTEGER: applySuccessful(100)
@end example
In case the SFP database does not contain the currently plugged SFP, the last
@t{snmpset} command will return @t{applySuccessfulMatchFailed(101)}.
Optionally restart the PTP:
@example
$ snmpset $SNMP_OPT wrpcPtpConfigRestart.0 = restartPtp
WR-WRPC-MIB::wrpcPtpConfigRestart.0 = INTEGER: restartPtpSuccessful(100)
@end example
Simple verification of performed actions:
@example
wrc# sfp show
1: PN:AXGE-1254-0531 dTx: 180625 dRx: 148451 alpha: 72169888
2: PN:AXGE-3454-0531 dTx: 180625 dRx: 148451 alpha: -73685416
3: PN:NEW-SFP dTx: 1111 dRx: 2222 alpha: 3333
@end example
The same add can also be achieved by performing @t{sfp add} command in
the @sc{wrpc}'s console:
@example
wrc# sfp add NEW-SFP 1111 2222 3333
Update existing SFP entry
3 SFPs in DB
@end example
Verify the result via SNMP:
@example
$ snmpwalk $SNMP_OPT wrpcSfpTable
WR-WRPC-MIB::wrpcSfpPn.1 = STRING: AXGE-1254-0531
WR-WRPC-MIB::wrpcSfpPn.2 = STRING: AXGE-3454-0531
WR-WRPC-MIB::wrpcSfpPn.3 = STRING: NEW-SFP
WR-WRPC-MIB::wrpcSfpDeltaTx.1 = INTEGER: 180625
WR-WRPC-MIB::wrpcSfpDeltaTx.2 = INTEGER: 180625
WR-WRPC-MIB::wrpcSfpDeltaTx.3 = INTEGER: 1111
WR-WRPC-MIB::wrpcSfpDeltaRx.1 = INTEGER: 148451
WR-WRPC-MIB::wrpcSfpDeltaRx.2 = INTEGER: 148451
WR-WRPC-MIB::wrpcSfpDeltaRx.3 = INTEGER: 2222
WR-WRPC-MIB::wrpcSfpAlpha.1 = INTEGER: 72169888
WR-WRPC-MIB::wrpcSfpAlpha.2 = INTEGER: -73685416
WR-WRPC-MIB::wrpcSfpAlpha.3 = INTEGER: 3333
End of MIB
@end example
It is also possible to erase the SFPs database via SNMP (equivalent of
the @t{sfp erase} command):
@example
$ snmpset $SNMP_OPT wrpcPtpConfigApply.0 = eraseFlash
WR-WRPC-MIB::wrpcPtpConfigApply.0 = INTEGER: applySuccessful(100)
@end example
To verify that database is empty:
@example
wrc# sfp show
SFP database empty
@end example
@c --------------------------------------------------------------------------
@node Adding new objects to the SNMP
@subsection Adding new objects to the SNMP
The @i{Mini SNMP responder} can be easily expanded to export new objects.
Values of new objects can come from @sc{wrpc}'s variables or other HDL modules
as long as there is a proper interface to the @sc{wrpc} to read these values.
This section contains the instruction how to export new objects with
the given variables' content.
The @i{Mini SNMP responder} internally divides all OIDs into two parts.
The first part is called @i{limb}. The @i{limb} part of the incoming OID is
matched by a function @t{snmp_respond}, with the defined @i{limb} parts of OIDs
in the structure @t{oid_limb_array}.
When the @i{limb} part is matched then the corresponding function from
the structure @t{oid_limb_array} is called to try to match the second part of
OID (the @i{twig} part).
The example below adds to the @i{Mini SNMP responder} an @t{int32_t} variable
(@t{example_i32var}) with OID @t{1.3.6.1.4.1.96.102.1.1.0} and a string
(@t{example_string}) with OID @t{1.3.6.1.4.1.96.102.1.2.0}.
Before assigning new OIDs in your projects please contact the maintainer of
@t{wrpc-sw} repo to avoid conflicts.
@itemize
@item First declare @t{example_i32var} and @t{example_string}:
@smallexample
static int32_t example_i32var;
static char example_string[] = "test string";
@end smallexample
@item Define the @i{limb} part of the OID:
@smallexample
static uint8_t oid_wrpcExampleGroup[] = {0x2B,6,1,4,1,96,101,99};
@end smallexample
@item Define the @i{twig} part of the OID:
@smallexample
static uint8_t oid_wrpcExampleV1[] = {1,0};
static uint8_t oid_wrpcExampleV2[] = {2,0};
@end smallexample
@item Add a group definition to the @t{struct snmp_oid_limb oid_limb_array}.
Please note that this structure has to be sorted by ascending OIDs.
@smallexample
OID_LIMB_FIELD(oid_wrpcExampleGroup, func_group, oid_array_wrpcExampleGroup),
@end smallexample
The macro @t{OID_LIMB_FIELD} takes the following arguments:
@itemize @bullet
@item @t{oid_wrpcExampleGroup} -- an array with the @i{limb} part of the
OID
@item @t{func_group} -- a function to be called when the @i{limb} part of
the OID is matched; this function will try to match the @i{twig} part
of the OID within a table or a group.
@item @t{oid_array_wrpcExampleGroup} -- an array of @i{twig} parts of OIDs
@end itemize
@item Declare a previously used @t{oid_wrpcExampleGroup}. Please note that
this structure has to be sorted by ascending @i{twig} part of OIDs.
@smallexample
static struct snmp_oid oid_array_wrpcExampleGroup[] = {
OID_FIELD_VAR(oid_wrpcExampleV1, get_p, set_p, ASN_INTEGER, &example_i32var),
OID_FIELD_VAR(oid_wrpcExampleV2, get_p, set_p, ASN_OCTET_STR, &example_string),
{ 0, }
};
@end smallexample
The macro @t{OID_FIELD_VAR} takes the following arguments:
@itemize @bullet
@item @t{oid_wrpcExampleV1} -- an array with @i{twig} part of the OID
@item @t{get_p} (or @t{get_pp)} -- a function to be called when @i{twig}
part of the OID is matched for SNMP GET requests;
@item @t{set_p} (or @t{set_pp)} -- a function to be called when a @i{twig}
part of the OID is matched for SNMP SET requests; if no SET
functionality is planned, please use NULL
@item @t{ASN_INTEGER, ASN_OCTET_STR} -- type of the OID; please
check the source for other possible types
@item @t{&example_i32var, &example_string} -- addresses to the data in
memory
@end itemize
In case the address of variables is not known at boot, it is possible to define
a pointer to the variable which will be initialized (e.g. in the @t{snmp_init}
the function) at the boot time. In that case function @t{get_pp} (@t{set_pp}) has
to be used instead of @t{get_p} (@t{set_p}). For variables that are a part of
a structure and have to be accessed via a pointer, a macro @t{OID_FIELD_STRUCT}
is available.
For more complex extraction of variables or run-time value corrections,
it is possible to use a custom @i{get} function. It is possible to pass
a constant number to the custom function instead of an address. For example:
@smallexample
OID_FIELD_VAR(oid_wrpcPtpServoUpdateTime, get_servo, NO_SET, ASN_COUNTER64, \
SERVO_UPDATE_TIME),
@end smallexample
@end itemize
Perform a @t{snmpwalk} to get new OIDs:
@smallexample
$ snmpwalk -On $SNMP_OPT 1.3.6.1.4.1.96.102.1
.1.3.6.1.4.1.96.102.1.1.0 = INTEGER: 123432
.1.3.6.1.4.1.96.102.1.2.0 = STRING: "test string"
End of MIB
@end smallexample
Trying to set too long string into the @t{example_string} results in an error:
@smallexample
$ snmpset -On $SNMP_OPT 1.3.6.1.4.1.96.102.1.2.0 s "new long string"
Error in packet.
Reason: (badValue) The value given has the wrong type or length.
Failed object: .1.3.6.1.4.1.96.102.1.2.0
@end smallexample
A short enough (not longer than defined @t{"test string"}) value succeeds:
@smallexample
$ snmpset -On $SNMP_OPT 1.3.6.1.4.1.96.102.1.2.0 s "new value12"
.1.3.6.1.4.1.96.102.1.2.0 = STRING: "new value12"
@end smallexample
Set 999 to the @t{example_i32var}:
@smallexample
$ snmpset -On $SNMP_OPT 1.3.6.1.4.1.96.102.1.1.0 i 999
.1.3.6.1.4.1.96.102.1.1.0 = INTEGER: 999
@end smallexample
Perform @t{snmpwalk} to verify changes:
@smallexample
$ snmpwalk -On $SNMP_OPT 1.3.6.1.4.1.96.102.1
.1.3.6.1.4.1.96.102.1.1.0 = INTEGER: 999
.1.3.6.1.4.1.96.102.1.2.0 = STRING: "new value12"
End of MIB
@end smallexample
@c --------------------------------------------------------------------------
@node Mini SNMP responder's tests
@subsection Mini SNMP responder's tests
In the @t{wrpc-sw} repo, automatic tests are available to validate the @i{Mini
SNMP responder} implementation. These tests are placed in the @t{test/snmp}
directory.
They use the @t{bats} framework (@uref{https://github.com/sstephenson/bats}).
To run these tests, please go to @t{test/snmp} directory, then set
@t{TARGET_IP} environment varaible to the IP of your target board, then type
@t{make}. For example:
@example
$ TARGET_IP=192.168.1.20 make
bats/libexec/bats snmp_tests_*.bats
Host up 192.168.1.20
Check the presence of snmpget
Check the presence of snmpgetnext
Check the presence of snmpwalk
Check the presence of snmpset
snmpget existing oid 1.3.6.1.4.1.96.101.1.1.1.0
[...]
snmpwalk 1.3.6.1.4.1.95
snmpwalk 1.3.6 count all OIDs
100 tests, 0 failures
@end example
On the left of each test there will be a tick symbol shown or an @t{x}
depending of the test's result (not included in the example above).
Be aware that it might be necessary to clone the @t{bats} repo first.
@t{make} command will inform whether this is needed.
In case the number of OIDs changes please correct variable @t{TOTAL_NUM_OIDS}
in file @t{snmp_test_config.bash}.
These tests have to be executed after any changes are made to the @i{Mini SNMP
responder}.
@c ##########################################################################
@node Troubleshooting
@chapter Troubleshooting
......@@ -814,7 +1222,7 @@ aligned to external 1-PPS and 10 MHz)
@item @code{sfp erase} @tab erases the @sc{sfp} database stored in the Flash/EEPROM
@item @code{sfp add <ID> <deltaTx> <deltaRx> <alpha>} @tab stores calibration
@item @code{sfp add <PN> <deltaTx> <deltaRx> <alpha>} @tab stores calibration
parameters for @sc{sfp} to a file in Flash/EEPROM
@item @code{sfp show} @tab prints all @sc{sfp} transceivers stored in database
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment