Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-21 19:41:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

XArray: Document the locking requirement for the xa_state

Browse Source 
It wasn't obvious to all readers that it's unsafe to reuse an xa_state
after dropping the xas_lock() or the rcu_read_lock().

Reported-by: Charan Teja Kalla <charante@codeaurora.org>
Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
This commit is contained in:
Matthew Wilcox (Oracle) 2021-12-13 23:03:54 -05:00
parent 1f2cfdd349
commit ac23d1a964
1 changed files with 9 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
Documentation/core-api/xarray.rst
View File

@ -315,11 +315,15 @@ indeed the normal API is implemented in terms of the advanced API. The
advanced API is only available to modules with a GPL-compatible license. advanced API is only available to modules with a GPL-compatible license.
The advanced API is based around the xa_state. This is an opaque data The advanced API is based around the xa_state. This is an opaque data
structure which you declare on the stack using the XA_STATE() structure which you declare on the stack using the XA_STATE() macro.
macro. This macro initialises the xa_state ready to start walking This macro initialises the xa_state ready to start walking around the
around the XArray. It is used as a cursor to maintain the position XArray. It is used as a cursor to maintain the position in the XArray
in the XArray and let you compose various operations together without and let you compose various operations together without having to restart
having to restart from the top every time. from the top every time. The contents of the xa_state are protected by
the rcu_read_lock() or the xas_lock(). If you need to drop whichever of
those locks is protecting your state and tree, you must call xas_pause()
so that future calls do not rely on the parts of the state which were
left unprotected.
The xa_state is also used to store errors. You can call The xa_state is also used to store errors. You can call
xas_error() to retrieve the error. All operations check whether xas_error() to retrieve the error. All operations check whether