ExternalVendorCode/genode
1
0
Fork 0
mirror of https://github.com/genodelabs/genode.git synced 2024-12-21 06:33:31 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Revised API documentation

Browse Source 
This patch curates the API documentation to become suitable for the
functional specificaton, which is partially generated from the header
files.
This commit is contained in:
Norman Feske 2015-03-20 17:50:41 +01:00 committed by Christian Helmuth
parent 7441df33c9
commit eaac3cc1bd
107 changed files with 610 additions and 444 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
repos/base/include/32bit/base/fixed_stdint.h
View File

@ -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;

16
repos/base/include/64bit/base/fixed_stdint.h
View File

@ -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;

2
repos/base/include/base/affinity.h
View File

@ -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.

51
repos/base/include/base/allocator.h
View File

@ -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 <typename T, typename DEALLOC> 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 <typename T, typename DEALLOC>
void Genode::destroy(DEALLOC && dealloc, T *obj)
{

16
repos/base/include/base/allocator_avl.h
View File

@ -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);

15
repos/base/include/base/blocking.h
View File

@ -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_ */

4
repos/base/include/base/cancelable_lock.h
View File

@ -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();

6
repos/base/include/base/capability.h
View File

@ -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 <typename EXC_TL>
@ -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 <typename IF, unsigned I>
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

23
repos/base/include/base/child.h
View File

@ -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<Parent>
/**
* 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<Parent>
/**
* 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<Parent>
/**
* 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'.

7
repos/base/include/base/connection.h
View File

@ -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<SESSION_TYPE> cap, On_destruction od = CLOSE):
_cap(cap), _on_destruction(od) { }

10
repos/base/include/base/console.h
View File

@ -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.
*/

5
repos/base/include/base/env.h
View File

@ -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.
*/
/*

8
repos/base/include/base/heap.h
View File

@ -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<Dataspace>
{
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> _block_list; /* list of allocated blocks */

6
repos/base/include/base/ipc.h
View File

@ -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.

13
repos/base/include/base/lock_guard.h
View File

@ -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 <typename> 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 <typename LT>
class Genode::Lock_guard

4
repos/base/include/base/native_capability.h
View File

@ -38,8 +38,8 @@ namespace Genode { template <typename> 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 <typename POLICY>
class Genode::Native_capability_tpl

7
repos/base/include/base/object_pool.h
View File

@ -73,10 +73,11 @@ class Genode::Object_pool
friend class Object_pool;
friend class Avl_tree<Entry>;
/**
* 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(); };

4
repos/base/include/base/pager.h
View File

@ -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()
{

5
repos/base/include/base/printf.h
View File

@ -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)));
}

2
repos/base/include/base/rpc.h
View File

@ -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

2
repos/base/include/base/rpc_args.h
View File

@ -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.

44
repos/base/include/base/rpc_client.h
View File

@ -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<Rpc_function>(arguments...)'.
*/
template <typename RPC_INTERFACE>
struct Rpc_client : Capability<RPC_INTERFACE>, RPC_INTERFACE
{
typedef RPC_INTERFACE Rpc_interface;
Rpc_client(Capability<RPC_INTERFACE> const &cap)
: Capability<RPC_INTERFACE>(cap) { }
};
template <typename> struct Rpc_client;
/**
* Count capabilities of a RPC_FUNCTION which are out parameters.
@ -68,9 +51,9 @@ namespace Genode {
enum { Value = Rpc_caps_out<typename RPC_FUNCTION::Server_args>::Value +
Cap_return <typename RPC_FUNCTION::Ret_type>::Value}; };
/*********************************************************
/***************************************************
** Implementation of 'Capability:call' functions **
*********************************************************/
***************************************************/
template <typename RPC_INTERFACE>
template <typename ATL>
@ -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<Rpc_function>(arguments...)'.
*/
template <typename RPC_INTERFACE>
struct Genode::Rpc_client : Capability<RPC_INTERFACE>, RPC_INTERFACE
{
typedef RPC_INTERFACE Rpc_interface;
Rpc_client(Capability<RPC_INTERFACE> const &cap)
: Capability<RPC_INTERFACE>(cap) { }
};
#endif /* _INCLUDE__BASE__RPC_CLIENT_H_ */

58
repos/base/include/base/rpc_server.h
View File

@ -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 <typename RPC_INTERFACE, typename SERVER = RPC_INTERFACE>
class Genode::Rpc_dispatcher : public RPC_INTERFACE
@ -232,7 +232,7 @@ struct Genode::Rpc_object : Rpc_object_base, Rpc_dispatcher<RPC_INTERFACE, SERVE
* activation-using server can ensure that it gets initialized completely
* before the first capability invocations come in. Once the server is
* ready, it must enable the entrypoint explicitly by calling the
* 'activate()' function. The 'start_on_construction' argument is a
* 'activate()' method. The 'start_on_construction' argument is a
* shortcut for the common case where the server's capability is handed
* over to other parties _after_ the server is completely initialized.
*/
@ -253,7 +253,7 @@ class Genode::Rpc_entrypoint : Thread_base, public Object_pool<Rpc_object_base>
/**
* 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<Rpc_object_base>
Capability<Exit> _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<Rpc_object_base>
/**
* 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<Rpc_object_base>
/**
* 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<Rpc_object_base>
/**
* Return true if the caller corresponds to the entrypoint called
*
* \noapi
*
* This method is solely needed on Linux.
*/
bool is_myself() const;
};

