fix: debug info alignment (#1468)

This PR reintroduces explicit alignments in our debug-info. Additionally, for struct-types, the offsets are now manually calculated and then compared with the LLVM-offset, choosing the bigger value. This prevents overlap when reading values from memory during debugging, which would lead to corrupted values.

In particular, this issue arose for variables placed after 64-bit types. In the example below, the running offset didn't match the actual offset in memory. 304 + 8 != 308.

`(gdb) ptype /o <struct>`:
```
/*    304      |       8 */    LINT var_LINT;
/*    308      |      26 */    BYTE check_after_LINT[26];
```

After reading a bit further into the LLVM documentation/performance guide for frontend authors, I have decided to enable alignment for each variable-type except globals. While alignment can safely be omitted for x86 architectures with little-to-no performance drawbacks, it is still recommended for MIPS and ARM ISAs.
[When to specify alignment](https://llvm.org/docs/Frontend/PerformanceTips.html#when-to-specify-alignment)

For global variables, however, it is recommended to let the target choose how it wants to align variables in memory. Specifying an alignment here would force the target to use the specified alignment and prevent targets and optimizers from over-aligning.
[Global vars](https://llvm.org/docs/LangRef.html#globalvars)

While these points are generally not written in regards to debug-information, I think i doesn't hurt to match these specifications when generating DI aswell.

Author: mhasel

compiler/plc_driver/src/tests/snapshots/plc_driver__tests__multi_files__multiple_files_in_different_locations_with_debug_info.snap

@@ -1,6 +1,7 @@
 ---
 source: compiler/plc_driver/./src/tests/multi_files.rs
 expression: "results.join(\"\\n\")"
+snapshot_kind: text
 ---
 ; ModuleID = 'app/file1.st'
 source_filename = "app/file1.st"
@@ -32,7 +33,7 @@ attributes #0 = { nofree nosync nounwind readnone speculatable willreturn }
 !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression())
 !1 = distinct !DIGlobalVariable(name: "mainProg", scope: !2, file: !2, line: 2, type: !3, isLocal: false, isDefinition: true)
 !2 = !DIFile(filename: "file2.st", directory: "lib")
-!3 = !DICompositeType(tag: DW_TAG_structure_type, name: "mainProg", scope: !2, file: !2, line: 2, flags: DIFlagPublic, elements: !4, identifier: "mainProg")
+!3 = !DICompositeType(tag: DW_TAG_structure_type, name: "mainProg", scope: !2, file: !2, line: 2, align: 64, flags: DIFlagPublic, elements: !4, identifier: "mainProg")
 !4 = !{}
 !5 = !{i32 2, !"Dwarf Version", i32 5}
 !6 = !{i32 2, !"Debug Info Version", i32 3}
@@ -43,7 +44,7 @@ attributes #0 = { nofree nosync nounwind readnone speculatable willreturn }
 !11 = !DIFile(filename: "file1.st", directory: "app")
 !12 = !DISubroutineType(flags: DIFlagPublic, types: !13)
 !13 = !{null}
-!14 = !DILocalVariable(name: "main", scope: !10, file: !11, line: 2, type: !15)
+!14 = !DILocalVariable(name: "main", scope: !10, file: !11, line: 2, type: !15, align: 16)
 !15 = !DIBasicType(name: "INT", size: 16, encoding: DW_ATE_signed, flags: DIFlagPublic)
 !16 = !DILocation(line: 2, column: 13, scope: !10)
 !17 = !DILocation(line: 10, column: 4, scope: !10)
@@ -76,7 +77,7 @@ attributes #0 = { nofree nosync nounwind readnone speculatable willreturn }
 !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression())
 !1 = distinct !DIGlobalVariable(name: "mainProg", scope: !2, file: !2, line: 2, type: !3, isLocal: false, isDefinition: true)
 !2 = !DIFile(filename: "file2.st", directory: "lib")
-!3 = !DICompositeType(tag: DW_TAG_structure_type, name: "mainProg", scope: !2, file: !2, line: 2, flags: DIFlagPublic, elements: !4, identifier: "mainProg")
+!3 = !DICompositeType(tag: DW_TAG_structure_type, name: "mainProg", scope: !2, file: !2, line: 2, align: 64, flags: DIFlagPublic, elements: !4, identifier: "mainProg")
 !4 = !{}
 !5 = !{i32 2, !"Dwarf Version", i32 5}
 !6 = !{i32 2, !"Debug Info Version", i32 3}

compiler/plc_driver/src/tests/snapshots/plc_driver__tests__multi_files__multiple_files_with_debug_info.snap

@@ -1,6 +1,7 @@
 ---
 source: compiler/plc_driver/./src/tests/multi_files.rs
 expression: "results.join(\"\\n\")"
+snapshot_kind: text
 ---
 ; ModuleID = 'file1.st'
 source_filename = "file1.st"
@@ -32,7 +33,7 @@ attributes #0 = { nofree nosync nounwind readnone speculatable willreturn }
 !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression())
 !1 = distinct !DIGlobalVariable(name: "mainProg", scope: !2, file: !2, line: 2, type: !3, isLocal: false, isDefinition: true)
 !2 = !DIFile(filename: "file2.st", directory: "")
