Received: by 2002:a05:7412:bbc7:b0:fc:a2b0:25d7 with SMTP id kh7csp2710472rdb; Mon, 5 Feb 2024 15:34:46 -0800 (PST) X-Google-Smtp-Source: AGHT+IFNt/FDDHWeYWzQrJugvOoHNzv2bN/WC3xQYhrUIZ0sTbDsqih46vvou1jxK5oHjmp16k9l X-Received: by 2002:a9d:6243:0:b0:6e0:ade8:3d93 with SMTP id i3-20020a9d6243000000b006e0ade83d93mr783065otk.1.1707176086244; Mon, 05 Feb 2024 15:34:46 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCUuIpAwHSgPf7r4MEGdeUMQrM6iEG6tJgoLoUSXKUhgujXI2Cnrt2AP4QIJlO2mzwwOe2N0WqR0jIHnZk771DlZweHbz189hqIEg/PTUw== Return-Path: Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [2604:1380:45d1:ec00::1]) by mx.google.com with ESMTPS id w22-20020ac857d6000000b0042c33d3083asi457449qta.498.2024.02.05.15.34.46 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 05 Feb 2024 15:34:46 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-54091-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1; Authentication-Results: mx.google.com; dkim=pass header.i=@nxp.com header.s=selector2 header.b=D0z34VYs; arc=fail (signature failed); spf=pass (google.com: domain of linux-kernel+bounces-54091-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-54091-linux.lists.archive=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=nxp.com Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ny.mirrors.kernel.org (Postfix) with ESMTPS id EADC91C23F10 for ; Mon, 5 Feb 2024 23:34:45 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 1F0FB4F216; Mon, 5 Feb 2024 23:34:04 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=nxp.com header.i=@nxp.com header.b="D0z34VYs" Received: from EUR03-AM7-obe.outbound.protection.outlook.com (mail-am7eur03on2066.outbound.protection.outlook.com [40.107.105.66]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 74ED04CB47; Mon, 5 Feb 2024 23:33:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=fail smtp.client-ip=40.107.105.66 ARC-Seal:i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707176041; cv=fail; b=CIw2lC2zzsJomo80Z3CbpGorWelmy5JINwW/R2HwWy63TwMQisediS9RaT7afYecnNM46nkb91HYqRrmoGieGYYndGGfU/xLaK1n7z1KlK8Cxl6GUQ/8R7flWWxekeeQyNiqDnq0UyOSpUslC+imWay7258vNVA/0r93/ZSu80s= ARC-Message-Signature:i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1707176041; c=relaxed/simple; bh=cbqJ8B8zoNb1wL5cvsafYdWHOXGpucToAPhTV87jaLA=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: Content-Type:MIME-Version; b=eibD7RLq1mCXthVtgfsm4V++k3bOUDXBYG/ZvjDrBG7to7bScyYZ2S6qfZwrLLAJsnhAqX1XyXakKlD/vn1z/Z5XaFlS2n3zt3lksxi2Ao+/f8FyX+6HKJPivYxAfLbEgxabDBCyy2QEGpGXtArufAHYQVM3+jHFj5T37klm/h0= ARC-Authentication-Results:i=2; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=nxp.com; spf=pass smtp.mailfrom=nxp.com; dkim=pass (1024-bit key) header.d=nxp.com header.i=@nxp.com header.b=D0z34VYs; arc=fail smtp.client-ip=40.107.105.66 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=nxp.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=nxp.com ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=apSsAoSbMlFt4q40QQK34/BikBhlN9Nhm+TWLflrlZ10GypExc4/f/7CoJGKwzss47krQj8wfCYsgOozWms9elEue3vw8mp8ZZpMMaBaZN1WlMpVrKNZ43XaurE60jnuwf45KN89LKz/8kf5gs0w6I+UBjbyMJnMRRtYjGvGhuFBe8Q2Mqt65OPDYUDZNNQWhtGZJBl+ExmROjp8qHHBNiiinuYtJ0GGvy6HQbWyw38InH1A5d8oV8s/l4SXCxgoE57MHOgjR6lDvqi+QwrexAtLuDeSzVcZgvFN+2So+2RQg5cBzsgcFE5B+TZjPkraISpz1w5cvy/d/bA2u71OCQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=NcAD7n5DFC8zY5SMsqG6DN1S/Q3hAt3IaNHuvXjxowM=; b=AXZekxsuBD/dqB22UDfz/BqY0t6PPpXOWa3sDUYlwCDnm9yajbyOlfBtrlk9oYxDQkc+ksSdq6XjrKBzo+lLArmmL6ymS3756g4oeIZdMWed7+5hJ2SU47iE88buahNZ9UtSa21beE17JOms0VcYHpPaGeSQwYKA0AUiLKJvmb7HPCWXYuDBnsYaMNti6ovneF56EEweTxE4EZy6KgnotVJLNFMg3W08NsyV1khOpxmiH3QqFofHaiXBIff4khetnhfA1bNgxQJ8Akg0wzs3Lfs6Q4HhIxUymVYkfbgYOzB9/CjNV/nTwCKoitD/vyW662BUhPHyfj/tNa94QVwPRw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=nxp.com; dmarc=pass action=none header.from=nxp.com; dkim=pass header.d=nxp.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=NcAD7n5DFC8zY5SMsqG6DN1S/Q3hAt3IaNHuvXjxowM=; b=D0z34VYsBVsxFBY0HT9xy2q2kam2a1sWr5YoEUCOrjPx2+I99IBdwZ0osGWi8AQ/NH92DcBwnqiuJeYyb0EWHibq0N32IUMBzKHsEh7ep8jx9FmVeR/Gh4qngzhShdgmqJJ+PuUCNeMR9hpPGYdh+rT80KeVXryJEiDapN+FTQ8= Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=nxp.com; Received: from PAXPR04MB9642.eurprd04.prod.outlook.com (2603:10a6:102:240::14) by AS8PR04MB9205.eurprd04.prod.outlook.com (2603:10a6:20b:44c::13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7249.34; Mon, 5 Feb 2024 23:33:55 +0000 Received: from PAXPR04MB9642.eurprd04.prod.outlook.com ([fe80::c8b4:5648:8948:e85c]) by PAXPR04MB9642.eurprd04.prod.outlook.com ([fe80::c8b4:5648:8948:e85c%3]) with mapi id 15.20.7249.032; Mon, 5 Feb 2024 23:33:55 +0000 From: Frank Li To: frank.li@nxp.com Cc: alexandre.belloni@bootlin.com, conor.culhane@silvaco.com, devicetree@vger.kernel.org, gregkh@linuxfoundation.org, ilpo.jarvinen@linux.intel.com, imx@lists.linux.dev, jirislaby@kernel.org, joe@perches.com, krzysztof.kozlowski+dt@linaro.org, krzysztof.kozlowski@linaro.org, linux-i3c@lists.infradead.org, linux-kernel@vger.kernel.org, linux-serial@vger.kernel.org, miquel.raynal@bootlin.com, robh@kernel.org, zbigniew.lukwinski@linux.intel.com Subject: [PATCH v7 3/8] Documentation: i3c: Add I3C target mode controller and function Date: Mon, 5 Feb 2024 18:33:21 -0500 Message-Id: <20240205233326.552576-4-Frank.Li@nxp.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240205233326.552576-1-Frank.Li@nxp.com> References: <20240205233326.552576-1-Frank.Li@nxp.com> Content-Transfer-Encoding: 8bit Content-Type: text/plain X-ClientProxiedBy: BYAPR02CA0005.namprd02.prod.outlook.com (2603:10b6:a02:ee::18) To PAXPR04MB9642.eurprd04.prod.outlook.com (2603:10a6:102:240::14) Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: PAXPR04MB9642:EE_|AS8PR04MB9205:EE_ X-MS-Office365-Filtering-Correlation-Id: 5fccec00-f995-47f4-8ec0-08dc26a2eb37 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: ucEdafYMeVBcornuejJV6yQncZmvdlP29tApgG05FjYE8dx9df2KaPsKpuSD1eEe6bBX9jvsd1JJvNScC/8azJcuM/N6fmWF/Q8uOb4ae3ruW/E8XjejQO0fQWSPh7HyUFomDwiyFzMf376RRSynHvwOocsKaJxpFmXyboXTV6m+KaXBy9DQSoCyFJqqS9y0B0mcarX8kZBPXlHH40QkIvUbGkxF4XMYuiyx0M/IyPd+Scxm+mBMSd/Fxjkm4ZKrOxekt1ZuCcUKH4/4zdrgBjaZyN0q8puAMAD6fW8XvKB6arHcTpM/mMMSP+s6m3CX21+Tm68Px+GYfMYLDF74Qtw3TMYx8v06cvlSptPoGJ70glQ2WVowFEIZHEjE+p6QEsq0f7ikN86np2DRmhy0YqOUIu2AzEYCk3mPcyM+KCT7nxknIuTQz5hrsvRww7eD9mRdQbVgY7DyM3/ZjSZo+9dwo+EriQhXhM9vd2P7lfhZh/HplB/GZrADVW6VLyoH/N+pBreSUcM4b1T36npP3MVS3yz0AKy/wLYkiRGnnFR40BDOAcDontBW2eavPd/jdxfZoDksGqIRH9uPAlh2WXfHelWVu9L71PCiN4N4xt6NkCnaNrBlP4qA7SzSGzjX X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:PAXPR04MB9642.eurprd04.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230031)(39860400002)(136003)(346002)(396003)(376002)(366004)(230922051799003)(186009)(451199024)(1800799012)(64100799003)(1076003)(2616005)(26005)(86362001)(41300700001)(7416002)(30864003)(6486002)(5660300002)(2906002)(38350700005)(316002)(37006003)(66476007)(66556008)(66946007)(478600001)(8676002)(34206002)(4326008)(8936002)(36756003)(6512007)(6506007)(52116002)(6666004)(38100700002)(83380400001);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?Vdht8OpPE3qlp4a+l2zrPM1ZYmmDQuH2TPPsJO1ZDG+Ck9n0wQKWhGSi6F7z?= =?us-ascii?Q?qtNyZcfLErRCBrXg0pdtWkmFCEu0bozGv9NWxloTI58tPEGmxLCyUERMeXRI?= =?us-ascii?Q?zbUvb2pWDnnylhPccDAR+JL3SCt6mryWvSZz6S0KkdyWpMTMUyHUeU3OqSjT?= =?us-ascii?Q?Qz224A5sCJTSGiJ0u8XqKZPGOaCUzLA7XFHEzZsLD7/4FJLZC91Tq2k6g1cT?= =?us-ascii?Q?djaC/9Sf0xXzY1OJoIWEAsx3cEW3/EKkHbEU8NmVXITCYT4c1aGVrgtpWCzh?= =?us-ascii?Q?hnGHnXjAfxDdnNErJbW7D8MxYBrStv7SyfYF8+orHlPhzUGS7qQhv8Yskpc1?= =?us-ascii?Q?+drS+gaWrHfSP9gzPfS6WReeyTEqqOsibth1zy6+rQ46pjQJ7G6uiOVIyiBk?= =?us-ascii?Q?AlgJqGeWs6ZFAsIIG0deD1/L1Z8250FERC0ZH0JpUCghJ6wUj+VQZ7qqcFcM?= =?us-ascii?Q?i/t9Ry9jkEhS/f3JeUXegotgIOUrTLyfj905yA2hpNXCXvRrz+DIcnysMQ0k?= =?us-ascii?Q?VGlRkGa8dr6DhVueLbn7yG2PhFmwOoVBNBC/QE4Z2cWALI/Xql9ITSkWeXw8?= =?us-ascii?Q?+Fqh84vRcspsPjf3TL2642unjbzueGrPzdSNq8S5bCRII3CvRFuTio4aGYqb?= =?us-ascii?Q?kJao8q0Ri6ffDTOFMO22/S87nF1GIvECCTnR08doafkJ1juP2MonA+dqZEsL?= =?us-ascii?Q?jQBHmqnBYtjDQTpE/oIrEUTfTFzyji98yAmFEr7obza26bFnYRmHPdobeBwR?= =?us-ascii?Q?U5tKQQ8gKqeHl2RGTqzwsitlJL6rb3Wz3uur0oYZN9KgPm4R0XV5nG3yX9Oi?= =?us-ascii?Q?yujT9cRKClFKAQeE13mdyZ7M6XdPEIKjqWYGFuap/XxMf7GUMHmWaWBWlbIj?= =?us-ascii?Q?37dbcTRMGl4MR+8rpr6ir01hyQSLkLHuQudd3tRrN9Tjso2OBVy0Msr3ntQO?= =?us-ascii?Q?xHCJPo7CEA8oCb39QvRe5wcphCPKXI90zMqHruKZRl2NDeYNYhHDdY6Msmhh?= =?us-ascii?Q?druGkUUGQUca/sQyD0G9M7gYZJcAS2QE0lNjky5ZqykOdWHxAAvP+k2XVDjG?= =?us-ascii?Q?9OkDRZdQ2njMA0E0v3R+F7HV9xnC8FGZEa9CDL8414QJBal6r4qIc2ZO4iSa?= =?us-ascii?Q?ojC11oe9OrUZmlyYihNtWsAHyo6BFbygns/+fIe/UtN5KS8qR/6TExyJ/VgW?= =?us-ascii?Q?8JfBkzdEGmBkQegwSLxODapWLlLY8KeGjGsxcxa/1o6ng+j5CM9+uRSD1mzI?= =?us-ascii?Q?A2HWQB/suxpn8GnNT/ODcQJj7qEqFQt60+ZM5CHXRXe85EEpdEe1um+qnV+4?= =?us-ascii?Q?2FYeWKK7VCeHYqlPkZaKDAMYnpQgWwI3E5hflHX63fkbcVpZT3KrDS2yT9Gt?= =?us-ascii?Q?jjScA8+EmuCdp/veg4tOqqKAPaFAgwdFbPFTlj1CYwcco1kFpoCmKp7qLgQu?= =?us-ascii?Q?uLQBq4OuSx8ySVPiq9DxNNCBFu5rm42W+nBeQapSbVGJSNSfqcu9Km5qkgAK?= =?us-ascii?Q?glVWEmUxktWJrqnINPr4py4qp3jwanCLCiZhat6tRty6MQCNzr6FFGTb2aeZ?= =?us-ascii?Q?q2pclJjbzpG3bg5LxfUtzNeXakHjkgF/MotTB8QC?= X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-Network-Message-Id: 5fccec00-f995-47f4-8ec0-08dc26a2eb37 X-MS-Exchange-CrossTenant-AuthSource: PAXPR04MB9642.eurprd04.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 Feb 2024 23:33:55.5037 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: KyJWIYHqG1jkZIVsct0s0sbhbLS3sD92zn2wEw6fvlLJuNESJhAGdkSeDV32XDd2lAN1k7NjTK1oUbbxJGHD/Q== X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS8PR04MB9205 Add I3C target mode and tty over i3c func driver document. Signed-off-by: Frank Li --- Documentation/driver-api/i3c/index.rst | 1 + .../driver-api/i3c/target/i3c-target-cfs.rst | 109 ++++++++++ .../driver-api/i3c/target/i3c-target.rst | 189 ++++++++++++++++++ .../driver-api/i3c/target/i3c-tty-howto.rst | 109 ++++++++++ Documentation/driver-api/i3c/target/index.rst | 13 ++ 5 files changed, 421 insertions(+) create mode 100644 Documentation/driver-api/i3c/target/i3c-target-cfs.rst create mode 100644 Documentation/driver-api/i3c/target/i3c-target.rst create mode 100644 Documentation/driver-api/i3c/target/i3c-tty-howto.rst create mode 100644 Documentation/driver-api/i3c/target/index.rst diff --git a/Documentation/driver-api/i3c/index.rst b/Documentation/driver-api/i3c/index.rst index 783d6dad054b6..345a43c9f61b0 100644 --- a/Documentation/driver-api/i3c/index.rst +++ b/Documentation/driver-api/i3c/index.rst @@ -9,3 +9,4 @@ I3C subsystem protocol device-driver-api master-driver-api + target/index diff --git a/Documentation/driver-api/i3c/target/i3c-target-cfs.rst b/Documentation/driver-api/i3c/target/i3c-target-cfs.rst new file mode 100644 index 0000000000000..1fcf829dc4ae2 --- /dev/null +++ b/Documentation/driver-api/i3c/target/i3c-target-cfs.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Configuring I3C Target Using CONFIGFS +======================================= + +:Author: Frank Li + +The I3C Target Core exposes configfs entry (i3c_target) to configure the I3C +target function and to bind the target function with the target controller. +(For introducing other mechanisms to configure the I3C Target Function refer to +[1]). + +Mounting configfs +================= + +The I3C Target Core layer creates i3c_target directory in the mounted configfs +directory. configfs can be mounted using the following command:: + + mount -t configfs none /sys/kernel/config + +Directory Structure +=================== + +The i3c_target configfs has two directories at its root: controllers and +functions. Every Controller device present in the system will have an entry in +the *controllers* directory and every Function driver present in the system will +have an entry in the *functions* directory. +:: + + /sys/kernel/config/i3c_target/ + .. controllers/ + .. functions/ + +Creating Function Device +=================== + +Every registered Function driver will be listed in controllers directory. The +entries corresponding to Function driver will be created by the Function core. +:: + + /sys/kernel/config/i3c_target/functions/ + .. / + ... / + ... / + ... / + .. / + ... / + ... / + +In order to create a of the type probed by , +the user has to create a directory inside . + +Every directory consists of the following entries that can be +used to configure the standard configuration header of the target function. +(These entries are created by the framework when any new is +created) +:: + + .. / + ... / + ... vendor_id + ... part_id + ... bcr + ... dcr + ... ext_id + ... instance_id + ... max_read_len + ... max_write_len + ... vendor_info + +Controller Device +========== + +Every registered Controller device will be listed in controllers directory. The +entries corresponding to Controller device will be created by the Controller +core. +:: + + /sys/kernel/config/i3c_target/controllers/ + .. / + ... / + .. / + ... / + +The directory will have a list of symbolic links to +. These symbolic links should be created by the user to +represent the functions present in the target device. Only +that represents a physical function can be linked to a Controller device. + +:: + + | controllers/ + | / + | + | functions/ + | / + | / + | vendor_id + | part_id + | bcr + | dcr + | ext_id + | instance_id + | max_read_len + | max_write_len + | vendor_info + +[1] Documentation/I3C/target/pci-target.rst diff --git a/Documentation/driver-api/i3c/target/i3c-target.rst b/Documentation/driver-api/i3c/target/i3c-target.rst new file mode 100644 index 0000000000000..09ae26b1f311a --- /dev/null +++ b/Documentation/driver-api/i3c/target/i3c-target.rst @@ -0,0 +1,189 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Author: Frank Li + +This document is a guide to use the I3C Target Framework in order to create +target controller driver, target function driver, and using configfs interface +to bind the function driver to the controller driver. + +Introduction +============ + +Linux has a comprehensive I3C subsystem to support I3C controllers that +operates in master mode. The subsystem has capability to scan I3C bus,assign +i3c device address, load I3C driver (based on Manufacturer ID, part ID), +support other services like hot-join, In-Band Interrupt(IBI). + +However the I3C controller IP integrated in some SoCs is capable of operating +either in Master mode or Target mode. I3C Target Framework will add target mode +support in Linux. This will help to run Linux in an target system which can +have a wide variety of use cases from testing or validation, co-processor +accelerator, etc. + +I3C Target Core +================= + +The I3C Target Core layer comprises 3 components: the Target Controller +library, the Target Function library, and the configfs layer to bind the target +function with the target controller. + +I3C Target Controller Library +------------------------------------ + +The Controller library provides APIs to be used by the controller that can +operate in target mode. It also provides APIs to be used by function +driver/library in order to implement a particular target function. + +APIs for the I3C Target controller Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section lists the APIs that the I3C Target core provides to be used by the +I3C controller driver. + +* devm_i3c_target_ctrl_create()/i3c_target_ctrl_create() + + The I3C controller driver should implement the following ops: + + * set_config: ops to set i3c configuration + * enable: ops to enable controller + * disable: ops to disable controller + * raise_ibi: ops to raise IBI to master controller + * alloc_request: ops to alloc a transfer request + * free_request: ops to free a transfer request + * queue: ops to queue a request to transfer queue + * dequeue: ops to dequeue a request from transfer queue + * cancel_all_reqs: ops to cancel all request from transfer queue + * fifo_status: ops to get fifo status + * fifo_flush: ops to flush hardware fifo + * get_features: ops to get controller supported features + + The I3C controller driver can then create a new Controller device by + invoking devm_i3c_target_ctrl_create()/i3c_target_ctrl_create(). + +* devm_i3c_target_ctrl_destroy()/i3c_target_ctrl_destroy() + + The I3C controller driver can destroy the Controller device created by + either devm_i3c_target_ctrl_create() or i3c_target_ctrl_create() using + devm_i3c_target_ctrl_destroy() or i3c_target_ctrl_destroy(). + +I3C Target Controller APIs for the I3C Target Function Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section lists the APIs that the I3C Target core provides to be used by the +I3C target function driver. + +* i3c_target_ctrl_set_config() + + The I3C target function driver should use i3c_target_ctrl_set_config() to + write i3c configuration to the target controller. + +* i3c_target_ctrl_enable()/i3c_target_ctrl_disable() + + The I3C target function driver should use i3c_target_ctrl_enable()/ + i3c_target_ctrl_disable() to enable/disable i3c target controller. + +* i3c_target_ctrl_alloc_request()/i3c_target_ctrl_free_request() + + The I3C target function driver should usei3c_target_ctrl_alloc_request() / + i3c_target_ctrl_free_request() to alloc/free a i3c request. + +* i3c_target_ctrl_raise_ibi() + + The I3C target function driver should use i3c_target_ctrl_raise_ibi() to + raise IBI. + +* i3c_target_ctrl_queue()/i3c_target_ctrl_dequeue() + + The I3C target function driver should use i3c_target_ctrl_queue()/ + i3c_target_ctrl_dequeue(), to queue/dequeue I3C transfer to/from transfer + queue. + +* i3c_target_ctrl_get_features() + + The I3C target function driver should use i3c_target_ctrl_get_features() to + get I3C target controller supported features. + +Other I3C Target Controller APIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are other APIs provided by the Controller library. These are used for +binding the I3C Target Function device with Controlller device. i3c-cfs.c can +be used as reference for using these APIs. + +* i3c_target_ctrl_get() + + Get a reference to the I3C target controller based on the device name of + the controller. + +* i3c_target_ctrl_put() + + Release the reference to the I3C target controller obtained using + i3c_target_ctrl_get() + +* i3c_target_ctrl_add_func() + + Add a I3C target function to a I3C target controller. + +* i3c_target_ctrl_remove_func() + + Remove the I3C target function from I3C target controller. + +I3C Target Function Library +---------------------------------- + +The I3C Target Function library provides APIs to be used by the function driver +and the Controller library to provide target mode functionality. + +I3C Target Function APIs for the I3C Target Function Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section lists the APIs that the I3C Target core provides to be used +by the I3C target function driver. + +* i3c_target_func_register_driver() + + The I3C Target Function driver should implement the following ops: + * bind: ops to perform when a Controller device has been bound to + Function device + * unbind: ops to perform when a binding has been lost between a + Controller device and Function device + + The I3C Function driver can then register the I3C Function driver by using + i3c_target_func_register_driver(). + +* i3c_target_func_unregister_driver() + + The I3C Function driver can unregister the I3C Function driver by using + i3c_epf_unregister_driver(). + +APIs for the I3C Target Controller Library +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section lists the APIs that the I3C Target core provides to be used by the +I3C target controller library. + +Other I3C Target APIs +~~~~~~~~~~~~~~~~~~~~ + +There are other APIs provided by the Function library. These are used to notify +the function driver when the Function device is bound to the EPC device. +i3c-cfs.c can be used as reference for using these APIs. + +* i3c_target_func_create() + + Create a new I3C Function device by passing the name of the I3C EPF device. + This name will be used to bind the Function device to a Function driver. + +* i3c_target_func_destroy() + + Destroy the created I3C Function device. + +* i3c_target_func_bind() + + i3c_target_func_bind() should be invoked when the EPF device has been bound + to a Controller device. + +* i3c_target_func_unbind() + + i3c_target_func_unbind() should be invoked when the binding between EPC + device and function device is lost. diff --git a/Documentation/driver-api/i3c/target/i3c-tty-howto.rst b/Documentation/driver-api/i3c/target/i3c-tty-howto.rst new file mode 100644 index 0000000000000..43a129b18e938 --- /dev/null +++ b/Documentation/driver-api/i3c/target/i3c-tty-howto.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +I3C TTY User Guide +=================== + +:Author: Frank Li + +This document is a guide to help users use i3c-target-tty function driver and +i3ctty master driver for testing I3C. The list of steps to be followed in the +master side and target side is given below. + +Endpoint Device +=============== + +Endpoint Controller Devices +--------------------------- + +To find the list of target controller devices in the system:: + + # ls /sys/class/i3c_target/ + 44330000.i3c-target + +If CONFIG_I3C_SLAVE_CONFIGFS is enabled:: + + # ls /sys/kernel/config/i3c_target/controllers/ + 44330000.i3c-target + + +Endpoint Function Drivers +------------------------- + +To find the list of target function drivers in the system:: + + # ls /sys/bus/i3c_target_func/drivers + tty + +If CONFIG_I3C_SLAVE_CONFIGFS is enabled:: + + # ls /sys/kernel/config/i3c_target/functions + tty + + +Creating i3c-target-tty Device +---------------------------- + +I3C target function device can be created using the configfs. To create +i3c-target-tty device, the following commands can be used:: + + # mount -t configfs none /sys/kernel/config + # cd /sys/kernel/config/i3c_target/ + # mkdir functions/tty/func1 + +The "mkdir func1" above creates the i3c-target-tty function device that will +be probed by i3c tty driver. + +The I3C target framework populates the directory with the following +configurable fields:: + + # ls functions/tty/func1 + bcr dcr ext_id instance_id max_read_len max_write_len + part_id vendor_id vendor_info + +The I3C target function driver populates these entries with default values when +the device is bound to the driver. The i3c-target-tty driver populates vendorid +with 0xffff and interrupt_pin with 0x0001:: + + # cat functions/tty/func1/vendor_id + 0x0 + +Configuring i3c-target-tty Device +------------------------------- + +The user can configure the i3c-target-tty device using configfs entry. In order +to change the vendorid, the following commands can be used:: + + # echo 0x011b > functions/tty/func1/vendor_id + # echo 0x1000 > functions/tty/func1/part_id + # echo 0x6 > functions/tty/t/bcr + +Binding i3c-target-tty Device to target Controller +------------------------------------------------ + +In order for the target function device to be useful, it has to be bound to a +I3C target controller driver. Use the configfs to bind the function device to +one of the controller driver present in the system:: + + # ln -s functions/tty/func1 controllers/44330000.i3c-target/ + +I3C Master Device +================ + +Check I3C tty device is probed + + # ls /sys/bus/i3c/devices/0-23610000000 + 0-23610000000:0 bcr dcr driver dynamic_address hdrcap + modalias pid power subsystem tty uevent + +Using Target TTY function Device +----------------------------------- + +Host side: + cat /dev/ttyI3C0 +Target side + echo abc >/dev/ttyI3C0 + +You will see "abc" show at console. + +You can use other tty tool to test I3C target tty device. diff --git a/Documentation/driver-api/i3c/target/index.rst b/Documentation/driver-api/i3c/target/index.rst new file mode 100644 index 0000000000000..56eabfae83aa4 --- /dev/null +++ b/Documentation/driver-api/i3c/target/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== +I3C Target Framework +====================== + +.. toctree:: + :maxdepth: 2 + + i3c-target + i3c-target-cfs + i3c-tty-howto + -- 2.34.1