From: Julien Grall <jgrall@amazon.com>

It is not very clear the shared page adddress is not contained in the
connection record. Additionally, it is misleading to say the grant
will always point to the share paged as a domain is free to revoke the
permission. The restore code would need to make sure it doesn't
fail/crash if this is happening.

The sentence is now replaced with a paragraph explaining why the GFN is
not preserved and that the grant is not guarantee to exist during
restore.

Take the opportunity to replace "code" with "node" when description the
permission.

Reported-by: Raphael Ning <raphning@amazon.com>
Signed-off-by: Julien Grall <jgrall@amazon.com>

---
Cc: raphning@gmail.com
Cc: edvin.torok@citrix.com
Cc: jgross@suse.com

Ian, would you still consider documentation update for 4.15?
---
 docs/designs/xenstore-migration.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/designs/xenstore-migration.md b/docs/designs/xenstore-migration.md
index 1a5b94b31da8..5f1155273ec3 100644
--- a/docs/designs/xenstore-migration.md
+++ b/docs/designs/xenstore-migration.md
@@ -216,8 +216,10 @@ For `shared ring` connections it is as follows:
 |           | by xenstored to communicate with `domid`          |
 |           |                                                   |
 
-Since the ABI guarantees that entry 1 in `domid`'s grant table will always
-contain the GFN of the shared page.
+The GFN of the shared page is not preserved because the ABI reserves
+entry 1 in `domid`'s grant table to point to the xenstore shared page.
+Note there is no guarantee the page will still be valid at the time of
+the restore because a domain can revoke the permission.
 
 For `socket` connections it is as follows:
 
@@ -398,7 +400,7 @@ A node permission specifier has the following format:
 |         |                                                     |
 | `domid` | The domain-id to which the permission relates       |
 
-Note that perm1 defines the domain owning the code. See [4] for more
+Note that perm1 defines the domain owning the node. See [4] for more
 explanation of node permissions.
 
 * * *
-- 
2.17.1

On 25.03.21 12:12, Julien Grall wrote:
> From: Julien Grall <jgrall@amazon.com>
> 
> It is not very clear the shared page adddress is not contained in the
> connection record. Additionally, it is misleading to say the grant
> will always point to the share paged as a domain is free to revoke the
> permission. The restore code would need to make sure it doesn't
> fail/crash if this is happening.
> 
> The sentence is now replaced with a paragraph explaining why the GFN is
> not preserved and that the grant is not guarantee to exist during
> restore.
> 
> Take the opportunity to replace "code" with "node" when description the
> permission.
> 
> Reported-by: Raphael Ning <raphning@amazon.com>
> Signed-off-by: Julien Grall <jgrall@amazon.com>

Reviewed-by: Juergen Gross <jgross@suse.com>


Juergen

Julien Grall writes ("[PATCH for-4.15?] docs/design: Update xenstore-migration.md"):
> From: Julien Grall <jgrall@amazon.com>
> 
> It is not very clear the shared page adddress is not contained in the
> connection record. Additionally, it is misleading to say the grant
> will always point to the share paged as a domain is free to revoke the
> permission. The restore code would need to make sure it doesn't
> fail/crash if this is happening.
> 
> The sentence is now replaced with a paragraph explaining why the GFN is
> not preserved and that the grant is not guarantee to exist during
> restore.
> 
> Take the opportunity to replace "code" with "node" when description the
> permission.
> 
> Reported-by: Raphael Ning <raphning@amazon.com>
> Signed-off-by: Julien Grall <jgrall@amazon.com>

Release-Acked-by: Ian Jackson <iwj@xenproject.org>

Hi Ian,

On 26/03/2021 12:06, Ian Jackson wrote:
> Julien Grall writes ("[PATCH for-4.15?] docs/design: Update xenstore-migration.md"):
>> From: Julien Grall <jgrall@amazon.com>
>>
>> It is not very clear the shared page adddress is not contained in the
>> connection record. Additionally, it is misleading to say the grant
>> will always point to the share paged as a domain is free to revoke the
>> permission. The restore code would need to make sure it doesn't
>> fail/crash if this is happening.
>>
>> The sentence is now replaced with a paragraph explaining why the GFN is
>> not preserved and that the grant is not guarantee to exist during
>> restore.
>>
>> Take the opportunity to replace "code" with "node" when description the
>> permission.
>>
>> Reported-by: Raphael Ning <raphning@amazon.com>
>> Signed-off-by: Julien Grall <jgrall@amazon.com>
> 
> Release-Acked-by: Ian Jackson <iwj@xenproject.org>

Thanks! I have committed the patch to staging and cherry-pick in 
staging-4.15.

Cheers,

-- 
Julien Grall