Added doxygen comments and errno values.

src/arch/i386/image/nbi.c

@@ -4,22 +4,44 @@
 #include "gateA20.h"
 #include "osloader.h"
 #include "etherboot.h"
+#include "errno.h"
 
-/* An NBI image header */
+/** @file
+ *
+ * NBI image format.
+ *
+ * The Net Boot Image format is defined by the "Draft Net Boot Image
+ * Proposal 0.3" by Jamie Honan, Gero Kuhlmann and Ken Yap.  It is now
+ * considered to be a legacy format, but it still included because a
+ * large amount of software (e.g. nymph, LTSP) makes use of NBI files.
+ *
+ * Etherboot does not implement the INT 78 callback interface
+ * described by the NBI specification.  For a callback interface on
+ * x86 architecture, use PXE.
+ *
+ */
+
+/**
+ * An NBI image header
+ *
+ * Note that the length field uses a peculiar encoding; use the
+ * NBI_LENGTH() macro to decode the actual header length.
+ *
+ */
 struct imgheader {
-	unsigned long magic;
+	unsigned long magic;		/**< Magic number (NBI_MAGIC) */
 	union {
-		unsigned char length;
-		unsigned long flags;
+		unsigned char length;	/**< Nibble-coded header length */
+		unsigned long flags;	/**< Image flags */
 	};
-	segoff_t location;
+	segoff_t location;		/**< 16-bit seg:off header location */
 	union {
-		segoff_t segoff;
-		unsigned long linear;
+		segoff_t segoff;	/**< 16-bit seg:off entry point */
+		unsigned long linear;	/**< 32-bit entry point */
 	} execaddr;
 } __attribute__ (( packed ));
 
-/* NBI magic number */
+/** NBI magic number */
 #define NBI_MAGIC 0x1B031336UL
 
 /* Interpretation of the "length" fields */
