View source for PDDREF:Resource Management

This chapter contains a description of the OS/2 Resource Management architecture. Areas covered include architecture overview, programming interface definitions, programming structure definitions, and general development usage information. 

==Overview==
The increased user demand for additional functions in a computer system has resulted in a broader range of more sophisticated peripheral and internal system devices. The continued expansion of computer devices has in turn, stressed the already limited pool of system resources, as well as raised the complexity of detecting and configuring the devices.

Therefore, OS/2 is introducing a centralized Resource Management architecture to facilitate the coexistence and cooperation of the increasing number of device drivers. The following figure depicts the main components that comprise the OS/2 Resource Management architecture.

With the introduction of this architecture, a functional line has been drawn separating previous device driver capabilities and those of the OS/2 device drivers written to use the Resource Manager services. Device drivers written to use the Resource Manager Services are referred to as RM-aware drivers. Existing OS/2 2.x device drivers are referred to as legacy drivers. Furthermore, the definition of legacy drivers includes DOS, Windows**, and OS/2 2.x drivers.

At the center of this architecture is the Resource Manager (RESOURCE.SYS), which provides a set of C-callable services to the other RM-aware components. As denoted by the dotted box surrounding the legacy drivers in the preceding figure, an additional RM-aware component (RESERVE.SYS) has been added to report the resources used by these drivers. This reservation driver is key to maintaining an accurate map of the system resources being managed by the Resource Manager. (See RESERVE.SYS for more details on the reservation driver.)

The Resource Manager manages much more than just the system hardware resources. It also assumes centralized responsibility for coordinating all aspects of both the logical and physical views of the hardware and supporting software in the system. The logical view is defined as the standard aliases assigned to devices for application reference (such as COM1, drive A, and LPT1). The physical view is defined as the actual details of the hardware topology such as port addresses and bus type.

In order to discuss the organization of the logical and physical views provided by the Resource Manager, several concepts and terms need to be reviewed. These concepts and terms are presented next. 

====Resources====
The hardware resources managed by the Resource Manager are:

* I/O Port Ranges
* IRQ Levels
* DMA Channels
* Memory Regions
* Timer Channels 

Driver writers are encouraged to identify their hardware settings during driver initialization directly rather than relying on the end-user to provide this information.

The Resource Manager services facilitate this process by identifying resources (I/O Ports, DMA Channels, and IRQ Levels) that are already claimed by drivers and have been initialized previously. A driver using the Resource Management calls can avoid inadvertently corrupting the state of adapters that were initialized by previously loaded drivers.

When resources are assigned, various levels of sharing are allowed. The type of sharing allowed depends on the underlying characteristics of the devices. Resource sharing options are discussed in Managing System Resources. 

====Drivers, Adapters, and Devices====
The Resource Manager also manages drivers, adapters, and devices. Adapters and devices are associated with each other in a parent-child-sibling relationship. A driver is associated with each adapter or device node. They are defined as follows: 

======Drivers======
A driver usually represents a software module responsible for management of one or more pieces of physical hardware. In addition, drivers include value-added subsystems that may not directly interact with physical hardware. To use other Resource Manager services, it is necessary to provide a driver handle that is obtained when declaring a driver. 

======Adapters======
Adapters are defined as devices that convert from one bus protocol to another. For example, a SCSI adapter converts the host bus protocol (for example, ISA, EISA, or PCI), to SCSI bus protocols. The system bus (for example, ISA, EISA, or PCI) is represented in the Resource Manager as an adapter, converting from the CPU-internal bus protocols to a standard host-bus protocol.

In some cases, adapters may not directly correspond to physical packaging. An example of this could be a CD-ROM port on a multifunction sound board that is represented as a separate adapter. However, it is generally encouraged to try to "align" adapters with the physical packaging of the system to help end-users to identify their hardware easily. 

======Devices======
Devices are defined in the "traditional" meaning of end-user devices. This includes printers, disks, CD-ROMS, and so forth. 

