// CoverFilter is PC hash set that can be placed in shared memory.

//

// The set can cover up to 4 distinct 1GB regions of PCs.

// This restriction allows for efficient, simple and shared memory compatible representation,

// but should be enough to cover any reasonable combination of kernel/modules mapping.

//

// Low 3 bits of PCs are discarded. This reduces memory consumption 8x, but allows for some false positives.

// However, in practice false positives should be very rare. A typical coverage call instruction is 4/5 bytes,

// and there must be at least 1 other instruction in between them to make them different basic blocks,

// so it's practically impossible to place 2 of them in the same 8-byte region.

// For signal with hashed low 12 bits the probability is also low b/c overall density of coverage callbacks

// is relatively low, a KASAN Linux kernel contains 1 callback per 88 bytes of code on average.

// So even if we discard low 3 bits, average densitiy is still 1/11.

// For gVisor with dense coverage IDs special care must be taken to avoid collisions.

//

// The set is organized as a 3 level table.

// The top "region" level is linear lookup, but contains at most 4 entries, each covering 1GB.

// Most likely the first entry is the right one. This level allows to cover unconnected regions of PCs.

// The next "L1" level splits 1GB chunks into 1MB chunks, and allows to allocate memory only

// for a subset of these 1MB chunks.

// The last "L2" level covers 1MB chunks with 16KB bitmaps (1MB divided by 8 for 3 discarded PC bits,

// and divided by 8 again for 8 bits in a byte).

class CoverFilter

{

public:

	CoverFilter()

		  // 申请一片共享内存，大小 kMemSize

	    : shmem_(kMemSize),

		  // 把共享内存首地址解释成 Table 结构体指针，所以共享内存的布局就是 Table 的定义

	      tab_(static_cast<Table*>(shmem_.Mem()))

	{

	}

	CoverFilter(int fd, void* preferred = nullptr)

	    : shmem_(fd, preferred, kMemSize, false),

	      tab_(static_cast<Table*>(shmem_.Mem()))

	{

	}

	// 把 pc 插入 filter

	void Insert(uint64 pc)

	{

		auto [byte, bit] = FindByte(pc, true);

		byte |= bit;

	}

	// 检查 pc 是否在 filter 中

	bool Contains(uint64 pc)

	{

		auto [byte, bit] = FindByte(pc, false);

		return byte & bit;

	}

	// Prevents any future modifications to the filter.

	// 只读保护，防止未来修改

	void Seal()

	{

		shmem_.Seal();

	}

	// 用于把这块共享内存传给子进程

	int FD() const

	{

		return shmem_.FD();

	}

private:

	static constexpr size_t kNumRegions = 4;

	static constexpr size_t kL1Size = 1 << 30;

	static constexpr size_t kL2Size = 1 << 20;

	static constexpr size_t kPCDivider = 8;

	static constexpr size_t kByteBits = 8;

	// Approximately how much .text we can cover (2GB of PCs require 32MB shmem region).

	static constexpr size_t kMaxCovered = 2ull << 30;

	static constexpr size_t kCompression = kPCDivider * kByteBits;

	static constexpr size_t kMemSize = kMaxCovered / kCompression;

	static constexpr size_t kNoRegion = static_cast<size_t>(-1);

	// 共享内存布局，三级表结构

	//regions: 每个 region 占 8 字节，存放该 region 覆盖的 1GB 地址的最高地址（低 30 位全 1）

	//l1: 每个 region 包含 1024 个 l1 entries，每个 entries 占 2 字节，存放对应的 l2 索引

	//l2: 每个 l2 条目是一个 16KB bitmap，覆盖 1MB 的 PC 范围 （丢低 3 位 + 用 1bit 来表示 1byte，1MB / 8 / 8 = 16KB）

	struct Table {

		uint64 regions[kNumRegions];

		uint16 l1[kNumRegions][kL1Size / kL2Size];

		uint8 l2[][kL2Size / kCompression];

	};

	ShmemFile shmem_;

	Table* tab_ = nullptr;

	uint16 alloc_ = 0;

	// 给定 pc 找到对应 bitmap 的 “字节引用 + bit mask”

	std::pair<uint8&, uint8> FindByte(uint64 pc, bool add = false)

	{

		static const uint8 empty = 0;

		size_t reg = FindRegion(pc, add);

		if (reg == kNoRegion)

			return {const_cast<uint8&>(empty), 0};

		size_t l1 = (pc % kL1Size) / kL2Size;

		size_t l2 = tab_->l1[reg][l1];

		if (l2 == 0) {

			if (!add)

				return {const_cast<uint8&>(empty), 0};

			l2 = ++alloc_;

			tab_->l1[reg][l1] = l2;

			if ((tab_->l2[l2 - 1] + 1) > reinterpret_cast<uint8*>(tab_) + kMemSize)

				Overflow(pc);

		}

		size_t off = (pc % kL2Size) / kCompression;

		size_t shift = (pc / kPCDivider) % kByteBits;

		return {tab_->l2[l2 - 1][off], 1 << shift};

	}

	// 把 PC 归类到最多 4 个 1GB 区域，返回区域索引

	size_t FindRegion(uint64 pc, bool add = false)

