From patchwork Mon Dec 6 20:57:52 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: philipp hortmann X-Patchwork-Id: 522472 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id F0D58C433FE for ; Mon, 6 Dec 2021 20:57:57 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1349966AbhLFVB0 (ORCPT ); Mon, 6 Dec 2021 16:01:26 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54704 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1349957AbhLFVBZ (ORCPT ); Mon, 6 Dec 2021 16:01:25 -0500 Received: from mail-wm1-x331.google.com (mail-wm1-x331.google.com [IPv6:2a00:1450:4864:20::331]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D36C8C061746; Mon, 6 Dec 2021 12:57:55 -0800 (PST) Received: by mail-wm1-x331.google.com with SMTP id i12so9140972wmq.4; Mon, 06 Dec 2021 12:57:55 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=HP8SKA09sXO9NSVfX3UQ4Y1Z+0wRgCYWOwD6pVkBing=; b=IxnIWTVAz+ekMsTnsuiEWfIaiRpsnREU+/L7Fgk+Vkc/dCjlnasjva2vyrvOaibCOV mkrFI1T4vTvagMtvMVNUJWNPHUs21sKKUDZWxZ2NcPTVpw3v8UgdPCvGRpil4hkcTWPC C8gqC5fyzcKPhpvMwfbTnhFAmHN01mnCaTlyH72uhvvRnV764Rad4BERhwkh3s4KSjaN QibnSXICZU+3hgOoK/XlQM8nmJ3OlAH1fsq1OqPSVCQ3AFBBC4mqHY7sEHriZYJudkkL RUrb09SYnkHaBbelTrc5DaUmWuwji80J10ZdXvxh8zySrnFgIBiV/prulaHN4U1eoGyu ODuA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=HP8SKA09sXO9NSVfX3UQ4Y1Z+0wRgCYWOwD6pVkBing=; b=UvnUEcFdCnE/nTi8qnnHqbdxlxXHHiOVnObMUWS4R1qK81N+L4NLOtLk4maOHcuJFx QRe8JmQptNpZxZjoDSqsi2PsE8wi0WawmPrsv5u4li6Mh416mPtg8AgpRJuw5j6V+vEc iwE1U5M3ke7WNT0hHLJkbUakWJMyrpm6og7GnfVdcejtu3L6xezJtCOh328nKbGOs8xo Al4jARKu/0f2aWU92qBiYVwa7KFwK4UQlMcQTv52wP89w18WfFKga3z/0mPn1CJ04d04 fOqsajJsBCIaIIGKee9IoOCBaJEKjiAKoEbOptuTKg0O2wIchLRuv+Mq5thFyKHPpEt5 PO/w== X-Gm-Message-State: AOAM533ZCO65s42ITBE5sjRiop2BLePYDCcavO88gl6FmjjZ1ngsDMPB MwkxdxQwRmB+45siGUyVKEA= X-Google-Smtp-Source: ABdhPJzQ/eqF4ADe1MjYVK9V8uA61GeT0FHVneXcmHMfXu9Ta31/XXek4zy85vMhDf/9La3Mxzzn5g== X-Received: by 2002:a7b:c194:: with SMTP id y20mr1274003wmi.2.1638824274448; Mon, 06 Dec 2021 12:57:54 -0800 (PST) Received: from matrix-ESPRIMO-P710 (p200300c78f4e06972f325cc5fe1c0146.dip0.t-ipconnect.de. [2003:c7:8f4e:697:2f32:5cc5:fe1c:146]) by smtp.gmail.com with ESMTPSA id l26sm500587wms.15.2021.12.06.12.57.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 06 Dec 2021 12:57:54 -0800 (PST) Date: Mon, 6 Dec 2021 21:57:52 +0100 From: Philipp Hortmann To: corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: linux-usb@vger.kernel.org, gregkh@linuxfoundation.org Subject: [PATCH v3 1/5] Docs: usb: update usb_bulk_msg receiving example Message-ID: <3b794ef1936eb410b60cb536e47a0a00e36611d4.1638771720.git.philipp.g.hortmann@gmail.com> References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-usb@vger.kernel.org Clarification that this example is not in the driver template anymore. Update code example so that it fits best to usb-skeleton.c Signed-off-by: Philipp Hortmann --- V1 -> V2: Added "Update format of function names" to patch description Corrected format of function names like the following example: "`usb_bulk_msg` function" to "usb_bulk_msg()" V2 -> V3: Moved corrections of the function name to an own patch in this patch series Took back change of variable from retval to rv --- .../driver-api/usb/writing_usb_driver.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index b43e1ce49f0e..1fd7bf1dbdb0 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -218,7 +218,7 @@ do very much processing at that time. Our implementation of ``skel_write_bulk_callback`` merely reports if the urb was completed successfully or not and then returns. -The read function works a bit differently from the write function in +This read function works a bit differently from the write function in that we do not use an urb to transfer data from the device to the driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used to send or receive data from a device without having to create urbs and @@ -229,25 +229,25 @@ receiving any data from the device, the function will fail and return an error message. This can be shown with the following code:: /* do an immediate bulk read to get data from the device */ - retval = usb_bulk_msg (skel->dev, - usb_rcvbulkpipe (skel->dev, - skel->bulk_in_endpointAddr), - skel->bulk_in_buffer, - skel->bulk_in_size, - &count, 5000); + retval = usb_bulk_msg(dev->udev, + usb_rcvbulkpipe (dev->udev, + dev->bulk_in_endpointAddr), + dev->bulk_in_buffer, + dev->bulk_in_size, + &len, 5000); /* if the read was successful, copy the data to user space */ if (!retval) { - if (copy_to_user (buffer, skel->bulk_in_buffer, count)) + if (copy_to_user (buffer, dev->bulk_in_buffer, len)) retval = -EFAULT; else - retval = count; + retval = len; } The :c:func:`usb_bulk_msg` function can be very useful for doing single reads or writes to a device; however, if you need to read or write constantly to a device, it is recommended to set up your own urbs and submit them to -the USB subsystem. +the USB subsystem. The template uses urbs for read and write. When the user program releases the file handle that it has been using to talk to the device, the release function in the driver is called. In From patchwork Mon Dec 6 20:57:58 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: philipp hortmann X-Patchwork-Id: 521242 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 267DEC433EF for ; Mon, 6 Dec 2021 20:58:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1349980AbhLFVBc (ORCPT ); Mon, 6 Dec 2021 16:01:32 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54742 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1349944AbhLFVBa (ORCPT ); Mon, 6 Dec 2021 16:01:30 -0500 Received: from mail-wm1-x334.google.com (mail-wm1-x334.google.com [IPv6:2a00:1450:4864:20::334]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8D056C0613F8; Mon, 6 Dec 2021 12:58:01 -0800 (PST) Received: by mail-wm1-x334.google.com with SMTP id i12so9141126wmq.4; Mon, 06 Dec 2021 12:58:01 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=n1BPb/xYNq5uaSEPzD+4FghbzJv0Q/8If9Mqaicr6qI=; b=WZjBMyXZESGunyh9UbdimRNbU77++G6ojMueTs+jjMbXTl9bdOfuDRT2rXwFI4DBxC od0HjK2ICjreVMEu1LsL7xFOk4aE4V2mmOfnt3u0Fu1pHLpAkc3g0hUkmQBujsYEdTjq vzawGH2eCZhUm7Rwcne7LUWlWr1SbY/bMiX/Ax7FKjMF6RTb9EOqoE8wDjmqfIvbYouj cM6MUpvdmHqLIPxXrzCB9pfStlRcLfeLuGo/x0QbTqSHjz4l2DXCDZSvYBDdiqujhCSB xCycVui+MxZxOZyBtbTSF1LHbNsqb2/4cy7vwvpTOgvu04UY8FzXC8Im0B6tpFq646kc 3oag== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=n1BPb/xYNq5uaSEPzD+4FghbzJv0Q/8If9Mqaicr6qI=; b=XlV3Xg5WyN0VL7dl8tK19+fKcp24Yw/upEeruwmOxJcG71GKc22wBUbIhMRBcJBnSw TOjM+QA8HM82fqqR2cnGTiULjxw9cAf47niV9WUlYoklyLB2qIFEe3Zu3KpMQUrLCepL DVL8UHVx0Rbyhmg5KnB9zjR8nJFudfkH1TYujiHbmeIwbf51t58zdsdJoEQZQeSxT/7D 1i0YVJHDx5bGOKqo0AFLBIy6PkX0hHXgYTGYVUUn2rj4Tk6S1310DWK7DDQbSolWnVvq QH82RhTQJFu5PwMhkPgTZuZe5M3rOtGCYeoFdWg4wnc3UZp0XySxBXtJYIy4pWEC4ToM nuAA== X-Gm-Message-State: AOAM532AKyDrzESy13GT+r/cuMQ3V2tWka9tUh1UV4pDdCUiJAyQP5Il dZaI+RuSmnsf7f6wf+iq0CAaM7NtqwNLhA== X-Google-Smtp-Source: ABdhPJwIwVkZi4QOIq6rIMRFZMYenWd2/mDUnEveInUHh+/OYBkw2bSkdY86H9qUkQTSFN80wvsWTQ== X-Received: by 2002:a05:600c:1d91:: with SMTP id p17mr1196223wms.193.1638824280148; Mon, 06 Dec 2021 12:58:00 -0800 (PST) Received: from matrix-ESPRIMO-P710 (p200300c78f4e06972f325cc5fe1c0146.dip0.t-ipconnect.de. [2003:c7:8f4e:697:2f32:5cc5:fe1c:146]) by smtp.gmail.com with ESMTPSA id j40sm469413wms.19.2021.12.06.12.57.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 06 Dec 2021 12:57:59 -0800 (PST) Date: Mon, 6 Dec 2021 21:57:58 +0100 From: Philipp Hortmann To: corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: linux-usb@vger.kernel.org, gregkh@linuxfoundation.org Subject: [PATCH v3 2/5] Docs: usb: update comment and code near decrement our usage count for the device Message-ID: References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-usb@vger.kernel.org Update comment: decrement our usage count .. and code according to usb-skeleton.c Signed-off-by: Philipp Hortmann --- V1 -> V2: Corrected format of function name to skel_release() V2 -> V3: Moved correction of the function name to an own patch in this patch series --- Documentation/driver-api/usb/writing_usb_driver.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 1fd7bf1dbdb0..c336dfd82426 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -254,8 +254,8 @@ talk to the device, the release function in the driver is called. In this function we decrement our private usage count and wait for possible pending writes:: - /* decrement our usage count for the device */ - --skel->open_count; + /* decrement the count on our device */ + kref_put(&dev->kref, skel_delete); One of the more difficult problems that USB drivers must be able to From patchwork Mon Dec 6 20:58:03 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: philipp hortmann X-Patchwork-Id: 522471 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4A8CBC433EF for ; Mon, 6 Dec 2021 20:58:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1350022AbhLFVBk (ORCPT ); Mon, 6 Dec 2021 16:01:40 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54770 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1350024AbhLFVBg (ORCPT ); Mon, 6 Dec 2021 16:01:36 -0500 Received: from mail-wm1-x32b.google.com (mail-wm1-x32b.google.com [IPv6:2a00:1450:4864:20::32b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8CE21C061359; Mon, 6 Dec 2021 12:58:06 -0800 (PST) Received: by mail-wm1-x32b.google.com with SMTP id 133so9203877wme.0; Mon, 06 Dec 2021 12:58:06 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=/6TXMCjmZMjMTXVDAGqRENQL5FuXlJEx6FcJui0lUVI=; b=nrax9v2Tf28pHs4A+QcLepaXnYTnUIjOzRA8KmSXbjCYQRRqNDDugbbzeKKfT6vh2h oPoW8D1XnxZi0c+CHt8KWiNCwanM126NPz/pDLkhAo9oEnSjueDAoIWQuhZxZaR1cnw/ gQeNuQUL/M9BK47V6oCDQtFbGZKbcaawdx5O+W1jCNXHKVsGDgjQHdUc92JyHgMBlOUS DuSbN0KA9gdqM71iVVXC6hAzLcf1GUOwLXiEs4bhzFQGuyiWEBwstn7haPy70rHT9tGu 3mQfJrh3BJbDPbQSymzv8A/8TDBMhvyOPGIg2khpEvSSf12tHpxcuq82RPmR5bLAVbPw i/IQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=/6TXMCjmZMjMTXVDAGqRENQL5FuXlJEx6FcJui0lUVI=; b=B8uo3QmiZ4AABEUx+SWQTuLsRqso4VHSDK2GjG5e6ka3rKc+1gHE7y/I3nZXwtkiBL UFmcH32B/VRn/opB2lJTBIHf0iW0/LDelg+eKvkJieq6fhq6Gppa6G2ycCdl9L7BrlZS 1TgGb0Ck2LpbG0+8yngZsvo+Z0u56Ydp5HO4wHHD3M7R4cdlWnp93r/AMoRm+tnOZGO1 vLeSXF1WmbuO5H3Foy/bI1tIHwQRUuqx+x7Ve+JyD1id8pLZQFHk5EXsk3TM/Rl3TQtN BZVqvMjF/20OUaY+Ubope+Mq1kGZRf3i2QxAXKdUjsFGEtYIejT3SLHccaJRg34+k7sb oF/A== X-Gm-Message-State: AOAM531ksQFSo614ga7WW9cObIwnhDKcyxbedjdvZFd0uRXgvkqXNpLy A23Ndwbg9kfrA3/JkmL0WYk= X-Google-Smtp-Source: ABdhPJyaB0FMJEEgxGGhPArvXaTPcwiHc1ly+78X900aejXIq13cB1WjtUvs2NxK1zXwF2xw1z4IzQ== X-Received: by 2002:a7b:cc94:: with SMTP id p20mr816726wma.162.1638824285171; Mon, 06 Dec 2021 12:58:05 -0800 (PST) Received: from matrix-ESPRIMO-P710 (p200300c78f4e06972f325cc5fe1c0146.dip0.t-ipconnect.de. [2003:c7:8f4e:697:2f32:5cc5:fe1c:146]) by smtp.gmail.com with ESMTPSA id u15sm490981wmq.13.2021.12.06.12.58.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 06 Dec 2021 12:58:04 -0800 (PST) Date: Mon, 6 Dec 2021 21:58:03 +0100 From: Philipp Hortmann To: corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: linux-usb@vger.kernel.org, gregkh@linuxfoundation.org Subject: [PATCH v3 3/5] Docs: usb: update comment and code of function skel_delete Message-ID: References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-usb@vger.kernel.org Update code according to usb-skeleton.c Signed-off-by: Philipp Hortmann --- V1 -> V2: Corrected format of function name to skel_delete() V2 -> V3: Moved correction of the function name to an own patch in this patch series --- .../driver-api/usb/writing_usb_driver.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index c336dfd82426..6c487ac5eab2 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -266,15 +266,15 @@ notify the user-space programs that the device is no longer there. The following code (function ``skel_delete``) is an example of how to do this:: - static inline void skel_delete (struct usb_skel *dev) + static void skel_delete(struct kref *kref) { - kfree (dev->bulk_in_buffer); - if (dev->bulk_out_buffer != NULL) - usb_free_coherent (dev->udev, dev->bulk_out_size, - dev->bulk_out_buffer, - dev->write_urb->transfer_dma); - usb_free_urb (dev->write_urb); - kfree (dev); + struct usb_skel *dev = to_skel_dev(kref); + + usb_free_urb(dev->bulk_in_urb); + usb_put_intf(dev->interface); + usb_put_dev(dev->udev); + kfree(dev->bulk_in_buffer); + kfree(dev); } From patchwork Mon Dec 6 20:58:08 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: philipp hortmann X-Patchwork-Id: 521241 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id C2AD7C433FE for ; Mon, 6 Dec 2021 20:58:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1350024AbhLFVBt (ORCPT ); Mon, 6 Dec 2021 16:01:49 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54812 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1350030AbhLFVBm (ORCPT ); Mon, 6 Dec 2021 16:01:42 -0500 Received: from mail-wm1-x335.google.com (mail-wm1-x335.google.com [IPv6:2a00:1450:4864:20::335]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E3905C061359; Mon, 6 Dec 2021 12:58:11 -0800 (PST) Received: by mail-wm1-x335.google.com with SMTP id 133so9204014wme.0; Mon, 06 Dec 2021 12:58:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=E2HX35lv9bDKnO4lFBuFX4Xmi03jMOcJniXoHiK6jHU=; b=ObjPGxXgS47W+YxYmtgbzwuUFSn4MvSUvTt4Xrt+pM+JmRdW1YWOgPT3/FOqxWUVu9 Kxmot+F0OK6WerWjqgeAG0SCkegY6q6+m0HHWNT+pntDuX/kY5KdVmAaSMNxTqfSLULx HhUt8fDGT+qNAJQuaYem55yhQnEEC+8TcK7hbaYonoNJKiw6bGs5TO94APQ4OcckKyql TKOG93OWHjKeIzvERDdyG1oUgUc7Sqg9m10qP7SagfjGvuVJoer2Q0emhDWOK1KvjyFz AQsHAZTz/a59H424e6UdVJwcIXG11WWpWRWWkw0BeGXO+2rj58UsT4SqCMOKwsbPVBNy Fpbw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=E2HX35lv9bDKnO4lFBuFX4Xmi03jMOcJniXoHiK6jHU=; b=vvoucsmdhDYVMIe9lwDwFD8MgpG5pBt+B+8+E/oqNTF83eSDvxRe3iPT0MC10+ir9n jg5lFsZ26AiW2uBaSo9uegfqdmxBcaOcBwclK/pMBi4Lt4IRRW1cbZhPJa/md3bifY7D YbupcDLyXsEzryuzLalZc08834gF8nw0IFQN2m8fJtMFchaD1XEXIgTF85HbYeJ5dHN/ XpSvnimcf2DMgpYV1V3l/2/pVKutN0/ML1stpf7X4ECkRGT25e7N55CnxVlkub+iG0ps 2sWDwVVE+l0JlKV2p9lcvTkPKdRcAeRivVnjTig8HJkJZzrsa/DVZFBUItWs+u/0AdwM PFCw== X-Gm-Message-State: AOAM531vsrofXwD3e1Qr8QjvO+uoyL6jjFWSNCmbxKxODj3B7xk9nP14 Vl9vp0wWE/ZhtK9G8t1dsUo= X-Google-Smtp-Source: ABdhPJxtK0kucM1mh5Rovcj6r5jVVtCJ9DnMzIl3ZDlqesq9IJuz6HyW+Y+QbuwpE44oC5Yf7Q30yg== X-Received: by 2002:a1c:1903:: with SMTP id 3mr1205934wmz.89.1638824290575; Mon, 06 Dec 2021 12:58:10 -0800 (PST) Received: from matrix-ESPRIMO-P710 (p200300c78f4e06972f325cc5fe1c0146.dip0.t-ipconnect.de. [2003:c7:8f4e:697:2f32:5cc5:fe1c:146]) by smtp.gmail.com with ESMTPSA id l11sm11806981wrp.61.2021.12.06.12.58.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 06 Dec 2021 12:58:10 -0800 (PST) Date: Mon, 6 Dec 2021 21:58:08 +0100 From: Philipp Hortmann To: corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: linux-usb@vger.kernel.org, gregkh@linuxfoundation.org Subject: [PATCH v3 4/5] Docs: usb: update explanation for device_present to disconnected Message-ID: References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-usb@vger.kernel.org Update text for `device_present` flag to `disconnected` flag Signed-off-by: Philipp Hortmann --- V1 -> V2: Corrected format of function name to skel_disconnect() V2 -> V3: Moved correction of the function name to an own patch in this patch series --- .../driver-api/usb/writing_usb_driver.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 6c487ac5eab2..1968cf5c55f6 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -278,15 +278,13 @@ this:: } -If a program currently has an open handle to the device, we reset the -flag ``device_present``. For every read, write, release and other +If the driver probed the device successfully, the flag ``disconnected`` +is initialized and set to false. For every read, write and other functions that expect a device to be present, the driver first checks -this flag to see if the device is still present. If not, it releases -that the device has disappeared, and a ``-ENODEV`` error is returned to the -user-space program. When the release function is eventually called, it -determines if there is no device and if not, it does the cleanup that -the ``skel_disconnect`` function normally does if there are no open files -on the device (see Listing 5). +this flag to see if the device is still present. If not, a ``-ENODEV`` +error is returned to the user-space program. When the device is +disconnected, the ``skel_disconnect`` function is called. It sets +``disconnected`` to true and cleans up. Isochronous Data ================ From patchwork Mon Dec 6 20:58:14 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: philipp hortmann X-Patchwork-Id: 522470 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id C6E0EC433FE for ; Mon, 6 Dec 2021 20:58:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1350030AbhLFVBz (ORCPT ); Mon, 6 Dec 2021 16:01:55 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54840 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1350115AbhLFVBr (ORCPT ); Mon, 6 Dec 2021 16:01:47 -0500 Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7B411C061D60; Mon, 6 Dec 2021 12:58:18 -0800 (PST) Received: by mail-wr1-x42b.google.com with SMTP id i5so25092035wrb.2; Mon, 06 Dec 2021 12:58:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=DK4hAvvrL0g/m+zIiQELRMmxA9g3fGN68aSymQFpmw4=; b=ns+q3Q5a/YFhnnV6OVF+Mt3rUmr9uxUqqFynmSsthxdw9baWp1zLvrtmq2p5CHftOV M+7f1l6wrmMQyHblMftzJnSeGXh++0iiymEaqZ9TkqnGyxzpdhZGU7rEj1Zyp5H2FLDc grQd1lN/zGijD2p+r8brP/JZaAB49ZhBkfWIiB+KcQphK2LpzrY9G8XFFQHD8tZqwXY+ hycl6tWZMSPLYXpqGHZWA0AJtaIShzSKUmQg917UdzCOe1aMKmUAxc2dhWvVthKSDIkK 5em8JyL+2RhW7hQHDVGp1JPG6WVvTXoOM1YqCEvD9GOtMQjEAreFdRs8vAWksKSoQcqu Cmyg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=DK4hAvvrL0g/m+zIiQELRMmxA9g3fGN68aSymQFpmw4=; b=KvDoR4ODh5Frgnx0+h0+6JSO1xNYp/1qz9U2HzZALkgJ48eGgS4KrBNoUwMFR8oPSF UoK+/MRRwmwMiO2gyl5nW/mxyrWlvLoD8xxpgaLRpqYczjJ0+l3XWULGc7PDlybfApky EFFElAojwFBSDSr/wmOk+4H93qAozaoQ0JOue/MENVaHnO3zvKiUCuVyyYJtJPfR3ZAC Hwg/eGQWGLy+ZDNj66JJnVbx71Rm6IckenHDmgmNMsSgO9ss5q106lA4cSkj4rxFuS5U K8crGVjE3GSB8cRXD5lZjseR4uxbJboSyzXAu3OFH1qfvW34d9odeRwJs/Jn5Ovw+7Ub 5GcQ== X-Gm-Message-State: AOAM533zOXXq8WepcHatAaaFOGpCVZyWfomh9/PFQ9a1JI8Y9h2T7h1y G+wvgpfRUOxQ+we5AbtVofE= X-Google-Smtp-Source: ABdhPJwnO0TTqOoGSYCkB3lOmDvLnLodImOh+yQ3A1lfhP6Q0C/PqnUKVp5NE/Atd4UObejQZ5WWlA== X-Received: by 2002:adf:e747:: with SMTP id c7mr46458155wrn.38.1638824297093; Mon, 06 Dec 2021 12:58:17 -0800 (PST) Received: from matrix-ESPRIMO-P710 (p200300c78f4e06972f325cc5fe1c0146.dip0.t-ipconnect.de. [2003:c7:8f4e:697:2f32:5cc5:fe1c:146]) by smtp.gmail.com with ESMTPSA id az15sm454600wmb.0.2021.12.06.12.58.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 06 Dec 2021 12:58:16 -0800 (PST) Date: Mon, 6 Dec 2021 21:58:14 +0100 From: Philipp Hortmann To: corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: linux-usb@vger.kernel.org, gregkh@linuxfoundation.org Subject: [PATCH v3 5/5] Docs: usb: correct format of function names in the explanations Message-ID: <6ef296c812baabd973e5ae7b661b1620d5fd45be.1638771720.git.philipp.g.hortmann@gmail.com> References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-usb@vger.kernel.org Correct format of function names like the following example: "`usb_bulk_msg` function" to "usb_bulk_msg()" Signed-off-by: Philipp Hortmann --- .../driver-api/usb/writing_usb_driver.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 1968cf5c55f6..9f4181cafc41 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -220,10 +220,10 @@ successfully or not and then returns. This read function works a bit differently from the write function in that we do not use an urb to transfer data from the device to the -driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used +driver. Instead we call usb_bulk_msg(), which can be used to send or receive data from a device without having to create urbs and -handle urb completion callback functions. We call the :c:func:`usb_bulk_msg` -function, giving it a buffer into which to place any data received from +handle urb completion callback functions. We call usb_bulk_msg(), +giving it a buffer into which to place any data received from the device and a timeout value. If the timeout period expires without receiving any data from the device, the function will fail and return an error message. This can be shown with the following code:: @@ -244,13 +244,13 @@ error message. This can be shown with the following code:: } -The :c:func:`usb_bulk_msg` function can be very useful for doing single reads +usb_bulk_msg() can be very useful for doing single reads or writes to a device; however, if you need to read or write constantly to a device, it is recommended to set up your own urbs and submit them to the USB subsystem. The template uses urbs for read and write. When the user program releases the file handle that it has been using to -talk to the device, the release function in the driver is called. In +talk to the device, skel_release() in the driver is called. In this function we decrement our private usage count and wait for possible pending writes:: @@ -262,9 +262,8 @@ One of the more difficult problems that USB drivers must be able to handle smoothly is the fact that the USB device may be removed from the system at any point in time, even if a program is currently talking to it. It needs to be able to shut down any current reads and writes and -notify the user-space programs that the device is no longer there. The -following code (function ``skel_delete``) is an example of how to do -this:: +notify the user-space programs that the device is no longer there. +skel_delete() is an example of how to do this:: static void skel_delete(struct kref *kref) { @@ -283,8 +282,8 @@ is initialized and set to false. For every read, write and other functions that expect a device to be present, the driver first checks this flag to see if the device is still present. If not, a ``-ENODEV`` error is returned to the user-space program. When the device is -disconnected, the ``skel_disconnect`` function is called. It sets -``disconnected`` to true and cleans up. +disconnected, skel_disconnect() is called. It sets ``disconnected`` +to true and cleans up. Isochronous Data ================