1 // Copyright 2024 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 /// @defgroup pw_must_place 17 /// @{ 18 19 // clang-format off 20 /// @cond PRIVATE 21 #define ___PW_MUST_PLACE(isection, start_sym, end_sym) \ 22 start_sym = .; \ 23 isection \ 24 end_sym = .; \ 25 ASSERT(start_sym != end_sym, \ 26 "Error: No symbols found in pattern below"); \ 27 ASSERT(start_sym != end_sym, #isection) 28 29 #define __PW_MUST_PLACE(isection, sym_prefix, unique) \ 30 ___PW_MUST_PLACE(isection, sym_prefix ## start_ ## unique, sym_prefix ## end_ ## unique) 31 32 #define _PW_MUST_PLACE(isection, sym_prefix, unique) \ 33 __PW_MUST_PLACE(isection, sym_prefix, unique) 34 /// @endcond 35 36 /// PW_MUST_PLACE is a macro intended for use in linker scripts to ensure inputs 37 /// are non-zero sized. 38 /// 39 /// Say you want to place a specific object file into a particular section. You 40 /// can reference it by file path like: 41 /// 42 /// @code 43 /// SECTIONS 44 /// { 45 /// .special_code 46 /// { 47 /// */src/path/libspecial_code.a:*.o 48 /// } 49 /// } 50 /// @endcode 51 /// 52 /// This works but is fragile as it will silently break if the filename or path 53 /// changes. Use PW_MUST_PLACE to get a linker assertion if the input is empty. 54 /// 55 /// @code 56 /// #include "pw_build/must_place.ld.h" 57 /// 58 /// SECTIONS 59 /// { 60 /// .special_code 61 /// { 62 /// PW_MUST_PLACE(*/src/path/libspecial_code.a:*.o) 63 /// } 64 /// } 65 /// @endcode 66 /// 67 /// If the wildcard match fails PW_MUST_PLACE will generate an error telling you 68 /// which input had no symbols. 69 /// 70 /// @code 71 /// Error: No symbols found in pattern below 72 /// */src/path/libspecial_code.a:*.o 73 /// @endcode 74 /// 75 /// This could be because you had a typo, the path changed, or the symbols were 76 /// dropped due to linker section garbage collection.In the latter case, 77 /// you can choose to add ``KEEP()`` around your input to prevent garbage 78 /// collection. 79 #define PW_MUST_PLACE(isection) \ 80 _PW_MUST_PLACE(isection, __section_place_, __LINE__) 81 82 /// @} 83