libfdt.h 66 KB

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