diff --git a/examples/ccl/scatter.cc b/examples/ccl/scatter.cc new file mode 100644 index 0000000..21cd062 --- /dev/null +++ b/examples/ccl/scatter.cc @@ -0,0 +1,195 @@ +/** + * InfiniCCL Example: Thread-per-GPU Single-Node `Scatter` + * + * This example creates one native CCL rank per GPU and performs a rooted + * scatter without any OpenMPI dependencies. + * + * Use `--launcher none` for this thread-per-GPU example. + */ + +#include + +#include +#include +#include +#include +#include +#include + +// Public API +#include "infiniccl.h" + +// Example-Specific Utilities +#include "utils.h" + +// Internal Headers (Accessible via example-specific include paths, technically +// not public APIs) +#include "backend_manifest.h" + +using namespace infini::ccl; + +constexpr int kRoot = 0; + +// Structure to pass execution data to each GPU worker thread. +struct ThreadArgs { + int rank; + int size; + infinicclUniqueId id; + size_t num_elements; + int warmup_iter; + int profile_iter; + int *correct; +}; + +// Worker function executed by each CPU thread. +void WorkerThread(ThreadArgs args) { + constexpr Device::Type kDevType = + ListGetBest(EnabledDevices{}); + using Rt = Runtime; + + // Bind this CPU thread to its local GPU. + CHECK_RT(Rt, Rt::SetDevice(args.rank)); + + infinicclComm_t comm = nullptr; + CHECK_INFINI(infinicclCommInitRank(&comm, args.size, args.id, args.rank)); + + // Prepare Data: only root sends, and each rank receives its own block. + const bool is_root = args.rank == kRoot; + const size_t recv_bytes = args.num_elements * sizeof(float); + const size_t send_bytes = recv_bytes * static_cast(args.size); + std::vector h_send( + is_root ? args.num_elements * static_cast(args.size) : 0, 0.0f); + std::vector h_recv(args.num_elements, 0.0f); + if (is_root) { + for (int r = 0; r < args.size; ++r) { + for (size_t i = 0; i < args.num_elements; ++i) { + h_send[static_cast(r) * args.num_elements + i] = + static_cast(r + 1); + } + } + } + + float *d_send = nullptr; + float *d_recv = nullptr; + if (is_root) { + CHECK_RT(Rt, Rt::Malloc(reinterpret_cast(&d_send), send_bytes)); + CHECK_RT(Rt, Rt::Memcpy(d_send, h_send.data(), send_bytes, + Rt::MemcpyHostToDevice)); + } + CHECK_RT(Rt, Rt::Malloc(reinterpret_cast(&d_recv), recv_bytes)); + CHECK_RT(Rt, Rt::Memcpy(d_recv, h_recv.data(), recv_bytes, + Rt::MemcpyHostToDevice)); + CHECK_RT(Rt, Rt::StreamSynchronize(nullptr)); + + // Warm-up Iterations + for (int i = 0; i < args.warmup_iter; ++i) { + CHECK_INFINI(infinicclScatter(d_send, d_recv, args.num_elements, + infinicclFloat32, kRoot, comm, nullptr)); + } + CHECK_RT(Rt, Rt::StreamSynchronize(nullptr)); + + // Profiling Iterations + Timer timer; + for (int i = 0; i < args.profile_iter; ++i) { + CHECK_INFINI(infinicclScatter(d_send, d_recv, args.num_elements, + infinicclFloat32, kRoot, comm, nullptr)); + } + CHECK_RT(Rt, Rt::StreamSynchronize(nullptr)); + const double elapsed_ms = + timer.ElapsedMs() / static_cast(args.profile_iter); + + // Result Validation: every rank checks its complete receive block. + CHECK_RT(Rt, Rt::Memcpy(h_recv.data(), d_recv, recv_bytes, + Rt::MemcpyDeviceToHost)); + CHECK_RT(Rt, Rt::StreamSynchronize(nullptr)); + *args.correct = Validator::ValidateResult(h_recv.data(), args.num_elements, + static_cast(args.rank + 1), + args.rank, true, "Scatter"); + + // Metrics Reporting (Only Root) + if (is_root) { + Metrics metrics{elapsed_ms, send_bytes, args.size}; + metrics.Print(); + } + + // Cleanup local rank resources. + if (is_root) { + CHECK_RT(Rt, Rt::Free(d_send)); + } + CHECK_RT(Rt, Rt::Free(d_recv)); + CHECK_INFINI(infinicclCommDestroy(comm)); +} + +int main(int argc, char **argv) { + int num_gpus = 8; + int warmup_iters = 2; + int profile_iters = 20; + size_t num_elements = 1 << 20; + + int opt; + while ((opt = getopt(argc, argv, "g:w:p:n:h")) != -1) { + switch (opt) { + case 'g': + num_gpus = std::stoi(optarg); + break; + case 'w': + warmup_iters = std::stoi(optarg); + break; + case 'p': + profile_iters = std::stoi(optarg); + break; + case 'n': + num_elements = static_cast(std::stoull(optarg)); + break; + case 'h': + std::cout << "Usage: " << argv[0] << " [options]\n" + << "Options:\n" + << " -g Number of GPUs (default: 8)\n" + << " -w Warmup iterations (default: 2)\n" + << " -p Profile iterations (default: 20)\n" + << " -n Number of elements (default: " + << (1 << 20) << ")\n"; + return EXIT_SUCCESS; + default: + std::cerr << "Invalid argument. Use -h for help." << std::endl; + return EXIT_FAILURE; + } + } + + if (num_gpus <= 0 || warmup_iters <= 0 || profile_iters <= 0 || + num_elements == 0 || + num_elements > std::numeric_limits::max() / sizeof(float) / + static_cast(num_gpus)) { + std::cerr << "`Scatter` arguments or buffer size are invalid." << std::endl; + return EXIT_FAILURE; + } + + char hostname[256]; + gethostname(hostname, sizeof(hostname)); + std::cout << "[Main Process] Host: " << hostname + << " | Target GPUs: " << num_gpus << std::endl; + + infinicclUniqueId shared_id; + CHECK_INFINI(infinicclGetUniqueId(&shared_id)); + + std::vector correct(num_gpus, 0); + std::vector threads; + threads.reserve(num_gpus); + for (int rank = 0; rank < num_gpus; ++rank) { + ThreadArgs args{rank, num_gpus, shared_id, num_elements, + warmup_iters, profile_iters, &correct[rank]}; + threads.emplace_back(WorkerThread, args); + } + + for (auto &thread : threads) { + if (thread.joinable()) { + thread.join(); + } + } + + const bool result = std::all_of(correct.begin(), correct.end(), + [](int value) { return value != 0; }); + std::cout << "[Main Process] Scatter validation " + << (result ? "passed." : "failed.") << std::endl; + return result ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/examples/ccl_mpi_hybrid/scatter.cc b/examples/ccl_mpi_hybrid/scatter.cc new file mode 100644 index 0000000..c4226c2 --- /dev/null +++ b/examples/ccl_mpi_hybrid/scatter.cc @@ -0,0 +1,180 @@ +/** + * InfiniCCL Example: `Scatter` (OpenMPI + CCL Hybrid) + * + * This example demonstrates the API for performing a collective + * data distribution across multiple GPUs and nodes, where `root` + * sends a distinct block to every rank. + */ + +#include + +#include +#include +#include + +// Public API +#include "infiniccl.h" + +// Example-Specific Utilities +#include "utils.h" + +// Internal Headers (Accessible via example-specific include paths, technically +// not public APIs) +#include "backend_manifest.h" +#include "device.h" +#include "runtime.h" +#include "traits.h" + +using namespace infini::ccl; + +bool RunScatterExample(int argc, char **argv, int warmup_iter, int profile_iter, + const size_t kNumElements) { + constexpr Device::Type kDevType = + ListGetBest(EnabledDevices{}); + using Rt = Runtime; + + CHECK_INFINI(infinicclInit(&argc, &argv)); + + int rank, size; + CHECK_INFINI(infinicclGetRank(&rank)); + CHECK_INFINI(infinicclGetSize(&size)); + + char hostname[256]; + gethostname(hostname, sizeof(hostname)); + + // Map local rank to GPU device. + const char *local_rank_str = std::getenv("OMPI_COMM_WORLD_LOCAL_RANK"); + int local_rank = 0; + if (local_rank_str != nullptr) { + local_rank = std::atoi(local_rank_str); + } + + CHECK_RT(Rt, Rt::SetDevice(local_rank)); + + std::cout << "[Rank " << rank << "] Host: " << hostname + << " | GPU: " << Device::StringFromType(kDevType) << " " + << " | Device " << local_rank << std::endl; + + // Setup Communicator + infinicclComm_t comm = nullptr; + CHECK_INFINI(infinicclCommInitAll(&comm, size, nullptr)); + infinicclUniqueId id; + if (rank == 0) { + CHECK_INFINI(infinicclGetUniqueId(&id)); + } + CHECK_INFINI(infinicclBroadcast(&id, &id, sizeof(id), infinicclChar, 0, comm, + nullptr)); + CHECK_INFINI(infinicclCommInitRank(&comm, size, id, rank)); + + // Root of the Scatter + constexpr int kRoot = 0; + + // Prepare Data + if (size <= 0 || kNumElements == 0 || + kNumElements > std::numeric_limits::max() / sizeof(float) / + static_cast(size)) { + std::cerr << "`Scatter` buffer size is invalid." << std::endl; + CHECK_INFINI(infinicclCommDestroy(comm)); + CHECK_INFINI(infinicclFinalize()); + return false; + } + const bool is_root = rank == kRoot; + std::vector h_send( + is_root ? kNumElements * static_cast(size) : 0, 0.0f); + std::vector h_recv(kNumElements, 0.0f); + + // Initialize: `root` fills the block destined for rank `r` with `(r + 1)`. + if (rank == kRoot) { + for (int r = 0; r < size; ++r) { + for (size_t i = 0; i < kNumElements; ++i) { + h_send[static_cast(r) * kNumElements + i] = + static_cast(r + 1); + } + } + } + + float *d_send = nullptr; + float *d_recv = nullptr; + size_t recv_bytes = kNumElements * sizeof(*d_recv); + size_t send_bytes = recv_bytes * size; + if (is_root) { + CHECK_RT(Rt, Rt::Malloc((void **)&d_send, send_bytes)); + } + CHECK_RT(Rt, Rt::Malloc((void **)&d_recv, recv_bytes)); + if (is_root) { + CHECK_RT(Rt, Rt::Memcpy(d_send, h_send.data(), send_bytes, + Rt::MemcpyHostToDevice)); + } + CHECK_RT(Rt, Rt::Memcpy(d_recv, h_recv.data(), recv_bytes, + Rt::MemcpyHostToDevice)); + + if (rank == kRoot) { + std::cout << "\n=== Performing Scatter on GPU Memory ===" << std::endl; + std::cout << "Data size per rank: " << kNumElements << " floats (" + << recv_bytes / 1024 / 1024 << " MB)" << std::endl; + std::cout << "Operation: Scatter" << std::endl; + std::cout << "Root Rank: " << kRoot << std::endl; + std::cout << "Warm-up iterations: " << warmup_iter << std::endl; + std::cout << "Profile iterations: " << profile_iter << std::endl; + } + + CHECK_RT(Rt, Rt::StreamSynchronize(nullptr)); + + // Warm-up + for (int i = 0; i < warmup_iter; ++i) { + CHECK_INFINI(infinicclScatter(d_send, d_recv, kNumElements, + infinicclFloat32, kRoot, comm, nullptr)); + } + CHECK_RT(Rt, Rt::StreamSynchronize(nullptr)); + + // Profiling + Timer timer; + + for (int i = 0; i < profile_iter; ++i) { + CHECK_INFINI(infinicclScatter(d_send, d_recv, kNumElements, + infinicclFloat32, kRoot, comm, nullptr)); + } + + CHECK_RT(Rt, Rt::StreamSynchronize(nullptr)); + double elapsed = timer.ElapsedMs() / static_cast(profile_iter); + + // Result Validation: every rank should receive its own `(rank + 1)` block. + CHECK_RT(Rt, Rt::Memcpy(h_recv.data(), d_recv, recv_bytes, + Rt::MemcpyDeviceToHost)); + + CHECK_RT(Rt, Rt::StreamSynchronize(nullptr)); + const bool correct = Validator::ValidateResult(h_recv.data(), kNumElements, + static_cast(rank + 1), + rank, true, "Scatter"); + + // Metrics Reporting (Only from rank 0 for cleaner output) + if (rank == kRoot) { + Metrics metrics{elapsed, send_bytes, size}; + metrics.Print(); + } + + // Cleanup + if (is_root) { + CHECK_RT(Rt, Rt::Free(d_send)); + } + CHECK_RT(Rt, Rt::Free(d_recv)); + + CHECK_INFINI(infinicclCommDestroy(comm)); + CHECK_INFINI(infinicclFinalize()); + + if (rank == kRoot) { + std::cout << "InfiniCCL finalized." << std::endl; + } + return correct; +} + +int main(int argc, char **argv) { + int warmup_iters = 2; + int profile_iters = 20; + size_t num_elements = 1 << 20; + + return RunScatterExample(argc, argv, warmup_iters, profile_iters, + num_elements) + ? EXIT_SUCCESS + : EXIT_FAILURE; +} diff --git a/src/backends/ccl/common/impl/scatter.h b/src/backends/ccl/common/impl/scatter.h new file mode 100644 index 0000000..07e7699 --- /dev/null +++ b/src/backends/ccl/common/impl/scatter.h @@ -0,0 +1,67 @@ +#ifndef INFINI_CCL_BACKENDS_CCL_COMMON_IMPL_SCATTER_H_ +#define INFINI_CCL_BACKENDS_CCL_COMMON_IMPL_SCATTER_H_ + +#include +#include + +#include "backends/ccl/common/api.h" +#include "backends/ccl/common/comm_instance.h" +#include "base/scatter.h" +#include "communicator.h" +#include "data_type_impl.h" +#include "logging.h" + +namespace infini::ccl { + +template +class CclScatterImpl { + public: + static ReturnStatus Apply(const void *send_buff, void *recv_buff, + size_t count, DataType data_type, int root, + Communicator *comm, void *stream) { + using Api = CclApi; + using TypeMap = CclTypeMap; + using CommInstance = CclCommInstance; + + if (!comm || !comm->intra_comm() || comm->intra_comm_backend() != backend || + comm->device_type() != device) { + return ReturnStatus::kInternalError; + } + + if (comm->size() <= 0 || comm->rank() < 0 || comm->rank() >= comm->size() || + root < 0 || root >= comm->size()) { + LOG("Invalid rank, root, or world size for native CCL `Scatter`."); + return ReturnStatus::kInternalError; + } + + auto *instance = static_cast(comm->intra_comm()); + if (!instance->handle) { + return ReturnStatus::kInternalError; + } + + typename Api::DataType native_type{}; + if (!TypeMap::ToBackendDataType(data_type, &native_type)) { + return ReturnStatus::kNotSupported; + } + + const size_t type_size = kDataTypeToSize.at(data_type); + if (count > std::numeric_limits::max() / type_size) { + LOG("Per-rank byte size overflows `size_t` for native CCL `Scatter`."); + return ReturnStatus::kInvalidArgument; + } + const size_t rank_bytes = count * type_size; + const size_t world_size = static_cast(comm->size()); + if (rank_bytes > std::numeric_limits::max() / world_size) { + LOG("Total byte size overflows `size_t` for native CCL `Scatter`."); + return ReturnStatus::kInvalidArgument; + } + + return Api::Check(Api::Scatter( + send_buff, recv_buff, count, native_type, root, instance->handle, + reinterpret_cast(stream))); + } +}; + +} // namespace infini::ccl + +#endif // INFINI_CCL_BACKENDS_CCL_COMMON_IMPL_SCATTER_H_ diff --git a/src/backends/ccl/mccl/api.h b/src/backends/ccl/mccl/api.h index ab08249..cfbb610 100644 --- a/src/backends/ccl/mccl/api.h +++ b/src/backends/ccl/mccl/api.h @@ -43,6 +43,13 @@ struct McclApi { static Result CommDestroy(Comm comm) { return mcclCommDestroy(comm); } + static Result Scatter(const void *send_buff, void *recv_buff, size_t count, + DataType data_type, int root, Comm comm, + Stream stream) { + return mcclScatter(send_buff, recv_buff, count, data_type, root, comm, + stream); + } + static Result AllReduce(const void *send_buff, void *recv_buff, size_t count, DataType data_type, RedOp op, Comm comm, Stream stream) { diff --git a/src/backends/ccl/mccl/impl/scatter.h b/src/backends/ccl/mccl/impl/scatter.h new file mode 100644 index 0000000..438ad46 --- /dev/null +++ b/src/backends/ccl/mccl/impl/scatter.h @@ -0,0 +1,17 @@ +#ifndef INFINI_CCL_BACKENDS_CCL_MCCL_IMPL_SCATTER_H_ +#define INFINI_CCL_BACKENDS_CCL_MCCL_IMPL_SCATTER_H_ + +#include "backends/ccl/common/impl/scatter.h" + +namespace infini::ccl { + +template +class ScatterImpl + : public CclScatterImpl {}; + +template <> +struct BackendEnabled : std::true_type {}; + +} // namespace infini::ccl + +#endif // INFINI_CCL_BACKENDS_CCL_MCCL_IMPL_SCATTER_H_ diff --git a/src/backends/ccl/nccl/api.h b/src/backends/ccl/nccl/api.h index 85c7e91..4c71fd8 100644 --- a/src/backends/ccl/nccl/api.h +++ b/src/backends/ccl/nccl/api.h @@ -42,6 +42,13 @@ struct NcclApi { static Result CommDestroy(Comm comm) { return ncclCommDestroy(comm); } + static Result Scatter(const void* send_buff, void* recv_buff, size_t count, + DataType data_type, int root, Comm comm, + Stream stream) { + return ncclScatter(send_buff, recv_buff, count, data_type, root, comm, + stream); + } + static Result AllReduce(const void* send_buff, void* recv_buff, size_t count, DataType data_type, RedOp op, Comm comm, Stream stream) { diff --git a/src/backends/ccl/nccl/impl/scatter.h b/src/backends/ccl/nccl/impl/scatter.h new file mode 100644 index 0000000..b710f00 --- /dev/null +++ b/src/backends/ccl/nccl/impl/scatter.h @@ -0,0 +1,17 @@ +#ifndef INFINI_CCL_BACKENDS_CCL_NCCL_IMPL_SCATTER_H_ +#define INFINI_CCL_BACKENDS_CCL_NCCL_IMPL_SCATTER_H_ + +#include "backends/ccl/common/impl/scatter.h" + +namespace infini::ccl { + +template +class ScatterImpl + : public CclScatterImpl {}; + +template <> +struct BackendEnabled : std::true_type {}; + +} // namespace infini::ccl + +#endif // INFINI_CCL_BACKENDS_CCL_NCCL_IMPL_SCATTER_H_ diff --git a/src/base/scatter.h b/src/base/scatter.h index 62643f6..a95b390 100644 --- a/src/base/scatter.h +++ b/src/base/scatter.h @@ -18,18 +18,13 @@ class Scatter : public Operation { static ReturnStatus Execute(const void *send_buff, void *recv_buff, size_t count, DataType datatype, int root, void *comm_handle, void *stream) { - if (!comm_handle) { - LOG("Invalid communicator handle for `Scatter`."); - return ReturnStatus::kInvalidArgument; - } - - auto *comm = static_cast(comm_handle); - if (HasInvalidArgs(send_buff, recv_buff, datatype, root, comm)) { - return ReturnStatus::kInvalidArgument; - } if (count == 0) { return ReturnStatus::kSuccess; } + if (HasInvalidArgs(send_buff, recv_buff, datatype, root, comm_handle)) { + return ReturnStatus::kInvalidArgument; + } + auto *comm = static_cast(comm_handle); return ScatterImpl::Apply( send_buff, recv_buff, count, datatype, root, comm, stream); @@ -37,7 +32,12 @@ class Scatter : public Operation { private: static bool HasInvalidArgs(const void *send_buff, void *recv_buff, - DataType datatype, int root, Communicator *comm) { + DataType datatype, int root, void *comm_handle) { + if (!comm_handle) { + LOG("Invalid communicator handle for `Scatter`."); + return true; + } + auto *comm = static_cast(comm_handle); if (datatype < DataType::kChar || datatype >= DataType::kNumTypes) { LOG("Invalid data type for `Scatter`."); return true;