9
repos/base/include/base/semaphore.h
View File

@ -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();

8
repos/base/include/base/service.h
View File

@ -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)
{

39
repos/base/include/base/signal.h
View File

@ -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,

22
repos/base/include/base/slab.h
View File

@ -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; }
/*************************

8
repos/base/include/base/snprintf.h
View File

@ -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)

2
repos/base/include/base/stdint.h
View File

@ -1,5 +1,5 @@
/*
* \brief Genode-specific integer types
* \brief Integer types
* \author Christian Helmuth
* \date 2006-05-10
*/

2
repos/base/include/base/sync_allocator.h
View File

@ -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; }

29
repos/base/include/base/thread.h
View File

@ -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.

116
repos/base/include/base/weak_ptr.h
View File

@ -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<Weak_ptr_base>::Element
{
private:
@ -79,6 +51,11 @@ class Genode::Weak_ptr_base : public Genode::List<Weak_ptr_base>::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<Weak_ptr_base>::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<T>' only
*
* \noapi
*/
template <typename T>
Weak_ptr<T> _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 <typename T>
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 <typename T>
struct Genode::Weak_object : Genode::Weak_object_base
{
/**
* Obtain a weak pointer referring to the weak object
*/
Weak_ptr<T> weak_ptr() { return _weak_ptr<T>(); }
};
/**
* 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 <typename T>
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<T *>(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; }
};

8
repos/base/include/cpu_session/cpu_session.h
View File

@ -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'.

2
repos/base/include/io_port_session/io_port_session.h
View File

@ -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

10
repos/base/include/parent/parent.h
View File

@ -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 <typename ROOT_INTERFACE>
@ -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

2
repos/base/include/ram_session/client.h
View File

@ -1,5 +1,5 @@
/*
* \brief Client-side ram session interface
* \brief Client-side RAM session interface
* \author Norman Feske
* \date 2006-05-31
*/

3
repos/base/include/ram_session/ram_session.h
View File

@ -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"; }

14
repos/base/include/rom_session/rom_session.h
View File

@ -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

18
repos/base/include/root/component.h
View File

@ -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<Typed_root<SESSION_TYPE> >,
* 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<Typed_root<SESSION_TYPE> >,
* 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<Typed_root<SESSION_TYPE> >,
/**
* 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:

15
repos/base/include/session/session.h
View File

@ -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_ */

2
repos/base/include/signal_session/signal_session.h
View File

@ -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;

2
repos/base/include/signal_session/source.h
View File

@ -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,

4
repos/base/include/util/arg_string.h
View File

@ -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
*/

5
repos/base/include/util/avl_string.h
View File

@ -32,6 +32,11 @@ class Genode::Avl_string_base : public Avl_node<Avl_string_base>
protected:
/**
* Constructor
*
* \noapi
*/
Avl_string_base(const char *str) : _str(str) { }
public:

46
repos/base/include/util/avl_tree.h
View File

@ -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 <typename NT>
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<NT *>(_child[i]); }
inline NT *child(Side i) const { return static_cast<NT *>(_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 <typename NT>
class Genode::Avl_tree : Avl_node<NT>
@ -199,8 +206,7 @@ class Genode::Avl_tree : Avl_node<NT>
/**
* 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<NT>::LEFT); }
};

5
repos/base/include/util/bit_allocator.h
View File

@ -28,6 +28,11 @@ class Genode::Bit_allocator
addr_t _next;
Bit_array<BITS> _array;
/**
* Reserve consecutive number of bits
*
* \noapi
*/
void _reserve(addr_t bit_start, size_t const num)
{
if (!num) return;

4
repos/base/include/util/fifo.h
View File

@ -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
*/

2
repos/base/include/util/list.h
View File

@ -57,8 +57,6 @@ class Genode::List
/**
* Constructor
*
* Start with an empty list.
*/
List() : _first(0) { }

2
repos/base/include/util/mmio.h
View File

@ -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'.

15
repos/base/include/util/noncopyable.h
View File

@ -28,12 +28,27 @@ class Genode::Noncopyable
{
private:
/**
* Constructor
*/
Noncopyable(const Noncopyable&);
const Noncopyable& operator=(const Noncopyable&);
protected:
/**
* Constructor
*
* \noapi
*/
Noncopyable() {}
/**
* Destructor
*
* \noapi
*/
~Noncopyable() {}
};

36
repos/base/include/util/string.h
View File

@ -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)
{

4
repos/base/include/util/token.h
View File

@ -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

4
repos/base/include/x86/cpu/string.h
View File

@ -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; }
}

2
repos/os/include/block/driver.h
View File

@ -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() { }

28
repos/os/include/block_session/block_session.h
View File

@ -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 };

