added a new section on converse one sided communication interface.
[charm.git] / doc / converse / onesided.tex
1 \chapter{\converse{} One Sided Communication Interface}
2
3 This chapter deals with one sided communication support in converse.
4 It is imperative to provide a one-sided communication interface to take
5 advantage of the hardware RDMA facilities provided by a lot of NIC cards.
6 Drivers for these hardware provide or promise to soon provide capabilities
7 to use this feature. 
8
9 \converse{} provides an implementation which wraps the functionality provided
10 by different hardware and presents them as a uniform interface to the
11 programmer. For machines which do not have a one-sided hardware at their
12 disposal, these operations are emulated through converse messages.
13
14 \converse{} provides the following types of operations to support one-sided
15 communication.
16
17
18 \section{Registering / Unregistering Memory for RDMA}
19 The interface provides functions to register(pin) and unregister(unpin) memory
20 on the NIC hardware. The emulated version of these operations do not do anything.
21
22 \function{int CmiRegisterMemory(void *addr, unsigned int size);}
23 \index{CmiRegister}
24 \desc{This function takes an allocated memory at starting address {\it addr} 
25 of length {\it size} and registers it with the hardware NIC, 
26 thus making this memory DMAable. This is also called pinning memory on the
27 NIC hardware, making remote DMA operations on this memory possible.
28 This directly calls the hardware driver function for registering the memory
29 region and is usually an expensive operation, so should be used sparingly.}
30
31 \function{int CmiUnRegisterMemory(void *addr, unsigned int size);}
32 \index{CmiUnregister}
33 \desc{This function unregisters the memory at starting address {\it addr} 
34 of length {\it size}, making it no longer DMAable. This operation corresponds
35 to unpinning memory from the NIC hardware. This is also an expensive operation
36 and should be sparingly used.}
37
38 For certain machine layers which support a DMA, we support the function
39 \function{void *CmiDMAAlloc(int size);}
40 \index{CmiDMAAlloc}
41 \desc{This operation allocates a memory region of length {\it size} from the 
42 DMAable region on the NIC hardware. The memory region returned is pinned to the
43 NIC hardware. This is an alternative to {\it CmiRegisterMemory} and is implemented
44 only for hardwares that support this.}
45
46
47 \section{RDMA operations (Get / Put)}
48 This section presents functions that provide the actual RDMA operations.
49 For hardware architectures that support these operations these functions 
50 provide a standard interface to the operations, while for NIC architectures that
51 do not support RDMA operations, we provide an emulated implementation.
52 There are three types of NIC architectures based on how much support they
53 provide for RDMA operations:
54 \begin{itemize}
55 \item Hardware support for both {\it Get} and {\it Put} operations.
56 \item Hardware support for one of the two operations, mostly for {\it Put}. For these
57 the other RDMA operation is emulated by using the operation that is implemented
58 in hardware and extra messages.
59 \item No hardware support for any RDMA operation. For these, both the RDMA operations
60 are emulated through messages.
61 \end{itemize}
62
63 The RDMA operations return an opaque handle to the programmer, which can 
64 only be used to verify if the operation is complete.
65
66 {\bf For machine layer developer:} Internally, every machine layer is free
67 to create a suitable data structure for this purpose. This is the reason this
68 has been kept opaque from the programmer.
69
70 \function{void *CmiPut(unsinged int sourceId, unsigned int targetId, void &Saddr, void *Taadr, unsigned int size);}
71 \index{CmiPut}
72 \desc{This function is pretty self explanatory. It puts the memory location 
73 at {\it Saddr} on the machine specified by {\it sourceId} to {\it Taddr} on
74 the machine specified by {\it targetId}. The memory region being RDMA'ed is
75 of length {\it size} bytes.}
76
77 \function{void *CmiGet(unsinged int sourceId, unsigned int targetId, void &Saddr, void *Taadr, unsigned int size);}
78 \index{CmiGet}
79 \desc{Exactly similar to {\it CmiPut} except the direction of the data transfer
80 is opposite; from target to source.}
81
82
83 \section{Completion of RDMA operation}
84 This section presents functions that are used to check for completion
85 of an RDMA operation. The one sided communication operations are
86 asynchronous, thus there needs to be a mechanism to verify for completion.
87 One mechanism is for the programmer to check for completion. The other 
88 mechanism is through callback functions registered during the RDMA operations.
89
90 \function{int CmiWaitTest(void *obj);}
91 \index{CmiWaitTest}
92 \desc{This function takes this RDMA handle and verifies if the operation
93 corresponding to this handle has completed.}
94
95 A typical usage of this function would be in AMPI when there is a call to
96 AMPI_Wait. The implementation should call the CmiWaitTest for all 
97 pending RDMA operations in that window.