Whamcloud - gitweb
LU-5710 all: second batch of corrected typos and grammar errors
[fs/lustre-release.git] / lnet / doc / portals3.lyx
1 #LyX 1.2 created this file. For more info see http://www.lyx.org/
2 \lyxformat 220
3 \textclass report
4 \begin_preamble
5 \usepackage{fullpage}
6 \renewenvironment{comment}%
7 {\begin{quote}\textbf{Discussion}: \slshape}%
8 {\end{quote}}
9 \pagestyle{myheadings}
10 \end_preamble
11 \language american
12 \inputencoding auto
13 \fontscheme pslatex
14 \graphics default
15 \paperfontsize 10
16 \spacing single 
17 \papersize letterpaper
18 \paperpackage a4
19 \use_geometry 0
20 \use_amsmath 0
21 \use_natbib 0
22 \use_numerical_citations 0
23 \paperorientation portrait
24 \secnumdepth 2
25 \tocdepth 2
26 \paragraph_separation indent
27 \defskip medskip
28 \quotes_language english
29 \quotes_times 2
30 \papercolumns 1
31 \papersides 2
32 \paperpagestyle headings
33
34 \layout Title
35
36 The Portals 3.2 Message Passing Interface 
37 \newline 
38  Revision 1.1
39 \layout Author
40
41 Ron Brightwell
42 \begin_inset Foot
43 collapsed true
44
45 \layout Standard
46
47 R.
48  Brightwell and R.
49  Riesen are with the Scalable Computing Systems Department, Sandia National
50  Laboratories, P.O.
51  Box 5800, Albuquerque, NM\SpecialChar ~
52 \SpecialChar ~
53 87111-1110, bright@cs.sandia.gov, rolf@cs.sandia.gov.
54 \end_inset 
55
56 , Arthur B.
57  Maccabe
58 \begin_inset Foot
59 collapsed true
60
61 \layout Standard
62
63 A.
64  B.
65  Maccabe is with the Computer Science Department, University of New Mexico,
66  Albuquerque, NM\SpecialChar ~
67 \SpecialChar ~
68 87131-1386, maccabe@cs.unm.edu.
69 \end_inset 
70
71 , Rolf Riesen and Trammell Hudson
72 \layout Abstract
73
74 This report presents a specification for the Portals 3.2 message passing
75  interface.
76  Portals 3.2 is intended to allow scalable, high-performance network communicatio
77 n between nodes of a parallel computing system.
78  Specifically, it is designed to support a parallel computing platform composed
79  of clusters of commodity workstations connected by a commodity system area
80  network fabric.
81  In addition, Portals 3.2 is well suited to massively parallel processing
82  and embedded systems.
83  Portals 3.2 represents an adaption of the data movement layer developed
84  for massively parallel processing platforms, such as the 4500-node Intel
85  TeraFLOPS machine.
86  
87 \layout Standard
88
89
90 \begin_inset ERT
91 status Collapsed
92
93 \layout Standard
94
95 \backslash 
96 clearpage
97 \backslash 
98 pagenumbering{roman}
99 \backslash 
100 setcounter{page}{3}
101 \end_inset 
102
103
104 \layout Standard
105
106
107 \begin_inset LatexCommand \tableofcontents{}
108
109 \end_inset 
110
111
112 \layout Standard
113
114
115 \begin_inset ERT
116 status Collapsed
117
118 \layout Standard
119
120 \backslash 
121 cleardoublepage
122 \end_inset 
123
124
125 \layout Standard
126
127
128 \begin_inset FloatList figure
129
130 \end_inset 
131
132
133 \layout Standard
134
135
136 \begin_inset ERT
137 status Collapsed
138
139 \layout Standard
140
141 \backslash 
142 cleardoublepage
143 \end_inset 
144
145
146 \layout Standard
147
148
149 \begin_inset FloatList table
150
151 \end_inset 
152
153
154 \layout Standard
155
156
157 \begin_inset ERT
158 status Collapsed
159
160 \layout Standard
161
162 \backslash 
163 cleardoublepage
164 \end_inset 
165
166
167 \layout Chapter*
168
169 Summary of Changes for Revision 1.1
170 \layout Enumerate
171
172 Updated version number to 3.2 throughout the document
173 \layout Enumerate
174
175 Section 
176 \begin_inset LatexCommand \ref{sub:PtlGetId}
177
178 \end_inset 
179
180 : added 
181 \family typewriter 
182 PTL_SEGV
183 \family default 
184  to error list for 
185 \shape italic 
186 PtlGetId
187 \shape default 
188 .
189 \layout Enumerate
190
191 Section 
192 \begin_inset LatexCommand \ref{sec:meattach}
193
194 \end_inset 
195
196 : added 
197 \family typewriter 
198 PTL_ML_TOOLONG
199 \family default 
200  to error list for 
201 \shape italic 
202 PtlMEAttach
203 \shape default 
204 .
205 \layout Enumerate
206
207 Section 
208 \begin_inset LatexCommand \ref{sec:meunlink}
209
210 \end_inset 
211
212 : removed text referring to a list of associated memory descriptors.
213 \layout Enumerate
214
215 Section 
216 \begin_inset LatexCommand \ref{sec:mdfree}
217
218 \end_inset 
219
220 : added text to describe unlinking a free-floating memory descriptor.
221 \layout Enumerate
222
223 Table 
224 \begin_inset LatexCommand \ref{tab:types}
225
226 \end_inset 
227
228 : added entry for 
229 \family typewriter 
230 ptl_seq_t
231 \family default 
232 .
233 \layout Enumerate
234
235 Section 
236 \begin_inset LatexCommand \ref{sec:md-type}
237
238 \end_inset 
239
240 :
241 \begin_deeper 
242 \layout Enumerate
243
244 added definition of 
245 \family typewriter 
246 max_offset
247 \family default 
248 .
249 \layout Enumerate
250
251 added text to clarify 
252 \family typewriter 
253 PTL_MD_MANAGE_REMOTE
254 \family default 
255 .
256 \end_deeper 
257 \layout Enumerate
258
259 Section 
260 \begin_inset LatexCommand \ref{sec:mdattach}
261
262 \end_inset 
263
264 : modified text for 
265 \family typewriter 
266 unlink_op
267 \family default 
268 .
269 \layout Enumerate
270
271 Section 
272 \begin_inset LatexCommand \ref{sec:niinit}
273
274 \end_inset 
275
276 : added text to clarify multiple calls to 
277 \shape italic 
278 PtlNIInit
279 \shape default 
280 .
281 \layout Enumerate
282
283 Section 
284 \begin_inset LatexCommand \ref{sec:mdattach}
285
286 \end_inset 
287
288 : added text to clarify 
289 \family typewriter 
290 unlink_nofit
291 \family default 
292 .
293 \layout Enumerate
294
295 Section 
296 \begin_inset LatexCommand \ref{sec:receiving}
297
298 \end_inset 
299
300 : removed text indicating that an MD will reject a message if the associated
301  EQ is full.
302 \layout Enumerate
303
304 Section 
305 \begin_inset LatexCommand \ref{sec:mdfree}
306
307 \end_inset 
308
309 : added 
310 \family typewriter 
311 PTL_MD_INUSE
312 \family default 
313  error code and text to indicate that only MDs with no pending operations
314  can be unlinked.
315 \layout Enumerate
316
317 Table 
318 \begin_inset LatexCommand \ref{tab:retcodes}
319
320 \end_inset 
321
322 : added 
323 \family typewriter 
324 PTL_MD_INUSE
325 \family default 
326  return code.
327 \layout Enumerate
328
329 Section 
330 \begin_inset LatexCommand \ref{sec:event-type}
331
332 \end_inset 
333
334 : added user id field, MD handle field, and NI specific failure field to
335  the 
336 \family typewriter 
337 ptl_event_t
338 \family default 
339  structure.
340 \layout Enumerate
341
342 Table 
343 \begin_inset LatexCommand \ref{tab:types}
344
345 \end_inset 
346
347 : added 
348 \family typewriter 
349 ptl_ni_fail_t
350 \family default 
351 .
352 \layout Enumerate
353
354 Section 
355 \begin_inset LatexCommand \ref{sec:event-type}
356
357 \end_inset 
358
359 : added 
360 \family typewriter 
361 PTL_EVENT_UNLINK
362 \family default 
363  event type.
364 \layout Enumerate
365
366 Table 
367 \begin_inset LatexCommand \ref{tab:func}
368
369 \end_inset 
370
371 : removed 
372 \shape slanted 
373 PtlTransId
374 \shape default 
375 .
376 \layout Enumerate
377
378 Section 
379 \begin_inset LatexCommand \ref{sec:meattach}
380
381 \end_inset 
382
383 , Section 
384 \begin_inset LatexCommand \ref{sec:meinsert}
385
386 \end_inset 
387
388 , Section 
389 \begin_inset LatexCommand \ref{sec:put}
390
391 \end_inset 
392
393 : listed allowable constants with relevant fields.
394 \layout Enumerate
395
396 Table 
397 \begin_inset LatexCommand \ref{tab:func}
398
399 \end_inset 
400
401 : added 
402 \shape italic 
403 PtlMEAttachAny
404 \shape default 
405  function.
406 \layout Enumerate
407
408 Table 
409 \begin_inset LatexCommand \ref{tab:retcodes}
410
411 \end_inset 
412
413 : added 
414 \family typewriter 
415 PTL_PT_FULL
416 \family default 
417  return code for 
418 \shape italic 
419 PtlMEAttachAny
420 \shape default 
421 .
422 \layout Enumerate
423
424 Table 
425 \begin_inset LatexCommand \ref{tab:oconsts}
426
427 \end_inset 
428
429 : updated to reflect new event types.
430 \layout Enumerate
431
432 Section 
433 \begin_inset LatexCommand \ref{sec:id-type}
434
435 \end_inset 
436
437 : added 
438 \family typewriter 
439 ptl_nid_t
440 \family default 
441
442 \family typewriter 
443 ptl_pid_t
444 \family default 
445 , and 
446 \family typewriter 
447 ptl_uid_t
448 \family default 
449 .
450 \layout Chapter*
451
452 Summary of Changes for Version 3.1
453 \layout Section*
454
455 Thread Issues
456 \layout Standard
457
458 The most significant change to the interface from version 3.0 to 3.1 involves
459  the clarification of how the interface interacts with multi-threaded applicatio
460 ns.
461  We adopted a generic thread model in which processes define an address
462  space and threads share the address space.
463  Consideration of the API in the light of threads lead to several clarifications
464  throughout the document: 
465 \layout Enumerate
466
467 Glossary: 
468 \begin_deeper 
469 \layout Enumerate
470
471 added a definition for 
472 \emph on 
473 thread
474 \emph default 
475
476 \layout Enumerate
477
478 reworded the definition for 
479 \emph on 
480 process
481 \emph default 
482 .
483  
484 \end_deeper 
485 \layout Enumerate
486
487 Section\SpecialChar ~
488
489 \begin_inset LatexCommand \ref{sec:apiover}
490
491 \end_inset 
492
493 : added section\SpecialChar ~
494
495 \begin_inset LatexCommand \ref{sec:threads}
496
497 \end_inset 
498
499  to describe the multi-threading model used by the Portals API.
500  
501 \layout Enumerate
502
503 Section\SpecialChar ~
504
505 \begin_inset LatexCommand \ref{sec:ptlinit}
506
507 \end_inset 
508
509
510 \emph on 
511 PtlInit
512 \emph default 
513  must be called at least once and may be called any number of times.
514  
515 \layout Enumerate
516
517 Section\SpecialChar ~
518
519 \begin_inset LatexCommand \ref{sec:ptlfini}
520
521 \end_inset 
522
523
524 \emph on 
525 PtlFini
526 \emph default 
527  should be called once as the process is terminating and not as each thread
528  terminates.
529  
530 \layout Enumerate
531
532 Section\SpecialChar ~
533
534 \begin_inset LatexCommand \ref{sec:pid}
535
536 \end_inset 
537
538 : Portals does not define thread ids.
539  
540 \layout Enumerate
541
542 Section\SpecialChar ~
543
544 \begin_inset LatexCommand \ref{sec:ni}
545
546 \end_inset 
547
548 : network interfaces are associated with processes, not threads.
549  
550 \layout Enumerate
551
552 Section\SpecialChar ~
553
554 \begin_inset LatexCommand \ref{sec:niinit}
555
556 \end_inset 
557
558
559 \emph on 
560 PtlNIInit
561 \emph default 
562  must be called at least once and may be called any number of times.
563  
564 \layout Enumerate
565
566 Section\SpecialChar ~
567
568 \begin_inset LatexCommand \ref{sec:eqget}
569
570 \end_inset 
571
572
573 \emph on 
574 PtlEQGet
575 \emph default 
576  returns 
577 \family typewriter 
578 PTL_EQ_EMPTY
579 \family default 
580  if a thread is blocked on 
581 \emph on 
582 PtlEQWait
583 \emph default 
584 .
585  
586 \layout Enumerate
587
588 Section\SpecialChar ~
589
590 \begin_inset LatexCommand \ref{sec:eqwait}
591
592 \end_inset 
593
594 : waiting threads are awakened in FIFO order.
595  
596 \layout Standard
597
598 Two functions, 
599 \emph on 
600 PtlNIBarrier
601 \emph default 
602  and 
603 \emph on 
604 PtlEQCount
605 \emph default 
606  were removed from the API.
607  
608 \emph on 
609 PtlNIBarrier
610 \emph default 
611  was defined to block the calling process until all of the processes in
612  the application group had invoked 
613 \emph on 
614 PtlNIBarrier
615 \emph default 
616 .
617  We now consider this functionality, along with the concept of groups (see
618  the discussion under 
619 \begin_inset Quotes eld
620 \end_inset 
621
622 other changes
623 \begin_inset Quotes erd
624 \end_inset 
625
626 ), to be part of the runtime system, not part of the Portals API.
627  
628 \emph on 
629 PtlEQCount
630 \emph default 
631  was defined to return the number of events in an event queue.
632  Because external operations may lead to new events being added and other
633  threads may remove events, the value returned by 
634 \emph on 
635 PtlEQCount
636 \emph default 
637  would have to be a hint about the number of events in the event queue.
638 \layout Section*
639
640 Handling small, unexpected messages
641 \layout Standard
642
643 Another set of changes relates to handling small unexpected messages in
644  MPI.
645  In designing version 3.0, we assumed that each unexpected message would
646  be placed in a unique memory descriptor.
647  To avoid the need to process a long list of memory descriptors, we moved
648  the memory descriptors out of the match list and hung them off of a single
649  match list entry.
650  In this way, large unexpected messages would only encounter a single 
651 \begin_inset Quotes eld
652 \end_inset 
653
654 short message
655 \begin_inset Quotes erd
656 \end_inset 
657
658  match list entry before encountering the 
659 \begin_inset Quotes eld
660 \end_inset 
661
662 long message
663 \begin_inset Quotes erd
664 \end_inset 
665
666  match list entry.
667  Experience with this strategy identified resource management problems with
668  this approach.
669  In particular, a long sequence of very short (or zero length) messages
670  could quickly exhaust the memory descriptors constructed for handling unexpecte
671 d messages.
672  Our new strategy involves the use of several very large memory descriptors
673  for small unexpected messages.
674  Consecutive unexpected messages will be written into the first of these
675  memory descriptors until the memory descriptor fills up.
676  When the first of the 
677 \begin_inset Quotes eld
678 \end_inset 
679
680 small memory
681 \begin_inset Quotes erd
682 \end_inset 
683
684  descriptors fills up, it will be unlinked and subsequent short messages
685  will be written into the next 
686 \begin_inset Quotes eld
687 \end_inset 
688
689 short message
690 \begin_inset Quotes erd
691 \end_inset 
692
693  memory descriptor.
694  In this case, a 
695 \begin_inset Quotes eld
696 \end_inset 
697
698 short message
699 \begin_inset Quotes erd
700 \end_inset 
701
702  memory descriptor will be declared full when it does not have sufficient
703  space for the largest small unexpected message.
704 \layout Standard
705
706 This lead to two significant changes.
707  First, each match list entry now has a single memory descriptor rather
708  than a list of memory descriptors.
709  Second, in addition to exceeding the operation threshold, a memory descriptor
710  can be unlinked when the local offset exceeds a specified value.
711  These changes have lead to several changes in this document: 
712 \layout Enumerate
713
714 Section\SpecialChar ~
715
716 \begin_inset LatexCommand \ref{subsec:paddress}
717
718 \end_inset 
719
720
721 \begin_deeper 
722 \layout Enumerate
723
724 removed references to the memory descriptor list, 
725 \layout Enumerate
726
727 changed the portals address translation description to indicate that unlinking
728  a memory descriptor implies unlinking the associated match list entry--match
729  list entries can no longer be unlinked independently from the memory descriptor.
730  
731 \end_deeper 
732 \layout Enumerate
733
734 Section\SpecialChar ~
735
736 \begin_inset LatexCommand \ref{sec:meattach}
737
738 \end_inset 
739
740
741 \begin_deeper 
742 \layout Enumerate
743
744 removed unlink from argument list, 
745 \layout Enumerate
746
747 removed description of 
748 \family typewriter 
749 ptl_unlink
750 \family default 
751  type, 
752 \layout Enumerate
753
754 changed wording of the error condition when the Portal table index already
755  has an associated match list.
756  
757 \end_deeper 
758 \layout Enumerate
759
760 Section\SpecialChar ~
761
762 \begin_inset LatexCommand \ref{sec:meinsert}
763
764 \end_inset 
765
766 : removed unlink from argument list.
767  
768 \layout Enumerate
769
770 Section\SpecialChar ~
771
772 \begin_inset LatexCommand \ref{sec:md-type}
773
774 \end_inset 
775
776 : added 
777 \family typewriter 
778 max_offset
779 \family default 
780 .
781  
782 \layout Enumerate
783
784 Section\SpecialChar ~
785
786 \begin_inset LatexCommand \ref{sec:mdattach}
787
788 \end_inset 
789
790
791 \begin_deeper 
792 \layout Enumerate
793
794 added description of 
795 \family typewriter 
796 ptl_unlink
797 \family default 
798  type, 
799 \layout Enumerate
800
801 removed reference to memory descriptor lists, 
802 \layout Enumerate
803
804 changed wording of the error condition when match list entry already has
805  an associated memory descriptor, 
806 \layout Enumerate
807
808 changed the description of the 
809 \family typewriter 
810 unlink
811 \family default 
812  argument.
813  
814 \end_deeper 
815 \layout Enumerate
816
817 Section\SpecialChar ~
818
819 \begin_inset LatexCommand \ref{sec:md}
820
821 \end_inset 
822
823 : removed 
824 \family typewriter 
825 PtlMDInsert
826 \family default 
827  operation.
828  
829 \layout Enumerate
830
831 Section\SpecialChar ~
832
833 \begin_inset LatexCommand \ref{sec:mdbind}
834
835 \end_inset 
836
837 : removed references to memory descriptor list.
838  
839 \layout Enumerate
840
841 Section\SpecialChar ~
842
843 \begin_inset LatexCommand \ref{sec:mdfree}
844
845 \end_inset 
846
847 : removed reference to memory descriptor list.
848  
849 \layout Enumerate
850
851 Section\SpecialChar ~
852
853 \begin_inset LatexCommand \ref{sec:summary}
854
855 \end_inset 
856
857 : removed references to PtlMDInsert.
858  
859 \layout Enumerate
860
861 Section\SpecialChar ~
862
863 \begin_inset LatexCommand \ref{sec:semantics}
864
865 \end_inset 
866
867 : removed reference to memory descriptor list.
868  
869 \layout Enumerate
870
871 Section\SpecialChar ~
872
873 \begin_inset LatexCommand \ref{sec:exmpi}
874
875 \end_inset 
876
877 : revised the MPI example to reflect the changes to the interface.
878  
879 \layout Standard
880
881 Several changes have been made to improve the general documentation of the
882  interface.
883  
884 \layout Enumerate
885
886 Section\SpecialChar ~
887
888 \begin_inset LatexCommand \ref{sec:handle-type}
889
890 \end_inset 
891
892 : documented the special value 
893 \family typewriter 
894 PTL_EQ_NONE
895 \family default 
896 .
897  
898 \layout Enumerate
899
900 Section\SpecialChar ~
901
902 \begin_inset LatexCommand \ref{sec:id-type}
903
904 \end_inset 
905
906 : documented the special value 
907 \family typewriter 
908 PTL_ID_ANY
909 \family default 
910 .
911  
912 \layout Enumerate
913
914 Section\SpecialChar ~
915
916 \begin_inset LatexCommand \ref{sec:mdbind}
917
918 \end_inset 
919
920 : documented the return value 
921 \family typewriter 
922 PTL_INV_EQ
923 \layout Enumerate
924
925 Section\SpecialChar ~
926
927 \begin_inset LatexCommand \ref{sec:mdupdate}
928
929 \end_inset 
930
931 : clarified the description of the 
932 \emph on 
933 PtlMDUpdate
934 \emph default 
935  function.
936  
937 \layout Enumerate
938
939 Section\SpecialChar ~
940
941 \begin_inset LatexCommand \ref{sec:implvals}
942
943 \end_inset 
944
945 : introduced a new section to document the implementation defined values.
946  
947 \layout Enumerate
948
949 Section\SpecialChar ~
950
951 \begin_inset LatexCommand \ref{sec:summary}
952
953 \end_inset 
954
955 : modified Table\SpecialChar ~
956
957 \begin_inset LatexCommand \ref{tab:oconsts}
958
959 \end_inset 
960
961  to indicate where each constant is introduced and where it is used.
962  
963 \layout Section*
964
965 Other changes
966 \layout Subsection*
967
968 Implementation defined limits (Section 
969 \begin_inset LatexCommand \ref{sec:niinit}
970
971 \end_inset 
972
973 )
974 \layout Standard
975
976 The earlier version provided implementation defined limits for the maximum
977  number of match entries, the maximum number of memory descriptors, etc.
978  Rather than spanning the entire implementation, these limits are now associated
979  with individual network interfaces.
980 \layout Subsection*
981
982 Added User Ids (Section 
983 \begin_inset LatexCommand \ref{sec:uid}
984
985 \end_inset 
986
987 )
988 \layout Standard
989
990 Group Ids had been used to simplify access control entries.
991  In particular, a process could allow access for all of the processes in
992  a group.
993  User Ids have been introduced to regain this functionality.
994  We use user ids to fill this role.
995 \layout Subsection*
996
997 Removed Group Ids and Rank Ids (Section 
998 \begin_inset LatexCommand \ref{sec:pid}
999
1000 \end_inset 
1001
1002 )
1003 \layout Standard
1004
1005 The earlier version of Portals had two forms for addressing processes: <node
1006  id, process id> and <group id, rank id>.
1007  A process group was defined as the collection processes created during
1008  application launch.
1009  Each process in the group was given a unique rank id in the range 0 to
1010  
1011 \begin_inset Formula $n-1$
1012 \end_inset 
1013
1014  where 
1015 \begin_inset Formula $n$
1016 \end_inset 
1017
1018  was the number of processes in the group.
1019  We removed groups because they are better handled in the runtime system.
1020 \layout Subsection*
1021
1022 Match lists (Section 
1023 \begin_inset LatexCommand \ref{sec:meattach}
1024
1025 \end_inset 
1026
1027 )
1028 \layout Standard
1029
1030 It is no longer illegal to have an existing match entry when calling PtlMEAttach.
1031  A position argument was added to the list of arguments supplied to 
1032 \emph on 
1033 PtlMEAttach
1034 \emph default 
1035  to specify whether the new match entry is prepended or appended to the
1036  existing list.
1037  If there is no existing match list, the position argument is ignored.
1038 \layout Subsection*
1039
1040 Unlinking Memory Descriptors (Section 
1041 \begin_inset LatexCommand \ref{sec:md}
1042
1043 \end_inset 
1044
1045 )
1046 \layout Standard
1047
1048 Previously, a memory descriptor could be unlinked if the offset exceeded
1049  a threshold upon the completion of an operation.
1050  In this version, the unlinking is delayed until there is a matching operation
1051  which requires more memory than is currently available in the descriptor.
1052  In addition to changes in section, this lead to a revision of Figure\SpecialChar ~
1053
1054 \begin_inset LatexCommand \ref{fig:flow}
1055
1056 \end_inset 
1057
1058 .
1059 \layout Subsection*
1060
1061 Split Phase Operations and Events (Section 
1062 \begin_inset LatexCommand \ref{sec:eq}
1063
1064 \end_inset 
1065
1066 )
1067 \layout Standard
1068
1069 Previously, there were five types of events: 
1070 \family typewriter 
1071 PTL_EVENT_PUT
1072 \family default 
1073
1074 \family typewriter 
1075 PTL_EVENT_GET
1076 \family default 
1077
1078 \family typewriter 
1079 PTL_EVENT_REPLY
1080 \family default 
1081
1082 \family typewriter 
1083 PTL_EVENT_SENT
1084 \family default 
1085 , and 
1086 \family typewriter 
1087 PTL_EVENT_ACK.
1088  
1089 \family default 
1090 The first four of these reflected the completion of potentially long operations.
1091  We have introduced new event types to reflect the fact that long operations
1092  have a distinct starting point and a distinct completion point.
1093  Moreover, the completion may be successful or unsuccessful.
1094 \layout Standard
1095
1096 In addition to providing a mechanism for reporting failure to higher levels
1097  of software, this split provides an opportunity for for improved ordering
1098  semantics.
1099  Previously, if one process intiated two operations (e.g., two put operations)
1100  on a remote process, these operations were guaranteed to complete in the
1101  same order that they were initiated.
1102  Now, we only guarantee that the initiation events are delivered in the
1103  same order.
1104  In particular, the operations do not need to complete in the order that
1105  they were intiated.
1106 \layout Subsection*
1107
1108 Well known proces ids (Section 
1109 \begin_inset LatexCommand \ref{sec:niinit}
1110
1111 \end_inset 
1112
1113 )
1114 \layout Standard
1115
1116 To support the notion of 
1117 \begin_inset Quotes eld
1118 \end_inset 
1119
1120 well known process ids,
1121 \begin_inset Quotes erd
1122 \end_inset 
1123
1124  we added a process id argument to the arguments for PtlNIInit.
1125 \layout Chapter*
1126
1127 Glossary
1128 \layout Description
1129
1130 API Application Programming Interface.
1131  A definition of the functions and semantics provided by library of functions.
1132  
1133 \layout Description
1134
1135 Initiator A 
1136 \emph on 
1137 process
1138 \emph default 
1139  that initiates a message operation.
1140  
1141 \layout Description
1142
1143 Message An application-defined unit of data that is exchanged between 
1144 \emph on 
1145 processes
1146 \emph default 
1147 .
1148  
1149 \layout Description
1150
1151 Message\SpecialChar ~
1152 Operation Either a put operation, which writes data, or a get operation,
1153  which reads data.
1154  
1155 \layout Description
1156
1157 Network A network provides point-to-point communication between 
1158 \emph on 
1159 nodes
1160 \emph default 
1161 .
1162  Internally, a network may provide multiple routes between endpoints (to
1163  improve fault tolerance or to improve performance characteristics); however,
1164  multiple paths will not be exposed outside of the network.
1165  
1166 \layout Description
1167
1168 Node A node is an endpoint in a 
1169 \emph on 
1170 network
1171 \emph default 
1172 .
1173  Nodes provide processing capabilities and memory.
1174  A node may provide multiple processors (an SMP node) or it may act as a
1175  
1176 \emph on 
1177 gateway
1178 \emph default 
1179  between networks.
1180  
1181 \layout Description
1182
1183 Process A context of execution.
1184  A process defines a virtual memory (VM) context.
1185  This context is not shared with other processes.
1186  Several threads may share the VM context defined by a process.
1187  
1188 \layout Description
1189
1190 Target A 
1191 \emph on 
1192 process
1193 \emph default 
1194  that is acted upon by a message operation.
1195  
1196 \layout Description
1197
1198 Thread A context of execution that shares a VM context with other threads.
1199  
1200 \layout Standard
1201
1202
1203 \begin_inset ERT
1204 status Collapsed
1205
1206 \layout Standard
1207
1208 \backslash 
1209 cleardoublepage
1210 \layout Standard
1211
1212 \backslash 
1213 setcounter{page}{1}
1214 \backslash 
1215 pagenumbering{arabic}
1216 \end_inset 
1217
1218
1219 \layout Chapter
1220
1221 Introduction
1222 \begin_inset LatexCommand \label{sec:intro}
1223
1224 \end_inset 
1225
1226
1227 \layout Section
1228
1229 Overview
1230 \layout Standard
1231
1232 This document describes an application programming interface for message
1233  passing between nodes in a system area network.
1234  The goal of this interface is to improve the scalability and performance
1235  of network communication by defining the functions and semantics of message
1236  passing required for scaling a parallel computing system to ten thousand
1237  nodes.
1238  This goal is achieved by providing an interface that will allow a quality
1239  implementation to take advantage of the inherently scalable design of Portals.
1240 \layout Standard
1241
1242 This document is divided into several sections: 
1243 \layout Description
1244
1245 Section\SpecialChar ~
1246
1247 \begin_inset LatexCommand \ref{sec:intro}
1248
1249 \end_inset 
1250
1251 ---Introduction This section describes the purpose and scope of the Portals
1252  API.
1253  
1254 \layout Description
1255
1256 Section\SpecialChar ~
1257
1258 \begin_inset LatexCommand \ref{sec:apiover}
1259
1260 \end_inset 
1261
1262 ---An\SpecialChar ~
1263 Overview\SpecialChar ~
1264 of\SpecialChar ~
1265 the\SpecialChar ~
1266 Portals\SpecialChar ~
1267 3.1\SpecialChar ~
1268 API This section gives a brief overview of the
1269  Portals API.
1270  The goal is to introduce the key concepts and terminology used in the descripti
1271 on of the API.
1272  
1273 \layout Description
1274
1275 Section\SpecialChar ~
1276
1277 \begin_inset LatexCommand \ref{sec:api}
1278
1279 \end_inset 
1280
1281 ---The\SpecialChar ~
1282 Portals\SpecialChar ~
1283 3.2\SpecialChar ~
1284 API This section describes the functions and semantics of
1285  the Portals application programming interface.
1286  
1287 \layout Description
1288
1289 Section\SpecialChar ~
1290
1291 \begin_inset LatexCommand \ref{sec:semantics}
1292
1293 \end_inset 
1294
1295 --The\SpecialChar ~
1296 Semantics\SpecialChar ~
1297 of\SpecialChar ~
1298 Message\SpecialChar ~
1299 Transmission This section describes the semantics
1300  of message transmission.
1301  In particular, the information transmitted in each type of message and
1302  the processing of incoming messages.
1303  
1304 \layout Description
1305
1306 Section\SpecialChar ~
1307
1308 \begin_inset LatexCommand \ref{sec:examples}
1309
1310 \end_inset 
1311
1312 ---Examples This section presents several examples intended to illustrates
1313  the use of the Portals API.
1314  
1315 \layout Section
1316
1317 Purpose
1318 \layout Standard
1319
1320 Existing message passing technologies available for commodity cluster networking
1321  hardware do not meet the scalability goals required by the Cplant\SpecialChar ~
1322
1323 \begin_inset LatexCommand \cite{Cplant}
1324
1325 \end_inset 
1326
1327  project at Sandia National Laboratories.
1328  The goal of the Cplant project is to construct a commodity cluster that
1329  can scale to the order of ten thousand nodes.
1330  This number greatly exceeds the capacity for which existing message passing
1331  technologies have been designed and implemented.
1332 \layout Standard
1333
1334 In addition to the scalability requirements of the network, these technologies
1335  must also be able to support a scalable implementation of the Message Passing
1336  Interface (MPI)\SpecialChar ~
1337
1338 \begin_inset LatexCommand \cite{MPIstandard}
1339
1340 \end_inset 
1341
1342  standard, which has become the 
1343 \shape italic 
1344 de facto
1345 \shape default 
1346  standard for parallel scientific computing.
1347  While MPI does not impose any scalability limitations, existing message
1348  passing technologies do not provide the functionality needed to allow implement
1349 ations of MPI to meet the scalability requirements of Cplant.
1350 \layout Standard
1351
1352 The following are properties of a network architecture that do not impose
1353  any inherent scalability limitations: 
1354 \layout Itemize
1355
1356 Connectionless - Many connection-oriented architectures, such as VIA\SpecialChar ~
1357
1358 \begin_inset LatexCommand \cite{VIA}
1359
1360 \end_inset 
1361
1362  and TCP/IP sockets, have limitations on the number of peer connections
1363  that can be established.
1364  
1365 \layout Itemize
1366
1367 Network independence - Many communication systems depend on the host processor
1368  to perform operations in order for messages in the network to be consumed.
1369  Message consumption from the network should not be dependent on host processor
1370  activity, such as the operating system scheduler or user-level thread scheduler.
1371  
1372 \layout Itemize
1373
1374 User-level flow control - Many communication systems manage flow control
1375  internally to avoid depleting resources, which can significantly impact
1376  performance as the number of communicating processes increases.
1377  
1378 \layout Itemize
1379
1380 OS Bypass - High performance network communication should not involve memory
1381  copies into or out of a kernel-managed protocol stack.
1382  
1383 \layout Standard
1384
1385 The following are properties of a network architecture that do not impose
1386  scalability limitations for an implementation of MPI:
1387 \layout Itemize
1388
1389 Receiver-managed - Sender-managed message passing implementations require
1390  a persistent block of memory to be available for every process, requiring
1391  memory resources to increase with job size and requiring user-level flow
1392  control mechanisms to manage these resources.
1393  
1394 \layout Itemize
1395
1396 User-level Bypass - While OS Bypass is necessary for high-performance, it
1397  alone is not sufficient to support the Progress Rule of MPI asynchronous
1398  operations.
1399  
1400 \layout Itemize
1401
1402 Unexpected messages - Few communication systems have support for receiving
1403  messages for which there is no prior notification.
1404  Support for these types of messages is necessary to avoid flow control
1405  and protocol overhead.
1406  
1407 \layout Section
1408
1409 Background
1410 \layout Standard
1411
1412 Portals was originally designed for and implemented on the nCube machine
1413  as part of the SUNMOS (Sandia/UNM OS)\SpecialChar ~
1414
1415 \begin_inset LatexCommand \cite{SUNMOS}
1416
1417 \end_inset 
1418
1419  and Puma\SpecialChar ~
1420
1421 \begin_inset LatexCommand \cite{PumaOS}
1422
1423 \end_inset 
1424
1425  lightweight kernel development projects.
1426  Portals went through two design phases, the latter of which is used on
1427  the 4500-node Intel TeraFLOPS machine\SpecialChar ~
1428
1429 \begin_inset LatexCommand \cite{TFLOPS}
1430
1431 \end_inset 
1432
1433 .
1434  Portals have been very successful in meeting the needs of such a large
1435  machine, not only as a layer for a high-performance MPI implementation\SpecialChar ~
1436
1437 \begin_inset LatexCommand \cite{PumaMPI}
1438
1439 \end_inset 
1440
1441 , but also for implementing the scalable run-time environment and parallel
1442  I/O capabilities of the machine.
1443 \layout Standard
1444
1445 The second generation Portals implementation was designed to take full advantage
1446  of the hardware architecture of large MPP machines.
1447  However, efforts to implement this same design on commodity cluster technology
1448  identified several limitations, due to the differences in network hardware
1449  as well as to shortcomings in the design of Portals.
1450 \layout Section
1451
1452 Scalability
1453 \layout Standard
1454
1455 The primary goal in the design of Portals is scalability.
1456  Portals are designed specifically for an implementation capable of supporting
1457  a parallel job running on tens of thousands of nodes.
1458  Performance is critical only in terms of scalability.
1459  That is, the level of message passing performance is characterized by how
1460  far it allows an application to scale and not by how it performs in micro-bench
1461 marks (e.g., a two node bandwidth or latency test).
1462 \layout Standard
1463
1464 The Portals API is designed to allow for scalability, not to guarantee it.
1465  Portals cannot overcome the shortcomings of a poorly designed application
1466  program.
1467  Applications that have inherent scalability limitations, either through
1468  design or implementation, will not be transformed by Portals into scalable
1469  applications.
1470  Scalability must be addressed at all levels.
1471  Portals do not inhibit scalability, but do not guarantee it either.
1472 \layout Standard
1473
1474 To support scalability, the Portals interface maintains a minimal amount
1475  of state.
1476  Portals provide reliable, ordered delivery of messages between pairs of
1477  processes.
1478  They are connectionless: a process is not required to explicitly establish
1479  a point-to-point connection with another process in order to communicate.
1480  Moreover, all buffers used in the transmission of messages are maintained
1481  in user space.
1482  The target process determines how to respond to incoming messages, and
1483  messages for which there are no buffers are discarded.
1484 \layout Section
1485
1486 Communication Model
1487 \layout Standard
1488
1489 Portals combine the characteristics of both one-side and two-sided communication.
1490  They define a 
1491 \begin_inset Quotes eld
1492 \end_inset 
1493
1494 matching put
1495 \begin_inset Quotes erd
1496 \end_inset 
1497
1498  operation and a 
1499 \begin_inset Quotes eld
1500 \end_inset 
1501
1502 matching get
1503 \begin_inset Quotes erd
1504 \end_inset 
1505
1506  operation.
1507  The destination of a put (or send) is not an explicit address; instead,
1508  each message contains a set of match bits that allow the receiver to determine
1509  where incoming messages should be placed.
1510  This flexibility allows Portals to support both traditional one-sided operation
1511 s and two-sided send/receive operations.
1512 \layout Standard
1513
1514 Portals allows the target to determine whether incoming messages are acceptable.
1515  A target process can choose to accept message operations from any specific
1516  process or can choose to ignore message operations from any specific process.
1517 \layout Section
1518
1519 Zero Copy, OS Bypass and Application Bypass
1520 \layout Standard
1521
1522 In traditional system architectures, network packets arrive at the network
1523  interface card (NIC), are passed through one or more protocol layers in
1524  the operating system, and eventually copied into the address space of the
1525  application.
1526  As network bandwidth began to approach memory copy rates, reduction of
1527  memory copies became a critical concern.
1528  This concern lead to the development of zero-copy message passing protocols
1529  in which message copies are eliminated or pipelined to avoid the loss of
1530  bandwidth.
1531 \layout Standard
1532
1533 A typical zero-copy protocol has the NIC generate an interrupt for the CPU
1534  when a message arrives from the network.
1535  The interrupt handler then controls the transfer of the incoming message
1536  into the address space of the appropriate application.
1537  The interrupt latency, the time from the initiation of an interrupt until
1538  the interrupt handler is running, is fairly significant.
1539  To avoid this cost, some modern NICs have processors that can be programmed
1540  to implement part of a message passing protocol.
1541  Given a properly designed protocol, it is possible to program the NIC to
1542  control the transfer of incoming messages, without needing to interrupt
1543  the CPU.
1544  Because this strategy does not need to involve the OS on every message
1545  transfer, it is frequently called 
1546 \begin_inset Quotes eld
1547 \end_inset 
1548
1549 OS Bypass.
1550 \begin_inset Quotes erd
1551 \end_inset 
1552
1553  ST\SpecialChar ~
1554
1555 \begin_inset LatexCommand \cite{ST}
1556
1557 \end_inset 
1558
1559 , VIA\SpecialChar ~
1560
1561 \begin_inset LatexCommand \cite{VIA}
1562
1563 \end_inset 
1564
1565 , FM\SpecialChar ~
1566
1567 \begin_inset LatexCommand \cite{FM2}
1568
1569 \end_inset 
1570
1571 , GM\SpecialChar ~
1572
1573 \begin_inset LatexCommand \cite{GM}
1574
1575 \end_inset 
1576
1577 , and Portals are examples of OS Bypass protocols.
1578 \layout Standard
1579
1580 Many protocols that support OS Bypass still require that the application
1581  actively participate in the protocol to ensure progress.
1582  As an example, the long message protocol of PM requires that the application
1583  receive and reply to a request to put or get a long message.
1584  This complicates the runtime environment, requiring a thread to process
1585  incoming requests, and significantly increases the latency required to
1586  initiate a long message protocol.
1587  The Portals message passing protocol does not require activity on the part
1588  of the application to ensure progress.
1589  We use the term 
1590 \begin_inset Quotes eld
1591 \end_inset 
1592
1593 Application Bypass
1594 \begin_inset Quotes erd
1595 \end_inset 
1596
1597  to refer to this aspect of the Portals protocol.
1598 \layout Section
1599
1600 Faults 
1601 \layout Standard
1602
1603 Given the number of components that we are dealing with and the fact that
1604  we are interested in supporting applications that run for very long times,
1605  failures are inevitable.
1606  The Portals API recognizes that the underlying transport may not be able
1607  to successfully complete an operation once it has been initiated.
1608  This is reflected in the fact that the Portals API reports three types
1609  of events: events indicating the initiation of an operation, events indicating
1610  the successful completion of an operation, and events indicating the unsuccessf
1611 ul completion of an operation.
1612  Every initiation event is eventually followed by a successful completion
1613  event or an unsuccessful completion event.
1614 \layout Standard
1615
1616 Between the time an operation is started and the time that the operation
1617  completes (successfully or unsuccessfully), any memory associated with
1618  the operation should be considered volatile.
1619  That is, the memory may be changed in unpredictable ways while the operation
1620  is progressing.
1621  Once the operation completes, the memory associated with the operation
1622  will not be subject to further modification (from this operation).
1623  Notice that unsuccessful operations may alter memory in an essentially
1624  unpredictable fashion.
1625 \layout Chapter
1626
1627 An Overview of the Portals API
1628 \begin_inset LatexCommand \label{sec:apiover}
1629
1630 \end_inset 
1631
1632
1633 \layout Standard
1634
1635 In this section, we give a conceptual overview of the Portals API.
1636  The goal is to provide a context for understanding the detailed description
1637  of the API presented in the next section.
1638 \layout Section
1639
1640 Data Movement
1641 \begin_inset LatexCommand \label{sec:dmsemantics}
1642
1643 \end_inset 
1644
1645
1646 \layout Standard
1647
1648 A Portal represents an opening in the address space of a process.
1649  Other processes can use a Portal to read (get) or write (put) the memory
1650  associated with the portal.
1651  Every data movement operation involves two processes, the 
1652 \series bold 
1653 initiator
1654 \series default 
1655  and the 
1656 \series bold 
1657 target
1658 \series default 
1659 .
1660  The initiator is the process that initiates the data movement operation.
1661  The target is the process that responds to the operation by either accepting
1662  the data for a put operation, or replying with the data for a get operation.
1663 \layout Standard
1664
1665 In this discussion, activities attributed to a process may refer to activities
1666  that are actually performed by the process or 
1667 \emph on 
1668 on behalf of the process
1669 \emph default 
1670 .
1671  The inclusiveness of our terminology is important in the context of 
1672 \emph on 
1673 application bypass
1674 \emph default 
1675 .
1676  In particular, when we note that the target sends a reply in the case of
1677  a get operation, it is possible that reply will be generated by another
1678  component in the system, bypassing the application.
1679 \layout Standard
1680
1681 Figures\SpecialChar ~
1682
1683 \begin_inset LatexCommand \ref{fig:put}
1684
1685 \end_inset 
1686
1687  and 
1688 \begin_inset LatexCommand \ref{fig:get}
1689
1690 \end_inset 
1691
1692  present graphical interpretations of the Portal data movement operations:
1693  put and get.
1694  In the case of a put operation, the initiator sends a put request message
1695  containing the data to the target.
1696  The target translates the Portal addressing information in the request
1697  using its local Portal structures.
1698  When the request has been processed, the target optionally sends an acknowledge
1699 ment message.
1700 \layout Standard
1701
1702
1703 \begin_inset Float figure
1704 placement htbp
1705 wide false
1706 collapsed false
1707
1708 \layout Standard
1709 \align center 
1710
1711 \begin_inset Graphics FormatVersion 1
1712         filename put.eps
1713         display color
1714         size_type 0
1715         rotateOrigin center
1716         lyxsize_type 1
1717         lyxwidth 218pt
1718         lyxheight 119pt
1719 \end_inset 
1720
1721
1722 \layout Caption
1723
1724 Portal Put (Send)
1725 \begin_inset LatexCommand \label{fig:put}
1726
1727 \end_inset 
1728
1729
1730 \end_inset 
1731
1732
1733 \layout Standard
1734
1735 In the case of a get operation, the initiator sends a get request to the
1736  target.
1737  As with the put operation, the target translates the Portal addressing
1738  information in the request using its local Portal structures.
1739  Once it has translated the Portal addressing information, the target sends
1740  a reply that includes the requested data.
1741 \layout Standard
1742
1743
1744 \begin_inset Float figure
1745 placement htbp
1746 wide false
1747 collapsed false
1748
1749 \layout Standard
1750 \align center 
1751
1752 \begin_inset Graphics FormatVersion 1
1753         filename get.eps
1754         display color
1755         size_type 0
1756         rotateOrigin center
1757         lyxsize_type 1
1758         lyxwidth 218pt
1759         lyxheight 119pt
1760 \end_inset 
1761
1762
1763 \layout Caption
1764
1765 Portal Get
1766 \begin_inset LatexCommand \label{fig:get}
1767
1768 \end_inset 
1769
1770
1771 \end_inset 
1772
1773
1774 \layout Standard
1775
1776 We should note that Portal address translations are only performed on nodes
1777  that respond to operations initiated by other nodes.
1778  Acknowledgements and replies to get operations bypass the portals address
1779  translation structures.
1780 \layout Section
1781
1782 Portal Addressing
1783 \begin_inset LatexCommand \label{subsec:paddress}
1784
1785 \end_inset 
1786
1787
1788 \layout Standard
1789
1790 One-sided data movement models (e.g., shmem\SpecialChar ~
1791
1792 \begin_inset LatexCommand \cite{CraySHMEM}
1793
1794 \end_inset 
1795
1796 , ST\SpecialChar ~
1797
1798 \begin_inset LatexCommand \cite{ST}
1799
1800 \end_inset 
1801
1802 , MPI-2\SpecialChar ~
1803
1804 \begin_inset LatexCommand \cite{MPI2}
1805
1806 \end_inset 
1807
1808 ) typically use a triple to address memory on a remote node.
1809  This triple consists of a process id, memory buffer id, and offset.
1810  The process id identifies the target process, the memory buffer id specifies
1811  the region of memory to be used for the operation, and the offset specifies
1812  an offset within the memory buffer.
1813 \layout Standard
1814
1815 In addition to the standard address components (process id, memory buffer
1816  id, and offset), a Portal address includes a set of match bits.
1817  This addressing model is appropriate for supporting one-sided operations
1818  as well as traditional two-sided message passing operations.
1819  Specifically, the Portals API provides the flexibility needed for an efficient
1820  implementation of MPI-1, which defines two-sided operations with one-sided
1821  completion semantics.
1822 \layout Standard
1823
1824 Figure\SpecialChar ~
1825
1826 \begin_inset LatexCommand \ref{fig:portals}
1827
1828 \end_inset 
1829
1830  presents a graphical representation of the structures used by a target
1831  in the interpretation of a Portal address.
1832  The process id is used to route the message to the appropriate node and
1833  is not reflected in this diagram.
1834  The memory buffer id, called the 
1835 \series bold 
1836 portal id
1837 \series default 
1838 , is used as an index into the Portal table.
1839  Each element of the Portal table identifies a match list.
1840  Each element of the match list specifies two bit patterns: a set of 
1841 \begin_inset Quotes eld
1842 \end_inset 
1843
1844 don't care
1845 \begin_inset Quotes erd
1846 \end_inset 
1847
1848  bits, and a set of 
1849 \begin_inset Quotes eld
1850 \end_inset 
1851
1852 must match
1853 \begin_inset Quotes erd
1854 \end_inset 
1855
1856  bits.
1857  In addition to the two sets of match bits, each match list element has
1858  at most one memory descriptor.
1859  Each memory descriptor identifies a memory region and an optional event
1860  queue.
1861  The memory region specifies the memory to be used in the operation and
1862  the event queue is used to record information about these operations.
1863 \layout Standard
1864
1865
1866 \begin_inset Float figure
1867 placement htbp
1868 wide false
1869 collapsed false
1870
1871 \layout Standard
1872 \align center 
1873
1874 \begin_inset Graphics FormatVersion 1
1875         filename portals.eps
1876         display color
1877         size_type 0
1878         rotateOrigin center
1879         lyxsize_type 1
1880         lyxwidth 305pt
1881         lyxheight 106pt
1882 \end_inset 
1883
1884
1885 \layout Caption
1886
1887 Portal Addressing Structures
1888 \begin_inset LatexCommand \label{fig:portals}
1889
1890 \end_inset 
1891
1892
1893 \end_inset 
1894
1895
1896 \layout Standard
1897
1898 Figure\SpecialChar ~
1899
1900 \begin_inset LatexCommand \ref{fig:flow}
1901
1902 \end_inset 
1903
1904  illustrates the steps involved in translating a Portal address, starting
1905  from the first element in a match list.
1906  If the match criteria specified in the match list entry are met and the
1907  memory descriptor list accepts the operation
1908 \begin_inset Foot
1909 collapsed true
1910
1911 \layout Standard
1912
1913 Memory descriptors can reject operations because a threshold has been exceeded
1914  or because the memory region does not have sufficient space, see Section\SpecialChar ~
1915
1916 \begin_inset LatexCommand \ref{sec:md}
1917
1918 \end_inset 
1919
1920
1921 \end_inset 
1922
1923 , the operation (put or get) is performed using the memory region specified
1924  in the memory descriptor.
1925  If the memory descriptor specifies that it is to be unlinked when a threshold
1926  has been exceeded, the match list entry is removed from the match list
1927  and the resources associated with the memory descriptor and match list
1928  entry are reclaimed.
1929  Finally, if there is an event queue specified in the memory descriptor,
1930  the operation is logged in the event queue.
1931 \layout Standard
1932
1933
1934 \begin_inset Float figure
1935 placement htbp
1936 wide false
1937 collapsed false
1938
1939 \layout Standard
1940 \align center 
1941
1942 \begin_inset Graphics FormatVersion 1
1943         filename flow_new.eps
1944         display color
1945         size_type 0
1946         rotateOrigin center
1947         lyxsize_type 1
1948         lyxwidth 447pt
1949         lyxheight 282pt
1950 \end_inset 
1951
1952
1953 \layout Caption
1954
1955 Portals Address Translation
1956 \begin_inset LatexCommand \label{fig:flow}
1957
1958 \end_inset 
1959
1960
1961 \end_inset 
1962
1963
1964 \layout Standard
1965
1966 If the match criteria specified in the match list entry are not met, or
1967  there is no memory descriptor associated with the match list entry, or
1968  the memory descriptor associated with the match list entry rejects the
1969  operation, the address translation continues with the next match list entry.
1970  If the end of the match list has been reached, the address translation
1971  is aborted and the incoming requested is discarded.
1972 \layout Section
1973
1974 Access Control
1975 \layout Standard
1976
1977 A process can control access to its portals using an access control list.
1978  Each entry in the access control list specifies a process id and a Portal
1979  table index.
1980  The access control list is actually an array of entries.
1981  Each incoming request includes an index into the access control list (i.e.,
1982  a 
1983 \begin_inset Quotes eld
1984 \end_inset 
1985
1986 cookie
1987 \begin_inset Quotes erd
1988 \end_inset 
1989
1990  or hint).
1991  If the id of the process issuing the request doesn't match the id specified
1992  in the access control list entry or the Portal table index specified in
1993  the request doesn't match the Portal table index specified in the access
1994  control list entry, the request is rejected.
1995  Process identifiers and Portal table indexes may include wild card values
1996  to increase the flexibility of this mechanism.
1997  
1998 \layout Standard
1999
2000 Two aspects of this design merit further discussion.
2001  First, the model assumes that the information in a message header, the
2002  sender's id in particular, is trustworthy.
2003  In most contexts, we assume that the entity that constructs the header
2004  is trustworthy; however, using cryptographic techniques, we could easily
2005  devise a protocol that would ensure the authenticity of the sender.
2006 \layout Standard
2007
2008 Second, because the access check is performed by the receiver, it is possible
2009  that a malicious process will generate thousands of messages that will
2010  be denied by the receiver.
2011  This could saturate the network and/or the receiver, resulting in a 
2012 \emph on 
2013 denial of service
2014 \emph default 
2015  attack.
2016  Moving the check to the sender using capabilities, would remove the potential
2017  for this form of attack.
2018  However, the solution introduces the complexities of capability management
2019  (exchange of capabilities, revocation, protections, etc).
2020 \layout Section
2021
2022 Multi-threaded Applications
2023 \begin_inset LatexCommand \label{sec:threads}
2024
2025 \end_inset 
2026
2027  
2028 \layout Standard
2029
2030 The Portals API supports a generic view of multi-threaded applications.
2031  From the perspective of the Portals API, an application program is defined
2032  by a set of processes.
2033  Each process defines a unique address space.
2034  The Portals API defines access to this address space from other processes
2035  (using portals addressing and the data movement operations).
2036  A process may have one or more 
2037 \emph on 
2038 threads
2039 \emph default 
2040  executing in its address space.
2041  
2042 \layout Standard
2043
2044 With the exception of 
2045 \emph on 
2046 PtlEQWait
2047 \emph default 
2048  every function in the Portals API is non-blocking and atomic with respect
2049  to both other threads and external operations that result from data movement
2050  operations.
2051  While individual operations are atomic, sequences of these operations may
2052  be interleaved between different threads and with external operations.
2053  The Portals API does not provide any mechanisms to control this interleaving.
2054  It is expected that these mechanisms will be provided by the API used to
2055  create threads.
2056 \layout Chapter
2057
2058 The Portals API
2059 \begin_inset LatexCommand \label{sec:api}
2060
2061 \end_inset 
2062
2063
2064 \layout Section
2065
2066 Naming Conventions
2067 \begin_inset LatexCommand \label{sec:conv}
2068
2069 \end_inset 
2070
2071
2072 \layout Standard
2073
2074 The Portals API defines two types of entities: functions and types.
2075  Function always start with 
2076 \emph on 
2077 Ptl
2078 \emph default 
2079  and use mixed upper and lower case.
2080  When used in the body of this report, function names appear in italic face,
2081  e.g., 
2082 \emph on 
2083 PtlInit
2084 \emph default 
2085 .
2086  The functions associated with an object type will have names that start
2087  with 
2088 \emph on 
2089 Ptl
2090 \emph default 
2091 , followed by the two letter object type code shown in Table\SpecialChar ~
2092
2093 \begin_inset LatexCommand \ref{tab:objcodes}
2094
2095 \end_inset 
2096
2097 .
2098  As an example, the function 
2099 \emph on 
2100 PtlEQAlloc
2101 \emph default 
2102  allocates resources for an event queue.
2103 \layout Standard
2104
2105
2106 \begin_inset Float table
2107 placement htbp
2108 wide false
2109 collapsed false
2110
2111 \layout Caption
2112
2113 Object Type Codes
2114 \begin_inset LatexCommand \label{tab:objcodes}
2115
2116 \end_inset 
2117
2118
2119 \begin_inset ERT
2120 status Collapsed
2121
2122 \layout Standard
2123  
2124 \backslash 
2125 medskip
2126 \newline 
2127   
2128 \end_inset 
2129
2130
2131 \layout Standard
2132 \align center 
2133
2134 \size small 
2135
2136 \begin_inset  Tabular
2137 <lyxtabular version="3" rows="5" columns="3">
2138 <features firstHeadEmpty="true">
2139 <column alignment="left" valignment="top" width="0pt">
2140 <column alignment="left" valignment="top" width="0pt">
2141 <column alignment="left" valignment="top" width="0pt">
2142 <row bottomline="true">
2143 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
2144 \begin_inset Text
2145
2146 \layout Standard
2147
2148  
2149 \emph on 
2150 xx
2151 \end_inset 
2152 </cell>
2153 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
2154 \begin_inset Text
2155
2156 \layout Standard
2157
2158  Name 
2159 \end_inset 
2160 </cell>
2161 <cell alignment="left" valignment="top" bottomline="true" usebox="none">
2162 \begin_inset Text
2163
2164 \layout Standard
2165
2166  Section 
2167 \end_inset 
2168 </cell>
2169 </row>
2170 <row>
2171 <cell alignment="left" valignment="top" usebox="none">
2172 \begin_inset Text
2173
2174 \layout Standard
2175
2176 EQ 
2177 \end_inset 
2178 </cell>
2179 <cell alignment="left" valignment="top" usebox="none">
2180 \begin_inset Text
2181
2182 \layout Standard
2183
2184  Event Queue 
2185 \end_inset 
2186 </cell>
2187 <cell alignment="left" valignment="top" usebox="none">
2188 \begin_inset Text
2189
2190 \layout Standard
2191
2192  
2193 \begin_inset LatexCommand \ref{sec:eq}
2194
2195 \end_inset 
2196
2197
2198 \end_inset 
2199 </cell>
2200 </row>
2201 <row>
2202 <cell alignment="left" valignment="top" usebox="none">
2203 \begin_inset Text
2204
2205 \layout Standard
2206
2207  MD 
2208 \end_inset 
2209 </cell>
2210 <cell alignment="left" valignment="top" usebox="none">
2211 \begin_inset Text
2212
2213 \layout Standard
2214
2215  Memory Descriptor 
2216 \end_inset 
2217 </cell>
2218 <cell alignment="left" valignment="top" usebox="none">
2219 \begin_inset Text
2220
2221 \layout Standard
2222
2223  
2224 \begin_inset LatexCommand \ref{sec:md}
2225
2226 \end_inset 
2227
2228
2229 \end_inset 
2230 </cell>
2231 </row>
2232 <row>
2233 <cell alignment="left" valignment="top" usebox="none">
2234 \begin_inset Text
2235
2236 \layout Standard
2237
2238  ME 
2239 \end_inset 
2240 </cell>
2241 <cell alignment="left" valignment="top" usebox="none">
2242 \begin_inset Text
2243
2244 \layout Standard
2245
2246  Match list Entry 
2247 \end_inset 
2248 </cell>
2249 <cell alignment="left" valignment="top" usebox="none">
2250 \begin_inset Text
2251
2252 \layout Standard
2253
2254  
2255 \begin_inset LatexCommand \ref{sec:me}
2256
2257 \end_inset 
2258
2259
2260 \end_inset 
2261 </cell>
2262 </row>
2263 <row>
2264 <cell alignment="left" valignment="top" usebox="none">
2265 \begin_inset Text
2266
2267 \layout Standard
2268
2269  NI 
2270 \end_inset 
2271 </cell>
2272 <cell alignment="left" valignment="top" usebox="none">
2273 \begin_inset Text
2274
2275 \layout Standard
2276
2277  Network Interface 
2278 \end_inset 
2279 </cell>
2280 <cell alignment="left" valignment="top" usebox="none">
2281 \begin_inset Text
2282
2283 \layout Standard
2284
2285  
2286 \begin_inset LatexCommand \ref{sec:ni}
2287
2288 \end_inset 
2289
2290
2291 \end_inset 
2292 </cell>
2293 </row>
2294 </lyxtabular>
2295
2296 \end_inset 
2297
2298
2299 \end_inset 
2300
2301
2302 \layout Standard
2303
2304 Type names use lower case with underscores to separate words.
2305  Each type name starts with 
2306 \family typewriter 
2307 ptl
2308 \family default 
2309 _ and ends with 
2310 \family typewriter 
2311 _t
2312 \family default 
2313 .
2314  When used in the body of this report, type names appear in a fixed font,
2315  e.g., 
2316 \family typewriter 
2317 ptl_match_bits_t
2318 \family default 
2319 .
2320 \layout Standard
2321
2322 Names for constants use upper case with underscores to separate words.
2323  Each constant name starts with 
2324 \family typewriter 
2325 PTL_
2326 \family default 
2327 .
2328  When used in the body of this report, type names appear in a fixed font,
2329  e.g., 
2330 \family typewriter 
2331 PTL_OK
2332 \family default 
2333 .
2334 \layout Section
2335
2336 Base Types
2337 \layout Standard
2338
2339 The Portals API defines a variety of base types.
2340  These types represent a simple renaming of the base types provided by the
2341  C programming language.
2342  In most cases these new type names have been introduced to improve type
2343  safety and to avoid issues arising from differences in representation sizes
2344  (e.g., 16-bit or 32-bit integers).
2345 \layout Subsection
2346
2347 Sizes
2348 \begin_inset LatexCommand \label{sec:size-t}
2349
2350 \end_inset 
2351
2352  
2353 \layout Standard
2354
2355 The type 
2356 \family typewriter 
2357 ptl_size_t
2358 \family default 
2359  is an unsigned 64-bit integral type used for representing sizes.
2360 \layout Subsection
2361
2362 Handles
2363 \begin_inset LatexCommand \label{sec:handle-type}
2364
2365 \end_inset 
2366
2367  
2368 \layout Standard
2369
2370 Objects maintained by the API are accessed through handles.
2371  Handle types have names of the form 
2372 \family typewriter 
2373 ptl_handle_
2374 \emph on 
2375 xx
2376 \emph default 
2377 _t
2378 \family default 
2379 , where 
2380 \emph on 
2381 xx
2382 \emph default 
2383  is one of the two letter object type codes shown in Table\SpecialChar ~
2384
2385 \begin_inset LatexCommand \ref{tab:objcodes}
2386
2387 \end_inset 
2388
2389 .
2390  For example, the type 
2391 \family typewriter 
2392 ptl_handle_ni_t
2393 \family default 
2394  is used for network interface handles.
2395 \layout Standard
2396
2397 Each type of object is given a unique handle type to enhance type checking.
2398  The type, 
2399 \family typewriter 
2400 ptl_handle_any_t
2401 \family default 
2402 , can be used when a generic handle is needed.
2403  Every handle value can be converted into a value of type 
2404 \family typewriter 
2405 ptl_handle_any_t
2406 \family default 
2407  without loss of information.
2408 \layout Standard
2409
2410 Handles are not simple values.
2411  Every portals object is associated with a specific network interface and
2412  an identifier for this interface (along with an object identifier) is part
2413  of the handle for the object.
2414 \layout Standard
2415
2416 The special value 
2417 \family typewriter 
2418 PTL_EQ_NONE
2419 \family default 
2420 , of type 
2421 \family typewriter 
2422 ptl_handle_eq_t
2423 \family default 
2424 , is used to indicate the absence of an event queue.
2425  See sections 
2426 \begin_inset LatexCommand \ref{sec:mdfree}
2427
2428 \end_inset 
2429
2430  and\SpecialChar ~
2431
2432 \begin_inset LatexCommand \ref{sec:mdupdate}
2433
2434 \end_inset 
2435
2436  for uses of this value.
2437 \layout Subsection
2438
2439 Indexes
2440 \begin_inset LatexCommand \label{sec:index-type}
2441
2442 \end_inset 
2443
2444  
2445 \layout Standard
2446
2447 The types 
2448 \family typewriter 
2449 ptl_pt_index_t
2450 \family default 
2451  and 
2452 \family typewriter 
2453 ptl_ac_index_t
2454 \family default 
2455  are integral types used for representing Portal table indexes and access
2456  control tables indexes, respectively.
2457  See section\SpecialChar ~
2458
2459 \begin_inset LatexCommand \ref{sec:niinit}
2460
2461 \end_inset 
2462
2463  for limits on values of these types.
2464 \layout Subsection
2465
2466 Match Bits
2467 \begin_inset LatexCommand \label{sec:mb-type}
2468
2469 \end_inset 
2470
2471  
2472 \layout Standard
2473
2474 The type 
2475 \family typewriter 
2476 ptl_match_bits_t
2477 \family default 
2478  is capable of holding unsigned 64-bit integer values.
2479 \layout Subsection
2480
2481 Network Interfaces
2482 \begin_inset LatexCommand \label{sec:ni-type}
2483
2484 \end_inset 
2485
2486  
2487 \layout Standard
2488
2489 The type 
2490 \family typewriter 
2491 ptl_interface_t
2492 \family default 
2493  is an integral type used for identifying different network interfaces.
2494  Users will need to consult the local documentation to determine appropriate
2495  values for the interfaces available.
2496  The special value 
2497 \family typewriter 
2498 PTL_IFACE_DEFAULT
2499 \family default 
2500  identifies the default interface.
2501 \layout Subsection
2502
2503 Identifiers
2504 \begin_inset LatexCommand \label{sec:id-type}
2505
2506 \end_inset 
2507
2508
2509 \layout Standard
2510
2511 The type 
2512 \family typewriter 
2513 ptl_nid_t
2514 \family default 
2515  is an integral type used for representing node ids
2516 \family typewriter 
2517 , ptl_pid_t
2518 \family default 
2519  is an integral type for representing process ids, and 
2520 \family typewriter 
2521 ptl_uid_t 
2522 \family default 
2523 is an integral type for representing user ids.
2524 \layout Standard
2525
2526 The special values 
2527 \family typewriter 
2528 PTL_PID_ANY
2529 \family default 
2530  matches any process identifier, PTL_NID_ANY matches any node identifier,
2531  and 
2532 \family typewriter 
2533 PTL_UID_ANY
2534 \family default 
2535  matches any user identifier.
2536  See sections 
2537 \begin_inset LatexCommand \ref{sec:meattach}
2538
2539 \end_inset 
2540
2541  and\SpecialChar ~
2542
2543 \begin_inset LatexCommand \ref{sec:acentry}
2544
2545 \end_inset 
2546
2547  for uses of these values.
2548 \layout Subsection
2549
2550 Status Registers
2551 \begin_inset LatexCommand \label{sec:stat-type}
2552
2553 \end_inset 
2554
2555
2556 \layout Standard
2557
2558 Each network interface maintains an array of status registers that can be
2559  accessed using the 
2560 \family typewriter 
2561 PtlNIStatus
2562 \family default 
2563  function (see Section\SpecialChar ~
2564
2565 \begin_inset LatexCommand \ref{sec:nistatus}
2566
2567 \end_inset 
2568
2569 ).
2570  The type 
2571 \family typewriter 
2572 ptl_sr_index_t
2573 \family default 
2574  defines the types of indexes that can be used to access the status registers.
2575  The only index defined for all implementations is 
2576 \family typewriter 
2577 PTL_SR_DROP_COUNT
2578 \family default 
2579  which identifies the status register that counts the dropped requests for
2580  the interface.
2581  Other indexes (and registers) may be defined by the implementation.
2582 \layout Standard
2583
2584 The type 
2585 \family typewriter 
2586 ptl_sr_value_t
2587 \family default 
2588  defines the types of values held in status registers.
2589  This is a signed integer type.
2590  The size is implementation dependent, but must be at least 32 bits.
2591 \layout Section
2592
2593 Initialization and Cleanup
2594 \begin_inset LatexCommand \label{sec:init}
2595
2596 \end_inset 
2597
2598
2599 \layout Standard
2600
2601 The Portals API includes a function, 
2602 \emph on 
2603 PtlInit
2604 \emph default 
2605 , to initialize the library and a function, 
2606 \emph on 
2607 PtlFini
2608 \emph default 
2609 , to cleanup after the application is done using the library.
2610 \layout Subsection
2611
2612 PtlInit
2613 \begin_inset LatexCommand \label{sec:ptlinit}
2614
2615 \end_inset 
2616
2617
2618 \layout LyX-Code
2619
2620 int PtlInit( int *max_interfaces );
2621 \layout Standard
2622 \noindent 
2623 The 
2624 \emph on 
2625 PtlInit
2626 \emph default 
2627  function initializes the Portals library.
2628  PtlInit must be called at least once by a process before any thread makes
2629  a Portals function call, but may be safely called more than once.
2630 \layout Subsubsection
2631
2632 Return Codes
2633 \layout Description
2634
2635 PTL_OK Indicates success.
2636  
2637 \layout Description
2638
2639 PTL_FAIL Indicates an error during initialization.
2640  
2641 \layout Description
2642
2643 PTL_SEGV Indicates that 
2644 \family typewriter 
2645 max_interfaces
2646 \family default 
2647  is not a legal address.
2648  
2649 \layout Subsubsection
2650
2651 Arguments
2652 \layout Standard
2653
2654
2655 \begin_inset  Tabular
2656 <lyxtabular version="3" rows="1" columns="3">
2657 <features>
2658 <column alignment="right" valignment="top" width="0pt">
2659 <column alignment="center" valignment="top" width="0pt">
2660 <column alignment="left" valignment="top" width="5in">
2661 <row>
2662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2663 \begin_inset Text
2664
2665 \layout Standard
2666
2667
2668 \family typewriter 
2669 max_interfaces
2670 \end_inset 
2671 </cell>
2672 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2673 \begin_inset Text
2674
2675 \layout Standard
2676
2677
2678 \series bold 
2679 output
2680 \end_inset 
2681 </cell>
2682 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2683 \begin_inset Text
2684
2685 \layout Standard
2686 \noindent 
2687 On successful return, this location will hold the maximum number of interfaces
2688  that can be initialized.
2689 \end_inset 
2690 </cell>
2691 </row>
2692 </lyxtabular>
2693
2694 \end_inset 
2695
2696
2697 \layout Subsection
2698
2699 PtlFini
2700 \begin_inset LatexCommand \label{sec:ptlfini}
2701
2702 \end_inset 
2703
2704
2705 \layout LyX-Code
2706
2707 void PtlFini( void );
2708 \layout Standard
2709 \noindent 
2710 The 
2711 \emph on 
2712 PtlFini
2713 \emph default 
2714  function cleans up after the Portals library is no longer needed by a process.
2715  After this function is called, calls to any of the functions defined by
2716  the Portal API or use of the structures set up by the Portals API will
2717  result in undefined behavior.
2718  This function should be called once and only once during termination by
2719  a process.
2720  Typically, this function will be called in the exit sequence of a process.
2721  Individual threads should not call PtlFini when they terminate.
2722 \layout Section
2723
2724 Network Interfaces
2725 \begin_inset LatexCommand \label{sec:ni}
2726
2727 \end_inset 
2728
2729  
2730 \layout Standard
2731
2732 The Portals API supports the use of multiple network interfaces.
2733  However, each interface is treated as an independent entity.
2734  Combining interfaces (e.g., 
2735 \begin_inset Quotes eld
2736 \end_inset 
2737
2738 bonding
2739 \begin_inset Quotes erd
2740 \end_inset 
2741
2742  to create a higher bandwidth connection) must be implemented by the application
2743  or embedded in the underlying network.
2744  Interfaces are treated as independent entities to make it easier to cache
2745  information on individual network interface cards.
2746 \layout Standard
2747
2748 Once initialized, each interface provides a Portal table, an access control
2749  table, and a collection of status registers.
2750  See Section\SpecialChar ~
2751
2752 \begin_inset LatexCommand \ref{sec:me}
2753
2754 \end_inset 
2755
2756  for a discussion of updating Portal table entries using the 
2757 \emph on 
2758 PtlMEAttach
2759 \emph default 
2760  function.
2761  See Section\SpecialChar ~
2762
2763 \begin_inset LatexCommand \ref{sec:ac}
2764
2765 \end_inset 
2766
2767  for a discussion of the initialization and updating of entries in the access
2768  control table.
2769  See Section\SpecialChar ~
2770
2771 \begin_inset LatexCommand \ref{sec:nistatus}
2772
2773 \end_inset 
2774
2775  for a discussion of the 
2776 \emph on 
2777 PtlNIStatus
2778 \emph default 
2779  function which can be used to determine the value of a status register.
2780 \layout Standard
2781
2782 Every other type of Portal object (e.g., memory descriptor, event queue, or
2783  match list entry) is associated with a specific network interface.
2784  The association to a network interface is established when the object is
2785  created and is encoded in the handle for the object.
2786 \layout Standard
2787
2788 Each network interface is initialized and shutdown independently.
2789  The initialization routine, 
2790 \emph on 
2791 PtlNIInit
2792 \emph default 
2793 , returns a handle for an interface object which is used in all subsequent
2794  Portal operations.
2795  The 
2796 \emph on 
2797 PtlNIFini
2798 \emph default 
2799  function is used to shutdown an interface and release any resources that
2800  are associated with the interface.
2801  Network interface handles are associated with processes, not threads.
2802  All threads in a process share all of the network interface handles.
2803 \layout Standard
2804
2805 The Portals API also defines the 
2806 \emph on 
2807 PtlNIStatus
2808 \emph default 
2809  function to query the status registers for a network interface, the 
2810 \emph on 
2811 PtlNIDist
2812 \emph default 
2813  function to determine the 
2814 \begin_inset Quotes eld
2815 \end_inset 
2816
2817 distance
2818 \begin_inset Quotes erd
2819 \end_inset 
2820
2821  to another process, and the 
2822 \emph on 
2823 PtlNIHandle
2824 \emph default 
2825  function to determine the network interface that an object is associated
2826  with.
2827 \layout Subsection
2828
2829 PtlNIInit
2830 \begin_inset LatexCommand \label{sec:niinit}
2831
2832 \end_inset 
2833
2834
2835 \layout LyX-Code
2836
2837 typedef struct {
2838 \newline 
2839     int            max_match_entries;
2840 \newline 
2841     int            max_mem_descriptors;
2842 \newline 
2843     int            max_event_queues;
2844 \newline 
2845     ptl_ac_index_t max_atable_index; 
2846 \newline 
2847     ptl_pt_index_t max_ptable_index;
2848 \newline 
2849 } ptl_ni_limits_t;
2850 \newline 
2851
2852 \newline 
2853 int PtlNIInit( ptl_interface_t  interface
2854 \newline 
2855                ptl_pid_t        pid,
2856 \newline 
2857                ptl_ni_limits_t* desired,
2858 \newline 
2859                ptl_ni_limits_t* actual,
2860 \newline 
2861                ptl_handle_ni_t* handle );
2862 \layout Standard
2863
2864 Values of type 
2865 \family typewriter 
2866 ptl_ni_limits_t
2867 \family default 
2868  include the following members:
2869 \layout Description
2870
2871 max_match_entries Maximum number of match entries that can be allocated
2872  at any one time.
2873 \layout Description
2874
2875 max_mem_descriptors Maximum number of memory descriptors that can be allocated
2876  at any one time.
2877 \layout Description
2878
2879 max_event_queues Maximum number of event queues that can be allocated at
2880  any one time.
2881 \layout Description
2882
2883 max_atable_index Largest access control table index for this interface,
2884  valid indexes range from zero to 
2885 \family typewriter 
2886 max_atable_index
2887 \family default 
2888 , inclusive.
2889 \layout Description
2890
2891 max_ptable_index Largest Portal table index for this interface, valid indexes
2892  range from zero to 
2893 \family typewriter 
2894 max_ptable_index
2895 \family default 
2896 , inclusive.
2897 \layout Standard
2898 \noindent 
2899 The 
2900 \emph on 
2901 PtlNIInit
2902 \emph default 
2903  function is used to initialized the Portals API for a network interface.
2904  This function must be called at least once by each process before any other
2905  operations that apply to the interface by any process or thread.
2906  For subsequent calls to 
2907 \shape italic 
2908 PtlNIInit
2909 \shape default 
2910  from within the same process (either by different threads or the same thread),
2911  the desired limits will be ignored and the call will return the existing
2912  NI handle.
2913 \layout Subsubsection
2914
2915 Return Codes
2916 \layout Description
2917
2918 PTL_OK Indicates success.
2919  
2920 \layout Description
2921
2922 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
2923  
2924 \layout Description
2925
2926 PTL_INIT_DUP Indicates a duplicate initialization of 
2927 \family typewriter 
2928 interface
2929 \family default 
2930 .
2931  
2932 \layout Description
2933
2934 PTL_INIT_INV Indicates that 
2935 \family typewriter 
2936 interface
2937 \family default 
2938  is not a valid network interface.
2939  
2940 \layout Description
2941
2942 PTL_NOSPACE Indicates that there is insufficient memory to initialize the
2943  interface.
2944  
2945 \layout Description
2946
2947 PTL_INV_PROC Indicates that 
2948 \family typewriter 
2949 pid
2950 \family default 
2951  is not a valid process id.
2952 \layout Description
2953
2954 PTL_SEGV Indicates that 
2955 \family typewriter 
2956 actual 
2957 \family default 
2958 or
2959 \family typewriter 
2960  handle
2961 \family default 
2962  is not a legal address.
2963  
2964 \layout Subsubsection
2965
2966 Arguments
2967 \layout Standard
2968
2969
2970 \begin_inset  Tabular
2971 <lyxtabular version="3" rows="5" columns="3">
2972 <features>
2973 <column alignment="right" valignment="top" width="0pt">
2974 <column alignment="center" valignment="top" width="0pt">
2975 <column alignment="left" valignment="top" width="4.7in">
2976 <row>
2977 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2978 \begin_inset Text
2979
2980 \layout Standard
2981
2982
2983 \family typewriter 
2984 interface
2985 \end_inset 
2986 </cell>
2987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2988 \begin_inset Text
2989
2990 \layout Standard
2991
2992
2993 \series bold 
2994 input
2995 \end_inset 
2996 </cell>
2997 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2998 \begin_inset Text
2999
3000 \layout Standard
3001 \noindent 
3002 Identifies the network interface to be initialized.
3003   (See section\SpecialChar ~
3004
3005 \begin_inset LatexCommand \ref{sec:ni-type}
3006
3007 \end_inset 
3008
3009  for a discussion of  values used to identify network interfaces.)
3010 \end_inset 
3011 </cell>
3012 </row>
3013 <row>
3014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3015 \begin_inset Text
3016
3017 \layout Standard
3018
3019
3020 \family typewriter 
3021 pid
3022 \end_inset 
3023 </cell>
3024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3025 \begin_inset Text
3026
3027 \layout Standard
3028
3029
3030 \series bold 
3031 input
3032 \end_inset 
3033 </cell>
3034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3035 \begin_inset Text
3036
3037 \layout Standard
3038 \noindent 
3039 Identifies the desired process id (for well known process ids).
3040  The value 
3041 \family typewriter 
3042 PTL_PID_ANY
3043 \family default 
3044  may be used to have the process id assigned by the underlying library.
3045 \end_inset 
3046 </cell>
3047 </row>
3048 <row>
3049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3050 \begin_inset Text
3051
3052 \layout Standard
3053
3054
3055 \family typewriter 
3056 desired
3057 \end_inset 
3058 </cell>
3059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3060 \begin_inset Text
3061
3062 \layout Standard
3063
3064
3065 \series bold 
3066 input
3067 \end_inset 
3068 </cell>
3069 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3070 \begin_inset Text
3071
3072 \layout Standard
3073 \noindent 
3074 If non-NULL, points to a structure that holds the desired limits.
3075 \end_inset 
3076 </cell>
3077 </row>
3078 <row>
3079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3080 \begin_inset Text
3081
3082 \layout Standard
3083
3084
3085 \family typewriter 
3086 actual
3087 \end_inset 
3088 </cell>
3089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3090 \begin_inset Text
3091
3092 \layout Standard
3093
3094
3095 \series bold 
3096 output
3097 \end_inset 
3098 </cell>
3099 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3100 \begin_inset Text
3101
3102 \layout Standard
3103 \noindent 
3104 On successful return, the location pointed to by actual will hold the actual
3105  limits.
3106 \end_inset 
3107 </cell>
3108 </row>
3109 <row>
3110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3111 \begin_inset Text
3112
3113 \layout Standard
3114
3115
3116 \family typewriter 
3117 handle
3118 \end_inset 
3119 </cell>
3120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3121 \begin_inset Text
3122
3123 \layout Standard
3124
3125
3126 \series bold 
3127 output
3128 \end_inset 
3129 </cell>
3130 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3131 \begin_inset Text
3132
3133 \layout Standard
3134 \noindent 
3135 On successful return, this location will hold a  handle for the interface.
3136 \end_inset 
3137 </cell>
3138 </row>
3139 </lyxtabular>
3140
3141 \end_inset 
3142
3143
3144 \layout Comment
3145
3146 The use of desired is implementation dependent.
3147  In particular, an implementation may choose to ignore this argument.
3148 \layout Subsection
3149
3150 PtlNIFini
3151 \begin_inset LatexCommand \label{sec:nifini}
3152
3153 \end_inset 
3154
3155
3156 \layout LyX-Code
3157
3158 int PtlNIFini( ptl_handle_ni_t interface );
3159 \layout Standard
3160 \noindent 
3161 The 
3162 \emph on 
3163 PtlNIFini
3164 \emph default 
3165  function is used to release the resources allocated for a network interface.
3166  Once the 
3167 \emph on 
3168 PtlNIFini
3169 \emph default 
3170  operation has been started, the results of pending API operations (e.g.,
3171  operations initiated by another thread) for this interface are undefined.
3172  Similarly, the effects of incoming operations (puts and gets) or return
3173  values (acknowledgements and replies) for this interface are undefined.
3174 \layout Subsubsection
3175
3176 Return Codes
3177 \layout Description
3178
3179 PTL_OK Indicates success.
3180  
3181 \layout Description
3182
3183 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3184  
3185 \layout Description
3186
3187 PTL_INV_NI Indicates that 
3188 \family typewriter 
3189 interface
3190 \family default 
3191  is not a valid network interface handle.
3192  
3193 \layout Subsubsection
3194
3195 Arguments
3196 \layout Standard
3197
3198
3199 \begin_inset  Tabular
3200 <lyxtabular version="3" rows="1" columns="3">
3201 <features>
3202 <column alignment="right" valignment="top" width="0pt">
3203 <column alignment="center" valignment="top" width="0pt">
3204 <column alignment="center" valignment="top" width="0pt">
3205 <row>
3206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3207 \begin_inset Text
3208
3209 \layout Standard
3210
3211 interface
3212 \end_inset 
3213 </cell>
3214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3215 \begin_inset Text
3216
3217 \layout Standard
3218
3219
3220 \series bold 
3221 input
3222 \end_inset 
3223 </cell>
3224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3225 \begin_inset Text
3226
3227 \layout Standard
3228
3229 A handle for the interface to shutdown.
3230 \end_inset 
3231 </cell>
3232 </row>
3233 </lyxtabular>
3234
3235 \end_inset 
3236
3237
3238 \layout Subsection
3239
3240 PtlNIStatus
3241 \begin_inset LatexCommand \label{sec:nistatus}
3242
3243 \end_inset 
3244
3245
3246 \layout LyX-Code
3247
3248 int PtlNIStatus( ptl_handle_ni_t interface,
3249 \newline 
3250                  ptl_sr_index_t  status_register,
3251 \newline 
3252                  ptl_sr_value_t* status );
3253 \layout Standard
3254 \noindent 
3255 The 
3256 \emph on 
3257 PtlNIStatus
3258 \emph default 
3259  function returns the value of a status register for the specified interface.
3260  (See section\SpecialChar ~
3261
3262 \begin_inset LatexCommand \ref{sec:stat-type}
3263
3264 \end_inset 
3265
3266  for more information on status register indexes and status register values.)
3267 \layout Subsubsection
3268
3269 Return Codes
3270 \layout Description
3271
3272 PTL_OK Indicates success.
3273  
3274 \layout Description
3275
3276 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3277  
3278 \layout Description
3279
3280 PTL_INV_NI Indicates that 
3281 \family typewriter 
3282 interface
3283 \family default 
3284  is not a valid network interface handle.
3285  
3286 \layout Description
3287
3288 PTL_INV_SR_INDX Indicates that 
3289 \family typewriter 
3290 status_register
3291 \family default 
3292  is not a valid status register.
3293  
3294 \layout Description
3295
3296 PTL_SEGV Indicates that 
3297 \family typewriter 
3298 status
3299 \family default 
3300  is not a legal address.
3301  
3302 \layout Subsubsection
3303
3304 Arguments
3305 \layout Standard
3306
3307
3308 \begin_inset  Tabular
3309 <lyxtabular version="3" rows="3" columns="3">
3310 <features>
3311 <column alignment="right" valignment="top" width="0pt">
3312 <column alignment="center" valignment="top" width="0pt">
3313 <column alignment="left" valignment="top" width="4.7in">
3314 <row>
3315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3316 \begin_inset Text
3317
3318 \layout Standard
3319
3320
3321 \family typewriter 
3322 interface
3323 \end_inset 
3324 </cell>
3325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3326 \begin_inset Text
3327
3328 \layout Standard
3329
3330
3331 \series bold 
3332 input
3333 \end_inset 
3334 </cell>
3335 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3336 \begin_inset Text
3337
3338 \layout Standard
3339 \noindent 
3340 A handle for the interface to use.
3341  
3342 \end_inset 
3343 </cell>
3344 </row>
3345 <row>
3346 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3347 \begin_inset Text
3348
3349 \layout Standard
3350
3351
3352 \family typewriter 
3353 status_register
3354 \end_inset 
3355 </cell>
3356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3357 \begin_inset Text
3358
3359 \layout Standard
3360
3361
3362 \series bold 
3363 input
3364 \end_inset 
3365 </cell>
3366 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3367 \begin_inset Text
3368
3369 \layout Standard
3370 \noindent 
3371 An index for the status register to read.
3372 \end_inset 
3373 </cell>
3374 </row>
3375 <row>
3376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3377 \begin_inset Text
3378
3379 \layout Standard
3380
3381
3382 \family typewriter 
3383 status
3384 \end_inset 
3385 </cell>
3386 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3387 \begin_inset Text
3388
3389 \layout Standard
3390
3391
3392 \series bold 
3393 output
3394 \end_inset 
3395 </cell>
3396 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3397 \begin_inset Text
3398
3399 \layout Standard
3400 \noindent 
3401 On successful return, this location will hold the current value of the status
3402  register.
3403 \end_inset 
3404 </cell>
3405 </row>
3406 </lyxtabular>
3407
3408 \end_inset 
3409
3410
3411 \layout Comment
3412
3413 The only status register that must be defined is a drop count register (
3414 \family typewriter 
3415 PTL_SR_DROP_COUNT
3416 \family default 
3417 ).
3418  Implementations may define additional status registers.
3419  Identifiers for the indexes associated with these registers should start
3420  with the prefix 
3421 \family typewriter 
3422 PTL_SR_
3423 \family default 
3424 .
3425 \layout Subsection
3426
3427 PtlNIDist
3428 \layout LyX-Code
3429
3430 int PtlNIDist( ptl_handle_ni_t  interface,
3431 \newline 
3432                ptl_process_id_t process,
3433 \newline 
3434                unsigned long*   distance );
3435 \layout Standard
3436 \noindent 
3437 The 
3438 \emph on 
3439 PtlNIDist
3440 \emph default 
3441  function returns the distance to another process using the specified interface.
3442  Distances are only defined relative to an interface.
3443  Distance comparisons between different interfaces on the same process may
3444  be meaningless.
3445 \layout Subsubsection
3446
3447 Return Codes
3448 \layout Description
3449
3450 PTL_OK Indicates success.
3451  
3452 \layout Description
3453
3454 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3455  
3456 \layout Description
3457
3458 PTL_INV_NI Indicates that 
3459 \family typewriter 
3460 interface
3461 \family default 
3462  is not a valid network interface handle.
3463  
3464 \layout Description
3465
3466 PTL_INV_PROC Indicates that 
3467 \family typewriter 
3468 process
3469 \family default 
3470  is not a valid process identifier.
3471  
3472 \layout Description
3473
3474 PTL_SEGV Indicates that 
3475 \family typewriter 
3476 distance
3477 \family default 
3478  is not a legal address.
3479  
3480 \layout Subsubsection
3481
3482 Arguments
3483 \layout Standard
3484
3485
3486 \begin_inset  Tabular
3487 <lyxtabular version="3" rows="3" columns="3">
3488 <features>
3489 <column alignment="right" valignment="top" width="0pt">
3490 <column alignment="center" valignment="top" width="0pt">
3491 <column alignment="left" valignment="top" width="4.7in">
3492 <row>
3493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3494 \begin_inset Text
3495
3496 \layout Standard
3497
3498
3499 \family typewriter 
3500 interface
3501 \end_inset 
3502 </cell>
3503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3504 \begin_inset Text
3505
3506 \layout Standard
3507
3508
3509 \series bold 
3510 input
3511 \end_inset 
3512 </cell>
3513 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3514 \begin_inset Text
3515
3516 \layout Standard
3517 \noindent 
3518 A handle for the interface to use.
3519  
3520 \end_inset 
3521 </cell>
3522 </row>
3523 <row>
3524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3525 \begin_inset Text
3526
3527 \layout Standard
3528
3529
3530 \family typewriter 
3531 process
3532 \end_inset 
3533 </cell>
3534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3535 \begin_inset Text
3536
3537 \layout Standard
3538
3539
3540 \series bold 
3541 input
3542 \end_inset 
3543 </cell>
3544 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3545 \begin_inset Text
3546
3547 \layout Standard
3548 \noindent 
3549 An identifier for the process whose distance is being  requested.
3550  
3551 \end_inset 
3552 </cell>
3553 </row>
3554 <row>
3555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3556 \begin_inset Text
3557
3558 \layout Standard
3559
3560
3561 \family typewriter 
3562 distance
3563 \end_inset 
3564 </cell>
3565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3566 \begin_inset Text
3567
3568 \layout Standard
3569
3570
3571 \series bold 
3572 output
3573 \end_inset 
3574 </cell>
3575 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3576 \begin_inset Text
3577
3578 \layout Standard
3579 \noindent 
3580 On successful return, this location will hold the  distance to the remote
3581  process.
3582 \end_inset 
3583 </cell>
3584 </row>
3585 </lyxtabular>
3586
3587 \end_inset 
3588
3589
3590 \layout Comment
3591
3592 This function should return a static measure of distance.
3593  Examples include minimum latency, the inverse of available bandwidth, or
3594  the number of switches between the two endpoints.
3595 \layout Subsection
3596
3597 PtlNIHandle
3598 \layout LyX-Code
3599
3600 int PtlNIHandle( ptl_handle_any_t handle,
3601 \newline 
3602                  ptl_handle_ni_t* interface );
3603 \layout Standard
3604 \noindent 
3605 The 
3606 \emph on 
3607 PtlNIHandle
3608 \emph default 
3609  function returns a handle for the network interface with which the object
3610  identified by 
3611 \family typewriter 
3612 handle
3613 \family default 
3614  is associated.
3615  If the object identified by 
3616 \family typewriter 
3617 handle
3618 \family default 
3619  is a network interface, this function returns the same value it is passed.
3620 \layout Subsubsection
3621
3622 Return Codes
3623 \layout Description
3624
3625 PTL_OK Indicates success.
3626  
3627 \layout Description
3628
3629 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3630  
3631 \layout Description
3632
3633 PTL_INV_HANDLE Indicates that 
3634 \family typewriter 
3635 handle
3636 \family default 
3637  is not a valid handle.
3638  
3639 \layout Description
3640
3641 PTL_SEGV Indicates that 
3642 \family typewriter 
3643 interface
3644 \family default 
3645  is not a legal address.
3646  
3647 \layout Subsubsection
3648
3649 Arguments
3650 \layout Standard
3651
3652
3653 \begin_inset  Tabular
3654 <lyxtabular version="3" rows="2" columns="3">
3655 <features>
3656 <column alignment="right" valignment="top" width="0pt">
3657 <column alignment="center" valignment="top" width="0pt">
3658 <column alignment="left" valignment="top" width="4.7in">
3659 <row>
3660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3661 \begin_inset Text
3662
3663 \layout Standard
3664
3665
3666 \family typewriter 
3667 handle
3668 \end_inset 
3669 </cell>
3670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3671 \begin_inset Text
3672
3673 \layout Standard
3674
3675
3676 \series bold 
3677 input
3678 \end_inset 
3679 </cell>
3680 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3681 \begin_inset Text
3682
3683 \layout Standard
3684 \noindent 
3685 A handle for the object.
3686 \end_inset 
3687 </cell>
3688 </row>
3689 <row>
3690 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3691 \begin_inset Text
3692
3693 \layout Standard
3694
3695
3696 \family typewriter 
3697 interface
3698 \end_inset 
3699 </cell>
3700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3701 \begin_inset Text
3702
3703 \layout Standard
3704
3705
3706 \series bold 
3707 output
3708 \end_inset 
3709 </cell>
3710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3711 \begin_inset Text
3712
3713 \layout Standard
3714 \noindent 
3715 On successful return, this location will hold a handle for the network interface
3716  associated with 
3717 \family typewriter 
3718 handle
3719 \family default 
3720 .
3721 \end_inset 
3722 </cell>
3723 </row>
3724 </lyxtabular>
3725
3726 \end_inset 
3727
3728
3729 \layout Comment
3730
3731 Every handle should encode the network interface and the object id relative
3732  to this handle.
3733  Both are presumably encoded using integer values.
3734 \layout Section
3735
3736 User Identification
3737 \begin_inset LatexCommand \label{sec:uid}
3738
3739 \end_inset 
3740
3741
3742 \layout Standard
3743
3744 Every process runs on behalf of a user.
3745  
3746 \layout Subsection
3747
3748 PtlGetUid
3749 \layout LyX-Code
3750
3751 int PtlGetUid( ptl_handle_ni_t   ni_handle,
3752 \newline 
3753                ptl_uid_t*        uid );
3754 \layout Subsubsection
3755
3756 Return Codes
3757 \layout Description
3758
3759 PTL_OK Indicates success.
3760  
3761 \layout Description
3762
3763 PTL_INV_NI Indicates that 
3764 \family typewriter 
3765 ni_handle
3766 \family default 
3767  is not a valid network interface handle.
3768  
3769 \layout Description
3770
3771 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3772  
3773 \layout Description
3774
3775 PTL_SEGV Indicates that 
3776 \family typewriter 
3777 interface
3778 \family default 
3779  is not a legal address.
3780  
3781 \layout Subsubsection
3782
3783 Arguments
3784 \layout Standard
3785
3786
3787 \begin_inset  Tabular
3788 <lyxtabular version="3" rows="2" columns="3">
3789 <features>
3790 <column alignment="right" valignment="top" width="0pt">
3791 <column alignment="center" valignment="top" width="0pt">
3792 <column alignment="left" valignment="top" width="5in">
3793 <row>
3794 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3795 \begin_inset Text
3796
3797 \layout Standard
3798
3799
3800 \family typewriter 
3801 handle
3802 \end_inset 
3803 </cell>
3804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3805 \begin_inset Text
3806
3807 \layout Standard
3808
3809
3810 \series bold 
3811 input
3812 \end_inset 
3813 </cell>
3814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3815 \begin_inset Text
3816
3817 \layout Standard
3818 \noindent 
3819 A network interface handle.
3820 \end_inset 
3821 </cell>
3822 </row>
3823 <row>
3824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3825 \begin_inset Text
3826
3827 \layout Standard
3828
3829
3830 \family typewriter 
3831 id
3832 \end_inset 
3833 </cell>
3834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3835 \begin_inset Text
3836
3837 \layout Standard
3838
3839
3840 \series bold 
3841 output
3842 \end_inset 
3843 </cell>
3844 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3845 \begin_inset Text
3846
3847 \layout Standard
3848 \noindent 
3849 On successful return, this location will hold the user id for the calling
3850  process.
3851 \end_inset 
3852 </cell>
3853 </row>
3854 </lyxtabular>
3855
3856 \end_inset 
3857
3858
3859 \layout Comment
3860
3861 Note that user identifiers are dependent on the network interface(s).
3862  In particular, if a node has multiple interfaces, a process may have multiple
3863  user identifiers.
3864 \layout Section
3865
3866 Process Identification
3867 \begin_inset LatexCommand \label{sec:pid}
3868
3869 \end_inset 
3870
3871
3872 \layout Standard
3873
3874 Processes that use the Portals API, can be identified using a node id and
3875  process id.
3876  Every node accessible through a network interface has a unique node identifier
3877  and every process running on a node has a unique process identifier.
3878  As such, any process in the computing system can be identified by its node
3879  id and process id.
3880  
3881 \layout Standard
3882
3883 The Portals API defines a type, 
3884 \family typewriter 
3885 ptl_process_id_t
3886 \family default 
3887  for representing process ids and a function, 
3888 \emph on 
3889 PtlGetId
3890 \emph default 
3891 , which can be used to obtain the id of the current process.
3892 \layout Comment
3893
3894 The portals API does not include thread identifiers.
3895   Messages are delivered to processes (address spaces) not threads (contexts
3896  of  execution).
3897 \layout Subsection
3898
3899 The Process Id Type
3900 \begin_inset LatexCommand \label{sec:pid-type}
3901
3902 \end_inset 
3903
3904
3905 \layout LyX-Code
3906
3907 typedef struct {
3908 \newline 
3909     ptl_nid_t       nid; /* node id */
3910 \newline 
3911     ptl_pid_t       pid; /* process id */
3912 \newline 
3913 } ptl_process_id_t;
3914 \layout Standard
3915 \noindent 
3916 The 
3917 \family typewriter 
3918 ptl_process_id_t
3919 \family default 
3920  type uses two identifiers to represent a process id: a node id and a process
3921  id.
3922  
3923 \layout Subsection
3924
3925 PtlGetId
3926 \begin_inset LatexCommand \label{sub:PtlGetId}
3927
3928 \end_inset 
3929
3930
3931 \layout LyX-Code
3932
3933 int PtlGetId( ptl_handle_ni_t   ni_handle,
3934 \newline 
3935               ptl_process_id_t* id );
3936 \layout Subsubsection
3937
3938 Return Codes
3939 \layout Description
3940
3941 PTL_OK Indicates success.
3942  
3943 \layout Description
3944
3945 PTL_INV_NI Indicates that 
3946 \family typewriter 
3947 ni_handle
3948 \family default 
3949  is not a valid network interface handle.
3950  
3951 \layout Description
3952
3953 PTL_NOINIT Indicates that the Portals API has not been successfully initialized.
3954  
3955 \layout Description
3956
3957 PTL_SEGV Indicates that 
3958 \family typewriter 
3959 id
3960 \family default 
3961  is not a legal address.
3962  
3963 \layout Subsubsection
3964
3965 Arguments
3966 \layout Standard
3967
3968
3969 \begin_inset  Tabular
3970 <lyxtabular version="3" rows="2" columns="3">
3971 <features>
3972 <column alignment="right" valignment="top" width="0pt">
3973 <column alignment="center" valignment="top" width="0pt">
3974 <column alignment="left" valignment="top" width="5in">
3975 <row>
3976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3977 \begin_inset Text
3978
3979 \layout Standard
3980
3981
3982 \family typewriter 
3983 handle
3984 \end_inset 
3985 </cell>
3986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3987 \begin_inset Text
3988
3989 \layout Standard
3990
3991
3992 \series bold 
3993 input
3994 \end_inset 
3995 </cell>
3996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3997 \begin_inset Text
3998
3999 \layout Standard
4000 \noindent 
4001 A network interface handle.
4002 \end_inset 
4003 </cell>
4004 </row>
4005 <row>
4006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4007 \begin_inset Text
4008
4009 \layout Standard
4010
4011
4012 \family typewriter 
4013 id
4014 \end_inset 
4015 </cell>
4016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4017 \begin_inset Text
4018
4019 \layout Standard
4020
4021
4022 \series bold 
4023 output
4024 \end_inset 
4025 </cell>
4026 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4027 \begin_inset Text
4028
4029 \layout Standard
4030 \noindent 
4031 On successful return, this location will hold the id for the calling process.
4032 \end_inset 
4033 </cell>
4034 </row>
4035 </lyxtabular>
4036
4037 \end_inset 
4038
4039
4040 \layout Comment
4041
4042 Note that process identifiers are dependent on the network interface(s).
4043  In particular, if a node has multiple interfaces, it may have multiple
4044  node identifiers.
4045 \layout Section
4046
4047 Match List Entries and Match Lists
4048 \begin_inset LatexCommand \label{sec:me}
4049
4050 \end_inset 
4051
4052
4053 \layout Standard
4054
4055 A match list is a chain of match list entries.
4056  Each match list entry includes a memory descriptor and a set of match criteria.
4057  The match criteria can be used to reject incoming requests based on process
4058  id or the match bits provided in the request.
4059  A match list is created using the 
4060 \emph on 
4061 PtlMEAttach
4062 \emph default 
4063  or 
4064 \shape italic 
4065 PtlMEAttachAny
4066 \shape default 
4067  functions, which create a match list consisting of a single match list
4068  entry, attaches the match list to the specified Portal index, and returns
4069  a handle for the match list entry.
4070  Match entries can be dynamically inserted and removed from a match list
4071  using the 
4072 \emph on 
4073 PtlMEInsert
4074 \emph default 
4075  and 
4076 \emph on 
4077 PtlMEUnlink
4078 \emph default 
4079  functions.
4080 \layout Subsection
4081
4082 PtlMEAttach
4083 \begin_inset LatexCommand \label{sec:meattach}
4084
4085 \end_inset 
4086
4087
4088 \layout LyX-Code
4089
4090 typedef enum { PTL_RETAIN, PTL_UNLINK } ptl_unlink_t;
4091 \newline 
4092
4093 \layout LyX-Code
4094
4095 typedef enum { PTL_INS_BEFORE, PTL_INS_AFTER } ptl_ins_pos_t;
4096 \newline 
4097
4098 \layout LyX-Code
4099
4100 int PtlMEAttach( ptl_handle_ni_t  interface,
4101 \newline 
4102                  ptl_pt_index_t   index,
4103 \newline 
4104                  ptl_process_id_t matchid,
4105 \newline 
4106                  ptl_match_bits_t match_bits,
4107 \newline 
4108                  ptl_match_bits_t ignorebits,
4109 \newline 
4110                  ptl_unlink_t     unlink,
4111 \newline 
4112                  ptl_ins_pos_t    position,
4113 \newline 
4114                  ptl_handle_me_t* handle );
4115 \layout Standard
4116 \noindent 
4117 Values of the type 
4118 \family typewriter 
4119 ptl_ins_pos_t
4120 \family default 
4121  are used to control where a new item is inserted.
4122  The value 
4123 \family typewriter 
4124 PTL_INS_BEFORE
4125 \family default 
4126  is used to insert the new item before the current item or before the head
4127  of the list.
4128  The value 
4129 \family typewriter 
4130 PTL_INS_AFTER
4131 \family default 
4132  is used to insert the new item after the current item or after the last
4133  item in the list.
4134  
4135 \layout Standard
4136
4137 The 
4138 \emph on 
4139 PtlMEAttach
4140 \emph default 
4141  function creates a match list consisting of a single entry and attaches
4142  this list to the Portal table for 
4143 \family typewriter