Software Design Description
for TREVBUS

Alex Pollard
Student 3099177

June 2001


Contents

Introduction

This document details the design of TREVBUS - Transmission Repeaters Enabling Virtually Bandwidth-Unlimited Streaming. It is a deliverable as part of my project at the Australian National University entitled:

Organisational and technical basis for community media streaming on a broadband metropolitan-area network.

TREVBUS 1.0 will run as a single process on both repeater nodes and director nodes.

Its functionality has two related parts:

Only director nodes utilise the director capabilities of the software. A director is therefore a repeater with its director functionality in use. The director functionality is trivial compared to that of the repeater functionality, but redefines the use a repeater is put to.

Purpose

The purpose of this document is to clarify the design of TREVBUS to aid any future effort to improve upon TREVBUS.

Scope

This document applies to TREVBUS 1.0. Further revisions of TREVBUS will require further revisions of this document and vice-versa. The description here does not correlate exactly to the structure or function of the C source code. In particular, redundant data structures and functions have been retained in the code in case they are useful in the future. If they do not appear in the design, they can generally be ignored. In any case, this design should be useful in understanding how TREVBUS works.

Definition and acronyms

See the SRS.

References

Module decomposition

The repeater shall be a single process which will deal with at least one streamed presentation. For each presentation it shall connect to one upstream repeater, the presentation's director, or for the director itself, the generator. For each presentation it shall relay RTSP and RTP between the upstream node and multiple downstream nodes, each of which may be either a client or another repeater.

The system can be decomposed in to the modules seen in figure 1. These modules are supported by a number of modules for message parsing, socket manipulation, and other basic functionality.


  
Figure 1: Functional dependencies of modules in TREVBUS 1.0

Main module description

The main module exists to encompass the functionality of TREVBUS and make it available to the user.

This module performs basic initialisation tasks and reads the configuration file. It then commences a loop, servicing each of the downstream and upstream sessions by calling the eventloop module.

Eventloop module description

The eventloop module exists to encompass the the functionality of each session.

The event loop module checks the file descriptors associated with the session to determine if any of them require reading, or if there is any data ready to be written to output file descriptors.

If data has arrived in the RTSP file descriptor, the message handler module is called. If data has arrived at one of the RTP file descriptors, then the function associated with the file descriptor is called. This function determines whether the data is a RTP packet, and if so, sends the packet to all the downstream sessions sharing this presentation which are in PLAY_STATE.

Finally, the module checks if the session is quitting. If so, it frees allocated data structures and removes the session.

Message handler module description

The purpose of the message handler module is to encompass the task of parsing incoming RTSP data so that any events arising can be handled. The message handler module determines whether the incoming data is a valid RTSP request or response. The module then calls the event handler module for whichever type of session this is - downstream or upstream.

Downstream module description

The downstream module exists to serve connections to downstream nodes. It encompasses the functionality related to this connection.

The downstream module is an event handler, featuring a state machine, and associated event handler functions. The state machine, seen in figure 2, has three states: INIT_STATE, READY_STATE and PLAY_STATE.

The transition from INIT_STATE to READY_STATE should only occur when all the streams have been SETUP. This is an improvement to the design which will eventually need to be made in order to deal with abnormal situations correctly.


  
Figure 2: The finite state machine of a downstream session. Only state transitions encountered in the normal operation of TREVBUS are shown.

In object-oriented terms, the downstream module operates upon downstream session objects.

A downstream session is an object which represents the relationship between a downstream node (either a repeater or a client) and the repeater itself.

Each downstream session has an associated upstream session. Thus, they share a presentation, which the downstream session repeats to its downstream node.

Upstream module description

The upstream module exists to serve connections to upstream nodes.

The upstream module operates upon upstream session objects. An upstream session is an object which represents the relationship between an upstream node and the repeater itself. The node is either a repeater, the director or, for the director itself, the generator.

Each upstream session has zero or more downstream sessions. An upstream session would not have a corresponding downstream session after a REDIRECT has been issued downstream, in the expectation of receiving a RTSP connection from downstream. Otherwise, there is always one of more downstream sessions for each presentation.

