libfdt.h 70 KB

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