@@ -31,18 +53,24 @@ struct imgheader {
 #define	NBI_PROGRAM_RETURNS(flags)	( (flags) & ( 1 << 8 ) )
 #define	NBI_LINEAR_EXEC_ADDR(flags)	( (flags) & ( 1 << 31 ) )
 
-/* NBI header length */
+/** NBI header length */
 #define NBI_HEADER_LENGTH	512
 
-/* An NBI segment header */
+/**
+ * An NBI segment header
+ *
+ * Note that the length field uses a peculiar encoding; use the
+ * NBI_LENGTH() macro to decode the actual header length.
+ *
+ */
 struct segheader {
-	unsigned char length;
-	unsigned char vendortag;
+	unsigned char length;		/**< Nibble-coded header length */
+	unsigned char vendortag;	/**< Vendor-defined private tag */
 	unsigned char reserved;
-	unsigned char flags;
-	unsigned long loadaddr;
-	unsigned long imglength;
-	unsigned long memlength;
+	unsigned char flags;		/**< Segment flags */
+	unsigned long loadaddr;		/**< Load address */
+	unsigned long imglength;	/**< Segment length in NBI file */
+	unsigned long memlength;	/**< Segment length in memory */
 };
 
 /* Interpretation of the "flags" fields */
@@ -53,28 +81,41 @@ struct segheader {
 #define NBI_LOADADDR_BEFORE		0x03
 #define NBI_LAST_SEGHEADER(flags)	( (flags) & ( 1 << 2 ) )
 
-/* Info passed to NBI image */
+/** Info passed to NBI image */
 static struct ebinfo loaderinfo = {
 	VERSION_MAJOR, VERSION_MINOR,
 	0
 };
 
-/*
+/**
  * Determine whether or not this is a valid NBI image
  *
+ * @v start		Address of the image
+ * @v len		Length of the image
+ * @v context		NBI image context
+ * @ret	True		Image is a valid NBI image
+ * @ret	False		Image is not a valid NBI image
+ * @err	EBADIMG		Image is not a valid NBI image
+ * 
+ * "context" is filled in with a context pointer suitable for passing to
+ * nbi_load() and nbi_boot().
+ *
  */
 static int nbi_probe ( physaddr_t start, off_t len, void **context ) {
 	static struct imgheader imgheader;
 
 	if ( (unsigned)len < sizeof ( imgheader ) ) {
 		DBG ( "NBI image too small\n" );
+		errno = EBADIMG;
 		return 0;
 	}
 
 	copy_from_phys ( &imgheader, start, sizeof ( imgheader ) );
 
-	if ( imgheader.magic != NBI_MAGIC )
+	if ( imgheader.magic != NBI_MAGIC ) {
+		errno = EBADIMG;
 		return 0;
+	}
 
 	/* Record image context */
 	DBG ( "NBI found valid image\n" );
@@ -82,9 +123,17 @@ static int nbi_probe ( physaddr_t start, off_t len, void **context ) {
 	return 1;
 }
 
-/*
+/**
  * Prepare a segment for an NBI image
  *
+ * @v dest		Address of segment
+ * @v imglen		Length of initialised-data portion of the segment
+ * @v memlen		Total length of the segment
+ * @v src		Source for initialised data
+ * @ret True		Segment can be used
+ * @ret False		Segment cannot be used
+ * @err other		As returned by prep_segment()
+ *
  */
 static int nbi_prepare_segment ( physaddr_t dest, off_t imglen, off_t memlen,
 				 physaddr_t src __unused ) {
@@ -93,9 +142,15 @@ static int nbi_prepare_segment ( physaddr_t dest, off_t imglen, off_t memlen,
 	return prep_segment ( dest, dest + imglen, dest + memlen );
 }
 
-/*
+/**
  * Load a segment for an NBI image
  *
+ * @v dest		Address of segment
+ * @v imglen		Length of initialised-data portion of the segment
+ * @v memlen		Total length of the segment
+ * @v src		Source for initialised data
+ * @ret True		Always
+ *
  */
 static int nbi_load_segment ( physaddr_t dest, off_t imglen,
 			      off_t memlen __unused, physaddr_t src ) {
@@ -104,9 +159,18 @@ static int nbi_load_segment ( physaddr_t dest, off_t imglen,
 	return 1;
 }
 
-/*
+/**
  * Process segments of an NBI image
  *
+ * @v start		Address of the image
+ * @v len		Length of the image
+ * @v imgheader		Image header information
+ * @v process		Function to call for each segment
+ * @ret True		All segments were processed successfully
+ * @ret False		An error occurred processing a segment
+ * @err EBADIMG		Image is not a valid NBI image
+ * @err other		As returned by the "process" function
+ *
  */
 static int nbi_process_segments ( physaddr_t start, off_t len,
 				  struct imgheader *imgheader,
@@ -136,6 +200,7 @@ static int nbi_process_segments ( physaddr_t start, off_t len,
 		if ( sh.length == 0 ) {
 			/* Avoid infinite loop? */
 			DBG ( "NBI invalid segheader length 0\n" );
+			errno = EBADIMG;
 			return 0;
 		}
 		
@@ -159,8 +224,8 @@ static int nbi_process_segments ( physaddr_t start, off_t len,
 				- sh.loadaddr;
 			break;
 		default:
-			DBG ( "NBI can't count up to three\n" );
-			return 0;
+			/* Cannot be reached */
+			DBG ( "NBI can't count up to three!\n" );
 		}
 
 		/* Process this segment */
@@ -175,6 +240,7 @@ static int nbi_process_segments ( physaddr_t start, off_t len,
 		sh_off += NBI_LENGTH ( sh.length );
 		if ( sh_off >= NBI_HEADER_LENGTH ) {
 			DBG ( "NBI header overflow\n" );
+			errno = EBADIMG;
 			return 0;
 		}
 
@@ -183,22 +249,35 @@ static int nbi_process_segments ( physaddr_t start, off_t len,
 	if ( offset != len ) {
 		DBG ( "NBI length mismatch (file %d, metadata %d)\n",
 		      len, offset );
+		errno = EBADIMG;
 		return 0;
 	}
 
 	return 1;
 }
 
-/*
+/**
  * Load an NBI image into memory
  *
+ * @v start		Address of image
+ * @v len		Length of image
+ * @v context		NBI context (as returned by nbi_probe())
+ * @ret True		Image loaded into memory
+ * @ret False		Image not loaded into memory
+ * @err EBADIMG		Image is not a valid NBI image
+ * @err other		As returned by nbi_process_segments()
+ * @err other		As returned by nbi_prepare_segment()
+ * @err other		As returned by nbi_load_segment()
+ *
  */
 static int nbi_load ( physaddr_t start, off_t len, void *context ) {
 	struct imgheader *imgheader = context;
 
 	/* If we don't have enough data give up */
-	if ( len < NBI_HEADER_LENGTH )
+	if ( len < NBI_HEADER_LENGTH ) {
+		errno = EBADIMG;
 		return 0;
+	}
 	
 	DBG ( "NBI placing header at %hx:%hx\n",
 	      imgheader->location.segment, imgheader->location.offset );
@@ -220,9 +299,14 @@ static int nbi_load ( physaddr_t start, off_t len, void *context ) {
 	return 1;
 }
 
-/*
+/**
  * Boot a 16-bit NBI image
  *
+ * @v imgheader		Image header information
+ * @ret Never		NBI program booted successfully
+ * @ret False		NBI program returned
+ * @err EIMGRET		NBI program returned
+ *
  */
 static int nbi_boot16 ( struct imgheader *imgheader ) {
 	uint16_t basemem_bootp;
@@ -256,12 +340,23 @@ static int nbi_boot16 ( struct imgheader *imgheader ) {
 		    CLOBBER ( "eax", "ecx", "edx", "ebp" ) );
 	BASEMEM_PARAMETER_DONE ( bootp_data );
 	
+	errno = EIMGRET;
 	return 0;
 }
 
-/*
+/**
  * Boot a 32-bit NBI image
  *
+ * @v imgheader		Image header information
+ * @ret False		NBI program should not have returned
+ * @ret other		As returned by NBI program
+ * @err EIMGRET		NBI program should not have returned
+ *
+ * To distinguish between the case of an NBI program returning false,
+ * and an NBI program that should not have returned, check errno.
+ * errno will be set to EIMGRET only if the NBI program should not
+ * have returned.
+ *
  */
 static int nbi_boot32 ( struct imgheader *imgheader ) {
 	int rc = 0;
@@ -270,6 +365,7 @@ static int nbi_boot32 ( struct imgheader *imgheader ) {
 	      imgheader->execaddr.linear );
 
 	/* no gateA20_unset for PM call */
+	errno = ENOERR;
 	rc = xstart32 ( imgheader->execaddr.linear,
 			virt_to_phys ( &loaderinfo ),
 			( ( imgheader->location.segment << 4 ) +
@@ -278,15 +374,24 @@ static int nbi_boot32 ( struct imgheader *imgheader ) {
 	printf ( "Secondary program returned %d\n", rc );
 	if ( ! NBI_PROGRAM_RETURNS ( imgheader->flags ) ) {
 		/* We shouldn't have returned */
+		errno = EIMGRET;
 		rc = 0;
 	}
 
 	return rc;
 }
 
-/*
+/**
  * Boot a loaded NBI image
  *
+ * @v context		NBI context (as returned by nbi_probe())
+ * @ret Never		NBI program booted successfully
+ * @ret False		NBI program should not have returned
+ * @ret other		As returned by NBI program
+ * @err EIMGRET		NBI program should not have returned
+ *
+ * See also nbi_boot16() and nbi_boot32().
+ *
  */
 static int nbi_boot ( void *context ) {
 	struct imgheader *imgheader = context;
@@ -298,6 +403,7 @@ static int nbi_boot ( void *context ) {
 	}
 }
 
+/** Declaration of the NBI image format */
 static struct image nbi_image __image = {
 	.name	= "NBI",
 	.probe	= nbi_probe,