The upstream module is an event handler, which is a state machine, seen in figure 3, with the associated event handler functions. It is similar to that of the downstream session, except that state transitions are usually triggered by responses from the upstream node. These are responses to requests sent by the session itself. There is also a pseudo-state, REDIRECTING. This state entered when the upstream node sends a RTSP REDIRECT. The redirecting flag is set, but the session actually remains in INIT_STATE. A TEARDOWN request is sent upstream, and upon response, the connection is closed and a new connection made to the new RTSP URL.

The transition from INIT_STATE to READY_STATE is made only when all the streams specified in the DESCRIBE response have been SETUP.


  
Figure 3: The finite state machine of an upstream session. Only state transitions encountered in the normal operation of TREVBUS are shown.

Director module description

The purpose of the director module is to handle functionality required to establish and coordinate a tree of TREVBUS repeaters.

The director functionality shall be an addition to the repeater functionality. The director shall respond to HTTP GET requests on a port specified at run-time. It shall respond to requests for a presentation it is responsible for with a dynamically allocated RTSP URL. It shall then coordinate the repeater tree for this presentation by inserting additional RTSP messages in to the RTSP connection between the generator and the repeater tree.

Concurrent process decomposition

The single process running as both a repeater and a director will not operate actual processeses in the low-level sense. It shall instead round-robin between sessions it is handling. The decomposition between processes is best described as upstream vs downstream. Each session object is either upstream or downstream.

For more information, refer to the section on Interprocess Communication.

Data decomposition

The most significant data structures are those that hold information about each session. A session object is of type struct SESSION_STATE. There are two sets of struct SESSION_STATE objects: the upstream sessions and the downstream sessions.

Upstream and downstream sessions share a lot of characteristics, so in object-oriented terms, they each inherit from a notional generic session object.

Session data description

Attribute Description
session_id A unique numerical identifier for the session
cur_state The current state of the session
flags Miscellaneous status flags
num_streams The number of streams currently known about for
  this presentation
streams A list of STREAM objects, one for each stream
  for this presentation
objurl The name of the object from the end of the URL.
DescribedFlag A flag indicating whether a DESCRIBE request
  has been received for this session.
RTSP_last_request The type of the last RTSP request handled by
  this session.
RTSP_send_seq_num The CSeq number of the next RTSP message
  to be sent to another node by this session.
RTSP_recv_seq_num The CSeq number of the next RTSP message
  to be received from another node by this session.
in_buffer The buffer which holds RTSP messages received from the
  connected node.
in_size The length of the content in in_buffer.
out_buffer The buffer which holds RTSP messages to be sent to the
  connected node.
out_size The length of the content in out_buffer.
in_eventloop A flag to control entry in to the eventloop module.
fd The file descriptor that this session reads and writes RTSP
  messages with.
fd_stream A FILE pointer to ensure the RTSP file descriptor is flushed.
QuitSession A flag to indicate if this session should be destroyed.
readers A list of functions associated with each file descriptor
  which this session uses to receive RTP or RTCP packets.

 

Downstream session data description

The downstream module has a list of downstream session objects. In object-oriented terms, the downstream session class inherits attributes from the session class. In addition, it has the following attributes:

Attribute Description
serverurl The URL of this repeater, in the form rtsp://repeater:port/
url The complete URL for this presentation recorded from
  the downstream node's requests.
trevbus_url The unique identifier for the presentation this session handles,
  which is the remainder of the complete url after the serverurl
us_session A reference to the upstream session which this
  session shares a presentation with.
poll_here A reference to the cache which holds the RTSP response from upstream
heartbeater A flag indicating whether this downstream session
  should send its RTCP packets upstream
redirecting A flag indicating that this session has
  redirected a downstream node.

 

Upstream session data description

The upstream module has a list of upstream session objects. The upstream session class inherits from session and also has these attributes:

Attribute Description
serverurl The URL of the upstream node this session is connected to.
url The complete URL sent upstream in requests
trevbus_url The unique identifier for the presentation this session
  handles.
us_session A flag which is false if this is an upstream session.
poll_here A flag which is false if this is an upstream session.
cache_list A list of struct CACHE_LIST objects for holding RTSP
  responses from upstream.
