Any Linux device tree syntax experts here? - Page 1
Forum section: electronics / general

author: HwAoRrDk
author_rank: Super Contributor
timestamp: August 11, 2022, 03:08:36 pm
content: For a Raspberry Pi, I'm trying to customise a standard device tree overlay,gpio-shutdown-overlay.dts, that enables you to use a GPIO pin as a shutdown button. What I want to do is change the GPIO pin that it uses.Yes, I know you can specify parameters to this overlay to change the GPIO pin.But for reasons I won't bore you with, I can't do that, so instead I want to compile a custom .dtbo that has the desired GPIO pin as the hard-coded default.But I'm struggling to understand the syntax of device tree files, and I'm not sure exactly what parts do or do not need to be changed. Is there anyone here who is familiar with this stuff that can advise?I won't quote the whole .dts file - it's linked above - just excerpts from areas I have questions about:Code:pin_state: shutdown_button_pins@3 {brcm,pins = <3>; // gpio numberbrcm,function = <0>; // 0 = input, 1 = outputbrcm,pull = <2>; // 0 = none, 1 = pull down, 2 = pull up};Here, the GPIO number is obvious - I change the<3>. But theshutdown_button_pins@3is confusing me. Is it also referencing the GPIO number? Do I need to change the '@3' here too? Or is it referencing the number of elements within the following block? I can't find out what this '@' syntax is supposed to be.Code:shutdown_button: shutdown_button@3 {Again, same as above. But because this block has more than 3 elements contained within, I assume this '@3' isn't actually a count, but something else.I also note it's not the same name as above either (no '_pins' suffix).Code:button: shutdown {label = "shutdown";linux,code = <116>; // KEY_POWERgpios = <&gpio 3 1>;debounce-interval = <100>; // ms};It seems obvious what to change here, the '3' in the line containing<&gpio 3 1>. But what is the '1' part? There's only supposed to be a single GPIO pin in play here.Code:__overrides__ {// Allow overriding the GPIO number.gpio_pin = <&button>,"gpios:4",<&shutdown_button>,"reg:0",<&pin_state>,"reg:0",<&pin_state>,"brcm,pins:0";What is the relevance here of"gpios:4"? That's obviously not the GPIO number, so why is it '4'? Also, if I don't want any parameters at all for my overlay, can I just omit the whole__overrides__block?

author: Nominal Animal
author_rank: Super Contributor
timestamp: August 11, 2022, 07:19:28 pm
content: Quote from: HwAoRrDk on August 11, 2022, 03:08:36 pmWhy not head over to theDevice Tree Specifications, and learn it for yourself instead?In particular, indevicetree-specification-v0.3.pdf, section 2.2.1 Node Names, on page 7 explains that nodes are named usingnode-name@unit-address, with theunit-addresspart match the first reg property of the node; here, the GPIO number. So, if you change the default to say 5, you need to change the @3 to @5 also.Quote from: HwAoRrDk on August 11, 2022, 03:08:36 pmIt is equivalent toGPIO_ACTIVE_LOW. (0corresponds toGPIO_ACTIVE_HIGH).Thebutton:buttonname{gpios: <&controllerpinstate>; }syntax is described in the Linux Kernel Documentation,GPIO Device Treesection. Essentially, that snippet defines the data that the actual Kernel driver uses to determine which GPIO pin it should monitor or link to. (I could find the actual snippet in the kernel usingBootlin Elixir Cross Referencer, but I'm too lazy; sorry.)In other words, that snippet tells the actual kernel driver that it should monitor pin 3 in gpio controller, active low. (Which makes sense, because earlier the snippet defined internal pull-up resistors. I do the same in my own microcontroller projects, as then my buttons only short the pin to ground. Safer that way, at least for someone with my sausagey fingers.)If you had bothered to open the link in the comment,https://www.kernel.org/doc/Documentation/devicetree/bindings/input/gpio-keys.txt, you would already know this. (Yes, I do get to be snarky while being helpful at the same time. The mix of positive and negative reinforcement is supposed to strengthen your will to find out more, spend a bit more effort, before asking others; and to give you a serotonin boost when do learn –– it is your body telling you win that way.)Quote from: HwAoRrDk on August 11, 2022, 03:08:36 pmThese are parameter declarations. They form a list of pairs<&label>, "property.offset8"<&label>, "property;offset16"<&label>, "property:offset32"<&label>, "property#offset64"It describes the parameters that can be used to override specific values in the DT snippet. It does not describe what those values are, butwhere.

author: HwAoRrDk
author_rank: Super Contributor
timestamp: August 11, 2022, 08:46:05 pm
content: Thanks for your help. My mind has been running in circles trying to make sense of this stuff today.I had actually started reading some of the links in the .dts file comments, as well as theRaspberry Pi docs, which covers a lot of the stuff mentioned elsewhere.Quote from: Nominal Animal on August 11, 2022, 07:19:28 pmOkay, thanks for confirming. Since posting I did come across a description of the '@' syntax as being for unit-address, but it's hard to know whether things that have the same number are correlated, or it's just coincidence but otherwise unrelated, or what.This is part of the larger confusion I'm having - coming at this as a noob, it's so difficult to understand what are names/labels/IDs that have been devised and specified only within the .dts file, and what are references to other pre-existing things elsewhere.Quote from: Nominal Animal on August 11, 2022, 07:19:28 pmActually, that documentdoesn'texplain the<&gpio ...>specifier - it only says "OF device-tree gpio specification" (WTF does "OF" stand for?).But I have now found yet another Linux kernel doc that does:https://www.kernel.org/doc/Documentation/devicetree/bindings/gpio/gpio.txt.It seems the state 'cell' is actually a bit-field, of which active-high/low is only 1 flag. Seems there is others for push-pull, open-drain, etc. but I assume it's okay to leave them all zero (as they'll be when specifying a 0/1 decimal value for state).Can I actually use the constant symbolGPIO_ACTIVE_LOWinstead, or does that depend on some include somewhere?Quote from: Nominal Animal on August 11, 2022, 07:19:28 pmThank you for being so mindful of my physiological and mental wellbeing.Quote from: Nominal Animal on August 11, 2022, 07:19:28 pmOkay, so ':4' (or ':0') is an offset... relative to what exactly? I assume that<&button>refers to the same label declared on line 54, and similar for others (<&shutdown_button>, line 38;<&pin_state>, line 27). But thegpioselement of thebuttonblock only has 3 elements, so how can the offset be 4?! And I still don't understand what an offset of zero into 'reg' is? What is 'reg'?

author: Nominal Animal
author_rank: Super Contributor
timestamp: August 12, 2022, 12:40:22 am
content: Quote from: HwAoRrDk on August 11, 2022, 08:46:05 pmIt's doubly hard when you need to do a real-world change, and would rather go on withthatthan try reading "documentation" often written by humans who perhaps would be better doing something else but do mean well.At least, it is for me.Quote from: HwAoRrDk on August 11, 2022, 08:46:05 pmI suspect the original intent is to make sure that node identifiers are unique; that two identifiers, if they are the same, always and for sure refer to the same node. I could be wrong, though.Quote from: HwAoRrDk on August 11, 2022, 08:46:05 pmI can sympathise. When trying to unravel this kind of stuff, I look for real-world examples I can test and investigate, and compare against the descriptions. It is slow going, unless you have a virtual machine (since those can boot in fractions of a second). Even then, it takes time.Quote from: HwAoRrDk on August 11, 2022, 08:46:05 pmOpen Firmware. That's where the entire idea of a device tree comes from.Quote from: HwAoRrDk on August 11, 2022, 08:46:05 pmThey are available if you#include <dt-bindings/gpio/gpio.h>.Quote from: HwAoRrDk on August 11, 2022, 08:46:05 pmI thought it would be useful to know there was a positive purpose behind the varying tone.Bah, get off my lawn you irreverent whippersnapper. It's time for my nap anyway.Quote from: HwAoRrDk on August 11, 2022, 08:46:05 pm"gpios:4" refers tothe fifth byte in the gpios property. The offset is always in bytes, the delimiter defines the size of the target. (I don't get why RPi uses "gpios:4" here either, but a lot of their code makes little sense anyway.)regis a property that can override the unit-address part, or refer to the unit-address part when used in relation to some node.That is,<&pin_state>,"reg:0"refers to the unit-address part of thepin_statenode in the same section.There are multiple entries in this list because when one changes the pin number, it has to be changed at multiple places. This overlay snippet lists those places.

author: HwAoRrDk
author_rank: Super Contributor
timestamp: August 12, 2022, 01:24:06 pm
content: Quote from: Nominal Animal on August 12, 2022, 12:40:22 amBut that's a C thing. I was talking about DTS/include/statements, or whatever.Quote from: Nominal Animal on August 12, 2022, 12:40:22 amThat seems... crazy. That means you have to have intimate knowledge of the target property value. That'd be like in C having to access struct members by byte offset rather than name - you'd need to know how the compiler had organised that particular struct.So, if I am interpreting things correctly,"gpios:4"is saying "access from the 5th byte onwards (at offset 4) of the 'gpios' property and interpret it as a 32-bit integer", regardless of whatever structure that property may have. I guess that makes sense for<&gpio 3 1>if it is a 'cells' array consisting of 32-bit values. A byte offset of 4 will indeed access the second 'cell', which is the pin number.Quote from: Nominal Animal on August 12, 2022, 12:40:22 amAh, I see now. Thanks.I wonder why it's called 'reg'. That makes me think 'register', but I doubt we're dealing with hardware registers here.Edit:After reading the 'Node Names' section ofhttps://elinux.org/Device_Tree_Usage,I get it now - 'reg' is animpliedproperty that each (every?) node with a unit-address has that is equal to the address, even when not explicitly specified.

author: Nominal Animal
author_rank: Super Contributor
timestamp: August 13, 2022, 12:36:59 am
content: Quote from: HwAoRrDk on August 12, 2022, 01:24:06 pmEh?At least the ones in the Linux kernel tree support#includeand#define. Even the one forRaspberry Pi Model 4 Buses them.Quote from: HwAoRrDk on August 12, 2022, 01:24:06 pmYes, I agree. Remember, this entire__overrides__facililty seems to only be used with RPis, so having some Broadcom inanity in them is to be expected.I do believe the idea is that thegpiosproperty consists of an unsigned 32-bit identifier (referring to thegpionode), followed by two 32-bit unsigned 32-byte values: the pin number, and the active state identifier. Thus,<&button>,"gpios:4"refers to the pin number in the gpios property of the button node, and<&button>,"gpios:8"refers to the active state identifier in the gpios property of the button node. This seems to match the DTS in question (linked to in your first post).Quote from: HwAoRrDk on August 12, 2022, 01:24:06 pmYes, except DT does not make any distinction between implied and explicit properties.Anyway, the eLinux page and linux kernel docs explain things much better than I can; I'm definitely not a Linux device tree syntax expert.Probably should have not posted, but I just couldn't help myself.

author: HwAoRrDk
author_rank: Super Contributor
timestamp: August 13, 2022, 12:58:07 pm
content: Quote from: Nominal Animal on August 13, 2022, 12:36:59 amHuh. So they do. So why does/include/exist then?Is the device tree compiler just some bastardisation of the C pre-processor, which is translating down to C code and compiling, or something like that?

author: Nominal Animal
author_rank: Super Contributor
timestamp: August 13, 2022, 01:42:49 pm
content: Quote from: HwAoRrDk on August 13, 2022, 12:58:07 pmActually, it's the other way around. Linux dts files use#include, because they're built using the kernel build machinery.The dtc in Linux kernel supports both.Quote from: HwAoRrDk on August 13, 2022, 12:58:07 pmNo. It's a proper compiler built using flex and bison.