portals3.lyx

lustre 1.6.5 source code

\end_inset 

 bits, and a set of 
\begin_inset Quotes eld
\end_inset 

must match
\begin_inset Quotes erd
\end_inset 

 bits.
 In addition to the two sets of match bits, each match list element has
 at most one memory descriptor.
 Each memory descriptor identifies a memory region and an optional event
 queue.
 The memory region specifies the memory to be used in the operation and
 the event queue is used to record information about these operations.
\layout Standard


\begin_inset Float figure
placement htbp
wide false
collapsed false

\layout Standard
\align center 

\begin_inset Graphics FormatVersion 1
	filename portals.eps
	display color
	size_type 0
	rotateOrigin center
	lyxsize_type 1
	lyxwidth 305pt
	lyxheight 106pt
\end_inset 


\layout Caption

Portal Addressing Structures
\begin_inset LatexCommand \label{fig:portals}

\end_inset 


\end_inset 


\layout Standard

Figure\SpecialChar ~

\begin_inset LatexCommand \ref{fig:flow}

\end_inset 

 illustrates the steps involved in translating a Portal address, starting
 from the first element in a match list.
 If the match criteria specified in the match list entry are met and the
 memory descriptor list accepts the operation
\begin_inset Foot
collapsed true

\layout Standard

Memory descriptors can reject operations because a threshold has been exceeded
 or because the memory region does not have sufficient space, see Section\SpecialChar ~

\begin_inset LatexCommand \ref{sec:md}

\end_inset 


\end_inset 

, the operation (put or get) is performed using the memory region specified
 in the memory descriptor.
 If the memory descriptor specifies that it is to be unlinked when a threshold
 has been exceeded, the match list entry is removed from the match list
 and the resources associated with the memory descriptor and match list
 entry are reclaimed.
 Finally, if there is an event queue specified in the memory descriptor,
 the operation is logged in the event queue.
\layout Standard


\begin_inset Float figure
placement htbp
wide false
collapsed false

\layout Standard
\align center 

\begin_inset Graphics FormatVersion 1
	filename flow_new.eps
	display color
	size_type 0
	rotateOrigin center
	lyxsize_type 1
	lyxwidth 447pt
	lyxheight 282pt
\end_inset 


\layout Caption

Portals Address Translation
\begin_inset LatexCommand \label{fig:flow}

\end_inset 


\end_inset 


\layout Standard

If the match criteria specified in the match list entry are not met, or
 there is no memory descriptor associated with the match list entry, or
 the memory descriptor associated with the match list entry rejects the
 operation, the address translation continues with the next match list entry.
 If the end of the match list has been reached, the address translation
 is aborted and the incoming requested is discarded.
\layout Section

Access Control
\layout Standard

A process can control access to its portals using an access control list.
 Each entry in the access control list specifies a process id and a Portal
 table index.
 The access control list is actually an array of entries.
 Each incoming request includes an index into the access control list (i.e.,
 a 
\begin_inset Quotes eld
\end_inset 

cookie
\begin_inset Quotes erd
\end_inset 

 or hint).
 If the id of the process issuing the request doesn't match the id specified
 in the access control list entry or the Portal table index specified in
 the request doesn't match the Portal table index specified in the access
 control list entry, the request is rejected.
 Process identifiers and Portal table indexes may include wild card values
 to increase the flexibility of this mechanism.
 
\layout Standard

Two aspects of this design merit further discussion.
 First, the model assumes that the information in a message header, the
 sender's id in particular, is trustworthy.
 In most contexts, we assume that the entity that constructs the header
 is trustworthy; however, using cryptographic techniques, we could easily
 devise a protocol that would ensure the authenticity of the sender.
\layout Standard

Second, because the access check is performed by the receiver, it is possible
 that a malicious process will generate thousands of messages that will
 be denied by the receiver.
 This could saturate the network and/or the receiver, resulting in a 
\emph on 
denial of service
\emph default 
 attack.
 Moving the check to the sender using capabilities, would remove the potential
 for this form of attack.
 However, the solution introduces the complexities of capability management
 (exchange of capabilities, revocation, protections, etc).
\layout Section

Multi-threaded Applications
\begin_inset LatexCommand \label{sec:threads}

\end_inset 

 
\layout Standard

The Portals API supports a generic view of multi-threaded applications.
 From the perspective of the Portals API, an application program is defined
 by a set of processes.
 Each process defines a unique address space.
 The Portals API defines access to this address space from other processes
 (using portals addressing and the data movement operations).
 A process may have one or more 
\emph on 
threads
\emph default 
 executing in its address space.
 
\layout Standard

With the exception of 
\emph on 
PtlEQWait
\emph default 
 every function in the Portals API is non-blocking and atomic with respect
 to both other threads and external operations that result from data movement
 operations.
 While individual operations are atomic, sequences of these operations may
 be interleaved between different threads and with external operations.
 The Portals API does not provide any mechanisms to control this interleaving.
 It is expected that these mechanisms will be provided by the API used to
 create threads.
\layout Chapter

The Portals API
\begin_inset LatexCommand \label{sec:api}

\end_inset 


\layout Section

Naming Conventions
\begin_inset LatexCommand \label{sec:conv}

\end_inset 


\layout Standard

The Portals API defines two types of entities: functions and types.
 Function always start with 
