ThreadedIrqDispatcher.h

/*
 * Copyright (c) 2026, Pedigree Developers
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted.
 */
 
#ifndef PEDIGREE_KERNEL_MACHINE_THREADEDIRQDISPATCHER_H
#define PEDIGREE_KERNEL_MACHINE_THREADEDIRQDISPATCHER_H
#include "pedigree/kernel/Spinlock.h"
#include "pedigree/kernel/compiler.h"
#include "pedigree/kernel/process/SchedulerWorkerWake.h"
#include "pedigree/kernel/process/WaitQueue.h"
#include "pedigree/kernel/processor/types.h"
#include "pedigree/kernel/utilities/StaticString.h"
#include "pedigree/kernel/utilities/String.h"
 
#include <config.h>
 
class Thread;
class PerProcessorScheduler;
class Pic;
struct IrqLineDiagnosticSnapshot;
 
class EXPORTED_PUBLIC ThreadedIrqDispatcher {
 public:
  static constexpr size_t MaxLines = 17;
  using DispatchCallback = void (*)(void*, uint8_t, size_t);
  using RemoteWakeCallback = bool (*)(void*, uint8_t, size_t);
 
  ThreadedIrqDispatcher(const String& name, size_t lineCount, DispatchCallback callback,
                        void* callbackContext);
  ~ThreadedIrqDispatcher();
 
  bool initialise();
 
  bool shutdown();
 
  bool canShutdown() const;
 
  bool isInitialised() const;
 
  bool isCurrentWorker() const;
 
  bool publishFromInterrupt(uint8_t line, size_t cookie);
 
#if HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS
  using PublicationObservedHook = void (*)(ThreadedIrqDispatcher*, uint8_t, size_t, size_t);
  using PendingScanAdmittedHook = void (*)(ThreadedIrqDispatcher*, uint8_t);
 
  void setPublicationObservedHookForTest(PublicationObservedHook hook);
 
  bool setPendingSlotCountForTest(size_t slotCount);
 
  bool publishFromSlotForTest(uint8_t line, size_t slot, size_t cookie);
 
  void rejectNextPublicationForTest();
 
  void setPendingScanAdmittedHookForTest(PendingScanAdmittedHook hook);
 
  size_t remotePublicationRejectionsForTest() const {
    return __atomic_load_n(&m_RemotePublicationRejectionsForTest, __ATOMIC_ACQUIRE);
  }
 
  MUST_USE_RESULT bool setRemoteWakeCallbackForTest(RemoteWakeCallback callback,
                                                    void* callbackContext) {
    // Hosted smoke modules are dynamically loaded, so keep this setup
    // hook inline rather than adding a production-exported test symbol.
    m_ConfigurationLock.acquire();
    if (__atomic_load_n(&m_ConfigurationClosed, __ATOMIC_ACQUIRE)) {
      m_ConfigurationLock.release();
      return false;
    }
 
    m_RemoteWakeCallback = callback;
    m_RemoteWakeCallbackContext = callbackContext;
    m_ConfigurationLock.release();
    return true;
  }
#endif
 
  bool hasPending(uint8_t line) const;
 
  size_t pendingCookie(uint8_t line) const;
  size_t activeCookie(uint8_t line) const;
  size_t completedBatches(uint8_t line) const;
  size_t completedCookie(uint8_t line) const;
  uintptr_t workerIdentity(uint8_t line) const;
  bool callbackActive(uint8_t line) const;
  bool publicationClosed(uint8_t line) const;
 
  void snapshotDiagnostics(uint8_t line, IrqLineDiagnosticSnapshot& snapshot) const;
 
 private:
  friend class Pic;
 
  MUST_USE_RESULT bool setRemoteWakeCallback(RemoteWakeCallback callback, void* callbackContext);
 
  class Line {
   public:
    Line();
    ~Line();
 
    void configure(ThreadedIrqDispatcher* owner, uint8_t line, DispatchCallback callback,
                   void* callbackContext);
    bool start();
    void beginStop();
    bool join();
    bool publishFromInterrupt(size_t cookie);
    bool hasPending() const;
    bool isWorker(const Thread* thread) const;
    size_t pendingCookie() const;
    size_t activeCookie() const;
    size_t completedBatches() const;
    size_t completedCookie() const;
    uintptr_t workerIdentity() const;
    bool callbackActive() const;
    bool publicationClosed() const;
    void snapshotDiagnostics(IrqLineDiagnosticSnapshot& snapshot) const;
 
   private:
    static constexpr size_t PublicationClosed = static_cast<size_t>(1)
                                                << ((sizeof(size_t) * 8) - 1);
    static constexpr size_t PublicationCountMask = ~PublicationClosed;
 
    static int workerEntry(void* context);
    int run();
    bool hasPendingForWorker() const;
    size_t pendingCookieForWorker() const;
    size_t takePendingCookie();
    static bool generationReached(size_t current, size_t target);
 
    ThreadedIrqDispatcher* m_Owner;
    DispatchCallback m_Callback;
    void* m_CallbackContext;
    Thread* m_Thread;
    PerProcessorScheduler* m_Scheduler;
    WaitQueue m_WorkerWaiters;
    SchedulerWorkerWake m_WorkerWake;
    size_t m_WorkerProcessor;
    uint8_t m_Line;
    size_t* m_PendingCookies;
    size_t m_PendingCookieCount;
    size_t m_ActiveCookie;
    size_t m_CallbackActive;
    mutable size_t m_PublicationState;
    size_t m_Started;
    size_t m_CompletedBatches;
    size_t m_CompletedCookie;
    size_t m_PendingSinceTimestamp;
    size_t m_ActiveCallbackStartedTimestamp;
    size_t m_LastWakeLatency;
    size_t m_MaximumWakeLatency;
    size_t m_LastCallbackRuntime;
    size_t m_MaximumCallbackRuntime;
 
    Line(const Line&) = delete;
    Line& operator=(const Line&) = delete;
  };
 
  Line m_Lines[MaxLines];
  NormalStaticString m_Name;
  size_t m_LineCount;
  DispatchCallback m_Callback;
  void* m_CallbackContext;
  Spinlock m_ConfigurationLock;
  RemoteWakeCallback m_RemoteWakeCallback;
  void* m_RemoteWakeCallbackContext;
  size_t m_ConfigurationClosed;
  size_t m_Initialised;
  size_t m_ShutdownClaimed;
#if HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS
  PublicationObservedHook m_PublicationObservedHook;
  PendingScanAdmittedHook m_PendingScanAdmittedHook;
  size_t m_PendingSlotCountForTest;
  size_t m_PublicationSlotForTest;
  size_t m_RejectNextPublicationForTest;
  size_t m_RemotePublicationRejectionsForTest;
#endif
 
  ThreadedIrqDispatcher(const ThreadedIrqDispatcher&) = delete;
  ThreadedIrqDispatcher& operator=(const ThreadedIrqDispatcher&) = delete;
};
 
#endif