API documentation refinements

repos/base/include/base/entrypoint.h

@@ -190,8 +190,10 @@ class Genode::Entrypoint : Genode::Noncopyable
 		/**
 		 * Trigger a suspend-resume cycle in the entrypoint
 		 *
-		 * 'suspended' is called after the entrypoint entered the safe suspend
+		 * The 'suspended' callback is called after the entrypoint entered the
-		 * state, while 'resumed is called when the entrypoint is fully functional again.
+		 * safe suspend state.
+		 * The 'resumed' callback is called when the entrypoint is fully
+		 * functional again.
 		 */
 		void schedule_suspend(void (*suspended)(), void (*resumed)());
 

repos/base/include/base/env.h

@@ -33,10 +33,10 @@ struct Genode::Env
 	virtual Parent &parent() = 0;
 
 	/**
-	 * RAM session of the component
+	 * RAM allocator of the component
 	 *
-	 * The RAM Session represents a budget of memory (quota) that is available
+	 * The RAM allocator is backed with the RAM budget of the component's PD
-	 * to the component. This budget can be used to allocate RAM dataspaces.
+	 * session. This budget can be used to allocate RAM dataspaces.
 	 */
 	virtual Ram_session &ram() = 0;
 
@@ -62,15 +62,21 @@ struct Genode::Env
 	 */
 	virtual Entrypoint &ep() = 0;
 
+	/**
+	 * Deprecated
+	 *
+	 * \deprecated  the RAM session has become part of the PD session
+	 * \noapi
+	 */
 	virtual Ram_session_capability ram_session_cap() = 0;
+
+	/**
+	 * Return the CPU-session capability of the component
+	 */
 	virtual Cpu_session_capability cpu_session_cap() = 0;
 
-	/*
+	/**
-	 * XXX temporary
+	 * Return the PD-session capability of the component
-	 *
-	 * The PD session capability is solely used for upgrading the PD session,
-	 * e.g., when the dynamic linker attaches dataspaces to the linker area.
-	 * Once we add 'Env::upgrade', we can remove this accessor.
 	 */
 	virtual Pd_session_capability pd_session_cap()  = 0;
 

repos/base/include/base/registry.h

@@ -144,8 +144,8 @@ struct Genode::Registry : private Registry_base
  * Using this helper, an arbitrary type can be turned into a registry element
  * type. E.g., in order to keep 'Child_service' objects in a registry, a new
  * registry-compatible type can be created via 'Registered<Child_service>'.
- * Objects of this type can be kept in a 'Registry<Registered<Child_service>
+ * Objects of this type can be kept in a 'Registry<Registered<Child_service> >'.
- * >'. The constructor of such "registered" objects expect the registry as the
+ * The constructor of such "registered" objects expect the registry as the
  * first argument. The other arguments are forwarded to the constructor of the
  * enclosed type.
  */
@@ -158,6 +158,11 @@ class Genode::Registered : public T
 
 	public:
 
+		/**
+		 * Compile-time check
+		 *
+		 * \noapi
+		 */
 		static_assert(__has_virtual_destructor(T), "registered object must have virtual destructor");
 
 		template <typename... ARGS>
@@ -169,9 +174,10 @@ class Genode::Registered : public T
 /**
  * Variant of Registered that does not require a vtable in the base class
  *
- * The generic Registered convenience class requires the base class to provide
+ * The generic 'Registered' convenience class requires the base class to
- * a vtable resp. a virtual destructor for safe deletion of a base class
+ * provide a vtable resp. a virtual destructor for safe deletion of a base
- * pointer. By using Registered_no_delete this requirement can be lifted.
+ * class pointer. By using 'Registered_no_delete', this requirement can be
+ * lifted.
  */
 template <typename T>
 class Genode::Registered_no_delete : public T

repos/base/include/cpu_session/cpu_session.h

@@ -32,6 +32,9 @@ namespace Genode {
 
 struct Genode::Cpu_session : Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "CPU"; }
 
 	/*

repos/base/include/io_mem_session/io_mem_session.h

@@ -31,6 +31,9 @@ struct Genode::Io_mem_dataspace : Dataspace { };
 
 struct Genode::Io_mem_session : Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "IO_MEM"; }
 
 	/*

repos/base/include/io_port_session/io_port_session.h

@@ -33,6 +33,9 @@ namespace Genode { struct Io_port_session; }
 
 struct Genode::Io_port_session : Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "IO_PORT"; }
 
 	enum { CAP_QUOTA = 2 };

repos/base/include/irq_session/irq_session.h

@@ -73,6 +73,9 @@ struct Genode::Irq_session : Session
 	 ** Session **
 	 *************/
 
