From ff472848a9b0b707dce5edb4c827089f8ef131b9 Mon Sep 17 00:00:00 2001 From: fincs Date: Sun, 28 Jan 2018 16:22:44 +0100 Subject: [PATCH] Start doxygen bringup, with some miscellaneous cleanup --- .gitignore | 13 +++++- CODESTYLE.md | 34 +++++++------- Changelog.md | 0 LICENSE.md | 2 +- README.md | 8 ++-- nx/Doxyfile | 30 ++++++++++--- nx/include/switch.h | 1 + nx/include/switch/arm/cache.h | 30 +++++++++++++ nx/include/switch/arm/tls.h | 11 +++++ nx/include/switch/ipc.h | 10 ++++- nx/include/switch/kernel/svc.h | 3 +- nx/include/switch/result.h | 44 ++++++++++--------- nx/include/switch/runtime/devices/console.h | 6 ++- nx/include/switch/runtime/devices/fs_dev.h | 20 +++++---- nx/include/switch/runtime/devices/usb_comms.h | 8 +++- nx/include/switch/runtime/util/utf.h | 2 + nx/include/switch/types.h | 23 +++++----- 17 files changed, 171 insertions(+), 74 deletions(-) create mode 100644 Changelog.md diff --git a/.gitignore b/.gitignore index 7c41a47b..3c739fbb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,14 @@ +*~ *.o *.bz2 - +*.nro +*.nso +*.elf +*.npdm +*.pfs0 +Thumbs.db +.*/ +debug/ +release/ +lib/ +docs/ diff --git a/CODESTYLE.md b/CODESTYLE.md index e573e9ae..393e0a03 100644 --- a/CODESTYLE.md +++ b/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 \ No newline at end of file +## Functions +`modulenameFunctionName` + +## Macros +`LIKE_THIS` diff --git a/Changelog.md b/Changelog.md new file mode 100644 index 00000000..e69de29b diff --git a/LICENSE.md b/LICENSE.md index b4249b0e..b8327e3f 100644 --- a/LICENSE.md +++ b/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. diff --git a/README.md b/README.md index 746bba89..dcd51e22 100644 --- a/README.md +++ b/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/). diff --git a/nx/Doxyfile b/nx/Doxyfile index 5d2e991b..574d9afa 100644 --- a/nx/Doxyfile +++ b/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 - diff --git a/nx/include/switch.h b/nx/include/switch.h index 45503abb..706160a3 100644 --- a/nx/include/switch.h +++ b/nx/include/switch.h @@ -1,6 +1,7 @@ /** * @file switch.h * @brief Central Switch header. Includes all others. + * @copyright libnx Authors */ #pragma once diff --git a/nx/include/switch/arm/cache.h b/nx/include/switch/arm/cache.h index f40da62a..5cab03ee 100644 --- a/nx/include/switch/arm/cache.h +++ b/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); diff --git a/nx/include/switch/arm/tls.h b/nx/include/switch/arm/tls.h index 7ad9bfd2..e24ac85d 100644 --- a/nx/include/switch/arm/tls.h +++ b/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)); diff --git a/nx/include/switch/ipc.h b/nx/include/switch/ipc.h index 19e13350..2ceea7ac 100644 --- a/nx/include/switch/ipc.h +++ b/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 diff --git a/nx/include/switch/kernel/svc.h b/nx/include/switch/kernel/svc.h index 91439ab8..03139c6f 100644 --- a/nx/include/switch/kernel/svc.h +++ 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, diff --git a/nx/include/switch/result.h b/nx/include/switch/result.h index 01fcbee7..3827152d 100644 --- a/nx/include/switch/result.h +++ b/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 }; diff --git a/nx/include/switch/runtime/devices/console.h b/nx/include/switch/runtime/devices/console.h index f0a30a07..7c7f3726 100644 --- a/nx/include/switch/runtime/devices/console.h +++ b/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); - diff --git a/nx/include/switch/runtime/devices/fs_dev.h b/nx/include/switch/runtime/devices/fs_dev.h index 31fa3690..76164d40 100644 --- a/nx/include/switch/runtime/devices/fs_dev.h +++ b/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 #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); - diff --git a/nx/include/switch/runtime/devices/usb_comms.h b/nx/include/switch/runtime/devices/usb_comms.h index 6b0883ca..7c2c3efb 100644 --- a/nx/include/switch/runtime/devices/usb_comms.h +++ b/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); - diff --git a/nx/include/switch/runtime/util/utf.h b/nx/include/switch/runtime/util/utf.h index 40865b0a..a9a08df5 100644 --- a/nx/include/switch/runtime/util/utf.h +++ b/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 diff --git a/nx/include/switch/types.h b/nx/include/switch/types.h index 34aa86ce..683c8d23 100644 --- a/nx/include/switch/types.h +++ b/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.