Libctru 3DS

libctru
General
Author	devkitPro, fincs, WinterMute
Type	Developments
Version	2.4.1
License	Mixed
Last Updated	2024/11/04
Links
Website
Source
Support Author

libctru (formerly ctrulib) is a library for writing user mode ARM11 code for the 3DS (CTR).

It aims to provide the foundations necessary to write 3DS Homebrew, and straightforwardly access the different functionalities provided by the 3DS operating system. It is not meant to provide higher level functions; to put things in perspective, the purpose of libctru would be to sit between the OS and a possible port of SDL rather than replace it.

Originally located at github.com/smealum/ctrulib.

Installation

libctru is just a library and needs a toolchain to function. devkitARM (created by devkitPro) is the officially supported ARM cross compiling toolchain, which provides the framework necessary to supply a usable POSIX-like environment, with working C and C++ standard libraries; as well as the tools required to compile homebrew in the 3DSX format, and assemble GPU shaders. The use of other ARM toolchains is severely discouraged.

The most recent version of devkitARM is always recommended. The installers/setup scripts supplied by devkitPro install a prebuilt copy of the latest stable version of libctru, which is recommended for general use. Please note that devkitPro has a policy of keeping legacy code to a minimum, so a library upgrade may result in older code failing to compile or behave properly. Developers are encouraged to keep their code working with the latest versions of the tools and libraries.

You may find instructions on how to install devkitARM on the devkitPro Wiki.

User guide

Documentation can be found here.

Media

ctrulib first anniversary gource visualization (smea)

Changelog

v2.4

• Added full support for all QTM services, with extensive documentation and technical details in qtm.h and qtmc.h (breaking change); examples have been updated for this
• Added MCUHWC_SetInfoLedPattern
• Added ndspChnGetFormat
• Fixed PTMSYSM_CheckNew3DS
• Fixed NDMU_QueryStatus
• Fixed a few service commands improperly deserializing boolean output
• Fixed documentation of ACU_GetWifiStatus and ACU_SetAllowApType
• Fixed shaderInstanceInit to initialize all fields
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.

v2.3.1

• remove 3dstypes.h include from poll.h
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.

v2.3.0

• Fix typo in docs by @DeltaF1
• Add GPU_DOT3_RGBA texture combiner function by @oreo639
• FSUSER_GetLegacyBannerData: Fix documentation typo by @Tekito-256
• Add CTR_ prefix to ALIGN,PACKED,DEPRECATED macros by @glebm
• Buffer console control sequences by @piepie62
• Prevent CPU from postponing threadOnException memory writes
  • Add SSID-related ac:i functions
• ACI_LoadNetworkSetting, ACI_GetNetworkWirelessEssidSecuritySsid and acGetSessionHandle.
• Prevent double call of destructors on exit.
• Added experimental support for standard threading APIs (pthread, C threads, C++ std::thread)
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.

v2.2.1

• add define for curl.

v2.2.0

• apt: add deliver arg support to chainloader

v2.1.2