2
repos/os/include/block_session/rpc_object.h
View File

@ -43,7 +43,7 @@ class Block::Session_rpc_object : public Genode::Rpc_object<Session, Session_rpc
/**
* Return capability to packet-stream channel
*
* This function is called by the client via an RPC call at session
* This method is called by the client via an RPC call at session
* construction time.
*/
Genode::Capability<Tx> _tx_cap() { return _tx.cap(); }

4
repos/os/include/cli_monitor/child.h
View File

@ -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()

2
repos/os/include/decorator/window.h
View File

@ -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.
*/

2
repos/os/include/decorator/window_stack.h
View File

@ -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()
{

2
repos/os/include/file_system_session/rpc_object.h
View File

@ -41,7 +41,7 @@ class File_system::Session_rpc_object : public Genode::Rpc_object<Session, Sessi
/**
* Return capability to packet-stream channel
*
* This function is called by the client via an RPC call at session
* This method is called by the client via an RPC call at session
* construction time.
*/
Capability<Tx> _tx_cap() { return _tx.cap(); }

2
repos/os/include/framebuffer_session/connection.h
View File

@ -62,7 +62,7 @@ class Framebuffer::Connection : public Genode::Connection<Session>,
*
* 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,

8
repos/os/include/framebuffer_session/framebuffer_session.h
View File

@ -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;

6
repos/os/include/init/child.h
View File

@ -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.
*/

4
repos/os/include/init/child_config.h
View File

@ -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() {

4
repos/os/include/init/child_policy.h
View File

@ -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,

2
repos/os/include/ldso/arch.h
View File

@ -1,5 +1,5 @@
/*
* \brief Architecture specific functions
* \brief Architecture-specific functions
* \author Sebastian Sumpf
* \date 2009-10-26
*/

4
repos/os/include/loader_session/loader_session.h
View File

@ -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;

2
repos/os/include/net/arp.h
View File

@ -266,7 +266,7 @@ class Net::Arp_packet
/***************************
** convenience functions **
** Convenience functions **
***************************/
/**

6
repos/os/include/net/dhcp.h
View File

@ -252,9 +252,9 @@ class Net::Dhcp_packet
mac.copy(&_chaddr); }
/***************************
** Convenience functions **
***************************/
/*************************
** Convenience methods **
*************************/
static bool is_dhcp(Udp_packet *udp)
{

6
repos/os/include/net/netaddress.h
View File

@ -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); }

2
repos/os/include/nic/driver.h
View File

@ -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).
*/

27
repos/os/include/nic_session/nic_session.h
View File

@ -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 };

2
repos/os/include/nitpicker_session/client.h
View File

@ -90,7 +90,7 @@ class Nitpicker::Session_client : public Genode::Rpc_client<Session>
* 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.
*/

10
repos/os/include/nitpicker_session/nitpicker_session.h
View File

@ -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> 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

14
repos/os/include/os/alarm.h
View File

@ -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);

2
repos/os/include/os/attached_dataspace.h
View File

@ -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

16
repos/os/include/os/attached_ram_dataspace.h
View File

@ -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:

2
repos/os/include/os/attached_rom_dataspace.h
View File

@ -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

8
repos/os/include/os/child_policy_dynamic_rom.h
View File

@ -34,7 +34,7 @@ class Genode::Child_policy_dynamic_rom_file : public Rpc_object<Rom_session>,
* 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<Rom_session>,
void close(Session_capability) { }
/*********************
** Policy function **
*********************/
/**********************
** Policy interface **
**********************/
Service *resolve_session_request(const char *service_name,
const char *args)

2
repos/os/include/os/config.h
View File

@ -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();

2
repos/os/include/os/handle_registry.h
View File

@ -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'.
*/

2
repos/os/include/os/irq_activation.h
View File

