Eric Patterson / mbed-rtos

Fork of official mbed Real Time Operating System based on the RTX implementation of the CMSIS-RTOS API open standard.

Dependents:   Final_Coffee_Roaster

Fork of mbed-rtos by mbed official

rtx/rt_Task.c@7:80173c64d05d, 2012-11-23 (annotated)

Committer:
emilmont
Date:
Fri Nov 23 10:16:38 2012 +0000
Revision:
7:80173c64d05d
Parent:
6:350b53afb889
Child:
11:db1fc233faa9
Avoid using C++ keyword for C structure filed name

Who changed what in which revision?

UserRevisionLine numberNew contents of line
emilmont 6:350b53afb889 1 /*----------------------------------------------------------------------------
emilmont 6:350b53afb889 2 * RL-ARM - RTX
emilmont 6:350b53afb889 3 *----------------------------------------------------------------------------
emilmont 6:350b53afb889 4 * Name: RT_TASK.C
emilmont 6:350b53afb889 5 * Purpose: Task functions and system start up.
emilmont 6:350b53afb889 6 * Rev.: V4.60
emilmont 6:350b53afb889 7 *----------------------------------------------------------------------------
emilmont 6:350b53afb889 8 *
emilmont 6:350b53afb889 9 * Copyright (c) 1999-2009 KEIL, 2009-2012 ARM Germany GmbH
emilmont 6:350b53afb889 10 * All rights reserved.
emilmont 6:350b53afb889 11 * Redistribution and use in source and binary forms, with or without
emilmont 6:350b53afb889 12 * modification, are permitted provided that the following conditions are met:
emilmont 6:350b53afb889 13 * - Redistributions of source code must retain the above copyright
emilmont 6:350b53afb889 14 * notice, this list of conditions and the following disclaimer.
emilmont 6:350b53afb889 15 * - Redistributions in binary form must reproduce the above copyright
emilmont 6:350b53afb889 16 * notice, this list of conditions and the following disclaimer in the
emilmont 6:350b53afb889 17 * documentation and/or other materials provided with the distribution.
emilmont 6:350b53afb889 18 * - Neither the name of ARM nor the names of its contributors may be used
emilmont 6:350b53afb889 19 * to endorse or promote products derived from this software without
emilmont 6:350b53afb889 20 * specific prior written permission.
emilmont 6:350b53afb889 21 *
emilmont 6:350b53afb889 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
emilmont 6:350b53afb889 23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
emilmont 6:350b53afb889 24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
emilmont 6:350b53afb889 25 * ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
emilmont 6:350b53afb889 26 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
emilmont 6:350b53afb889 27 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
emilmont 6:350b53afb889 28 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
emilmont 6:350b53afb889 29 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
emilmont 6:350b53afb889 30 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
emilmont 6:350b53afb889 31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
emilmont 6:350b53afb889 32 * POSSIBILITY OF SUCH DAMAGE.
emilmont 6:350b53afb889 33 *---------------------------------------------------------------------------*/
emilmont 6:350b53afb889 34
emilmont 6:350b53afb889 35 #include "rt_TypeDef.h"
emilmont 6:350b53afb889 36 #include "RTX_Config.h"
emilmont 6:350b53afb889 37 #include "rt_System.h"
emilmont 6:350b53afb889 38 #include "rt_Task.h"
emilmont 6:350b53afb889 39 #include "rt_List.h"
emilmont 6:350b53afb889 40 #include "rt_MemBox.h"
emilmont 6:350b53afb889 41 #include "rt_Robin.h"
emilmont 6:350b53afb889 42 #include "rt_HAL_CM.h"
emilmont 6:350b53afb889 43
emilmont 6:350b53afb889 44 /*----------------------------------------------------------------------------
emilmont 6:350b53afb889 45 * Global Variables
emilmont 6:350b53afb889 46 *---------------------------------------------------------------------------*/
emilmont 6:350b53afb889 47
emilmont 6:350b53afb889 48 /* Running and next task info. */
emilmont 6:350b53afb889 49 struct OS_TSK os_tsk;
emilmont 6:350b53afb889 50
emilmont 6:350b53afb889 51 /* Task Control Blocks of idle demon */
emilmont 6:350b53afb889 52 struct OS_TCB os_idle_TCB;
emilmont 6:350b53afb889 53
emilmont 6:350b53afb889 54
emilmont 6:350b53afb889 55 /*----------------------------------------------------------------------------
emilmont 6:350b53afb889 56 * Local Functions
emilmont 6:350b53afb889 57 *---------------------------------------------------------------------------*/
emilmont 6:350b53afb889 58
emilmont 6:350b53afb889 59 OS_TID rt_get_TID (void) {
emilmont 6:350b53afb889 60 U32 tid;
emilmont 6:350b53afb889 61
emilmont 6:350b53afb889 62 for (tid = 1; tid <= os_maxtaskrun; tid++) {
emilmont 6:350b53afb889 63 if (os_active_TCB[tid-1] == NULL) {
emilmont 6:350b53afb889 64 return ((OS_TID)tid);
emilmont 6:350b53afb889 65 }
emilmont 6:350b53afb889 66 }
emilmont 6:350b53afb889 67 return (0);
emilmont 6:350b53afb889 68 }
emilmont 6:350b53afb889 69
emilmont 6:350b53afb889 70 #if defined (__CC_ARM) && !defined (__MICROLIB)
emilmont 6:350b53afb889 71 /*--------------------------- __user_perthread_libspace ---------------------*/
emilmont 6:350b53afb889 72 extern void *__libspace_start;
emilmont 6:350b53afb889 73
emilmont 6:350b53afb889 74 void *__user_perthread_libspace (void) {
emilmont 6:350b53afb889 75 /* Provide a separate libspace for each task. */
emilmont 6:350b53afb889 76 if (os_tsk.run == NULL) {
emilmont 6:350b53afb889 77 /* RTX not running yet. */
emilmont 6:350b53afb889 78 return (&__libspace_start);
emilmont 6:350b53afb889 79 }
emilmont 6:350b53afb889 80 return (void *)(os_tsk.run->std_libspace);
emilmont 6:350b53afb889 81 }
emilmont 6:350b53afb889 82 #endif
emilmont 6:350b53afb889 83
emilmont 6:350b53afb889 84 /*--------------------------- rt_init_context -------------------------------*/
emilmont 6:350b53afb889 85
emilmont 6:350b53afb889 86 void rt_init_context (P_TCB p_TCB, U8 priority, FUNCP task_body) {
emilmont 6:350b53afb889 87 /* Initialize general part of the Task Control Block. */
emilmont 6:350b53afb889 88 p_TCB->cb_type = TCB;
emilmont 6:350b53afb889 89 p_TCB->state = READY;
emilmont 6:350b53afb889 90 p_TCB->prio = priority;
emilmont 6:350b53afb889 91 p_TCB->p_lnk = NULL;
emilmont 6:350b53afb889 92 p_TCB->p_rlnk = NULL;
emilmont 6:350b53afb889 93 p_TCB->p_dlnk = NULL;
emilmont 6:350b53afb889 94 p_TCB->p_blnk = NULL;
emilmont 6:350b53afb889 95 p_TCB->delta_time = 0;
emilmont 6:350b53afb889 96 p_TCB->interval_time = 0;
emilmont 6:350b53afb889 97 p_TCB->events = 0;
emilmont 6:350b53afb889 98 p_TCB->waits = 0;
emilmont 6:350b53afb889 99 p_TCB->stack_frame = 0;
emilmont 6:350b53afb889 100
emilmont 6:350b53afb889 101 rt_init_stack (p_TCB, task_body);
emilmont 6:350b53afb889 102 }
emilmont 6:350b53afb889 103
emilmont 6:350b53afb889 104
emilmont 6:350b53afb889 105 /*--------------------------- rt_switch_req ---------------------------------*/
emilmont 6:350b53afb889 106
emilmont 6:350b53afb889 107 void rt_switch_req (P_TCB p_new) {
emilmont 6:350b53afb889 108 /* Switch to next task (identified by "p_new"). */
emilmont 7:80173c64d05d 109 os_tsk.new_tsk = p_new;
emilmont 6:350b53afb889 110 p_new->state = RUNNING;
emilmont 6:350b53afb889 111 DBG_TASK_SWITCH(p_new->task_id);
emilmont 6:350b53afb889 112 }
emilmont 6:350b53afb889 113
emilmont 6:350b53afb889 114
emilmont 6:350b53afb889 115 /*--------------------------- rt_dispatch -----------------------------------*/
emilmont 6:350b53afb889 116
emilmont 6:350b53afb889 117 void rt_dispatch (P_TCB next_TCB) {
emilmont 6:350b53afb889 118 /* Dispatch next task if any identified or dispatch highest ready task */
emilmont 6:350b53afb889 119 /* "next_TCB" identifies a task to run or has value NULL (=no next task) */
emilmont 6:350b53afb889 120 if (next_TCB == NULL) {
emilmont 6:350b53afb889 121 /* Running task was blocked: continue with highest ready task */
emilmont 6:350b53afb889 122 next_TCB = rt_get_first (&os_rdy);
emilmont 6:350b53afb889 123 rt_switch_req (next_TCB);
emilmont 6:350b53afb889 124 }
emilmont 6:350b53afb889 125 else {
emilmont 6:350b53afb889 126 /* Check which task continues */
emilmont 6:350b53afb889 127 if (next_TCB->prio > os_tsk.run->prio) {
emilmont 6:350b53afb889 128 /* preempt running task */
emilmont 6:350b53afb889 129 rt_put_rdy_first (os_tsk.run);
emilmont 6:350b53afb889 130 os_tsk.run->state = READY;
emilmont 6:350b53afb889 131 rt_switch_req (next_TCB);
emilmont 6:350b53afb889 132 }
emilmont 6:350b53afb889 133 else {
emilmont 6:350b53afb889 134 /* put next task into ready list, no task switch takes place */
emilmont 6:350b53afb889 135 next_TCB->state = READY;
emilmont 6:350b53afb889 136 rt_put_prio (&os_rdy, next_TCB);
emilmont 6:350b53afb889 137 }
emilmont 6:350b53afb889 138 }
emilmont 6:350b53afb889 139 }
emilmont 6:350b53afb889 140
emilmont 6:350b53afb889 141
emilmont 6:350b53afb889 142 /*--------------------------- rt_block --------------------------------------*/
emilmont 6:350b53afb889 143
emilmont 6:350b53afb889 144 void rt_block (U16 timeout, U8 block_state) {
emilmont 6:350b53afb889 145 /* Block running task and choose next ready task. */
emilmont 6:350b53afb889 146 /* "timeout" sets a time-out value or is 0xffff (=no time-out). */
emilmont 6:350b53afb889 147 /* "block_state" defines the appropriate task state */
emilmont 6:350b53afb889 148 P_TCB next_TCB;
emilmont 6:350b53afb889 149
emilmont 6:350b53afb889 150 if (timeout) {
emilmont 6:350b53afb889 151 if (timeout < 0xffff) {
emilmont 6:350b53afb889 152 rt_put_dly (os_tsk.run, timeout);
emilmont 6:350b53afb889 153 }
emilmont 6:350b53afb889 154 os_tsk.run->state = block_state;
emilmont 6:350b53afb889 155 next_TCB = rt_get_first (&os_rdy);
emilmont 6:350b53afb889 156 rt_switch_req (next_TCB);
emilmont 6:350b53afb889 157 }
emilmont 6:350b53afb889 158 }
emilmont 6:350b53afb889 159
emilmont 6:350b53afb889 160
emilmont 6:350b53afb889 161 /*--------------------------- rt_tsk_pass -----------------------------------*/
emilmont 6:350b53afb889 162
emilmont 6:350b53afb889 163 void rt_tsk_pass (void) {
emilmont 6:350b53afb889 164 /* Allow tasks of same priority level to run cooperatively.*/
emilmont 6:350b53afb889 165 P_TCB p_new;
emilmont 6:350b53afb889 166
emilmont 6:350b53afb889 167 p_new = rt_get_same_rdy_prio();
emilmont 6:350b53afb889 168 if (p_new != NULL) {
emilmont 6:350b53afb889 169 rt_put_prio ((P_XCB)&os_rdy, os_tsk.run);
emilmont 6:350b53afb889 170 os_tsk.run->state = READY;
emilmont 6:350b53afb889 171 rt_switch_req (p_new);
emilmont 6:350b53afb889 172 }
emilmont 6:350b53afb889 173 }
emilmont 6:350b53afb889 174
emilmont 6:350b53afb889 175
emilmont 6:350b53afb889 176 /*--------------------------- rt_tsk_self -----------------------------------*/
emilmont 6:350b53afb889 177
emilmont 6:350b53afb889 178 OS_TID rt_tsk_self (void) {
emilmont 6:350b53afb889 179 /* Return own task identifier value. */
emilmont 6:350b53afb889 180 if (os_tsk.run == NULL) {
emilmont 6:350b53afb889 181 return (0);
emilmont 6:350b53afb889 182 }
emilmont 6:350b53afb889 183 return (os_tsk.run->task_id);
emilmont 6:350b53afb889 184 }
emilmont 6:350b53afb889 185
emilmont 6:350b53afb889 186
emilmont 6:350b53afb889 187 /*--------------------------- rt_tsk_prio -----------------------------------*/
emilmont 6:350b53afb889 188
emilmont 6:350b53afb889 189 OS_RESULT rt_tsk_prio (OS_TID task_id, U8 new_prio) {
emilmont 6:350b53afb889 190 /* Change execution priority of a task to "new_prio". */
emilmont 6:350b53afb889 191 P_TCB p_task;
emilmont 6:350b53afb889 192
emilmont 6:350b53afb889 193 if (task_id == 0) {
emilmont 6:350b53afb889 194 /* Change execution priority of calling task. */
emilmont 6:350b53afb889 195 os_tsk.run->prio = new_prio;
emilmont 6:350b53afb889 196 run:if (rt_rdy_prio() > new_prio) {
emilmont 6:350b53afb889 197 rt_put_prio (&os_rdy, os_tsk.run);
emilmont 6:350b53afb889 198 os_tsk.run->state = READY;
emilmont 6:350b53afb889 199 rt_dispatch (NULL);
emilmont 6:350b53afb889 200 }
emilmont 6:350b53afb889 201 return (OS_R_OK);
emilmont 6:350b53afb889 202 }
emilmont 6:350b53afb889 203
emilmont 6:350b53afb889 204 /* Find the task in the "os_active_TCB" array. */
emilmont 6:350b53afb889 205 if (task_id > os_maxtaskrun || os_active_TCB[task_id-1] == NULL) {
emilmont 6:350b53afb889 206 /* Task with "task_id" not found or not started. */
emilmont 6:350b53afb889 207 return (OS_R_NOK);
emilmont 6:350b53afb889 208 }
emilmont 6:350b53afb889 209 p_task = os_active_TCB[task_id-1];
emilmont 6:350b53afb889 210 p_task->prio = new_prio;
emilmont 6:350b53afb889 211 if (p_task == os_tsk.run) {
emilmont 6:350b53afb889 212 goto run;
emilmont 6:350b53afb889 213 }
emilmont 6:350b53afb889 214 rt_resort_prio (p_task);
emilmont 6:350b53afb889 215 if (p_task->state == READY) {
emilmont 6:350b53afb889 216 /* Task enqueued in a ready list. */
emilmont 6:350b53afb889 217 p_task = rt_get_first (&os_rdy);
emilmont 6:350b53afb889 218 rt_dispatch (p_task);
emilmont 6:350b53afb889 219 }
emilmont 6:350b53afb889 220 return (OS_R_OK);
emilmont 6:350b53afb889 221 }
emilmont 6:350b53afb889 222
emilmont 6:350b53afb889 223 /*--------------------------- rt_tsk_delete ---------------------------------*/
emilmont 6:350b53afb889 224
emilmont 6:350b53afb889 225 OS_RESULT rt_tsk_delete (OS_TID task_id) {
emilmont 6:350b53afb889 226 /* Terminate the task identified with "task_id". */
emilmont 6:350b53afb889 227 P_TCB task_context;
emilmont 6:350b53afb889 228
emilmont 6:350b53afb889 229 if (task_id == 0 || task_id == os_tsk.run->task_id) {
emilmont 6:350b53afb889 230 /* Terminate itself. */
emilmont 6:350b53afb889 231 os_tsk.run->state = INACTIVE;
emilmont 6:350b53afb889 232 os_tsk.run->tsk_stack = rt_get_PSP ();
emilmont 6:350b53afb889 233 rt_stk_check ();
emilmont 6:350b53afb889 234 os_active_TCB[os_tsk.run->task_id-1] = NULL;
emilmont 6:350b53afb889 235
emilmont 6:350b53afb889 236 os_tsk.run->stack = NULL;
emilmont 6:350b53afb889 237 DBG_TASK_NOTIFY(os_tsk.run, __FALSE);
emilmont 6:350b53afb889 238 os_tsk.run = NULL;
emilmont 6:350b53afb889 239 rt_dispatch (NULL);
emilmont 6:350b53afb889 240 /* The program should never come to this point. */
emilmont 6:350b53afb889 241 }
emilmont 6:350b53afb889 242 else {
emilmont 6:350b53afb889 243 /* Find the task in the "os_active_TCB" array. */
emilmont 6:350b53afb889 244 if (task_id > os_maxtaskrun || os_active_TCB[task_id-1] == NULL) {
emilmont 6:350b53afb889 245 /* Task with "task_id" not found or not started. */
emilmont 6:350b53afb889 246 return (OS_R_NOK);
emilmont 6:350b53afb889 247 }
emilmont 6:350b53afb889 248 task_context = os_active_TCB[task_id-1];
emilmont 6:350b53afb889 249 rt_rmv_list (task_context);
emilmont 6:350b53afb889 250 rt_rmv_dly (task_context);
emilmont 6:350b53afb889 251 os_active_TCB[task_id-1] = NULL;
emilmont 6:350b53afb889 252
emilmont 6:350b53afb889 253 task_context->stack = NULL;
emilmont 6:350b53afb889 254 DBG_TASK_NOTIFY(task_context, __FALSE);
emilmont 6:350b53afb889 255 }
emilmont 6:350b53afb889 256 return (OS_R_OK);
emilmont 6:350b53afb889 257 }
emilmont 6:350b53afb889 258
emilmont 6:350b53afb889 259
emilmont 6:350b53afb889 260 /*--------------------------- rt_sys_init -----------------------------------*/
emilmont 6:350b53afb889 261
emilmont 6:350b53afb889 262 #ifdef __CMSIS_RTOS
emilmont 6:350b53afb889 263 void rt_sys_init (void) {
emilmont 6:350b53afb889 264 #else
emilmont 6:350b53afb889 265 void rt_sys_init (FUNCP first_task, U32 prio_stksz, void *stk) {
emilmont 6:350b53afb889 266 #endif
emilmont 6:350b53afb889 267 /* Initialize system and start up task declared with "first_task". */
emilmont 6:350b53afb889 268 U32 i;
emilmont 6:350b53afb889 269
emilmont 6:350b53afb889 270 DBG_INIT();
emilmont 6:350b53afb889 271
emilmont 6:350b53afb889 272 /* Initialize dynamic memory and task TCB pointers to NULL. */
emilmont 6:350b53afb889 273 for (i = 0; i < os_maxtaskrun; i++) {
emilmont 6:350b53afb889 274 os_active_TCB[i] = NULL;
emilmont 6:350b53afb889 275 }
emilmont 6:350b53afb889 276
emilmont 6:350b53afb889 277 /* Set up TCB of idle demon */
emilmont 6:350b53afb889 278 os_idle_TCB.task_id = 255;
emilmont 6:350b53afb889 279 os_idle_TCB.priv_stack = idle_task_stack_size;
emilmont 6:350b53afb889 280 os_idle_TCB.stack = idle_task_stack;
emilmont 6:350b53afb889 281 rt_init_context (&os_idle_TCB, 0, os_idle_demon);
emilmont 6:350b53afb889 282
emilmont 6:350b53afb889 283 /* Set up ready list: initially empty */
emilmont 6:350b53afb889 284 os_rdy.cb_type = HCB;
emilmont 6:350b53afb889 285 os_rdy.p_lnk = NULL;
emilmont 6:350b53afb889 286 /* Set up delay list: initially empty */
emilmont 6:350b53afb889 287 os_dly.cb_type = HCB;
emilmont 6:350b53afb889 288 os_dly.p_dlnk = NULL;
emilmont 6:350b53afb889 289 os_dly.p_blnk = NULL;
emilmont 6:350b53afb889 290 os_dly.delta_time = 0;
emilmont 6:350b53afb889 291
emilmont 6:350b53afb889 292 /* Fix SP and systemvariables to assume idle task is running */
emilmont 6:350b53afb889 293 /* Transform main program into idle task by assuming idle TCB */
emilmont 6:350b53afb889 294 #ifndef __CMSIS_RTOS
emilmont 6:350b53afb889 295 rt_set_PSP (os_idle_TCB.tsk_stack+32);
emilmont 6:350b53afb889 296 #endif
emilmont 6:350b53afb889 297 os_tsk.run = &os_idle_TCB;
emilmont 6:350b53afb889 298 os_tsk.run->state = RUNNING;
emilmont 6:350b53afb889 299
emilmont 6:350b53afb889 300 /* Initialize ps queue */
emilmont 6:350b53afb889 301 os_psq->first = 0;
emilmont 6:350b53afb889 302 os_psq->last = 0;
emilmont 6:350b53afb889 303 os_psq->size = os_fifo_size;
emilmont 6:350b53afb889 304
emilmont 6:350b53afb889 305 rt_init_robin ();
emilmont 6:350b53afb889 306
emilmont 6:350b53afb889 307 /* Intitialize SVC and PendSV */
emilmont 6:350b53afb889 308 rt_svc_init ();
emilmont 6:350b53afb889 309
emilmont 6:350b53afb889 310 #ifndef __CMSIS_RTOS
emilmont 6:350b53afb889 311 /* Intitialize and start system clock timer */
emilmont 6:350b53afb889 312 os_tick_irqn = os_tick_init ();
emilmont 6:350b53afb889 313 if (os_tick_irqn >= 0) {
emilmont 6:350b53afb889 314 OS_X_INIT(os_tick_irqn);
emilmont 6:350b53afb889 315 }
emilmont 6:350b53afb889 316
emilmont 6:350b53afb889 317 /* Start up first user task before entering the endless loop */
emilmont 6:350b53afb889 318 rt_tsk_create (first_task, prio_stksz, stk, NULL);
emilmont 6:350b53afb889 319 #endif
emilmont 6:350b53afb889 320 }
emilmont 6:350b53afb889 321
emilmont 6:350b53afb889 322
emilmont 6:350b53afb889 323 /*--------------------------- rt_sys_start ----------------------------------*/
emilmont 6:350b53afb889 324
emilmont 6:350b53afb889 325 #ifdef __CMSIS_RTOS
emilmont 6:350b53afb889 326 void rt_sys_start (void) {
emilmont 6:350b53afb889 327 /* Start system */
emilmont 6:350b53afb889 328
emilmont 6:350b53afb889 329 /* Intitialize and start system clock timer */
emilmont 6:350b53afb889 330 os_tick_irqn = os_tick_init ();
emilmont 6:350b53afb889 331 if (os_tick_irqn >= 0) {
emilmont 6:350b53afb889 332 OS_X_INIT(os_tick_irqn);
emilmont 6:350b53afb889 333 }
emilmont 6:350b53afb889 334 }
emilmont 6:350b53afb889 335 #endif
emilmont 6:350b53afb889 336
emilmont 6:350b53afb889 337 /*----------------------------------------------------------------------------
emilmont 6:350b53afb889 338 * end of file
emilmont 6:350b53afb889 339 *---------------------------------------------------------------------------*/