top logo menu kitty mascot
AROS.ORG Developers Localization Bounties

hidd_hidd

Index


Classes


hiddclass

--background_hiddclass-- --background_relations-- aoHidd_DevicePath aoHidd_DriverData
aoHidd_HardwareName aoHidd_Name aoHidd_Parent aoHidd_Producer
aoHidd_ProducerName aoHidd_Product aoHW_Device moHidd_AddRelation
moHidd_EnumRelations moHidd_FindDevicePath moHidd_FindRelated moHidd_RemoveRelation

--background_hiddclass--

Notes

This class is a base class for all object-oriented hardware drivers in AROS. Its
main purpose is to provide some information about the driver itself.

At the moment this class is just a primary design. Many defined attributes and
methods are drafts and reserved. This documentation includes only already
estabilished definitions. Do not use any other methods and attributes, their
definitions may change at any moment.

--background_relations--

Notes

The subsystem tree, as walked with moHW_EnumDrivers, only tells which
subsystem created which driver object. It does not tell that a display
driver runs a particular PCI device, that it owns an I2C bus, or that a
temperature sensor belongs to it. Relations describe these connections
in one place, so that they can be queried from any object without
knowing the class of that object.

A relation connects two objects and has a type (vHidd_Relation_#?).
It is declared once, by either of the two objects, using
moHidd_AddRelation. Both objects then report it, each from its own
point of view: if a driver declares vHidd_Relation_Device to a PCI
device object, that object reports the driver as vHidd_Relation_Driver.

The target of a relation can also be named by its device path (see
aoHidd_DevicePath) instead of by object pointer. Such a relation
connects to the object carrying that path whenever one exists, in
whatever order the two come to life, and it reports the bare path
while there is none. This is how hardware that is described by another
component, or not represented by an object at all (an ACPI namespace
node, for example), is referred to.

Relations are removed automatically when one of their objects is
disposed. Subsystem objects (CLID_HW) are HIDD objects too, and every
driver added with moHW_AddDriver is given a vHidd_Relation_Parent
relation to its subsystem.

aoHidd_DevicePath

Synopsis

[I.G], CONST_STRPTR

Function

A string identifying the piece of hardware the object represents,
which is unique in the system and can be worked out by other components
from what they know about the hardware.

The path starts with the name of the namespace the hardware is
enumerated in, followed by a slash and the address inside it:

    pci/0000:00:02.0        PCI segment:bus:device.function (hex). The
                            segment is the number of the host bridge
                            driver, in the order they were created.
    pci/0000                The host bridge driver of that segment
    acpi/\_SB_.PCI0.GFX0    Full ACPI namespace path, as returned by
                            AcpiGetName()
    usb/1-2.3               USB bus, then the chain of ports
    dt/soc/serial@10000000  Device tree node, by its full path with
                            unit addresses

The supplied string is copied.

Notes

Objects that do not stand for one addressable piece of hardware do not
need a path.

aoHidd_DriverData

Synopsis

[I..], APTR

Function

Provide private data for driver creation.

This attribute is actually reserved for private use by device drivers.
Many driver classes will scan the system and instantiate one or more
objects of own class to control the discovered hardware. This attribute
is intended to specify details of the actual device. For example for
PCI device drivers this can be a pointer to PCI device objects.

Notes

Be careful and do not use this attribute if you implement a public reusable
class which is meant to be subclassed. In this case this attribute can be
used by subclasses, and your own use will make a conflict.

This attribute actually exists only in order to free the developer from need
to create own private interface just for one attribute.

See also

aoHidd_Producer


aoHidd_HardwareName

Synopsis

[I.G], STRPTR

Function

Query hardware name string.

Notes

Initial value for this attribute is usually supplied by driver class in its
moRoot_New implementation.

The supplied string is not copied!

See also

aoHidd_Name


aoHidd_Name

Synopsis

[I.G], STRPTR

Function

Name of the driver instance under which it is known to the OS. This name is
provided to OS components that use the driver. For example Intuition's MONITORCLASS
expects to find something like "ati_dvi1.monitor", "ati_vga1.monitor" or
"pcvga.monitor" here.

Note that is is instance name, not class name. Different instances of the driver may
need to provide different names for different objects (like in ATI example) in order
to let the OS to distinguish between them.

The supplied string is internally copied, you may destroy it after object creation.

Notes

Initial value for this attribute is usually supplied by driver class in its
moRoot_New implementation.

aoHidd_Parent

Synopsis

[I.G], OOP_Object *

Function

The object this object belongs to: the subsystem a driver is registered
in, the controller of a bus, the bus of a unit, the driver of a display.

This is the vHidd_Relation_Parent relation of the object. Supplying
the attribute on creation declares that relation, and reading it
returns the first object the object has such a relation with.

Notes

Objects created with moHW_AddDriver get this relation to their
subsystem without asking for it.

aoHidd_Producer

Synopsis

[I.G], ULONG

Function

Query hardware manufacturer's numeric ID. This ID may come for example from PCI
or Zorro bus configuration data.

Notes

It is valid to return 0 if your hardware doesn't provide any ID number.

Initial value for this attribute is usually supplied by driver class in its
moRoot_New implementation.

See also

aoHidd_Product


aoHidd_ProducerName

Synopsis

[I.G], STRPTR

Function

Query hardware manufacturer string. NULL is a valid value for this attribute
meaning that the information is not specified.

Notes

Initial value for this attribute is usually supplied by driver class in its
moRoot_New implementation.

The supplied string is not copied!

aoHidd_Product

Synopsis

[I.G], ULONG

Function

Query hardware's numeric produce ID. This ID may come for example from PCI
or Zorro bus configuration data.

Notes

It is valid to return 0 if your hardware doesn't provide any ID number.

Initial value for this attribute is usually supplied by driver class in its
moRoot_New implementation.

See also

aoHidd_Producer


aoHW_Device

Synopsis

[I.G], OOP_Object *

Function

The object representing the device a driver object operates, for
example the CLID_Hidd_PCIDevice object of a PCI card.

This attribute applies to driver objects, not to subsystems. It is
implemented by hiddclass, as the vHidd_Relation_Device relation of the
object: supplying it on creation declares that relation, and reading it
returns the first object the driver has such a relation with.

Notes

The device object has to be a HIDD object. A driver which operates
hardware that is not represented by an object can name it by its
device path instead, using moHidd_AddRelation.

moHidd_AddRelation

Synopsis

BOOL OOP_DoMethod(OOP_Object *obj, struct pHidd_AddRelation *Msg);

BOOL HIDD_AddRelation(OOP_Object *obj, ULONG type, OOP_Object *target,
                      struct TagItem *tags);

Function

Declares a relation between the object and another object.

Inputs

obj    - The object declaring the relation.
type   - What the target is to the object, one of vHidd_Relation_#?:

            vHidd_Relation_Parent      - The object containing or managing it.
            vHidd_Relation_Child       - An object it contains or manages.
            vHidd_Relation_Device      - The bus device object it operates.
            vHidd_Relation_Driver      - A driver object operating it.
            vHidd_Relation_Uses        - A resource it depends on.
            vHidd_Relation_UsedBy      - An object depending on it.
            vHidd_Relation_Exposes     - An object it publishes, for example
                                         a telemetry object or a display.
            vHidd_Relation_ExposedBy   - The object publishing it.
            vHidd_Relation_Firmware    - Its description in the firmware.
            vHidd_Relation_FirmwareOf  - The hardware it describes.
            vHidd_Relation_PoweredBy   - What supplies it with power.
            vHidd_Relation_Powers      - What it supplies with power.
            vHidd_Relation_Monitors    - The hardware its readings are about.
            vHidd_Relation_MonitoredBy - An object reading its state.
            vHidd_Relation_Companion   - Another function of the same device.

         Types from vHidd_Relation_User on are free for private use.
target - The other object, which has to be a HIDD object too, or NULL
         if it is named with tHidd_Relation_Path.
tags   - Optional additional information:

            tHidd_Relation_Path (CONST_STRPTR)
                Device path of the target. The relation connects to the
                object with this aoHidd_DevicePath when there is one,
                and follows it coming and going. Ignored when a target
                object is given.
            tHidd_Relation_Label (CONST_STRPTR)
                A short description of what the target is used as,
                such as "DDC bus" or "Core temperature".

         The strings are copied.

Result

TRUE if the relation exists now, FALSE in case of failure.

Notes

A relation needs to be declared by one of its two objects only. Declaring
one that exists already, from either side, succeeds without effect.

This method must not be called from within a moHidd_EnumRelations hook.

moHidd_EnumRelations

Synopsis

VOID OOP_DoMethod(OOP_Object *obj, struct pHidd_EnumRelations *Msg);

VOID HIDD_EnumRelations(OOP_Object *obj, ULONG type, struct Hook *callback,
                        APTR hookMsg);

Function

Enumerates the relations of the object, including those declared by
other objects.

Inputs

obj      - The object to query.
type     - The type of relation to report, or vHidd_Relation_Any.
callback - A user-supplied hook which will be called for every relation.
hookMsg  - A user-defined data to be passed to the hook.

The hook will be called with the following parameters:
    AROS_UFHA(struct Hook *         , hook    , A0)
        - A pointer to hook structure itself
    AROS_UFHA(struct HIDD_Relation *, relation, A2)
        - Description of the relation:
            hr_Type   - Its type, as seen from the object queried.
            hr_Object - The related object, or NULL if the relation
                        was declared by path and there is no object
                        with this path at the moment.
            hr_Path   - Device path of the related object, or NULL.
            hr_Label  - Description of the relation, or NULL.
    AROS_UFHA(APTR                  , message , A1)
        - User-defined data

The hook should return FALSE in order to continue enumeration
or TRUE in order to stop it.

Result

None.

Notes

The structure and its strings are only valid during the call.

moHidd_FindDevicePath

Synopsis

OOP_Object *OOP_DoMethod(OOP_Object *obj, struct pHidd_FindDevicePath *Msg);

OOP_Object *HIDD_FindDevicePath(OOP_Object *obj, CONST_STRPTR path);

Function

Finds the object representing a piece of hardware.

Inputs

obj  - Any HIDD object. The result does not depend on it. The
       CLID_HW_Root object is the usual choice.
path - The device path to look for.

Result

A pointer to the object which was created with this aoHidd_DevicePath,
or NULL if there is none.

moHidd_FindRelated

Synopsis

OOP_Object *OOP_DoMethod(OOP_Object *obj, struct pHidd_FindRelated *Msg);

OOP_Object *HIDD_FindRelated(OOP_Object *obj, ULONG type, CONST_STRPTR classID);

Function

Returns the first object the object has a relation of the given kind with.

Inputs

obj     - The object to query.
type    - The type of relation, or vHidd_Relation_Any.
classID - If not NULL, only objects of this public class, or of a
          subclass of it, are considered.

Result

A pointer to the related object, or NULL if there is none.

Example

// The subsystem a driver is registered in
subsystem = HIDD_FindRelated(driver, vHidd_Relation_Parent, NULL);

// The first sensor a driver publishes
sensor = HIDD_FindRelated(driver, vHidd_Relation_Exposes, CLID_Hidd_Telemetry);

moHidd_RemoveRelation

Synopsis

BOOL OOP_DoMethod(OOP_Object *obj, struct pHidd_RemoveRelation *Msg);

BOOL HIDD_RemoveRelation(OOP_Object *obj, ULONG type, OOP_Object *target,
                         CONST_STRPTR path);

Function

Removes a relation of the object.

Inputs

obj    - The object.
type   - Type of the relation, as seen from the object.
target - The related object, or NULL to select the relation by path.
path   - The device path the relation was declared with. Only used if
         target is NULL.

Result

TRUE if the relation was found and removed.

Notes

There is no need to remove relations before disposing an object.

This method must not be called from within a moHidd_EnumRelations hook.

CLID_HW_Root

--background_hwroot--      

--background_hwroot--

Notes

This class represents a root of HIDD subsystem tree. In other words, it
represents your computer. Calling HW_EnumDrivers() on it will enumerate
installed subsystem classes.

By design this class is a singletone. In order to get access to it, just
call OOP_NewObject() on it. Every call will return the same pointer to
the same object. You do not need to call OOP_Dispose object on it. Such
calls will simply do nothing.

Subsystem classes need to register themselves in the tree by calling
HW_AddDriver() on this class. The class keeps an eye on the subsystem
usage and will allow to remove it using HW_RemoveDriver() only if the
subsystem being removed is not in use by any other components.

CLID_HW

--background_hwclass-- aoHW_ClassName aoHW_InUse moHW_AddDriver
moHW_CleanUpDriver moHW_EnumDrivers moHW_RemoveDriver moHW_SetUpDriver

--background_hwclass--

Notes

The hwclass is the base class for all hardware subsystems in AROS. Its
main purpose is to manage hardware driver instances.

A hardware subsystem is typically a class of devices, e. g. keyboards, mice, etc.
The hwclass stores information about existing driver instances, for enumeration by client
applications.

The hwclass is a subclass of hiddclass. A subsystem object thus has relations like any
other HIDD object, and every driver object added to it is given a vHidd_Relation_Parent
relation to it (see moHidd_AddRelation).

A typical hardware subsystem class should be implemented as a singleton to simplify
handling.

aoHW_ClassName

Synopsis

[I.G], CONST_STRPTR

Function

Query human-readable description of the class. E. g. "Keyboards".

aoHW_InUse

Synopsis

[..G], BOOL

Function

Returns TRUE if the subsystem is currently in use by some driver(s)
and FALSE otherwise.

moHW_AddDriver

Synopsis

OOP_Object *OOP_DoMethod(OOP_Object *obj, struct pHW_AddHardwareDriver *Msg);

OOP_Object *HW_AddDriver(OOP_Object *obj, OOP_Class *driverClass,
                         struct TagItem *tags);

Function

Creates a hardware driver object instance, and registers it in the subsystem.

Inputs

obj         - The subsystem object to operate on.
driverClass - A pointer to OOP class of the driver. In order to create an object
              of some previously registered public class, use
              oop.library/OOP_FindClass().
tags        - An optional taglist which will be passed to driver class' New() method.

Result

A pointer to driver object or NULL in case of failure.

Notes

Do not dispose the returned object yourself, use HW_RemoveDriver() for it.

moHW_CleanUpDriver

Synopsis

void OOP_DoMethod(OOP_Object *obj, struct pHW_CleanUpDriver *Msg);

void HW_CleanUpDriver(OOP_Object *obj, OOP_Object *driverObject);

Function

Performs subsystem-specific cleanup before driver object disposal.
This method is intended to be used only by subclasses of CLID_HW.

Inputs

obj          - A subsystem object.
driverObject - Device driver object.

Result

None.

Notes

In base class this method does nothing.

See also

moHW_SetUpDriver


moHW_EnumDrivers

Synopsis

void OOP_DoMethod(OOP_Object *obj, struct pHW_EnumDrivers *Msg);

void HW_EnumDrivers(OOP_Object *obj, struct Hook *callback, APTR hookMsg);

Function

Enumerates all installed driver in the subsystem.

Inputs

obj      - A subsystem object to query.
callback - A user-supplied hook which will be called for every driver.
hookMsg  - A user-defined data to be passed to the hook.

The hook must be defined using the AROS_UFH family of macros,
and it will be called with the following parameters:
    AROS_UFHA(struct Hook *, hook        , A0)
        - A pointer to hook structure itself
    AROS_UFHA(OOP_Object * , driverObject, A2)
        - A device driver object
    AROS_UFHA(APTR         , message     , A1)
        - User-defined data

The hook should return FALSE in order to continue enumeration
or TRUE in order to stop it.

Result

None.

moHW_RemoveDriver

Synopsis

void OOP_DoMethod(OOP_Object *obj, struct pHW_RemoveDriver *Msg);

void HW_RemoveDriver(OOP_Object *obj, OOP_Object *driver);

Function

Unregisters and disposes hardware driver object.

Inputs

obj    - The subsystem object from which the driver should be removed.
driver - A pointer to a driver object, returned by HW_AddDriver().

Result

TRUE if removal successful or FALSE upon failure.

Notes

The base class returns FALSE only if the driver is not registered
in the subsystem. However, subclasses implementing actual subsystems
can add their own checks, for example whether the driver currently
owns some objects which are in use, and thus cannot be disposed.

See also

moHW_AddDriver


moHW_SetUpDriver

Synopsis

void OOP_DoMethod(OOP_Object *obj, struct pHW_SetUpDriver *Msg);

void HW_SetUpDriver(OOP_Object *obj, OOP_Object *driverObject);

Function

Performs subsystem-specific setup after driver object creation.
This method is intended to be used only by subclasses of CLID_HW.

Inputs

obj          - A subsystem object.
driverObject - Device driver object.

Result

TRUE if setup completed successfully and FALSE in case of error.
If this method returns error, the driver object will be disposed
and moHW_AddDriver method will fail.

Notes

In base class this method does nothing and always returns TRUE.

Docutils System Messages

System Message: ERROR/3 (/home/runner/work/1/b/documentation/web/documentation/developers/autodocs/hidd_hidd.en.rst, line 911); backlink

Unknown target name: "mohw_remhardwaredriver".