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