From nobody Tue Feb 10 01:16:14 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=philmd@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=philmd@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1640818346; cv=none; d=zohomail.com; s=zohoarc; b=PIWwYRXyeZXlvyLbybiHG9xXhmAhoMJzKbwprGRfm4XZdWdM479sZUG15hcudwkAqyZKtTUaawUxorTIcgIruNZqaZkYVfshsmNyvI+7HK1C2f1E7R1a30MhuN9w0Iqt3U7iJbtRzKpltaeTzfQXZ+w1JTBfuO+xAsvQ607Q+Zw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1640818346; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To; bh=uqL8vZZPvn+NdNRr9VNi7rmG13LdpKOsdG9YYXl47e0=; b=dxbSNqhqeiuNaaOKx7axv6ysjZ8Ecg4kAYlNyZ1u0WB+zSXEWS9fkCa3UCcy+e/GI0EVvNA2OZXfddw3ItEp9KrMBIcbBw4SmIJIGHI1gq4Vvr2dQA6JSSmdPfpyI7DcaCTldWxGFjetBG25ZCvPZE3w/BTsclBW61swYWI8VG8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=philmd@redhat.com; dmarc=pass header.from= (p=none dis=none) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 164081834653383.33594282002014; Wed, 29 Dec 2021 14:52:26 -0800 (PST) Received: from mail-wr1-f69.google.com (mail-wr1-f69.google.com [209.85.221.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-407-26DScZW8Mv6Dw5vax1SoGg-1; Wed, 29 Dec 2021 17:52:24 -0500 Received: by mail-wr1-f69.google.com with SMTP id x20-20020adfbb54000000b001a0d044e20fso5446669wrg.11 for ; Wed, 29 Dec 2021 14:52:24 -0800 (PST) Return-Path: Return-Path: Received: from x1w.. (26.red-83-50-86.dynamicip.rima-tde.net. [83.50.86.26]) by smtp.gmail.com with ESMTPSA id e5sm25289236wrq.116.2021.12.29.14.52.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 29 Dec 2021 14:52:22 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1640818345; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=uqL8vZZPvn+NdNRr9VNi7rmG13LdpKOsdG9YYXl47e0=; b=NknRLXjCkjZrB4iVDObXU1KBrOBGyogUY/itqO6AjiOZXnbXWGRkSS5KafpYiuwWbtjaG0 KKssJigIodFjaRT166ZA0+DVYk9wwZeTV+/NYXwfVcCW467W+/imAXc2KKdtBNCcw+VR5f F+5eEoUqFZkFblw2HQrC2s5DVn2ng3k= X-MC-Unique: 26DScZW8Mv6Dw5vax1SoGg-1 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=uqL8vZZPvn+NdNRr9VNi7rmG13LdpKOsdG9YYXl47e0=; b=IeYqu45ga+dBLxxmv7PiXepsqC1Q6QvxH90FQWcvgq0blnb0fFLAK2l4MKVrjRR0oh Cfn9hHwfAJQAc4xQ2AnPOlWGULpJeTuEQjc1ZWXsanVfBf6nX07ig41B/KCNSoW5/U7t lvcwUqu0KuP3k9NIVd12kvRQDSv/wLLPzxjqpCkO3BuQDqPFUp2zvrTXJvOfz9JPzymj /mzoOW/3BAeG8GMw1RuSQ1vT46aQPoZouZFBu4NfrDLwDJ115/wiLDL+1P7ogQg+/jeB qX798ruvjTwUMRE1c9Fjh2JBRfzyRLmdjzgTLg39tZColB0Rj2ZF+R8ARY+LdGjywIsf c3Aw== X-Gm-Message-State: AOAM530thxCWr/6K4onMe/nxFXBaYzchr2ACfRGG1nKu+R7nMNlfWFGz q9iKWKkehagB7paQ3PeJYbs1M7lVE8GtMhMk7jV6iY/cSNHs9XTJJuHwLWB9UZSnnkKa9x0+r2w ORz7lJ2YqOew9Dg== X-Received: by 2002:a05:600c:1d8f:: with SMTP id p15mr23685437wms.102.1640818343403; Wed, 29 Dec 2021 14:52:23 -0800 (PST) X-Google-Smtp-Source: ABdhPJw1+hlMZ/ltqE4Tzud7R7Rd6xQgmcqVKrh37e2H+5JTXkTd/vc993T+03P96RWNnah8R1JRig== X-Received: by 2002:a05:600c:1d8f:: with SMTP id p15mr23685432wms.102.1640818343242; Wed, 29 Dec 2021 14:52:23 -0800 (PST) From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= To: qemu-devel@nongnu.org Cc: Yanan Wang , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell , Richard Henderson , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Subject: [PATCH 3/3] hw/sysbus: Document GPIO related functions Date: Wed, 29 Dec 2021 23:52:06 +0100 Message-Id: <20211229225206.171882-4-philmd@redhat.com> X-Mailer: git-send-email 2.33.1 In-Reply-To: <20211229225206.171882-1-philmd@redhat.com> References: <20211229225206.171882-1-philmd@redhat.com> MIME-Version: 1.0 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=philmd@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1640818348528000001 Similarly to cd07d7f9f51 ("qdev: Document GPIO related functions"), add documentation comments for the various sysbus functions related to creating and connecting GPIO lines. Signed-off-by: Philippe Mathieu-Daud=C3=A9 --- include/hw/sysbus.h | 67 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 64 insertions(+), 3 deletions(-) diff --git a/include/hw/sysbus.h b/include/hw/sysbus.h index 24645ee7996..7b2b7c7faaa 100644 --- a/include/hw/sysbus.h +++ b/include/hw/sysbus.h @@ -69,14 +69,75 @@ typedef void FindSysbusDeviceFunc(SysBusDevice *sbdev, = void *opaque); =20 void sysbus_init_mmio(SysBusDevice *dev, MemoryRegion *memory); MemoryRegion *sysbus_mmio_get_region(SysBusDevice *dev, int n); -void sysbus_init_irq(SysBusDevice *dev, qemu_irq *p); -void sysbus_pass_irq(SysBusDevice *dev, SysBusDevice *target); -void sysbus_init_ioports(SysBusDevice *dev, uint32_t ioport, uint32_t size= ); =20 +/** + * sysbus_init_irq: Create an output GPIO line + * @dev: Sysbus device to create output GPIO for + * @irq: Pointer to qemu_irq for the GPIO lines + * + * Sysbus devices should use this function in their instance_init + * or realize methods to create any output GPIO lines they need. + * + * The @irq argument should be a pointer to either a "qemu_irq" in + * the device's state structure. The device implementation can then raise + * and lower the GPIO line by calling qemu_set_irq(). (If anything is + * connected to the other end of the GPIO this will cause the handler + * function for that input GPIO to be called.) + * + * See sysbus_connect_irq() for how code that uses such a device can + * connect to one of its output GPIO lines. + * + * There is no need to release the @pins allocated array because it + * will be automatically released when @dev calls its instance_finalize() + * handler. + */ +void sysbus_init_irq(SysBusDevice *dev, qemu_irq *irq); + +/** + * sysbus_pass_irq: Create GPIO lines on container which pass through + * to a target device + * @dev: Device which needs to expose GPIO lines + * @target: Device which has GPIO lines + * + * This function allows a container device to create GPIO arrays on itself + * which simply pass through to a GPIO array of another device. It is + * useful when modelling complex devices such system-on-chip, where a + * sysbus device contains other sysbus devices. + * + * It is not possible to pass a subset of the GPIO lines with this functio= n. + * + * To users of the container sysbus device, the GPIO array created on @dev + * behaves exactly like any other. + */ +void sysbus_pass_irq(SysBusDevice *dev, SysBusDevice *target); + +void sysbus_init_ioports(SysBusDevice *dev, uint32_t ioport, uint32_t size= ); =20 bool sysbus_has_irq(SysBusDevice *dev, int n); bool sysbus_has_mmio(SysBusDevice *dev, unsigned int n); + +/** + * sysbus_connect_irq: Connect a sysbus device output GPIO line + * @dev: sysbus device whose GPIO to connect + * @n: Number of the output GPIO line (which must be in range) + * @pin: qemu_irq to connect the output line to + * + * This function connects an output GPIO line on a sysbus device + * up to an arbitrary qemu_irq, so that when the device asserts that + * output GPIO line, the qemu_irq's callback is invoked. + * The index @n of the GPIO line must be valid, otherwise this function + * will assert(). + * + * Outbound GPIO lines can be connected to any qemu_irq, but the common + * case is connecting them to another device's inbound GPIO line, using + * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named(). + * + * It is not valid to try to connect one outbound GPIO to multiple + * qemu_irqs at once, or to connect multiple outbound GPIOs to the + * same qemu_irq; see qdev_connect_gpio_out() for details. + */ void sysbus_connect_irq(SysBusDevice *dev, int n, qemu_irq irq); + void sysbus_mmio_map(SysBusDevice *dev, int n, hwaddr addr); void sysbus_mmio_map_overlap(SysBusDevice *dev, int n, hwaddr addr, int priority); --=20 2.33.1