From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755608AbcEYDr4 (ORCPT ); Tue, 24 May 2016 23:47:56 -0400 Received: from mail1.bemta8.messagelabs.com ([216.82.243.198]:21680 "EHLO mail1.bemta8.messagelabs.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755362AbcEYDqv (ORCPT ); Tue, 24 May 2016 23:46:51 -0400 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFjrFIsWRWlGSWpSXmKPExsVywNY2Q1dOwTX c4ME0BYuFbUtYLC7vmsPmwOTxeZNcAGMUa2ZeUn5FAmvGt/tzWQt++1Qc2HOPsYFxk00XIxeH kMBuRolZszvYIZwDjBIrr85lgXAuM0qcvXCfGcJZxyhxbP9CJghnC6PE4VMf2LoYOTnYBAwkZ t65yw5iiwicZ5F4eisXxBYWiJc483wCWJxFQFViyurVzCA2r4CXxIM7cxlBbAkBOYmTxyazgt icQPENDd+YQGwhAU+J97cbWCFsNYnDZx+xQdQHS1ybe5IFYo6gxMmZT8BsZgEJiYMvXjBPYBS chSQ1C0lqASPTKkaN4tSistQiXUMzvaSizPSMktzEzBxdQwMLvdzU4uLE9NScxKRiveT83E2M wHCtZ2Bg3ME4Ybf7IUZJDiYlUd6DT1zChfiS8lMqMxKLM+KLSnNSiw8xynBwKEnwSsq7hgsJF qWmp1akZeYAIwcmLcHBoyTCqw6S5i0uSMwtzkyHSJ1i1OVYsuvBWiYhlrz8vFQpcd5vckBFAi BFGaV5cCNgUXyJUVZKmJeRgYFBiKcgtSg3swRV/hWjOAejkjDvF5ApPJl5JXCbXgEdwQR0hP8 XZ5AjShIRUlINjK4vnyxjU33TJX/Pax2P5Ca7L7YxhY+u2CirPG7xP9lTNonfZWfBD5751m73 /fmyJLb8NlsesyrV2VRmwZmeE4u9ElY2h9818/OMYE005K9xvjbpic30taZBewqWTgu3nOa/7 dkanXv9j8XbmbtN5oq1TnzCc0fNsm6jz9WPFfm12t+Dzu6MUGIpzkg01GIuKk4EAFsZ59ndAg AA X-Env-Sender: David.Kershner@unisys.com X-Msg-Ref: server-5.tower-75.messagelabs.com!1464147994!20507385!16 X-Originating-IP: [192.61.61.104] X-StarScan-Received: X-StarScan-Version: 8.34; banners=-,-,- X-VirusChecked: Checked From: David Kershner To: , , , , , , , , , , , , , , , , , , , , , Subject: [PATCH 20/24] staging: unisys: visorbus: Add kerneldoc-style comments for visorbus API Date: Tue, 24 May 2016 23:45:58 -0400 Message-ID: <1464147962-26650-21-git-send-email-david.kershner@unisys.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1464147962-26650-1-git-send-email-david.kershner@unisys.com> References: <1464147962-26650-1-git-send-email-david.kershner@unisys.com> X-OriginalArrivalTime: 25 May 2016 03:46:25.0400 (UTC) FILETIME=[02ED8780:01D1B638] MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: David Binder Adds kerneldoc-style comments for those functions which may be used outside of the visorbus driver. Signed-off-by: David Binder Signed-off-by: David Kershner --- drivers/staging/unisys/include/visorbus.h | 127 ++++++++++++++++++++++++ drivers/staging/unisys/visorbus/visorbus_main.c | 42 -------- 2 files changed, 127 insertions(+), 42 deletions(-) diff --git a/drivers/staging/unisys/include/visorbus.h b/drivers/staging/unisys/include/visorbus.h index 2c103e8..99c7beb 100644 --- a/drivers/staging/unisys/include/visorbus.h +++ b/drivers/staging/unisys/include/visorbus.h @@ -177,22 +177,149 @@ struct visor_device { #define to_visor_device(x) container_of(x, struct visor_device, device) +/** + * visorbus_register_visor_driver() - registers the provided driver + * @struct visor_driver *: the driver to register + * + * A particular type of visor driver calls this function to register + * the driver. The caller MUST fill in the following fields within the + * #drv structure: + * name, version, owner, channel_types, probe, remove + * + * Here's how the whole Linux bus / driver / device model works. + * + * At system start-up, the visorbus kernel module is loaded, which registers + * visorbus_type as a bus type, using bus_register(). + * + * All kernel modules that support particular device types on a + * visorbus bus are loaded. Each of these kernel modules calls + * visorbus_register_visor_driver() in their init functions, passing a + * visor_driver struct. visorbus_register_visor_driver() in turn calls + * register_driver(&visor_driver.driver). This .driver member is + * initialized with generic methods (like probe), whose sole responsibility + * is to act as a broker for the real methods, which are within the + * visor_driver struct. (This is the way the subclass behavior is + * implemented, since visor_driver is essentially a subclass of the + * generic driver.) Whenever a driver_register() happens, core bus code in + * the kernel does (see device_attach() in drivers/base/dd.c): + * + * for each dev associated with the bus (the bus that driver is on) that + * does not yet have a driver + * if bus.match(dev,newdriver) == yes_matched ** .match specified + * ** during bus_register(). + * newdriver.probe(dev) ** for visor drivers, this will call + * ** the generic driver.probe implemented in visorbus.c, + * ** which in turn calls the probe specified within the + * ** struct visor_driver (which was specified by the + * ** actual device driver as part of + * ** visorbus_register_visor_driver()). + * + * The above dance also happens when a new device appears. + * So the question is, how are devices created within the system? + * Basically, just call device_add(dev). See pci_bus_add_devices(). + * pci_scan_device() shows an example of how to build a device struct. It + * returns the newly-created struct to pci_scan_single_device(), who adds it + * to the list of devices at PCIBUS.devices. That list of devices is what + * is traversed by pci_bus_add_devices(). + * + * Return: integer indicating success (zero) or failure (non-zero) + */ int visorbus_register_visor_driver(struct visor_driver *); + +/** + * visorbus_unregister_visor_driver() - unregisters the provided driver + * @struct visor_driver *: the driver to unregister + */ void visorbus_unregister_visor_driver(struct visor_driver *); + +/** + * visorbus_read_channel() - reads from the designated channel into + * the provided buffer + * @dev: the device whose channel is read from + * @offset: the offset into the channel at which reading starts + * @dest: the destination buffer that is written into from the channel + * @nbytes: the number of bytes to read from the channel + * + * If receiving a message, use the visorchannel_signalremove() + * function instead. + * + * Return: integer indicating success (zero) or failure (non-zero) + */ int visorbus_read_channel(struct visor_device *dev, unsigned long offset, void *dest, unsigned long nbytes); + +/** + * visorbus_write_channel() - writes the provided buffer into the designated + * channel + * @dev: the device whose channel is written to + * @offset: the offset into the channel at which writing starts + * @src: the source buffer that is written into the channel + * @nbytes: the number of bytes to write into the channel + * + * If sending a message, use the visorchannel_signalinsert() + * function instead. + * + * Return: integer indicating success (zero) or failure (non-zero) + */ int visorbus_write_channel(struct visor_device *dev, unsigned long offset, void *src, unsigned long nbytes); +/** + * visorbus_enable_channel_interrupts() - enables interrupts on the + * designated device + * @dev: the device on which to enable interrupts + */ void visorbus_enable_channel_interrupts(struct visor_device *dev); + +/** + * visorbus_disable_channel_interrupts() - disables interrupts on the + * designated device + * @dev: the device on which to disable interrupts + */ void visorbus_disable_channel_interrupts(struct visor_device *dev); +/** + * visorchannel_signalremove() - removes a message from the designated + * channel/queue + * @channel: the channel the message will be removed from + * @queue: the queue the message will be removed from + * @msg: the message to remove + * + * Return: boolean indicating whether the removal succeeded or failed + */ bool visorchannel_signalremove(struct visorchannel *channel, u32 queue, void *msg); + +/** + * visorchannel_signalinsert() - inserts a message into the designated + * channel/queue + * @channel: the channel the message will be added to + * @queue: the queue the message will be added to + * @msg: the message to insert + * + * Return: boolean indicating whether the insertion succeeded or failed + */ bool visorchannel_signalinsert(struct visorchannel *channel, u32 queue, void *msg); + +/** + * visorchannel_signalempty() - checks if the designated channel/queue + * contains any messages + * @channel: the channel to query + * @queue: the queue in the channel to query + * + * Return: boolean indicating whether any messages in the designated + * channel/queue are present + */ bool visorchannel_signalempty(struct visorchannel *channel, u32 queue); + +/** + * visorchannel_get_uuid() - queries the UUID of the designated channel + * @channel: the channel to query + * + * Return: the UUID of the provided channel + */ uuid_le visorchannel_get_uuid(struct visorchannel *channel); #define BUS_ROOT_DEVICE UINT_MAX diff --git a/drivers/staging/unisys/visorbus/visorbus_main.c b/drivers/staging/unisys/visorbus/visorbus_main.c index 850998e..0a537c7 100644 --- a/drivers/staging/unisys/visorbus/visorbus_main.c +++ b/drivers/staging/unisys/visorbus/visorbus_main.c @@ -616,48 +616,6 @@ visordriver_remove_device(struct device *xdev) return 0; } -/** - * A particular type of visor driver calls this function to register - * the driver. The caller MUST fill in the following fields within the - * #drv structure: - * name, version, owner, channel_types, probe, remove - * - * Here's how the whole Linux bus / driver / device model works. - * - * At system start-up, the visorbus kernel module is loaded, which registers - * visorbus_type as a bus type, using bus_register(). - * - * All kernel modules that support particular device types on a - * visorbus bus are loaded. Each of these kernel modules calls - * visorbus_register_visor_driver() in their init functions, passing a - * visor_driver struct. visorbus_register_visor_driver() in turn calls - * register_driver(&visor_driver.driver). This .driver member is - * initialized with generic methods (like probe), whose sole responsibility - * is to act as a broker for the real methods, which are within the - * visor_driver struct. (This is the way the subclass behavior is - * implemented, since visor_driver is essentially a subclass of the - * generic driver.) Whenever a driver_register() happens, core bus code in - * the kernel does (see device_attach() in drivers/base/dd.c): - * - * for each dev associated with the bus (the bus that driver is on) that - * does not yet have a driver - * if bus.match(dev,newdriver) == yes_matched ** .match specified - * ** during bus_register(). - * newdriver.probe(dev) ** for visor drivers, this will call - * ** the generic driver.probe implemented in visorbus.c, - * ** which in turn calls the probe specified within the - * ** struct visor_driver (which was specified by the - * ** actual device driver as part of - * ** visorbus_register_visor_driver()). - * - * The above dance also happens when a new device appears. - * So the question is, how are devices created within the system? - * Basically, just call device_add(dev). See pci_bus_add_devices(). - * pci_scan_device() shows an example of how to build a device struct. It - * returns the newly-created struct to pci_scan_single_device(), who adds it - * to the list of devices at PCIBUS.devices. That list of devices is what - * is traversed by pci_bus_add_devices(). - */ int visorbus_register_visor_driver(struct visor_driver *drv) { int rc = 0; -- 1.9.1