-!3 = !DICompositeType(tag: DW_TAG_structure_type, name: "mainProg", scope: !2, file: !2, line: 2, flags: DIFlagPublic, elements: !4, identifier: "mainProg")
+!3 = !DICompositeType(tag: DW_TAG_structure_type, name: "mainProg", scope: !2, file: !2, line: 2, align: 64, flags: DIFlagPublic, elements: !4, identifier: "mainProg")
 !4 = !{}
 !5 = !{i32 2, !"Dwarf Version", i32 5}
 !6 = !{i32 2, !"Debug Info Version", i32 3}
@@ -43,7 +44,7 @@ attributes #0 = { nofree nosync nounwind readnone speculatable willreturn }
 !11 = !DIFile(filename: "file1.st", directory: "")
 !12 = !DISubroutineType(flags: DIFlagPublic, types: !13)
 !13 = !{null}
-!14 = !DILocalVariable(name: "main", scope: !10, file: !11, line: 2, type: !15)
+!14 = !DILocalVariable(name: "main", scope: !10, file: !11, line: 2, type: !15, align: 16)
 !15 = !DIBasicType(name: "INT", size: 16, encoding: DW_ATE_signed, flags: DIFlagPublic)
 !16 = !DILocation(line: 2, column: 13, scope: !10)
 !17 = !DILocation(line: 10, column: 4, scope: !10)
@@ -76,7 +77,7 @@ attributes #0 = { nofree nosync nounwind readnone speculatable willreturn }
 !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression())
 !1 = distinct !DIGlobalVariable(name: "mainProg", scope: !2, file: !2, line: 2, type: !3, isLocal: false, isDefinition: true)
 !2 = !DIFile(filename: "file2.st", directory: "")
-!3 = !DICompositeType(tag: DW_TAG_structure_type, name: "mainProg", scope: !2, file: !2, line: 2, flags: DIFlagPublic, elements: !4, identifier: "mainProg")
+!3 = !DICompositeType(tag: DW_TAG_structure_type, name: "mainProg", scope: !2, file: !2, line: 2, align: 64, flags: DIFlagPublic, elements: !4, identifier: "mainProg")
 !4 = !{}
 !5 = !{i32 2, !"Dwarf Version", i32 5}
 !6 = !{i32 2, !"Debug Info Version", i32 3}

src/codegen/debug.rs

@@ -72,7 +72,7 @@ pub trait Debug<'ink> {
     /// function's stub as well as its interface (variables/parameters)
     fn register_function<'idx>(
         &mut self,
