Release 2.2.0 (#15)

Co-authored-by: Alex Utter <[email protected]>

.gitignore

@@ -1,4 +1,4 @@
-# Copyright 2019, 2021 The Aerospace Corporation
+# Copyright 2019, 2021, 2022 The Aerospace Corporation
 #
 # This file is part of SatCat5.
 #
@@ -25,8 +25,12 @@
 .vscode/settings.json
 .vscode/settings.json
 
-# Ignore all Vivado-created subfolders
-project/vivado_2015.4/*/
+# Ignore test reports.
+cppcheck.xml
+cpplint.log
+
+# Ignore temporary files from example designs.
+test/log_viewer/build_tmp
 
 # Ignore most Lattice-created project files
 project/icecube2_2017.8/**
@@ -40,4 +44,4 @@ project/icecube2_2017.8/**
 project/libero/*/
 
 # Ignore all yosys-created subfolders
-project/yosys/*/
+project/yosys/*/

Makefile

@@ -1,4 +1,4 @@
-# Copyright 2020, 2021 The Aerospace Corporation
+# Copyright 2020, 2021, 2022 The Aerospace Corporation
 #
 # This file is part of SatCat5.
 #
@@ -26,13 +26,23 @@ VIVADO_VERSION ?= 2016.3
 export VIVADO_VERSION := ${VIVADO_VERSION}
 
 # Shortcuts for running Vivado in batch mode.
-# Special case for fake-GUI mode using XVFB (required for SDK)
+# Always set a fake GUI environment with XVFB, for SDK and block-diagram export.
 VIVADO_SETUP := source /opt/Xilinx/Vivado/${VIVADO_VERSION}/settings64.sh
 VIVADO_BATCH := vivado -mode batch -nojournal -nolog -notrace -source
-VIVADO_RUN := ${VIVADO_SETUP} && ${VIVADO_BATCH}
-VIVADO_GUI := ${VIVADO_SETUP} && xvfb-run -a ${VIVADO_BATCH}
+VIVADO_RUN := ${VIVADO_SETUP} && xvfb-run -a ${VIVADO_BATCH}
 VIVADO_BUILD := ${VIVADO_RUN} ../../project/vivado/build_project.tcl -tclargs
 
+# Software analysis parameters
+CPPCHECK_RUN := cppcheck \
+    --std=c++11 --enable=all --xml --xml-version=2 \
+    -DSATCAT5_VLAN_ENABLE=1 \
+    -i src/cpp/hal_ublaze/overrides.cc \
+    --suppress=missingInclude \
+    --suppress=unusedFunction
+CPPLINT_RUN := cpplint \
+    --filter=-build/include_order,-build/include_subdir,-readability/casting,-readability/namespace,-runtime/indentation_namespace,-whitespace,+whitespace/end_of_line \
+    --verbose=3 --recursive --exclude=src/cpp/hal_test/catch.hpp
+
 # Set working folders
 SIMS_DIR := ./sim/vhdl/
 SW_TEST_DIR := ./sim/cpp
@@ -78,18 +88,32 @@ arty_100t:
 
 .PHONY: arty_managed_35t
 arty_managed_35t:
-	@cd examples/arty_managed && ${VIVADO_GUI} create_all.tcl -tclargs 35T
+	@cd examples/arty_managed && ${VIVADO_RUN} create_all.tcl -tclargs 35T
 
 .PHONY: arty_managed_100t
 arty_managed_100t:
-	@cd examples/arty_managed && ${VIVADO_GUI} create_all.tcl -tclargs 100T
+	@cd examples/arty_managed && ${VIVADO_RUN} create_all.tcl -tclargs 100T
 
 # Example router design using AC701.
 .PHONY: ac701_router
 ac701_router:
 	@cd examples/ac701_router && ${VIVADO_RUN} create_project_router_ac701.tcl
 	@cd examples/ac701_router && ${VIVADO_BUILD} router_ac701
 
+# NetFPGA example design
+.PHONY: netfpga
+netfpga:
+	@cd examples/netfpga && ${VIVADO_RUN} create_all.tcl
+
+# VC707 example designs
+.PHONY: vc707_clksynth
+vc707_clksynth:
+	@cd examples/vc707_clksynth && ${VIVADO_RUN} create_vivado.tcl
+
+.PHONY: vc707_managed
+vc707_managed:
+	@cd examples/vc707_managed && ${VIVADO_RUN} create_all.tcl
+
 # Example design for ZedBoard.
 .PHONY: zed_converter
 zed_converter:
@@ -106,6 +130,16 @@ mpf_splash:
 ice40_rmii_serial:
 	@cd examples/ice40_hx8k && ./yosys_ice40_hx8k.sh switch_top_rmii_serial_adapter
 
+# Build and run the Log-Viewer tool
+.PHONY: log_viewer
+log_viewer:
+	@cd test/log_viewer && make run
+
+# Build each of the C++ example tools.
+.PHONY: sw_tools
+sw_tools:
+	@cd test/log_viewer && make all
+
 # Build and run software tests
 .PHONY: sw_test
 sw_test:
@@ -120,3 +154,20 @@ sw_coverage:
 .PHONY: sw_covertest
 sw_covertest:
 	@cd ${SW_TEST_DIR} && make coverage_test
+
+# Run "cppcheck" static analyzer on C++ software
+.PHONY: sw_cppcheck
+sw_cppcheck:
+	@${CPPCHECK_RUN} src/cpp 2> cppcheck.xml
+
+# Run "cpplint" linter on C++ software
+.PHONY: sw_cpplint
+sw_cpplint:
+	@${CPPLINT_RUN} src/cpp 2> cpplint.log
+
+# Build and run python software tests
+# Note: Run with "sudo" or grant CAP_NET_RAW to the Python executable.
+#   e.g., "sudo setcap cap_net_raw+eip /usr/bin/python3.6".
+.PHONY: sw_python
+sw_python:
+	@cd sim/python && python3 cfgbus_test.py

README.md

@@ -2,18 +2,24 @@
 
 ![SatCat5 Logo](doc/images/satcat5.svg)
 
-SatCat5 is FPGA software that implements a low-power, mixed-media Ethernet switch.
+SatCat5 is FPGA gateware that implements a low-power, mixed-media Ethernet switch.
 It also includes embedded software libraries to help microcontrollers interact with Ethernet networks.
 
 A SatCat5 switch is functionally equivalent to commercially available, unmanaged Ethernet switches for home use.
 However, it also supports lower-speed connections to the same network using I2C, SPI, or UART.
-These lower-rate data links, (commonly used in simple, low-cost, low-power microcontrollers)
+These lower-rate data links (commonly used in simple, low-cost, low-power microcontrollers)
 allow nearly any device to participate in the same local communication network, regardless of its capability level.
 
 Like any Ethernet switch, this one has multiple ports; each port is a point-to-point link from
 the switch to a network device, which could be a PC, a microcontroller, or even another switch.
 Power draw required for the switch itself is well under 1 watt.
 
+The main expected users of this project are cubesat and smallsat developers.
+By encouraging everyone to use this technology, we create a mutually-compatible ecosystem that will make it easier
+to develop new small-satellite payloads, and simultaneously make it easier to integrate those payloads into vehicles.
+For more information on SatCat5 and cubesats, refer to [our SmallSat 2020 publication](https://digitalcommons.usu.edu/smallsat/2020/all2020/174/). However, we think the same technology might be useful to other embedded systems,
+including Internet-of-Things systems that want to integrate microcontrollers onto a full-featured LAN.
+
 # Switch Capabilities
 
 ![Example network with microcontrollers and other nodes](doc/images/example_network.svg)
@@ -29,38 +35,39 @@ The latter options are typically lower speed (1-10 Mbps), but use physical layer
 protocols that are more amenable to use with simple microcontrollers.
 All interfaces transmit and receive standard Ethernet Frames.
 
-Detailed version history is available in the [changelog](doc/CHANGELOG.md).
-
-More information is available in the [Frequently Asked Questions](doc/FAQ.md).
+Switch operation can be designed in an HDL-only environment - however, many designs use
+soft-core embedded processors to provide higher level functionality such as handling of
+ARP, ICMP, IP, and UDP messages, along with switch or attached device configuration.
 
 # What Is Provided
 
 This project is effectively a set of building blocks, ready to be used to build and connect to your own custom Ethernet switch.
 The switch can be optimized to your needs, tailored to your preferred platform, port count, interface types, etc.
 
-In addition, SatCat5 includes [software libraries](src/cpp/README.md) for:
-
-* Sending and receiving Ethernet frames.
-* Sending and receiving ARP, ICMP, IP, and UDP messages.
-* Configuring a managed SatCat5 Ethernet switch.
-* Configuring various SatCat5 I/O peripherals (e.g., I2C, MDIO, SPI, or UART).
-
-In addition to these building blocks, we include several reference designs that showcase many of the available features.
-The easiest way to get started is with the [Digilent Arty A7](https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/), a low-cost FPGA development board.
-We've included a reference design that specifically targets this board.
+In addition to these building blocks, we include several
+[reference designs](examples/) that showcase many of the available features.
+The easiest way to get started is with the
+[Digilent Arty A7](https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/),
+a low-cost FPGA development board. We've included a reference design and
+[companion documentation](doc/ARTY_A7.md) that specifically targets this board.
 PMOD connector pinouts are chosen to be directly compatible with off-the-shelf USB-UART adapters.
 
 Other reference designs include the [prototype](doc/images/prototype.jpg) that we built to develop, test, and demonstrate the SatCat5 switch.
 It is intended to run on many off-the-shelf FPGA development boards, using an FMC port to attached to a [custom PCB](test/proto_pcb).
 The custom PCB includes Ethernet transceivers, PMOD connectors, and other I/O.
 
-The main expected users of this project are cubesat and smallsat developers.
-By encouraging everyone to use this technology, we create a mutually-compatible ecosystem that will make it easier
-to develop new small-satellite payloads, and simultaneously make it easier to integrate those payloads into vehicles.
-For more information on SatCat5 and cubesats, refer to [our SmallSat 2020 publication](https://digitalcommons.usu.edu/smallsat/2020/all2020/174/).
+SatCat5 also includes [software libraries](src/cpp/README.md) targeting both baremetal and
+POSIX systems for:
 
-However, we think the same technology might be useful to other embedded systems,
-including Internet-of-Things systems that want to integrate microcontrollers onto a full-featured LAN.
+* Sending and receiving Ethernet frames.
+* Sending and receiving ARP, ICMP, IP, and UDP messages.
+* Configuring a managed SatCat5 Ethernet switch.
+* Configuring various SatCat5 I/O peripherals (e.g., I2C, MDIO, SPI, or UART).
+
+A simple memory-mapped interface for configuration registers called [ConfigBus](doc/CONFIGBUS.md)
+was designed and can be found in the majority of designs. It is much lighter weight than AXI4-Lite
+as it is designed for small control registers. More information, including Microblaze libraries,
+control over Ethernet, and user register setup can be found in [its documentation](doc/CONFIGBUS.md).
 
 # Getting Started
 
@@ -72,52 +79,70 @@ If you'd like to build your own design, create a new top-level VHDL file and add
 
 * Any number of port_xx blocks. (e.g., port_spi, port_uart, port_rgmii, etc.)
 * At least one switch_core block.
-  * One is always functionally adequate.
-  * Sometimes you can save memory, power, and other resources if you use two.
 * One switch_aux block. This provides error-reporting, status LEDs, and other niceties.
 * Clock generation. Check the documentation for selected port type(s) to see what's needed.
 
-More information is available in the [Frequently Asked Questions](doc/FAQ.md).
+Another option for user designs on Xilinx platforms is the
+[Vivado IP Integrator](doc/IPI_FLOW.md). SatCat5 natively supports this block-diagram based flow
+and offers wrappers for the vast majority of compatible blocks. The drag-and-drop nature and
+single-wire bus interface connections make this a good choice for complex designs.
+
+# Further Reading
+
+Once started and familiar with the basics of SatCat5, it is highly recommended to read through the
+[Frequently Asked Questions (FAQs)](doc/FAQ.md). This contains a huge swath of tips, guidance,
+clarifications, and potential issues.
+
+Advice and tips on good development operations (DevOps) practices, including automated and
+hardware-in-the-loop testig, can also be found in the [DevOps documentation](doc/DEVOPS.md)
 
 # Folder Structure
 
-* doc: Documentation and associated images.
+* doc: Documentation and associated images. All documentation is linked somewhere in this README.
 * example: [Example designs](examples/README.md) for specific hardware platforms
-* project: Scripts and project files for specific vendor tools.
+* project: Scripts and project files for specific vendor tools
   * libero: Building Microsemi designs in Libero. (Tested with version 12.3.)
   * modelsim: Running VHDL simulations in ModelSim. (Tested with version 10.0a.)
   * vivado: Packagine IP-cores, building, or simulating Xilinx designs in Vivado. (Tested with Vivado version 2019.1.)
   * yosis: Building Lattice designs using Yosis.
-* sim: Simulation and verification of the design.
+* sim: Simulation and verification of the design
   * cpp: Unit tests for the embedded software libraries.
   * matlab: MATLAB/Octave scripts used to generate certain lookup tables.
   * test: Test data for various unit-test simulations.
   * vhdl: VHDL unit tests for individual functional blocks.
 * src: Source code for the core SatCat5 design
-  * cpp: Embedded software libraries for connecting to and configuring an Ethernet network.
-  * python: Python libraries for connecting to raw-Ethernet and Ethernet-over-UART ports.
-  * vhdl/common: VHDL implementation of most functional blocks.  (Common / all platforms)
-  * vhdl/lattice: Platform-specific VHDL for the Lattice iCE40.
-  * vhdl/microsemi: Platform-specific VHDL for the Microsemi Polarfire.
-  * vhdl/xilinx: Platform-specific VHDL for Xilinx Artix7 and Kintex7. (Including Arty and AC701 example designs.)
-* test: Additional testing, including the prototype reference design.
+  * cpp: C/C++ software libraries targeting various platforms
+    * hal_ublaze: Microblaze-specific hardware abstraction layer (HAL).
+    * hal_posix: Linux HAL intended to be used to run embedded unit tests on a Linux host.
+    * satcat5: Cross-platform libraries for connecting to and configuring an Ethernet network.
+  * python: Python libraries for connecting to raw-Ethernet / Ethernet-over-UART ports and remote ConfigBus control.
+  * vhdl: VHDL implementation of functional blocks
+    * common: Location of most functional blocks, targets all platforms.
+    * lattice: Platform-specific VHDL for the Lattice iCE40.
+    * microsemi: Platform-specific VHDL for the Microsemi Polarfire.
+    * xilinx: Platform-specific VHDL for Xilinx 7-series and Ultrascale platforms.
+* test: Additional testing, including the prototype reference design
   * chat_client: A demo application that implements chatroom functions using raw Ethernet frames.
+  * log_viewer: A demo application for viewing Chat/Log messages from example designs.
   * pi_wire: A tool for connecting to SatCat5 with a Raspberry Pi.
-  * proto_pcb: PCB design files for the prototype reference design.
 
 # Contributing
 
 We encourage you to contribute to SatCat5! Please check out the [guidelines here](doc/CONTRIBUTING.md) for information on how to submit bug reports and code changes.
 
+# Changelog
+
+A log of major changes per SatCat5 release can be found in the [Change Log](doc/CHANGELOG.md).
+
 # Patents
 
-Portions of SatCat5 are patent pending, USPTO application number 16/708,306.
+Portions of SatCat5 are patented under US11055254B2.
 
 In accordance with SatCat5's LGPL license agreement, we grant a royalty-free license for use of this technology. Refer to section 11 of the GPLv3 license for details.
 
 # Copyright Notice
 
-Copyright 2019, 2020, 2021 The Aerospace Corporation
+Copyright 2019, 2020, 2021, 2022 The Aerospace Corporation
 
 This file is part of SatCat5.
 

doc/CHANGELOG.md

@@ -67,9 +67,20 @@ This log will be updated for each new release, but may not reflect the latest de
 * Defined API for 10-gigabit Ethernet ports.
 * Bug-fixes for eth_preamble_rx and port_inline_status.
 
+## v2.2.0
+
+* Added Vernier-PLL system for timestamps with sub-nanosecond precision.
+* Defined API for ingress and egress timestamps and integrated with all SatCat5 port types.
+* More formatting options for the "satcat5::log" API, including signed decimal numbers.
+* New all-in-one IP/UDP network stack for simplified software networking.
+* New "log_viewer" diagnostic tool for display of messages from the "satcat5::log" API.
+* Reworked TCAM and MAC-lookup blocks to allow runtime read/write of MAC-address tables.
+* Tooltips for all IP-core configuration parameters.
+* Bug-fixes for router_inline and MDIO device-driver.
+
 # Copyright Notice
 
-Copyright 2019, 2020, 2021 The Aerospace Corporation
+Copyright 2019, 2020, 2021, 2022 The Aerospace Corporation
 
 This file is part of SatCat5.