@ -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.

6
repos/os/include/os/packet_allocator.h
View File

@ -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) { }

11
repos/os/include/os/packet_stream.h
View File

@ -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)
{

7
repos/os/include/os/ring_buffer.h
View File

@ -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()
{

10
repos/os/include/os/signal_rpc_dispatcher.h
View File

@ -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))

2
repos/os/include/os/slave.h
View File

@ -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;

8
repos/os/include/os/static_root.h
View File

@ -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 <typename> 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 <typename SESSION>
class Genode::Static_root : public Genode::Rpc_object<Genode::Typed_root<SESSION> >

2
repos/os/include/os/surface.h
View File

@ -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)

19
repos/os/include/os/synced_interface.h
View File

@ -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 <typename IF, typename LOCK>
class Genode::Synced_interface
{

4
repos/os/include/packet_stream_rx/rpc_object.h
View File

@ -59,7 +59,7 @@ class Packet_stream_rx::Rpc_object : public Genode::Rpc_object<CHANNEL, Rpc_obje
~Rpc_object() { _ep.dissolve(this); }
/*
* The 'sigh_ack_avail()' and 'sigh_ready_to_submit()' functions
* The 'sigh_ack_avail()' and 'sigh_ready_to_submit()' methods
* may be called at session-creation time to override the default
* data-flow signal handlers as provided by the packet-stream source.
* The default handlers let the server block in the event of data
@ -67,7 +67,7 @@ class Packet_stream_rx::Rpc_object : public Genode::Rpc_object<CHANNEL, Rpc_obje
* implementation is able to avoid blocking for a single event by
* facilitating the use of a select-like mode of operation.
*
* Note that calling these functions after the finished creation of
* Note that calling these methods after the finished creation of
* the session has no effect because the client queries the signal
* handlers only once at session-creation time.
*/

4
repos/os/include/packet_stream_tx/packet_stream_tx.h
View File

@ -29,10 +29,10 @@ struct Packet_stream_tx::Channel
/**
* Request transmission interface
*
* This function enables the client-side use of the 'Channel' using
* This method enables the client-side use of the 'Channel' using
* the abstract 'Channel' interface only. This is useful in cases
* where both source and sink of the 'Channel' are co-located in
* one program. At the server side of the 'Channel', this function
* one program. At the server side of the 'Channel', this method
* has no meaning.
*/
virtual Source *source() { return 0; }

4
repos/os/include/packet_stream_tx/rpc_object.h
View File

@ -58,7 +58,7 @@ class Packet_stream_tx::Rpc_object : public Genode::Rpc_object<CHANNEL, Rpc_obje
~Rpc_object() { _ep.dissolve(this); }
/*
* The 'sigh_packet_avail()' and 'sigh_ready_to_ack()' functions
* The 'sigh_packet_avail()' and 'sigh_ready_to_ack()' methods
* may be called at session-creation time to override the default
* data-flow signal handlers as provided by the packet-stream sink.
* The default handlers let the server block in the event of data
@ -66,7 +66,7 @@ class Packet_stream_tx::Rpc_object : public Genode::Rpc_object<CHANNEL, Rpc_obje
* implementation is able to avoid blocking for a single event by
* facilitating the use of a select-like mode of operation.
*
* Note that calling these functions after the finished creation of
* Note that calling these methods after the finished creation of
* the session has no effect because the client queries the signal
* handlers only once at session-creation time.
*/

4
repos/os/include/pci_device/pci_device.h
View File

@ -150,10 +150,6 @@ struct Pci::Device
Access_size size) = 0;
/***************************
** Convenience functions **
***************************/
/*
* The base classes are defined as follows:
*

2
repos/os/include/pci_session/pci_session.h
View File

@ -51,7 +51,7 @@ struct Pci::Session : Genode::Session
/**
* Free server-internal data structures representing the device
*
* Use this function to relax the heap partition of your PCI session.
* Use this method to relax the heap partition of your PCI session.
*/
virtual void release_device(Device_capability device) = 0;

2
repos/os/include/platform/imx53/imx_framebuffer_session/connection.h
View File

@ -62,7 +62,7 @@ class Framebuffer::Imx_connection : public Genode::Connection<Imx_session>,
*
* 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,

2
repos/os/include/platform/rpi/platform_session/platform_session.h
View File

@ -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;

4
repos/os/include/report_session/report_session.h
View File

@ -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

2
repos/os/include/terminal/cell_array.h
View File

@ -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 <typename CELL>
class Cell_array

2
repos/os/include/terminal_session/terminal_session.h
View File

@ -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

Some files were not shown because too many files have changed in this diff Show More