From nobody Tue Nov 26 02:00:42 2024 Received: from mail-pg1-f180.google.com (mail-pg1-f180.google.com [209.85.215.180]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 2A63A1448DF; Wed, 23 Oct 2024 05:34:05 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.180 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661646; cv=none; b=GjIjr46Pi7so5/SFZ0+kPoj7zeV/pHkXv8mGJkRdfh18JMcSv7Fg2rdXjVbEob3YzlBHjOTCha61CRBkC1YOsQKBOom3pExeZy7fjXIYBOp5qBbI1ro8ouOwqn70CjBnvVUICHocypL03aNTY7PXqLE2yUxVdNU9cL+JWIKdyLI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661646; c=relaxed/simple; bh=zJEvpa9INE9yXtYQiz3469DzQraDqTRRxFPVZ6a8zxg=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=FkhqBR009DzkW6+Bz72SQ2GM8lWitEPpOi4ARmp7OYgBX76AqIMAu+phBPrak7pel4h2z4qsnBUXw56yS+kqblETD5+UdRWKMskscUwu4Tr1qjV7sdAlr/p5dO3YR9fWXUnc6arFkN30Y1Q+OJQi5olQj06ZlwqDXAieEiiTq60= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=PBORMLOh; arc=none smtp.client-ip=209.85.215.180 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="PBORMLOh" Received: by mail-pg1-f180.google.com with SMTP id 41be03b00d2f7-7ea0ff74b15so4177551a12.3; Tue, 22 Oct 2024 22:34:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729661644; x=1730266444; darn=vger.kernel.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=76j18HLREuq6z2ueP2pra56wnYMu3LZ3kaThEHsixtw=; b=PBORMLOhM4b5SiPo2mpASFANR072bTG+MM5yzK32D+DjxItYdK9Jod6jFDI+mtTpQt hDKJmEDbegQaWVapVNEzexzRnTnoTjdmFpPjTbDiEDK7OUlAXIUCRb0tGVfnu7IXEoA7 fs2yl/D5f1B8vmOI/c1e6Bd6K8I0YKtV4BK5x8LjBXKfunXYvMF36cAfCg8AMItknqDX SAIyJzgeJdz3KcQ7vdVEcF8DwQFDplM+A61M08z8pHNdhrQ7OI25khN1rawQiT3NVuIf RI4qpqsfqpal29qO0pbmN7TXGYYUzkepkUcaY8EY61rK487zQKw3aZNdhKqoI55jF/MW gD1A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729661644; x=1730266444; 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=76j18HLREuq6z2ueP2pra56wnYMu3LZ3kaThEHsixtw=; b=cL17SDAEUgAdFhU83tZjKNR40JNwwHPP7fdUoPUHI0b4ytVYJq120eOQ387AaCmAQJ +EEsVC3+p4eVEA/P2B5jPxatYiKz56VRZU0E7HO6p3wut1KHfrsRwa1sNVQkPC0LXJp1 TIYKmJ7TL4aPI2UqgeQKCZGUMQO7gzRYyBw6FawW5APwaz/1tU6E8F4gR/pxqtTLBcgx 2cyfIytv42srdtZ4KKBq2FQqyb43Pbid5LWdiGsT8HIMAq/TGxGPQZu8FWhRdJU14fVS kjzlrxyQm8IbaCgDvGuKL7fSqUhVKHYhNOvp8IF6PMkFH6k5LgL+9g2GInm7/O9RU6/f Kq6w== X-Forwarded-Encrypted: i=1; AJvYcCU9Ot35jtFxl+VB/npJxVmEYebhmLYSbidQLjwW0DpN9WM7rXNPi8NLjclJRWSvX0Wq48wrs+NUQDs=@vger.kernel.org, AJvYcCVqG1BNpTQkdueo2F6yuMqgn7uTL+EOL0R6cFd1mLaHNuFHoS/QsuaVjTLsj/TUGy758nqyCN5Uw7GCCybE@vger.kernel.org X-Gm-Message-State: AOJu0Yx3Z3qke9s7ZeIcqqvECIWFxoa/A0OChc7NkC0nYs8/Aq+u9bXi k+3aBh/HWPSfqNOQ/dpO7gRqxtjmeW0DI8K9iHBB6+N4w0C/21D0 X-Google-Smtp-Source: AGHT+IGdw4eXSwqHJ23qEQRaHPAi+TZFQJoJ4sh7IaI1ZrE0an07kAb8bFiyDgKdfpXKcq6kyzRB4A== X-Received: by 2002:a05:6a21:9208:b0:1d8:a49b:ee71 with SMTP id adf61e73a8af0-1d978b32745mr1696241637.29.1729661644438; Tue, 22 Oct 2024 22:34:04 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e76e0877a6sm428695a91.54.2024.10.22.22.34.02 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 22:34:03 -0700 (PDT) From: anish kumar To: ohad@wizery.com, bjorn.andersson@linaro.org, mathieu.poirier@linaro.org, corbet@lwn.net Cc: linux-remoteproc@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, anish kumar Subject: [PATCH V4 1/7] Remoteproc: Documentation: add the main index Date: Tue, 22 Oct 2024 22:33:51 -0700 Message-Id: <20241023053357.5261-2-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241023053357.5261-1-yesanishhere@gmail.com> References: <20241023053357.5261-1-yesanishhere@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" In prepration of moving the remoteproc documentation from staging to mainline and also for enhancing the documentation. Signed-off-by: anish kumar Reported-by: kernel test robot --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/remoteproc/index.rst | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 Documentation/driver-api/remoteproc/index.rst diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/= index.rst index c57c609ad2eb..ec9d669b92e5 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -30,6 +30,7 @@ available subsections can be seen below. frame-buffer regulator reset + remoteproc/index iio/index input usb/index diff --git a/Documentation/driver-api/remoteproc/index.rst b/Documentation/= driver-api/remoteproc/index.rst new file mode 100644 index 000000000000..8b8c8f512e2b --- /dev/null +++ b/Documentation/driver-api/remoteproc/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +remoteproc - remote processor subsystem in Linux(TM) kernel +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Authors: + - anish kumar + + remote processor subsystem is a way to manage the lifecycle of + a subsytem that is external to the Linux. The remoteproc framework + allows different platforms/architectures to control (power on, + load firmware, power off) those remote processors while abstracting + the hardware differences, so the entire driver doesn't need to be + duplicated. + +Mailing List +------------ +To post a message, send an email to +linux-remoteproc@vger.kernel.org --=20 2.39.3 (Apple Git-146) From nobody Tue Nov 26 02:00:42 2024 Received: from mail-pf1-f171.google.com (mail-pf1-f171.google.com [209.85.210.171]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D37301465BA; Wed, 23 Oct 2024 05:34:06 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.171 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661648; cv=none; b=JMpJFvvHpYleVNIlPaqLgt+/zg+zSHLwNmIbWmh9M7e5ydUBCaybfyzcd3kEzKpwYv3BFXZAlCztED6OJL0n842haXGUTWX3kYq86FCw20Lc+UtvAfWlp+NUqllxnPJVlSUYPRFIhbyTh+QMfaJawV39iwFxhr88qRPqA8FTQSE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661648; c=relaxed/simple; bh=F9wyVBaF0oSJbY/ZwpGmuvQ3WfCyLVP5YNotULhlD4w=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=qjxeZ7Lf3zuFG69xkQKOJs5Cw+DT71eVP9HcFdN2/mhdJE5XRI8dGEGjXy0tPBcef/NGgxcjPK92AY96JBTpyFSPCV5a7BGcTvAMszm0Cq62l7QIAvcYvVxwXus/oiLGdmLjCyKOM7Vv7DsubK0KhrdKsFPAmInniI04Eb6i5zo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=YtWb+2Sq; arc=none smtp.client-ip=209.85.210.171 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="YtWb+2Sq" Received: by mail-pf1-f171.google.com with SMTP id d2e1a72fcca58-71e592d7f6eso4184036b3a.3; Tue, 22 Oct 2024 22:34:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729661646; x=1730266446; darn=vger.kernel.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=d4H28hFRgfMxE6n6xvKEknwZOvdBzOexKEGHxbARteQ=; b=YtWb+2SqtQA0ZuYLG1tWshZIb+sqv4+E/f8YYw6/VkvOPkkK/cAVCtiwc2b3EjBHqo zQLCa4tVwMi8mBSxxnhLHtFm+9FUwb19Bo13q0MLj940Aho4G8KgJgcZ2GGTGTpbDswT AAlP3L3mzKQzChUD5pqAtXaeO3Dajx9JW09LHYwtU64iFzPr+ZXPd+T9zm9b8LMQ7w8C NWEwOr/dnvh4xsJhQaa/DqIy9C3xZ+HK0OsPx+8rc6/wKWxjW51PZT67les5eQkoGdmV uSxflEgEW4SQ6vzKyrC7yLrn9uyUuNEVpnwWckbzH107R7hGi9ucS4w4j83VyQH5yTly ZmsA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729661646; x=1730266446; 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=d4H28hFRgfMxE6n6xvKEknwZOvdBzOexKEGHxbARteQ=; b=g/gWzQ9o9kWKihNUERRUT0pHLsj6gq12yE3aSgAEBjElQsyhKoRFXcXrm0u6ay+J/I WVQb5I9nFKo3sDbvtzY3yrEYLjI+5SjP7q94uhietG1+5BR1vL470joV3Fsvl4ltzgNf 4ydErgentwmUsO9KDktFocvYD1FLEDLAwQjHZi/KOM2Tr/W4lPTTPpzghmmgB+G2IazH gHOZE4DuvKTgBDmK1ZfXJ9Vl6DgqmWNPAbl+yLROZ05AbbBeA2klvrzyhJR3sIKiU4YD PavFxBYPVbYqowYI/+xQn+DMiOdxYqWy7thehmFaHRDNlh7J93b1yRFNsIvsIZoj0HZF QF1g== X-Forwarded-Encrypted: i=1; AJvYcCUft4+DuozVcJLu1Ub3uEqNoBuRw59P2fNHj+LmU9U7/NkpMlaHB/eI+l1Yw+6elSgr5C/BEZKkKUk=@vger.kernel.org, AJvYcCXhdmzGF9/ucIOpRywBSYwvq2CJ/MDyovKXA6340Ey6toinlD3EOs4NUP4xVGzbo8SG4SvNg89wq8z8cqcV@vger.kernel.org X-Gm-Message-State: AOJu0YwoHvwjxNvUMWZDCIqbylTAod1jFcX2FqiJ0+P1KWXmARQXnDom 3sFpRc/78jPs9MXsKEfCNFT4mv3sWBnuDD00C/Wuap4EE3tWZK6Q2kWjuMKi X-Google-Smtp-Source: AGHT+IGmatMTJnxCvEg3igsnFWsQvmr94iHKUL+dS5GXCEpfMtQ9lYjxJVCOrVzjj69MOKf30LWjbw== X-Received: by 2002:a05:6a20:43a5:b0:1d9:1783:6a2d with SMTP id adf61e73a8af0-1d978af7c47mr1807757637.13.1729661646206; Tue, 22 Oct 2024 22:34:06 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e76e0877a6sm428695a91.54.2024.10.22.22.34.04 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 22:34:05 -0700 (PDT) From: anish kumar To: ohad@wizery.com, bjorn.andersson@linaro.org, mathieu.poirier@linaro.org, corbet@lwn.net Cc: linux-remoteproc@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, anish kumar Subject: [PATCH V4 2/7] Documentation: remoteproc: move from staging Date: Tue, 22 Oct 2024 22:33:52 -0700 Message-Id: <20241023053357.5261-3-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241023053357.5261-1-yesanishhere@gmail.com> References: <20241023053357.5261-1-yesanishhere@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" In preparation for upcoming enhancements, this commit relocates the existing documentation from the staging area to the mainline Documentation directory. Future patches will add further documentation to improve clarity and usability. Signed-off-by: anish kumar Reported-by: kernel test robot --- Documentation/driver-api/remoteproc/index.rst | 6 ++++++ .../{staging =3D> driver-api/remoteproc}/remoteproc.rst | 0 Documentation/staging/index.rst | 1 - 3 files changed, 6 insertions(+), 1 deletion(-) rename Documentation/{staging =3D> driver-api/remoteproc}/remoteproc.rst (= 100%) diff --git a/Documentation/driver-api/remoteproc/index.rst b/Documentation/= driver-api/remoteproc/index.rst index 8b8c8f512e2b..6ac5a082bf4f 100644 --- a/Documentation/driver-api/remoteproc/index.rst +++ b/Documentation/driver-api/remoteproc/index.rst @@ -14,6 +14,12 @@ Authors: the hardware differences, so the entire driver doesn't need to be duplicated. =20 + +.. toctree:: + :maxdepth: 1 + + remoteproc + Mailing List ------------ To post a message, send an email to diff --git a/Documentation/staging/remoteproc.rst b/Documentation/driver-ap= i/remoteproc/remoteproc.rst similarity index 100% rename from Documentation/staging/remoteproc.rst rename to Documentation/driver-api/remoteproc/remoteproc.rst diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.= rst index abd0d18254d2..8884af4556b4 100644 --- a/Documentation/staging/index.rst +++ b/Documentation/staging/index.rst @@ -8,7 +8,6 @@ Unsorted Documentation =20 crc32 lzo - remoteproc rpmsg speculation static-keys --=20 2.39.3 (Apple Git-146) From nobody Tue Nov 26 02:00:42 2024 Received: from mail-pj1-f41.google.com (mail-pj1-f41.google.com [209.85.216.41]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 14C801494C3; Wed, 23 Oct 2024 05:34:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.41 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661652; cv=none; b=ZIgGdb7jK/ej0SqcRfS/FfQQscRLnOAa3/tl/M3omy3AF3JT4/sEyV0m5kBc/Re3yHzHsctdMP8Z2ZKNuD4diM9ebaz49KIbKPslbsbOfLXyxykQWjzBuCfN0/dVgiF5Y7ImWc8N2gWRTXf7u+eaYbOh1SFUUzLUYIFb+p3v2AY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661652; c=relaxed/simple; bh=hU/SsVLleIFpxyaxtEAnm7BjNLwpp98U+lhk6GQaG2I=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=Dn1ka5odgApddxWN9k17m+PFYd1QYaqhZhDUW3TRS7JkOJrEtzHsQQyJuvy0f03p3Y6KqoYoFSGW/7lCLQzXuPq49TV5wo6JKtSmSe09f0ynp+ThBodutz7sMge71SWkNKSc10hWG5VSmV68n7ctLndk3KcOgLuGFQZo70nIceo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=go9jPXjW; arc=none smtp.client-ip=209.85.216.41 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="go9jPXjW" Received: by mail-pj1-f41.google.com with SMTP id 98e67ed59e1d1-2e2cc469c62so4318660a91.2; Tue, 22 Oct 2024 22:34:09 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729661649; x=1730266449; darn=vger.kernel.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=7nCYj2FORf768o8FcjxuViHniSxTlDq4/6V2zE0Vs88=; b=go9jPXjWsNaJewX0TSksuoH9hFV08GNFuy0ISCigjzTIxEm+R+d7IhmghvpKYTrTXB UJ/cmS4fN/o93RyVKVFUGHCXUU21bw1G7YMpVX1vsKdwQ7GOOymaYB04vVMkAMOdYZ9v mA3QIGRAs5dmJS6kXIcJfHoRYRRt/rg3a86UNQZLp8J/o225abdBTyhDbUrqFo66413n f4v5cjkLhMP2U0Omznsz466ioxql9hfwySYgyuMtafQRreFnvnX0E5CjJPFkQRTSthdJ k/16qvpOdSGdFqACI8VLDxFpZZ90J1VWJ8eADU/PSEDHp9LVz13XR6cqCwxtxqgHmdjG eV/g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729661649; x=1730266449; 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=7nCYj2FORf768o8FcjxuViHniSxTlDq4/6V2zE0Vs88=; b=wnvILsfvhE7OU1i+yFjaDzSkU/aDW3jXTGWTcd26IO7vaWdvNl0l1SVA8pqVESkAZH cleuQyqG1bLmqdSdFNYc9YJJQ8J1wbL8FrRGjTCf4IFzn2w03eZ7+kueAwTNORpdm00Q tOBNIRiKZHob1n8+oy2/HbMvNZ1ePCyCSbNi7YY8vDPuV83q0Wo7X2MpQqlVjHXwrRdG TSxd4B72A3SR1n+UbwHDLr0YJX50Hy+aq5tcL9Mfjf2O2fy2NSwgjz1tpS2Exr9Knnbf B5a6+3fUV4Ny8et5sVbbyRrTlMB/L4H6txxxAicsBYWKiiETKOooPwZ2EPQkcpm2MVTA TP3g== X-Forwarded-Encrypted: i=1; AJvYcCUTytid6JaEfo5GTiRT3byTcStZ+Jmz8g5giu+yxq7QemSurBD8ySjm8pOROSWe2AWsSvoxZvu++/8=@vger.kernel.org, AJvYcCUf+80EGcKyKDB1smb2LmW+0s564RZyrAD+huMcaRgGP79tzofULAoTBFw2I6cLmwBeBqctrXDVxm2dE+UV@vger.kernel.org X-Gm-Message-State: AOJu0YxVuylpSfobPeCymxyMT96ik2Z+Kfk4n9wX1hfzOE61jubsyIT7 OZJak+RtGH8YaK1ssAu18osbVUWlxTwdA7ESvqeg5gKGobMNm6DfXf6QJA8A X-Google-Smtp-Source: AGHT+IHEHpgXsOvN8Ga4NSfO8L3l95T92YERqHlKeehoTLfgqooopacOMZYegwLARt9hkPZFvK1GfA== X-Received: by 2002:a17:90b:274c:b0:2e2:b922:48a with SMTP id 98e67ed59e1d1-2e76b5fd63dmr1494041a91.18.1729661647919; Tue, 22 Oct 2024 22:34:07 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e76e0877a6sm428695a91.54.2024.10.22.22.34.06 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 22:34:07 -0700 (PDT) From: anish kumar To: ohad@wizery.com, bjorn.andersson@linaro.org, mathieu.poirier@linaro.org, corbet@lwn.net Cc: linux-remoteproc@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, anish kumar Subject: [PATCH V4 3/7] Documentation: remoteproc: add more information Date: Tue, 22 Oct 2024 22:33:53 -0700 Message-Id: <20241023053357.5261-4-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241023053357.5261-1-yesanishhere@gmail.com> References: <20241023053357.5261-1-yesanishhere@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Added following changes: 1. Components provided by remoteproc framework. 2. Remoteproc driver responsibilities. 3. Remoteproc framework responsibilities. 4. Better explanation of how to ask for resources from the framework by the remote processor. Signed-off-by: anish kumar Reported-by: kernel test robot --- .../driver-api/remoteproc/remoteproc.rst | 596 +++++++----------- 1 file changed, 243 insertions(+), 353 deletions(-) diff --git a/Documentation/driver-api/remoteproc/remoteproc.rst b/Documenta= tion/driver-api/remoteproc/remoteproc.rst index 9cccd3dd6a4b..7ca545eea153 100644 --- a/Documentation/driver-api/remoteproc/remoteproc.rst +++ b/Documentation/driver-api/remoteproc/remoteproc.rst @@ -1,359 +1,249 @@ +.. SPDX-License-Identifier: GPL-2.0 + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D Remote Processor Framework =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =20 -Introduction -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -Modern SoCs typically have heterogeneous remote processor devices in asymm= etric -multiprocessing (AMP) configurations, which may be running different insta= nces -of operating system, whether it's Linux or any other flavor of real-time O= S. - -OMAP4, for example, has dual Cortex-A9, dual Cortex-M3 and a C64x+ DSP. -In a typical configuration, the dual cortex-A9 is running Linux in a SMP -configuration, and each of the other three cores (two M3 cores and a DSP) -is running its own instance of RTOS in an AMP configuration. - -The remoteproc framework allows different platforms/architectures to -control (power on, load firmware, power off) those remote processors while -abstracting the hardware differences, so the entire driver doesn't need to= be -duplicated. In addition, this framework also adds rpmsg virtio devices -for remote processors that supports this kind of communication. This way, -platform-specific remoteproc drivers only need to provide a few low-level -handlers, and then all rpmsg drivers will then just work -(for more information about the virtio-based rpmsg bus and its drivers, -please read Documentation/staging/rpmsg.rst). -Registration of other types of virtio devices is now also possible. Firmwa= res -just need to publish what kind of virtio devices do they support, and then -remoteproc will add those devices. This makes it possible to reuse the -existing virtio drivers with remote processor backends at a minimal develo= pment -cost. - -User API -=3D=3D=3D=3D=3D=3D=3D=3D - -:: - - int rproc_boot(struct rproc *rproc) - -Boot a remote processor (i.e. load its firmware, power it on, ...). - -If the remote processor is already powered on, this function immediately -returns (successfully). - -Returns 0 on success, and an appropriate error value otherwise. -Note: to use this function you should already have a valid rproc -handle. There are several ways to achieve that cleanly (devres, pdata, -the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we -might also consider using dev_archdata for this). - -:: - - void rproc_shutdown(struct rproc *rproc) - -Power off a remote processor (previously booted with rproc_boot()). -In case @rproc is still being used by an additional user(s), then -this function will just decrement the power refcount and exit, -without really powering off the device. - -Every call to rproc_boot() must (eventually) be accompanied by a call -to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug. - -.. note:: - - we're not decrementing the rproc's refcount, only the power refcount. - which means that the @rproc handle stays valid even after - rproc_shutdown() returns, and users can still use it with a subsequent - rproc_boot(), if needed. - -:: - - struct rproc *rproc_get_by_phandle(phandle phandle) - -Find an rproc handle using a device tree phandle. Returns the rproc -handle on success, and NULL on failure. This function increments -the remote processor's refcount, so always use rproc_put() to -decrement it back once rproc isn't needed anymore. - -Typical usage -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -:: - - #include - - /* in case we were given a valid 'rproc' handle */ - int dummy_rproc_example(struct rproc *my_rproc) - { - int ret; - - /* let's power on and boot our remote processor */ - ret =3D rproc_boot(my_rproc); - if (ret) { - /* - * something went wrong. handle it and leave. - */ - } - - /* - * our remote processor is now powered on... give it some work - */ - - /* let's shut it down now */ - rproc_shutdown(my_rproc); - } - -API for implementors -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -:: - - struct rproc *rproc_alloc(struct device *dev, const char *name, - const struct rproc_ops *ops, - const char *firmware, int len) - -Allocate a new remote processor handle, but don't register -it yet. Required parameters are the underlying device, the -name of this remote processor, platform-specific ops handlers, -the name of the firmware to boot this rproc with, and the -length of private data needed by the allocating rproc driver (in bytes). - -This function should be used by rproc implementations during -initialization of the remote processor. - -After creating an rproc handle using this function, and when ready, -implementations should then call rproc_add() to complete -the registration of the remote processor. - -On success, the new rproc is returned, and on failure, NULL. - -.. note:: - - **never** directly deallocate @rproc, even if it was not registered - yet. Instead, when you need to unroll rproc_alloc(), use rproc_free(). - -:: - - void rproc_free(struct rproc *rproc) - -Free an rproc handle that was allocated by rproc_alloc. - -This function essentially unrolls rproc_alloc(), by decrementing the -rproc's refcount. It doesn't directly free rproc; that would happen -only if there are no other references to rproc and its refcount now -dropped to zero. - -:: - - int rproc_add(struct rproc *rproc) - -Register @rproc with the remoteproc framework, after it has been -allocated with rproc_alloc(). - -This is called by the platform-specific rproc implementation, whenever -a new remote processor device is probed. - -Returns 0 on success and an appropriate error code otherwise. -Note: this function initiates an asynchronous firmware loading -context, which will look for virtio devices supported by the rproc's -firmware. - -If found, those virtio devices will be created and added, so as a result -of registering this remote processor, additional virtio drivers might get -probed. - -:: - - int rproc_del(struct rproc *rproc) - -Unroll rproc_add(). - -This function should be called when the platform specific rproc -implementation decides to remove the rproc device. it should -_only_ be called if a previous invocation of rproc_add() -has completed successfully. - -After rproc_del() returns, @rproc is still valid, and its -last refcount should be decremented by calling rproc_free(). - -Returns 0 on success and -EINVAL if @rproc isn't valid. - -:: - - void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type) - -Report a crash in a remoteproc - -This function must be called every time a crash is detected by the -platform specific rproc implementation. This should not be called from a -non-remoteproc driver. This function can be called from atomic/interrupt -context. - -Implementation callbacks +.. Contents: + + 1. Introduction + 2. Remoteproc framework responsibilities + 3. Remoteproc driver responsibilities + 4. Virtio and rpmsg + +1. Introduction +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Modern System on Chips (SoCs) typically integrate heterogeneous remote +processor devices in asymmetric multiprocessing (AMP) configurations. +These processors may run different operating systems, such as Linux and +various real-time operating systems (RTOS). + +For example, the OMAP4 platform features dual Cortex-A9 cores, dual +Cortex-M3 cores, and a C64x+ DSP. In a standard setup, the Cortex-A9 +cores execute Linux in a symmetric multiprocessing (SMP) configuration, +while the M3 cores and DSP run independent instances of an RTOS. + +The remoteproc framework allows various platforms and architectures to +manage remote processors, including operations such as powering on, +loading firmware, and powering off. This framework abstracts hardware +differences, promoting code reuse and minimizing duplication. It also +supports rpmsg virtio devices for remote processors that utilize this +communication method. Consequently, platform-specific remoteproc drivers +need only implement a few low-level handlers, enabling seamless operation +of all rpmsg drivers. (For more details about the virtio-based rpmsg +bus and its drivers, refer to rpmsg documentation.) + +Additionally, the framework allows for the registration of various +virtio devices. Firmware can publish the types of virtio devices it +supports, facilitating their addition to the remoteproc framework. This +flexibility enables the reuse of existing virtio drivers with remote +processor backends at minimal development cost. + +The primary purpose of the remoteproc framework is to download firmware +for remote processors and manage their lifecycle. The framework consists +of several key components: + +- **Character Driver**: Provides userspace access to control the remote + processor. +- **ELF Utility**: Offers functions for handling ELF files and managing + resources requested by the remote processor. +- **Remoteproc Core**: Manages firmware downloads and recovery actions + in case of a remote processor crash. +- **Coredump**: Provides facilities for coredumping and tracing from + the remote processor in the event of a crash. +- **Userspace Interaction**: Uses sysfs and debugfs to manage the + lifecycle and status of the remote processor. +- **Virtio Support**: Facilitates interaction with the virtio and + rpmsg bus. + +From here on, references to "framework" denote the remoteproc +framework, and "driver" refers to the remoteproc driver that utilizes +the framework for managing remote processors. + +2. Remoteproc framework Responsibilities +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The framework begins by gathering information about the firmware file +to be downloaded through the request_firmware function. It supports +the ELF format and parses the firmware image to identify the physical +addresses that need to be populated from the corresponding ELF sections. +The framework also requires knowledge of the logical or I/O-mapped +addresses in the application processor. Once this information is +obtained from the driver, the framework transfers the data to the +specified addresses and starts the remote, along with +any devices physically or logically connected to it. + +Dependent devices, referred to as `subdevices` within the framework, +are also managed post-registration by their respective drivers. +Subdevices can register themselves using `rproc_(add/remove)_subdev`. +Non-remoteproc drivers can use subdevices as a way to logically connect +to remote and get lifecycle notifications of the remote. + +The framework oversees the lifecycle of the remote and +provides the `rproc_report_crash` function, which the driver invokes +upon receiving a crash notification from the remote. The +notification method can differ based on the design of the remote +processor and its communication with the application processor. For +instance, if the remote is a DSP equipped with a watchdog, +unresponsive behavior triggers the watchdog, generating an interrupt +that routes to the application processor, allowing it to call +`rproc_report_crash` in the driver's interrupt context. + +During crash handling, the framework performs the following actions: + +a. Sends a request to stop the remote and any connected or + dependent subdevices. +b. Generates a coredump, dumping all `resources` requested by the + remote alongside relevant debugging information. Resources are + explained below. +c. Reloads the firmware and restarts the remote. + +If the `RPROC_FEAT_ATTACH_ON_RECOVERY` flag is set, the detach and +attach callbacks of the driver are invoked without reloading the +firmware. This is useful when the remote requires no +assistance for recovery, or when the application processor can restart +independently. After recovery, the application processor can reattach +to the remote. + +The remote can request resources from the framework, which +allocates a ".resource_table" section. During the ELF parsing phase, +the framework identifies this section and calls the appropriate +handler to allocate the requested resources. + +Resource management within the framework can accommodate any type of +`fw_resource_type`. + +.. code-block:: c + + enum fw_resource_type { + RSC_CARVEOUT =3D 0, + RSC_DEVMEM =3D 1, + RSC_TRACE =3D 2, + RSC_VDEV =3D 3, + RSC_LAST =3D 4, + RSC_VENDOR_START =3D 128, + RSC_VENDOR_END =3D 512, + }; + + struct resource_table { + u32 ver; + u32 num; + u32 reserved[2]; + u32 offset[]; + } __packed; + + struct fw_rsc_hdr { + u32 type; + u8 data[]; + } __packed; + +For example, if the remote requests both `RSC_TRACE` and +`RSC_CARVEOUT` for memory allocation, the ELF firmware can be structured +as follows: + +.. code-block:: c + + #define MAX_SHARED_RESOURCE 2 + #define LOG_BUF_SIZE 1000 + #define CARVEOUT_DUMP_PA 0x12345678 + #define CARVEOUT_DUMP_SIZE 2000 + + struct shared_resource_table { + u32 ver; + u32 num; + u32 reserved[2]; + u32 offset[MAX_SHARED_RESOURCE]; + struct fw_rsc_trace log_trace; + struct fw_rsc_carveout dump_carveout; + }; + + volatile struct shared_resource_table table =3D { + .ver =3D 1, + .num =3D 2, + .reserved =3D {0, 0}, + .offset =3D { + offsetof(struct resource_table, log_trace), + offsetof(struct resource_table, dump_carveout), + }, + .log_trace =3D { + RSC_TRACE, + (u32)log_buf, LOG_BUF_SIZE, 0, "log_trace", + }, + .dump_carveout =3D { + RSC_CARVEOUT, + (u32)FW_RSC_ADDR_ANY, CARVEOUT_PA, 0, "carveout_dump", + }, + }; + +The framework creates a sysfs file when it encounters the `RSC_TRACE` +type to expose log information to userspace. Other resource types are +handled accordingly. In the example above, `CARVEOUT_DUMP_SIZE` bytes +of DMA memory will be allocated starting from `CARVEOUT_DUMP_PA`. + + +3. Remoteproc driver responsibilities +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The driver must provide the following information to the core: + +a. Translate device addresses (physical addresses) found in the ELF + firmware to virtual addresses in Linux using the `da_to_va` + callback. This allows the framework to copy ELF firmware from the + filesystem to the addresses expected by the remote since + the framework cannot directly access those physical addresses. +b. Prepare/unprepare the remote prior to firmware loading, + which may involve allocating carveout and reserved memory regions. +c. Implement methods for starting and stopping the remote, + whether by setting registers or sending explicit interrupts, + depending on the hardware design. +d. Provide attach and detach callbacks to start the remote + without loading the firmware. This is beneficial when the remote + processor is already loaded and running. +e. Implement a load callback for firmware loading, typically using + the ELF loader provided by the framework; currently, only ELF + format is supported. +f. Invoke the framework's crash handler API upon detecting a remote + crash. + +Drivers must fill the `rproc_ops` structure and call `rproc_alloc` +to register themselves with the framework. + +.. code-block:: c + + struct rproc_ops { + int (*prepare)(struct rproc *rproc); + int (*unprepare)(struct rproc *rproc); + int (*start)(struct rproc *rproc); + int (*stop)(struct rproc *rproc); + int (*attach)(struct rproc *rproc); + int (*detach)(struct rproc *rproc); + void * (*da_to_va)(struct rproc *rproc, u64 da, size_t len, + bool *is_iomem); + int (*parse_fw)(struct rproc *rproc, const struct firmware *fw); + int (*handle_rsc)(struct rproc *rproc, u32 rsc_type, + void *rsc, int offset, int avail); + int (*load)(struct rproc *rproc, const struct firmware *fw); + //snip + }; + + +4. Virtio and Remoteproc =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -These callbacks should be provided by platform-specific remoteproc -drivers:: - - /** - * struct rproc_ops - platform-specific device handlers - * @start: power on the device and boot it - * @stop: power off the device - * @kick: kick a virtqueue (virtqueue id given as a parameter) - */ - struct rproc_ops { - int (*start)(struct rproc *rproc); - int (*stop)(struct rproc *rproc); - void (*kick)(struct rproc *rproc, int vqid); - }; - -Every remoteproc implementation should at least provide the ->start and ->= stop -handlers. If rpmsg/virtio functionality is also desired, then the ->kick h= andler -should be provided as well. - -The ->start() handler takes an rproc handle and should then power on the -device and boot it (use rproc->priv to access platform-specific private da= ta). -The boot address, in case needed, can be found in rproc->bootaddr (remotep= roc -core puts there the ELF entry point). -On success, 0 should be returned, and on failure, an appropriate error cod= e. - -The ->stop() handler takes an rproc handle and powers the device down. -On success, 0 is returned, and on failure, an appropriate error code. - -The ->kick() handler takes an rproc handle, and an index of a virtqueue -where new message was placed in. Implementations should interrupt the remo= te -processor and let it know it has pending messages. Notifying remote proces= sors -the exact virtqueue index to look in is optional: it is easy (and not -too expensive) to go through the existing virtqueues and look for new buff= ers -in the used rings. - -Binary Firmware Structure -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D - -At this point remoteproc supports ELF32 and ELF64 firmware binaries. Howev= er, -it is quite expected that other platforms/devices which we'd want to -support with this framework will be based on different binary formats. - -When those use cases show up, we will have to decouple the binary format -from the framework core, so we can support several binary formats without -duplicating common code. - -When the firmware is parsed, its various segments are loaded to memory -according to the specified device address (might be a physical address -if the remote processor is accessing memory directly). - -In addition to the standard ELF segments, most remote processors would -also include a special section which we call "the resource table". - -The resource table contains system resources that the remote processor -requires before it should be powered on, such as allocation of physically -contiguous memory, or iommu mapping of certain on-chip peripherals. -Remotecore will only power up the device after all the resource table's -requirement are met. - -In addition to system resources, the resource table may also contain -resource entries that publish the existence of supported features -or configurations by the remote processor, such as trace buffers and -supported virtio devices (and their configurations). - -The resource table begins with this header:: - - /** - * struct resource_table - firmware resource table header - * @ver: version number - * @num: number of resource entries - * @reserved: reserved (must be zero) - * @offset: array of offsets pointing at the various resource entries - * - * The header of the resource table, as expressed by this structure, - * contains a version number (should we need to change this format in the - * future), the number of available resource entries, and their offsets - * in the table. - */ - struct resource_table { - u32 ver; - u32 num; - u32 reserved[2]; - u32 offset[0]; - } __packed; - -Immediately following this header are the resource entries themselves, -each of which begins with the following resource entry header:: - - /** - * struct fw_rsc_hdr - firmware resource entry header - * @type: resource type - * @data: resource data - * - * Every resource entry begins with a 'struct fw_rsc_hdr' header providi= ng - * its @type. The content of the entry itself will immediately follow - * this header, and it should be parsed according to the resource type. - */ - struct fw_rsc_hdr { - u32 type; - u8 data[0]; - } __packed; - -Some resources entries are mere announcements, where the host is informed -of specific remoteproc configuration. Other entries require the host to -do something (e.g. allocate a system resource). Sometimes a negotiation -is expected, where the firmware requests a resource, and once allocated, -the host should provide back its details (e.g. address of an allocated -memory region). - -Here are the various resource types that are currently supported:: - - /** - * enum fw_resource_type - types of resource entries - * - * @RSC_CARVEOUT: request for allocation of a physically contiguous - * memory region. - * @RSC_DEVMEM: request to iommu_map a memory-based peripheral. - * @RSC_TRACE: announces the availability of a trace buffer into whi= ch - * the remote processor will be writing logs. - * @RSC_VDEV: declare support for a virtio device, and serve as its - * virtio header. - * @RSC_LAST: just keep this one at the end - * @RSC_VENDOR_START: start of the vendor specific resource types range - * @RSC_VENDOR_END: end of the vendor specific resource types range - * - * Please note that these values are used as indices to the rproc_handle= _rsc - * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to - * check the validity of an index before the lookup table is accessed, so - * please update it as needed. - */ - enum fw_resource_type { - RSC_CARVEOUT =3D 0, - RSC_DEVMEM =3D 1, - RSC_TRACE =3D 2, - RSC_VDEV =3D 3, - RSC_LAST =3D 4, - RSC_VENDOR_START =3D 128, - RSC_VENDOR_END =3D 512, - }; - -For more details regarding a specific resource type, please see its -dedicated structure in include/linux/remoteproc.h. - -We also expect that platform-specific resource entries will show up -at some point. When that happens, we could easily add a new RSC_PLATFORM -type, and hand those resources to the platform-specific rproc driver to ha= ndle. - -Virtio and remoteproc -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -The firmware should provide remoteproc information about virtio devices -that it supports, and their configurations: a RSC_VDEV resource entry -should specify the virtio device id (as in virtio_ids.h), virtio features, -virtio config space, vrings information, etc. - -When a new remote processor is registered, the remoteproc framework -will look for its resource table and will register the virtio devices -it supports. A firmware may support any number of virtio devices, and -of any type (a single remote processor can also easily support several -rpmsg virtio devices this way, if desired). - -Of course, RSC_VDEV resource entries are only good enough for static -allocation of virtio devices. Dynamic allocations will also be made possib= le -using the rpmsg bus (similar to how we already do dynamic allocations of -rpmsg channels; read more about it in rpmsg.txt). +The firmware must provide remoteproc with information regarding the +virtio devices it supports and their configurations: an `RSC_VDEV` +resource entry should detail the virtio device ID (as defined in +`virtio_ids.h`), virtio features, virtio config space, vrings +information, etc. + +Upon registration of a new remote, the remoteproc framework +searches for its resource table and registers the supported virtio +devices. A firmware may support multiple virtio devices, of various +types (a single remote can support multiple rpmsg virtio +devices if required). + +Moreover, `RSC_VDEV` resource entries suffice for static allocation +of virtio devices. Dynamic allocations will also be supported using +the rpmsg bus, akin to the handling of dynamic allocations for rpmsg +channels. For more information, refer to rpmsg documentation. --=20 2.39.3 (Apple Git-146) From nobody Tue Nov 26 02:00:42 2024 Received: from mail-pj1-f53.google.com (mail-pj1-f53.google.com [209.85.216.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 61DE6149C7A; Wed, 23 Oct 2024 05:34:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.53 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661653; cv=none; b=Qucy+vaeZnB1XpKOHMBSBfZ/edtdnBXYooNpxaTah2wDH7I0n1C903K04s9SLpuYfli10rrGGCv6dbSAwcXo8VJgTxu15UBvaUeTbNV6vlZCuMF0ykCS/vW7Owk+uCP+4M5z1num7WbjsDttQROf+fY6LUTu35pSUijmdHgfti8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661653; c=relaxed/simple; bh=zpWK1pE7J8SblnCBHHB7GnCCypi6DTBFFi3yutdVRDk=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=rVukvmDi8FLrgBSzTg4wxm3COlQ8pe4dltia/VoNRU9Khdv47+5wP0/muy1G7vrNI8t4ufD/6eqpBSJyMC8s+LV7G3+KilJI5tbEsPMrhxFHcH4aIHgOoNlv5Xfc/UkWLArm/n4YEP73Npc1jfvKDtKVmNEZPUyh06IW8wmkqXE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=nsvSkfZ0; arc=none smtp.client-ip=209.85.216.53 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="nsvSkfZ0" Received: by mail-pj1-f53.google.com with SMTP id 98e67ed59e1d1-2e34a089cd3so5219882a91.3; Tue, 22 Oct 2024 22:34:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729661651; x=1730266451; darn=vger.kernel.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=g0tU3F5tmvnRnzyj0QOsHvr34uUH1l0/ActVUyyOu3E=; b=nsvSkfZ0ku24om5ziwUalXCNnXVZrjsLoYmZ7JrREa1A/KlCLQ8MdhKKT+pmAYqtsH 4g2UX3neS4nW5GeqaSB+RgiPe7Ux194rYZLDv7DNLC7tvTS7+LleazWmg+A5wLfAbTu4 tvQeH5Lp3cWk9U+tYiFoEhpzy64twNT75uCOu9PuLPjUXrTRTO1KMgEHWUo3WA2U25c2 bzmEgPRUVydHKiA/VV6akB8ntgd9BKPButMHLf7BWAFxeo7j9ycgTRsKbIzAzIDSptWM PsFNgLKqQBtjST7tiRo+ccWQJ095gAP2cAIQUGkwu2NNj8SRIGzz7XpTvMwtot0CaIrF zVOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729661651; x=1730266451; 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=g0tU3F5tmvnRnzyj0QOsHvr34uUH1l0/ActVUyyOu3E=; b=q7N3KchAHfaxgaq8x13whf236x8vuRYCXCUHh0jljx8KudDrJt4vYhjojPwrctfOEz cNHzFn9Qik0VJE6BRgzBLoIpz63wDNwW3OnnH3c3k0quusMU/L5wPs/eOADy6FIWZT/6 4M917Z3NR9Hp065w43pCwu2QWWd1xdwVwSKnDbO25cC1raEX4JSiVSSCojPk1FNvGKSa 1PfBHlkpoRcig/W+zfgJ7LHoBQWA2DlKmOUSdYd6EYX96fofJ9EVf9rC46EaoJaN1iDp xhow3Kd8+0DpKBuB/QIrOTQH6ZqUzFHFd6zWfhZn7GUc3vGb2AY09w5fHGkk42XITN7+ xaBw== X-Forwarded-Encrypted: i=1; AJvYcCVKVHWU6r983WjgcYBNNVIb1sM+7Hnkinz1xTUpJZDlyfpI7qKujiPYj7WDYlPZ+8dLycjKSOaG2psGnt9f@vger.kernel.org, AJvYcCWTmRPtbTanmdNF1V1e6V+hHIyFbXMUBDjZFeJC4lUT5d5GPFQA83vuOdUhqZA9ZxpPaZV7xfPrIfQ=@vger.kernel.org X-Gm-Message-State: AOJu0YxxBkP/YKxVr5ucFRQXL+gT6ZGKmOlzzsvcQUV3utMgJLkqQ/lG 1nDU2p1UXeLHFIrOM/5Q0+gWRUJWaNNIh2hyMDNnzq6uEmkfTnXo X-Google-Smtp-Source: AGHT+IGtTLFuF8afYDNUOqIa/1/53sb+Eu6DYa89AXaEqV1ez+hwVsD1xBuPhPxUX7w6F5cqah0ppw== X-Received: by 2002:a17:90a:9ee:b0:2e2:cd65:de55 with SMTP id 98e67ed59e1d1-2e76b601619mr1723248a91.20.1729661650647; Tue, 22 Oct 2024 22:34:10 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e76e0877a6sm428695a91.54.2024.10.22.22.34.08 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 22:34:09 -0700 (PDT) From: anish kumar To: ohad@wizery.com, bjorn.andersson@linaro.org, mathieu.poirier@linaro.org, corbet@lwn.net Cc: linux-remoteproc@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, anish kumar Subject: [PATCH V4 4/7] Remoteproc: Documentation: add driver api Date: Tue, 22 Oct 2024 22:33:54 -0700 Message-Id: <20241023053357.5261-5-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241023053357.5261-1-yesanishhere@gmail.com> References: <20241023053357.5261-1-yesanishhere@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Add driver api documenation for remoteproc. Signed-off-by: anish kumar Reported-by: kernel test robot --- Documentation/driver-api/remoteproc/index.rst | 1 + .../remoteproc/remoteproc-kernel-api.rst | 239 ++++++++++++++++++ 2 files changed, 240 insertions(+) create mode 100644 Documentation/driver-api/remoteproc/remoteproc-kernel-a= pi.rst diff --git a/Documentation/driver-api/remoteproc/index.rst b/Documentation/= driver-api/remoteproc/index.rst index 6ac5a082bf4f..7fa1c5755be8 100644 --- a/Documentation/driver-api/remoteproc/index.rst +++ b/Documentation/driver-api/remoteproc/index.rst @@ -19,6 +19,7 @@ Authors: :maxdepth: 1 =20 remoteproc + remoteproc-kernel-api =20 Mailing List ------------ diff --git a/Documentation/driver-api/remoteproc/remoteproc-kernel-api.rst = b/Documentation/driver-api/remoteproc/remoteproc-kernel-api.rst new file mode 100644 index 000000000000..018c5bf9b3d7 --- /dev/null +++ b/Documentation/driver-api/remoteproc/remoteproc-kernel-api.rst @@ -0,0 +1,239 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D +The Linux Remoteproc subsystem Driver Core kernel API +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +anish kumar + +Introduction +------------ +This document does not describe what a Remote processor subsystem +(RPROC) Driver or Device is. It also does not describe the API +which can be used by user space to communicate with a RPROC driver. +If you want to know this then please read the following +file: Documentation/remoteproc/rproc-api.rst . + +So what does this document describe? It describes the API that can be used= by +remote processor Drivers that want to use the remote processor Driver Core +Framework. This framework provides all interfacing towards user space so t= hat +the same code does not have to be reproduced each time. This also means th= at +a remote processor driver then only needs to provide the different routines +(operations) that control the remote processor. + +The API +------- +Each remote processor driver that wants to use the remote processor Driver= Core +must #include (you would have to do this anyway when +writing a rproc device driver). This include file contains following +register routine:: + + int devm_rproc_add(struct device *dev, struct rproc *rproc) + +The devm_rproc_add routine registers a remote processor device. +The parameter of this routine is a pointer to a rproc device structure. +This routine returns zero on success and a negative errno code for failure. + +The rproc device structure looks like this:: + + struct rproc { + struct list_head node; + struct iommu_domain *domain; + const char *name; + const char *firmware; + void *priv; + struct rproc_ops *ops; + struct device dev; + atomic_t power; + unsigned int state; + enum rproc_dump_mechanism dump_conf; + struct mutex lock; + struct dentry *dbg_dir; + struct list_head traces; + int num_traces; + struct list_head carveouts; + struct list_head mappings; + u64 bootaddr; + struct list_head rvdevs; + struct list_head subdevs; + struct idr notifyids; + int index; + struct work_struct crash_handler; + unsigned int crash_cnt; + bool recovery_disabled; + int max_notifyid; + struct resource_table *table_ptr; + struct resource_table *clean_table; + struct resource_table *cached_table; + size_t table_sz; + bool has_iommu; + bool auto_boot; + bool sysfs_read_only; + struct list_head dump_segments; + int nb_vdev; + u8 elf_class; + u16 elf_machine; + struct cdev cdev; + bool cdev_put_on_release; + DECLARE_BITMAP(features, RPROC_MAX_FEATURES); + }; + +It contains following fields: + +* node: list node of this rproc object +* domain: iommu domain +* name: human readable name of the rproc +* firmware: name of firmware file to be loaded +* priv: private data which belongs to the platform-specific rproc module +* ops: platform-specific start/stop rproc handlers +* dev: virtual device for refcounting and common remoteproc behavior +* power: refcount of users who need this rproc powered up +* state: state of the device +* dump_conf: Currently selected coredump configuration +* lock: lock which protects concurrent manipulations of the rproc +* dbg_dir: debugfs directory of this rproc device +* traces: list of trace buffers +* num_traces: number of trace buffers +* carveouts: list of physically contiguous memory allocations +* mappings: list of iommu mappings we initiated, needed on shutdown +* bootaddr: address of first instruction to boot rproc with (optional) +* rvdevs: list of remote virtio devices +* subdevs: list of subdevices, to following the running state +* notifyids: idr for dynamically assigning rproc-wide unique notify ids +* index: index of this rproc device +* crash_handler: workqueue for handling a crash +* crash_cnt: crash counter +* recovery_disabled: flag that state if recovery was disabled +* max_notifyid: largest allocated notify id. +* table_ptr: pointer to the resource table in effect +* clean_table: copy of the resource table without modifications. Used +* when a remote processor is attached or detached from the core +* cached_table: copy of the resource table +* table_sz: size of @cached_table +* has_iommu: flag to indicate if remote processor is behind an MMU +* auto_boot: flag to indicate if remote processor should be auto-started +* sysfs_read_only: flag to make remoteproc sysfs files read only +* dump_segments: list of segments in the firmware +* nb_vdev: number of vdev currently handled by rproc +* elf_class: firmware ELF class +* elf_machine: firmware ELF machine +* cdev: character device of the rproc +* cdev_put_on_release: flag to indicate if remoteproc should be shutdown o= n @char_dev release +* features: indicate remoteproc features + +The list of rproc operations is defined as:: + + struct rproc_ops { + int (*prepare)(struct rproc *rproc); + int (*unprepare)(struct rproc *rproc); + int (*start)(struct rproc *rproc); + int (*stop)(struct rproc *rproc); + int (*attach)(struct rproc *rproc); + int (*detach)(struct rproc *rproc); + void (*kick)(struct rproc *rproc, int vqid); + void * (*da_to_va)(struct rproc *rproc, u64 da, size_t len, bool *is_iome= m); + int (*parse_fw)(struct rproc *rproc, const struct firmware *fw); + int (*handle_rsc)(struct rproc *rproc, u32 rsc_type, void *rsc, + int offset, int avail); + struct resource_table *(*find_loaded_rsc_table)( + struct rproc *rproc, const struct firmware *fw); + struct resource_table *(*get_loaded_rsc_table)( + struct rproc *rproc, size_t *size); + int (*load)(struct rproc *rproc, const struct firmware *fw); + int (*sanity_check)(struct rproc *rproc, const struct firmware *fw); + u64 (*get_boot_addr)(struct rproc *rproc, const struct firmware *fw); + unsigned long (*panic)(struct rproc *rproc); + void (*coredump)(struct rproc *rproc); + }; + +Most of the operations are optional. Currently in the implementation +there are no mandatory operations, however from the practical standpoint +minimum ops are: + +* start: this is a pointer to the routine that starts the remote processor + device. + The routine needs a pointer to the remote processor device structure as a + parameter. It returns zero on success or a negative errno code for failu= re. + +* stop: with this routine the remote processor device is being stopped. + + The routine needs a pointer to the remote processor device structure as a + parameter. It returns zero on success or a negative errno code for failu= re. + +* da_to_va: this is the routine that needs to translate device address to + application processor virtual address that it can copy code to. + + The routine needs a pointer to the remote processor device structure as a + parameter. It returns zero on success or a negative errno code for failu= re. + + The routine provides the device address it finds in the ELF firmware and= asks + the driver to convert that to virtual address. + +All other callbacks are optional in case of ELF provided firmware. + +* load: this is to load the firmware on to the remote device. + + The routine needs firmware file that it needs to load on to the remote p= rocessor. + If the driver overrides this callback then default ELF loader will not g= et used. + Otherwise default framework provided loader gets used. + + load =3D rproc_elf_load_segments; + parse_fw =3D rproc_elf_load_rsc_table; + find_loaded_rsc_table =3D rproc_elf_find_loaded_rsc_table; + sanity_check =3D rproc_elf_sanity_check; + get_boot_addr =3D rproc_elf_get_boot_addr; + +* parse_fw: this routing parses the provided firmware. In case of ELF form= at, + framework provided rproc_elf_load_rsc_table function can be used. + +* sanity_check: Check the format of the firmware. + +* coredump: If the driver prefers to manage coredumps independently, it can + implement its own coredump handling. However, the framework offers a def= ault + implementation for the ELF format by assigning this callback to + rproc_coredump, unless the driver has overridden it. + +* get_boot_addr: In case the bootaddr defined in ELF firmware is different= , driver + can use this callback to set a different boot address for remote process= or to + starts its reset vector from. + +* find_loaded_rsc_table: this routine gets the loaded resource table from = the firmware. + + resource table should have a section named (.resource_table) for the fra= mework + to understand and interpret its content. Resource table is a way for rem= ote + processor to ask for resources such as memory for dumping and logging. L= ook + at core documentation to know how to create the ELF section for the same. + +* get_loaded_rsc_table: Driver can customize passing the resource table by= overriding + this callback. Framework doesn't provide any default implementation for = the same. + + +The rproc_report_crash function allows you to report a crash when crash is +detected by the driver. + +:: + + void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type); + +To add a subdev corresponding driver can call:: + + void rproc_add_subdev(struct rproc *rproc, struct rproc_subdev *subdev); + +To remove a subdev, driver can call. + +:: + + void rproc_remove_subdev(struct rproc *rproc, struct rproc_subdev *subde= v); + +To work with ELF coredump below function can be called:: + + void rproc_coredump_cleanup(struct rproc *rproc); + void rproc_coredump(struct rproc *rproc); + void rproc_coredump_using_sections(struct rproc *rproc); + int rproc_coredump_add_segment(struct rproc *rproc, dma_addr_t da, size_= t size); + int rproc_coredump_add_custom_segment(struct rproc *rproc, + dma_addr_t da, size_t size, + void (*dumpfn)(struct rproc *rproc, + struct rproc_dump_segment *segm= ent, + void *dest, size_t offset, + size_t size), + +Remember that coredump functions provided by the framework only works with= ELF format. --=20 2.39.3 (Apple Git-146) From nobody Tue Nov 26 02:00:42 2024 Received: from mail-pj1-f42.google.com (mail-pj1-f42.google.com [209.85.216.42]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7553914A09C; Wed, 23 Oct 2024 05:34:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.42 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661654; cv=none; b=iqIH14f6/LlyBFoEtHlynt7Wi9aJc0l0sGR1ROuGySFmtqYhc+TziyTAWk5oD3p+n8Q06+snqeW80JnHa14irUuIwOi3WxWlU+BthKHcbnhqeYQSAUPAdj3ZHzbCbRkHimcOPbN9s195kufgSM6v0B8AEHPwjHTNPoukHApgyvw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661654; c=relaxed/simple; bh=uTAW3pkWYe+GuE2RBQ/1OUtIO/ENd2+9Ewakwcbcsaw=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=gFoA8yI5cOsBv8LQMEjoIWk7BySUm6ZDEQppwDWOL+Ns9K0puASEzWrQCyAolD26c9kOSa3Sod5OVNMMHB3yVhtSuP7CwsbDFiS992c8cPBKgm3eKs9KsA2zxH8/jmPDN48extpXohezeONJ0gbBTx58DUV1HmZYTG56pwBcyc4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=DEbCnGJi; arc=none smtp.client-ip=209.85.216.42 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="DEbCnGJi" Received: by mail-pj1-f42.google.com with SMTP id 98e67ed59e1d1-2e3fca72a41so4390449a91.1; Tue, 22 Oct 2024 22:34:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729661653; x=1730266453; darn=vger.kernel.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=z4rRoXjGVEerACUHjG3hf4rLkB65lTUBBhdOo3L4OOE=; b=DEbCnGJiJ6guVZI6VF1+AkOmO8yNkGCB11o3lVfHHwzGDVE6ENPABNiqIXwsgyUlRc LROEhB9uG5CiuRtkNFmmT0nkO7cqfwhEF6fvV2/1SyCou6jf595u+uavPoTxjkI3dJXS 8Srd5SreqewwvtHAiYVaVcx07EWHewnAwnUg1vkGojrz+7WHKtL09M+1WrdfQVt3WVQq DH+nhqj24m+qTefQ8OzNmzAvJE0Sjus95GewbVupdGYe+qXnAjdAdY1z0FsZTKrwe/Np XSJnK9ywiGW8oHgn2LQgmWSSK+jS2K+55mepUX504yoBa42arODtLvpgRGekvrKDBPW6 MpTw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729661653; x=1730266453; 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=z4rRoXjGVEerACUHjG3hf4rLkB65lTUBBhdOo3L4OOE=; b=ugiDYanVNF58ZOqVH5nyQfLoH0sOg76nmuhJaz8y3WOSjLemNSiKVRtzY+2n1iNQKA 3yykED/bPTvcgNqKmTHejwCdtsQPRCZL+39clxk3gCPqmJCxVyeUPxULJalUxq+YphQj 1tZ8rlywBTpuLVFuRXWTmius6sXnzgAQLkm1vhNsNGL2bFIUOWRDCKdyxr8LXoxTaWGg v5/OdpJmAKgwHrODWs1X15rD0VrFmNtLzQpqVQGgYgw2Kc4T2V98Wmrj62D60VrT8VpB RB0kwypWe982vK8BOl7B6WA7hHqtV9aYt85fIPJLXBwAFiWmf8+ez8Zdm9iI0qYCIixh r4lg== X-Forwarded-Encrypted: i=1; AJvYcCU6Sv+Ei74bhWwjbrLXD0LxpLe5tv+9vZLCL3hlyJoFpRMFhafmgXm1w0Bt1/Pq5D7xbaaTb6xiR7g=@vger.kernel.org, AJvYcCUUDF+KfghOgFMYRaXbqq4KrAyOlt0C5I46l66SQKaCR1Jnfi9BRx37QnJPaZ8uq5/LMLGrkX6nmyEe2vuU@vger.kernel.org X-Gm-Message-State: AOJu0Yx6PBuMlToNuC6owyifQJXhWzaSUqZ+O5TnSP7ZQUwgQH+WUFHT DIYfHdN6nwQ7+1oRpkmTByPo3nkQEL/MOd47E5wgil2siwPSfXPX X-Google-Smtp-Source: AGHT+IFFrs4AhOv4uU0T3PYddUDmXOS8TMkOBlzXFG9cQpqCYBKrekzzHBF92EpgQ2XMGN6LuVsxiA== X-Received: by 2002:a17:90a:e681:b0:2e2:a6ee:9280 with SMTP id 98e67ed59e1d1-2e76b6ea2e0mr1494906a91.26.1729661652631; Tue, 22 Oct 2024 22:34:12 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e76e0877a6sm428695a91.54.2024.10.22.22.34.10 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 22:34:11 -0700 (PDT) From: anish kumar To: ohad@wizery.com, bjorn.andersson@linaro.org, mathieu.poirier@linaro.org, corbet@lwn.net Cc: linux-remoteproc@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, anish kumar Subject: [PATCH V4 5/7] Remoteproc: Documentation: add userspace api Date: Tue, 22 Oct 2024 22:33:55 -0700 Message-Id: <20241023053357.5261-6-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241023053357.5261-1-yesanishhere@gmail.com> References: <20241023053357.5261-1-yesanishhere@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Add information about how userspace can control the remoteproc framework and different ways to do that. Signed-off-by: anish kumar Reported-by: kernel test robot --- Documentation/driver-api/remoteproc/index.rst | 1 + .../driver-api/remoteproc/remoteproc-api.rst | 77 +++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 Documentation/driver-api/remoteproc/remoteproc-api.rst diff --git a/Documentation/driver-api/remoteproc/index.rst b/Documentation/= driver-api/remoteproc/index.rst index 7fa1c5755be8..840b4672352b 100644 --- a/Documentation/driver-api/remoteproc/index.rst +++ b/Documentation/driver-api/remoteproc/index.rst @@ -20,6 +20,7 @@ Authors: =20 remoteproc remoteproc-kernel-api + remoteproc-api =20 Mailing List ------------ diff --git a/Documentation/driver-api/remoteproc/remoteproc-api.rst b/Docum= entation/driver-api/remoteproc/remoteproc-api.rst new file mode 100644 index 000000000000..0306b331a20e --- /dev/null +++ b/Documentation/driver-api/remoteproc/remoteproc-api.rst @@ -0,0 +1,77 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +The Linux Remoteproc userspace API +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Introduction +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +A Remoteproc (rproc) is a subsystem for managing the lifecycle +of a processor that is connected to Linux. + +At times, userspace may need to check the state of the remote processor to +prevent other processes from using it. For instance, if the remote process= or +is a DSP used for playback, there may be situations where the DSP is +undergoing recovery and cannot be used. In such cases, attempts to access = the +DSP for playback should be blocked. The rproc framework provides sysfs APIs +to inform userspace of the processor's current status which should be util= ised +to achieve the same. + +Additionally, there are scenarios where userspace applications need to exp= licitly +control the rproc. In these cases, rproc also offers the file descriptors. + +The simplest API +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Below set of api's can be used to start and stop the rproc +where 'X' refers to instance of associated remoteproc. There can be systems +where there are more than one rprocs such as multiple DSP's +connected to application processors running Linux. + +.. code-block:: c + + echo start > /sys/class/remoteproc/remoteprocX/state + echo stop > /sys/class/remoteproc/remoteprocX/state + +To know the state of rproc: + +.. code-block:: c + + cat /sys/class/remoteproc/remoteprocX/state + + +To dynamically replace firmware, execute the following commands: + +.. code-block:: c + + echo stop > /sys/class/remoteproc/remoteprocX/state + echo -n > + /sys/class/remoteproc/remoteprocX/firmware + echo start > /sys/class/remoteproc/remoteprocX/state + +To simulate a remote crash, execute: + +.. code-block:: c + + echo 1 > /sys/kernel/debug/remoteproc/remoteprocX/crash + +To get the trace logs, execute + +.. code-block:: c + + cat /sys/kernel/debug/remoteproc/remoteprocX/crashX + +where X will be 0 or 1 if there are 2 resources. Also, this +file will only exist if resources are defined in ELF firmware +file. + +The coredump feature can be disabled with the following command: + +.. code-block:: c + + echo disabled > /sys/kernel/debug/remoteproc/remoteprocX/coredump + +Userspace can also control start/stop of rproc by using a +remoteproc Character Device, it can open the open a file descriptor +and write `start` to initiate it, and `stop` to terminate it. + +[FIXME -- better explanations] --=20 2.39.3 (Apple Git-146) From nobody Tue Nov 26 02:00:42 2024 Received: from mail-pf1-f178.google.com (mail-pf1-f178.google.com [209.85.210.178]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id EE87C14A4D4; Wed, 23 Oct 2024 05:34:14 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.178 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661656; cv=none; b=jisO7tFJAy3sQBJKHeX/dcDt8rNzrD9nmvlBa2j3dN5CRaHbEBIMOz7K4lbgVto37K2Tq1bAHa4pN1ZnyaNnbdlP9Bxlyx0WTGkMdd5H/Yxnna5GzMEXO+9JINkeA/aR8b4mauOyjeYBi1HSehei32ysrCG7ujR0onAZaHqH0lI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661656; c=relaxed/simple; bh=H08U5oWZUJNTY30DSm31TfVn5UwgrqSEj7at2YqMbM4=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=tLtsek0Jb0LfPWgu5yopC0f+FuOiqVE3jFjD4q9Tkh9D2egGitKjlJX/OwT/A/29PkoZOKVEGZJ7l37zMWsYDyAqASOuioV90Tr+j3Psg9vXSFESQA7cyoHRH5GDBX5meWfyKJQMvVvuAhyIhTUCtLD2jsi6PUYGKGBvOkU2Ves= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=QcLoQ8W/; arc=none smtp.client-ip=209.85.210.178 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="QcLoQ8W/" Received: by mail-pf1-f178.google.com with SMTP id d2e1a72fcca58-71eb1d0e3c2so2964998b3a.2; Tue, 22 Oct 2024 22:34:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729661654; x=1730266454; darn=vger.kernel.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=/wVoklxOBqW21xTyhDYcC8JN3gnOiU9+L5vGfbyRiSg=; b=QcLoQ8W/VxYiAWIBXj/DXsPGDQXKmeRY4Nl4yEaIkMFtmP2do0OEQPALTQxv8sq6ce W9HHNDP28C5MuDfzK6i/eTyUrRm1X5ZvL3uQfyfM51WSIDMiGGi1excfEL3P9am9XnV/ P+xFkiY6xA5B1fZYXPG1dg9+ihsiRUIWqU/b9RVTMP48kb+kvb61Bfwhy9tEce8rA9qr InTYrmBwz8uDalwz+xguOedr/AXWDjo5g7BTff5PDXPqQNowktzupwA9xzqJcAlCPpxG /5BsYKAf3WaHroyRhawrT9kFPlsLXIw4uqfoFwyJuPWeK5Y9TJhNY1IVjgZSmtBAxSxh VTDw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729661654; x=1730266454; 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=/wVoklxOBqW21xTyhDYcC8JN3gnOiU9+L5vGfbyRiSg=; b=UQAWEGLoT0ErOYaMo18HUiVDzoEgNHJa3gACZwZ3CdkRbTDvh1GfP2LQjhXaKSS4oN LVZZuFxoJS2Aldkjzabttl+c5HultG5J5H9pGP4cDJyjLulmJBVKYQjf7LwnRRZYrzZD rB0pN7mdoYS4MJNXggFEmyIl4CARJcNz3q0md9SUM4H5oZar/7yTi8tQE25mjV6Yv4mU fJ/Y6Y5ReQzbcKraal9vWzP/BNIJR4qgj5fBe82003kNJ27ICO+rc0r/HT1AZN609cR7 qaVQK9AFTUR66S3oes3nVQKdMJot3FfQJghDeKYrXQF72r2GmlqHUemBZd/5w5y+NzVC Jkxg== X-Forwarded-Encrypted: i=1; AJvYcCUEuBCxD4tyhvEkfnGjaBQKrptM+OpI9zzavIO2sAXuh8bBUz713WPn2gCzC3abMlTRSLjUUXxg2hs=@vger.kernel.org, AJvYcCWJmBYIp5OgvS0gVA4c7HpgvQMXJUap6vNyoC4LynvcmIT126cx2UvNQ4k8rqdFun9cLq/hPa43NSiUAZuK@vger.kernel.org X-Gm-Message-State: AOJu0YwjlRwMcyH+RU8VtWIJlSPqdllL5elF+/+QB5/aaEqT4B1eH3JA FMgpOLBIytDaw2Mj9rDy9qnGW58oWrhhg2cSLiPNs3Yj3nvla0Bm8lkyBoWI X-Google-Smtp-Source: AGHT+IGacROSmH/+O42SAkylik2rWf6UAyq1kifRT6Ue1e3+6d9SLf7AmlXEP58plectNdXSlew63g== X-Received: by 2002:a05:6a21:3942:b0:1d9:2bed:c7d8 with SMTP id adf61e73a8af0-1d978bd541cmr1775484637.43.1729661654191; Tue, 22 Oct 2024 22:34:14 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e76e0877a6sm428695a91.54.2024.10.22.22.34.12 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 22:34:13 -0700 (PDT) From: anish kumar To: ohad@wizery.com, bjorn.andersson@linaro.org, mathieu.poirier@linaro.org, corbet@lwn.net Cc: linux-remoteproc@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, anish kumar Subject: [PATCH V4 6/7] MAINTAINERS: remoteproc documentation path update Date: Tue, 22 Oct 2024 22:33:56 -0700 Message-Id: <20241023053357.5261-7-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241023053357.5261-1-yesanishhere@gmail.com> References: <20241023053357.5261-1-yesanishhere@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" As remoteproc documentation moved from staging, update the same in this file. Signed-off-by: anish kumar Reported-by: kernel test robot --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index eeb4c70b3d5b..1fa39bee6ab7 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -15907,7 +15907,7 @@ S: Maintained T: git git://git.kernel.org/pub/scm/linux/kernel/git/andersson/remoteproc.= git rproc-next F: Documentation/ABI/testing/sysfs-class-remoteproc F: Documentation/devicetree/bindings/remoteproc/ -F: Documentation/staging/remoteproc.rst +F: Documentation/driver-api/remoteproc/ F: drivers/remoteproc/ F: include/linux/remoteproc.h F: include/linux/remoteproc/ --=20 2.39.3 (Apple Git-146) From nobody Tue Nov 26 02:00:42 2024 Received: from mail-pj1-f49.google.com (mail-pj1-f49.google.com [209.85.216.49]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5A7DC145FEB; Wed, 23 Oct 2024 05:34:16 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661657; cv=none; b=K35RyRdFh1eahei2Cg/RmspSDoYWuUdwKOmjJGrGyxSyDlt7Ni4ce2nFNLfdmj7bVau6QJf81C56LvsNzHSsxA8Y0t7SD9NmUz5gPwQAcX1gN9XO9pHbnY8PnRfUGWYQ83DuW4ih95cNxdyEzzDdJFmXtc+O9xGi2yziQD2QOCs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729661657; c=relaxed/simple; bh=khqAKUaBlTUcj257l5qQoN0wPr87NJmbqzaFVDfK9sQ=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=cfzkUq7CXvcfEKUfGtalRUz+RTFdTn1ECdiZHp7DlgF3UctlYkBynepgHW14Bqzzwo1ohBJq6UHj0irXJYDAPf0co3UpCC1d7/RtRO1RFCUWBCwY+HhDHuRK00l9LCRZFvSA8EDlQ8tatON2bFdYgbS4fQiEiLlv2l6i1YqgP/A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=F1u4qahk; arc=none smtp.client-ip=209.85.216.49 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="F1u4qahk" Received: by mail-pj1-f49.google.com with SMTP id 98e67ed59e1d1-2e2fb304e7dso5227666a91.1; Tue, 22 Oct 2024 22:34:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729661656; x=1730266456; darn=vger.kernel.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=a5VMbFcY6CEGa8mSQ8SIl+CmW5nmrRXjE9y4EUBsQZI=; b=F1u4qahkl2HjRqj+i6cnU2UXOAR/dSVSEC2b1eAljia3e52JIq5nMqL89o9Mhkuj5o HgSb7r9nXOmEESNzzPg2XqAwmiq5Taz2sDgKURPEvWqv3c3He6b8CcWQPUuj9KwzaAMM VO/vQIlTCyKYTlaUHJV/xK8VpKhS6lTFl2gXnYCIkMIlCV1G4WVrWOC5E8StzTMEDiXv FEcwvFGY5EFu38030o6VdQA4CGFqgwhrOatZf2rc8ppVgpA/+RwjmsiT3o6h6SLwomQD C59ghFI1FFOWVWDSh7esh7F59tBDHQZyqQY7BSsZLgz6DNJoeUm79f+Y3KCUQvOlE3qs YC/Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729661656; x=1730266456; 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=a5VMbFcY6CEGa8mSQ8SIl+CmW5nmrRXjE9y4EUBsQZI=; b=EEWi56oix+pPE9BUpxr5P2LVG7Sk1lK+H0oNCA7Y5yIiR05Erjs2OdvfenHs1wq189 ymJdw+nzvMnVNI949HO+mgRvnw3CTevxr/lE/9OHSMPZ8dcdQQijLF58y038nm70ytVs kCoFHvFn18jpx1QrabUtF2EwJ9v23JEztNjq2DabLsR52nQvPNYUqJ2Uj++Y8exNR22E JbdglpmwUcJq6s/y62ELvuQ4wY2FxtaclosZamAivwbgnIvxG0MUr0BBU2ee8nmSWH1w orNj8Kw/Ne7zllDC/1seMjz6ZnM7ashT8CTybkPRQ4oYPse/8Izl4oP3Ty+lDObzIqFX pxLg== X-Forwarded-Encrypted: i=1; AJvYcCU59tGjnJScD4wcEhQGGSgqLcPZM7eUMEjdUTyVzOspBREhyDYu8YSYEz1FjtiNcRhIQdEoGqQL/AuGIWpU@vger.kernel.org, AJvYcCX+o8QbAvEpFcSL6GpTjUo+x+4H5pJ9Y6GY1qRAOXiTBIRWLDBHeKkbRlF+FjcRI84pH9chhC00YsY=@vger.kernel.org X-Gm-Message-State: AOJu0YzTa25GnbMXO6YD9Dzn5yAY0/ASxdfQOMGA+9oGOoUEmfS9LAuP 8Tz698fsKqs32xW1JTXIf9F1GmoBT0jqbEaVN++eABzPlyxah04X X-Google-Smtp-Source: AGHT+IFmpnftxB6HTXGUZIROek0Di1jrRQY9H0e03R+mkaok0KKf6SbvrWveY4qFXep/gNwiwsZuHA== X-Received: by 2002:a17:90a:fa0b:b0:2e0:d693:7884 with SMTP id 98e67ed59e1d1-2e76b5b5900mr1660262a91.5.1729661655717; Tue, 22 Oct 2024 22:34:15 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e76e0877a6sm428695a91.54.2024.10.22.22.34.14 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 22:34:15 -0700 (PDT) From: anish kumar To: ohad@wizery.com, bjorn.andersson@linaro.org, mathieu.poirier@linaro.org, corbet@lwn.net Cc: linux-remoteproc@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, anish kumar Subject: [PATCH V4 7/7] rpmsg: Documentation: update the path Date: Tue, 22 Oct 2024 22:33:57 -0700 Message-Id: <20241023053357.5261-8-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241023053357.5261-1-yesanishhere@gmail.com> References: <20241023053357.5261-1-yesanishhere@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Remoteproc documentation is moved from text file to reStructuredText file. Signed-off-by: anish kumar Reported-by: kernel test robot --- Documentation/staging/rpmsg.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.= rst index 1ce353cb232a..937cd2574584 100644 --- a/Documentation/staging/rpmsg.rst +++ b/Documentation/staging/rpmsg.rst @@ -5,7 +5,7 @@ Remote Processor Messaging (rpmsg) Framework .. note:: =20 This document describes the rpmsg bus and how to write rpmsg drivers. - To learn how to add rpmsg support for new platforms, check out remotepro= c.txt + To learn how to add rpmsg support for new platforms, check out remoteproc (also a resident of Documentation/). =20 Introduction --=20 2.39.3 (Apple Git-146)