[Tinyos-2-commits] CVS: tinyos-2.x/apps/tutorials/SharedResourceDemo Makefile, NONE, 1.1 README.txt, NONE, 1.1 ResourceOperations.nc, NONE, 1.1 ResourceP.nc, NONE, 1.1 SharedResourceC.nc, NONE, 1.1 SharedResourceDemoAppC.nc, NONE, 1.1 SharedResourceDemoC.nc, NONE, 1.1 SharedResourceImplP.nc, NONE, 1.1 SharedResourceP.nc, NONE, 1.1

Fri Jul 13 16:43:19 PDT 2007

Update of /cvsroot/tinyos/tinyos-2.x/apps/tutorials/SharedResourceDemo
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv23604/apps/tutorials/SharedResourceDemo

Added Files:
	Makefile README.txt ResourceOperations.nc ResourceP.nc 
	SharedResourceC.nc SharedResourceDemoAppC.nc 
	SharedResourceDemoC.nc SharedResourceImplP.nc 
	SharedResourceP.nc 
Log Message:
Moved the apps/tests/TestSharedResources application into the tutorials directory and gave it a new name to fit more appropriately in there.  Also modified the tutorial itself to reflect these changes and added / deleted dsome obsolete text from it.

--- NEW FILE: Makefile ---
COMPONENT=SharedResourceDemoAppC
include $(MAKERULES)

--- NEW FILE: README.txt ---
README for SharedResourceDemo
Author/Contact: tinyos-help at millennium.berkeley.edu
@author Kevin Klues <klues at tkn.tu-berlin.de>

Description:

This application is used to test the use of Shared Resources.  
Three Resource users are created and all three request
control of the resource before any one of them is granted it.
Once the first user is granted control of the resource, it performs
some operation on it.  Once this operation has completed, a timer
is set to allow this user to have control of it for a specific
amount of time.  Once this timer expires, the resource is released
and then immediately requested again.  Upon releasing the resource
control will be granted to the next user that has requested it in 
round robin order.  Initial requests are made by the three resource 
users in the following order.
  -- Resource 0
  -- Resource 2
  -- Resource 1
It is expected then that using a round robin policy, control of the
resource will be granted in the order of 0,1,2 and the Leds
corresponding to each resource will flash whenever this occurs.
  -- Led 0 -> Resource 0
  -- Led 1 -> Resource 1
  -- Led 2 -> Resource 2

Tools:

None.

Known bugs/limitations:

None.

--- NEW FILE: ResourceOperations.nc ---
/*
 * "Copyright (c) 2006 Washington University in St. Louis.
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 *
 * IN NO EVENT SHALL WASHINGTON UNIVERSITY IN ST. LOUIS BE LIABLE TO ANY PARTY
 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
 * OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF WASHINGTON
 * UNIVERSITY IN ST. LOUIS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * WASHINGTON UNIVERSITY IN ST. LOUIS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND WASHINGTON UNIVERSITY IN ST. LOUIS HAS NO
 * OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
 * MODIFICATIONS."
 */

/**
 * An EXAMPLE of an interface for performing operations on a resource.
 * In this test application it is provided by the dedicated ResourceP component
 * and passed through all of the proper components before being exposed by the
 * shared resource at the topmost level.
 *
 * @author Kevin Klues (klueska at cs.wustl.edu)
 * @version $Revision: 1.1 $
 * @date $Date: 2007/07/13 23:43:17 $
 */

interface ResourceOperations {
	command error_t operation();
	event void operationDone(error_t error);
}

--- NEW FILE: ResourceP.nc ---
/*
 * "Copyright (c) 2006 Washington University in St. Louis.
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 *
 * IN NO EVENT SHALL WASHINGTON UNIVERSITY IN ST. LOUIS BE LIABLE TO ANY PARTY
 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
 * OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF WASHINGTON
 * UNIVERSITY IN ST. LOUIS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * WASHINGTON UNIVERSITY IN ST. LOUIS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND WASHINGTON UNIVERSITY IN ST. LOUIS HAS NO
 * OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
 * MODIFICATIONS."
 */

