From mboxrd@z Thu Jan 1 00:00:00 1970 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 kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5CC7CC77B7C for ; Tue, 24 Jun 2025 13:39:57 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 0B7A78D000E; Tue, 24 Jun 2025 09:39:43 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 03F8C8D0001; Tue, 24 Jun 2025 09:39:42 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id E24738D000E; Tue, 24 Jun 2025 09:39:42 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0016.hostedemail.com [216.40.44.16]) by kanga.kvack.org (Postfix) with ESMTP id B87318D0001 for ; Tue, 24 Jun 2025 09:39:42 -0400 (EDT) Received: from smtpin06.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay03.hostedemail.com (Postfix) with ESMTP id 7B2A8BA002 for ; Tue, 24 Jun 2025 13:39:42 +0000 (UTC) X-FDA: 83590401804.06.FA6D672 Received: from mail-wm1-f41.google.com (mail-wm1-f41.google.com [209.85.128.41]) by imf11.hostedemail.com (Postfix) with ESMTP id 683584000D for ; Tue, 24 Jun 2025 13:39:40 +0000 (UTC) Authentication-Results: imf11.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b=Ko62cojJ; dmarc=pass (policy=quarantine) header.from=suse.com; spf=pass (imf11.hostedemail.com: domain of ptesarik@suse.com designates 209.85.128.41 as permitted sender) smtp.mailfrom=ptesarik@suse.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1750772380; a=rsa-sha256; cv=none; b=cDnb1kDdm8Et6MtXGbLZpgrQKF+9CBd6nxMWhyaBfKkEsib1hchHb1QR66ZGM0v2CSXuDV LZ1TxBfGQCrXFsN7h/iIMVqjoKcDy7WgcSp9LeowJ0YUitIYjdFozEllRAiRi2SEefwMZj 2zh9DChrDsv2H28ThwOSblowlSy94jo= ARC-Authentication-Results: i=1; imf11.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b=Ko62cojJ; dmarc=pass (policy=quarantine) header.from=suse.com; spf=pass (imf11.hostedemail.com: domain of ptesarik@suse.com designates 209.85.128.41 as permitted sender) smtp.mailfrom=ptesarik@suse.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1750772380; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=4sx2Gr9jg00N7+zRyz0IpMFfOiCDQPryj3aB7m6WADE=; b=gGc1Aqm32h6GcFjZyQtHRLQKIj/JlSiqOiv0d8ABXuECxCw2Eitra+F5D3sBOsULNyac9R y/dL+c5Itq0Nza+p7LLXXkUtMk/7uUTZw/fBoSyIEH7kwn2Iq/YXaTxTfH9Rkcl2OwIV32 sf2Eq1TnIuwC134pp4EmgL1dnavJjeg= Received: by mail-wm1-f41.google.com with SMTP id 5b1f17b1804b1-45306976410so1905815e9.3 for ; Tue, 24 Jun 2025 06:39:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1750772379; x=1751377179; darn=kvack.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=4sx2Gr9jg00N7+zRyz0IpMFfOiCDQPryj3aB7m6WADE=; b=Ko62cojJXjJJ7/W/zhz6HfabxvDkL2rTGQ1ujYi4Z9dNBlO9D6Bgk4qRrS9M/kNL8c dCdF8RNCBgy8DsYjeYRAmGZWyiWu4Brwy2O9nPsp7BxyfqYkFSE2hLywIbwTM0LpxVp0 2y7RJQ4mstf2ZzXahsnF65IB6LQvYe/pzSABNOgGPwY5vS3JvTX1aw9eUSEBBnddBSmM Qk56yZmxdJtcNRVEKg8lQqJLuvj1y1npIQ6IUKC6jucdWSEAjFFm4Cs9Sfkn+X0wAc6F 1VeSjINnLj4ysEjsrG4AfRVvHV0W8MW7FXf52Y/vJdbTx8ELeR2aeFszAV053bmfmSyw V88A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1750772379; x=1751377179; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=4sx2Gr9jg00N7+zRyz0IpMFfOiCDQPryj3aB7m6WADE=; b=trigD/oc/LqkMFf0MknbMOjrpzhkeElGMtH5wxjftGwzr0wBMOWb0s2ceKvEc/f6PM uJ+qEOggeme760qsbDA3dWcpnMyHMr9mSvMfEg0cIFfBx+QkOgsyYJbwggPTw3AxhX3o eUG4xbmbD8aCNyn0sfJcUuz27vszLMJ9/PLx2MMy+AujzUnglR1I/rdOLrjZ3wx3B6NW pSi+CnZHfzlXbXVg3KRfyXmnwghzL08QVU30q6ArPxtvbhFHeQHjWGkf3evbieFVinHP ai+VPMaTTFRs0clcO9pFBcQ3dmy5MmyfKyshzV+j2hSSMuzyE7dNBOZHFcGPspoDMSKW TVBQ== X-Forwarded-Encrypted: i=1; AJvYcCUCoXSAJTYOcLtxdCLj6apSxIvRVubsmcsB0yPGfnY7D6YBSDVWofutb55WHNa0aK96BK88s//6DA==@kvack.org X-Gm-Message-State: AOJu0Yw82f+VCRcZzzI/JYjuxpezNaPAicHxv+qaInpvfGZsyZ6znLtd F3Jw9sN2B43V6CE1UzcrC9nyQEst0PBs66UJo/PluxtTSnrNoHH7pT7imTR+w8KStZs= X-Gm-Gg: ASbGnctUGIWI+2Mnr014XRlyYzGLYYO+U1ZqUA/d6MxgTMMwVn7IG8w1PErgGGqftgt +BnGtVgVxOWFKenZp+F6PKL2ZyF2dLmj59Bi8F3jjN6RL0p4DP1Yh33ToCDwJdsVGNlNhvu2Po1 NbyadSUjKXmFsGWJtxLLABjmRscpO508dvVBBqubB1dXH/zu9jhMtPG8frcTEt5nYVyY6HrarV2 bO2vkeWfTeDPNpL4kbuEi8pZf3U8LPX/MNW9dTEooKv6ZXgiXx31kxuMd/kZOtNlKpWJXvFfhdw HdUGoLPNfkxLkXxOAeg2nV309V7ztpNmJTTY8GO1ZeUgp/Z6r5oWEEL9hFOyhwoFeyUlCSsk+IH 11LAEmoAvcxtMQBn2eKlBOQbezuKs3WKsLWKStfGW+xbHEt3XQV6m X-Google-Smtp-Source: AGHT+IHjfatN3aA0WosLoWdQDyKydeoZw/uVFREpIVO7tEoIVnSxxs5IGUHXJ6h6lYlWKWIGlOYciQ== X-Received: by 2002:a05:600c:4e8a:b0:451:eed7:6d76 with SMTP id 5b1f17b1804b1-453659ca55cmr57962935e9.8.1750772378926; Tue, 24 Jun 2025 06:39:38 -0700 (PDT) Received: from localhost (dynamic-2a00-1028-83b8-1e7a-3010-3bd6-8521-caf1.ipv6.o2.cz. [2a00:1028:83b8:1e7a:3010:3bd6:8521:caf1]) by smtp.gmail.com with UTF8SMTPSA id ffacd0b85a97d-3a6e805100dsm2044971f8f.18.2025.06.24.06.39.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 24 Jun 2025 06:39:38 -0700 (PDT) From: Petr Tesarik To: Jonathan Corbet , Morton Cc: Marek Szyprowski , Leon Romanovsky , Keith Busch , Caleb Sander Mateos , Sagi Grimberg , Jens Axboe , John Garry , linux-doc@vger.kernel.org (open list:DOCUMENTATION), linux-kernel@vger.kernel.org (open list), linux-mm@kvack.org (open list:MEMORY MANAGEMENT), Petr Tesarik Subject: [PATCH 8/8] docs: dma-api: clean up documentation of dma_map_sg() Date: Tue, 24 Jun 2025 15:39:23 +0200 Message-ID: <20250624133923.1140421-9-ptesarik@suse.com> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250624133923.1140421-1-ptesarik@suse.com> References: <20250624133923.1140421-1-ptesarik@suse.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Rspam-User: X-Rspamd-Queue-Id: 683584000D X-Rspamd-Server: rspam10 X-Stat-Signature: 1a79jtxpk6bednzucnid1asf3drgu4mp X-HE-Tag: 1750772380-871987 X-HE-Meta: U2FsdGVkX195+uzVD4mE9CSTRMk3bMcfOHA4frdpc91DyM48OJONF+u7cOEJB0jBPNwJjnt1xwf51s4o8xDwdNOtD/jeGAWdpbCeVjk0g2J2Tz4SANxSyEyFRrhs8D3ZmoGn9hf6WXgBmAvCMMGbi3GhRDl3PN4ABT/lWH44mZamV35x9QjcAJ3Ojiob0hgb2gefkFnzd+6ZNdmYNm/ptl8d6qjy3zjkc12ONByUJP5YAtRuAfz/X2yeMAMN8iilUPHjYU0jz649FdMPA62X5uk5u7aaiRzynA3HN67+oVO+lkJEk9+QMQiZTV8eUAoNtWPOY9vyT8bwfLkQremZtnZbO2rwwK2Q1UbcwIiI3xnZv+fyEOtgzmMPygrhATKaaO+heQTmfOCnXiLdkThbWm/LOFRzVbJIEMT5p/gWYwFk7dlUI0PqEr+w/XxmTeP8HH8Z+TItCNWA/e61xx4X7F8wvdYoDq8944l1gOZcQ6P4xVP2tAI37UOBMpKBm+nSyeQdy8D2MPJ+gKPOTd9J7NvZVTQKh2b8c95BFG8EOgHuqip4RgkFApBGKuX5xd8/60wstXKV2JDvcZXZoCxKA6dATP4S3IlYirZt66MLDCIC5KlDC3Ma4l3zfgSG/cjk4PAEy7TfOcaVU5R61WRdahcn5K5s9eyGcYqI+mWRGPMnjqPlXNIQU7UWJwWLCLtsIlfoLmq7g4Fmvhh7b8SWe2o+Jb/9QyVoMzBvB0zD9hr+050XfeC/+HJXGMUSTVMGQIEwJXk9tnln9Ro8hOR9EvkJWVzHlmnTweJr89BI4SdVdMKYeuVEo+q7R+lyBtqlIKFB3SjHOMR/S/bnFvjM49mDicefPn8GkMFibFO1dQa08kCL8OtPw3zhEV39k4x65JdMkLGWBFr/1CpfT7lCEP5iWNvZ/jMP930YOneSsajG8UQNSsx1/rCa6u5MIKchpoTyRQfGxf2erIXvEba zm1dMKQd susn8JeeaiAqxRASaIgpIhFd9lLpza6Zg4tgQl25bdpXnw0Nji9ekZw5cqaxpFb78HDUjldN4RKy92tws/tiaMGCgGuowJ8FSsiz6EW/aAn+xTN4/aPLU7B+Kj2UeLzhCzgh8CLe8quCVZaDSJoEBPAM1mhbvUAq6QrWgMTCJgnlND9q2/O9NkJ91xcPGzJ0XcOHAI1qtKc69mzRXluty1o1i/2BLtL91QWS2GsNbo95l1qMIx/RSiIPUYboBzFC6hquX0Utqeavs+DwQKl6ZKYTfwBxiuxAkDj3WTIamuebKSdwTeOoTXVeKXY5HhMmqEVuShCSx7qmSPsWwy8EzrZzASugHr0TNPWNhIeonwxMov9w= X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: Describe in one sentence what the function does. Do not repeat example situations when the returned number is lower than the number of segments on input. Signed-off-by: Petr Tesarik --- Documentation/core-api/dma-api.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index 65132ec88104..f5aadb7f8626 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -308,10 +308,10 @@ action (e.g. reduce current DMA mapping usage or delay and try again later). dma_map_sg(struct device *dev, struct scatterlist *sg, int nents, enum dma_data_direction direction) -Returns: the number of DMA address segments mapped (this may be shorter -than passed in if some elements of the scatter/gather list are -physically or virtually adjacent and an IOMMU maps them with a single -entry). +Maps a scatter/gather list for DMA. Returns the number of DMA address segments +mapped, which may be smaller than passed in if several consecutive +sglist entries are merged (e.g. with an IOMMU, or if some adjacent segments +just happen to be physically contiguous). Please note that the sg cannot be mapped again if it has been mapped once. The mapping process is allowed to destroy information in the sg. @@ -335,9 +335,8 @@ With scatterlists, you use the resulting mapping like this:: where nents is the number of entries in the sglist. The implementation is free to merge several consecutive sglist entries -into one (e.g. with an IOMMU, or if several pages just happen to be -physically contiguous) and returns the actual number of sg entries it -mapped them to. On failure 0, is returned. +into one. The returned number is the actual number of sg entries it +mapped them to. On failure, 0 is returned. Then you should loop count times (note: this can be less than nents times) and use sg_dma_address() and sg_dma_len() macros where you previously -- 2.49.0