libfdt.h 75 KB

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