+	/**
+	 * \noapi
+	 */
 	static const char * service_name() { return "IRQ"; }
 
 	enum { CAP_QUOTA = 3 };

repos/base/include/log_session/log_session.h

@@ -28,6 +28,9 @@ namespace Genode {
 
 struct Genode::Log_session : Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "LOG"; }
 
 	/*

repos/base/include/parent/parent.h

@@ -157,7 +157,7 @@ class Genode::Parent
 		 * \throw Out_of_caps             session CAP quota exceeds our resources
 		 * \throw Out_of_ram              session RAM quota exceeds our resources
 		 *
-		 * \return session capability of the new session is immediately
+		 * \return session capability if the new session is immediately
 		 *         available, or an invalid capability
 		 *
 		 * If the returned capability is invalid, the request is pending at the
@@ -241,7 +241,7 @@ class Genode::Parent
 		/**
 		 * Request additional resources
 		 *
-		 * By invoking this method, a process is able to inform its
+		 * By invoking this method, a component 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
@@ -250,7 +250,7 @@ class Genode::Parent
 		 * resources expected from the parent. If the parent complies with
 		 * the request, it submits a resource-available signal to the
 		 * handler registered via 'resource_avail_sigh()'. On the reception
-		 * of such a signal, the process can re-evaluate its resource quota
+		 * of such a signal, the component can re-evaluate its resource quota
 		 * and resume execution.
 		 */
 		virtual void resource_request(Resource_args const &args) = 0;
@@ -258,7 +258,7 @@ class Genode::Parent
 		/**
 		 * Register signal handler for resource yield notifications
 		 *
-		 * Using the yield signal, the parent is able to inform the process
+		 * Using the yield signal, the parent is able to inform the component
 		 * about its wish to regain resources.
 		 */
 		virtual void yield_sigh(Signal_context_capability sigh) = 0;
@@ -268,8 +268,8 @@ class Genode::Parent
 		 *
 		 * 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
+		 * as a friendly beg to cooperate. The component is not obligated
-		 * to comply. If the process decides to take action to free
+		 * to comply. If the component decides to take action to free
 		 * resources, it can inform its parent about the availability
 		 * of freed up resources by calling 'yield_response()'.
 		 */

repos/base/include/pd_session/pd_session.h

@@ -31,6 +31,9 @@ namespace Genode {
 
 struct Genode::Pd_session : Session, Ram_allocator
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "PD"; }
 
 	/*
@@ -218,6 +221,9 @@ struct Genode::Pd_session : Session, Ram_allocator
 	 */
 	virtual Cap_quota used_caps() const = 0;
 
+	/**
+	 * Return amount of available capabilities
+	 */
 	Cap_quota avail_caps() const
 	{
 		return Cap_quota { cap_quota().value - used_caps().value };

repos/base/include/rm_session/rm_session.h

@@ -22,6 +22,9 @@ namespace Genode { struct Rm_session; }
 
 struct Genode::Rm_session : Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "RM"; }
 
 	/*

repos/base/include/rom_session/rom_session.h

@@ -36,6 +36,9 @@ struct Genode::Rom_dataspace : Dataspace { };
 
 struct Genode::Rom_session : Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "ROM"; }
 
 	/*

repos/base/include/trace_session/trace_session.h

@@ -24,6 +24,9 @@ namespace Genode { namespace Trace { struct Session; } }
 
 struct Genode::Trace::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "TRACE"; }
 
 	enum { CAP_QUOTA = 4 };

repos/os/README

@@ -1,19 +1,2 @@
-This is the example operating system based on the Genode OS framework:
+This source-code repository contains genuine low-level OS components and
-
+interfaces of Genode. It solely depends on the framework's base API.
-:_Init_: is the first real process in the system. The provided implementation
-  uses a very simple XML parser to read its configuration files.
-
-:_Drivers_: The example OS has basic drivers for frame buffer, mouse and
-  keyboard input, the PCI bus, the real-time clock, and system-specific timers.
-
-:_Server_: The only server in the example OS is Nitpicker, a
-  minimal-complexity GUI server.
-
-:_Test_: are also part of the example OS. You may have a look at the fork
-  bomb as a simple system stress test.
-
-:_Ldso_: is the dynamic linker used for loading executables that are linked
-  against shared libraries.
-
-:_Lib_: contains libraries used by the components of the OS repository,
-  for example, the alarm framework.

repos/os/include/audio_in_session/audio_in_session.h

@@ -269,6 +269,9 @@ class Audio_in::Session : public Genode::Session
 
 	public:
 
+		/**
+		 * \noapi
+		 */
 		static const char *service_name() { return "Audio_in"; }
 
 		enum { CAP_QUOTA = 4 };

repos/os/include/audio_out_session/audio_out_session.h

