Date: Sat, 17 Feb 2018 22:25:04 -0800 From: Oleksandr Tymoshenko <gonzo@bluezbox.com> To: arch@freebsd.org Subject: Inconsistencies in OF_* functions return values Message-ID: <20180218062504.GA3226@bluezbox.com>
next in thread | raw e-mail | index | archive | help
Hello, I've been writing documentation for Open Firmware API (OF_* functions) and found some inconsistencies. As far as I understand OF_* functions are used to access device tree in abstract way and mostly serve as wrappers to methods in concrete implementations. There are two implementations at the moment: standard Open Firmware and FDT. Nodes in device tree represented by opaque integer type phandle_t. So whenever function should return reference to the node it returns phandle_t value. The problem is that error reporting is not consistent across concrete implementations. Just as error checks in API consumer code. Standard Open Firmware implementations of tree navigations functions OF_peer, OF_child, OF_parent return -1 in case of internal error and just passes value returned by succefull call to firmware. FDT implementations return 0 to indicate both errors and absense of requested node. OF_finddevice in Standard OF acts like navigation functions: -1 and pass through. OF_finddevice in FDT returns -1 both on error and if path can't be found. API consumers of navigation functions are more or less consistently check for 0. There are two code instances that check for -1. API consumers for OF_finddevice are all over the place. Some check for 0, some for -1, some for both. Also phandle_t is uint32_t so consumer code can't be just converted to if (node > 0) ... I didn't find any reserved values for phandle in FDT specification [1]. The only requirement for it is to be unique within device tree. So in theory 0 is also valid phandle_t. In practice both GNU dtc and our own dtc start numbering nodes from 1. I think the right way to fix this is to consistently use 0 to indicate error or "no node" situation. I don't have enough historical insight about OpenFirmware to claim that this approach is compatible with older standards. I'd appreciate input on this topic from people who actually work with non-FDT implementation of OF_ API. [1] https://github.com/devicetree-org/devicetree-specification/releases/tag/v0.2 -- gonzo
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20180218062504.GA3226>