From 3e8d044d12aed86efa6a1251405bb8f347847619 Mon Sep 17 00:00:00 2001 From: Leo Rouleau Date: Sun, 21 Jun 2026 15:10:35 -0400 Subject: [PATCH] Devices: Move documentation to docs/develop/apps Change-Id: I2ff31810df1a4afc16533d3820af61a1d2a8ccd1 Reviewed-on: https://review.haiku-os.org/c/haiku/+/11172 Reviewed-by: Adrien Destugues Tested-by: Commit checker robot --- docs/develop/apps/devices/Design.rst | 146 ++++++++++++++++++ .../develop/apps/devices/Specification.rst | 71 +++++---- docs/develop/apps/devices/Todo.rst | 13 ++ docs/develop/apps/devices/index.rst | 9 ++ docs/develop/index.rst | 1 + src/apps/devices/Documentation/Design.txt | 128 --------------- src/apps/devices/Documentation/Todo.txt | 11 -- 7 files changed, 208 insertions(+), 171 deletions(-) create mode 100644 docs/develop/apps/devices/Design.rst rename src/apps/devices/Documentation/Specification.txt => docs/develop/apps/devices/Specification.rst (50%) create mode 100644 docs/develop/apps/devices/Todo.rst create mode 100644 docs/develop/apps/devices/index.rst delete mode 100644 src/apps/devices/Documentation/Design.txt delete mode 100644 src/apps/devices/Documentation/Todo.txt diff --git a/docs/develop/apps/devices/Design.rst b/docs/develop/apps/devices/Design.rst new file mode 100644 index 0000000000..c6e559843a --- /dev/null +++ b/docs/develop/apps/devices/Design.rst @@ -0,0 +1,146 @@ +DeviceManager Design +==================== + +Requirements +------------ + +1) Graphically list each device in the system, with all the information available for that specific device type: + + - PCI + - USB + - SCSI + - Bluetooth? + - ISA? + - ATAPI? + - AHCI? + - Firewire? + +2) Generate a comprehensive text listing of the devices present to allow users to share detailed information with developers + +- Generate an email with this information attached + +3) Let the user generate a report on how well Haiku supports the devices in the system. + +- Present a list of devices and per device a star rating on the support, and provide a space for comments on the device support. +- For each device allow comments +- Include all available information for the device (including loaded driver) +- Perhaps this can go into the Haikuware compatibility database? + +4) Arrange the devices in different orders (by category, by connection, by bus type, by resource assignment?) + +Graphical Design +---------------- + +:: + + +=========+ + | Devices | + +=========+======================================================+ + | Devices | Help | | + +----------------------------------------------------------------+ + | +------------------------+-----------------------------------+ | + | | Sort by: [Category v] | / Basic \/ \/ Advanced \ | | + | | ------------------- | + +--------+----------+--+ | | + | | v Audio/Video Devices | | Device Name: Netlink 5787M | | | + | | Hauppauge WinTV | | Manufacturer: Broadcom | | | + | | Intel HDA Audio | | Category: Network Devices | | | + | | v Human Interface Dev. | | Driver used: broadcom570x | | | + | | USB Mouse | | | | | + | | USB Keyboard | | | | | + | | v Network Devices | | | | | + | | -->Broadcom 5787M<-- | | | | | + | | Intel 4965 WIFI | | | | | + | | v Graphics Card | | | | | + | | NVidia 8600M GT | | | | | + | | .... | +-------------------------------+ | | + | +------------------------+-----------------------------------+ | + | +-------------------------+ +------------+ +-----------+ | + | | Report hardware support | | Gen. email | | Gen. Text | | + | +-------------------------+ +------------+ +-----------+ | + +================================================================+ + +Menu: + +Devices + +- Refresh devices +- Report compatibility +- Generate system information +- \----- +- About Devices +- \----- +- Quit + +Interface details: + +- The left list is an OutlineListView, + + - Is inside a scroll container + - Will contain nice icons per type/device + - Clicking on a device will show the details in the right view + +- The right view contains 3 tabs: + + - Basic tab: Information available for every kind device + - tab: Information specific to the bus type of device. (PCI, USB, etc) + - Advanced tab: Has a list of name-value pairs of all available information + +- Sort by allows the user to arrange the treeview by: + + - Category: + - Connection + - Bus type + +- Report Hardware Support + + - List all devices + - For each device + +When you click Report Hardware Support, this appears: + +:: + + +=========================+ + | Report Hardware Support | + +=========================+============================+ + | Report Device Supported Comment | + | [x] Broadcom Netlink 5787M ***** _________ | + | [x] Hauppauge WinTV ***** _________ | + | [x] Intel 4965 WIFI ..... _________ | + | [x] Intel HDA Audio ****. _________ | + | [x] NVidia 8600M GT ***.. _________ | + | [x] USB Keyboard ***** _________ | + | [x] USB Mouse ***** _________ | + | [ ] Intel 82801 PCI Bridge ..... _________ | + | [ ] Intel 82801H PCI Express ..... _________ | + | | + | If you wish, you can leave your contact details so | + | developers can get in touch with you for questions | + | about your devices. These will be stored privately. | + | | + | Name: _______________ Email: __________________ | + | | + | Haiku-os.org account: __________________________ | + | | + | +--------------------+ +---------------+ | + | | Preview submission | | Generate File | | + | +--------------------+ +---------------+ | + +======================================================+ + +Interface details: +------------------ + +- All devices are _not_ selected for report by default +- As soon as a rating is given, it is selected to be reported +- Preview submission will popup the generated list with a submit button +- Generate file will generate a file that can be uploaded manually, or emailed to a specific address. +- As you mouse over the rating, a popup will appear detailing what each star stands for: + + :: + + ..... : No support + X.... : Crashes Haiku + **... : Detected but doesn't work with 3rd party driver + ***.. : Detected but doesn't work out of the box + ****. : Detected and works with 3rd party driver + ***** : Detected and works out of the box diff --git a/src/apps/devices/Documentation/Specification.txt b/docs/develop/apps/devices/Specification.rst similarity index 50% rename from src/apps/devices/Documentation/Specification.txt rename to docs/develop/apps/devices/Specification.rst index 0433db5002..5042f8ba4f 100644 --- a/src/apps/devices/Documentation/Specification.txt +++ b/docs/develop/apps/devices/Specification.rst @@ -1,4 +1,8 @@ +DeviceManager Specification +=========================== + Each device has: + - Name (long/short) - Manufacturer (long/short) - Category (one master list, each bus type maps its device types onto the master list) @@ -8,62 +12,65 @@ Each device has: - Its connection parent, if applicable Each source has: (currently the RescanDevices method does this) + - Init function - Scan method that returns the devices. - DevManSource, USBSource, FWSource, ... -DeviceManager Specification -=========================== - DeviceManager : BApplication -------------- +---------------------------- DeviceManagerView : BView ------------------ - +------------------------- Device : public BStringItem ------- -BString GetName() const; -BString GetManufacturer() const; -Category GetCategory() const; -BString DriverUsed() const; -BString DevPathsPublished() const; -BView Get -private: -BString _name; -BString _manufacturer; -Category _category; -BString _driverUsed; -BString devPathsPublished; -map _attributes; +--------------------------- + +:: + + BString GetName() const; + BString GetManufacturer() const; + Category GetCategory() const; + BString DriverUsed() const; + BString DevPathsPublished() const; + BView Get + private: + BString _name; + BString _manufacturer; + Category _category; + BString _driverUsed; + BString devPathsPublished; + map _attributes; Bus : public BStringItem ---- -virtual bool IsPresent() const = 0; -virtual Scan() = 0; -virtual vector Devices() = 0; +------------------------ + +:: + + virtual bool IsPresent() const = 0; + virtual Scan() = 0; + virtual vector Devices() = 0; PCIBus : public Bus ------- +------------------- PCIDevice: public Device ---------- +------------------------ ISABus : public Bus ------ +------------------- ISADevice : public Device ---------- +------------------------- USBBus : public Bus ------- +------------------- USBDevice : public Device ---------- +------------------------- SCSIBus : public Bus -------- +-------------------- SCSIDevice : public Device ----------- +-------------------------- diff --git a/docs/develop/apps/devices/Todo.rst b/docs/develop/apps/devices/Todo.rst new file mode 100644 index 0000000000..76b9618ec0 --- /dev/null +++ b/docs/develop/apps/devices/Todo.rst @@ -0,0 +1,13 @@ +TODO +==== + +* Fix view color? +* Fix forwarding of messages to view +* Bottom scrollbar strangeness +* Reduce executable size? +* Find a place for unknown devices (or decypher the names better) +* Reselect currently selected on sort-by change - unique device id (device_node_cookie?) +* Check for keyboard navigation +* Loading and saving settings (sort by, position, size and sizes of views) +* Icons per device type +* Index attributes by enum, not string diff --git a/docs/develop/apps/devices/index.rst b/docs/develop/apps/devices/index.rst new file mode 100644 index 0000000000..70960f69de --- /dev/null +++ b/docs/develop/apps/devices/index.rst @@ -0,0 +1,9 @@ +Devices +======= + +.. toctree:: + :maxdepth: 2 + + Design + Specification + Todo diff --git a/docs/develop/index.rst b/docs/develop/index.rst index 1dfbb999e1..a31092dc01 100644 --- a/docs/develop/index.rst +++ b/docs/develop/index.rst @@ -50,6 +50,7 @@ Table of contents /kernel/index /file_systems/index /drivers/index + /apps/devices/index /apps/haikudepot/server /debugging/index diff --git a/src/apps/devices/Documentation/Design.txt b/src/apps/devices/Documentation/Design.txt deleted file mode 100644 index e31438da02..0000000000 --- a/src/apps/devices/Documentation/Design.txt +++ /dev/null @@ -1,128 +0,0 @@ -DeviceManager Design -==================== - -Requirements ------------- -1) Graphically list each device in the system, with all the information available for that specific device type: - - PCI - - USB - - SCSI - - Bluetooth? - - ISA? - - ATAPI? - - AHCI? - - Firewire? - -2) Generate a comprehensive text listing of the devices present to allow users to share detailed information with developers -- Generate an email with this information attached - -3) Let the user generate a report on how well Haiku supports the devices in the system. -- Present a list of devices and per device a star rating on the support, and provide a space for comments on the device support. -- For each device allow comments -- Include all available information for the device (including loaded driver) -- Perhaps this can go into the Haikuware compatibility database? - -4) Arrange the devices in different orders (by category, by connection, by bus type, by resource assignment?) - -Graphical Design ----------------- -+=========+ -| Devices | -+=========+======================================================+ -| Devices | Help | | -+----------------------------------------------------------------+ -| +------------------------+-----------------------------------+ | -| | Sort by: [Category v] | / Basic \/ \/ Advanced \ | | -| | ------------------- | + +--------+----------+--+ | | -| | v Audio/Video Devices | | Device Name: Netlink 5787M | | | -| | Hauppauge WinTV | | Manufacturer: Broadcom | | | -| | Intel HDA Audio | | Category: Network Devices | | | -| | v Human Interface Dev. | | Driver used: broadcom570x | | | -| | USB Mouse | | | | | -| | USB Keyboard | | | | | -| | v Network Devices | | | | | -| | -->Broadcom 5787M<-- | | | | | -| | Intel 4965 WIFI | | | | | -| | v Graphics Card | | | | | -| | NVidia 8600M GT | | | | | -| | .... | +-------------------------------+ | | -| +------------------------+-----------------------------------+ | -| +-------------------------+ +------------+ +-----------+ | -| | Report hardware support | | Gen. email | | Gen. Text | | -| +-------------------------+ +------------+ +-----------+ | -+================================================================+ - -Menu: -Devices -- Refresh devices -- Report compatibility -- Generate system information -- ----- -- About Devices -- ----- -- Quit - -Interface details: -- The left list is an OutlineListView, - - Is inside a scroll container - - Will contain nice icons per type/device - - Clicking on a device will show the details in the right view - -- The right view contains 3 tabs: - - Basic tab: Information available for every kind device - - tab: Information specific to the bus type of device. (PCI, USB, etc) - - Advanced tab: Has a list of name-value pairs of all available information - -- Sort by allows the user to arrange the treeview by: - - Category: - - Connection - - Bus type - -- Report Hardware Support - - List all devices - - For each device - -When you click Report Hardware Support, this appears: - -+=========================+ -| Report Hardware Support | -+=========================+============================+ -| Report Device Supported Comment | -| [x] Broadcom Netlink 5787M ***** _________ | -| [x] Hauppauge WinTV ***** _________ | -| [x] Intel 4965 WIFI ..... _________ | -| [x] Intel HDA Audio ****. _________ | -| [x] NVidia 8600M GT ***.. _________ | -| [x] USB Keyboard ***** _________ | -| [x] USB Mouse ***** _________ | -| [ ] Intel 82801 PCI Bridge ..... _________ | -| [ ] Intel 82801H PCI Express ..... _________ | -| | -| If you wish, you can leave your contact details so | -| developers can get in touch with you for questions | -| about your devices. These will be stored privately. | -| | -| Name: _______________ Email: __________________ | -| | -| Haiku-os.org account: __________________________ | -| | -| +--------------------+ +---------------+ | -| | Preview submission | | Generate File | | -| +--------------------+ +---------------+ | -+======================================================+ - -Interface details: ------------------- -- All devices are _not_ selected for report by default -- As soon as a rating is given, it is selected to be reported -- Preview submission will popup the generated list with a submit button -- Generate file will generate a file that can be uploaded manually, or emailed to a specific address. -- As you mouse over the rating, a popup will appear detailing what each star stands for: - - ..... : No support - - X.... : Crashes Haiku - - **... : Detected but doesn't work with 3rd party driver - - ***.. : Detected but doesn't work out of the box - - ****. : Detected and works with 3rd party driver - - ***** : Detected and works out of the box - - diff --git a/src/apps/devices/Documentation/Todo.txt b/src/apps/devices/Documentation/Todo.txt deleted file mode 100644 index eea810fca0..0000000000 --- a/src/apps/devices/Documentation/Todo.txt +++ /dev/null @@ -1,11 +0,0 @@ -TODO: - * Fix view color? - * Fix forwarding of messages to view - * Bottom scrollbar strangeness - * Reduce executable size? - * Find a place for unknown devices (or decypher the names better) - * Reselect currently selected on sort-by change - unique device id (device_node_cookie?) - * Check for keyboard navigation - * Loading and saving settings (sort by, position, size and sizes of views) - * Icons per device type - * Index attributes by enum, not string