	{

		const uint64 reg = pc | (kL1Size - 1);

		for (size_t r = 0; r < kNumRegions; r++) {

			if (tab_->regions[r] == reg)

				return r;

		}

		if (!add)

			return kNoRegion;

		for (size_t r = 0; r < kNumRegions; r++) {

			if (tab_->regions[r] == 0) {

				tab_->regions[r] = reg;

				return r;

			}

		}

		Overflow(pc);

	}

	// 满了就直接 fail

	NORETURN void Overflow(uint64 pc)

	{

		failmsg("coverage filter is full", "pc=0x%llx regions=[0x%llx 0x%llx 0x%llx 0x%llx] alloc=%u",

			pc, tab_->regions[0], tab_->regions[1], tab_->regions[2], tab_->regions[3], alloc_);

	}

	CoverFilter(const CoverFilter&) = delete;

	CoverFilter& operator=(const CoverFilter&) = delete;

};

// ShmemFile is shared memory region wrapper.

class ShmemFile

{

public:

	// Maps shared memory region of size 'size' from a new temp file.

	// 创建一个 “匿名的、可继承 / 可传 fd 的共享内存对象”，兼容性强。

	ShmemFile(size_t size)

	{

		// 创建一个唯一的临时文件并打开

		char file_name[] = "syz.XXXXXX";

		fd_ = mkstemp(file_name); //file_name 会被 mkstemp 改成实际文件名

		if (fd_ == -1)

			failmsg("shmem open failed", "file=%s", file_name);

		// OpenBSD has neither fallocate nor posix_fallocate.

		// 用 ftruncate 把文件扩展到 size，作为共享内存的 backing store。

		if (ftruncate(fd_, size))

			failmsg("shmem ftruncate failed", "size=%zu", size);

		// 映射这段文件到内存

		Mmap(fd_, nullptr, size, true);

		// 马上 unlink 掉文件名， 这样的好处是：

		// 1. 不在文件系统留下垃圾文件

		// 2. 生命周期由进程控制，进程结束后内核自动回收

		if (unlink(file_name))

			fail("shmem unlink failed");

	}

	// Maps shared memory region from the file 'fd' in read/write or write-only mode,

	// preferably at the address 'preferred'.

	// 从已有 fd 直接映射共享区（attach 模式）

	ShmemFile(int fd, void* preferred, size_t size, bool write)

	{

		Mmap(fd, preferred, size, write);

	}

	~ShmemFile()

	{

		if (munmap(mem_, size_))

			fail("shmem munmap failed");

		if (fd_ != -1)

			close(fd_);

	}

	// Prevents any future modifications to the region.

	// 把共享区变成只读，并且关闭 fd

	void Seal()

	{

		if (mprotect(mem_, size_, PROT_READ))

			fail("shmem mprotect failed");

		if (fd_ != -1)

			close(fd_);

		fd_ = -1;

	}

	int FD() const

	{

		return fd_;

	}

	void* Mem() const

	{

		return mem_;

	}

private:

	void* mem_ = nullptr;

	size_t size_ = 0;

	int fd_ = -1;

	void Mmap(int fd, void* preferred, size_t size, bool write)

	{

		size_ = size;

		// MAP_SHARED：多个进程映射同一个 fd 时，看到的是同一份物理页（可共享修改）

		mem_ = mmap(preferred, size, PROT_READ | (write ? PROT_WRITE : 0), MAP_SHARED, fd, 0);

		if (mem_ == MAP_FAILED)

			failmsg("shmem mmap failed", "size=%zu", size);

	}

	ShmemFile(const ShmemFile&) = delete;

	ShmemFile& operator=(const ShmemFile&) = delete;

};

void Loop()

	{

		Select select;

		// 监听与 Manager 的 TCP 连接

		select.Arm(conn_.FD());

		for (auto& proc : procs_)

			// 监听每个子进程的响应管道和输出管道

			proc->Arm(select);

		// Wait for ready host connection and subprocess pipes.

		// Timeout is for terminating hanged subprocesses.

		select.Wait(1000); // 等待最多 1000ms（1 秒）

		uint64 now = current_time_ms();

		// TCP socket 有数据可读 (manager 发来了新的请求)

		if (select.Ready(conn_.FD())) {

			rpc::HostMessageRawT raw;

			// 从 socket 读取消息（阻塞直到完整消息到达）

			conn_.Recv(raw);

			if (auto* msg = raw.msg.AsExecRequest())

				Handle(*msg); // 执行请求

			else if (auto* msg = raw.msg.AsSignalUpdate())

				Handle(*msg); // 信号更新（覆盖率过滤器）

			else if (auto* msg = raw.msg.AsCorpusTriaged())

				Handle(*msg); // 语料库分类完成

			else if (auto* msg = raw.msg.AsStateRequest())

				Handle(*msg); // 状态查询请求

			else

				failmsg("unknown host message type", "type=%d", static_cast<int>(raw.msg.type));

		}

		// 处理子进程的事件

		for (auto& proc : procs_) {

			// 检查子进程状态（是否完成、是否超时、是否有输出），如果之前子进程刚创建等待握手，

			// 则这里会检查握手是否完成，并把之前因为握手耽误的任务继续下发执行。

			proc->Ready(select, now, requests_.empty());

			// 如果有待执行的请求且子进程空闲，分配任务

			if (!requests_.empty()) {

				if (proc->Execute(requests_.front()))

					requests_.pop_front();

			}

		}

		// 健全性检查

		if (restarting_ < 0 || restarting_ > static_cast<int>(procs_.size()))

			failmsg("bad restarting", "restarting=%d", restarting_);

	}

