Context Navigation

-                      r0765f9b
+                      rbb4b574
+#
 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

doc/common/setup.texi

-                      r0765f9b
+                      rbb4b574
 @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

doc/porting/interrupts.t

-                      r0765f9b
+                      rbb4b574
 @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
 …
 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
 …
 @subsection Interrupt Dispatching
 The _ISR_Handler routine provides the RTEMS interrupt management.
+The @code{_ISR_Handler} routine provides the RTEMS interrupt management.
 @example
 …
 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
 …
 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
 …
 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
 …
  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

doc/porting/prioritybitmap.t

-                      r0765f9b
+                      rbb4b574
 routines is used to maintain and search the bit map array.
+When manipulating the bitmap array, RTEMS internally divides the
+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
 …
 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
 …
   @}
 @end example
 There are a number of variables in using a "find first bit" type
 …
 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
 …
 @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

doc/porting/taskcontext.t

-                      r0765f9b
+                      rbb4b574
 @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
 …
 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
 …
   Context_Control  *heir
 );
+@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

doc/started/gdb.t

-                      r0765f9b
+                      rbb4b574
 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

doc/started/intro.t

-                      r0765f9b
+                      rbb4b574
 @subsection RTEMS Mailing List
 rtems-list@@OARcorp.com
+rtems-users@@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.
+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

doc/started/sample.t

-                      r0765f9b
+                      rbb4b574
 @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
 …
 @example
 tools/hello_world_c/o-<BOARD_SUPPORT_PACKAGE>/<filename>.exe
+tools/hello_world_c/o-optimize/<filename>.exe
 @end example

doc/started_ada/intro.t

-                      r0765f9b
+                      rbb4b574
 @subsection RTEMS Mailing List
 rtems-list@@OARcorp.com
+rtems-users@@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.
+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

doc/started_ada/sample.t

-                      r0765f9b
+                      rbb4b574
 @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
 …
 @example
 tools/hello_world_ada/o-<BOARD_SUPPORT_PACKAGE>/<filename>.exe
+tools/hello_world_ada/o-optimize/<filename>.exe
 @end example

doc/user/sem.t

-                      r0765f9b
+                      rbb4b574
 @item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
 and 1 and do not allow nested access.
+and 1, do not allow nested access, allow deletion of locked semaphore.
 @item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
 …
 @item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
 and 1 and do not allow nested access.
+and 1, block on nested access, allow deletion of locked semaphore.
 @item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset bb4b574 in rtems

Legend:

Download in other formats: