mailbox_receive: Improved debug message when attempting to read messa…

…ge that does not fit.

storm/generic/mailbox.c

@@ -4,8 +4,7 @@
 //          Per Lundberg <per@chaosdev.io>
 
 // © Copyright 1999-2000 chaos development
-// © Copyright 2013 chaos development
-// © Copyright 2015-2016 chaos development
+// © Copyright 2013-2017 chaos development
 
 // Define this as TRUE if you are debugging this module.
 #define DEBUG           TRUE
@@ -485,8 +484,8 @@ return_type mailbox_receive(mailbox_id_type mailbox_id,
     }
     else
     {
-        // Need more space.
-        DEBUG_MESSAGE(DEBUG, "%x < %x", message_parameter->length, mailbox->first_message->length);
+        DEBUG_MESSAGE(DEBUG, "Message was too large (max %u bytes, message size was %u bytes)",
+                      message_parameter->length, mailbox->first_message->length);
 
         message_parameter->length = mailbox->first_message->length;
         mutex_kernel_signal(&tss_tree_mutex);

storm/include/storm/mailbox.h

@@ -1,21 +1,28 @@
 // Abstract: Mailbox structures
 // Author: Per Lundberg <per@chaosdev.io>
-
-// © Copyright 2000, 2013 chaos development.
+//
+// © Copyright 1999-2000 chaos development
+// © Copyright 2013-2017 chaos development
 
 #pragma once
 
 #include <storm/types.h>
 
-// Those parameters are passed to the mailbox system calls.
+// The message_parameter_type is a structure which gets passed in to mailbox_send and mailbox_receive.
 typedef struct
 {
     unsigned int protocol;
     unsigned int message_class;
 
+    // When receiving a message, the maximum size of a message that can be received. This is usually (but not necessarily) the
+    // number of bytes allocated for the 'data' pointer.
+    //
+    // When sending a message, this is the length of the message.
     unsigned int length;
 
     bool block;
 
+    // A pointer to the data buffer. Note that when receiving messages, this is presumed to be allocated by the caller already;
+    // mailbox_receive will not allocate memory for you.
     void *data;
 } message_parameter_type;