Merge #534

534: Emit more Cluster arrays as arrays instead of lists of elements. r=burrbull a=rcls

(This obsoletes #531)
Some Cluster arrays cannot be emitted as Rust (built-in) arrays due to padding between elements.
Add a helper zero-sized type `ArrayProxy` that overloads `[]` to do pointer-arithmetic internally.

I believe, although I'm not 100% confident, that I'm not breaking Rust safety, as follows: There is no way for (safe) code to create an `ArrayProxy`. Code that produces a (reference to) an `ArrayProxy` has to use `unsafe` somewhere.

See rcls/svd2rust-example@b8645fe for any example of the difference this makes (or does not make):
- STM32L051 and LPC408x get no change.
- Cypress PSOC gets a significant difference.

This uses const generics, so the new functionality requires the `--const_generic` command line optoin.

Co-authored-by: Ralph Loader <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Support for device.x generation for riscv targets and `__EXTERNAL_INTERRUPTS` vector table
 - Re-export base's module for derived peripherals
+- More Cluster arrays are now emitted as an array rather than a list of
+  elements.  An `ArrayProxy` wrapper is used when a Rust built-in array does not
+  match the cluster layout.  Requires the `--const_generic` command line option.
 
 ## [v0.19.0] - 2021-05-26
 

src/generate/array_proxy.rs

@@ -0,0 +1,46 @@
+
+/// Access an array of `COUNT` items of type `T` with the items `STRIDE` bytes
+/// apart.  This is a zero-sized-type.  No objects of this type are ever
+/// actually created, it is only a convenience for wrapping pointer arithmetic.
+///
+/// There is no safe way to produce items of this type.  Unsafe code can produce
+/// references by pointer casting.  It is up to the unsafe code doing that, to
+/// ensure that the memory really is backed by appropriate content.
+///
+/// Typically, this is used for accessing hardware registers.
+pub struct ArrayProxy<T, const COUNT: usize, const STRIDE: usize> {
+    /// As well as providing a PhantomData, this field is non-public, and
+    /// therefore ensures that code outside of this module can never create
+    /// an ArrayProxy.
+    _array: marker::PhantomData<T>
+}
+
+impl<T, const C: usize, const S: usize> ArrayProxy<T, C, S> {
+    /// Get a reference from an [ArrayProxy] with no bounds checking.
+    pub unsafe fn get_ref(&self, index: usize) -> &T {
+        let base = self as *const Self as usize;
+        let address = base + S * index;
+        &*(address as *const T)
+    }
+    /// Get a reference from an [ArrayProxy], or return `None` if the index
+    /// is out of bounds.
+    pub fn get(&self, index: usize) -> Option<&T> {
+        if index < C {
+            Some(unsafe { self.get_ref(index) })
+        }
+        else {
+            None
+        }
+    }
+    /// Return the number of items.
+    pub fn len(&self) -> usize { C }
+}
+
+impl<T, const C: usize, const S: usize> core::ops::Index<usize> for ArrayProxy<T, C, S> {
+    type Output = T;
+    fn index(&self, index: usize) -> &T {
+        // Do a real array dereference for the bounds check.
+        [(); C][index];
+        unsafe { self.get_ref(index) }
+    }
+}

src/generate/device.rs

@@ -146,6 +146,10 @@ pub fn render(d: &Device, config: &Config, device_x: &mut String) -> Result<Toke
                 std::str::from_utf8(include_bytes!("generic_msp430_atomic.rs"))?;
             writeln!(file, "\n{}", msp430_atomic_file)?;
         }
+        if config.const_generic {
+            let array_proxy = std::str::from_utf8(include_bytes!("array_proxy.rs"))?;
+            writeln!(file, "{}", array_proxy)?;
+        }
 
         if !config.make_mod {
             out.extend(quote! {
@@ -156,32 +160,27 @@ pub fn render(d: &Device, config: &Config, device_x: &mut String) -> Result<Toke
             });
         }
     } else {
-        let tokens = syn::parse_file(generic_file)?.into_token_stream();
-
+        let mut tokens = syn::parse_file(generic_file)?.into_token_stream();
         if config.target == Target::Msp430 && config.nightly {
             let msp430_atomic_file =
                 std::str::from_utf8(include_bytes!("generic_msp430_atomic.rs"))?;
             let generic_msp430_atomic = syn::parse_file(msp430_atomic_file)?.into_token_stream();
-            out.extend(quote! {
-                #[allow(unused_imports)]
-                use generic::*;
-                ///Common register and bit access and modify traits
-                pub mod generic {
-                    #tokens
-
-                    #generic_msp430_atomic
-                }
-            });
-        } else {
-            out.extend(quote! {
-                #[allow(unused_imports)]
-                use generic::*;
-                ///Common register and bit access and modify traits
-                pub mod generic {
-                    #tokens
-                }
-            });
+            tokens.extend(generic_msp430_atomic);
+        }
+        if config.const_generic {
+            let array_proxy = std::str::from_utf8(include_bytes!("array_proxy.rs"))?;
+            let generic_array_proxy = syn::parse_file(array_proxy)?.into_token_stream();
+            tokens.extend(generic_array_proxy);
         }
+
+        out.extend(quote! {
+            #[allow(unused_imports)]
+            use generic::*;
+            ///Common register and bit access and modify traits
+            pub mod generic {
+                #tokens
+            }
+        });
     }
 
     out.extend(interrupt::render(config.target, &d.peripherals, device_x)?);

src/generate/peripheral.rs

@@ -2,7 +2,9 @@ use std::borrow::Cow;
 use std::cmp::Ordering;
 use std::collections::HashMap;
 
-use crate::svd::{Cluster, ClusterInfo, Peripheral, Register, RegisterCluster, RegisterProperties};
+use crate::svd::{
+    Cluster, ClusterInfo, DimElement, Peripheral, Register, RegisterCluster, RegisterProperties,
+};
 use log::warn;
 use proc_macro2::TokenStream;
 use proc_macro2::{Ident, Punct, Spacing, Span};
@@ -701,6 +703,10 @@ fn expand_cluster(
                     offset: info.address_offset,
                     size: cluster_size * array_info.dim,
                 });
+            } else if sequential_indexes && config.const_generic {
+                // Include a ZST ArrayProxy giving indexed access to the
+                // elements.
+                cluster_expanded.push(array_proxy(info, array_info, name)?);
             } else {
                 for (field_num, field) in expand_svd_cluster(cluster, name)?.iter().enumerate() {
                     cluster_expanded.push(RegisterBlockField {
@@ -901,6 +907,30 @@ fn convert_svd_register(
     })
 }
 
+/// Return an syn::Type for an ArrayProxy.
+fn array_proxy(
+    info: &ClusterInfo,
+    array_info: &DimElement,
+    name: Option<&str>,
+) -> Result<RegisterBlockField, syn::Error> {
+    let ty_name = util::replace_suffix(&info.name, "");
+    let tys = name_to_ty_str(&ty_name, name);
+
+    let ap_path = parse_str::<syn::TypePath>(&format!(
+        "crate::ArrayProxy<{}, {}, {}>",
+        tys,
+        array_info.dim,
+        util::hex(array_info.dim_increment as u64)
+    ))?;
+
+    Ok(RegisterBlockField {
+        field: new_syn_field(&ty_name.to_sanitized_snake_case(), ap_path.into()),
+        description: info.description.as_ref().unwrap_or(&info.name).into(),
+        offset: info.address_offset,
+        size: 0,
+    })
+}
+
 /// Takes a svd::Cluster which may contain a register array, and turn in into
 /// a list of syn::Field where the register arrays have been expanded.
 fn expand_svd_cluster(