==Physical View Management==
The Resource Manager maintains a physical view of the system (hardware topology) that is utilized by all RM-aware components.

The physical view is shown in a tree structure. Each node within the tree structure represents a device or adapter. Associated with each adapter or device node are resource and driver structures.

The Resource Manager automatically creates adapter and device nodes representing basic system resources, such as the CPU and system buses during its initialization. In addition, devices managed directly by the OS/2 kernel, such as the Interrupt Controller (PIC) and DMA Channels, are also automatically defined. In the following diagram, the X_Bus represents the system bus where many of the integrated components reside, such as the DMA control and the real-time clock. The following is a physical view of the Resource Manager.

As device drivers initialize, additional adapter and device nodes are created by the device drivers issuing Resource Manager service calls.

Each node has associated resources owned by the underlying device or adapter and the software driver responsible for managing the adapter or device. The following diagram illustrates the process. 

====Device Adapter Keys====
Each adapter device node contains text describing the adapter or device. To facilitate searching for a particular node, the beginning characters of the descriptive text are assumed to be keys. Keys are subject to the following rules:
* Any sibling nodes, such as nodes connected to the same parent, must have unique keys.
* Keys end at the first blank character or the 16th consecutive non-blank character.
* Keys are part of the descriptive text and must consist of printable ASCII characters. 

Assign unique keys to adapter nodes based on their product name or function. For example:

CPU_0

    CPU x486 

IDE_0

    Generic IDE Channel Adapter 

AHA154X_0

    AHA154X_0 

AHA154X_1

    Adaptec** 154X SCSI Adapters 

PAS16

    Pro AudioSpectrum** Audio Adapter 

If multiple occurrences of the same type of adapter occurs, keys must be made unique by appending a _0, _1, ..., suffix to the key.

The Resource Manager services can automatically generate the _0, _1, ... suffix based on the adapter number supplied. Refer to RMCreateAdapter for further information.

Assign the following the naming conventions for device nodes:

COMM_0

    Serial Port 

DISK_0

    DASD Device 

CDROM_0

    CDROM Device 

TAPE_0

    Tape Device 

PRINTER_0

    Printer Device 

SCANNER_0

    Scanner Device 

The Resource Manager services can automatically generate the _0, _1, ... suffix based on the device number supplied. This is done by including a "#" character at the end of the key. The RMCreateAdapter service and the RMCreateDevice service will replace the "#" character with the adapter or device number indicated. For example:

      DSKT_#  - 1.44MB diskette drive

will be converted to:

      DSKT_0  - 1.44 MB diskette drive

This process will occur provided that an adjunct structure containing the device number (ADJ_DEVICE_NUMBER) is passed on the RMCreateDevice service call. Adjunct data structures are discussed in Adjunct Data. Keys for SCSI devices should use the above device types followed by _(t,l) corresponding to the Target/Lun SCSI device. For example:

    DISK_(0,0)
    CDROM_(3,0)

RMParseSCSIInquiry automatically generates appropriate keys for SCSI devices. An adjunct structure containing the Target/Lun device (ADJ_SCSI_TARGET_LUN) should be passed on the RMCreateDevice service call. 

====Adjunct Data====
At times it is necessary to pass data to the Resource Manager services that can be relevant in one case but not in another call to the same service. In these cases, this optional data is passed in a linked list of structures called an Adjunct List.

The contents of the structures are determined by the adjunct types that are defined in RMBASE.H. A few of the more common adjunct types are listed as follows:

ADJ_DEVICE_NUMBER
        Contains the zero-based unit number for the device being created. The Resource Manager will use this number to enumerate the key for the device. 

ADJ_ADAPTER_NUMBER
        Contains the zero-based adapter number for the adapter being created. The Resource Manager will use this number to enumerate the key for the adapter. 

ADJ_SCSI_TARGET_LUN
        Contains the SCSI Target/Lun for the device being created. The Resource Manager will generate a SCSI type enumeration suffix as described in Device Adapter Keys. 

ADJ_ADD_UNIT
        Contains the ADD/DM ADD Handle and Unit Handle assigned to the device being created. 

