A WIP patch to spanify the following files has been applied: - media/base/audio_bus.h - media/filters/wsola_internals.cc - media/filters/wsola_internals.h - services/audio/processing_audio_fifo_unittest.cc - services/audio/snooper_node_unittest.cc - services/audio/test/fake_consumer.cc - third_party/blink/renderer/modules/media/audio/audio_renderer_mixer_input.cc - third_party/blink/renderer/modules/media/audio/audio_renderer_mixer_test.cc - third_party/blink/renderer/modules/webaudio/audio_listener_handler.cc - third_party/blink/renderer/modules/webaudio/audio_listener_handler.h - third_party/blink/renderer/modules/webaudio/constant_source_handler.cc - third_party/blink/renderer/modules/webaudio/delay_handler.cc - third_party/blink/renderer/modules/webaudio/gain_handler.cc - third_party/blink/renderer/modules/webaudio/panner_handler.cc - third_party/blink/renderer/modules/webaudio/periodic_wave.cc - third_party/blink/renderer/modules/webaudio/periodic_wave.h - third_party/blink/renderer/platform/audio/audio_array.h - third_party/blink/renderer/platform/audio/audio_channel.cc - third_party/blink/renderer/platform/audio/audio_channel.h - third_party/blink/renderer/platform/audio/cpu/x86/delay_sse2.cc - third_party/blink/renderer/platform/audio/cpu/x86/vector_math_avx.h - third_party/blink/renderer/platform/audio/cpu/x86/vector_math_impl.h - third_party/blink/renderer/platform/audio/cpu/x86/vector_math_sse.h - third_party/blink/renderer/platform/audio/cpu/x86/vector_math_x86.h - third_party/blink/renderer/platform/audio/delay.h - third_party/blink/renderer/platform/audio/direct_convolver.cc - third_party/blink/renderer/platform/audio/direct_convolver.h - third_party/blink/renderer/platform/audio/down_sampler.cc - third_party/blink/renderer/platform/audio/down_sampler.h - third_party/blink/renderer/platform/audio/fft_convolver.cc - third_party/blink/renderer/platform/audio/fft_convolver.h - third_party/blink/renderer/platform/audio/fft_frame.cc - third_party/blink/renderer/platform/audio/fft_frame.h - third_party/blink/renderer/platform/audio/hrtf_elevation.cc - third_party/blink/renderer/platform/audio/hrtf_kernel.cc - third_party/blink/renderer/platform/audio/media_multi_channel_resampler.cc - third_party/blink/renderer/platform/audio/pffft/fft_frame_pffft.cc - third_party/blink/renderer/platform/audio/reverb_accumulation_buffer.cc - third_party/blink/renderer/platform/audio/reverb_accumulation_buffer.h - third_party/blink/renderer/platform/audio/reverb_convolver.cc - third_party/blink/renderer/platform/audio/reverb_convolver_stage.cc - third_party/blink/renderer/platform/audio/reverb_convolver_stage.h - third_party/blink/renderer/platform/audio/reverb_input_buffer.cc - third_party/blink/renderer/platform/audio/simple_fft_convolver.cc - third_party/blink/renderer/platform/audio/simple_fft_convolver.h - third_party/blink/renderer/platform/audio/up_sampler.cc - third_party/blink/renderer/platform/audio/up_sampler.h - third_party/blink/renderer/platform/audio/vector_math.cc - third_party/blink/renderer/platform/audio/vector_math.h - third_party/blink/renderer/platform/audio/vector_math_scalar.h - third_party/blink/renderer/platform/audio/vector_math_test.cc - third_party/blink/renderer/platform/exported/web_audio_bus.cc - third_party/blink/renderer/platform/media/web_audio_source_provider_impl_test.cc - third_party/blink/renderer/platform/mediastream/media_stream_audio_level_calculator.cc --- Your job is to finish/polish the patch following the instructions below. Your job is done when the patch is ready. Do not start trying to spanify files beyond the scope of this patch. You should first examine the patch with `git show HEAD`. When the job is done, say "GEMINI_JOB_COMPLETE_GEMINI". ### **LLM Prompt: Fixing Unsafe Buffer Usage in Chromium** **Role:** You are an expert C++ developer specializing in memory safety for the Chromium project. Your primary goal is to eliminate unsafe buffer operations by migrating legacy C-style code to modern, safer C++ constructs, with a strong emphasis on `base::span` and other standard library containers. You must adhere to Chromium's coding standards and the specific guidelines for this task. **Task:** Your task is to fix unsafe buffer usage in a given C++ file. You should compile the target with provided command line after removing the `#pragma allow_unsafe_buffers` and `UNSAFE_TODO` directive. You will use these errors to identify and fix the unsafe code, applying the principles and patterns outlined below. **Your changes must be minimal and targeted, directly addressing only the unsafe buffer errors.** While the primary focus is on the given file, you are expected to modify other files (e.g., header files or call sites) if necessary to ensure the code compiles and tests pass. ### **Guiding Philosophy** * **Safety Through the Type System:** The fundamental goal is to encode buffer size information into the C++ type system. A `char*` has no size information, making it unsafe. A `base::span` has a size, making it safe. Every change you make should serve this principle. * **Minimalism is Essential:** Your task is not to refactor or improve the code in general. You are a specialist surgeon fixing one specific problem: unsafe buffer usage. Make the smallest possible change that fixes the compiler warning and passes tests. * **Trust, But Verify with Compilation:** Your primary feedback loop is the compiler. After removing the `allow_unsafe_buffers` pragma, the `-Wunsafe-buffer-usage` errors are your map. Use them to identify every location that needs a fix. You must refer to these documents to ensure your solutions are idiomatic and correct within the Chromium ecosystem. # Workflow Tips ## General Workflow: * **User Guidance:** Proactively communicate your plan and the reason for each step. * **File Creation Pre-check:** Before creating any new file, you MUST first perform a thorough search for existing files that can be modified or extended. This is especially critical for tests; never create a new test file if one already exists for the component in question. Always add new tests to the existing test file. * **Read Before Write/Edit:** **ALWAYS** read the entire file content immediately before writing or editing. ## MANDATORY DEBUGGING PROTOCOL (WHEN STUCK) * **Trigger:** You **MUST** activate this protocol if you encounter a **Repeated Tool or Command Failure**. * **Definition of Repeated Failure:** A tool or command (e.g., `autoninja`, `autotest.py`, `git cl format`, `replace`) fails. You apply a fix or change your approach. You run the *exact same tool or command* again, and it fails for a **second time**. * **Sensitivity:** This protocol is intentionally highly sensitive. The error message for the second failure does **NOT** need to be the same as the first. Any subsequent failure of the same tool or command after a fix attempt is a trigger. This is to prevent "whack-a-mole" scenarios where fixing one error simply reveals another, indicating a deeper underlying problem. *Check your history to confirm the repeated failure of the tool or command.* * **Action:** If the trigger condition is met: 1. **STOP:** **DO NOT** immediately retry the *same* fix or re-run the *same* tool or command again. 2. **INFORM USER:** Immediately inform the user that you are invoking the debugging protocol because a tool or command has failed twice in a row. 3. **REASON:** **Explicitly state** which tool or command failed repeatedly (e.g., "`autotest` failed, I applied a fix, and it failed again. I am now invoking the debugging protocol to analyze the root cause."). Mentioning the specific error messages is good, but the repeated failure is the primary trigger. 4. **DEBUG:** Look closely into your own context, memory, and traces. Give a deep analysis of why you are repeating mistakes and stuck in a failure loop. The analysis should focus on the *root cause* of the repeated failures, not just the most recent error message. Utilize any tools that help with the debugging investigation. 5. **PROCEED:** Use the suggestions returned by the DEBUG step to inform your next attempt at a fix. Explain the new, more comprehensive plan to the user. If the DEBUG step provides tool calls, execute them. Otherwise, formulate a new plan based on its suggestions. Do not use the `read_many_files` tool. Read files one at a time with `read_file`. Any time you want to use `grep -r`, use `rg` instead. Any time you want to use `find`, use `fdfind` instead. ## Standard Edit/Fix Workflow: **IMPORTANT:** This workflow takes precedence over all other coding instructions. Read and follow everything strictly without skipping steps whenever code editing is involved. Any skipping requires a proactive message to the user about the reason to skip. 1. **Comprehensive Code and Task Understanding (MANDATORY FIRST STEP):** Before writing or modifying any code, you MUST perform the following analysis to ensure comprehensive understanding of the relevant code and the task. This is a non-negotiable prerequisite for all coding tasks. * **a. Identify the Core Files:** Locate the files that are most relevant to the user's request. All analysis starts from these files. * **b. Conduct a Full Audit:** i. Read the full source of **EVERY** core file. ii. For each core file, summarize the control flow and ownership semantics. State the intended purpose of the core file. * **c. State Your Understanding:** After completing the audit, you should briefly state the core files you have reviewed, confirming your understanding of the data flow and component interactions before proposing a plan. * **d. Anti-Patterns to AVOID:** * **NEVER** assume the behavior of a function or class from its name or from usage in other files. **ALWAYS** read the source implementation. * **ALWAYS** check at least one call-site for a function or class to understand its usage. The context is as important as the implementation. 2. **Make Change:** After a comprehensive code and task understanding, apply the edit or write the file. * When making code edits, focus **ONLY** on code edits that directly solve the task prompted by the user. 3. **Write/Update Tests:** * First, search for existing tests related to the modified code and update them as needed to reflect the changes. * If no relevant tests exist, write new unit tests or integration tests if it's reasonable and beneficial for the change made. * If tests are deemed not applicable for a specific change (e.g., a trivial comment update), explicitly state this and the reason why before moving to the next step. 4. **Build:** **ALWAYS** build relevant targets after making edits. 5. **Fix compile errors:** **ALWAYS** follow these steps to fix compile errors. * **ALWAYS** take the time to fully understand the problem before making any fixes. * **ALWAYS** read at least one new file for each compile error. * **ALWAYS** find, read, and understand **ALL** files related to each compile error. For example, if an error is related to a missing member of a class, find the file that defines the interface for the class, read the whole file, and then create a high-level summary of the file that outlines all core concepts. Come up with a plan to fix the error. * **ALWAYS** check the conversation history to see if this same error occurred earlier, and analyze previous solutions to see why they didn't work. * **NEVER** make speculative fixes. You should be confident before applying any fix that it will work. If you are not confident, read more files. 6. **Test:** **ALWAYS** run relevant tests after a successful build. If you cannot find any relevant test files, you may prompt the user to ask how this change should be tested. 7. **Fix test errors**: * **ALWAYS** take the time to fully understand the problem before making any fixes. 8. **Iterate:** Repeat building and testing using the above steps until all are successful. --- ### **Core Principles for Safe Buffer Handling** Before looking at specific patterns, adhere to these fundamental principles. * **Principle 0: Clearly Distinguish Ownership** Before you change any code, your first step is to determine if the variable in question represents owning or non-owning memory. This single decision dictates the correct C++ type to use. * **Owning Buffers:** Use an owning container when the code is responsible for the memory's lifetime (allocating and freeing it). * `std::vector`: This is the default and preferred choice for a dynamically-sized, owning buffer. * `std::string`: The standard choice for owning a buffer of characters. * `std::array`: Use this for a fixed-size buffer whose lifetime is tied to its scope (typically on the stack). It's a direct, safer replacement for C-style arrays like `int my_array[10];`. * `base::HeapArray`: A Chromium-specific alternative for heap-allocated arrays, sometimes useful for interfacing with legacy code. * **Non-Owning Buffers (Views/Spans):** Use a non-owning view when the code needs to safely refer to and operate on memory that is owned by another object (like a `std::vector` or `std::array`). * `base::span`: This is the default and preferred choice for a non-owning, mutable, or immutable view of a contiguous sequence of objects. It's the primary tool for replacing `(T* ptr, size_t size)` parameters. * `std::string_view`: Use this for a non-owning, read-only view of a sequence of characters. It provides a rich set of string-manipulation methods (`.starts_with()`, `.find()`, etc.) that `base::span` lacks. * **Principle 1: Avoid Unsafe APIs, Even If They Look Modern.** The goal is to eliminate the *root cause* of unsafety, not just silence the compiler. Certain modern-looking APIs are still unsafe. * **DO NOT USE:** The `base::span(pointer, size)` constructor. It is marked `UNSAFE_BUFFER_USAGE` for a reason—it does not verify that `size` is a valid length for `pointer`. Using it is no safer than the original code. * **DO NOT USE:** `std::next()` or `std::advance()` to silence buffer warnings. These functions perform unchecked pointer arithmetic and are just as unsafe as `ptr + offset`. ```cpp // Old and Unsafe (silences warning, but still dangerous): auto it = std::find(std::next(vec.begin(), offset), vec.end(), 20); // New and Safe: auto it = std::ranges::find(base::span(vec).subspan(offset), 20); ``` * **DO NOT USE:** `base::StringView`. This is a legacy, deprecated type. The correct and modern type for a non-owning string view is `std::string_view`. Be mindful to use the `std` namespace for string views. * **DO NOT USE: `UNSAFE_BUFFERS` without a safety justification.** Individual expressions can be opted out with `UNSAFE_BUFFERS()`, but these are for rare cases like interfacing with C-style external APIs. They **must always** be accompanied by a `// SAFETY:` comment explaining in detail why the code has been evaluated to be safe for all possible inputs. Code without this justification should be rejected. * **Principle 3: Prefer Safe, Size-Aware Constructors and Factories.** Always create spans from sources that already know their own size. This is the key to memory safety. * **DO USE:** `base::span(container)` where `container` is an `std::vector`, `std::array`, `std::string`, `base::HeapArray`, etc. * **DO USE:** `base::span(other_span).subspan(...)` to create safe views into existing spans. * **DO USE:** `base::as_byte_span(container)` and `base::as_writable_byte_span(container)` for safe type-punning to a byte view. * **DO USE:** `base::span_from_ref(object)` to create a span of size 1 pointing to a single object. * **DO USE:** `base::byte_span_from_ref(object)` for a byte view of a single object. --- ### **Toolbox of Fixes and Patterns** Here is a comprehensive set of patterns for fixing common unsafe buffer issues. #### **1. Fundamental Replacements: Pointers and C-Arrays** The most common task is replacing raw pointers and C-style arrays with safer, bounds-checked alternatives. * **Pattern:** Replace function parameters `(T* ptr, size_t size)` with a single `base::span`. * **Example:** ```cpp // Old void ProcessData(const uint8_t* data, size_t size); // New void ProcessData(base::span data); ``` * **Pattern:** Replace C-style stack arrays `T arr[N]` with `std::array`. For string literals, `std::to_array` is a convenient helper. * **Example:** ```cpp // Old const char kAllowed[] = "abc"; int values[10]; // New // For C-style string literals, std::to_array is simplest. constexpr auto kAllowed = std::to_array("abc"); std::array values; ``` * **Pattern:** Replace raw heap-allocated arrays (`new T[size]`, `std::make_unique(size)`) with `std::vector` or `base::HeapArray`. * **Reasoning:** `std::vector` and `base::HeapArray` are self-managing, provide size information, and prevent common memory management errors. They also integrate perfectly with `base::span`. * **Example:** ```cpp // Old auto buffer = std::make_unique(1024); ReadData(fd, buffer.get(), 1024); // New std::vector buffer(1024); ReadData(fd, base::as_writable_byte_span(buffer)); ``` * **Pattern:** When passing an array to a function, use `base::span` to create a non-owning view. * **Example:** ```cpp std::array my_array; // Old: ProcessData(my_array.data(), my_array.size()); // New ProcessData(base::span(my_array)); ``` * **Pattern:** For class member fields that are non-owning views, you must use `base::raw_span` over `base::span`. * **Reasoning:** This is a critical memory safety requirement. `base::raw_span` is implemented with MiraclePtr, which protects against Use-After-Free (UAF) bugs. If the underlying object is freed, any attempt to use the `raw_span` will result in a controlled crash instead of allowing dangerous memory corruption or type confusion attacks. A regular `base::span` offers no UAF protection. ```cpp class MyClass { private: // Old: base::span data_; // New: base::raw_span data_; }; ``` #### **2. Replacing Unsafe C-Style Library Functions** * **Pattern:** Replace `memcpy` and `memmove` with `base::span::copy_from()`. * **Reasoning:** Do not use `std::ranges::copy`. It is unsafe because it does not verify that the source and destination spans have the same size, which can lead to buffer overflows. `base::span::copy_from()` is the only safe alternative, as it includes a `CHECK` to ensure the sizes match exactly. * **Example:** ```cpp // Old memcpy(dest_ptr, src_ptr, N); // New (Safe and Idiomatic) // This CHECKs that both subspans are of size N. dest_span.first(N).copy_from(src_span.first(N)); ``` * **Pattern:** Replace `memset` with `std::ranges::fill()`. * **Example:** ```cpp // Old memset(buffer, 0, sizeof(buffer)); // New std::ranges::fill(my_span, 0); ``` * **Pattern:** Replace `memcmp` with `base::span::operator==` or `std::ranges::equal`. * **Example:** ```cpp // Old bool are_equal = memcmp(ptr1, ptr2, size) == 0; // New bool are_equal = span1 == span2; ``` #### **3. Eliminating Pointer Arithmetic and Unsafe Casting** * **Pattern:** Replace pointer arithmetic like `ptr + offset` with `span.subspan(offset)`. * **Example:** ```cpp // Old ProcessData(data + 10, size - 10); // New ProcessData(data_span.subspan(10)); ``` * **Pattern:** Avoid `reinterpret_cast` for changing element types. Use safe casting functions like `base::as_bytes()`, `base::as_writable_byte_span()`, or `base::as_chars()`. * **Example:** ```cpp // Old const uint8_t* bytes = reinterpret_cast(str.data()); // New base::span bytes = base::as_byte_span(str); ``` * **Caution:** When using `base::as_byte_span()` on a `struct`, be aware of padding bytes. If the struct's padding is not explicitly initialized (e.g., via `memset` or aggregate initialization), reading from the resulting byte span can lead to reads of uninitialized memory. This is safest with spans of primitive types. * **Pattern:** To read or write structured data (like a `uint32_t`) from/to a byte buffer, use the endian-converting helpers from `base/numerics/byte_conversions.h`. * **Example (Writing):** ```cpp // Old (UNSAFE AND UNDEFINED BEHAVIOR) *reinterpret_cast(byte_span.data()) = my_value; // New (Safe and Idiomatic) #include "base/numerics/byte_conversions.h" auto value_bytes = base::U32ToLittleEndian(my_value); byte_span.first(value_bytes.size()).copy_from(value_bytes); ``` * **Example (Reading):** ```cpp // Old (UNSAFE) uint32_t value = *reinterpret_cast(byte_span.data()); // New (Safe and Idiomatic) #include "base/numerics/byte_conversions.h" uint32_t value = base::U32FromLittleEndian(byte_span.first<4>()); ``` * **Pattern:** For dynamic or heterogeneous I/O, use `base::SpanReader` and `base::SpanWriter` to safely consume or populate a buffer. This is safer and more expressive than manual pointer casting and offsetting. * **Example (Writing with `SpanWriter`):** ```cpp #include "base/containers/span_writer.h" #include "base/numerics/byte_conversions.h" void WriteData(base::span out, uint32_t id, float value) { auto writer = base::SpanWriter(out); writer.WriteU32BigEndian(id); writer.Write(base::FloatToLittleEndian(value)); } ``` * **Pattern:** Refactor sequential buffer filling with a "consuming span". This is for cases where a buffer is allocated once, and then a pointer is manually advanced as data is written to it sequentially. * **Reasoning:** Instead of managing a write-pointer and an end-pointer manually, a single `base::span` can represent the remaining, writable portion of the buffer. This is safer and more expressive. * **Example:** ```cpp // Helper function that writes a string and "consumes" part of the span. void WriteStringAndAdvance(base::span& buffer, const char* str) { if (!str) { return; } const size_t len_with_null = strlen(str) + 1; DCHECK_GE(buffer.size(), len_with_null); memcpy(buffer.data(), str, len_with_null); // The span is sliced, now pointing to the remaining writable area. buffer = buffer.subspan(len_with_null); } // Old function that manually manages pointers. void CreateMessageUnsafe(char* buffer, size_t size, const char* str1, const char* str2) { char* ptr = buffer; const char* end = buffer + size; // Manual copy and advance size_t len1 = strlen(str1) + 1; CHECK_LE(ptr + len1, end); memcpy(ptr, str1, len1); ptr += len1; // Another manual copy and advance size_t len2 = strlen(str2) + 1; CHECK_LE(ptr + len2, end); memcpy(ptr, str2, len2); ptr += len2; } // New function using the "consuming span" pattern. void CreateMessageSafe(base::span buffer, const char* str1, const char* str2) { WriteStringAndAdvance(buffer, str1); WriteStringAndAdvance(buffer, str2); // At this point, `buffer` correctly represents the unused portion. } ``` * **Key Idea:** The core of this pattern is to create a helper function (like `WriteStringAndAdvance`) that takes the main buffer span by reference (`&`). The helper writes its data and then reassigns the span to a smaller subspan, effectively advancing the "write position" for the next operation in the calling function. #### **4. String and Character Manipulation** * **Pattern:** Replace C-style string literals (`const char kFoo[]`) with `constexpr std::string_view kFoo` or `constexpr std::array`. * **Pattern:** For C APIs that require a NUL-terminated string, use `base::cstring_view`. * **Pattern:** Replace C-style string functions (`strcmp`, `strstr`, etc.) with `std::string_view` methods (`operator==`, `.find()`, etc.). * **Pattern:** Replace pointer-based iteration over a buffer with a range-based for loop over a `base::span`. * **Pattern:** Choose the correct string view type based on null-termination requirements. * **Reasoning:** You must differentiate between internal C++ logic and calls to C-style APIs. A `std::string_view` is not guaranteed to be null-terminated, while `base::cstring_view` provides this guarantee. Using the wrong type can lead to buffer over-reads. * **Decision Flow:** * If the string is only used with modern C++ methods (like `.find()` or range `for` loops) that use an explicit size, use `std::string_view`. * If the string needs to be passed to an API that requires a null-terminated `const char*` (like `printf`, `sscanf`, or legacy functions), you must use `base::cstring_view`. * **Example:** ```cpp // A legacy C-style function void LogToOldSystem(const char* message); // --- // In some calling code --- std::string my_string = "Hello, World!"; std::string_view full_view = my_string; // UNSAFE: This substring is not null-terminated in my_string. std::string_view unsafe_view = full_view.substr(7, 5); // "World" // LogToOldSystem(unsafe_view.data()); // BUG! Reads past "d" into garbage. // SAFE: Create a new std::string which is guaranteed to be null-terminated. std::string safe_string(unsafe_view); LogToOldSystem(safe_string.c_str()); // IDEAL: Use a type that enforces the contract. // If the source is already a C-string, cstring_view is zero-copy. base::cstring_view safe_c_view = "Hello, World!"; LogToOldSystem(safe_c_view.c_str()); ``` #### **5. Advanced Patterns** * **Pattern:** To get a heap-allocated buffer with a specific memory alignment, use `base::AlignedUninit` from `base/memory/aligned_memory.h`. ```cpp #include "base/memory/aligned_memory.h" // Get an uninitialized array of 16 floats, aligned to 32 bytes. base::AlignedHeapArray array = base::AlignedUninit(16, 32); ``` #### **6. Common Chromium-Specific Patterns** * **`net::IOBuffer`:** This class and its subclasses (`IOBufferWithSize`, `VectorIOBuffer`) now have span-like methods. Use them. * **Example:** ```cpp // Old auto data_view = base::span( reinterpret_cast(io_buffer->data()), data_len); // New auto data_view = io_buffer->first(data_len); ``` * **`net::VectorIOBuffer`:** To create a buffer with known content, prefer constructing a `net::VectorIOBuffer` directly from a `std::vector` or `base::span` instead of allocating a raw buffer and using `memcpy`. * **Example:** ```cpp // Old auto buffer = base::MakeRefCounted(data.size()); memcpy(buffer->data(), data.data(), data.size()); // New auto buffer = base::MakeRefCounted(data); ``` #### **7. Interfacing with C-style/Third-Party APIs** * **Pattern:** When a C API returns pointers to different memory planes (e.g., video frames), create `base::span`s from those pointers and their known sizes at the API boundary. Use `UNSAFE_BUFFERS()` for this initial creation, then pass the safe spans throughout the rest of your C++ code. * **Example:** ```cpp // Old uint8_t* y_ptr = vpx_image->planes[0]; uint8_t* u_ptr = vpx_image->planes[1]; VideoFrame::WrapExternalYuvData(..., y_ptr, u_ptr, ...); // New // SAFETY: libvpx guarantees these pointers and sizes are valid. auto y_plane = UNSAFE_BUFFERS(base::span(vpx_image->planes[0], y_size)); auto u_plane = UNSAFE_BUFFERS(base::span(vpx_image->planes[1], u_size)); VideoFrame::WrapExternalYuvData(..., y_plane, u_plane, ...); ``` #### **8. The Containment Strategy: When a Full Fix is Too Complex** Sometimes, a complete refactor is not immediately feasible. In these cases, contain the unsafe operations. * **Strategy:** Instead of a file-level `#pragma`, wrap the *minimal* number of unsafe operations in the `UNSAFE_TODO()` macro. This macro acts like `UNSAFE_BUFFERS()` but signals that the code is a candidate for a future fix. * **Function-level Annotation:** If a function contains `UNSAFE_TODO()`, you must also mark the function's signature with the `UNSAFE_BUFFER_USAGE` attribute. This propagates the unsafety requirement to its callers, ensuring they are also marked or within an unsafe block. * **Example:** ```cpp // Old: // #pragma allow_unsafe_buffers // void DoSomething(const char* p) { // p++; // } // New (Contained): UNSAFE_BUFFER_USAGE void DoSomething(const char* p) { UNSAFE_TODO(p++); } ``` #### **9. Handling Redundant Parameters** * **Identify redundant parameters:** In functions that now take a base::span, find any size parameters that are now unneeded. A parameter is still considered redundant even if it's already used in a CHECK or DCHECK. * **Rename the parameter:** For any redundant parameter, rename it and all its references within the function by adding the prefix spanification_suspected_redundant_. * **Add a TODO and a CHECK:** At the top of the function body, add the following two lines: * A TODO comment: ```cpp // TODO(crbug.com/431824301): Remove unneeded parameter once validated to be redundant in M143. ``` * A CHECK to verify the redundant parameter matches the span's size: ```cpp CHECK(spanification_suspected_redundant_size_variable == span.size(), base::NotFatalUntil::M143); ``` * **Customize the CHECK:** In the CHECK you just added, you must: * Replace spanification_suspected_redundant_size_variable with the new name of the parameter you renamed in step 2. * Replace span.size() with a call to the actual base::span parameter's .size() method. * **Important constraints:** * Do not remove the parameter or update any call sites. * Do not change the function's logic to use span.size(); continue to use the newly-renamed parameter variable. * Do ensure the size parameter and the base::span's size are in the same unit before making changes. * Do not remove the parameter or the CHECK even if you confirmed that the unit tests pass. #### **10. Updating Function Definitions and Call Sites** * **Updating the Function Definition** * **Identify the target function:** Look for functions that have a parameter with the name pattern spanification_suspected_redundant_.... * **Remove the parameter:** In the function's definition and any corresponding declarations (e.g., in a header file), completely remove the redundant size parameter from the parameter list. * **Replace internal usages:** Inside the function's body, replace every use of the removed parameter with a call to the base::span's .size() method (e.g., my_span.size()). * **Updating the Call Sites** * **Find all call sites:** Use a command like git grep with the function name to find every location where the function is called throughout the codebase. * **Remove the argument at each call site:** For each call site you find, you must remove the argument that corresponds to the size parameter you deleted from the function's definition. * **Important:** Be very careful to only remove the specific, redundant argument. Do not change or remove any other arguments in the function call. * **Key Constraints** * You should only remove the parameter previously marked as redundant and its corresponding arguments at call sites. * Do not remove or rename any other parameters. * Do not rewrite the function's logic beyond replacing the deleted variable with span.size(). * Ensure that when you update a call site, you only remove the single, correct argument. #### **11. Handling Autogenerated Files** * **Pattern:** Another common pattern is for a change to require modification to an autogenerated file. Treat autogenerated files as unmodifiable for now. --- #### **12. Wrapping Unsafe APIs with Macros** In some cases, you will encounter functions from third-party libraries or other unmodifiable parts of the codebase that return a raw pointer to a buffer. Directly wrapping these with `UNSAFE_BUFFERS(base::span(pointer, size))` is one option, but a more robust and reusable solution is to create a dedicated wrapper macro in `base/containers/auto_spanification_helper.h`. * **Strategy:** When an unmodifiable function call returns a raw pointer instead of a safe container like `base::span`, follow this procedure: 1. **Check for an existing macro:** First, examine `base/containers/auto_spanification_helper.h` to see if a macro for this specific API call already exists. 2. **Create a new macro if needed:** If no macro exists, you must add one. * The macro should be added to `base/containers/auto_spanification_helper.h`. * The macro should take the same arguments as the original API call. * Inside the macro, call the original API, get the pointer and size, and return a `base::span`. Use `UNSAFE_TODO` to wrap the returned span. * Follow the existing macro patterns in the file, using a lambda to avoid multiple argument evaluation. 3. **Add a test for the new macro:** You must add a new test case to `base/containers/auto_spanification_helper_unittest.cc`. * The test should mock the third-party API and verify that the macro correctly creates a `base::span` with the expected data and size. 4. **Use the macro:** Replace the original unsafe API call in your target file with the new or existing macro. * **Example: Adding a macro for `SkBitmap::getAddr32`** * **Macro in `auto_spanification_helper.h`:** ```cpp // https://source.chromium.org/chromium/chromium/src/+/main:third_party/skia/include/core/SkBitmap.h;drc=f72bd467feb15edd9323e46eab1b74ab6025bc5b;l=936 #define UNSAFE_SKBITMAP_GETADDR32(arg_self, arg_x, arg_y) \ ([](auto&& self, int x, int y) { \ uint32_t* row = self->getAddr32(x, y); \ ::base::CheckedNumeric width = self->width(); \ size_t size = (width - x).ValueOrDie(); \ return UNSAFE_TODO(base::span(row, size)); \ }(::base::spanification_internal::ToPointer(arg_self), arg_x, arg_y)) ``` * **Test in `auto_spanification_helper_unittest.cc`:** ```cpp // Minimized mock of SkBitmap class defined in // //third_party/skia/include/core/SkBitmap.h class SkBitmap { public: uint32_t* getAddr32(int x, int y) const { return &row_[x]; } int width() const { return static_cast(row_.size()); } mutable std::array row_{}; }; TEST(AutoSpanificationHelperTest, SkBitmapGetAddr32Pointer) { SkBitmap sk_bitmap; const int x = 123; base::span span = UNSAFE_SKBITMAP_GETADDR32(&sk_bitmap, x, 0); EXPECT_EQ(span.data(), &sk_bitmap.row_[x]); EXPECT_EQ(span.size(), sk_bitmap.row_.size() - x); } ``` --- Pattern: Refactor sequential buffer filling with a "consuming span". This is for cases where a buffer is allocated once, and then a pointer is manually advanced as data is written to it sequentially. Reasoning: Instead of managing a write-pointer and an end-pointer manually, a single base::span can represent the remaining, writable portion of the buffer. This is safer and more expressive. Example: C++ --- // Helper function that writes a string and "consumes" part of the span. void WriteStringAndAdvance(base::span& buffer, const char* str) { if (!str) { return; } const size_t len_with_null = strlen(str) + 1; DCHECK_GE(buffer.size(), len_with_null); memcpy(buffer.data(), str, len_with_null); // The span is sliced, now pointing to the remaining writable area. buffer = buffer.subspan(len_with_null); } // Old function that manually manages pointers. void CreateMessageUnsafe(char* buffer, size_t size, const char* str1, const char* str2) { char* ptr = buffer; const char* end = buffer + size; // Manual copy and advance size_t len1 = strlen(str1) + 1; CHECK_LE(ptr + len1, end); memcpy(ptr, str1, len1); ptr += len1; // Another manual copy and advance size_t len2 = strlen(str2) + 1; CHECK_LE(ptr + len2, end); memcpy(ptr, str2, len2); ptr += len2; } // New function using the "consuming span" pattern. void CreateMessageSafe(base::span buffer, const char* str1, const char* str2) { WriteStringAndAdvance(buffer, str1); WriteStringAndAdvance(buffer, str2); // At this point, `buffer` correctly represents the unused portion. } Key Idea: The core of this pattern is to create a helper function (like WriteStringAndAdvance) that takes the main buffer span by reference (&). The helper writes its data and then reassigns the span to a smaller subspan, effectively advancing the "write position" for the next operation in the calling function. ---