\chapter{The (Revised) Addressing Structure in NS}
\label{chap:Address}

This chapter describes the internals of the revised addressing format
implemented in \ns. The chapter consists of five sections. We
describe the APIs that can be used for allocating bits to the ns addressing
structure. The address space as described in chapter 3, can be thought
of a contiguous field of {\em n} bits, where n may vary as per the
address requirement of the simulation. The default value of {\em n} is
16 (as defined by {\em MAXADDRSIZE\_}). The maximum value of {\em n} is
set to 32 (defined as {\em MAXADDRSIZE\_}). These default and maximum 
address sizes are defined in \nsf{/tcl/lib/ns-default.tcl}.

The address space consists of 2 parts, the node-id and the port-id.
The higher bits are assigned as the node's
address or id\_ and remaining lower bits are assigned to form port-id or
the identification of the agent attached to the node. Of the higher
bits, 1 bit is assigned for multicast. The address space consists of 32 bits and port id space consists of 32 bits as well.
The higher 32 bits for node-id, the MSB for multicast and the lower 32
bits for port-id. Additionally, the address space may
also be set in hierarchical format, consisting of multiple levels of
addressing hierarchy. 
We shall be describing the APIs for setting address structure in
different formats as described above as well as expanding the address
space. 
The procedures and functions described in this chapter can be found in
\nsf{tcl/lib/ns-address.tcl, address.cc and address.h}.

\section{The Default Address Format}
\label{sec:defaultFormat}

The default settings allocates 32 lower bits for port-id, 1 higher bit
for mcast and the rest 32 higher bits for node-id. The procedure to set
the address format in default mode is called during initialisation of
the simulator as:


\begin{program}
{\cf # The preamble}
set ns [new Simulator]                  \; initialise the simulation;
\end{program}

It can also be called explicitly set as:
\begin{program}
\$ns set-address-format def
\end{program}


\section{The Hierarchical Address Format}
\label{sec:hierFormat}

There are two options for setting an address to hierarchical format, the
default and the specified.

\subsection{Default Hierarchical Setting}
\label{sec:def-hier}
The default hierarchical node-id consists of 3 levels with (10 11 11) bits
in the three levels. The hierarchical configuration may be invoked as
follows: 

\$ns set-address-format hierarchical

\begin{quote}
This sets :

* 32 bits for port-id, 
* 32 bits for node-id assigned in 
  - 3 levels of hierarchy 
  - (10 11 11) bits for the three levels. 
  - or (9 11 11) if multicast is enabled. 
\end{quote}

\subsection{Specific Hierarchical Setting}
\label{sec:sp-hier}
The second option allows a hierarchical address to be set with specified
number of levels with number of bits assigned for each level. The API
would be as the following:

\$ns set-address-format hierarchical <\#n hierarchy levels> <\#bits for
level1> <\#bits for level 2> ....<\#bits for nth level> 


An example configuration would be:

\$ns set-address-format hierarchical 2 8 15 

where 2 levels of hierarchy is specified, assigning 8 bits for the 1st
level and 15 bits for the second.


\section{The Expanded Node-Address Format}
\label{sec:expandFormat}

NOTE: Please note that this command is now obsolete given that node address and port address spaces are 32 bits wide.

On the event of requirement of more bits to the address space, the
expanded address API may be used as:

\$ns set-address-format expanded   

This expands the address space to 30 bits, allocating 22 higher bits to
node-id and lower 8 bits to port-id. 


\section{Expanding port-id field}    
\label{sec:expandportFormat}

NOTE: Please note that this command is now obsolete given that node address and port address spaces are 32 bits wide.

This primitive may be used in case of need to expand portid in the event
of requirement to attach a large number of agents to the nodes. This may
be used in conjunction with set-addres-format command (with different
options) explained above. Synopsis for this command shall be:

expand-port-field-bits <\#bits for portid> 

expand-port-field-bits checks and raises error in the following if the
requested portsize cannot be accomodated (i.e if sufficient num.of free
bits are not available) or if requested portsize is less than or equal
to the existing portsize. 

\section{Errors in setting address format}
\label{sec:err-add}

Errors are returned for both {\em set-address-format} and
{\em expand-port-field-bits} primitives in the following cases:
\begin{quote}
* if number of bits specified is less than 0.
* if bit positions clash (contiguous number of requested free bits not
* found).  
* if total number of bits exceed MAXADDRSIZE\_.
* if expand-port-field-bits is attempted with portbits less than or
* equal to the existing portsize.
* if number of hierarchy levels donot match with number of bits
* specified (for each level).  
\end{quote}

\section{Commands at a glance}
\label{sec:addresscommand}

The following is a list of address-format related commands used in simulation
scripts:
\begin{flushleft}
\code{$ns_ set-address-format def}\\
This command is used internally to set the address format to its default value
of 32 lower bits for port-id, 1 higher bit for mcast and the rest 31 higher bits
for node-id. However this API has been replaced by the new node API\\
\code{$ns_ node-config -addressType flat}.


\code{$ns_ set-address-format hierarchical}\\
This command is used to set the address format to the hierarchical configuration
that consists of 3 levels with 8bits assigned to each level and 32 lower bits
for port-id. However this API has been replaced by the new node API\\
\code{$ns_ node-config -addressType hierarchical}.


\code{$ns_ set-address-format hierarchical <levels> <args>}\\
This command is used to set the address format to a specific hierarchical
setting. The <levels> indicate the number of levels of hierarchy in the addressing
structure, while the args define number of bits for each level. An example
would be \code{$ns_ set-address-format hierachical 3 4 4 16} , where 4, 4 and
16 defines the number of bits to be used for the address space in level 1 , 2
and 3 respectively.


\code{$ns_ set-address-format expanded}\\
THIS COMMAND IS NOW OBSOLETE
This command was used to expand the address space to 30 bits, allocating
22 higher bits for node-id and lower 8 bits for port-id. However this command
is obsoleted now by 32 bit addressing, i.e node-id field is 32 bit wide.


\code{expand-port-field-bits <bits-for-portid>}\\
THIS COMMAND IS NOW OBSOLETE
Similar to the command above, this was used to expand the address space for
the port-id field to <bits-for-portid> number of bits. However this command
is obsolete now that the ports are 32 bit wide.


\end{flushleft}
\endinput





