Line data    Source code

       1              : /**
       2              :  * Copyright (c) 2025 Huawei Technologies Co., Ltd.
       3              :  * This program is free software, you can redistribute it and/or modify it under the terms and conditions of
       4              :  * CANN Open Software License Agreement Version 2.0 (the "License").
       5              :  * Please refer to the License for details. You may not use this file except in compliance with the License.
       6              :  * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
       7              :  * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
       8              :  * See LICENSE in the root of the software repository for the full text of the License.
       9              :  */
      10              : 
      11              : #ifndef ENDPOINT_H
      12              : #define ENDPOINT_H
      13              : 
      14              : #include <memory>
      15              : #include <functional>
      16              : #include <vector>
      17              : #include <string>
      18              : #include "reged_mem_mgr.h"
      19              : #include "socket/socket.h"
      20              : #include "socket_handle_manager.h"
      21              : #include "rdma_handle_manager.h"
      22              : #include "../../common/orion_adpt_utils.h"
      23              : #include "hccp_hdc_manager.h"
      24              : #include "hcomm_nic_plugin.h"
      25              : #include "proc_reged_mem_mgr_cache.h"
      26              : #include "jetty_context.h"
      27              : #include "dfx/endpoint_monitor.h"
      28              : 
      29              : namespace hcomm {
      30              : class EndpointMonitor;
      31              : /**
      32              :  * @note 职责：通信设备Endpoint的C++抽象接口类，管理通信设备上下文，以及设备上的注册内存。
      33              :  *       共享 Jetty 数据面资源（jetty 句柄 / QP key / PI·CI / JFC / 远端 jetty 缓存）内聚于
      34              :  *       JettyContext，Endpoint 持 unique_ptr 延迟创建，控制面职责不因共享 jetty 特性膨胀。
      35              :  *       IS_SHARED_QUEUE=true 时，本 endpoint 下创建的 channel 复用 jettyContext_ 中的 jetty 句柄。
      36              :  */
      37              : class Endpoint {
      38              : public:
      39              :     // 兼容别名：历史代码直接引用 Endpoint::SharedJettyCtx，实际为 JettyContext::Ctx 视图
      40              :     using SharedJettyCtx = JettyContext::Ctx;
      41              :     using SharedRemoteJettyCtx = JettyContext::SharedRemoteJettyCtx;
      42              : 
      43              :     explicit Endpoint(const EndpointDesc& endpointDesc);
      44              : 
      45              :     virtual ~Endpoint();
      46              : 
      47              :     static HcclResult CreateEndpoint(const EndpointDesc& endpointDesc, std::unique_ptr<Endpoint>& endpointPtr);
      48              : 
      49              :     virtual HcclResult Init() = 0;
      50              : 
      51              :     virtual HcclResult ServerSocketListen(const uint32_t port) = 0;
      52              : 
      53            0 :     virtual HcclResult ServerSocketStopListen([[maybe_unused]] const uint32_t port) { return HCCL_E_NOT_SUPPORT; };
      54            1 :     virtual HcclResult ServerSocketGetListenPort([[maybe_unused]] uint32_t* port) { return HCCL_E_NOT_SUPPORT; };
      55              : 
      56           43 :     virtual std::shared_ptr<RegedMemMgr> GetRegedMemMgr() { return regedMemMgr_; }
      57              : 
      58          140 :     void* GetRdmaHandle() { return ctxHandle_; }
      59              : 
      60            7 :     bool IsCtxHandleValid() const
      61              :     {
      62            7 :         if (ctxHandle_ == nullptr) {
      63            2 :             return false;
      64              :         }
      65            5 :         return Hccl::RdmaHandleManager::GetInstance().IsHandleValid(static_cast<Hccl::RdmaHandle>(ctxHandle_));
      66              :     }
      67              : 
      68          314 :     EndpointDesc GetEndpointDesc() { return endpointDesc_; }
      69              : 
      70              :     // 注册内存
      71              :     virtual HcclResult RegisterMemory(HcommMem mem, const char* memTag, void** memHandle) = 0;
      72              : 
      73              :     // 注销内存
      74              :     virtual HcclResult UnregisterMemory(void* memHandle) = 0;
      75              : 
      76              :     // 导出指定内存描述，用于交换
      77              :     virtual HcclResult MemoryExport(void* memHandle, void** memDesc, uint32_t* memDescLen) = 0;
      78              : 
      79              :     // 基于内存描述，导入获得内存
      80              :     virtual HcclResult MemoryImport(const void* memDesc, uint32_t descLen, HcommMem* outMem) = 0;
      81              : 
      82              :     // 关闭内存
      83              :     virtual HcclResult MemoryUnimport(const void* memDesc, uint32_t descLen) = 0;
      84              : 
      85              :     virtual HcclResult GetAllMemHandles(void** memHandles, uint32_t* memHandleNum) = 0;
      86              : 
      87            0 :     virtual HcclResult MemoryGrant([[maybe_unused]] const HcommMemGrantInfo* remoteGrantInfo) { return HCCL_SUCCESS; }
      88              : 
      89              :     static HcclResult CheckFeature(const EndpointDesc& endpointDesc, HcommEndpointFeatureType featureType, bool& value);
      90              : 
      91              :     // 获取UB异步事件
      92            0 :     virtual HcclResult GetAsyncEvents(uint32_t devPhyId, struct AsyncEvent events[], uint32_t& num)
      93              :     {
      94              :         (void)devPhyId;
      95              :         (void)events;
      96            0 :         num = 0;
      97            0 :         return HCCL_SUCCESS;
      98              :     }
      99              : 
     100              :     // ---- 共享 Jetty 管理（仅 IS_SHARED_QUEUE=true 时使用）----
     101              :     /**
     102              :      * @brief 获取或创建共享 jetty。命中复用 refCount++；未命中调 provideCtx 创建并缓存。
     103              :      * @param[in] provideCtx 创建回调（首次时调用，回调内创建 jetty 并填入 ctx）
     104              :      * @param[out] outCtx 输出的 jetty 上下文
     105              :      */
     106              :     HcclResult AcquireSharedJetty(const std::function<HcclResult(SharedJettyCtx&)>& provideCtx, SharedJettyCtx& outCtx);
     107              :     /** 释放共享 jetty 引用，refCount-- 归 0 时销毁 jetty 并清空 ctx */
     108              :     HcclResult ReleaseSharedJetty();
     109              : 
     110              :     HcclResult AcquireSharedRemoteJetty(
     111              :         const uint8_t* remoteQpKey, uint32_t keySize, bool& needImport, uint64_t& handle, void*& handlePtr,
     112              :         uint32_t& tpn);
     113              :     HcclResult PublishSharedRemoteJetty(
     114              :         const uint8_t* remoteQpKey, uint32_t keySize, uint64_t handle, void* handlePtr, uint32_t tpn);
     115              : 
     116              :     /** 延迟创建并获取 JettyContext（首次调用创建，后续返回已有） */
     117              :     JettyContext* GetJettyContext();
     118              : 
     119              :     // ------------------ NIC插件相关 ------------------
     120           94 :     void SetNicEndpointCtx(HcommNicEndpointOps* nicOps, void* nicCtx)
     121              :     {
     122           94 :         nicOps_ = nicOps;
     123           94 :         nicCtx_ = nicCtx;
     124           94 :     }
     125          274 :     HcommNicEndpointOps* GetNicOps() const { return nicOps_; }
     126          130 :     void* GetNicCtx() const { return nicCtx_; }
     127              : 
     128              :     // Register：AttachMonitor 拷贝 GetHolder，再用持有的指针 RegisterToEndpointMonitor。
     129              :     // Destroy / 析构走 ReleaseEndpointMonitor。未 Register 的空指针直接返回。不要再调 GetHolder()。
     130              :     void AttachMonitor(s32 logicId);
     131              :     HcclResult RegisterToEndpointMonitor(s32 logicId, EndpointHandle handle);
     132              :     void ReleaseEndpointMonitor(EndpointHandle handle);
     133              : 
     134              : protected:
     135              :     static HcclResult CreateEndpointBase(const EndpointDesc& endpointDesc, std::unique_ptr<Endpoint>& endpointPtr);
     136              :     // Init 成功后持有 Cache GetHolder 拷贝；析构走 ReleaseCache，不要再调 GetHolder()。
     137              :     HcclResult AttachCache(const MemMgrCacheKey& key, std::function<std::shared_ptr<RegedMemMgr>()> creator);
     138              :     void ReleaseCache();
     139              :     void* ctxHandle_{nullptr};
     140              :     std::shared_ptr<RegedMemMgr> regedMemMgr_{};
     141              :     EndpointDesc endpointDesc_;
     142              :     std::once_flag jettyContextOnce_;
     143              : 
     144              :     // 共享 jetty 数据面资源内聚于 JettyContext，延迟创建，控制面职责不膨胀
     145              :     std::unique_ptr<JettyContext> jettyContext_{nullptr};
     146              :     HcommNicEndpointOps* nicOps_{nullptr};
     147              :     void* nicCtx_{nullptr};
     148              :     MemMgrCacheKey cacheKey_{};
     149              :     std::shared_ptr<ProcRegedMemMgrCache> cacheKeepAlive_{};
     150              :     std::shared_ptr<EndpointMonitor> monitorKeepAlive_{};
     151              : };
     152              : 
     153              : } // namespace hcomm
     154              : #endif // ENDPOINT_H