6 files changed, 51 insertions, 10 deletions
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 33e8c11..fb6421e 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -47,7 +47,7 @@ copyright = u'2012-2018, Armin Rigo, Maciej Fijalkowski'
 # The short X.Y version.
 version = '1.15'
 # The full version, including alpha/beta/rc tags.
-release = '1.15.0'
+release = '1.15.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 6d55eb5..4859c83 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -52,13 +52,13 @@ Download and Installation:
 
 * https://pypi.python.org/pypi/cffi
 
-* Checksums of the "source" package version 1.15.0:
+* Checksums of the "source" package version 1.15.1:
 
-   - MD5: f3a3f26cd3335fc597479c9475da0a0b
+   - MD5: ...
 
-   - SHA1: 9c51c29e35510adf7f94542e1f8e05611930b07b
+   - SHA1: ...
 
-   - SHA256: 920f0d66a896c2d99f0adbb391f990a84091179542c205fa53ce5787aff87954
+   - SHA256: ...
 
 * Or grab the most current version from the `Heptapod page`_:
   ``hg clone https://foss.heptapod.net/pypy/cffi``
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
index dbc3540..3de8a3f 100644
--- a/doc/source/overview.rst
+++ b/doc/source/overview.rst
@@ -15,7 +15,12 @@ two sections delve deeper in the CFFI library.
 
 Make sure you have `cffi installed`__.
 
+You can find these and some other complete demos in the demo__ directory
+of the repository__.
+
 .. __: installation.html
+.. __: https://foss.heptapod.net/pypy/cffi/-/tree/branch/default/demo
+.. __: https://foss.heptapod.net/pypy/cffi
 
 .. _out-of-line-api-level:
 .. _real-example:
diff --git a/doc/source/ref.rst b/doc/source/ref.rst
index 05c0f7c..946e48c 100644
--- a/doc/source/ref.rst
+++ b/doc/source/ref.rst
@@ -846,20 +846,35 @@ allowed.
    argument is identical to a ``item[]`` argument (and ``ffi.cdef()``
    doesn't record the difference).  So when you call such a function,
    you can pass an argument that is accepted by either C type, like
-   for example passing a Python string to a ``char *`` argument
+   for example passing a Python byte string to a ``char *`` argument
    (because it works for ``char[]`` arguments) or a list of integers
    to a ``int *`` argument (it works for ``int[]`` arguments).  Note
    that even if you want to pass a single ``item``, you need to
    specify it in a list of length 1; for example, a ``struct point_s
    *`` argument might be passed as ``[[x, y]]`` or ``[{'x': 5, 'y':
-   10}]``.
+   10}]``.  In all these cases (including passing a byte string to
+   a ``char *`` argument), the required C data structure is created
+   just before the call is done, and freed afterwards.
 
    As an optimization, CFFI assumes that a
-   function with a ``char *`` argument to which you pass a Python
+   function with a ``char *`` argument to which you pass a Python byte
    string will not actually modify the array of characters passed in,
-   and so passes directly a pointer inside the Python string object.
+   and so it attempts to pass directly a pointer inside the Python
+   byte string object.  This still doesn't mean that the ``char *``
+   argument can be stored by the C function and inspected later.
+   The ``char *`` is only valid for the duration of the call, even if
+   the Python object is kept alive for longer.
    (On PyPy, this optimization is only available since PyPy 5.4
-   with CFFI 1.8.)
+   with CFFI 1.8.  It may fail in rare cases and fall back to making
+   a copy anyway, but only for short strings so it shouldn't be
+   noticeable.)
+
+   If you need to pass a ``char *`` that must be valid for longer than
+   just the call, you need to build it explicitly, either with ``p =
+   ffi.new("char[]", mystring)`` (which makes a copy) or by not using a
+   byte string in the first place but something else like a buffer object,
+   or a bytearray and ``ffi.from_buffer()``; or just use
+   ``ffi.new("char[]", length)`` directly if possible.
 
 `[2]` C function calls are done with the GIL released.
 
diff --git a/doc/source/using.rst b/doc/source/using.rst
index 38c96ba..ccaa4db 100644
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -383,6 +383,18 @@ argument and may mutate it!):
 
     assert lib.strlen("hello") == 5
 
+(Note that there is no guarantee that the ``char *`` passed to the
+function remains valid after the call is done.  Similarly, if you write
+``lib.f(x); lib.f(x)`` where ``x`` is a variable containing a byte string,
+the two calls to ``f()`` could sometimes receive different ``char *``
+pointers, with each of them only valid during the corresponding call.  This is
+important notably for PyPy which uses many optimizations tweaking the data
+underlying a byte string object.  CFFI will not make and free a copy of
+the whole string at *every* call---it usually won't---but you *cannot*
+write code that relies on it: there are cases were that would break.
+If you need a pointer to remain valid, you need to make one explicitly,
+for example with ``ptr = ffi.new("char[]", x)``.)
+
 You can also pass unicode strings as ``wchar_t *`` or ``char16_t *`` or
 ``char32_t *`` arguments.  Note that
 the C language makes no difference between argument declarations that
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
index aa7f2fe..ff2b7ba 100644
--- a/doc/source/whatsnew.rst
+++ b/doc/source/whatsnew.rst
@@ -2,6 +2,15 @@
 What's New
 ======================
 
+v1.15.1
+=======
+
+* If you call `ffi.embedding_api()` but don't write any `extern "Python"`
+  function there, then the resulting C code would fail an assert.  Fixed.
+
+* Updated Windows/arm64 embedded libffi static lib to v3.4.2, and scripted
+  to ease future updates (thanks Niyas Sait!)
+
 v1.15.0
 =======