\emph on 
Ptl
\emph default 
 and use mixed upper and lower case.
 When used in the body of this report, function names appear in italic face,
 e.g., 
\emph on 
PtlInit
\emph default 
.
 The functions associated with an object type will have names that start
 with 
\emph on 
Ptl
\emph default 
, followed by the two letter object type code shown in Table\SpecialChar ~

\begin_inset LatexCommand \ref{tab:objcodes}

\end_inset 

.
 As an example, the function 
\emph on 
PtlEQAlloc
\emph default 
 allocates resources for an event queue.
\layout Standard


\begin_inset Float table
placement htbp
wide false
collapsed false

\layout Caption

Object Type Codes
\begin_inset LatexCommand \label{tab:objcodes}

\end_inset 


\begin_inset ERT
status Collapsed

\layout Standard
 
\backslash 
medskip
\newline 
  
\end_inset 


\layout Standard
\align center 

\size small 

\begin_inset  Tabular
<lyxtabular version="3" rows="5" columns="3">
<features firstHeadEmpty="true">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0pt">
<row bottomline="true">
<cell alignment="left" valignment="top" bottomline="true" usebox="none">
\begin_inset Text

\layout Standard

 
\emph on 
xx
\end_inset 
</cell>
<cell alignment="left" valignment="top" bottomline="true" usebox="none">
\begin_inset Text

\layout Standard

 Name 
\end_inset 
</cell>
<cell alignment="left" valignment="top" bottomline="true" usebox="none">
\begin_inset Text

\layout Standard

 Section 
\end_inset 
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

EQ 
\end_inset 
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 Event Queue 
\end_inset 
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 
\begin_inset LatexCommand \ref{sec:eq}

\end_inset 


\end_inset 
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 MD 
\end_inset 
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 Memory Descriptor 
\end_inset 
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 
\begin_inset LatexCommand \ref{sec:md}

\end_inset 


\end_inset 
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 ME 
\end_inset 
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 Match list Entry 
\end_inset 
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 
\begin_inset LatexCommand \ref{sec:me}

\end_inset 


\end_inset 
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 NI 
\end_inset 
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 Network Interface 
\end_inset 
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text

\layout Standard

 
\begin_inset LatexCommand \ref{sec:ni}

\end_inset 


\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\end_inset 


\layout Standard

Type names use lower case with underscores to separate words.
 Each type name starts with 
\family typewriter 
ptl
\family default 
_ and ends with 
\family typewriter 
_t
\family default 
.
 When used in the body of this report, type names appear in a fixed font,
 e.g., 
\family typewriter 
ptl_match_bits_t
\family default 
.
\layout Standard

Names for constants use upper case with underscores to separate words.
 Each constant name starts with 
\family typewriter 
PTL_
\family default 
.
 When used in the body of this report, type names appear in a fixed font,
 e.g., 
\family typewriter 
PTL_OK
\family default 
.
\layout Section

Base Types
\layout Standard

The Portals API defines a variety of base types.
 These types represent a simple renaming of the base types provided by the
 C programming language.
 In most cases these new type names have been introduced to improve type
 safety and to avoid issues arising from differences in representation sizes
 (e.g., 16-bit or 32-bit integers).
\layout Subsection

Sizes
\begin_inset LatexCommand \label{sec:size-t}

\end_inset 

 
\layout Standard

The type 
\family typewriter 
ptl_size_t
\family default 
 is an unsigned 64-bit integral type used for representing sizes.
\layout Subsection

Handles
\begin_inset LatexCommand \label{sec:handle-type}

\end_inset 

 
\layout Standard

Objects maintained by the API are accessed through handles.
 Handle types have names of the form 
\family typewriter 
ptl_handle_
\emph on 
xx
\emph default 
_t
\family default 
, where 
\emph on 
xx
\emph default 
 is one of the two letter object type codes shown in Table\SpecialChar ~

\begin_inset LatexCommand \ref{tab:objcodes}

\end_inset 

.
 For example, the type 
\family typewriter 
ptl_handle_ni_t
\family default 
 is used for network interface handles.
\layout Standard

Each type of object is given a unique handle type to enhance type checking.
 The type, 
\family typewriter 
ptl_handle_any_t
\family default 
, can be used when a generic handle is needed.
 Every handle value can be converted into a value of type 
\family typewriter 
ptl_handle_any_t
\family default 
 without loss of information.
\layout Standard

Handles are not simple values.
 Every portals object is associated with a specific network interface and
 an identifier for this interface (along with an object identifier) is part
 of the handle for the object.
\layout Standard

The special value 
\family typewriter 
PTL_EQ_NONE
\family default 
, of type 
\family typewriter 
ptl_handle_eq_t
\family default 
, is used to indicate the absence of an event queue.
 See sections 
\begin_inset LatexCommand \ref{sec:mdfree}

\end_inset 

 and\SpecialChar ~

\begin_inset LatexCommand \ref{sec:mdupdate}

\end_inset 

 for uses of this value.
\layout Subsection

Indexes
\begin_inset LatexCommand \label{sec:index-type}

\end_inset 

 
\layout Standard

The types 
\family typewriter 
ptl_pt_index_t
\family default 
 and 
\family typewriter 
ptl_ac_index_t
\family default 
 are integral types used for representing Portal table indexes and access
 control tables indexes, respectively.
 See section\SpecialChar ~

\begin_inset LatexCommand \ref{sec:niinit}