summaryrefslogtreecommitdiffstats
path: root/doc/developer-guide
diff options
context:
space:
mode:
authorAmar Tumballi <amarts@redhat.com>2018-07-20 10:33:00 +0530
committerAmar Tumballi <amarts@redhat.com>2018-08-02 05:14:32 +0000
commit45b023aac0cafa93a43a078c7bc94c8f5b8c3cb7 (patch)
treee89b8a1384cc0ea36b41d2c8205eeb3105857fec /doc/developer-guide
parentbca47bd4015ead34ac3e380b5839ba32fd701b88 (diff)
coding-standard: add points on structure padding
This is a recommendation for users, and reviewers can take a point from this. Updates: bz#1193929 Change-Id: Idcd778e42a886fd79b549da4927149a07573a20b Signed-off-by: Amar Tumballi <amarts@redhat.com>
Diffstat (limited to 'doc/developer-guide')
-rw-r--r--doc/developer-guide/coding-standard.md48
1 files changed, 48 insertions, 0 deletions
diff --git a/doc/developer-guide/coding-standard.md b/doc/developer-guide/coding-standard.md
index 446e342..eb9cd9d 100644
--- a/doc/developer-guide/coding-standard.md
+++ b/doc/developer-guide/coding-standard.md
@@ -26,6 +26,54 @@ DBTYPE access_mode; /* access mode for accessing
*/
```
+Structure members should be aligned based on the padding requirements
+---------------------------------------------------------------------
+
+The compiler will make sure that structure members have optimum alignment,
+but at the expense of suboptimal padding. More important is to optimize the
+padding. The compiler won't do that for you.
+
+This also will help utilize the memory better
+
+*Bad:*
+```
+struct bad {
+ bool b; /* 0 */
+ /* 1..7 pad */
+ void *p; /* 8..15 */
+ char c; /* 16 */
+ char a[16]; /* 17..33 */
+ /* 34..39 pad */
+ int64_t ii; /* 40..47 */
+ int32_t i; /* 48..51 */
+ /* 52..55 pad */
+ int64_t iii; /* 56..63 */
+};
+```
+
+*Good:*
+```
+struct good {
+ int64_t ii; /* explicit 64-bit types */
+ void *p; /* may be 64- or 32-bit */
+ long l; /* may be 64- or 32-bit */
+ int i; /* 32-bit */
+ short s; /* 16-bit */
+ char c; /* 8-bit */
+ bool b; /* 8-bit */
+ char a[1024];
+);
+```
+Make sure the items with the most stringent alignment requirements will need
+to come earliest (ie, pointers and perhaps uint64_t etc), and those with less
+stringent alignment requirements at the end (uint16/uint8 and char). Also note
+that the long array (if any) should be at the end of the structure, regardless
+of the type.
+
+Also note, if your structure's overall size is crossing 1k-4k limit, it is
+recommended to mention the reason why the particular structure needs so much
+memory as a comment at the top.
+
Use \_typename for struct tags and typename\_t for typedefs
---------------------------------------------------------