ADJ_DRIVER_DATA
        Contains the device driver information for the detected device.

====Managing System Resources====
When a device driver allocates resources, it specifies the level of sharing that the driver is willing to accept. The level of sharing selected depends on the characteristics of the hardware, such as its ability to coordinate usage of IRQ or DMA channels with other adapters, as well as the importance of other functions that may need the same IRQ level. Resources are allocated on a first-come first-serve basis.

If a driver requests a resource that has been previously allocated to another driver, then the sharing mode selected by the earlier driver is used to determine if the new driver's request will be granted.

The following resource sharing options are available:

    EXCLUSIVE
        The resource (such as the I/O Port and DMA Channel) is committed to the owner until it is explicitly released. Any other requests for this resource will be denied. 

SHARED
        The resource will be granted to any requester that also requests the resource as shared. This implies that the users of the resource can use it at any time without interfering with each other. An example of a shared resource would be a shared interrupt on a Micro Channel* or EISA bus machine. 

MULTIPLEXED
        The resource will be granted to any requester that also requests the resource as multiplexed. Multiplexed (unlike shared) implies that only one owner can actively be using the resource and that there is explicit notification between owners to control which requester is using the resource. In general, this sharing protocol is private to the multiplexed resource. 

GRANTYIELD
        The resource will be granted to any requester that also requests the resource as GRANTYIELD. GRANTYIELD implies that the owner of the resource is willing to participate in a sharing of a resource that is arbitrated by a Resource Manager.

'''Note:''' GRANTYIELD protocol is not currently in version 1.1 of RESOURCE.SYS. 
 
==Logical View Management==
The Resource Manager maintains a logical view of the system device nodes that is utilized by applications, end-users, and device managers (or drivers performing similar functions). This section discusses the key aspects of the logical view.

OS/2 uses aliases to identify various physical devices. Typically, these aliases are short descriptive names that are familiar to most users, such as DISK_0, drive A or C, COM1, and LPT1.

The use of aliases simplifies the operating system's (and end-user's) view of the system in the following ways:

* The implementation of a physical device (for example, a disk), depends on a combination of the system bus, a SCSI or IDE adapter, and the disk device. It is convenient to the end user to abstract this to a simple name such as DISK_0, DISK_1, and so forth, rather than using the full path name to the device.
* The operating system may subdivide (or group) devices so the physical device boundaries are no longer relevant. For example, partitioning subdivides a physical disk into a series of separate drives, while a RAID array may group several physical devices into a single drive.
* The operating system can have alternate views of the same physical device. For example, a physical serial port can be used as a FAX port (FMD1$) or used as an ASYNC port (COM1), depending on the application using the port. 

To provide a mapping from the logical (end-user) view of the system to the actual hardware topology, the Resource Manager maintains a separate node structure called a logical tree as shown in the following diagram:

The logical tree contains two types of nodes, logical devices (LDEVs) and system names (SYSNAMEs). Logical device nodes represent aliases of nodes on the physical device tree. The system name nodes represent named divisions of the parent LDEV.

Depending on the nature of the device, these names can be alternate definitions of the LDEV that are mutually exclusive (such as FMD1$ and COM1:) or they can be shared (such as drive letters C, E, or F).

Logical devices and system names are associated with each other in a parent-child-sibling relationship. A driver is associated with each LDEV node.

The Resource Manager automatically creates logical device nodes representing basic system device types such as DASD, CD-ROM, tape, serial, and parallel, during its initialization. Device managers and certain device drivers (such as COM.SYS) create additional logical devices and system name nodes as they declare new devices to the OS/2 kernel. 

==RESERVE.SYS ==
RESERVE.SYS is used in conjunction with the Resource Manager in two separate scenarios:

* If you are using a device driver that is not Resource Manager-aware and you know the resources that the device uses, use RESERVE.SYS to reserve those resources so the Resource Manager-aware drivers will not have access to those resources.
* If you have a piece of hardware that does not tolerate the examination of its resources, reserve the resources so the Resource Manager-aware drivers do not examine the hardware. 