• Added cdc:CHK service wrappers
• Added support for clock_gettime
• svc: Fixed svcGetDmaState writing out-of-bounds data
• svc: Changed svcCreateCodeSet address parameters to pointer-sized integers, improve documentation
• fspxi: Fixed FSPXI_CreateFile and FSPXI_WriteFile
• ndsp: Added various ndspGet* and ndspChnGet* methods
• ir: Added IRU_GetSend/RecvFinishedEvent
• errf: Added ERRF_SetUserString and clarify documentation
• mcuhwc: Added mcuHwcGetSessionHandle
• apt: Fixed dirty homebrew chainload bug (used when Home Menu hasn't been started)
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.

v2.1.1

• FPSCR is now initialized with a predictable value in all threads (including the main thread).
• Added gspGetSessionHandle and gspLcdGetSessionHandle.
• Fixed bugs related to uninitialized data in srv/errf service wrappers.
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.

v2.1.0

• The #define for the 3DS platform has been changed to __3DS__ (previously it was _3DS) - please update your Makefiles and your code.

graphics:

• Refactored VRAM allocators:
  • Added proper handling for VRAM banks (A and B, 3 MiB each)
  • Allocations no longer cross VRAM bank boundaries
  • Added vramAllocAt, vramMemAlignAt
• Add gspIsPresentPending.
• Add return value to gspPresentBuffer.
• libctru console now supports SGR 38 and 48 escape sequences (needed by fmtlib).
• Fixed GPU_TEXFACE enum.

filesystem:

• Changed rename to replace existing files, for better compatibility with POSIX (#483)
• Added SDMMC speed info types, and more clock rates (#480).

miscellaneous:

• Added support for 3dslink stdio redirection (#488).
• Added ptm:gets, ptm:sets and more ptm service commands.
• Added AM_ContentInfo, AM_ContentInfoFlags structs.
• Added AMAPP_GetDLCContentInfoCount, AMAPP_ListDLCContentInfos.
• Fixed bug in Huffman decoder.
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.

v2.0.1

• Added CFG_SystemModel enum.
• Fixed bug in condvar code.
• Fixed bug in srvpm code.
• Fixed const correctness issues in gspgpu code.
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.

v2.0.0

system:

• Added support for userAppInit/userAppExit (backported from libnx).
• Changed default heap allocation logic to be more robust:
  • Resource limit SVCs are now used to detect available memory.
  • The heap size calculation algorithm was tweaked so that 32MB of linear heap are available for normal apps running under the default appmemtype layout on Old 3DS, as it was the case prior to libctru 1.8.0.
• SVC enhancements:
  • Added svcControlPerformanceCounter with corresponding enums.
  • Overhauled support for DMA related SVCs:
    • Added svcRestartDma.
    • Added enums and structures needed for DMA SVCs.
    • Added dmaDeviceConfigInitDefault, dmaConfigInitDefault.
  • Added svcArbitrateAddressNoTimeout (minor ABI optimization for the svcArbitrateAddress syscall when the timeout parameter is not used).
  • Changed process memory SVCs to use u32 parameters instead of void* for foreign-process addresses.
• Major refactor of OS related functions:
  • Added defines for Arm11 userland memory region addresses/sizes.
  • Added struct definitions for the kernel/system shared config pages: osKernelConfig_s, osSharedConfig_s.
  • Added macros to access the kernel/system shared config pages: OS_KernelConfig, OS_SharedConfig.
  • Fixed return type of osGetMemRegionUsed, osGetMemRegionFree (s64 -> u32).
  • Refactored osConvertVirtToPhys and added support for the missing linearly mapped memory regions.
  • Rewritten RTC time reading support to improve accuracy and match official logic more closely.
    • Time drift correction is now implemented.
    • Added osGetTimeRef function for reading the current reference timepoint published by the PTM sysmodule.
• Fixed osStrError to actually work properly.
• Cleaned up osGetSystemVersionData implementation.
• Other miscellaneous internal cleanup.

synchronization:

• Improved safety of usermode synchronization primitives when used in intercore contexts.
• Added CondVar synchronization primitive implementation.
• Added syncArbitrateAddress, syncArbitrateAddressWithTimeout.
  • These functions replace __sync_get_arbiter (which has been removed).
• Added __dmb (Data Memory Barrier) intrinsic.
• Added LightEvent_WaitTimeout.
• Added LightSemaphore_TryAcquire.
• Changed LightLock to support 0 as a valid initial (unlocked) state.
  • This effectively adds support for trivially initialized/zerofilled locks.
• Fixed bug in LightSemaphore_Acquire.

graphics:

• Major refactor of the GSP service wrapper. It should now be possible to use GSP directly without the gfx API, if the user so desires.
• Major internal refactor of the gfx wrapper API that increases maintainability.
• Added support for 800px wide mode with non-square pixels on the top screen - usable on every 3DS model except for Old 2DS (but including New 2DS XL).
• Added support for 800px wide mode to the libctru console.
• Transferred most of the GSP initialization duties to gspInit/gspExit (previously done by the gfx wrapper).
• Added defines for screen IDs and screen dimensions.
• Added gspPresentBuffer for pushing a framebuffer to the internal GSP swap queue (previously this was an internal function in the gfx wrapper).
• Added gspGetBytesPerPixel, gspHasGpuRight.
• Added gfxScreenSwapBuffers, with support for duplicating left->right eye content during stereoscopic 3D mode.
• Fixed LCD configuration mode when using framebuffers on VRAM with the gfx wrapper.
• Changed gfxExit to set LCD force-black status to true.
• Changed the gfx wrapper to always use gspPresentBuffer during swap. This means the immediate parameter of gfxConfigScreen no longer has any effect, and gfxSwapBuffers/gfxSwapBuffersGpu now do the same thing - that is, present the rendered content during the next VBlank.
• Renamed GSPGPU_FramebufferFormats enum to GSPGPU_FramebufferFormat.
• Deprecated gfxConfigScreen (use gfxScreenSwapBuffers instead).
• Removed gspInitEventHandler, gspExitEventHandler (now handled automatically inside gspInit/gspExit).
• Removed sharedGspCmdBuf param from gspSubmitGxCommand (now uses the proper GSP shared memory address automatically).
• Removed GSPGPU_REBASE_REG define (leftover from early 3DS homebrew).
• Removed numerous internal fields that were previously publicly accessible.

audio:

• DSP access rights are now managed using a hook mechanism, similar to the APT hook.
  • This fixes audio playback during libapplet invocations, as they no longer relinquish DSP rights.
• Changed NDSP to use the DSP hook instead of the APT hook.
• Added dspIsComponentLoaded, dspHook, dspUnhook.
• Fixed and improved robustness of wavebuf handling in NDSP code.
• Fixed and refactored NDSP sleep/wakeup code to improve accuracy compared to official logic.

filesystem:

• Reduced TLS footprint of the archive/romfs devices by sharing buffers.
• Reduced the maximum number of concurrently registered archive devices from 32 to 8 in order to save memory.
• Backported multi-mount romfs system from libnx, with additional optimizations (breaking API change).
• Added romfsMountFromTitle.
• Fixed stat for romfs device to return -1 for non-existent files/directories.

applet:

• Major internal refactor of the APT service wrapper that should improve accuracy compared to official logic.
• Fixed sleep handling when the app is inactive (i.e. app is suspended).
• Added support for screen capture during libapplet transitions.
• Added support for proper DSP access right management.
• aptLaunchLibraryApplet no longer calls aptMainLoop internally. Library applet calls no longer return a bool value, users are advised to check APT state manually afterwards.
• Added functions for checking APT state: aptIsActive, aptShouldClose, aptShouldJumpToHome, aptCheckHomePressRejected (replaces aptIsHomePressed).
• Added functions for handling incoming requests: aptHandleSleep, aptHandleJumpToHome.
• Added aptJumpToHomeMenu.
• Changed aptMainLoop to use the new wrapper functions (this means aptMainLoop can now be replaced by custom logic if desired).
• Changed APTHOOK_ONEXIT to be invoked during aptExit instead of during aptMainLoop.
• Added aptClearChainloader, aptSetChainloaderToSelf.

miscellaneous:

• Fix decompress out-of-bounds access.
• Added NDM_ prefix to NDM enum members in order to avoid name collisions.
• Corrected parameter type in several CFGU functions.
• Corrected return value of GSPLCD_GetBrightness.
• Removed obsolete support for ninjhax 1.x's fake hb:HB service.
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.

v1.9.0

• hid: Added hidKeysDownRepeat, hidWaitForAnyEvent. Allow user override of irsst usage.
• Add ptm rtc time commands.
• Add sleep state FSM handling service commands.
• Revamp mappableAlloc.
• Fixed stat on romfs for directories, implemented lstat via stat (FAT32 has no symlinks).
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.
• (binaries available via devkitPro pacman).

v1.8.0

• Added support for environments where the home menu is not launched (such as running under SAFE_FIRM).
• Added FSPXI service wrappers.
• Changed heap allocation logic to be more flexible; this fixes support for certain system memory layouts.
• Cleaned up and optimized light lock locking code.
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience.
• (binaries available via devkitPro pacman).

Release notes.

External links

• Official website - https://libctru.devkitpro.org
• GitHub - https://github.com/devkitPro/libctru