sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget&/translations/zh_CN/driver-api/usb/URBmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/zh_TW/driver-api/usb/URBmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/it_IT/driver-api/usb/URBmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ja_JP/driver-api/usb/URBmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ko_KR/driver-api/usb/URBmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/pt_BR/driver-api/usb/URBmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/sp_SP/driver-api/usb/URBmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhtarget)}(h .. _usb-urb:h]h}(h]h ]h"]h$]h&]refidusb-urbuh1hhKhhhhh@/var/lib/git/docbuild/linux/Documentation/driver-api/usb/URB.rstubhsection)}(hhh](htitle)}(hUSB Request Block (URB)h]hUSB Request Block (URB)}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh field_list)}(hhh](hfield)}(hhh](h field_name)}(hRevisedh]hRevised}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhKubh field_body)}(h 2000-Dec-05h]h paragraph)}(hhh]h 2000-Dec-05}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hAgainh]hAgain}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhKubh)}(h 2002-Jul-06h]h)}(hj'h]h 2002-Jul-06}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj%ubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hAgainh]hAgain}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjBhhhKubh)}(h 2005-Sep-19h]h)}(hjUh]h 2005-Sep-19}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjSubah}(h]h ]h"]h$]h&]uh1hhjBubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hAgainh]hAgain}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhjphhhKubh)}(h 2017-Mar-29 h]h)}(h 2017-Mar-29h]h 2017-Mar-29}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjubah}(h]h ]h"]h$]h&]uh1hhjpubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubeh}(h]h ]h"]h$]h&]uh1hhhhhhhhKubhnote)}(hXThe USB subsystem now has a substantial section at :ref:`usb-hostside-api` section, generated from the current source code. This particular documentation file isn't complete and may not be updated to the last version; don't rely on it except for a quick overview.h]h)}(hXThe USB subsystem now has a substantial section at :ref:`usb-hostside-api` section, generated from the current source code. This particular documentation file isn't complete and may not be updated to the last version; don't rely on it except for a quick overview.h](h3The USB subsystem now has a substantial section at }(hjhhhNhNubh)}(h:ref:`usb-hostside-api`h]hinline)}(hjh]husb-hostside-api}(hjhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocdriver-api/usb/URB refdomainjreftyperef refexplicitrefwarn reftargetusb-hostside-apiuh1hhhhKhjubh section, generated from the current source code. This particular documentation file isn’t complete and may not be updated to the last version; don’t rely on it except for a quick overview.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubh)}(hhh](h)}(h"Basic concept or 'What is an URB?'h]h&Basic concept or ‘What is an URB?’}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hvThe basic idea of the new driver is message passing, the message itself is called USB Request Block, or URB for short.h]hvThe basic idea of the new driver is message passing, the message itself is called USB Request Block, or URB for short.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh bullet_list)}(hhh](h list_item)}(hqAn URB consists of all relevant information to execute any USB transaction and deliver the data and status back. h]h)}(hpAn URB consists of all relevant information to execute any USB transaction and deliver the data and status back.h]hpAn URB consists of all relevant information to execute any USB transaction and deliver the data and status back.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hExecution of an URB is inherently an asynchronous operation, i.e. the :c:func:`usb_submit_urb` call returns immediately after it has successfully queued the requested action. h]h)}(hExecution of an URB is inherently an asynchronous operation, i.e. the :c:func:`usb_submit_urb` call returns immediately after it has successfully queued the requested action.h](hFExecution of an URB is inherently an asynchronous operation, i.e. the }(hj*hhhNhNubh)}(h:c:func:`usb_submit_urb`h]hliteral)}(hj4h]husb_submit_urb()}(hj8hhhNhNubah}(h]h ](jcc-funceh"]h$]h&]uh1j6hj2ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_submit_urbuh1hhhhKhj*ubhP call returns immediately after it has successfully queued the requested action.}(hj*hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj&ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hQTransfers for one URB can be canceled with :c:func:`usb_unlink_urb` at any time. h]h)}(hPTransfers for one URB can be canceled with :c:func:`usb_unlink_urb` at any time.h](h+Transfers for one URB can be canceled with }(hjhhhhNhNubh)}(h:c:func:`usb_unlink_urb`h]j7)}(hjrh]husb_unlink_urb()}(hjthhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjpubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_unlink_urbuh1hhhhK!hjhubh at any time.}(hjhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK!hjdubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hEach URB has a completion handler, which is called after the action has been successfully completed or canceled. The URB also contains a context-pointer for passing information to the completion handler. h]h)}(hEach URB has a completion handler, which is called after the action has been successfully completed or canceled. The URB also contains a context-pointer for passing information to the completion handler.h]hEach URB has a completion handler, which is called after the action has been successfully completed or canceled. The URB also contains a context-pointer for passing information to the completion handler.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK$hjubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hXTEach endpoint for a device logically supports a queue of requests. You can fill that queue, so that the USB hardware can still transfer data to an endpoint while your driver handles completion of another. This maximizes use of USB bandwidth, and supports seamless streaming of data to (or from) devices when using periodic transfer modes. h]h)}(hXREach endpoint for a device logically supports a queue of requests. You can fill that queue, so that the USB hardware can still transfer data to an endpoint while your driver handles completion of another. This maximizes use of USB bandwidth, and supports seamless streaming of data to (or from) devices when using periodic transfer modes.h]hXREach endpoint for a device logically supports a queue of requests. You can fill that queue, so that the USB hardware can still transfer data to an endpoint while your driver handles completion of another. This maximizes use of USB bandwidth, and supports seamless streaming of data to (or from) devices when using periodic transfer modes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKhjhhubeh}(h]basic-concept-or-what-is-an-urbah ]h"]"basic concept or 'what is an urb?'ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hThe URB structureh]hThe URB structure}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK0ubh)}(h&Some of the fields in struct urb are::h]h%Some of the fields in struct urb are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hjhhubh literal_block)}(hXstruct urb { // (IN) device and pipe specify the endpoint queue struct usb_device *dev; // pointer to associated USB device unsigned int pipe; // endpoint information unsigned int transfer_flags; // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc. // (IN) all urbs need completion routines void *context; // context for completion routine usb_complete_t complete; // pointer to completion routine // (OUT) status after each completion int status; // returned status // (IN) buffer used for data transfers void *transfer_buffer; // associated data buffer u32 transfer_buffer_length; // data buffer length int number_of_packets; // size of iso_frame_desc // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used u32 actual_length; // actual data buffer length // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest) unsigned char *setup_packet; // setup packet (control only) // Only for PERIODIC transfers (ISO, INTERRUPT) // (IN/OUT) start_frame is set unless URB_ISO_ASAP isn't set int start_frame; // start frame int interval; // polling interval // ISO only: packets are only "best effort"; each can have errors int error_count; // number of errors struct usb_iso_packet_descriptor iso_frame_desc[0]; };h]hXstruct urb { // (IN) device and pipe specify the endpoint queue struct usb_device *dev; // pointer to associated USB device unsigned int pipe; // endpoint information unsigned int transfer_flags; // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc. // (IN) all urbs need completion routines void *context; // context for completion routine usb_complete_t complete; // pointer to completion routine // (OUT) status after each completion int status; // returned status // (IN) buffer used for data transfers void *transfer_buffer; // associated data buffer u32 transfer_buffer_length; // data buffer length int number_of_packets; // size of iso_frame_desc // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used u32 actual_length; // actual data buffer length // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest) unsigned char *setup_packet; // setup packet (control only) // Only for PERIODIC transfers (ISO, INTERRUPT) // (IN/OUT) start_frame is set unless URB_ISO_ASAP isn't set int start_frame; // start frame int interval; // polling interval // ISO only: packets are only "best effort"; each can have errors int error_count; // number of errors struct usb_iso_packet_descriptor iso_frame_desc[0]; };}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhK4hjhhubh)}(hYour driver must create the "pipe" value using values from the appropriate endpoint descriptor in an interface that it's claimed.h]hYour driver must create the “pipe” value using values from the appropriate endpoint descriptor in an interface that it’s claimed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjhhubeh}(h]the-urb-structureah ]h"]the urb structureah$]h&]uh1hhhhhhhhK0ubh)}(hhh](h)}(hHow to get an URB?h]hHow to get an URB?}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj&hhhhhK]ubh)}(h7URBs are allocated by calling :c:func:`usb_alloc_urb`::h](hURBs are allocated by calling }(hj7hhhNhNubh)}(h:c:func:`usb_alloc_urb`h]j7)}(hjAh]husb_alloc_urb()}(hjChhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj?ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnj usb_alloc_urbuh1hhhhK_hj7ubh:}(hj7hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK_hj&hhubj)}(h7struct urb *usb_alloc_urb(int isoframes, int mem_flags)h]h7struct urb *usb_alloc_urb(int isoframes, int mem_flags)}hjhsbah}(h]h ]h"]h$]h&]jjuh1jhhhKahj&hhubh)}(hX[Return value is a pointer to the allocated URB, 0 if allocation failed. The parameter isoframes specifies the number of isochronous transfer frames you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter holds standard memory allocation flags, letting you control (among other things) whether the underlying code may block or not.h]hX[Return value is a pointer to the allocated URB, 0 if allocation failed. The parameter isoframes specifies the number of isochronous transfer frames you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter holds standard memory allocation flags, letting you control (among other things) whether the underlying code may block or not.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKchj&hhubh)}(h,To free an URB, use :c:func:`usb_free_urb`::h](hTo free an URB, use }(hjhhhNhNubh)}(h:c:func:`usb_free_urb`h]j7)}(hjh]husb_free_urb()}(hjhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnj usb_free_urbuh1hhhhKihjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKihj&hhubj)}(h"void usb_free_urb(struct urb *urb)h]h"void usb_free_urb(struct urb *urb)}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKkhj&hhubh)}(hYou may free an urb that you've submitted, but which hasn't yet been returned to you in a completion callback. It will automatically be deallocated when it is no longer in use.h]hYou may free an urb that you’ve submitted, but which hasn’t yet been returned to you in a completion callback. It will automatically be deallocated when it is no longer in use.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKmhj&hhubeh}(h]how-to-get-an-urbah ]h"]how to get an urb?ah$]h&]uh1hhhhhhhhK]ubh)}(hhh](h)}(hWhat has to be filled in?h]hWhat has to be filled in?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKsubh)}(hXDepending on the type of transaction, there are some inline functions defined in ``linux/usb.h`` to simplify the initialization, such as :c:func:`usb_fill_control_urb`, :c:func:`usb_fill_bulk_urb` and :c:func:`usb_fill_int_urb`. In general, they need the usb device pointer, the pipe (usual format from usb.h), the transfer buffer, the desired transfer length, the completion handler, and its context. Take a look at the some existing drivers to see how they're used.h](hQDepending on the type of transaction, there are some inline functions defined in }(hjhhhNhNubj7)}(h``linux/usb.h``h]h linux/usb.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh) to simplify the initialization, such as }(hjhhhNhNubh)}(h:c:func:`usb_fill_control_urb`h]j7)}(hjh]husb_fill_control_urb()}(hjhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_fill_control_urbuh1hhhhKuhjubh, }(hjhhhNhNubh)}(h:c:func:`usb_fill_bulk_urb`h]j7)}(hj)h]husb_fill_bulk_urb()}(hj+hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj'ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_fill_bulk_urbuh1hhhhKuhjubh and }(hjhhhNhNubh)}(h:c:func:`usb_fill_int_urb`h]j7)}(hjLh]husb_fill_int_urb()}(hjNhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjJubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_fill_int_urbuh1hhhhKuhjubh. In general, they need the usb device pointer, the pipe (usual format from usb.h), the transfer buffer, the desired transfer length, the completion handler, and its context. Take a look at the some existing drivers to see how they’re used.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKuhjhhubh)}(hFlags:h]hFlags:}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hjhhubj)}(hhh](j )}(hGFor ISO there are two startup behaviors: Specified start_frame or ASAP.h]h)}(hjh]hGFor ISO there are two startup behaviors: Specified start_frame or ASAP.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(h1For ASAP set ``URB_ISO_ASAP`` in transfer_flags. h]h)}(h0For ASAP set ``URB_ISO_ASAP`` in transfer_flags.h](h For ASAP set }(hjhhhNhNubj7)}(h``URB_ISO_ASAP``h]h URB_ISO_ASAP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh in transfer_flags.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hUIf short packets should NOT be tolerated, set ``URB_SHORT_NOT_OK`` in transfer_flags.h](h.If short packets should NOT be tolerated, set }(hjhhhNhNubj7)}(h``URB_SHORT_NOT_OK``h]hURB_SHORT_NOT_OK}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh in transfer_flags.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]what-has-to-be-filled-inah ]h"]what has to be filled in?ah$]h&]uh1hhhhhhhhKsubh)}(hhh](h)}(hHow to submit an URB?h]hHow to submit an URB?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h$Just call :c:func:`usb_submit_urb`::h](h Just call }(hjhhhNhNubh)}(h:c:func:`usb_submit_urb`h]j7)}(hjh]husb_submit_urb()}(hjhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_submit_urbuh1hhhhKhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h2int usb_submit_urb(struct urb *urb, int mem_flags)h]h2int usb_submit_urb(struct urb *urb, int mem_flags)}hj5sbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hThe ``mem_flags`` parameter, such as ``GFP_ATOMIC``, controls memory allocation, such as whether the lower levels may block when memory is tight.h](hThe }(hjChhhNhNubj7)}(h ``mem_flags``h]h mem_flags}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjCubh parameter, such as }(hjChhhNhNubj7)}(h``GFP_ATOMIC``h]h GFP_ATOMIC}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjCubh^, controls memory allocation, such as whether the lower levels may block when memory is tight.}(hjChhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hrIt immediately returns, either with status 0 (request queued) or some error code, usually caused by the following:h]hrIt immediately returns, either with status 0 (request queued) or some error code, usually caused by the following:}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh](j )}(hOut of memory (``-ENOMEM``)h]h)}(hjh](hOut of memory (}(hjhhhNhNubj7)}(h ``-ENOMEM``h]h-ENOMEM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(hUnplugged device (``-ENODEV``)h]h)}(hjh](hUnplugged device (}(hjhhhNhNubj7)}(h ``-ENODEV``h]h-ENODEV}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(hStalled endpoint (``-EPIPE``)h]h)}(hjh](hStalled endpoint (}(hjhhhNhNubj7)}(h ``-EPIPE``h]h-EPIPE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(h+Too many queued ISO transfers (``-EAGAIN``)h]h)}(hjh](hToo many queued ISO transfers (}(hjhhhNhNubj7)}(h ``-EAGAIN``h]h-EAGAIN}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(h*Too many requested ISO frames (``-EFBIG``)h]h)}(hj,h](hToo many requested ISO frames (}(hj.hhhNhNubj7)}(h ``-EFBIG``h]h-EFBIG}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hj.ubh)}(hj.hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj*ubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(h"Invalid INT interval (``-EINVAL``)h]h)}(hjUh](hInvalid INT interval (}(hjWhhhNhNubj7)}(h ``-EINVAL``h]h-EINVAL}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjWubh)}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjSubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(h+More than one packet for INT (``-EINVAL``) h]h)}(h*More than one packet for INT (``-EINVAL``)h](hMore than one packet for INT (}(hjhhhNhNubj7)}(h ``-EINVAL``h]h-EINVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj|ubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hAfter submission, ``urb->status`` is ``-EINPROGRESS``; however, you should never look at that value except in your completion callback.h](hAfter submission, }(hjhhhNhNubj7)}(h``urb->status``h]h urb->status}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh is }(hjhhhNhNubj7)}(h``-EINPROGRESS``h]h -EINPROGRESS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubhR; however, you should never look at that value except in your completion callback.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hFor isochronous endpoints, your completion handlers should (re)submit URBs to the same endpoint with the ``URB_ISO_ASAP`` flag, using multi-buffering, to get seamless ISO streaming.h](hiFor isochronous endpoints, your completion handlers should (re)submit URBs to the same endpoint with the }(hjhhhNhNubj7)}(h``URB_ISO_ASAP``h]h URB_ISO_ASAP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh< flag, using multi-buffering, to get seamless ISO streaming.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]how-to-submit-an-urbah ]h"]how to submit an urb?ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h%How to cancel an already running URB?h]h%How to cancel an already running URB?}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hThere are two ways to cancel an URB you've submitted but which hasn't been returned to your driver yet. For an asynchronous cancel, call :c:func:`usb_unlink_urb`::h](hThere are two ways to cancel an URB you’ve submitted but which hasn’t been returned to your driver yet. For an asynchronous cancel, call }(hjhhhNhNubh)}(h:c:func:`usb_unlink_urb`h]j7)}(hj!h]husb_unlink_urb()}(hj#hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_unlink_urbuh1hhhhKhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h#int usb_unlink_urb(struct urb *urb)h]h#int usb_unlink_urb(struct urb *urb)}hjHsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hXIt removes the urb from the internal list and frees all allocated HW descriptors. The status is changed to reflect unlinking. Note that the URB will not normally have finished when :c:func:`usb_unlink_urb` returns; you must still wait for the completion handler to be called.h](hIt removes the urb from the internal list and frees all allocated HW descriptors. The status is changed to reflect unlinking. Note that the URB will not normally have finished when }(hjVhhhNhNubh)}(h:c:func:`usb_unlink_urb`h]j7)}(hj`h]husb_unlink_urb()}(hjbhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj^ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_unlink_urbuh1hhhhKhjVubhF returns; you must still wait for the completion handler to be called.}(hjVhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h=To cancel an URB synchronously, call :c:func:`usb_kill_urb`::h](h%To cancel an URB synchronously, call }(hjhhhNhNubh)}(h:c:func:`usb_kill_urb`h]j7)}(hjh]husb_kill_urb()}(hjhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnj usb_kill_urbuh1hhhhKhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h"void usb_kill_urb(struct urb *urb)h]h"void usb_kill_urb(struct urb *urb)}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hXIt does everything :c:func:`usb_unlink_urb` does, and in addition it waits until after the URB has been returned and the completion handler has finished. It also marks the URB as temporarily unusable, so that if the completion handler or anyone else tries to resubmit it they will get a ``-EPERM`` error. Thus you can be sure that when :c:func:`usb_kill_urb` returns, the URB is totally idle.h](hIt does everything }(hjhhhNhNubh)}(h:c:func:`usb_unlink_urb`h]j7)}(hjh]husb_unlink_urb()}(hjhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_unlink_urbuh1hhhhKhjubh does, and in addition it waits until after the URB has been returned and the completion handler has finished. It also marks the URB as temporarily unusable, so that if the completion handler or anyone else tries to resubmit it they will get a }(hjhhhNhNubj7)}(h ``-EPERM``h]h-EPERM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j6hjubh( error. Thus you can be sure that when }(hjhhhNhNubh)}(h:c:func:`usb_kill_urb`h]j7)}(hjh]husb_kill_urb()}(hjhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnj usb_kill_urbuh1hhhhKhjubh" returns, the URB is totally idle.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXThere is a lifetime issue to consider. An URB may complete at any time, and the completion handler may free the URB. If this happens while :c:func:`usb_unlink_urb` or :c:func:`usb_kill_urb` is running, it will cause a memory-access violation. The driver is responsible for avoiding this, which often means some sort of lock will be needed to prevent the URB from being deallocated while it is still in use.h](hThere is a lifetime issue to consider. An URB may complete at any time, and the completion handler may free the URB. If this happens while }(hj,hhhNhNubh)}(h:c:func:`usb_unlink_urb`h]j7)}(hj6h]husb_unlink_urb()}(hj8hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj4ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_unlink_urbuh1hhhhKhj,ubh or }(hj,hhhNhNubh)}(h:c:func:`usb_kill_urb`h]j7)}(hjYh]husb_kill_urb()}(hj[hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjWubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnj usb_kill_urbuh1hhhhKhj,ubh is running, it will cause a memory-access violation. The driver is responsible for avoiding this, which often means some sort of lock will be needed to prevent the URB from being deallocated while it is still in use.}(hj,hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXOn the other hand, since usb_unlink_urb may end up calling the completion handler, the handler must not take any lock that is held when usb_unlink_urb is invoked. The general solution to this problem is to increment the URB's reference count while holding the lock, then drop the lock and call usb_unlink_urb or usb_kill_urb, and then decrement the URB's reference count. You increment the reference count by calling :c:func`usb_get_urb`::h]hXOn the other hand, since usb_unlink_urb may end up calling the completion handler, the handler must not take any lock that is held when usb_unlink_urb is invoked. The general solution to this problem is to increment the URB’s reference count while holding the lock, then drop the lock and call usb_unlink_urb or usb_kill_urb, and then decrement the URB’s reference count. You increment the reference count by calling :c:func`usb_get_urb`:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h(struct urb *usb_get_urb(struct urb *urb)h]h(struct urb *usb_get_urb(struct urb *urb)}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(h(ignore the return value; it is the same as the argument) and decrement the reference count by calling :c:func:`usb_free_urb`. Of course, none of this is necessary if there's no danger of the URB being freed by the completion handler.h](hg(ignore the return value; it is the same as the argument) and decrement the reference count by calling }(hjhhhNhNubh)}(h:c:func:`usb_free_urb`h]j7)}(hjh]husb_free_urb()}(hjhhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hjubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnj usb_free_urbuh1hhhhKhjubhp. Of course, none of this is necessary if there’s no danger of the URB being freed by the completion handler.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]$how-to-cancel-an-already-running-urbah ]h"]%how to cancel an already running urb?ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h"What about the completion handler?h]h"What about the completion handler?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h&The handler is of the following type::h]h%The handler is of the following type:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h,typedef void (*usb_complete_t)(struct urb *)h]h,typedef void (*usb_complete_t)(struct urb *)}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hI.e., it gets the URB that caused the completion call. In the completion handler, you should have a look at ``urb->status`` to detect any USB errors. Since the context parameter is included in the URB, you can pass information to the completion handler.h](hlI.e., it gets the URB that caused the completion call. In the completion handler, you should have a look at }(hj hhhNhNubj7)}(h``urb->status``h]h urb->status}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hj ubh to detect any USB errors. Since the context parameter is included in the URB, you can pass information to the completion handler.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXNote that even when an error (or unlink) is reported, data may have been transferred. That's because USB transfers are packetized; it might take sixteen packets to transfer your 1KByte buffer, and ten of them might have transferred successfully before the completion was called.h]hXNote that even when an error (or unlink) is reported, data may have been transferred. That’s because USB transfers are packetized; it might take sixteen packets to transfer your 1KByte buffer, and ten of them might have transferred successfully before the completion was called.}(hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubhwarning)}(hONEVER SLEEP IN A COMPLETION HANDLER. These are often called in atomic context.h](h)}(h$NEVER SLEEP IN A COMPLETION HANDLER.h]h$NEVER SLEEP IN A COMPLETION HANDLER.}(hj6 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj2 ubh)}(h)These are often called in atomic context.h]h)These are often called in atomic context.}(hjD hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj2 ubeh}(h]h ]h"]h$]h&]uh1j0 hjhhhhhNubh)}(hIn the current kernel, completion handlers run with local interrupts disabled, but in the future this will be changed, so don't assume that local IRQs are always disabled inside completion handlers.h]hIn the current kernel, completion handlers run with local interrupts disabled, but in the future this will be changed, so don’t assume that local IRQs are always disabled inside completion handlers.}(hjX hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]!what-about-the-completion-handlerah ]h"]"what about the completion handler?ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h&How to do isochronous (ISO) transfers?h]h&How to do isochronous (ISO) transfers?}(hjq hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjn hhhhhKubh)}(hX~Besides the fields present on a bulk transfer, for ISO, you also have to set ``urb->interval`` to say how often to make transfers; it's often one per frame (which is once every microframe for highspeed devices). The actual interval used will be a power of two that's no bigger than what you specify. You can use the :c:func:`usb_fill_int_urb` macro to fill most ISO transfer fields.h](hMBesides the fields present on a bulk transfer, for ISO, you also have to set }(hj hhhNhNubj7)}(h``urb->interval``h]h urb->interval}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hj ubh to say how often to make transfers; it’s often one per frame (which is once every microframe for highspeed devices). The actual interval used will be a power of two that’s no bigger than what you specify. You can use the }(hj hhhNhNubh)}(h:c:func:`usb_fill_int_urb`h]j7)}(hj h]husb_fill_int_urb()}(hj hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_fill_int_urbuh1hhhhKhj ubh( macro to fill most ISO transfer fields.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjn hhubh)}(hFor ISO transfers you also have to fill a :c:type:`usb_iso_packet_descriptor` structure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for each packet you want to schedule.h](h*For ISO transfers you also have to fill a }(hj hhhNhNubh)}(h#:c:type:`usb_iso_packet_descriptor`h]j7)}(hj h]husb_iso_packet_descriptor}(hj hhhNhNubah}(h]h ](jjBc-typeeh"]h$]h&]uh1j6hj ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypetype refexplicitrefwarnjusb_iso_packet_descriptoruh1hhhhKhj ubh/ structure, allocated at the end of the URB by }(hj hhhNhNubh)}(h:c:func:`usb_alloc_urb`h]j7)}(hj h]husb_alloc_urb()}(hj hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnj usb_alloc_urbuh1hhhhKhj ubh', for each packet you want to schedule.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjn hhubh)}(hThe :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented interval value that is less than or equal to the requested interval value. If ``URB_ISO_ASAP`` scheduling is used, ``urb->start_frame`` is also updated.h](hThe }(hj hhhNhNubh)}(h:c:func:`usb_submit_urb`h]j7)}(hj h]husb_submit_urb()}(hj" hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_submit_urbuh1hhhhKhj ubh call modifies }(hj hhhNhNubj7)}(h``urb->interval``h]h urb->interval}(hjA hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hj ubhc to the implemented interval value that is less than or equal to the requested interval value. If }(hj hhhNhNubj7)}(h``URB_ISO_ASAP``h]h URB_ISO_ASAP}(hjS hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hj ubh scheduling is used, }(hj hhhNhNubj7)}(h``urb->start_frame``h]hurb->start_frame}(hje hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hj ubh is also updated.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjn hhubh)}(hXFor each entry you have to specify the data offset for this frame (base is transfer_buffer), and the length you want to write/expect to read. After completion, actual_length contains the actual transferred length and status contains the resulting status for the ISO transfer for this frame. It is allowed to specify a varying length from frame to frame (e.g. for audio synchronisation/adaptive transfer rates). You can also use the length 0 to omit one or more frames (striping).h]hXFor each entry you have to specify the data offset for this frame (base is transfer_buffer), and the length you want to write/expect to read. After completion, actual_length contains the actual transferred length and status contains the resulting status for the ISO transfer for this frame. It is allowed to specify a varying length from frame to frame (e.g. for audio synchronisation/adaptive transfer rates). You can also use the length 0 to omit one or more frames (striping).}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjn hhubh)}(hXFor scheduling you can choose your own start frame or ``URB_ISO_ASAP``. As explained earlier, if you always keep at least one URB queued and your completion keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb bandwidth utilization allows).h](h6For scheduling you can choose your own start frame or }(hj hhhNhNubj7)}(h``URB_ISO_ASAP``h]h URB_ISO_ASAP}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hj ubh. As explained earlier, if you always keep at least one URB queued and your completion keeps (re)submitting a later URB, you’ll get smooth ISO streaming (if usb bandwidth utilization allows).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjn hhubh)}(hIf you specify your own start frame, make sure it's several frames in advance of the current frame. You might want this model if you're synchronizing ISO data with some other event stream.h]hIf you specify your own start frame, make sure it’s several frames in advance of the current frame. You might want this model if you’re synchronizing ISO data with some other event stream.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjn hhubeh}(h]#how-to-do-isochronous-iso-transfersah ]h"]&how to do isochronous (iso) transfers?ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h'How to start interrupt (INT) transfers?h]h'How to start interrupt (INT) transfers?}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hX'Interrupt transfers, like isochronous transfers, are periodic, and happen in intervals that are powers of two (1, 2, 4 etc) units. Units are frames for full and low speed devices, and microframes for high speed ones. You can use the :c:func:`usb_fill_int_urb` macro to fill INT transfer fields.h](hInterrupt transfers, like isochronous transfers, are periodic, and happen in intervals that are powers of two (1, 2, 4 etc) units. Units are frames for full and low speed devices, and microframes for high speed ones. You can use the }(hj hhhNhNubh)}(h:c:func:`usb_fill_int_urb`h]j7)}(hj h]husb_fill_int_urb()}(hj hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_fill_int_urbuh1hhhhMhj ubh# macro to fill INT transfer fields.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hThe :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented interval value that is less than or equal to the requested interval value.h](hThe }(hj hhhNhNubh)}(h:c:func:`usb_submit_urb`h]j7)}(hj h]husb_submit_urb()}(hj hhhNhNubah}(h]h ](jjBc-funceh"]h$]h&]uh1j6hj ubah}(h]h ]h"]h$]h&]refdocj refdomainjBreftypefunc refexplicitrefwarnjusb_submit_urbuh1hhhhMhj ubh call modifies }(hj hhhNhNubj7)}(h``urb->interval``h]h urb->interval}(hj. hhhNhNubah}(h]h ]h"]h$]h&]uh1j6hj ubh^ to the implemented interval value that is less than or equal to the requested interval value.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hX In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically restarted when they complete. They end when the completion handler is called, just like other URBs. If you want an interrupt URB to be restarted, your completion handler must resubmit it. sh]hX In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically restarted when they complete. They end when the completion handler is called, just like other URBs. If you want an interrupt URB to be restarted, your completion handler must resubmit it. s}(hjF hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]$how-to-start-interrupt-int-transfersah ]h"]'how to start interrupt (int) transfers?ah$]h&]uh1hhhhhhhhMubeh}(h](usb-request-block-urbheh ]h"](usb request block (urb)usb-urbeh$]h&]uh1hhhhhhhhKexpect_referenced_by_name}jb hsexpect_referenced_by_id}hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehÌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}h]hasnameids}(jb hja j^ jjj#j jjjjjjjjjk jh j j jY jV u nametypes}(jb ja jj#jjjjjk j jY uh}(hhj^ hjjj jjj&jjjjjjjh jj jn jV j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h-Hyperlink target "usb-urb" is not referenced.}hj sbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehÌlineKuh1j uba transformerN include_log] decorationNhhub.