summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Make.config4
-rw-r--r--doc/common/setup.texi8
-rw-r--r--doc/porting/interrupts.t34
-rw-r--r--doc/porting/prioritybitmap.t43
-rw-r--r--doc/porting/taskcontext.t57
-rw-r--r--doc/started/gdb.t9
-rw-r--r--doc/started/intro.t15
-rw-r--r--doc/started/sample.t7
-rw-r--r--doc/started_ada/intro.t15
-rw-r--r--doc/started_ada/sample.t7
-rw-r--r--doc/user/sem.t4
11 files changed, 154 insertions, 49 deletions
diff --git a/doc/Make.config b/doc/Make.config
index a200653c32..1b6d54068b 100644
--- a/doc/Make.config
+++ b/doc/Make.config
@@ -4,12 +4,12 @@
# $Id$
#
-RTEMS_VERSION=4.5-beta1b
+RTEMS_VERSION=4.5-beta2
#DOC_INSTALL_BASE=/usr1/rtems/tmp/rtemsdoc-$(RTEMS_VERSION)
DOC_INSTALL_BASE=/home/httpd/html/rtems/rtemsdoc-$(RTEMS_VERSION)
# DOC_INSTALL_BASE=/home/httpd/html/rtems/doc/rtems
-SRCDIR=/usr1/rtems/rtemsdoc-work
+SRCDIR=/usr1/rtems/4.5-work/rtems-doc
BMENU=$(SRCDIR)/tools/bmenu/bmenu
PDL2TEXI=$(SRCDIR)/tools/pdl2texi/pdl2texi
diff --git a/doc/common/setup.texi b/doc/common/setup.texi
index 23775d08c0..27bb5ce266 100644
--- a/doc/common/setup.texi
+++ b/doc/common/setup.texi
@@ -10,11 +10,11 @@
@c Set Variables
@c
-@set RTEMS-RELEASE 4.5-beta1b
+@set RTEMS-RELEASE 4.5-beta2
@set RTEMS-EDITION 1
-@set RTEMS-VERSION 4.5-beta1b
-@set RTEMS-UPDATE-DATE February 23 2000
-@set RTEMS-UPDATE-MONTH February 2000
+@set RTEMS-VERSION 4.5-beta2
+@set RTEMS-UPDATE-DATE April 13 2000
+@set RTEMS-UPDATE-MONTH April 2000
@c
@c The following determines which set of the tables and figures we will use.
diff --git a/doc/porting/interrupts.t b/doc/porting/interrupts.t
index e469491d52..a73c21c0d0 100644
--- a/doc/porting/interrupts.t
+++ b/doc/porting/interrupts.t
@@ -193,7 +193,7 @@ NOTE: This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
#define CPU_ALLOCATE_INTERRUPT_STACK TRUE
@end example
-If the CPU_HAS_SOFTWARE_INTERRUPT_STACK macro is set to TRUE, then RTEMS automatically allocates the stack memory in the initialization of the Interrupt Manager and the switch to that stack is performed in _ISR_Handler on the outermost interrupt. The _CPU_Interrupt_stack_low and _CPU_Interrupt_stack_high variables contain the addresses of the the lowest and highest addresses of the memory allocated for the interrupt stack. Although technically only one of these addresses is required to switch to the interrupt stack, by always providing both addresses, the port has more options avaialble to it without requiring modifications to the portable parts of the executive. Whether the stack grows up or down, this give the CPU dependent code the option of picking the version it wants to use.
+If the CPU_HAS_SOFTWARE_INTERRUPT_STACK macro is set to TRUE, then RTEMS automatically allocates the stack memory in the initialization of the Interrupt Manager and the switch to that stack is performed in @code{_ISR_Handler} on the outermost interrupt. The _CPU_Interrupt_stack_low and _CPU_Interrupt_stack_high variables contain the addresses of the the lowest and highest addresses of the memory allocated for the interrupt stack. Although technically only one of these addresses is required to switch to the interrupt stack, by always providing both addresses, the port has more options avaialble to it without requiring modifications to the portable parts of the executive. Whether the stack grows up or down, this give the CPU dependent code the option of picking the version it wants to use.
@example
SCORE_EXTERN void *_CPU_Interrupt_stack_low;
@@ -283,7 +283,7 @@ _CPU_ISR_install_raw_handler( vector, new_handler, old_handler );
@end example
We put the actual user ISR address in _ISR_vector_table. This will be
-used by the _ISR_Handler so the user gets control.
+used by the @code{_ISR_Handler} so the user gets control.
@example
_ISR_Vector_table[ vector ] = new_handler;
@@ -312,7 +312,7 @@ typedef struct @{
@subsection Interrupt Dispatching
-The _ISR_Handler routine provides the RTEMS interrupt management.
+The @code{_ISR_Handler} routine provides the RTEMS interrupt management.
@example
void _ISR_Handler()
@@ -326,18 +326,26 @@ allowing the ISR to preserve only those that would normally be corrupted
by a subroutine call.
Also note that the exact order is to a large extent flexible. Hardware
-will dictate a sequence for a certain subset of _ISR_Handler while
+will dictate a sequence for a certain subset of @code{_ISR_Handler} while
requirements for setting the RTEMS state variables that indicate the
-interrupt nest level (XX) and dispatching disable level (XXX) will also
+interrupt nest level (@code{_ISR_Nest_level}) and dispatching disable
+level (@code{_Thread_Dispatch_disable_level}) will also
restrict the allowable order.
-Upon entry to the "common" _ISR_Handler, the vector number must be
+Upon entry to @code{_ISR_Handler}, @code{_Thread_Dispatch_disable_level} is
+zero if the interrupt occurred while outside an RTEMS service call.
+Conversely, it will be non-zero if interrupting an RTEMS service
+call. Thus, @code{_Thread_Dispatch_disable_level} will always be
+greater than or equal to @code{_ISR_Nest_level} and not strictly
+equal.
+
+Upon entry to the "common" @code{_ISR_Handler}, the vector number must be
available. On some CPUs the hardware puts either the vector number or the
offset into the vector table for this ISR in a known place. If the
hardware does not provide this information, then the assembly portion of
RTEMS for this port will contain a set of distinct interrupt entry points
which somehow place the vector number in a known place (which is safe if
-another interrupt nests this one) and branches to _ISR_Handler.
+another interrupt nests this one) and branches to @code{_ISR_Handler}.
@example
save some or all context on stack
@@ -361,9 +369,10 @@ if ( !_Context_Switch_necessary )
goto the label "exit interrupt (simple case)"
if ( !_ISR_Signals_to_thread_executing )
- _ISR_Signals_to_thread_executing = FALSE;
goto the label "exit interrupt (simple case)"
+_ISR_Signals_to_thread_executing = FALSE;
+
call _Thread_Dispatch() or prepare to return to _ISR_Dispatch
prepare to get out of interrupt
return from interrupt (maybe to _ISR_Dispatch)
@@ -372,6 +381,15 @@ LABEL "exit interrupt (simple case):
prepare to get out of interrupt
return from interrupt
@end example
+
+Some ports have the special routine @code{_ISR_Dispatch} because
+the CPU has a special "interrupt mode" and RTEMS must switch back
+to the task stack and/or non-interrupt mode before invoking
+@code{_Thread_Dispatch}. For example, consider the MC68020 where
+upon return from the outermost interrupt, the CPU must switch
+from the interrupt stack to the master stack before invoking
+@code{_Thread_Dispatch}. @code{_ISR_Dispatch} is the special port
+specific wrapper for @code{_Thread_Dispatch} used in this case.
@subsection ISR Invoked with Frame Pointer
diff --git a/doc/porting/prioritybitmap.t b/doc/porting/prioritybitmap.t
index b4a6a92f90..b71790cf74 100644
--- a/doc/porting/prioritybitmap.t
+++ b/doc/porting/prioritybitmap.t
@@ -27,9 +27,26 @@ ready task at that priority. The bit array can be efficiently searched to
determine the highest priority ready task. This family of data type and
routines is used to maintain and search the bit map array.
+When manipulating the bitmap array, RTEMS internally divides the
+8 bits of the task priority into "major" and "minor" components.
+The most significant 4 bits are the major component, while the least
+significant are the minor component. The major component of a priority
+value is used to determine which 16-bit wide entry in the
+@code{_Priority_Bit_map} array is associated with this priority.
+Each element in the @code{_Priority_Bit_map} array has a bit
+in the @code{_Priority_Major_bit_map} associated with it.
+That bit is cleared when all of the bits in a particular
+@code{_Priority_Bit_map} array entry are zero.
+
+The minor component of a priority is used to determine
+specifically which bit in @code{_Priority_Bit_map[major]}
+indicates whether or not there is a ready to execute task
+at the priority.
+
+
@section _Priority_Bit_map_control Type
-The _Priority_Bit_map_Control type is the fundamental data type of the
+The @code{_Priority_Bit_map_Control} type is the fundamental data type of the
priority bit map array used to determine which priorities have ready
tasks. This type may be either 16 or 32 bits wide although only the 16
least significant bits will be used. The data type is based upon what is
@@ -41,8 +58,8 @@ instruction.
@section Find First Bit Routine
The _CPU_Bitfield_Find_first_bit routine sets _output to the bit number of
-the first bit set in _value. _value is of CPU dependent type
-Priority_Bit_map_control. A stub version of this routine is as follows:
+the first bit set in @code{_value}. @code{_value} is of CPU dependent type
+@code{Priority_Bit_map_control}. A stub version of this routine is as follows:
@example
#define _CPU_Bitfield_Find_first_bit( _value, _output ) \
@@ -51,6 +68,8 @@ Priority_Bit_map_control. A stub version of this routine is as follows:
@}
@end example
+
+
There are a number of variables in using a "find first bit" type
instruction.
@@ -69,7 +88,7 @@ instruction.
RTEMS guarantees that (1) will never happen so it is not a concern.
Cases (2),(3), (4) are handled by the macros _CPU_Priority_mask() and
_CPU_Priority_bits_index(). These three form a set of routines which must
-logically operate together. Bits in the _value are set and cleared based
+logically operate together. Bits in the @code{_value} are set and cleared based
on masks built by CPU_Priority_mask(). The basic major and minor values
calculated by _Priority_Major() and _Priority_Minor() are "massaged" by
_CPU_Priority_bits_index() to properly range between the values returned
@@ -154,7 +173,21 @@ _CPU_Bitfield_Find_first_bit searches for the most significant bit set:
@section Bit Scan Support
-The _CPU_Priority_bits_index routine translates the bit numbers returned by _CPU_Bitfield_Find_first_bit() into something suitable for use as a major or minor component of a priority. For example, the find first bit routine may number the bits in a way that is difficult to map into the major and minor components of the priority. This routine allows that unwieldy form to be converted into something easier to process. See the discussion of that routine for more details.
+The @code{_CPU_Priority_bits_index} routine translates the bit numbers
+returned by @code{_CPU_Bitfield_Find_first_bit()} into something
+suitable for use as a major or minor component of a priority.
+The find first bit routine may number the bits in a
+way that is difficult to map into the major and minor components
+of the priority. For example, when finding the first bit set in
+the value 0x8000, a CPU may indicate that bit 15 or 16 is set
+based on whether the least significant bit is "zero" or "one".
+Similarly, a CPU may only scan 32-bit values and consider the
+most significant bit to be bit zero or one. In this case, this
+would be bit 16 or 17.
+
+This routine allows that unwieldy form to be converted
+into a normalized form that is easier to process and use
+as an index.
@example
#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
diff --git a/doc/porting/taskcontext.t b/doc/porting/taskcontext.t
index 57f83b5caa..6608a734b9 100644
--- a/doc/porting/taskcontext.t
+++ b/doc/porting/taskcontext.t
@@ -169,13 +169,27 @@ void _CPU_Context_Initialize(
);
@end example
-This is_fp parameter is TRUE if the thread is to be a floating point
+The @code{is_fp} parameter is TRUE if the thread is to be a floating point
thread. This is typically only used on CPUs where the FPU may be easily
disabled by software such as on the SPARC where the PSR contains an enable
FPU bit. The use of an FPU enable bit allows RTEMS to ensure that a
non-floating point task is unable to access the FPU. This guarantees that
a deferred floating point context switch is safe.
+The @code{_stack_base} parameter is the base address of the memory area
+allocated for use as the task stack. It is critical to understand that
+@code{_stack_base} may not be the starting stack pointer for this task.
+On CPU families where the stack grows from high addresses to lower ones,
+(i.e. @code{CPU_STACK_GROWS_UP} is FALSE) the starting stack point
+will be near the end of the stack memory area or close to
+@code{_stack_base} + @code{_size}. Even on CPU families where the stack
+grows from low to higher addresses, there may be some required
+outermost stack frame that must be put at the address @code{_stack_base}.
+
+The @code{_size} parameter is the requested size in bytes of the stack for
+this task. It is assumed that the memory area @code{_stack_base}
+is of this size.
+
XXX explain other parameters and check prototype
@subsection Performing a Context Switch
@@ -190,6 +204,47 @@ void _CPU_Context_switch(
);
@end example
+This routine begins by saving the current state of the
+CPU (i.e. the context) in the context area at @code{run}.
+Then the routine should load the CPU context pointed to
+by @code{heir}. Loading the new context will cause a
+branch to its task code, so the task that invoked
+@code{_CPU_Context_switch} will not run for a while.
+When, eventually, a context switch is made to load
+context from @code{*run} again, this task will resume
+and @code{_CPU_Context_switch} will return to its caller.
+
+Care should be exercise when writing this routine. All
+registers assumed to be preserved across subroutine calls
+must be preserved. These registers may be saved in
+the task's context area or on its stack. However, the
+stack pointer and address to resume executing the task
+at must be included in the context (normally the subroutine
+return address to the caller of @code{_Thread_Dispatch}.
+The decision of where to store the task's context is based
+on numerous factors including the capabilities of
+the CPU architecture itself and simplicity as well
+as external considerations such as debuggers wishing
+to examine a task's context. In this case, it is
+often simpler to save all data in the context area.
+
+Also there may be special considerations
+when loading the stack pointers or interrupt level of the
+incoming task. Independent of CPU specific considerations,
+if some context is saved on the task stack, then the porter
+must ensure that the stack pointer is adjusted @b{BEFORE}
+to make room for this context information before the
+information is written. Otherwise, an interrupt could
+occur writing over the context data. The following is
+an example of an @b{INCORRECT} sequence:
+
+@example
+save part of context beyond current top of stack
+interrupt pushes context -- overwriting written context
+interrupt returns
+adjust stack pointer
+@end example
+
@subsection Restoring a Context
The _CPU_Context_restore routine is generally used only to restart the
diff --git a/doc/started/gdb.t b/doc/started/gdb.t
index ee05ee2958..1052315875 100644
--- a/doc/started/gdb.t
+++ b/doc/started/gdb.t
@@ -67,15 +67,6 @@ find . -name "*.rej" -print
If any files are found with the .rej extension, a patch has been rejected.
This should not happen with a good patch file.
-To see the files that have been modified use the sequence:
-
-@example
-cd tools/@value{GDB-UNTAR}
-find . -name "*.orig" -print
-@end example
-
-The files that are found, have been modified by the patch file.
-
@end ifset
@section Using the bit_gdb script
diff --git a/doc/started/intro.t b/doc/started/intro.t
index 5b6354f4fe..b89ecedd22 100644
--- a/doc/started/intro.t
+++ b/doc/started/intro.t
@@ -127,13 +127,14 @@ use to RTEMS users.
@subsection RTEMS Mailing List
-rtems-list@@OARcorp.com
-
-This mailing list is dedicated to discussion of issues related
-to RTEMS. If you have questions about RTEMS, wish to make
-suggestions, or just want to pick up hints, this is a good
-list to subscribe to. Subscribe by sending a message with
-the one line "subscribe" to rtems-list-request@@OARcorp.com.
+rtems-users@@OARcorp.com
+
+This mailing list is dedicated to the discussion of issues related
+to RTEMS, including GNAT/RTEMS. If you have questions about RTEMS,
+wish to make suggestions, or just want to pick up hints, this is a
+good list to subscribe to. Subscribe by sending an empty mail
+message to rtems-users-subscribe@@OARcorp.com. Messages sent
+to rtems-users@@OARcorp.com are posted to the list.
@subsection CrossGCC Mailing List
diff --git a/doc/started/sample.t b/doc/started/sample.t
index 9f8da9eb60..897b444007 100644
--- a/doc/started/sample.t
+++ b/doc/started/sample.t
@@ -36,9 +36,12 @@ Use the following command to start the build of the sample application:
@example
cd tools/hello_world_c
-gmake
+make
@end example
+NOTE: GNU make is the preferred @code{make} utility. Other @code{make}
+implementations may work but all testing is done with GNU make.
+
If no errors are detected during the sample application build, it is
reasonable to assume that the build of the GNU C/C++ Cross Compiler Tools
for RTEMS and RTEMS itself for the selected host and target
@@ -50,7 +53,7 @@ If the sample application has successfully been build, then the application
executable is placed in the following directory:
@example
-tools/hello_world_c/o-<BOARD_SUPPORT_PACKAGE>/<filename>.exe
+tools/hello_world_c/o-optimize/<filename>.exe
@end example
How this executable is downloaded to the target board is very dependent
diff --git a/doc/started_ada/intro.t b/doc/started_ada/intro.t
index bbdb374769..b8ae0ca57f 100644
--- a/doc/started_ada/intro.t
+++ b/doc/started_ada/intro.t
@@ -127,13 +127,14 @@ use to GNAT/RTEMS users.
@subsection RTEMS Mailing List
-rtems-list@@OARcorp.com
-
-This mailing list is dedicated to discussion of issues related
-to RTEMS. If you have questions about RTEMS, wish to make
-suggestions, or just want to pick up hints, this is a good
-list to subscribe to. Subscribe by sending a message with
-the one line "subscribe" to rtems-list-request@@OARcorp.com.
+rtems-users@@OARcorp.com
+
+This mailing list is dedicated to the discussion of issues related
+to RTEMS, including GNAT/RTEMS. If you have questions about RTEMS,
+wish to make suggestions, or just want to pick up hints, this is a
+good list to subscribe to. Subscribe by sending an empty mail
+message to rtems-users-subscribe@@OARcorp.com. Messages sent
+to rtems-users@@OARcorp.com are posted to the list.
@subsection CrossGCC Mailing List
diff --git a/doc/started_ada/sample.t b/doc/started_ada/sample.t
index d64af1c092..53a2ba4cbb 100644
--- a/doc/started_ada/sample.t
+++ b/doc/started_ada/sample.t
@@ -32,9 +32,12 @@ Use the following command to start the build of the sample application:
@example
cd tools/hello_world_ada
-gmake -f Makefile.<BOARD_SUPPORT_PACKAGE>
+make -f Makefile.<BOARD_SUPPORT_PACKAGE>
@end example
+NOTE: GNU make is the preferred @code{make} utility. Other @code{make}
+implementations may work but all testing is done with GNU make.
+
If the BSP specific modifications to the Makefile were correct and
no errors are detected during the sample application build, it is
reasonable to assume that the build of the GNAT/RTEMS Cross Compiler Tools
@@ -47,7 +50,7 @@ If the sample application has successfully been build, then the application
executable is placed in the following directory:
@example
-tools/hello_world_ada/o-<BOARD_SUPPORT_PACKAGE>/<filename>.exe
+tools/hello_world_ada/o-optimize/<filename>.exe
@end example
How this executable is downloaded to the target board is very dependent
diff --git a/doc/user/sem.t b/doc/user/sem.t
index e1d075085c..abc5a113e8 100644
--- a/doc/user/sem.t
+++ b/doc/user/sem.t
@@ -193,7 +193,7 @@ the set of valid semaphore attributes:
@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
@item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
-0 and 1 and do not allow nested access.
+0 and 1, do not allow nested access, allow deletion of locked semaphore.
@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
inheritance (default)
@@ -452,7 +452,7 @@ defined by RTEMS:
@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
@item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
-0 and 1 and do not allow nested access.
+0 and 1, block on nested access, allow deletion of locked semaphore.
@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
inheritance (default)