director A flag indicating whether this session coordinates a tree
  of repeaters for this presentation. False if this session is not a director.
redirecting A flag indicating this session has been redirected by an upstream node.
redirect_to The new URL specified in the REDIRECT request.
describe_request The DESCRIBE request received from downstream which would
  be sent again after being redirected to another upstream node.

Cache list data description

Cache list is a list held by each upstream session which can hold a cached copy of a response to each type of RTSP request sent upstream. It is not used for SETUP, PAUSE and TEARDOWN responses. A SETUP response is recorded in the stream object it relates to. PAUSE and TEARDOWN requests from downstream are not sent upstream unless the upstream session has to, so the responses are not cached.

Attribute Description
serverurl The URL of the upstream node this session is connected to.
url The complete URL sent upstream in requests
trevbus_url The remainder of the complete URL after the server's URL.
us_session A flag which is false if this is an upstream session.
poll_here A flag which is false if this is an upstream session.
cache_list A list of struct CACHE_LIST objects for holding RTSP
  responses from upstream.
director A reference to a data structure related to coordinating a tree
  of repeaters for this presentation. False if this session is not a director.

Stream data description

For each session object, data for each stream in the presentation is recorded in a struct STREAM object. It has the following attributes:

Attribute Description
next The next stream object in the list.
stream_id The numerical ID of this stream.
stream_name The text identifier for this stream used in SETUP requests.
seq_num The sequence number of the last RTP or RTCP packet received.
rtp_saddr_in The socket address for the incoming RTP packets.
rtcp_saddr_in The socket address for the incoming RTCP packets.
rtp_saddr_out The socket address for the outgoing RTP packets.
rtcp_saddr_out The socket address for the outgoing RTCP packets.
my_rtp_port The UDP port from which RTP packets are sent by this stream.
my_rtcp_port The UDP port from which RTCP packets are sent by this stream.
its_rtp_port The UDP port from which RTP packets are received for this stream.
its_rtcp_port The UDP port from which RTCP packets are received for this stream.
rtp_fd The file descriptor from which RTP packets are sent or received
  for this stream.
rtcp_fd The file descriptor from which RTCP packets are sent or received
  for this stream.

its_ip

The IP address of the node which this stream exchanges
  RTP and RTCP packets with.

cache_flag

A flag which indicates if there is a cached SETUP response
  for this stream from upstream, or if it has been requested
  but is pending.
cache Holds the cached copy of the SETUP response for this stream
  from upstream.

Director data description

The director shall have number of data structures that will enable it to model the TREVBUS repeater tree which it coordinates. These are yet to be decided upon.

Main data description

The main module has a collection of variables which are used to listen to and create new RTSP connections on the TCP port specified in the configuration file.

Eventloop data description

The eventloop module has the following significant data structures:

Attribute Description
downstream A flag indicating if the session under consideration
  should be treated as an upstream session or a
  downstream session.
readset For determining which of the session's file
  descriptors is ready for reading.
writeset For determining which of the session's file
  descriptors is ready for writing.

Message handler data description

The message handler module has the no significant data structures.

Intermodule dependencies

The dependencies of the modules are shown in figure 1.

Interprocess dependencies

TREVBUS is a single process and does not communicate with any other processes other than by HTTP, RTSP and RTP (including RTCP).

However, there is communication between sessions within this process. There is interaction between upstream and downstream sessions and this interaction is managed both synchronously and asynchronously.

A downstream process makes synchronous use of upstream functionality. When a new downstream connection is created, the downstream session calls check_upstream to determine if an upstream session already exists which serves this presentation. Also, when the downstream session receives a RTSP request, it may find that there is no cached copy of the RTSP response. In this case, it will synchronously call the appropriate upstream function which sends the request to the upstream node. It will also set flags in the upstream session's data structure indicating that a response is being waited for and keep a reference to the cache's location. The sessions then communicate asynchronously. The downstream session enters polling mode and takes no further action until the referenced cache is filled.

When the cache is filled, the downstream session makes a copy of the cache and adjusts it so that it can be sent to the downstream node.