class Select

{

public:

	Select()

	{

		FD_ZERO(&rdset_);

	}

	// 告诉 Select “我关心这个 fd”

	// 每一轮 wait 前，都会重新构造一个 Select 来监听需要关注的 fd

	void Arm(int fd)

	{

		FD_SET(fd, &rdset_);

		max_fd_ = std::max(max_fd_, fd);

	}

	// 事后检查 “是哪个 fd 触发了”

	bool Ready(int fd) const

	{

		//rdset_ 会被内核修改，只保留 “已经就绪” 的 fd

		return FD_ISSET(fd, &rdset_);

	}

	// 阻塞当前线程，直到有 fd 可读或超时或中断

	void Wait(int ms)

	{

		timespec timeout = {.tv_sec = ms / 1000, .tv_nsec = (ms % 1000) * 1000 * 1000};

		for (;;) {

			if (pselect(max_fd_ + 1, &rdset_, nullptr, nullptr, &timeout, nullptr) >= 0)

				break;

			if (errno != EINTR && errno != EAGAIN)

				fail("pselect failed");

		}

	}

	// 把 fd 设成非阻塞（O_NONBLOCK），防止 read/write 卡住

	static void Prepare(int fd)

	{

		if (fcntl(fd, F_SETFL, fcntl(fd, F_GETFL, 0) | O_NONBLOCK))

			fail("fcntl(O_NONBLOCK) failed");

	}

private:

	fd_set rdset_; // 当前要监听的 “可读 fd 集合”

	int max_fd_ = -1;

	Select(const Select&) = delete;

	Select& operator=(const Select&) = delete;

};

void Handle(rpc::ExecRequestRawT& msg)

	{

		debug("recv exec request %llu: type=%llu flags=0x%llx env=0x%llx exec=0x%llx size=%zu\n",

		      static_cast<uint64>(msg.id),

		      static_cast<uint64>(msg.type),

		      static_cast<uint64>(msg.flags),

		      static_cast<uint64>(msg.exec_opts->env_flags()),

		      static_cast<uint64>(msg.exec_opts->exec_flags()),

		      msg.data.size());

		// 处理二进制执行请求

		if (msg.type == rpc::RequestType::Binary) {

			ExecuteBinary(msg);

			return;

		}

		// 尝试将执行任务下发到子进程，轮询直到找到空闲子进程

		for (auto& proc : procs_) {

			if (proc->Execute(msg))

				return;

		}

		// 所有子进程都忙，加入队列

		requests_.push_back(std::move(msg));

	}

void ExecuteBinary(rpc::ExecRequestRawT& msg)

	{

		rpc::ExecutingMessageRawT exec;

		// 设置 id，通知 manager 这个请求开始执行

		exec.id = msg.id;

		rpc::ExecutorMessageRawT raw;

		raw.msg.Set(std::move(exec));

		// 立即通知 manager, 这个请求已经开始执行。

		conn_.Send(raw);

		// 创建临时工作目录，并放宽权限

		char dir_template[] = "syz-bin-dirXXXXXX";

		char* dir = mkdtemp(dir_template);

		if (dir == nullptr)

			fail("mkdtemp failed");

		if (chmod(dir, 0777))

			fail("chmod failed");

		// 实际执行二进制文件，获取错误信息和输出

		auto [err, output] = ExecuteBinaryImpl(msg, dir);

		// 如果 err 非空，把 errno 信息附加到 err 后面

		if (!err.empty()) {

			char tmp[64];

			snprintf(tmp, sizeof(tmp), " (errno %d: %s)", errno, strerror(errno));

			err += tmp;

		}

		// 无论成功与否，删除临时目录

		remove_dir(dir);

		// 发送执行结果给 manager

		rpc::ExecResultRawT res;

		res.id = msg.id;

		res.error = std::move(err);

		res.output = std::move(output);

		raw.msg.Set(std::move(res));

		conn_.Send(raw);

	}

