Fix large message bug in SI95 data callback

The receive buffer was not being allocated correctly and in some
cases would cause a segment fault when a large buffer was received.
The fix also includes dropping a message which is larger than the
allocated message.  The rmr_init() manual page has been updated to
better define the meaning of the max message length pararmeter which
is passed.

Signed-off-by: E. Scott Daniels <daniels@research.att.com>
Change-Id: I20eb0d7ed8ba914b380807d9b3142d51d4f9f0b6
diff --git a/docs/rel-notes.rst b/docs/rel-notes.rst
index 35c181f..a9b2ab7 100644
--- a/docs/rel-notes.rst
+++ b/docs/rel-notes.rst
@@ -15,6 +15,46 @@
 completely up to date listing of API changes. 
  
  
+2020 January 24; verison 3.0.5 
+-------------------------------------------------------------------------------------------- 
+ 
+Fix bug in SI95 with receive buffer allocation. 
+ 
+ 
+2020 January 23; verison 3.0.4 
+-------------------------------------------------------------------------------------------- 
+ 
+Fix bug in SI95 causing excessive CPU usage on poll. 
+ 
+ 
+2020 January 22; verison 3.0.3 
+-------------------------------------------------------------------------------------------- 
+ 
+Enable thread support for multiple receive threads. 
+ 
+ 
+2020 January 21; verison 3.0.2 
+-------------------------------------------------------------------------------------------- 
+ 
+Fix bug in SI95 (missing reallocate payload function). 
+ 
+ 
+2020 January 20; verison 3.0.1 
+-------------------------------------------------------------------------------------------- 
+ 
+Enable support for dynamic route table updates via RMR 
+session. 
+ 
+ 
+2020 January 16; version 3.0.0 
+-------------------------------------------------------------------------------------------- 
+ 
+Introduce support for SI95 transport library to replace NNG. 
+(RMR library versions will use leading odd numbers to avoid 
+tag collisions with the wrapper tags which will use even 
+numbers.) 
+ 
+ 
 2019 December 9; version 1.13.1 
 -------------------------------------------------------------------------------------------- 
  
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index ad62076..c0b7bc8 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -1180,10 +1180,16 @@
 library to send messages. 
  
 *Port* is used to listen for connection requests from other 
-RMR based applications. The value of *max_msg_size* will be 
-used when allocating zero copy send buffers which must be 
-allocated, possibly, prior to the application knowing the 
-actual size of a specific message. 
+RMR based applications. The *max_msg_size* parameter is used 
+to allocate receive buffers and is the maximum message size 
+which the application expects to receive. This value is the 
+sum of **both** the maximum payload size **and** the maximum 
+trace data size. This value is also used as the default 
+message size when allocating message buffers. Messages 
+arriving which are longer than the given maximum will be 
+dropped without notification to the application. A warning is 
+written to standard error for the first message which is too 
+large on each connection. 
  
 *Flags* allows for selection of some RMr options at the time 
 of initialisation. These are set by ORing RMRFL constants 
@@ -1207,6 +1213,15 @@
 RMRFL_MTCALL 
    
   Enable multi-threaded call support. 
+   
+  &ditem Some underlying transport providers (e.g. SI95) 
+  enable locking to be turned off if the user application is 
+  single threaded, or otherwise can guarantee that RMR 
+  functions will not be invoked concurrently from different 
+  threads. Turning off locking can help make message receipt 
+  more efficient. If this flag is set when the underlying 
+  transport does not support disabling locks, it will be 
+  ignored. 
  
  
 Multi-threaded Calling 
@@ -1218,7 +1233,7 @@
 safely use the function. Further, timeouts were message count 
 based and not time unit based. Multi-threaded call support 
 adds the ability for a user application with multiple threads 
-to invoke a blocking call function with the guarentee that 
+to invoke a blocking call function with the guarantee that 
 the correct response message is delivered to the thread. The 
 additional support is implemented with the *rmr_mt_call()* 
 and *rmr_mt_rcv()* function calls. 
@@ -2463,7 +2478,7 @@
 On success, a new message buffer, with an empty payload, is 
 returned for the application to use for the next send. The 
 state in this buffer will reflect the overall send operation 
-state and should be RMR_OK. 
+state and will be RMR_OK when the send was successful. 
  
 When the message cannot be successfully sent this function 
 will return the unsent (original) message buffer with the 
@@ -2476,6 +2491,15 @@
 documentation, but there will be little that the user 
 application can do other than to move on. 
  
+**CAUTION:** In some cases it is extremely likely that the 
+message returned by the send function does **not** reference 
+the same memory structure. Thus is important for the user 
+programme to capture the new pointer for future use or to be 
+passed to rmr_free(). If you are experiencing either double 
+free errors or segment faults in either rmr_free() or 
+rmr_send_msg(), ensure that the return value from this 
+function is being captured and used. 
+ 
 ERRORS 
 -------------------------------------------------------------------------------------------- 
  
@@ -2605,19 +2629,18 @@
       }
       // reference payload and fill in message type
      pm = (msg_t*) send_msg->payload;
-     send_msg->mtype = MT_ANSWER;    
-     msg->len = generate_data( pm );         e// something that fills the payload in
-     msg = rmr_send_msg( mr, send_msg );
+     send_msg->mtype = MT_ANSWER;
+     msg->len = generate_data( pm );       // something that fills the payload in
+     msg = rmr_send_msg( mr, send_msg );   // ensure new pointer used after send
      mif( ! msg ) {
      m    !return ERROR;
      m} else {
      m    sif( msg->state != RMR_OK ) {
-     m    s    m// check for eagain, and resend if needed
+     m    s    m// check for RMR_ERR_RETRY, and resend if needed
      m    s    m// else return error
      m    s}
      m}
      mreturn OK;
-     m    r    ;