libfdt.h 68 KB

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