std::tuple<std::string, std::vector<uint8_t>> ExecuteBinaryImpl(rpc::ExecRequestRawT& msg, const char* dir)

	{

		// For simplicity we just wait for binary tests to complete blocking everything else.

		// 把 msg.data 写成一个可执行文件 dir/syz-executor

		std::string file = std::string(dir) + "/syz-executor";

		int fd = open(file.c_str(), O_WRONLY | O_CLOEXEC | O_CREAT, 0755);

		if (fd == -1)

			return {"binary file creation failed", {}};

		ssize_t wrote = write(fd, msg.data.data(), msg.data.size());

		close(fd);

		if (wrote != static_cast<ssize_t>(msg.data.size()))

			return {"binary file write failed", {}};

		// 创建管道，用于子进程的 stdin/stdout/stderr 重定向

		int stdin_pipe[2];

		if (pipe(stdin_pipe))

			fail("pipe failed");

		int stdout_pipe[2];

		if (pipe(stdout_pipe))

			fail("pipe failed");

		// 配置子进程参数和文件描述符重定向

		const char* argv[] = {file.c_str(), nullptr};

		std::vector<std::pair<int, int>> fds = {

		    {stdin_pipe[0], STDIN_FILENO},

		    {stdout_pipe[1], STDOUT_FILENO},

		    {stdout_pipe[1], STDERR_FILENO},

		};

		// 创建子进程并执行

		Subprocess process(argv, fds);

		// 关闭不需要的端

		close(stdin_pipe[0]);

		close(stdout_pipe[1]);

		// 最多给 5x program timeout 时间让子进程跑完，未完就杀掉

		int status = process.WaitAndKill(5 * program_timeout_ms_);

		// 读取子进程的全部输出（按 1024 字节块读）

		std::vector<uint8_t> output;

		for (;;) {

			const size_t kChunk = 1024;

			output.resize(output.size() + kChunk);

			ssize_t n = read(stdout_pipe[0], output.data() + output.size() - kChunk, kChunk);

			output.resize(output.size() - kChunk + std::max<ssize_t>(n, 0));

			if (n <= 0)

				break;

		}

		close(stdin_pipe[1]);

		close(stdout_pipe[0]);

		return {status == kFailStatus ? "process failed" : "", std::move(output)};

	}

};

bool Execute(rpc::ExecRequestRawT& msg)

	{

		// 检查状态：只有 Started 或 Idle 状态才能接受新请求

		if (state_ != State::Started && state_ != State::Idle)

			return false;

		// 检查 proc ID 过滤，确保请求允许使用当前 proc ID

		if (((~msg.avoid) & proc_id_pool_.Mask()) == 0)

			msg.avoid = 0;

		if (msg.avoid & (1ull << id_))

			return false; // 请求要避开这个 proc ID

		// 检查是否已有待处理的消息

		if (msg_)

			fail("already have pending msg");

		// 记录等待时间

		if (wait_start_)

			wait_end_ = current_time_ms();

		// Restart every once in a while to not let too much state accumulate.

		// Also request if request type differs as it affects program timeout.

		// 决定是否需要重启进程

		constexpr uint64 kRestartEvery = 600;

		if (state_ == State::Idle && ((corpus_triaged_ && restarting_ == 0 && freshness_ >= kRestartEvery) ||

					      req_type_ != msg.type ||

					      exec_env_ != msg.exec_opts->env_flags() || sandbox_arg_ != msg.exec_opts->sandbox_arg()))

			Restart(); // 定期重启或环境变化时重启

		// 保存请求并开始处理

		attempts_ = 0;

		msg_ = std::move(msg); // 接管请求的所有权

		if (state_ == State::Started)

			Handshake(); // 新启动的进程先握手

		else

			Execute(); // 空闲进程直接执行

		return true; // 成功接受请求

	}

void Restart()

	{

		debug("proc %d: restarting subprocess, current state %u attempts %llu\n", id_, state_, attempts_);

		// 杀掉当前子进程并回收

		int status = process_->KillAndWait();

		// 释放 Subprocess 对象（RAII），确保 fd / 资源不再持有

		process_.reset();

		debug("proc %d: subprocess exit status %d\n", id_, status);

		// 重启超过 20 次就视为不可恢复，收集输出并 fail

		if (++attempts_ > 20) {

			// 把子进程的 stdout/stderr pipe 里剩余内容尽量读干净，写入 output_

			while (ReadOutput());

			// 把 output_ 直接写到 STDERR_FILENO（父进程 stderr）

			// 如果子进程输出里包含自己的 SYFAIL（executor 内部的失败标记），

			// 希望它出现在我们最终 SYZFAIL 之前，便于诊断 “到底先发生了什么”

			ssize_t wrote = write(STDERR_FILENO, output_.data(), output_.size());

			if (wrote != static_cast<ssize_t>(output_.size()))

				fprintf(stderr, "output truncated: %zd/%zd (errno=%d)\n",

					wrote, output_.size(), errno);

			// 输出失败信息并终止，不能无限重试掩盖系统性错误

			uint64 req_id = msg_ ? msg_->id : -1;

			failmsg("repeatedly failed to execute the program", "proc=%d req=%lld state=%d status=%d",

				id_, req_id, state_, status);

		}

		// Ignore all other errors.

		// Without fork server executor can legitimately exit (program contains exit_group),

		// with fork server the top process can exit with kFailStatus if it wants special handling.

		// 其它错误都忽略，只把 kFailStatus 当成需要特殊处理的状态

		if (status != kFailStatus)

			status = 0;

		// 决定是否 “失败当前请求”，并在需要时做收尾与上报

		if (FailCurrentRequest(status == kFailStatus)) {

			// Read out all pening output until EOF.

			// 如果请求要求返回输出，则把输出读到底

			if (IsSet(msg_->flags, rpc::RequestFlag::ReturnOutput)) {

				while (ReadOutput())

					;

			}

			// 判断是否 hanged，并上报完成

			bool hanged = SYZ_EXECUTOR_USES_FORK_SERVER && state_ == State::Executing;

			HandleCompletion(status, hanged);

			if (hanged) {

				// If the process has hanged, it may still be using per-proc resources,

				// so allocate a fresh proc id.

				// 如果 hang，重新分配一个新的 proc id

				// 因为 hang 的进程可能还在使用一些与 proc id 相关的资源被占用，使用新 id 避免冲突

				int new_id = proc_id_pool_.Alloc(id_);

				debug("proc %d: changing proc id to %d\n", id_, new_id);

				id_ = new_id;

			}

		} else if (attempts_ > 3) // 如果不需要失败当前请求，短暂睡眠，避免疯狂重启打爆系统

			sleep_ms(100 * attempts_);

		Start(); // 启动一个新的子进程

	}

