libfdt.h 72 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048
  1. /* SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) */
  2. #ifndef LIBFDT_H
  3. #define LIBFDT_H
  4. /*
  5. * libfdt - Flat Device Tree manipulation
  6. * Copyright (C) 2006 David Gibson, IBM Corporation.
  7. */
  8. #include "libfdt_env.h"
  9. #include "fdt.h"
  10. #define FDT_FIRST_SUPPORTED_VERSION 0x02
  11. #define FDT_LAST_SUPPORTED_VERSION 0x11
  12. /* Error codes: informative error codes */
  13. #define FDT_ERR_NOTFOUND 1
  14. /* FDT_ERR_NOTFOUND: The requested node or property does not exist */
  15. #define FDT_ERR_EXISTS 2
  16. /* FDT_ERR_EXISTS: Attempted to create a node or property which
  17. * already exists */
  18. #define FDT_ERR_NOSPACE 3
  19. /* FDT_ERR_NOSPACE: Operation needed to expand the device
  20. * tree, but its buffer did not have sufficient space to
  21. * contain the expanded tree. Use fdt_open_into() to move the
  22. * device tree to a buffer with more space. */
  23. /* Error codes: codes for bad parameters */
  24. #define FDT_ERR_BADOFFSET 4
  25. /* FDT_ERR_BADOFFSET: Function was passed a structure block
  26. * offset which is out-of-bounds, or which points to an
  27. * unsuitable part of the structure for the operation. */
  28. #define FDT_ERR_BADPATH 5
  29. /* FDT_ERR_BADPATH: Function was passed a badly formatted path
  30. * (e.g. missing a leading / for a function which requires an
  31. * absolute path) */
  32. #define FDT_ERR_BADPHANDLE 6
  33. /* FDT_ERR_BADPHANDLE: Function was passed an invalid phandle.
  34. * This can be caused either by an invalid phandle property
  35. * length, or the phandle value was either 0 or -1, which are
  36. * not permitted. */
  37. #define FDT_ERR_BADSTATE 7
  38. /* FDT_ERR_BADSTATE: Function was passed an incomplete device
  39. * tree created by the sequential-write functions, which is
  40. * not sufficiently complete for the requested operation. */
  41. /* Error codes: codes for bad device tree blobs */
  42. #define FDT_ERR_TRUNCATED 8
  43. /* FDT_ERR_TRUNCATED: FDT or a sub-block is improperly
  44. * terminated (overflows, goes outside allowed bounds, or
  45. * isn't properly terminated). */
  46. #define FDT_ERR_BADMAGIC 9
  47. /* FDT_ERR_BADMAGIC: Given "device tree" appears not to be a
  48. * device tree at all - it is missing the flattened device
  49. * tree magic number. */
  50. #define FDT_ERR_BADVERSION 10
  51. /* FDT_ERR_BADVERSION: Given device tree has a version which
  52. * can't be handled by the requested operation. For
  53. * read-write functions, this may mean that fdt_open_into() is
  54. * required to convert the tree to the expected version. */
  55. #define FDT_ERR_BADSTRUCTURE 11
  56. /* FDT_ERR_BADSTRUCTURE: Given device tree has a corrupt
  57. * structure block or other serious error (e.g. misnested
  58. * nodes, or subnodes preceding properties). */
  59. #define FDT_ERR_BADLAYOUT 12
  60. /* FDT_ERR_BADLAYOUT: For read-write functions, the given
  61. * device tree has it's sub-blocks in an order that the
  62. * function can't handle (memory reserve map, then structure,
  63. * then strings). Use fdt_open_into() to reorganize the tree
  64. * into a form suitable for the read-write operations. */
  65. /* "Can't happen" error indicating a bug in libfdt */
  66. #define FDT_ERR_INTERNAL 13
  67. /* FDT_ERR_INTERNAL: libfdt has failed an internal assertion.
  68. * Should never be returned, if it is, it indicates a bug in
  69. * libfdt itself. */
  70. /* Errors in device tree content */
  71. #define FDT_ERR_BADNCELLS 14
  72. /* FDT_ERR_BADNCELLS: Device tree has a #address-cells, #size-cells
  73. * or similar property with a bad format or value */
  74. #define FDT_ERR_BADVALUE 15
  75. /* FDT_ERR_BADVALUE: Device tree has a property with an unexpected
  76. * value. For example: a property expected to contain a string list
  77. * is not NUL-terminated within the length of its value. */
  78. #define FDT_ERR_BADOVERLAY 16
  79. /* FDT_ERR_BADOVERLAY: The device tree overlay, while
  80. * correctly structured, cannot be applied due to some
  81. * unexpected or missing value, property or node. */
  82. #define FDT_ERR_NOPHANDLES 17
  83. /* FDT_ERR_NOPHANDLES: The device tree doesn't have any
  84. * phandle available anymore without causing an overflow */
  85. #define FDT_ERR_BADFLAGS 18
  86. /* FDT_ERR_BADFLAGS: The function was passed a flags field that
  87. * contains invalid flags or an invalid combination of flags. */
  88. #define FDT_ERR_MAX 18
  89. /* constants */
  90. #define FDT_MAX_PHANDLE 0xfffffffe
  91. /* Valid values for phandles range from 1 to 2^32-2. */
  92. /**********************************************************************/
  93. /* Low-level functions (you probably don't need these) */
  94. /**********************************************************************/
  95. #ifndef SWIG /* This function is not useful in Python */
  96. const void *fdt_offset_ptr(const void *fdt, int offset, unsigned int checklen);
  97. #endif
  98. static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)
  99. {
  100. return (void *)(uintptr_t)fdt_offset_ptr(fdt, offset, checklen);
  101. }
  102. uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);
  103. static inline void fdt32_st(void *property, uint32_t value)
  104. {
  105. uint8_t *bp = (uint8_t *)property;
  106. bp[0] = value >> 24;
  107. bp[1] = (value >> 16) & 0xff;
  108. bp[2] = (value >> 8) & 0xff;
  109. bp[3] = value & 0xff;
  110. }
  111. static inline void fdt64_st(void *property, uint64_t value)
  112. {
  113. uint8_t *bp = (uint8_t *)property;
  114. bp[0] = value >> 56;
  115. bp[1] = (value >> 48) & 0xff;
  116. bp[2] = (value >> 40) & 0xff;
  117. bp[3] = (value >> 32) & 0xff;
  118. bp[4] = (value >> 24) & 0xff;
  119. bp[5] = (value >> 16) & 0xff;
  120. bp[6] = (value >> 8) & 0xff;
  121. bp[7] = value & 0xff;
  122. }
  123. /**********************************************************************/
  124. /* Traversal functions */
  125. /**********************************************************************/
  126. int fdt_next_node(const void *fdt, int offset, int *depth);
  127. /**
  128. * fdt_first_subnode() - get offset of first direct subnode
  129. *
  130. * @fdt: FDT blob
  131. * @offset: Offset of node to check
  132. * @return offset of first subnode, or -FDT_ERR_NOTFOUND if there is none
  133. */
  134. int fdt_first_subnode(const void *fdt, int offset);
  135. /**
  136. * fdt_next_subnode() - get offset of next direct subnode
  137. *
  138. * After first calling fdt_first_subnode(), call this function repeatedly to
  139. * get direct subnodes of a parent node.
  140. *
  141. * @fdt: FDT blob
  142. * @offset: Offset of previous subnode
  143. * @return offset of next subnode, or -FDT_ERR_NOTFOUND if there are no more
  144. * subnodes
  145. */
  146. int fdt_next_subnode(const void *fdt, int offset);
  147. /**
  148. * fdt_for_each_subnode - iterate over all subnodes of a parent
  149. *
  150. * @node: child node (int, lvalue)
  151. * @fdt: FDT blob (const void *)
  152. * @parent: parent node (int)
  153. *
  154. * This is actually a wrapper around a for loop and would be used like so:
  155. *
  156. * fdt_for_each_subnode(node, fdt, parent) {
  157. * Use node
  158. * ...
  159. * }
  160. *
  161. * if ((node < 0) && (node != -FDT_ERR_NOTFOUND)) {
  162. * Error handling
  163. * }
  164. *
  165. * Note that this is implemented as a macro and @node is used as
  166. * iterator in the loop. The parent variable be constant or even a
  167. * literal.
  168. *
  169. */
  170. #define fdt_for_each_subnode(node, fdt, parent) \
  171. for (node = fdt_first_subnode(fdt, parent); \
  172. node >= 0; \
  173. node = fdt_next_subnode(fdt, node))
  174. /**********************************************************************/
  175. /* General functions */
  176. /**********************************************************************/
  177. #define fdt_get_header(fdt, field) \
  178. (fdt32_to_cpu(((const struct fdt_header *)(fdt))->field))
  179. #define fdt_magic(fdt) (fdt_get_header(fdt, magic))
  180. #define fdt_totalsize(fdt) (fdt_get_header(fdt, totalsize))
  181. #define fdt_off_dt_struct(fdt) (fdt_get_header(fdt, off_dt_struct))
  182. #define fdt_off_dt_strings(fdt) (fdt_get_header(fdt, off_dt_strings))
  183. #define fdt_off_mem_rsvmap(fdt) (fdt_get_header(fdt, off_mem_rsvmap))
  184. #define fdt_version(fdt) (fdt_get_header(fdt, version))
  185. #define fdt_last_comp_version(fdt) (fdt_get_header(fdt, last_comp_version))
  186. #define fdt_boot_cpuid_phys(fdt) (fdt_get_header(fdt, boot_cpuid_phys))
  187. #define fdt_size_dt_strings(fdt) (fdt_get_header(fdt, size_dt_strings))
  188. #define fdt_size_dt_struct(fdt) (fdt_get_header(fdt, size_dt_struct))
  189. #define fdt_set_hdr_(name) \
  190. static inline void fdt_set_##name(void *fdt, uint32_t val) \
  191. { \
  192. struct fdt_header *fdth = (struct fdt_header *)fdt; \
  193. fdth->name = cpu_to_fdt32(val); \
  194. }
  195. fdt_set_hdr_(magic);
  196. fdt_set_hdr_(totalsize);
  197. fdt_set_hdr_(off_dt_struct);
  198. fdt_set_hdr_(off_dt_strings);
  199. fdt_set_hdr_(off_mem_rsvmap);
  200. fdt_set_hdr_(version);
  201. fdt_set_hdr_(last_comp_version);
  202. fdt_set_hdr_(boot_cpuid_phys);
  203. fdt_set_hdr_(size_dt_strings);
  204. fdt_set_hdr_(size_dt_struct);
  205. #undef fdt_set_hdr_
  206. /**
  207. * fdt_header_size - return the size of the tree's header
  208. * @fdt: pointer to a flattened device tree
  209. */
  210. size_t fdt_header_size(const void *fdt);
  211. /**
  212. * fdt_header_size_ - internal function which takes a version number
  213. */
  214. size_t fdt_header_size_(uint32_t version);
  215. /**
  216. * fdt_check_header - sanity check a device tree header
  217. * @fdt: pointer to data which might be a flattened device tree
  218. *
  219. * fdt_check_header() checks that the given buffer contains what
  220. * appears to be a flattened device tree, and that the header contains
  221. * valid information (to the extent that can be determined from the
  222. * header alone).
  223. *
  224. * returns:
  225. * 0, if the buffer appears to contain a valid device tree
  226. * -FDT_ERR_BADMAGIC,
  227. * -FDT_ERR_BADVERSION,
  228. * -FDT_ERR_BADSTATE,
  229. * -FDT_ERR_TRUNCATED, standard meanings, as above
  230. */
  231. int fdt_check_header(const void *fdt);
  232. /**
  233. * fdt_move - move a device tree around in memory
  234. * @fdt: pointer to the device tree to move
  235. * @buf: pointer to memory where the device is to be moved
  236. * @bufsize: size of the memory space at buf
  237. *
  238. * fdt_move() relocates, if possible, the device tree blob located at
  239. * fdt to the buffer at buf of size bufsize. The buffer may overlap
  240. * with the existing device tree blob at fdt. Therefore,
  241. * fdt_move(fdt, fdt, fdt_totalsize(fdt))
  242. * should always succeed.
  243. *
  244. * returns:
  245. * 0, on success
  246. * -FDT_ERR_NOSPACE, bufsize is insufficient to contain the device tree
  247. * -FDT_ERR_BADMAGIC,
  248. * -FDT_ERR_BADVERSION,
  249. * -FDT_ERR_BADSTATE, standard meanings
  250. */
  251. int fdt_move(const void *fdt, void *buf, int bufsize);
  252. /**********************************************************************/
  253. /* Read-only functions */
  254. /**********************************************************************/
  255. int fdt_check_full(const void *fdt, size_t bufsize);
  256. /**
  257. * fdt_get_string - retrieve a string from the strings block of a device tree
  258. * @fdt: pointer to the device tree blob
  259. * @stroffset: offset of the string within the strings block (native endian)
  260. * @lenp: optional pointer to return the string's length
  261. *
  262. * fdt_get_string() retrieves a pointer to a single string from the
  263. * strings block of the device tree blob at fdt, and optionally also
  264. * returns the string's length in *lenp.
  265. *
  266. * returns:
  267. * a pointer to the string, on success
  268. * NULL, if stroffset is out of bounds, or doesn't point to a valid string
  269. */
  270. const char *fdt_get_string(const void *fdt, int stroffset, int *lenp);
  271. /**
  272. * fdt_string - retrieve a string from the strings block of a device tree
  273. * @fdt: pointer to the device tree blob
  274. * @stroffset: offset of the string within the strings block (native endian)
  275. *
  276. * fdt_string() retrieves a pointer to a single string from the
  277. * strings block of the device tree blob at fdt.
  278. *
  279. * returns:
  280. * a pointer to the string, on success
  281. * NULL, if stroffset is out of bounds, or doesn't point to a valid string
  282. */
  283. const char *fdt_string(const void *fdt, int stroffset);
  284. /**
  285. * fdt_find_max_phandle - find and return the highest phandle in a tree
  286. * @fdt: pointer to the device tree blob
  287. * @phandle: return location for the highest phandle value found in the tree
  288. *
  289. * fdt_find_max_phandle() finds the highest phandle value in the given device
  290. * tree. The value returned in @phandle is only valid if the function returns
  291. * success.
  292. *
  293. * returns:
  294. * 0 on success or a negative error code on failure
  295. */
  296. int fdt_find_max_phandle(const void *fdt, uint32_t *phandle);
  297. /**
  298. * fdt_get_max_phandle - retrieves the highest phandle in a tree
  299. * @fdt: pointer to the device tree blob
  300. *
  301. * fdt_get_max_phandle retrieves the highest phandle in the given
  302. * device tree. This will ignore badly formatted phandles, or phandles
  303. * with a value of 0 or -1.
  304. *
  305. * This function is deprecated in favour of fdt_find_max_phandle().
  306. *
  307. * returns:
  308. * the highest phandle on success
  309. * 0, if no phandle was found in the device tree
  310. * -1, if an error occurred
  311. */
  312. static inline uint32_t fdt_get_max_phandle(const void *fdt)
  313. {
  314. uint32_t phandle;
  315. int err;
  316. err = fdt_find_max_phandle(fdt, &phandle);
  317. if (err < 0)
  318. return (uint32_t)-1;
  319. return phandle;
  320. }
  321. /**
  322. * fdt_generate_phandle - return a new, unused phandle for a device tree blob
  323. * @fdt: pointer to the device tree blob
  324. * @phandle: return location for the new phandle
  325. *
  326. * Walks the device tree blob and looks for the highest phandle value. On
  327. * success, the new, unused phandle value (one higher than the previously
  328. * highest phandle value in the device tree blob) will be returned in the
  329. * @phandle parameter.
  330. *
  331. * Returns:
  332. * 0 on success or a negative error-code on failure
  333. */
  334. int fdt_generate_phandle(const void *fdt, uint32_t *phandle);
  335. /**
  336. * fdt_num_mem_rsv - retrieve the number of memory reserve map entries
  337. * @fdt: pointer to the device tree blob
  338. *
  339. * Returns the number of entries in the device tree blob's memory
  340. * reservation map. This does not include the terminating 0,0 entry
  341. * or any other (0,0) entries reserved for expansion.
  342. *
  343. * returns:
  344. * the number of entries
  345. */
  346. int fdt_num_mem_rsv(const void *fdt);
  347. /**
  348. * fdt_get_mem_rsv - retrieve one memory reserve map entry
  349. * @fdt: pointer to the device tree blob
  350. * @address, @size: pointers to 64-bit variables
  351. *
  352. * On success, *address and *size will contain the address and size of
  353. * the n-th reserve map entry from the device tree blob, in
  354. * native-endian format.
  355. *
  356. * returns:
  357. * 0, on success
  358. * -FDT_ERR_BADMAGIC,
  359. * -FDT_ERR_BADVERSION,
  360. * -FDT_ERR_BADSTATE, standard meanings
  361. */
  362. int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);
  363. /**
  364. * fdt_subnode_offset_namelen - find a subnode based on substring
  365. * @fdt: pointer to the device tree blob
  366. * @parentoffset: structure block offset of a node
  367. * @name: name of the subnode to locate
  368. * @namelen: number of characters of name to consider
  369. *
  370. * Identical to fdt_subnode_offset(), but only examine the first
  371. * namelen characters of name for matching the subnode name. This is
  372. * useful for finding subnodes based on a portion of a larger string,
  373. * such as a full path.
  374. */
  375. #ifndef SWIG /* Not available in Python */
  376. int fdt_subnode_offset_namelen(const void *fdt, int parentoffset,
  377. const char *name, int namelen);
  378. #endif
  379. /**
  380. * fdt_subnode_offset - find a subnode of a given node
  381. * @fdt: pointer to the device tree blob
  382. * @parentoffset: structure block offset of a node
  383. * @name: name of the subnode to locate
  384. *
  385. * fdt_subnode_offset() finds a subnode of the node at structure block
  386. * offset parentoffset with the given name. name may include a unit
  387. * address, in which case fdt_subnode_offset() will find the subnode
  388. * with that unit address, or the unit address may be omitted, in
  389. * which case fdt_subnode_offset() will find an arbitrary subnode
  390. * whose name excluding unit address matches the given name.
  391. *
  392. * returns:
  393. * structure block offset of the requested subnode (>=0), on success
  394. * -FDT_ERR_NOTFOUND, if the requested subnode does not exist
  395. * -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE
  396. * tag
  397. * -FDT_ERR_BADMAGIC,
  398. * -FDT_ERR_BADVERSION,
  399. * -FDT_ERR_BADSTATE,
  400. * -FDT_ERR_BADSTRUCTURE,
  401. * -FDT_ERR_TRUNCATED, standard meanings.
  402. */
  403. int fdt_subnode_offset(const void *fdt, int parentoffset, const char *name);
  404. /**
  405. * fdt_path_offset_namelen - find a tree node by its full path
  406. * @fdt: pointer to the device tree blob
  407. * @path: full path of the node to locate
  408. * @namelen: number of characters of path to consider
  409. *
  410. * Identical to fdt_path_offset(), but only consider the first namelen
  411. * characters of path as the path name.
  412. */
  413. #ifndef SWIG /* Not available in Python */
  414. int fdt_path_offset_namelen(const void *fdt, const char *path, int namelen);
  415. #endif
  416. /**
  417. * fdt_path_offset - find a tree node by its full path
  418. * @fdt: pointer to the device tree blob
  419. * @path: full path of the node to locate
  420. *
  421. * fdt_path_offset() finds a node of a given path in the device tree.
  422. * Each path component may omit the unit address portion, but the
  423. * results of this are undefined if any such path component is
  424. * ambiguous (that is if there are multiple nodes at the relevant
  425. * level matching the given component, differentiated only by unit
  426. * address).
  427. *
  428. * returns:
  429. * structure block offset of the node with the requested path (>=0), on
  430. * success
  431. * -FDT_ERR_BADPATH, given path does not begin with '/' or is invalid
  432. * -FDT_ERR_NOTFOUND, if the requested node does not exist
  433. * -FDT_ERR_BADMAGIC,
  434. * -FDT_ERR_BADVERSION,
  435. * -FDT_ERR_BADSTATE,
  436. * -FDT_ERR_BADSTRUCTURE,
  437. * -FDT_ERR_TRUNCATED, standard meanings.
  438. */
  439. int fdt_path_offset(const void *fdt, const char *path);
  440. /**
  441. * fdt_get_name - retrieve the name of a given node
  442. * @fdt: pointer to the device tree blob
  443. * @nodeoffset: structure block offset of the starting node
  444. * @lenp: pointer to an integer variable (will be overwritten) or NULL
  445. *
  446. * fdt_get_name() retrieves the name (including unit address) of the
  447. * device tree node at structure block offset nodeoffset. If lenp is
  448. * non-NULL, the length of this name is also returned, in the integer
  449. * pointed to by lenp.
  450. *
  451. * returns:
  452. * pointer to the node's name, on success
  453. * If lenp is non-NULL, *lenp contains the length of that name
  454. * (>=0)
  455. * NULL, on error
  456. * if lenp is non-NULL *lenp contains an error code (<0):
  457. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
  458. * tag
  459. * -FDT_ERR_BADMAGIC,
  460. * -FDT_ERR_BADVERSION,
  461. * -FDT_ERR_BADSTATE, standard meanings
  462. */
  463. const char *fdt_get_name(const void *fdt, int nodeoffset, int *lenp);
  464. /**
  465. * fdt_first_property_offset - find the offset of a node's first property
  466. * @fdt: pointer to the device tree blob
  467. * @nodeoffset: structure block offset of a node
  468. *
  469. * fdt_first_property_offset() finds the first property of the node at
  470. * the given structure block offset.
  471. *
  472. * returns:
  473. * structure block offset of the property (>=0), on success
  474. * -FDT_ERR_NOTFOUND, if the requested node has no properties
  475. * -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_BEGIN_NODE tag
  476. * -FDT_ERR_BADMAGIC,
  477. * -FDT_ERR_BADVERSION,
  478. * -FDT_ERR_BADSTATE,
  479. * -FDT_ERR_BADSTRUCTURE,
  480. * -FDT_ERR_TRUNCATED, standard meanings.
  481. */
  482. int fdt_first_property_offset(const void *fdt, int nodeoffset);
  483. /**
  484. * fdt_next_property_offset - step through a node's properties
  485. * @fdt: pointer to the device tree blob
  486. * @offset: structure block offset of a property
  487. *
  488. * fdt_next_property_offset() finds the property immediately after the
  489. * one at the given structure block offset. This will be a property
  490. * of the same node as the given property.
  491. *
  492. * returns:
  493. * structure block offset of the next property (>=0), on success
  494. * -FDT_ERR_NOTFOUND, if the given property is the last in its node
  495. * -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_PROP tag
  496. * -FDT_ERR_BADMAGIC,
  497. * -FDT_ERR_BADVERSION,
  498. * -FDT_ERR_BADSTATE,
  499. * -FDT_ERR_BADSTRUCTURE,
  500. * -FDT_ERR_TRUNCATED, standard meanings.
  501. */
  502. int fdt_next_property_offset(const void *fdt, int offset);
  503. /**
  504. * fdt_for_each_property_offset - iterate over all properties of a node
  505. *
  506. * @property_offset: property offset (int, lvalue)
  507. * @fdt: FDT blob (const void *)
  508. * @node: node offset (int)
  509. *
  510. * This is actually a wrapper around a for loop and would be used like so:
  511. *
  512. * fdt_for_each_property_offset(property, fdt, node) {
  513. * Use property
  514. * ...
  515. * }
  516. *
  517. * if ((property < 0) && (property != -FDT_ERR_NOTFOUND)) {
  518. * Error handling
  519. * }
  520. *
  521. * Note that this is implemented as a macro and property is used as
  522. * iterator in the loop. The node variable can be constant or even a
  523. * literal.
  524. */
  525. #define fdt_for_each_property_offset(property, fdt, node) \
  526. for (property = fdt_first_property_offset(fdt, node); \
  527. property >= 0; \
  528. property = fdt_next_property_offset(fdt, property))
  529. /**
  530. * fdt_get_property_by_offset - retrieve the property at a given offset
  531. * @fdt: pointer to the device tree blob
  532. * @offset: offset of the property to retrieve
  533. * @lenp: pointer to an integer variable (will be overwritten) or NULL
  534. *
  535. * fdt_get_property_by_offset() retrieves a pointer to the
  536. * fdt_property structure within the device tree blob at the given
  537. * offset. If lenp is non-NULL, the length of the property value is
  538. * also returned, in the integer pointed to by lenp.
  539. *
  540. * Note that this code only works on device tree versions >= 16. fdt_getprop()
  541. * works on all versions.
  542. *
  543. * returns:
  544. * pointer to the structure representing the property
  545. * if lenp is non-NULL, *lenp contains the length of the property
  546. * value (>=0)
  547. * NULL, on error
  548. * if lenp is non-NULL, *lenp contains an error code (<0):
  549. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
  550. * -FDT_ERR_BADMAGIC,
  551. * -FDT_ERR_BADVERSION,
  552. * -FDT_ERR_BADSTATE,
  553. * -FDT_ERR_BADSTRUCTURE,
  554. * -FDT_ERR_TRUNCATED, standard meanings
  555. */
  556. const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
  557. int offset,
  558. int *lenp);
  559. /**
  560. * fdt_get_property_namelen - find a property based on substring
  561. * @fdt: pointer to the device tree blob
  562. * @nodeoffset: offset of the node whose property to find
  563. * @name: name of the property to find
  564. * @namelen: number of characters of name to consider
  565. * @lenp: pointer to an integer variable (will be overwritten) or NULL
  566. *
  567. * Identical to fdt_get_property(), but only examine the first namelen
  568. * characters of name for matching the property name.
  569. */
  570. #ifndef SWIG /* Not available in Python */
  571. const struct fdt_property *fdt_get_property_namelen(const void *fdt,
  572. int nodeoffset,
  573. const char *name,
  574. int namelen, int *lenp);
  575. #endif
  576. /**
  577. * fdt_get_property - find a given property in a given node
  578. * @fdt: pointer to the device tree blob
  579. * @nodeoffset: offset of the node whose property to find
  580. * @name: name of the property to find
  581. * @lenp: pointer to an integer variable (will be overwritten) or NULL
  582. *
  583. * fdt_get_property() retrieves a pointer to the fdt_property
  584. * structure within the device tree blob corresponding to the property
  585. * named 'name' of the node at offset nodeoffset. If lenp is
  586. * non-NULL, the length of the property value is also returned, in the
  587. * integer pointed to by lenp.
  588. *
  589. * returns:
  590. * pointer to the structure representing the property
  591. * if lenp is non-NULL, *lenp contains the length of the property
  592. * value (>=0)
  593. * NULL, on error
  594. * if lenp is non-NULL, *lenp contains an error code (<0):
  595. * -FDT_ERR_NOTFOUND, node does not have named property
  596. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
  597. * tag
  598. * -FDT_ERR_BADMAGIC,
  599. * -FDT_ERR_BADVERSION,
  600. * -FDT_ERR_BADSTATE,
  601. * -FDT_ERR_BADSTRUCTURE,
  602. * -FDT_ERR_TRUNCATED, standard meanings
  603. */
  604. const struct fdt_property *fdt_get_property(const void *fdt, int nodeoffset,
  605. const char *name, int *lenp);
  606. static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,
  607. const char *name,
  608. int *lenp)
  609. {
  610. return (struct fdt_property *)(uintptr_t)
  611. fdt_get_property(fdt, nodeoffset, name, lenp);
  612. }
  613. /**
  614. * fdt_getprop_by_offset - retrieve the value of a property at a given offset
  615. * @fdt: pointer to the device tree blob
  616. * @offset: offset of the property to read
  617. * @namep: pointer to a string variable (will be overwritten) or NULL
  618. * @lenp: pointer to an integer variable (will be overwritten) or NULL
  619. *
  620. * fdt_getprop_by_offset() retrieves a pointer to the value of the
  621. * property at structure block offset 'offset' (this will be a pointer
  622. * to within the device blob itself, not a copy of the value). If
  623. * lenp is non-NULL, the length of the property value is also
  624. * returned, in the integer pointed to by lenp. If namep is non-NULL,
  625. * the property's namne will also be returned in the char * pointed to
  626. * by namep (this will be a pointer to within the device tree's string
  627. * block, not a new copy of the name).
  628. *
  629. * returns:
  630. * pointer to the property's value
  631. * if lenp is non-NULL, *lenp contains the length of the property
  632. * value (>=0)
  633. * if namep is non-NULL *namep contiains a pointer to the property
  634. * name.
  635. * NULL, on error
  636. * if lenp is non-NULL, *lenp contains an error code (<0):
  637. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
  638. * -FDT_ERR_BADMAGIC,
  639. * -FDT_ERR_BADVERSION,
  640. * -FDT_ERR_BADSTATE,
  641. * -FDT_ERR_BADSTRUCTURE,
  642. * -FDT_ERR_TRUNCATED, standard meanings
  643. */
  644. #ifndef SWIG /* This function is not useful in Python */
  645. const void *fdt_getprop_by_offset(const void *fdt, int offset,
  646. const char **namep, int *lenp);
  647. #endif
  648. /**
  649. * fdt_getprop_namelen - get property value based on substring
  650. * @fdt: pointer to the device tree blob
  651. * @nodeoffset: offset of the node whose property to find
  652. * @name: name of the property to find
  653. * @namelen: number of characters of name to consider
  654. * @lenp: pointer to an integer variable (will be overwritten) or NULL
  655. *
  656. * Identical to fdt_getprop(), but only examine the first namelen
  657. * characters of name for matching the property name.
  658. */
  659. #ifndef SWIG /* Not available in Python */
  660. const void *fdt_getprop_namelen(const void *fdt, int nodeoffset,
  661. const char *name, int namelen, int *lenp);
  662. static inline void *fdt_getprop_namelen_w(void *fdt, int nodeoffset,
  663. const char *name, int namelen,
  664. int *lenp)
  665. {
  666. return (void *)(uintptr_t)fdt_getprop_namelen(fdt, nodeoffset, name,
  667. namelen, lenp);
  668. }
  669. #endif
  670. /**
  671. * fdt_getprop - retrieve the value of a given property
  672. * @fdt: pointer to the device tree blob
  673. * @nodeoffset: offset of the node whose property to find
  674. * @name: name of the property to find
  675. * @lenp: pointer to an integer variable (will be overwritten) or NULL
  676. *
  677. * fdt_getprop() retrieves a pointer to the value of the property
  678. * named 'name' of the node at offset nodeoffset (this will be a
  679. * pointer to within the device blob itself, not a copy of the value).
  680. * If lenp is non-NULL, the length of the property value is also
  681. * returned, in the integer pointed to by lenp.
  682. *
  683. * returns:
  684. * pointer to the property's value
  685. * if lenp is non-NULL, *lenp contains the length of the property
  686. * value (>=0)
  687. * NULL, on error
  688. * if lenp is non-NULL, *lenp contains an error code (<0):
  689. * -FDT_ERR_NOTFOUND, node does not have named property
  690. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
  691. * tag
  692. * -FDT_ERR_BADMAGIC,
  693. * -FDT_ERR_BADVERSION,
  694. * -FDT_ERR_BADSTATE,
  695. * -FDT_ERR_BADSTRUCTURE,
  696. * -FDT_ERR_TRUNCATED, standard meanings
  697. */
  698. const void *fdt_getprop(const void *fdt, int nodeoffset,
  699. const char *name, int *lenp);
  700. static inline void *fdt_getprop_w(void *fdt, int nodeoffset,
  701. const char *name, int *lenp)
  702. {
  703. return (void *)(uintptr_t)fdt_getprop(fdt, nodeoffset, name, lenp);
  704. }
  705. /**
  706. * fdt_get_phandle - retrieve the phandle of a given node
  707. * @fdt: pointer to the device tree blob
  708. * @nodeoffset: structure block offset of the node
  709. *
  710. * fdt_get_phandle() retrieves the phandle of the device tree node at
  711. * structure block offset nodeoffset.
  712. *
  713. * returns:
  714. * the phandle of the node at nodeoffset, on success (!= 0, != -1)
  715. * 0, if the node has no phandle, or another error occurs
  716. */
  717. uint32_t fdt_get_phandle(const void *fdt, int nodeoffset);
  718. /**
  719. * fdt_get_alias_namelen - get alias based on substring
  720. * @fdt: pointer to the device tree blob
  721. * @name: name of the alias th look up
  722. * @namelen: number of characters of name to consider
  723. *
  724. * Identical to fdt_get_alias(), but only examine the first namelen
  725. * characters of name for matching the alias name.
  726. */
  727. #ifndef SWIG /* Not available in Python */
  728. const char *fdt_get_alias_namelen(const void *fdt,
  729. const char *name, int namelen);
  730. #endif
  731. /**
  732. * fdt_get_alias - retrieve the path referenced by a given alias
  733. * @fdt: pointer to the device tree blob
  734. * @name: name of the alias th look up
  735. *
  736. * fdt_get_alias() retrieves the value of a given alias. That is, the
  737. * value of the property named 'name' in the node /aliases.
  738. *
  739. * returns:
  740. * a pointer to the expansion of the alias named 'name', if it exists
  741. * NULL, if the given alias or the /aliases node does not exist
  742. */
  743. const char *fdt_get_alias(const void *fdt, const char *name);
  744. /**
  745. * fdt_get_path - determine the full path of a node
  746. * @fdt: pointer to the device tree blob
  747. * @nodeoffset: offset of the node whose path to find
  748. * @buf: character buffer to contain the returned path (will be overwritten)
  749. * @buflen: size of the character buffer at buf
  750. *
  751. * fdt_get_path() computes the full path of the node at offset
  752. * nodeoffset, and records that path in the buffer at buf.
  753. *
  754. * NOTE: This function is expensive, as it must scan the device tree
  755. * structure from the start to nodeoffset.
  756. *
  757. * returns:
  758. * 0, on success
  759. * buf contains the absolute path of the node at
  760. * nodeoffset, as a NUL-terminated string.
  761. * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
  762. * -FDT_ERR_NOSPACE, the path of the given node is longer than (bufsize-1)
  763. * characters and will not fit in the given buffer.
  764. * -FDT_ERR_BADMAGIC,
  765. * -FDT_ERR_BADVERSION,
  766. * -FDT_ERR_BADSTATE,
  767. * -FDT_ERR_BADSTRUCTURE, standard meanings
  768. */
  769. int fdt_get_path(const void *fdt, int nodeoffset, char *buf, int buflen);
  770. /**
  771. * fdt_supernode_atdepth_offset - find a specific ancestor of a node
  772. * @fdt: pointer to the device tree blob
  773. * @nodeoffset: offset of the node whose parent to find
  774. * @supernodedepth: depth of the ancestor to find
  775. * @nodedepth: pointer to an integer variable (will be overwritten) or NULL
  776. *
  777. * fdt_supernode_atdepth_offset() finds an ancestor of the given node
  778. * at a specific depth from the root (where the root itself has depth
  779. * 0, its immediate subnodes depth 1 and so forth). So
  780. * fdt_supernode_atdepth_offset(fdt, nodeoffset, 0, NULL);
  781. * will always return 0, the offset of the root node. If the node at
  782. * nodeoffset has depth D, then:
  783. * fdt_supernode_atdepth_offset(fdt, nodeoffset, D, NULL);
  784. * will return nodeoffset itself.
  785. *
  786. * NOTE: This function is expensive, as it must scan the device tree
  787. * structure from the start to nodeoffset.
  788. *
  789. * returns:
  790. * structure block offset of the node at node offset's ancestor
  791. * of depth supernodedepth (>=0), on success
  792. * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
  793. * -FDT_ERR_NOTFOUND, supernodedepth was greater than the depth of
  794. * nodeoffset
  795. * -FDT_ERR_BADMAGIC,
  796. * -FDT_ERR_BADVERSION,
  797. * -FDT_ERR_BADSTATE,
  798. * -FDT_ERR_BADSTRUCTURE, standard meanings
  799. */
  800. int fdt_supernode_atdepth_offset(const void *fdt, int nodeoffset,
  801. int supernodedepth, int *nodedepth);
  802. /**
  803. * fdt_node_depth - find the depth of a given node
  804. * @fdt: pointer to the device tree blob
  805. * @nodeoffset: offset of the node whose parent to find
  806. *
  807. * fdt_node_depth() finds the depth of a given node. The root node
  808. * has depth 0, its immediate subnodes depth 1 and so forth.
  809. *
  810. * NOTE: This function is expensive, as it must scan the device tree
  811. * structure from the start to nodeoffset.
  812. *
  813. * returns:
  814. * depth of the node at nodeoffset (>=0), on success
  815. * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
  816. * -FDT_ERR_BADMAGIC,
  817. * -FDT_ERR_BADVERSION,
  818. * -FDT_ERR_BADSTATE,
  819. * -FDT_ERR_BADSTRUCTURE, standard meanings
  820. */
  821. int fdt_node_depth(const void *fdt, int nodeoffset);
  822. /**
  823. * fdt_parent_offset - find the parent of a given node
  824. * @fdt: pointer to the device tree blob
  825. * @nodeoffset: offset of the node whose parent to find
  826. *
  827. * fdt_parent_offset() locates the parent node of a given node (that
  828. * is, it finds the offset of the node which contains the node at
  829. * nodeoffset as a subnode).
  830. *
  831. * NOTE: This function is expensive, as it must scan the device tree
  832. * structure from the start to nodeoffset, *twice*.
  833. *
  834. * returns:
  835. * structure block offset of the parent of the node at nodeoffset
  836. * (>=0), on success
  837. * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
  838. * -FDT_ERR_BADMAGIC,
  839. * -FDT_ERR_BADVERSION,
  840. * -FDT_ERR_BADSTATE,
  841. * -FDT_ERR_BADSTRUCTURE, standard meanings
  842. */
  843. int fdt_parent_offset(const void *fdt, int nodeoffset);
  844. /**
  845. * fdt_node_offset_by_prop_value - find nodes with a given property value
  846. * @fdt: pointer to the device tree blob
  847. * @startoffset: only find nodes after this offset
  848. * @propname: property name to check
  849. * @propval: property value to search for
  850. * @proplen: length of the value in propval
  851. *
  852. * fdt_node_offset_by_prop_value() returns the offset of the first
  853. * node after startoffset, which has a property named propname whose
  854. * value is of length proplen and has value equal to propval; or if
  855. * startoffset is -1, the very first such node in the tree.
  856. *
  857. * To iterate through all nodes matching the criterion, the following
  858. * idiom can be used:
  859. * offset = fdt_node_offset_by_prop_value(fdt, -1, propname,
  860. * propval, proplen);
  861. * while (offset != -FDT_ERR_NOTFOUND) {
  862. * // other code here
  863. * offset = fdt_node_offset_by_prop_value(fdt, offset, propname,
  864. * propval, proplen);
  865. * }
  866. *
  867. * Note the -1 in the first call to the function, if 0 is used here
  868. * instead, the function will never locate the root node, even if it
  869. * matches the criterion.
  870. *
  871. * returns:
  872. * structure block offset of the located node (>= 0, >startoffset),
  873. * on success
  874. * -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
  875. * tree after startoffset
  876. * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
  877. * -FDT_ERR_BADMAGIC,
  878. * -FDT_ERR_BADVERSION,
  879. * -FDT_ERR_BADSTATE,
  880. * -FDT_ERR_BADSTRUCTURE, standard meanings
  881. */
  882. int fdt_node_offset_by_prop_value(const void *fdt, int startoffset,
  883. const char *propname,
  884. const void *propval, int proplen);
  885. /**
  886. * fdt_node_offset_by_phandle - find the node with a given phandle
  887. * @fdt: pointer to the device tree blob
  888. * @phandle: phandle value
  889. *
  890. * fdt_node_offset_by_phandle() returns the offset of the node
  891. * which has the given phandle value. If there is more than one node
  892. * in the tree with the given phandle (an invalid tree), results are
  893. * undefined.
  894. *
  895. * returns:
  896. * structure block offset of the located node (>= 0), on success
  897. * -FDT_ERR_NOTFOUND, no node with that phandle exists
  898. * -FDT_ERR_BADPHANDLE, given phandle value was invalid (0 or -1)
  899. * -FDT_ERR_BADMAGIC,
  900. * -FDT_ERR_BADVERSION,
  901. * -FDT_ERR_BADSTATE,
  902. * -FDT_ERR_BADSTRUCTURE, standard meanings
  903. */
  904. int fdt_node_offset_by_phandle(const void *fdt, uint32_t phandle);
  905. /**
  906. * fdt_node_check_compatible: check a node's compatible property
  907. * @fdt: pointer to the device tree blob
  908. * @nodeoffset: offset of a tree node
  909. * @compatible: string to match against
  910. *
  911. *
  912. * fdt_node_check_compatible() returns 0 if the given node contains a
  913. * 'compatible' property with the given string as one of its elements,
  914. * it returns non-zero otherwise, or on error.
  915. *
  916. * returns:
  917. * 0, if the node has a 'compatible' property listing the given string
  918. * 1, if the node has a 'compatible' property, but it does not list
  919. * the given string
  920. * -FDT_ERR_NOTFOUND, if the given node has no 'compatible' property
  921. * -FDT_ERR_BADOFFSET, if nodeoffset does not refer to a BEGIN_NODE tag
  922. * -FDT_ERR_BADMAGIC,
  923. * -FDT_ERR_BADVERSION,
  924. * -FDT_ERR_BADSTATE,
  925. * -FDT_ERR_BADSTRUCTURE, standard meanings
  926. */
  927. int fdt_node_check_compatible(const void *fdt, int nodeoffset,
  928. const char *compatible);
  929. /**
  930. * fdt_node_offset_by_compatible - find nodes with a given 'compatible' value
  931. * @fdt: pointer to the device tree blob
  932. * @startoffset: only find nodes after this offset
  933. * @compatible: 'compatible' string to match against
  934. *
  935. * fdt_node_offset_by_compatible() returns the offset of the first
  936. * node after startoffset, which has a 'compatible' property which
  937. * lists the given compatible string; or if startoffset is -1, the
  938. * very first such node in the tree.
  939. *
  940. * To iterate through all nodes matching the criterion, the following
  941. * idiom can be used:
  942. * offset = fdt_node_offset_by_compatible(fdt, -1, compatible);
  943. * while (offset != -FDT_ERR_NOTFOUND) {
  944. * // other code here
  945. * offset = fdt_node_offset_by_compatible(fdt, offset, compatible);
  946. * }
  947. *
  948. * Note the -1 in the first call to the function, if 0 is used here
  949. * instead, the function will never locate the root node, even if it
  950. * matches the criterion.
  951. *
  952. * returns:
  953. * structure block offset of the located node (>= 0, >startoffset),
  954. * on success
  955. * -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
  956. * tree after startoffset
  957. * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
  958. * -FDT_ERR_BADMAGIC,
  959. * -FDT_ERR_BADVERSION,
  960. * -FDT_ERR_BADSTATE,
  961. * -FDT_ERR_BADSTRUCTURE, standard meanings
  962. */
  963. int fdt_node_offset_by_compatible(const void *fdt, int startoffset,
  964. const char *compatible);
  965. /**
  966. * fdt_stringlist_contains - check a string list property for a string
  967. * @strlist: Property containing a list of strings to check
  968. * @listlen: Length of property
  969. * @str: String to search for
  970. *
  971. * This is a utility function provided for convenience. The list contains
  972. * one or more strings, each terminated by \0, as is found in a device tree
  973. * "compatible" property.
  974. *
  975. * @return: 1 if the string is found in the list, 0 not found, or invalid list
  976. */
  977. int fdt_stringlist_contains(const char *strlist, int listlen, const char *str);
  978. /**
  979. * fdt_stringlist_count - count the number of strings in a string list
  980. * @fdt: pointer to the device tree blob
  981. * @nodeoffset: offset of a tree node
  982. * @property: name of the property containing the string list
  983. * @return:
  984. * the number of strings in the given property
  985. * -FDT_ERR_BADVALUE if the property value is not NUL-terminated
  986. * -FDT_ERR_NOTFOUND if the property does not exist
  987. */
  988. int fdt_stringlist_count(const void *fdt, int nodeoffset, const char *property);
  989. /**
  990. * fdt_stringlist_search - find a string in a string list and return its index
  991. * @fdt: pointer to the device tree blob
  992. * @nodeoffset: offset of a tree node
  993. * @property: name of the property containing the string list
  994. * @string: string to look up in the string list
  995. *
  996. * Note that it is possible for this function to succeed on property values
  997. * that are not NUL-terminated. That's because the function will stop after
  998. * finding the first occurrence of @string. This can for example happen with
  999. * small-valued cell properties, such as #address-cells, when searching for
  1000. * the empty string.
  1001. *
  1002. * @return:
  1003. * the index of the string in the list of strings
  1004. * -FDT_ERR_BADVALUE if the property value is not NUL-terminated
  1005. * -FDT_ERR_NOTFOUND if the property does not exist or does not contain
  1006. * the given string
  1007. */
  1008. int fdt_stringlist_search(const void *fdt, int nodeoffset, const char *property,
  1009. const char *string);
  1010. /**
  1011. * fdt_stringlist_get() - obtain the string at a given index in a string list
  1012. * @fdt: pointer to the device tree blob
  1013. * @nodeoffset: offset of a tree node
  1014. * @property: name of the property containing the string list
  1015. * @index: index of the string to return
  1016. * @lenp: return location for the string length or an error code on failure
  1017. *
  1018. * Note that this will successfully extract strings from properties with
  1019. * non-NUL-terminated values. For example on small-valued cell properties
  1020. * this function will return the empty string.
  1021. *
  1022. * If non-NULL, the length of the string (on success) or a negative error-code
  1023. * (on failure) will be stored in the integer pointer to by lenp.
  1024. *
  1025. * @return:
  1026. * A pointer to the string at the given index in the string list or NULL on
  1027. * failure. On success the length of the string will be stored in the memory
  1028. * location pointed to by the lenp parameter, if non-NULL. On failure one of
  1029. * the following negative error codes will be returned in the lenp parameter
  1030. * (if non-NULL):
  1031. * -FDT_ERR_BADVALUE if the property value is not NUL-terminated
  1032. * -FDT_ERR_NOTFOUND if the property does not exist
  1033. */
  1034. const char *fdt_stringlist_get(const void *fdt, int nodeoffset,
  1035. const char *property, int index,
  1036. int *lenp);
  1037. /**********************************************************************/
  1038. /* Read-only functions (addressing related) */
  1039. /**********************************************************************/
  1040. /**
  1041. * FDT_MAX_NCELLS - maximum value for #address-cells and #size-cells
  1042. *
  1043. * This is the maximum value for #address-cells, #size-cells and
  1044. * similar properties that will be processed by libfdt. IEE1275
  1045. * requires that OF implementations handle values up to 4.
  1046. * Implementations may support larger values, but in practice higher
  1047. * values aren't used.
  1048. */
  1049. #define FDT_MAX_NCELLS 4
  1050. /**
  1051. * fdt_address_cells - retrieve address size for a bus represented in the tree
  1052. * @fdt: pointer to the device tree blob
  1053. * @nodeoffset: offset of the node to find the address size for
  1054. *
  1055. * When the node has a valid #address-cells property, returns its value.
  1056. *
  1057. * returns:
  1058. * 0 <= n < FDT_MAX_NCELLS, on success
  1059. * 2, if the node has no #address-cells property
  1060. * -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
  1061. * #address-cells property
  1062. * -FDT_ERR_BADMAGIC,
  1063. * -FDT_ERR_BADVERSION,
  1064. * -FDT_ERR_BADSTATE,
  1065. * -FDT_ERR_BADSTRUCTURE,
  1066. * -FDT_ERR_TRUNCATED, standard meanings
  1067. */
  1068. int fdt_address_cells(const void *fdt, int nodeoffset);
  1069. /**
  1070. * fdt_size_cells - retrieve address range size for a bus represented in the
  1071. * tree
  1072. * @fdt: pointer to the device tree blob
  1073. * @nodeoffset: offset of the node to find the address range size for
  1074. *
  1075. * When the node has a valid #size-cells property, returns its value.
  1076. *
  1077. * returns:
  1078. * 0 <= n < FDT_MAX_NCELLS, on success
  1079. * 1, if the node has no #size-cells property
  1080. * -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
  1081. * #size-cells property
  1082. * -FDT_ERR_BADMAGIC,
  1083. * -FDT_ERR_BADVERSION,
  1084. * -FDT_ERR_BADSTATE,
  1085. * -FDT_ERR_BADSTRUCTURE,
  1086. * -FDT_ERR_TRUNCATED, standard meanings
  1087. */
  1088. int fdt_size_cells(const void *fdt, int nodeoffset);
  1089. /**********************************************************************/
  1090. /* Write-in-place functions */
  1091. /**********************************************************************/
  1092. /**
  1093. * fdt_setprop_inplace_namelen_partial - change a property's value,
  1094. * but not its size
  1095. * @fdt: pointer to the device tree blob
  1096. * @nodeoffset: offset of the node whose property to change
  1097. * @name: name of the property to change
  1098. * @namelen: number of characters of name to consider
  1099. * @idx: index of the property to change in the array
  1100. * @val: pointer to data to replace the property value with
  1101. * @len: length of the property value
  1102. *
  1103. * Identical to fdt_setprop_inplace(), but modifies the given property
  1104. * starting from the given index, and using only the first characters
  1105. * of the name. It is useful when you want to manipulate only one value of
  1106. * an array and you have a string that doesn't end with \0.
  1107. */
  1108. #ifndef SWIG /* Not available in Python */
  1109. int fdt_setprop_inplace_namelen_partial(void *fdt, int nodeoffset,
  1110. const char *name, int namelen,
  1111. uint32_t idx, const void *val,
  1112. int len);
  1113. #endif
  1114. /**
  1115. * fdt_setprop_inplace - change a property's value, but not its size
  1116. * @fdt: pointer to the device tree blob
  1117. * @nodeoffset: offset of the node whose property to change
  1118. * @name: name of the property to change
  1119. * @val: pointer to data to replace the property value with
  1120. * @len: length of the property value
  1121. *
  1122. * fdt_setprop_inplace() replaces the value of a given property with
  1123. * the data in val, of length len. This function cannot change the
  1124. * size of a property, and so will only work if len is equal to the
  1125. * current length of the property.
  1126. *
  1127. * This function will alter only the bytes in the blob which contain
  1128. * the given property value, and will not alter or move any other part
  1129. * of the tree.
  1130. *
  1131. * returns:
  1132. * 0, on success
  1133. * -FDT_ERR_NOSPACE, if len is not equal to the property's current length
  1134. * -FDT_ERR_NOTFOUND, node does not have the named property
  1135. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1136. * -FDT_ERR_BADMAGIC,
  1137. * -FDT_ERR_BADVERSION,
  1138. * -FDT_ERR_BADSTATE,
  1139. * -FDT_ERR_BADSTRUCTURE,
  1140. * -FDT_ERR_TRUNCATED, standard meanings
  1141. */
  1142. #ifndef SWIG /* Not available in Python */
  1143. int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,
  1144. const void *val, int len);
  1145. #endif
  1146. /**
  1147. * fdt_setprop_inplace_u32 - change the value of a 32-bit integer property
  1148. * @fdt: pointer to the device tree blob
  1149. * @nodeoffset: offset of the node whose property to change
  1150. * @name: name of the property to change
  1151. * @val: 32-bit integer value to replace the property with
  1152. *
  1153. * fdt_setprop_inplace_u32() replaces the value of a given property
  1154. * with the 32-bit integer value in val, converting val to big-endian
  1155. * if necessary. This function cannot change the size of a property,
  1156. * and so will only work if the property already exists and has length
  1157. * 4.
  1158. *
  1159. * This function will alter only the bytes in the blob which contain
  1160. * the given property value, and will not alter or move any other part
  1161. * of the tree.
  1162. *
  1163. * returns:
  1164. * 0, on success
  1165. * -FDT_ERR_NOSPACE, if the property's length is not equal to 4
  1166. * -FDT_ERR_NOTFOUND, node does not have the named property
  1167. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1168. * -FDT_ERR_BADMAGIC,
  1169. * -FDT_ERR_BADVERSION,
  1170. * -FDT_ERR_BADSTATE,
  1171. * -FDT_ERR_BADSTRUCTURE,
  1172. * -FDT_ERR_TRUNCATED, standard meanings
  1173. */
  1174. static inline int fdt_setprop_inplace_u32(void *fdt, int nodeoffset,
  1175. const char *name, uint32_t val)
  1176. {
  1177. fdt32_t tmp = cpu_to_fdt32(val);
  1178. return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
  1179. }
  1180. /**
  1181. * fdt_setprop_inplace_u64 - change the value of a 64-bit integer property
  1182. * @fdt: pointer to the device tree blob
  1183. * @nodeoffset: offset of the node whose property to change
  1184. * @name: name of the property to change
  1185. * @val: 64-bit integer value to replace the property with
  1186. *
  1187. * fdt_setprop_inplace_u64() replaces the value of a given property
  1188. * with the 64-bit integer value in val, converting val to big-endian
  1189. * if necessary. This function cannot change the size of a property,
  1190. * and so will only work if the property already exists and has length
  1191. * 8.
  1192. *
  1193. * This function will alter only the bytes in the blob which contain
  1194. * the given property value, and will not alter or move any other part
  1195. * of the tree.
  1196. *
  1197. * returns:
  1198. * 0, on success
  1199. * -FDT_ERR_NOSPACE, if the property's length is not equal to 8
  1200. * -FDT_ERR_NOTFOUND, node does not have the named property
  1201. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1202. * -FDT_ERR_BADMAGIC,
  1203. * -FDT_ERR_BADVERSION,
  1204. * -FDT_ERR_BADSTATE,
  1205. * -FDT_ERR_BADSTRUCTURE,
  1206. * -FDT_ERR_TRUNCATED, standard meanings
  1207. */
  1208. static inline int fdt_setprop_inplace_u64(void *fdt, int nodeoffset,
  1209. const char *name, uint64_t val)
  1210. {
  1211. fdt64_t tmp = cpu_to_fdt64(val);
  1212. return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
  1213. }
  1214. /**
  1215. * fdt_setprop_inplace_cell - change the value of a single-cell property
  1216. *
  1217. * This is an alternative name for fdt_setprop_inplace_u32()
  1218. */
  1219. static inline int fdt_setprop_inplace_cell(void *fdt, int nodeoffset,
  1220. const char *name, uint32_t val)
  1221. {
  1222. return fdt_setprop_inplace_u32(fdt, nodeoffset, name, val);
  1223. }
  1224. /**
  1225. * fdt_nop_property - replace a property with nop tags
  1226. * @fdt: pointer to the device tree blob
  1227. * @nodeoffset: offset of the node whose property to nop
  1228. * @name: name of the property to nop
  1229. *
  1230. * fdt_nop_property() will replace a given property's representation
  1231. * in the blob with FDT_NOP tags, effectively removing it from the
  1232. * tree.
  1233. *
  1234. * This function will alter only the bytes in the blob which contain
  1235. * the property, and will not alter or move any other part of the
  1236. * tree.
  1237. *
  1238. * returns:
  1239. * 0, on success
  1240. * -FDT_ERR_NOTFOUND, node does not have the named property
  1241. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1242. * -FDT_ERR_BADMAGIC,
  1243. * -FDT_ERR_BADVERSION,
  1244. * -FDT_ERR_BADSTATE,
  1245. * -FDT_ERR_BADSTRUCTURE,
  1246. * -FDT_ERR_TRUNCATED, standard meanings
  1247. */
  1248. int fdt_nop_property(void *fdt, int nodeoffset, const char *name);
  1249. /**
  1250. * fdt_nop_node - replace a node (subtree) with nop tags
  1251. * @fdt: pointer to the device tree blob
  1252. * @nodeoffset: offset of the node to nop
  1253. *
  1254. * fdt_nop_node() will replace a given node's representation in the
  1255. * blob, including all its subnodes, if any, with FDT_NOP tags,
  1256. * effectively removing it from the tree.
  1257. *
  1258. * This function will alter only the bytes in the blob which contain
  1259. * the node and its properties and subnodes, and will not alter or
  1260. * move any other part of the tree.
  1261. *
  1262. * returns:
  1263. * 0, on success
  1264. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1265. * -FDT_ERR_BADMAGIC,
  1266. * -FDT_ERR_BADVERSION,
  1267. * -FDT_ERR_BADSTATE,
  1268. * -FDT_ERR_BADSTRUCTURE,
  1269. * -FDT_ERR_TRUNCATED, standard meanings
  1270. */
  1271. int fdt_nop_node(void *fdt, int nodeoffset);
  1272. /**********************************************************************/
  1273. /* Sequential write functions */
  1274. /**********************************************************************/
  1275. /* fdt_create_with_flags flags */
  1276. #define FDT_CREATE_FLAG_NO_NAME_DEDUP 0x1
  1277. /* FDT_CREATE_FLAG_NO_NAME_DEDUP: Do not try to de-duplicate property
  1278. * names in the fdt. This can result in faster creation times, but
  1279. * a larger fdt. */
  1280. #define FDT_CREATE_FLAGS_ALL (FDT_CREATE_FLAG_NO_NAME_DEDUP)
  1281. /**
  1282. * fdt_create_with_flags - begin creation of a new fdt
  1283. * @fdt: pointer to memory allocated where fdt will be created
  1284. * @bufsize: size of the memory space at fdt
  1285. * @flags: a valid combination of FDT_CREATE_FLAG_ flags, or 0.
  1286. *
  1287. * fdt_create_with_flags() begins the process of creating a new fdt with
  1288. * the sequential write interface.
  1289. *
  1290. * fdt creation process must end with fdt_finished() to produce a valid fdt.
  1291. *
  1292. * returns:
  1293. * 0, on success
  1294. * -FDT_ERR_NOSPACE, bufsize is insufficient for a minimal fdt
  1295. * -FDT_ERR_BADFLAGS, flags is not valid
  1296. */
  1297. int fdt_create_with_flags(void *buf, int bufsize, uint32_t flags);
  1298. /**
  1299. * fdt_create - begin creation of a new fdt
  1300. * @fdt: pointer to memory allocated where fdt will be created
  1301. * @bufsize: size of the memory space at fdt
  1302. *
  1303. * fdt_create() is equivalent to fdt_create_with_flags() with flags=0.
  1304. *
  1305. * returns:
  1306. * 0, on success
  1307. * -FDT_ERR_NOSPACE, bufsize is insufficient for a minimal fdt
  1308. */
  1309. int fdt_create(void *buf, int bufsize);
  1310. int fdt_resize(void *fdt, void *buf, int bufsize);
  1311. int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size);
  1312. int fdt_finish_reservemap(void *fdt);
  1313. int fdt_begin_node(void *fdt, const char *name);
  1314. int fdt_property(void *fdt, const char *name, const void *val, int len);
  1315. static inline int fdt_property_u32(void *fdt, const char *name, uint32_t val)
  1316. {
  1317. fdt32_t tmp = cpu_to_fdt32(val);
  1318. return fdt_property(fdt, name, &tmp, sizeof(tmp));
  1319. }
  1320. static inline int fdt_property_u64(void *fdt, const char *name, uint64_t val)
  1321. {
  1322. fdt64_t tmp = cpu_to_fdt64(val);
  1323. return fdt_property(fdt, name, &tmp, sizeof(tmp));
  1324. }
  1325. #ifndef SWIG /* Not available in Python */
  1326. static inline int fdt_property_cell(void *fdt, const char *name, uint32_t val)
  1327. {
  1328. return fdt_property_u32(fdt, name, val);
  1329. }
  1330. #endif
  1331. /**
  1332. * fdt_property_placeholder - add a new property and return a ptr to its value
  1333. *
  1334. * @fdt: pointer to the device tree blob
  1335. * @name: name of property to add
  1336. * @len: length of property value in bytes
  1337. * @valp: returns a pointer to where where the value should be placed
  1338. *
  1339. * returns:
  1340. * 0, on success
  1341. * -FDT_ERR_BADMAGIC,
  1342. * -FDT_ERR_NOSPACE, standard meanings
  1343. */
  1344. int fdt_property_placeholder(void *fdt, const char *name, int len, void **valp);
  1345. #define fdt_property_string(fdt, name, str) \
  1346. fdt_property(fdt, name, str, strlen(str)+1)
  1347. int fdt_end_node(void *fdt);
  1348. int fdt_finish(void *fdt);
  1349. /**********************************************************************/
  1350. /* Read-write functions */
  1351. /**********************************************************************/
  1352. int fdt_create_empty_tree(void *buf, int bufsize);
  1353. int fdt_open_into(const void *fdt, void *buf, int bufsize);
  1354. int fdt_pack(void *fdt);
  1355. /**
  1356. * fdt_add_mem_rsv - add one memory reserve map entry
  1357. * @fdt: pointer to the device tree blob
  1358. * @address, @size: 64-bit values (native endian)
  1359. *
  1360. * Adds a reserve map entry to the given blob reserving a region at
  1361. * address address of length size.
  1362. *
  1363. * This function will insert data into the reserve map and will
  1364. * therefore change the indexes of some entries in the table.
  1365. *
  1366. * returns:
  1367. * 0, on success
  1368. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1369. * contain the new reservation entry
  1370. * -FDT_ERR_BADMAGIC,
  1371. * -FDT_ERR_BADVERSION,
  1372. * -FDT_ERR_BADSTATE,
  1373. * -FDT_ERR_BADSTRUCTURE,
  1374. * -FDT_ERR_BADLAYOUT,
  1375. * -FDT_ERR_TRUNCATED, standard meanings
  1376. */
  1377. int fdt_add_mem_rsv(void *fdt, uint64_t address, uint64_t size);
  1378. /**
  1379. * fdt_del_mem_rsv - remove a memory reserve map entry
  1380. * @fdt: pointer to the device tree blob
  1381. * @n: entry to remove
  1382. *
  1383. * fdt_del_mem_rsv() removes the n-th memory reserve map entry from
  1384. * the blob.
  1385. *
  1386. * This function will delete data from the reservation table and will
  1387. * therefore change the indexes of some entries in the table.
  1388. *
  1389. * returns:
  1390. * 0, on success
  1391. * -FDT_ERR_NOTFOUND, there is no entry of the given index (i.e. there
  1392. * are less than n+1 reserve map entries)
  1393. * -FDT_ERR_BADMAGIC,
  1394. * -FDT_ERR_BADVERSION,
  1395. * -FDT_ERR_BADSTATE,
  1396. * -FDT_ERR_BADSTRUCTURE,
  1397. * -FDT_ERR_BADLAYOUT,
  1398. * -FDT_ERR_TRUNCATED, standard meanings
  1399. */
  1400. int fdt_del_mem_rsv(void *fdt, int n);
  1401. /**
  1402. * fdt_set_name - change the name of a given node
  1403. * @fdt: pointer to the device tree blob
  1404. * @nodeoffset: structure block offset of a node
  1405. * @name: name to give the node
  1406. *
  1407. * fdt_set_name() replaces the name (including unit address, if any)
  1408. * of the given node with the given string. NOTE: this function can't
  1409. * efficiently check if the new name is unique amongst the given
  1410. * node's siblings; results are undefined if this function is invoked
  1411. * with a name equal to one of the given node's siblings.
  1412. *
  1413. * This function may insert or delete data from the blob, and will
  1414. * therefore change the offsets of some existing nodes.
  1415. *
  1416. * returns:
  1417. * 0, on success
  1418. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob
  1419. * to contain the new name
  1420. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1421. * -FDT_ERR_BADMAGIC,
  1422. * -FDT_ERR_BADVERSION,
  1423. * -FDT_ERR_BADSTATE, standard meanings
  1424. */
  1425. int fdt_set_name(void *fdt, int nodeoffset, const char *name);
  1426. /**
  1427. * fdt_setprop - create or change a property
  1428. * @fdt: pointer to the device tree blob
  1429. * @nodeoffset: offset of the node whose property to change
  1430. * @name: name of the property to change
  1431. * @val: pointer to data to set the property value to
  1432. * @len: length of the property value
  1433. *
  1434. * fdt_setprop() sets the value of the named property in the given
  1435. * node to the given value and length, creating the property if it
  1436. * does not already exist.
  1437. *
  1438. * This function may insert or delete data from the blob, and will
  1439. * therefore change the offsets of some existing nodes.
  1440. *
  1441. * returns:
  1442. * 0, on success
  1443. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1444. * contain the new property value
  1445. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1446. * -FDT_ERR_BADLAYOUT,
  1447. * -FDT_ERR_BADMAGIC,
  1448. * -FDT_ERR_BADVERSION,
  1449. * -FDT_ERR_BADSTATE,
  1450. * -FDT_ERR_BADSTRUCTURE,
  1451. * -FDT_ERR_BADLAYOUT,
  1452. * -FDT_ERR_TRUNCATED, standard meanings
  1453. */
  1454. int fdt_setprop(void *fdt, int nodeoffset, const char *name,
  1455. const void *val, int len);
  1456. /**
  1457. * fdt_setprop_placeholder - allocate space for a property
  1458. * @fdt: pointer to the device tree blob
  1459. * @nodeoffset: offset of the node whose property to change
  1460. * @name: name of the property to change
  1461. * @len: length of the property value
  1462. * @prop_data: return pointer to property data
  1463. *
  1464. * fdt_setprop_placeholer() allocates the named property in the given node.
  1465. * If the property exists it is resized. In either case a pointer to the
  1466. * property data is returned.
  1467. *
  1468. * This function may insert or delete data from the blob, and will
  1469. * therefore change the offsets of some existing nodes.
  1470. *
  1471. * returns:
  1472. * 0, on success
  1473. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1474. * contain the new property value
  1475. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1476. * -FDT_ERR_BADLAYOUT,
  1477. * -FDT_ERR_BADMAGIC,
  1478. * -FDT_ERR_BADVERSION,
  1479. * -FDT_ERR_BADSTATE,
  1480. * -FDT_ERR_BADSTRUCTURE,
  1481. * -FDT_ERR_BADLAYOUT,
  1482. * -FDT_ERR_TRUNCATED, standard meanings
  1483. */
  1484. int fdt_setprop_placeholder(void *fdt, int nodeoffset, const char *name,
  1485. int len, void **prop_data);
  1486. /**
  1487. * fdt_setprop_u32 - set a property to a 32-bit integer
  1488. * @fdt: pointer to the device tree blob
  1489. * @nodeoffset: offset of the node whose property to change
  1490. * @name: name of the property to change
  1491. * @val: 32-bit integer value for the property (native endian)
  1492. *
  1493. * fdt_setprop_u32() sets the value of the named property in the given
  1494. * node to the given 32-bit integer value (converting to big-endian if
  1495. * necessary), or creates a new property with that value if it does
  1496. * not already exist.
  1497. *
  1498. * This function may insert or delete data from the blob, and will
  1499. * therefore change the offsets of some existing nodes.
  1500. *
  1501. * returns:
  1502. * 0, on success
  1503. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1504. * contain the new property value
  1505. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1506. * -FDT_ERR_BADLAYOUT,
  1507. * -FDT_ERR_BADMAGIC,
  1508. * -FDT_ERR_BADVERSION,
  1509. * -FDT_ERR_BADSTATE,
  1510. * -FDT_ERR_BADSTRUCTURE,
  1511. * -FDT_ERR_BADLAYOUT,
  1512. * -FDT_ERR_TRUNCATED, standard meanings
  1513. */
  1514. static inline int fdt_setprop_u32(void *fdt, int nodeoffset, const char *name,
  1515. uint32_t val)
  1516. {
  1517. fdt32_t tmp = cpu_to_fdt32(val);
  1518. return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
  1519. }
  1520. /**
  1521. * fdt_setprop_u64 - set a property to a 64-bit integer
  1522. * @fdt: pointer to the device tree blob
  1523. * @nodeoffset: offset of the node whose property to change
  1524. * @name: name of the property to change
  1525. * @val: 64-bit integer value for the property (native endian)
  1526. *
  1527. * fdt_setprop_u64() sets the value of the named property in the given
  1528. * node to the given 64-bit integer value (converting to big-endian if
  1529. * necessary), or creates a new property with that value if it does
  1530. * not already exist.
  1531. *
  1532. * This function may insert or delete data from the blob, and will
  1533. * therefore change the offsets of some existing nodes.
  1534. *
  1535. * returns:
  1536. * 0, on success
  1537. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1538. * contain the new property value
  1539. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1540. * -FDT_ERR_BADLAYOUT,
  1541. * -FDT_ERR_BADMAGIC,
  1542. * -FDT_ERR_BADVERSION,
  1543. * -FDT_ERR_BADSTATE,
  1544. * -FDT_ERR_BADSTRUCTURE,
  1545. * -FDT_ERR_BADLAYOUT,
  1546. * -FDT_ERR_TRUNCATED, standard meanings
  1547. */
  1548. static inline int fdt_setprop_u64(void *fdt, int nodeoffset, const char *name,
  1549. uint64_t val)
  1550. {
  1551. fdt64_t tmp = cpu_to_fdt64(val);
  1552. return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
  1553. }
  1554. /**
  1555. * fdt_setprop_cell - set a property to a single cell value
  1556. *
  1557. * This is an alternative name for fdt_setprop_u32()
  1558. */
  1559. static inline int fdt_setprop_cell(void *fdt, int nodeoffset, const char *name,
  1560. uint32_t val)
  1561. {
  1562. return fdt_setprop_u32(fdt, nodeoffset, name, val);
  1563. }
  1564. /**
  1565. * fdt_setprop_string - set a property to a string value
  1566. * @fdt: pointer to the device tree blob
  1567. * @nodeoffset: offset of the node whose property to change
  1568. * @name: name of the property to change
  1569. * @str: string value for the property
  1570. *
  1571. * fdt_setprop_string() sets the value of the named property in the
  1572. * given node to the given string value (using the length of the
  1573. * string to determine the new length of the property), or creates a
  1574. * new property with that value if it does not already exist.
  1575. *
  1576. * This function may insert or delete data from the blob, and will
  1577. * therefore change the offsets of some existing nodes.
  1578. *
  1579. * returns:
  1580. * 0, on success
  1581. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1582. * contain the new property value
  1583. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1584. * -FDT_ERR_BADLAYOUT,
  1585. * -FDT_ERR_BADMAGIC,
  1586. * -FDT_ERR_BADVERSION,
  1587. * -FDT_ERR_BADSTATE,
  1588. * -FDT_ERR_BADSTRUCTURE,
  1589. * -FDT_ERR_BADLAYOUT,
  1590. * -FDT_ERR_TRUNCATED, standard meanings
  1591. */
  1592. #define fdt_setprop_string(fdt, nodeoffset, name, str) \
  1593. fdt_setprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
  1594. /**
  1595. * fdt_setprop_empty - set a property to an empty value
  1596. * @fdt: pointer to the device tree blob
  1597. * @nodeoffset: offset of the node whose property to change
  1598. * @name: name of the property to change
  1599. *
  1600. * fdt_setprop_empty() sets the value of the named property in the
  1601. * given node to an empty (zero length) value, or creates a new empty
  1602. * property if it does not already exist.
  1603. *
  1604. * This function may insert or delete data from the blob, and will
  1605. * therefore change the offsets of some existing nodes.
  1606. *
  1607. * returns:
  1608. * 0, on success
  1609. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1610. * contain the new property value
  1611. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1612. * -FDT_ERR_BADLAYOUT,
  1613. * -FDT_ERR_BADMAGIC,
  1614. * -FDT_ERR_BADVERSION,
  1615. * -FDT_ERR_BADSTATE,
  1616. * -FDT_ERR_BADSTRUCTURE,
  1617. * -FDT_ERR_BADLAYOUT,
  1618. * -FDT_ERR_TRUNCATED, standard meanings
  1619. */
  1620. #define fdt_setprop_empty(fdt, nodeoffset, name) \
  1621. fdt_setprop((fdt), (nodeoffset), (name), NULL, 0)
  1622. /**
  1623. * fdt_appendprop - append to or create a property
  1624. * @fdt: pointer to the device tree blob
  1625. * @nodeoffset: offset of the node whose property to change
  1626. * @name: name of the property to append to
  1627. * @val: pointer to data to append to the property value
  1628. * @len: length of the data to append to the property value
  1629. *
  1630. * fdt_appendprop() appends the value to the named property in the
  1631. * given node, creating the property if it does not already exist.
  1632. *
  1633. * This function may insert data into the blob, and will therefore
  1634. * change the offsets of some existing nodes.
  1635. *
  1636. * returns:
  1637. * 0, on success
  1638. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1639. * contain the new property value
  1640. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1641. * -FDT_ERR_BADLAYOUT,
  1642. * -FDT_ERR_BADMAGIC,
  1643. * -FDT_ERR_BADVERSION,
  1644. * -FDT_ERR_BADSTATE,
  1645. * -FDT_ERR_BADSTRUCTURE,
  1646. * -FDT_ERR_BADLAYOUT,
  1647. * -FDT_ERR_TRUNCATED, standard meanings
  1648. */
  1649. int fdt_appendprop(void *fdt, int nodeoffset, const char *name,
  1650. const void *val, int len);
  1651. /**
  1652. * fdt_appendprop_u32 - append a 32-bit integer value to a property
  1653. * @fdt: pointer to the device tree blob
  1654. * @nodeoffset: offset of the node whose property to change
  1655. * @name: name of the property to change
  1656. * @val: 32-bit integer value to append to the property (native endian)
  1657. *
  1658. * fdt_appendprop_u32() appends the given 32-bit integer value
  1659. * (converting to big-endian if necessary) to the value of the named
  1660. * property in the given node, or creates a new property with that
  1661. * value if it does not already exist.
  1662. *
  1663. * This function may insert data into the blob, and will therefore
  1664. * change the offsets of some existing nodes.
  1665. *
  1666. * returns:
  1667. * 0, on success
  1668. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1669. * contain the new property value
  1670. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1671. * -FDT_ERR_BADLAYOUT,
  1672. * -FDT_ERR_BADMAGIC,
  1673. * -FDT_ERR_BADVERSION,
  1674. * -FDT_ERR_BADSTATE,
  1675. * -FDT_ERR_BADSTRUCTURE,
  1676. * -FDT_ERR_BADLAYOUT,
  1677. * -FDT_ERR_TRUNCATED, standard meanings
  1678. */
  1679. static inline int fdt_appendprop_u32(void *fdt, int nodeoffset,
  1680. const char *name, uint32_t val)
  1681. {
  1682. fdt32_t tmp = cpu_to_fdt32(val);
  1683. return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
  1684. }
  1685. /**
  1686. * fdt_appendprop_u64 - append a 64-bit integer value to a property
  1687. * @fdt: pointer to the device tree blob
  1688. * @nodeoffset: offset of the node whose property to change
  1689. * @name: name of the property to change
  1690. * @val: 64-bit integer value to append to the property (native endian)
  1691. *
  1692. * fdt_appendprop_u64() appends the given 64-bit integer value
  1693. * (converting to big-endian if necessary) to the value of the named
  1694. * property in the given node, or creates a new property with that
  1695. * value if it does not already exist.
  1696. *
  1697. * This function may insert data into the blob, and will therefore
  1698. * change the offsets of some existing nodes.
  1699. *
  1700. * returns:
  1701. * 0, on success
  1702. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1703. * contain the new property value
  1704. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1705. * -FDT_ERR_BADLAYOUT,
  1706. * -FDT_ERR_BADMAGIC,
  1707. * -FDT_ERR_BADVERSION,
  1708. * -FDT_ERR_BADSTATE,
  1709. * -FDT_ERR_BADSTRUCTURE,
  1710. * -FDT_ERR_BADLAYOUT,
  1711. * -FDT_ERR_TRUNCATED, standard meanings
  1712. */
  1713. static inline int fdt_appendprop_u64(void *fdt, int nodeoffset,
  1714. const char *name, uint64_t val)
  1715. {
  1716. fdt64_t tmp = cpu_to_fdt64(val);
  1717. return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
  1718. }
  1719. /**
  1720. * fdt_appendprop_cell - append a single cell value to a property
  1721. *
  1722. * This is an alternative name for fdt_appendprop_u32()
  1723. */
  1724. static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,
  1725. const char *name, uint32_t val)
  1726. {
  1727. return fdt_appendprop_u32(fdt, nodeoffset, name, val);
  1728. }
  1729. /**
  1730. * fdt_appendprop_string - append a string to a property
  1731. * @fdt: pointer to the device tree blob
  1732. * @nodeoffset: offset of the node whose property to change
  1733. * @name: name of the property to change
  1734. * @str: string value to append to the property
  1735. *
  1736. * fdt_appendprop_string() appends the given string to the value of
  1737. * the named property in the given node, or creates a new property
  1738. * with that value if it does not already exist.
  1739. *
  1740. * This function may insert data into the blob, and will therefore
  1741. * change the offsets of some existing nodes.
  1742. *
  1743. * returns:
  1744. * 0, on success
  1745. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1746. * contain the new property value
  1747. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1748. * -FDT_ERR_BADLAYOUT,
  1749. * -FDT_ERR_BADMAGIC,
  1750. * -FDT_ERR_BADVERSION,
  1751. * -FDT_ERR_BADSTATE,
  1752. * -FDT_ERR_BADSTRUCTURE,
  1753. * -FDT_ERR_BADLAYOUT,
  1754. * -FDT_ERR_TRUNCATED, standard meanings
  1755. */
  1756. #define fdt_appendprop_string(fdt, nodeoffset, name, str) \
  1757. fdt_appendprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
  1758. /**
  1759. * fdt_appendprop_addrrange - append a address range property
  1760. * @fdt: pointer to the device tree blob
  1761. * @parent: offset of the parent node
  1762. * @nodeoffset: offset of the node to add a property at
  1763. * @name: name of property
  1764. * @addr: start address of a given range
  1765. * @size: size of a given range
  1766. *
  1767. * fdt_appendprop_addrrange() appends an address range value (start
  1768. * address and size) to the value of the named property in the given
  1769. * node, or creates a new property with that value if it does not
  1770. * already exist.
  1771. * If "name" is not specified, a default "reg" is used.
  1772. * Cell sizes are determined by parent's #address-cells and #size-cells.
  1773. *
  1774. * This function may insert data into the blob, and will therefore
  1775. * change the offsets of some existing nodes.
  1776. *
  1777. * returns:
  1778. * 0, on success
  1779. * -FDT_ERR_BADLAYOUT,
  1780. * -FDT_ERR_BADMAGIC,
  1781. * -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
  1782. * #address-cells property
  1783. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1784. * -FDT_ERR_BADSTATE,
  1785. * -FDT_ERR_BADSTRUCTURE,
  1786. * -FDT_ERR_BADVERSION,
  1787. * -FDT_ERR_BADVALUE, addr or size doesn't fit to respective cells size
  1788. * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
  1789. * contain a new property
  1790. * -FDT_ERR_TRUNCATED, standard meanings
  1791. */
  1792. int fdt_appendprop_addrrange(void *fdt, int parent, int nodeoffset,
  1793. const char *name, uint64_t addr, uint64_t size);
  1794. /**
  1795. * fdt_delprop - delete a property
  1796. * @fdt: pointer to the device tree blob
  1797. * @nodeoffset: offset of the node whose property to nop
  1798. * @name: name of the property to nop
  1799. *
  1800. * fdt_del_property() will delete the given property.
  1801. *
  1802. * This function will delete data from the blob, and will therefore
  1803. * change the offsets of some existing nodes.
  1804. *
  1805. * returns:
  1806. * 0, on success
  1807. * -FDT_ERR_NOTFOUND, node does not have the named property
  1808. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1809. * -FDT_ERR_BADLAYOUT,
  1810. * -FDT_ERR_BADMAGIC,
  1811. * -FDT_ERR_BADVERSION,
  1812. * -FDT_ERR_BADSTATE,
  1813. * -FDT_ERR_BADSTRUCTURE,
  1814. * -FDT_ERR_TRUNCATED, standard meanings
  1815. */
  1816. int fdt_delprop(void *fdt, int nodeoffset, const char *name);
  1817. /**
  1818. * fdt_add_subnode_namelen - creates a new node based on substring
  1819. * @fdt: pointer to the device tree blob
  1820. * @parentoffset: structure block offset of a node
  1821. * @name: name of the subnode to locate
  1822. * @namelen: number of characters of name to consider
  1823. *
  1824. * Identical to fdt_add_subnode(), but use only the first namelen
  1825. * characters of name as the name of the new node. This is useful for
  1826. * creating subnodes based on a portion of a larger string, such as a
  1827. * full path.
  1828. */
  1829. #ifndef SWIG /* Not available in Python */
  1830. int fdt_add_subnode_namelen(void *fdt, int parentoffset,
  1831. const char *name, int namelen);
  1832. #endif
  1833. /**
  1834. * fdt_add_subnode - creates a new node
  1835. * @fdt: pointer to the device tree blob
  1836. * @parentoffset: structure block offset of a node
  1837. * @name: name of the subnode to locate
  1838. *
  1839. * fdt_add_subnode() creates a new node as a subnode of the node at
  1840. * structure block offset parentoffset, with the given name (which
  1841. * should include the unit address, if any).
  1842. *
  1843. * This function will insert data into the blob, and will therefore
  1844. * change the offsets of some existing nodes.
  1845. * returns:
  1846. * structure block offset of the created nodeequested subnode (>=0), on
  1847. * success
  1848. * -FDT_ERR_NOTFOUND, if the requested subnode does not exist
  1849. * -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE
  1850. * tag
  1851. * -FDT_ERR_EXISTS, if the node at parentoffset already has a subnode of
  1852. * the given name
  1853. * -FDT_ERR_NOSPACE, if there is insufficient free space in the
  1854. * blob to contain the new node
  1855. * -FDT_ERR_NOSPACE
  1856. * -FDT_ERR_BADLAYOUT
  1857. * -FDT_ERR_BADMAGIC,
  1858. * -FDT_ERR_BADVERSION,
  1859. * -FDT_ERR_BADSTATE,
  1860. * -FDT_ERR_BADSTRUCTURE,
  1861. * -FDT_ERR_TRUNCATED, standard meanings.
  1862. */
  1863. int fdt_add_subnode(void *fdt, int parentoffset, const char *name);
  1864. /**
  1865. * fdt_del_node - delete a node (subtree)
  1866. * @fdt: pointer to the device tree blob
  1867. * @nodeoffset: offset of the node to nop
  1868. *
  1869. * fdt_del_node() will remove the given node, including all its
  1870. * subnodes if any, from the blob.
  1871. *
  1872. * This function will delete data from the blob, and will therefore
  1873. * change the offsets of some existing nodes.
  1874. *
  1875. * returns:
  1876. * 0, on success
  1877. * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
  1878. * -FDT_ERR_BADLAYOUT,
  1879. * -FDT_ERR_BADMAGIC,
  1880. * -FDT_ERR_BADVERSION,
  1881. * -FDT_ERR_BADSTATE,
  1882. * -FDT_ERR_BADSTRUCTURE,
  1883. * -FDT_ERR_TRUNCATED, standard meanings
  1884. */
  1885. int fdt_del_node(void *fdt, int nodeoffset);
  1886. /**
  1887. * fdt_overlay_apply - Applies a DT overlay on a base DT
  1888. * @fdt: pointer to the base device tree blob
  1889. * @fdto: pointer to the device tree overlay blob
  1890. *
  1891. * fdt_overlay_apply() will apply the given device tree overlay on the
  1892. * given base device tree.
  1893. *
  1894. * Expect the base device tree to be modified, even if the function
  1895. * returns an error.
  1896. *
  1897. * returns:
  1898. * 0, on success
  1899. * -FDT_ERR_NOSPACE, there's not enough space in the base device tree
  1900. * -FDT_ERR_NOTFOUND, the overlay points to some inexistant nodes or
  1901. * properties in the base DT
  1902. * -FDT_ERR_BADPHANDLE,
  1903. * -FDT_ERR_BADOVERLAY,
  1904. * -FDT_ERR_NOPHANDLES,
  1905. * -FDT_ERR_INTERNAL,
  1906. * -FDT_ERR_BADLAYOUT,
  1907. * -FDT_ERR_BADMAGIC,
  1908. * -FDT_ERR_BADOFFSET,
  1909. * -FDT_ERR_BADPATH,
  1910. * -FDT_ERR_BADVERSION,
  1911. * -FDT_ERR_BADSTRUCTURE,
  1912. * -FDT_ERR_BADSTATE,
  1913. * -FDT_ERR_TRUNCATED, standard meanings
  1914. */
  1915. int fdt_overlay_apply(void *fdt, void *fdto);
  1916. /**
  1917. * fdt_overlay_apply_node - Merges a node into the base device tree
  1918. *
  1919. * See overlay_apply_node() for details.
  1920. */
  1921. int fdt_overlay_apply_node(void *fdt, int target, void *fdto, int node);
  1922. /**********************************************************************/
  1923. /* Debugging / informational functions */
  1924. /**********************************************************************/
  1925. const char *fdt_strerror(int errval);
  1926. #endif /* LIBFDT_H */