On 2/23/21 10:20 AM, John Wood wrote:

Hi,

On Sun, Feb 21, 2021 at 06:47:16PM -0800, Randy Dunlap wrote:

quoted

Hi--

scripts/kernel-doc does not like these items to be marked
as being in kernel-doc notation. scripts/kernel-doc does not
recognize them as one of: struct, union, enum, typedef, so it
defaults to trying to interpret these as functions, and then
says:

(I copied these blocks to my test megatest.c source file.)


../src/megatest.c:1214: warning: cannot understand function prototype: 'const u64 BRUTE_EMA_WEIGHT_NUMERATOR = 7; '
../src/megatest.c:1219: warning: cannot understand function prototype: 'const u64 BRUTE_EMA_WEIGHT_DENOMINATOR = 10; '
../src/megatest.c:1228: warning: cannot understand function prototype: 'const unsigned char BRUTE_MAX_FAULTS = 200; '
../src/megatest.c:1239: warning: cannot understand function prototype: 'const unsigned char BRUTE_MIN_FAULTS = 5; '
../src/megatest.c:1249: warning: cannot understand function prototype: 'const u64 BRUTE_CRASH_PERIOD_THRESHOLD = 30000; '


On 2/21/21 7:49 AM, John Wood wrote:

quoted

+/**
+ * brute_stats_ptr_lock - Lock to protect the brute_stats structure pointer.
+ */
+static DEFINE_RWLOCK(brute_stats_ptr_lock);

quoted

+/**
+ * BRUTE_EMA_WEIGHT_NUMERATOR - Weight's numerator of EMA.
+ */
+static const u64 BRUTE_EMA_WEIGHT_NUMERATOR = 7;

quoted

+/**
+ * BRUTE_EMA_WEIGHT_DENOMINATOR - Weight's denominator of EMA.
+ */
+static const u64 BRUTE_EMA_WEIGHT_DENOMINATOR = 10;

quoted

+/**
+ * BRUTE_MAX_FAULTS - Maximum number of faults.
+ *
+ * If a brute force attack is running slowly for a long time, the application
+ * crash period's EMA is not suitable for the detection. This type of attack
+ * must be detected using a maximum number of faults.
+ */
+static const unsigned char BRUTE_MAX_FAULTS = 200;

quoted

+/**
+ * BRUTE_MIN_FAULTS - Minimum number of faults.
+ *
+ * The application crash period's EMA cannot be used until a minimum number of
+ * data has been applied to it. This constraint allows getting a trend when this
+ * moving average is used. Moreover, it avoids the scenario where an application
+ * fails quickly from execve system call due to reasons unrelated to a real
+ * attack.
+ */
+static const unsigned char BRUTE_MIN_FAULTS = 5;

quoted

+/**
+ * BRUTE_CRASH_PERIOD_THRESHOLD - Application crash period threshold.
+ *
+ * The units are expressed in milliseconds.
+ *
+ * A fast brute force attack is detected when the application crash period falls
+ * below this threshold.
+ */
+static const u64 BRUTE_CRASH_PERIOD_THRESHOLD = 30000;

Basically we don't support scalars in kernel-doc notation...

So, to keep it commented it would be better to use a normal comment block?

/*
 * Documentation here
 */

What do you think?

Yes, please, just a normal /* comment block.

thanks.
-- 
~Randy