From 30459ddde672b3130d7775fe16d91e63c6f95943 Mon Sep 17 00:00:00 2001 From: Laszlo Ersek Date: Thu, 10 Oct 2019 11:07:39 +0200 Subject: UefiCpuPkg/MpInitLib: expand comment on initial AP enumeration Before adding another AP enumeration mode, clarify the documentation on the current logic. No functional changes. Cc: Eric Dong Cc: Ray Ni Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=1515 Signed-off-by: Laszlo Ersek Reviewed-by: Ray Ni --- UefiCpuPkg/Library/MpInitLib/MpLib.c | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/UefiCpuPkg/Library/MpInitLib/MpLib.c b/UefiCpuPkg/Library/MpInitLib/MpLib.c index d6f84c6f45..594a035d8b 100644 --- a/UefiCpuPkg/Library/MpInitLib/MpLib.c +++ b/UefiCpuPkg/Library/MpInitLib/MpLib.c @@ -1045,14 +1045,36 @@ WakeUpAP ( } if (CpuMpData->InitFlag == ApInitConfig) { // - // Here support two methods to collect AP count through adjust - // PcdCpuApInitTimeOutInMicroSeconds values. + // The AP enumeration algorithm below is suitable for two use cases. // - // one way is set a value to just let the first AP to start the - // initialization, then through the later while loop to wait all Aps - // finsh the initialization. - // The other way is set a value to let all APs finished the initialzation. - // In this case, the later while loop is useless. + // (1) The check-in time for an individual AP is bounded, and APs run + // through their initialization routines strongly concurrently. In + // particular, the number of concurrently running APs + // ("NumApsExecuting") is never expected to fall to zero + // *temporarily* -- it is expected to fall to zero only when all + // APs have checked-in. + // + // In this case, the platform is supposed to set + // PcdCpuApInitTimeOutInMicroSeconds to a low-ish value (just long + // enough for one AP to start initialization). The timeout will be + // reached soon, and remaining APs are collected by watching + // NumApsExecuting fall to zero. If NumApsExecuting falls to zero + // mid-process, while some APs have not completed initialization, + // the behavior is undefined. + // + // (2) The check-in time for an individual AP is unbounded, and/or APs + // may complete their initializations widely spread out. In + // particular, some APs may finish initialization before some APs + // even start. + // + // In this case, the platform is supposed to set + // PcdCpuApInitTimeOutInMicroSeconds to a high-ish value. The AP + // enumeration will always take that long (except when the boot CPU + // count happens to be maximal, that is, + // PcdCpuMaxLogicalProcessorNumber). All APs are expected to + // check-in before the timeout, and NumApsExecuting is assumed zero + // at timeout. APs that miss the time-out may cause undefined + // behavior. // TimedWaitForApFinish ( CpuMpData, -- cgit v1.2.3