void Handshake()

	{

		// 必须是 Started 状态且有消息

		if (state_ != State::Started || !msg_)

			fail("wrong handshake state");

		debug("proc %d: handshaking to execute request %llu\n", id_, static_cast<uint64>(msg_->id));

		// 切换状态

		ChangeState(State::Handshaking);

		// 记录开始时间

		exec_start_ = current_time_ms();

		// 缓存本次请求的关键字段

		req_type_ = msg_->type;

		exec_env_ = msg_->exec_opts->env_flags() & ~rpc::ExecEnv::ResetState; // 把 ResetState 位清掉

		sandbox_arg_ = msg_->exec_opts->sandbox_arg();

		// 把执行配置发给 exec 子进程

		handshake_req req = {

		    .magic = kInMagic,

		    .use_cover_edges = use_cover_edges_,

		    .is_kernel_64_bit = is_kernel_64_bit_,

		    .flags = exec_env_,

		    .pid = static_cast<uint64>(id_),

		    .sandbox_arg = static_cast<uint64>(sandbox_arg_),

		    .syscall_timeout_ms = syscall_timeout_ms_,

		    .program_timeout_ms = ProgramTimeoutMs(),

		    .slowdown_scale = slowdown_,

		};

		// 通过 req_pipe_（子进程 stdin）写入握手包；失败就重启

		// 子进程不可控，通信出错就重启恢复，而不是试图修补半坏状态。

		if (write(req_pipe_, &req, sizeof(req)) != sizeof(req)) {

			debug("request pipe write failed (errno=%d)\n", errno);

			Restart();

		}

	}

void Execute()

	{

		// 只能在 Idle 且已有 msg_ 时执行

		if (state_ != State::Idle || !msg_)

			fail("wrong state for execute");

		debug("proc %d: start executing request %llu\n", id_, static_cast<uint64>(msg_->id));

		// 封装执行消息

		rpc::ExecutingMessageRawT exec;

		exec.id = msg_->id;

		exec.proc_id = id_;

		exec.try_ = attempts_; // 重试次数

		// 如果有等待时间统计，则填充 wait_duration 字段

		if (wait_start_) {

			exec.wait_duration = (wait_end_ - wait_start_) * 1000 * 1000;

			wait_end_ = wait_start_ = 0;

		}

		rpc::ExecutorMessageRawT raw;

		raw.msg.Set(std::move(exec));

		conn_.Send(raw); // 通知 Manager："我开始执行请求 XXX 了"

		//all_call_signal 是 64-bit 位图：第 i 位 = 1 表示要收集第 i 个 syscall 的 signal

		uint64 all_call_signal = 0;

		//all_extra_signal 用于控制要不要从 extra 里过滤已有的 signal

		// 为假时会把 “max_signal 里已经有的 signal” 过滤掉，extra 里只剩 “新 signal”。

		// 为真时则不过滤，extra 里包含所有 signal。

		//extra signal 是指 “非 syscall 产生的 signal”，比如背景任务、内核线程等产生的 signal。

		bool all_extra_signal = false;

		// 解析 msg_->all_signal：决定 “要哪些 syscall 的 signal”

		for (int32_t call : msg_->all_signal) {

			// 确保 “call index 可以用 uint64 位图表达” 这个假设成立。

			static_assert(kMaxCalls == 64);

			if (call < -1 || call >= static_cast<int32_t>(kMaxCalls))

				failmsg("bad all_signal call", "call=%d", call);

			if (call < 0)

				all_extra_signal = true;

			else

				all_call_signal |= 1ull << call; // 设置位标志

		}

		// 将 program 数据写入共享内存

		memcpy(req_shmem_.Mem(), msg_->data.data(), std::min(msg_->data.size(), kMaxInput));

		// 构造执行请求结构体

		execute_req req{

		    .magic = kInMagic,

		    .id = static_cast<uint64>(msg_->id),

		    .type = msg_->type,

		    .exec_flags = static_cast<uint64>(msg_->exec_opts->exec_flags()),

		    .all_call_signal = all_call_signal,

		    .all_extra_signal = all_extra_signal,

		};

		// 记录开始时间，切换状态

		exec_start_ = current_time_ms();

		ChangeState(State::Executing);

		// 通过管道发送执行命令给子进程，失败就重启	

		if (write(req_pipe_, &req, sizeof(req)) != sizeof(req)) {

			debug("request pipe write failed (errno=%d)\n", errno);

			Restart();

		}

	}

void Handle(const rpc::SignalUpdateRawT& msg)

	{

		// Manager 发现了新的覆盖率，添加到本地的 “所有信号” 集合中

		debug("recv signal update: new=%zu\n", msg.new_max.size());

		if (!max_signal_)

			fail("signal update when no signal filter installed");

		for (auto pc : msg.new_max)

			max_signal_->Insert(pc);

	}

