€•
Å      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ./translations/zh_CN/process/botching-up-ioctls”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/zh_TW/process/botching-up-ioctls”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/it_IT/process/botching-up-ioctls”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/ja_JP/process/botching-up-ioctls”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/ko_KR/process/botching-up-ioctls”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/pt_BR/process/botching-up-ioctls”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/sp_SP/process/botching-up-ioctls”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ!(How to avoid) Botching up ioctls”h]”hŒ!(How to avoid) Botching up ioctls”…””}”(hh¼h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhh·h²hh³ŒH/var/lib/git/docbuild/linux/Documentation/process/botching-up-ioctls.rst”h´KubhŒ	paragraph”“”)”}”(hŒ;From: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html”h]”(hŒFrom: ”…””}”(hhÍh²hh³Nh´NubhŒ	reference”“”)”}”(hŒ5https://blog.ffwll.ch/2013/11/botching-up-ioctls.html”h]”hŒ5https://blog.ffwll.ch/2013/11/botching-up-ioctls.html”…””}”(hh×h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”hÙuh1hÕhhÍubeh}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khh·h²hubhÌ)”}”(hŒ6By: Daniel Vetter, Copyright Â© 2013 Intel Corporation”h]”hŒ6By: Daniel Vetter, Copyright Â© 2013 Intel Corporation”…””}”(hhìh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khh·h²hubhÌ)”}”(hX÷  One clear insight kernel graphics hackers gained in the past few years is that
trying to come up with a unified interface to manage the execution units and
memory on completely different GPUs is a futile effort. So nowadays every
driver has its own set of ioctls to allocate memory and submit work to the GPU.
Which is nice, since there's no more insanity in the form of fake-generic, but
actually only used once interfaces. But the clear downside is that there's much
more potential to screw things up.”h]”hXû  One clear insight kernel graphics hackers gained in the past few years is that
trying to come up with a unified interface to manage the execution units and
memory on completely different GPUs is a futile effort. So nowadays every
driver has its own set of ioctls to allocate memory and submit work to the GPU.
Which is nice, since thereâ€™s no more insanity in the form of fake-generic, but
actually only used once interfaces. But the clear downside is that thereâ€™s much
more potential to screw things up.”…””}”(hhúh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K	hh·h²hubhÌ)”}”(hXf  To avoid repeating all the same mistakes again I've written up some of the
lessons learned while botching the job for the drm/i915 driver. Most of these
only cover technicalities and not the big-picture issues like what the command
submission ioctl exactly should look like. Learning these lessons is probably
something every GPU driver has to do on its own.”h]”hXh  To avoid repeating all the same mistakes again Iâ€™ve written up some of the
lessons learned while botching the job for the drm/i915 driver. Most of these
only cover technicalities and not the big-picture issues like what the command
submission ioctl exactly should look like. Learning these lessons is probably
something every GPU driver has to do on its own.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khh·h²hubh¶)”}”(hhh]”(h»)”}”(hŒPrerequisites”h]”hŒPrerequisites”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj  h²hh³hÊh´KubhÌ)”}”(hŒsFirst the prerequisites. Without these you have already failed, because you
will need to add a 32-bit compat layer:”h]”hŒsFirst the prerequisites. Without these you have already failed, because you
will need to add a 32-bit compat layer:”…””}”(hj'  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Khj  h²hubhŒblock_quote”“”)”}”(hXT  * Only use fixed sized integers. To avoid conflicts with typedefs in userspace
  the kernel has special types like __u32, __s64. Use them.

* Align everything to the natural size and use explicit padding. 32-bit
  platforms don't necessarily align 64-bit values to 64-bit boundaries, but
  64-bit platforms do. So we always need padding to the natural size to get
  this right.

* Pad the entire struct to a multiple of 64-bits if the structure contains
  64-bit types - the structure size will otherwise differ on 32-bit versus
  64-bit. Having a different structure size hurts when passing arrays of
  structures to the kernel, or if the kernel checks the structure size, which
  e.g. the drm core does.

* Pointers are __u64, cast from/to a uintptr_t on the userspace side and
  from/to a void __user * in the kernel. Try really hard not to delay this
  conversion or worse, fiddle the raw __u64 through your code since that
  diminishes the checking tools like sparse can provide. The macro
  u64_to_user_ptr can be used in the kernel to avoid warnings about integers
  and pointers of different sizes.

”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ‡Only use fixed sized integers. To avoid conflicts with typedefs in userspace
the kernel has special types like __u32, __s64. Use them.
”h]”hÌ)”}”(hŒ†Only use fixed sized integers. To avoid conflicts with typedefs in userspace
the kernel has special types like __u32, __s64. Use them.”h]”hŒ†Only use fixed sized integers. To avoid conflicts with typedefs in userspace
the kernel has special types like __u32, __s64. Use them.”…””}”(hjF  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KhjB  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj=  ubjA  )”}”(hŒæAlign everything to the natural size and use explicit padding. 32-bit
platforms don't necessarily align 64-bit values to 64-bit boundaries, but
64-bit platforms do. So we always need padding to the natural size to get
this right.
”h]”hÌ)”}”(hŒåAlign everything to the natural size and use explicit padding. 32-bit
platforms don't necessarily align 64-bit values to 64-bit boundaries, but
64-bit platforms do. So we always need padding to the natural size to get
this right.”h]”hŒçAlign everything to the natural size and use explicit padding. 32-bit
platforms donâ€™t necessarily align 64-bit values to 64-bit boundaries, but
64-bit platforms do. So we always need padding to the natural size to get
this right.”…””}”(hj^  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K!hjZ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj=  ubjA  )”}”(hX=  Pad the entire struct to a multiple of 64-bits if the structure contains
64-bit types - the structure size will otherwise differ on 32-bit versus
64-bit. Having a different structure size hurts when passing arrays of
structures to the kernel, or if the kernel checks the structure size, which
e.g. the drm core does.
”h]”hÌ)”}”(hX<  Pad the entire struct to a multiple of 64-bits if the structure contains
64-bit types - the structure size will otherwise differ on 32-bit versus
64-bit. Having a different structure size hurts when passing arrays of
structures to the kernel, or if the kernel checks the structure size, which
e.g. the drm core does.”h]”hX<  Pad the entire struct to a multiple of 64-bits if the structure contains
64-bit types - the structure size will otherwise differ on 32-bit versus
64-bit. Having a different structure size hurts when passing arrays of
structures to the kernel, or if the kernel checks the structure size, which
e.g. the drm core does.”…””}”(hjv  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K&hjr  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj=  ubjA  )”}”(hX…  Pointers are __u64, cast from/to a uintptr_t on the userspace side and
from/to a void __user * in the kernel. Try really hard not to delay this
conversion or worse, fiddle the raw __u64 through your code since that
diminishes the checking tools like sparse can provide. The macro
u64_to_user_ptr can be used in the kernel to avoid warnings about integers
and pointers of different sizes.

”h]”hÌ)”}”(hXƒ  Pointers are __u64, cast from/to a uintptr_t on the userspace side and
from/to a void __user * in the kernel. Try really hard not to delay this
conversion or worse, fiddle the raw __u64 through your code since that
diminishes the checking tools like sparse can provide. The macro
u64_to_user_ptr can be used in the kernel to avoid warnings about integers
and pointers of different sizes.”h]”hXƒ  Pointers are __u64, cast from/to a uintptr_t on the userspace side and
from/to a void __user * in the kernel. Try really hard not to delay this
conversion or worse, fiddle the raw __u64 through your code since that
diminishes the checking tools like sparse can provide. The macro
u64_to_user_ptr can be used in the kernel to avoid warnings about integers
and pointers of different sizes.”…””}”(hjŽ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K,hjŠ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj=  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1j;  h³hÊh´Khj7  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j5  h³hÊh´Khj  h²hubeh}”(h]”Œprerequisites”ah ]”h"]”Œprerequisites”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒBasics”h]”hŒBasics”…””}”(hj»  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj¸  h²hh³hÊh´K5ubhÌ)”}”(hX8  With the joys of writing a compat layer avoided we can take a look at the basic
fumbles. Neglecting these will make backward and forward compatibility a real
pain. And since getting things wrong on the first attempt is guaranteed you
will have a second iteration or at least an extension for any given interface.”h]”hX8  With the joys of writing a compat layer avoided we can take a look at the basic
fumbles. Neglecting these will make backward and forward compatibility a real
pain. And since getting things wrong on the first attempt is guaranteed you
will have a second iteration or at least an extension for any given interface.”…””}”(hjÉ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K7hj¸  h²hubj6  )”}”(hXE  * Have a clear way for userspace to figure out whether your new ioctl or ioctl
  extension is supported on a given kernel. If you can't rely on old kernels
  rejecting the new flags/modes or ioctls (since doing that was botched in the
  past) then you need a driver feature flag or revision number somewhere.

* Have a plan for extending ioctls with new flags or new fields at the end of
  the structure. The drm core checks the passed-in size for each ioctl call
  and zero-extends any mismatches between kernel and userspace. That helps,
  but isn't a complete solution since newer userspace on older kernels won't
  notice that the newly added fields at the end get ignored. So this still
  needs a new driver feature flags.

* Check all unused fields and flags and all the padding for whether it's 0,
  and reject the ioctl if that's not the case. Otherwise your nice plan for
  future extensions is going right down the gutters since someone will submit
  an ioctl struct with random stack garbage in the yet unused parts. Which
  then bakes in the ABI that those fields can never be used for anything else
  but garbage. This is also the reason why you must explicitly pad all
  structures, even if you never use them in an array - the padding the compiler
  might insert could contain garbage.

* Have simple testcases for all of the above.

”h]”j<  )”}”(hhh]”(jA  )”}”(hX-  Have a clear way for userspace to figure out whether your new ioctl or ioctl
extension is supported on a given kernel. If you can't rely on old kernels
rejecting the new flags/modes or ioctls (since doing that was botched in the
past) then you need a driver feature flag or revision number somewhere.
”h]”hÌ)”}”(hX,  Have a clear way for userspace to figure out whether your new ioctl or ioctl
extension is supported on a given kernel. If you can't rely on old kernels
rejecting the new flags/modes or ioctls (since doing that was botched in the
past) then you need a driver feature flag or revision number somewhere.”h]”hX.  Have a clear way for userspace to figure out whether your new ioctl or ioctl
extension is supported on a given kernel. If you canâ€™t rely on old kernels
rejecting the new flags/modes or ioctls (since doing that was botched in the
past) then you need a driver feature flag or revision number somewhere.”…””}”(hjâ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K<hjÞ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hjÛ  ubjA  )”}”(hX–  Have a plan for extending ioctls with new flags or new fields at the end of
the structure. The drm core checks the passed-in size for each ioctl call
and zero-extends any mismatches between kernel and userspace. That helps,
but isn't a complete solution since newer userspace on older kernels won't
notice that the newly added fields at the end get ignored. So this still
needs a new driver feature flags.
”h]”hÌ)”}”(hX•  Have a plan for extending ioctls with new flags or new fields at the end of
the structure. The drm core checks the passed-in size for each ioctl call
and zero-extends any mismatches between kernel and userspace. That helps,
but isn't a complete solution since newer userspace on older kernels won't
notice that the newly added fields at the end get ignored. So this still
needs a new driver feature flags.”h]”hX™  Have a plan for extending ioctls with new flags or new fields at the end of
the structure. The drm core checks the passed-in size for each ioctl call
and zero-extends any mismatches between kernel and userspace. That helps,
but isnâ€™t a complete solution since newer userspace on older kernels wonâ€™t
notice that the newly added fields at the end get ignored. So this still
needs a new driver feature flags.”…””}”(hjú  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KAhjö  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hjÛ  ubjA  )”}”(hX,  Check all unused fields and flags and all the padding for whether it's 0,
and reject the ioctl if that's not the case. Otherwise your nice plan for
future extensions is going right down the gutters since someone will submit
an ioctl struct with random stack garbage in the yet unused parts. Which
then bakes in the ABI that those fields can never be used for anything else
but garbage. This is also the reason why you must explicitly pad all
structures, even if you never use them in an array - the padding the compiler
might insert could contain garbage.
”h]”hÌ)”}”(hX+  Check all unused fields and flags and all the padding for whether it's 0,
and reject the ioctl if that's not the case. Otherwise your nice plan for
future extensions is going right down the gutters since someone will submit
an ioctl struct with random stack garbage in the yet unused parts. Which
then bakes in the ABI that those fields can never be used for anything else
but garbage. This is also the reason why you must explicitly pad all
structures, even if you never use them in an array - the padding the compiler
might insert could contain garbage.”h]”hX/  Check all unused fields and flags and all the padding for whether itâ€™s 0,
and reject the ioctl if thatâ€™s not the case. Otherwise your nice plan for
future extensions is going right down the gutters since someone will submit
an ioctl struct with random stack garbage in the yet unused parts. Which
then bakes in the ABI that those fields can never be used for anything else
but garbage. This is also the reason why you must explicitly pad all
structures, even if you never use them in an array - the padding the compiler
might insert could contain garbage.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KHhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hjÛ  ubjA  )”}”(hŒ-Have simple testcases for all of the above.

”h]”hÌ)”}”(hŒ+Have simple testcases for all of the above.”h]”hŒ+Have simple testcases for all of the above.”…””}”(hj*  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KQhj&  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hjÛ  ubeh}”(h]”h ]”h"]”h$]”h&]”j¨  j©  uh1j;  h³hÊh´K<hj×  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j5  h³hÊh´K<hj¸  h²hubeh}”(h]”Œbasics”ah ]”h"]”Œbasics”ah$]”h&]”uh1hµhh·h²hh³hÊh´K5ubh¶)”}”(hhh]”(h»)”}”(hŒFun with Error Paths”h]”hŒFun with Error Paths”…””}”(hjU  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjR  h²hh³hÊh´KUubhÌ)”}”(hŒìNowadays we don't have any excuse left any more for drm drivers being neat
little root exploits. This means we both need full input validation and solid
error handling paths - GPUs will die eventually in the oddmost corner cases
anyway:”h]”hŒîNowadays we donâ€™t have any excuse left any more for drm drivers being neat
little root exploits. This means we both need full input validation and solid
error handling paths - GPUs will die eventually in the oddmost corner cases
anyway:”…””}”(hjc  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KWhjR  h²hubj6  )”}”(hX–  * The ioctl must check for array overflows. Also it needs to check for
  over/underflows and clamping issues of integer values in general. The usual
  example is sprite positioning values fed directly into the hardware with the
  hardware just having 12 bits or so. Works nicely until some odd display
  server doesn't bother with clamping itself and the cursor wraps around the
  screen.

* Have simple testcases for every input validation failure case in your ioctl.
  Check that the error code matches your expectations. And finally make sure
  that you only test for one single error path in each subtest by submitting
  otherwise perfectly valid data. Without this an earlier check might reject
  the ioctl already and shadow the codepath you actually want to test, hiding
  bugs and regressions.

* Make all your ioctls restartable. First X really loves signals and second
  this will allow you to test 90% of all error handling paths by just
  interrupting your main test suite constantly with signals. Thanks to X's
  love for signal you'll get an excellent base coverage of all your error
  paths pretty much for free for graphics drivers. Also, be consistent with
  how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its
  userspace library. The i915 driver botched this with the set_tiling ioctl,
  now we're stuck forever with some arcane semantics in both the kernel and
  userspace.

* If you can't make a given codepath restartable make a stuck task at least
  killable. GPUs just die and your users won't like you more if you hang their
  entire box (by means of an unkillable X process). If the state recovery is
  still too tricky have a timeout or hangcheck safety net as a last-ditch
  effort in case the hardware has gone bananas.

* Have testcases for the really tricky corner cases in your error recovery code
  - it's way too easy to create a deadlock between your hangcheck code and
  waiters.

”h]”j<  )”}”(hhh]”(jA  )”}”(hXy  The ioctl must check for array overflows. Also it needs to check for
over/underflows and clamping issues of integer values in general. The usual
example is sprite positioning values fed directly into the hardware with the
hardware just having 12 bits or so. Works nicely until some odd display
server doesn't bother with clamping itself and the cursor wraps around the
screen.
”h]”hÌ)”}”(hXx  The ioctl must check for array overflows. Also it needs to check for
over/underflows and clamping issues of integer values in general. The usual
example is sprite positioning values fed directly into the hardware with the
hardware just having 12 bits or so. Works nicely until some odd display
server doesn't bother with clamping itself and the cursor wraps around the
screen.”h]”hXz  The ioctl must check for array overflows. Also it needs to check for
over/underflows and clamping issues of integer values in general. The usual
example is sprite positioning values fed directly into the hardware with the
hardware just having 12 bits or so. Works nicely until some odd display
server doesnâ€™t bother with clamping itself and the cursor wraps around the
screen.”…””}”(hj|  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K\hjx  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hju  ubjA  )”}”(hX  Have simple testcases for every input validation failure case in your ioctl.
Check that the error code matches your expectations. And finally make sure
that you only test for one single error path in each subtest by submitting
otherwise perfectly valid data. Without this an earlier check might reject
the ioctl already and shadow the codepath you actually want to test, hiding
bugs and regressions.
”h]”hÌ)”}”(hX  Have simple testcases for every input validation failure case in your ioctl.
Check that the error code matches your expectations. And finally make sure
that you only test for one single error path in each subtest by submitting
otherwise perfectly valid data. Without this an earlier check might reject
the ioctl already and shadow the codepath you actually want to test, hiding
bugs and regressions.”h]”hX  Have simple testcases for every input validation failure case in your ioctl.
Check that the error code matches your expectations. And finally make sure
that you only test for one single error path in each subtest by submitting
otherwise perfectly valid data. Without this an earlier check might reject
the ioctl already and shadow the codepath you actually want to test, hiding
bugs and regressions.”…””}”(hj”  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Kchj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hju  ubjA  )”}”(hXV  Make all your ioctls restartable. First X really loves signals and second
this will allow you to test 90% of all error handling paths by just
interrupting your main test suite constantly with signals. Thanks to X's
love for signal you'll get an excellent base coverage of all your error
paths pretty much for free for graphics drivers. Also, be consistent with
how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its
userspace library. The i915 driver botched this with the set_tiling ioctl,
now we're stuck forever with some arcane semantics in both the kernel and
userspace.
”h]”hÌ)”}”(hXU  Make all your ioctls restartable. First X really loves signals and second
this will allow you to test 90% of all error handling paths by just
interrupting your main test suite constantly with signals. Thanks to X's
love for signal you'll get an excellent base coverage of all your error
paths pretty much for free for graphics drivers. Also, be consistent with
how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its
userspace library. The i915 driver botched this with the set_tiling ioctl,
now we're stuck forever with some arcane semantics in both the kernel and
userspace.”h]”hX[  Make all your ioctls restartable. First X really loves signals and second
this will allow you to test 90% of all error handling paths by just
interrupting your main test suite constantly with signals. Thanks to Xâ€™s
love for signal youâ€™ll get an excellent base coverage of all your error
paths pretty much for free for graphics drivers. Also, be consistent with
how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its
userspace library. The i915 driver botched this with the set_tiling ioctl,
now weâ€™re stuck forever with some arcane semantics in both the kernel and
userspace.”…””}”(hj¬  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Kjhj¨  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hju  ubjA  )”}”(hXX  If you can't make a given codepath restartable make a stuck task at least
killable. GPUs just die and your users won't like you more if you hang their
entire box (by means of an unkillable X process). If the state recovery is
still too tricky have a timeout or hangcheck safety net as a last-ditch
effort in case the hardware has gone bananas.
”h]”hÌ)”}”(hXW  If you can't make a given codepath restartable make a stuck task at least
killable. GPUs just die and your users won't like you more if you hang their
entire box (by means of an unkillable X process). If the state recovery is
still too tricky have a timeout or hangcheck safety net as a last-ditch
effort in case the hardware has gone bananas.”h]”hX[  If you canâ€™t make a given codepath restartable make a stuck task at least
killable. GPUs just die and your users wonâ€™t like you more if you hang their
entire box (by means of an unkillable X process). If the state recovery is
still too tricky have a timeout or hangcheck safety net as a last-ditch
effort in case the hardware has gone bananas.”…””}”(hjÄ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KthjÀ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hju  ubjA  )”}”(hŒ¡Have testcases for the really tricky corner cases in your error recovery code
- it's way too easy to create a deadlock between your hangcheck code and
waiters.

”h]”hÌ)”}”(hŒŸHave testcases for the really tricky corner cases in your error recovery code
- it's way too easy to create a deadlock between your hangcheck code and
waiters.”h]”hŒ¡Have testcases for the really tricky corner cases in your error recovery code
- itâ€™s way too easy to create a deadlock between your hangcheck code and
waiters.”…””}”(hjÜ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KzhjØ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hju  ubeh}”(h]”h ]”h"]”h$]”h&]”j¨  j©  uh1j;  h³hÊh´K\hjq  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j5  h³hÊh´K\hjR  h²hubeh}”(h]”Œfun-with-error-paths”ah ]”h"]”Œfun with error paths”ah$]”h&]”uh1hµhh·h²hh³hÊh´KUubh¶)”}”(hhh]”(h»)”}”(hŒTime, Waiting and Missing it”h]”hŒTime, Waiting and Missing it”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj  h²hh³hÊh´K€ubhÌ)”}”(hX  GPUs do most everything asynchronously, so we have a need to time operations and
wait for outstanding ones. This is really tricky business; at the moment none of
the ioctls supported by the drm/i915 get this fully right, which means there's
still tons more lessons to learn here.”h]”hX  GPUs do most everything asynchronously, so we have a need to time operations and
wait for outstanding ones. This is really tricky business; at the moment none of
the ioctls supported by the drm/i915 get this fully right, which means thereâ€™s
still tons more lessons to learn here.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K‚hj  h²hubj6  )”}”(hX  * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and
  v4l use by default nowadays. But let userspace know which timestamps are
  derived from different clock domains like your main system clock (provided
  by the kernel) or some independent hardware counter somewhere else. Clocks
  will mismatch if you look close enough, but if performance measuring tools
  have this information they can at least compensate. If your userspace can
  get at the raw values of some clocks (e.g. through in-command-stream
  performance counter sampling instructions) consider exposing those also.

* Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most
  convenient time specification, but it's mostly the standard.

* Check that input time values are normalized and reject them if not. Note
  that the kernel native struct ktime has a signed integer for both seconds
  and nanoseconds, so beware here.

* For timeouts, use absolute times. If you're a good fellow and made your
  ioctl restartable relative timeouts tend to be too coarse and can
  indefinitely extend your wait time due to rounding on each restart.
  Especially if your reference clock is something really slow like the display
  frame counter. With a spec lawyer hat on this isn't a bug since timeouts can
  always be extended - but users will surely hate you if their neat animations
  starts to stutter due to this.

* Consider ditching any synchronous wait ioctls with timeouts and just deliver
  an asynchronous event on a pollable file descriptor. It fits much better
  into event driven applications' main loop.

* Have testcases for corner-cases, especially whether the return values for
  already-completed events, successful waits and timed-out waits are all sane
  and suiting to your needs.

”h]”j<  )”}”(hhh]”(jA  )”}”(hXN  Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and
v4l use by default nowadays. But let userspace know which timestamps are
derived from different clock domains like your main system clock (provided
by the kernel) or some independent hardware counter somewhere else. Clocks
will mismatch if you look close enough, but if performance measuring tools
have this information they can at least compensate. If your userspace can
get at the raw values of some clocks (e.g. through in-command-stream
performance counter sampling instructions) consider exposing those also.
”h]”hÌ)”}”(hXM  Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and
v4l use by default nowadays. But let userspace know which timestamps are
derived from different clock domains like your main system clock (provided
by the kernel) or some independent hardware counter somewhere else. Clocks
will mismatch if you look close enough, but if performance measuring tools
have this information they can at least compensate. If your userspace can
get at the raw values of some clocks (e.g. through in-command-stream
performance counter sampling instructions) consider exposing those also.”h]”hXO  Use CLOCK_MONOTONIC as your reference time, always. Itâ€™s what alsa, drm and
v4l use by default nowadays. But let userspace know which timestamps are
derived from different clock domains like your main system clock (provided
by the kernel) or some independent hardware counter somewhere else. Clocks
will mismatch if you look close enough, but if performance measuring tools
have this information they can at least compensate. If your userspace can
get at the raw values of some clocks (e.g. through in-command-stream
performance counter sampling instructions) consider exposing those also.”…””}”(hj.  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K‡hj*  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj'  ubjA  )”}”(hŒ‰Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most
convenient time specification, but it's mostly the standard.
”h]”hÌ)”}”(hŒˆUse __s64 seconds plus __u64 nanoseconds to specify time. It's not the most
convenient time specification, but it's mostly the standard.”h]”hŒŒUse __s64 seconds plus __u64 nanoseconds to specify time. Itâ€™s not the most
convenient time specification, but itâ€™s mostly the standard.”…””}”(hjF  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KhjB  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj'  ubjA  )”}”(hŒ´Check that input time values are normalized and reject them if not. Note
that the kernel native struct ktime has a signed integer for both seconds
and nanoseconds, so beware here.
”h]”hÌ)”}”(hŒ³Check that input time values are normalized and reject them if not. Note
that the kernel native struct ktime has a signed integer for both seconds
and nanoseconds, so beware here.”h]”hŒ³Check that input time values are normalized and reject them if not. Note
that the kernel native struct ktime has a signed integer for both seconds
and nanoseconds, so beware here.”…””}”(hj^  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K“hjZ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj'  ubjA  )”}”(hXÔ  For timeouts, use absolute times. If you're a good fellow and made your
ioctl restartable relative timeouts tend to be too coarse and can
indefinitely extend your wait time due to rounding on each restart.
Especially if your reference clock is something really slow like the display
frame counter. With a spec lawyer hat on this isn't a bug since timeouts can
always be extended - but users will surely hate you if their neat animations
starts to stutter due to this.
”h]”hÌ)”}”(hXÓ  For timeouts, use absolute times. If you're a good fellow and made your
ioctl restartable relative timeouts tend to be too coarse and can
indefinitely extend your wait time due to rounding on each restart.
Especially if your reference clock is something really slow like the display
frame counter. With a spec lawyer hat on this isn't a bug since timeouts can
always be extended - but users will surely hate you if their neat animations
starts to stutter due to this.”h]”hX×  For timeouts, use absolute times. If youâ€™re a good fellow and made your
ioctl restartable relative timeouts tend to be too coarse and can
indefinitely extend your wait time due to rounding on each restart.
Especially if your reference clock is something really slow like the display
frame counter. With a spec lawyer hat on this isnâ€™t a bug since timeouts can
always be extended - but users will surely hate you if their neat animations
starts to stutter due to this.”…””}”(hjv  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K—hjr  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj'  ubjA  )”}”(hŒÁConsider ditching any synchronous wait ioctls with timeouts and just deliver
an asynchronous event on a pollable file descriptor. It fits much better
into event driven applications' main loop.
”h]”hÌ)”}”(hŒÀConsider ditching any synchronous wait ioctls with timeouts and just deliver
an asynchronous event on a pollable file descriptor. It fits much better
into event driven applications' main loop.”h]”hŒÂConsider ditching any synchronous wait ioctls with timeouts and just deliver
an asynchronous event on a pollable file descriptor. It fits much better
into event driven applicationsâ€™ main loop.”…””}”(hjŽ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KŸhjŠ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj'  ubjA  )”}”(hŒ²Have testcases for corner-cases, especially whether the return values for
already-completed events, successful waits and timed-out waits are all sane
and suiting to your needs.

”h]”hÌ)”}”(hŒ°Have testcases for corner-cases, especially whether the return values for
already-completed events, successful waits and timed-out waits are all sane
and suiting to your needs.”h]”hŒ°Have testcases for corner-cases, especially whether the return values for
already-completed events, successful waits and timed-out waits are all sane
and suiting to your needs.”…””}”(hj¦  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K£hj¢  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj'  ubeh}”(h]”h ]”h"]”h$]”h&]”j¨  j©  uh1j;  h³hÊh´K‡hj#  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j5  h³hÊh´K‡hj  h²hubeh}”(h]”Œtime-waiting-and-missing-it”ah ]”h"]”Œtime, waiting and missing it”ah$]”h&]”uh1hµhh·h²hh³hÊh´K€ubh¶)”}”(hhh]”(h»)”}”(hŒLeaking Resources, Not”h]”hŒLeaking Resources, Not”…””}”(hjÑ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjÎ  h²hh³hÊh´K©ubhÌ)”}”(hX  A full-blown drm driver essentially implements a little OS, but specialized to
the given GPU platforms. This means a driver needs to expose tons of handles
for different objects and other resources to userspace. Doing that right
entails its own little set of pitfalls:”h]”hX  A full-blown drm driver essentially implements a little OS, but specialized to
the given GPU platforms. This means a driver needs to expose tons of handles
for different objects and other resources to userspace. Doing that right
entails its own little set of pitfalls:”…””}”(hjß  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K«hjÎ  h²hubj6  )”}”(hX¹  * Always attach the lifetime of your dynamically created resources to the
  lifetime of a file descriptor. Consider using a 1:1 mapping if your resource
  needs to be shared across processes -  fd-passing over unix domain sockets
  also simplifies lifetime management for userspace.

* Always have O_CLOEXEC support.

* Ensure that you have sufficient insulation between different clients. By
  default pick a private per-fd namespace which forces any sharing to be done
  explicitly. Only go with a more global per-device namespace if the objects
  are truly device-unique. One counterexample in the drm modeset interfaces is
  that the per-device modeset objects like connectors share a namespace with
  framebuffer objects, which mostly are not shared at all. A separate
  namespace, private by default, for framebuffers would have been more
  suitable.

* Think about uniqueness requirements for userspace handles. E.g. for most drm
  drivers it's a userspace bug to submit the same object twice in the same
  command submission ioctl. But then if objects are shareable userspace needs
  to know whether it has seen an imported object from a different process
  already or not. I haven't tried this myself yet due to lack of a new class
  of objects, but consider using inode numbers on your shared file descriptors
  as unique identifiers - it's how real files are told apart, too.
  Unfortunately this requires a full-blown virtual filesystem in the kernel.

”h]”j<  )”}”(hhh]”(jA  )”}”(hX  Always attach the lifetime of your dynamically created resources to the
lifetime of a file descriptor. Consider using a 1:1 mapping if your resource
needs to be shared across processes -  fd-passing over unix domain sockets
also simplifies lifetime management for userspace.
”h]”hÌ)”}”(hX  Always attach the lifetime of your dynamically created resources to the
lifetime of a file descriptor. Consider using a 1:1 mapping if your resource
needs to be shared across processes -  fd-passing over unix domain sockets
also simplifies lifetime management for userspace.”h]”hX  Always attach the lifetime of your dynamically created resources to the
lifetime of a file descriptor. Consider using a 1:1 mapping if your resource
needs to be shared across processes -  fd-passing over unix domain sockets
also simplifies lifetime management for userspace.”…””}”(hjø  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K°hjô  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hjñ  ubjA  )”}”(hŒAlways have O_CLOEXEC support.
”h]”hÌ)”}”(hŒAlways have O_CLOEXEC support.”h]”hŒAlways have O_CLOEXEC support.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´Kµhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hjñ  ubjA  )”}”(hX  Ensure that you have sufficient insulation between different clients. By
default pick a private per-fd namespace which forces any sharing to be done
explicitly. Only go with a more global per-device namespace if the objects
are truly device-unique. One counterexample in the drm modeset interfaces is
that the per-device modeset objects like connectors share a namespace with
framebuffer objects, which mostly are not shared at all. A separate
namespace, private by default, for framebuffers would have been more
suitable.
”h]”hÌ)”}”(hX
  Ensure that you have sufficient insulation between different clients. By
default pick a private per-fd namespace which forces any sharing to be done
explicitly. Only go with a more global per-device namespace if the objects
are truly device-unique. One counterexample in the drm modeset interfaces is
that the per-device modeset objects like connectors share a namespace with
framebuffer objects, which mostly are not shared at all. A separate
namespace, private by default, for framebuffers would have been more
suitable.”h]”hX
  Ensure that you have sufficient insulation between different clients. By
