Merge pull request #15038 from xXPBSXx/docs-kernel-waiteventflag-args

docs(debt): say that sceKernelWaitEventFlag fails a zero pattern and a bad wait mode

docs/dev/debt/libkernel.md

@@ -90,6 +90,7 @@
 - [scePthreadRwlockDestroy, pthread_rwlock_destroy](../../../core/libs/prx/libkernel/Pthread/src/Rwlock.cpp) (libkernel) - measured on a PS5 (firmware 13.60): destroying a rwlock returns 0 whether it is free or held for reading or writing, and leaves 1 in the handle; every call on that handle then returns `EINVAL` until it is initialized again, and a zero handle is initialized on first use by the `scePthreadRwlock` calls as by the POSIX ones. A rwlock destroyed while held is not freed, so its memory leaks. Destroying a rwlock while another thread is acquiring it is not guarded
 - [scePthreadCondWait / scePthreadCondTimedwait](../../../core/libs/prx/libkernel/Pthread/src/Cond.cpp) (libkernel) - the mutex's owner is checked before waiting, as in FreeBSD libthr's [`cond_wait_common`](https://github.com/freebsd/freebsd-src/blob/main/lib/libthr/thread/thr_cond.c#L1992-L2029). Measured in a payload process on a PS5 (firmware 13.60): `EPERM` (`0x80020001`) for an unowned mutex of every type, the adaptive initializer (slot 1), an uninitialized slot and a mutex owned by another thread, `EINVAL` for the destroyed mutex (slot 2), and a recursive mutex is released completely and relocked to its depth. `scePthreadCondDestroy` stores 1, which every condition call refuses with `EINVAL`, and leaves an uninitialized slot alone. Cancellation restores the mutex and depth before cleanup and a canceled waiter forwards a wake, per POSIX; its ordering is not measured
 - [sceKernelOpenEventFlag](../../../core/libs/prx/libkernel/EventFlag/src/EventFlag.cpp) (libkernel) - opens only flags this process created with attribute 0x100. On the console, other processes' 0x100 flags, such as the shell's `SceShellCoreUtilAppFocus`, can be opened too. They do not exist here, so opening them returns `SCE_KERNEL_ERROR_ESRCH`. A null output with the name of an openable flag returns `SCE_KERNEL_ERROR_EFAULT`, the host's answer to the console's fault there, not a measured code. With a plain flag's name it returns `SCE_KERNEL_ERROR_ESRCH`, as measured; with a missing name, or a null output and a missing name, it returns `SCE_KERNEL_ERROR_ESRCH`, as a payload process on PS5 firmware 13.60 got.
+- [sceKernelWaitEventFlag](../../../core/libs/prx/libkernel/EventFlag/src/EventFlag.cpp) (libkernel) - once the event flag is resolved, a zero bit pattern, a wait mode without exactly one of AND (0x1) and OR (0x2), or one with both clear flags (0x10 and 0x20) returns `EINVAL`, as `sceKernelPollEventFlag` does; the console's answers for them are not measured. fpPS4 (PS4, commit 04cefd43e6fddd1ab033e7980cd356d14c964905), shadPS4 (PS4, commit 0614ce324be092791b758d79f93d9f1ca5b10a81) and KytyPS5 (PS5, commit 5e837a9beac82c031868eaad9348d6a48245fb99) return `EINVAL` for a zero pattern; for a wait mode without exactly one of AND and OR fpPS4 returns it too, while shadPS4 and KytyPS5 stop. Every direct call in the titles checked with a constant bit pattern passes a non-zero one and every call with a constant wait mode passes a valid one, so none reaches the check; calls not shown to be constants and the tail jumps are not known.
 - [sceKernelCreateEventFlag](../../../core/libs/prx/libkernel/EventFlag/src/EventFlag.cpp) (libkernel) - event flag handles are host addresses here, while the console returns small IDs (0x22 for the first in a payload process on PS5 firmware 13.60). That console checks the attribute before the name length, as here: attributes 0x3, 0x30, 0x40 and 0x200 return `SCE_KERNEL_ERROR_EINVAL` with a 32-byte name too, and attributes 0 and 0x100 return `SCE_KERNEL_ERROR_ENAMETOOLONG` with it. Of 114 call sites read in 12 titles (PPSA02530 not included), single sites pass the attribute 0x10 (PPSA24779 0x943887) and 0x22 (PPSA30601 0x16157f1), and 0x21 in PPSA04354 (0xee7dc7) and PPSA35169 (0x5a539e), all with the initial value 0; how the attributes are distributed over the other sites is not shown.
 - [sceKernelAioSubmitReadCommandsMultiple / sceKernelAioSubmitWriteCommandsMultiple / sceKernelAioWaitRequests / sceKernelAioPollRequests / sceKernelAioCancelRequest / sceKernelAioCancelRequests / sceKernelAioDeleteRequests](../../../core/libs/prx/libkernel/Aio/src/Aio.cpp) (libkernel) - one id per request for the Multiple submits and wait mode 2 returning once one request completed follow shadPS4. Requests run synchronously on submit, so cancel never finds one processing. The console's ids are not the small numbers used here (it returned 33, 0x2021, 0x4021)
 - [sceKernelWaitSema, sceKernelPollSema, sceKernelSignalSema, sceKernelCancelSema, sceKernelDeleteSema](../../../core/libs/prx/libkernel/Semaphore/src/Semaphore.cpp) (libkernel) - `SCE_KERNEL_ERROR_ESRCH` for a null handle follows [shadPS4](https://github.com/shadps4-emu/shadPS4/blob/60c42b925c3d1e00008621b8587819999260ec31/src/core/libraries/kernel/threads/semaphore.cpp#L329-L366) (PS4), unverified on PS5. Handles are pointers, so a non-null handle that is not a live semaphore is not detected; shadPS4 returns `ESRCH` for any unallocated handle.