# PLAN — Port ANSCORE Licensing Core to Linux (x86_64 + Jetson aarch64) **Status:** Draft, awaiting product-side decisions before execution **Target platforms:** Ubuntu 22.04 x86_64, JetPack 6.x (Ubuntu 22.04 aarch64) **Components in scope:** `core/anslicensing`, `core/ANSLicensingSystem`, `core/ANSLibsLoader` **Estimated effort:** ~6–7 focused weeks for one engineer **Risk:** Medium (HWID compatibility with license server is the dominant risk) **Owner:** Tuan Nghia Nguyen **Branch to create:** `linux-licensing-port` --- ## Decisions already made (do not re-litigate) 1. **Three components are in scope, in this order**: `ANSLibsLoader` (easiest), `anslicensing` (medium), `ANSLicensingSystem` (hardest). Engine modules (`ANSODEngine`, `ANSCV`, etc.) are NOT part of this plan — they come after licensing is up. 2. **No LabVIEW support on Linux.** The `_LV` exports and `LabVIEWHeader/extcode.h` includes are stripped from the Linux build via `#ifdef _WIN32`. The C++ and C-string (`_CS`) entry points become the only Linux surface. 3. **`lfreist/hwinfo` stays.** It is already vendored at `C:/ANSLibs/ANS-HWiNFO/` and is cross-platform (verified — its `platform.h` defines `HWINFO_UNIX` on Linux). All 8 `hwinfo::` call sites in `ANSLicense.cpp` are portable as-is. No replacement library needed. 4. **HWID gains real signals on Linux.** Today `hwid.cpp` Linux branches stub the SMBIOS UUID slot with `"4294967296"` and leave `GetHDDPropertyList` empty (2-point HWID strength vs Windows 4-point). We will fill those slots using `hwinfo::MainBoard::serialNumber()` and `hwinfo::RAM::serialNumber()` for parity. 5. **`rand.cpp` Linux path is replaced with `getrandom(2)`**. The current `srand(time(NULL)) + rand()` path is cryptographically broken and a security-correctness issue, not just a portability one. 6. **`DetectClockManipulation` on Linux ships as a best-effort stub.** Reading `journalctl` history is expensive and not always available (containers, no systemd). It will log a warning and return `false`. Acceptable anti-tamper degradation; flagged for follow-up. 7. **MediaClient and other non-licensing Windows surface stays Windows-only.** This plan does not touch them. 8. **HWiNFO is NOT the commercial HWiNFO64.** It's the open-source MIT-licensed [`lfreist/hwinfo`](https://github.com/lfreist/hwinfo) C++ library. No commercial license concern. ## Pre-work already completed (discovery, not code) - ✅ Confirmed `core/anslicensing/` already has Linux scaffolding: `CMakeLists.txt` branches on `WIN32` and links `curl ssl crypto`; `precomp.h` has POSIX shims; `download.cpp` has a complete libcurl path; `hwid.cpp` has Linux CPU-ID and MAC code. - ✅ Inventoried Windows API surface in `ANSLicensingSystem/ANSLicense.cpp` (4,021 LOC): - Only 2 `#ifdef _WIN32` blocks — the file assumes Windows top-to-bottom - 8 × `hwinfo::` calls — **portable as-is** - 12 × PDH counter sites — need `/proc` rewrite (Phase 3.3) - 7 × DXGI sites — need NVML/libdrm rewrite (Phase 3.4) - 1 × WMI `MSAcpi_ThermalZoneTemperature` query — Linux `/sys/class/thermal/` (Phase 3.2) - 1 × WinHTTP block — replace with libcurl already in `anslicensing/download.cpp` (Phase 3.5) - 1 × `DnsQuery_A` — replace with `getaddrinfo` (Phase 3.6) - Misc: `GlobalMemoryStatusEx`, `GetProcessMemoryInfo`, `GetSystemDirectoryW + GetDiskFreeSpaceExW`, `GetCurrentProcessId` (Phase 3.7) - ✅ Confirmed `lfreist/hwinfo` cross-platform support via its `platform.h` and the header set at `C:/ANSLibs/ANS-HWiNFO/include/hwinfo/`. --- ## Open product decisions (BLOCK Phase 0) These must be resolved with the licensing-backend team before any code is written. They determine the shape of Phase 1. ### Decision 1 — HWID format compatibility with the license server The license server validates a HWID hash that's currently produced from Windows WMI data (`Win32_ComputerSystemProduct.UUID`, `Win32_NetworkAdapter.MACAddress`, `Win32_PhysicalMedia.SerialNumber`, `Win32_Processor.ProcessorId`). On Linux we will produce hashes from different data sources (SMBIOS via `/sys/class/dmi/id/`, NIC MACs via `getifaddrs`, RAM serial via DMI, CPU ID via `__get_cpuid`). The hash format (the bit-packed 125-bit `BitStream3` in `hwid.cpp`) stays identical, but the **values being hashed differ**. Three options: - **A. Unified HWID, same algorithm**: server treats Windows and Linux licenses identically; admin has to physically activate each device once and the hash is opaque. **Simplest. Recommended.** - **B. Separate Linux license pool**: server tracks platform field; Linux activations come from a dedicated key range. More work backend-side. - **C. Backward-compat dance**: keep some Windows-specific fields empty on Linux (status quo) — license matching weakens. **Reject.** **Owner to confirm with backend team before Phase 0.** ### Decision 2 — HWiNFO `MainBoard::serialNumber()` availability on Jetson `lfreist/hwinfo` reads `/sys/class/dmi/id/board_serial` on Linux. **On Jetson this file may not exist** — ARM SBCs use device-tree, not DMI. We need to: - Test on a real Jetson Orin/AGX board early. - Define fallback signal: `/proc/device-tree/serial-number` (Jetson exposes this) or eMMC CID (`/sys/block/mmcblk*/device/cid`). **Owner needs a Jetson devkit available before Phase 1.** ### Decision 3 — Boost dependencies on Jetson `ANSLicensingSystem` currently links `libboost_log-vc143-mt-x64-1_82.lib` and uses `boost::property_tree::ptree` and `boost::date_time`. Ubuntu 22.04 ships Boost 1.74 by default (`libboost-all-dev`). Choices: - **A. Use system Boost on Linux** (1.74). Accept minor API differences; pin via `find_package(Boost 1.74 REQUIRED)`. - **B. Vendor Boost 1.82**. Painful build but exact parity. - **C. Drop Boost.PropertyTree on Linux** and use `nlohmann/json` (already a project dep via `ANSLIBS_DIR/nlohmann`). Smaller dep surface but a code change in `ANSLicense.cpp` JSON output paths. **Recommendation: A.** Defer until Phase 0.5 spike confirms it builds. --- ## Quick Start for a new session If you're a fresh Claude session and the user has asked you to execute this plan: 1. **Read this entire document end-to-end** before editing anything. The per-file checklist in Appendix A is the source of truth for what changes. 2. **Confirm prerequisites are in place**: ```bash ls "C:/ANSLibs/ANS-HWiNFO/include/hwinfo/platform.h" # cross-platform lib present git status # clean working tree git branch --show-current # should be linux-licensing-port ``` 3. **Verify the three product decisions above are resolved.** Ask the user to paste the answers if they're not in this doc. Do NOT start Phase 1 without Decision 1 (HWID format) answered. 4. **Ask the user which phase to start with.** Default to Phase 0.1. 5. **Use TaskCreate** to track progress through the phases — the seven-phase structure (0 through 4 plus per-3.x sub-phases) is the natural top-level task list. 6. **Work in small commits.** One file, one logical change, verify build on Windows AND Linux before the next change. The Windows build must stay green at every step. 7. **Never modify a `*_LV` function signature.** Even on Linux where we don't compile it, the source still exists on the Windows-shared file. Touch only what's gated by `#ifdef _WIN32`. ### How to invoke this plan The user can paste any of these to start: > "Read `docs/PLAN_Linux_Licensing_Port.md` and walk me through Phase 0." > "Continue the Linux licensing port. Read `docs/PLAN_Linux_Licensing_Port.md` and ask what's done." > "Execute Phase 1.1 from `docs/PLAN_Linux_Licensing_Port.md`." ### Context the new session might need that isn't in this plan - **Build system on Linux**: CMake 3.28+, Ninja, GCC 11+ on Ubuntu 22.04. Cross-compile to Jetson via JetPack 6.x SDK Manager + sysroot. - **CUDA on Linux**: CUDA 12.x, cuDNN, TensorRT 10.x from `apt` or NVIDIA's repo. - **Licensing server endpoint**: ask the user for the staging URL — it is NOT in source control. - **Test hardware**: x86 Ubuntu box AND a Jetson Orin Nano/AGX devkit are both required. Do not declare Phase 1 done from x86 testing alone. --- ## 1. Background ANSCORE targets Linux (Jetson + industrial x86) per the product roadmap. The Flutter mobile app will be replaced by a Qt QML UI talking to ANSCORE over gRPC + RTSP. Licensing is the blocking dependency: **no module can be loaded without `ANSLicensingSystem` validating the license**, so it must come first. The three components are layered: ``` ┌──────────────────────────────┐ │ Module DLLs (ANSCV, ANSOD,…) │ ← consumers, NOT part of this plan ├──────────────────────────────┤ │ ANSLicensingSystem (façade) │ ← Phase 3 (4–5 weeks) ├──────────────────────────────┤ │ anslicensing (SDK) │ ← Phase 1 (2–3 weeks) │ ANSLibsLoader (dynload) │ ← Phase 2 (1 week) └──────────────────────────────┘ ``` `ANSLicensingSystem` depends on `anslicensing`; `ANSLibsLoader` is independent of both but consumed by `ANSCV` later. Phase ordering keeps the build green at every step. ## 2. Goals - All three components build on Ubuntu 22.04 x86_64 and JetPack 6.x aarch64. - `libANSLicensingSystem.so` exports the same C++ symbols and C ABI as the Windows DLL (less LabVIEW exports). - Linux HWID is a 4-signal hash, equivalent strength to Windows. - License validation works against the existing license server. - All Windows behavior preserved unchanged. Zero behavioral regressions on Windows builds. - `rand.cpp` on Linux uses `getrandom(2)` instead of insecure `rand()`. ## 3. Non-goals - LabVIEW support on Linux. - macOS port (separate effort). - `DetectClockManipulation` feature parity on Linux (acceptable degradation, logged). - Re-architecting the licensing protocol (wire compat preserved). - Engine modules (`ANSODEngine`, `ANSCV`, etc.) — separate plans. - Build infra changes (Conan/vcpkg adoption, etc.). ## 4. Phases ### Phase 0 — Windows-side prep (1 week, zero behavioral change) Done on Windows. No Linux changes yet. Each step must keep the Windows build green and tests passing. - **0.1** Add `ANSCORE_API` visibility macro to all three components' public headers: ```cpp #if defined(_WIN32) #if defined(ANSCORE_EXPORTS) #define ANSCORE_API __declspec(dllexport) #else #define ANSCORE_API __declspec(dllimport) #endif #elif defined(__GNUC__) #define ANSCORE_API __attribute__((visibility("default"))) #else #define ANSCORE_API #endif ``` Replace `__declspec(dllexport)` / `__declspec(dllimport)` site-by-site. Test on Windows that the resulting DLL exports the same symbol set (`dumpbin /exports`). - **0.2** Split LabVIEW exports out of `ANSLicense.h` into a new `ANSLicense_LV.h` that includes the LabVIEW header and declares only the `_LV` functions. Update Windows-side `ANSLicense.cpp` to include `ANSLicense_LV.h`. **Result: `ANSLicense.h` has zero LabVIEW types**, so Linux consumers don't drag in `extcode.h`. - **0.3** Strip ``, ``, etc. from public headers (`ANSLIB.h:6 #include ` line is the worst offender). Use forward declarations or guard with `#ifdef _WIN32` where needed in implementation files only. - **0.4** Vendor `lfreist/hwinfo` as a git submodule at `3rdparty/hwinfo` (or confirm `C:/ANSLibs/ANS-HWiNFO/` is the canonical copy and update CMake to point at it consistently). Add a top-level CMake option `ANSCORE_USE_VENDORED_HWINFO` that defaults to ON. - **0.5** Stand up an Ubuntu 22.04 build environment (CI runner or local VM). Install: `build-essential cmake ninja-build libboost-all-dev libcurl4-openssl-dev libssl-dev libzip-dev zlib1g-dev libnvidia-ml-dev libdrm-dev libsensors4-dev`. Verify CUDA 12.x + TensorRT 10.x are reachable. Smoke test: `cmake -B build && ninja -C build core/anslicensing` should currently fail — but it should fail with **predictable errors** (missing hwinfo Linux build, etc.), not config errors. **Acceptance for Phase 0**: - Windows build green, all existing tests pass. - `dumpbin /exports ANSLicensingSystem.dll` symbol set is byte-identical to baseline. - `ANSLicense.h` does not include `LabVIEWHeader/extcode.h`. - Ubuntu environment is reproducible. - Decision 1, 2, 3 above are answered in writing. ### Phase 1 — Port `core/anslicensing` (2–3 weeks) This is the lowest-level SDK. Already 80% portable. - **1.1** **Strengthen Linux HWID** in `hwid.cpp`: - Replace the `propList.push_back("4294967296")` stub at line 254 with `hwinfo::MainBoard board; propList.push_back(board.serialNumber());`. Falls back to `/proc/device-tree/serial-number` on aarch64 if board_serial is missing. - Implement `GetHDDPropertyList` on Linux at line 142: enumerate block devices via `/sys/block/*/device/wwid` or `/sys/block/*/device/serial`. Filter to non-removable (skip `/sys/block/*/removable == 1`). - Add the same source to the `MatchCurrentHardwareId` Linux branches (lines 416, 538). - Cross-test: HWID produced on Ubuntu must validate on the same machine across reboots. - **1.2** **Replace `rand.cpp` Linux RNG** with `getrandom(2)`: ```cpp #include // ::srand(time(NULL)); ← DELETE // rnd = ::rand(); ← DELETE ssize_t n = getrandom(&rnd, sizeof(rnd), 0); if (n != sizeof(rnd)) { // fallback: open /dev/urandom directly } ``` Keep `random::random()` constructor cheap (no kernel call); make `random::rand()` the syscall site. Document the change in a header comment. - **1.3** **`DetectClockManipulation` Linux stub** in `helper.cpp` — return `false` with `ANS_DBG("ClockTamper", "skipped on Linux — no-op fallback")`. Document as a known degradation. - **1.4** **Wire CMake on Linux**. The CMakeLists already has the Linux branch; verify: - `find_package(CURL REQUIRED)` resolves - `target_link_libraries(... curl ssl crypto)` links cleanly - Add `find_package(hwinfo REQUIRED)` or use the submodule - **1.5** **Round-trip test**: a small test binary that calls `HardwareId::GetCurrentHardwareId()`, persists the string, then calls `HardwareId::MatchCurrentHardwareId(saved)` and asserts true. Run on Ubuntu x86 AND a Jetson devkit. **Acceptance for Phase 1**: - `libanslicensing.so` builds on Ubuntu 22.04 x86_64 and Jetson aarch64. - Round-trip HWID test passes on both targets across at least 3 reboots. - `strings libanslicensing.so | grep -c '4294967296'` returns 0. - Static analysis (cppcheck or clang-tidy) shows no new warnings on Linux build. ### Phase 2 — Port `core/ANSLibsLoader` (1 week) Mechanical port from `LoadLibrary`/`GetProcAddress` to `dlopen`/`dlsym`. Independent of Phase 1 and Phase 3 — can be done in parallel. - **2.1** Port `DynLibUtils.cpp` core helpers: ```cpp #ifdef _WIN32 HMODULE LoadLib(const char* p) { return LoadLibraryA(p); } void* GetSym(HMODULE h, const char* s) { return GetProcAddress(h, s); } void UnloadLib(HMODULE h) { FreeLibrary(h); } #else void* LoadLib(const char* p) { return dlopen(p, RTLD_NOW | RTLD_LOCAL); } void* GetSym(void* h, const char* s) { return dlsym(h, s); } void UnloadLib(void* h) { dlclose(h); } #endif ``` Wrap the handle type behind an opaque `DynLibHandle` typedef so callers don't see the difference. - **2.2** Update `CvLoader.cpp`, `NvDynLoader.cpp`, `OvLoader.cpp`, `EPLoader.cpp` to use the cross-platform helpers. Most logic is search-path discovery — that needs branching too: - Windows: `C:/ANSLibs/...` paths - Linux: `/opt/ANSLibs/...`, `/usr/lib/x86_64-linux-gnu/`, `/usr/local/cuda/lib64/`, and `${LD_LIBRARY_PATH}` - **2.3** Naming convention: Windows `.dll`, Linux `.so` with `lib` prefix. Centralize in a `PLATFORM_DLL_NAME("opencv_world")` macro that expands to `"opencv_world.dll"` on Windows and `"libopencv_world.so"` on Linux. - **2.4** Symbol visibility: Linux `.so` exports everything by default unless built with `-fvisibility=hidden`. Apply `-fvisibility=hidden` globally in the top-level CMakeLists and use the `ANSCORE_API` macro to opt in to exports. - **2.5** Smoke test: `ANSLibsLoader` opens `libopencv_world.so` on Ubuntu and returns valid handles for a known set of OpenCV symbols. **Acceptance for Phase 2**: - `libANSLibsLoader.so` builds and runs. - All four sub-loaders (CV/OV/NV/EP) load their respective libraries successfully on Linux. - No symbol-visibility regressions on Windows (verify with `dumpbin /exports`). ### Phase 3 — Port `core/ANSLicensingSystem` (4–5 weeks) The big one. Split into independently mergeable PRs. #### 3.1 — Misc Win32 cleanup (1 day) - `GlobalMemoryStatusEx` → read `/proc/meminfo` MemTotal / MemAvailable - `GetProcessMemoryInfo` → read `/proc/self/status` VmRSS, VmSwap, VmPeak - `GetSystemDirectoryW + GetDiskFreeSpaceExW` (line 1056-1064) → `statvfs("/")` - `GetCurrentProcessId` → `getpid()` - `WideCharToMultiByte` / `WideToUtf8` → `std::wstring_convert` or just use `std::string` throughout the Linux path (no wide chars needed without WMI) #### 3.2 — CPU thermal (1 day) Replace `ReadCpuTempCelsiusViaWmi()` (line 603) with a Linux reader: ```cpp double ReadCpuTempCelsiusLinux() { // Scan /sys/class/thermal/thermal_zone*/type for "x86_pkg_temp" (x86) // or "CPU-therm" / "thermal-fan-est" (Jetson) // Read corresponding /sys/class/thermal/thermal_zone*/temp (milli-Celsius) // Return max across all CPU zones, or -1 if none found } ``` Keep the Windows function intact behind `#ifdef _WIN32`. Dispatch through a single `ReadCpuTempCelsius()` wrapper. #### 3.3 — System health sampler / PDH rewrite (1 week) The `HealthSampler` class (lines 906–1089) is the largest single port. Build a Linux `HealthSamplerLinux` class with the same public API as the Windows one. Then dispatch at instantiation: ```cpp #ifdef _WIN32 using HealthSampler = HealthSamplerWin; #else using HealthSampler = HealthSamplerLinux; #endif ``` PDH counter → Linux source mapping: | PDH counter | Linux source | |---|---| | `\Processor Information(_Total)\% Processor Time` | `/proc/stat` delta of (user+nice+system) vs idle | | `\Processor Information(_Total)\% Processor Performance` | `/sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq` / base freq | | `\Processor Information(_Total)\% Processor Utility` | Same as Processor Time on Linux (no MS-specific util concept) | | `\PhysicalDisk(_Total)\% Disk Time` | `/proc/diskstats` field 13 (io_time ms / interval ms) | | `\PhysicalDisk(_Total)\Disk Read Bytes/sec` | `/proc/diskstats` field 6 × 512 / interval | | `\PhysicalDisk(_Total)\Disk Write Bytes/sec` | `/proc/diskstats` field 10 × 512 / interval | | `\Network Interface(*)\Bytes Received/Sent/sec` | `/proc/net/dev` rx_bytes / tx_bytes deltas | | `\Network Interface(*)\Current Bandwidth` | `/sys/class/net/*/speed` (Mbit/s) | | `\GPU Engine(*)\Utilization Percentage` | NVML `nvmlDeviceGetUtilizationRates` | | `\GPU Process Memory(*)\Dedicated Usage` | NVML `nvmlDeviceGetMemoryInfo` | The sampler keeps a `prev_*` snapshot for delta computation (no PDH built-in differencing on Linux). Sample interval: same 2-second cadence as Windows. Acceptance: the populated `ANSCENTER::SystemHealthInfo` struct has all the same fields filled on Linux as on Windows (allowing -1 / empty for fields that genuinely don't exist). #### 3.4 — GPU adapter enumeration (1 week) Replace `EnumerateGpuAdapters` (line 721) with NVML on systems with NVIDIA drivers, falling back to libdrm: ```cpp std::vector EnumerateGpuAdaptersLinux() { std::vector out; // Try NVML first (covers Jetson + dGPU x86) if (nvmlInit_v2() == NVML_SUCCESS) { unsigned int count = 0; nvmlDeviceGetCount_v2(&count); for (unsigned int i = 0; i < count; ++i) { nvmlDevice_t dev; nvmlDeviceGetHandleByIndex_v2(i, &dev); GpuAdapter a; // populate a.name, a.vendorId=0x10DE, a.dedicatedVramMB... out.push_back(a); } nvmlShutdown(); } // Then enumerate non-NVIDIA via libdrm (/dev/dri/card*) // for Intel/AMD users on x86 Linux // ... return out; } ``` `AggregateGpuCounter` (line 773) — the LUID-based attribution machinery — collapses on Linux because NVML hands you per-device handles directly. Replace with a simpler `for (auto& dev : nvmlDevices)` loop. Caveat: `nvmlDeviceGetUtilizationRates` returns whole-device utilization, not per-process. Per-process GPU memory needs `nvmlDeviceGetProcessUtilization` (where supported) or `nvmlDeviceGetComputeRunningProcesses`. On Jetson, NVML support is partial — test early. #### 3.5 — License-server HTTP (1 day) Delete the `WinHttpHandle` block (lines 1101–1166) on Linux. Reuse `anslicensing/download.cpp`'s `UrlDownloadToString` libcurl path. The function signature is already compatible. One small wrinkle: `UrlDownloadToString` is in `anslicensing.dll`, so `ANSLicensingSystem` must link against it — it already does. #### 3.6 — DNS public-IP probe (0.5 day) Replace `DnsQuery_A` (line 1228) with `getaddrinfo`: ```cpp struct addrinfo hints{}, *res = nullptr; hints.ai_family = AF_INET; if (getaddrinfo("myip.opendns.com", nullptr, &hints, &res) == 0 && res) { char buf[INET_ADDRSTRLEN]; inet_ntop(AF_INET, &((sockaddr_in*)res->ai_addr)->sin_addr, buf, sizeof(buf)); publicIp = buf; freeaddrinfo(res); } ``` If the existing Windows query uses a TXT record specifically, fall back to `libresolv res_query` for parity. Verify with the user which probe is in use. #### 3.7 — CMake + linking (3 days) Rewrite `ANSLicensingSystem/CMakeLists.txt` Linux branch: ```cmake if(WIN32) target_link_libraries(ANSLicensingSystem PRIVATE HWiNFO.lib OpenCL.lib OpenCLExt.lib bz2.lib zip.lib libboost_log-vc143-mt-x64-1_82.lib shlwapi.lib winhttp.lib pdh.lib psapi.lib wbemuuid.lib oleaut32.lib ole32.lib dxgi.lib dnsapi.lib ${WIN_COMMON_LIBS} ) else() find_package(Boost REQUIRED COMPONENTS log date_time) find_package(CURL REQUIRED) target_link_libraries(ANSLicensingSystem PRIVATE hwinfo::hwinfo # vendored or apt Boost::log Boost::date_time CURL::libcurl zip # libzip-dev z # zlib1g-dev nvidia-ml # libnvidia-ml-dev (NVML) drm # libdrm-dev (optional, for non-NVIDIA) pthread dl ) endif() target_compile_definitions(ANSLicensingSystem PRIVATE ANSLICENSE_EXPORTS ANSLICENSINGSYSTEM_EXPORTS $<$:UNICODE _UNICODE> ) ``` Drop `ANSLIBS_DIR/ANS-HWiNFO/lib` and `ANSLIBS_DIR/boost/lib` from `target_link_directories` on Linux. #### 3.8 — End-to-end license activation (3 days) Run the full activation flow from a Linux client against the staging license server: 1. `GenerateHardwareId()` returns a string 2. Operator pastes it into the activation portal 3. Server returns license blob 4. Linux client `ValidateLicense(blob)` returns `SUCCESS` 5. Subsequent `IsLicenseValid()` calls return true 6. Restart process — license still valid 7. Move drive to second machine — license **invalid** (HWID mismatch detected) The last item is the critical anti-piracy check. If it fails (license validates on second machine), the HWID is too lax — go back to Phase 1.1. **Acceptance for Phase 3 overall**: - `libANSLicensingSystem.so` builds and links cleanly. - All public symbols (less `_LV` set) match Windows-side exports. - Full activation round-trip succeeds against staging server. - `SystemHealthInfo` struct populates all fields with real (non -1) data on Jetson and on x86 Ubuntu. - Anti-piracy test passes (HWID mismatch is detected). ### Phase 4 — Integration & Hardening (1 week) - **4.1** **Cross-arch CI**: add an `aarch64` build matrix entry. Cross-compile from x86 host using JetPack 6.x sysroot, or natively on a Jetson runner. Both options work; pick whichever the team prefers. - **4.2** **Soak test**: run an ANSLicensingSystem-based test harness on a Jetson for 24 hours. Watch for memory leaks (`valgrind --leak-check=full` for a short run, then `top` / smaps tracking long-term). NVML on Jetson has known leak patterns — defend against them. - **4.3** **Documentation**: write `docs/LINUX_BUILD_GUIDE.md` covering apt deps, Boost version notes, Jetson cross-compile, and the HWID format change (so support knows licenses don't transfer Windows↔Linux without re-issuance). - **4.4** **Top-level CMake gating**: in the root `CMakeLists.txt`, remove `if(WIN32)` gates around the three components — they now build everywhere. Engine modules stay Windows-only for now since this plan doesn't cover them. **Acceptance for Phase 4**: - CI green on Windows, Ubuntu x86, Jetson aarch64. - 24h soak shows stable memory profile. - LINUX_BUILD_GUIDE.md merged and reviewed. --- ## 5. Risks & mitigations | Risk | Likelihood | Impact | Mitigation | |---|---|---|---| | License server rejects Linux HWID format | Medium | **Blocks Phase 1 acceptance** | Resolve Decision 1 before Phase 0; coordinate with backend team early | | Jetson `/sys/class/dmi/id/board_serial` missing | High | Phase 1 HWID is weak on Jetson | Decision 2: validate on real Jetson hardware; fall back to device-tree serial | | NVML on Jetson missing some APIs | Medium | GPU telemetry sparse on Jetson | Test `nvmlDeviceGetUtilizationRates` early; gracefully degrade fields that aren't available | | Boost version mismatch (1.74 system vs 1.82 vendored) | Medium | Subtle behavioral differences | Phase 0.5 spike build; switch to nlohmann/json if PropertyTree breaks | | `lfreist/hwinfo` ARM support gaps | Low | HWID source incomplete on Jetson | Read its `cpuid.h` Linux branch; have device-tree fallback ready | | Symbol visibility differences cause ABI breakage | Low | Linker errors at integration time | `-fvisibility=hidden` from day one; `ANSCORE_API` discipline | | WMI thermal-zone has no Linux semantic equivalent | Low | `cpuTempDegC` field is less accurate | Document field as "best-effort, may be -1 on hardware without thermal zones" | | `libnvidia-ml` not present on dev-only x86 box | Low | Build fails on developer machines | dynamic-load NVML via dlopen with weak symbol; fallback to "no GPU" state | --- ## 6. Dependencies for Ubuntu / Jetson development ```bash # Build essentials sudo apt install -y \ build-essential cmake ninja-build pkg-config git \ libboost-all-dev libcurl4-openssl-dev libssl-dev \ libzip-dev zlib1g-dev \ libnvidia-ml-dev libdrm-dev libsensors4-dev \ libgtest-dev cppcheck clang-tidy # CUDA 12.x + cuDNN + TensorRT 10.x — from NVIDIA's apt repo (separate setup) # JetPack 6.x — flash via SDK Manager onto target board ``` For Jetson cross-compile: install JetPack 6.x SDK on host, point CMake at `/opt/nvidia/jetson-linux-sysroot/aarch64-ubuntu22.04`. --- ## 7. Testing strategy - **Unit tests** (`tests/anslicensing-unittest`): exercise each platform-specific helper with known synthetic data. New tests: HWID-determinism, getrandom-fallback, /proc/meminfo parser, /proc/stat delta computation. - **Integration tests** (`tests/anslicensingsystem-integration`): in-process activation round-trip against a mock license server. Run on Windows + Linux + Jetson. - **E2E tests**: real staging server. Run **once per phase acceptance**, not on every commit (slow + flaky over real network). - **Anti-piracy regression test**: documented in Phase 3.8. **Must run before merging Phase 3 to main.** - **Determinism test**: generate HWID 10× across reboots on the same machine; assert all identical. Generate on two physically different Jetsons; assert different. --- ## Appendix A — Per-file change checklist Files marked **NEW** are created; **MOD** is modified; **DELETE** is removed. ### `core/anslicensing/` | File | Action | Phase | Change | |---|---|---|---| | `hwid.cpp` | MOD | 1.1 | Linux branches: use `hwinfo::MainBoard::serialNumber()` for UUID slot; implement `GetHDDPropertyList` reading `/sys/block/*/device/wwid` | | `rand.cpp` | MOD | 1.2 | Replace `srand`/`rand` with `getrandom(2)` + `/dev/urandom` fallback | | `helper.cpp` | MOD | 1.3 | `DetectClockManipulation` Linux stub with ANS_DBG warning | | `download.cpp` | — | — | Already done — libcurl path exists | | `precomp.h` | — | — | Already done — POSIX shims exist | | `CMakeLists.txt` | MOD | 1.4 | Add `find_package(hwinfo)` on non-Windows | ### `core/ANSLicensingSystem/` | File | Action | Phase | Change | |---|---|---|---| | `ANSLicense.h` | MOD | 0.2 | Remove `#include "LabVIEWHeader/extcode.h"`; remove `LDbl`/`LDblPtr`/`LDblHandle` (moved to `ANSLicense_LV.h`) | | `ANSLicense_LV.h` | NEW | 0.2 | Windows-only header with all `_LV` exports, includes `extcode.h` | | `ANSLicense.cpp` | MOD | 3.1–3.6 | Replace each Win32 call site with `#ifdef _WIN32` / `#else` branch | | `HealthSamplerLinux.cpp` | NEW | 3.3 | New file: `/proc`-based sampler | | `HealthSamplerLinux.h` | NEW | 3.3 | Class declaration matching `HealthSampler`'s public API | | `Utility.h` | MOD | 0.3 | Strip any Windows-specific types from declarations | | `Utility.cpp` | MOD | 3.1 | Verify std::filesystem path operations work on Linux | | `CMakeLists.txt` | MOD | 3.7 | Add Linux branch with curl/boost/hwinfo/nvml | ### `core/ANSLibsLoader/` | File | Action | Phase | Change | |---|---|---|---| | `DynLibUtils.cpp` | MOD | 2.1 | dlopen/dlsym/dlclose Linux branches | | `CvLoader.cpp` | MOD | 2.2 | Linux search paths + `.so` naming | | `NvDynLoader.cpp` | MOD | 2.2 | Linux search paths | | `OvLoader.cpp` | MOD | 2.2 | Linux search paths | | `EPLoader.cpp` | MOD | 2.2 | Linux search paths | | `ANSLibsLoader.def` | — | — | Windows-only `.def`; leave alone, use `__attribute__((visibility))` on Linux | | `CMakeLists.txt` | MOD | 2.4 | `-fvisibility=hidden`; link `dl` on Linux | ### Top-level | File | Action | Phase | Change | |---|---|---|---| | `CMakeLists.txt` | MOD | 0.4, 4.4 | `ANSCORE_USE_VENDORED_HWINFO` option; ungate three core components from `if(WIN32)` | | `cmake/Dependencies.cmake` | MOD | 0.4, 3.7 | Add `hwinfo`, `NVML` (`CUDA::nvml`), `libdrm` resolution | | `3rdparty/hwinfo/` | NEW (submodule) | 0.4 | `git submodule add https://github.com/lfreist/hwinfo 3rdparty/hwinfo` | | `docs/LINUX_BUILD_GUIDE.md` | NEW | 4.3 | Developer onboarding | --- ## Appendix B — Symbol map (Win32 → Linux) Reference table for the engineer porting `ANSLicense.cpp`: | Win32 symbol / API | File:line | Linux replacement | |---|---|---| | `PdhOpenQueryW` / `PdhAddEnglishCounterW` / `PdhCollectQueryData` | ANSLicense.cpp:906–928 | Custom `/proc/stat`, `/proc/diskstats`, `/proc/net/dev` delta sampler (Phase 3.3) | | `IWbemLocator::ConnectServer("ROOT\\WMI")` + `MSAcpi_ThermalZoneTemperature` | ANSLicense.cpp:618–663 | `/sys/class/thermal/thermal_zone*/temp` (Phase 3.2) | | `CreateDXGIFactory1` / `IDXGIAdapter1::GetDesc1` | ANSLicense.cpp:721–747 | `nvmlDeviceGetCount_v2` + per-device queries; libdrm for non-NVIDIA (Phase 3.4) | | `WinHttpOpen` / `WinHttpSendRequest` / etc. | ANSLicense.cpp:1101–1166 | Reuse `anslicensing/download.cpp` libcurl path (Phase 3.5) | | `DnsQuery_A` | ANSLicense.cpp:1228 | `getaddrinfo` or `res_query` (Phase 3.6) | | `GlobalMemoryStatusEx` | ANSLicense.cpp:1036 | `/proc/meminfo` parser (Phase 3.1) | | `GetProcessMemoryInfo` | ANSLicense.cpp:1048 | `/proc/self/status` parser (Phase 3.1) | | `GetSystemDirectoryW` + `GetDiskFreeSpaceExW` | ANSLicense.cpp:1056–1064 | `statvfs("/")` (Phase 3.1) | | `GetCurrentProcessId` | ANSLicense.cpp:993, 1026 | `getpid()` (Phase 3.1) | | `WideCharToMultiByte` / `WideToUtf8` | ANSLicense.cpp:712 | drop on Linux — no wide chars needed without WMI | | `CoInitializeEx` / `CoSetProxyBlanket` / `CoUninitialize` | ANSLicense.cpp:604, 611, 669 | delete on Linux — COM not needed | | `__declspec(dllexport)` | (everywhere) | `__attribute__((visibility("default")))` via `ANSCORE_API` macro (Phase 0.1) | | `LStrHandle`, `LDbl`, `extcode.h` | ANSLicense.h:75 + many | move to `ANSLicense_LV.h`, Windows-only (Phase 0.2) | --- ## Appendix C — License-server coordination checklist Before Phase 1 starts, the license-server team confirms in writing: - [ ] Server accepts HWID format generated by the new Linux `hwid.cpp` path - [ ] Server's HWID validation algorithm matches the new client-side hash inputs - [ ] Decision on license-pool separation: unified vs. Linux-only pool - [ ] Staging environment endpoint available for E2E testing in Phase 3.8 - [ ] Activation portal supports pasting a Linux-generated HWID --- ## Appendix D — What this plan deliberately does NOT cover So a future session doesn't accidentally scope-creep: - **MediaClient port to Linux** — separate plan; ANSCV depends on this but licensing does not - **GStreamer backend for ANSCV** — separate plan - **Engine modules** (ANSODEngine, ANSFR, ANSLPR, ANSOCR, etc.) — separate plans, post-licensing - **gRPC service layer** (ANSService) — planned after engine modules are up - **Qt QML UI** — separate repo, depends on gRPC layer - **macOS support** — not in roadmap currently - **Dropping LabVIEW on Windows** — `_LV` exports stay on Windows builds untouched - **License protocol changes** — wire compatibility preserved; only the input data to the HWID hash changes on Linux --- *End of plan.*