Subversion Repositories HelenOS-historic

Rev

Rev 1380 | Rev 1702 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed

  1. /*
  2.  * Copyright (C) 2001-2004 Jakub Jermar
  3.  * All rights reserved.
  4.  *
  5.  * Redistribution and use in source and binary forms, with or without
  6.  * modification, are permitted provided that the following conditions
  7.  * are met:
  8.  *
  9.  * - Redistributions of source code must retain the above copyright
  10.  *   notice, this list of conditions and the following disclaimer.
  11.  * - Redistributions in binary form must reproduce the above copyright
  12.  *   notice, this list of conditions and the following disclaimer in the
  13.  *   documentation and/or other materials provided with the distribution.
  14.  * - The name of the author may not be used to endorse or promote products
  15.  *   derived from this software without specific prior written permission.
  16.  *
  17.  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18.  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20.  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21.  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22.  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26.  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27.  */
  28.  
  29. /**
  30.  * @file    scheduler.c
  31.  * @brief   Scheduler and load balancing.
  32.  *
  33.  * This file contains the scheduler and kcpulb kernel thread which
  34.  * performs load-balancing of per-CPU run queues.
  35.  */
  36.  
  37. #include <proc/scheduler.h>
  38. #include <proc/thread.h>
  39. #include <proc/task.h>
  40. #include <mm/frame.h>
  41. #include <mm/page.h>
  42. #include <mm/as.h>
  43. #include <time/delay.h>
  44. #include <arch/asm.h>
  45. #include <arch/faddr.h>
  46. #include <atomic.h>
  47. #include <synch/spinlock.h>
  48. #include <config.h>
  49. #include <context.h>
  50. #include <func.h>
  51. #include <arch.h>
  52. #include <adt/list.h>
  53. #include <panic.h>
  54. #include <typedefs.h>
  55. #include <cpu.h>
  56. #include <print.h>
  57. #include <debug.h>
  58.  
  59. static void before_task_runs(void);
  60. static void before_thread_runs(void);
  61. static void after_thread_ran(void);
  62. static void scheduler_separated_stack(void);
  63.  
  64. atomic_t nrdy;  /**< Number of ready threads in the system. */
  65.  
  66. /** Carry out actions before new task runs. */
  67. void before_task_runs(void)
  68. {
  69.     before_task_runs_arch();
  70. }
  71.  
  72. /** Take actions before new thread runs.
  73.  *
  74.  * Perform actions that need to be
  75.  * taken before the newly selected
  76.  * tread is passed control.
  77.  *
  78.  * THREAD->lock is locked on entry
  79.  *
  80.  */
  81. void before_thread_runs(void)
  82. {
  83.     before_thread_runs_arch();
  84. #ifdef CONFIG_FPU_LAZY
  85.     if(THREAD==CPU->fpu_owner)
  86.         fpu_enable();
  87.     else
  88.         fpu_disable();
  89. #else
  90.     fpu_enable();
  91.     if (THREAD->fpu_context_exists)
  92.         fpu_context_restore(THREAD->saved_fpu_context);
  93.     else {
  94.         fpu_init();
  95.         THREAD->fpu_context_exists=1;
  96.     }
  97. #endif
  98. }
  99.  
  100. /** Take actions after THREAD had run.
  101.  *
  102.  * Perform actions that need to be
  103.  * taken after the running thread
  104.  * had been preempted by the scheduler.
  105.  *
  106.  * THREAD->lock is locked on entry
  107.  *
  108.  */
  109. void after_thread_ran(void)
  110. {
  111.     after_thread_ran_arch();
  112. }
  113.  
  114. #ifdef CONFIG_FPU_LAZY
  115. void scheduler_fpu_lazy_request(void)
  116. {
  117. restart:
  118.     fpu_enable();
  119.     spinlock_lock(&CPU->lock);
  120.  
  121.     /* Save old context */
  122.     if (CPU->fpu_owner != NULL) {  
  123.         spinlock_lock(&CPU->fpu_owner->lock);
  124.         fpu_context_save(CPU->fpu_owner->saved_fpu_context);
  125.         /* don't prevent migration */
  126.         CPU->fpu_owner->fpu_context_engaged=0;
  127.         spinlock_unlock(&CPU->fpu_owner->lock);
  128.         CPU->fpu_owner = NULL;
  129.     }
  130.  
  131.     spinlock_lock(&THREAD->lock);
  132.     if (THREAD->fpu_context_exists) {
  133.         fpu_context_restore(THREAD->saved_fpu_context);
  134.     } else {
  135.         /* Allocate FPU context */
  136.         if (!THREAD->saved_fpu_context) {
  137.             /* Might sleep */
  138.             spinlock_unlock(&THREAD->lock);
  139.             spinlock_unlock(&CPU->lock);
  140.             THREAD->saved_fpu_context = slab_alloc(fpu_context_slab,
  141.                                    0);
  142.             /* We may have switched CPUs during slab_alloc */
  143.             goto restart;
  144.         }
  145.         fpu_init();
  146.         THREAD->fpu_context_exists=1;
  147.     }
  148.     CPU->fpu_owner=THREAD;
  149.     THREAD->fpu_context_engaged = 1;
  150.     spinlock_unlock(&THREAD->lock);
  151.  
  152.     spinlock_unlock(&CPU->lock);
  153. }
  154. #endif
  155.  
  156. /** Initialize scheduler
  157.  *
  158.  * Initialize kernel scheduler.
  159.  *
  160.  */
  161. void scheduler_init(void)
  162. {
  163. }
  164.  
  165. /** Get thread to be scheduled
  166.  *
  167.  * Get the optimal thread to be scheduled
  168.  * according to thread accounting and scheduler
  169.  * policy.
  170.  *
  171.  * @return Thread to be scheduled.
  172.  *
  173.  */
  174. static thread_t *find_best_thread(void)
  175. {
  176.     thread_t *t;
  177.     runq_t *r;
  178.     int i;
  179.  
  180.     ASSERT(CPU != NULL);
  181.  
  182. loop:
  183.     interrupts_enable();
  184.    
  185.     if (atomic_get(&CPU->nrdy) == 0) {
  186.         /*
  187.          * For there was nothing to run, the CPU goes to sleep
  188.          * until a hardware interrupt or an IPI comes.
  189.          * This improves energy saving and hyperthreading.
  190.          */
  191.  
  192.         /*
  193.          * An interrupt might occur right now and wake up a thread.
  194.          * In such case, the CPU will continue to go to sleep
  195.          * even though there is a runnable thread.
  196.          */
  197.  
  198.          cpu_sleep();
  199.          goto loop;
  200.     }
  201.  
  202.     interrupts_disable();
  203.    
  204.     for (i = 0; i<RQ_COUNT; i++) {
  205.         r = &CPU->rq[i];
  206.         spinlock_lock(&r->lock);
  207.         if (r->n == 0) {
  208.             /*
  209.              * If this queue is empty, try a lower-priority queue.
  210.              */
  211.             spinlock_unlock(&r->lock);
  212.             continue;
  213.         }
  214.  
  215.         atomic_dec(&CPU->nrdy);
  216.         atomic_dec(&nrdy);
  217.         r->n--;
  218.  
  219.         /*
  220.          * Take the first thread from the queue.
  221.          */
  222.         t = list_get_instance(r->rq_head.next, thread_t, rq_link);
  223.         list_remove(&t->rq_link);
  224.  
  225.         spinlock_unlock(&r->lock);
  226.  
  227.         spinlock_lock(&t->lock);
  228.         t->cpu = CPU;
  229.  
  230.         t->ticks = us2ticks((i+1)*10000);
  231.         t->priority = i;    /* correct rq index */
  232.  
  233.         /*
  234.          * Clear the X_STOLEN flag so that t can be migrated when load balancing needs emerge.
  235.          */
  236.         t->flags &= ~X_STOLEN;
  237.         spinlock_unlock(&t->lock);
  238.  
  239.         return t;
  240.     }
  241.     goto loop;
  242.  
  243. }
  244.  
  245. /** Prevent rq starvation
  246.  *
  247.  * Prevent low priority threads from starving in rq's.
  248.  *
  249.  * When the function decides to relink rq's, it reconnects
  250.  * respective pointers so that in result threads with 'pri'
  251.  * greater or equal @start are moved to a higher-priority queue.
  252.  *
  253.  * @param start Threshold priority.
  254.  *
  255.  */
  256. static void relink_rq(int start)
  257. {
  258.     link_t head;
  259.     runq_t *r;
  260.     int i, n;
  261.  
  262.     list_initialize(&head);
  263.     spinlock_lock(&CPU->lock);
  264.     if (CPU->needs_relink > NEEDS_RELINK_MAX) {
  265.         for (i = start; i<RQ_COUNT-1; i++) {
  266.             /* remember and empty rq[i + 1] */
  267.             r = &CPU->rq[i + 1];
  268.             spinlock_lock(&r->lock);
  269.             list_concat(&head, &r->rq_head);
  270.             n = r->n;
  271.             r->n = 0;
  272.             spinlock_unlock(&r->lock);
  273.        
  274.             /* append rq[i + 1] to rq[i] */
  275.             r = &CPU->rq[i];
  276.             spinlock_lock(&r->lock);
  277.             list_concat(&r->rq_head, &head);
  278.             r->n += n;
  279.             spinlock_unlock(&r->lock);
  280.         }
  281.         CPU->needs_relink = 0;
  282.     }
  283.     spinlock_unlock(&CPU->lock);
  284.  
  285. }
  286.  
  287. /** The scheduler
  288.  *
  289.  * The thread scheduling procedure.
  290.  * Passes control directly to
  291.  * scheduler_separated_stack().
  292.  *
  293.  */
  294. void scheduler(void)
  295. {
  296.     volatile ipl_t ipl;
  297.  
  298.     ASSERT(CPU != NULL);
  299.  
  300.     ipl = interrupts_disable();
  301.  
  302.     if (atomic_get(&haltstate))
  303.         halt();
  304.    
  305.     if (THREAD) {
  306.         spinlock_lock(&THREAD->lock);
  307. #ifndef CONFIG_FPU_LAZY
  308.         fpu_context_save(THREAD->saved_fpu_context);
  309. #endif
  310.         if (!context_save(&THREAD->saved_context)) {
  311.             /*
  312.              * This is the place where threads leave scheduler();
  313.              */
  314.             spinlock_unlock(&THREAD->lock);
  315.             interrupts_restore(THREAD->saved_context.ipl);
  316.            
  317.             return;
  318.         }
  319.  
  320.         /*
  321.          * Interrupt priority level of preempted thread is recorded here
  322.          * to facilitate scheduler() invocations from interrupts_disable()'d
  323.          * code (e.g. waitq_sleep_timeout()).
  324.          */
  325.         THREAD->saved_context.ipl = ipl;
  326.     }
  327.  
  328.     /*
  329.      * Through the 'THE' structure, we keep track of THREAD, TASK, CPU, VM
  330.      * and preemption counter. At this point THE could be coming either
  331.      * from THREAD's or CPU's stack.
  332.      */
  333.     the_copy(THE, (the_t *) CPU->stack);
  334.  
  335.     /*
  336.      * We may not keep the old stack.
  337.      * Reason: If we kept the old stack and got blocked, for instance, in
  338.      * find_best_thread(), the old thread could get rescheduled by another
  339.      * CPU and overwrite the part of its own stack that was also used by
  340.      * the scheduler on this CPU.
  341.      *
  342.      * Moreover, we have to bypass the compiler-generated POP sequence
  343.      * which is fooled by SP being set to the very top of the stack.
  344.      * Therefore the scheduler() function continues in
  345.      * scheduler_separated_stack().
  346.      */
  347.     context_save(&CPU->saved_context);
  348.     context_set(&CPU->saved_context, FADDR(scheduler_separated_stack), (__address) CPU->stack, CPU_STACK_SIZE);
  349.     context_restore(&CPU->saved_context);
  350.     /* not reached */
  351. }
  352.  
  353. /** Scheduler stack switch wrapper
  354.  *
  355.  * Second part of the scheduler() function
  356.  * using new stack. Handling the actual context
  357.  * switch to a new thread.
  358.  *
  359.  * Assume THREAD->lock is held.
  360.  */
  361. void scheduler_separated_stack(void)
  362. {
  363.     int priority;
  364.    
  365.     ASSERT(CPU != NULL);
  366.    
  367.     if (THREAD) {
  368.         /* must be run after the switch to scheduler stack */
  369.         after_thread_ran();
  370.  
  371.         switch (THREAD->state) {
  372.             case Running:
  373.             spinlock_unlock(&THREAD->lock);
  374.             thread_ready(THREAD);
  375.             break;
  376.  
  377.             case Exiting:
  378. repeat:
  379.                 if (THREAD->detached) {
  380.                 thread_destroy(THREAD);
  381.             } else {
  382.                 /*
  383.                  * The thread structure is kept allocated until somebody
  384.                  * calls thread_detach() on it.
  385.                  */
  386.                 if (!spinlock_trylock(&THREAD->join_wq.lock)) {
  387.                     /*
  388.                      * Avoid deadlock.
  389.                      */
  390.                     spinlock_unlock(&THREAD->lock);
  391.                     delay(10);
  392.                     spinlock_lock(&THREAD->lock);
  393.                     goto repeat;
  394.                 }
  395.                 _waitq_wakeup_unsafe(&THREAD->join_wq, false);
  396.                 spinlock_unlock(&THREAD->join_wq.lock);
  397.                
  398.                 THREAD->state = Undead;
  399.                 spinlock_unlock(&THREAD->lock);
  400.             }
  401.             break;
  402.            
  403.             case Sleeping:
  404.             /*
  405.              * Prefer the thread after it's woken up.
  406.              */
  407.             THREAD->priority = -1;
  408.  
  409.             /*
  410.              * We need to release wq->lock which we locked in waitq_sleep().
  411.              * Address of wq->lock is kept in THREAD->sleep_queue.
  412.              */
  413.             spinlock_unlock(&THREAD->sleep_queue->lock);
  414.  
  415.             /*
  416.              * Check for possible requests for out-of-context invocation.
  417.              */
  418.             if (THREAD->call_me) {
  419.                 THREAD->call_me(THREAD->call_me_with);
  420.                 THREAD->call_me = NULL;
  421.                 THREAD->call_me_with = NULL;
  422.             }
  423.  
  424.             spinlock_unlock(&THREAD->lock);
  425.  
  426.             break;
  427.  
  428.             default:
  429.             /*
  430.              * Entering state is unexpected.
  431.              */
  432.             panic("tid%d: unexpected state %s\n", THREAD->tid, thread_states[THREAD->state]);
  433.             break;
  434.         }
  435.  
  436.         THREAD = NULL;
  437.     }
  438.  
  439.     THREAD = find_best_thread();
  440.    
  441.     spinlock_lock(&THREAD->lock);
  442.     priority = THREAD->priority;
  443.     spinlock_unlock(&THREAD->lock);
  444.  
  445.     relink_rq(priority);       
  446.  
  447.     /*
  448.      * If both the old and the new task are the same, lots of work is avoided.
  449.      */
  450.     if (TASK != THREAD->task) {
  451.         as_t *as1 = NULL;
  452.         as_t *as2;
  453.  
  454.         if (TASK) {
  455.             spinlock_lock(&TASK->lock);
  456.             as1 = TASK->as;
  457.             spinlock_unlock(&TASK->lock);
  458.         }
  459.  
  460.         spinlock_lock(&THREAD->task->lock);
  461.         as2 = THREAD->task->as;
  462.         spinlock_unlock(&THREAD->task->lock);
  463.        
  464.         /*
  465.          * Note that it is possible for two tasks to share one address space.
  466.          */
  467.         if (as1 != as2) {
  468.             /*
  469.              * Both tasks and address spaces are different.
  470.              * Replace the old one with the new one.
  471.              */
  472.             as_switch(as1, as2);
  473.         }
  474.         TASK = THREAD->task;
  475.         before_task_runs();
  476.     }
  477.  
  478.     spinlock_lock(&THREAD->lock);  
  479.     THREAD->state = Running;
  480.  
  481. #ifdef SCHEDULER_VERBOSE
  482.     printf("cpu%d: tid %d (priority=%d,ticks=%lld,nrdy=%ld)\n", CPU->id, THREAD->tid, THREAD->priority, THREAD->ticks, atomic_get(&CPU->nrdy));
  483. #endif 
  484.  
  485.     /*
  486.      * Some architectures provide late kernel PA2KA(identity)
  487.      * mapping in a page fault handler. However, the page fault
  488.      * handler uses the kernel stack of the running thread and
  489.      * therefore cannot be used to map it. The kernel stack, if
  490.      * necessary, is to be mapped in before_thread_runs(). This
  491.      * function must be executed before the switch to the new stack.
  492.      */
  493.     before_thread_runs();
  494.  
  495.     /*
  496.      * Copy the knowledge of CPU, TASK, THREAD and preemption counter to thread's stack.
  497.      */
  498.     the_copy(THE, (the_t *) THREAD->kstack);
  499.    
  500.     context_restore(&THREAD->saved_context);
  501.     /* not reached */
  502. }
  503.  
  504. #ifdef CONFIG_SMP
  505. /** Load balancing thread
  506.  *
  507.  * SMP load balancing thread, supervising thread supplies
  508.  * for the CPU it's wired to.
  509.  *
  510.  * @param arg Generic thread argument (unused).
  511.  *
  512.  */
  513. void kcpulb(void *arg)
  514. {
  515.     thread_t *t;
  516.     int count, average, i, j, k = 0;
  517.     ipl_t ipl;
  518.  
  519. loop:
  520.     /*
  521.      * Work in 1s intervals.
  522.      */
  523.     thread_sleep(1);
  524.  
  525. not_satisfied:
  526.     /*
  527.      * Calculate the number of threads that will be migrated/stolen from
  528.      * other CPU's. Note that situation can have changed between two
  529.      * passes. Each time get the most up to date counts.
  530.      */
  531.     average = atomic_get(&nrdy) / config.cpu_active + 1;
  532.     count = average - atomic_get(&CPU->nrdy);
  533.  
  534.     if (count <= 0)
  535.         goto satisfied;
  536.  
  537.     /*
  538.      * Searching least priority queues on all CPU's first and most priority queues on all CPU's last.
  539.      */
  540.     for (j=RQ_COUNT-1; j >= 0; j--) {
  541.         for (i=0; i < config.cpu_active; i++) {
  542.             link_t *l;
  543.             runq_t *r;
  544.             cpu_t *cpu;
  545.  
  546.             cpu = &cpus[(i + k) % config.cpu_active];
  547.  
  548.             /*
  549.              * Not interested in ourselves.
  550.              * Doesn't require interrupt disabling for kcpulb is X_WIRED.
  551.              */
  552.             if (CPU == cpu)
  553.                 continue;
  554.             if (atomic_get(&cpu->nrdy) <= average)
  555.                 continue;
  556.  
  557.             ipl = interrupts_disable();
  558.             r = &cpu->rq[j];
  559.             spinlock_lock(&r->lock);
  560.             if (r->n == 0) {
  561.                 spinlock_unlock(&r->lock);
  562.                 interrupts_restore(ipl);
  563.                 continue;
  564.             }
  565.        
  566.             t = NULL;
  567.             l = r->rq_head.prev;    /* search rq from the back */
  568.             while (l != &r->rq_head) {
  569.                 t = list_get_instance(l, thread_t, rq_link);
  570.                 /*
  571.                  * We don't want to steal CPU-wired threads neither threads already stolen.
  572.                  * The latter prevents threads from migrating between CPU's without ever being run.
  573.                  * We don't want to steal threads whose FPU context is still in CPU.
  574.                  */
  575.                 spinlock_lock(&t->lock);
  576.                 if ( (!(t->flags & (X_WIRED | X_STOLEN))) && (!(t->fpu_context_engaged)) ) {
  577.                     /*
  578.                      * Remove t from r.
  579.                      */
  580.                     spinlock_unlock(&t->lock);
  581.                    
  582.                     atomic_dec(&cpu->nrdy);
  583.                     atomic_dec(&nrdy);
  584.  
  585.                     r->n--;
  586.                     list_remove(&t->rq_link);
  587.  
  588.                     break;
  589.                 }
  590.                 spinlock_unlock(&t->lock);
  591.                 l = l->prev;
  592.                 t = NULL;
  593.             }
  594.             spinlock_unlock(&r->lock);
  595.  
  596.             if (t) {
  597.                 /*
  598.                  * Ready t on local CPU
  599.                  */
  600.                 spinlock_lock(&t->lock);
  601. #ifdef KCPULB_VERBOSE
  602.                 printf("kcpulb%d: TID %d -> cpu%d, nrdy=%ld, avg=%nd\n", CPU->id, t->tid, CPU->id, atomic_get(&CPU->nrdy), atomic_get(&nrdy) / config.cpu_active);
  603. #endif
  604.                 t->flags |= X_STOLEN;
  605.                 t->state = Entering;
  606.                 spinlock_unlock(&t->lock);
  607.    
  608.                 thread_ready(t);
  609.  
  610.                 interrupts_restore(ipl);
  611.    
  612.                 if (--count == 0)
  613.                     goto satisfied;
  614.                    
  615.                 /*
  616.                  * We are not satisfied yet, focus on another CPU next time.
  617.                  */
  618.                 k++;
  619.                
  620.                 continue;
  621.             }
  622.             interrupts_restore(ipl);
  623.         }
  624.     }
  625.  
  626.     if (atomic_get(&CPU->nrdy)) {
  627.         /*
  628.          * Be a little bit light-weight and let migrated threads run.
  629.          */
  630.         scheduler();
  631.     } else {
  632.         /*
  633.          * We failed to migrate a single thread.
  634.          * Give up this turn.
  635.          */
  636.         goto loop;
  637.     }
  638.        
  639.     goto not_satisfied;
  640.  
  641. satisfied:
  642.     goto loop;
  643. }
  644.  
  645. #endif /* CONFIG_SMP */
  646.  
  647.  
  648. /** Print information about threads & scheduler queues */
  649. void sched_print_list(void)
  650. {
  651.     ipl_t ipl;
  652.     int cpu,i;
  653.     runq_t *r;
  654.     thread_t *t;
  655.     link_t *cur;
  656.  
  657.     /* We are going to mess with scheduler structures,
  658.      * let's not be interrupted */
  659.     ipl = interrupts_disable();
  660.     for (cpu=0;cpu < config.cpu_count; cpu++) {
  661.  
  662.         if (!cpus[cpu].active)
  663.             continue;
  664.  
  665.         spinlock_lock(&cpus[cpu].lock);
  666.         printf("cpu%d: address=%p, nrdy=%ld, needs_relink=%ld\n",
  667.                cpus[cpu].id, &cpus[cpu], atomic_get(&cpus[cpu].nrdy), cpus[cpu].needs_relink);
  668.        
  669.         for (i=0; i<RQ_COUNT; i++) {
  670.             r = &cpus[cpu].rq[i];
  671.             spinlock_lock(&r->lock);
  672.             if (!r->n) {
  673.                 spinlock_unlock(&r->lock);
  674.                 continue;
  675.             }
  676.             printf("\trq[%d]: ", i);
  677.             for (cur=r->rq_head.next; cur!=&r->rq_head; cur=cur->next) {
  678.                 t = list_get_instance(cur, thread_t, rq_link);
  679.                 printf("%d(%s) ", t->tid,
  680.                        thread_states[t->state]);
  681.             }
  682.             printf("\n");
  683.             spinlock_unlock(&r->lock);
  684.         }
  685.         spinlock_unlock(&cpus[cpu].lock);
  686.     }
  687.    
  688.     interrupts_restore(ipl);
  689. }
  690.