void Handle(const rpc::CorpusTriagedRawT& msg)

	{

		// TODO: repair leak checking (#4728).

		// Manager 通知语料库分类完成，会影响是否要 restart 子进程

		debug("recv corpus triaged\n");

		corpus_triaged_ = true;

	}

void Handle(const rpc::StateRequestRawT& msg)

	{

		// Debug request about our internal state.

		// Manager 想知道 runner 的内部状态（调试用）

		std::ostringstream ss;

		ss << *this; // 输出 Runner 和所有 Proc 的状态

		const std::string& str = ss.str();

		rpc::StateResultRawT res;

		res.data.insert(res.data.begin(), str.data(), str.data() + str.size());

		rpc::ExecutorMessageRawT raw;

		raw.msg.Set(std::move(res));

		conn_.Send(raw); // 通过 RPC 发回 Manager

	}

int main(int argc, char** argv)

{

	if (argc == 1) {

		fprintf(stderr, "no command");

		return 1;

	}

	if (strcmp(argv[1], "runner") == 0) {

		runner(argv, argc); // 控制端入口，不应该返回

		fail("runner returned");

	}

	if (strcmp(argv[1], "leak") == 0) {

#if SYZ_HAVE_LEAK_CHECK

		check_leaks(argv + 2, argc - 2);

#else

		fail("leak checking is not implemented");

#endif

		return 0;

	}

	if (strcmp(argv[1], "test") == 0)

		return run_tests(argc == 3 ? argv[2] : nullptr);

	// 真正执行 fuzz program 的子进程入口，由 Proc::start () 启动

	if (strcmp(argv[1], "exec") != 0) {

		fprintf(stderr, "unknown command");

		return 1;

	}

	// 记录启动时间

	start_time_ms = current_time_ms();

	// OS / 环境初始化，提高复现一致性

	os_init(argc, argv, (char*)SYZ_DATA_OFFSET, SYZ_NUM_PAGES * SYZ_PAGE_SIZE);

	// 把工作目录切到临时目录

	use_temporary_dir();

	// 安装段错误处理函数，

	install_segv_handler();

	// init_mount_image_config();

	//executor 内部有自己的 “线程 /worker” 结构体数组

	current_thread = &threads[0];

	//snapshot 模式

	if (argc > 2 && strcmp(argv[2], "snapshot") == 0) {

		SnapshotSetup(argv, argc);

	} else {

		// 常规模式

		// 从指定的 fd 映射共享内存区域，用于接收输入，此时 runner 已经启动并 dup 好这些 fd 了

		// 大数据 (program) 走共享内存传输，小数据 (结构化命令) 走 pipe 传输

		void* mmap_out = mmap(NULL, kMaxInput, PROT_READ, MAP_SHARED, kInFd, 0);

		if (mmap_out == MAP_FAILED)

			fail("mmap of input file failed");

		//input_data 指向共享内存区域

		input_data = static_cast<uint8*>(mmap_out);

		// 映射输出区域，用于存放执行结果

		mmap_output(kInitialOutput);

		// Prevent test programs to mess with these fds.

		// Due to races in collider mode, a program can e.g. ftruncate one of these fds,

		// which will cause fuzzer to crash.

		// 防 fuzz 过程中篡改 executor 通道 (可能会有 close ()/dup2 () 等 syscall 把 fd 搞坏)

		close(kInFd);

#if !SYZ_EXECUTOR_USES_FORK_SERVER

		// For SYZ_EXECUTOR_USES_FORK_SERVER, close(kOutFd) is invoked in the forked child,

		// after the program has been received.

		close(kOutFd);

#endif

		// 如果 runner 提供了信号相关的 fd，则 mmap 它们并关闭原 fd

		if (fcntl(kMaxSignalFd, F_GETFD) != -1) { // 如果 fd 没传进来会 EBADF

			// Use random addresses for coverage filters to not collide with output_data.

			max_signal.emplace(kMaxSignalFd, reinterpret_cast<void*>(0x110c230000ull));

			close(kMaxSignalFd);

		}

		if (fcntl(kCoverFilterFd, F_GETFD) != -1) {

			cover_filter.emplace(kCoverFilterFd, reinterpret_cast<void*>(0x110f230000ull));

			close(kCoverFilterFd);

		}

		// 设置 runner 和 executor 的之间的控制管道

		setup_control_pipes();

		// 接收并解析 runner 的握手请求，进行初始化设置

		receive_handshake();

#if !SYZ_EXECUTOR_USES_FORK_SERVER

		// We receive/reply handshake when fork server is disabled just to simplify runner logic.

		// It's a bit suboptimal, but no fork server is much slower anyway.

		// 非 fork server 模式下：简化 runner 逻辑，先回握手再收 execute 信息并解析

		reply_execute(0);

		receive_execute();

#endif

	}

	// 覆盖率初始化（kcov）：按线程开、部分预 mmap

	if (flag_coverage) {

		int create_count = kCoverDefaultCount, mmap_count = create_count;

		if (flag_delay_kcov_mmap) {

			create_count = kCoverOptimizedCount;

			mmap_count = kCoverOptimizedPreMmap;

		}

		if (create_count > kMaxThreads)

			create_count = kMaxThreads;

		for (int i = 0; i < create_count; i++) {

			//per-thread 的覆盖收集

			threads[i].cov.fd = kCoverFd + i;

			cover_open(&threads[i].cov, false);

			if (i < mmap_count) {

				// Pre-mmap coverage collection for some threads. This should be enough for almost

				// all programs, for the remaning few ones coverage will be set up when it's needed.

				thread_mmap_cover(&threads[i]);

			}

		}

		// 额外的覆盖源

		extra_cov.fd = kExtraCoverFd;

		cover_open(&extra_cov, true);

		cover_mmap(&extra_cov);

		cover_protect(&extra_cov);

		if (flag_extra_coverage) {

			// Don't enable comps because we don't use them in the fuzzer yet.

			cover_enable(&extra_cov, false, true);

		}

	}

	// 选择 sandbox 执行主循环

	int status = 0;

	if (flag_sandbox_none)

		status = do_sandbox_none();

#if SYZ_HAVE_SANDBOX_SETUID

	else if (flag_sandbox_setuid)

		status = do_sandbox_setuid();

#endif

#if SYZ_HAVE_SANDBOX_NAMESPACE

	else if (flag_sandbox_namespace)

		status = do_sandbox_namespace();

#endif

#if SYZ_HAVE_SANDBOX_ANDROID

	else if (flag_sandbox_android)

		status = do_sandbox_android(sandbox_arg);

#endif

	else

		fail("unknown sandbox type");

	// 下面的代码在正常执行流程中是不可达的

#if SYZ_EXECUTOR_USES_FORK_SERVER

	fprintf(stderr, "loop exited with status %d\n", status);

	// If an external sandbox process wraps executor, the out pipe will be closed

	// before the sandbox process exits this will make ipc package kill the sandbox.

	// As the result sandbox process will exit with exit status 9 instead of the executor

	// exit status (notably kFailStatus). So we duplicate the exit status on the pipe.

	//fork server 模式下，退出前把状态发给 runner

	reply_execute(status);

	doexit(status);

	// Unreachable.

	return 1;

#else

	// 非 fork server 模式下，直接把执行结果通过管道发给 runner

	reply_execute(status);

	return status;

#endif

}

