[clang] [Clang][analyzer] add documentation for optin performance padding (padding checker) #73675 (PR #86411)
via cfe-commits
cfe-commits at lists.llvm.org
Sun Mar 24 09:52:09 PDT 2024
https://github.com/komalverma04 updated https://github.com/llvm/llvm-project/pull/86411
>From b6ca6f0ef83d03e299d6ee9a8ed9b8044477914e Mon Sep 17 00:00:00 2001
From: komalverma04 <114138604+komalverma04 at users.noreply.github.com>
Date: Sat, 23 Mar 2024 11:14:44 -0700
Subject: [PATCH 1/5] Update checkers.rst
Modification of documentation to demonstrate utilization of AllowedPad within PaddingChecker, along with its use and effects on code analysis.
---
clang/docs/analyzer/checkers.rst | 22 ++++++++++++++++++++--
1 file changed, 20 insertions(+), 2 deletions(-)
diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index fe211514914272..64b09bc6ecd1d8 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -804,10 +804,28 @@ Check for performance anti-patterns when using Grand Central Dispatch.
.. _optin-performance-Padding:
-optin.performance.Padding
-"""""""""""""""""""""""""
+optin.performance.Padding (PaddingChecker)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Check for excessively padded structs.
+.. code-block:: objc
+
+ struct TestStruct {
+ int data1; // 4 bytes
+ char data2; // 1 byte
+ char padding[27]; // 27 bytes of padding
+ }; // Total size: 32 bytes
+
+ void TestFunction() {
+ struct TestStruct struct1; // Warning is generated due to excessive padding.
+ }
+
+ // Reports are only generated if the excessive padding exceeds 'AllowedPad' in bytes.
+
+ // AllowedPad: Default Value: 24 bytes
+
+ Usage: `AllowedPad=<value>`
+
.. _optin-portability-UnixAPI:
optin.portability.UnixAPI
>From 403115cd960653a3afe0491d2855d35d377d9312 Mon Sep 17 00:00:00 2001
From: komalverma04 <114138604+komalverma04 at users.noreply.github.com>
Date: Sat, 23 Mar 2024 11:20:46 -0700
Subject: [PATCH 2/5] Update Checkers.td
Changed NotDocumented to HasDocumentation for Padding Checker under performance checker.
---
clang/include/clang/StaticAnalyzer/Checkers/Checkers.td | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang/include/clang/StaticAnalyzer/Checkers/Checkers.td b/clang/include/clang/StaticAnalyzer/Checkers/Checkers.td
index 686e5e99f4a62c..c0e4e9a70c2ef3 100644
--- a/clang/include/clang/StaticAnalyzer/Checkers/Checkers.td
+++ b/clang/include/clang/StaticAnalyzer/Checkers/Checkers.td
@@ -908,7 +908,7 @@ def PaddingChecker : Checker<"Padding">,
"24",
Released>
]>,
- Documentation<NotDocumented>;
+ Documentation<HasDocumentation>;
} // end: "padding"
>From cdef12fa6a6b6c4833bc2017dae9557ee7115c92 Mon Sep 17 00:00:00 2001
From: komalverma04 <komal148btit21 at igdtuw.ac.in>
Date: Sun, 24 Mar 2024 20:39:56 +0530
Subject: [PATCH 3/5] Update checkers.rst
Made Indentation consistent and added description on limitation of checker.
---
clang/docs/analyzer/checkers.rst | 44 ++++++++++++++++++++------------
1 file changed, 27 insertions(+), 17 deletions(-)
diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index 64b09bc6ecd1d8..85f3f33d68bc5d 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -804,27 +804,37 @@ Check for performance anti-patterns when using Grand Central Dispatch.
.. _optin-performance-Padding:
-optin.performance.Padding (PaddingChecker)
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+optin.performance.Padding (C, C++, objC)
+""""""""""""""""""""""""""""""""""""""""
Check for excessively padded structs.
-.. code-block:: objc
-
- struct TestStruct {
- int data1; // 4 bytes
- char data2; // 1 byte
- char padding[27]; // 27 bytes of padding
- }; // Total size: 32 bytes
-
- void TestFunction() {
- struct TestStruct struct1; // Warning is generated due to excessive padding.
- }
-
- // Reports are only generated if the excessive padding exceeds 'AllowedPad' in bytes.
+This checker detects structs with excessive padding, which can lead to wasted memory and decreased performance. Padding bytes are added by compilers to align data within the struct for performance optimization or memory alignment purposes. However, excessive padding can significantly increase the size of the struct without adding useful data, leading to inefficient memory usage, cache misses, and decreased performance.
+
+.. code-block:: C
+
+ #include <stdio.h>
+ // #pragma pack(1) // Uncomment it to disable structure padding
+ struct TestStruct {
+ char data1; // 1 byte
+ char data2; // 1 byte
+ int data3; // 4 bytes
+ }; // Total size: 6 bytes
+
+ int main () {
+ struct TestStruct struct1;
+ print("Structure size: %d",sizeof(struct1)); // Structure size: 8
+ return 0;
+ }
+
+Total memory used is 8 bytes due to structure padding. In this case, padding is of 2 bytes. Padding is done to decrease the number of CPU cycles needed to access data members of the structure; it increases the performance of the processor but at the penalty of memory.
+Padding can be disabled by using the pragma directive.
+Padding can also be decreased by putting data members of the structure in descending order of their size.
- // AllowedPad: Default Value: 24 bytes
+Reports are only generated if the excessive padding exceeds 'AllowedPad' in bytes. AllowedPad is the threshold value of padding.
- Usage: `AllowedPad=<value>`
+AllowedPad Option:
+- Default Value: 24 bytes
+- Usage: ``AllowedPad=<value>``
.. _optin-portability-UnixAPI:
>From 54bc64616cc2ca5bb1d0bac32767dad0290743c0 Mon Sep 17 00:00:00 2001
From: komalverma04 <komal148btit21 at igdtuw.ac.in>
Date: Sun, 24 Mar 2024 21:12:31 +0530
Subject: [PATCH 4/5] Update checkers.rst
Fixed some typos
---
clang/docs/analyzer/checkers.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index 85f3f33d68bc5d..ef8a1ed6fb889e 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -810,7 +810,7 @@ Check for excessively padded structs.
This checker detects structs with excessive padding, which can lead to wasted memory and decreased performance. Padding bytes are added by compilers to align data within the struct for performance optimization or memory alignment purposes. However, excessive padding can significantly increase the size of the struct without adding useful data, leading to inefficient memory usage, cache misses, and decreased performance.
-.. code-block:: C
+.. code-block:: c
#include <stdio.h>
// #pragma pack(1) // Uncomment it to disable structure padding
@@ -822,7 +822,7 @@ This checker detects structs with excessive padding, which can lead to wasted me
int main () {
struct TestStruct struct1;
- print("Structure size: %d",sizeof(struct1)); // Structure size: 8
+ printf("Structure size: %d",sizeof(struct1)); // Structure size: 8
return 0;
}
>From fb65412a90c2fb36330cb79e9605e3220ad02d76 Mon Sep 17 00:00:00 2001
From: komalverma04 <komal148btit21 at igdtuw.ac.in>
Date: Sun, 24 Mar 2024 22:22:01 +0530
Subject: [PATCH 5/5] Update checkers.rst
Fixed a typo in objC and changed it to ObjC
---
clang/docs/analyzer/checkers.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index ef8a1ed6fb889e..c2215f8eb6581a 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -804,7 +804,7 @@ Check for performance anti-patterns when using Grand Central Dispatch.
.. _optin-performance-Padding:
-optin.performance.Padding (C, C++, objC)
+optin.performance.Padding (C, C++, ObjC)
""""""""""""""""""""""""""""""""""""""""
Check for excessively padded structs.
@@ -826,11 +826,11 @@ This checker detects structs with excessive padding, which can lead to wasted me
return 0;
}
-Total memory used is 8 bytes due to structure padding. In this case, padding is of 2 bytes. Padding is done to decrease the number of CPU cycles needed to access data members of the structure; it increases the performance of the processor but at the penalty of memory.
+Total memory used is 8 bytes due to structure padding. In this case, padding is of 2 bytes. Padding is done to decrease the number of CPU cycles needed to access data members of the structure, it increases the performance of the processor but at the penalty of memory.
Padding can be disabled by using the pragma directive.
Padding can also be decreased by putting data members of the structure in descending order of their size.
-Reports are only generated if the excessive padding exceeds 'AllowedPad' in bytes. AllowedPad is the threshold value of padding.
+Reports are only generated if the excessive padding exceeds ``AllowedPad`` in bytes. AllowedPad is the threshold value of padding.
AllowedPad Option:
- Default Value: 24 bytes
More information about the cfe-commits
mailing list