[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep108.txt,1.6,1.7

Kevin Klues klueska at users.sourceforge.net
Fri Jan 5 10:53:45 PST 2007


Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv11880/txt

Modified Files:
	tep108.txt 
Log Message:
Update of tep to finalized version....



Index: tep108.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep108.txt,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** tep108.txt	12 Dec 2006 18:22:54 -0000	1.6
--- tep108.txt	5 Jan 2007 18:53:43 -0000	1.7
***************
*** 59,63 ****
  - You have no control over the timing of a sequence of operations. One
    example of when this can be a problem is timing-sensitive use of an 
!   A/D converter.
  
  - If a hardware resource supports reservation, you cannot express this
--- 59,64 ----
  - You have no control over the timing of a sequence of operations. One
    example of when this can be a problem is timing-sensitive use of an 
!   A/D converter.  You need a way to pre-reserve the use of the ADC so
!   that its operations can be run at the exact moment they are desired.
  
  - If a hardware resource supports reservation, you cannot express this
***************
*** 178,193 ****
  provide information useful for a variety of other services, such as
  power management. An arbiter MUST provide a parameterized Resource
! interface as well as an instance of the ArbiterInfo interface. An
! arbiter SHOULD also provide a parameterized ResourceRequested interface 
! and use a parameterized ResourceConfigure interface.  It MAY also provide 
! an instance of the ResourceController interface or any additional
! interfaces specific to the particular arbitration policy being 
! implemented.
  
  3.1 Resource
  -------------------------------
  
! Clients of a shared resource arbiter request access 
! using the Resource interface::
  
    interface Resource {
--- 179,209 ----
  provide information useful for a variety of other services, such as
  power management. An arbiter MUST provide a parameterized Resource
! interface as well as an instance of the ArbiterInfo interface. The Resource
! interface is instantiated by different clients wanting to gain access to a 
! resource.  The ArbiterInfo interface is used by components that wish to 
! retrieve global information about the status of a resource (i.e. if it is in 
! use, who is using it, etc.).  An arbiter SHOULD also provide a parameterized 
! ResourceRequested interface and use a parameterized ResourceConfigure interface. 
! It MAY also provide an instance of the ResourceDefaultOwner interface or 
! any additional interfaces specific to the particular arbitration policy 
! being implemented.  Each of these interfaces is explained in greater detail below::
  
+  Resource     ArbiterInfo ResourceRequested     ResourceDefaultOwner 
+     |                |         |                        |
+     |                |         |                        |
+     |               \|/       \|/                       |
+     |             \---------------/                     |
+     |--------------|   Arbiter   |----------------------|
+                   /---------------\
+                           |
+                           |      
+                          \|/
+                    ResourceConfigure
+                                 
  3.1 Resource
  -------------------------------
  
! Clients of an arbiter request access 
! to a shared resource using the Resource interface::
  
    interface Resource {
***************
*** 210,215 ****
  requests before receiving a granted event, an EBUSY value is returned, 
  and the request is not queued.  Using this policy, clients are not able to 
! hog the resource queue by making multiple requests, but they may still be
! able to hog the resource if they do not release it in a timely manner.
  
  Clients can also request the use of a resource through the 
--- 226,232 ----
  requests before receiving a granted event, an EBUSY value is returned, 
  and the request is not queued.  Using this policy, clients are not able to 
! monolopize the resource queue by making multiple requests, but they may still be
! able to monopolize the use of the resource if they do not release it in a 
! timely manner.
  
  Clients can also request the use of a resource through the 
***************
*** 228,231 ****
--- 245,267 ----
  should be made to commands provided by that resource.
  
+ The diagram below shows how a simple shared resource can be 
+ built from a dedicated resource by using just the Resource interface 
+ provided by an arbiter.
+ 
+            /|\                    /|\
+             |                      |
+             | Data Interface       | Resource
+             |                      |  
+   --------------------------------------------
+   |               Shared Resource            |
+   --------------------------------------------
+            /|\                    /|\
+             |                      |
+             | Data Interface       | Resource
+             |                      |
+   ----------------------      ----------------
+   | Dedicated Resource |      |    Arbiter   |
+   ----------------------      ----------------
+ 
  An arbiter MUST provide exactly one parameterized Resource interface,
  where the parameter is a client ID, following the Service
***************
*** 237,241 ****
  SomeNameP are visible in the referring component.
  
! Please refer to Appendix B for an example of how to wrap this component
  inside a generic configuration. Wrapping the component in this way ensures that
  each Resource client is given a unique client ID, with the added
--- 273,277 ----
  SomeNameP are visible in the referring component.
  
! Please refer to Appendix B for an example of how to wrap a component of this type
  inside a generic configuration. Wrapping the component in this way ensures that
  each Resource client is given a unique client ID, with the added
***************
*** 243,250 ****
  refer to the same client ID.
  
! For a complete example of how the I2C resource might be abstracted 
! according to this pattern, please refer to Appendix B.  For further 
! examples please refer to the various chip implementations in the 
! tinyos-2.x source tree under tinyos-2.x/chips/
  
  3.2 ArbiterInfo
--- 279,285 ----
  refer to the same client ID.
  
! Appendix B also provides a complete example of how an I2C resource might be 
! abstracted according to this pattern.  For further examples see the various 
! chip implementations in the tinyos-2.x source tree under tinyos-2.x/chips/
  
  3.2 ArbiterInfo
***************
*** 257,267 ****
    interface ArbiterInfo {
      async command bool inUse();
!     async command uint8_t userId();
    }
  
! The ArbiterInfo interface has a variety of uses. For example, the resource 
! implementation can use it to refuse requests from clients that do not
! currently have access.  For an example of how this interface is used
! in this fashion please refer to Appendix B.
  
  3.3 ResourceRequested
--- 292,327 ----
    interface ArbiterInfo {
      async command bool inUse();
!     async command uint8_t clientId();
    }
+   
+ In contrast to the parameterized Resource interface provided by an arbiter, 
+ only a single ArbiterInfo interface is provided.  Its purpose is 
+ to allow one to find out:
  
! - Whether the resource for which it is arbitrating use is currently in use or not
! - Which client is using it.  
! 
! One can view ArbiterInfo as an interface for obtaining global information about  
! the use of a resource, while Resource can be viewed as an interface for obtaining 
! local access to that resource.
! 
! The primary use of the ArbiterInfo interface is to allow a shared resource to reject 
! any calls made through its data interface by clients that do not currently have access to 
! it.  For an example of how this interface is used in this fashion refer to Appendix B.::
! 
!            /|\                        /|\
!             |                          |
!             | Data Interface           | Resource
!             |                          |  
!   -----------------------------------------------------------
!   |                     Shared Resource                     |
!   -----------------------------------------------------------
!            /|\                    /|\         /|\
!             |                      |           |
!             | Data Interface       | Resource  | ArbiterInfo
!             |                      |           |
!   ----------------------      -------------------------------
!   | Dedicated Resource |      |           Arbiter           |
!   ----------------------      -------------------------------
  
  3.3 ResourceRequested
***************
*** 287,301 ****
  ResourceRequested interface should be coupled with the client id of the Resource 
  interface to ensure that all events are signaled to the proper clients.  Please 
! refer to Appendix B for an example of how this interface might be used.
  
  3.4 ResourceConfigure
  -------------------------------
  
! The ResourceConfigure interface provides a mechanism for clients
! that need to use a resource with different configurations to do so.
! Rather than forcing a client to reconfigure the resource itself, the
! component representing a client can wire to an arbiter's
! ResourceConfigure interface, which is called just before granting the
! client the resource:: 
  
    interface ResourceConfigure {
--- 347,379 ----
  ResourceRequested interface should be coupled with the client id of the Resource 
  interface to ensure that all events are signaled to the proper clients.  Please 
! refer to Appendix B for an example of how this interface might be used.::
! 
!            /|\                        /|\                   /|\
!             |                          |                     |
!             | Data Interface           | Resource            | ResourceRequested
!             |                          |                     |
!   --------------------------------------------------------------------------------
!   |                              Shared Resource                                 |
!   --------------------------------------------------------------------------------
!            /|\                    /|\         /|\            /|\
!             |                      |           |              |
!             | Data Interface       | Resource  | ArbiterInfo  | ResourceRequested
!             |                      |           |              |
!   ----------------------      ----------------------------------------------------
!   | Dedicated Resource |      |                     Arbiter                      |
!   ----------------------      ----------------------------------------------------
  
  3.4 ResourceConfigure
  -------------------------------
  
! The existence of the ResourceConfigure interface allows a resource to be 
! automatically configured just before a client is granted access to it.
! Components providing the ResourceConfigure interface use the interfaces
! provided by an underlying dedicated resource to configure it into one
! of its desired modes of operation.  A cleint then wires its shared resource 
! abstraction to the component implementing the desired configuration.  The 
! configure command is called immediataely before the client is granted access 
! to the resource, and the unconfigure command is called just before fully 
! releasing it.::
  
    interface ResourceConfigure {
***************
*** 303,306 ****
--- 381,400 ----
      async command void unconfigure();
    }
+   
+ :: 
+ 
+     ResourceConfigure       ResourceConfigure      ResourceConfigure
+            |                       |                     /|\
+            |                       |                      |
+           \|/                     \|/                     |                
+   -------------------     -------------------    ------------------- 
+   | Configuration 1 |     | Configuration 2 |    | Shared Resource |
+   -------------------     -------------------    -------------------
+            |                       |                     /|\
+            |   Control Interface   |                      | ResourceConfigure
+           \|/                     \|/                     |
+         ------------------------------               -----------                 
+         |     Dedicated Resource     |               | Arbiter |
+         ------------------------------               -----------
  
  The arbiter SHOULD use a parameterized ResourceConfigure interface, with 
***************
*** 316,342 ****
  made again.
  
! Using the parameterized ResourceConfigure interface that calls out rather than 
! additional commands being put into the Resource interface
! simplifies code reuse. Introducing these new commands into the
! Resource interface could lead to a large number of clients all
! including redundant configuration code, while using the call out
! approach provided by the parameterized interface will only have one
! instance of the code. 
  
! For an example of how the three different modes of the Msp430 Usart
! component can take advantage of this ResourceConfigure interface 
! please refer to Appendix B as well as section 4 on the use of 
  cross-component reservation.
  
! 3.5 ResourceController
  -------------------------------
  
  The normal Resource interface is for use by clients that all share the resource 
! in an equal fashion. The ResourceController interface is for use by a single 
  client that needs to be given control of the resource whenever no one else is 
! using it. An arbiter MAY provide a single instance of the ResourceController 
! interface.::
  
!   interface ResourceController {
      async event void granted();
      async command error_t release();
--- 410,435 ----
  made again.
  
! The commands included in this interface could have been made part of the standard
! Resource interface (and changed into callback events), but at a higher cost than 
! keeping them separate. Introducing these new commands into the Resource interface 
! would have lead to a large number of clients all including redundant configuration 
! code, while using the call out approach to a separate component ensures that we 
! only have a single instance of the code. 
  
! For an example of how configurations for the three different modes of the 
! Msp430 Usart component can take advantage of the ResourceConfigure 
! interface refer to Appendix B as well as section 4 on the use of 
  cross-component reservation.
  
! 3.5 ResourceDefaultOwner
  -------------------------------
  
  The normal Resource interface is for use by clients that all share the resource 
! in an equal fashion. The ResourceDefaultOwner interface is for use by a single 
  client that needs to be given control of the resource whenever no one else is 
! using it. An arbiter MAY provide a single instance of the ResourceDefaultOwner 
! interface. It MUST NOT provide more than one.::
  
!   interface ResourceDefaultOwner {
      async event void granted();
      async command error_t release();
***************
*** 346,353 ****
    }
    
! The Arbiter MUST guarantee that the user of the ResourceController interface is
  made the owner of the resource before the boot initialization sequence is 
  completed.  When a normal resource client makes a request for the resource, the 
! ResourceController will receive either a requested() or an immediateRequested() 
  event depending on how the request was made.  It must then decide if and when to 
  release it.  Once released, all clients that have pending requests will be 
--- 439,446 ----
    }
    
! The Arbiter MUST guarantee that the client of the ResourceDefaulrClient interface is
  made the owner of the resource before the boot initialization sequence is 
  completed.  When a normal resource client makes a request for the resource, the 
! ResourceDefaultOwner will receive either a requested() or an immediateRequested() 
  event depending on how the request was made.  It must then decide if and when to 
  release it.  Once released, all clients that have pending requests will be 
***************
*** 355,392 ****
  the arbiter in use.  Once all pending requests have been granted (including 
  those that came in while other clients had access to the resource), the 
! ResourceController is automatically given control of the resource, receiving its 
! granted() event in the process.  The ResourceController interface also contains 
  the same isOwner() command as the normal Resource interface, and the semantics 
  of its use are exactly the same.
  
! Although the ResourceController interface looks similar to a combination of the 
  normal Resource interface and the ResourceRequested interface, its intended use 
! is quite different.  The ResourceController interface should only be used by 
  clients that wish to have access to a resource only when no other clients are 
! using it.  They do not actively seek out access to the resource, but rather use 
  it to perform operations when it would otherwise simply be idle.  
- 
- Combining the use of the Resource and ResourceRequested interfaces could be made 
- to operate in a similar manner as the ResourceController interface, except that 
- there is no way to tell a client with these interfaces that a resource has gone 
- completely idle.  Each client must actively request the use of the resource and 
- be granted that resource in the order determined by the queuing policy of its 
- arbiter.  With the ResourceController interface, there is no active request of 
- the resource.  The arbiter simply signals the granted event to the 
- ResourceController whenever there are no more pending requests and the last 
- client that owned the resource releases it.
    
! The primary motivation behind the definition of the ResourceController 
! interface was to allow for an easy integration of the power management
! policy used by the resource with the arbitration of the resource
! itself.  Arbiters that want to allow a resource to be controlled by a particular power management policy can provide the ResourceController interface 
! for use by a component that implements that policy. The power management component will receive the granted() event whenever the resource has gone idle, 
! and will then proceed in powering it down.  When another
! client requests the resource, the power manager will be notified through
! either the requested() or immediateRequested() events as appropriate.  It
! can then power up the resource and release it once the power up has completed.
! Note that if power up is a split-phase operation (takes a while), then calls 
! by clients to immediateRequest() when in the powered down state will not return 
! SUCCESS. Please see the TEP on the Power Management of Non-Virtualized devices
  ([4]_) for more details.
  
--- 448,477 ----
  the arbiter in use.  Once all pending requests have been granted (including 
  those that came in while other clients had access to the resource), the 
! ResourceDefaultOwner is automatically given control of the resource, receiving its 
! granted() event in the process.  The ResourceDefaultOwner interface also contains 
  the same isOwner() command as the normal Resource interface, and the semantics 
  of its use are exactly the same.
  
! Although the ResourceDefaultOwner interface looks similar to a combination of the 
  normal Resource interface and the ResourceRequested interface, its intended use 
! is quite different.  The ResourceDefaultOwner interface should only be used by 
  clients that wish to have access to a resource only when no other clients are 
! using it.  They do not actively seek access to the resource, but rather use 
  it to perform operations when it would otherwise simply be idle.  
    
! The primary motivation behind the definition of the ResourceDefaultOwner 
! interface is to allow for an easy integration of power management
! for a resource with its arbitration policy.  Arbiters that want to allow 
! a resource to be controlled by a particular power management policy can 
! provide the ResourceDefaultOwner interface for use by a component that 
! implements that policy. The power management component will receive the 
! granted() event whenever the resource has gone idle, and will proceed in
! powering it down.  When another client requests the resource, the power 
! manager will be notified through either the requested() or 
! immediateRequested() events as appropriate.  It can then power up the resource 
! and release it once the power up has completed.  Note that if power up is 
! a split-phase operation (takes a while), then calls by clients to 
! immediateRequest() when in the powered down state will return 
! FAIL. Please see the TEP on the Power Management of Non-Virtualized devices
  ([4]_) for more details.
  
***************
*** 444,457 ****
  Msp430Spi0P component.  This is where the mapping of the two
  different ids begins.  As well as *providing* a parameterized
! Resource interface, the Msp430Spi0P component also *uses* a
! parameterized Resource interface. Whenever a client makes a call
! through the provided Resource interface with id CLIENT_ID, an
! underlying call to the used Resource interface with the same id is
! implicitly made.  By wiring the used Resource interface with id
! CLIENT_ID to the instance of the Resource interface provided by the
! instantiation of the Msp430Usart0C component, the mapping is complete.
! Any calls to the Resource interface provided by a new instantiation of
! the Msp430Spi0C component will now be made through a unique Resource
! interface on the underlying  Msp430Usart0C component.
  
  This level of indirection is necessary because it may not always be
--- 529,542 ----
  Msp430Spi0P component.  This is where the mapping of the two
  different ids begins.  As well as *providing* a parameterized
! Resource interface (Msp430Spi0P.Resource), the Msp430Spi0P component 
! also *uses* a parameterized Resource interface (Msp430Spi0P.UsartResource). 
! Whenever a client makes a call through the provided Resource interface 
! with id CLIENT_ID, an underlying call to the Msp430Spi0P.Resource interface 
! with the same id is implicitly made.  By then wiring the Msp430Spi0P.UsartResource 
! interface with id CLIENT_ID to an instance of the Resource interface 
! provided by the instantiation of the Msp430Usart0C component, the mapping 
! is complete. Any calls to the Resource interface provided by a new 
! instantiation of the Msp430Spi0C component will now be made through a 
! unique Resource interface on the underlying  Msp430Usart0C component.
  
  This level of indirection is necessary because it may not always be
***************
*** 495,499 ****
      provides interface Resource[uint8_t id];
      provides interface ResourceRequested[uint8_t id];
!     provides interface ResourceController;
      provides interface ArbiterInfo;
      uses interface ResourceConfigure[uint8_t id];
--- 580,584 ----
      provides interface Resource[uint8_t id];
      provides interface ResourceRequested[uint8_t id];
!     provides interface ResourceDefaultOwner;
      provides interface ArbiterInfo;
      uses interface ResourceConfigure[uint8_t id];
***************
*** 502,506 ****
  The "Simple" arbiters are intended for use by resources that 
  do not require the additional overhead incurred by providing the
! ResourceController interface.
  
  For many situations, changing an arbitration policy requires nothing
--- 587,591 ----
  The "Simple" arbiters are intended for use by resources that 
  do not require the additional overhead incurred by providing the
! ResourceDefaultOwner interface.
  
  For many situations, changing an arbitration policy requires nothing
***************
*** 548,552 ****
    }
  
! This generic configuration can instantiated by a resource in order
  to grant requests made by its clients in an FCFS fashion.
    
--- 633,637 ----
    }
  
! This generic configuration can be instantiated by a resource in order
  to grant requests made by its clients in an FCFS fashion.
    
***************
*** 565,568 ****
--- 650,664 ----
    - RoundRobinArbiterC 
    
+ Keep in mind that neither the implementation of an arbiter nor its 
+ queuing policy can be used to explicitly restrict access to an 
+ underlying shared resource.  The arbiter simply provides a standardized
+ way of managing client ids so that shared resources don't have to duplicate 
+ this functionality themselves every time they are implemented.  In order to
+ actually restrict clients from using a resource without first requesting it,
+ a shared resource must use the functionality provided by the ArbiterInfo interface
+ to perform runtime checks on the current owner of a resource.  Please refer 
+ to the section on the ArbiterInfo interface in Appendix B for more information
+ on how such runtime checks can be performed. 
+   
  6. Author's Address
  ====================================================================
***************
*** 729,733 ****
    #endif
    
! This service would then be made available to a user through
  the generic configuration seen below::
  
--- 825,829 ----
    #endif
    
! This service would then be made available to a client through
  the generic configuration seen below::
  
***************
*** 800,804 ****
         
    async command error_t Msp430Adc12SingleChannel.getSingleData[uint8_t id]() {
!     if (call ADCArbiterInfo.userId() == id){
        configureChannel()
        // Start getting data
--- 896,900 ----
         
    async command error_t Msp430Adc12SingleChannel.getSingleData[uint8_t id]() {
!     if (call ADCArbiterInfo.clientId() == id){
        configureChannel()
        // Start getting data
***************
*** 808,812 ****
           
    async command error_t Msp430Adc12FastSingleChannel.configure[uint8_t id]() {
!     if (call ADCArbiterInfo.userId() == id){
        clientID = id
        configureChannel()
--- 904,908 ----
           
    async command error_t Msp430Adc12FastSingleChannel.configure[uint8_t id]() {
!     if (call ADCArbiterInfo.clientId() == id){
        clientID = id
        configureChannel()
***************
*** 853,857 ****
    }  
           
! Since these are generic components, users simply need to instantiate them
  in order to get access to a single Resource interface that is already
  properly coupled with a Msp430Adc12SingleChannel or Msp430Adc12FastSingleChannel
--- 949,953 ----
    }  
           
! Since these are generic components, clients simply need to instantiate them
  in order to get access to a single Resource interface that is already
  properly coupled with a Msp430Adc12SingleChannel or Msp430Adc12FastSingleChannel



More information about the Tinyos-2-commits mailing list