To use RESERVE.SYS, place the following statement as the first line in CONFIG.SYS:

 basedev=reserve.sys  <arguments>

Arguments:
<PRE>
    ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
    v                                             ³
 ÃÄÄÂÄÄ /IO:  ÄÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÁÄÄÄ
    ÃÄÄ /P:   ÄÄÁÄÄ/DW: ÄÄ´      ÃÄÄ /EXC ÄÄ´
    ³                     ³      ÃÄÄ /MUL ÄÄ´
    ÃÄÄ /MEM: ÄÄÄÄÄÄÄÄÄÄÄÄ´      ÀÄÄ /SHA ÄÄÙ
    ÃÄÄ /DMA: ÄÄÄÄÄÄÄÄÄÄÄÄ´
    ÀÄÄ /IRQ: ÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³Switch         ³Format         ³Example        ³Description    ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/IO:           ³/IO:x,x        ³/IO:340,4      ³Reserve IO     ³
³               ³               ³               ³ports. The     ³
³               ³               ³               ³first number is³
³               ³               ³               ³the base port  ³
³               ³               ³               ³in HEX, and is ³
³               ³               ³               ³followed by the³
³               ³               ³               ³length (number ³
³               ³               ³               ³of ports) in   ³
³               ³               ³               ³hexidecimal    ³
³               ³               ³               ³format.        ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/P:            ³same as /IO:   ³               ³               ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/MEM:          ³/MEM:x,x       ³/MEM:CA00,1000 ³Reserve Memory.³
³               ³               ³               ³The first      ³
³               ³               ³               ³number is the  ³
³               ³               ³               ³base memory    ³
³               ³               ³               ³address (HEX), ³
³               ³               ³               ³with the       ³
³               ³               ³               ³assumption that³
³               ³               ³               ³the address is ³
³               ³               ³               ³XXXX:0, and is ³
³               ³               ³               ³followed by the³
³               ³               ³               ³length (number ³
³               ³               ³               ³of address) in ³
³               ³               ³               ³hexidecimal    ³
³               ³               ³               ³format.        ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/DMA:          ³/DMA:x         ³/DMA:2         ³Reserve DMA    ³
³               ³               ³               ³Channel. The   ³
³               ³               ³               ³number is in   ³
³               ³               ³               ³decimal format.³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/IRQ:          ³/IRQ:x         ³/IRQ:13        ³Reserve IRQ.   ³
³               ³               ³               ³The number is  ³
³               ³               ³               ³in decimal     ³
³               ³               ³               ³format.        ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/EXC           ³/EXC           ³/EXC           ³Exclusive      ³
³               ³               ³               ³resource       ³
³               ³               ³               ³attribute.     ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/MUL           ³/MUL           ³/MUL           ³Multiplexed    ³
³               ³               ³               ³resource       ³
³               ³               ³               ³attribute.     ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/SHA           ³/SHA           ³/SHA           ³Shared resource³
³               ³               ³               ³attribute.     ³
ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³/DW:           ³/DW:x          ³/DW:10         ³Decode width of³
³               ³               ³               ³IO address.    ³
³               ³               ³               ³Valid numbers  ³
³               ³               ³               ³are 10 and 16. ³
³               ³               ³               ³Only valid with³
³               ³               ³               ³/IO: switch.   ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
</PRE>
More than one resource attribute per-resource entry is an error and is not allowed. If no attribute or decode width is set, the default is EXCLUSIVE and 16, respectively. For example, to reserve IRQ 13 EXCLUSIVE, DMA 0 SHARED, MEMORY CA00:0 for 1000 hex-bytes shared, IO port 340 for 10 hex-ports EXCLUSIVE with a decode width of 16, and IO port 300 for 64-hex ports, with a decode width of 10:

 BASEDEV=RESERVE.SYS /IRQ:13 /DMA:0 /SHA /MEM:CA00,1000 /SHA /IO:340,10 /IO:300,64 /DW:10