default pick a private per-fd namespace which forces any sharing to be done
explicitly. Only go with a more global per-device namespace if the objects
are truly device-unique. One counterexample in the drm modeset interfaces is
that the per-device modeset objects like connectors share a namespace with
framebuffer objects, which mostly are not shared at all. A separate
namespace, private by default, for framebuffers would have been more
suitable.”…””}”(hj(  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´K·hj$  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hjñ  ubjA  )”}”(hXO  Think about uniqueness requirements for userspace handles. E.g. for most drm
drivers it's a userspace bug to submit the same object twice in the same
command submission ioctl. But then if objects are shareable userspace needs
to know whether it has seen an imported object from a different process
already or not. I haven't tried this myself yet due to lack of a new class
of objects, but consider using inode numbers on your shared file descriptors
as unique identifiers - it's how real files are told apart, too.
Unfortunately this requires a full-blown virtual filesystem in the kernel.

”h]”hÌ)”}”(hXM  Think about uniqueness requirements for userspace handles. E.g. for most drm
drivers it's a userspace bug to submit the same object twice in the same
command submission ioctl. But then if objects are shareable userspace needs
to know whether it has seen an imported object from a different process
already or not. I haven't tried this myself yet due to lack of a new class
of objects, but consider using inode numbers on your shared file descriptors
as unique identifiers - it's how real files are told apart, too.
Unfortunately this requires a full-blown virtual filesystem in the kernel.”h]”hXS  Think about uniqueness requirements for userspace handles. E.g. for most drm
drivers itâ€™s a userspace bug to submit the same object twice in the same
command submission ioctl. But then if objects are shareable userspace needs
to know whether it has seen an imported object from a different process
already or not. I havenâ€™t tried this myself yet due to lack of a new class
of objects, but consider using inode numbers on your shared file descriptors
as unique identifiers - itâ€™s how real files are told apart, too.
Unfortunately this requires a full-blown virtual filesystem in the kernel.”…””}”(hj@  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÀhj<  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hjñ  ubeh}”(h]”h ]”h"]”h$]”h&]”j¨  j©  uh1j;  h³hÊh´K°hjí  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j5  h³hÊh´K°hjÎ  h²hubeh}”(h]”Œleaking-resources-not”ah ]”h"]”Œleaking resources, not”ah$]”h&]”uh1hµhh·h²hh³hÊh´K©ubh¶)”}”(hhh]”(h»)”}”(hŒLast, but not Least”h]”hŒLast, but not Least”…””}”(hjk  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjh  h²hh³hÊh´KËubhÌ)”}”(hŒ$Not every problem needs a new ioctl:”h]”hŒ$Not every problem needs a new ioctl:”…””}”(hjy  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÍhjh  h²hubj6  )”}”(hX  * Think hard whether you really want a driver-private interface. Of course
  it's much quicker to push a driver-private interface than engaging in
  lengthy discussions for a more generic solution. And occasionally doing a
  private interface to spearhead a new concept is what's required. But in the
  end, once the generic interface comes around you'll end up maintaining two
  interfaces. Indefinitely.

* Consider other interfaces than ioctls. A sysfs attribute is much better for
  per-device settings, or for child objects with fairly static lifetimes (like
  output connectors in drm with all the detection override attributes). Or
  maybe only your testsuite needs this interface, and then debugfs with its
  disclaimer of not having a stable ABI would be better.
”h]”j<  )”}”(hhh]”(jA  )”}”(hXŠ  Think hard whether you really want a driver-private interface. Of course
it's much quicker to push a driver-private interface than engaging in
lengthy discussions for a more generic solution. And occasionally doing a
private interface to spearhead a new concept is what's required. But in the
end, once the generic interface comes around you'll end up maintaining two
interfaces. Indefinitely.
”h]”hÌ)”}”(hX‰  Think hard whether you really want a driver-private interface. Of course
it's much quicker to push a driver-private interface than engaging in
lengthy discussions for a more generic solution. And occasionally doing a
private interface to spearhead a new concept is what's required. But in the
end, once the generic interface comes around you'll end up maintaining two
interfaces. Indefinitely.”h]”hX  Think hard whether you really want a driver-private interface. Of course
itâ€™s much quicker to push a driver-private interface than engaging in
lengthy discussions for a more generic solution. And occasionally doing a
private interface to spearhead a new concept is whatâ€™s required. But in the
end, once the generic interface comes around youâ€™ll end up maintaining two
interfaces. Indefinitely.”…””}”(hj’  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÏhjŽ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj‹  ubjA  )”}”(hXc  Consider other interfaces than ioctls. A sysfs attribute is much better for
per-device settings, or for child objects with fairly static lifetimes (like
output connectors in drm with all the detection override attributes). Or
maybe only your testsuite needs this interface, and then debugfs with its
disclaimer of not having a stable ABI would be better.
”h]”hÌ)”}”(hXb  Consider other interfaces than ioctls. A sysfs attribute is much better for
per-device settings, or for child objects with fairly static lifetimes (like
output connectors in drm with all the detection override attributes). Or
maybe only your testsuite needs this interface, and then debugfs with its
disclaimer of not having a stable ABI would be better.”h]”hXb  Consider other interfaces than ioctls. A sysfs attribute is much better for
per-device settings, or for child objects with fairly static lifetimes (like
output connectors in drm with all the detection override attributes). Or
maybe only your testsuite needs this interface, and then debugfs with its
disclaimer of not having a stable ABI would be better.”…””}”(hjª  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÖhj¦  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j@  hj‹  ubeh}”(h]”h ]”h"]”h$]”h&]”j¨  j©  uh1j;  h³hÊh´KÏhj‡  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j5  h³hÊh´KÏhjh  h²hubhÌ)”}”(hX«  Finally, the name of the game is to get it right on the first attempt, since if
your driver proves popular and your hardware platforms long-lived then you'll
be stuck with a given ioctl essentially forever. You can try to deprecate
horrible ioctls on newer iterations of your hardware, but generally it takes
years to accomplish this. And then again years until the last user able to
complain about regressions disappears, too.”h]”hX­  Finally, the name of the game is to get it right on the first attempt, since if
your driver proves popular and your hardware platforms long-lived then youâ€™ll
be stuck with a given ioctl essentially forever. You can try to deprecate
horrible ioctls on newer iterations of your hardware, but generally it takes
years to accomplish this. And then again years until the last user able to
complain about regressions disappears, too.”…””}”(hjÊ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hËh³hÊh´KÜhjh  h²hubeh}”(h]”Œlast-but-not-least”ah ]”h"]”Œlast, but not least”ah$]”h&]”uh1hµhh·h²hh³hÊh´KËubeh}”(h]”Œhow-to-avoid-botching-up-ioctls”ah ]”h"]”Œ!(how to avoid) botching up ioctls”ah$]”h&]”uh1hµhhh²hh³hÊh´Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”hÊuh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hºNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”hÊŒ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jå  jâ  jµ  j²  jO  jL  j  jþ  jË  jÈ  je  jb  jÝ  jÚ  uŒ	nametypes”}”(jå  ‰jµ  ‰jO  ‰j  ‰jË  ‰je  ‰jÝ  ‰uh}”(jâ  h·j²  j  jL  j¸  jþ  jR  jÈ  j  jb  jÎ  jÚ  jh  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nh²hub.