Initial commit

srcs/RobotNet10/Commons/RobotNet10.Realtime/README.md

@@ -0,0 +1,158 @@
+# RobotNet10.Realtime
+
+## Overview / Tổng quan
+
+`RobotNet10.Realtime` là một wrapper library cho các tính năng realtime của Linux preempt_rt kernel. Library này cung cấp các API .NET để sử dụng các tính năng realtime như scheduling policies, CPU affinity, memory locking, và high-resolution timers.
+
+## Features / Tính năng
+
+- **Real-time Scheduling**: SCHED_FIFO, SCHED_RR scheduling policies
+- **CPU Affinity**: Pin threads to specific CPU cores
+- **Memory Locking**: Prevent memory from being swapped to disk
+- **High-resolution Timers**: timerfd-based timers for precise timing
+- **High-resolution Clocks**: Access to CLOCK_MONOTONIC and other Linux clocks
+
+## Requirements / Yêu cầu
+
+- Linux kernel with preempt_rt patch
+- .NET 10.0 runtime
+- Root privileges may be required for some operations (scheduling policies, memory locking)
+
+## Usage Examples / Ví dụ Sử dụng
+
+### Real-time Scheduling
+
+```csharp
+using RobotNet10.Realtime;
+
+// Set SCHED_FIFO policy with priority 50
+RealtimeScheduler.SetSchedulingPolicy(RealtimeSchedulingPolicy.Fifo, 50);
+
+// Get current policy and priority
+var policy = RealtimeScheduler.GetSchedulingPolicy();
+var priority = RealtimeScheduler.GetPriority();
+
+// Change priority only
+RealtimeScheduler.SetPriority(75);
+```
+
+### CPU Affinity
+
+```csharp
+using RobotNet10.Realtime;
+
+// Pin current thread to CPU 0 and 1
+CpuAffinity.SetAffinity(0, 1);
+
+// Or use CpuAffinity class for more control
+var affinity = new CpuAffinity();
+affinity.AddCpu(0);
+affinity.AddCpu(2);
+affinity.Apply();
+
+// Get current affinity
+var currentAffinity = CpuAffinity.GetAffinity();
+var cpus = currentAffinity.GetCpus(); // List of CPU numbers
+```
+
+### Memory Locking
+
+```csharp
+using RobotNet10.Realtime;
+
+// Lock all current and future memory pages
+MemoryLock.LockAll(MemoryLockFlags.Current | MemoryLockFlags.Future);
+
+// Lock a specific array
+var array = new byte[1024 * 1024];
+var handle = MemoryLock.LockArray(array);
+try
+{
+    // Use array...
+}
+finally
+{
+    handle.Free();
+    MemoryLock.Unlock(handle.AddrOfPinnedObject(), new IntPtr(array.Length));
+}
+```
+
+### High-resolution Timer
+
+```csharp
+using RobotNet10.Realtime;
+
+// Create a periodic timer
+using var timer = new RealtimeTimer(RealtimeClockType.Monotonic);
+timer.SetPeriodic(TimeSpan.FromMilliseconds(10)); // 10ms interval
+
+// In a loop, read expirations
+while (running)
+{
+    ulong expirations = timer.ReadExpirations();
+    if (expirations > 0)
+    {
+        // Timer expired, do work
+        DoWork();
+    }
+}
+
+// One-shot timer
+timer.SetOneShot(TimeSpan.FromSeconds(5)); // Fire once after 5 seconds
+```
+
+### High-resolution Clock
+
+```csharp
+using RobotNet10.Realtime;
+
+// Use monotonic clock for measuring elapsed time
+var clock = new RealtimeClock(RealtimeClockType.Monotonic);
+var startTime = clock.GetTimeSpan();
+
+// Do work...
+
+var elapsed = clock.GetTimeSpan() - startTime;
+Console.WriteLine($"Elapsed: {elapsed.TotalMilliseconds} ms");
+
+// Get clock resolution
+var resolution = clock.GetResolution();
+Console.WriteLine($"Clock resolution: {resolution.TotalNanoseconds} ns");
+```
+
+## Important Notes / Lưu Ý Quan trọng
+
+1. **Root Privileges**: Many real-time operations require root privileges. Run your application with `sudo` or set capabilities:
+   ```bash
+   sudo setcap cap_sys_nice+ep /path/to/your/app
+   ```
+
+2. **Memory Locking Limits**: The system has limits on how much memory can be locked. Check `/proc/sys/vm/max_locked_memory`.
+
+3. **Priority Range**: Real-time priorities range from 1-99. Higher numbers = higher priority.
+
+4. **Platform Specific**: This library only works on Linux. Use `#if` directives or runtime checks for cross-platform code.
+
+5. **Thread Safety**: Most operations affect the current thread only. Use appropriate synchronization for multi-threaded applications.
+
+## Error Handling / Xử lý Lỗi
+
+All operations throw `RealtimeException` on failure:
+
+```csharp
+try
+{
+    RealtimeScheduler.SetSchedulingPolicy(RealtimeSchedulingPolicy.Fifo, 50);
+}
+catch (RealtimeException ex)
+{
+    Console.WriteLine($"Failed: {ex.Message}, errno: {ex.Errno}");
+}
+```
+
+## Related Documents / Tài liệu Liên quan
+
+- Linux man pages: `man 2 sched_setscheduler`, `man 2 timerfd_create`, etc.
+- [Linux RT Wiki](https://rt.wiki.kernel.org/)
+- [PREEMPT_RT Patch Documentation](https://wiki.linuxfoundation.org/realtime/documentation)
+