kernel
/
dtc
mirror of https://git.kernel.org/pub/scm/utils/dtc/dtc.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

libfdt: Add some documenting comments in libfdt.h 

This patch adds some internal documentation in libfdt.h, in the form
of comments on the error codes and some functions.  Only a couple of
functions are covered so far, leaving the documentation still woefully
inadequate, but hey, it's a start.

Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
main
David Gibson 2007-10-24 17:10:58 +10:00 committed by Jon Loeliger
parent 3c44c87bde
commit cec0c384ef
1 changed files with 136 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
libfdt/libfdt.h
View File

@ -59,27 +59,64 @@

/* Error codes: informative error codes */
#define FDT_ERR_NOTFOUND 1
/* FDT_ERR_NOTFOUND: The requested node or property does not exist */
#define FDT_ERR_EXISTS 2
/* FDT_ERR_EXISTS: Attemped to create a node or property which
* already exists */
#define FDT_ERR_NOSPACE 3
/* FDT_ERR_NOSPACE: Operation needed to expand the device
* tree, but its buffer did not have sufficient space to
* contain the expanded tree. Use fdt_open_into() to move the
* device tree to a buffer with more space. */

/* Error codes: codes for bad parameters */
#define FDT_ERR_BADOFFSET 4
/* FDT_ERR_BADOFFSET: Function was passed a structure block
* offset which is out-of-bounds, or which points to an
* unsuitable part of the structure for the operation. */
#define FDT_ERR_BADPATH 5
/* FDT_ERR_BADPATH: Function was passed a badly formatted path
* (e.g. missing a leading / for a function which requires an
* absolute path) */
#define FDT_ERR_BADSTATE 6
/* FDT_ERR_BADSTATE: Function was passed an incomplete device
* tree created by the sequential-write functions, which is
* not sufficiently complete for the requested operation. */

/* Error codes: codes for bad device tree blobs */
#define FDT_ERR_TRUNCATED 7
/* FDT_ERR_TRUNCATED: Structure block of the given device tree
* ends without an FDT_END tag. */
#define FDT_ERR_BADMAGIC 8
/* FDT_ERR_BADMAGIC: Given "device tree" appears not to be a
* device tree at all - it is missing the flattened device
* tree magic number. */
#define FDT_ERR_BADVERSION 9
/* FDT_ERR_BADVERSION: Given device tree has a version which
* can't be handled by the requested operation. For
* read-write functions, this may mean that fdt_open_into() is
* required to convert the tree to the expected version. */
#define FDT_ERR_BADSTRUCTURE 10
/* FDT_ERR_BADSTRUCTURE: Given device tree has a corrupt
* structure block or other serious error (e.g. misnested
* nodes, or subnodes preceding properties). */
#define FDT_ERR_BADLAYOUT 11
/* FDT_ERR_BADLAYOUT: For read-write functions, the given
* device tree has it's sub-blocks in an order that the
* function can't handle (memory reserve map, then structure,
* then strings). Use fdt_open_into() to reorganize the tree
* into a form suitable for the read-write operations. */

/* "Can't happen" error indicating a bug in libfdt */
#define FDT_ERR_INTERNAL 12
/* FDT_ERR_INTERNAL: libfdt has failed an internal assertion.
* Indicates a bug in libfdt itself. */

#define FDT_ERR_MAX 12

/* Low-level functions (you probably don't need these) */
/**********************************************************************/
/* Low-level functions (you probably don't need these) */
/**********************************************************************/

const void *fdt_offset_ptr(const void *fdt, int offset, int checklen);
static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)
@ -95,7 +132,10 @@ static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)

uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);

/* General functions */
/**********************************************************************/
/* General functions */
/**********************************************************************/

#define fdt_get_header(fdt, field) \
(fdt32_to_cpu(((const struct fdt_header *)(fdt))->field))
#define fdt_magic(fdt) (fdt_get_header(fdt, magic))
@ -112,15 +152,91 @@ uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);
#define fdt_set_header(fdt, field, val) \
((struct fdt_header *)(fdt))->field = cpu_to_fdt32(val)

