From: richardbarry <richardbarry@1d2547de-c912-0410-9cb9-b8ca96c0e9e2>
Date: Sun, 17 Jan 2010 16:32:43 +0000 (+0000)
Subject: General tidy up of SH files.
X-Git-Tag: V6.0.3~20
X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=8370f5cefe1ba2dd685cd1b7618fa8ca7168710e;p=freertos

General tidy up of SH files.

git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@966 1d2547de-c912-0410-9cb9-b8ca96c0e9e2
---

diff --git a/Source/portable/Renesas/SH2A_FPU/port.c b/Source/portable/Renesas/SH2A_FPU/port.c
index c52485c81..7ce291939 100644
--- a/Source/portable/Renesas/SH2A_FPU/port.c
+++ b/Source/portable/Renesas/SH2A_FPU/port.c
@@ -62,9 +62,14 @@
 /* Library includes. */
 #include "string.h"
 
-#define portINITIAL_SR			0UL /* No interrupts masked. */
+/*-----------------------------------------------------------*/
+
+/* The SR assigned to a newly created task.  The only important thing in this
+value is for all interrupts to be enabled. */
+#define portINITIAL_SR				( 0UL )
 
-/* Allocate enough space for FPR0 to FPR15, FPUL and FPSCR, each of which is 4
+/* Dimensions the array into which the floating point context is saved.  
+Allocate enough space for FPR0 to FPR15, FPUL and FPSCR, each of which is 4
 bytes big.  If this number is changed then the 72 in portasm.src also needs
 changing. */
 #define portFLOP_REGISTERS_TO_STORE	( 18 )
@@ -72,11 +77,6 @@ changing. */
 
 /*-----------------------------------------------------------*/
 
-/*
- * Setup a peripheral timer to generate the RTOS tick interrupt.
- */
-static void prvSetupTimerInterrupt( void );
-
 /*
  * The TRAPA handler used to force a context switch.
  */
@@ -200,10 +200,18 @@ pxTopOfStack--;
 
 portBASE_TYPE xPortStartScheduler( void )
 {
-	/* Start the tick interrupt. */
-	prvSetupTimerInterrupt();
-	
-	/* Start the first task. */
+extern void vApplicationSetupTimerInterrupt( void );
+
+	/* Call an application function to set up the timer that will generate the
+	tick interrupt.  This way the application can decide which peripheral to 
+	use.  A demo application is provided to show a suitable example. */
+	vApplicationSetupTimerInterrupt();
+
+	/* Start the first task.  This will only restore the standard registers and
+	not the flop registers.  This does not really matter though because the only
+	flop register that is initialised to a particular value is fpscr, and it is
+	only initialised to the current value, which will still be the current value
+	when the first task starts executing. */
 	trapa( portSTART_SCHEDULER_TRAP_NO );
 
 	/* Should not get here. */
@@ -217,30 +225,12 @@ void vPortEndScheduler( void )
 }
 /*-----------------------------------------------------------*/
 
-void vPortTickInterrupt( void )
-{
-	vTaskIncrementTick();
-	#if configUSE_PREEMPTION == 1
-		vTaskSwitchContext();
-	#endif
-}
-/*-----------------------------------------------------------*/
-
-static void prvSetupTimerInterrupt( void )
-{
-extern void vApplicationSetupTimerInterrupt( void );
-
-	/* Call an application function to set up the timer.  This way the application
-	can decide which peripheral to use.  A demo application is provided to show a
-	suitable example. */
-	vApplicationSetupTimerInterrupt();
-}
-/*-----------------------------------------------------------*/
-
 void vPortYield( void )
 {
 long lInterruptMask;
 
+	/* Ensure the yield trap runs at the same priority as the other interrupts
+	that can cause a context switch. */
 	lInterruptMask = get_imask();
 
 	/* taskYIELD() can only be called from a task, not an interrupt, so the
@@ -250,6 +240,8 @@ long lInterruptMask;
 	
 	trapa( portYIELD_TRAP_NO );
 	
+	/* Restore the interrupt mask to whatever it was previously (when the
+	function was entered. */
 	set_imask( ( int ) lInterruptMask );
 }
 /*-----------------------------------------------------------*/
@@ -260,9 +252,15 @@ unsigned long *pulFlopBuffer;
 portBASE_TYPE xReturn;
 extern void * volatile pxCurrentTCB;
 
