Subversion Repositories HelenOS

Rev

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

  1. /*
  2.  * Copyright (c) 2009 Lukas Mejdrech
  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 arp
  30.  *  @{
  31.  */
  32.  
  33. /** @file
  34.  *  ARP module implementation.
  35.  *  @see arp.h
  36.  */
  37.  
  38. #include <async.h>
  39. #include <malloc.h>
  40. #include <mem.h>
  41. #include <rwlock.h>
  42. #include <stdio.h>
  43.  
  44. #include <ipc/ipc.h>
  45. #include <ipc/services.h>
  46.  
  47. #include "../../err.h"
  48. #include "../../messages.h"
  49. #include "../../modules.h"
  50.  
  51. #include "../../include/byteorder.h"
  52. #include "../../include/device.h"
  53. #include "../../include/arp_messages.h"
  54. #include "../../include/nil_messages.h"
  55. #include "../../include/protocol_map.h"
  56.  
  57. #include "../../structures/measured_strings.h"
  58. #include "../../structures/packet/packet.h"
  59. #include "../../structures/packet/packet_client.h"
  60.  
  61. #include "arp.h"
  62. #include "arp_header.h"
  63. #include "arp_oc.h"
  64. #include "arp_module.h"
  65. #include "arp_wrappers.h"
  66.  
  67. /** ARP global data.
  68.  */
  69. arp_globals_t   arp_globals;
  70.  
  71. /** Creates new protocol specific data.
  72.  *  @param proto Protocol specific data. Output parameter.
  73.  *  @param service Protocol module service. Input parameter.
  74.  *  @param address Actual protocol device address. Input parameter.
  75.  *  @returns EOK on success.
  76.  *  @returns ENOMEM if there is not enough memory left.
  77.  */
  78. int arp_proto_create( arp_proto_ref * proto, services_t service, measured_string_ref address );
  79.  
  80. /** Registers the device.
  81.  *  Creates new device entry in the cache or updates the protocol address if the device with the device identifier and the driver service exists.
  82.  *  @param device_id The device identifier. Input parameter.
  83.  *  @param service The device driver service. Input parameter.
  84.  *  @param protocol The protocol service. Input parameter.
  85.  *  @param address The actual device protocol address.
  86.  *  @returns EOK on success.
  87.  *  @returns EEXIST if another device with the same device identifier and different driver service exists.
  88.  *  @returns ENOMEM if there is not enough memory left.
  89.  *  @returns Other error codes as defined for the measured_strings_return() function.
  90.  */
  91. int arp_device_message( device_id_t device_id, services_t service, services_t protocol, measured_string_ref address );
  92.  
  93. /** Returns the hardware address for the given protocol address.
  94.  *  Sends the ARP request packet if the hardware address is not found in the cache.
  95.  *  @param device_id The device identifier. Input parameter.
  96.  *  @param protocol The protocol service. Input parameter.
  97.  *  @param target The target protocol address. Input parameter.
  98.  *  @returns The hardware address of the target.
  99.  *  @returns NULL if the target parameter is NULL.
  100.  *  @returns NULL if the device is not found.
  101.  *  @returns NULL if the device packet is too small to send a&nbsp;request.
  102.  *  @returns NULL if the hardware address is not found in the cache.
  103.  */
  104. measured_string_ref arp_translate_message( device_id_t device_id, services_t protocol, measured_string_ref target );
  105.  
  106. /** Processes the received ARP packet.
  107.  *  Updates the source hardware address if the source entry exists or the packet is targeted to my protocol address.
  108.  *  Responses to the ARP request if the packet is the ARP request and is targeted to my address.
  109.  *  @param device_id The source device identifier. Input parameter.
  110.  *  @param packet The received packet. Input/output parameter.
  111.  *  @returns EOK on success.
  112.  *  @returns EINVAL if the packet is too small to carry the ARP packet.
  113.  *  @returns EINVAL if the received address lengths differs from the registered values.
  114.  *  @returns ENOENT if the device is not found in the cache.
  115.  *  @returns ENOENT if the protocol for the device is not found in the cache.
  116.  *  @returns ENOMEM if there is not enough memory left.
  117.  */
  118. int arp_receive_message( device_id_t device_id, packet_t packet );
  119.  
  120. /** Clears the device specific data.
  121.  *  @param device The device specific data.
  122.  */
  123. void    clear_device( arp_device_ref device );
  124.  
  125. /** Processes IPC messages from the registered device driver modules in an infinite loop.
  126.  *  @param iid The message identifier. Input parameter.
  127.  *  @param icall The message parameters. Input/output parameter.
  128.  */
  129. void    arp_receiver( ipc_callid_t iid, ipc_call_t * icall );
  130.  
  131. DEVICE_MAP_IMPLEMENT( arp_cache, arp_device_t )
  132.  
  133. INT_MAP_IMPLEMENT( arp_protos, arp_proto_t )
  134.  
  135. GENERIC_CHAR_MAP_IMPLEMENT( arp_addr, measured_string_t )
  136.  
  137. int arp_clear_device_wrapper( device_id_t device_id ){
  138.     arp_device_ref  device;
  139.  
  140.     rwlock_write_lock( & arp_globals.lock );
  141.     device = arp_cache_find( & arp_globals.cache, device_id );
  142.     if( ! device ){
  143.         rwlock_write_unlock( & arp_globals.lock );
  144.         return ENOENT;
  145.     }
  146.     clear_device( device );
  147.     printf( "\nDevice %d cleared", device_id );
  148.     rwlock_write_unlock( & arp_globals.lock );
  149.     return EOK;
  150. }
  151.  
  152. int arp_clean_cache_wrapper( void ){
  153.     int             count;
  154.     arp_device_ref  device;
  155.  
  156.     rwlock_write_lock( & arp_globals.lock );
  157.     for( count = arp_cache_count( & arp_globals.cache ) - 1; count >= 0; -- count ){
  158.         device = arp_cache_get_index( & arp_globals.cache, count );
  159.         if( device ){
  160.             clear_device( device );
  161.             if( device->addr_data ) free( device->addr_data );
  162.             if( device->broadcast_data ) free( device->broadcast_data );
  163.         }
  164.     }
  165.     arp_cache_clear( & arp_globals.cache );
  166.     rwlock_write_unlock( & arp_globals.lock );
  167.     printf( "\nCache cleaned" );
  168.     return EOK;
  169. }
  170.  
  171. int arp_device_wrapper( device_id_t device_id, services_t protocol, services_t netif, measured_string_ref address ){
  172.     ERROR_DECLARE;
  173.  
  174.     measured_string_ref tmp;
  175.  
  176.     tmp = measured_string_copy( address );
  177.     if( ERROR_OCCURRED( arp_device_message( device_id, netif, protocol, tmp ))){
  178.         free( tmp->value );
  179.         free( tmp );
  180.     }
  181.     return ERROR_CODE;
  182. }
  183.  
  184. int arp_translate_wrapper( device_id_t device_id, services_t protocol, measured_string_ref address, measured_string_ref * translation, char ** data ){
  185.     measured_string_ref tmp;
  186.  
  187.     rwlock_read_lock( & arp_globals.lock );
  188.     tmp = arp_translate_message( device_id, protocol, address );
  189.     if( tmp ){
  190.         * translation = measured_string_copy( tmp );
  191.         rwlock_read_unlock( & arp_globals.lock );
  192.         if( * translation ){
  193.             * data = ( ** translation ).value;
  194.             return EOK;
  195.         }else{
  196.             return ENOMEM;
  197.         }
  198.     }else{
  199.         rwlock_read_unlock( & arp_globals.lock );
  200.         return ENOENT;
  201.     }
  202. }
  203.  
  204. int arp_initialize( void ){
  205.     ERROR_DECLARE;
  206.  
  207.     rwlock_initialize( & arp_globals.lock );
  208.     rwlock_write_lock( & arp_globals.lock );
  209.     ERROR_PROPAGATE( arp_cache_initialize( & arp_globals.cache ));
  210.     rwlock_write_unlock( & arp_globals.lock );
  211.     return EOK;
  212. }
  213.  
  214. int arp_proto_create( arp_proto_ref * proto, services_t service, measured_string_ref address ){
  215.     ERROR_DECLARE;
  216.  
  217.     * proto = ( arp_proto_ref ) malloc( sizeof( arp_proto_t ));
  218.     if( !( * proto )) return ENOMEM;
  219.     ( ** proto ).service = service;
  220.     ( ** proto ).addr = address;
  221.     ( ** proto ).addr_data = address->value;
  222.     if( ERROR_OCCURRED( arp_addr_initialize( &( ** proto).addresses ))){
  223.         free( * proto );
  224.         return ERROR_CODE;
  225.     }
  226.     return EOK;
  227. }
  228.  
  229. int arp_device_message( device_id_t device_id, services_t service, services_t protocol, measured_string_ref address ){
  230.     ERROR_DECLARE;
  231.  
  232.     arp_device_ref  device;
  233.     arp_proto_ref   proto;
  234.     int             index;
  235.  
  236.     rwlock_write_lock( & arp_globals.lock );
  237.     // an existing device?
  238.     device = arp_cache_find( & arp_globals.cache, device_id );
  239.     if( device ){
  240.         if( device->service != service ){
  241.             printf( "\nDevice %d already exists", device->device_id );
  242.             rwlock_write_unlock( & arp_globals.lock );
  243.             return EEXIST;
  244.         }
  245.         proto = arp_protos_find( & device->protos, protocol );
  246.         if( proto ){
  247.             free( proto->addr );
  248.             free( proto->addr_data );
  249.             proto->addr = address;
  250.             proto->addr_data = address->value;
  251.         }else{
  252.             if( ERROR_OCCURRED( arp_proto_create( & proto, protocol, address ))){
  253.                 rwlock_write_unlock( & arp_globals.lock );
  254.                 return ERROR_CODE;
  255.             }
  256.             index = arp_protos_add( & device->protos, proto->service, proto );
  257.             if( index < 0 ){
  258.                 rwlock_write_unlock( & arp_globals.lock );
  259.                 free( proto );
  260.                 return index;
  261.             }
  262.         }
  263.         printf( "\nCache of the existing device %d cleaned", device->device_id );
  264.     }else{
  265.         index = hardware_map( service );
  266.         if( ! index ) return ENOENT;
  267.         // create a new device
  268.         device = ( arp_device_ref ) malloc( sizeof( arp_device_t ));
  269.         if( ! device ){
  270.             rwlock_write_unlock( & arp_globals.lock );
  271.             return ENOMEM;
  272.         }
  273.         device->hardware = index;
  274.         device->device_id = device_id;
  275.         if( ERROR_OCCURRED( arp_protos_initialize( & device->protos ))
  276.         || ERROR_OCCURRED( arp_proto_create( & proto, protocol, address ))){
  277.             rwlock_write_unlock( & arp_globals.lock );
  278.             free( device );
  279.             return ERROR_CODE;
  280.         }
  281.         index = arp_protos_add( & device->protos, proto->service, proto );
  282.         if( index < 0 ){
  283.             rwlock_write_unlock( & arp_globals.lock );
  284.             arp_protos_destroy( & device->protos );
  285.             free( device );
  286.             return index;
  287.         }
  288.         device->service = service;
  289.         // bind the new one
  290.         device->phone = bind_service( device->service, device->device_id, SERVICE_ARP, 0, arp_receiver );
  291.         if( device->phone < 0 ){
  292.             rwlock_write_unlock( & arp_globals.lock );
  293.             arp_protos_destroy( & device->protos );
  294.             free( device );
  295.             return EREFUSED;
  296.         }
  297.         // get packet dimensions
  298.         if( ERROR_OCCURRED( nil_packet_size_req( device->phone, device_id, & device->addr_len, & device->prefix, & device->content, & device->suffix ))){
  299.             rwlock_write_unlock( & arp_globals.lock );
  300.             arp_protos_destroy( & device->protos );
  301.             free( device );
  302.             return ERROR_CODE;
  303.         }
  304.         // get hardware address
  305.         if( ERROR_OCCURRED( nil_get_addr( device->phone, device_id, & device->addr, & device->addr_data ))){
  306.             rwlock_write_unlock( & arp_globals.lock );
  307.             arp_protos_destroy( & device->protos );
  308.             free( device );
  309.             return ERROR_CODE;
  310.         }
  311.         // get broadcast address
  312.         if( ERROR_OCCURRED( nil_get_broadcast_addr( device->phone, device_id, & device->broadcast_addr, & device->broadcast_data ))){
  313.             rwlock_write_unlock( & arp_globals.lock );
  314.             free( device->addr );
  315.             free( device->addr_data );
  316.             arp_protos_destroy( & device->protos );
  317.             free( device );
  318.             return ERROR_CODE;
  319.         }
  320.         if( ERROR_OCCURRED( arp_cache_add( & arp_globals.cache, device->device_id, device ))){
  321.             rwlock_write_unlock( & arp_globals.lock );
  322.             free( device->addr );
  323.             free( device->addr_data );
  324.             free( device->broadcast_addr );
  325.             free( device->broadcast_data );
  326.             arp_protos_destroy( & device->protos );
  327.             free( device );
  328.             return ERROR_CODE;
  329.         }
  330.         printf( "\nNew device registered:\n\tid\t= %d\n\ttype\t= 0x%x\n\tservice\t= %d", device->device_id, device->hardware, device->service );
  331.     }
  332.     rwlock_write_unlock( & arp_globals.lock );
  333.     return EOK;
  334. }
  335.  
  336. measured_string_ref arp_translate_message( device_id_t device_id, services_t protocol, measured_string_ref target ){
  337.     arp_device_ref      device;
  338.     arp_proto_ref       proto;
  339.     measured_string_ref addr;
  340.     size_t              length;
  341.     packet_t            packet;
  342.     arp_header_ref      header;
  343.  
  344.     if( ! target ) return NULL;
  345.     device = arp_cache_find( & arp_globals.cache, device_id );
  346.     if( ! device ) return NULL;
  347.     proto = arp_protos_find( & device->protos, protocol );
  348.     if(( ! proto ) || ( proto->addr->length != target->length )) return NULL;
  349.     addr = arp_addr_find( & proto->addresses, target->value, target->length );
  350.     if( addr ) return addr;
  351.     // ARP packet content size = header + ( address + translation ) * 2
  352.     length = 8 + ( CONVERT_SIZE( char, uint8_t, proto->addr->length ) + CONVERT_SIZE( char, uint8_t, device->addr->length )) * 2;
  353.     if( length > device->content ) return NULL;
  354.     packet = packet_get_4( arp_globals.networking_phone, device->addr_len, device->prefix, length, device->suffix );
  355.     if( ! packet ) return NULL;
  356.     header = ( arp_header_ref ) packet_suffix( packet, length );
  357.     header->hardware = htons( device->hardware );
  358.     header->hardware_length = device->addr->length;
  359.     header->protocol = htons( protocol_map( device->service, protocol ));
  360.     header->protocol_length = proto->addr->length;
  361.     header->operation = htons( ARPOP_REQUEST );
  362.     length = sizeof( arp_header_t );
  363.     memcpy((( uint8_t * ) header ) + length, device->addr->value, device->addr->length );
  364.     length += device->addr->length;
  365.     memcpy((( uint8_t * ) header ) + length, proto->addr->value, proto->addr->length );
  366.     length += proto->addr->length;
  367.     bzero((( uint8_t * ) header ) + length, device->addr->length );
  368.     length += device->addr->length;
  369.     memcpy((( uint8_t * ) header ) + length, target->value, target->length );
  370.     packet_set_addr( packet, ( uint8_t * ) device->addr->value, ( uint8_t * ) device->broadcast_addr->value, CONVERT_SIZE( char, uint8_t, device->addr->length ));
  371.     nil_send_msg( device->phone, device_id, packet, SERVICE_ARP );
  372.     return NULL;
  373. }
  374.  
  375. int arp_receive_message( device_id_t device_id, packet_t packet ){
  376.     ERROR_DECLARE;
  377.  
  378.     size_t              length;
  379.     arp_header_ref      header;
  380.     arp_device_ref      device;
  381.     arp_proto_ref       proto;
  382.     measured_string_ref hw_source;
  383.     uint8_t *           src_hw;
  384.     uint8_t *           src_proto;
  385.     uint8_t *           des_hw;
  386.     uint8_t *           des_proto;
  387.  
  388.     length = packet_get_data_length( packet );
  389.     if( length <= sizeof( arp_header_t )) return EINVAL;
  390.     device = arp_cache_find( & arp_globals.cache, device_id );
  391.     if( ! device ) return ENOENT;
  392.     header = ( arp_header_ref ) packet_get_data( packet );
  393.     if(( ntohs( header->hardware ) != device->hardware )
  394.     || ( length < sizeof( arp_header_t ) + ( header->hardware_length + header->protocol_length ) * 2 )){
  395.         return EINVAL;
  396.     }
  397.     proto = arp_protos_find( & device->protos, protocol_unmap( device->service, ntohs( header->protocol )));
  398.     if( ! proto ) return ENOENT;
  399.     src_hw = (( uint8_t * ) header ) + sizeof( arp_header_t );
  400.     src_proto = src_hw + header->hardware_length;
  401.     des_hw = src_proto + header->protocol_length;
  402.     des_proto = des_hw + header->hardware_length;
  403.     hw_source = arp_addr_find( & proto->addresses, ( char * ) src_proto, CONVERT_SIZE( uint8_t, char, header->protocol_length ));
  404.     // exists?
  405.     if( hw_source ){
  406.         if( hw_source->length != CONVERT_SIZE( uint8_t, char, header->hardware_length )){
  407.             return EINVAL;
  408.         }
  409.         memcpy( hw_source->value, src_hw, hw_source->length );
  410.     }
  411.     // is my protocol address?
  412.     if( proto->addr->length != CONVERT_SIZE( uint8_t, char, header->hardware_length )){
  413.         return EINVAL;
  414.     }
  415.     if( ! strncmp( proto->addr->value, ( char * ) des_proto, proto->addr->length )){
  416.         // not already upadted?
  417.         if( ! hw_source ){
  418.             hw_source = measured_string_create_bulk(( char * ) src_hw, CONVERT_SIZE( uint8_t, char, header->hardware_length ));
  419.             if( ! hw_source ) return ENOMEM;
  420.             ERROR_PROPAGATE( arp_addr_add( & proto->addresses, ( char * ) src_proto, CONVERT_SIZE( uint8_t, char, header->protocol_length ), hw_source ));
  421.         }
  422.         if( ntohs( header->operation ) == ARPOP_REQUEST ){
  423.             header->operation = htons( ARPOP_REPLY );
  424.             memcpy( des_proto, src_proto, header->protocol_length );
  425.             memcpy( src_proto, proto->addr->value, header->protocol_length );
  426.             memcpy( src_hw, des_hw, header->hardware_length );
  427.             memcpy( des_hw, hw_source->value, header->hardware_length );
  428.             packet_set_addr( packet, src_hw, des_hw, header->hardware_length );
  429.             nil_send_msg( device->phone, device_id, packet, SERVICE_ARP );
  430.         }else{
  431.             pq_release( arp_globals.networking_phone, packet_get_id( packet ));
  432.         }
  433.     }
  434.     return EOK;
  435. }
  436.  
  437. void clear_device( arp_device_ref device ){
  438.     int             count;
  439.     arp_proto_ref   proto;
  440.  
  441.     for( count = arp_protos_count( & device->protos ) - 1; count >= 0; -- count ){
  442.         proto = arp_protos_get_index( & device->protos, count );
  443.         if( proto ){
  444.             if( proto->addr ) free( proto->addr );
  445.             if( proto->addr_data ) free( proto->addr_data );
  446.             arp_addr_destroy( & proto->addresses );
  447.         }
  448.     }
  449.     arp_protos_clear( & device->protos );
  450. }
  451.  
  452. int arp_message( ipc_callid_t callid, ipc_call_t * call, ipc_call_t * answer, int * answer_count ){
  453.     ERROR_DECLARE;
  454.  
  455.     measured_string_ref address;
  456.     measured_string_ref translation;
  457.     char *              data;
  458.  
  459. //  printf( "\nmessage %d - %d", IPC_GET_METHOD( * call ), NET_ARP_FIRST );
  460.     * answer_count = 0;
  461.     switch( IPC_GET_METHOD( * call )){
  462.         case IPC_M_PHONE_HUNGUP:
  463.             return EOK;
  464.         case NET_ARP_DEVICE:
  465.             ERROR_PROPAGATE( measured_strings_receive( & address, & data, 1 ));
  466.             if( ERROR_OCCURRED( arp_device_message( IPC_GET_DEVICE( call ), IPC_GET_SERVICE( call ), ARP_GET_PROTO( call ), address ))){
  467.                 free( address );
  468.                 free( data );
  469.             }
  470.             return ERROR_CODE;
  471.         case NET_ARP_TRANSLATE:
  472.             ERROR_PROPAGATE( measured_strings_receive( & address, & data, 1 ));
  473.             rwlock_read_lock( & arp_globals.lock );
  474.             translation = arp_translate_message( IPC_GET_DEVICE( call ), ARP_GET_PROTO( call ), address );
  475.             free( address );
  476.             free( data );
  477.             if( ! translation ){
  478.                 rwlock_read_unlock( & arp_globals.lock );
  479.                 return ENOENT;
  480.             }
  481.             ERROR_CODE = measured_strings_reply( translation, 1 );
  482.             rwlock_read_unlock( & arp_globals.lock );
  483.             return ERROR_CODE;
  484.         case NET_ARP_CLEAR_DEVICE:
  485.             return arp_clear_device_wrapper( IPC_GET_DEVICE( call ));
  486.         case NET_ARP_CLEAN_CACHE:
  487.             return arp_clean_cache_wrapper();
  488.     }
  489.     return ENOTSUP;
  490. }
  491.  
  492. void arp_receiver( ipc_callid_t iid, ipc_call_t * icall ){
  493.     ERROR_DECLARE;
  494.  
  495.     packet_t        packet;
  496.  
  497.     while( true ){
  498.         switch( IPC_GET_METHOD( * icall )){
  499.             case NET_IL_DEVICE_STATE:
  500.                 // do nothing - keep the cache
  501.                 ipc_answer_0( iid, EOK );
  502.                 break;
  503.             case NET_IL_RECEIVED:
  504.                 if( ! ERROR_OCCURRED( packet_translate( arp_globals.networking_phone, & packet, IPC_GET_PACKET( icall )))){
  505.                     rwlock_read_lock( & arp_globals.lock );
  506.                     ERROR_CODE = arp_receive_message( IPC_GET_DEVICE( icall ), packet );
  507.                     rwlock_read_unlock( & arp_globals.lock );
  508.                 }
  509.                 ipc_answer_0( iid, ERROR_CODE );
  510.                 break;
  511.             default:
  512.                 ipc_answer_0( iid, ENOTSUP );
  513.         }
  514.         iid = async_get_call( icall );
  515.     }
  516. }
  517.  
  518. /** @}
  519.  */
  520.