@@ -305,6 +305,9 @@ class Audio_out::Session : public Genode::Session
 
 	public:
 
+		/**
+		 * \noapi
+		 */
 		static const char *service_name() { return "Audio_out"; }
 
 		enum { CAP_QUOTA = 4 };

repos/os/include/block_session/block_session.h

@@ -127,6 +127,9 @@ struct Block::Session : public Genode::Session
 
 	typedef Packet_stream_tx::Channel<Tx_policy> Tx;
 
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Block"; }
 
 	enum { CAP_QUOTA = 5 };

repos/os/include/file_system_session/file_system_session.h

@@ -256,6 +256,9 @@ struct File_system::Session : public Genode::Session
 
 	typedef Packet_stream_tx::Channel<Tx_policy> Tx;
 
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "File_system"; }
 
 	enum { CAP_QUOTA = 5 };

repos/os/include/framebuffer_session/framebuffer_session.h

@@ -80,6 +80,9 @@ struct Framebuffer::Mode
 
 struct Framebuffer::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Framebuffer"; }
 
 	/*

repos/os/include/gpio_session/gpio_session.h

@@ -26,6 +26,9 @@ namespace Gpio { struct Session; }
 
 struct Gpio::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Gpio"; }
 
 	enum { CAP_QUOTA = 2 };

repos/os/include/input_session/input_session.h

@@ -24,6 +24,9 @@ namespace Input { struct Session; }
 
 struct Input::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Input"; }
 
 	/*

repos/os/include/loader_session/loader_session.h

@@ -57,6 +57,9 @@ struct Loader::Session : Genode::Session
 	typedef Genode::Rpc_in_buffer<64>  Name;
 	typedef Genode::Rpc_in_buffer<128> Path;
 
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Loader"; }
 
 	enum { CAP_QUOTA = 2 };

repos/os/include/nic_session/nic_session.h

@@ -66,6 +66,9 @@ struct Nic::Session : Genode::Session
 	typedef Packet_stream_tx::Channel<Policy> Tx;
 	typedef Packet_stream_rx::Channel<Policy> Rx;
 
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Nic"; }
 
 	/*

repos/os/include/nitpicker_session/nitpicker_session.h

@@ -43,6 +43,9 @@ namespace Nitpicker {
 
 struct Nitpicker::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Nitpicker"; }
 
 	/*

repos/os/include/regulator_session/regulator_session.h

@@ -21,6 +21,9 @@ namespace Regulator { struct Session; }
 
 struct Regulator::Session : public Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Regulator"; }
 
 	enum { CAP_QUOTA = 2 };

repos/os/include/report_session/report_session.h

@@ -50,6 +50,9 @@ namespace Report {
 
 struct Report::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Report"; }
 
 	/*

repos/os/include/rtc_session/rtc_session.h

@@ -40,6 +40,9 @@ struct Rtc::Timestamp
 
 struct Rtc::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Rtc"; }
 
 	enum { CAP_QUOTA = 2 };

repos/os/include/spec/imx53/platform_session/platform_session.h

@@ -36,6 +36,9 @@ struct Platform::Session : Genode::Session
 		UNKNOWN,
 	};
 
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Platform"; }
 
 	enum { CAP_QUOTA = 2 };

repos/os/include/spec/rpi/platform_session/platform_session.h

@@ -27,6 +27,9 @@ namespace Platform {
 
 struct Platform::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Platform"; }
 
 	enum { CAP_QUOTA = 2 };

repos/os/include/spec/x86/platform_session/platform_session.h

@@ -32,6 +32,9 @@ struct Platform::Session : Genode::Session
 
 	class Fatal : public Genode::Out_of_ram { };
 
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Platform"; }
 
 	enum { CAP_QUOTA = 2 };

repos/os/include/terminal_session/terminal_session.h

@@ -24,6 +24,9 @@ namespace Terminal { struct Session; }
 
 struct Terminal::Session : Genode::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Terminal"; }
 
 	/*

repos/os/include/timer_session/timer_session.h

@@ -26,6 +26,9 @@ struct Timer::Session : Genode::Session
 {
 	typedef Genode::Signal_context_capability Signal_context_capability;
 
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Timer"; }
 
 	enum { CAP_QUOTA = 2 };

repos/os/include/uart_session/uart_session.h

@@ -29,6 +29,9 @@ namespace Uart {
 
 struct Uart::Session : Terminal::Session
 {
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Uart"; }
 
 	/**

repos/os/include/usb_session/usb_session.h

@@ -153,6 +153,9 @@ struct Usb::Session : public Genode::Session
 	 ** Session interface **
 	 ***********************/
 
+	/**
+	 * \noapi
+	 */
 	static const char *service_name() { return "Usb"; }
 
 	enum { CAP_QUOTA = 5 };