search

rust-embedded / svd2rust

Generate Rust register maps (`struct`s) from SVD files
Apache License 2.0
715 stars 152 forks source link

Whitespace in SVD files is lost #858

Open thejpster opened 3 months ago

thejpster commented 3 months ago

Raspberry Pi provide SVD files with descriptions like:

        <description>DW_apb_i2c address block

            List of configuration constants for the Synopsys I2C hardware (you may see references to these in I2C register header; these are *fixed* values, set at hardware design time):

            IC_ULTRA_FAST_MODE ................ 0x0 
            IC_UFM_TBUF_CNT_DEFAULT ........... 0x8 
(etc)
        </description>

It comes out in the Rust code as:

#[doc = "DW_apb_i2c address block List of configuration constants for the Synopsys I2C hardware (you may see references to these in I2C register header; these are *fixed* values, set at hardware design time): IC_ULTRA_FAST_MODE ....."]

I suspect this is because whitespace in XML is collapsed - any run of whitespace is converted into a single space character.

I tried putting the description in a <![CDATA[ ]> block, but a) svdtools removed it and b) even if I force it back it, svd2rust ignores it.

How can I try and make sure the whitespace in the description is carried through into the docs? In particular, I want to avoid very very very long single line descriptions appearing in https://docs.rs/rp235x-pac/latest/rp235x_pac/index.html

burrbull commented 4 weeks ago

The causer is respace. But I do not know what should we do with it. Sometimes squashing of strings is really helpful.

thejpster commented 4 weeks ago

Can it be a configuration option?

burrbull commented 4 weeks ago

Can it be a configuration option?

Yes. It was my first thought.

burrbull commented 3 weeks ago

I think respace was introduced to avoid this situation: https://github.com/rust-embedded/svd2rust/actions/runs/11520507042/job/32072026803?pr=879#step:7:47 I also think that this is STM32-specific issue (need to check this somehow). If it is true we I can remove respace entirely from svd2rust and move this as option to svdtools (to apply in stm32-rs).