/**
* fdt_check_header - sanity check a device tree or possible device tree
* @fdt: pointer to data which might be a flattened device tree
*
* fdt_check_header() checks that the given buffer contains what
* appears to be a flattened device tree with sane information in its
* header.
*
* returns:
* 0, if the buffer appears to contain a valid device tree
* -FDT_ERR_BADMAGIC,
* -FDT_ERR_BADVERSION,
* -FDT_ERR_BADSTATE, standard meanings, as above
*/
int fdt_check_header(const void *fdt);

/**
* fdt_move - move a device tree around in memory
* @fdt: pointer to the device tree to move
* @buf: pointer to memory where the device is to be moved
* @bufsize: size of the memory space at buf
*
* fdt_move() relocates, if possible, the device tree blob located at
* fdt to the buffer at buf of size bufsize. The buffer may overlap
* with the existing device tree blob at fdt. Therefore,
* fdt_move(fdt, fdt, fdt_totalsize(fdt))
* should always succeed.
*
* returns:
* 0, on success
* -FDT_ERR_NOSPACE, bufsize is insufficient to contain the device tree
* -FDT_ERR_BADMAGIC,
* -FDT_ERR_BADVERSION,
* -FDT_ERR_BADSTATE, standard meanings
*/
int fdt_move(const void *fdt, void *buf, int bufsize);

/* Read-only functions */
/**********************************************************************/
/* Read-only functions */
/**********************************************************************/

/**
* fdt_string - retreive a string from the strings block of a device tree
* @fdt: pointer to the device tree blob
* @stroffset: offset of the string within the strings block (native endian)
*
* fdt_string() retrieves a pointer to a single string from the
* strings block of the device tree blob at fdt.
*
* returns:
* a pointer to the string, on success
* NULL, if stroffset is out of bounds
*/
const char *fdt_string(const void *fdt, int stroffset);

int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);
/**
* fdt_num_mem_rsv - retreive the number of memory reserve map entries
* @fdt: pointer to the device tree blob
*
* Returns the number of entries in the device tree blob's memory
* reservation map. This does not include the terminating 0,0 entry
* or any other (0,0) entries reserved for expansion.
*
* returns:
* the number of entries
*/
int fdt_num_mem_rsv(const void *fdt);

/**
* fdt_get_mem_rsv - retreive one memory reserve map entry
* @fdt: pointer to the device tree blob
* @address, @size: pointers to 64-bit variables
*
* On success, *address and *size will contain the address and size of
* the n-th reserve map entry from the device tree blob, in
* native-endian format.
*
* returns:
* 0, on success
* -FDT_ERR_BADMAGIC,
* -FDT_ERR_BADVERSION,
* -FDT_ERR_BADSTATE, standard meanings
*/
int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);

int fdt_subnode_offset_namelen(const void *fdt, int parentoffset,
const char *name, int namelen);
int fdt_subnode_offset(const void *fdt, int parentoffset, const char *name);
@ -164,7 +280,10 @@ int fdt_node_check_compatible(const void *fdt, int nodeoffset,
int fdt_node_offset_by_compatible(const void *fdt, int startoffset,
const char *compatible);

/* Write-in-place functions */
/**********************************************************************/
/* Write-in-place functions */
/**********************************************************************/

int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,
const void *val, int len);

@ -177,7 +296,10 @@ int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,
int fdt_nop_property(void *fdt, int nodeoffset, const char *name);
int fdt_nop_node(void *fdt, int nodeoffset);

/* Sequential-write functions */
/**********************************************************************/
/* Sequential write functions */
/**********************************************************************/

int fdt_create(void *buf, int bufsize);
int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size);
int fdt_finish_reservemap(void *fdt);
@ -193,7 +315,10 @@ int fdt_property(void *fdt, const char *name, const void *val, int len);
int fdt_end_node(void *fdt);
int fdt_finish(void *fdt);

/* Read-write functions */
/**********************************************************************/
/* Read-write functions */
/**********************************************************************/

int fdt_open_into(void *fdt, void *buf, int bufsize);
int fdt_pack(void *fdt);

@ -215,7 +340,10 @@ int fdt_add_subnode_namelen(void *fdt, int parentoffset,
int fdt_add_subnode(void *fdt, int parentoffset, const char *name);
int fdt_del_node(void *fdt, int nodeoffset);

/* Extra functions */
/**********************************************************************/
/* Debugging / informational functions */
/**********************************************************************/

const char *fdt_strerror(int errval);

#endif /* _LIBFDT_H */