From 3fef8f811a013d1392f702fda1347c5211471ed7 Mon Sep 17 00:00:00 2001 From: Dave Barach Date: Fri, 15 Mar 2019 11:27:30 -0400 Subject: DOC ONLY: fix g2 build documentation Removed a broken paragraph, replaced it with a link. Some nuisance white-space cleanups courtesy of emacs: (add-hook 'before-save-hook 'delete-trailing-whitespace) Change-Id: Ib348107c2dc0df8249461591015347d7b4f6fa4a Signed-off-by: Dave Barach --- .../developers/buildsystem/cmakeandninja.rst | 48 +++++++++++----------- docs/gettingstarted/developers/eventviewer.rst | 45 +++++++++----------- 2 files changed, 44 insertions(+), 49 deletions(-) diff --git a/docs/gettingstarted/developers/buildsystem/cmakeandninja.rst b/docs/gettingstarted/developers/buildsystem/cmakeandninja.rst index 86638beb088..b6d83f225ce 100644 --- a/docs/gettingstarted/developers/buildsystem/cmakeandninja.rst +++ b/docs/gettingstarted/developers/buildsystem/cmakeandninja.rst @@ -26,7 +26,7 @@ of files: rule/function definitions, and target lists. - Build target lists come from CMakeLists.txt files found in subdirectories, which are named in the SUBDIRS list in .../src/CMakeLists.txt :: - + ############################################################################## # subdirs - order matters ############################################################################## @@ -46,7 +46,7 @@ of files: rule/function definitions, and target lists. endforeach() - The vpp cmake configuration hierarchy discovers the list of plugins to be built by searching for subdirectories in .../src/plugins which contain CMakeLists.txt files - + :: @@ -61,13 +61,13 @@ of files: rule/function definitions, and target lists. get_filename_component(dir ${f} DIRECTORY) add_subdirectory(${dir}) endforeach() - + How to write a plugin CMakeLists.txt file ----------------------------------------- It's really quite simple. Follow the pattern: -:: +:: add_vpp_plugin(mactime SOURCES @@ -83,7 +83,7 @@ It's really quite simple. Follow the pattern: API_TEST_SOURCES mactime_test.c - ) + ) Adding a target elsewhere in the source tree -------------------------------------------- @@ -92,9 +92,11 @@ Within reason, adding a subdirectory to the SUBDIRS list in .../src/CMakeLists.txt is perfectly OK. The indicated directory will need a CMakeLists.txt file. +.. _building-g2: + Here's how we build the g2 event data visualization tool: -:: +:: option(VPP_BUILD_G2 "Build g2 tool." OFF) if(VPP_BUILD_G2) @@ -134,7 +136,7 @@ how the top-level Makefile and .../build-root/Makefile set all of the cmake arguments. One strategy to enable an optional component is fairly obvious. Add -DVPP_BUILD_G2=ON to vpp_cmake_args. -That would work, of course, but it's not a particularly elegant solution. +That would work, of course, but it's not a particularly elegant solution. Tinkering with build options: ccmake ------------------------------------ @@ -151,25 +153,25 @@ Here's approximately what you'll see: :: - CCACHE_FOUND /usr/bin/ccache - CMAKE_BUILD_TYPE + CCACHE_FOUND /usr/bin/ccache + CMAKE_BUILD_TYPE CMAKE_INSTALL_PREFIX /scratch/vpp-gate/build-root/install-vpp-nati DPDK_INCLUDE_DIR /scratch/vpp-gate/build-root/install-vpp-nati DPDK_LIB /scratch/vpp-gate/build-root/install-vpp-nati - MBEDTLS_INCLUDE_DIR /usr/include - MBEDTLS_LIB1 /usr/lib/x86_64-linux-gnu/libmbedtls.so - MBEDTLS_LIB2 /usr/lib/x86_64-linux-gnu/libmbedx509.so - MBEDTLS_LIB3 /usr/lib/x86_64-linux-gnu/libmbedcrypto.so - MUSDK_INCLUDE_DIR MUSDK_INCLUDE_DIR-NOTFOUND - MUSDK_LIB MUSDK_LIB-NOTFOUND - PRE_DATA_SIZE 128 - VPP_API_TEST_BUILTIN ON - VPP_BUILD_G2 OFF - VPP_BUILD_PERFTOOL OFF - VPP_BUILD_VCL_TESTS ON - VPP_BUILD_VPPINFRA_TESTS OFF - - CCACHE_FOUND: Path to a program. + MBEDTLS_INCLUDE_DIR /usr/include + MBEDTLS_LIB1 /usr/lib/x86_64-linux-gnu/libmbedtls.so + MBEDTLS_LIB2 /usr/lib/x86_64-linux-gnu/libmbedx509.so + MBEDTLS_LIB3 /usr/lib/x86_64-linux-gnu/libmbedcrypto.so + MUSDK_INCLUDE_DIR MUSDK_INCLUDE_DIR-NOTFOUND + MUSDK_LIB MUSDK_LIB-NOTFOUND + PRE_DATA_SIZE 128 + VPP_API_TEST_BUILTIN ON + VPP_BUILD_G2 OFF + VPP_BUILD_PERFTOOL OFF + VPP_BUILD_VCL_TESTS ON + VPP_BUILD_VPPINFRA_TESTS OFF + + CCACHE_FOUND: Path to a program. Press [enter] to edit option Press [d] to delete an entry CMake Version 3.10.2 Press [c] to configure Press [h] for help Press [q] to quit without generating diff --git a/docs/gettingstarted/developers/eventviewer.rst b/docs/gettingstarted/developers/eventviewer.rst index 19d3e7c3c59..59aaef0604d 100644 --- a/docs/gettingstarted/developers/eventviewer.rst +++ b/docs/gettingstarted/developers/eventviewer.rst @@ -16,7 +16,7 @@ A typical event definition and logging call looks like this: .. code-block:: c - ELOG_TYPE_DECLARE (e) = + ELOG_TYPE_DECLARE (e) = { .format = "tx-msg: stream %d local seq %d attempt %d", .format_args = "i4i4i4", @@ -35,7 +35,7 @@ pretty-prints enumerated values: .. code-block:: c - ELOG_TYPE_DECLARE (e) = + ELOG_TYPE_DECLARE (e) = { .format = "get_or_create: %s", .format_args = "t4", @@ -104,17 +104,10 @@ highly scalable, supporting O(1e7 events) and O(1e3 discrete display "tracks"). G2 displays binary data generated by the vppinfra "elog.[ch]" logger component, and also supports the CPEL file format, as described in this section. -Building --------------- +Building G2 +----------- -.. code-block:: console - - $ cd build-root - $ make g2-install - $ ./install-native/g2/bin/g2 --help - g2 [--ticks-per-us ][--cpel-input ] [--clib-input - G2 (x86_64 GNU/Linux) major version 3.0 - Built Wed Feb 3 10:58:12 EST 2016 +This link describes :ref:`how to build G2 ` Setting the Display Preferences ------------------------------------------------ @@ -131,7 +124,7 @@ Simply un-comment one of the stanzas shown below, or experiment as desired. * event_selector_lines=20 * drawbox_height=800 * drawbox_width=600 - * + * * new mac w/ no monitor: * event_selector_lines=20 * drawbox_height=1200 @@ -141,7 +134,7 @@ Simply un-comment one of the stanzas shown below, or experiment as desired. * drawbox_width=1200 * drawbox_height=1000 * event_selector_lines=25 - * + * * for making screenshots on a Macbook Pro * drawbox_width=1200 * drawbox_height=600 @@ -152,36 +145,36 @@ Screen Taxonomy ---------------------------- Here is an annotated G2 viewer screenshot, corresponding to activity during BGP -prefix download. This data was captured on a Cisco IOS-XR system: +prefix download. This data was captured on a Cisco IOS-XR system: .. figure:: /_images/g21.jpg :scale: 75% - + The viewer has two main scrollbars: the horizontal axis scrollbar shifts the main drawing area in time; the vertical axis changes the set of visible process traces. The zoomin / zoomout operators change the time scale. -The event selector PolyCheckMenu changes the set of displayed events. +The event selector PolyCheckMenu changes the set of displayed events. Using these tools -- and some patience -- you can understand a given event log. Mouse Gestures ------------------------- G2 has three fairly sophisticated mouse gesture interfaces, which are worth describing -in detail. First, a left mouse click on a display event pops up a per-event detail box. +in detail. First, a left mouse click on a display event pops up a per-event detail box. .. figure:: /_images/g22.jpg :scale: 75% -A left mouse click on an event detail box closes it. +A left mouse click on an event detail box closes it. To zoom to a region of the display, press and hold the left mouse button, then drag right or left until the zoom-fence pair appears: .. figure:: /_images/g23.jpg :scale: 75% -When the zoom operation completes, the display is as follows: +When the zoom operation completes, the display is as follows: .. figure:: /_images/g24.jpg @@ -193,7 +186,7 @@ Time Ruler To use a time ruler, press and hold the right mouse button; drag right or left until the ruler measures the region of interest. If the time axis scale is coarse, event boxes can have significant width in time, so use a "reference point" in -each event box when using the time ruler. +each event box when using the time ruler. .. figure:: /_images/g25.jpg :scale: 75% @@ -202,12 +195,12 @@ Event Selection ------------------------- Changing the Event Selector setup controls the set of points displayed in an -obvious way. Here, we suppress all events except "this thread is now running on the CPU": +obvious way. Here, we suppress all events except "this thread is now running on the CPU": .. figure:: /_images/g26.jpg :scale: 75% -Same setup, with all events displayed: +Same setup, with all events displayed: .. figure:: /_images/g27.jpg :scale: 75% @@ -237,12 +230,12 @@ example, if one selects an event which means "thread running on the CPU" the fir N displayed traces will be the first M threads to run (N <= M; a thread may run more than once. This feature addresses analytic problems caused by the finite size of the drawing area. -In standard (NoChaseEvent) mode, it looks like only BGP threads 5 and 9 are active: +In standard (NoChaseEvent) mode, it looks like only BGP threads 5 and 9 are active: .. figure:: /_images/g28.jpg :scale: 75% -After pressing the ChaseEvent button, we see a different picture: +After pressing the ChaseEvent button, we see a different picture: .. figure:: /_images/g29.jpg :scale: 75% @@ -270,7 +263,7 @@ Hotkeys ------------- G2 supports the following hotkey actions, supposedly (circa 1996) Quake-like -according to the feature's original author: +according to the feature's original author: +----------------------+--------------------------------------------------------+ | Key | Function | -- cgit 1.2.3-korg