clang-tools-extra/docs/clang-tidy/checks/altera/struct-pack-align.rst

   1 .. title:: clang-tidy - altera-struct-pack-align
   2
   3 altera-struct-pack-align
   4 ========================
   5
   6 Finds structs that are inefficiently packed or aligned, and recommends
   7 packing and/or aligning of said structs as needed.
   8
   9 Structs that are not packed take up more space than they should, and accessing
  10 structs that are not well aligned is inefficient.
  11
  12 Fix-its are provided to fix both of these issues by inserting and/or amending
  13 relevant struct attributes.
  14
  15 Based on the `Altera SDK for OpenCL: Best Practices Guide
  16 <https://www.altera.com/en_US/pdfs/literature/hb/opencl-sdk/aocl_optimization_guide.pdf>`_.
  17
  18 .. code-block:: c++
  19
  20   // The following struct is originally aligned to 4 bytes, and thus takes up
  21   // 12 bytes of memory instead of 10. Packing the struct will make it use
  22   // only 10 bytes of memory, and aligning it to 16 bytes will make it
  23   // efficient to access.
  24   struct example {
  25     char a;    // 1 byte
  26     double b;  // 8 bytes
  27     char c;    // 1 byte
  28   };
  29
  30   // The following struct is arranged in such a way that packing is not needed.
  31   // However, it is aligned to 4 bytes instead of 8, and thus needs to be
  32   // explicitly aligned.
  33   struct implicitly_packed_example {
  34     char a;  // 1 byte
  35     char b;  // 1 byte
  36     char c;  // 1 byte
  37     char d;  // 1 byte
  38     int e;   // 4 bytes
  39   };
  40
  41   // The following struct is explicitly aligned and packed.
  42   struct good_example {
  43     char a;    // 1 byte
  44     double b;  // 8 bytes
  45     char c;    // 1 byte
  46   } __attribute__((packed)) __attribute__((aligned(16));
  47
  48   // Explicitly aligning a struct to the wrong value will result in a warning.
  49   // The following example should be aligned to 16 bytes, not 32.
  50   struct badly_aligned_example {
  51     char a;    // 1 byte
  52     double b;  // 8 bytes
  53     char c;    // 1 byte
  54   } __attribute__((packed)) __attribute__((aligned(32)));