Whamcloud - gitweb
b=16046
[fs/lustre-release.git] / lnet / doc / NAL-HOWTO
1 This document is a first attempt at describing how to write a NAL
2 for the Portals 3 library.  It also defines the library architecture
3 and the abstraction of protection domains.
4
5
6 First, an overview of the architecture:
7
8     Application
9
10 ----|----+--------
11          |
12    API  === NAL        (User space)
13          |   
14 ---------+---|-----
15          |    
16    LIB  === NAL        (Library space)
17          |
18 ---------+---|-----
19           
20     Physical wire      (NIC space)
21           
22
23 Application
24     API
25 API-side NAL
26 ------------
27 LIB-side NAL
28     LIB
29 LIB-side NAL
30    wire
31
32 Communication is through the indicated paths via well defined
33 interfaces.  The API and LIB portions are written to be portable
34 across platforms and do not depend on the network interface.
35
36 Communcation between the application and the API code is
37 defined in the Portals 3 API specification.  This is the
38 user-visible portion of the interface and should be the most
39 stable.
40
41
42
43 API-side NAL:
44 ------------
45
46 The user space NAL needs to implement only a few functions
47 that are stored in a nal_t data structure and called by the
48 API-side library:
49
50         int forward( nal_t *nal,
51                 int     index,
52                 void    *args,
53                 size_t  arg_len,
54                 void    *ret,
55                 size_t  ret_len
56         );
57
58 Most of the data structures in the portals library are held in
59 the LIB section of the code, so it is necessary to forward API
60 calls across the protection domain to the library.  This is
61 handled by the NAL's forward method.  Once the argument and return
62 blocks are on the remote side the NAL should call lib_dispatch()
63 to invoke the appropriate API function.
64
65         int validate( nal_t *nal,
66                 void    *base,
67                 size_t  extent,
68                 void    **trans_base,
69                 void    **trans_data
70         );
71
72 The validate method provides a means for the NAL to prevalidate
73 and possibly pretranslate user addresses into a form suitable
74 for fast use by the network card or kernel module.  The trans_base
75 pointer will be used by the library everytime it needs to
76 refer to the block of memory.  The trans_data result is a
77 cookie that will be handed to the NAL along with the trans_base.
78
79 The library never performs calculations on the trans_base value;
80 it only computes offsets that are then handed to the NAL.
81
82
83         int shutdown( nal_t *nal, int interface );
84
85 Brings down the network interface.  The remote NAL side should
86 call lib_fini() to bring down the library side of the network.
87
88         void yield( nal_t *nal );
89
90 This allows the user application to gracefully give up the processor
91 while busy waiting.  Performance critical applications may not
92 want to take the time to call this function, so it should be an
93 option to the PtlEQWait call.  Right now it is not implemented as such.
94
95 Lastly, the NAL must implement a function named PTL_IFACE_*, where
96 * is the name of the NAL such as PTL_IFACE_IP or PTL_IFACE_MYR.
97 This initialization function is to set up communication with the
98 library-side NAL, which should call lib_init() to bring up the
99 network interface.
100
101
102
103 LIB-side NAL:
104 ------------
105
106 On the library-side, the NAL has much more responsibility.  It
107 is responsible for calling lib_dispatch() on behalf of the user,
108 it is also responsible for bringing packets off the wire and
109 pushing bits out.  As on the user side, the methods are stored
110 in a nal_cb_t structure that is defined on a per network
111 interface basis.
112
113 The calls to lib_dispatch() need to be examined.  The prototype:
114
115         void    lib_dispatch(
116                         nal_cb_t                *nal,
117                         void                    *private,
118                         int                     index,
119                         void                    *arg_block,
120                         void                    *ret_block
121         );
122
123 has two complications.  The private field is a NAL-specific
124 value that will be passed to any callbacks produced as a result
125 of this API call.  Kernel module implementations may use this
126 for task structures, or perhaps network card data.  It is ignored
127 by the library.
128
129 Secondly, the arg_block and ret_block must be in the same protection
130 domain as the library.  The NAL's two halves must communicate the
131 sizes and perform the copies.  After the call, the buffer pointed
132 to by ret_block will be filled in and should be copied back to
133 the user space.  How this is to be done is NAL specific.
134
135         int lib_parse(
136                         nal_cb_t                *nal,
137                         ptl_hdr_t               *hdr,
138                         void                    *private
139         );
140
141 This is the only other entry point into the library from the NAL.
142 When the NAL detects an incoming message on the wire it should read
143 sizeof(ptl_hdr_t) bytes and pass a pointer to the header to
144 lib_parse().  It may set private to be anything that it needs to
145 tie the incoming message to callbacks that are made as a result
146 of this event.
147
148 The method calls are:
149
150         int     (*send)(
151                         nal_cb_t                *nal,
152                         void                    *private,
153                         lib_msg_t               *cookie,
154                         ptl_hdr_t               *hdr,
155                         int                     nid,
156                         int                     pid,
157                         int                     gid,
158                         int                     rid,
159                         user_ptr                trans_base,
160                         user_ptr                trans_data,
161                         size_t                  offset,
162                         size_t                  len
163         );
164
165 This is a tricky function -- it must support async output
166 of messages as well as properly syncronized event log writing.
167 The private field is the same that was passed into lib_dispatch()
168 or lib_parse() and may be used to tie this call to the event
169 that initiated the entry to the library.
170
171 The cookie is a pointer to a library private value that must
172 be passed to lib_finalize() once the message has been completely
173 sent.  It should not be examined by the NAL for any meaning.
174
175 The four ID fields are passed in, although some implementations
176 may not use all of them.
177
178 The single base pointer has been replaced with the translated
179 address that the API NAL generated in the api_nal->validate()
180 call.  The trans_data is unchanged and the offset is in bytes.
181
182
183         int     (*recv)(
184                         nal_cb_t                *nal,
185                         void                    *private,
186                         lib_msg_t               *cookie,
187                         user_ptr                trans_base,
188                         user_ptr                trans_data,
189                         size_t                  offset,
190                         size_t                  mlen,
191                         size_t                  rlen
192         );
193
194 This callback will only be called in response to lib_parse().
195 The cookie, trans_addr and trans_data  are as discussed in send().
196 The NAL should read mlen bytes from the wire, deposit them into
197 trans_base + offset and then discard (rlen - mlen) bytes.
198 Once the entire message has been received the NAL should call
199 lib_finalize() with the lib_msg_t *cookie.
200
201 The special arguments of base=NULL, data=NULL, offset=0, mlen=0, rlen=0
202 is used to indicate that the NAL should clean up the wire.  This could
203 be implemented as a blocking call, although having it return as quickly
204 as possible is desirable.
205
206         int     (*write)(
207                         nal_cb_t                *nal,
208                         void                    *private,
209                         user_ptr                trans_addr,
210                         user_ptr                trans_data,
211                         size_t                  offset,
212
213                         void                    *src_addr,
214                         size_t                  len
215         );
216
217 This is essentially a cross-protection domain memcpy().  The user address
218 has been pretranslated by the api_nal->translate() call.
219
220         void    *(*malloc)(
221                         nal_cb_t                *nal,
222                         size_t                  len
223         );
224
225         void    (*free)(
226                         nal_cb_t                *nal,
227                         void                    *buf
228         );
229
230 Since the NAL may be in a non-standard hosted environment it can
231 not call malloc().  This allows the library side NAL to implement
232 the system specific malloc().  In the current reference implementation
233 the libary only calls nal->malloc() when the network interface is
234 initialized and then calls free when it is brought down.  The library
235 maintains its own pool of objects for allocation so only one call to
236 malloc is made per object type.
237
238         void    (*invalidate)(
239                         nal_cb_t                *nal,
240                         user_ptr                trans_base,
241                         user_ptr                trans_data,
242                         size_t                  extent
243         );
244
245 User addresses are validated/translated at the user-level API NAL
246 method, which is likely to push them to this level.  Meanwhile,
247 the library NAL will be notified when the library no longer
248 needs the buffer.  Overlapped buffers are not detected by the
249 library, so the NAL should ref count each page involved.
250
251 Unfortunately we have a few bugs when the invalidate method is
252 called.  It is still in progress...
253
254         void    (*printf)(
255                         nal_cb_t                *nal,
256                         const char              *fmt,
257                         ...
258         );
259
260 As with malloc(), the library does not have any way to do printf
261 or printk.  It is not necessary for the NAL to implement the this
262 call, although it will make debugging difficult.
263
264         void    (*cli)(
265                         nal_cb_t                *nal,
266                         unsigned long           *flags
267         );
268
269         void    (*sti)(
270                         nal_cb_t                *nal,
271                         unsigned long           *flags
272         );
273
274 These are used by the library to mark critical sections.
275
276         int     (*gidrid2nidpid)(
277                         nal_cb_t                *nal,
278                         ptl_id_t                gid,
279                         ptl_id_t                rid,
280                         ptl_id_t                *nid,
281                         ptl_id_t                *pid
282         );
283
284
285         int     (*nidpid2gidrid)(
286                         nal_cb_t                *nal,
287                         ptl_id_t                nid,
288                         ptl_id_t                pid,
289                         ptl_id_t                *gid,
290                         ptl_id_t                *rid
291         );
292
293 Rolf added these.  I haven't looked at how they have to work yet.