From adb26b5216d912fd596e1521f661e363decfa0fd Mon Sep 17 00:00:00 2001 From: Norman Feske Date: Wed, 24 May 2017 14:41:19 +0200 Subject: [PATCH] API documentation refinements --- repos/base/include/base/entrypoint.h | 6 +++-- repos/base/include/base/env.h | 24 ++++++++++++------- repos/base/include/base/registry.h | 16 +++++++++---- repos/base/include/cpu_session/cpu_session.h | 3 +++ .../include/io_mem_session/io_mem_session.h | 3 +++ .../include/io_port_session/io_port_session.h | 3 +++ repos/base/include/irq_session/irq_session.h | 3 +++ repos/base/include/log_session/log_session.h | 3 +++ repos/base/include/parent/parent.h | 12 +++++----- repos/base/include/pd_session/pd_session.h | 6 +++++ repos/base/include/rm_session/rm_session.h | 3 +++ repos/base/include/rom_session/rom_session.h | 3 +++ .../include/trace_session/trace_session.h | 3 +++ repos/os/README | 21 ++-------------- .../audio_in_session/audio_in_session.h | 3 +++ .../audio_out_session/audio_out_session.h | 3 +++ .../os/include/block_session/block_session.h | 3 +++ .../file_system_session/file_system_session.h | 3 +++ .../framebuffer_session/framebuffer_session.h | 3 +++ repos/os/include/gpio_session/gpio_session.h | 3 +++ .../os/include/input_session/input_session.h | 3 +++ .../include/loader_session/loader_session.h | 3 +++ repos/os/include/nic_session/nic_session.h | 3 +++ .../nitpicker_session/nitpicker_session.h | 3 +++ .../regulator_session/regulator_session.h | 3 +++ .../include/report_session/report_session.h | 3 +++ repos/os/include/rtc_session/rtc_session.h | 3 +++ .../imx53/platform_session/platform_session.h | 3 +++ .../rpi/platform_session/platform_session.h | 3 +++ .../x86/platform_session/platform_session.h | 3 +++ .../terminal_session/terminal_session.h | 3 +++ .../os/include/timer_session/timer_session.h | 3 +++ repos/os/include/uart_session/uart_session.h | 3 +++ repos/os/include/usb_session/usb_session.h | 3 +++ 34 files changed, 128 insertions(+), 41 deletions(-) diff --git a/repos/base/include/base/entrypoint.h b/repos/base/include/base/entrypoint.h index ba14451be..d23794a2f 100644 --- a/repos/base/include/base/entrypoint.h +++ b/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 - * state, while 'resumed is called when the entrypoint is fully functional again. + * The 'suspended' callback is called after the entrypoint entered the + * safe suspend state. + * The 'resumed' callback is called when the entrypoint is fully + * functional again. */ void schedule_suspend(void (*suspended)(), void (*resumed)()); diff --git a/repos/base/include/base/env.h b/repos/base/include/base/env.h index 3bcf083fc..f8a992c47 100644 --- a/repos/base/include/base/env.h +++ b/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 - * to the component. This budget can be used to allocate RAM dataspaces. + * The RAM allocator is backed with the RAM budget of the component's PD + * 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 - * - * 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. + /** + * Return the PD-session capability of the component */ virtual Pd_session_capability pd_session_cap() = 0; diff --git a/repos/base/include/base/registry.h b/repos/base/include/base/registry.h index 50561821e..643dbb023 100644 --- a/repos/base/include/base/registry.h +++ b/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'. - * Objects of this type can be kept in a 'Registry - * >'. The constructor of such "registered" objects expect the registry as the + * Objects of this type can be kept in a 'Registry >'. + * 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 @@ -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 - * a vtable resp. a virtual destructor for safe deletion of a base class - * pointer. By using Registered_no_delete this requirement can be lifted. + * The generic 'Registered' convenience class requires the base class to + * provide a vtable resp. a virtual destructor for safe deletion of a base + * class pointer. By using 'Registered_no_delete', this requirement can be + * lifted. */ template class Genode::Registered_no_delete : public T diff --git a/repos/base/include/cpu_session/cpu_session.h b/repos/base/include/cpu_session/cpu_session.h index 79c424d86..0f44b7c77 100644 --- a/repos/base/include/cpu_session/cpu_session.h +++ b/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"; } /* diff --git a/repos/base/include/io_mem_session/io_mem_session.h b/repos/base/include/io_mem_session/io_mem_session.h index 2ed9b71d2..103184874 100644 --- a/repos/base/include/io_mem_session/io_mem_session.h +++ b/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"; } /* diff --git a/repos/base/include/io_port_session/io_port_session.h b/repos/base/include/io_port_session/io_port_session.h index b33d430e7..b4e66d7be 100644 --- a/repos/base/include/io_port_session/io_port_session.h +++ b/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 }; diff --git a/repos/base/include/irq_session/irq_session.h b/repos/base/include/irq_session/irq_session.h index 58370d97f..f5b85ac2b 100644 --- a/repos/base/include/irq_session/irq_session.h +++ b/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 }; diff --git a/repos/base/include/log_session/log_session.h b/repos/base/include/log_session/log_session.h index e61ba4dfc..94cd78602 100644 --- a/repos/base/include/log_session/log_session.h +++ b/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"; } /* diff --git a/repos/base/include/parent/parent.h b/repos/base/include/parent/parent.h index 9671dc87e..c030db28d 100644 --- a/repos/base/include/parent/parent.h +++ b/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 - * to comply. If the process decides to take action to free + * as a friendly beg to cooperate. The component is not obligated + * 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()'. */ diff --git a/repos/base/include/pd_session/pd_session.h b/repos/base/include/pd_session/pd_session.h index fd2a2968d..9f33feac1 100644 --- a/repos/base/include/pd_session/pd_session.h +++ b/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 }; diff --git a/repos/base/include/rm_session/rm_session.h b/repos/base/include/rm_session/rm_session.h index f6f1e823a..58174e799 100644 --- a/repos/base/include/rm_session/rm_session.h +++ b/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"; } /* diff --git a/repos/base/include/rom_session/rom_session.h b/repos/base/include/rom_session/rom_session.h index b38df4cc8..9a81086ac 100644 --- a/repos/base/include/rom_session/rom_session.h +++ b/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"; } /* diff --git a/repos/base/include/trace_session/trace_session.h b/repos/base/include/trace_session/trace_session.h index f8dc0f8fb..e9f1076ae 100644 --- a/repos/base/include/trace_session/trace_session.h +++ b/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 }; diff --git a/repos/os/README b/repos/os/README index 55d57ce51..194591395 100644 --- a/repos/os/README +++ b/repos/os/README @@ -1,19 +1,2 @@ -This is the example operating system based on the Genode OS framework: - -:_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. +This source-code repository contains genuine low-level OS components and +interfaces of Genode. It solely depends on the framework's base API. diff --git a/repos/os/include/audio_in_session/audio_in_session.h b/repos/os/include/audio_in_session/audio_in_session.h index bc3cfb8a4..75c1ffbf5 100644 --- a/repos/os/include/audio_in_session/audio_in_session.h +++ b/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 }; diff --git a/repos/os/include/audio_out_session/audio_out_session.h b/repos/os/include/audio_out_session/audio_out_session.h index 601a65f4a..6c41a8250 100644 --- a/repos/os/include/audio_out_session/audio_out_session.h +++ b/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 }; diff --git a/repos/os/include/block_session/block_session.h b/repos/os/include/block_session/block_session.h index 16b7a6905..b137223cc 100644 --- a/repos/os/include/block_session/block_session.h +++ b/repos/os/include/block_session/block_session.h @@ -127,6 +127,9 @@ struct Block::Session : public Genode::Session typedef Packet_stream_tx::Channel Tx; + /** + * \noapi + */ static const char *service_name() { return "Block"; } enum { CAP_QUOTA = 5 }; diff --git a/repos/os/include/file_system_session/file_system_session.h b/repos/os/include/file_system_session/file_system_session.h index 75180318e..383be6632 100644 --- a/repos/os/include/file_system_session/file_system_session.h +++ b/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; + /** + * \noapi + */ static const char *service_name() { return "File_system"; } enum { CAP_QUOTA = 5 }; diff --git a/repos/os/include/framebuffer_session/framebuffer_session.h b/repos/os/include/framebuffer_session/framebuffer_session.h index 75dc336ed..46aa4fb0b 100644 --- a/repos/os/include/framebuffer_session/framebuffer_session.h +++ b/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"; } /* diff --git a/repos/os/include/gpio_session/gpio_session.h b/repos/os/include/gpio_session/gpio_session.h index e4df1f7b7..8eda199cb 100644 --- a/repos/os/include/gpio_session/gpio_session.h +++ b/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 }; diff --git a/repos/os/include/input_session/input_session.h b/repos/os/include/input_session/input_session.h index 5695bf4ae..f5a588008 100644 --- a/repos/os/include/input_session/input_session.h +++ b/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"; } /* diff --git a/repos/os/include/loader_session/loader_session.h b/repos/os/include/loader_session/loader_session.h index 5881d0eac..dbce653a6 100644 --- a/repos/os/include/loader_session/loader_session.h +++ b/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 }; diff --git a/repos/os/include/nic_session/nic_session.h b/repos/os/include/nic_session/nic_session.h index 2d63d6161..3a9c1436c 100644 --- a/repos/os/include/nic_session/nic_session.h +++ b/repos/os/include/nic_session/nic_session.h @@ -66,6 +66,9 @@ struct Nic::Session : Genode::Session typedef Packet_stream_tx::Channel Tx; typedef Packet_stream_rx::Channel Rx; + /** + * \noapi + */ static const char *service_name() { return "Nic"; } /* diff --git a/repos/os/include/nitpicker_session/nitpicker_session.h b/repos/os/include/nitpicker_session/nitpicker_session.h index 73b9e9673..d13e27b17 100644 --- a/repos/os/include/nitpicker_session/nitpicker_session.h +++ b/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"; } /* diff --git a/repos/os/include/regulator_session/regulator_session.h b/repos/os/include/regulator_session/regulator_session.h index 0f68f0e69..72fa4cac2 100644 --- a/repos/os/include/regulator_session/regulator_session.h +++ b/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 }; diff --git a/repos/os/include/report_session/report_session.h b/repos/os/include/report_session/report_session.h index d3c2e8819..5c327018e 100644 --- a/repos/os/include/report_session/report_session.h +++ b/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"; } /* diff --git a/repos/os/include/rtc_session/rtc_session.h b/repos/os/include/rtc_session/rtc_session.h index 8c5b3007d..ee8d5e835 100644 --- a/repos/os/include/rtc_session/rtc_session.h +++ b/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 }; diff --git a/repos/os/include/spec/imx53/platform_session/platform_session.h b/repos/os/include/spec/imx53/platform_session/platform_session.h index b8216872c..4ffc5c750 100644 --- a/repos/os/include/spec/imx53/platform_session/platform_session.h +++ b/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 }; diff --git a/repos/os/include/spec/rpi/platform_session/platform_session.h b/repos/os/include/spec/rpi/platform_session/platform_session.h index 7335c7436..17cc82554 100644 --- a/repos/os/include/spec/rpi/platform_session/platform_session.h +++ b/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 }; diff --git a/repos/os/include/spec/x86/platform_session/platform_session.h b/repos/os/include/spec/x86/platform_session/platform_session.h index dc2dfd075..a4212a007 100644 --- a/repos/os/include/spec/x86/platform_session/platform_session.h +++ b/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 }; diff --git a/repos/os/include/terminal_session/terminal_session.h b/repos/os/include/terminal_session/terminal_session.h index 854a10ee9..ada3478cc 100644 --- a/repos/os/include/terminal_session/terminal_session.h +++ b/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"; } /* diff --git a/repos/os/include/timer_session/timer_session.h b/repos/os/include/timer_session/timer_session.h index 58a7e40cc..734e381af 100644 --- a/repos/os/include/timer_session/timer_session.h +++ b/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 }; diff --git a/repos/os/include/uart_session/uart_session.h b/repos/os/include/uart_session/uart_session.h index d35b3036c..1b53a7888 100644 --- a/repos/os/include/uart_session/uart_session.h +++ b/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"; } /** diff --git a/repos/os/include/usb_session/usb_session.h b/repos/os/include/usb_session/usb_session.h index d5bfbf2a5..0b71eb28b 100644 --- a/repos/os/include/usb_session/usb_session.h +++ b/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 };