Subversion Repositories shark

----------------------------------
Pong demo

by

Spencer Hoke
James Kim
Tao Luo

for

CS 324 Real-Time Systems
at The University of Illinois at Urbana-Champaign
with Marco Caccamo

May 5, 2004
----------------------------------

FILES:
  MAKEFILE     The makefile used to compile the application;
  PONG.H       Header file containing constants used by both pong and JET
  PONG.C       Main code
  JETCTRL.C    Tasks for the JET monitors
               (This file is based on the jetctrl.c file from other Shark demos)
  INITFILE.C   Initializes EDF/CBS scheduling and mutexes
  README.TXT   This file

USAGE:
- Copy the source files into a folder within the shark/demos and use 'make' to
  compile.
- Run by typing 'x pong' at the A:\> prompt if using the standard boot disk.

PROGRAM OPERATION:
- The purpose of each player is to control the paddle so that the balls bounce
  off the paddle and past the other player's paddle.
- Adding new balls is done by pressing the space bar.
- The number of balls can be kept constant by pressing the L key. "Locked"
  will be displayed under the number of balls indicating that the number of
  balls will be held constant at this number. The countMonitor task adds new
  balls whenever one leaves. When L is pressed again, balls that exit will not
  be reintroduced.
- The scores for each player are shown in the upper left corner and are
  updated whenever a ball reaches the top or bottom of the play area. At this
  time, that ball is removed.
- The difficulty of the computer's paddle can be changed by adjusting the
  length of each paddle, and constants controlled by keys 0-9.
- You can adjust the length of the paddles or constants at any time.

GRAPHICS:
- It works at 640x480 8 bit colors using the grx interface
- On the left is the main playing area. On the right are the commands and the
  JET information. Adjustable parameters are shown above and below the play
  area.

TASKS:
- Ball - each ball is a separate task. There can be as many of these as can be
  scheduled. Each one stores a position and angle, and updates with a new
  position each task cycle, drawing a black circle over its old position and
  drawing its new position. The balls also check to make sure that their new
  position is not outside the play area or inside of a paddle, in which case
  balls will bounce and change angles. If a ball goes past the paddle, it
  is removed and the task ends. Ball bounces are done elastically.
- Paddle1 - this is the user-controlled paddle. It uses the keys entered by
  the user to update its position during each cycle.
- Paddle2 - this is the computer-controlled paddle. It uses a position
  generated by task p2ai and moves toward a new position by applying both
  proportional and derivative forces. The paddle's mass and constants kp and
  kd are all adjustable at run-time.
- P2ai - this task reads all the current balls in the system that are within
  the AI viewing window (adjustable at run-time) and determines the position
  that paddle2 should move to in order to hit the next ball. The first ball to
  hit is calculated based on the position and angles of the balls, and also
  accounts for bouncing
- CountMonitor - if the number of balls is locked, this task checks to see if
  the number of balls in the system is at least equal to the min_balls
  variable and adds ball tasks if not.
- JetCtrl - updates the table of tasks with their mean/max execution times
- JetDummy - draws the system utilization graph
- JetSlide - draws the utilization bars beside each task listed in the JET
  task list.
- Main - after initialization, main reads the keyboard. Reads are blocking,
  and the appropriate action is taken after a key is pressed.

TASK SCHEDULING:
- Tasks are scheduled using EDF with a CBS. JET tasks are soft and follow
  CBS, while all other tasks are hard and follow EDF scheduling. Parameters for
  the tasks are (in ms):

    JetCtrl   7.5  met   100 period
    JetDummy  0.2  met   100 period
    JetSlide  2.1  met   100 period
    Balls     0.75 wcet   40 period
    CountMon  0.75 wcet   40 period
    Paddles   0.25 wcet   40 period
    P2ai      0.25 wcet   40 period

- Feel free to change any of the wcet and periods to make it better for
  different CPU's. The mean and max execution time of each task can be seen in
  the JET display of the program. These numbers were tested on a P3 866 MHz
  machine.

- The system will not overload with 145 hard balls, which reaches the
  maximum number of processes that shark is able to handle. In order to test
  overload, the periods of balls, or the radius of the balls could be increased
  to increase their utilization.

- The ball and paddle tasks were given the same periods because to ensure that
  our speeds were constant across both tasks and to avoid discrepencies between
  the positions of the objects. The ai task was also given a period of 40 ms
  because it is pointless for it to update the target position of paddle2 more
  than once during a paddle2 cycle.

- Decreasing the periods of the paddles would make the movement of the user
  paddle more responsive, if desired, because updates are only drawn to the
  screen currently every 40 ms.

PADDLE 2 CONTROL:
- We used the proportional and derivative control model, so the force applied
  to the paddle at a given point is:
    F = kp(distance to target position) - kd(velocity)
  Force is divided by mass to give the paddle acceleration.
- The default values shown give some oscillation around the target position.
  Increasing kd will decrease the oscillations. Increasing both will make the
  computer harder.
- Kp and Kd are limited to values >= 0, mass is limited to values > 0.

SYNCHRONIZATION:
- One mutex was used around all calls to the grx functions that write to the
  screen.
- Another mutex was used for all accesses to the linked list of ball positions
  that was used for the p2ai task to determine which ball will hit next.
- Both mutexes use priority inheritance to minimize blocking time of higher
  priority tasks.

POSSIBLE NEXT STEPS:
- Balls currently bounce from their current position once they determine that
  their next position will be out of bounds. This could be changed so that the
  balls determine the distance to the wall, subtract that distance from their
  speed, reflect the path around the wall, and end up at the new position.
- Updating of positions for the balls and the paddles is done based cycles
  (once per cycle, the ball moves BALL_SPEED pixels). In a large time
  interval, the average speed is equal to this, but the speed in a small
  period of a ball might be greater or smaller than BALL_SPEED. This could be 
  changed so that the exact time is used and during each cycle, the ball might
  move slightly more or less than BALL_SPEED pixels. In the current demo, the
  updates happen to fast for the user to notice the difference.
- If balls move too fast, they may skip over a paddle and score a point even though the
  paddle is in the way, but at this point, the balls are too fast for the user
  to respond to them, so the game is not playable.
- Main does keyboard reading in the current program. This could be changed to
  using keyboard hooks and having a seperate function for each key. I tried
  this implementation, but the numeric keys did not function properly, so I
  restored all key reading to main. I do not know if there would be a
  performance increase by changing them, but the switch statement would be
  removed, which would make it at least slightly more responsive.