Add (and use) generic reference counter, to improve signal:noise ratio

in code defining reference-counted objects.

src/include/gpxe/interface.h

@@ -7,6 +7,8 @@
  *
  */
 
+#include <gpxe/refcnt.h>
+
 /** An object communication interface */
 struct interface {
 	/** Destination interface
@@ -18,19 +20,14 @@ struct interface {
 	 * unplugged, it should point to a null interface.
 	 */
 	struct interface *dest;
-	/** Update reference count
+	/** Reference counter
 	 *
-	 * @v intf		Interface
-	 * @v delta		Change to apply to reference count
-	 *
-	 * This method updates the reference count for the object
-	 * containing the interface.
+	 * If this interface is not part of a reference-counted
+	 * object, this field may be NULL.
 	 */
-	void ( * refcnt ) ( struct interface *intf, int delta );
+	struct refcnt *refcnt;
 };
 
 extern void plug ( struct interface *intf, struct interface *dest );
 
-extern void null_refcnt ( struct interface *intf, int delta );
-
 #endif /* _GPXE_INTERFACE_H */

src/include/gpxe/job.h

@@ -76,12 +76,11 @@ extern void ignore_progress ( struct job_interface *job,
  *
  * @v job		Job control interface
  * @v op		Job control interface operations
- * @v refcnt		Job control interface reference counting method
+ * @v refcnt		Containing object reference counter, or NULL
  */
 static inline void job_init ( struct job_interface *job,
-			       struct job_interface_operations *op,
-			       void ( * refcnt ) ( struct interface *intf,
-						   int delta ) ) {
+			      struct job_interface_operations *op,
+			      struct refcnt *refcnt ) {
 	job->intf.dest = &null_job.intf;
 	job->intf.refcnt = refcnt;
 	job->op = op;

src/include/gpxe/refcnt.h

@@ -0,0 +1,39 @@
+#ifndef _GPXE_REFCNT_H
+#define _GPXE_REFCNT_H
+
+/** @file
+ *
+ * Reference counting
+ *
+ */
+
+/**
+ * A reference counter
+ *
+ * This data structure is designed to be embedded within a
+ * reference-counted object.
+ */
+struct refcnt {
+	/** Current reference count
+	 *
+	 * When this count is decremented below zero, the free()
+	 * method will be called.
+	 */
+	int refcnt;
+	/** Free containing object
+	 *
+	 * This method is called when the reference count is
+	 * decremented below zero.
+	 *
+	 * If this method is left NULL, the standard library free()
+	 * function will be called.  The upshot of this is that you
+	 * may omit the free() method if the @c refcnt object is the
+	 * first element of your reference-counted struct.
+	 */
+	void ( * free ) ( struct refcnt *refcnt );
+};
+
+extern void ref_get ( struct refcnt *refcnt );
+extern void ref_put ( struct refcnt *refcnt );
+
+#endif /* _GPXE_REFCNT_H */

src/include/gpxe/xfer.h

@@ -114,12 +114,11 @@ extern int ignore_deliver_raw ( struct xfer_interface *xfer,
  *
  * @v xfer		Data transfer interface
  * @v op		Data transfer interface operations
- * @v refcnt		Data transfer interface reference counting method
+ * @v refcnt		Containing object reference counter, or NULL
  */
 static inline void xfer_init ( struct xfer_interface *xfer,
 			       struct xfer_interface_operations *op,
-			       void ( * refcnt ) ( struct interface *intf,
-						   int delta ) ) {
+			       struct refcnt *refcnt ) {
 	xfer->intf.dest = &null_xfer.intf;
 	xfer->intf.refcnt = refcnt;
 	xfer->op = op;