diff --git a/docs/PLAN_Linux_Licensing_Port.md b/docs/PLAN_Linux_Licensing_Port.md new file mode 100644 index 0000000..4a5182b --- /dev/null +++ b/docs/PLAN_Linux_Licensing_Port.md @@ -0,0 +1,573 @@ +# 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.*