/**
 * This is an example implementation of a dedicated resource.  
 * It provides the SplitControl interface for power management
 * of the resource and an EXAMPLE ResourceOperations interface
 * for performing operations on it.
 *
 * @author Kevin Klues (klueska at cs.wustl.edu)
 * @version $Revision: 1.1 $
 * @date $Date: 2007/07/13 23:43:17 $
 */

module ResourceP {
  provides {
    interface SplitControl;
    interface ResourceOperations;
  }
}
implementation {

  bool lock;

  task void startDone() {
  	lock = FALSE;
  	signal SplitControl.startDone(SUCCESS);
  }

  task void stopDone() {
  	signal SplitControl.stopDone(SUCCESS);
  }

  task void operationDone() {
  	lock = FALSE;
  	signal ResourceOperations.operationDone(SUCCESS);
  }

  command error_t SplitControl.start() {
  	post startDone();
  	return  SUCCESS;
  }

  command error_t SplitControl.stop() {
  	lock = TRUE;
  	post stopDone();
  	return  SUCCESS;
  }

  command error_t ResourceOperations.operation() {
  	if(lock == FALSE) {
      lock = TRUE;
  	  post operationDone();
  	  return SUCCESS;
  	}
  	return FAIL;
  }
}

--- NEW FILE: SharedResourceC.nc ---
/*
 * "Copyright (c) 2006 Washington University in St. Louis.
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 *
 * IN NO EVENT SHALL WASHINGTON UNIVERSITY IN ST. LOUIS BE LIABLE TO ANY PARTY
 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
 * OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF WASHINGTON
 * UNIVERSITY IN ST. LOUIS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * WASHINGTON UNIVERSITY IN ST. LOUIS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND WASHINGTON UNIVERSITY IN ST. LOUIS HAS NO
 * OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
 * MODIFICATIONS."
 */

/**
 * SharedResourceC is used to provide a generic configuration around 
 * the SharedResourceP component so that new instantiations of 
 * it provide a single set of interfaces that are all properly associated 
 * with one another rather than requiring the user to deal with the complexity
 * of doing this themselves.
 *
 * @author Kevin Klues (klueska at cs.wustl.edu)
 * @version $Revision: 1.1 $
 * @date $Date: 2007/07/13 23:43:17 $
 */

#define UQ_SHARED_RESOURCE   "Shared.Resource"
generic configuration SharedResourceC() {
	provides interface Resource;
	provides interface ResourceRequested;
	provides interface ResourceOperations;
    uses interface ResourceConfigure;
}
implementation {
  components SharedResourceP;

  enum {
    RESOURCE_ID = unique(UQ_SHARED_RESOURCE)
  };

  Resource = SharedResourceP.Resource[RESOURCE_ID];
  ResourceRequested = SharedResourceP.ResourceRequested[RESOURCE_ID];
  ResourceOperations = SharedResourceP.ResourceOperations[RESOURCE_ID];
  ResourceConfigure = SharedResourceP.ResourceConfigure[RESOURCE_ID];
}

--- NEW FILE: SharedResourceDemoAppC.nc ---
/*
 * "Copyright (c) 2006 Washington University in St. Louis.
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 *
 * IN NO EVENT SHALL WASHINGTON UNIVERSITY IN ST. LOUIS BE LIABLE TO ANY PARTY
 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
 * OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF WASHINGTON
 * UNIVERSITY IN ST. LOUIS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * WASHINGTON UNIVERSITY IN ST. LOUIS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND WASHINGTON UNIVERSITY IN ST. LOUIS HAS NO
 * OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
 * MODIFICATIONS."
 */

/**
 *
 * This application is used to test the use of Shared Resources. 
 * Three Resource users are created and all three request
 * control of the resource before any one of them is granted it.
 * Once the first user is granted control of the resource, it performs
 * some operation on it. Once this operation has completed, a timer
 * is set to allow this user to have control of it for a specific
 * amount of time. Once this timer expires, the resource is released
 * and then immediately requested again. Upon releasing the resource
 * control will be granted to the next user that has requested it in 
 * round robin order. Initial requests are made by the three resource 
 * users in the following order. 
 * <li> Resource 0
 * <li> Resource 2
 * <li> Resource 1
 * 
 * It is expected then that using a round robin policy, control of the
 * resource will be granted in the order of 0,1,2 and the Leds
 * corresponding to each resource will flash whenever this occurs. 
 * <li> Led 0 -> Resource 0
 * <li> Led 1 -> Resource 1
 * <li> Led 2 -> Resource 2
 * 
 * 
 * @author Kevin Klues (klueska at cs.wustl.edu)
 * @version $Revision: 1.1 $
 * @date $Date: 2007/07/13 23:43:17 $
 */

