From 12be40e22aae582cca9abbd151031edaab800cae Mon Sep 17 00:00:00 2001 From: Kimplul Date: Mon, 23 May 2022 23:00:55 +0300 Subject: start writing documentation --- include/libfdt.h | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) (limited to 'include/libfdt.h') diff --git a/include/libfdt.h b/include/libfdt.h index 33ce0fb..a1266c9 100644 --- a/include/libfdt.h +++ b/include/libfdt.h @@ -11,25 +11,84 @@ #include /* apos additions, implementation can be found in common/fdt.c */ + +/** + * FDT cell info. + */ struct cell_info { + /** Value size of cell. */ uint32_t size_cells; + /** Address size of cell. */ uint32_t addr_cells; }; +/** + * Get information about a cell. + * + * @param fdt Pointer to the global FDT. + * @param offset Offset of cell to poke. + * @return Cell information. + */ struct cell_info get_cellinfo(const void *fdt, const int offset); + +/** + * Get information about a register. + * + * @param fdt Pointer to the global fdt. + * @param path Path to be searched. + * @return Register information. + */ struct cell_info get_reginfo(const void *fdt, const char *path); #if defined(DEBUG) +/** + * Print FDT node at specified location. + * + * @param fdt Pointer to global FDT. + * @param node_offset Offset of node. + * @param depth Depth of node. + */ void __dbg_fdt(const void *fdt, int node_offset, int depth); + +/** + * Convenience wrapper around \ref __dbg_fdt(), used to print whole tree. + */ #define dbg_fdt(fdt) __dbg_fdt(fdt, 0, 0) #else +/** + * Debugging is disabled when in release mode, so all calls to dbg_fdt need to + * be erased. + */ #define dbg_fdt(...) #endif +/** + * Load int32 from FDT at location specified by pointer. Integers inside the FDT + * may be unaligned, and accessing them should preferably be done through this + * and \ref fdt_load_int64_ptr(). + * + * @param p Pointer to int32 inside the global FDT. + */ #define fdt_load_int32_ptr(p) fdt32_to_cpu(get_unaligned((uint32_t *)p)) +/** + * Load int64 from FDT at location specified by pointer. + * + * @param p Pointer to int64 inside the global FDT. + * @return Value of int32 at location p. + * + * See \ref fdt_load_int32_ptr() + */ #define fdt_load_int64_ptr(p) fdt64_to_cpu(get_unaligned((uint64_t *)p)) +/** + * Load int{32,64} from FDT at location specified by pointer. + * + * @param c Size of int, where 2 == int64 and everything else int32. Query int + * size from FDT with \ref get_cellinfo() and \ref get_reginfo(). + * @param p Pointer to int{32,64} inside the global FDT. + * @return Value of integer at location p. + */ #define fdt_load_int_ptr(c, p) \ ((c) == 2 ? fdt_load_int64_ptr(p) : fdt_load_int32_ptr(p)) -- cgit v1.3