GASNet portals4-conduit documentation -*- text -*-
Brian Barrett <bwbarre@sandia.gov>

User Information:
-----------------

Portals 4 is the next generation network programming interface developed
at Sandia National Laboratories, building on the lessons learned from the
Portals 3.3 specification.  Information on Portals, including a copy of
the specification,  can be found at the Sandia Portals page:

  http://www.cs.sandia.gov/Portals/

A reference implementation of Portals 4.0 which runs over InfiniBand and
UDP is available at:

  https://code.google.com/p/portals4/

Recognized environment variables:
---------------------------------

* All the standard GASNet environment variables (see top-level README)

Optional compile-time settings:
------------------------------

* All the compile-time settings from extended-ref (see the extended-ref README)

Known problems:
---------------

* See the Berkeley UPC Bugzilla server for details on known bugs.

Future work:
------------

* Implement the extended API directly over Portals 4.


==============================================================================

Design Overview:
----------------

* Usage of Portals header fields...
 header data: op count
 match bits used on AM_PT
   0 1 23 4567 0 1234567 0 1234567 01234567 01234567 01234567 01234567 01234567
  | | |  |      |         |             payload length
   ^ ^ ^    ^      ^
   | | |    |      +--- handler id
   | | |    +--- AM argument count
   | | +--- Protocol: AM_SHORT, AM_MEDIUM, AM_LONG, or AM_LONG_PACKED
   | +--- Request/Response: AM_REQUEST or AM_REPLY (0 if LONG_DATA) 
   +-- Type: ACTIVE_MESSAGE or LONG_DATA

* Short messages:
   Type: ACTIVE_MESSAGE
   Req/Rep: as specified
   Protocol: AM_SHORT
   AM argument count: as specied
   handler id: as specified
   payload length: 0
   data:
     <AM argument count * 4 bytes of arguments>

* Medium messages:
   Type: ACTIVE_MESSAGE
   Req/Rep: as specified
   Protocol: AM_MEDIUM
   AM argument count: as specied
   handler id: as specified
   payload length: as specified (nbytes)
   data:
     <AM argument count * 4 bytes of arguments>
     <nbytes of payload>

* Long Packable messages (nbytes < 2048 - 8)
   Type: ACTIVE_MESSAGE
   Req/Rep: as specified
   Protocol: AM_LONG_PACKED
   AM argument count: as specied
   handler id: as specified
   payload length: as specified (nbytes)
   data:
     <AM argument count * 4 bytes of arguments>
     <uint64_t remote address>
     <nbytes of payload>

* Long Messages
   Type: ACTIVE_MESSAGE
   Req/Rep: as specified
   Protocol: AM_LONG
   AM argument count: as specied
   handler id: as specified
   payload length: 0;
   data:
     <AM argument count * 4 bytes of arguments>

   Type: LONG_DATA
   Req/Rep: as specified
   Protocol: AM_LONG
   AM argument count: 0
   handler id: 0
   payload length: 0
   data:
     <nbytes of data delivered direcly to target address>

   Note that the start + offset in the LONG_DATA gives you the remote
   address for the active message callback.


        

