From eaac3cc1bd70cf9b055313ee386844e95b08a5f0 Mon Sep 17 00:00:00 2001 From: Norman Feske Date: Fri, 20 Mar 2015 17:50:41 +0100 Subject: [PATCH] Revised API documentation This patch curates the API documentation to become suitable for the functional specificaton, which is partially generated from the header files. --- repos/base/include/32bit/base/fixed_stdint.h | 16 +-- repos/base/include/64bit/base/fixed_stdint.h | 16 +-- repos/base/include/base/affinity.h | 2 +- repos/base/include/base/allocator.h | 51 ++++---- repos/base/include/base/allocator_avl.h | 16 ++- repos/base/include/base/blocking.h | 15 +-- repos/base/include/base/cancelable_lock.h | 4 +- repos/base/include/base/capability.h | 6 +- repos/base/include/base/child.h | 23 ++-- repos/base/include/base/connection.h | 7 ++ repos/base/include/base/console.h | 10 +- repos/base/include/base/env.h | 5 +- repos/base/include/base/heap.h | 8 +- repos/base/include/base/ipc.h | 6 +- repos/base/include/base/lock_guard.h | 13 +- repos/base/include/base/native_capability.h | 4 +- repos/base/include/base/object_pool.h | 7 +- repos/base/include/base/pager.h | 4 +- repos/base/include/base/printf.h | 5 +- repos/base/include/base/rpc.h | 2 +- repos/base/include/base/rpc_args.h | 2 +- repos/base/include/base/rpc_client.h | 44 ++++--- repos/base/include/base/rpc_server.h | 58 ++++++--- repos/base/include/base/semaphore.h | 9 ++ repos/base/include/base/service.h | 8 +- repos/base/include/base/signal.h | 39 +++--- repos/base/include/base/slab.h | 22 +++- repos/base/include/base/snprintf.h | 8 +- repos/base/include/base/stdint.h | 2 +- repos/base/include/base/sync_allocator.h | 2 +- repos/base/include/base/thread.h | 29 ++--- repos/base/include/base/weak_ptr.h | 116 ++++++++++++------ repos/base/include/cpu_session/cpu_session.h | 8 +- .../include/io_port_session/io_port_session.h | 2 +- repos/base/include/parent/parent.h | 10 +- repos/base/include/ram_session/client.h | 2 +- repos/base/include/ram_session/ram_session.h | 3 + repos/base/include/rom_session/rom_session.h | 14 +-- repos/base/include/root/component.h | 18 +-- repos/base/include/session/session.h | 15 ++- .../include/signal_session/signal_session.h | 2 +- repos/base/include/signal_session/source.h | 2 +- repos/base/include/util/arg_string.h | 4 +- repos/base/include/util/avl_string.h | 5 + repos/base/include/util/avl_tree.h | 46 ++++--- repos/base/include/util/bit_allocator.h | 5 + repos/base/include/util/fifo.h | 4 +- repos/base/include/util/list.h | 2 - repos/base/include/util/mmio.h | 2 +- repos/base/include/util/noncopyable.h | 15 +++ repos/base/include/util/string.h | 36 +++--- repos/base/include/util/token.h | 4 +- repos/base/include/x86/cpu/string.h | 4 +- repos/os/include/block/driver.h | 2 +- .../os/include/block_session/block_session.h | 28 +++-- repos/os/include/block_session/rpc_object.h | 2 +- repos/os/include/cli_monitor/child.h | 4 +- repos/os/include/decorator/window.h | 2 +- repos/os/include/decorator/window_stack.h | 2 +- .../include/file_system_session/rpc_object.h | 2 +- .../include/framebuffer_session/connection.h | 2 +- .../framebuffer_session/framebuffer_session.h | 8 +- repos/os/include/init/child.h | 6 +- repos/os/include/init/child_config.h | 4 +- repos/os/include/init/child_policy.h | 4 +- repos/os/include/ldso/arch.h | 2 +- .../include/loader_session/loader_session.h | 4 +- repos/os/include/net/arp.h | 2 +- repos/os/include/net/dhcp.h | 6 +- repos/os/include/net/netaddress.h | 6 +- repos/os/include/nic/driver.h | 2 +- repos/os/include/nic_session/nic_session.h | 27 ++-- repos/os/include/nitpicker_session/client.h | 2 +- .../nitpicker_session/nitpicker_session.h | 10 +- repos/os/include/os/alarm.h | 14 +-- repos/os/include/os/attached_dataspace.h | 2 +- repos/os/include/os/attached_ram_dataspace.h | 16 +-- repos/os/include/os/attached_rom_dataspace.h | 2 +- .../os/include/os/child_policy_dynamic_rom.h | 8 +- repos/os/include/os/config.h | 2 +- repos/os/include/os/handle_registry.h | 2 +- repos/os/include/os/irq_activation.h | 2 +- repos/os/include/os/packet_allocator.h | 6 +- repos/os/include/os/packet_stream.h | 11 +- repos/os/include/os/ring_buffer.h | 7 +- repos/os/include/os/signal_rpc_dispatcher.h | 10 +- repos/os/include/os/slave.h | 2 +- repos/os/include/os/static_root.h | 8 +- repos/os/include/os/surface.h | 2 +- repos/os/include/os/synced_interface.h | 19 +-- .../os/include/packet_stream_rx/rpc_object.h | 4 +- .../packet_stream_tx/packet_stream_tx.h | 4 +- .../os/include/packet_stream_tx/rpc_object.h | 4 +- repos/os/include/pci_device/pci_device.h | 4 - repos/os/include/pci_session/pci_session.h | 2 +- .../imx_framebuffer_session/connection.h | 2 +- .../rpi/platform_session/platform_session.h | 2 +- .../include/report_session/report_session.h | 4 +- repos/os/include/terminal/cell_array.h | 2 +- .../terminal_session/terminal_session.h | 2 +- .../os/include/timer_session/timer_session.h | 4 +- repos/os/include/usb_session/rpc_object.h | 2 +- repos/os/include/util/dirty_rect.h | 2 +- repos/os/include/util/xml_generator.h | 2 +- repos/os/include/util/xml_node.h | 8 +- repos/os/include/vfs/dir_file_system.h | 2 +- repos/os/include/vfs/file_system.h | 2 +- 107 files changed, 610 insertions(+), 444 deletions(-) diff --git a/repos/base/include/32bit/base/fixed_stdint.h b/repos/base/include/32bit/base/fixed_stdint.h index 8e9d60f254..1b20f8a176 100644 --- a/repos/base/include/32bit/base/fixed_stdint.h +++ b/repos/base/include/32bit/base/fixed_stdint.h @@ -1,5 +1,5 @@ /* - * \brief Standard fixed-width integer types + * \brief Fixed-width integer types for 32-bit architectures * \author Christian Helmuth * \author Norman Feske * \date 2006-05-10 @@ -28,9 +28,10 @@ #define _INCLUDE__32BIT__BASE__FIXED_STDINT_H_ -/* - * Fixed-size types usable from both C and C++ programs - */ +/********************************************************** + ** Fixed-size types usable from both C and C++ programs ** + **********************************************************/ + typedef signed char genode_int8_t; typedef unsigned char genode_uint8_t; typedef signed short genode_int16_t; @@ -41,9 +42,10 @@ typedef signed long long genode_int64_t; typedef unsigned long long genode_uint64_t; -/* - * Types residing within Genode's C++ namespace - */ +/************************************************** + ** Types residing within Genode's C++ namespace ** + **************************************************/ + #ifdef __cplusplus namespace Genode { typedef genode_int8_t int8_t; diff --git a/repos/base/include/64bit/base/fixed_stdint.h b/repos/base/include/64bit/base/fixed_stdint.h index 6ef09e0083..9cc6638baf 100644 --- a/repos/base/include/64bit/base/fixed_stdint.h +++ b/repos/base/include/64bit/base/fixed_stdint.h @@ -1,5 +1,5 @@ /* - * \brief Standard fixed-width integer types + * \brief Fixed-width integer types for 64-bit architectures * \author Christian Helmuth * \author Norman Feske * \date 2006-05-10 @@ -18,9 +18,10 @@ #define _INCLUDE__64BIT__BASE__FIXED_STDINT_H_ -/* - * Fixed-size types usable from both C and C++ programs - */ +/********************************************************** + ** Fixed-size types usable from both C and C++ programs ** + **********************************************************/ + typedef signed char genode_int8_t; typedef unsigned char genode_uint8_t; typedef signed short genode_int16_t; @@ -31,9 +32,10 @@ typedef signed long long genode_int64_t; typedef unsigned long long genode_uint64_t; -/* - * Types residing within Genode's C++ namespace - */ +/************************************************** + ** Types residing within Genode's C++ namespace ** + **************************************************/ + #ifdef __cplusplus namespace Genode { typedef genode_int8_t int8_t; diff --git a/repos/base/include/base/affinity.h b/repos/base/include/base/affinity.h index d9a6e5c9a5..27d26c6e05 100644 --- a/repos/base/include/base/affinity.h +++ b/repos/base/include/base/affinity.h @@ -79,7 +79,7 @@ class Genode::Affinity * Return the location of the Nth CPU within the affinity * space * - * This function returns a valid location even if the index + * This method returns a valid location even if the index * is larger than the number of CPUs in the space. In this * case, the x and y coordinates are wrapped by the bounds * of the space. diff --git a/repos/base/include/base/allocator.h b/repos/base/include/base/allocator.h index 9d4747ec6d..a6b3cec69f 100644 --- a/repos/base/include/base/allocator.h +++ b/repos/base/include/base/allocator.h @@ -23,27 +23,13 @@ namespace Genode { struct Allocator; struct Range_allocator; - /** - * Destroy object - * - * For destroying an object, we need to specify the allocator that was used - * by the object. Because we cannot pass the allocator directly to the - * delete expression, we mimic the expression by using this template - * function. The function explicitly calls the object destructor and - * operator delete afterwards. - * - * For details see https://github.com/genodelabs/genode/issues/1030. - * - * \param T implicit object type - * - * \param dealloc reference or pointer to allocator from which the object - * was allocated - * \param obj object to destroy - */ template void destroy(DEALLOC && dealloc, T *obj); } +/** + * Deallocator interface + */ struct Genode::Deallocator { /** @@ -56,7 +42,7 @@ struct Genode::Deallocator * * The generic 'Allocator' interface requires the caller of 'free' * to supply a valid size argument but not all implementations make - * use of this argument. If this function returns false, it is safe + * use of this argument. If this method returns false, it is safe * to call 'free' with an invalid size. * * Allocators that rely on the size argument must not be used for @@ -94,7 +80,7 @@ struct Genode::Allocator : Deallocator * Allocate typed block * * This template allocates a typed block returned as a pointer to - * a non-void type. By providing this function, we prevent the + * a non-void type. By providing this method, we prevent the * compiler from warning us about "dereferencing type-punned * pointer will break strict-aliasing rules". */ @@ -116,11 +102,6 @@ struct Genode::Allocator : Deallocator */ virtual size_t overhead(size_t size) = 0; - - /*************************** - ** Convenience functions ** - ***************************/ - /** * Allocate block and signal error as an exception * @@ -199,7 +180,7 @@ struct Genode::Range_allocator : Allocator /** * Free a previously allocated block * - * NOTE: We have to declare the 'Allocator::free(void *)' function + * NOTE: We have to declare the 'Allocator::free(void *)' method * here as well to make the compiler happy. Otherwise the C++ * overload resolution would not find 'Allocator::free(void *)'. */ @@ -255,14 +236,30 @@ void *operator new [] (Genode::size_t, Genode::Allocator &); * we print a warning and pass the zero size argument anyway. * * :Warning: Never use an allocator that depends on the size argument of the - * 'free()' function for the allocation of objects that may throw exceptions + * 'free()' method for the allocation of objects that may throw exceptions * at their construction time! */ void operator delete (void *, Genode::Deallocator *); void operator delete (void *, Genode::Deallocator &); -/* implemented here as it needs the special delete operators */ +/** + * Destroy object + * + * For destroying an object, we need to specify the allocator that was used + * by the object. Because we cannot pass the allocator directly to the + * delete expression, we mimic the expression by using this template + * function. The function explicitly calls the object destructor and + * operator delete afterwards. + * + * For details see https://github.com/genodelabs/genode/issues/1030. + * + * \param T implicit object type + * + * \param dealloc reference or pointer to allocator from which the object + * was allocated + * \param obj object to destroy + */ template void Genode::destroy(DEALLOC && dealloc, T *obj) { diff --git a/repos/base/include/base/allocator_avl.h b/repos/base/include/base/allocator_avl.h index b873da11eb..fc5877c321 100644 --- a/repos/base/include/base/allocator_avl.h +++ b/repos/base/include/base/allocator_avl.h @@ -2,10 +2,6 @@ * \brief Interface of AVL-tree-based allocator * \author Norman Feske * \date 2006-04-16 - * - * Each block of the managed address space is present in two AVL trees, - * one tree ordered by the base addresses of the blocks and one tree ordered - * by the available capacity within the block. */ /* @@ -149,9 +145,17 @@ class Genode::Allocator_avl_base : public Range_allocator size_t avail_in_subtree(void); /** - * Debug hooks + * Debug hook + * + * \noapi */ void dump(); + + /** + * Debug hook + * + * \noapi + */ void dump_dot(int indent = 0); }; @@ -230,6 +234,8 @@ class Genode::Allocator_avl_base : public Range_allocator /** * Debug hook + * + * \noapi */ void dump_addr_tree(Block *addr_node = 0); diff --git a/repos/base/include/base/blocking.h b/repos/base/include/base/blocking.h index c08aa246a6..791869d5d3 100644 --- a/repos/base/include/base/blocking.h +++ b/repos/base/include/base/blocking.h @@ -2,13 +2,6 @@ * \brief Support for blocking operations * \author Norman Feske * \date 2007-09-06 - * - * In Genode, two operations may block a thread, - * waiting at a lock or performing an IPC call. - * Both operations may be canceled when killing - * the thread. In this case, the thread unblocks - * and throws an exception, and therefore, is able - * to clean up the thread state before exiting. */ /* @@ -25,6 +18,14 @@ namespace Genode { class Blocking_canceled; } +/** + * Blocking-canceled exception + * + * Two operations may block a thread, waiting at a lock or performing an RPC + * call. Both operations may be canceled when the thread is destructed. In this + * case, the thread unblocks and throws an exception, and therefore, is able to + * clean up the thread state before exiting. + */ class Genode::Blocking_canceled : public Exception { }; #endif /* _INCLUDE__BASE__BLOCKING_H_ */ diff --git a/repos/base/include/base/cancelable_lock.h b/repos/base/include/base/cancelable_lock.h index d2b591e6f0..babc747122 100644 --- a/repos/base/include/base/cancelable_lock.h +++ b/repos/base/include/base/cancelable_lock.h @@ -77,9 +77,9 @@ class Genode::Cancelable_lock explicit Cancelable_lock(State initial = UNLOCKED); /** - * Try to aquire lock an block while lock is not free + * Try to aquire the lock and block while the lock is not free * - * This function may throw a Genode::Blocking_canceled exception. + * \throw Genode::Blocking_canceled */ void lock(); diff --git a/repos/base/include/base/capability.h b/repos/base/include/base/capability.h index 00e399c856..42e4cef888 100644 --- a/repos/base/include/base/capability.h +++ b/repos/base/include/base/capability.h @@ -90,7 +90,7 @@ class Genode::Capability : public Untyped_capability * A server-side exception is indicated by a non-zero exception * code. Each exception code corresponds to an entry in the * exception type list specified in the RPC function declaration. - * The '_check_for_exception' function template throws the + * The '_check_for_exception' method template throws the * exception type belonging to the received exception code. */ template @@ -117,7 +117,7 @@ class Genode::Capability : public Untyped_capability typename IF::Ret_type &ret) const; /** - * Shortcut for querying argument types used in 'call' functions + * Shortcut for querying argument types used in 'call' methods */ template struct Arg @@ -148,7 +148,7 @@ class Genode::Capability : public Untyped_capability * * Each 'call' overload creates an instance of the return value * type as local variable. A reference to this variable is passed - * to the '_call' function, which will assign its value. Even + * to the '_call' method, which will assign its value. Even * though the variable does not need to be initialized prior the * call of '_call', the GCC will still complain "warning: ‘ret’ may * be used uninitialized in this function". Wrapping the return diff --git a/repos/base/include/base/child.h b/repos/base/include/base/child.h index 70909d1f34..6468ce830b 100644 --- a/repos/base/include/base/child.h +++ b/repos/base/include/base/child.h @@ -105,7 +105,7 @@ struct Genode::Child_policy /** * Reference RAM session * - * The RAM session returned by this function is used for session-quota + * The RAM session returned by this method is used for session-quota * transfers. */ virtual Ram_session *ref_ram_session() { return env()->ram_session(); } @@ -113,7 +113,7 @@ struct Genode::Child_policy /** * Return platform-specific PD-session arguments * - * This function is used on Linux to supply additional PD-session + * This method is used on Linux to supply additional PD-session * argument to core, i.e., the chroot path, the UID, and the GID. */ virtual Native_pd_args const *pd_args() const { return 0; } @@ -121,7 +121,7 @@ struct Genode::Child_policy /** * Respond to the release of resources by the child * - * This function is called when the child confirms the release of + * This method is called when the child confirms the release of * resources in response to a yield request. */ virtual void yield_response() { } @@ -137,14 +137,11 @@ struct Genode::Child_policy * Implementation of the parent interface that supports resource trading * * There are three possible cases of how a session can be provided to - * a child: - * - * # The service is implemented locally - * # The session was obtained by asking our parent - * # The session is provided by one of our children + * a child: The service is implemented locally, the session was obtained by + * asking our parent, or the session is provided by one of our children. * * These types must be differentiated for the quota management when a child - * issues the closing of a session or a transfers quota via our parent + * issues the closing of a session or transfers quota via our parent * interface. * * If we close a session to a local service, we transfer the session quota @@ -154,7 +151,7 @@ struct Genode::Child_policy * account and must transfer this amount to the session-closing child. * * If we close a session provided by a server child, we close the session - * at the server, transfer the session quota from the server's ram session + * at the server, transfer the session quota from the server's RAM session * to our account, and subsequently transfer the same amount from our * account to the client. */ @@ -225,7 +222,7 @@ class Genode::Child : protected Rpc_object /** * Return service interface targetting the parent * - * The service returned by this function is used as default + * The service returned by this method is used as default * provider for the RAM, CPU, and RM resources of the child. It is * solely used for targeting resource donations during * 'Parent::upgrade_quota()' calls. @@ -290,7 +287,7 @@ class Genode::Child : protected Rpc_object /** * Discard all sessions to specified service * - * When this function is called, we assume the server protection + * When this method is called, we assume the server protection * domain to be dead and all that all server quota was already * transferred back to our own 'env()->ram_session()' account. Note * that the specified server object may not exist anymore. We do @@ -301,7 +298,7 @@ class Genode::Child : protected Rpc_object /** * Instruct the child to yield resources * - * By calling this function, the child will be notified about the + * By calling this method, the child will be notified about the * need to release the specified amount of resources. For more * details about the protocol between a child and its parent, * refer to the description given in 'parent/parent.h'. diff --git a/repos/base/include/base/connection.h b/repos/base/include/base/connection.h index cdc7209883..c52717dd12 100644 --- a/repos/base/include/base/connection.h +++ b/repos/base/include/base/connection.h @@ -65,6 +65,13 @@ class Genode::Connection : public Noncopyable * * \param cap session capability * \param od session policy applied when destructing the connection + * + * The 'op' argument defines whether the session should automatically + * be closed by the destructor of the connection (CLOSE), or the + * session should stay open (KEEP_OPEN). The latter is useful in + * situations where the creator a connection merely passes the + * session capability of the connection to another party but never + * invokes any of the session's RPC functions. */ Connection(Capability cap, On_destruction od = CLOSE): _cap(cap), _on_destruction(od) { } diff --git a/repos/base/include/base/console.h b/repos/base/include/base/console.h index 51d0fe7fc8..8aebec2cd4 100644 --- a/repos/base/include/base/console.h +++ b/repos/base/include/base/console.h @@ -34,18 +34,18 @@ class Genode::Console protected: /** - * Backend function for the output of one character + * Back end used for the output of a single character */ virtual void _out_char(char c) = 0; /** - * Backend function for the output of a null-terminated string + * Back end for the output of a null-terminated string * - * The default implementation uses _out_char. This function may + * The default implementation uses _out_char. This method may * be overridden by the backend for improving efficiency. * - * This function is virtual to enable the use an optimized - * string-output functions on some target platforms, e.g. + * This method is virtual to enable the use an optimized + * string-output operation on some target platforms, e.g., * a kernel debugger that offers a string-output syscall. The * default implementation calls '_out_char' for each character. */ diff --git a/repos/base/include/base/env.h b/repos/base/include/base/env.h index 0467150b4f..2f915ed9a9 100644 --- a/repos/base/include/base/env.h +++ b/repos/base/include/base/env.h @@ -1,10 +1,7 @@ /* - * \brief Environment of a process + * \brief Environment of a component * \author Norman Feske * \date 2006-07-01 - * - * The environment of a Genode process is defined by its parent and initialized - * on startup. */ /* diff --git a/repos/base/include/base/heap.h b/repos/base/include/base/heap.h index 9ec53262a6..8a1e477d0c 100644 --- a/repos/base/include/base/heap.h +++ b/repos/base/include/base/heap.h @@ -30,7 +30,7 @@ namespace Genode { /** * Heap that uses dataspaces as backing store * - * The heap class provides an allocator that uses a list of dataspaces of a ram + * The heap class provides an allocator that uses a list of dataspaces of a RAM * session as backing store. One dataspace may be used for holding multiple blocks. */ class Genode::Heap : public Allocator @@ -76,7 +76,7 @@ class Genode::Heap : public Allocator */ struct Dataspace_pool : public List { - Ram_session *ram_session; /* ram session for backing store */ + Ram_session *ram_session; /* RAM session for backing store */ Rm_session *rm_session; /* region manager */ Dataspace_pool(Ram_session *ram_session, Rm_session *rm_session) @@ -120,7 +120,7 @@ class Genode::Heap : public Allocator * * \return true on success * - * This function is a utility used by '_unsynchronized_alloc' to + * This method is a utility used by '_unsynchronized_alloc' to * avoid code duplication. */ bool _try_local_alloc(size_t size, void **out_addr); @@ -185,7 +185,7 @@ class Genode::Sliced_heap : public Allocator class Block; - Ram_session *_ram_session; /* ram session for backing store */ + Ram_session *_ram_session; /* RAM session for backing store */ Rm_session *_rm_session; /* region manager */ size_t _consumed; /* number of allocated bytes */ List _block_list; /* list of allocated blocks */ diff --git a/repos/base/include/base/ipc.h b/repos/base/include/base/ipc.h index bb4b3c0399..63049a692f 100644 --- a/repos/base/include/base/ipc.h +++ b/repos/base/include/base/ipc.h @@ -295,7 +295,7 @@ class Genode::Ipc_ostream : public Ipc_marshaller /** * Return current 'IPC_SEND' destination * - * This function is typically needed by a server than sends replies + * This method is typically needed by a server than sends replies * in a different order as the incoming calls. */ Native_capability dst() const { return _dst; } @@ -535,7 +535,7 @@ class Genode::Ipc_server : public Ipc_istream, public Ipc_ostream /** * Wait for incoming call * - * In constrast to 'Ipc_istream::_wait()', this function stores the + * In constrast to 'Ipc_istream::_wait()', this method stores the * next reply destination from into 'dst' of the 'Ipc_ostream'. */ void _wait(); @@ -543,7 +543,7 @@ class Genode::Ipc_server : public Ipc_istream, public Ipc_ostream /** * Send reply to destination * - * In contrast to 'Ipc_ostream::_send()', this function prepares + * In contrast to 'Ipc_ostream::_send()', this method prepares * the 'Ipc_server' to send another subsequent reply without the * calling '_wait()' in between. This is needed when a server * answers calls out of order. diff --git a/repos/base/include/base/lock_guard.h b/repos/base/include/base/lock_guard.h index 261a95c6f0..5ddcf364e7 100644 --- a/repos/base/include/base/lock_guard.h +++ b/repos/base/include/base/lock_guard.h @@ -2,13 +2,6 @@ * \brief Lock guard * \author Norman Feske * \date 2006-07-26 - * - * A lock guard is instantiated as a local variable. - * When a lock guard is constructed, it acquires the lock that - * is specified as constructor argument. When the control - * flow leaves the scope of the lock guard variable via - * a return statement or an exception, the lock guard's - * destructor gets called, freeing the lock. */ /* @@ -28,6 +21,12 @@ namespace Genode { template class Lock_guard; } * Lock guard template * * \param LT lock type + * + * A lock guard is instantiated as a local variable. When a lock guard is + * constructed, it acquires the lock that is specified as constructor argument. + * When the control flow leaves the scope of the lock-guard variable via a + * return statement or an exception, the lock guard's destructor gets called, + * freeing the lock. */ template class Genode::Lock_guard diff --git a/repos/base/include/base/native_capability.h b/repos/base/include/base/native_capability.h index 2c7e291120..6328b51dfb 100644 --- a/repos/base/include/base/native_capability.h +++ b/repos/base/include/base/native_capability.h @@ -38,8 +38,8 @@ namespace Genode { template class Native_capability_tpl; } * * The 'Dst' type is the platform-specific destination type (e.g., the ID * of the destination thread targeted by the capability). The 'valid' - * function returns true if the specified destination is valid. The - * 'invalid' function produces an invalid destination. + * method returns true if the specified destination is valid. The + * 'invalid' method produces an invalid destination. */ template class Genode::Native_capability_tpl diff --git a/repos/base/include/base/object_pool.h b/repos/base/include/base/object_pool.h index 93db32b025..7df0d5a419 100644 --- a/repos/base/include/base/object_pool.h +++ b/repos/base/include/base/object_pool.h @@ -73,10 +73,11 @@ class Genode::Object_pool friend class Object_pool; friend class Avl_tree; - /** - * Support functions for atomic lookup and lock - * functionality of class Object_pool. + /* + * Support methods for atomic lookup and lock functionality of + * class Object_pool. */ + void lock() { _entry_lock.lock(); }; void unlock() { _entry_lock.unlock(); }; diff --git a/repos/base/include/base/pager.h b/repos/base/include/base/pager.h index 09be0bf0f6..7a21b1342e 100644 --- a/repos/base/include/base/pager.h +++ b/repos/base/include/base/pager.h @@ -149,7 +149,7 @@ class Genode::Pager_activation_base: public Thread_base /** * Set entry point, which the activation serves * - * This function is only called by the 'Pager_entrypoint' + * This method is only called by the 'Pager_entrypoint' * constructor. */ void ep(Pager_entrypoint *ep) { _ep = ep; } @@ -162,7 +162,7 @@ class Genode::Pager_activation_base: public Thread_base /** * Return capability to this activation * - * This function should only be called from 'Pager_entrypoint' + * This method should only be called from 'Pager_entrypoint' */ Native_capability cap() { diff --git a/repos/base/include/base/printf.h b/repos/base/include/base/printf.h index ef514d0f4b..27f7acac6b 100644 --- a/repos/base/include/base/printf.h +++ b/repos/base/include/base/printf.h @@ -1,5 +1,5 @@ /* - * \brief Interface of the printf backend + * \brief Interface of the printf back end * \author Norman Feske * \date 2006-04-08 */ @@ -19,9 +19,10 @@ namespace Genode { /** - * For your convenience... + * Output format string to LOG session */ void printf(const char *format, ...) __attribute__((format(printf, 1, 2))); + void vprintf(const char *format, va_list) __attribute__((format(printf, 1, 0))); } diff --git a/repos/base/include/base/rpc.h b/repos/base/include/base/rpc.h index 73e92559a1..b28c7e5ec9 100644 --- a/repos/base/include/base/rpc.h +++ b/repos/base/include/base/rpc.h @@ -18,7 +18,7 @@ /** - * Macro for declaring a RPC function + * Macro for declaring an RPC function * * \param rpc_name type name representing the RPC function * \param ret_type RPC return type diff --git a/repos/base/include/base/rpc_args.h b/repos/base/include/base/rpc_args.h index e232951fce..a70869be44 100644 --- a/repos/base/include/base/rpc_args.h +++ b/repos/base/include/base/rpc_args.h @@ -114,7 +114,7 @@ class Genode::Rpc_in_buffer : public Rpc_in_buffer_base * * \return pointer to null-terminated string * - * The function returns an empty string if the buffer does not hold + * The method returns an empty string if the buffer does not hold * a valid null-terminated string. To distinguish a buffer holding * an invalid string from a buffer holding a valid empty string, * the function 'is_valid_string' can be used. diff --git a/repos/base/include/base/rpc_client.h b/repos/base/include/base/rpc_client.h index 49b0090f8d..f5082e9067 100644 --- a/repos/base/include/base/rpc_client.h +++ b/repos/base/include/base/rpc_client.h @@ -19,24 +19,7 @@ namespace Genode { - /** - * RPC client - * - * This class template is the base class of the client-side implementation - * of the specified 'RPC_INTERFACE'. Usually, it inherits the pure virtual - * functions declared in 'RPC_INTERFACE' and has the built-in facility to - * perform RPC calls to this particular interface. Hence, the client-side - * implementation of each pure virtual interface function comes down to a - * simple wrapper in the line of 'return call(arguments...)'. - */ - template - struct Rpc_client : Capability, RPC_INTERFACE - { - typedef RPC_INTERFACE Rpc_interface; - - Rpc_client(Capability const &cap) - : Capability(cap) { } - }; + template struct Rpc_client; /** * Count capabilities of a RPC_FUNCTION which are out parameters. @@ -68,9 +51,9 @@ namespace Genode { enum { Value = Rpc_caps_out::Value + Cap_return ::Value}; }; - /********************************************************* + /*************************************************** ** Implementation of 'Capability:call' functions ** - *********************************************************/ + ***************************************************/ template template @@ -171,4 +154,25 @@ namespace Genode { } } + +/** + * RPC client + * + * This class template is the base class of the client-side implementation + * of the specified 'RPC_INTERFACE'. Usually, it inherits the pure virtual + * functions declared in 'RPC_INTERFACE' and has the built-in facility to + * perform RPC calls to this particular interface. Hence, the client-side + * implementation of each pure virtual interface function comes down to a + * simple wrapper in the line of 'return call(arguments...)'. + */ +template +struct Genode::Rpc_client : Capability, RPC_INTERFACE +{ + typedef RPC_INTERFACE Rpc_interface; + + Rpc_client(Capability const &cap) + : Capability(cap) { } +}; + + #endif /* _INCLUDE__BASE__RPC_CLIENT_H_ */ diff --git a/repos/base/include/base/rpc_server.h b/repos/base/include/base/rpc_server.h index 528b4cb2c9..5a0186bc15 100644 --- a/repos/base/include/base/rpc_server.h +++ b/repos/base/include/base/rpc_server.h @@ -42,11 +42,11 @@ namespace Genode { * server functions according to the RPC declarations in 'RPC_INTERFACE'. * * If using the default argument for 'SERVER', the 'RPC_INTERFACE' is expected - * to contain the abstract interface for all RPC functions. So virtual functions + * to contain the abstract interface for all RPC functions. So virtual methods * must be declared in 'RPC_INTERFACE'. In contrast, by explicitly specifying - * the 'SERVER' argument, the server-side dispatching performs direct function - * calls to the respective member functions of the 'SERVER' class and thereby - * omits virtual functions calls. + * the 'SERVER' argument, the server-side dispatching performs direct + * calls to the respective methods of the 'SERVER' class and thereby + * omits virtual method calls. */ template class Genode::Rpc_dispatcher : public RPC_INTERFACE @@ -232,7 +232,7 @@ struct Genode::Rpc_object : Rpc_object_base, Rpc_dispatcher /** * Hook to let low-level thread init code access private members * - * This function is only used on NOVA. + * This method is only used on NOVA. */ static void _activation_entry(); @@ -285,27 +285,37 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool Capability _exit_cap; /** - * Back-end function to associate RPC object with the entry point + * Back end used to associate RPC object with the entry point + * + * \noapi */ Untyped_capability _manage(Rpc_object_base *obj); /** - * Back-end function to Dissolve RPC object from entry point + * Back end used to Dissolve RPC object from entry point + * + * \noapi */ void _dissolve(Rpc_object_base *obj); /** * Force activation to cancel dispatching the specified server object + * + * \noapi */ void _leave_server_object(Rpc_object_base *obj); /** * Wait until the entrypoint activation is initialized + * + * \noapi */ void _block_until_cap_valid(); /** * Thread interface + * + * \noapi */ void entry(); @@ -354,10 +364,12 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool /** * Request reply capability for current call * - * Note: This is a temporary API function, which is going to be - * removed. Please do not use this function. + * \noapi * - * Typically, a capability obtained via this function is used as + * Note: This is a temporary API method, which is going to be + * removed. Please do not use this method. + * + * Typically, a capability obtained via this method is used as * argument of 'intermediate_reply'. */ Untyped_capability reply_dst(); @@ -365,24 +377,28 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool /** * Prevent reply of current request * - * Note: This is a temporary API function, which is going to be - * removed. Please do not use this function. + * \noapi * - * This function can be used to keep the calling client blocked + * Note: This is a temporary API method, which is going to be + * removed. Please do not use this method. + * + * This method can be used to keep the calling client blocked * after the server has finished the processing of the client's * request. At a later time, the server may chose to unblock the - * client via the 'intermedate_reply' function. + * client via the 'intermedate_reply' method. */ void omit_reply(); /** * Send a reply out of the normal call-reply order * - * Note: This is a temporary API function, which is going to be - * removed. Please do not use this function. + * \noapi * - * In combination with the 'reply_dst' accessor functions, this - * function can be used to implement services that dispatch client + * Note: This is a temporary API method, which is going to be + * removed. Please do not use this method. + * + * In combination with the 'reply_dst' accessor method, this + * method can be used to implement services that dispatch client * requests out of order. In such cases, the server activation may * send reply messages to multiple blocking clients before * answering the original call. @@ -391,6 +407,10 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool /** * Return true if the caller corresponds to the entrypoint called + * + * \noapi + * + * This method is solely needed on Linux. */ bool is_myself() const; }; diff --git a/repos/base/include/base/semaphore.h b/repos/base/include/base/semaphore.h index f0908f0b01..81f80c27ef 100644 --- a/repos/base/include/base/semaphore.h +++ b/repos/base/include/base/semaphore.h @@ -53,6 +53,12 @@ class Genode::Semaphore try { _meta_lock.lock(); } catch (...) { } } + /** + * Increment semphore counter + * + * This method may wake up another thread that currently blocks on + * a 'down' call at the same semaphore. + */ void up() { Lock::Guard lock_guard(_meta_lock); @@ -69,6 +75,9 @@ class Genode::Semaphore element->wake_up(); } + /** + * Decrement semaphore counter, block if the counter reaches zero + */ void down() { _meta_lock.lock(); diff --git a/repos/base/include/base/service.h b/repos/base/include/base/service.h index 1940efd64d..91001eff55 100644 --- a/repos/base/include/base/service.h +++ b/repos/base/include/base/service.h @@ -370,9 +370,9 @@ class Genode::Service_registry /** * Wait for service * - * This function is called by the clients's thread - * when requesting a session creation. It blocks - * if the requested service is not available. + * This method is called by the clients's thread when requesting a + * session creation. It blocks if the requested service is not + * available. * * \return service structure that matches the request or * 0 if the waiting was canceled. @@ -422,7 +422,7 @@ class Genode::Service_registry /** * Register service * - * This function is called by the server's thread. + * This method is called by the server's thread. */ void insert(Service *service) { diff --git a/repos/base/include/base/signal.h b/repos/base/include/base/signal.h index 4f0885ab38..a3ac70cefd 100644 --- a/repos/base/include/base/signal.h +++ b/repos/base/include/base/signal.h @@ -91,7 +91,7 @@ class Genode::Signal */ Signal(Data data); - friend class Kernel::Signal_receiver; + friend class Kernel::Signal_receiver; friend class Signal_receiver; friend class Signal_context; @@ -101,7 +101,12 @@ class Genode::Signal public: Signal(Signal const &other); - Signal &operator=(Signal const &other); + + /** + * \noapi + */ + Signal &operator = (Signal const &other); + ~Signal(); Signal_context *context() { return _data.context; } @@ -184,9 +189,9 @@ class Genode::Signal_receiver : Noncopyable /** * Helper to dissolve given context * - * This function prevents duplicated code in '~Signal_receiver' + * This method prevents duplicated code in '~Signal_receiver' * and 'dissolve'. Note that '_contexts_lock' must be held when - * calling this function. + * calling this method. */ void _unsynchronized_dissolve(Signal_context *context); @@ -246,13 +251,17 @@ class Genode::Signal_receiver : Noncopyable /** * Locally submit signal to the receiver + * + * \noapi */ void local_submit(Signal::Data signal); /** * Framework-internal signal-dispatcher * - * This function is called from the thread that monitors the signal + * \noapi + * + * This method is called from the thread that monitors the signal * source associated with the process. It must not be used for other * purposes. */ @@ -265,7 +274,7 @@ class Genode::Signal_receiver : Noncopyable * * A signal context is a destination for signals. One receiver can listen * to multple contexts. If a signal arrives, the context is provided with the - * signel. This enables the receiver to distinguish different signal sources + * signal. This enables the receiver to distinguish different signal sources * and dispatch incoming signals context-specific. */ class Genode::Signal_context @@ -286,7 +295,7 @@ class Genode::Signal_context * Receiver to which the context is associated with * * This member is initialized by the receiver when associating - * the context with the receiver via the 'cap' function. + * the context with the receiver via the 'cap' method. */ Signal_receiver *_receiver; @@ -299,7 +308,7 @@ class Genode::Signal_context /** * Capability assigned to this context after being assocated with - * a 'Signal_receiver' via the 'manage' function. We store this + * a 'Signal_receiver' via the 'manage' method. We store this * capability in the 'Signal_context' for the mere reason to * properly destruct the context (see '_unsynchronized_dissolve'). */ @@ -330,6 +339,8 @@ class Genode::Signal_context /** * Local signal submission (DEPRECATED) * + * \noapi + * * Trigger local signal submission (within the same address space), the * context has to be bound to a sginal receiver beforehand. * @@ -339,7 +350,7 @@ class Genode::Signal_context /* * Signal contexts are never invoked but only used as arguments for - * 'Signal_session' functions. Hence, there exists a capability + * 'Signal_session' methods. Hence, there exists a capability * type for it but no real RPC interface. */ GENODE_RPC_INTERFACE(); @@ -356,13 +367,13 @@ struct Genode::Signal_dispatcher_base : Signal_context /** - * Adapter for directing signals to member functions + * Adapter for directing signals to object methods * - * This utility associates member functions with signals. It is intended to + * This utility associates object methods with signals. It is intended to * be used as a member variable of the class that handles incoming signals * of a certain type. The constructor takes a pointer-to-member to the - * signal handling function as argument. If a signal is received at the - * common signal reception code, this function will be invoked by calling + * signal handling method as argument. If a signal is received at the + * common signal reception code, this method will be invoked by calling * 'Signal_dispatcher_base::dispatch'. * * \param T type of signal-handling class @@ -384,7 +395,7 @@ class Genode::Signal_dispatcher : public Signal_dispatcher_base, * * \param sig_rec signal receiver to associate the signal * handler with - * \param obj,member object and member function to call when + * \param obj,member object and method to call when * the signal occurs */ Signal_dispatcher(Signal_receiver &sig_rec, diff --git a/repos/base/include/base/slab.h b/repos/base/include/base/slab.h index c42126b32d..54ee222589 100644 --- a/repos/base/include/base/slab.h +++ b/repos/base/include/base/slab.h @@ -59,11 +59,13 @@ class Genode::Slab_block */ /** - * Accessor functions to allocation state - * - * \param idx index of slab entry + * Return the allocation state of a slab entry */ inline bool state(int idx) { return _data[idx]; } + + /** + * Set the allocation state of a slab entry + */ inline void state(int idx, bool state) { _data[idx] = state; } /** @@ -205,16 +207,22 @@ class Genode::Slab : public Allocator /** * Debug function for dumping the current slab block list + * + * \noapi */ void dump_sb_list(); /** * Remove block from slab block list + * + * \noapi */ void remove_sb(Slab_block *sb); /** * Insert block into slab block list + * + * \noapi */ void insert_sb(Slab_block *sb, Slab_block *at = 0); @@ -235,8 +243,16 @@ class Genode::Slab : public Allocator /** * Define/request backing-store allocator + * + * \noapi */ void backing_store(Allocator *bs) { _backing_store = bs; } + + /** + * Request backing-store allocator + * + * \noapi + */ Allocator *backing_store() { return _backing_store; } /************************* diff --git a/repos/base/include/base/snprintf.h b/repos/base/include/base/snprintf.h index 1735ac39d3..92a6ae5a38 100644 --- a/repos/base/include/base/snprintf.h +++ b/repos/base/include/base/snprintf.h @@ -24,9 +24,13 @@ namespace Genode { /** * Print format string into character buffer * + * \param dst destination buffer + * \param dst_len size of 'dst' in bytes + * \param format format string followed by the list of arguments + * * \return number of characters written to destination buffer */ - inline int snprintf(char *, size_t, const char *, ...) + inline int snprintf(char *dst, size_t dst_size, const char *format, ...) __attribute__((format(printf, 3, 4))); } @@ -45,7 +49,7 @@ class Genode::String_console : public Console * Constructor * * \param dst destination character buffer - * \param dst_len size of dst + * \param dst_len size of 'dst' */ String_console(char *dst, size_t dst_len) : _dst(dst), _dst_len(dst_len), _w_offset(0) diff --git a/repos/base/include/base/stdint.h b/repos/base/include/base/stdint.h index 72876c888f..5c1f032b5a 100644 --- a/repos/base/include/base/stdint.h +++ b/repos/base/include/base/stdint.h @@ -1,5 +1,5 @@ /* - * \brief Genode-specific integer types + * \brief Integer types * \author Christian Helmuth * \date 2006-05-10 */ diff --git a/repos/base/include/base/sync_allocator.h b/repos/base/include/base/sync_allocator.h index c84fc038e9..10ebac5183 100644 --- a/repos/base/include/base/sync_allocator.h +++ b/repos/base/include/base/sync_allocator.h @@ -165,7 +165,7 @@ class Genode::Synchronized_range_allocator : public Range_allocator * methods in addition to the Range_allocator interface. * * NOTE: Synchronize accesses to the raw allocator by facilitating - * the lock() member function. + * the lock() method. */ ALLOCATOR_IMPL *raw() { return &_alloc; } diff --git a/repos/base/include/base/thread.h b/repos/base/include/base/thread.h index 6caa75038e..f30cb220dd 100644 --- a/repos/base/include/base/thread.h +++ b/repos/base/include/base/thread.h @@ -78,7 +78,7 @@ namespace Genode { * Concurrent control flow * * A 'Thread_base' object corresponds to a physical thread. The execution - * starts at the 'entry()' function as soon as 'start()' is called. + * starts at the 'entry()' method as soon as 'start()' is called. */ class Genode::Thread_base { @@ -260,7 +260,7 @@ class Genode::Thread_base * * On some platforms, each new thread has to perform a startup * protocol, e.g., waiting for a message from the kernel. This hook - * function allows for the implementation of such protocols. + * method allows for the implementation of such protocols. */ void _thread_bootstrap(); @@ -323,7 +323,7 @@ class Genode::Thread_base /** * Return 'Trace::Logger' instance of calling thread * - * This function is used by the tracing framework internally. + * This method is used by the tracing framework internally. */ static Trace::Logger *_logger(); @@ -354,7 +354,7 @@ class Genode::Thread_base * Constructor * * \param quota CPU quota that shall be granted to the thread - * \param name thread name for debugging + * \param name thread name for DEBUGging * \param stack_size stack size * * \throw Stack_too_large @@ -365,7 +365,6 @@ class Genode::Thread_base * of the process environment. A small portion of the stack size is * internally used by the framework for storing thread-context * information such as the thread's name ('Context'). - * */ Thread_base(size_t quota, const char *name, size_t stack_size) : @@ -400,14 +399,14 @@ class Genode::Thread_base virtual ~Thread_base(); /** - * Entry function of the thread + * Entry method of the thread */ virtual void entry() = 0; /** * Start execution of the thread * - * This function is virtual to enable the customization of threads + * This method is virtual to enable the customization of threads * used as server activation. */ virtual void start(); @@ -450,7 +449,9 @@ class Genode::Thread_base void cancel_blocking(); /** - * Only to be called from platform-specific code + * Return thread ID + * + * \noapi Only to be called from platform-specific code */ Native_thread & tid() { return _tid; } @@ -471,8 +472,7 @@ class Genode::Thread_base /** * Return 'Thread_base' object corresponding to the calling thread * - * \return pointer to 'Thread_base' object, or - * 0 if the calling thread is the main thread + * \return pointer to caller's 'Thread_base' object */ static Thread_base *myself(); @@ -489,14 +489,15 @@ class Genode::Thread_base /** * Return user-level thread control block * - * Note that it is safe to call this function on the result of the - * 'myself' function. It handles the special case of 'myself' being - * 0 when called by the main thread. + * Note that it is safe to call this method on the result of the + * 'myself' class function. It handles the special case of 'myself' + * being 0 when called by the main thread during the component + * initialization phase. */ Native_utcb *utcb(); /** - * Block until the thread leaves the 'entry' function + * Block until the thread leaves the 'entry' method * * Join must not be called more than once. Subsequent calls have * undefined behaviour. diff --git a/repos/base/include/base/weak_ptr.h b/repos/base/include/base/weak_ptr.h index 754a803a72..17289171d9 100644 --- a/repos/base/include/base/weak_ptr.h +++ b/repos/base/include/base/weak_ptr.h @@ -2,40 +2,6 @@ * \brief Utilities for object life-time management * \author Norman Feske * \date 2013-03-09 - * - * This header provides utilities for avoiding dangling pointers. Such a - * situation happens when an object disappears while pointers to the object - * are still in use. One way to solve this problem is to explicitly notify the - * holders of those pointers about the disappearance of the object. But this - * would require the object to keep references to those pointer holder, which, - * in turn, might disappear as well. Consequently, this approach tends to - * become a complex solution, which is prone to deadlocks or race conditions - * when multiple threads are involved. - * - * The utilities provided herein implement a more elegant pattern called - * "weak pointers" to deal with such situations. An object that might - * disappear at any time is represented by the 'Weak_object' class - * template. It keeps track of a list of so-called weak pointers pointing - * to the object. A weak pointer, in turn, holds privately the pointer to the - * object alongside a validity flag. It cannot be used to dereference the - * object. For accessing the actual object, a locked pointer must be created - * from a weak pointer. If this creation succeeds, the object is guaranteed to - * be locked (not destructed) until the locked pointer gets destroyed. If the - * object no longer exists, the locked pointer will be invalid. This condition - * can (and should) be detected via the 'Locked_ptr::is_valid()' function prior - * dereferencing the pointer. - * - * In the event a weak object gets destructed, all weak pointers that point - * to the object are automatically invalidated. So a subsequent conversion into - * a locked pointer will yield an invalid pointer, which can be detected (in - * contrast to a dangling pointer). - * - * To use this mechanism, the destruction of a weak object must be - * deferred until no locked pointer points to the object anymore. This is - * done by calling the function 'Weak_object::lock_for_destruction()' - * at the beginning of the destructor of the to-be-destructed object. - * When this function returns, all weak pointers to the object will have been - * invalidated. So it is save to destruct and free the object. */ /* @@ -62,6 +28,12 @@ namespace Genode { } +/** + * Type-agnostic base class of a weak pointer + * + * This class implements the mechanics of the the 'Weak_ptr' class template. + * It is not used directly. + */ class Genode::Weak_ptr_base : public Genode::List::Element { private: @@ -79,6 +51,11 @@ class Genode::Weak_ptr_base : public Genode::List::Element protected: + /** + * Return pointer to object if it exists, or 0 if object vanished + * + * \noapi + */ Weak_object_base *obj() const { return _valid ? _obj: 0; } explicit inline Weak_ptr_base(Weak_object_base *obj); @@ -104,11 +81,16 @@ class Genode::Weak_ptr_base : public Genode::List::Element /** * Inspection hook for unit test + * + * \noapi */ void debug_info() const; }; +/** + * Type-agnostic base class of a weak object + */ class Genode::Weak_object_base { private: @@ -130,10 +112,17 @@ class Genode::Weak_object_base protected: + /** + * Destructor + * + * \noapi + */ inline ~Weak_object_base(); /** * To be called from 'Weak_object' only + * + * \noapi */ template Weak_ptr _weak_ptr(); @@ -141,13 +130,17 @@ class Genode::Weak_object_base public: /** - * Function to be called by the destructor of a weak object to + * Mark object as safe to be destructed + * + * This method must be called by the destructor of a weak object to * defer the destruction until no 'Locked_ptr' is held to the object. */ void lock_for_destruction() { _destruct_lock.lock(); } /** * Inspection hook for unit test + * + * \noapi */ void debug_info() const; }; @@ -159,11 +152,33 @@ class Genode::Locked_ptr_base Weak_object_base *curr; + /** + * Constructor + * + * \noapi + */ inline Locked_ptr_base(Weak_ptr_base &weak_ptr); + + /** + * Destructor + * + * \noapi + */ inline ~Locked_ptr_base(); }; +/** + * Weak pointer to a given type + * + * A weak pointer can be obtained from a weak object (an object that inherits + * the 'Weak_object' class template) and safely survives the lifetime of the + * associated weak object. If the weak object disappears, all + * weak pointers referring to the object are automatically invalidated. + * To avoid race conditions between the destruction and use of a weak object, + * a weak pointer cannot be de-reference directly. To access the object, a + * weak pointer must be turned into a locked pointer ('Locked_ptr'). + */ template struct Genode::Weak_ptr : Genode::Weak_ptr_base { @@ -187,13 +202,38 @@ struct Genode::Weak_ptr : Genode::Weak_ptr_base }; +/** + * Weak object + * + * This class template must be inherited in order to equip an object with + * the weak-pointer mechanism. + * + * \param T type of the derived class + */ template struct Genode::Weak_object : Genode::Weak_object_base { + /** + * Obtain a weak pointer referring to the weak object + */ Weak_ptr weak_ptr() { return _weak_ptr(); } }; +/** + * Locked pointer + * + * A locked pointer is constructed from a weak pointer. After construction, + * its validity can (and should) be checked by calling the 'is_valid' + * method. If the locked pointer is valid, the pointed-to object is known to + * be locked until the locked pointer is destroyed. During this time, the + * locked pointer can safely be de-referenced. + * + * The typical pattern of using a locked pointer is to declare it as a + * local variable. Once the execution leaves the scope of the variable, the + * locked pointer is destructed, which unlocks the pointed-to weak object. + * It effectively serves as a lock guard. + */ template struct Genode::Locked_ptr : Genode::Locked_ptr_base { @@ -203,6 +243,12 @@ struct Genode::Locked_ptr : Genode::Locked_ptr_base T &operator * () { return *static_cast(curr); } + /** + * Returns true if the locked pointer is valid + * + * Only if valid, the locked pointer can be de-referenced. Otherwise, + * the attempt will result in a null-pointer access. + */ bool is_valid() const { return curr != 0; } }; diff --git a/repos/base/include/cpu_session/cpu_session.h b/repos/base/include/cpu_session/cpu_session.h index 16bed05483..50fa035d75 100644 --- a/repos/base/include/cpu_session/cpu_session.h +++ b/repos/base/include/cpu_session/cpu_session.h @@ -103,7 +103,7 @@ struct Genode::Cpu_session : Session /** * Pause the specified thread * - * After calling this function, the execution of the thread can be + * After calling this method, the execution of the thread can be * continued by calling 'resume'. */ virtual void pause(Thread_capability thread) = 0; @@ -158,7 +158,7 @@ struct Genode::Cpu_session : Session /** * Enable/disable single stepping for specified thread. * - * Since this functions is currently supported by a small number of + * Since this method is currently supported by a small number of * platforms, we provide a default implementation * * \param thread thread to set into single step mode @@ -169,7 +169,7 @@ struct Genode::Cpu_session : Session /** * Return affinity space of CPU nodes available to the CPU session * - * The dimension of the affinity space as returned by this function + * The dimension of the affinity space as returned by this method * represent the physical CPUs that are available. */ virtual Affinity::Space affinity_space() const = 0; @@ -335,7 +335,7 @@ struct Genode::Cpu_session : Session /* * 'GENODE_RPC_INTERFACE' declaration done manually * - * The number of RPC function of this interface exceeds the maximum + * The number of RPC functions of this interface exceeds the maximum * number of elements supported by 'Meta::Type_list'. Therefore, we * construct the type list by hand using nested type tuples instead * of employing the convenience macro 'GENODE_RPC_INTERFACE'. diff --git a/repos/base/include/io_port_session/io_port_session.h b/repos/base/include/io_port_session/io_port_session.h index df5e4acd67..9a40b14aba 100644 --- a/repos/base/include/io_port_session/io_port_session.h +++ b/repos/base/include/io_port_session/io_port_session.h @@ -7,7 +7,7 @@ * variable-sized accesses (i.e., 8, 16, 32 bit) at arbitrary addresses are * allowed - currently, alignment is not enforced. Core enforces that access is * limited to the session-defined range while the user provides physical I/O port - * addresses as function parameters. + * addresses as arguments. * * The design is founded on experiences while programming PCI configuration * space which needs two 32-bit port registers. Each byte, word and dword in diff --git a/repos/base/include/parent/parent.h b/repos/base/include/parent/parent.h index 6bf10de39c..31610382f4 100644 --- a/repos/base/include/parent/parent.h +++ b/repos/base/include/parent/parent.h @@ -90,7 +90,7 @@ class Genode::Parent * The type of the specified 'service_root' capability match with * an interface that provides a 'Session_type' type (i.e., a * 'Typed_root' interface). This 'Session_type' is expected to - * host a static function called 'service_name' returning the + * host a class function called 'service_name' returning the * name of the provided interface as null-terminated string. */ template @@ -123,7 +123,7 @@ class Genode::Parent * * \return untyped capability to new session * - * The use of this function is discouraged. Please use the type safe + * The use of this method is discouraged. Please use the type safe * 'session()' template instead. */ virtual Session_capability session(Service_name const &service_name, @@ -162,7 +162,7 @@ class Genode::Parent * \throw Quota_exceeded quota could not be transferred * * The 'args' argument has the same principle format as the 'args' - * argument of the 'session' function. + * argument of the 'session' operation. * The error case indicates that there is not enough unused quota on * the source side. */ @@ -187,7 +187,7 @@ class Genode::Parent /** * Request additional resources * - * By invoking this function, a process is able to inform its + * By invoking this method, a process is able to inform its * parent about the need for additional resources. The argument * string contains a resource description in the same format as * used for session-construction arguments. In particular, for @@ -212,7 +212,7 @@ class Genode::Parent /** * Obtain information about the amount of resources to free * - * The amount of resources returned by this function is the + * The amount of resources returned by this method is the * goal set by the parent. It is not commanded but merely meant * as a friendly beg to cooperate. The process is not obligated * to comply. If the process decides to take action to free diff --git a/repos/base/include/ram_session/client.h b/repos/base/include/ram_session/client.h index 4171a8eea9..910b618fbd 100644 --- a/repos/base/include/ram_session/client.h +++ b/repos/base/include/ram_session/client.h @@ -1,5 +1,5 @@ /* - * \brief Client-side ram session interface + * \brief Client-side RAM session interface * \author Norman Feske * \date 2006-05-31 */ diff --git a/repos/base/include/ram_session/ram_session.h b/repos/base/include/ram_session/ram_session.h index 085939d4c1..5cc41bd632 100644 --- a/repos/base/include/ram_session/ram_session.h +++ b/repos/base/include/ram_session/ram_session.h @@ -34,6 +34,9 @@ namespace Genode { struct Genode::Ram_dataspace : Dataspace { }; +/** + * RAM session interface + */ struct Genode::Ram_session : Session { static const char *service_name() { return "RAM"; } diff --git a/repos/base/include/rom_session/rom_session.h b/repos/base/include/rom_session/rom_session.h index d5cf419ba1..a218703b71 100644 --- a/repos/base/include/rom_session/rom_session.h +++ b/repos/base/include/rom_session/rom_session.h @@ -46,11 +46,11 @@ struct Genode::Rom_session : Session * * The capability may be invalid. * - * Consecutive calls of this functions are not guaranteed to return the + * Consecutive calls of this method are not guaranteed to return the * same dataspace as dynamic ROM sessions may update the ROM data - * during the lifetime of the session. When calling the function, the + * during the lifetime of the session. When calling the method, the * server may destroy the old dataspace and replace it with a new one - * containing the updated data. Hence, prior calling this function, the + * containing the updated data. Hence, prior calling this method, the * client should make sure to detach the previously requested dataspace * from its local address space. */ @@ -59,7 +59,7 @@ struct Genode::Rom_session : Session /** * Update ROM dataspace content * - * This function is an optimization for use cases where ROM dataspaces + * This method is an optimization for use cases where ROM dataspaces * are updated at a high rate. In such cases, requesting a new * dataspace for each update induces a large overhead because * memory mappings must be revoked and updated (e.g., handling the @@ -67,12 +67,12 @@ struct Genode::Rom_session : Session * fits in the existing dataspace, those costly operations can be * omitted. * - * When this function is called, the server may replace the dataspace + * When this method is called, the server may replace the dataspace * content with new data. * * \return true if the existing dataspace contains up-to-date content, * or false if a new dataspace must be requested via the - * 'dataspace' function + * 'dataspace' method */ virtual bool update() { return false; } @@ -85,7 +85,7 @@ struct Genode::Rom_session : Session * where this data is generated rather than originating from a static * file, for example to update a program's configuration at runtime. * - * By installing a signal handler using the 'sigh()' function, the + * By installing a signal handler using the 'sigh()' method, the * client will receive a notification each time the data changes at the * server. From the client's perspective, the original data contained * in the currently used dataspace remains unchanged until the client diff --git a/repos/base/include/root/component.h b/repos/base/include/root/component.h index 7b2d90b37c..9f66b6ecca 100644 --- a/repos/base/include/root/component.h +++ b/repos/base/include/root/component.h @@ -78,7 +78,7 @@ struct Genode::Multiple_clients * creation to only one instance at a time (using the 'Single_session' * policy) or multiple instances (using the 'Multiple_sessions' policy). * - * The 'POLICY' class must provide the following two functions: + * The 'POLICY' class must provide the following two methods: * * :'aquire(const char *args)': is called with the session arguments * at creation time of each new session. It can therefore implement @@ -123,7 +123,7 @@ class Genode::Root_component : public Rpc_object >, * of its 'new' operator and must implement the session * creation at a place, where the required knowledge exist. * - * In the implementation of this function, the heap, provided + * In the implementation of this method, the heap, provided * by 'Root_component' must be used for allocating the session * object. * @@ -151,16 +151,16 @@ class Genode::Root_component : public Rpc_object >, * Inform session about a quota upgrade * * Once a session is created, its client can successively extend - * its quota donation via the 'Parent::transfer_quota' function. + * its quota donation via the 'Parent::transfer_quota' operation. * This will result in the invokation of 'Root::upgrade' at the * root interface the session was created with. The root interface, * in turn, informs the session about the new resources via the - * '_upgrade_session' function. The default implementation is + * '_upgrade_session' method. The default implementation is * suited for sessions that use a static amount of resources * accounted for at session-creation time. For such sessions, an * upgrade is not useful. However, sessions that dynamically * allocate resources on behalf of its client, should respond to - * quota upgrades by implementing this function. + * quota upgrades by implementing this method. * * \param session session to upgrade * \param args description of additional resources in the @@ -174,8 +174,12 @@ class Genode::Root_component : public Rpc_object >, /** * Return allocator to allocate server object in '_create_session()' */ - Allocator *md_alloc() { return _md_alloc; } - Rpc_entrypoint *ep() { return _ep; } + Allocator *md_alloc() { return _md_alloc; } + + /** + * Return entrypoint that serves the root component + */ + Rpc_entrypoint *ep() { return _ep; } public: diff --git a/repos/base/include/session/session.h b/repos/base/include/session/session.h index 9f9c44eed0..7d26d9de49 100644 --- a/repos/base/include/session/session.h +++ b/repos/base/include/session/session.h @@ -26,12 +26,15 @@ namespace Genode { class Session; } /** * Base class of session interfaces - * - * Each session interface must implement the function 'service_name' - * ! static const char *service_name(); - * This function returns the name of the service provided via the session - * interface. */ -class Genode::Session { }; +class Genode::Session +{ + /* + * Each session interface must implement the class function 'service_name' + * ! static const char *service_name(); + * This function returns the name of the service provided via the session + * interface. + */ +}; #endif /* _INCLUDE__SESSION_H_ */ diff --git a/repos/base/include/signal_session/signal_session.h b/repos/base/include/signal_session/signal_session.h index d71064bbb6..ba9eb7026e 100644 --- a/repos/base/include/signal_session/signal_session.h +++ b/repos/base/include/signal_session/signal_session.h @@ -76,7 +76,7 @@ struct Genode::Signal_session : Session * but by using it as argument to our trusted signal-session * interface. Otherwise, a potential signal receiver could supply * a capability with a blocking interface to compromise the - * nonblocking behaviour of the submit function. + * nonblocking behaviour of the signal submission. */ virtual void submit(Signal_context_capability context, unsigned cnt = 1) = 0; diff --git a/repos/base/include/signal_session/source.h b/repos/base/include/signal_session/source.h index 5a6e10a9d5..5e4574cf95 100644 --- a/repos/base/include/signal_session/source.h +++ b/repos/base/include/signal_session/source.h @@ -27,7 +27,7 @@ namespace Genode { struct Signal_source; } /** * Blocking part of the signal-session interface * - * The blocking 'wait_for_signal()' function cannot be part of the + * The blocking 'wait_for_signal()' operation cannot be part of the * signal-session interface because otherwise, context allocations or * signal submissions would not be possible while blocking for signals. * Therefore, the blocking part is implemented a separate interface, diff --git a/repos/base/include/util/arg_string.h b/repos/base/include/util/arg_string.h index 312a197e8d..8b70ca02c2 100644 --- a/repos/base/include/util/arg_string.h +++ b/repos/base/include/util/arg_string.h @@ -61,7 +61,7 @@ class Genode::Arg * \param out_sign 1 if positive; -1 if negative * \return true if no syntactic anomaly occured * - * This function handles the numberic modifiers G (2^30), + * This method handles the numberic modifiers G (2^30), * M (2^20), and K (2^10). */ bool read_ulong(unsigned long *out_value, int *out_sign) const @@ -228,7 +228,7 @@ class Genode::Arg_string /** * Append source string to destination string * - * NOTE: check string length before calling this function! + * NOTE: check string length before calling this method! * * \return last character of result string */ diff --git a/repos/base/include/util/avl_string.h b/repos/base/include/util/avl_string.h index b49eae49d4..10e4b9dea1 100644 --- a/repos/base/include/util/avl_string.h +++ b/repos/base/include/util/avl_string.h @@ -32,6 +32,11 @@ class Genode::Avl_string_base : public Avl_node protected: + /** + * Constructor + * + * \noapi + */ Avl_string_base(const char *str) : _str(str) { } public: diff --git a/repos/base/include/util/avl_tree.h b/repos/base/include/util/avl_tree.h index 9fe409ced6..39e6b37ca5 100644 --- a/repos/base/include/util/avl_tree.h +++ b/repos/base/include/util/avl_tree.h @@ -43,16 +43,16 @@ class Genode::Avl_node_base * \retval false if n2 is lower than n1 * \retval true if n2 is higher than or equal to n1 * - * This function must be provided by the derived class. - * It determines the order of nodes inside the avl tree. + * This method must be provided by the derived class. + * It determines the order of nodes inside the AVL tree. */ virtual bool higher(Avl_node_base *n1, Avl_node_base *n2) const = 0; /** * Node recomputation hook * - * If a node gets rearranged, this function is called. - * It can be used to update avl-tree-position dependent + * If a node gets rearranged, this method is called. + * It can be used to update AVL-tree-position dependent * meta data. */ virtual void recompute(Avl_node_base *) { } @@ -137,30 +137,37 @@ class Genode::Avl_node_base * * \param NT type of the class derived from 'Avl_node' * - * Each object to be stored in the avl tree must be derived from - * 'Avl_node'. The type of the derived class is to be specified as - * template argument to enable 'Avl_node' to call virtual functions - * specific for the derived class. + * Each object to be stored in the AVL tree must be derived from 'Avl_node'. + * The type of the derived class is to be specified as template argument to + * enable 'Avl_node' to call virtual methods specific for the derived class. + * + * The NT class must implement a method called 'higher' that takes a pointer to + * another NT object as argument and returns a bool value. The bool value is + * true if the specified node is higher or equal in the tree order. */ template -class Genode::Avl_node : public Avl_node_base +struct Genode::Avl_node : Avl_node_base { - public: + /** + * Return child of specified side, or nullptr if there is no child + * + * This method can be called by the NT objects to traverse the tree. + */ + inline NT *child(Side i) const { return static_cast(_child[i]); } - inline NT *child(Side i) const { return static_cast(_child[i]); } - - /** - * Default policy - */ - void recompute() { } + /** + * Default policy + * + * \noapi + */ + void recompute() { } }; /** * Root node of the AVL tree * - * The real nodes are always attached at the left branch of - * this root node. + * The real nodes are always attached at the left branch of this root node. */ template class Genode::Avl_tree : Avl_node @@ -199,8 +206,7 @@ class Genode::Avl_tree : Avl_node /** * Request first node of the tree * - * \return first node - * \retval NULL if tree is empty + * \return first node, or nullptr if the tree is empty */ inline NT *first() const { return this->child(Avl_node::LEFT); } }; diff --git a/repos/base/include/util/bit_allocator.h b/repos/base/include/util/bit_allocator.h index 559eec9061..4dfab4bcab 100644 --- a/repos/base/include/util/bit_allocator.h +++ b/repos/base/include/util/bit_allocator.h @@ -28,6 +28,11 @@ class Genode::Bit_allocator addr_t _next; Bit_array _array; + /** + * Reserve consecutive number of bits + * + * \noapi + */ void _reserve(addr_t bit_start, size_t const num) { if (!num) return; diff --git a/repos/base/include/util/fifo.h b/repos/base/include/util/fifo.h index a5819a8757..08e5256a73 100644 --- a/repos/base/include/util/fifo.h +++ b/repos/base/include/util/fifo.h @@ -71,8 +71,6 @@ class Genode::Fifo /** * Constructor - * - * Start with an empty list. */ Fifo(): _head(0), _tail(0) { } @@ -130,7 +128,7 @@ class Genode::Fifo } /** - * Obtain head element of the queue and remove element from queue + * Remove head element from queue * * \return head element or 0 if queue is empty */ diff --git a/repos/base/include/util/list.h b/repos/base/include/util/list.h index 4fe6cfe10b..f67a8d7b0e 100644 --- a/repos/base/include/util/list.h +++ b/repos/base/include/util/list.h @@ -57,8 +57,6 @@ class Genode::List /** * Constructor - * - * Start with an empty list. */ List() : _first(0) { } diff --git a/repos/base/include/util/mmio.h b/repos/base/include/util/mmio.h index 57056e0259..27abd00a72 100644 --- a/repos/base/include/util/mmio.h +++ b/repos/base/include/util/mmio.h @@ -23,7 +23,7 @@ namespace Genode { class Mmio; } /** * A continuous MMIO region * - * For correct behavior of the member functions of 'Mmio', a class that + * For correct behavior of the methods of 'Mmio', a class that * derives from one of the subclasses of 'Mmio' must not define members * named 'Register_base', 'Bitfield_base', 'Register_array_base' or * 'Array_bitfield_base'. diff --git a/repos/base/include/util/noncopyable.h b/repos/base/include/util/noncopyable.h index 656f117382..24280e2314 100644 --- a/repos/base/include/util/noncopyable.h +++ b/repos/base/include/util/noncopyable.h @@ -28,12 +28,27 @@ class Genode::Noncopyable { private: + /** + * Constructor + */ Noncopyable(const Noncopyable&); + const Noncopyable& operator=(const Noncopyable&); protected: + /** + * Constructor + * + * \noapi + */ Noncopyable() {} + + /** + * Destructor + * + * \noapi + */ ~Noncopyable() {} }; diff --git a/repos/base/include/util/string.h b/repos/base/include/util/string.h index d83ec1bec1..9c7eb73dd3 100644 --- a/repos/base/include/util/string.h +++ b/repos/base/include/util/string.h @@ -1,5 +1,5 @@ /* - * \brief String utility functions + * \brief String utilities * \author Norman Feske * \author Sebastian Sumpf * \date 2006-05-10 @@ -59,7 +59,7 @@ class Genode::Number_of_bytes namespace Genode { /** - * Determine length of null-terminated string + * Return length of null-terminated string in bytes */ inline size_t strlen(const char *s) { @@ -75,9 +75,9 @@ namespace Genode { * \param len maximum number of characters to compare, * default is unlimited * - * \retval 0 strings are equal - * \retval >0 s1 is higher than s2 - * \retval <0 s1 is lower than s2 + * \return 0 if both strings are equal, or + * a positive number if s1 is higher than s2, or + * a negative number if s1 is lower than s2 */ inline int strcmp(const char *s1, const char *s2, size_t len = ~0UL) { @@ -87,7 +87,7 @@ namespace Genode { /** - * Simple memmove + * Copy memory buffer to a potentially overlapping destination buffer * * \param dst destination memory block * \param src source memory block @@ -110,7 +110,7 @@ namespace Genode { /** - * Copy memory block + * Copy memory buffer to a non-overlapping destination buffer * * \param dst destination memory block * \param src source memory block @@ -158,11 +158,11 @@ namespace Genode { * \param size maximum number of characters to copy * \return pointer to destination string * - * This function is not fully compatible to the C standard, in particular - * there is no zero-padding if the length of 'src' is smaller than 'size'. - * Furthermore, in contrast to the libc version, this function always - * produces a null-terminated string in the 'dst' buffer if the 'size' - * argument is greater than 0. + * Note that this function is not fully compatible to the C standard, in + * particular there is no zero-padding if the length of 'src' is smaller + * than 'size'. Furthermore, in contrast to the libc version, this function + * always produces a null-terminated string in the 'dst' buffer if the + * 'size' argument is greater than 0. */ inline char *strncpy(char *dst, const char *src, size_t size) { @@ -191,9 +191,9 @@ namespace Genode { /** * Compare memory blocks * - * \retval 0 memory blocks are equal - * \retval <0 first memory block is less than second one - * \retval >0 first memory block is greater than second one + * \return 0 if both memory blocks are equal, or + * a negative number if 'p0' is less than 'p1', or + * a positive number if 'p0' is greater than 'p1' */ inline int memcmp(const void *p0, const void *p1, size_t size) { @@ -209,7 +209,11 @@ namespace Genode { /** - * Memset + * Fill destination buffer with given value + * + * \param dst destination buffer + * \param i byte value + * \param size buffer size in bytes */ inline void *memset(void *dst, int i, size_t size) { diff --git a/repos/base/include/util/token.h b/repos/base/include/util/token.h index a0396702ef..9365d1e89d 100644 --- a/repos/base/include/util/token.h +++ b/repos/base/include/util/token.h @@ -121,10 +121,10 @@ class Genode::Token * * \param max_len maximum token length * - * This function is used during the construction of 'Token' + * This method is used during the construction of 'Token' * objects, in particular for determining the value of the '_len' * member. Therefore, we explicitely pass the 'max_len' to the - * function. For the public interface, there exists the 'type()' + * method. For the public interface, there exists the 'type()' * accessor, which relies on '_len' as implicit argument. */ Type _type(size_t max_len) const diff --git a/repos/base/include/x86/cpu/string.h b/repos/base/include/x86/cpu/string.h index e496a35b8e..956f9c1362 100644 --- a/repos/base/include/x86/cpu/string.h +++ b/repos/base/include/x86/cpu/string.h @@ -1,5 +1,5 @@ /* - * \brief Cpu specifi memcpy + * \brief CPU-specific memcpy * \author Sebastian Sumpf * \date 2012-08-02 */ @@ -23,7 +23,7 @@ namespace Genode { * \param src source memory block * \param size number of bytes to copy * - * \return Number of bytes not copied + * \return number of bytes not copied */ inline size_t memcpy_cpu(void *, const void *, size_t size) { return size; } } diff --git a/repos/os/include/block/driver.h b/repos/os/include/block/driver.h index 87380f2c24..83dd12eca5 100644 --- a/repos/os/include/block/driver.h +++ b/repos/os/include/block/driver.h @@ -205,7 +205,7 @@ class Block::Driver * Informs the driver that the client session was closed * * Note: drivers with state (e.g. asynchronously working) - * should override this function, and reset their internal state + * should override this method, and reset their internal state */ virtual void session_invalidated() { } diff --git a/repos/os/include/block_session/block_session.h b/repos/os/include/block_session/block_session.h index 6650a47a4e..8470f0f379 100644 --- a/repos/os/include/block_session/block_session.h +++ b/repos/os/include/block_session/block_session.h @@ -2,16 +2,6 @@ * \brief Block session interface. * \author Stefan Kalkowski * \date 2010-07-06 - * - * A block session corresponds to a block device, that can be used to read - * or store data. Payload is communicated over the packet-stream interface - * set up between 'Session_client' and 'Session_server'. - * - * Even though the functions 'tx' and 'tx_channel' are specific for the client - * side of the block session interface, they are part of the abstract 'Session' - * class to enable the client-side use of the block interface via a pointer to - * the abstract 'Session' class. This way, we can transparently co-locate the - * packet-stream server with the client in same program. */ /* @@ -41,8 +31,9 @@ namespace Block { /** - * Represents an operation request with respect to a block, - * the data associated with the 'Packet_descriptor' is either + * Represents an block-operation request + * + * The data associated with the 'Packet_descriptor' is either * the data read from or written to the block indicated by * its number. */ @@ -91,6 +82,19 @@ class Block::Packet_descriptor : public Genode::Packet_descriptor }; +/* + * Block session interface + * + * A block session corresponds to a block device that can be used to read + * or store data. Payload is communicated over the packet-stream interface + * set up between 'Session_client' and 'Session_server'. + * + * Even though the methods 'tx' and 'tx_channel' are specific for the client + * side of the block session interface, they are part of the abstract 'Session' + * class to enable the client-side use of the block interface via a pointer to + * the abstract 'Session' class. This way, we can transparently co-locate the + * packet-stream server with the client in same program. + */ struct Block::Session : public Genode::Session { enum { TX_QUEUE_SIZE = 256 }; diff --git a/repos/os/include/block_session/rpc_object.h b/repos/os/include/block_session/rpc_object.h index 6c31fd545e..7e00bbd947 100644 --- a/repos/os/include/block_session/rpc_object.h +++ b/repos/os/include/block_session/rpc_object.h @@ -43,7 +43,7 @@ class Block::Session_rpc_object : public Genode::Rpc_object _tx_cap() { return _tx.cap(); } diff --git a/repos/os/include/cli_monitor/child.h b/repos/os/include/cli_monitor/child.h index c9f3d73579..f4a6945811 100644 --- a/repos/os/include/cli_monitor/child.h +++ b/repos/os/include/cli_monitor/child.h @@ -188,7 +188,7 @@ class Child_base : public Genode::Child_policy /** * Try to respond to a current resource request issued by the child * - * This function evaluates the conditions, under which a resource + * This method evaluates the conditions, under which a resource * request can be answered: There must be enough room between the * current quota and the configured limit, and there must be enough * slack memory available. If both conditions are met, the quota @@ -236,7 +236,7 @@ class Child_base : public Genode::Child_policy /** * Return RAM quota status of the child * - * XXX should be a const function, but the 'Ram_session' accessors + * XXX should be a const method, but the 'Ram_session' accessors * are not const */ Ram_status ram_status() diff --git a/repos/os/include/decorator/window.h b/repos/os/include/decorator/window.h index 316926086f..ae166856f7 100644 --- a/repos/os/include/decorator/window.h +++ b/repos/os/include/decorator/window.h @@ -203,7 +203,7 @@ class Decorator::Window_base : public Window_list::Element * \return true if window changed * * We do not immediately update the views as part of the update - * function because at the time when updating the model, the + * method because at the time when updating the model, the * decorations haven't been redrawn already. If we updated the * nitpicker views at this point, we would reveal not-yet-drawn pixels. */ diff --git a/repos/os/include/decorator/window_stack.h b/repos/os/include/decorator/window_stack.h index 3101e0d807..95717e0354 100644 --- a/repos/os/include/decorator/window_stack.h +++ b/repos/os/include/decorator/window_stack.h @@ -70,7 +70,7 @@ class Decorator::Window_stack /** * Generate window list in reverse order * - * After calling this function, the '_windows' list is empty. + * After calling this method, the '_windows' list is empty. */ Window_list _reversed_window_list() { diff --git a/repos/os/include/file_system_session/rpc_object.h b/repos/os/include/file_system_session/rpc_object.h index ab199b621e..723b3eb355 100644 --- a/repos/os/include/file_system_session/rpc_object.h +++ b/repos/os/include/file_system_session/rpc_object.h @@ -41,7 +41,7 @@ class File_system::Session_rpc_object : public Genode::Rpc_object _tx_cap() { return _tx.cap(); } diff --git a/repos/os/include/framebuffer_session/connection.h b/repos/os/include/framebuffer_session/connection.h index e759e9f49b..4603675d17 100644 --- a/repos/os/include/framebuffer_session/connection.h +++ b/repos/os/include/framebuffer_session/connection.h @@ -62,7 +62,7 @@ class Framebuffer::Connection : public Genode::Connection, * * The specified values are not enforced. After creating the * session, you should validate the actual frame-buffer attributes - * by calling the 'info' function of the frame-buffer interface. + * by calling the 'info' method of the frame-buffer interface. */ Connection(unsigned width = 0, unsigned height = 0, diff --git a/repos/os/include/framebuffer_session/framebuffer_session.h b/repos/os/include/framebuffer_session/framebuffer_session.h index 381452009f..3bba53a2f6 100644 --- a/repos/os/include/framebuffer_session/framebuffer_session.h +++ b/repos/os/include/framebuffer_session/framebuffer_session.h @@ -76,9 +76,9 @@ struct Framebuffer::Session : Genode::Session /** * Request dataspace representing the logical frame buffer * - * By calling this function, the framebuffer client enables the server + * By calling this method, the framebuffer client enables the server * to reallocate the framebuffer dataspace (e.g., on mode changes). - * Hence, prior calling this function, the client should make sure to + * Hence, prior calling this method, the client should make sure to * have detached the previously requested dataspace from its local * address space. */ @@ -86,7 +86,7 @@ struct Framebuffer::Session : Genode::Session /** * Request display-mode properties of the framebuffer ready to be - * obtained via the 'dataspace()' function + * obtained via the 'dataspace()' method */ virtual Mode mode() const = 0; @@ -98,7 +98,7 @@ struct Framebuffer::Session : Genode::Session * get resized according to the window dimensions. By installing a * signal handler for mode changes, the framebuffer client can respond * to such changes. The new mode can be obtained using the 'mode()' - * function. However, from the client's perspective, the original mode + * method. However, from the client's perspective, the original mode * stays in effect until the it calls 'dataspace()' again. */ virtual void mode_sigh(Genode::Signal_context_capability sigh) = 0; diff --git a/repos/os/include/init/child.h b/repos/os/include/init/child.h index 66b67b864e..c8fb74877a 100644 --- a/repos/os/include/init/child.h +++ b/repos/os/include/init/child.h @@ -132,7 +132,7 @@ namespace Init { Genode::size_t const child_name_len = Genode::strlen(child_name); /* - * If the function was called with a valid "label" string, the + * If the method was called with a valid "label" string, the * following condition should be always satisfied. See the * comment in 'service_node_args_condition_satisfied'. */ @@ -180,7 +180,7 @@ namespace Init { * Skip child-name prefix if the key is the process "label". * * Because 'filter_session_args' is called prior the call of - * 'resolve_session_request' from the 'Child::session' function, + * 'resolve_session_request' from the 'Child::session' method, * 'args' contains the filtered arguments, in particular the label * prefixed with the child's name. For the 'if-args' declaration, * however, we want to omit specifying this prefix because the @@ -261,7 +261,7 @@ class Init::Routed_service : public Genode::Service Genode::Affinity const &affinity) { /* - * This function is called from the context of the client's + * This method is called from the context of the client's * activation thread. If the service is not yet announced, * we let the client block. */ diff --git a/repos/os/include/init/child_config.h b/repos/os/include/init/child_config.h index 285c67462c..4ebf759e2e 100644 --- a/repos/os/include/init/child_config.h +++ b/repos/os/include/init/child_config.h @@ -122,7 +122,7 @@ class Init::Child_config /** * Return file name if configuration comes from a file * - * If the configuration is provided inline, the function returns 0. + * If the configuration is provided inline, the method returns 0. */ char const *filename() const { return _filename[0] != 0 ? _filename : 0; } @@ -130,7 +130,7 @@ class Init::Child_config /** * Request dataspace holding the start node's configuration data * - * This function returns a valid dataspace only when using an + * This method returns a valid dataspace only when using an * inline configuration (if 'filename()' returns 0). */ Genode::Dataspace_capability dataspace() { diff --git a/repos/os/include/init/child_policy.h b/repos/os/include/init/child_policy.h index 9ecd1bd870..42f057c2bc 100644 --- a/repos/os/include/init/child_policy.h +++ b/repos/os/include/init/child_policy.h @@ -47,7 +47,7 @@ class Init::Child_policy_ram_phys /** * Filter arguments of session request * - * This function removes phys_start and phys_size ram_session + * This method removes phys_start and phys_size ram_session * parameters if the child configuration does not explicitly * permits this. */ @@ -86,7 +86,7 @@ class Init::Child_policy_enforce_labeling /** * Filter arguments of session request * - * This function modifies the 'label' argument and leaves all other + * This method modifies the 'label' argument and leaves all other * session arguments intact. */ void filter_session_args(const char *, char *args, diff --git a/repos/os/include/ldso/arch.h b/repos/os/include/ldso/arch.h index 909ad16b48..daf21265d9 100644 --- a/repos/os/include/ldso/arch.h +++ b/repos/os/include/ldso/arch.h @@ -1,5 +1,5 @@ /* - * \brief Architecture specific functions + * \brief Architecture-specific functions * \author Sebastian Sumpf * \date 2009-10-26 */ diff --git a/repos/os/include/loader_session/loader_session.h b/repos/os/include/loader_session/loader_session.h index 1b5d307867..9108d73cd7 100644 --- a/repos/os/include/loader_session/loader_session.h +++ b/repos/os/include/loader_session/loader_session.h @@ -106,7 +106,7 @@ struct Loader::Session : Genode::Session /** * Constrain size of the nitpicker buffer used by the subsystem * - * Calling this function prior 'start()' enables the virtualization + * Calling this method prior 'start()' enables the virtualization * of the nitpicker session interface. */ virtual void constrain_geometry(Area size) = 0; @@ -134,7 +134,7 @@ struct Loader::Session : Genode::Session * the possible types of faults, please refer to the documentation of * 'Rm_session::fault_handler' and 'Cpu_session::exception_handler'. * - * This function should not be called after the 'start' function. + * This method should not be called after the 'start' method. */ virtual void fault_sigh(Signal_context_capability sigh) = 0; diff --git a/repos/os/include/net/arp.h b/repos/os/include/net/arp.h index 047f6b2378..da5ec34ced 100644 --- a/repos/os/include/net/arp.h +++ b/repos/os/include/net/arp.h @@ -266,7 +266,7 @@ class Net::Arp_packet /*************************** - ** convenience functions ** + ** Convenience functions ** ***************************/ /** diff --git a/repos/os/include/net/dhcp.h b/repos/os/include/net/dhcp.h index 21330e9a8b..e0ea86a30c 100644 --- a/repos/os/include/net/dhcp.h +++ b/repos/os/include/net/dhcp.h @@ -252,9 +252,9 @@ class Net::Dhcp_packet mac.copy(&_chaddr); } - /*************************** - ** Convenience functions ** - ***************************/ + /************************* + ** Convenience methods ** + *************************/ static bool is_dhcp(Udp_packet *udp) { diff --git a/repos/os/include/net/netaddress.h b/repos/os/include/net/netaddress.h index d18427967e..608e90d804 100644 --- a/repos/os/include/net/netaddress.h +++ b/repos/os/include/net/netaddress.h @@ -43,9 +43,9 @@ class Net::Network_address Genode::memcpy(&addr, src, LEN); } - /*********************** - ** Helper functions ** - ***********************/ + /********************* + ** Helper methods ** + *********************/ void copy(void *dst) { Genode::memcpy(dst, addr, LEN); } diff --git a/repos/os/include/nic/driver.h b/repos/os/include/nic/driver.h index c1d9878032..cdebf968aa 100644 --- a/repos/os/include/nic/driver.h +++ b/repos/os/include/nic/driver.h @@ -70,7 +70,7 @@ struct Nic::Driver : Genode::Irq_handler * \param packet start of packet * \param size packet size * - * If the packet size is not a multiple of 4 bytes, this function + * If the packet size is not a multiple of 4 bytes, this method * accesses the bytes after the packet buffer up to the next 4-byte * length (in the worst case, 3 bytes after the packet end). */ diff --git a/repos/os/include/nic_session/nic_session.h b/repos/os/include/nic_session/nic_session.h index 15e79c858e..a91e0905dd 100644 --- a/repos/os/include/nic_session/nic_session.h +++ b/repos/os/include/nic_session/nic_session.h @@ -2,18 +2,6 @@ * \brief NIC session interface * \author Norman Feske * \date 2009-11-13 - * - * A NIC session corresponds to a network adaptor, which can be used to - * transmit and receive network packets. Payload is communicated over the - * packet-stream interface set up between 'Session_client' and - * 'Session_server'. - * - * Even though the functions 'tx', 'tx_channel', 'rx', and 'rx_channel' are - * specific for the client side of the NIC session interface, they are part of - * the abstract 'Session' class to enable the client-side use of the NIC - * interface via a pointer to the abstract 'Session' class. This way, we can - * transparently co-locate the packet-stream server with the client in same - * program. */ /* @@ -48,6 +36,21 @@ namespace Nic { struct Nic::Mac_address { char addr[6]; }; +/* + * NIC session interface + * + * A NIC session corresponds to a network adaptor, which can be used to + * transmit and receive network packets. Payload is communicated over the + * packet-stream interface set up between 'Session_client' and + * 'Session_server'. + * + * Even though the methods 'tx', 'tx_channel', 'rx', and 'rx_channel' are + * specific for the client side of the NIC session interface, they are part of + * the abstract 'Session' class to enable the client-side use of the NIC + * interface via a pointer to the abstract 'Session' class. This way, we can + * transparently co-locate the packet-stream server with the client in same + * program. + */ struct Nic::Session : Genode::Session { enum { QUEUE_SIZE = 1024 }; diff --git a/repos/os/include/nitpicker_session/client.h b/repos/os/include/nitpicker_session/client.h index 7b4f02fb9c..b076ccb30b 100644 --- a/repos/os/include/nitpicker_session/client.h +++ b/repos/os/include/nitpicker_session/client.h @@ -90,7 +90,7 @@ class Nitpicker::Session_client : public Genode::Rpc_client * Enqueue command to command buffer * * The submitted command is not executed immediately. To execute a - * batch of enqueued commands, the 'execute' function must be called. + * batch of enqueued commands, the 'execute' method must be called. * Only in the corner case when there is not space left in the command * buffer, the 'execute' is called to make room in the buffer. */ diff --git a/repos/os/include/nitpicker_session/nitpicker_session.h b/repos/os/include/nitpicker_session/nitpicker_session.h index 1d095fc63f..7353aabdc7 100644 --- a/repos/os/include/nitpicker_session/nitpicker_session.h +++ b/repos/os/include/nitpicker_session/nitpicker_session.h @@ -41,7 +41,7 @@ struct Nitpicker::Session : Genode::Session /** * Session-local view handle * - * When issuing commands to nitpicker via the 'execute' function, views + * When issuing commands to nitpicker via the 'execute' method, views * are referenced by session-local handles. */ typedef Genode::Handle View_handle; @@ -155,7 +155,7 @@ struct Nitpicker::Session : Genode::Session * Enqueue command * * The command will be dropped if the buffer is full. Check for this - * condition by calling 'is_full()' prior calling this function. + * condition by calling 'is_full()' prior calling this method. */ void enqueue(Command const &command) { @@ -213,8 +213,8 @@ struct Nitpicker::Session : Genode::Session /** * Return session-local handle for the specified view * - * The handle returned by this functions can be used to issue commands - * via the 'execute' function. + * The handle returned by this method can be used to issue commands + * via the 'execute' method. * * \param handle designated view handle to be assigned to the imported * view. By default, a new handle will be allocated. @@ -269,7 +269,7 @@ struct Nitpicker::Session : Genode::Session * Set focused session * * Normally, the focused session is defined by the user by clicking on a - * view. The 'focus' function allows a client to set the focus without user + * view. The 'focus' method allows a client to set the focus without user * action. However, the change of the focus is performed only is the * currently focused session belongs to a child or the same process as the * called session. This relationship is checked by comparing the session diff --git a/repos/os/include/os/alarm.h b/repos/os/include/os/alarm.h index ab27638f3b..0bfcf1aa09 100644 --- a/repos/os/include/os/alarm.h +++ b/repos/os/include/os/alarm.h @@ -32,7 +32,7 @@ class Genode::Alarm friend class Alarm_scheduler; - Lock _dispatch_lock; /* taken during handle function */ + Lock _dispatch_lock; /* taken during handle method */ Time _deadline; /* next deadline */ Time _period; /* duration between alarms */ int _active; /* set to one when active */ @@ -48,9 +48,9 @@ class Genode::Alarm protected: /** - * Function to be called on when deadline is reached + * Method to be called on when deadline is reached * - * This function must be implemented by a derived class. If the + * This method must be implemented by a derived class. If the * return value is 'true' and the alarm is periodically scheduled, * the alarm is scheduled again. */ @@ -68,14 +68,14 @@ class Genode::Alarm_scheduler { private: - Lock _lock; /* protect alarm list */ - Alarm *_head; /* head of alarm list */ - Alarm::Time _now; /* recent time (updated by handle function) */ + Lock _lock; /* protect alarm list */ + Alarm *_head; /* head of alarm list */ + Alarm::Time _now; /* recent time (updated by handle method) */ /** * Enqueue alarm into alarm queue * - * This is a helper function for 'schedule' and 'handle'. + * This is a helper for 'schedule' and 'handle'. */ void _unsynchronized_enqueue(Alarm *alarm); diff --git a/repos/os/include/os/attached_dataspace.h b/repos/os/include/os/attached_dataspace.h index 9cecc479e3..cb94402ff3 100644 --- a/repos/os/include/os/attached_dataspace.h +++ b/repos/os/include/os/attached_dataspace.h @@ -86,7 +86,7 @@ class Genode::Attached_dataspace : Noncopyable /** * Forget dataspace, thereby skipping the detachment on destruction * - * This function can be called if the the dataspace is known to be + * This method can be called if the the dataspace is known to be * physically destroyed, e.g., because the session where the dataspace * originated from was closed. In this case, core will already have * removed the memory mappings of the dataspace. So we have to omit the diff --git a/repos/os/include/os/attached_ram_dataspace.h b/repos/os/include/os/attached_ram_dataspace.h index ddc2c0601f..45cd0cab81 100644 --- a/repos/os/include/os/attached_ram_dataspace.h +++ b/repos/os/include/os/attached_ram_dataspace.h @@ -2,13 +2,6 @@ * \brief RAM dataspace utility * \author Norman Feske * \date 2008-03-22 - * - * The combination of RAM allocation and a local RM attachment - * is a frequent use case. Each function may fail, which makes - * error handling inevitable. This utility class encapsulates - * this functionality to handle both operations as a transaction. - * When embedded as a member, this class also takes care about - * freeing and detaching the dataspace at destruction time. */ /* @@ -28,6 +21,15 @@ namespace Genode { class Attached_ram_dataspace; } +/* + * Utility for allocating and attaching a RAM dataspace + * + * The combination of RAM allocation and a local RM attachment is a frequent + * use case. Each function may fail, which makes error handling inevitable. + * This utility class encapsulates this functionality to handle both operations + * as a transaction. When embedded as a member, this class also takes care + * about freeing and detaching the dataspace at destruction time. + */ class Genode::Attached_ram_dataspace { private: diff --git a/repos/os/include/os/attached_rom_dataspace.h b/repos/os/include/os/attached_rom_dataspace.h index e36a48ba6c..75fb017724 100644 --- a/repos/os/include/os/attached_rom_dataspace.h +++ b/repos/os/include/os/attached_rom_dataspace.h @@ -47,7 +47,7 @@ class Genode::Attached_rom_dataspace * '_rom.dataspace()'. * * The ROM server may destroy the original dataspace when the - * 'dataspace()' function is called. In this case, all existing + * 'dataspace()' method is called. In this case, all existing * mappings of the dataspace will be flushed by core. A destruction * of 'Attached_dataspace' after this point will attempt to detach * the already flushed mappings, thereby producing error messages diff --git a/repos/os/include/os/child_policy_dynamic_rom.h b/repos/os/include/os/child_policy_dynamic_rom.h index b2c2c562f8..5801075801 100644 --- a/repos/os/include/os/child_policy_dynamic_rom.h +++ b/repos/os/include/os/child_policy_dynamic_rom.h @@ -34,7 +34,7 @@ class Genode::Child_policy_dynamic_rom_file : public Rpc_object, * e.g., written by the main thread and consumed by the child's * entrypoint that manages the local ROM service for handing out a * dynamic config. Hence, the '_lock' is used to synchronize the - * 'load' and 'dataspace' functions. + * 'load' and 'dataspace' methods. */ Lock _lock; @@ -156,9 +156,9 @@ class Genode::Child_policy_dynamic_rom_file : public Rpc_object, void close(Session_capability) { } - /********************* - ** Policy function ** - *********************/ + /********************** + ** Policy interface ** + **********************/ Service *resolve_session_request(const char *service_name, const char *args) diff --git a/repos/os/include/os/config.h b/repos/os/include/os/config.h index dfc013a124..b330e8afc0 100644 --- a/repos/os/include/os/config.h +++ b/repos/os/include/os/config.h @@ -57,7 +57,7 @@ class Genode::Config * * \throw Invalid if the new configuration has an invalid syntax * - * This function is meant to be called as response to a signal + * This method is meant to be called as response to a signal * received by the signal handler as registered via 'sigh()'. */ void reload(); diff --git a/repos/os/include/os/handle_registry.h b/repos/os/include/os/handle_registry.h index 3f7c59caea..6930a22e9d 100644 --- a/repos/os/include/os/handle_registry.h +++ b/repos/os/include/os/handle_registry.h @@ -60,7 +60,7 @@ class Genode::Handle * \param OBJ type of context associated with a handle * * The constructor of the 'HANDLE' type must take an unsigned value as argument - * and have a 'value()' function that returns the same value. + * and have a 'value()' method that returns the same value. * * The 'OBJ' type must be inherited from 'Weak_object'. */ diff --git a/repos/os/include/os/irq_activation.h b/repos/os/include/os/irq_activation.h index 47c422559a..3939ac240e 100644 --- a/repos/os/include/os/irq_activation.h +++ b/repos/os/include/os/irq_activation.h @@ -70,7 +70,7 @@ class Genode::Irq_activation : Thread_base } /** - * Thread entry function + * Thread entry * * The interrupt thread infinitely waits for interrupts and calls * the handler on occurrence. diff --git a/repos/os/include/os/packet_allocator.h b/repos/os/include/os/packet_allocator.h index 910b341509..cc78053e7b 100644 --- a/repos/os/include/os/packet_allocator.h +++ b/repos/os/include/os/packet_allocator.h @@ -134,9 +134,9 @@ class Genode::Packet_allocator : public Genode::Range_allocator } - /********************* - ** Dummy functions ** - *********************/ + /************* + ** Dummies ** + *************/ bool need_size_for_free() const override { return false; } void free(void *addr) { } diff --git a/repos/os/include/os/packet_stream.h b/repos/os/include/os/packet_stream.h index de5f5ce780..190c67073d 100644 --- a/repos/os/include/os/packet_stream.h +++ b/repos/os/include/os/packet_stream.h @@ -58,7 +58,7 @@ * empty acknowledgement queue and delivers a 'ack_avail' signal. * * These conditions can be avoided by querying the state of the submit and - * acknowledge buffers using the functions 'packet_avail', + * acknowledge buffers using the methods 'packet_avail', * 'ready_to_submit', 'ready_to_ack', and 'ack_avail'. * * If bidirectional data exchange between two processes is desired, two pairs @@ -407,10 +407,7 @@ class Genode::Packet_descriptor_receiver /** - * Helper class for 'Packet_stream_source' and 'Packet_stream_sink' - * containing code shared between both classes. - * - * This class is private to the packet-stream interface. + * Common base of 'Packet_stream_source' and 'Packet_stream_sink' */ class Genode::Packet_stream_base { @@ -802,7 +799,7 @@ class Genode::Packet_stream_sink : private Packet_stream_base /** * Get next packet from source * - * This function blocks if no packets are available. + * This method blocks if no packets are available. */ Packet_descriptor get_packet() { @@ -839,7 +836,7 @@ class Genode::Packet_stream_sink : private Packet_stream_base /** * Tell the source that the processing of the specified packet is completed * - * This function blocks if the acknowledgement queue is full. + * This method blocks if the acknowledgement queue is full. */ void acknowledge_packet(Packet_descriptor packet) { diff --git a/repos/os/include/os/ring_buffer.h b/repos/os/include/os/ring_buffer.h index d4b6b02885..4f9a68c364 100644 --- a/repos/os/include/os/ring_buffer.h +++ b/repos/os/include/os/ring_buffer.h @@ -86,8 +86,7 @@ class Ring_buffer /** * Place element into ring buffer * - * If the ring buffer is full, this function - * throws an Overflow exception. + * \throw Overflow the ring buffer is full */ void add(ET ev) { @@ -106,8 +105,8 @@ class Ring_buffer * * \return element * - * If the ring buffer is empty, this function - * blocks until an element gets available. + * If the ring buffer is empty, this method blocks until an element + * gets available. */ ET get() { diff --git a/repos/os/include/os/signal_rpc_dispatcher.h b/repos/os/include/os/signal_rpc_dispatcher.h index 34bd7be310..5dac72563c 100644 --- a/repos/os/include/os/signal_rpc_dispatcher.h +++ b/repos/os/include/os/signal_rpc_dispatcher.h @@ -133,13 +133,13 @@ namespace Server{ /** - * Signal dispatcher for directing signals via RPC to member function + * Signal dispatcher for directing signals via RPC to object methods * - * This utility associates member functions with signals. It is intended to + * This utility associates object methods with signals. It is intended to * be used as a member variable of the class that handles incoming signals * of a certain type. The constructor takes a pointer-to-member to the - * signal handling function as argument. If a signal is received at the - * common signal reception code, this function will be invoked by calling + * signal-handling method as argument. If a signal is received at the + * common signal reception code, this method will be invoked by calling * 'Signal_dispatcher_base::dispatch'. * * \param T type of signal-handling class @@ -157,7 +157,7 @@ struct Genode::Signal_rpc_member : Genode::Signal_rpc_dispatcher_base, * Constructor * * \param ep entrypoint managing this signal RPC - * \param obj,member object and member function to call when + * \param obj,member object and method to call when * the signal occurs */ Signal_rpc_member(EP &ep, T &obj, void (T::*member)(unsigned)) diff --git a/repos/os/include/os/slave.h b/repos/os/include/os/slave.h index 92a18d41fd..60d864a8df 100644 --- a/repos/os/include/os/slave.h +++ b/repos/os/include/os/slave.h @@ -44,7 +44,7 @@ class Genode::Slave_policy : public Genode::Child_policy /** * Return white list of services the slave is permitted to use * - * The list is terminated via a NULL pointer. + * The list is terminated via a null pointer. */ virtual char const **_permitted_services() const = 0; diff --git a/repos/os/include/os/static_root.h b/repos/os/include/os/static_root.h index d35577ad0a..e10ad5c75e 100644 --- a/repos/os/include/os/static_root.h +++ b/repos/os/include/os/static_root.h @@ -2,10 +2,6 @@ * \brief Root component for singleton services * \author Norman Feske * \date 2012-10-05 - * - * Many components, in particular device drivers, support only one client - * at a time. In this case, one single session may be created right at the - * start of the program and handed out via the 'Root::session' function. */ /* @@ -29,6 +25,10 @@ namespace Genode { template class Static_root; } /** * Root interface that hands out a statically created session + * + * Many components, in particular device drivers, support only one client + * at a time. In this case, one single session may be created right at the + * start of the program and handed out via the 'Root::session' method. */ template class Genode::Static_root : public Genode::Rpc_object > diff --git a/repos/os/include/os/surface.h b/repos/os/include/os/surface.h index 6e476a4e63..4bd90716d4 100644 --- a/repos/os/include/os/surface.h +++ b/repos/os/include/os/surface.h @@ -65,7 +65,7 @@ class Genode::Surface_base /** * Register part of surface to be flushed * - * This function is called by graphics primitives when surface regions + * This method is called by graphics primitives when surface regions * are changed. */ void flush_pixels(Rect rect) diff --git a/repos/os/include/os/synced_interface.h b/repos/os/include/os/synced_interface.h index 8dcfc6ea69..cb48e99693 100644 --- a/repos/os/include/os/synced_interface.h +++ b/repos/os/include/os/synced_interface.h @@ -1,14 +1,7 @@ /* - * \brief Utility for synchronizing the access of interface functions + * \brief Utility for synchronizing the access of interface methods * \author Norman Feske * \date 2013-05-16 - * - * The 'Synced_interface' utility makes the serialization of interface - * function calls easy. The 'Synced_interface' is a functor that takes a lock - * and a pointer to an interface as arguments. When called, the functor - * returns a smart pointer to the interface. When this smart pointer gets - * dereferenced, the smart pointer takes care of acquiring and releasing - * the lock while the interface function is executed. */ #ifndef _INCLUDE__OS__SYNCED_INTERFACE_H_ @@ -23,6 +16,16 @@ namespace Genode { } +/* + * Utility for synchronizing the access of interface methods + * + * The 'Synced_interface' utility makes the serialization of interface + * method calls easy. The 'Synced_interface' is a functor that takes a lock + * and a pointer to an interface as arguments. When called, the functor + * returns a smart pointer to the interface. When this smart pointer gets + * dereferenced, the smart pointer takes care of acquiring and releasing + * the lock while the interface method is executed. + */ template class Genode::Synced_interface { diff --git a/repos/os/include/packet_stream_rx/rpc_object.h b/repos/os/include/packet_stream_rx/rpc_object.h index a28de1ffd7..b62741c925 100644 --- a/repos/os/include/packet_stream_rx/rpc_object.h +++ b/repos/os/include/packet_stream_rx/rpc_object.h @@ -59,7 +59,7 @@ class Packet_stream_rx::Rpc_object : public Genode::Rpc_object, * * The specified values are not enforced. After creating the * session, you should validate the actual frame-buffer attributes - * by calling the 'info' function of the frame-buffer interface. + * by calling the 'info' method of the frame-buffer interface. */ Imx_connection(unsigned width = 0, unsigned height = 0, diff --git a/repos/os/include/platform/rpi/platform_session/platform_session.h b/repos/os/include/platform/rpi/platform_session/platform_session.h index 1a305b5564..b7c579cf88 100644 --- a/repos/os/include/platform/rpi/platform_session/platform_session.h +++ b/repos/os/include/platform/rpi/platform_session/platform_session.h @@ -34,7 +34,7 @@ struct Platform::Session : Genode::Session * * The 'info' argument serves as both input and output parameter. As input, * it describes the desired properties of the framebuffer. In return, the - * function delivers the values that were actually taken into effect. + * method delivers the values that were actually taken into effect. */ virtual void setup_framebuffer(Framebuffer_info &info) = 0; diff --git a/repos/os/include/report_session/report_session.h b/repos/os/include/report_session/report_session.h index f70bdf3fd1..0287a5bc7e 100644 --- a/repos/os/include/report_session/report_session.h +++ b/repos/os/include/report_session/report_session.h @@ -61,7 +61,7 @@ struct Report::Session : Genode::Session * * \param length length of report in bytes * - * While this function is called, the information in the dataspace + * While this method is called, the information in the dataspace * must not be modified by the client. */ virtual void submit(size_t length) = 0; @@ -74,7 +74,7 @@ struct Report::Session : Genode::Session /** * Request a response from the recipient of reports * - * By calling this function, the client expects that the server will + * By calling this method, the client expects that the server will * replace the content of the dataspace with new information. * * \return length of response in bytes diff --git a/repos/os/include/terminal/cell_array.h b/repos/os/include/terminal/cell_array.h index facba1d6c3..29e5d577d5 100644 --- a/repos/os/include/terminal/cell_array.h +++ b/repos/os/include/terminal/cell_array.h @@ -23,7 +23,7 @@ * about the glyph and its attributes * * The 'CELL' type must have a default constructor and has to provide the - * function 'set_cursor()' and 'clear_cursor'. + * methods 'set_cursor()' and 'clear_cursor'. */ template class Cell_array diff --git a/repos/os/include/terminal_session/terminal_session.h b/repos/os/include/terminal_session/terminal_session.h index cf20b8b82f..2f901f5d5c 100644 --- a/repos/os/include/terminal_session/terminal_session.h +++ b/repos/os/include/terminal_session/terminal_session.h @@ -66,7 +66,7 @@ struct Terminal::Session : Genode::Session /** * Register signal handler to be informed about the established connection * - * This function is used for a simple startup protocol of terminal + * This method is used for a simple startup protocol of terminal * sessions. At session-creation time, the terminal session may not * be ready to use. For example, a TCP terminal session needs an * established TCP connection first. However, we do not want to let the diff --git a/repos/os/include/timer_session/timer_session.h b/repos/os/include/timer_session/timer_session.h index 0ef9131532..fb204f294b 100644 --- a/repos/os/include/timer_session/timer_session.h +++ b/repos/os/include/timer_session/timer_session.h @@ -54,13 +54,13 @@ struct Timer::Session : Genode::Session virtual unsigned long elapsed_ms() const = 0; /** - * Client-side convenience function for sleeping the specified number + * Client-side convenience method for sleeping the specified number * of milliseconds */ virtual void msleep(unsigned ms) = 0; /** - * Client-side convenience function for sleeping the specified number + * Client-side convenience method for sleeping the specified number * of microseconds */ virtual void usleep(unsigned us) = 0; diff --git a/repos/os/include/usb_session/rpc_object.h b/repos/os/include/usb_session/rpc_object.h index cb764d8ac9..f02025e4e1 100644 --- a/repos/os/include/usb_session/rpc_object.h +++ b/repos/os/include/usb_session/rpc_object.h @@ -42,7 +42,7 @@ class Usb::Session_rpc_object : public Genode::Rpc_object _tx_cap() { return _tx.cap(); } diff --git a/repos/os/include/util/dirty_rect.h b/repos/os/include/util/dirty_rect.h index 185fb21381..215cc0aa1c 100644 --- a/repos/os/include/util/dirty_rect.h +++ b/repos/os/include/util/dirty_rect.h @@ -75,7 +75,7 @@ class Genode::Dirty_rect * Call functor for each dirty area * * The functor 'fn' takes a 'Rect const &' as argument. - * This function resets the dirty rectangles. + * This method resets the dirty rectangles. */ template void flush(FN const &fn) diff --git a/repos/os/include/util/xml_generator.h b/repos/os/include/util/xml_generator.h index 23845a1305..dd3746c336 100644 --- a/repos/os/include/util/xml_generator.h +++ b/repos/os/include/util/xml_generator.h @@ -34,7 +34,7 @@ class Genode::Xml_generator /** * Buffer descriptor where the XML output goes to * - * All 'append' functions may throw a 'Buffer_exceeded' exception. + * All 'append' methods may throw a 'Buffer_exceeded' exception. */ class Out_buffer { diff --git a/repos/os/include/util/xml_node.h b/repos/os/include/util/xml_node.h index a3d3e01fab..1439a4df6b 100644 --- a/repos/os/include/util/xml_node.h +++ b/repos/os/include/util/xml_node.h @@ -400,12 +400,12 @@ class Genode::Xml_node * * \return end tag or invalid tag * - * The function searches for a end tag that matches the same + * The method searches for a end tag that matches the same * depth level and the same name as the start tag of the XML * node. If the XML structure is invalid, the search results * is an invalid Tag. * - * During the search, the function also counts the number of + * During the search, the method also counts the number of * immediate sub nodes. */ Tag _init_end_tag() @@ -576,7 +576,7 @@ class Genode::Xml_node * points directly into a sub range of the unmodified Xml_node * address range. * - * XXX This function is deprecated. Use 'content_base()' instead. + * XXX This method is deprecated. Use 'content_base()' instead. */ char *content_addr() const { return _start_tag.next_token().start(); } @@ -758,7 +758,7 @@ class Genode::Xml_node * reads optional attributes (those with default values) has to * handle the exception accordingly. Such code tends to become * clumsy, in particular when many attributes are processed in a - * subsequent fashion. This function template relieves the XML node + * subsequent fashion. This method template relieves the XML node * user from implementing the exception handling manually. */ template diff --git a/repos/os/include/vfs/dir_file_system.h b/repos/os/include/vfs/dir_file_system.h index a681eea880..ade9ac7c81 100644 --- a/repos/os/include/vfs/dir_file_system.h +++ b/repos/os/include/vfs/dir_file_system.h @@ -354,7 +354,7 @@ class Vfs::Dir_file_system : public File_system path = _sub_path(path); /* - * If the resulting 'path' is non-NULL, the path lies + * If the resulting 'path' is non-null, the path lies * within our tree. In this case, determine the sum of * matching dirents of all our file systems. Otherwise, * the specified path lies outside our directory node. diff --git a/repos/os/include/vfs/file_system.h b/repos/os/include/vfs/file_system.h index bd4254a37f..1644605365 100644 --- a/repos/os/include/vfs/file_system.h +++ b/repos/os/include/vfs/file_system.h @@ -32,7 +32,7 @@ struct Vfs::File_system : Directory_service, File_io_service /** * Synchronize file system * - * This function is only used by a Fs_file_system because such a file + * This method is only used by a Fs_file_system because such a file * system may employ a backend, which maintains a internal cache, that * needs to be flushed. */