- Timestamp:
- 05/21/14 08:33:43 (10 years ago)
- Branches:
- 4.11, 5, 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)
- Location:
- doc/user
- Files:
-
- 3 edited
Legend:
- Unmodified
- Added
- Removed
-
doc/user/Makefile.am
r9f058fb r8fcafdd5 97 97 98 98 barrier.texi: barrier.t 99 $(BMENU2) -p "Semaphore Manager SEMAPHORE_ FLUSH - Unblock all tasks waiting ona semaphore" \99 $(BMENU2) -p "Semaphore Manager SEMAPHORE_SET_PRIORITY - Set priority by scheduler for a semaphore" \ 100 100 -u "Top" \ 101 101 -n "Message Manager" < $< > $@ -
doc/user/conf.t
r9f058fb r8fcafdd5 685 685 @subheading NOTES: 686 686 This 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: 700 Unsigned integer (@code{uint32_t}). 701 702 @item RANGE: 703 Zero or positive. 704 705 @item DEFAULT VALUE: 706 The default value is 0. 707 708 @end table 709 710 @subheading DESCRIPTION: 711 @code{CONFIGURE_MAXIMUM_MRSP_SEMAPHORES} is the 712 maximum number of Classic API Semaphores using the Multiprocessor Resource 713 Sharing Protocol (MrsP) that can be concurrently active. 714 715 @subheading NOTES: 716 This configuration option is only used on SMP configurations. On uni-processor 717 configurations the Priority Ceiling Protocol is used for MrsP semaphores and 718 thus no extra memory is necessary. 687 719 688 720 @c -
doc/user/sem.t
r9f058fb r8fcafdd5 25 25 @item @code{@value{DIRPREFIX}semaphore_release} - Release a semaphore 26 26 @item @code{@value{DIRPREFIX}semaphore_flush} - Unblock all tasks waiting on a semaphore 27 @item @code{@value{DIRPREFIX}semaphore_set_priority} - Set priority by 28 scheduler for a semaphore 27 29 @end itemize 28 30 … … 174 176 be restored to the normal value. 175 177 178 @subsection Multiprocessor Resource Sharing Protocol 179 180 The Multiprocessor Resource Sharing Protocol (MrsP) is defined in @cite{A. 181 Burns and A.J. Wellings, A Schedulability Compatible Multiprocessor Resource 182 Sharing Protocol - MrsP, Proceedings of the 25th Euromicro Conference on 183 Real-Time Systems (ECRTS 2013), July 2013}. It is a generalization of the 184 Priority Ceiling Protocol to SMP systems. Each MrsP semaphore uses a ceiling 185 priority per scheduler instance. These ceiling priorities can be specified 186 with @code{rtems_semaphore_set_priority()}. A task obtaining or owning a MrsP 187 semaphore will execute with the ceiling priority for its scheduler instance as 188 specified by the MrsP semaphore object. Tasks waiting to get ownership of a 189 MrsP semaphore will not relinquish the processor voluntarily. In case the 190 owner of a MrsP semaphore gets preempted it can ask all tasks waiting for this 191 semaphore to help out and temporarily borrow the right to execute on one of 192 their assigned processors. 193 176 194 @subsection Building a Semaphore Attribute Set 177 195 … … 199 217 @item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance 200 218 201 @item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling202 203 219 @item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority 204 220 ceiling (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 225 Multiprocessor Resource Sharing Protocol (default) 226 227 @item @code{@value{RPREFIX}MULTIPROCESSOR_RESOURCE_SHARING} - use 228 Multiprocessor Resource Sharing Protocol 205 229 206 230 @item @code{@value{RPREFIX}LOCAL} - local semaphore (default) … … 490 514 @item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance 491 515 492 @item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling493 494 516 @item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority 495 517 ceiling (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 522 Multiprocessor Resource Sharing Protocol (default) 523 524 @item @code{@value{RPREFIX}MULTIPROCESSOR_RESOURCE_SHARING} - use 525 Multiprocessor Resource Sharing Protocol 496 526 497 527 @item @code{@value{RPREFIX}LOCAL} - local semaphore (default) … … 512 542 The total number of global objects, including semaphores, is limited by 513 543 the maximum_global_objects field in the Configuration Table. 544 545 It 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 547 configurations in this case. This prevents lock order reversal problems with 548 the allocator mutex. 514 549 515 550 @c … … 736 771 this directive. 737 772 773 It is not allowed to obtain a MrsP semaphore more than once by one task at a 774 time (nested access) and the @code{@value{RPREFIX}UNSATISFIED} status code will 775 be returned on SMP configurations in this case. 776 738 777 @c 739 778 @c … … 832 871 @code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@* 833 872 @code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@* 873 @code{@value{RPREFIX}NOT_DEFINED} - operation not defined for the protocol of 874 the semaphore@* 834 875 @code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported for remote semaphores 835 876 … … 859 900 unblocked, and the proxy used to represent the task is reclaimed. 860 901 861 902 It is not allowed to flush a MrsP semaphore and the 903 @code{@value{RPREFIX}NOT_DEFINED} status code will be returned on SMP 904 configurations 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 919 rtems_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 934 the semaphore@* 935 @code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported for remote semaphores 936 937 @subheading DESCRIPTION: 938 939 This directive sets the priority value with respect to the specified scheduler 940 of a semaphore. 941 942 The special priority value @code{RTEMS_CURRENT_PRIORITY} can be used to get the 943 current priority value without changing it. 944 945 The interpretation of the priority value depends on the protocol of the 946 semaphore object. 947 948 @itemize @bullet 949 @item The Multiprocessor Resource Sharing Protocol needs a ceiling priority per 950 scheduler instance. This operation can be used to specify these priority 951 values. 952 @item For the Priority Ceiling Protocol the ceiling priority is used with this 953 operation. 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 970 static 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 1048 RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(a); 1049 1050 RTEMS_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.