-        index: &Index,
+        indices: (&Index, &LlvmTypedIndex<'ink>),
         func: &FunctionContext<'ink, 'idx>,
         return_type: Option<&'idx DataType>,
         parent_function: Option<FunctionValue<'ink>>,
@@ -303,44 +303,110 @@ impl<'ink> DebugBuilder<'ink> {
             .unwrap_or_else(|| self.compile_unit.get_file());
 
         let mut types = vec![];
-        for (element_index, (member_name, dt, location)) in index_types.into_iter().enumerate() {
+        let mut last_offset_bits = 0;
+        let mut last_size_bits = 0;
+
+        for (element_index, (member_name, dt, location)) in index_types.iter().enumerate() {
             let di_type = self.get_or_create_debug_type(dt, index, types_index)?;
 
-            //Adjust the offset based on the field alignment
-            let size = types_index
-                .find_associated_type(dt.get_name())
-                .map(|llvm_type| self.target_data.get_bit_size(&llvm_type))
+            // Get the size and alignment
+            let llvm_type = types_index.find_associated_type(dt.get_name());
+            let align_bits =
+                llvm_type.map(|ty| self.target_data.get_preferred_alignment(&ty) * 8).unwrap_or(0);
+            let size_bits = llvm_type.map(|ty| self.target_data.get_bit_size(&ty)).unwrap_or(0);
+
+            // Get LLVM's calculated offset
+            let llvm_offset_bits = self
+                .target_data
+                .offset_of_element(&struct_type, element_index as u32)
+                .map(|offset| offset * 8)
                 .unwrap_or(0);
-            //Offset in bits
-            let offset =
-                self.target_data.offset_of_element(&struct_type, element_index as u32).unwrap_or(0) * 8;
 
+            // Calculate the properly aligned offset based on the previous field
+            // and this field's alignment requirements
+            let offset_bits = if size_bits == 0 || (last_size_bits == 0 && element_index > 0) {
+                // For zero-sized types, always use LLVM's offset directly
+                // This ensures they don't contribute to the overall layout calculation
+                // If the previous field was zero-sized, use LLVM's offset
+                // for proper alignment of fields after zero-sized types
+                llvm_offset_bits
+            } else {
+                let next_offset_bits: u64 = last_offset_bits + last_size_bits;
+
+                // Special handling based on alignment requirements:
+                // - Fields with alignment of 64 bits need to be explicitly aligned
+                //   to their alignment boundary to prevent misaligned accesses
+                // - Fields with a lower alignment can use LLVM's natural layout
+                // This differentiation is crucial for correctly representing complex structures
+                // where some fields (like LWORD, LINT) need specific alignment while others (like BYTE, BOOL)
+                // can be packed more efficiently
+                if align_bits == 64 {
+                    // For fields requiring special alignment (64 bit types),
+                    // round up to the nearest alignment boundary
+                    next_offset_bits.div_ceil(align_bits as u64) * align_bits as u64
+                } else {
+                    // For smaller fields fields (BYTE, BOOL, DINT), we still ensure we don't
+                    // overlap with previous fields by using the maximum of our calculated offset
+                    // and LLVM's calculated offset
+                    std::cmp::max(next_offset_bits, llvm_offset_bits)
+                }
+            };
+
+            // Update tracking variables for next field
+            last_offset_bits = offset_bits;
+            last_size_bits = size_bits;
+
+            // Create the member type with calculated offset
             types.push(
                 self.debug_info
                     .create_member_type(
                         file.as_debug_info_scope(),
                         member_name,
                         file,
                         location.get_line_plus_one() as u32,
-                        size,
-                        0, // No set alignment
-                        offset,
+                        size_bits,
+                        align_bits,
+                        offset_bits,
                         DIFlags::PUBLIC,
                         di_type.into(),
                     )
                     .as_type(),
             );
         }
 
-        let size = self.target_data.get_bit_size(&struct_type);
-        //Create a struct type
+        // Calculate struct size based on the last field's offset + size, properly aligned
+        let llvm_size = self.target_data.get_bit_size(&struct_type);
+        // Calculate our manual size based on adjusted offsets
+        let calculated_size = {
+            // Get struct alignment requirement (usually 8 bytes/64 bits for 64-bit architectures)
+            let struct_align_bits = self.target_data.get_preferred_alignment(&struct_type) * 8;
+
+            // Calculate total size based on last field offset + size, rounded up to alignment
+            let last_field_end_bits = last_offset_bits + last_size_bits;
+            let aligned_size_bits =
+                last_field_end_bits.div_ceil(struct_align_bits as u64) * struct_align_bits as u64;
+
+            // If our calculated size is larger than LLVM's, use ours
+            if aligned_size_bits > llvm_size {
+                log::trace!(
+                    "Struct {}: adjusted size from {} to {} bits due to field alignment",
+                    name,
+                    llvm_size,
+                    aligned_size_bits
+                );
+                aligned_size_bits
+            } else {
+                llvm_size
+            }
+        };
+
         let struct_type = self.debug_info.create_struct_type(
             file.as_debug_info_scope(),
             name,
             file,
             location.get_line_plus_one() as u32,
-            size,
-            0, // No set alignment
+            calculated_size,
+            self.target_data.get_preferred_alignment(&struct_type) * 8,
             DIFlags::PUBLIC,
             None,
             types.as_slice(),
@@ -364,20 +430,18 @@ impl<'ink> DebugBuilder<'ink> {
     ) -> Result<(), Diagnostic> {
         //find the inner type debug info
         let inner_type = index.get_type(inner_type)?;
-        //Find the dimenstions as ranges
+        //Find the dimensions as ranges
         let subscript = dimensions
             .iter()
             .map(|it| it.get_range_plus_one(index))
-            //Convert to normal range
             .collect::<Result<Vec<Range<i64>>, _>>()
             .map_err(|err| Diagnostic::codegen_error(err, SourceLocation::undefined()))?;
         let inner_type = self.get_or_create_debug_type(inner_type, index, types_index)?;
-        let array_type = self.debug_info.create_array_type(
-            inner_type.into(),
-            size,
-            0, //No set alignment
-            subscript.as_slice(),
-        );
+        let llvm_type = types_index.get_associated_type(name)?;
+        let align_bits = self.target_data.get_preferred_alignment(&llvm_type) * 8;
+        let array_type =
+            self.debug_info.create_array_type(inner_type.into(), size, align_bits, subscript.as_slice());
+
         self.register_concrete_type(name, DebugType::Composite(array_type));
         Ok(())
     }
@@ -392,11 +456,13 @@ impl<'ink> DebugBuilder<'ink> {
     ) -> Result<(), Diagnostic> {
         let inner_type = index.get_type(inner_type)?;
         let inner_type = self.get_or_create_debug_type(inner_type, index, types_index)?;
+        let llvm_type = types_index.get_associated_type(name)?;
+        let align_bits = self.target_data.get_preferred_alignment(&llvm_type) * 8;
         let pointer_type = self.debug_info.create_pointer_type(
             name,
             inner_type.into(),
             size,
-            0, //No set alignment
+            align_bits,
             inkwell::AddressSpace::from(ADDRESS_SPACE_GLOBAL),
         );
         self.register_concrete_type(name, DebugType::Derived(pointer_type));
@@ -438,14 +504,17 @@ impl<'ink> DebugBuilder<'ink> {
             StringEncoding::Utf16 => index.get_effective_type_or_void_by_name(WCHAR_TYPE),
         };
         let inner_type = self.get_or_create_debug_type(inner_type, index, types_index)?;
+        let llvm_type = types_index.get_associated_type(name)?;
+        let align_bits = self.target_data.get_preferred_alignment(&llvm_type) * 8;
         //Register an array
         let array_type = self.debug_info.create_array_type(
             inner_type.into(),
             size,
-            0, //No set alignment
+            align_bits,
             #[allow(clippy::single_range_in_vec_init)]
             &[(0..length)],
         );
+
         self.register_concrete_type(name, DebugType::Composite(array_type));
         Ok(())
     }
@@ -465,13 +534,15 @@ impl<'ink> DebugBuilder<'ink> {
             .map(|it| self.get_or_create_debug_file(it))
             .unwrap_or_else(|| self.compile_unit.get_file());
 
+        let llvm_type = types_index.get_associated_type(name)?;
+        let align_bits = self.target_data.get_preferred_alignment(&llvm_type) * 8;
         let typedef = self.debug_info.create_typedef(
             inner_type.into(),
             name,
             file,
             location.get_line_plus_one() as u32,
             file.as_debug_info_scope(),
-            0, //No set alignment
+            align_bits,
         );
         self.register_concrete_type(name, DebugType::Derived(typedef));
 
@@ -547,6 +618,7 @@ impl<'ink> DebugBuilder<'ink> {
         pou: &PouIndexEntry,
         func: &FunctionContext<'ink, '_>,
         index: &Index,
+        types_index: &LlvmTypedIndex<'ink>,
     ) {
         let mut param_offset = 0;
         //Register the return and local variables for debugging
@@ -555,7 +627,12 @@ impl<'ink> DebugBuilder<'ink> {
             .iter()
             .filter(|it| it.is_local() || it.is_temp() || it.is_return())
         {
-            self.register_local_variable(variable, 0, func);
+            let align_bits = types_index
+                .get_associated_type(&variable.data_type_name)
+                .map(|it| self.target_data.get_preferred_alignment(&it))
+                .unwrap_or(0)
+                * 8;
+            self.register_local_variable(variable, align_bits, func);
         }
 
         let implementation = pou.find_implementation(index).expect("A POU will have an impl at this stage");
@@ -611,13 +688,14 @@ impl<'ink> Debug<'ink> for DebugBuilder<'ink> {
 
     fn register_function<'idx>(
         &mut self,
-        index: &Index,
+        indices: (&Index, &LlvmTypedIndex<'ink>),
         func: &FunctionContext<'ink, 'idx>,
         return_type: Option<&'idx DataType>,
         parent_function: Option<FunctionValue<'ink>>,
         parameter_types: &[&'idx DataType],
         implementation_start: usize,
     ) {
+        let (index, types_index) = indices;
         let pou = index.find_pou(func.linking_context.get_call_name()).expect("POU is available");
         if matches!(pou.get_linkage(), LinkageType::External) || pou.get_location().is_internal() {
             return;
@@ -635,7 +713,7 @@ impl<'ink> Debug<'ink> for DebugBuilder<'ink> {
         let subprogram = self.create_function(scope, pou, return_type, parameter_types, implementation_start);
         func.function.set_subprogram(subprogram);
         //Create function parameters
-        self.create_function_variables(pou, func, index);
+        self.create_function_variables(pou, func, index, types_index);
     }
 
     fn register_debug_type<'idx>(
@@ -720,7 +798,7 @@ impl<'ink> Debug<'ink> for DebugBuilder<'ink> {
                 false,
                 None,
                 None,
-                global_variable.get_alignment(),
+                0, // Global variable alignment does not need to be forced/set. See https://llvm.org/docs/LangRef.html#global-variables
             );
             let gv_metadata = debug_variable.as_metadata_value(self.context);
 
@@ -893,7 +971,7 @@ impl<'ink> Debug<'ink> for DebugBuilderEnum<'ink> {
 
     fn register_function<'idx>(
         &mut self,
-        index: &Index,
+        indices: (&Index, &LlvmTypedIndex<'ink>),
         func: &FunctionContext<'ink, 'idx>,
         return_type: Option<&'idx DataType>,
         parent_function: Option<FunctionValue<'ink>>,
@@ -903,7 +981,7 @@ impl<'ink> Debug<'ink> for DebugBuilderEnum<'ink> {
         match self {
             Self::None | Self::VariablesOnly(..) => {}
             Self::Full(obj) => obj.register_function(
-                index,
+                indices,
                 func,
                 return_type,
                 parent_function,

src/codegen/generators/pou_generator.rs

@@ -314,7 +314,7 @@ impl<'ink, 'cg> PouGenerator<'ink, 'cg> {
             blocks: FxHashMap::default(),
         };
         debug.register_function(
-            self.index,
+            (self.index, self.llvm_index),
             &function_context,
             return_type,
             parent_function,