services/: Add Doxygen file headers; document sm.h

MrKcyre · Feb 10, 2018 · 9559264 · 9559264
1 parent 6c79424
commit 9559264
Show file tree

Hide file tree

Showing 14 changed files with 177 additions and 10 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <assert.h>
 #include "../types.h"
 #include "../services/sm.h"

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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"