[RFC PATCH 2/2] libfdt: Add documentation and warnings about deprecation

[Simon Glass <sjg@xxxxxxxxxxxx>]

Any change to the tag format would affect functions which return
struct fdt_property. Add documentation for this and allow generation of
warnings in libfdt client code.

Signed-off-by: Simon Glass <sjg@xxxxxxxxxxxx>
---

 README              | 14 ++++++++++++++
 libfdt/fdt.h        |  2 +-
 libfdt/libfdt.h     | 22 ++++++++++++++++------
 libfdt/libfdt_env.h |  7 +++++++
 4 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/README b/README
index 15232ab..479cc9c 100644
--- a/README
+++ b/README
@@ -8,6 +8,20 @@ David Gibson <david@xxxxxxxxxxxxxxxxxxxxx>
 Jon Loeliger <jdl@xxxxxxx>
 
 
+Deprecated functions (November 2018)
+------------------------------------
+
+In preparation for potential internal libfdt changes to support additional
+features, some API functions have been determined to be problematic. Currently
+the list includes those that return struct fdt_property, since this struct may
+not exist in future libfdt versions.
+
+Define LIBFDT_DEPRECATION_WARNINGS before including libfdt_env.h to generate
+gcc deprecation warnings for deprecated functions and types. Deprecated
+functions may not work in future libfdt versions. Deprecated types may become
+inaccessible.
+
+
 Python library
 --------------
 
diff --git a/libfdt/fdt.h b/libfdt/fdt.h
index 74961f9..14326c5 100644
--- a/libfdt/fdt.h
+++ b/libfdt/fdt.h
@@ -83,7 +83,7 @@ struct fdt_node_header {
 	char name[0];
 };
 
-struct fdt_property {
+struct __deprecated fdt_property {
 	fdt32_t tag;
 	fdt32_t len;
 	fdt32_t nameoff;
diff --git a/libfdt/libfdt.h b/libfdt/libfdt.h
index fdaa3e6..468e7ea 100644
--- a/libfdt/libfdt.h
+++ b/libfdt/libfdt.h
@@ -581,6 +581,9 @@ int fdt_next_property_offset(const void *fdt, int offset);
 
 /**
  * fdt_get_property_by_offset - retrieve the property at a given offset
+ *
+ * NOTE THIS FUNCTION IS DEPRECATED. Please use fdt_getprop_by_offset() instead.
+ *
  * @fdt: pointer to the device tree blob
  * @offset: offset of the property to retrieve
  * @lenp: pointer to an integer variable (will be overwritten) or NULL
@@ -608,10 +611,13 @@ int fdt_next_property_offset(const void *fdt, int offset);
  */
 const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
 						      int offset,
-						      int *lenp);
+						      int *lenp) __deprecated;
 
 /**
  * fdt_get_property_namelen - find a property based on substring
+ *
+ * NOTE THIS FUNCTION IS DEPRECATED. Please use fdt_getprop_namelen() instead.
+ *
  * @fdt: pointer to the device tree blob
  * @nodeoffset: offset of the node whose property to find
  * @name: name of the property to find
@@ -625,11 +631,15 @@ const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
 const struct fdt_property *fdt_get_property_namelen(const void *fdt,
 						    int nodeoffset,
 						    const char *name,
-						    int namelen, int *lenp);
+						    int namelen, int *lenp)
+						    __deprecated;
 #endif
 
 /**
  * fdt_get_property - find a given property in a given node
+ *
+ * NOTE THIS FUNCTION IS DEPRECATED. Please use fdt_getprop() instead.
+ *
  * @fdt: pointer to the device tree blob
  * @nodeoffset: offset of the node whose property to find
  * @name: name of the property to find
@@ -657,10 +667,10 @@ const struct fdt_property *fdt_get_property_namelen(const void *fdt,
  *		-FDT_ERR_TRUNCATED, standard meanings
  */
 const struct fdt_property *fdt_get_property(const void *fdt, int nodeoffset,
-					    const char *name, int *lenp);
-static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,
-						      const char *name,
-						      int *lenp)
+					    const char *name, int *lenp)
+					    __deprecated;
+static __deprecated inline struct fdt_property *fdt_get_property_w(void *fdt,
+			   int nodeoffset, const char *name, int *lenp)
 {
 	return (struct fdt_property *)(uintptr_t)
 		fdt_get_property(fdt, nodeoffset, name, lenp);
diff --git a/libfdt/libfdt_env.h b/libfdt/libfdt_env.h
index eb20538..55d24c8 100644
--- a/libfdt/libfdt_env.h
+++ b/libfdt/libfdt_env.h
@@ -110,6 +110,13 @@ static inline fdt64_t cpu_to_fdt64(uint64_t x)
 #undef CPU_TO_FDT16
 #undef EXTRACT_BYTE
 
+/* Functions and types marked deprecated */
+#if defined(LIBFDT_DEPRECATION_WARNINGS) && defined(__GNUC__)
+#define __deprecated __attribute__ ((deprecated))
+#else
+#define __deprecated
+#endif
+
 #ifdef __APPLE__
 #include <AvailabilityMacros.h>
 
-- 
2.19.1.1215.g8438c0b245-goog