static void mmap_output(uint32 size)

{

	// 如果不需要扩容就直接返回，output_size 表示当前已经映射的输出区大小

	if (size <= output_size)

		return;

	// 必须按页对齐

	if (size % SYZ_PAGE_SIZE != 0)

		failmsg("trying to mmap output area that is not divisible by page size", "page=%d,area=%d", SYZ_PAGE_SIZE, size);

	uint32* mmap_at = NULL;

	// 第一次映射输出缓冲区

	if (output_data == NULL) {

		if (kAddressSanitizer) {

			// ASan allows user mappings only at some specific address ranges,

			// so we don't randomize. But we also assume 64-bits and that we are running tests.

			// 如果开了 ASan，则映射到一个固定地址（因为 ASan 只允许在特定地址映射用户内存）

			mmap_at = (uint32*)0x7f0000000000ull;

		} else {

			// It's the first time we map output region - generate its location.

			// The output region is the only thing in executor process for which consistency matters.

			// If it is corrupted ipc package will fail to parse its contents and panic.

			// But fuzzer constantly invents new ways of how to corrupt the region,

			// so we map the region at a (hopefully) hard to guess address with random offset,

			// surrounded by unmapped pages.

			// The address chosen must also work on 32-bit kernels with 1GB user address space.

			// 非 ASan 下挑 “难猜” 的地址来映射输出缓冲区，避免被 Fuzzer 猜到地址后篡改

			const uint64 kOutputBase = 0x1b2bc20000ull;

			mmap_at = (uint32*)(kOutputBase + (1 << 20) * (getpid() % 128));

		}

	} else {

		// We are expanding the mmapped region. Adjust the parameters to avoid mmapping already

		// mmapped area as much as possible.

		// There exists a mremap call that could have helped, but it's purely Linux-specific.

		// 扩容时，把新区域接在旧区域后面

		mmap_at = (uint32*)((char*)(output_data) + output_size);

	}

	// 只映射 “新增部分”，且用 MAP_FIXED 强制指定地址

	void* result = mmap(mmap_at, size - output_size,

			    PROT_READ | PROT_WRITE, MAP_SHARED | MAP_FIXED, kOutFd, output_size);

	if (result == MAP_FAILED || (mmap_at && result != mmap_at))

		failmsg("mmap of output file failed", "want %p, got %p", mmap_at, result);

	// 第一次映射时设置 output_data 指针到共享输出区

	if (output_data == NULL)

		output_data = static_cast<OutputData*>(result);

	// 更新 output_size 为新大小

	output_size = size;

}

void setup_control_pipes()

