summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorIdo Barnea <ibarnea@cisco.com>2017-03-15 14:01:26 +0200
committerIdo Barnea <ibarnea@cisco.com>2017-03-15 14:01:26 +0200
commit051360159df9fddc6c9e99a032780247d4b7c9db (patch)
tree442be4a6c06e427431e3dfcb579eab25ed480420
parent0f986442b3cf2b7b5cdd386ca277779c9ced69fb (diff)
V2.21 doc changes
Signed-off-by: Ido Barnea <ibarnea@cisco.com>
-rwxr-xr-xdoc/release_notes.asciidoc74
-rwxr-xr-xdoc/trex_book.asciidoc40
-rw-r--r--doc/trex_faq.asciidoc2
-rwxr-xr-xdoc/trex_stateless.asciidoc32
4 files changed, 97 insertions, 51 deletions
diff --git a/doc/release_notes.asciidoc b/doc/release_notes.asciidoc
index 1ec3eaba..ac1f47d9 100755
--- a/doc/release_notes.asciidoc
+++ b/doc/release_notes.asciidoc
@@ -23,6 +23,22 @@ ifdef::backend-docbook[]
endif::backend-docbook[]
+== Release 2.21 ==
+
+* New command line arguments. ``--no-hw-flow-stat'', and ``--software'', for changing behavior of stateless
+per stream flow statistics and latency features. See detail link:trex_manual.html#_command_line_options[here].
+* Support for QinQ packets in stateless per port statistics (if using new ``--software'' command line arg).
+* Support for all types of VIC cards (including ones will old firmware), using ``--software''. Since we do not
+ have all cards in our lab, we could not test all of them. Will be glad for feedback on this (good or bad).
+
+=== Fixed issues: ===
+
+* link:https://trex-tgn.cisco.com/youtrack/issue/trex-370[trex-370]
+* link:https://trex-tgn.cisco.com/youtrack/issue/trex-373[trex-373]
+* link:https://trex-tgn.cisco.com/youtrack/issue/trex-375[trex-375]
+* link:https://trex-tgn.cisco.com/youtrack/issue/trex-377[trex-377]
+* link:https://trex-tgn.cisco.com/youtrack/issue/trex-378[trex-378]
+
== Release 2.20 ==
* hotfix release add mlx-dpdk share objects to the package
@@ -37,7 +53,7 @@ endif::backend-docbook[]
* RX thread CPU% is not 100% all the time from this version
* Better handling of latency packets (case of fast start/stop)
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-295[trex-295]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-364[trex-364]
@@ -64,7 +80,7 @@ WARNING: you must upgrade to OFED 4.0 even with ConnectX-4 cards
* Stateless packet capture - ability to capture tx side
* mlx5 dpdk driver is share object. Reduce image OFED libs dependency
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-344[trex-344]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-269[trex-269]
@@ -74,7 +90,7 @@ WARNING: you must upgrade to OFED 4.0 even with ConnectX-4 cards
* hotfix release
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-342[trex-342]
@@ -104,7 +120,7 @@ The Tutorial shows a little bit of our new packet capture ability
which was released on v2.16
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-258[trex-258]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-337[trex-337]
@@ -114,7 +130,7 @@ which was released on v2.16
* XL710/X710 VF (SR-IOV) mode works better
* 599 VF mode is *not* supported
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-333[trex-333]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-331[trex-331]
@@ -130,7 +146,7 @@ which was released on v2.16
* Fix Cluster mode breakage (v2.12-v2.13)
* Stateless GUI v3.0 works with this version
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-319[trex-319]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-322[trex-322]
@@ -150,7 +166,7 @@ which was released on v2.16
* RPC API version is 3.0 - New stateless GUI is required
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-317[trex-317]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-282[trex-282]
@@ -187,7 +203,7 @@ Not setting the port information :
===========================
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-257[trex-257]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-265[trex-265]
@@ -202,7 +218,7 @@ Not setting the port information :
* Early support for Mellanox ConnectX-4 cards (100/50/25GbE) - based on contributions from Mellanox DPDK team see here for more info link:trex_manual.html#_mellanox_connectx_4_support[Mellanox ConnectX-4 Support]
* Add support for Cisco VIC 1300 series adapter (40GbE)- based on Cisco VIC DPDK team see link:trex_manual.html#_cisco_vic_support[Cisco VIC Support]
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-268[trex-268]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-267[trex-267]
@@ -226,7 +242,7 @@ See link:trex_manual.html#_configuration_yaml_parameter_of_cfg_option[here] and
** Getting xstats names (can be polled once and then combined with updated values): link:trex_rpc_server_spec.html#_get_xstat_names[get_port_xstats_names]
** Getting xstats values: link:trex_rpc_server_spec.html#_get_xstat_values[get_port_xstats_values]
-=== fix issues: ===
+=== Fixed issues: ===
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-253[trex-253]
* link:https://trex-tgn.cisco.com/youtrack/issue/trex-212[trex-212]
@@ -241,7 +257,7 @@ See link:trex_manual.html#_configuration_yaml_parameter_of_cfg_option[here] and
* Support dual mode for push pcap/remote Python API. see here link:cp_stl_docs/api/client_code.html#trex_stl_lib.trex_stl_client.STLClient.push_remote[push_remote] and link:cp_stl_docs/api/client_code.html#trex_stl_lib.trex_stl_client.STLClient.push_pcap[push_pcap] Using this feature pcap can be splited to client/server ports
* Add infra for L2 emulation support
-=== fix issues: ===
+=== Fixed issues: ===
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-243[trex-243]
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-247[trex-247]
@@ -267,7 +283,7 @@ $sudo ./dpdk_setup_ports.py -c 03:00.0 03:00.1 -o /etc/trex_cfg.yaml # create op
* Add a way to stop/close NICS at TRex termination (link would be down) `-close-at-end`
* IPv6 XL710 ICMP packets are supported now
-=== fix issues: ===
+=== Fixed issues: ===
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-240[trex-240]
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-242[trex-242]
@@ -290,7 +306,7 @@ $sudo ./dpdk_setup_ports.py -c 03:00.0 03:00.1 -o /etc/trex_cfg.yaml # create op
For XL710/X710 there is a need to upgrade the firmware to 5.04 (or later)
=====================================
-=== fix issues: ===
+=== Fixed issues: ===
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-214[trex-214]
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-223[trex-223]
@@ -309,7 +325,7 @@ For XL710/X710 there is a need to upgrade the firmware to 5.04 (or later)
* TCP SYN Randomization learning support for advanced ASA stateful testing - link:trex_manual.html#_nat_support[here] and link:trex_manual.html#_trex_with_asa_5585[here]
* Advanced to latest DPDK 16.07RC3 - fix some XL710 driver performance issues
-=== fix issues: ===
+=== Fixed issues: ===
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-229[trex-229]
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-227[trex-227]
@@ -318,7 +334,7 @@ For XL710/X710 there is a need to upgrade the firmware to 5.04 (or later)
== Release 2.05 ==
-=== fix issues: ===
+=== Fixed issues: ===
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-221[trex-221]
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-220[trex-220]
@@ -334,7 +350,7 @@ For XL710/X710 there is a need to upgrade the firmware to 5.04 (or later)
* Ability to export core file
* Optimized the case of Latency stream, Field Engine and 9K template packets
-=== fix issues: ===
+=== Fixed issues: ===
* XL710/X710 present high latency with 9K packets link:http://trex-tgn.cisco.com/youtrack/issue/trex-214[trex-214]
* The latency seq number gets out of sync link:http://trex-tgn.cisco.com/youtrack/issue/trex-215[trex-215]
@@ -347,7 +363,7 @@ For XL710/X710 there is a need to upgrade the firmware to 5.04 (or later)
* More accurate stateless latency/more TUI support
* Speedup DPDK XL710 fdir driver
-=== fix issues: ===
+=== Fixed issues: ===
* Disconnect issue link:http://trex-tgn.cisco.com/youtrack/issue/trex-210[trex-210]
@@ -357,7 +373,7 @@ For XL710/X710 there is a need to upgrade the firmware to 5.04 (or later)
* The python latency statistic is compatible to JSON for easy manipulation
* Add latency minimum value Python API taken from histogram
-=== fix issues: ===
+=== Fixed issues: ===
* Fix corruption of mbuf in case of with high rate latency stream.
@@ -373,7 +389,7 @@ For XL710/X710 there is a need to upgrade the firmware to 5.04 (or later)
* Update Stateless presentation link:http://www.slideshare.net/HanochHaim/trex-realistic-traffic-generator-stateless-support[Statelss presenation]
* Stateful Python server API - Add support for iterator of remote file for Stateful GUI
-=== fix issues: ===
+=== Fixed issues: ===
* Performance issue, link:http://trex-tgn.cisco.com/youtrack/issue/trex-207[trex-207]
* Sporadic timeout on wait_on_traffic() API see link:http://trex-tgn.cisco.com/youtrack/issue/trex-209[trex-209]
@@ -391,7 +407,7 @@ For XL710/X710 there is a need to upgrade the firmware to 5.04 (or later)
image::images/trex_stl_gui.png[title="TRex Stateless GUI",align="left",width=600, link="images/trex_stl_gui.png"]
-=== fix issues: ===
+=== Fixed issues: ===
* X710/XL710 per stream hardware stats
** link:http://trex-tgn.cisco.com/youtrack/issue/trex-199[trex-199]
@@ -407,7 +423,7 @@ image::images/trex_stl_gui.png[title="TRex Stateless GUI",align="left",width=600
* The Client package includes Console/examples
* Client API verification mechanism. The client should match the server version range
-=== fix issues: ===
+=== Fixed issues: ===
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-193[trex-193]
* Python2/Python3 client API hardening
@@ -435,7 +451,7 @@ image::images/trex_stl_gui.png[title="TRex Stateless GUI",align="left",width=600
** Update per stream statistic documentation see link:draft_trex_stateless.html#_tutorial_per_stream_statistics[per stream statistic]
** Update HLTAPI arguments link:draft_trex_stateless.html#_hlt_supported_arguments_a_id_altapi_support_a[HLTAPI]
-=== fix issues: ===
+=== Fixed issues: ===
* Per stream statistic - Fix High speed of start/stop of giving zero in statistics
* Fix E1000 DPDK driver prints with ESXi
@@ -489,7 +505,7 @@ class STLS1(object):
* HLT fixes and support split_by variable
* First phase of per stream rx/tx statistic - XL710/X710 hardware support
-=== fix issues: ===
+=== Fixed issues: ===
* Fix some typo in Python API stl/example folder
* Fix Field Engine IPv4 checksum issue with big packet size
@@ -621,7 +637,7 @@ TRex > start -f stl/profiles/udp_1pkt.py -a -m 1mbps
* Basic Python HLTAPI support
-=== fix issues: ===
+=== Fixed issues: ===
* Dependent streams (e.g. `stl/burst_1000_pkt.yaml`) can be loaded
@@ -657,7 +673,7 @@ TRex > start -f stl/profiles/udp_1pkt.py -a -m 1mbps
** Console/Python API can be call from Cisco CEL now (ZMQ Python library is compiled to an old glibc)
** Add simulator for stateless
-=== fix issues: ===
+=== Fixed issues: ===
* The infamous DPDK error is not seen in case of a wrong core argument see here link:http://trex-tgn.cisco.com/youtrack/issue/trex-147[trex-147]
@@ -682,7 +698,7 @@ TRex > start -f stl/profiles/udp_1pkt.py -a -m 1mbps
** R/W support. only one client has R/W capability
* XL710/X710 support ICMP filter
-=== fix issues: ===
+=== Fixed issues: ===
* link:http://trex-tgn.cisco.com/youtrack/trex-110[trex-110]
@@ -693,7 +709,7 @@ TRex > start -f stl/profiles/udp_1pkt.py -a -m 1mbps
** change the JSON-RPC result format
* Support for specifying different modes for the packets used for latency measurement. Details link:trex_manual.html#_measure_jitter_latency[here].
-=== fix issues: ===
+=== Fixed issues: ===
* link:http://trex-tgn.cisco.com/youtrack/issue/trex-149[trex-149]
@@ -717,7 +733,7 @@ TRex > start -f stl/profiles/udp_1pkt.py -a -m 1mbps
* some clean up in tuple generator
* trex stateles console works with trex-mock
-=== fix issues: ===
+=== Fixed issues: ===
Python API fixup see here
@@ -734,7 +750,7 @@ Check for 64bit Kernel
== Release 1.76 ==
-=== fix issues: ===
+=== Fixed issues: ===
* minor pcap loader issues
* plugin cleanup
diff --git a/doc/trex_book.asciidoc b/doc/trex_book.asciidoc
index 6d07acd7..315f7cdb 100755
--- a/doc/trex_book.asciidoc
+++ b/doc/trex_book.asciidoc
@@ -1631,6 +1631,11 @@ This is an advance configuration, don't use it if you don't know what you are do
anchor:cml-line[]
+*--active-flows*::
+ An experimental switch to scale up or down the number of active flows.
+ It is not accurate due to the quantization of flow scheduler and in some cases does not work.
+ Example: --active-flows 500000 wil set the ballpark of the active flows to be ~0.5M.
+
*--allow-coredump*::
Allow creation of core dump.
@@ -1708,7 +1713,12 @@ This can be used to verify port connectivity. You can send packets from one port
By default (without this option), TRex waits for all flows to terminate gracefully. In case of a very long flow, termination might prolong.
*--no-flow-control-change*::
- Prevents TRex from changing flow control. By default (without this option), TRex disables flow control at startup for all cards, except for the Intel XL710 40G card.
+ Since version 2.21. +
+ Prevents TRex from changing flow control. By default (without this option), TRex disables flow control at startup for all cards, except for the Intel XL710 40G card.
+
+*--no-hw-flow-stat*::
+ Relevant only for Intel x710 stateless mode. Do not use HW counters for flow stats. +
+ Enabling this will support lower traffic rate, but will also report RX byte count statistics.
*--no-key*:: Daemon mode, don't get input from keyboard.
@@ -1731,6 +1741,14 @@ based routes to pass all traffic from one DUT port to the other. +
Enable Rx check module. Using this, each thread randomly samples 1/sample_rate of the flows and checks packet order, latency, and additional statistics for the sampled flows.
Note: This feature works on the RX thread.
+*--software*::
+ Since version 2.21. +
+ Do not configure any hardware rules. In this mode, all RX packets will be processed by software. No HW assist for dropping (while counting) packets will be used.
+ This mode is good for enabling features like link:trex_stateless.html#_tutorial_per_stream_statistics[per stream statistics], and
+ link:trex_stateless.html#_tutorial_per_stream_latency_jitter_packet_errors[latency], support packet types, not supported by HW flow director rules (For example QinQ).
+ Drawback of this is that because software has to handle all received packets, total rate of RX streams is significantly lower.
+ Currently, this mode is also limited to using only one TX core (and one RX core as usual).
+
*-v <verbosity level>*::
Show debug info. Value of 1 shows debug info on startup. Value of 3, shows debug info during run at some cases. Might slow down operation.
@@ -1740,11 +1758,6 @@ based routes to pass all traffic from one DUT port to the other. +
*-w <num seconds>*::
Wait additional time between NICs initialization and sending traffic. Can be useful if DUT needs extra setup time. Default is 1 second.
-*--active-flows*::
- An experimental switch to scale up or down the number of active flows.
- It is not accurate due to the quantization of flow scheduler and in some case does not work.
- Example --active-flows 500000 wil set the ballpark of the active flow to be ~0.5M
-
ifndef::backend-docbook[]
@@ -2950,11 +2963,16 @@ Checking for library ibverbs : yes
anchor:ciscovic_support[]
-* Supported from TRex version v2.12
-* Only 1300 series Cisco adapter supported
-* Must have VIC firmware version 2.0(13) for UCS C-series servers. Will be GA in Febuary 2017.
-* Must have VIC firmware version 3.1(2) for blade servers (which supports more filtering capabilities).
-* The feature can be enabled via Cisco CIMC or USCM with the 'advanced filters' radio button. When enabled, these additional flow director modes are available:
+* Supported from TRex version v2.12.
+* Since version 2.21, all VIC card types supported by DPDK are supported by TRex, using ``--software'' command line argument.
+Notice that if using ``--software'', no HW assist is used, causing supported packet rate to be much lower.
+Since we do not have all cards in our lab, we could not test all of them. Will be glad for feedback on this (good or bad).
+
+* If not using ``--software'', following limitations apply:
+** Only 1300 series Cisco adapter supported.
+** Must have VIC firmware version 2.0(13) for UCS C-series servers. Will be GA in Febuary 2017.
+** Must have VIC firmware version 3.1(2) for blade servers (which supports more filtering capabilities).
+** The feature can be enabled via Cisco CIMC or USCM with the 'advanced filters' radio button. When enabled, these additional flow director modes are available:
RTE_ETH_FLOW_NONFRAG_IPV4_OTHER
RTE_ETH_FLOW_NONFRAG_IPV4_SCTP
RTE_ETH_FLOW_NONFRAG_IPV6_UDP
diff --git a/doc/trex_faq.asciidoc b/doc/trex_faq.asciidoc
index 55e83f4e..966e22d0 100644
--- a/doc/trex_faq.asciidoc
+++ b/doc/trex_faq.asciidoc
@@ -557,7 +557,7 @@ always show N/A
This is because on these card types, we use hardware counters (as opposed to counting in software in other card types).
While this allows for counting of full 40G line rate streams, this does not allow for counting bytes (only packet
count available), because the hardware on these NICs lacks this support.
-
+Starting from version 2.21, new ``--no-hw-flow-stat'' flag will make x710 card behave like other cards.
diff --git a/doc/trex_stateless.asciidoc b/doc/trex_stateless.asciidoc
index 8edb5df4..1ca07a02 100755
--- a/doc/trex_stateless.asciidoc
+++ b/doc/trex_stateless.asciidoc
@@ -2826,21 +2826,25 @@ trex>
* Implementation:
** User chooses 32-bit packet group ID (pg_id) for each stream that need statistic reporting. Same pg_id can be used for more than one stream. In this case, statistics for all streams with the same pg_id will be combined.
** The IPv4 identification (or IPv6 flow label in case of IPv6 packet) field of the stream is changed to a value within the reserved range 0xff00 to 0xffff (0xff00 to 0xfffff in case of IPv6). Note that if a stream for which no statistics are needed has an IPv4 Id (or IPv6 flow label) in the reserved range, it is changed (the left bit becomes 0).
-** Software implementation: Hardware rules are used to direct packets from relevant streams to rx thread, where they are counted.
+** Software implementation: Hardware rules are used to direct packets from relevant streams to rx threads, where they are counted.
** Hardware implementation: Hardware rules are inserted to count packets from relevant streams.
* Summed up statistics (per stream, per port) is sent using a link:http://zguide.zeromq.org/[ZMQ] async channel to clients.
*Limitations*::
-* The feature supports following packet types:
-** IPv4 over Ethernet
-** IPv4 with one VLAN tag (except 82599 which does not support this type of packet)
-** IPv6 over Ethernet (except 82599 which does not support this type of packet)
-** IPv6 with one VLAN tag (except 82599 which does not support this type of packet)
+* The feature supports only following packet types.
+** IPv4 over Ethernet.
+** IPv4 with one VLAN tag (except 82599 which does not support this type of packet).
+** IPv6 over Ethernet (except 82599 which does not support this type of packet).
+** IPv6 with one VLAN tag (except 82599 which does not support this type of packet).
+** Since version 2.21, also QinQ (two vlan tags) is supported if using ``--software'' command line argument. Details link:trex_manual.html#_command_line_options[here].
* Maximum number of concurrent streams (with different pg_id) on which statistics may be collected: 127
* On x710/xl710 cards, all rx bytes counters (rx-bps, rx-bps-L1, ...) are not supported. This is because we use hardware
-counters which support only packets count on these cards.
+counters which support only packets count on these cards. +
+Starting from version 2.21, you can specify ``--no-hw-flow-stat'' command line argument in order to make x710 behave like other
+cards, and count statistics in software. This will enable RX byte count support, but will limit the total rate of streams
+we can count.
Two examples follow, one using the console and the other using the Python API.
@@ -2913,6 +2917,8 @@ Streams Statistics
<1> Tx bandwidth of the streams matches the configured values.
<2> Rx bandwidth (999.29 pps) matches the Tx bandwidth (999.29 pps), indicating that there were no drops.
<3> RX BPS is not supported on this platform (no hardware support for BPS), so TRex displays N/A.
+You can add ``--no-hw-flow-stat'' command line argument, in order to count everything in software, but max rate
+of streams that can be tracked will be lower.
*Flow Stats Using The Python API*::
@@ -2998,7 +3004,9 @@ in the "Per stream statistics" section is also available.
*Limitations*::
-* The feature supports following packet types:
+* The feature supports only following packet types (Unless using ``--software'' command line arg.
+See details link:trex_manual.html#_command_line_options[here]. Using this, *all* packet types are supported):
+
** IPv4 over Ethernet
** IPv4 with one VLAN tag (except 82599 which does not support this type of packet)
** IPv6 over Ethernet (except 82599 which does not support this type of packet)
@@ -3013,8 +3021,12 @@ in the "Per stream statistics" section is also available.
[IMPORTANT]
=====================================
-Latency streams are not supported in full line rate like normal streams. Both from, transmit and receive point of view. This is a design consideration to keep the latency measurement accurate and preserve CPU resource. One of the reason for doing so that in most cases it is enough to have a latency stream not in full rate. For example, if the required latency resolution is 10usec there is no need to send a latency stream in speed higher than 100KPPS- usually queues are built over time, so it is not possible that one packet will have a latency and another packet in the same path will not have the same latency. The none latency stream could be in full line rate (e.g. 100MPPS) to load the DUT while the low speed latency stream will measure this path latency.
-Don't expect the total latency streams rate to be higher than 1-5MPPS
+Latency streams are not supported in full line rate like normal streams. Both from transmit and receive point of view.
+This is a design consideration to keep the latency measurement accurate while preserving CPU resources.
+One of the reasons for doing so is that in most cases it is enough to have a latency stream in low rate. For example, if the required latency resolution is 10usec,
+there is no need to send latency stream in a speed higher than 100KPPS. Usually queues are built over time, so it is not possible that one packet will have
+latency and another packet in the same path will not have the same latency. The none latency streams could be in full line rate, to load the DUT, while the low speed latency streams will measure the latency of this path.
+Don't make the total rate of latency streams higher than 5MPPS.
=====================================
Two examples follow. One using the console and the other using the Python API.