blob: 1cf6e5107ea09e43400b51d0bd562a09b2a696aa [file] [log] [blame]
Josh Gaobfb6bae2016-07-15 17:25:21 -07001/*
Elliott Hughesdfb74c52016-10-24 12:53:17 -07002 * Copyright (C) 2016 The Android Open Source Project
Josh Gaobfb6bae2016-07-15 17:25:21 -07003 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
Elliott Hughesdfb74c52016-10-24 12:53:17 -07008 * http://www.apache.org/licenses/LICENSE-2.0
Josh Gaobfb6bae2016-07-15 17:25:21 -07009 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
Elliott Hughesc0f46562018-11-09 15:38:52 -080017#pragma once
Josh Gaobfb6bae2016-07-15 17:25:21 -070018
Dan Alberted2d3832024-08-28 20:21:52 +000019/**
20 * @def __ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__
21 *
22 * Controls whether calling APIs newer than the developer's minSdkVersion are a
23 * build error (when not defined) or allowed as a weak reference with a
24 * __builtin_available() guard (when defined).
25 *
26 * See https://developer.android.com/ndk/guides/using-newer-apis for more
27 * details.
28 */
Elliott Hughesa37b1812021-02-11 12:56:39 -080029#if defined(__ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__)
Dan Alberted2d3832024-08-28 20:21:52 +000030// In this mode, Clang will emit weak references to the APIs if the
31// minSdkVersion is less than the __what argument. This allows the libraries to
32// load even on systems too old to contain the API, but calls must be guarded
33// with `__builtin_available(android api_level, *)` to avoid segfaults.
Dan Albert398e1aa2024-05-01 22:06:54 +000034#define __BIONIC_AVAILABILITY(__what, ...) __attribute__((__availability__(android,__what __VA_OPT__(,) __VA_ARGS__)))
Dan Alberte5da4962024-10-24 22:09:09 +000035
36// When the caller is using weak API references, we should expose the decls for
37// APIs which are not available in the caller's minSdkVersion, otherwise there's
38// no way to take advantage of the weak references.
39#define __BIONIC_AVAILABILITY_GUARD(api_level) 1
Jiyong Park23bfed22020-08-10 13:35:05 +090040#else
Dan Alberted2d3832024-08-28 20:21:52 +000041// The 'strict' flag is required for NDK clients where the code was not written
42// to handle the case where the API was available at build-time but not at
43// run-time. Most 3p code ported to Android was not written to use
44// `__builtin_available()` for run-time availability checking, and so would not
45// compile in this mode (or worse, if the build doesn't use
46// -Werror=unguarded-availability, it would build but crash at runtime).
Dan Albert398e1aa2024-05-01 22:06:54 +000047#define __BIONIC_AVAILABILITY(__what, ...) __attribute__((__availability__(android,strict,__what __VA_OPT__(,) __VA_ARGS__)))
Dan Alberte5da4962024-10-24 22:09:09 +000048
49// When the caller is using strict API references, we hide APIs which are not
50// available in the caller's minSdkVersion. This is a bionic-only deviation in
51// behavior from the rest of the NDK headers, but it's necessary to maintain
52// source compatibility with 3p libraries that either can't correctly detect API
53// availability (either incorrectly detecting as always-available or as
54// never-available, but neither is true), or define their own polyfills which
55// conflict with our declarations.
56//
57// https://github.com/android/ndk/issues/2081
58#define __BIONIC_AVAILABILITY_GUARD(api_level) (__ANDROID_MIN_SDK_VERSION__ >= (api_level))
Jiyong Park23bfed22020-08-10 13:35:05 +090059#endif
60
Aditya Kumar52fe6ce2024-10-10 20:40:39 +000061#pragma clang diagnostic push
62#pragma clang diagnostic ignored "-Wc23-extensions"
63// Passing no argument for the '...' parameter of a variadic macro is a C23 extension
Elliott Hughesa37b1812021-02-11 12:56:39 -080064#define __INTRODUCED_IN(api_level) __BIONIC_AVAILABILITY(introduced=api_level)
Aditya Kumar52fe6ce2024-10-10 20:40:39 +000065#pragma clang diagnostic pop
66
Dan Alberte25abd92024-05-15 17:55:55 +000067#define __DEPRECATED_IN(api_level, msg) __BIONIC_AVAILABILITY(deprecated=api_level, message=msg)
68#define __REMOVED_IN(api_level, msg) __BIONIC_AVAILABILITY(obsoleted=api_level, message=msg)
Jiyong Park23bfed22020-08-10 13:35:05 +090069
70// The same availability attribute can't be annotated multiple times. Therefore, the macros are
71// defined for the configuration that it is valid for so that declarations like the below doesn't
72// cause inconsistent availability values which is an error with -Wavailability:
73//
74// void foo() __INTRODUCED_IN_32(30) __INTRODUCED_IN_64(31);
75//
Jiyong Park23bfed22020-08-10 13:35:05 +090076#if !defined(__LP64__)
Elliott Hughesa37b1812021-02-11 12:56:39 -080077#define __INTRODUCED_IN_32(api_level) __BIONIC_AVAILABILITY(introduced=api_level)
Logan Chiend7d9ebc2019-11-27 07:25:07 -080078#define __INTRODUCED_IN_64(api_level)
Jiyong Park23bfed22020-08-10 13:35:05 +090079#else
80#define __INTRODUCED_IN_32(api_level)
Elliott Hughesa37b1812021-02-11 12:56:39 -080081#define __INTRODUCED_IN_64(api_level) __BIONIC_AVAILABILITY(introduced=api_level)
Jiyong Park23bfed22020-08-10 13:35:05 +090082#endif