Trying to understand yaml structure and capabilities

[berkut0]

I'm in the process of exploring the capabilities of this tool and my enthusiasm dimmed when I tried some 'obvious' ideas and they didn't work.

I'm probably misunderstanding the tool's capabilities. But I would like to know exactly what I am doing wrong? If possible, give a detailed insight into how it all works and is organised.

# This code changes ADC:description, but does not affect CR0

_modify:
  version: 1.2.1
  ADC:
    name: ADC
    description: Analog-to-Digital Converter
    CR0:
      _modify:
        description: "ADC control register 0"

# This one causes an error:
# 1: According to `ADC`
# 2: Processing peripheral `ADC`
# 3: Value is not a hash map (dictionary): String("Analog-to-Digital Converter")

ADC:
  _modify:
    description: Analog-to-Digital Converter
  CR0:
    _modify:
      description: ADC control register 0

# Same issue:
# Value is not a hash map (dictionary): String("Analog-to-Digital Converter")
ADC:
  _modify:
    description: Analog-to-Digital Converter
    CR0:
      description: ADC control register 0

# Of course, because it is yaml:
# String("ADC"): duplicated key in mapping at byte 191 line 14 column 1

ADC:
  _modify:
    description: Analog-to-Digital Converter

ADC:
  _modify:
    CR0:
      description: ADC control register 0

# That's work:
# But how do I change the description of the ADC?

ADC:
  _modify:
    CR0:
      description: ADC control register 0

# It compiles, but I can't believe it's the ‘correct’ version yet.

_modify:
  version: 1.2.1
  ADC:
    description: Analog-to-Digital Converter

ADC:
  _modify:
    CR0:
      description: ADC control register 0

I just tried the most obvious ideas. And got different combinations of errors. I also had a long conversation with a neural network as a sanity check. It has very similar 'guesses' and the 'right option' it just can't 'come up with'.

The file I want to fix is just full of problems and I don't think I can fix it without svdtools.

Please give more technical information to understand how this should work.

[burrbull]

It compiles, but I can't believe it's the ‘correct’ version yet.

It is correct and there is a reason. (Although is not obvious in first view)

The signature of _modify is:

_modify:
   MATCH_SPEC:
      tag: value

MATCH_SPEC is glob-like string matches with names of registers/fields inside current path. For example CR[0-2] will modify CR0, CR1, CR2.

The main reason is that this is consistent with other commands like _delete, _add, _derive, etc.
And each command has its own priority (_delete is max priority, _array is minimal) that minimizes patch conflicts.
Ask yourself what if you want to modify register name and then make something other with it?

device tags like version is special case.

[burrbull]

See https://github.com/stm32-rs/stm32-rs or https://github.com/esp-rs/esp-pacs for examples.

[berkut0]

All right. I'll have to think about that. It seems logical, even if it's not obvious.

I use the stm32-rs repository as a reference. But there are files nested inside each other, and for example a similar chip (also cortex-m0) is not representative because of the nesting and the (high) quality of the source file. I don't think I would have realised what was going on at all without these files. Overall a useful resource, but still doesn't answer all the questions.

I'm doing something like this.
But I can't get the number through %s.
I understand that there must be an array for this, but I can't do such a trick at all?

ADC:
  _modify:
    CR[0-3]:
      description: ADC control register %s

[burrbull]

I understand that there must be an array for this, but I can't do such a trick at all?

Do you want to use %s for independent registers, not collected in array?

Interesting idea, but no. It is not implemented.

[berkut0]

I really thought it was a slightly different tool from the beginning 😂 I thought it was some kind of template matching tool with a developed validation and editing system.

I can't articulate what it is yet, but it's something different.

The worst thing is that I can't teach the neural network to write yaml to edit an svd file. It (and I) do not understand how to write quality yaml for this. I have to think hard about whether the amount of work on a yaml file would be the same as if I did all the work by hand (editing svd).

It would be cool to have something more script-like. YAML is too declarative for that. Maybe something more like a makefile - do this, include that, validate that, cut, paste, copy, delete. Maybe something like build.rs

The tool is already there and working successfully, and I was just passing by. But look at it from the other side: there is a whole bunch of Chinese chips with an incredible number of bugs. And you have to write a lot of patches for them. I tried a neural network, it reads the reference manual (in Chinese) and in principle fixes bugs and can even rewrite pieces of xml. But the volume of 10-15 thousand lines can't be digested, and a large number of iterations quickly overwhelms the context and the neural network starts to fail. It could write patches (like yaml), but it's very hard for it to understand the non-obvious structure. It (like me) immediately tries to write a script (instead of a declarative yaml file where the 'obvious' doesn't work). It seems to me that the closest thing to what should have been the basis for svdtools is makefile.

[berkut0]

For example. I made the neural network generate descriptions (there is not a single description in the file right now). And, as it turns out, generating descriptions will look like this:

_modify:
  ADC:
    description: Analog-to-Digital Converter
  BGR:
    description: Bandgap Reference
  TIM:
    description: Timer module
  ADT0:
    description: Advanced Timer 0
  ADT1:
    description: Advanced Timer 1
  ADT2:
    description: Advanced Timer 2
  BT0:
    description: Base Timer 0
  BT1:
    description: Base Timer 1
  BT2:
    description: Base Timer 2
  UART1:
    description: Universal Asynchronous Receiver/Transmitter 1

But everything inside those entities needs to be edited separately.

So the best I can do is to put it in a separate file and include it?

[burrbull]

I understood what you suggest. And this looks good to me.
All that remains is to implement it this feature :).

[burrbull]

All that remains is to implement it this feature :).

@berkut0 see https://github.com/rust-embedded/svdtools/tree/idx for prototype of such implementation. Only for peripherals for now.

[berkut0]

Ask yourself what if you want to modify register name and then make something other with it?

I've given this some thought, and I'll give my opinion anyway.

I think it should be possible to edit the entire xml branch. I think this is the main issue for me right now. I'd like to have a clear tree that I can make changes to. Just my gut tells me - here's the ADC tree, and you can make all the changes you want to make to it. Yes, you also need an advanced matching system (I see that there is an initiative to introduce regex, for example), would be cool to have tools to enumerate, group and optimize the yaml code in this case.

Or is the problem that the code is originally designed in such a way that when I want to edit an xml branch, I get unpredictable behavior? What is this unpredictable behavior? Maybe something can be done to make it possible to edit everything in some way?

The codebase is quite large, I've started to sort it out, but it will take some time (and I'm not sure it will lead to success). If you can provide more technical details, it would be appreciated.