This appendix describes the use, format, parameters, and options for the four GPIO com-mands that the user can invoke: aqdev, crddf, cvt_at, and rldev.
aqdev (acquire_device) Acquires control of a peripheral device.
FORMAT
aqdev pathname [-d[b]] [-c progname argJ arg2 ... ]
ARGUMENT
OPTION
pathname (required)
-d[b]
-c
The pathname of the DDF associated with the device to be acquired.
The pathname normally refers to the a DDF in Idev directory on the node to which the device is physically attached.
Acquires the device in debug mode. Specifying this option causes aqdev to display the addresses of the DDF and the CSR page, and to display information about device driver routines as they are loaded into user-process address space.
Allows aqdev to run a command instead of a shell. Specifying this op-tion causes aqdev to acquire the device, run progname (passing argJ, arg2 ... to the program), release the device, and finally, return to the shell. This option also allows the user to use aqdev in a shell script (see example 3).
DESCRIPTION
NOTE: This command is supported only for compatibility purposes. At SR10 the aqdev command is available only in the Aegis envi-ronment, and will not be supported in the next major Software Release.
The aqdev command is used to acquire a device at the shell command level. When in-voked, aqdev calls the routine pbu_$acquire, which maps to user-process address space the DDF, the device's CSR page, and device driver routines and associat~d data structures.
Currently, the aqdev command (without the -c option) creates a new copy of the shell after it installs the device driver. To release the device, exit the shell, which causes the new shell to return to the aqdev command. The aqdev command then releases the device.
A-2 GPIO Commands
ERROR MESSAGES
ddf has wrong file type
The file pointed to by the specified pathname is not a DDF.
name not found
The file pointed to by the specified pathname does not exist.
object is not local
The DDF belongs to a device that is physically connected to another node.
PBU not present
No peripheral bus is present on the system.
unit in use
Another process is using the device.
unit is global
EXAMPLES
Device unit number is already acquired as a global device.
1.
$ aqdev Idev/mtO -db
DDF mapped at 2DOOOO for 1024 bytes.
Interrupt stack_size
=
1024 CSR page at 2D8000aqdev
Interrupt library: start address = 000000, n_sects 3 Name PROCEDURE$, loc
=
2BABAE, len=
0002ACName = DATA$, loc = 2BAEFC, len = 000C6E Name = DEBUG$, loc
=
2BAE5A, len = 0000A2Call library: Start address
=
000000, n_sects 3 Name PROCEDURE $ , loc=
2E0040, len=
00126C Name DATA$, loc=
2BBB6A, len=
000190 Name DEBUG$, loc=
2E12AC, len = 00051C Device 3 acquired.$
aqdev
2.
3.
A-4 GP 10 Commands
$ aqdev /dev/my_dev Device 0 acquired.
$ (Run your program using the device.)
$ CTRL/Z
***
EOF***
Device 0 released.
$
$ aqdev /dev/my_dev -c driver_application Device 0 acquired.
(driver_application runs using the device.) Device 0 released.
$
crddf (create_ddf) Creates, displays, or modifies a Device Descriptor File (DDF).
FORMAT
crddf pathname [-option] [-option] ...
[-J
ARGUMENT
OPTIONS
pathname (required)
-at
The pathname of the DDF to be created. The pathname normally refers to a DDF in the Idev directory on the node to which the device is physi-cally attached.
Specifies that crddf is to read further options from stream_$stdin.
Specifies that the device resides on the IBM PC AT compatible bus. It is recommended that this option be the first specified when building a new DDF. Valid unit numbers when -at is specified must be in the range 0-15 and must not be used by Domain system-supplied devices. Specify-ing this option results in the generation of a Version 3 DDF.
-call_library pathname
-check
Specifies the pathname of the call side of the driver. This option is re-quired when creating a DDF.
Checks the DDF to ensure that all required files have been specified. The options associated with these requirements are call_library, initializa-tion_routine, node, and unit.
-cleanup_routine entry-name
Specifies the entry point name of a cleanup routine to be called when the device is released.
-csr_offset port-number
Specifies the offset into the CSR page, in hexadecimal format, at which the device's control and status registers are located. Device drivers may use this information during controller initialization. Specifying this option results in the generation of a Version 2 DDF.
crddf
-csrJlage iova Specifies the hexadecimal address of the device's CSR page. If this option is omitted, no CSR page is mapped. The following information applies to the particular bus structure implemented on your node:
-debug -display
• MULTIBUS: Optional. If specified, must be page aligned.
• VMEbus: Optional. If specified, must be page aligned and in the range 0000-7FFF (16-bit addressing, 16-bit data path) and COOO-DFFF (24-bit addressing, 16-bit data path).
• PC AT compatible bus: Optional. If specified, must be 8-byte aligned, may indicate a range (-csrj>age 200 21F). If the second parameter is missing, a range of eight consecutive bytes is assumed ("-csrj>age 200" assumes a range of 200-207). Use the cvt_at command (described in this appendix) to derive properly aligned iovas.
Specifies the device driver's initialization routine entry point name.
pbu_$acquire calls this routine during device acquisition. This option is required when creating a DDF.
-interrupt_library pathname
Specifies the pathname of the device driver's interrupt side. You only need to specify this parameter if you have user-written interrupt routines.
-interruptJoutine level [entry-name]
Assigns an interrupt request level to the device and optionally specifies the name of an interrupt routine to handle device interrupts at that level.
The level is required; the name of the interrupt routine is optional. If no entry-name is specified, the System Interrupt Handler processes the inter-rupt and advances the eventcount associated with the device. A single device may interrupt at several levels. If that is the case, this option can be specified more than once.
If the -interrupt_routine option is omitted, interrupts are processed at the level equal to the device's unit number.
A-6 GPIO Commands
crddf pbu[2L$map_controller to associate a virtual address with the memory on the controller. Specifying this option with an iova less than 64 KB results in the generation of a Version 2 DDF; if the iova is greater than 64 KB, a Version 3 DDF is generated.
-memory_size length
The size, in hexadecimal format, of controller memory. Device drivers use this information in arguments to pbu[2L$map_controller to associ-ate a virtual address with the memory on the controller. Specifying this pbu_$acquire to use copies of previously loaded call-side and interrupt-side libraries, so as to avoid loading mUltiple copies of the same driver.
Specifies an optional revision number as an 8-character string.
-serial_number [string-16]
Specifies an optional serial number as a 16-character string.
crddf
-share Specifies that the DDF describes a memory-mapped controller that can be shared by multiple applications. The pbu[2LSmap_controller routine maps the shared controller into global address space, and pbu_Smemytr returns its address. Unlike a nonshared controller, a shared controller is not automatically unmapped on abnormal termination of a device driver.
NOTE: Apollo recommends that a fault handler be estab-lished to ensure that the controller is unmapped should the driver terminate without going through the normal device release mechanism.
-stack_size decimal-number corresponds to the type of type_name. The crddf command then uses the result of the look-u..p as the DDF's major device number. If crddf bus structure implemented on your node:
• MULTIBUS: Must lie in the range 0-5 for a 16-bit controller
crddf - 20_ bit_addressing
DESCRIPTION
Specifies that the DDF describes a 20-bit controller. You must use this option when creating a DDF for a 20-bit controller on a node that has a 20-bit MULTIBUS.
Invoke the crddf command at the shell prompt or from a shell command file to create, display, or modify a DDF. The DDF created by crddf is a character special device file.
You can create different versions of a DDF, depending upon which options you specify with the crddf command. Modifying an existing DDF by adding Version 2 or Version 3 options results in the generation of a Version 2 or Version 3 DDF. Refer to Chapter 11, Table 11-1 for a list of the relevant options and to Chapter 11, Section 11.1 through Sec-tion 11.3 for a discussion of the different DDFs and examples that show how to create them. Note that all three versions must include the following options: unit, node, call_library, and initializationJoutine.
The following options are not used by the operating system and are only for the optional use of the driver: csr_offset, debug, dma_channel, memory_base, memory_size, revision, serial_number, and user_info.
The entire contents of the DDF are available to the driver's initialization routine by refer-ence through the ddf _ptr argument.
EXAMPLES
1. Create a new DDF specifying only the required information.
$ crddf Idev/mtO -new ddf.
> -unit 3
> -node 2f
> -csryage 1400
> -call_library /lib/mt.lib
> -initializationJoutine mt_$init
> -interrupt_library /lib/mt.int.lib
> -interruptJoutine 3 mt_$int
> -check
no missing fields.
> -end
$
crddf
$ crddf Idev/mtO -update -interruptJoutine 3 mt_$sio
$
4. Create a new DDF for a device that will be accessed through streams for the installed type "foodev" (for information on writing and using streams managers refer to the Using the OPEN System Toolkit to Extend the Streams Facility
> -interrupt_routine 3 mt_$int
> -type foodev
cvt_at (convert_at_addresses) Converts a PC AT compatible I/O address to a processor physical address.
FORMAT
ARGUMENTS at addr
A PC AT compatible I/O address in hexadecimal.
at_addr l-at_addr2
A range of PC AT I/O addresses in hexadecimal.
DESCRIPTION
The cvt_at command converts PC AT compatible bus addresses to physical addresses in processor address space. The command reports any conflict between the PC AT address you specify and the address of any system-supplied device. It also supplies the iova for so-called PC AT (16-bit) addresses (see Example 2 that follows).
If one or more addresses are specified, each is translated, and its physical address, page number, offset within a page, and the CSR page iova are displayed. If addresses are speci-fied in pairs and both fall on the same page, a warning is given. Also, if one of the ad-dresses in the pair is in the 0-3FF range for lO-bit controllers and the other address is in the 3FF-FFFF range for l6-bit controllers, a warning is given if they would conflict with each other on the bus.
If a dashed parameter is specified, all addresses between those values are generated and converted. Both addresses must be either lO-bit or l6-bit.
A warning is given if an address conflicts with a known system device control page within processor memory.
EXAMPLES DOMAIN device, if present: winchester (4DOOO).
The cvt_at command converts the I/O address 1A4 to the Domain address 4D004 and DOMAIN device, if present: winchester (4DOOO).
A-12 GPIO Commands
rldev (release_device) Releases a peripheral device.
FORMAT
rldev {unit-number
I
all} [-force]ARGUMENTS
unit-number
all
OPTION
-force
The unit number of the device to be released.
Causes rldev to release all devices acquired by the current process.
Causes rldev to release the device unconditionally. waiting 1 second (at most) for any I/O operations to complete.
DESCRIPTION
NOTE: This command is currently supported only for compatibility pur-poses. At SRI0 it is available only in the Aegis environment.
and will not be supported at the next major Software Release.
The r1dev command releases one or more devices previously acquired by the aqdev com-mand (or pbu_$acquire). Currently. when you invoke rldev. a message appears advising you to insert the EOF mark to release the device.
ERROR MESSAGES
device not acquired
The current process has not acquired any device associated with the specified unit number.
object is not local
The DDF belongs to a device that is physically connected to another node.