Add warning about indexing register arrays

Author: burrbull

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+- Add warning about indexing register arrays
 - Skip generating `.add(0)` and `1 *` in accessors
 - Bump MSRV of generated code to 1.76
 - move `must_use` from methods to generic type

src/generate/peripheral.rs

@@ -1052,6 +1052,10 @@ fn expand_cluster(cluster: &Cluster, config: &Config) -> Result<Vec<RegisterBloc
                     &description,
                 );
                 let mut accessors = Vec::with_capacity((array_info.dim + 1) as _);
+                let first_name = svd::array::names(info, array_info).next().unwrap();
+                let note = (array_info.indexes().next().unwrap() != "0").then(||
+                    format!("<div class=\"warning\">`n` is the index of {0} in the array. `n == 0` corresponds to `{first_name}` {0}.</div>", "cluster")
+                );
                 accessors.push(
                     Accessor::Array(ArrayAccessor {
                         doc,
@@ -1060,6 +1064,7 @@ fn expand_cluster(cluster: &Cluster, config: &Config) -> Result<Vec<RegisterBloc
                         offset: info.address_offset,
                         dim: array_info.dim,
                         increment: array_info.dim_increment,
+                        note,
                     })
                     .raw_if(!array_convertible),
                 );
@@ -1234,6 +1239,10 @@ fn expand_register(
                     &description,
                 );
                 let mut accessors = Vec::with_capacity((array_info.dim + 1) as _);
+                let first_name = svd::array::names(info, array_info).next().unwrap();
+                let note = (array_info.indexes().next().unwrap() != "0").then(||
+                    format!("<div class=\"warning\">`n` is the index of {0} in the array. `n == 0` corresponds to `{first_name}` {0}.</div>", "register")
+                );
                 accessors.push(
                     Accessor::Array(ArrayAccessor {
                         doc,
@@ -1242,6 +1251,7 @@ fn expand_register(
                         offset: info.address_offset,
                         dim: array_info.dim,
                         increment: array_info.dim_increment,
+                        note,
                     })
                     .raw_if(!array_convertible),
                 );

src/generate/peripheral/accessor.rs

@@ -62,10 +62,15 @@ impl ToTokens for AccessType {
                     }
                 }
             }
-            Self::Ref(Accessor::Array(ArrayAccessor { doc, name, ty, .. })) => {
+            Self::Ref(Accessor::Array(ArrayAccessor { doc, name, ty, note, .. })) => {
                 let name_iter = Ident::new(&format!("{name}_iter"), Span::call_site());
+                let note = note.as_ref().map(|note| quote! {
+                    #[doc = ""]
+                    #[doc = #note]
+                });
                 quote! {
                     #[doc = #doc]
+                    #note
                     #[inline(always)]
                     pub const fn #name(&self, n: usize) -> &#ty {
                         &self.#name[n]
@@ -85,14 +90,20 @@ impl ToTokens for AccessType {
                 offset,
                 dim,
                 increment,
+                note,
             })) => {
                 let name_iter = Ident::new(&format!("{name}_iter"), Span::call_site());
                 let offset = (*offset != 0).then(|| unsuffixed(*offset)).map(|o| quote!(.add(#o)));
                 let dim = unsuffixed(*dim);
                 let increment = (*increment != 1).then(|| unsuffixed(*increment)).map(|i| quote!(#i *));
+                let note = note.as_ref().map(|note| quote! {
+                    #[doc = ""]
+                    #[doc = #note]
+                });
                 let cast = quote! { unsafe { &*core::ptr::from_ref(self).cast::<u8>() #offset .add(#increment n).cast() } };
                 quote! {
                     #[doc = #doc]
+                    #note
                     #[inline(always)]
                     pub const fn #name(&self, n: usize) -> &#ty {
                         #[allow(clippy::no_effect)]
@@ -145,6 +156,7 @@ pub struct ArrayAccessor {
     pub offset: u32,
     pub dim: u32,
     pub increment: u32,
+    pub note: Option<String>,
 }
 
 #[derive(Clone, Debug)]