Subversion Repositories HelenOS

Rev

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

  1. /*
  2.  * Copyright (c) 2006 Ondrej Palkovsky
  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. /** @addtogroup genericipc
  30.  * @{
  31.  */
  32. /** @file
  33.  */
  34.  
  35. /* Lock ordering
  36.  *
  37.  * First the answerbox, then the phone.
  38.  */
  39.  
  40. #include <synch/spinlock.h>
  41. #include <synch/waitq.h>
  42. #include <synch/synch.h>
  43. #include <ipc/ipc.h>
  44. #include <errno.h>
  45. #include <mm/slab.h>
  46. #include <arch.h>
  47. #include <proc/task.h>
  48. #include <memstr.h>
  49. #include <debug.h>
  50.  
  51. #include <print.h>
  52. #include <proc/thread.h>
  53. #include <arch/interrupt.h>
  54. #include <ipc/irq.h>
  55.  
  56. /** Open channel that is assigned automatically to new tasks */
  57. answerbox_t *ipc_phone_0 = NULL;
  58.  
  59. static slab_cache_t *ipc_call_slab;
  60.  
  61. /** Initialize a call structure.
  62.  *
  63.  * @param call      Call structure to be initialized.
  64.  */
  65. static void _ipc_call_init(call_t *call)
  66. {
  67.     memsetb((uintptr_t) call, sizeof(*call), 0);
  68.     call->callerbox = &TASK->answerbox;
  69.     call->sender = TASK;
  70.     call->buffer = NULL;
  71. }
  72.  
  73. /** Allocate and initialize a call structure.
  74.  *
  75.  * The call is initialized, so that the reply will be directed to
  76.  * TASK->answerbox.
  77.  *
  78.  * @param flags     Parameters for slab_alloc (e.g FRAME_ATOMIC).
  79.  *
  80.  * @return      If flags permit it, return NULL, or initialized kernel
  81.  *          call structure.
  82.  */
  83. call_t *ipc_call_alloc(int flags)
  84. {
  85.     call_t *call;
  86.  
  87.     call = slab_alloc(ipc_call_slab, flags);
  88.     _ipc_call_init(call);
  89.  
  90.     return call;
  91. }
  92.  
  93. /** Initialize a statically allocated call structure.
  94.  *
  95.  * @param call      Statically allocated kernel call structure to be
  96.  *          initialized.
  97.  */
  98. void ipc_call_static_init(call_t *call)
  99. {
  100.     _ipc_call_init(call);
  101.     call->flags |= IPC_CALL_STATIC_ALLOC;
  102. }
  103.  
  104. /** Deallocate a call structure.
  105.  *
  106.  * @param call      Call structure to be freed.
  107.  */
  108. void ipc_call_free(call_t *call)
  109. {
  110.     ASSERT(!(call->flags & IPC_CALL_STATIC_ALLOC));
  111.     /* Check to see if we have data in the IPC_M_DATA_SEND buffer. */
  112.     if (call->buffer)
  113.         free(call->buffer);
  114.     slab_free(ipc_call_slab, call);
  115. }
  116.  
  117. /** Initialize an answerbox structure.
  118.  *
  119.  * @param box       Answerbox structure to be initialized.
  120.  */
  121. void ipc_answerbox_init(answerbox_t *box)
  122. {
  123.     spinlock_initialize(&box->lock, "ipc_box_lock");
  124.     spinlock_initialize(&box->irq_lock, "ipc_box_irqlock");
  125.     waitq_initialize(&box->wq);
  126.     list_initialize(&box->connected_phones);
  127.     list_initialize(&box->calls);
  128.     list_initialize(&box->dispatched_calls);
  129.     list_initialize(&box->answers);
  130.     list_initialize(&box->irq_notifs);
  131.     list_initialize(&box->irq_head);
  132.     box->task = TASK;
  133. }
  134.  
  135. /** Connect a phone to an answerbox.
  136.  *
  137.  * @param phone     Initialized phone structure.
  138.  * @param box       Initialized answerbox structure.
  139.  */
  140. void ipc_phone_connect(phone_t *phone, answerbox_t *box)
  141. {
  142.     spinlock_lock(&phone->lock);
  143.  
  144.     phone->state = IPC_PHONE_CONNECTED;
  145.     phone->callee = box;
  146.  
  147.     spinlock_lock(&box->lock);
  148.     list_append(&phone->link, &box->connected_phones);
  149.     spinlock_unlock(&box->lock);
  150.  
  151.     spinlock_unlock(&phone->lock);
  152. }
  153.  
  154. /** Initialize a phone structure.
  155.  *
  156.  * @param phone     Phone structure to be initialized.
  157.  */
  158. void ipc_phone_init(phone_t *phone)
  159. {
  160.     spinlock_initialize(&phone->lock, "phone_lock");
  161.     phone->callee = NULL;
  162.     phone->state = IPC_PHONE_FREE;
  163.     atomic_set(&phone->active_calls, 0);
  164. }
  165.  
  166. /** Helper function to facilitate synchronous calls.
  167.  *
  168.  * @param phone     Destination kernel phone structure.
  169.  * @param request   Call structure with request.
  170.  */
  171. void ipc_call_sync(phone_t *phone, call_t *request)
  172. {
  173.     answerbox_t sync_box;
  174.  
  175.     ipc_answerbox_init(&sync_box);
  176.  
  177.     /* We will receive data in a special box. */
  178.     request->callerbox = &sync_box;
  179.  
  180.     ipc_call(phone, request);
  181.     ipc_wait_for_call(&sync_box, SYNCH_NO_TIMEOUT, SYNCH_FLAGS_NONE);
  182. }
  183.  
  184. /** Answer a message which was not dispatched and is not listed in any queue.
  185.  *
  186.  * @param call      Call structure to be answered.
  187.  */
  188. static void _ipc_answer_free_call(call_t *call)
  189. {
  190.     answerbox_t *callerbox = call->callerbox;
  191.  
  192.     call->flags |= IPC_CALL_ANSWERED;
  193.  
  194.     spinlock_lock(&callerbox->lock);
  195.     list_append(&call->link, &callerbox->answers);
  196.     spinlock_unlock(&callerbox->lock);
  197.     waitq_wakeup(&callerbox->wq, WAKEUP_FIRST);
  198. }
  199.  
  200. /** Answer a message which is in a callee queue.
  201.  *
  202.  * @param box       Answerbox that is answering the message.
  203.  * @param call      Modified request that is being sent back.
  204.  */
  205. void ipc_answer(answerbox_t *box, call_t *call)
  206. {
  207.     /* Remove from active box */
  208.     spinlock_lock(&box->lock);
  209.     list_remove(&call->link);
  210.     spinlock_unlock(&box->lock);
  211.     /* Send back answer */
  212.     _ipc_answer_free_call(call);
  213. }
  214.  
  215. /** Simulate sending back a message.
  216.  *
  217.  * Most errors are better handled by forming a normal backward
  218.  * message and sending it as a normal answer.
  219.  *
  220.  * @param phone     Phone structure the call should appear to come from.
  221.  * @param call      Call structure to be answered.
  222.  * @param err       Return value to be used for the answer.
  223.  */
  224. void ipc_backsend_err(phone_t *phone, call_t *call, unative_t err)
  225. {
  226.     call->data.phone = phone;
  227.     atomic_inc(&phone->active_calls);
  228.     IPC_SET_RETVAL(call->data, err);
  229.     _ipc_answer_free_call(call);
  230. }
  231.  
  232. /** Unsafe unchecking version of ipc_call.
  233.  *
  234.  * @param phone     Phone structure the call comes from.
  235.  * @param box       Destination answerbox structure.
  236.  * @param call      Call structure with request.
  237.  */
  238. static void _ipc_call(phone_t *phone, answerbox_t *box, call_t *call)
  239. {
  240.     if (!(call->flags & IPC_CALL_FORWARDED)) {
  241.         atomic_inc(&phone->active_calls);
  242.         call->data.phone = phone;
  243.     }
  244.  
  245.     spinlock_lock(&box->lock);
  246.     list_append(&call->link, &box->calls);
  247.     spinlock_unlock(&box->lock);
  248.     waitq_wakeup(&box->wq, WAKEUP_FIRST);
  249. }
  250.  
  251. /** Send an asynchronous request using a phone to an answerbox.
  252.  *
  253.  * @param phone     Phone structure the call comes from and which is
  254.  *          connected to the destination answerbox.
  255.  * @param call      Call structure with request.
  256.  *
  257.  * @return      Return 0 on success, ENOENT on error.
  258.  */
  259. int ipc_call(phone_t *phone, call_t *call)
  260. {
  261.     answerbox_t *box;
  262.  
  263.     spinlock_lock(&phone->lock);
  264.     if (phone->state != IPC_PHONE_CONNECTED) {
  265.         spinlock_unlock(&phone->lock);
  266.         if (call->flags & IPC_CALL_FORWARDED) {
  267.             IPC_SET_RETVAL(call->data, EFORWARD);
  268.             _ipc_answer_free_call(call);
  269.         } else {
  270.             if (phone->state == IPC_PHONE_HUNGUP)
  271.                 ipc_backsend_err(phone, call, EHANGUP);
  272.             else
  273.                 ipc_backsend_err(phone, call, ENOENT);
  274.         }
  275.         return ENOENT;
  276.     }
  277.     box = phone->callee;
  278.     _ipc_call(phone, box, call);
  279.    
  280.     spinlock_unlock(&phone->lock);
  281.     return 0;
  282. }
  283.  
  284. /** Disconnect phone from answerbox.
  285.  *
  286.  * This call leaves the phone in the HUNGUP state. The change to 'free' is done
  287.  * lazily later.
  288.  *
  289.  * @param phone     Phone structure to be hung up.
  290.  *              
  291.  * @return      Return 0 if the phone is disconnected.
  292.  *          Return -1 if the phone was already disconnected.
  293.  */
  294. int ipc_phone_hangup(phone_t *phone)
  295. {
  296.     answerbox_t *box;
  297.     call_t *call;
  298.    
  299.     spinlock_lock(&phone->lock);
  300.     if (phone->state == IPC_PHONE_FREE ||
  301.         phone->state == IPC_PHONE_HUNGUP ||
  302.         phone->state == IPC_PHONE_CONNECTING) {
  303.         spinlock_unlock(&phone->lock);
  304.         return -1;
  305.     }
  306.     box = phone->callee;
  307.     if (phone->state != IPC_PHONE_SLAMMED) {
  308.         /* Remove myself from answerbox */
  309.         spinlock_lock(&box->lock);
  310.         list_remove(&phone->link);
  311.         spinlock_unlock(&box->lock);
  312.  
  313.         if (phone->state != IPC_PHONE_SLAMMED) {
  314.             call = ipc_call_alloc(0);
  315.             IPC_SET_METHOD(call->data, IPC_M_PHONE_HUNGUP);
  316.             call->flags |= IPC_CALL_DISCARD_ANSWER;
  317.             _ipc_call(phone, box, call);
  318.         }
  319.     }
  320.  
  321.     phone->state = IPC_PHONE_HUNGUP;
  322.     spinlock_unlock(&phone->lock);
  323.  
  324.     return 0;
  325. }
  326.  
  327. /** Forwards call from one answerbox to another one.
  328.  *
  329.  * @param call      Call structure to be redirected.
  330.  * @param newphone  Phone structure to target answerbox.
  331.  * @param oldbox    Old answerbox structure.
  332.  * @param mode      Flags that specify mode of the forward operation.
  333.  *
  334.  * @return      Return 0 if forwarding succeeded or an error code if
  335.  *          there was error.
  336.  *
  337.  * The return value serves only as an information for the forwarder,
  338.  * the original caller is notified automatically with EFORWARD.
  339.  */
  340. int ipc_forward(call_t *call, phone_t *newphone, answerbox_t *oldbox, int mode)
  341. {
  342.     spinlock_lock(&oldbox->lock);
  343.     list_remove(&call->link);
  344.     spinlock_unlock(&oldbox->lock);
  345.  
  346.     if (mode & IPC_FF_ROUTE_FROM_ME)
  347.         call->data.phone = newphone;
  348.  
  349.     return ipc_call(newphone, call);
  350. }
  351.  
  352.  
  353. /** Wait for a phone call.
  354.  *
  355.  * @param box       Answerbox expecting the call.
  356.  * @param usec      Timeout in microseconds. See documentation for
  357.  *          waitq_sleep_timeout() for decription of its special
  358.  *          meaning.
  359.  * @param flags     Select mode of sleep operation. See documentation for
  360.  *          waitq_sleep_timeout() for description of its special
  361.  *          meaning.
  362.  * @return      Recived call structure or NULL.
  363.  *
  364.  * To distinguish between a call and an answer, have a look at call->flags.
  365.  */
  366. call_t *ipc_wait_for_call(answerbox_t *box, uint32_t usec, int flags)
  367. {
  368.     call_t *request;
  369.     ipl_t ipl;
  370.     int rc;
  371.  
  372. restart:
  373.     rc = waitq_sleep_timeout(&box->wq, usec, flags);
  374.     if (SYNCH_FAILED(rc))
  375.         return NULL;
  376.    
  377.     spinlock_lock(&box->lock);
  378.     if (!list_empty(&box->irq_notifs)) {
  379.         ipl = interrupts_disable();
  380.         spinlock_lock(&box->irq_lock);
  381.  
  382.         request = list_get_instance(box->irq_notifs.next, call_t, link);
  383.         list_remove(&request->link);
  384.  
  385.         spinlock_unlock(&box->irq_lock);
  386.         interrupts_restore(ipl);
  387.     } else if (!list_empty(&box->answers)) {
  388.         /* Handle asynchronous answers */
  389.         request = list_get_instance(box->answers.next, call_t, link);
  390.         list_remove(&request->link);
  391.         atomic_dec(&request->data.phone->active_calls);
  392.     } else if (!list_empty(&box->calls)) {
  393.         /* Handle requests */
  394.         request = list_get_instance(box->calls.next, call_t, link);
  395.         list_remove(&request->link);
  396.         /* Append request to dispatch queue */
  397.         list_append(&request->link, &box->dispatched_calls);
  398.     } else {
  399.         /* This can happen regularly after ipc_cleanup */
  400.         spinlock_unlock(&box->lock);
  401.         goto restart;
  402.     }
  403.     spinlock_unlock(&box->lock);
  404.     return request;
  405. }
  406.  
  407. /** Answer all calls from list with EHANGUP answer.
  408.  *
  409.  * @param lst       Head of the list to be cleaned up.
  410.  */
  411. static void ipc_cleanup_call_list(link_t *lst)
  412. {
  413.     call_t *call;
  414.  
  415.     while (!list_empty(lst)) {
  416.         call = list_get_instance(lst->next, call_t, link);
  417.         list_remove(&call->link);
  418.  
  419.         IPC_SET_RETVAL(call->data, EHANGUP);
  420.         _ipc_answer_free_call(call);
  421.     }
  422. }
  423.  
  424. /** Cleans up all IPC communication of the current task.
  425.  *
  426.  * Note: ipc_hangup sets returning answerbox to TASK->answerbox, you
  427.  * have to change it as well if you want to cleanup other tasks than TASK.
  428.  */
  429. void ipc_cleanup(void)
  430. {
  431.     int i;
  432.     call_t *call;
  433.     phone_t *phone;
  434.     DEADLOCK_PROBE_INIT(p_phonelck);
  435.  
  436.     /* Disconnect all our phones ('ipc_phone_hangup') */
  437.     for (i = 0; i < IPC_MAX_PHONES; i++)
  438.         ipc_phone_hangup(&TASK->phones[i]);
  439.  
  440.     /* Disconnect all connected irqs */
  441.     ipc_irq_cleanup(&TASK->answerbox);
  442.  
  443.     /* Disconnect all phones connected to our answerbox */
  444. restart_phones:
  445.     spinlock_lock(&TASK->answerbox.lock);
  446.     while (!list_empty(&TASK->answerbox.connected_phones)) {
  447.         phone = list_get_instance(TASK->answerbox.connected_phones.next,
  448.             phone_t, link);
  449.         if (!spinlock_trylock(&phone->lock)) {
  450.             spinlock_unlock(&TASK->answerbox.lock);
  451.             DEADLOCK_PROBE(p_phonelck, DEADLOCK_THRESHOLD);
  452.             goto restart_phones;
  453.         }
  454.        
  455.         /* Disconnect phone */
  456.         ASSERT(phone->state == IPC_PHONE_CONNECTED);
  457.         phone->state = IPC_PHONE_SLAMMED;
  458.         list_remove(&phone->link);
  459.  
  460.         spinlock_unlock(&phone->lock);
  461.     }
  462.  
  463.     /* Answer all messages in 'calls' and 'dispatched_calls' queues */
  464.     ipc_cleanup_call_list(&TASK->answerbox.dispatched_calls);
  465.     ipc_cleanup_call_list(&TASK->answerbox.calls);
  466.     spinlock_unlock(&TASK->answerbox.lock);
  467.    
  468.     /* Wait for all async answers to arrive */
  469.     while (1) {
  470.         /* Go through all phones, until all are FREE... */
  471.         /* Locking not needed, no one else should modify
  472.          * it, when we are in cleanup */
  473.         for (i = 0; i < IPC_MAX_PHONES; i++) {
  474.             if (TASK->phones[i].state == IPC_PHONE_HUNGUP &&
  475.                 atomic_get(&TASK->phones[i].active_calls) == 0)
  476.                 TASK->phones[i].state = IPC_PHONE_FREE;
  477.            
  478.             /* Just for sure, we might have had some
  479.              * IPC_PHONE_CONNECTING phones */
  480.             if (TASK->phones[i].state == IPC_PHONE_CONNECTED)
  481.                 ipc_phone_hangup(&TASK->phones[i]);
  482.             /* If the hangup succeeded, it has sent a HANGUP
  483.              * message, the IPC is now in HUNGUP state, we
  484.              * wait for the reply to come */
  485.            
  486.             if (TASK->phones[i].state != IPC_PHONE_FREE)
  487.                 break;
  488.         }
  489.         /* Voila, got into cleanup */
  490.         if (i == IPC_MAX_PHONES)
  491.             break;
  492.        
  493.         call = ipc_wait_for_call(&TASK->answerbox, SYNCH_NO_TIMEOUT,
  494.             SYNCH_FLAGS_NONE);
  495.         ASSERT((call->flags & IPC_CALL_ANSWERED) ||
  496.             (call->flags & IPC_CALL_NOTIF));
  497.         ASSERT(!(call->flags & IPC_CALL_STATIC_ALLOC));
  498.        
  499.         atomic_dec(&TASK->active_calls);
  500.         ipc_call_free(call);
  501.     }
  502. }
  503.  
  504.  
  505. /** Initilize IPC subsystem */
  506. void ipc_init(void)
  507. {
  508.     ipc_call_slab = slab_cache_create("ipc_call", sizeof(call_t), 0, NULL,
  509.         NULL, 0);
  510. }
  511.  
  512.  
  513. /** List answerbox contents.
  514.  *
  515.  * @param taskid    Task ID.
  516.  */
  517. void ipc_print_task(task_id_t taskid)
  518. {
  519.     task_t *task;
  520.     int i;
  521.     call_t *call;
  522.     link_t *tmp;
  523.    
  524.     spinlock_lock(&tasks_lock);
  525.     task = task_find_by_id(taskid);
  526.     if (task)
  527.         spinlock_lock(&task->lock);
  528.     spinlock_unlock(&tasks_lock);
  529.     if (!task)
  530.         return;
  531.  
  532.     /* Print opened phones & details */
  533.     printf("PHONE:\n");
  534.     for (i = 0; i < IPC_MAX_PHONES; i++) {
  535.         spinlock_lock(&task->phones[i].lock);
  536.         if (task->phones[i].state != IPC_PHONE_FREE) {
  537.             printf("%d: ", i);
  538.             switch (task->phones[i].state) {
  539.             case IPC_PHONE_CONNECTING:
  540.                 printf("connecting ");
  541.                 break;
  542.             case IPC_PHONE_CONNECTED:
  543.                 printf("connected to: %p ",
  544.                        task->phones[i].callee);
  545.                 break;
  546.             case IPC_PHONE_SLAMMED:
  547.                 printf("slammed by: %p ",
  548.                        task->phones[i].callee);
  549.                 break;
  550.             case IPC_PHONE_HUNGUP:
  551.                 printf("hung up - was: %p ",
  552.                        task->phones[i].callee);
  553.                 break;
  554.             default:
  555.                 break;
  556.             }
  557.             printf("active: %d\n",
  558.                 atomic_get(&task->phones[i].active_calls));
  559.         }
  560.         spinlock_unlock(&task->phones[i].lock);
  561.     }
  562.  
  563.  
  564.     /* Print answerbox - calls */
  565.     spinlock_lock(&task->answerbox.lock);
  566.     printf("ABOX - CALLS:\n");
  567.     for (tmp = task->answerbox.calls.next; tmp != &task->answerbox.calls;
  568.         tmp = tmp->next) {
  569.         call = list_get_instance(tmp, call_t, link);
  570.         printf("Callid: %p Srctask:%llu M:%d A1:%d A2:%d A3:%d "
  571.             "Flags:%x\n", call, call->sender->taskid,
  572.             IPC_GET_METHOD(call->data), IPC_GET_ARG1(call->data),
  573.             IPC_GET_ARG2(call->data), IPC_GET_ARG3(call->data),
  574.             call->flags);
  575.     }
  576.     /* Print answerbox - calls */
  577.     printf("ABOX - DISPATCHED CALLS:\n");
  578.     for (tmp=task->answerbox.dispatched_calls.next;
  579.          tmp != &task->answerbox.dispatched_calls;
  580.          tmp = tmp->next) {
  581.         call = list_get_instance(tmp, call_t, link);
  582.         printf("Callid: %p Srctask:%llu M:%d A1:%d A2:%d A3:%d "
  583.             "Flags:%x\n", call, call->sender->taskid,
  584.             IPC_GET_METHOD(call->data), IPC_GET_ARG1(call->data),
  585.             IPC_GET_ARG2(call->data), IPC_GET_ARG3(call->data),
  586.             call->flags);
  587.     }
  588.     /* Print answerbox - calls */
  589.     printf("ABOX - ANSWERS:\n");
  590.     for (tmp = task->answerbox.answers.next; tmp != &task->answerbox.answers;
  591.         tmp = tmp->next) {
  592.         call = list_get_instance(tmp, call_t, link);
  593.         printf("Callid:%p M:%d A1:%d A2:%d A3:%d Flags:%x\n", call,
  594.             IPC_GET_METHOD(call->data), IPC_GET_ARG1(call->data),
  595.             IPC_GET_ARG2(call->data), IPC_GET_ARG3(call->data),
  596.             call->flags);
  597.     }
  598.  
  599.     spinlock_unlock(&task->answerbox.lock);
  600.     spinlock_unlock(&task->lock);
  601. }
  602.  
  603. /** @}
  604.  */
  605.