diff --git a/nx/include/switch/ipc.h b/nx/include/switch/ipc.h index 5fa1b0e1..9d52dcea 100644 --- a/nx/include/switch/ipc.h +++ b/nx/include/switch/ipc.h @@ -266,8 +266,8 @@ static inline void* ipcPrepareHeader(IpcCommand* cmd, size_t sizeof_raw) { } /** - * @brief Dispatches an IPC command structure. - * @param cmd IPC command structure. + * @brief Dispatches an IPC request. + * @param session IPC session handle. * @return Result code. */ static inline Result ipcDispatch(Handle session) { diff --git a/nx/include/switch/services/acc.h b/nx/include/switch/services/acc.h index 90fbcaca..481320d7 100644 --- a/nx/include/switch/services/acc.h +++ b/nx/include/switch/services/acc.h @@ -1,3 +1,9 @@ +/** + * @file acc.h + * @brief Account (acc:*) service IPC wrapper. + * @author yellows8 + * @copyright libnx Authors + */ #pragma once #include "../types.h" #include "sm.h" diff --git a/nx/include/switch/services/apm.h b/nx/include/switch/services/apm.h index 56548d8e..ca006948 100644 --- a/nx/include/switch/services/apm.h +++ b/nx/include/switch/services/apm.h @@ -1,3 +1,9 @@ +/** + * @file apm.h + * @brief Performance management (apm) service IPC wrapper. + * @author yellows8 + * @copyright libnx Authors + */ #pragma once #include "../types.h" diff --git a/nx/include/switch/services/applet.h b/nx/include/switch/services/applet.h index 4a076337..ef217b76 100644 --- a/nx/include/switch/services/applet.h +++ b/nx/include/switch/services/applet.h @@ -1,3 +1,9 @@ +/** + * @file applet.h + * @brief Applet (applet) service IPC wrapper. + * @author yellows8 + * @copyright libnx Authors + */ #pragma once #include "../types.h" diff --git a/nx/include/switch/services/bsd.h b/nx/include/switch/services/bsd.h index b6ba45fb..8191aa6f 100644 --- a/nx/include/switch/services/bsd.h +++ b/nx/include/switch/services/bsd.h @@ -1,3 +1,10 @@ +/** + * @file bsd.h + * @brief BSD sockets (bsd:u/s) service IPC wrapper. + * @author plutoo + * @author TuxSH + * @copyright libnx Authors + */ #pragma once #include "../types.h" #include "../kernel/tmem.h" diff --git a/nx/include/switch/services/fatal.h b/nx/include/switch/services/fatal.h index 82c460fe..28fc5305 100644 --- a/nx/include/switch/services/fatal.h +++ b/nx/include/switch/services/fatal.h @@ -1,4 +1,15 @@ +/** + * @file fatal.h + * @brief Fatal error (fatal:u) service IPC wrapper. + * @author plutoo + * @copyright libnx Authors + */ #pragma once #include "../types.h" -__attribute__((noreturn)) void fatalSimple(Result err); +/** + * @brief Triggers a system fatal error. + * @param err[in] Result code to throw. + * @note This function does not return. + */ +void NORETURN fatalSimple(Result err); diff --git a/nx/include/switch/services/fs.h b/nx/include/switch/services/fs.h index 43419a59..2cd41499 100644 --- a/nx/include/switch/services/fs.h +++ b/nx/include/switch/services/fs.h @@ -1,4 +1,10 @@ -// Copyright 2017 plutoo +/** + * @file fs.h + * @brief Filesystem (fsp-srv) service IPC wrapper. + * @author plutoo + * @author yellows8 + * @copyright libnx Authors + */ #pragma once #include "../types.h" #include "../services/sm.h" diff --git a/nx/include/switch/services/hid.h b/nx/include/switch/services/hid.h index 6cd5582c..d29a58ad 100644 --- a/nx/include/switch/services/hid.h +++ b/nx/include/switch/services/hid.h @@ -1,5 +1,11 @@ +/** + * @file hid.h + * @brief Human input device (hid) service IPC wrapper. + * @author shinyquagsire23 + * @author yellows8 + * @copyright libnx Authors + */ #pragma once - #include #include "../types.h" #include "../services/sm.h" diff --git a/nx/include/switch/services/irs.h b/nx/include/switch/services/irs.h index c63b0b9b..8c216922 100644 --- a/nx/include/switch/services/irs.h +++ b/nx/include/switch/services/irs.h @@ -1,6 +1,6 @@ /** * @file irs.h - * @brief HID IR sensor service. + * @brief HID IR sensor (irs) service IPC wrapper. * @author yellows8 * @copyright libnx Authors */ diff --git a/nx/include/switch/services/nv.h b/nx/include/switch/services/nv.h index bd69402e..ea3769a2 100644 --- a/nx/include/switch/services/nv.h +++ b/nx/include/switch/services/nv.h @@ -1,3 +1,9 @@ +/** + * @file nv.h + * @brief NVIDIA low level driver (nvdrv*) service IPC wrapper. + * @author yellows8 + * @copyright libnx Authors + */ #pragma once #include "../types.h" diff --git a/nx/include/switch/services/pm.h b/nx/include/switch/services/pm.h index e51c5053..a0af0c42 100644 --- a/nx/include/switch/services/pm.h +++ b/nx/include/switch/services/pm.h @@ -1,4 +1,9 @@ -// Copyright 2017 plutoo +/** + * @file pm.h + * @brief Process management (pm*) service IPC wrapper. + * @author plutoo + * @copyright libnx Authors + */ #pragma once #include "../types.h" diff --git a/nx/include/switch/services/sm.h b/nx/include/switch/services/sm.h index e31e47f3..1208e541 100644 --- a/nx/include/switch/services/sm.h +++ b/nx/include/switch/services/sm.h @@ -1,36 +1,69 @@ +/** + * @file sm.h + * @brief Service manager (sm) IPC wrapper. + * @author plutoo + * @author yellows8 + * @copyright libnx Authors + */ #pragma once #include "../types.h" #include "../kernel/svc.h" #include "../ipc.h" +/// Service type. typedef enum { - ServiceType_Uninitialized, - ServiceType_Normal, - ServiceType_Override + ServiceType_Uninitialized, ///< Uninitialized service. + ServiceType_Normal, ///< Normal service. + ServiceType_Override ///< Service overriden in the homebrew environment. } ServiceType; +/// Service object structure. typedef struct { Handle handle; ServiceType type; } Service; +/** + * @brief Returns whether a service is overriden in the homebrew environment. + * @param[in] s Service object. + * @return true if overriden. + */ static inline bool serviceIsOverride(Service* s) { return s->type == ServiceType_Override; } +/** + * @brief Returns whether a service has been initialized. + * @param[in] s Service object. + * @return true if initialized. + */ static inline bool serviceIsActive(Service* s) { return s->type != ServiceType_Uninitialized; } +/** + * @brief Dispatches an IPC request to a service. + * @param[in] s Service object. + * @return Result code + */ static inline Result serviceIpcDispatch(Service* s) { return ipcDispatch(s->handle); } +/** + * @brief Creates a service object from an IPC session handle. + * @param[in] s Service object. + * @param[in] h IPC session handle. + */ static inline void serviceCreate(Service* s, Handle h) { s->handle = h; s->type = ServiceType_Normal; } +/** + * @brief Closes a service. + * @param[in] s Service object. + */ static inline void serviceClose(Service* s) { switch (s->type) { @@ -49,13 +82,76 @@ static inline void serviceClose(Service* s) { s->type = ServiceType_Uninitialized; } +/** + * @brief Initializes SM. + * @return Result code. + * @note This function is already called in the default application startup code (before main() is called). + */ Result smInitialize(void); + +/** + * @brief Uninitializes SM. + * @return Result code. + * @note This function is already handled in the default application exit code (after main() returns). + */ void smExit(void); + +/** + * @brief Requests a service from SM. + * @param[out] service_out Service structure which will be filled in. + * @param[in] name Name of the service to request. + * @return Result code. + */ Result smGetService(Service* service_out, const char* name); + +/** + * @brief Requests a service from SM, as an IPC session handle directly + * @param[out] handle_out Variable containing IPC session handle. + * @param[in] name Name of the service to request. + * @return Result code. + */ Result smGetServiceOriginal(Handle* handle_out, u64 name); + +/** + * @brief Retrieves an overriden service in the homebrew environment. + * @param[in] name Name of the service to request (as 64-bit integer). + * @return IPC session handle. + */ Handle smGetServiceOverride(u64 name); + +/** + * @brief Creates and registers a new service within SM. + * @param[out] handle_out Variable containing IPC port handle. + * @param[in] name Name of the service. + * @param[in] is_light "Is light" + * @param[in] max_sessions Maximum number of concurrent sessions that the service will accept. + * @return Result code. + */ Result smRegisterService(Handle* handle_out, const char* name, bool is_light, int max_sessions); + +/** + * @brief Unregisters a previously registered service in SM. + * @param[in] name Name of the service. + * @return Result code. + */ Result smUnregisterService(const char* name); + +/** + * @brief Check whether SM is initialized. + * @return true if initialized. + */ bool smHasInitialized(void); + +/** + * @brief Encodes a service name as a 64-bit integer. + * @param[in] name Name of the service. + * @return Encoded name. + */ u64 smEncodeName(const char* name); + +/** + * @brief Overrides a service with a custom IPC service handle. + * @param[in] name Name of the service (as 64-bit integer). + * @param[in] handle IPC session handle. + */ void smAddOverrideHandle(u64 name, Handle handle); diff --git a/nx/include/switch/services/usb.h b/nx/include/switch/services/usb.h index c6597d8d..46288424 100644 --- a/nx/include/switch/services/usb.h +++ b/nx/include/switch/services/usb.h @@ -1,3 +1,9 @@ +/** + * @file usb.h + * @brief USB (usb:*) service IPC wrapper. + * @author yellows8 + * @copyright libnx Authors + */ #pragma once #include "../types.h" #include "../services/sm.h" diff --git a/nx/include/switch/services/vi.h b/nx/include/switch/services/vi.h index 6b24ea76..9ed0d846 100644 --- a/nx/include/switch/services/vi.h +++ b/nx/include/switch/services/vi.h @@ -1,3 +1,9 @@ +/** + * @file vi.h + * @brief Display (vi:*) service IPC wrapper. + * @author yellows8 + * @copyright libnx Authors + */ #pragma once #include "../types.h" #include "../services/sm.h"