{

	// 在启动子进程时，Proc 将 req_pipe [0] 绑定到了 STDIN_FILENO

	// 这里把 STDIN_FILENO 复制到 kInPipeFd，也即 kInPipeFd 现在也是 req_pipe [0]

	// 所以 kInPipeFd 就是 runner 发命令给 executor 的管道读端，executor 从中读取命令

	// 同理 kOutPipeFd 是 executor 发结果给 runner 的管道写端，runner 从中读取结果

	if (dup2(0, kInPipeFd) < 0)

		fail("dup2(0, kInPipeFd) failed");

	if (dup2(1, kOutPipeFd) < 0)

		fail("dup2(1, kOutPipeFd) failed");

	if (dup2(2, 1) < 0)

		fail("dup2(2, 1) failed");

	// We used to close(0), but now we dup stderr to stdin to keep fd numbers

	// stable across executor and C programs generated by pkg/csource.

	if (dup2(2, 0) < 0)

		fail("dup2(2, 0) failed");

}

void receive_handshake()

{

	handshake_req req = {};

	// 从 kInPipeFd 读取握手请求

	ssize_t n = read(kInPipeFd, &req, sizeof(req));

	if (n != sizeof(req))

		failmsg("handshake read failed", "read=%zu", n);

	// 解析握手请求，根据请求内容进行初始化设置

	parse_handshake(req);

}

void parse_handshake(const handshake_req& req)

{

	if (req.magic != kInMagic)

		failmsg("bad handshake magic", "magic=0x%llx", req.magic);

#if SYZ_HAVE_SANDBOX_ANDROID

	sandbox_arg = req.sandbox_arg;

#endif

	is_kernel_64_bit = req.is_kernel_64_bit;

	use_cover_edges = req.use_cover_edges;

	procid = req.pid;

	syscall_timeout_ms = req.syscall_timeout_ms;

	program_timeout_ms = req.program_timeout_ms;

	slowdown_scale = req.slowdown_scale;

	flag_debug = (bool)(req.flags & rpc::ExecEnv::Debug);

	flag_coverage = (bool)(req.flags & rpc::ExecEnv::Signal);

	flag_sandbox_none = (bool)(req.flags & rpc::ExecEnv::SandboxNone);

	flag_sandbox_setuid = (bool)(req.flags & rpc::ExecEnv::SandboxSetuid);

	flag_sandbox_namespace = (bool)(req.flags & rpc::ExecEnv::SandboxNamespace);

	flag_sandbox_android = (bool)(req.flags & rpc::ExecEnv::SandboxAndroid);

	flag_extra_coverage = (bool)(req.flags & rpc::ExecEnv::ExtraCover);

	flag_net_injection = (bool)(req.flags & rpc::ExecEnv::EnableTun);

	flag_net_devices = (bool)(req.flags & rpc::ExecEnv::EnableNetDev);

	flag_net_reset = (bool)(req.flags & rpc::ExecEnv::EnableNetReset);

	flag_cgroups = (bool)(req.flags & rpc::ExecEnv::EnableCgroups);

	flag_close_fds = (bool)(req.flags & rpc::ExecEnv::EnableCloseFds);

	flag_devlink_pci = (bool)(req.flags & rpc::ExecEnv::EnableDevlinkPCI);

	flag_vhci_injection = (bool)(req.flags & rpc::ExecEnv::EnableVhciInjection);

	flag_wifi = (bool)(req.flags & rpc::ExecEnv::EnableWifi);

	flag_delay_kcov_mmap = (bool)(req.flags & rpc::ExecEnv::DelayKcovMmap);

	flag_nic_vf = (bool)(req.flags & rpc::ExecEnv::EnableNicVF);

}

static int do_sandbox_none(void)

{

	// CLONE_NEWPID takes effect for the first child of the current process,

	// so we do it before fork to make the loop "init" process of the namespace.

	// We ought to do fail here, but sandbox=none is used in pkg/ipc tests

	// and they are usually run under non-root.

	// Also since debug is stripped by pkg/csource, we need to do {}

	// even though we generally don't do {} around single statements.

	// PID 隔离，让 loop 进程成为新 PID 命名空间的 init 进程

  if (unshare(CLONE_NEWPID)) {

		debug("unshare(CLONE_NEWPID): %d\n", errno);

	}

	int pid = fork();

	if (pid != 0)

    // 父进程

		return wait_for_loop(pid);

#if SYZ_EXECUTOR || SYZ_VHCI_INJECTION

  //vhci 初始化

	initialize_vhci();

#endif

  // 通用 sandbox 初始化

	sandbox_common();

  // 丢弃 Linux capabilities，降低权限，减少 “fuzzer 以特权搞乱系统” 的情况

	drop_caps();

#if SYZ_EXECUTOR || SYZ_NET_DEVICES

  // 网络设备相关的早期初始化

	initialize_netdevices_init();

#endif

  // 创建网络命名空间

	if (unshare(CLONE_NEWNET)) {

		debug("unshare(CLONE_NEWNET): %d\n", errno);

	}

	// Enable access to IPPROTO_ICMP sockets, must be done after CLONE_NEWNET.

  // 让 fuzz 程序能测试 ICMP 相关路径，而不会因权限卡死

	write_file("/proc/sys/net/ipv4/ping_group_range", "0 65535");

#if SYZ_EXECUTOR || SYZ_DEVLINK_PCI

  // PCI 设备相关的早期初始化

	initialize_devlink_pci();

#endif

#if SYZ_EXECUTOR || SYZ_NET_INJECTION

  // TUN/TAP 设备相关的早期初始化

	initialize_tun();