Changeset 8fcafdd5 in rtems for doc


Ignore:
Timestamp:
May 21, 2014, 8:33:43 AM (6 years ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
4.11, master
Children:
5fd4e35f
Parents:
9f058fb
git-author:
Sebastian Huber <sebastian.huber@…> (05/21/14 08:33:43)
git-committer:
Sebastian Huber <sebastian.huber@…> (05/28/14 08:50:41)
Message:

score: Multiprocessor Resource Sharing Protocol

Add basic support for the Multiprocessor Resource Sharing Protocol
(MrsP).

The Multiprocessor Resource Sharing Protocol (MrsP) is defined in A.
Burns and A.J. Wellings, A Schedulability Compatible Multiprocessor
Resource Sharing Protocol - MrsP, Proceedings of the 25th Euromicro
Conference on Real-Time Systems (ECRTS 2013), July 2013. It is a
generalization of the Priority Ceiling Protocol to SMP systems. Each
MrsP semaphore uses a ceiling priority per scheduler instance. These
ceiling priorities can be specified with rtems_semaphore_set_priority().
A task obtaining or owning a MrsP semaphore will execute with the
ceiling priority for its scheduler instance as specified by the MrsP
semaphore object. Tasks waiting to get ownership of a MrsP semaphore
will not relinquish the processor voluntarily. In case the owner of a
MrsP semaphore gets preempted it can ask all tasks waiting for this
semaphore to help out and temporarily borrow the right to execute on one
of their assigned processors.

The help out feature is not implemented with this patch.

Location:
doc/user
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • doc/user/Makefile.am

    r9f058fb r8fcafdd5  
    9797
    9898barrier.texi: barrier.t
    99         $(BMENU2) -p "Semaphore Manager SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore" \
     99        $(BMENU2) -p "Semaphore Manager SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore" \
    100100            -u "Top" \
    101101            -n "Message Manager" < $< > $@
  • doc/user/conf.t

    r9f058fb r8fcafdd5  
    685685@subheading NOTES:
    686686This object class can be configured in unlimited allocation mode.
     687
     688@c
     689@c === CONFIGURE_MAXIMUM_MRSP_SEMAPHORES ===
     690@c
     691@subsection Specify Maximum Classic API Semaphores usable with MrsP
     692
     693@findex CONFIGURE_MAXIMUM_MRSP_SEMAPHORES
     694
     695@table @b
     696@item CONSTANT:
     697@code{CONFIGURE_MAXIMUM_MRSP_SEMAPHORES}
     698
     699@item DATA TYPE:
     700Unsigned integer (@code{uint32_t}).
     701
     702@item RANGE:
     703Zero or positive.
     704
     705@item DEFAULT VALUE:
     706The default value is 0.
     707
     708@end table
     709
     710@subheading DESCRIPTION:
     711@code{CONFIGURE_MAXIMUM_MRSP_SEMAPHORES} is the
     712maximum number of Classic API Semaphores using the Multiprocessor Resource
     713Sharing Protocol (MrsP) that can be concurrently active.
     714
     715@subheading NOTES:
     716This configuration option is only used on SMP configurations.  On uni-processor
     717configurations the Priority Ceiling Protocol is used for MrsP semaphores and
     718thus no extra memory is necessary.
    687719
    688720@c
  • doc/user/sem.t

    r9f058fb r8fcafdd5  
    2525@item @code{@value{DIRPREFIX}semaphore_release} - Release a semaphore
    2626@item @code{@value{DIRPREFIX}semaphore_flush} - Unblock all tasks waiting on a semaphore
     27@item @code{@value{DIRPREFIX}semaphore_set_priority} - Set priority by
     28scheduler for a semaphore
    2729@end itemize
    2830
     
    174176be restored to the normal value.
    175177
     178@subsection Multiprocessor Resource Sharing Protocol
     179
     180The Multiprocessor Resource Sharing Protocol (MrsP) is defined in @cite{A.
     181Burns and A.J.  Wellings, A Schedulability Compatible Multiprocessor Resource
     182Sharing Protocol - MrsP, Proceedings of the 25th Euromicro Conference on
     183Real-Time Systems (ECRTS 2013), July 2013}.  It is a generalization of the
     184Priority Ceiling Protocol to SMP systems.  Each MrsP semaphore uses a ceiling
     185priority per scheduler instance.  These ceiling priorities can be specified
     186with @code{rtems_semaphore_set_priority()}.  A task obtaining or owning a MrsP
     187semaphore will execute with the ceiling priority for its scheduler instance as
     188specified by the MrsP semaphore object.  Tasks waiting to get ownership of a
     189MrsP semaphore will not relinquish the processor voluntarily.  In case the
     190owner of a MrsP semaphore gets preempted it can ask all tasks waiting for this
     191semaphore to help out and temporarily borrow the right to execute on one of
     192their assigned processors.
     193
    176194@subsection Building a Semaphore Attribute Set
    177195
     
    199217@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
    200218
    201 @item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
    202 
    203219@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
    204220ceiling (default)
     221
     222@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
     223
     224@item @code{@value{RPREFIX}NO_MULTIPROCESSOR_RESOURCE_SHARING} - do not use
     225Multiprocessor Resource Sharing Protocol (default)
     226
     227@item @code{@value{RPREFIX}MULTIPROCESSOR_RESOURCE_SHARING} - use
     228Multiprocessor Resource Sharing Protocol
    205229
    206230@item @code{@value{RPREFIX}LOCAL} - local semaphore (default)
     
    490514@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
    491515
    492 @item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
    493 
    494516@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
    495517ceiling (default)
     518
     519@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
     520
     521@item @code{@value{RPREFIX}NO_MULTIPROCESSOR_RESOURCE_SHARING} - do not use
     522Multiprocessor Resource Sharing Protocol (default)
     523
     524@item @code{@value{RPREFIX}MULTIPROCESSOR_RESOURCE_SHARING} - use
     525Multiprocessor Resource Sharing Protocol
    496526
    497527@item @code{@value{RPREFIX}LOCAL} - local semaphore (default)
     
    512542The total number of global objects, including semaphores, is limited by
    513543the maximum_global_objects field in the Configuration Table.
     544
     545It is not allowed to create an initially locked MrsP semaphore and the
     546@code{@value{RPREFIX}INVALID_NUMBER} status code will be returned on SMP
     547configurations in this case.  This prevents lock order reversal problems with
     548the allocator mutex.
    514549
    515550@c
     
    736771this directive.
    737772
     773It is not allowed to obtain a MrsP semaphore more than once by one task at a
     774time (nested access) and the @code{@value{RPREFIX}UNSATISFIED} status code will
     775be returned on SMP configurations in this case.
     776
    738777@c
    739778@c
     
    832871@code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@*
    833872@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
     873@code{@value{RPREFIX}NOT_DEFINED} - operation not defined for the protocol of
     874the semaphore@*
    834875@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported for remote semaphores
    835876
     
    859900unblocked, and the proxy used to represent the task is reclaimed.
    860901
    861 
     902It is not allowed to flush a MrsP semaphore and the
     903@code{@value{RPREFIX}NOT_DEFINED} status code will be returned on SMP
     904configurations in this case.
     905
     906@c
     907@c
     908@c
     909@page
     910@subsection SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore
     911
     912@cindex set priority by scheduler for a semaphore
     913
     914@subheading CALLING SEQUENCE:
     915
     916@ifset is-C
     917@findex rtems_semaphore_set_priority
     918@example
     919rtems_status_code rtems_semaphore_set_priority(
     920  rtems_id             semaphore_id,
     921  rtems_id             scheduler_id,
     922  rtems_task_priority  new_priority,
     923  rtems_task_priority *old_priority
     924);
     925@end example
     926@end ifset
     927
     928@subheading DIRECTIVE STATUS CODES:
     929@code{@value{RPREFIX}SUCCESSFUL} - successful operation@*
     930@code{@value{RPREFIX}INVALID_ID} - invalid semaphore or scheduler id@*
     931@code{@value{RPREFIX}INVALID_ADDRESS} - @code{old_priority} is NULL@*
     932@code{@value{RPREFIX}INVALID_PRIORITY} - invalid new priority value@*
     933@code{@value{RPREFIX}NOT_DEFINED} - operation not defined for the protocol of
     934the semaphore@*
     935@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported for remote semaphores
     936
     937@subheading DESCRIPTION:
     938
     939This directive sets the priority value with respect to the specified scheduler
     940of a semaphore.
     941
     942The special priority value @code{RTEMS_CURRENT_PRIORITY} can be used to get the
     943current priority value without changing it.
     944
     945The interpretation of the priority value depends on the protocol of the
     946semaphore object.
     947
     948@itemize @bullet
     949@item The Multiprocessor Resource Sharing Protocol needs a ceiling priority per
     950scheduler instance.  This operation can be used to specify these priority
     951values.
     952@item For the Priority Ceiling Protocol the ceiling priority is used with this
     953operation.
     954@item For other protocols this operation is not defined.
     955@end itemize
     956
     957@subheading EXAMPLE:
     958
     959@example
     960@group
     961#include <assert.h>
     962#include <stdlib.h>
     963
     964#include <rtems.h>
     965
     966#define SCHED_A rtems_build_name(' ', ' ', ' ', 'A')
     967
     968#define SCHED_B rtems_build_name(' ', ' ', ' ', 'B')
     969
     970static void Init(rtems_task_argument arg)
     971@{
     972  rtems_status_code   sc;
     973  rtems_id            semaphore_id;
     974  rtems_id            scheduler_a_id;
     975  rtems_id            scheduler_b_id;
     976  rtems_task_priority prio;
     977
     978  /* Get the scheduler identifiers */
     979
     980  sc = rtems_scheduler_ident(SCHED_A, &scheduler_a_id);
     981  assert(sc == RTEMS_SUCCESSFUL);
     982
     983  sc = rtems_scheduler_ident(SCHED_B, &scheduler_b_id);
     984  assert(sc == RTEMS_SUCCESSFUL);
     985
     986  /* Create a MrsP semaphore object */
     987
     988  sc = rtems_semaphore_create(
     989    rtems_build_name('M', 'R', 'S', 'P'),
     990    1,
     991    RTEMS_MULTIPROCESSOR_RESOURCE_SHARING
     992      | RTEMS_BINARY_SEMAPHORE,
     993    1,
     994    &semaphore_id
     995  );
     996  assert(sc == RTEMS_SUCCESSFUL);
     997
     998  /*
     999   * The ceiling priority values per scheduler are equal to the value specified
     1000   * for object creation.
     1001   */
     1002
     1003  prio = RTEMS_CURRENT_PRIORITY;
     1004  sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio);
     1005  assert(sc == RTEMS_SUCCESSFUL);
     1006  assert(prio == 1);
     1007
     1008  /* Check the old value and set a new ceiling priority for scheduler B */
     1009
     1010  prio = 2;
     1011  sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio);
     1012  assert(sc == RTEMS_SUCCESSFUL);
     1013  assert(prio == 1);
     1014
     1015  /* Check the ceiling priority values */
     1016
     1017  prio = RTEMS_CURRENT_PRIORITY;
     1018  sc = rtems_semaphore_set_priority(semaphore_id, scheduler_a_id, prio, &prio);
     1019  assert(sc == RTEMS_SUCCESSFUL);
     1020  assert(prio == 1);
     1021
     1022  prio = RTEMS_CURRENT_PRIORITY;
     1023  sc = rtems_semaphore_set_priority(semaphore_id, scheduler_b_id, prio, &prio);
     1024  assert(sc == RTEMS_SUCCESSFUL);
     1025  assert(prio == 2);
     1026
     1027  sc = rtems_semaphore_delete(semaphore_id);
     1028  assert(sc == RTEMS_SUCCESSFUL);
     1029
     1030  exit(0);
     1031@}
     1032
     1033#define CONFIGURE_SMP_APPLICATION
     1034
     1035#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
     1036#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
     1037
     1038#define CONFIGURE_MAXIMUM_TASKS 1
     1039#define CONFIGURE_MAXIMUM_SEMAPHORES 1
     1040#define CONFIGURE_MAXIMUM_MRSP_SEMAPHORES 1
     1041
     1042#define CONFIGURE_SMP_MAXIMUM_PROCESSORS 2
     1043
     1044#define CONFIGURE_SCHEDULER_SIMPLE_SMP
     1045
     1046#include <rtems/scheduler.h>
     1047
     1048RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(a);
     1049
     1050RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(b);
     1051
     1052#define CONFIGURE_SCHEDULER_CONTROLS \
     1053  RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(a, SCHED_A), \
     1054  RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(b, SCHED_B)
     1055
     1056#define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \
     1057  RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
     1058  RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY)
     1059
     1060#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
     1061
     1062#define CONFIGURE_INIT
     1063
     1064#include <rtems/confdefs.h>
     1065@end group
     1066@end example
Note: See TracChangeset for help on using the changeset viewer.