configuration SharedResourceDemoAppC{
}
implementation {
  components MainC,LedsC, SharedResourceDemoC as App,
  new TimerMilliC() as Timer0,
  new TimerMilliC() as Timer1,
  new TimerMilliC() as Timer2;
  App -> MainC.Boot;
  App.Leds -> LedsC;
  App.Timer0 -> Timer0;
  App.Timer1 -> Timer1;
  App.Timer2 -> Timer2;

  components
  new SharedResourceC() as Resource0,
  new SharedResourceC() as Resource1, 
  new SharedResourceC() as Resource2;
  App.Resource0 -> Resource0;
  App.Resource1 -> Resource1;
  App.Resource2 -> Resource2;
  App.ResourceOperations0 -> Resource0;
  App.ResourceOperations1 -> Resource1;
  App.ResourceOperations2 -> Resource2;
}

--- NEW FILE: SharedResourceDemoC.nc ---
/*
 * "Copyright (c) 2006 Washington University in St. Louis.
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 *
 * IN NO EVENT SHALL WASHINGTON UNIVERSITY IN ST. LOUIS BE LIABLE TO ANY PARTY
 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
 * OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF WASHINGTON
 * UNIVERSITY IN ST. LOUIS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * WASHINGTON UNIVERSITY IN ST. LOUIS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND WASHINGTON UNIVERSITY IN ST. LOUIS HAS NO
 * OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
 * MODIFICATIONS."
 */

#include "Timer.h"

/**
 *
 * This application is used to test the use of Shared Resources. 
 * Three Resource users are created and all three request
 * control of the resource before any one of them is granted it.
 * Once the first user is granted control of the resource, it performs
 * some operation on it. Once this operation has completed, a timer
 * is set to allow this user to have control of it for a specific
 * amount of time. Once this timer expires, the resource is released
 * and then immediately requested again. Upon releasing the resource
 * control will be granted to the next user that has requested it in 
 * round robin order. Initial requests are made by the three resource 
 * users in the following order. 
 * <li> Resource 0
 * <li> Resource 2
 * <li> Resource 1
 * 
 * It is expected then that using a round robin policy, control of the
 * resource will be granted in the order of 0,1,2 and the Leds
 * corresponding to each resource will flash whenever this occurs. 
 * <li> Led 0 -> Resource 0
 * <li> Led 1 -> Resource 1
 * <li> Led 2 -> Resource 2
 * 
 * 
 * @author Kevin Klues (klueska at cs.wustl.edu)
 * @version $Revision: 1.1 $
 * @date $Date: 2007/07/13 23:43:17 $
 */

module SharedResourceDemoC {
  uses {
    interface Boot;  
    interface Leds;
    interface Timer<TMilli> as Timer0;
    interface Timer<TMilli> as Timer1;
    interface Timer<TMilli> as Timer2;

    interface Resource as Resource0;
    interface ResourceOperations as ResourceOperations0;

    interface Resource as Resource1;
    interface ResourceOperations as ResourceOperations1;

    interface Resource as Resource2;
    interface ResourceOperations as ResourceOperations2;
  }
}
implementation {

  #define HOLD_PERIOD 250

  //All resources try to gain access
  event void Boot.booted() {
    call Resource0.request();
    call Resource2.request();
    call Resource1.request();
  }

  //If granted the resource, run some operation  
  event void Resource0.granted() {
  	call ResourceOperations0.operation();   
  }  
  event void Resource1.granted() {
  	call ResourceOperations1.operation();
  }  
  event void Resource2.granted() {
  	call ResourceOperations2.operation();
  }  

  //When the operation completes, flash the LED and hold the resource for a while
  event void ResourceOperations0.operationDone(error_t error) {
  	call Timer0.startOneShot(HOLD_PERIOD);  
    call Leds.led0Toggle();
  }
  event void ResourceOperations1.operationDone(error_t error) {
    call Timer1.startOneShot(HOLD_PERIOD);  
    call Leds.led1Toggle();
  }
  event void ResourceOperations2.operationDone(error_t error) {
    call Timer2.startOneShot(HOLD_PERIOD);  
    call Leds.led2Toggle();
  }

  //After the hold period release the resource and request it again
  event void Timer0.fired() {
    call Resource0.release();
    call Resource0.request();
  }
  event void Timer1.fired() {
    call Resource1.release();
    call Resource1.request();
  }
  event void Timer2.fired() {
    call Resource2.release();
    call Resource2.request();
  }
}

