[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