NDC API

Version 0.1.0

NDC API is an abstraction layer for heterogeneous near-data computing (NDC) devices. It provides a single, stable entry point between NDC devices and the higher-level software that wants to use them — minimizing the per-device work required to bring new hardware into existing stacks.

What v0.1.0 Covers

This first release targets devices that expose a CXL.mem interface. Support for additional interconnects and device classes is planned and will be added incrementally in future releases.

Why a New Abstraction

Bringing a new class of device into an existing software stack inevitably requires some level of modification. Several established approaches in industry already tackle this from different angles — through unified programming models, intermediate representations consumed by compilers and runtimes, and others. Each is valuable, but each also carries its own surface of per-device work, and none yet covers the full breadth of NDC scenarios.

NDC API is not proposed as a replacement for these efforts, nor as a new industry standard. It is a pragmatic, minimal abstraction layer positioned between devices and existing software technologies, designed to let device vendors and application developers move forward in parallel while broader ecosystem support continues to mature.

Status

NDC API is released as a proof-of-concept and reference implementation, with the goal of expanding the NDC device ecosystem and gathering feedback from both industry and academia. Distribution is planned through OCP, building on the examples presented at the 2025 OCP Global Summit.

Contents of subfolders:

• include - include contains class for objects in the NDC API.
  The files (context, device, module, function) of detph 1 are objects used by user(host).
  The functions other than constructors and destructors are implemented as virtual functions.
  

• src - src contains driver API library.

• scripts - scripts contains scripts for NDC API.
  It includes dev_reg_map.sh for configuration and example.c showing how to use the NDC API in practice.

System:

Currently we support Ubuntu 22.04 based systems with CMake. We recommend below version:

• GCC version >= 12.3.0
• Clang version >= 14.0
• CMake version >= 3.13.0

How to Build:

$ mkdir build && cd build
# 1) -DREGION_SRC
# - CXL (default): Region information is retrieved from /sys/bus/cxl/.
# - IOMEM: If your host system uses CXL 1.1 (e.g. SPR) or Linux Kernel with
#          CONFIG_CXL_REGION disabled, you must specify -DREGION_SRC=IOMEM
#          so that the region information can be retrieved from /proc/iomem.
$ cmake .. -DREGION_SRC=IOMEM
$ make -j

Need to Create /etc/ndc.conf:

To use the NDC-API, you need a /etc/ndc.conf file containing mapping information for devices and regions.

Note: On CXL 1.1 systems such as SPR, CXL regions are not exposed, so region information cannot be retrieved via sysfs or the provided scripts below. In this case, the user must manually define the mapping between ndc_memX.Y and regionZ in /etc/ndc.conf. If multiple devices are present, regions should be assigned in the order they appear in /proc/iomem (e.g., region0, region1, etc.). Each memory range must be associated with the appropriate ndc_memX.Y entry.

You can check and create it yourself, but just running our provided ndc-api/scripts/dev_reg_map.sh script will generate it automatically.

• Attention: After rebooting, you must delete the existing content and rewrite /etc/ndc.conf.
  

If you want to configure it manually, refer to the example below for manual creation.

To find the ndc_mem device for region0,

$ cat /sys/bus/cxl/devices/region0/target0
decoder3.0
$ readlink -f /sys/bus/cxl/devices/decoder3.0
/sys/devices/platform/ACPI0017:00/root0/port2/endpoint3/decoder3.0
$ readlink -f /sys/bus/cxl/devices/endpoint3/uport
/sys/devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/mem0
$ ls /sys/devices/pci0000:0c/0000:0c:00.0/0000:0d:00.0/ | grep "ndc_mem*"
ndc_mem0.0

Add the found ndc_mem device to /etc/ndc.conf

$ echo ndc_mem0.0 region0 >> /etc/ndc.conf

How to Use Debugging option:

Add the -DDEBUG option to build

$ cmake .. -DREGION_SRC=IOMEM -DDEBUG=ON

Then, NDC-API prints the allocation list as the below when you try to allocate the memory [DEBUG] [ndcMemAlloc:59]
[DEBUG] [printList:68] [addr: 0x7f326fe00000, size: 2097152] ->