===========================
libunwind README for Chapel
===========================

This copy of libunwind is being released with Chapel for
convenience and was obtained from:

  https://github.com/libunwind/libunwind/

Any Chapel issues that seem to be related to libunwind should be
directed to the Chapel team at https://chapel-lang.org/bugs.html.

Chapel modifications to libunwind
=================================

Avoid issue with GCC 15. This is a simple patch, the full PR is
https://github.com/libunwind/libunwind/pull/831. When that is included in a
release this patch will no longer be needed.

```
--- a/libunwind-src/tests/Gtest-nomalloc.c
+++ b/libunwind-src/tests/Gtest-nomalloc.c
@@ -37,10 +37,10 @@ int in_unwind;
 void *
 malloc(size_t s)
 {
-  static void * (*func)();
+  static void * (*func)(size_t);
 
   if(!func)
-    func = (void *(*)()) dlsym(RTLD_NEXT, "malloc");
+    func = (void *(*)(size_t)) dlsym(RTLD_NEXT, "malloc");
 
   if (in_unwind) {
     num_errors++;
```

Avoid issue with valgrind: https://github.com/libunwind/libunwind/pull/795

```
--- a/src/mi/Gaddress_validator.c
+++ b/src/mi/Gaddress_validator.c
@@ -242,7 +242,8 @@ _cache_valid_mem(unw_word_t page_addr)
  * Validates the memory range from @p addr to (@p addr + @p len - 1) is
  * readable.  Since the granularity of memory readability is the page, only one
  * byte needs to be validated per page for each page starting at @p addr and
- * encompassing @p len bytes. Only the first address of each page is checked.
+ * encompassing @p len bytes. Only the starting address of the memory range and
+ * the first address of each additional page is checked.
  *
  * @returns true if the memory is readable, false otherwise.
  */
@@ -288,7 +289,8 @@ unw_address_is_valid(unw_word_t addr, size_t len)
     {
       if (!_is_cached_valid_mem(page_addr))
         {
-          if (!_write_validate (page_addr))
+          /* Check 'addr' in first page to avoid uninitialized memory access. */
+          if (!_write_validate ((page_addr == start_page_addr) ? addr : page_addr))
             {
               Debug(1, "returning false\n");
               return false;
```

Upgrading libunwind versions
========================

The directory $CHPL_HOME/third-party/libunwind/libunwind-src/ contains the
un-tarballed libunwind package contents. Version updates should be done as
follows, assuming the CWD is $CHPL_HOME/third-party/libunwind/:

1. `wget https://github.com/libunwind/libunwind/releases/download/v1.8.3/libunwind-1.8.3.tar.gz && tar xf libunwind-1.8.3.tar.gz`
2. `rm -rf libunwind-src`
3. `mv libunwind-1.8.3 libunwind-src`
4. Validate and apply any patches listed above
5. `git add --force libunwind-src` (--force to ignore our .gitignore)
6. update the version number mentioned above
7. make sure these instructions are up to date :)
8. commit, PR, merge, etc