+	/* This function tells the kernel that the task referenced by xTask is
+	going to use the floating point registers and therefore requires the
+	floating point registers saved as part of its context. */
+
+	/* Passing NULL as xTask is used to indicate that the calling task is the
+	subject task - so pxCurrentTCB is the task handle. */
 	if( xTask == NULL )
 	{
-		xTask = pxCurrentTCB;
+		xTask = ( xTaskHandle ) pxCurrentTCB;
 	}
 
 	/* Allocate a buffer large enough to hold all the flop registers. */
@@ -270,12 +268,15 @@ extern void * volatile pxCurrentTCB;
 	
 	if( pulFlopBuffer != NULL )
 	{
+		/* Start with the registers in a benign state. */
 		memset( ( void * ) pulFlopBuffer, 0x00, portFLOP_STORAGE_SIZE );
 		
+		/* The first thing to get saved in the buffer is the FPSCR value -
+		initialise this to the current FPSCR value. */
 		*pulFlopBuffer = get_fpscr();
 		
-		/* Use the task tag to point to the flop buffer.  Pass pointer to just above
-		the buffer because the flop save routine uses a pre-decrement. */
+		/* Use the task tag to point to the flop buffer.  Pass pointer to just 
+		above the buffer because the flop save routine uses a pre-decrement. */
 		vTaskSetApplicationTaskTag( xTask, ( void * ) ( pulFlopBuffer + portFLOP_REGISTERS_TO_STORE ) );		
 		xReturn = pdPASS;
 	}
diff --git a/Source/portable/Renesas/SH2A_FPU/portmacro.h b/Source/portable/Renesas/SH2A_FPU/portmacro.h
index ca59d72db..93c64d96b 100644
--- a/Source/portable/Renesas/SH2A_FPU/portmacro.h
+++ b/Source/portable/Renesas/SH2A_FPU/portmacro.h
@@ -71,7 +71,8 @@ extern "C" {
  *-----------------------------------------------------------
  */
 
-/* Type definitions. */
+/* Type definitions - these are a bit legacy and not really used now, other than
+portSTACK_TYPE and portBASE_TYPE. */
 #define portCHAR		char
 #define portFLOAT		float
 #define portDOUBLE		double
@@ -90,7 +91,7 @@ extern "C" {
 /*-----------------------------------------------------------*/
 
 /* Hardware specifics. */
-#define portBYTE_ALIGNMENT				4
+#define portBYTE_ALIGNMENT				8
 #define portSTACK_GROWTH				-1
 #define portTICK_RATE_MS				( ( portTickType ) 1000 / configTICK_RATE_HZ )		
 #define portNOP()						nop()
@@ -101,19 +102,39 @@ extern "C" {
 void vPortYield( void );
 #define portYIELD()						vPortYield()
 
+/* 
+ * This function tells the kernel that the task referenced by xTask is going to 
+ * use the floating point registers and therefore requires the floating point 
+ * registers saved as part of its context. 
+ */
 portBASE_TYPE xPortUsesFloatingPoint( void* xTask );
+
+/*
+ * The flop save and restore functions are defined in portasm.src and called by
+ * the trace "task switched in" and "trace task switched out" macros. 
+ */
 void vPortSaveFlopRegisters( void *pulBuffer );
 void vPortRestoreFlopRegisters( void *pulBuffer );
+
+/*
+ * pxTaskTag is used to point to the buffer into which the floating point 
+ * context should be saved.  If pxTaskTag is NULL then the task does not use
+ * a floating point context.
+ */
 #define traceTASK_SWITCHED_OUT() if( pxCurrentTCB->pxTaskTag != NULL ) vPortSaveFlopRegisters( pxCurrentTCB->pxTaskTag )
 #define traceTASK_SWITCHED_IN() if( pxCurrentTCB->pxTaskTag != NULL ) vPortRestoreFlopRegisters( pxCurrentTCB->pxTaskTag )
 
-/*-----------------------------------------------------------*/
-
+/*
+ * These macros should be called directly, but through the taskENTER_CRITICAL()
+ * and taskEXIT_CRITICAL() macros.
+ */
 #define portENABLE_INTERRUPTS() 	set_imask( 0x00 )
 #define portDISABLE_INTERRUPTS() 	set_imask( portKERNEL_INTERRUPT_PRIORITY )
 
-/* Critical section handling. */
+/* Critical nesting counts are stored in the TCB. */
 #define portCRITICAL_NESTING_IN_TCB ( 1 )
+
+/* The critical nesting functions defined within tasks.c. */
 extern void vTaskEnterCritical( void );
 extern void vTaskExitCritical( void );
 #define portENTER_CRITICAL()	vTaskEnterCritical();