libfdt.h 72 KB

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