From 8871bf5a120443b085791e84b7f00100d2f1ff03 Mon Sep 17 00:00:00 2001 From: Andrew Sedlmayr Date: Tue, 29 Jun 2021 18:10:20 -0700 Subject: [PATCH 01/10] Added version information, will add git hash later. Modified the doxygen to be a little cleaner Former-commit-id: 7ba8a278694340105703404d55aa813c30b4c7e1 --- Agora_doxygen.conf | 27 +++-------------------- CMakeLists.txt | 5 ++++- simulator/chsim_main.cc | 2 ++ simulator/sender_cli.cc | 2 ++ src/agora/main.cc | 2 ++ src/client/user-main.cc | 2 ++ src/common/version_config.h.in | 12 ++++++++++ src/data_generator/data_generator_main.cc | 2 ++ src/mac/mac_basestation.cc | 4 +++- src/mac/mac_client.cc | 2 ++ 10 files changed, 34 insertions(+), 26 deletions(-) create mode 100644 src/common/version_config.h.in diff --git a/Agora_doxygen.conf b/Agora_doxygen.conf index e7c028892..06330e50d 100755 --- a/Agora_doxygen.conf +++ b/Agora_doxygen.conf @@ -790,7 +790,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = +INPUT = ./ ./README.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -820,11 +820,6 @@ FILE_PATTERNS = *.c \ *.cxx \ *.cpp \ *.c++ \ - *.java \ - *.ii \ - *.ixx \ - *.ipp \ - *.i++ \ *.inl \ *.idl \ *.ddl \ @@ -834,31 +829,15 @@ FILE_PATTERNS = *.c \ *.hxx \ *.hpp \ *.h++ \ - *.cs \ - *.d \ - *.php \ - *.php4 \ - *.php5 \ - *.phtml \ *.inc \ *.m \ *.markdown \ - *.md \ *.mm \ *.dox \ *.py \ *.pyw \ - *.f90 \ - *.f95 \ - *.f03 \ - *.f08 \ - *.f \ - *.for \ - *.tcl \ *.vhd \ *.vhdl \ - *.ucf \ - *.qsf # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -982,7 +961,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = README.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -1461,7 +1440,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -DISABLE_INDEX = YES +DISABLE_INDEX = NO # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag diff --git a/CMakeLists.txt b/CMakeLists.txt index a2714418c..338aaccb4 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,13 +1,16 @@ cmake_minimum_required(VERSION 2.8.8) include(CheckCSourceRuns) cmake_policy(SET CMP0054 NEW) -project(Agora) +#Allow project version +cmake_policy(SET CMP0048 NEW) +project(Agora VERSION 1.0.0) if(CMAKE_CXX_COMPILER_VERSION VERSION_GREATER 7.0) set(GCC_COVERAGE_COMPILE_FLAGS "-faligned-new") endif() set(SOURCE_DIR ".") +configure_file(${CMAKE_SOURCE_DIR}/src/common/version_config.h.in ${CMAKE_SOURCE_DIR}/src/common/version_config.h) option(FORCE_BUILD_PATH "Hardcode the build directory path to be 'Agora/build/'" ON) if(FORCE_BUILD_PATH) diff --git a/simulator/chsim_main.cc b/simulator/chsim_main.cc index 66d2f1f49..5699be89f 100644 --- a/simulator/chsim_main.cc +++ b/simulator/chsim_main.cc @@ -5,6 +5,7 @@ #include #include "channel_sim.h" +#include "version_config.h" DEFINE_uint64(bs_threads, 1, "Number of threads for handling reception of BS packets"); @@ -27,6 +28,7 @@ DEFINE_double(chan_snr, 20.0, "Signal-to-Noise Ratio"); int main(int argc, char* argv[]) { int ret = EXIT_FAILURE; gflags::ParseCommandLineFlags(&argc, &argv, true); + gflags::SetVersionString(GetAgoraProjectVersion()); std::printf("Base Station configuration\n"); auto bs_config = std::make_unique(FLAGS_bs_conf_file); std::printf("User configuration\n"); diff --git a/simulator/sender_cli.cc b/simulator/sender_cli.cc index 34927be52..0779e22b8 100644 --- a/simulator/sender_cli.cc +++ b/simulator/sender_cli.cc @@ -5,6 +5,7 @@ #include #include "sender.h" +#include "version_config.h" DEFINE_uint64(num_threads, 4, "Number of sender threads"); DEFINE_uint64(core_offset, 0, "Core ID of the first sender thread"); @@ -21,6 +22,7 @@ DEFINE_uint64( int main(int argc, char* argv[]) { gflags::ParseCommandLineFlags(&argc, &argv, true); + gflags::SetVersionString(GetAgoraProjectVersion()); std::string cur_directory = TOSTRING(PROJECT_DIRECTORY); std::string filename = FLAGS_conf_file; diff --git a/src/agora/main.cc b/src/agora/main.cc index b68f1560b..63b4c9e46 100644 --- a/src/agora/main.cc +++ b/src/agora/main.cc @@ -4,6 +4,7 @@ */ #include "agora.h" #include "gflags/gflags.h" +#include "version_config.h" DEFINE_string(conf_file, TOSTRING(PROJECT_DIRECTORY) "/data/tddconfig-sim-ul.json", @@ -11,6 +12,7 @@ DEFINE_string(conf_file, int main(int argc, char* argv[]) { gflags::SetUsageMessage("conf_file : set the configuration filename"); + gflags::SetVersionString(GetAgoraProjectVersion()); gflags::ParseCommandLineFlags(&argc, &argv, true); std::string conf_file; diff --git a/src/client/user-main.cc b/src/client/user-main.cc index 03325c2db..fe66e105d 100644 --- a/src/client/user-main.cc +++ b/src/client/user-main.cc @@ -8,6 +8,7 @@ #include "gflags/gflags.h" #include "phy-ue.h" #include "signal_handler.h" +#include "version_config.h" DEFINE_string(conf_file, TOSTRING(PROJECT_DIRECTORY) "/data/userconfig_512.json", @@ -15,6 +16,7 @@ DEFINE_string(conf_file, int main(int argc, char* argv[]) { gflags::SetUsageMessage("conf_file : set the configuration filename"); + gflags::SetVersionString(GetAgoraProjectVersion()); gflags::ParseCommandLineFlags(&argc, &argv, true); std::string filename; diff --git a/src/common/version_config.h.in b/src/common/version_config.h.in new file mode 100644 index 000000000..2402269a0 --- /dev/null +++ b/src/common/version_config.h.in @@ -0,0 +1,12 @@ +/** + * @file version_config.h + * @brief Agora project version configuration file + */ + +#ifndef VERSION_CONFIG_H_ +#define VERSION_CONFIG_H_ +#include + +const std::string GetAgoraProjectVersion() { return "@CMAKE_PROJECT_VERSION@"; } + +#endif // VERSION_CONFIG_H_ diff --git a/src/data_generator/data_generator_main.cc b/src/data_generator/data_generator_main.cc index f3510bb9f..a26a8c230 100644 --- a/src/data_generator/data_generator_main.cc +++ b/src/data_generator/data_generator_main.cc @@ -13,6 +13,7 @@ #include "data_generator.h" #include "logger.h" +#include "version_config.h" static constexpr bool kVerbose = false; static constexpr bool kPrintUplinkInformationBytes = false; @@ -27,6 +28,7 @@ DEFINE_string(conf_file, int main(int argc, char* argv[]) { const std::string cur_directory = TOSTRING(PROJECT_DIRECTORY); gflags::ParseCommandLineFlags(&argc, &argv, true); + gflags::SetVersionString(GetAgoraProjectVersion()); auto cfg = std::make_unique(FLAGS_conf_file.c_str()); const DataGenerator::Profile profile = diff --git a/src/mac/mac_basestation.cc b/src/mac/mac_basestation.cc index bfdeb1607..3db75eb21 100644 --- a/src/mac/mac_basestation.cc +++ b/src/mac/mac_basestation.cc @@ -10,6 +10,7 @@ #include "mac_receiver.h" #include "mac_sender.h" #include "signal_handler.h" +#include "version_config.h" DEFINE_uint64(num_sender_worker_threads, 1, "Number of mac basestation sender worker threads"); @@ -28,6 +29,7 @@ DEFINE_uint64( int main(int argc, char* argv[]) { PinToCoreWithOffset(ThreadType::kMaster, FLAGS_core_offset, 0); + gflags::SetVersionString(GetAgoraProjectVersion()); gflags::SetUsageMessage( "num_sender_threads, num_receiver_threads, core_offset, frame_duration, " "conf_file, data_file, enable_slow_start"); @@ -110,7 +112,7 @@ int main(int argc, char* argv[]) { thread.join(); } receiver.reset(); - ret = EXIT_SUCCESS; + ret = EXIT_SUCCESS; } catch (SignalException& e) { std::cerr << "SignalException: " << e.what() << std::endl; cfg->Running(false); diff --git a/src/mac/mac_client.cc b/src/mac/mac_client.cc index bbfed50db..802825fe0 100644 --- a/src/mac/mac_client.cc +++ b/src/mac/mac_client.cc @@ -10,6 +10,7 @@ #include "mac_receiver.h" #include "mac_sender.h" #include "signal_handler.h" +#include "version_config.h" DEFINE_uint64(num_sender_worker_threads, 1, "Number of mac client sender worker threads"); @@ -27,6 +28,7 @@ DEFINE_uint64( int main(int argc, char* argv[]) { PinToCoreWithOffset(ThreadType::kMaster, FLAGS_core_offset, 0); + gflags::SetVersionString(GetAgoraProjectVersion()); gflags::SetUsageMessage( "num_sender_threads, num_receiver_threads, core_offset, frame_duration, " From fa3115ce8fb88460cff6d6802bc1da98edd0f5df Mon Sep 17 00:00:00 2001 From: Andrew Sedlmayr Date: Tue, 29 Jun 2021 18:41:31 -0700 Subject: [PATCH 02/10] Updated the README with additional documentation Former-commit-id: f02dcff4e806ddfd928ab3048f3b0352ab683569 --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3a354f0a6..f592ab5fa 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Build Status](https://falcon.ecg.rice.edu:443/buildStatus/icon?job=github_public_agora%2Fdevelop)](https://falcon.ecg.rice.edu:443/job/github_public_agora/job/develop/) +[![Build Status](https://falcon.ecg.rice.edu:443/buildStatus/icon?job=github_public_agora%2Fpr-reldocs)](https://falcon.ecg.rice.edu:443/job/github_public_agora/job/pr-reldocs/) Agora is a complete software realization of real-time massive MIMO baseband processing. @@ -117,7 +117,7 @@ We provide a high performance [packet generator](simulator) to emulate the RRU. * Combined Testing (`--conf_file ue-mac-sim.json / bs-mac-sim.json`) * Terminal 1: `./build/data_generator --conf_file data/ue-mac-sim.json` to generate data files. - `./build/user -conf_file data/ue-mac-sim.json` to start users. + `./build/user --conf_file data/ue-mac-sim.json` to start users. * Terminal 2: `./build/chsim --bs_threads 1 --ue_threads 1 --worker_threads 2 --core_offset 28 --bs_conf_file data/bs-mac-sim.json --ue_conf_file data/ue-mac-sim.json` to run the channel simulator * Terminal 3: @@ -224,6 +224,12 @@ Check out [Agora Wiki](https://github.com/jianding17/Agora/wiki) for Agora's design overview and flow diagram that maps massive MIMO baseband processing to the actual code structure. Technical details and performance results can be found in * Jian Ding, Rahman Doost-Mohammady, Anuj Kalia, and Lin Zhong, "Agora: Real-time massive MIMO baseband processing in software," in Proc. of ACM CoNEXT, December 2020 ([PDF](https://www.yecl.org/publications/ding2020conext.pdf), [video](https://dl.acm.org/doi/abs/10.1145/3386367.3431296)). - + +To Generate the doxygen documentation for Agora run the following command from the repository root directory: +`doxygen Agora_doxygen.conf` +The latest hosted output is located at [Agora Doxygen](https://renew-wireless.org/agora-doxy/html/index.html) + +Other community resources can be found at the [RENEW Wireless Wiki](https://wiki.renew-wireless.org/) + ## Contact Jian Ding (jian.ding@yale.edu) From b2ba76313a2f87d4fa61fb2e0f91b05297949431 Mon Sep 17 00:00:00 2001 From: Andrew Sedlmayr Date: Tue, 29 Jun 2021 18:48:56 -0700 Subject: [PATCH 03/10] Fixed README spelling Former-commit-id: 76193f5199fd29940e88eb55fb4e716489d0ea94 --- README.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index f592ab5fa..c58fddfbd 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Agora is a complete software realization of real-time massive MIMO baseband proc Some highlights: * Agora currently supports 64x16 MU-MIMO (64 RRU antennas and 16 UEs) with 20 MHz bandwidth and 64QAM modulation, on a 36-core server with AVX512 support. -* Agora is configurable in terms of numbers of RRU antennas and UEs, bandwidth, moduation orders, LDPC code rates. +* Agora is configurable in terms of numbers of RRU antennas and UEs, bandwidth, modulation orders, LDPC code rates. * Agora supports an emulated RRU and UEs with a high-performance packet generator. * Agora has been tested with real RRUs with up to 64 antennas and up to 8 UEs. The RRU and UE devices are available from [Skylark Wireless](https://skylarkwireless.com). @@ -27,9 +27,9 @@ Some highlights: Agora requires CMake 2.8+ and works with both GNU and Intel compilers with C++17 support. ## Setting up the build environment * Setup CI: run `./config_ci.sh` - * Note for developers: You must run this command before checking out your new feature brach. Do not use `_` in your branch name. Use `-` instead. + * Note for developers: You must run this command before checking out your new feature branch. Do not use `_` in your branch name. Use `-` instead. - * See `scripts/ubuntu.sh` for required packages, including Linux packages, gtest, Armadillo, nlohmann json-dev and SoapySDR, and the corresponding versions. Run `./scripts/ubuntu.sh` to install these packages. + * See `scripts/ubuntu.sh` for required packages, including Linux packages, gtest, Armadillo, and SoapySDR, and the corresponding versions. Run `./scripts/ubuntu.sh` to install these packages. * Download and install Intel libraries: * Install Intel FlexRAN's FEC SDK for LDPC encoding and decoding * Download [Intel FlexRAN's FEC @@ -45,7 +45,7 @@ Some highlights: For example, if Intel compiler is in `/opt`, run `source $(find 2>/dev/null /opt -name compilervars.sh) intel64`. After running this command, ensure that `icc --version` reports 19.0.4. - * After instaling `icc 19.04`, compile FlexRAN as follows: + * After installing `icc 19.04`, compile FlexRAN as follows: ``` sudo chmod -R a+rwX FlexRAN-FEC-SDK-19-04/ # Allow all users read-write access cd /opt/FlexRAN-FEC-SDK-19-04/sdk/ @@ -60,7 +60,7 @@ Some highlights: * **NOTE**: To enable JIT acceleration applied for matrix multiplication in the code, MKL version after 2019 update 3 is required. * Optional: DPDK - * [DPDK](http://core.dpdk.org/download/) verison 20.02.1 is tested with + * [DPDK](http://core.dpdk.org/download/) version 20.02.1 is tested with Intel 40 GbE and Mellanox 100 GbE NICs in Agora. * To install it, run `sudo make install T=x86_64-native-linuxapp-gcc DESTDIR=/usr -j` @@ -68,7 +68,7 @@ Some highlights: ## Building and running with emulated RRU We provide a high performance [packet generator](simulator) to emulate the RRU. This generator allows Agora to run and be tested without actual RRU hardware. The following are steps to set up both Agora and the packet generator. - * Build Agora. This step also builds the sender, a data generator that generates random input data files, an end-to-end test that checks correctness of end results for both uplink and downlink, and several unit tests for testing either performance or correctness of invididual functions. + * Build Agora. This step also builds the sender, a data generator that generates random input data files, an end-to-end test that checks correctness of end results for both uplink and downlink, and several unit tests for testing either performance or correctness of individual functions. ``` cd Agora mkdir build @@ -126,14 +126,13 @@ We provide a high performance [packet generator](simulator) to emulate the RRU. `./build/agora --conf_file data/bs-mac-sim.json` run agora before running macbs. Run macuser -> agora -> macbs in quick succession. * Terminal 5: `./build/macbs --enable_slow_start 1 --conf_file data/bs-mac-sim.json ` to run to base station mac app. pecify --data_file "" to generate patterned data and --conf_file options as necessary. - * Note: make sure agora / user / chsim / macuser / macbs are using different set of cores,otherwise there will be performance slow down. + * Note: make sure agora / user / chsim / macuser / macbs are using different set of cores, otherwise there will be performance slow down. * To run with real wireless traffic from Faros/Iris hardware UEs, see the [Agora with real RRU](#agora-with-real-rru) section below. ## Building and running with real RRU -Agora suports a 64-antenna -Faros base station as RRU and Iris UE devices. Both are commercially available from +Agora supports a 64-antenna Faros base station as RRU and Iris UE devices. Both are commercially available from [Skylark Wireless](https://skylarkwireless.com) and are used in the [POWER-RENEW PAWR testbed](https://powderwireless.net/). Both Faros and Iris have their roots in the [Argos massive MIMO base station](https://www.yecl.org/argos/), especially [ArgosV3](https://www.yecl.org/argos/pubs/Shepard-MobiCom17-Demo.pdf). Agora also supports USRP-based RRU and UEs. @@ -202,9 +201,9 @@ The steps to collect and analyze timestamp traces are as follows: * We use data/tddconfig-sim-ul.json for uplink experiments and data/tddconfig-sim-dl.json for downlink experiments. In our [paper](#documentation), we change “antenna_num”, “ue_num” and “symbol_num_perframe” to different values to collect different data points in the figures. - * Gerenrate source data files by running + * Generate source data files by running `./build/data_generator --conf_file data/tddconfig-sim-ul.json`. - * Run Agora as a real-time process (to prevent OS from doing context swithes) using + * Run Agora as a real-time process (to prevent OS from doing context switches) using `sudo LD_LIBRARY_PATH=${LD_LIBRARY_PATH} chrt -rr 99 ./build/agora --conf_file data/tddconfig-sim-ul.json`. (**NOTE**: Using a process priority 99 is dangerous. Before running it, make sure you have directed OS interrupts away from cores used by Agora. If you have not done so, @@ -225,7 +224,7 @@ Agora's design overview and flow diagram that maps massive MIMO baseband process to the actual code structure. Technical details and performance results can be found in * Jian Ding, Rahman Doost-Mohammady, Anuj Kalia, and Lin Zhong, "Agora: Real-time massive MIMO baseband processing in software," in Proc. of ACM CoNEXT, December 2020 ([PDF](https://www.yecl.org/publications/ding2020conext.pdf), [video](https://dl.acm.org/doi/abs/10.1145/3386367.3431296)). -To Generate the doxygen documentation for Agora run the following command from the repository root directory: +Doxygen documentation generation for Agora can be initiated by running the following command from the repository root directory: `doxygen Agora_doxygen.conf` The latest hosted output is located at [Agora Doxygen](https://renew-wireless.org/agora-doxy/html/index.html) From c9b758bfbe6be0d6faa00f52adeee51fb457cfaf Mon Sep 17 00:00:00 2001 From: Naman Arora Date: Wed, 30 Jun 2021 11:29:48 -0500 Subject: [PATCH 04/10] README code-block fix in doxygen output Former-commit-id: 064d442b4b7e841e771734bdd88c2839138180f8 --- README.md | 165 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 117 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index c58fddfbd..86f59d717 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,10 @@ Some highlights: Agora currently only builds and runs on Linux, and has been tested on Ubuntu 16.04, 18.04, and 20.04. Agora requires CMake 2.8+ and works with both GNU and Intel compilers with C++17 support. ## Setting up the build environment - * Setup CI: run `./config_ci.sh` + * Setup CI: run + 
+    $ ./config_ci.sh
+
* Note for developers: You must run this command before checking out your new feature branch. Do not use `_` in your branch name. Use `-` instead. * See `scripts/ubuntu.sh` for required packages, including Linux packages, gtest, Armadillo, and SoapySDR, and the corresponding versions. Run `./scripts/ubuntu.sh` to install these packages. @@ -46,14 +49,14 @@ Some highlights: 2>/dev/null /opt -name compilervars.sh) intel64`. After running this command, ensure that `icc --version` reports 19.0.4. * After installing `icc 19.04`, compile FlexRAN as follows: - ``` - sudo chmod -R a+rwX FlexRAN-FEC-SDK-19-04/ # Allow all users read-write access - cd /opt/FlexRAN-FEC-SDK-19-04/sdk/ - sed -i '/add_compile_options("-Wall")/a \ \ add_compile_options("-ffreestanding")' cmake/intel-compile-options.cmake - ./create-makefiles-linux.sh - cd build-avx512-icc # or build-avx2-icc - make -j - ``` + 
+        $ sudo chmod -R a+rwX FlexRAN-FEC-SDK-19-04/ # Allow all users read-write access 
+        $ cd /opt/FlexRAN-FEC-SDK-19-04/sdk/ 
+        $ sed -i '/add_compile_options("-Wall")/a \ \ add_compile_options("-ffreestanding")' cmake/intel-compile-options.cmake 
+        $ ./create-makefiles-linux.sh 
+        $ cd build-avx512-icc # or build-avx2-icc 
+        $ make -j
+
* Install Intel MKL - See [instructions](https://software.intel.com/content/www/us/en/develop/articles/installing-intel-free-libs-and-python-apt-repo.html). * MKL can also be installed from Intel Parallel Studio XE. Agora has been tested with 2019 and 2020 versions. @@ -69,63 +72,111 @@ Some highlights: We provide a high performance [packet generator](simulator) to emulate the RRU. This generator allows Agora to run and be tested without actual RRU hardware. The following are steps to set up both Agora and the packet generator. * Build Agora. This step also builds the sender, a data generator that generates random input data files, an end-to-end test that checks correctness of end results for both uplink and downlink, and several unit tests for testing either performance or correctness of individual functions. - ``` - cd Agora - mkdir build - cd build - cmake .. - make -j - ``` + 
+    $ cd Agora
+    $ mkdir build
+    $ cd build
+    $ cmake ..
+    $ make -j
+
* Run end-to-end test to check correctness (uplink, downlink and combined tests should all pass if everything is set up correctly). - ``` - ./test/test_agora/test_agora.sh 10 out % Runs test for 10 iterations - ``` + 
+    $ ./test/test_agora/test_agora.sh 10 out # Runs test for 10 iterations
+
* Run Agora with emulated RRU traffic * **NOTE**: We recommend running Agora and the emulated RRU on two different machines. If you are running them on the same machine, make sure Agora and the emulated RRU are using different set of cores, otherwise there will be performance slow down. * First, return to the base directory (`cd ..`), then run - `./build/data_generator --conf_file data/tddconfig-sim-ul.json` to generate data - files. - * In one terminal, run `./build/agora --conf_file data/tddconfig-sim-ul.json` to - start Agora with uplink configuration. - * In another terminal, run `./build/sender --num_threads=2 --core_offset=1 --frame_duration=5000 --enable_slow_start=1 --conf_file=data/tddconfig-sim-ul.json` to start the emulated RRU - with uplink configuration. + 
+   $ ./build/data_generator --conf_file data/tddconfig-sim-ul.json
+
+ to generate data files. + * In one terminal, run + 
+   $ ./build/agora --conf_file data/tddconfig-sim-ul.json
+
+ to start Agora with uplink configuration. + * In another terminal, run + 
+   $ ./build/sender --num_threads=2 --core_offset=1 --frame_duration=5000 --enable_slow_start=1 --conf_file=data/tddconfig-sim-ul.json
+
+ to start the emulated RRU with uplink configuration. * The above steps use Linux networking stack for packet I/O. Agora also supports using DPDK - to bypass the kernel for packet I/O. To enable DPDK, run `cmake -DUSE_DPDK=1 ..; make -j` to - rebuild code for Mellanox NICs; for Intel NICs, run `cmake -DUSE_DPDK=1 -DUSE_MLX_NIC=0 ..; make -j` + to bypass the kernel for packet I/O. To enable DPDK, run + 
+   $ cmake -DUSE_DPDK=1 ..; make -j
+
+ to rebuild code for Mellanox NICs; for Intel NICs, run + 
+   $ cmake -DUSE_DPDK=1 -DUSE_MLX_NIC=0 ..; make -j
+
to exclude Mellanox libraries in the build. - When running the emulated RRU with DPDK, it is required to set the MAC address - of the NIC used by Agora. To do this, pass `--server_mac_addr=` to `sender`. + When running the emulated RRU with DPDK, it is required to set the MAC address of the NIC used by Agora. To do this, pass `--server_mac_addr=` to `sender`. * To test the real-time performance of Agora, see the [Running performance test](#running-performance-test) section below. * Run Agora with channel simulator and clients * First, return to the base directory (`cd ..`), then run - `./build/data_generator --conf_file data/bs-sim.json` to generate data files. - * In one terminal, run `./build/user --conf_file data/ue-sim.json` to start clients with + 
+   $ ./build/data_generator --conf_file data/bs-sim.json
+
+ to generate data files. + * In one terminal, run + 
+   $ ./build/user --conf_file data/ue-sim.json
+
+ to start clients with combined uplink & downlink configuration. - * In another terminal, run `./build/chsim --bs_threads 1 --ue_threads 1 --worker_threads 2 --core_offset 24 --bs_conf_file data/bs-sim.json --ue_conf_file data/ue-sim.json` - * In another terminal, run `./build/agora data/bs-sim.json` to start Agora with the combined configuration. + * In another terminal, run + 
+   $ ./build/chsim --bs_threads 1 --ue_threads 1 --worker_threads 2 --core_offset 24 --bs_conf_file data/bs-sim.json --ue_conf_file data/ue-sim.json
+
+ * In another terminal, run + 
+   $ ./build/agora data/bs-sim.json
+
+ to start Agora with the combined configuration. * Note: make sure Agora and sender are using different set of cores, otherwise there will be performance slow down. * Run Agora with channel simulator, clients, and mac enabled. - * Compile the code with `cmake .. -DENABLE_MAC=true` + * Compile the code with + 
+   $ cmake .. -DENABLE_MAC=true
+
* Uplink Testing (`--conf_file ue-mac-ul-sim.json / bs-mac-ul-sim.json`) * Downlink Testing (`--conf_file ue-mac-dl-sim.json / bs-mac-dl-sim.json`) * Combined Testing (`--conf_file ue-mac-sim.json / bs-mac-sim.json`) * Terminal 1: - `./build/data_generator --conf_file data/ue-mac-sim.json` to generate data files. - `./build/user --conf_file data/ue-mac-sim.json` to start users. + 
+       $./build/data_generator --conf_file data/ue-mac-sim.json
+
+ to generate data files. + 
+       $./build/user --conf_file data/ue-mac-sim.json
+
+ to start users. * Terminal 2: - `./build/chsim --bs_threads 1 --ue_threads 1 --worker_threads 2 --core_offset 28 --bs_conf_file data/bs-mac-sim.json --ue_conf_file data/ue-mac-sim.json` to run the channel simulator + 
+     $ ./build/chsim --bs_threads 1 --ue_threads 1 --worker_threads 2 --core_offset 28 --bs_conf_file data/bs-mac-sim.json --ue_conf_file data/ue-mac-sim.json
+
+ to run the channel simulator * Terminal 3: - `./build/macuser --enable_slow_start 1 --conf_file data/ue-mac-sim.json` to run to user mac app. Specify --data_file "" to generate patterned data and --conf_file options as necessary. + 
+       $ ./build/macuser --enable_slow_start 1 --conf_file data/ue-mac-sim.json
+
+ to run to user mac app. Specify `--data_file ""` to generate patterned data and `--conf_file` options as necessary. * Terminal 4: - `./build/agora --conf_file data/bs-mac-sim.json` run agora before running macbs. Run macuser -> agora -> macbs in quick succession. + 
+     $ ./build/agora --conf_file data/bs-mac-sim.json
+
+ run agora before running macbs. Run macuser -> agora -> macbs in quick succession. * Terminal 5: - `./build/macbs --enable_slow_start 1 --conf_file data/bs-mac-sim.json ` to run to base station mac app. pecify --data_file "" to generate patterned data and --conf_file options as necessary. + 
+     $ ./build/macbs --enable_slow_start 1 --conf_file data/bs-mac-sim.json
+
+ to run to base station mac app. specify `--data_file ""` to generate patterned data and `--conf_file` options as necessary. * Note: make sure agora / user / chsim / macuser / macbs are using different set of cores, otherwise there will be performance slow down. * To run with real wireless traffic from Faros/Iris hardware UEs, see the @@ -183,11 +234,17 @@ to get enough throughput for the traffic of 64 antennas. To reduce performance variations, we did the following configurations for the server that runs Agora: * **NOTE**: These steps are not strictly required if you just wanted to try out Agora and do not care about performance variations. * Disable Turbo Boost to reduce performance variation by running - `echo "0" | sudo tee /sys/devices/system/cpu/cpufreq/boost` + 
+    $ echo "0" | sudo tee /sys/devices/system/cpu/cpufreq/boost
+
* Set CPU scaling to performance by running - `sudo cpupower frequency-set -g performance`, + 
+    $ sudo cpupower frequency-set -g performance
+
where cpupower can be installed through - `sudo apt-get install -y linux-tools-$(uname -r)` + 
+    $ sudo apt-get install -y linux-tools-$(uname -r)
+
* Turn off hyper-threading. We provide an example bash script (scripts/tune_hyperthread.sh), where the core indices are machine dependent. * Set IRQ affinity to direct OS interrupts away from Agora's cores. @@ -202,13 +259,25 @@ The steps to collect and analyze timestamp traces are as follows: In our [paper](#documentation), we change “antenna_num”, “ue_num” and “symbol_num_perframe” to different values to collect different data points in the figures. * Generate source data files by running - `./build/data_generator --conf_file data/tddconfig-sim-ul.json`. + 
+    $ ./build/data_generator --conf_file data/tddconfig-sim-ul.json`.
+
* Run Agora as a real-time process (to prevent OS from doing context switches) using - `sudo LD_LIBRARY_PATH=${LD_LIBRARY_PATH} chrt -rr 99 ./build/agora --conf_file data/tddconfig-sim-ul.json`. + 
+    $ sudo LD_LIBRARY_PATH=${LD_LIBRARY_PATH} chrt -rr 99 ./build/agora --conf_file data/tddconfig-sim-ul.json
+
+ (**NOTE**: Using a process priority 99 is dangerous. Before running it, - make sure you have directed OS interrupts away from cores used by Agora. If you have not done so, - run `sudo LD_LIBRARY_PATH=${LD_LIBRARY_PATH} ./build/agora --conf_file data/tddconfig-sim-ul.json` instead to run Agora as a normal process.) - * Run the emulated RRU using `sudo LD_LIBRARY_PATH=${LD_LIBRARY_PATH} ./build/sender --server_mac_addr=00:00:00:00:00:00 --num_threads=2 --core_offset=0 --conf_file=data/tddconfig-sim-ul.json --delay=1000 --enable_slow_start=$2`. + make sure you have directed OS interrupts away from cores used by Agora. If you have not done so, run + 
+    $ sudo LD_LIBRARY_PATH=${LD_LIBRARY_PATH} ./build/agora --conf_file data/tddconfig-sim-ul.json
+
+ instead to run Agora as a normal process.) + * Run the emulated RRU using + 
+    $ sudo LD_LIBRARY_PATH=${LD_LIBRARY_PATH} ./build/sender --server_mac_addr=00:00:00:00:00:00 --num_threads=2 --core_offset=0 \
+      --conf_file=data/tddconfig-sim-ul.json --delay=1000 --enable_slow_start=$2
+
* The timestamps will be saved in data/timeresult.txt after Agora finishes processing. We can then use a [MATLAB script](matlab/parsedata_ul.m) to process the timestamp trace. * We also provide MATLAB scripts for [uplink](matlab/parse_multi_file_ul) and [downlink](matlab/parse_multi_file_dl) that are able to process multiple timestamp files and generate figures reported in our [paper](#documentation). From be044887c97eed449dbe216b8d3800b84c3ce09d Mon Sep 17 00:00:00 2001 From: Naman Arora Date: Wed, 30 Jun 2021 11:44:55 -0500 Subject: [PATCH 05/10] Remove third party includes from being added to docs Former-commit-id: 5bab6c0c977ee6b249adfbd0203e34a6d94e183f --- Agora_doxygen.conf | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Agora_doxygen.conf b/Agora_doxygen.conf index 06330e50d..cf05f2fe6 100755 --- a/Agora_doxygen.conf +++ b/Agora_doxygen.conf @@ -852,7 +852,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +EXCLUDE = src/third_party # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded From ac1f386e5e65f36073436bc93f9746af0f2285c8 Mon Sep 17 00:00:00 2001 From: Naman Arora Date: Wed, 30 Jun 2021 12:22:23 -0500 Subject: [PATCH 06/10] Added CONTRIBUTING page to include list This is a hack to get around Doxygen not parsing README as index when `*.md` is added to the list Former-commit-id: 26d0731249ca103508957312c71aa9c233b93ef2 --- Agora_doxygen.conf | 1 + 1 file changed, 1 insertion(+) diff --git a/Agora_doxygen.conf b/Agora_doxygen.conf index cf05f2fe6..a6583eb5f 100755 --- a/Agora_doxygen.conf +++ b/Agora_doxygen.conf @@ -838,6 +838,7 @@ FILE_PATTERNS = *.c \ *.pyw \ *.vhd \ *.vhdl \ + CONTRIBUTING.md \ # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. From 2b5f1cd3be41c6d38577ce1027f62feccb56ea18 Mon Sep 17 00:00:00 2001 From: Andrew Sedlmayr Date: Thu, 1 Jul 2021 07:50:18 -0700 Subject: [PATCH 07/10] Ignored the python files. EOL'd the python mac test files Former-commit-id: 08e8435941f5e1f1d5d38bb04dab3540b57c3ab3 --- Agora_doxygen.conf | 5 +++- python/bs_app.py | 48 --------------------------------------- python/client_app.py | 53 ------------------------------------------- src/common/.gitignore | 1 + 4 files changed, 5 insertions(+), 102 deletions(-) delete mode 100755 python/bs_app.py delete mode 100755 python/client_app.py create mode 100644 src/common/.gitignore diff --git a/Agora_doxygen.conf b/Agora_doxygen.conf index a6583eb5f..bd8e54395 100755 --- a/Agora_doxygen.conf +++ b/Agora_doxygen.conf @@ -853,7 +853,10 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = src/third_party +EXCLUDE = src/third_party \ + python/ \ + matlab/ \ + idl/ # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded diff --git a/python/bs_app.py b/python/bs_app.py deleted file mode 100755 index 9652b9db4..000000000 --- a/python/bs_app.py +++ /dev/null @@ -1,48 +0,0 @@ -#!/usr/bin/python3 - -# BS-side application that receives data packets from Agora MAC -# packet_size argument should correspond to the number of bits per -# PHY layer frame in Agora -# Running example: ./python/bs_app.py --packet-size 66 --stream-num 1 - -import socket -import sys -import time -from optparse import OptionParser -import signal - - -def bs_datarecv_app(size, streams, base_port): - # Create a UDP socket - sock = [socket.socket(socket.AF_INET, socket.SOCK_DGRAM) - for i in range(streams)] - server_address = [('localhost', base_port + i) for i in range(streams)] - for i in range(streams): - sock[i].bind(server_address[i]) - - signal.signal(signal.SIGINT, signal_handler) - while(True): - for i in range(streams): - message, server = sock[i].recvfrom(size) - print("Stream %d: " % i + "{}".format(list(message))) - - -def signal_handler(signal, frame): - sys.exit(0) - - -def main(): - parser = OptionParser() - parser.add_option("--stream-num", type="int", dest="stream_num", - help="number of user spatial streams", default=1) - parser.add_option("--packet-size", type="int", dest="packet_size", - help="size of packets in bytes", default=66) - parser.add_option("--base-port", type="int", dest="base_port", - help="server base listening port number to transmit data", default=8080) - (options, args) = parser.parse_args() - - bs_datarecv_app(options.packet_size, options.stream_num, options.base_port) - - -if __name__ == '__main__': - main() diff --git a/python/client_app.py b/python/client_app.py deleted file mode 100755 index 18ca741bc..000000000 --- a/python/client_app.py +++ /dev/null @@ -1,53 +0,0 @@ -#!/usr/bin/python3 - -# Client-side application that generates random bit data packets -# and sends through a socket to Agora client MAC for transmission -# through PHY layer. packet_size argument should correspond to the -# number of bits per PHY layer frame in Agora. delay argument -# specifies the delay between transmission of two consecutive packets. -# Running example: ./python/client_app.py --delay 0.00242 --packet-size 66 - -import socket -import sys -import time -import random -from optparse import OptionParser -import signal - - -def client_datagen_app(dly, size, streams, base_port): - # Create a UDP socket - sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) - server_address = ('localhost', base_port) - - signal.signal(signal.SIGINT, signal_handler) - while(True): - for u in range(streams): - message = bytearray(random.getrandbits(8) for _ in range(size)) - print("Stream %d: " % u + "{}".format(list(message))) - sock.sendto(message, server_address) - time.sleep(dly) - - -def signal_handler(signal, frame): - sys.exit(0) - - -def main(): - parser = OptionParser() - parser.add_option("--delay", type="float", dest="delay", - help="", default=0.00242) - parser.add_option("--packet-size", type="int", dest="packet_size", - help="size of packets in bytes", default=66) - parser.add_option("--stream-num", type="int", dest="stream_num", - help="number of user spatial streams", default=1) - parser.add_option("--base-port", type="int", dest="base_port", - help="server base listening port number to transmit data", default=9070) - (options, args) = parser.parse_args() - - client_datagen_app(options.delay, options.packet_size, - options.stream_num, options.base_port) - - -if __name__ == '__main__': - main() diff --git a/src/common/.gitignore b/src/common/.gitignore new file mode 100644 index 000000000..9c2ac05ca --- /dev/null +++ b/src/common/.gitignore @@ -0,0 +1 @@ +/version_config.h From 92559e9fa4e24fe18e6f435afa931c98df32228a Mon Sep 17 00:00:00 2001 From: Naman Arora Date: Thu, 1 Jul 2021 09:57:42 -0500 Subject: [PATCH 08/10] Refer 064d442b Former-commit-id: 2dd737f255b68b077b9e598eb67a0933368db5d8 --- CONTRIBUTING.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 181f00da6..dcbd38fd4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,43 +34,43 @@ For example, macros are acceptable to disable compilation of files that depend on proprietary libraries. So instead of: - ``` + 
     #ifdef USE_LDPC
         std::string raw_data_filename = x;
     #else
         std::string raw_data_filename = y;
     #endif
-    ```
+
prefer: - ``` + 
     std::string raw_data_filename = kUseLDPC ? x : y;
-    ```
+
* Avoid magic numbers. Instead of: - ``` + 
     n_rows = (ldpc_config.bg == 1) ? 46 : 42;
-    ```
+
prefer: - ``` + 
     n_rows = (ldpc_config.bg == 1) ? kBg1RowTotal : kBg2RowTotal;
-    ```
+
* Avoid variable copies. Instead of `size_t fft_thread_num = cfg->fft_thread_num;`, prefer using `cfg->fft_thread_num` directly. * Use enum classes instead of enums or macros. So instead of: - ``` + 
     #define PRINT_RX_PILOTS 0
     #define PRINT_RX 1
-    ```
+
prefer: - ``` - enum class PrintType {kRXPilots, kRX}; - ``` + 
+    enum class PrintType {kRXPilots, kRX};
+
* Add newlines between distinct blocks of code. See the vertical whitespace [section](https://google.github.io/styleguide/cppguide.html#Vertical_Whitespace). @@ -91,14 +91,14 @@ C-style casts. * Use auto type deduction when the type is clear. So instead of: - ``` + 
     struct Packet *pkt = new struct Packet[kNumPackets];
-    ```
+
prefer: - ``` + 
     auto *pkt = new Packet[kNumPackets];
-    ```
+
## Documentation requirements * Each file must have a comment at the top explaining what the file's purpose. From b0c0fdac4b00c666b7c5d757bf9a8d2b5ec1a705 Mon Sep 17 00:00:00 2001 From: Naman Arora Date: Thu, 1 Jul 2021 10:01:56 -0500 Subject: [PATCH 09/10] Fix broken clang-format ext link Former-commit-id: d500dc736e78732f86acdc789ec68347c2a28856 --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcbd38fd4..bcb4969e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ * Format the source code using `clang-format`. Running `clang-format -i *.cc *.h` will format source and header files in the current directory to match Agora's code style. There are also editor plugins for `clang-format` - ([example](https://github.com/google/vim_codefmt)). We recommend using clang-format version 11 or above. + ([example](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format)). We recommend using clang-format version 11 or above. ## Code style From 3fc909d09c76679aeaf6138ec8bc4ed644b51c82 Mon Sep 17 00:00:00 2001 From: Jian Ding Date: Thu, 1 Jul 2021 15:22:44 -0400 Subject: [PATCH 10/10] Update CI build badge Former-commit-id: ad4f4d3d4198cd101c64de6354898952292a5d2e --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 86f59d717..0f2d80285 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Build Status](https://falcon.ecg.rice.edu:443/buildStatus/icon?job=github_public_agora%2Fpr-reldocs)](https://falcon.ecg.rice.edu:443/job/github_public_agora/job/pr-reldocs/) +[![Build Status](https://falcon.ecg.rice.edu:443/buildStatus/icon?job=github_public_agora%2Fdevelop)](https://falcon.ecg.rice.edu:443/job/github_public_agora/job/develop/) Agora is a complete software realization of real-time massive MIMO baseband processing.