--- NEW FILE: SharedResourceImplP.nc ---
/*
 * "Copyright (c) 2006 Washington University in St. Louis.
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 *
 * IN NO EVENT SHALL WASHINGTON UNIVERSITY IN ST. LOUIS BE LIABLE TO ANY PARTY
 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
 * OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF WASHINGTON
 * UNIVERSITY IN ST. LOUIS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * WASHINGTON UNIVERSITY IN ST. LOUIS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND WASHINGTON UNIVERSITY IN ST. LOUIS HAS NO
 * OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
 * MODIFICATIONS."
 */

/**
 * The SharedResourceImplP component is used to wrap all of the operations
 * from a dedicated resource so that access to them is protected when 
 * it is used as a shared resource.  It uses the ArbiterInfo interface 
 * provided by an Arbiter to accomplish this.
 *
 * @author Kevin Klues (klueska at cs.wustl.edu)
 * @version $Revision: 1.1 $
 * @date $Date: 2007/07/13 23:43:17 $
 */

module SharedResourceImplP {
  provides {
    interface ResourceOperations as SharedResourceOperations[uint8_t id];
  }
  uses {
  	interface ArbiterInfo;
  	interface ResourceOperations;
  }
}
implementation {
  uint8_t current_id = 0xFF;

  event void ResourceOperations.operationDone(error_t error) {
  	signal SharedResourceOperations.operationDone[current_id](error);
  }

  command error_t SharedResourceOperations.operation[uint8_t id]() {
  	if(call ArbiterInfo.userId() == id && call ResourceOperations.operation() == SUCCESS) {
      current_id = id;
  	  return SUCCESS;
  	}
  	return FAIL;
  }

  default event void SharedResourceOperations.operationDone[uint8_t id](error_t error) {}
}

--- NEW FILE: SharedResourceP.nc ---
/*
 * "Copyright (c) 2006 Washington University in St. Louis.
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 *
 * IN NO EVENT SHALL WASHINGTON UNIVERSITY IN ST. LOUIS BE LIABLE TO ANY PARTY
 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
 * OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF WASHINGTON
 * UNIVERSITY IN ST. LOUIS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * WASHINGTON UNIVERSITY IN ST. LOUIS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND WASHINGTON UNIVERSITY IN ST. LOUIS HAS NO
 * OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
 * MODIFICATIONS."
 */

/**
 * The SharedResourceP component is used to create a shared resource
 * out of a dedicated one.
 *
 * @author Kevin Klues (klueska at cs.wustl.edu)
 * @version $Revision: 1.1 $
 * @date $Date: 2007/07/13 23:43:17 $
 */

#define UQ_SHARED_RESOURCE   "Shared.Resource"
configuration SharedResourceP {
	provides interface Resource[uint8_t id];
	provides interface ResourceRequested[uint8_t id];
	provides interface ResourceOperations[uint8_t id];
	uses interface ResourceConfigure[uint8_t id];
}
implementation {
  components new RoundRobinArbiterC(UQ_SHARED_RESOURCE) as Arbiter;
  components new SplitControlPowerManagerC() as PowerManager;
  components ResourceP;
  components SharedResourceImplP;

  ResourceOperations = SharedResourceImplP;
  Resource = Arbiter;
  ResourceRequested = Arbiter;
  ResourceConfigure = Arbiter;
  SharedResourceImplP.ArbiterInfo -> Arbiter;
  PowerManager.ResourceDefaultOwner -> Arbiter;

  PowerManager.SplitControl -> ResourceP;
  SharedResourceImplP.ResourceOperations -> ResourceP;
}