Module interface

Main description

The main module accepts as its input a command-line parameter. This specifies a configuration file which is used to set the following parameters:

Only a director makes use of the HTTP port. However, TREVBUS listens on the HTTP port even if it is only a repeater. This means that if multiple repeaters are running on the same node, they must be allocated different HTTP ports. An improvement would be for TREVBUS to not listen on a HTTP port if none is specified in the configuration file.

Configuration information concerning the arrangement of the repeater tree is hard-coded in to main/config.c. This should become an interface specified through the configuration file.

Eventloop description

The eventloop module has an interface of a single function eventloop with a parameter specifying which session is being served.

Message handler description

The message handler module has an interface of a single function, msg_handler. It takes as a parameter the session under consideration and a global variable downstream which flags whether this is a downstream session. This decides which event handling module is used, downstream or upstream.

Downstream description

The downstream module is first accessed through the function handle_event. This accesses the session's state machine, which calls the various event handler functions within the module. The function receives as parameters the session, the type of RTSP request or response detected, the RTSP response status if it is a response and a buffer holding the first line of the message.

The other functions in the downstream session interface are:

send_redirect is used by the director module when it decides not to directly serve a repeater. The repeater is REDIRECTed to another repeater.

The last three are used by eventloop module. When a cached response is detected, eventloop ends polling, and calls on the downstream session to pass the response to the downstream node. The three functions take the downstream session and the cached response as parameters. send_setup_reply also takes a STREAM structure as a parameter, though this is NULL when eventloop calls it.

Upstream description

The upstream module is first accessed through the function handle_event_us. This accesses the session's state machine, which calls the various event handler functions within the module. The function receives as parameters the session, the type of RTSP request or response detected, the RTSP response status if it is a response and a buffer holding the first line of the message.

The other functions in the upstream session interface are:

check_upstream is used by the downstream module as described previously and takes the downstream session as a parameter.

The last five are used by the downstream module. If no cached response is detected, the downstream session begins polling, and calls on the upstream session to pass the request to the upstream node. The functions take the upstream session as a parameter and, with the exception of send_close_request, the request message received from downstream. send_setup_request also takes the stream_id of the stream to be SETUP as a parameter.

Director description

The director shall communicate in the first instance by HTTP. It shall accept HTTP connections and deal with the HTTP GET request:
http://director_address:http_port/trevbus/presentation_name
with the .mov file as appropriate, in standard HTTP form including a Content-type: field:

HTTP/1.1 200 OK\r
Server: TREVBUS 1.0 for Linux\r
Content-type: video/quicktime\r
Content-length: %d\r
Accept-ranges: bytes\r
Connection: close\r
\r\n
rtsptext\r\n
rtsp://repeater_IP:rtsp_port/trevbus/director_IP:rtsp_port/object\r\n
\r\n

The .mov file starts with rtsptext which tells QuickTime Player to access the RTSP address given and connect to the repeater which the director has designated for this player. To do the above, the director module shall be called by the main module loop which serves each of the sessions in turn.

The director module shall then await an RTSP request of the following form:
DESCRIBE rtsp://director_IP:port/trevbus/director_IP:port/object

The director functionality executed by is_a_director_session which is called by check_upstream in the upstream module. If the originator receives such a request for the presentation it serves, it shall determine in what place in the TREVBUS tree it shall place the requesting client or repeater. It shall then issue a REDIRECT command to the connector, redirecting the connector to the desired repeater in the TREVBUS tree. The director shall call send_redirect in the downstream module to effect this. The director shall then await another call to is_a_director_session, signifying a connection from this repeater.

When this connection is obtained it shall then allow the connection to proceed as a normal repeater session, with the upstream module opening a RTSP connection to the generator.

About this document ...

Software Design Description
for TREVBUS

This document was generated using the LaTeX2HTML translator Version 98.1p1 release (March 2nd, 1998)

Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds.

The command line arguments were:
latex2html -split 0 -no_subdir -no_navigation SDD.tex.

The translation was initiated by Alexander Gray Pollard on 2001-06-28


Alexander Gray Pollard
2001-06-28