============================== begin LWG_RFC ===============================

LWG_RFC00002-0

SPE Runtime mailbox functions

------------------------------------------------------------------------

Severity: 2 		Status: submitted	Date attained: 03/31/2006
	  		Resolution: <r>		Date resolved: <mm/dd/yy>
						Date made: <mm/dd/yy>

Summary: Correct inconsistencies and limitation is the MFC mailbox functions
provided by the SPE Runtime Managment library

Documents effected: 
	 SPE Runtime Management Library		Version: 1.1


Sections and pages effected:
	 SPE Runtime Management Library		page 26
	 
	 Change the C Specification to read:

	 "#include <libspe.h>
	  int spe_read_out_mbox(speid_t speid, size_t entries, unsigned int *data);"
	 Change the Description to read:

	 "The spe_read_out_mbox functions returns a requested number of 
	  outbound mailbox entries, as specified by the entries parameter, 
	  corresponding to the SPE thread specified by the speid parameter,
	  to the array specified by data. 

	  This read has blocking symantics such that control is not returned 
	  to the caller until all the requested entries are read. To avoid 
	  blocking, spe_stat_out_mbox can be called to determine the 
	  number of available mailbox entries prior to reading the outbound
	  mailbox."

	 Add the following additional Parameters:

	 "entries    Specifies the number of 32-bit mailbox entries to be read
		     from the outbound mailbox

	  data	     Pointer to the array in which the mailbox entries are to
		     be placed. The array must be sufficiently large to hold
		     the requested number of mailbox entries."

	 Change the Return Values description to read:

	 "On success, spe_read_out_mbox returns 0 and the data array is filled
	  with the specified number of mailbox entries. On failure, -1 is 
	  returned."

	 SPE Runtime Management Library		page 27

	 Remove the spe_stat_out_intr_mbox function.

	 SPE Runtime Management Library		page 28

	 Change the C Specification to read:

	 "#include <libspe.h>
	  int spe_write_in_mbox(speid_t speid, size_t entries, unsigned int *data);"
	 Change the Description to read:

	 "The spe_write_in_mbox functions places the requested number of 
	  32-bit mailbox entries into the inbound mailbox for the SPE thread 
	  specified by the speid parameter. The entries parameter specifies 
	  the requested number data array elements to be written to the 
	  inbound mailbox.

	  This write has blocking symantics such that control is not returned 
	  to the caller until all the requested data is written to the mailbox.
	  To avoid blocking, spe_stat_in_mbox can be called to determine the 
	  number of available mailbox entries prior to writing to the inbound
	  mailbox."

	 Add the following additional Parameters:

	 "entries    Specifies the number of 32-bit mailbox entries to be 
		     written to the inbound mailbox

	  data	     Pointer to the array of data to be written into the 
		     inbound mailbox."


Submitter:	Dan Brokenshire		Date accepted: 03/31/2006
Requester:	Dan Brokenshire
Assigned to: 	Dan Brokenshire
Impact on software: libspe, many testcases and code samples
Keywords: 	MFC, mailboxes

------------------------------------------------------------------------

The current SPE Runtime Management Library mailbox functions have several
limitations and inconsistencies. This include:
 * spe_read_out_mbox is specified to return -1 if no mailbox data is available.
   With such an interface, programmers have no way to destinguish between no
   available data and data equal to -1 without "stat"ing the mailbox before
   reading. 
 * spe_write_in_mbox is specified to overwrite the last mailbox entry if it is
   full and that spe_stat_in_mbox must be called to ensure space is available 
   before writing to the queue. The current implementation actually blocks
   waiting for available space.
 * Mailboxes are defined to have capacity. However, this interface only allows
   one to read and write a single word at a time. This becomes inefficient for
   applications that which to send multiple words at a time through the 
   mailbox.
 * The spe_stat_out_intr_mbox routine appears to be senseless without the
   ability to read the outbound interrupting mailbox. Since the interrupting 
   mailbox data is read by the operating system and buffered in the event 
   queue, the need for "stat"ing the outbound interrupting mailbox does not
   exist.

This RFC proposes the following changes to address all of these issues. 
1) Modify the spe_read_out_mbox function to:
   - Add an additional size_t parameter that specifies the number of mailbox 
     entries to be read. 
   - Add an additional unsigned int * parameter to for returning mailbox data.
   - Change the return value to an int that returns success status only.
   - Change the documentation to indicate that the function blocks until all
     the requested data is read or an error is detected.
2) Modify the spe_write_in_mbox function to:
   - Add an additional size_t parameter that specifies the number 32-bit data
     words to be written to the SPE's inbound mailbox.
   - Change the data type of the "data" parameter to be a pointer to an 
     unsigned integer.
   - Change the description to state that control is not returned to the 
     caller until the "data" is successfully placed in the SPE threads mailbox
     and 0 is returned. If the specified thread is invalid or terminates before
     the data is written to the mailbox, then -1 is returned.
3) Remove the spe_stat_out_intr_mbox function.

=============================== end LWG_RFC ================================