{"id":31815802,"url":"https://github.com/xilinx/nanotube","last_synced_at":"2025-10-11T09:24:47.023Z","repository":{"id":138805077,"uuid":"609072327","full_name":"Xilinx/nanotube","owner":"Xilinx","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-13T16:13:26.000Z","size":867,"stargazers_count":103,"open_issues_count":2,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-22T02:43:21.105Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"LLVM","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Xilinx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-03-03T10:15:00.000Z","updated_at":"2025-03-18T06:45:54.000Z","dependencies_parsed_at":"2024-01-14T10:22:38.590Z","dependency_job_id":"b6dc91e0-d1c0-4f55-afd8-1bfdd25751f0","html_url":"https://github.com/Xilinx/nanotube","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Xilinx/nanotube","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xilinx%2Fnanotube","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xilinx%2Fnanotube/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xilinx%2Fnanotube/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xilinx%2Fnanotube/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Xilinx","download_url":"https://codeload.github.com/Xilinx/nanotube/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xilinx%2Fnanotube/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006755,"owners_count":26084178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T09:24:44.787Z","updated_at":"2025-10-11T09:24:47.016Z","avatar_url":"https://github.com/Xilinx.png","language":"LLVM","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Copyright and License\n\nCopyright (C) 2023, Advanced Micro Devices, Inc. All rights reserved.\nSPDX-License-Identifier: MIT\n\n# The Nanotube Compiler and Framework\n\nNanotube is a collection of compiler passes, libraries, and an API to\nfacilitate execution of EBPF XDP and similar networking code on an FPGA in a\nSmartNIC.  The compiler takes EBPF XDP C code as input and outputs a packet\nprocessing pipeline in HLS C++.  This HLS C++ code can then be synthesised\nusing Vitis HLS and placed on an FPGA.\n\nThe compiler performs various transformations on the program; starting with a\ntranslation of EBPF calls to calls to similar Nanotube API functions.  It then\nperforms multiple stages of transforming the code structurally and to different\nAPI levels:\n\n- mem2req: Converts C style pointer accesses (loads \u0026 stores) to explicit\n  accesses to map and packet data\n- optreq: combines adjacent map / packet accesses into fewer wider accesses\n- converge: straightens the control-flow graph around Nanotube API calls\n- pipeline: splits the single packet processing function into multiple\n  coarse-grained pipeline stages, and change the application logic to process\n  packet words flowing through, rather than a flat packet representation in\n  memory\n- hls: creates HLS C++ code from LLVM IR for synthesis with Vitis HLS\n\nThe Nanotube library implements packet accesses and maps in an implementation\nwhich is synthesis friendly, meaning that it will be placed in the application\nand will create efficient hardware in high-level synthesis.\n\n# Getting started\n\nBefore compiling Nanotube, you need to make sure all the dependencies\nare available.  Many of them are available as packages in common Linux\ndistributions.  The others are LLVM and Vitis-HLS.\n\nYou will need enough free storage space for Nanotube and its\ndependencies.  Using local storage will be faster, but network storage\ncan be used if preferred.\n\nBuilding Nanotube itself requires only the headers from Vitis-HLS and\nthat is enough to test the HLS output of Nanotube.  Generating Verilog\nfrom the HLS output and building bitfiles requires full installations\nof Vitis-HLS and Vivado.  The Nanotube build system will attempt to\nlocate installations of Vitis-HLS and Vivado on the legacy Xilinx\nnetwork.  If this fails, it will be necessary to provide the path to a\ndirectory which contains either a full Vitis-HLS install or just\ninclude sub-directory.\n\nApproximate sizes for a minimal installation are:\n\n      LLVM              24.2G\n      Vitis-HLS headers  5.6M\n      Nanotube           1.9G\n\nA full installation will require the following instead of the\nVitis-HLS headers:\n\n      Vitis-HLS full     6.5G\n      Vivado            81.8G\n\n## Installing Linux packages\n\nEvery Linux distribution has a different set of available packages and\npackage names vary between distributions.  To make things easier,\ninstructions are given here for some common distributions.  It may be\npossible to compile Nanotube on other distributions using similar\ninstructions, but there may be missing packages or other problems.\n\n### Installing packages on Ubuntu 20.04\n\nTo install the require packages, run these commands as root:\n\n      apt-get install -y cmake g++ m4 libpcap-dev wireshark scons libelf-dev libpci-dev\n      apt-get install -y libboost-dev libboost-doc libboost-program-options-dev\n      apt-get install -y python-is-python2 libxml2-dev libboost-system-dev\n      apt-get install -y python3-yaml python3-scapy libbpf-dev\n\nNote that the python-is-python2 package changes the /usr/bin/python\nsymlink to point to Python2, so it may affect other programs or\nprojects.  It is required for LLVM to work correctly.\n\n### Installing packages on Ubuntu 18.04\n\nTo install the require packages, run these commands as root:\n\n      apt-get install -y cmake g++ m4 libpcap-dev wireshark scons libelf-dev libpci-dev\n      apt-get install -y libboost-dev libboost-doc libboost-program-options-dev\n      apt-get install -y libxml2-dev libboost-system-dev\n      apt-get install -y python3-yaml python3-scapy libbpf-dev\n\n## Checking out the Nanotube repository\n\nTo checkout the Nanotube repository, run this command:\n\n      git clone https://github.com/Xilinx/nanotube.git\n\nor (if you are logged into Github):\n\n      git clone git@github.com:Xilinx/nanotube.git\n\n\n## Downloading and building LLVM\n\nYou will need to build LLVM before building Nanotube.  The build_llvm\nscript makes this process easier and selects LLVM build options which\nare known to work.  Nanotube is built against LLVM 12.0.0 built from source,\nbut we are planning to a more recent version of LLVM and explore the use of\ndistribution packages.\n\nThe script build_llvm accepts -j\u003cN\u003e like make does.\n\n### Downloading LLVM\n\nChoose a directory where LLVM will be built.  The instructions below\nuse /scratch/$USER/nanotube-llvm, but a different directory can be\nused if preferred.  Just make sure the correct path is given in\nlater commands.\n\n      mkdir -p /scratch/$USER\n      git clone -b llvmorg-12.0.0 https://github.com/llvm/llvm-project.git --depth 1  /scratch/$USER/nanotube-llvm\n\n### Building LLVM\n\nTo build LLVM on other systems, run this command:\n\n      scripts/build_llvm -j4 /scratch/$USER/nanotube-llvm\n\n## Installing Vitis-HLS and Vivado\n\nThe Nanotube compiler compiles from EBPF XDP C to C++ with HLS annotations,\nconverting the program in multiple steps.  The output of each step can be\nexecuted for testing, including the produced HLS C++ code.  For that, we need\nVitis-HLS headers; for synthesising the design onto an FPGA, a full\ninstallation of Vitis is required.\n\nVitis can be obtained from [its product page](https://www.xilinx.com/products/design-tools/vitis/vitis-platform.html).\n\nA minimal installation uses only the install directory from a normal\nVitis-HLS installation.  First find an existing installation of\nVitis-HLS or install a new one.  Then create a destination directory\nand copy the include directory into it.  For example:\n\n      mkdir  /scratch/$USER/Vitis_HLS_2022.2\n      rsync -a \u003cvitis_install_dir\u003e/Vitis_HLS/2022.2/include/ /scratch/$USER/Vitis_HLS_2022.2/include/\n\n## Building Nanotube\n\nThe Nanotube build system is based on scons.  When building the\nproject for the first time, it may be necessary to provide the\nlocations of dependencies on the scons command line.  The locations\nspecified are stored in the build configuration (build/config.json) so\nthey do not need to be provided when rebuilding the project.\n\nBy default, scons will build all the files in the build directory.\nThe scons command accepts extra command line arguments to control the\nbuild process:\n\n      LLVM_CONFIG=\u003cpath\u003e      Specify the location of the llvm-config executable.\n      XILINX_VITIS_HLS=\u003cpath\u003e Specify the location of the Vitis-HLS installation.\n      -j\u003cN\u003e                   Run \u003cN\u003e jobs in parallel.\n      run_tests               Build the project and run the tests.\n      \u003cpath-to-file\u003e          Build the specified file.\n      \u003cpath-to-directory\u003e     Build all the files in the specified directory.\n\nThe path to the llvm-config executable is specified using the\nLLVM_CONFIG variable on the scons command line and the path to the Vitis-HLS\ninstallation is specified using the XILINX_VITIS_HLS variable:\n\n      scons LLVM_CONFIG=/scratch/$USER/nanotube-llvm/build/bin/llvm-config XILINX_VITIS_HLS=/scratch/$USER/Vitis_HLS_2022.2 [args...]\n\n(NOTE: When building on a machine inside the AMD / Xilinx network, we use an\nexisting Vitis-HLS install and XILINX_VITIS_HLS is auto-detected and can be\nomitted.)\n\nOnce the build directory has been created using the commands above,\nthe LLVM_CONFIG and XILINX_VITIS_HLS options can be omitted, so the\ntests can be re-run using this shorter command:\n\n      scons -j4 run_tests\n\nTo compile the bpf-compile compiler (eBBPF -\u003e LLVM-IR) do the following:\n\n      scons build/bpf-compile\n\nTo run the resulting tool, use\n\n      build/bpf-compile examples/build/xdp_tx_iptunnel_kern.o\n\n## Running tests from outside the repository\n\nNanotube has support for running tests that live outside of the main\nrepository, but follow the same types (e.g., kernel_tests, pass_tests) and use\nthe same build \u0026 run infrastructure as the tests in this repository.  This can\nbe useful for running tests as part of regression testing that should not be in\nthis repository.\n\nThe external tests will be built into the normal build directory.  Note that\nthe setting will persist across invocations to scons, please see below.\n\nUse as follows:\n\n    scons ... EXTRA_TESTS=../my_additional_tests/ all\n    scons ... run_tests\n\nThe directory structure in my_additional_tests should match that of\nwhat exists in the normal Nanotube repository:\n\n    \u003e tree -L 2 -d ../my_additional_tests\n    ...\n    ├── testing\n    │   ├── kernel_tests\n    │   └── pass_tests\n    ...\n\nThese additional tests will use the same build and test running infrastructure\nas the existing tests, but custom files need to be provided in\nmy_additional_tests:\n\n- lit.cfg, lit.local.cfg .. defining the test suite\n- gen_test_list .. defining the different tests and options used for them\n\nHave a look at the tests in this repository for how they are used.\n\n## Perform an HLS build\n\nWhen scons has finished building the compiler and tests, the following\ncommand will perform an HLS build of one of the test programs.\n\n      scripts/hls_build -- \\\n        build/testing/kernel_tests/tap_packet_read.link_taps.inline_opt.hls \\\n        tmp/tap_packet_read \\\n        --pcap-in $(pwd)/build/testing/kernel_tests/golden/test_tap_packet_read.pcap.IN \\\n        --pcap-exp $(pwd)/build/testing/kernel_tests/golden/test_tap_packet_read.pcap.OUT\n\nThe HLS build benefits from machines with fast CPUs and lots of memory.  If\nyour environment has access to an LSF cluster, you can use \"--bsub\" after\n\"scripts/hls_build\" to run the compilation there.  Note that this may need\nadaptation depending on your specific LSF setup.  Add \"-j \u003cN\u003e\" to run multiple\njobs in parallel.  Add \"--clean most\" to remove the simulation directories\nafter completing each synthesis.\n\nThe utilisation and performance can be viewed with the following command:\n\n      scripts/report_hls_synth tmp/tap_packet_read\n\nThe -s option will give just the aggregate values.\n\n# Example\n\nPlease see examples/katran/README.md for an example using Facebook's Katran L4\nload balancer.\n\nThe tests (especially those in testing/kernel_tests) also provide insight into\nNanotube functionality.\n\n# Releases\n\nNanotube currently does not have a formal release process.  That means we do\nnot provide formal releases, stable branches, etc.  Instead, the main branch\nwill regularly receive new features, bug fixes, and occasionally bigger\nchanges such as API changes.\n\n# Contributing\n\nContributing to the Nanotube compiler is possible via GitHub pull requests.\nExternal contributions will be reviewed by core Nanotube developers.  If the\ncontribution passes the review and fits the project, we will merge it; if not,\nwe will provide comments on the proposed changes.\n\nHere are a few rules for contributing:\n\n* Contributed code will be released under the project's license; make sure\n  that this is okay (no lifting of code from elsewhere, make sure your employer\n  knows, etc)\n* Each commit must have a descriptive commit message describing a high-level\n  of the change and why it is needed\n* Each commit must compile and pass the tests in the repository\n* New contributed features should provide tests; that way, we can be more\n  confident they do not break in the future\n* Commits should be incremental and split logically for easier code review\n\n# Reporting bugs\n\nWe use GitHub issues for tracking bugs in the compiler.\n\n  https://github.com/Xilinx/nanotube/issues\n\nWhen filing a bug, the summary should include a short clear\ndescription of the bug.\n\n## Information to include in the description.\n\nThe description should provide enough details for someone else to\nreproduce the problem.  The following pieces of information will make\nthat easier.\n\n### What commands you typed.\n\nIf you provide the exact commands you typed then the person who is\ntrying to reproduce the problem can copy them into their terminal.\nWithout the exact commands, they are likely to type a different\ncommand which might not show the problem.  It's important to provide\nthe full commands, even if you think some parts are not relevant.\n\n### What you are trying to do.\n\nSometimes the desired effect of a command is not obvious.  If you\ndescribe what you are trying to do, the person handling the bug can\nconfirm that the commands you typed are expected to have the effect\nyou want.\n\n### What output you saw.\n\nThe person trying to reproduce the problem will want to know whether\ntheir attempt has been successful.  An easy way to do that is to copy\nthe output you saw into the bug report.  The output may also allow\nthem to diagnose the problem without reproducing it.\n\n### What output did you expected to see.\n\nIt's useful to be clear about what you expect to see, even if you\nthink that is obvious.  For example, if the program crashed, you might\nsay that you expect it to generate an error message or that you expect\nit to successfully generate the output file.  This is to make sure the\nbug gets fixed in a way which is acceptable to you.\n\n### The commit ID of the Nanotube repository.\n\nSome bugs only occur with specific versions of the Nanotube source\ncode.  To make sure the person trying to reproduce the problem is\nusing the same version, provide the commit ID in your description.\nThis can be obtained by using the following command:\n\n  git log -1\n\n### The version of the operating system being run.\n\nSome bugs only occur with a specific operating system or version of an\noperating system.  To handle these cases, it's useful to provide the\noperating system version being used in the bug description.  The\nfollowing command will report the operating system version on most\nLinux distributions:\n\n  lsb_release -a\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxilinx%2Fnanotube","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxilinx%2Fnanotube","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxilinx%2Fnanotube/lists"}