Files
swift-mirror/stdlib/public/EmbeddedPlatform/swift/EmbeddedPlatform.h
Boisy Pitre f9ce5f269b [stdlib] Convert EmbeddedPlatform.h doc comments to DocC syntax
The doc comments in the Embedded Swift Platform header used an
ad hoc "Parameters:" prose format that isn't recognized as
structured documentation by DocC's C header support. Convert
them to DocC's markdown list syntax (`- Parameters:` / `- Returns:`)
so the header's parameter and return-value descriptions render
as proper callouts instead of plain paragraphs.

Also fixes a typo in the _swift_generateRandomHashSeed doc comment
("constant values random than" -> "constant values rather than").
2026-07-15 14:03:22 -05:00

406 lines
15 KiB
C

/*===------------------ Embedded Swift Platform Declarations ------*- C -*-===*
*
* This source file is part of the Swift.org open source project
*
* Copyright (c) 2026 Apple Inc. and the Swift project authors
* Licensed under Apache License v2.0 with Runtime Library Exception
*
* See https: *swift.org/LICENSE.txt for license information
* See https: *swift.org/CONTRIBUTORS.txt for the list of Swift project authors
*
*===----------------------------------------------------------------------=== *
*
* This file provides a description of the functions that a platform is expected
* to provide to work with Embedded Swift. A "platform" in this case is broadly
* construed, and can be anything from a couple of function implementations
* within a standalone Embedded Swift program to a full-fledged SDK for an
* OS. Either way, any of these functions can be implemented either in Swift
* (using `@c`) or in C and linked into the final Embedded Swift executable.
*
* Many of these functions precisely match the signatures of functions defined
* by POSIX. This is deliberate, because it allows simple pass-through
* implementations for POSIX systems.
*
*===----------------------------------------------------------------------===*/
#ifndef EMBEDDED_SWIFT_PLATFORM_H
#define EMBEDDED_SWIFT_PLATFORM_H
#if defined(__SIZE_TYPE__) && defined(__PTRDIFF_TYPE__)
typedef __SIZE_TYPE__ __swift_size_t;
typedef __PTRDIFF_TYPE__ __swift_ptrdiff_t;
#else
#include <stddef.h>
typedef size_t __swift_size_t;
typedef ptrdiff_t __swift_ptrdiff_t;
#endif
/**
* 64-bit type identifier information that is used for typed allocation and
* deallocation.
*/
typedef unsigned long long __swift_typeid_t;
/**
* 64-bit type information that is used for typed allocation and
* deallocation.
*/
typedef unsigned long long __swift_options_t;
#if __has_feature(nullability)
#define EMBEDDED_SWIFT_NONNULL _Nonnull
#define EMBEDDED_SWIFT_NULLABLE _Nullable
#else
#define EMBEDDED_SWIFT_NONNULL
#define EMBEDDED_SWIFT_NULLABLE
#endif
#if defined(__has_feature) && (__has_feature(bounds_attributes) || __has_feature(bounds_safety_attributes))
#define EMBEDDED_SWIFT_COUNTED_BY(N) __attribute__((__counted_by__(N)))
#define EMBEDDED_SWIFT_SIZED_BY(N) __attribute__((__sized_by__(N)))
#define EMBEDDED_SWIFT_SINGLE __attribute__((__single__))
#else
#define EMBEDDED_SWIFT_COUNTED_BY(N)
#define EMBEDDED_SWIFT_SIZED_BY(N)
#define EMBEDDED_SWIFT_SINGLE
#endif
#if defined(__has_feature) && __has_attribute(flag_enum)
#define EMBEDDED_SWIFT_OPTION_SET __attribute__((flag_enum,enum_extensibility(open)))
#else
#define EMBEDDED_SWIFT_OPTION_SET
#endif
#if defined(__has_feature) && __has_attribute(swift_name)
#define EMBEDDED_SWIFT_NAME(_name) __attribute__((swift_name(#_name)))
#else
#define EMBEDDED_SWIFT_NAME(_name)
#endif
/**
* Major version number for the Swift Platform Abstraction Layer.
*
* The major version number will be increased when there is a breaking change to
* existing APIs.
*/
#define EMBEDDED_SWIFT_PLATFORM_VERSION_MAJOR 1
/**
* Minor version number for the Swift Platform Abstraction Layer.
*
* The minor version number will be increased when new APIs or flags are
* introduced in a manner that is not breaking for existing clients. The
* entrypoints might be optional, where the entrypoint is needed only when
* certain Swift functionality is used.
*/
#define EMBEDDED_SWIFT_PLATFORM_VERSION_MINOR 1
/**
* The number of pointer-size words that will be used to store a Mutex (as
* provided by the Synchronization library).
*
* This needs to be large enough to accommodate any implementation of Mutex that
* can be implemented for that given platform (e.g., via the `_swift_mutex_*`
* functions). It can be defined externally (via `-D` on the command line for
* Clang, `-Xcc -D` for Swift) to a different value, but that value must be
* consistent throughout the build to prevent ABI mismatches.
*/
#ifndef EMBEDDED_SWIFT_MUTEX_NUM_WORDS
#if defined(__APPLE__) && __SIZEOF_POINTER__ == 4
// On 32-bit Apple targets (e.g., watchOS armv7k / arm64_32) `pthread_mutex_t`
// is 40 bytes, which doesn't fit in 8 four-byte words.
#define EMBEDDED_SWIFT_MUTEX_NUM_WORDS (__swift_ptrdiff_t)12
#else
#define EMBEDDED_SWIFT_MUTEX_NUM_WORDS (__swift_ptrdiff_t)8
#endif
#endif
/**
* Determine the version of the platform abstraction layer that the Embedded
* Swift library was built with.
*
* - Parameters:
* - major: The value of EMBEDDED_SWIFT_PLATFORM_VERSION_MAJOR that the
* Swift standard library was built with.
* - minor: The value of EMBEDDED_SWIFT_PLATFORM_VERSION_MINOR that the
* Swift standard library was built with.
*
* This function is provided by the Swift standard library, and declared here
* for the convenience of C clients.
*/
void swift_getPlatformLayerVersion(
__swift_ptrdiff_t * EMBEDDED_SWIFT_NONNULL EMBEDDED_SWIFT_SINGLE major,
__swift_ptrdiff_t * EMBEDDED_SWIFT_NONNULL EMBEDDED_SWIFT_SINGLE minor);
/**
* Options provided to the Swift memory allocation function.
*/
typedef enum EMBEDDED_SWIFT_OPTION_SET: __swift_options_t {
/**
* No options.
*/
SWIFT_ALLOC_NONE EMBEDDED_SWIFT_NAME(none) = 0,
/**
* Zero the memory before returning it, like the C library function `calloc`.
*/
SWIFT_ALLOC_ZERO_MEMORY EMBEDDED_SWIFT_NAME(zeroMemory) = 0x01
} swift_alloc_flags_t EMBEDDED_SWIFT_NAME(SwiftAllocateFlags);
/**
* Options provided to the Swift memory deallocation function.
*/
typedef enum EMBEDDED_SWIFT_OPTION_SET: __swift_options_t {
/**
* No options.
*/
SWIFT_DEALLOC_NONE EMBEDDED_SWIFT_NAME(none) = 0,
} swift_dealloc_flags_t EMBEDDED_SWIFT_NAME(SwiftDeallocFlags);
/**
* Options provided to the Swift mutex initialization function.
*/
typedef enum EMBEDDED_SWIFT_OPTION_SET: __swift_options_t {
/**
* No options.
*/
SWIFT_MUTEX_NONE EMBEDDED_SWIFT_NAME(none) = 0,
/**
* Diagnose mutex misuse when the platform can do so cheaply.
*/
SWIFT_MUTEX_CHECKED EMBEDDED_SWIFT_NAME(checked) = 0x01,
/**
* Allow the same execution context to acquire the mutex recursively.
*/
SWIFT_MUTEX_RECURSIVE EMBEDDED_SWIFT_NAME(recursive) = 0x02
} swift_mutex_flags_t EMBEDDED_SWIFT_NAME(SwiftMutexFlags);
/**
* Allocates memory and returns the resulting pointer.
*
* - Parameters:
* - alignment: The minimum alignment of the resulting pointer, which must
* be a power of at least as large as `sizeof(void *)`.
* - size: The minimum number of bytes to allocate.
* - flags: Flags to control the behavior of the allocation.
*
* - Returns: The allocated pointer, or NULL on failure.
*
* This function is required when using any Embedded Swift facility that
* requires memory allocation from the heap, whether explicitly (e.g., via the
* `allocate` operation on unsafe pointers) or implicitly (e.g., creating a
* copy-on-write array or an instance of a class type).
*
* This function can be implemented as a call to `posix_memalign`.
*/
void * EMBEDDED_SWIFT_NULLABLE _swift_allocate(__swift_size_t alignment, __swift_size_t size, swift_alloc_flags_t flags);
/**
* Deallocates the memory referenced by `ptr`.
*
* - Parameters:
* - ptr: The pointer to be deallocated. If it is NULL, the operation does
* nothing.
* - alignment: The minimum alignment of the resulting pointer, which must
* be a power of at least as large as `sizeof(void *)`, or be zero to
* indicate that the alignment is not known.
* - size: The number of allocated bytes, which may be -1 if it is not
* known.
* - flags: Flags to control the behavior of the deallocation.
*
* This function is required when using any Embedded Swift facility that
* requires memory allocation from the heap, whether explicitly (e.g., via the
* `allocate` operation on unsafe pointers) or implicitly (e.g., creating a
* copy-on-write array or an instance of a class type).
*
* This function can be implemented as a direct call to `free`.
*/
void _swift_deallocate(void * EMBEDDED_SWIFT_NONNULL ptr, __swift_size_t alignment, __swift_size_t size, swift_dealloc_flags_t flags);
/**
* Allocates memory with a given type and returns the resulting pointer.
*
* - Parameters:
* - size: The minimum number of bytes to allocate.
* - alignment: The minimum alignment of the resulting pointer, which must
* be a power of at least as large as `sizeof(void *)`.
* - flags: Flags to control the behavior of the allocation.
* - typeId: An identifier used by a typed allocator to e.g. place the
* allocation in a particular bucket.
*
* - Returns: The allocated pointer, or NULL on failure.
*
* This function is required when using any Embedded Swift facility that
* requires typed memory allocation from the heap, e.g. class instance
* allocations when the TypedAllocation feature is enabled.
*
* This function can be implemented as a direct call to `posix_memalign`,
* if the target platform does not support typed allocations.
*/
void * EMBEDDED_SWIFT_NULLABLE _swift_typedAllocate(
__swift_size_t size, __swift_size_t alignment, swift_alloc_flags_t flags, __swift_typeid_t typeId);
/**
* Writes a sequence of UTF-8 code points to standard output.
*
* - Parameters:
* - chars: The UTF-8 code points to standard output. It is not
* NULL-terminated.
* - count: The number of UTF-8 code points.
*
* - Returns: The number of characters that were written.
*
* This function is required when using the Embedded Swift print() facilities.
*
* This function can be implemented as a call to fwrite or printf with the
* specified number of code points.
*/
__swift_size_t _swift_writeToStandardOutput(
const unsigned char * EMBEDDED_SWIFT_NULLABLE EMBEDDED_SWIFT_COUNTED_BY(count) chars,
__swift_size_t count);
/**
* Generates random bytes into the given buffer.
*
* - Parameters:
* - buffer: The buffer into which the random bytes should be generated.
* - nbytes: The number of bytes that should be generated into the buffer.
*
* This function is required when using Swift's SystemRandomNumberGenerator, the
* default random number generator used for shuffling elements and producing
* random values. While this function is encouraged to use a cryptographically
* secure algorithm, it is not required to do so.
*
* Note that this function is not used to provide random seeding for the hash
* functions used in Set and Dictionary. Those operations use
* `_swift_generateRandomHashSeed`.
*
* This function can be implemented as a direct call to `arc4random_buf`.
*/
void _swift_generateRandom(void * EMBEDDED_SWIFT_NONNULL EMBEDDED_SWIFT_SIZED_BY(nbytes) buffer, __swift_size_t nbytes);
/**
* Generates random bytes intended for a hashing seed into the given buffer.
*
* - Parameters:
* - buffer: The buffer into which the random bytes should be generated.
* - nbytes: The number of bytes that should be generated into the buffer.
*
* This function is required when using Swift's hashed collections, such as Set
* and Dictionary, to provide random seeding for the hash functions. Random
* seeding makes hash values differ from one execute to the next, mitigating
* against denial-of-service attacks that target a known hash function. The
* random number generator provided here need not be cryptographically
* secure. An implementation may choose to provide constant values rather than a
* random seed to make hashing deterministic.
*
* This function can be implemented as a direct call to `arc4random_buf`.
*/
void _swift_generateRandomHashSeed(void * EMBEDDED_SWIFT_NONNULL EMBEDDED_SWIFT_SIZED_BY(nbytes) buffer, __swift_size_t nbytes);
/**
* Retrieve a pointer that will be used to retain information needed for Swift's
* dynamic exclusivity checking.
*
* - Returns: The pointer most recently passed to `_swift_setExclusivityTLS` on
* this thread. If `_swift_setExclusivityTLS` has not been called on this
* thread, returns NULL.
*
* In a single-threaded environment, the `_swift_getExclusivityTLS` and
* `_swift_setExclusivityTLS` functions can get and set a global variable that
* is initialized to NULL. In a multi-threaded environment, the variable will
* need to be in thread-local storage (e.g., using C11 `_Thread_local`) or a
* similar facility.
*
* This function is required when using Swift's dynamic exclusivity checking,
* which is enabled by the Swift compiler option `-enforce-exclusivity=checked`
* and required when the compiler cannot statically prove that all accesses to a
* given variable (such as a global variable or a stored instance property of a
* class) respect the exclusivity model.
*/
void * EMBEDDED_SWIFT_NULLABLE _swift_getExclusivityTLS(void);
/**
* Set the pointer that will be used to retain information needed for Swift's
* dynamic exclusivity checking.
*
* - Parameters:
* - ptr: The pointer to set. A subsequent call to
* `_swift_getExclusivityTLS` on the same thread (without an intervening
* call to `_swift_setExclusivityTLS`) shall return `ptr`.
*
* See `_swift_getExclusivityTLS` for more information about dynamic exclusivity
* checking.
*/
void _swift_setExclusivityTLS(void * EMBEDDED_SWIFT_NULLABLE ptr);
/**
* Initializes a mutex.
*
* - Parameters:
* - mutex: Opaque caller-owned mutex storage initialized by this function
* and later passed to the other `_swift_mutex_*` functions. The contents
* are private to the platform implementation. The storage is at least
* EMBEDDED_SWIFT_MUTEX_NUM_WORDS pointer-sized words and has pointer
* alignment.
* - flags: Flags controlling mutex behavior.
*
* This function is required when using Synchronization.Mutex.
*/
void _swift_mutex_init(void * EMBEDDED_SWIFT_NONNULL mutex,
swift_mutex_flags_t flags);
/**
* Destroys a mutex initialized by `_swift_mutex_init`.
*
* - Parameters:
* - mutex: The mutex to destroy. Must not be locked.
*/
void _swift_mutex_destroy(void * EMBEDDED_SWIFT_NONNULL mutex);
/**
* Acquires a mutex, blocking or spinning until ownership is obtained.
*
* - Parameters:
* - mutex: The mutex to acquire.
*/
void _swift_mutex_lock(void * EMBEDDED_SWIFT_NONNULL mutex);
/**
* Releases a mutex held by the current execution context.
*
* - Parameters:
* - mutex: The mutex to release.
*/
void _swift_mutex_unlock(void * EMBEDDED_SWIFT_NONNULL mutex);
/**
* Attempts to acquire a mutex without blocking.
*
* - Parameters:
* - mutex: The mutex to attempt to acquire.
*
* - Returns: Nonzero if the mutex was acquired, or zero if it was not acquired.
*/
__swift_ptrdiff_t _swift_mutex_tryLock(void * EMBEDDED_SWIFT_NONNULL mutex);
/**
* Exit the program.
*
* - Parameters:
* - code: The exit code, which is typically 0 for normal termination.
*
* This function must not return.
*
* This function can be implemented directly with a call to the POSIX exit()
* function.
*/
void _swift_exit(__swift_ptrdiff_t code);
#undef EMBEDDED_SWIFT_NAME
#undef EMBEDDED_SWIFT_OPTION_SET
#endif