From nobody Tue Nov 26 01:44:01 2024 Received: from mail-pj1-f43.google.com (mail-pj1-f43.google.com [209.85.216.43]) (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 246181CFEB8; Tue, 22 Oct 2024 21:35:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.43 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632924; cv=none; b=gR1rOCIiDU263X0dNS9maFkMKMiBUL54niLStzTycyJ3KRJ+NP3xHcxp8cQwCmKuCDeC1lXH5X+mlBN+hb4Osam0/bfIYAHbOLQn2fI8zcrK+ic6RkX0MZKJTOL3HWi59W9CXQiib11rCfPw7tWUwlq77tGUmIsOlV6bY8ZTr8o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632924; c=relaxed/simple; bh=dFlyp/yLqOJIbJE/f6Jtl/z74dJgLyEpbG6i0Q7bXIk=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=EbGIIZSGck4vm6cSnNV5sX7fsW0ePWo0d3XMc8zPVGTYOh72kp9npVjA2m0QiiTWf9Nkp8uI3uVSkvKl9JTw9YNIhDFt4H3+UO0TRhrUSIDTd2TSO8z7ocOexKE0A2RUB3R6luRcP9CqGjP50T2N9NOSvZy/2a2O64IGQjeMsJg= 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=AaYaZz4E; arc=none smtp.client-ip=209.85.216.43 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="AaYaZz4E" Received: by mail-pj1-f43.google.com with SMTP id 98e67ed59e1d1-2e30fb8cb07so4461766a91.3; Tue, 22 Oct 2024 14:35:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729632922; x=1730237722; 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=UJCRJ5Dxh7BxRk94oDLEQNDTZ7KWVljyZzXVZCPXEdc=; b=AaYaZz4EuLLnEhfkmabbiQJ8F+2GN/Hu+Z0ER45kIdseAtSvpwJ9IWy+yCbE+A1ERv EYNcYYhgYhpWmKawT/8aGXn9cbYIfFwT3D0X+39esA1ZN+Bj5BUXYd4c+jAoJfGujVT6 qaH6lN2KNJrYOtE3ZX6WWiAquJj7hJGVSlVeB0qqBWIbnSR3pmGzXYNiN0z1onZJx934 9pkXUFcONJlwB/MtXquTC8Icts89aNf+SJKHoo96xNr9MMSqhIgngBjZxkJPeMYV1pyA 9dLsAM3i0Tb5thlXt+aO7PYwizWZltOanQe4/c0L9FUmdqukMFttncAjUIA18Pe/gh74 KPZg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729632922; x=1730237722; 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=UJCRJ5Dxh7BxRk94oDLEQNDTZ7KWVljyZzXVZCPXEdc=; b=MVPcSoOgCyOd+v4W2HHIxz3F5Ac4rw1++cKgiSA1wSGn4zCYm1QpCusWwBbVyJkOsS GR76IudI7lEOwjJ3LCauxMSGgfOH6jzztrWYZIg3NukGrCV6SZHLxwrl/LtMrOIJYleT z86i0OMBWY+XT/S/RcPX/BKn13GDZvowNnmcGDl7t9A3o4PJ3gQuOWTqUzUsbVrW+RIq KX+npOEVxW0bgUPxWdE38ZASLPSiCJCyujMiM/+ADWIQe17/RQp2ptLG4D9rwJmJ+rPJ fG9Nz0iBvCEIfuAq3DsZzLqlHzq4Sw+72VTi35ehALM0xA5OELwX85YHnjpRnqOWu0WB 7YUA== X-Forwarded-Encrypted: i=1; AJvYcCUgVZtS10aTU+K3eu0+JPoHFwZIi5JsupxoASqIXFpTZec2nbrey1Wqk02BIE/DqG+D1Lnib14QMW/jNqys@vger.kernel.org, AJvYcCX3rVrH8AiYIDhsF6DxfUdVRrg67QLd3oJ+YH0k6kVN3p7ohcWMNglHB0X2K5XIXW6x3zoD+g0trjU=@vger.kernel.org X-Gm-Message-State: AOJu0YyhDRVwFlidz95hMdMroqIuM67L9DGsiVo0lSSFwGO2uEOmd2dR jJ0jse8cPXvQv9WnIOv+1KeBnX91pHCHuGXawVJhOEyV/vN+CYww X-Google-Smtp-Source: AGHT+IFs0N2ydUZOyY7f24BZ4/6PCvA0vuqnDYUsU6D7S5VpS7u5qtPcD3CVOv+CMI128TdPwrqZSw== X-Received: by 2002:a17:90b:4a41:b0:2e0:74c9:ecf1 with SMTP id 98e67ed59e1d1-2e76b5e4fd2mr438485a91.10.1729632922314; Tue, 22 Oct 2024 14:35:22 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e5ad4ed73fsm6726369a91.44.2024.10.22.14.35.21 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 14:35:21 -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 1/7] Documentation: remoteproc: move from staging Date: Tue, 22 Oct 2024 14:35:10 -0700 Message-Id: <20241022213516.1756-2-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241022213516.1756-1-yesanishhere@gmail.com> References: <20241022213516.1756-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/{staging =3D> remoteproc}/remoteproc.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Documentation/{staging =3D> remoteproc}/remoteproc.rst (100%) diff --git a/Documentation/staging/remoteproc.rst b/Documentation/remotepro= c/remoteproc.rst similarity index 100% rename from Documentation/staging/remoteproc.rst rename to Documentation/remoteproc/remoteproc.rst --=20 2.39.3 (Apple Git-146) From nobody Tue Nov 26 01:44:01 2024 Received: from mail-pj1-f52.google.com (mail-pj1-f52.google.com [209.85.216.52]) (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 5B9261D041A; Tue, 22 Oct 2024 21:35:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.52 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632927; cv=none; b=KIjqm4qhems5vNc4BskD9hTlTCh3+gTDnrOoEMnMfq1z+lfv7edaffJzmcB2L/YIXXYX5qP4G72J+eUSY5n5pzm/uC4wAP6q0+MLasWf7gwZspmtAeoFKdR3ecwsxCQXu1Nc4ad04nyuCLCi8IM+v+ZeZnnU528xt4bru6YF8yk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632927; c=relaxed/simple; bh=NAmUcmye+YqwpPnj0tf2wSxJZ8/wNVMGvWLATHlOpmE=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=m5YsrVj1wGnrByf7MnmlTFs7Pm3pogjttz8eVrcuvW589cxavL2ReNw9+h41kTJynWFhJmdihJ+ch8NinpdYvIIPS+uJpplQNMVlxwI2Kvwtq54xoS1ibZjR+KIRQQWbEQ4zzAetNqESUpVwCp/xSbWrCrvxWklGCJHTXJElbQQ= 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=brBfYcBT; arc=none smtp.client-ip=209.85.216.52 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="brBfYcBT" Received: by mail-pj1-f52.google.com with SMTP id 98e67ed59e1d1-2e2e8c8915eso4840296a91.3; Tue, 22 Oct 2024 14:35:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729632925; x=1730237725; 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=EegGBrvfXRsDlaDJZ8noNC86HMbQuC7VmUGiP+5nn4k=; b=brBfYcBTypGqHQFz89SQ1mU+Bj7swHdDzy6WtNQL+wG1HEkhSwDp7MnSUPQLFe4Lna IOMk3irjmOrEnx45GyrosfSjRr/O12bUo8GI1wRD7KqBIhWBWbh/83AYCXUF5XQ6sIiE SuALl/QQ/EjmZBas70wvar65P01ktqgeLCeo7/D0GYE7SNMEIW1eOiIktrpmkvna1qE4 P8GbRHRBfGMiGFQGuJJ+mGypDYMxq/nBURJg+012FbQjMOAHaBCzh03ljX0y+24w/WgX VL5tQAcKhAOosNnBuLbb824kP2m2/pUhJZdla8Z4yxUNMy5yHK3j5oYO7wsDRPqAqKLM aFmg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729632925; x=1730237725; 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=EegGBrvfXRsDlaDJZ8noNC86HMbQuC7VmUGiP+5nn4k=; b=C5l9Hxq5AzrgMLomDSJbUTGibObjca/T8v1JuSNSebWIDf35KORRn1wx/1EMIADpCX AfhuOh+T/BaIkXIUuGDAfzXej2pQ6JgKPySTmySe8gUPtPpkf/Al1JgZbZSiZI8k4YCY MiOcT0s6Z44n04wOvIUDZxv4SakejWb/D8SOyL4zDYrm0RLF8zS7hOhr06pcXISG+2IL 9xcs+5IhDu7ZJXAsxd97ngfT1NoCce2hTeXyvSZfYuzdnnPCHY+l4lRJiDO1wNjpls5J wHFuHIqx3UVwm3CZuJH7fM5p7mSBzsV3AT5vkEezxweddc456kpMICpLG/O1pV6vFPJd juvg== X-Forwarded-Encrypted: i=1; AJvYcCVI7A5BFOPQ+piDLndq1as1NpRY3FJVnu6q1wadzgUmoEYp6aETL2M2KGBF3L3oe+lXbikOv/9WKrM=@vger.kernel.org, AJvYcCWWWdgt5HSEDO7v6Sf88L/7Zro6ctTpe3ad4tiojT2lAzzjxPvHoJz7WuzzW+sQgEDqxF3XSgiKQWFhjJ4L@vger.kernel.org X-Gm-Message-State: AOJu0YwSACDLQV6+Pn6gkZMFn+MquqzhuxiZ+QbFq+uE5OeJRWvotQyq LE9w6NZsKar6QjrGmDApT6SKS8y0lEAWvETnJJkZylUx8p4dpC3f X-Google-Smtp-Source: AGHT+IG2DmGYAdvaMuFuKuCEAUugZFchAclQ+HkC1ov8BwyK8vMP36ljNgqYmp0VwFdSDpoL8dx35A== X-Received: by 2002:a17:90a:7e87:b0:2e5:e269:1b5a with SMTP id 98e67ed59e1d1-2e76b73c852mr332795a91.41.1729632924197; Tue, 22 Oct 2024 14:35:24 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e5ad4ed73fsm6726369a91.44.2024.10.22.14.35.22 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 14:35:23 -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 2/7] Documentation: remoteproc: add more information Date: Tue, 22 Oct 2024 14:35:11 -0700 Message-Id: <20241022213516.1756-3-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241022213516.1756-1-yesanishhere@gmail.com> References: <20241022213516.1756-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 --- Documentation/remoteproc/remoteproc.rst | 564 ++++++++++-------------- 1 file changed, 226 insertions(+), 338 deletions(-) diff --git a/Documentation/remoteproc/remoteproc.rst b/Documentation/remote= proc/remoteproc.rst index 9cccd3dd6a4b..c04f1f1080e4 100644 --- a/Documentation/remoteproc/remoteproc.rst +++ b/Documentation/remoteproc/remoteproc.rst @@ -1,347 +1,235 @@ +.. 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 :doc:`Documentation/staging/rpmsg.rst`.) + +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, --=20 2.39.3 (Apple Git-146) From nobody Tue Nov 26 01:44:01 2024 Received: from mail-pj1-f51.google.com (mail-pj1-f51.google.com [209.85.216.51]) (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 5C134200B97; Tue, 22 Oct 2024 21:35:27 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632928; cv=none; b=WjZJTMq7f2R2uxKaEKA9bU3b/bIIJ4qSYNBbwika49tTPa8jO3URk934crQZhZtKD09hrbAT50KmK45rPkDSz6cAbN176oD6gBaGEhasNN5S5YjL3+cZyBPIpb+kqheiiSgfTy4tMm0893XH+zpnhwyErerApZdDkv8VBGdkpL8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632928; c=relaxed/simple; bh=ckaECOYXQ3oUgnFFA+gq4+c9Cv7Jamy9SW3zoT2xSZY=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=g0gbWNpoN6afJe0nQShsc/MnSfLMCf61+AnSBnzZUjQV8yOfemSNC8TNXMSmd6pSXssuMqXy0fqsHG3ZP79ZucltNVP5pqmeKHNfQAG4P5e0yngiND64lT/HgFVITr3UD29gzqdE0ZxzQLQ6nDY/iMoFjcNTkynu5b5IWdz3EEg= 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=CDPi0605; arc=none smtp.client-ip=209.85.216.51 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="CDPi0605" Received: by mail-pj1-f51.google.com with SMTP id 98e67ed59e1d1-2e30fb8cb07so4461802a91.3; Tue, 22 Oct 2024 14:35:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729632927; x=1730237727; 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=z0NGNJR4A85YquAcYDyAC3sQJGb8NuTCy8V8jRDMofU=; b=CDPi0605ETqOZV3vN5RhCsL6dUigJojq1hKwM5s3ZoSEsO8ItwKBWBiNfB65wkDUfE esbapZk+q1JotLKKfvRd1pdXOLCSZlwKvJ3WTBow+23IXvuP8CjPuv4OGEd1EU4ADjdL TYEpEYX4ap+b2+ZQ2pOPk0wDEPEMnhA8fFONeDYtaA0bJy7gctD2VFL9xqhAJDQM3X9F 6lgCoBqxXq2f9lN0etZOWG0AQg481kc1ss70ncqBu5GoCmpONQRrCRNu0wmkuZBTM5jq yDdrI/QyLhmhGeEM4SMcBYUeuaj0KhmbhXGho59O5Elb9DAoonHO8RAQNJZUfN8H4nax 219g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729632927; x=1730237727; 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=z0NGNJR4A85YquAcYDyAC3sQJGb8NuTCy8V8jRDMofU=; b=YWL8PPIes6Xnm2XWk0lrYv2DfsTkyzl08qLYexS2ioSVVBqBkquJZN2UOIR0TlrARG Q0OFaDIdUb6WOMyuhwUHxFH7/RSxvDNXVK/Tm8UH94lP9Gh/cDkmWw3lHZXLxoIMrzje xxdgo9wJCibdGLgr3yZ/64GWvHMAJRv72WB3sXoMyXgiiIkGTLczAMVlgK/WjtvDagzj 8Eq767HJ/FNK/VVmFnLo0adO7m93lN5/6dwrRKA5nsTl42YparSZAhJ23iLKjGzY4wA/ hDcdVz/D7D8smHdMxVYayR05Oav6fVZ9DpadtNJDSjDlStF8zKF1EJLYq3Grhe3sp3nx 4AKA== X-Forwarded-Encrypted: i=1; AJvYcCUuDpD+KjsxqxRIgwOV9vkxAcDUeQPULXfUgLknw1YCdW8WxM32AQb8G1pipXM6UJbYOYc2KLXT4Nnt0n72@vger.kernel.org, AJvYcCV++mfNC3dSgWxa+ZZtZC1QdSzvwvmSpKAz8+vMN51LFhTUt4eEWlBjxu7IVmpp/HzG5R3p6TVtfzk=@vger.kernel.org X-Gm-Message-State: AOJu0YyUsdVYuw0qUXDgki7CZRq3zNCRhd6GUrmIPTL9W8VldS+4DSB8 dRLUD9jYd3JKbnfxDfq4odZDMPgZ+GwLaPCz9377sEvsMCU6DOoZ X-Google-Smtp-Source: AGHT+IH2jGAJliuhOFOsK9yk/TtpPhYaclrQc7NxH0+t7mZlt694l0PvRq9jNXMbg8iRO2UvfvwXXg== X-Received: by 2002:a17:90a:6888:b0:2e2:8c75:b45 with SMTP id 98e67ed59e1d1-2e76b5e6406mr384799a91.11.1729632926633; Tue, 22 Oct 2024 14:35:26 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e5ad4ed73fsm6726369a91.44.2024.10.22.14.35.24 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 14:35:25 -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 3/7] Remoteproc: Documentation: add the main index Date: Tue, 22 Oct 2024 14:35:12 -0700 Message-Id: <20241022213516.1756-4-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241022213516.1756-1-yesanishhere@gmail.com> References: <20241022213516.1756-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 index file so that readthedocs.io pick this file up and properly build the documentation site. Signed-off-by: anish kumar Reported-by: kernel test robot --- Documentation/remoteproc/index.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 Documentation/remoteproc/index.rst diff --git a/Documentation/remoteproc/index.rst b/Documentation/remoteproc/= index.rst new file mode 100644 index 000000000000..af3573123ee4 --- /dev/null +++ b/Documentation/remoteproc/index.rst @@ -0,0 +1,25 @@ +.. 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. + +.. toctree:: + :maxdepth: 1 + + remoteproc + +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 01:44:01 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 97CD1200BB0; Tue, 22 Oct 2024 21:35:29 +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=1729632931; cv=none; b=JrRG6ZZ3pdAWoQhikCDjU65SwKTEx+JYTBGSylv4orPhR4CKyvLHtHb4ap7+YbUSBmEl1RfqowrjMTfkSgdWxfM3BniKu8ztezKyQQOyYo6TB3MQqLDZbeUzWPInSWxqQETJ2/ElkFUSlC7cpto1311GHW+2rNHNnagQaAaKI2I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632931; c=relaxed/simple; bh=QRFEs5Qiy8f+Av7QjdD+fmgfuQSyPAE6UuVnpXDtEAs=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=IkcWj/z5N9cEYcSuuUBSjCcPjZp3BO2DY1FQS8EKZWDZq55QXlUMoYuu1YLVp3SQRc03WfUqBOwC6DNy1ct5jRrxwEUzcLUDia2rrTxrYoBVy0uQBIC7wSNjznxO2V89RSmlaWXoyTC5Jo/2Rx12ThH7bFrBaTet3tptmIHfOdI= 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=S1Ab2ZUE; 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="S1Ab2ZUE" Received: by mail-pj1-f41.google.com with SMTP id 98e67ed59e1d1-2e2dcf4b153so4469525a91.1; Tue, 22 Oct 2024 14:35:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729632929; x=1730237729; 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=OK9gty8uo7RJ7bfJzWDN6HqnpReqAoiyWd2OW0kwKik=; b=S1Ab2ZUEOF4NbJ43Jnlp02icHMyBNW/wNr9I17GwsWUoQXJ75o5mpYSAoBmfGqcYZI hMaOAEZxkostGYV4OmtsUy4xZKufJnasMpo4MWT8XZlSITbm0/DQwUZiIryfeJVzXgSs WGEGEjcgSgmffa4YMxdCAYZSD1gHg+T0qkuPQc31byguwmkOmY/5I58i522l4dx23Hhl 7sy5CXjYUt1wwoNl335ouMHVy5/6gbz8nd33AIJ24KaWgEz+XGW27FjHaS3gxFSfcn7E 5pg+BhDXgDAXqsdCSDXnn5RXOZCl4NMQcx12Y2qBcTR0Ni3E7lFliK+3NnV6TYY5PBNH XQAA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729632929; x=1730237729; 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=OK9gty8uo7RJ7bfJzWDN6HqnpReqAoiyWd2OW0kwKik=; b=G09TavPl0YGd0sXIKHhCFMV4q17s6C9HeTf+hU/1sW/KcFt7Vn+9bs5dz7HQAYJ6w1 rmyTUA7LHuibeQR1OYwpNbtxLAA1G2uRqes+ZfSQctFFt2iXjSbomfQCd+wZ34KFL7Pz slbczi6xKctPzAS5UArHO4yj48lzDH5Z0OqZeKJzXdGfS8Gc5FOq+HijpSbbZheenTVR H5xWn617m/TSxUcEKLD8/d544xdi4LcnwxpngXbt8wJoBbIePXBSJP6uB2TmdQT5dkxv fnztUsPGurf3w4+3WK75bDKxgEHd2bWMlCF3/eBAYT9pa46Alea6Ok58JoTDnDDXzwR2 6qTg== X-Forwarded-Encrypted: i=1; AJvYcCUL6az26DrSLZMt69ORXNAgl/xubsmpVV5t1GYLHvvfgKw88XoA7e5nBttuu7CyyOxPOOB8E1z1DmY=@vger.kernel.org, AJvYcCVRVR5oGQrW6TgY7mIb7TJUSqJv+CWZciBmUx85GIfePk0ctYi7o+BDGRdd+fN/nyWIsMl6O4L2cxZ2cCv+@vger.kernel.org X-Gm-Message-State: AOJu0YzIgkhw598Q8yQaDWWIMn7xRw2gUg2LIqMM4K/J/2JACS4SqLzE B6e/mN6CYFsIP1EB05hxRS8sMApUKQTKrKPK5qdz2xA95IF45VsM X-Google-Smtp-Source: AGHT+IG5fvjBhiuE7hOfodjNKb0FGkVfLuJ5Y6dzQSvXIwF/nywI4hK65xSP/pugDxSiAJn2iF+o6Q== X-Received: by 2002:a17:90a:6547:b0:2e0:853a:af47 with SMTP id 98e67ed59e1d1-2e76b7270e6mr369102a91.33.1729632928727; Tue, 22 Oct 2024 14:35:28 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e5ad4ed73fsm6726369a91.44.2024.10.22.14.35.26 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 14:35:27 -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 4/7] Remoteproc: Documentation: add driver api Date: Tue, 22 Oct 2024 14:35:13 -0700 Message-Id: <20241022213516.1756-5-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241022213516.1756-1-yesanishhere@gmail.com> References: <20241022213516.1756-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 --- .../remoteproc/remoteproc-kernel-api.rst | 239 ++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 Documentation/remoteproc/remoteproc-kernel-api.rst diff --git a/Documentation/remoteproc/remoteproc-kernel-api.rst b/Documenta= tion/remoteproc/remoteproc-kernel-api.rst new file mode 100644 index 000000000000..018c5bf9b3d7 --- /dev/null +++ b/Documentation/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 01:44:01 2024 Received: from mail-pj1-f52.google.com (mail-pj1-f52.google.com [209.85.216.52]) (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 57675200CAF; Tue, 22 Oct 2024 21:35:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.52 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632932; cv=none; b=GevwmbpyybFqpCDNaIsFFDihYwY7W7A9I1MnOqFXBTbGnjl8hiCW0IaIvHnq7qJIMPz+l2+PU+lpmMyPDNNnVUWHjQCioPeATO57gdyklZbvTQvXxWbwGhJWCcu94HGeOX8VRIGBtjmOqNXyq4uVUdnhk3VE7shQpJLLxpbvrVs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632932; c=relaxed/simple; bh=oupMMCevCANOEJ/x0t7nUEeAcGmBvhsy7DMi0FF34Po=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=Oh6YJeHrKGDjeyU0S+Z0svFNOGFwAgZ5ZExUS/m7jrbH4v5DlYhnFFP++hFPowkMcGRlGDaCDLtm7r3caZDb7vQF7ZAvWN0sYKhkX51VX0/al4aFA+BbfK3tgBn90pqxn+RAGBUkxiq6w4hyW+JHblZ2sSn+Gawhf2KljJltXgs= 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=Je3Jfcwq; arc=none smtp.client-ip=209.85.216.52 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="Je3Jfcwq" Received: by mail-pj1-f52.google.com with SMTP id 98e67ed59e1d1-2e30fb8cb07so4461831a91.3; Tue, 22 Oct 2024 14:35:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729632930; x=1730237730; 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=yveh/RP4/RFoq633tQIwSkvGafOVfAL4UOgy/qRPxaA=; b=Je3JfcwqJB2+4aa2k9WtrhrmZWUpvxzox2MPhpI1BelQrcBXqH8Ta/Egi6Dpgp2Ght EVXQpLK1rzeTYRmn5bw1ROI5gRROEngcLf18Hkb7EeWIyUGdTa5cZ7zvmD/veBDUfNIZ 1w8KmKQ0fQM/6qO/103//mUboajXtKSQuiBh2SAicNjjVGl6SpvPLRvzQ1WsrzYSPVzv Pw1htDab7EJ43qW7Q8VqsaPV5ZQsaIUnpWDqkXUVAAVkLTpDp/dPE6Yjg+QKUBc/BvOA 9ofjm4A5Akq+NaZ/cb+/IcK/033+IelWsTG1TtyXB7Zr3F8/vUWGC/RRN5M1IiB0RSo6 ZAfg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729632930; x=1730237730; 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=yveh/RP4/RFoq633tQIwSkvGafOVfAL4UOgy/qRPxaA=; b=aOum9RpOBkuvrT6iOEm3eTOcrKvYp85zrw0fpDZdS6GFkGKZcgMlTczaA1zD9N9e1P TyNWocO/5NBslg09qCeKpNznB1DIOERPlZ29r4zgNt85R6iF+acpeAFPYLXzLl6iza/r 2v9AgvZKMVTk8jBk5G0ch8WfwPxbICGZkw6VgF0vGaXkem7MViLkfMpZNViPl377MRHj kAkt0RLMIqv/kNtFZT8G1FveJOlbWvZ+9FCB9+AKjVE5ODT9LKqZsTF4l4sOMo0MCtUb j9iz/0Gz2tGppKxRLzSI57y5uW0j0j4FHDCxybwBI9CV1Sc9IVod+TEiKYzOeUVz+uAX l2KA== X-Forwarded-Encrypted: i=1; AJvYcCUv+m8y1+j+lLlLFjs1WfxWjXWz2HtUsPKrl1/NSjVqZoPM8psKXpp4Usb050H0Hk6zLeJ/acASPZwsxxx/@vger.kernel.org, AJvYcCXvUQwuOsqcXlLv2sy78i9oIm2taYv+TOpIDAnvwkttwO8n6k9E0HtsAPdrqrbPG7RTlDwItmfFAC4=@vger.kernel.org X-Gm-Message-State: AOJu0Yyf0ErZGmHh6geXSFa03Cnh1Q8j+VDpctpcpWQZ9LuDKMLA4GjP I5tK4mZInIjiBYMPMnsm3WkvWsj2ZVAhhdnrkQNf9x45sbZm9MWz X-Google-Smtp-Source: AGHT+IHaFyahdrsyUVs3OCfK6Oz7muS9yWz/K06pAToapxxyyL8lo+n/NRgaxS9JywYsl8PJJGRG4w== X-Received: by 2002:a17:90a:b89:b0:2da:8c28:6561 with SMTP id 98e67ed59e1d1-2e76b618c4cmr393517a91.22.1729632930556; Tue, 22 Oct 2024 14:35:30 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e5ad4ed73fsm6726369a91.44.2024.10.22.14.35.28 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 14:35:29 -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 5/7] Remoteproc: Documentation: add userspace api Date: Tue, 22 Oct 2024 14:35:14 -0700 Message-Id: <20241022213516.1756-6-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241022213516.1756-1-yesanishhere@gmail.com> References: <20241022213516.1756-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/remoteproc/index.rst | 2 + Documentation/remoteproc/remoteproc-api.rst | 75 +++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 Documentation/remoteproc/remoteproc-api.rst diff --git a/Documentation/remoteproc/index.rst b/Documentation/remoteproc/= index.rst index af3573123ee4..243b5652cf79 100644 --- a/Documentation/remoteproc/index.rst +++ b/Documentation/remoteproc/index.rst @@ -18,6 +18,8 @@ Authors: :maxdepth: 1 =20 remoteproc + remoteproc-kernel-api + remoteproc-api =20 Mailing List ------------ diff --git a/Documentation/remoteproc/remoteproc-api.rst b/Documentation/re= moteproc/remoteproc-api.rst new file mode 100644 index 000000000000..548d3658fc1c --- /dev/null +++ b/Documentation/remoteproc/remoteproc-api.rst @@ -0,0 +1,75 @@ +=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. +:: + echo start > /sys/class/remoteproc/remoteprocX/state + echo stop > /sys/class/remoteproc/remoteprocX/state + +To know the state of rproc: + +.. code-block:: + + cat /sys/class/remoteproc/remoteprocX/state + + +To dynamically replace firmware, execute the following commands: + +.. code-block:: + + 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:: + + echo 1 > /sys/kernel/debug/remoteproc/remoteprocX/crash + +To get the trace logs, execute + +.. code-block:: + + 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:: + + 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 01:44:01 2024 Received: from mail-pg1-f176.google.com (mail-pg1-f176.google.com [209.85.215.176]) (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 2E7942022FE; Tue, 22 Oct 2024 21:35:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.176 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632934; cv=none; b=eXwhXKbwpvKzlYtqc+xeHcrsZEu2ri4fYbo9xB/Z5wc18MNzu9+6ct0SQjwpZHKdgS87sp6K9wJXlWqvgvtYnFUixD0Fx3B0a/ziOCfOK5TvtTh232iczgJxFsGURbdDLG5i4heSfSqaCvoBEimBFORZEbnGT8Ci8zlPLx3rCjk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632934; c=relaxed/simple; bh=JG/YDm/5RZeVRWl9eZ3sDAgg1bpmLA+CzqXOtqPSzb0=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=SEoTNRlNOYGC9g6Z0ti4M6yhKNsJ1HwPcmMlMmBsrr2O8zY1o/YW1QZNL+l5VF3fYfiy6sWxPd/ibBJAUUpj09cdguC0IQIDCZV8qePSj7QoPGkDPPeNGytenNMsSsWYeMtSd5r05C95H3alUWrl7KEkvRMErkiRapXyQXsdtxk= 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=UdvEzluO; arc=none smtp.client-ip=209.85.215.176 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="UdvEzluO" Received: by mail-pg1-f176.google.com with SMTP id 41be03b00d2f7-7ea76a12c32so4955084a12.1; Tue, 22 Oct 2024 14:35:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729632932; x=1730237732; 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=ExRxCgggPFAmIkz7VqayS6sIh76VaH0SrIaHrrXD0Ec=; b=UdvEzluO+fwxD2ZKj/qkTojRUnLkGiHAFKuUeiJF0y/WbVUdnsai3KiBHFUnad2HnI sOd27e6sppxBkslYQgOuLikC/zMoOqrCNnWSJbfRFtAR9KSsBJyDzhi6PKapPx62tnIt Wjq4BB/CsKMo0nGS3xZl9eyi2XgEPxxub9bv55qnYI4T3rODHvk+vSZ9FPSgdi3emqRq j6kFfnDEszks0A7FkWAZrp4YoIEXxgPWgRIcxltpi7vu9qbmNvahrzhiAEjgfiGxDWzl 7HsisRrXp9HNwyy1YetsYkpmjMbBcmLyw/cXywRKcuSKAiCLNosNg4A6p9t/nCOq8+RX HKyg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729632932; x=1730237732; 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=ExRxCgggPFAmIkz7VqayS6sIh76VaH0SrIaHrrXD0Ec=; b=iHvDtc49LPlhWAXeAc+I7R6OFfxLE9TUHd5Y0pIb1GfTc3B/fhzZYnCY+3Hi86li3S TMwZNb7Rig7xiIDRbTwLc0ZfRBX35bH36a3S8n9RlGJ5vAZNGRg31Dm588pQL9uNeDIa kqaHZ1MBThEw0gR7cfm7Vfualxg4tv+c9/axHa7q+Myw3WqE1xYLmhbP99n5piPXaDwF E3Z1+Zxn3NFhfwQbQ2n0AE4SLYUHxfByWVflOQ7E1QWI6r4kOfm9RbEcGlCTGkcDfyPp BuOPkuSxucLhTZpgp8Qp5O7rJ4BN9wfK7UGm8wu2LIk7FvAcXWaoMsgZEYcMOrsMBAQF h9Zg== X-Forwarded-Encrypted: i=1; AJvYcCXtXFoEDqrC4bTf59lDnFeAFIOVK79/nJoIDMgAJ+aBvUCajzlBsWCRT0qttb4gCFmtRWEXVkE6QOw=@vger.kernel.org, AJvYcCXyAlQFzp6RDjWB7NDqQfu0EHqrogWNz8ebqTtKURwSLFo3/O57bGmMQDoDGpnuRfqKiUqPvnrSbaiqMw+I@vger.kernel.org X-Gm-Message-State: AOJu0YzEnCETZ9Uy5V/xJoW0+NIbbU/Zhl1j2Zu37yM4kpskoHLVuRDg ykZMjOn7epnB1vQjIY0e3jyiT5+87ZKbbBJiVfCikinYTsg9LkzA X-Google-Smtp-Source: AGHT+IF8JpU0xXJrGf2MiesA/O7dXMJtGuVfnM7Z4/bSrugCDEGvc9uuk6DoVFqHeV0JJhj5l/Jwtg== X-Received: by 2002:a17:90b:4f82:b0:2e2:d434:854c with SMTP id 98e67ed59e1d1-2e76b5b6a35mr386797a91.2.1729632932387; Tue, 22 Oct 2024 14:35:32 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e5ad4ed73fsm6726369a91.44.2024.10.22.14.35.30 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 14:35:31 -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 6/7] MAINTAINERS: remoteproc documentation path update Date: Tue, 22 Oct 2024 14:35:15 -0700 Message-Id: <20241022213516.1756-7-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241022213516.1756-1-yesanishhere@gmail.com> References: <20241022213516.1756-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..bcece98ef32c 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/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 01:44:01 2024 Received: from mail-pj1-f48.google.com (mail-pj1-f48.google.com [209.85.216.48]) (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 C75D82038C9; Tue, 22 Oct 2024 21:35:34 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.48 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632936; cv=none; b=WFUUe50PN27NiWAqGtH1+XNz3VAKdcjSBMWrQN2kGeu7PClHFOuNmVwuUGjLr2MxsEMyntadz6Q0OOJTiRZ03STfwbrKTxfLDHDWT3ElhJARmB2SdOXVh7nI5eUlfkdg+8WeiEap3WYNWD/WI6hLt/43agwRS/4j7c63RTXX/38= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1729632936; c=relaxed/simple; bh=khqAKUaBlTUcj257l5qQoN0wPr87NJmbqzaFVDfK9sQ=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=UCT3JubyHp3vjsTaHHSfso96UTGCWOPvX/4m8cWYp+GLdtZqJ4qNFbaXTHycxtmjsGD3iXxSjNYvcZ608vTDw0ZtWw0vTYwOQSVPcfoStfS7f2Er2QizUd9GRhzsXyVN7TiSLhLbDXu/Nih1ep4SPRDq4QrW7Es8WrqxxV3/RB0= 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=RLz+mVc/; arc=none smtp.client-ip=209.85.216.48 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="RLz+mVc/" Received: by mail-pj1-f48.google.com with SMTP id 98e67ed59e1d1-2e2a97c2681so4463205a91.2; Tue, 22 Oct 2024 14:35:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1729632934; x=1730237734; 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=RLz+mVc/wkmZi7TBEPNSkSCQ8KLoCsgXv5YpB91GMk+dTeDNvNlI2f7923q9kBVaUX ppFgW8bxYtxR+BF4nDcFJc/q/ysO3c/8TBKlhioUtQhILg0eIH/VNRsd21S55AwSoNOu GVjd/Ou6n59cqtp1TYh+anUTqctc3q9cqIuIz/epfTG9uQwHW8wBYaCvkCqlIbFgdrcc rnUEQA0VRqT6QWTA7vE11vV8Cm+qDLNuL9L+ynMM2whiyES1LYAPFoWjux5OIDthgoFl gukS8aivrY9ONGTZLUurl8leBc4ATnb9BmnRrix251AzpgCyjTP2DLw/2Z0Mx5bngjJ9 JPjg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1729632934; x=1730237734; 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=tBsFUOAgU0l5sVNlNwa4XGmAYhLRj93xUw6hGcWznzbLtk6HBkLkTzJ1u+VeZ2AiLE g1LxFPgGz4hsV7A13cVaeKvy5yApG5bVfnnogeTehRqHn06KjmB3PuUV5Ul+8WQjnXFm PSQyn9f9JR/fAJ+go2IivIirghfG7znW0+MpyNFnng6N3f/GrrHV9LO+VGZdKTp/cUu5 ETUvaUsol9K0V/Xt7em1ZFPtqRfjwKdLO2tED6IKcADhcP1FwKlXl4/HJCPnLTRAgKZB 57YiHFgMyxfVm7L2Wz7XuuzPkm4jdFCIWgYdQ8f49Hv8OgsuZqyCbbzUYKr7LoFGcX7K U6Xw== X-Forwarded-Encrypted: i=1; AJvYcCVCkVmwjz1C70LaenA8dfYAQcNmZvJpwXL5YM+QL3u4SGYV9O929lm2Wxe7SGQcM2elKtiEe6hZ5to=@vger.kernel.org, AJvYcCWfWuALV6k8uJ8ii4hsHeIstLHUMKFjQbVbmjW1pZlpvSFgkS22awKpFgi/9s/qYk3LPXAZuaGjiBhMXZHO@vger.kernel.org X-Gm-Message-State: AOJu0YzDr4uQ9jUiiBEA4sMlEaLRAqoy7zFNhl+JTFI2DohrZdOaB2JF 72l1bEZfrCLtGtwhyotgFgTL0rHxTLtFmpnqUCoQigBVTuRBL5gy X-Google-Smtp-Source: AGHT+IGoyJ44rXCIw1j5svtG4RuoSRt31SniDfJaYujZUOpfUUFYRHCYtHqX/vo+ifoh3XM2xD7Cmg== X-Received: by 2002:a17:90a:68c8:b0:2d8:e3f3:fd66 with SMTP id 98e67ed59e1d1-2e76b727d1dmr363309a91.34.1729632934138; Tue, 22 Oct 2024 14:35:34 -0700 (PDT) Received: from anishs-Air.attlocal.net ([2600:1700:3bdc:8c10:1c93:3e9d:2c84:d5f9]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e5ad4ed73fsm6726369a91.44.2024.10.22.14.35.32 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 22 Oct 2024 14:35:33 -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 7/7] rpmsg: Documentation: update the path Date: Tue, 22 Oct 2024 14:35:16 -0700 Message-Id: <20241022213516.1756-8-yesanishhere@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-146) In-Reply-To: <20241022213516.1756-1-yesanishhere@gmail.com> References: <20241022213516.1756-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)