Start doxygen bringup, with some miscellaneous cleanup

.gitignore

@@ -1,3 +1,14 @@
+*~
 *.o
 *.bz2
-
+*.nro
+*.nso
+*.elf
+*.npdm
+*.pfs0
+Thumbs.db
+.*/
+debug/
+release/
+lib/
+docs/

CODESTYLE.md

@@ -1,24 +1,26 @@
-#### Types
-TypesAreCapitalizedLikeThis
+# Code Style
 
-#### Enums
-EnumType_EnumName
+## Types
+`TypesAreCapitalizedLikeThis`
 
-#### Struct members
-like_this
+## Enums
+`EnumType_EnumName`
 
-notlikethis
+## Struct members
+`like_this`
 
-#### Local variables
-like_this
+`notlikethis`
 
-notlikethis
+## Local variables
+`like_this`
 
-#### Global variables (or global statics)
-g_variableName
+`notlikethis`
 
-#### Functions
-modulenameFunctionName
+## Global variables (or global statics)
+`g_variableName`
 
-#### Macros
-LIKE_THIS
+## Functions
+`modulenameFunctionName`
+
+## Macros
+`LIKE_THIS`

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright 2017 libnx Authors
+Copyright 2017-2018 libnx Authors
 
 Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
 

README.md

@@ -4,11 +4,11 @@ Based on libctru.
 [![Build status](https://doozer.io/badge/switchbrew/libnx/buildstatus/master)](https://doozer.io/switchbrew/libnx)
 
 # Install instructions
-* Setup $DEVKITA64 in your environment.
-* make install
+* Install [devkitA64](https://sourceforge.net/projects/devkitpro/files/devkitA64/) to `$DEVKITPRO/devkitA64`.
+* `make install`
 
-See also the switch-tools repo if you want to manually build those.
+See also the [switch-tools](https://github.com/switchbrew/switch-tools) repo if you want to manually build those.
 
 # Icon
 
-The "default_icon" icon is based on the icon by [Sweet Farm from the Noun Project](https://thenounproject.com/term/nintendo-switch/694750/).
+`nx/default_icon.jpg` is based on the icon by [Sweet Farm from the Noun Project](https://thenounproject.com/term/nintendo-switch/694750/).

nx/Doxyfile

@@ -1,4 +1,4 @@
-# Doxyfile 1.8.11
+# Doxyfile 1.8.13
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
@@ -293,6 +293,15 @@ EXTENSION_MAPPING      =
 
 MARKDOWN_SUPPORT       = YES
 
+# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up
+# to that level are automatically included in the table of contents, even if
+# they do not have an id attribute.
+# Note: This feature currently applies only to Markdown headings.
+# Minimum value: 0, maximum value: 99, default value: 0.
+# This tag requires that the tag MARKDOWN_SUPPORT is set to YES.
+
+TOC_INCLUDE_HEADINGS   = 0
+
 # When enabled doxygen tries to link words that correspond to documented
 # classes, or namespaces to their corresponding documentation. Such a link can
 # be prevented in individual cases by putting a % sign in front of the word or
@@ -773,7 +782,9 @@ WARN_LOGFILE           =
 
 INPUT                  = include \
                          ../README.md \
-                         ../Changelog.md
+                         ../LICENSE.md \
+                         ../Changelog.md \
+                         ../CODESTYLE.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -795,8 +806,8 @@ INPUT_ENCODING         = UTF-8
 # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp,
 # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h,
 # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc,
-# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl,
-# *.vhd, *.vhdl, *.ucf, *.qsf, *.as and *.js.
+# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
+# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf.
 
 FILE_PATTERNS          = *.h \
                          *.c \
@@ -1983,7 +1994,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2023,7 +2034,8 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = SWITCH \
+                         __attribute__(x)=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -2345,6 +2357,11 @@ DIAFILE_DIRS           =
 
 PLANTUML_JAR_PATH      =
 
+# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a
+# configuration file for plantuml.
+
+PLANTUML_CFG_FILE      =
+
 # When using plantuml, the specified paths are searched for files specified by
 # the !include statement in a plantuml block.
 
@@ -2409,4 +2426,3 @@ GENERATE_LEGEND        = YES
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 DOT_CLEANUP            = YES
-

nx/include/switch.h

@@ -1,6 +1,7 @@
 /**
  * @file switch.h
  * @brief Central Switch header. Includes all others.
+ * @copyright libnx Authors
  */
 #pragma once
 

nx/include/switch/arm/cache.h

@@ -1,7 +1,37 @@
+/**
+ * @file cache.h
+ * @brief AArch64 cache operations.
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
+#include "../types.h"
 
+/**
+ * @brief Performs a data cache flush on the specified buffer.
+ * @param addr Address of the buffer.
+ * @param size Size of the buffer, in bytes.
+ * @remarks Cache flush is defined as Clean + Invalidate.
+ */
 void armDCacheFlush(void* addr, size_t size);
+
+/**
+ * @brief Performs a data cache clean on the specified buffer.
+ * @param addr Address of the buffer.
+ * @param size Size of the buffer, in bytes.
+ */
 void armDCacheClean(void* addr, size_t size);
+
+/**
+ * @brief Performs an instruction cache invalidation clean on the specified buffer.
+ * @param addr Address of the buffer.
+ * @param size Size of the buffer, in bytes.
+ */
 void armICacheInvalidate(void* addr, size_t size);
 
+/**
+ * @brief Performs a data cache zeroing operation on the specified buffer.
+ * @param addr Address of the buffer.
+ * @param size Size of the buffer, in bytes.
+ */
 void armDCacheZero(void* addr, size_t size);

nx/include/switch/arm/tls.h

@@ -1,5 +1,16 @@
+/**
+ * @file tls.h
+ * @brief AArch64 thread local storage.
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
+#include "../types.h"
 
+/**
+ * @brief Gets the thread local storage buffer.
+ * @return The thread local storage buffer.
+ */
 static inline void* armGetTls(void) {
     void* ret;
     __asm__ ("mrs %x[data], tpidrro_el0" : [data] "=r" (ret));

nx/include/switch/ipc.h

@@ -1,14 +1,22 @@
-// Copyright 2017 plutoo
+/**
+ * @file ipc.h
+ * @brief Inter-process communication handling
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "result.h"
 #include "arm/tls.h"
 #include "kernel/svc.h"
 
+/// IPC input header magic
 #define SFCI_MAGIC 0x49434653
+/// IPC output header magic
 #define SFCO_MAGIC 0x4f434653
 
 #pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
 
+/// IPC command structure.
 typedef struct {
     size_t NumSend; // A
     size_t NumRecv; // B

nx/include/switch/kernel/svc.h

@@ -1,6 +1,7 @@
 /**
  * @file svc.h
  * @brief Syscall wrappers.
+ * @copyright libnx Authors
  */
 #pragma once
 #include "../types.h"
@@ -24,7 +25,7 @@ typedef struct {
 
 typedef struct {
     u64 X[8];
-} __attribute__((packed)) SecmonArgs;
+} PACKED SecmonArgs;
 
 typedef enum {
     JitMapOperation_MapOwner=0,

nx/include/switch/result.h

@@ -1,6 +1,7 @@
 /**
  * @file result.h
- * @brief Switch result code tools
+ * @brief Switch result code tools.
+ * @copyright libnx Authors
  */
 #pragma once
 #include "types.h"
@@ -18,11 +19,13 @@
 #define MAKERESULT(module,description) \
     ((((module)&0x1FF)) | ((description)&0x1FFF)<<9)
 
+/// Module values
 enum {
     Module_Libnx=345,
-    Module_LibnxNvidia=348
+    Module_LibnxNvidia=348,
 };
 
+/// libnx error codes
 enum {
     LibnxError_BadReloc=1,
     LibnxError_OutOfMemory,
@@ -63,24 +66,25 @@ enum {
     LibnxError_IncompatSysVer,
 };
 
+/// libnx nvidia error codes
 enum {
     LibnxNvidiaError_Unknown=1,
-    LibnxNvidiaError_NotImplemented,       // Maps to Nvidia: 1
-    LibnxNvidiaError_NotSupported,         // Maps to Nvidia: 2
-    LibnxNvidiaError_NotInitialized,       // Maps to Nvidia: 3
-    LibnxNvidiaError_BadParameter,         // Maps to Nvidia: 4
-    LibnxNvidiaError_Timeout,              // Maps to Nvidia: 5
-    LibnxNvidiaError_InsufficientMemory,   // Maps to Nvidia: 6
-    LibnxNvidiaError_ReadOnlyAttribute,    // Maps to Nvidia: 7
-    LibnxNvidiaError_InvalidState,         // Maps to Nvidia: 8
-    LibnxNvidiaError_InvalidAddress,       // Maps to Nvidia: 9
-    LibnxNvidiaError_InvalidSize,          // Maps to Nvidia: 10
-    LibnxNvidiaError_BadValue,             // Maps to Nvidia: 11
-    LibnxNvidiaError_AlreadyAllocated,     // Maps to Nvidia: 13
-    LibnxNvidiaError_Busy,                 // Maps to Nvidia: 14
-    LibnxNvidiaError_ResourceError,        // Maps to Nvidia: 15
-    LibnxNvidiaError_CountMismatch,        // Maps to Nvidia: 16
-    LibnxNvidiaError_SharedMemoryTooSmall, // Maps to Nvidia: 0x1000
-    LibnxNvidiaError_FileOperationFailed,  // Maps to Nvidia: 0x30003
-    LibnxNvidiaError_IoctlFailed,          // Maps to Nvidia: 0x3000F
+    LibnxNvidiaError_NotImplemented,       ///< Maps to Nvidia: 1
+    LibnxNvidiaError_NotSupported,         ///< Maps to Nvidia: 2
+    LibnxNvidiaError_NotInitialized,       ///< Maps to Nvidia: 3
+    LibnxNvidiaError_BadParameter,         ///< Maps to Nvidia: 4
+    LibnxNvidiaError_Timeout,              ///< Maps to Nvidia: 5
+    LibnxNvidiaError_InsufficientMemory,   ///< Maps to Nvidia: 6
+    LibnxNvidiaError_ReadOnlyAttribute,    ///< Maps to Nvidia: 7
+    LibnxNvidiaError_InvalidState,         ///< Maps to Nvidia: 8
+    LibnxNvidiaError_InvalidAddress,       ///< Maps to Nvidia: 9
+    LibnxNvidiaError_InvalidSize,          ///< Maps to Nvidia: 10
+    LibnxNvidiaError_BadValue,             ///< Maps to Nvidia: 11
+    LibnxNvidiaError_AlreadyAllocated,     ///< Maps to Nvidia: 13
+    LibnxNvidiaError_Busy,                 ///< Maps to Nvidia: 14
+    LibnxNvidiaError_ResourceError,        ///< Maps to Nvidia: 15
+    LibnxNvidiaError_CountMismatch,        ///< Maps to Nvidia: 16
+    LibnxNvidiaError_SharedMemoryTooSmall, ///< Maps to Nvidia: 0x1000
+    LibnxNvidiaError_FileOperationFailed,  ///< Maps to Nvidia: 0x30003
+    LibnxNvidiaError_IoctlFailed,          ///< Maps to Nvidia: 0x3000F
 };

nx/include/switch/runtime/devices/console.h

@@ -1,6 +1,9 @@
 /**
  * @file console.h
- * @brief Switch stdio support.
+ * @brief Framebuffer text console.
+ * @author yellows8
+ * @author WinterMute
+ * @copyright libnx Authors
  *
  * Provides stdio integration for printing to the Switch screen as well as debug print
  * functionality provided by stderr.
@@ -161,4 +164,3 @@ void consoleDebugInit(debugDevice device);
 
 /// Clears the screan by using iprintf("\x1b[2J");
 void consoleClear(void);
-

nx/include/switch/runtime/devices/fs_dev.h

@@ -1,22 +1,25 @@
 /**
  * @file fs_dev.h
- * @brief FS driver.
+ * @brief FS driver, using devoptab.
+ * @author yellows8
+ * @author mtheall
+ * @copyright libnx Authors
  */
 #pragma once
 
 #include <sys/types.h>
 #include "../../services/fs.h"
 
-#define FSDEV_DIRITER_MAGIC 0x66736476 /* "fsdv" */
+#define FSDEV_DIRITER_MAGIC 0x66736476 ///< "fsdv"
 
-/*! Open directory struct */
+/// Open directory struct
 typedef struct
 {
-  u32               magic;          /*! "fsdv" */
-  FsDir             fd;
-  ssize_t           index;          /*! Current entry index */
-  size_t            size;           /*! Current batch size */
-  FsDirectoryEntry entry_data[32]; /*! Temporary storage for reading entries */
+  u32               magic;         ///< "fsdv"
+  FsDir             fd;            ///< File descriptor
+  ssize_t           index;         ///< Current entry index
+  size_t            size;          ///< Current batch size
+  FsDirectoryEntry entry_data[32]; ///< Temporary storage for reading entries
 } fsdev_dir_t;
 
 /// Initializes the FS driver. Automatically initializes the sdmc device if accessible. If called again, sdmc mounting will be attempted again if it's not mounted.
@@ -35,4 +38,3 @@ int fsdevUnmountDevice(const char *name);
 /// Uses fsFsCommit() with the specified device. This must be used after any savedata-write operations(not just file-write).
 /// This is not used automatically at device unmount.
 Result fsdevCommitDevice(const char *name);
-

nx/include/switch/runtime/devices/usb_comms.h

@@ -1,3 +1,10 @@
+/**
+ * @file usb_comms.h
+ * @brief USB comms.
+ * @author yellows8
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../../types.h"
 
@@ -6,4 +13,3 @@ void usbCommsExit(void);
 
 size_t usbCommsRead(void* buffer, size_t size);
 size_t usbCommsWrite(const void* buffer, size_t size);
-

nx/include/switch/runtime/util/utf.h

@@ -1,6 +1,8 @@
 /**
  * @file utf.h
  * @brief UTF conversion functions.
+ * @author mtheall
+ * @copyright libnx Authors
  */
 #pragma once
 #include <sys/types.h>

nx/include/switch/types.h

@@ -1,6 +1,7 @@
 /**
  * @file types.h
  * @brief Various system types.
+ * @copyright libnx Authors
  */
 #pragma once
 
@@ -11,7 +12,6 @@
 /// The maximum value of a u64.
 #define U64_MAX	UINT64_MAX
 
-/// would be nice if newlib had this already
 #ifndef SSIZE_MAX
 #ifdef SIZE_MAX
 #define SSIZE_MAX ((SIZE_MAX) >> 1)
@@ -39,19 +39,20 @@ typedef volatile s16 vs16; ///< 16-bit volatile signed integer.
 typedef volatile s32 vs32; ///< 32-bit volatile signed integer.
 typedef volatile s64 vs64; ///< 64-bit volatile signed integer.
 
-typedef u32 Handle;                 ///< Resource handle.
-typedef u32 Result;                 ///< Function result.
+typedef u32 Handle;                 ///< Kernel object handle.
+typedef u32 Result;                 ///< Function error code result type.
 typedef void (*ThreadFunc)(void *); ///< Thread entrypoint function.
-typedef void (*voidfn)(void);
+typedef void (*voidfn)(void);       ///< Function without arguments nor return value.
 
+/// Permission bitmasks
 typedef enum {
-    PERM_NONE = 0,
-    PERM_R    = 1,
-    PERM_W    = 2,
-    PERM_X    = 4,
-    PERM_RW   = PERM_R | PERM_W,
-    PERM_RX   = PERM_R | PERM_X,
-    PERM_DONTCARE = 0x10000000
+    PERM_NONE = 0,               ///< No permissions.
+    PERM_R    = 1,               ///< Read permission.
+    PERM_W    = 2,               ///< Write permission.
+    PERM_X    = 4,               ///< Execute permission.
+    PERM_RW   = PERM_R | PERM_W, ///< Read/write permissions.
+    PERM_RX   = PERM_R | PERM_X, ///< Read/execute permissions.
+    PERM_DONTCARE = 0x10000000,  ///< Don't care
 } Permission;
 
 /// Creates a bitmask from a bit number.