man pages section 9 DDI and DKI Properties and Data Structures · 2012. 2. 22. · thereisnoBUGSsection.Seetheintropagesformoreinformationanddetailabouteach section,andman(1)formoreinformationaboutmanpagesingeneral

man pages section 9: DDI and DKIProperties and Data StructuresBeta

Part No: 821–1478–06November 2010

Copyright © 2010, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectualproperty laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software,unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related software documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the followingnotice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are“commercial computer software” or “commercial technical data” pursuant to the applicable Federal Acquisition Regulation and agency-specific supplementalregulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicableGovernment contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, CommercialComputer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherentlydangerous applications, including applications which may create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim anyliability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. Intel and Intel Xeon aretrademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARCInternational, Inc. UNIX is a registered trademark licensed through X/Open Company, Ltd.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation andits affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporationand its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

110425@25097

Contents

Preface .....................................................................................................................................................7

Introduction .........................................................................................................................................11Intro(9S) .............................................................................................................................................. 12

Data Structures for Drivers ................................................................................................................15aio_req(9S) ......................................................................................................................................... 16audio_engine_ops(9S) ...................................................................................................................... 17buf(9S) .................................................................................................................................................. 19cb_ops(9S) ............................................................................................................................................ 22copyreq(9S) ......................................................................................................................................... 24copyresp(9S) ....................................................................................................................................... 25datab(9S) .............................................................................................................................................. 26ddi_device_acc_attr(9S) ................................................................................................................ 27ddi_dma_attr(9S) ............................................................................................................................... 32ddi_dma_cookie(9S) ........................................................................................................................... 36ddi_dmae_req(9S) ............................................................................................................................... 37ddi_dma_lim_sparc(9S) .................................................................................................................... 41ddi_dma_lim_x86(9S) ......................................................................................................................... 43ddi_dma_req(9S) ................................................................................................................................. 45ddi_fm_error(9S) ............................................................................................................................... 48ddi-forceattach(9P) ........................................................................................................................ 50ddi_idevice_cookie(9S) .................................................................................................................. 51devmap_callback_ctl(9S) ................................................................................................................ 52dev_ops(9S) ......................................................................................................................................... 54fmodsw(9S) ............................................................................................................................................ 56free_rtn(9S) ....................................................................................................................................... 57

3

gld_mac_info(9S) ............................................................................................................................... 58gld_stats(9S) ..................................................................................................................................... 62hook_nic_event(9S) ........................................................................................................................... 64hook_pkt_event(9S) ........................................................................................................................... 66hook_t(9S) ............................................................................................................................................ 68inquiry-device-type(9P) ................................................................................................................ 69iocblk(9S) ............................................................................................................................................ 70iovec(9S) .............................................................................................................................................. 71kstat(9S) .............................................................................................................................................. 72kstat_intr(9S) ................................................................................................................................... 74kstat_io(9S) ....................................................................................................................................... 75kstat_named(9S) ................................................................................................................................. 76linkblk(9S) ......................................................................................................................................... 77mac_callbacks(9S) ............................................................................................................................. 78mac_capab_lso(9S) ............................................................................................................................. 80mac_register(9S) ............................................................................................................................... 81modldrv(9S) ......................................................................................................................................... 83modlinkage(9S) ................................................................................................................................... 84modlmisc(9S) ....................................................................................................................................... 85modlstrmod(9S) ................................................................................................................................... 86module_info(9S) ................................................................................................................................. 87msgb(9S) ................................................................................................................................................ 88net_inject_t(9S) ............................................................................................................................... 89net_instance_t(9S) ........................................................................................................................... 90no-involuntary-power-cycles(9P) ............................................................................................... 91pm(9P) .................................................................................................................................................... 93pm-components(9P) ............................................................................................................................ 95qband(9S) .............................................................................................................................................. 98qinit(9S) .............................................................................................................................................. 99queclass(9S) ..................................................................................................................................... 100queue(9S) ............................................................................................................................................ 101removable-media(9P) ...................................................................................................................... 104scsi_address(9S) ............................................................................................................................. 105scsi_arq_status(9S) ....................................................................................................................... 106scsi_asc_key_strings(9S) ............................................................................................................ 107scsi_device(9S) ............................................................................................................................... 108

Contents

man pages section 9: DDI and DKI Properties and Data Structures • November 2010 (Beta)4

scsi_extended_sense(9S) .............................................................................................................. 109scsi_hba_tran(9S) ........................................................................................................................... 112scsi_inquiry(9S) ............................................................................................................................. 115scsi_pkt(9S) ..................................................................................................................................... 120scsi_status(9S) ............................................................................................................................... 125size(9P) ............................................................................................................................................. 127streamtab(9S) ................................................................................................................................... 129stroptions(9S) ................................................................................................................................. 130tuple(9S) ............................................................................................................................................ 132uio(9S) ................................................................................................................................................ 135usb_bulk_request(9S) .................................................................................................................... 137usb_callback_flags(9S) ................................................................................................................ 141usb_cfg_descr(9S) ........................................................................................................................... 146usb_client_dev_data(9S) .............................................................................................................. 148usb_completion_reason(9S) .......................................................................................................... 153usb_ctrl_request(9S) .................................................................................................................... 155usb_dev_descr(9S) ........................................................................................................................... 158usb_dev_qlf_descr(9S) .................................................................................................................. 160usb_ep_descr(9S) ............................................................................................................................. 162usb_if_descr(9S) ............................................................................................................................. 165usb_intr_request(9S) .................................................................................................................... 167usb_isoc_request(9S) .................................................................................................................... 172usb_other_speed_cfg_descr(9S) .................................................................................................. 176usb_request_attributes(9S) ........................................................................................................ 178usb_string_descr(9S) .................................................................................................................... 182

Contents

5

Preface

Both novice users and those familar with the SunOS operating system can use online man pagesto obtain information about the system and its features. A man page is intended to answerconcisely the question “What does it do?” The man pages in general comprise a referencemanual. They are not intended to be a tutorial.

OverviewThe following contains a brief description of each man page section and the information itreferences:

■ Section 1 describes, in alphabetical order, commands available with the operating system.■ Section 1M describes, in alphabetical order, commands that are used chiefly for system

maintenance and administration purposes.■ Section 2 describes all of the system calls. Most of these calls have one or more error returns.

An error condition is indicated by an otherwise impossible returned value.■ Section 3 describes functions found in various libraries, other than those functions that

directly invoke UNIX system primitives, which are described in Section 2.■ Section 4 outlines the formats of various files. The C structure declarations for the file

formats are given where applicable.■ Section 5 contains miscellaneous documentation such as character-set tables.■ Section 7 describes various special files that refer to specific hardware peripherals and device

drivers. STREAMS software drivers, modules and the STREAMS-generic set of system callsare also described.

■ Section 9E describes the DDI (Device Driver Interface)/DKI (Driver/Kernel Interface),DDI-only, and DKI-only entry-point routines a developer can include in a device driver.

■ Section 9F describes the kernel functions available for use by device drivers.■ Section 9S describes the data structures used by drivers to share information between the

driver and the kernel.

Below is a generic format for man pages. The man pages of each manual section generallyfollow this order, but include only needed headings. For example, if there are no bugs to report,

7

there is no BUGS section. See the intro pages for more information and detail about eachsection, and man(1) for more information about man pages in general.

NAME This section gives the names of the commands or functionsdocumented, followed by a brief description of what theydo.

SYNOPSIS This section shows the syntax of commands or functions.When a command or file does not exist in the standardpath, its full path name is shown. Options and argumentsare alphabetized, with single letter arguments first, andoptions with arguments next, unless a different argumentorder is required.

The following special characters are used in this section:

[ ] Brackets. The option or argument enclosed inthese brackets is optional. If the brackets areomitted, the argument must be specified.

. . . Ellipses. Several values can be provided for theprevious argument, or the previous argumentcan be specified multiple times, for example,"filename . . ." .

| Separator. Only one of the argumentsseparated by this character can be specified at atime.

{ } Braces. The options and/or argumentsenclosed within braces are interdependent,such that everything enclosed must be treatedas a unit.

PROTOCOL This section occurs only in subsection 3R to indicate theprotocol description file.

DESCRIPTION This section defines the functionality and behavior of theservice. Thus it describes concisely what the commanddoes. It does not discuss OPTIONS or cite EXAMPLES.Interactive commands, subcommands, requests, macros,and functions are described under USAGE.

IOCTL This section appears on pages in Section 7 only. Only thedevice class that supplies appropriate parameters to theioctl(2) system call is called ioctl and generates its ownheading. ioctl calls for a specific device are listedalphabetically (on the man page for that specific device).

Preface


http://www.oracle.com/pls/topic/lookup?ctx=821-1461&id=man-1http://www.oracle.com/pls/topic/lookup?ctx=821-1463&id=ioctl-2

ioctl calls are used for a particular class of devices all ofwhich have an io ending, such as mtio(7I).

OPTIONS This secton lists the command options with a concisesummary of what each option does. The options are listedliterally and in the order they appear in the SYNOPSISsection. Possible arguments to options are discussed underthe option, and where appropriate, default values aresupplied.

OPERANDS This section lists the command operands and describeshow they affect the actions of the command.

OUTPUT This section describes the output – standard output,standard error, or output files – generated by thecommand.

RETURN VALUES If the man page documents functions that return values,this section lists these values and describes the conditionsunder which they are returned. If a function can returnonly constant values, such as 0 or –1, these values are listedin tagged paragraphs. Otherwise, a single paragraphdescribes the return values of each function. Functionsdeclared void do not return values, so they are notdiscussed in RETURN VALUES.

ERRORS On failure, most functions place an error code in the globalvariable errno indicating why they failed. This section listsalphabetically all error codes a function can generate anddescribes the conditions that cause each error. When morethan one condition can cause the same error, eachcondition is described in a separate paragraph under theerror code.

USAGE This section lists special rules, features, and commandsthat require in-depth explanations. The subsections listedhere are used to explain built-in functionality:

CommandsModifiersVariablesExpressionsInput Grammar

EXAMPLES This section provides examples of usage or of how to use acommand or function. Wherever possible a complete

Preface

9

http://www.oracle.com/pls/topic/lookup?ctx=821-1475&id=mtio-7i

example including command-line entry and machineresponse is shown. Whenever an example is given, theprompt is shown as example%, or if the user must besuperuser, example#. Examples are followed byexplanations, variable substitution rules, or returnedvalues. Most examples illustrate concepts from theSYNOPSIS, DESCRIPTION, OPTIONS, and USAGEsections.

ENVIRONMENT VARIABLES This section lists any environment variables that thecommand or function affects, followed by a briefdescription of the effect.

EXIT STATUS This section lists the values the command returns to thecalling program or shell and the conditions that cause thesevalues to be returned. Usually, zero is returned forsuccessful completion, and values other than zero forvarious error conditions.

FILES This section lists all file names referred to by the man page,files of interest, and files created or required by commands.Each is followed by a descriptive summary or explanation.

ATTRIBUTES This section lists characteristics of commands, utilities,and device drivers by defining the attribute type and itscorresponding value. See attributes(5) for moreinformation.

SEE ALSO This section lists references to other man pages, in-housedocumentation, and outside publications.

DIAGNOSTICS This section lists diagnostic messages with a briefexplanation of the condition causing the error.

WARNINGS This section lists warnings about special conditions whichcould seriously affect your working conditions. This is nota list of diagnostics.

NOTES This section lists additional information that does notbelong anywhere else on the page. It takes the form of anaside to the user, covering points of special interest.Critical information is never covered here.

BUGS This section describes known bugs and, wherever possible,suggests workarounds.

Preface


http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5

Introduction

R E F E R E N C E

11

Intro – introduction to kernel data structures and properties

Section 9P describes kernel properties used by device drivers. Section 9S describes the datastructures used by drivers to share information between the driver and the kernel. SeeIntro(9E) for an overview of device driver interfaces.

In Section 9S, reference pages contain the following headings:■ NAME summarizes the purpose of the structure or property.■ SYNOPSIS lists the include file that defines the structure or property.■ INTERFACE LEVEL describes any architecture dependencies.■ DESCRIPTION provides general information about the structure or property.■ STRUCTURE MEMBERS lists all accessible structure members (for Section 9S).■ SEE ALSO gives sources for further information.

Of the preceding headings, Section 9P reference pages contain the NAME, DESCRIPTION, andSEE ALSO fields.

Every driver MUST include and , in that order, and as finalentries.

The following table summarizes the STREAMS structures described in Section 9S.

Structure Type

copyreq DDI/DKI

copyresp DDI/DKI

datab DDI/DKI

fmodsw Solaris DDI

free_rtn DDI/DKI

iocblk DDI/DKI

linkblk DDI/DKI

module_info DDI/DKI

msgb DDI/DKI

qband DDI/DKI

qinit DDI/DKI

queclass Solaris DDI

queue DDI/DKI

streamtab DDI/DKI

Name

Description

Intro(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 15 May 200112

http://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=intro-9e

Structure Type

stroptions DDI/DKI

The following table summarizes structures that are not specific to STREAMS I/O.

Structure Type

aio_req Solaris DDI

buf DDI/DKI

cb_ops Solaris DDI

ddi_device_acc_attr Solaris DDI

ddi_dma_attr Solaris DDI

ddi_dma_cookie Solaris DDI

ddi_dma_lim_sparc Solaris SPARC DDI

ddi_dma_lim_x86 Solaris x86 DDI

ddi_dma_req Solaris DDI

ddi_dmae_req Solaris x86 DDI

ddi_idevice_cookie Solaris DDI

ddi_mapdev_ctl Solaris DDI

devmap_callback_ctl Solaris DDI

dev_ops Solaris DDI

iovec DDI/DKI

kstat Solaris DDI

kstat_intr Solaris DDI

kstat_io Solaris DDI

kstat_named Solaris DDI

map DDI/DKI

modldrv Solaris DDI

modlinkage Solaris DDI

modlstrmod Solaris DDI

scsi_address Solaris DDI

Intro(9S)

Introduction 13

Structure Type

scsi_arq_status Solaris DDI

scsi_device Solaris DDI

scsi_extended_sense Solaris DDI

scsi_hba_tran Solaris DDI

scsi_inquiry Solaris DDI

scsi_pkt Solaris DDI

scsi_status Solaris DDI

uio DDI/DKI

Intro(9E)

Do not declare arrays of structures as the size of the structures can change between releases.Rely only on the structure members listed in this chapter and not on unlisted members or theposition of a member in a structure.

See Also

Notes

Intro(9S)


http://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=intro-9e

Data Structures for Drivers

R E F E R E N C E

15

aio_req – asynchronous I/O request structure

#include

#include

#include

#include

Solaris DDI specific (Solaris DDI)

An aio_req structure describes an asynchronous I/O request.

struct uio*aio_uio; /* uio structure describing the I/O request */

The aio_uio member is a pointer to a uio(9S) structure, describing the I/O transfer request.

aread(9E), awrite(9E), aphysio(9F), uio(9S)

Name

Synopsis

Interface Level

Description

StructureMembers

See Also

aio_req(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 28 Mar 199716

http://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=aread-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=awrite-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=aphysio-9f

audio_engine_ops – audio engine operations vector

#include


An audio_engine_ops structure defines vectors that an audio driver exports to the Sun audioframework.

One such vector is used for each DMA or PIO engine (sometimes referred to as a “stream”)supported on the device.

The audio framework provides the following synchronization guarantees for audio engines:

■ only one thread will be executing an audio engine entry point for a given audio device atany one time

■ no threads will be executing any audio engine entry points for a given audio device if thatdevice is suspended. See audio_dev_suspend(9F).

Each entry point receives as its first argument the driver private state that was registered withaudio_engine_set_private(9F).

int audio_engine_version; /* version number */

int (*audio_engine_open)(); /* open engine */

void (*audio_engine_close)(); /* close engine */

int (*audio_engine_start)(); /* start engine */

void (*audio_engine_stop)(); /* stop engine */

uint64_t (*audio_engine_count)(); /* get frame count */

int (*audio_engine_format)(); /* get format */

int (*audio_engine_channels)(); /* get num channels */

int (*audio_engine_rate)(); /* get sample rate */

void (*audio_engine_sync)(); /* dma cache sync */

uint_t (*audio_engine_qlen)(); /* get hw fifo len */

void (*audio_engine_chinfo)(); /* channel cfg info */

uint_t (*audio_engine_playahead)(); /* play ahead frames */

audio_engine_version The version of the engine interface. Drivers must supplyAUDIO_ENGINE_VERSION.

audio_engine_open Function entry that opens the engine and initializes hardwareand resources.

audio_engine_close Function entry that closes the engine and possibly releases anyresources.

audio_engine_start Function entry to start audio data transfer.

audio_engine_stop Function entry to stop audio data transfer.

audio_engine_count Function entry to return engine's frame count.

audio_engine_format Function entry to get the format of the engine.

Name

Synopsis

Interface Level

Description

StructureMembers

audio_engine_ops(9S)

Data Structures for Drivers 17

http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=audio-dev-suspend-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=audio-engine-set-private-9f

audio_engine_channels Function entry to get the number of channels of the engine.

audio_engine_rate Function entry to get the sample rate of the engine.

audio_engine_sync Function entry to synchronize the DMA cache for the bufferassociated with the engine.

audio_engine_qlen Function entry to determine the on-device FIFO len for theengine.

audio_engine_chinfo Function entry to determine number and layout channels fordevice.

audio_engine_playahead Function entry to determine minimum number of frames thatshould be queued to the engine.

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

attributes(5), audio(7D), audio_engine_channels(9E), audio_engine_chinfo(9E),audio_engine_count(9E), audio_engine_format(9E), audio_engine_open(9E),audio_engine_playahead(9E), audio_engine_qlen(9E), audio_engine_rate(9E),audio_engine_start(9E), audio_engine_sync(9E), audio_dev_add_engine(9F),audio_dev_suspend(9F), audio_engine_alloc(9F), audio_engine_set_private(9F)

Attributes

See Also

audio_engine_ops(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 21 Apr 201018

http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1475&id=audio-7dhttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-channels-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-chinfo-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-count-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-format-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-open-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-playahead-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-qlen-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-rate-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-start-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=audio-engine-sync-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=audio-dev-add-engine-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=audio-dev-suspend-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=audio-engine-alloc-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=audio-engine-set-private-9f

buf – block I/O data transfer structure

#include

#include

Architecture independent level 1 (DDI/DKI)

The buf structure is the basic data structure for block I/O transfers. Each block I/O transferhas an associated buffer header. The header contains all the buffer control and statusinformation. For drivers, the buffer header pointer is the sole argument to a block driverstrategy(9E) routine. Do not depend on the size of the buf structure when writing a driver.

A buffer header can be linked in multiple lists simultaneously. Because of this, most of themembers in the buffer header cannot be changed by the driver, even when the buffer header isin one of the driver's work lists.

Buffer headers are also used by the system for unbuffered or physical I/O for block drivers. Inthis case, the buffer describes a portion of user data space that is locked into memory.

Block drivers often chain block requests so that overall throughput for the device ismaximized. The av_forw and the av_back members of the buf structure can serve as linkpointers for chaining block requests.

int b_flags; /* Buffer status */

struct buf *av_forw; /* Driver work list link */

struct buf *av_back; /* Driver work list link */

size_t b_bcount; /* # of bytes to transfer */

union {

caddr_t b_addr; /* Buffer’s virtual address */

} b_un;

daddr_t b_blkno; /* Block number on device */

diskaddr_t b_lblkno; /* Expanded block number on dev. */

size_t b_resid; /* # of bytes not xferred */

size_t b_bufsize; /* size of alloc. buffer */

int (*b_iodone)(struct buf *); /* function called */

/* by biodone */

int b_error; /* expanded error field */

void *b_private; /* "opaque" driver private area */dev_t b_edev; /* expanded dev field */

The members of the buffer header available to test or set by a driver are as follows:

b_flags stores the buffer status and indicates to the driver whether to read or write to thedevice. The driver must never clear the b_flags member. If this is done, unpredictable resultscan occur including loss of disk sanity and the possible failure of other kernel processes.

All b_flags bit values not otherwise specified above are reserved by the kernel and may not beused.

Valid flags are as follows:

Name

Synopsis

Interface Level

Description

StructureMembers

buf(9S)


http://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=strategy-9e

B_BUSY Indicates the buffer is in use. The driver must not change this flag unless itallocated the buffer with getrbuf(9F) and no I/O operation is in progress.

B_DONE Indicates the data transfer has completed. This flag is read-only.

B_ERROR Indicates an I/O transfer error. It is set in conjunction with the b_error field.bioerror(9F) should be used in preference to setting the B_ERROR bit.

B_PAGEIO Indicates the buffer is being used in a paged I/O request. See the description ofthe b_un.b_addr field for more information. This flag is read-only.

B_PHYS indicates the buffer header is being used for physical (direct) I/O to a user dataarea. See the description of the b_un.b_addr field for more information. Thisflag is read-only.

B_READ Indicates that data is to be read from the peripheral device into main memory.

B_WRITE Indicates that the data is to be transferred from main memory to the peripheraldevice. B_WRITE is a pseudo flag and cannot be directly tested; it is only detectedas the NOT form of B_READ.

av_forw and av_back can be used by the driver to link the buffer into driver work lists.

b_bcount specifies the number of bytes to be transferred in both a paged and a non-paged I/Orequest.

b_un.b_addr is the virtual address of the I/O request, unless B_PAGEIO is set. The address is akernel virtual address, unless B_PHYS is set, in which case it is a user virtual address. IfB_PAGEIO is set, b_un.b_addr contains kernel private data. Note that either one of B_PHYS andB_PAGEIO, or neither, can be set, but not both.

b_blkno identifies which logical block on the device (the device is defined by the devicenumber) is to be accessed. The driver might have to convert this logical block number to aphysical location such as a cylinder, track, and sector of a disk. This is a 32-bit value. Thedriver should use b_blkno or b_lblkno, but not both.

b_lblkno identifies which logical block on the device (the device is defined by the devicenumber) is to be accessed. The driver might have to convert this logical block number to aphysical location such as a cylinder, track, and sector of a disk. This is a 64-bit value. Thedriver should use b_lblkno or b_blkno, but not both.

b_resid should be set to the number of bytes not transferred because of an error.

b_bufsize contains the size of the allocated buffer.

b_iodone identifies a specific biodone routine to be called by the driver when the I/O iscomplete.

buf(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 19 Sep 200220

http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=getrbuf-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=bioerror-9f

b_error can hold an error code that should be passed as a return code from the driver.b_error is set in conjunction with the B_ERROR bit set in the b_flags member. bioerror(9F)should be used in preference to setting the b_error field.

b_private is for the private use of the device driver.

b_edev contains the major and minor device numbers of the device accessed.

strategy(9E), aphysio(9F), bioclone(9F), biodone(9F), bioerror(9F), bioinit(9F),clrbuf(9F), getrbuf(9F), physio(9F), iovec(9S), uio(9S)

Writing Device Drivers

Buffers are a shared resource within the kernel. Drivers should read or write only the memberslisted in this section. Drivers that attempt to use undocumented members of the buf structurerisk corrupting data in the kernel or on the device.

See Also

Warnings

buf(9S)


http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=bioerror-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=strategy-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=aphysio-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=bioclone-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=biodone-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=bioerror-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=bioinit-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=clrbuf-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=getrbuf-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=physio-9fhttp://www.oracle.com/pls/topic/lookup?ctx=819-3196&id=driver

cb_ops – character/block entry points structure

#include

#include

#include


The cb_ops structure contains all entry points for drivers that support both character andblock entry points. All leaf device drivers that support direct user process access to a deviceshould declare a cb_ops structure.

All drivers that safely allow multiple threads of execution in the driver at the same time mustset the D_MP flag in the cb_flag field. See open(9E).

If the driver properly handles 64-bit offsets, it should also set the D_64BIT flag in the cb_flagfield. This specifies that the driver will use the uio_loffset field of the uio(9S) structure.

If the driver returns EINTR from open(9E), it should also set the D_OPEN_RETURNS_EINTR flag inthe cb_flag field. This lets the framework know that it is safe for the driver to return EINTRwhen waiting, to provide exclusion for a last-reference close(9E) call to complete beforecalling open(9E).

The mt-streams(9F) function describes other flags that can be set in the cb_flag field.

The cb_rev is the cb_ops structure revision number. This field must be set to CB_REV.

Non-STREAMS drivers should set cb_str to NULL.

The following DDI/DKI or DKI-only or DDI-only functions are provided in thecharacter/block driver operations structure.

block/char Function Description

b/c XXopen DDI/DKI

b/c XXclose DDI/DKI

b XXstrategy DDI/DKI

b XXprint DDI/DKI

b XXdump DDI(Sun)

c XXread DDI/DKI

c XXwrite DDI/DKI

c XXioctl DDI/DKI

Name

Synopsis

Interface Level

Description

cb_ops(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 24 Apr 200822

http://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=open-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=open-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=close-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=open-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=mt-streams-9f

block/char Function Description

c XXdevmap DDI(Sun)

c XXmmap DKI

c XXsegmap DKI

c XXchpoll DDI/DKI

c XXprop_op DDI(Sun)

c XXaread DDI(Sun)

c XXawrite DDI(Sun)

int (*cb_open)(dev_t *devp, int flag, int otyp, cred_t *credp);

int (*cb_close)(dev_t dev, int flag, int otyp, cred_t *credp);

int (*cb_strategy)(struct buf *bp);

int (*cb_print)(dev_t dev, char *str);

int (*cb_dump)(dev_t dev, caddr_t addr, daddr_t blkno, int nblk);

int (*cb_read)(dev_t dev, struct uio *uiop, cred_t *credp);

int (*cb_write)(dev_t dev, struct uio *uiop, cred_t *credp);

int (*cb_ioctl)(dev_t dev, int cmd, intptr_t arg, int mode,

cred_t *credp, int *rvalp);

int (*cb_devmap)(dev_t dev, devmap_cookie_t dhp, offset_t off,

size_t len, size_t *maplen, uint_t model);

int (*cb_mmap)(dev_t dev, off_t off, int prot);

int (*cb_segmap)(dev_t dev, off_t off, struct as *asp,

caddr_t *addrp, off_t len, unsigned int prot,

unsigned int maxprot, unsigned int flags, cred_t *credp);

int (*cb_chpoll)(dev_t dev, short events, int anyyet,

short *reventsp, struct pollhead **phpp);

int (*cb_prop_op)(dev_t dev, dev_info_t *dip,

ddi_prop_op_t prop_op, int mod_flags,

char *name, caddr_t valuep, int *length);

struct streamtab *cb_str; /* streams information */

int cb_flag;

int cb_rev;

int (*cb_aread)(dev_t dev, struct aio_req *aio, cred_t *credp);

int (*cb_awrite)(dev_t dev, struct aio_req *aio, cred_t *credp);

aread(9E), awrite(9E), chpoll(9E), close(9E), dump(9E), ioctl(9E), mmap(9E), open(9E),print(9E), prop_op(9E), read(9E), segmap(9E), strategy(9E), write(9E), nochpoll(9F),nodev(9F), nulldev(9F), dev_ops(9S), qinit(9S)


STREAMS Programming Guide

StructureMembers

See Also

cb_ops(9S)


http://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=aread-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=awrite-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=chpoll-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=close-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=dump-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=ioctl-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=mmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=open-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=print-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=prop-op-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=read-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=segmap-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=strategy-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1476&id=write-9ehttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=nochpoll-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=nodev-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=nulldev-9fhttp://www.oracle.com/pls/topic/lookup?ctx=819-3196&id=driverhttp://www.oracle.com/pls/topic/lookup?ctx=816-4855&id=streams

copyreq – STREAMS data structure for the M_COPYIN and the M_COPYOUT messagetypes

#include


The data structure for the M_COPYIN and the M_COPYOUT message types.

int cq_cmd; /* ioctl command (from ioc_cmd) */

cred_t *cq_cr; /* full credentials */

uint_t cq_id; /* ioctl id (from ioc_id) */

uint_t cq_flag; /* must be zero */

mblk_t *cq_private; /* private state information */

caddr_t cq_addr; /* address to copy data to/from */

size_t cq_size; /* number of bytes to copy */


Name

Synopsis

Interface Level

Description

StructureMembers

See Also

copyreq(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 6 October 200024

http://www.oracle.com/pls/topic/lookup?ctx=816-4855&id=streams

copyresp – STREAMS data structure for the M_IOCDATA message type

#include


The data structure copyresp is used with the M_IOCDATA message type.

int cp_cmd; /* ioctl command (from ioc_cmd) */

cred_t *cp_cr; /* full credentials */

uint_t cp_id; /* ioctl id (from ioc_id) */

uint_t cp_flag; /* ioctl flags */

mblk_t *cp_private; /* private state information */

caddr_t cp_rval; /* status of request: 0 -> success;

/* non-zero -> failure */


Name

Synopsis

Interface Level

Description

StructureMembers

See Also

copyresp(9S)


http://www.oracle.com/pls/topic/lookup?ctx=816-4855&id=streams

datab, dblk – STREAMS message data structure

#include

Architecture independent level 1 (DDI/DKI).

The datab structure describes the data of a STREAMS message. The actual data contained in aSTREAMS message is stored in a data buffer pointed to by this structure. A msgb (messageblock) structure includes a field that points to a datab structure.

Because a data block can have more than one message block pointing to it at one time, thedb_ref member keeps track of a data block's references, preventing it from being deallocateduntil all message blocks are finished with it.

unsigned char *db_base; /* first byte of buffer */

unsigned char *db_lim; /* last byte (+1) of buffer */

unsigned char db_ref; /* # of message pointers to this data */

unsigned char db_type; /* message type */

A datab structure is defined as type dblk_t.

free_rtn(9S), msgb(9S)



Name

Synopsis

Interface Level

Description

StructureMembers

See Also

datab(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 24 Oct 200326

http://www.oracle.com/pls/topic/lookup?ctx=819-3196&id=driverhttp://www.oracle.com/pls/topic/lookup?ctx=816-4855&id=streams

ddi_device_acc_attr – data access attributes structure

#include

#include


The ddi_device_acc_attr structure describes the data access characteristics andrequirements of the device.

ushort_t devacc_attr_version;

uchar_t devacc_attr_endian_flags;

uchar_t devacc_attr_dataorder;

uchar_t devacc_attr_access;

The devacc_attr_version member identifies the version number of this structure. Thecurrent version number is DDI_DEVICE_ATTR_V0.

The devacc_attr_endian_flags member describes the endian characteristics of the device.Specify one of the following values:

DDI_NEVERSWAP_ACC Data access with no byte swapping

DDI_STRUCTURE_BE_ACC Structural data access in big-endian format

DDI_STRUCTURE_LE_ACC Structural data access in little endian format

DDI_STRUCTURE_BE_ACC and DDI_STRUCTURE_LE_ACC describe the endian characteristics ofthe device as big-endian or little-endian, respectively. Although most of the devices have thesame endian characteristics as their buses, examples of devices that have opposite endiancharacteristics of the buses do exist. When DDI_STRUCTURE_BE_ACC orDDI_STRUCTURE_LE_ACC is set, byte swapping is automatically performed by the system if thehost machine and the device data formats have opposite endian characteristics. Theimplementation can take advantage of hardware platform byte swapping capabilities.

When you specify DDI_NEVERSWAP_ACC, byte swapping is not invoked in the data accessfunctions.

The devacc_attr_dataorder member describes the order in which the CPU references data.Specify one of the following values.

DDI_STRICTORDER_ACC Data references must be issued by a CPU in program order.Strict ordering is the default behavior.

DDI_UNORDERED_OK_ACC The CPU can reorder the data references. This includes allkinds of reordering. For example, a load followed by a storemight be replaced by a store followed by a load.

DDI_MERGING_OK_ACC The CPU can merge individual stores to consecutivelocations. For example, the CPU can turn two consecutivebyte stores into one half-word store. It can also batch

Name

Synopsis

Interface Level

Description

StructureMembers

ddi_device_acc_attr(9S)


individual loads. For example, the CPU might turn twoconsecutive byte loads into one half-word load.DDI_MERGING_OK_ACC also implies reordering.

DDI_LOADCACHING_OK_ACC The CPU can cache the data it fetches and reuse it untilanother store occurs. The default behavior is to fetch newdata on every load. DDI_LOADCACHING_OK_ACC also impliesmerging and reordering.

DDI_STORECACHING_OK_ACC The CPU can keep the data in the cache and push it to thedevice, perhaps with other data, at a later time. The defaultbehavior is to push the data right away.DDI_STORECACHING_OK_ACC also implies load caching,merging, and reordering.

These values are advisory, not mandatory. For example, data can be ordered without beingmerged, or cached, even though a driver requests unordered, merged, and cached together.

The values defined for devacc_attr_access are:

DDI_DEFAULT_ACC If an I/O fault occurs, the system will take the default action, whichmight be to panic.

DDI_FLAGERR_ACC Using this value indicates that the driver is hardened: able to copewith the incorrect results of I/O operations that might result from anI/O fault. The value also indicates that the driver will useddi_fm_acc_err_get(9F) to check access handles for faults on aregular basis.

If possible, the system should not panic on such an I/O fault, butshould instead mark the I/O handle through which the access wasmade as having faulted.

This value is advisory: it tells the system that the driver can continuein the face of I/O faults. The value does not guarantee that the systemwill not panic, as that depends on the nature of the fault and thecapabilities of the system. It is quite legitimate for an implementationto ignore this flag and panic anyway.

DDI_CAUTIOUS_ACC This value indicates that an I/O fault is anticipated and should behandled as gracefully as possible. For example, the framework shouldnot print a console message.

This value should be used when it is not certain that a device isphysically present: for example, when probing. As such, it provides analternative within the DDI access framework to the existing peek/poke



http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-fm-acc-err-get-9f

functions, which don't use access handles and cannot be integratedeasily into a more general I/O fault handling framework.

In order to guarantee safe recovery from an I/O fault, it might benecessary to acquire exclusive access to the parent bus, for example, orto synchronize across processors on an MP machine. “Cautious”access can be quite expensive and is only recommended for initialprobing and possibly for additional fault-recovery code.

The following examples illustrate the use of device register address mapping setup functionsand different data access functions.

EXAMPLE 1 Using ddi_device_acc_attr() in >ddi_regs_map_setup(9F)

This example demonstrates the use of the ddi_device_acc_attr() structure inddi_regs_map_setup(9F). It also shows the use of ddi_getw(9F) and ddi_putw(9F) functionsin accessing the register contents.

dev_info_t *dip;

uint_t rnumber;

ushort_t *dev_addr;

offset_t offset;

offset_t len;

ushort_t dev_command;

ddi_device_acc_attr_t dev_attr;

ddi_acc_handle_t handle;

. . .

/*

* setup the device attribute structure for little endian,

* strict ordering and 16-bit word access.

*/

dev_attr.devacc_attr_version = DDI_DEVICE_ATTR_V0;

dev_attr.devacc_attr_endian_flags = DDI_STRUCTURE_LE_ACC;

dev_attr.devacc_attr_dataorder = DDI_STRICTORDER_ACC;

/*

* set up the device registers address mapping

*/

ddi_regs_map_setup(dip, rnumber, (caddr_t *)&dev_addr, offset, len,

&dev_attr, &handle);

/* read a 16-bit word command register from the device */

dev_command = ddi_getw(handle, dev_addr);

dev_command |= DEV_INTR_ENABLE;

/* store a new value back to the device command register */

Examples



http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-regs-map-setup-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-getw-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-putw-9f

EXAMPLE 1 Using ddi_device_acc_attr() in >ddi_regs_map_setup(9F) (Continued)

ddi_putw(handle, dev_addr, dev_command);

EXAMPLE 2 Accessing a Device with Different Apertures

The following example illustrates the steps used to access a device with different apertures.Several apertures are assumed to be grouped under one single “reg” entry. For example, thesample device has four different apertures, each 32 Kbyte in size. The apertures represent YUVlittle-endian, YUV big-endian, RGB little-endian, and RGB big-endian. This sample deviceuses entry 1 of the “reg” property list for this purpose. The size of the address space is 128Kbyte with each 32 Kbyte range as a separate aperture. In the register mapping setup function,the sample driver uses the offset and len parameters to specify one of the apertures.

ulong_t *dev_addr;



uchar_t buf[256];

. . .

/*

* setup the device attribute structure for never swap,

* unordered and 32-bit word access.

*/


dev_attr.devacc_attr_endian_flags = DDI_NEVERSWAP_ACC;

dev_attr.devacc_attr_dataorder = DDI_UNORDERED_OK_ACC;

/*

* map in the RGB big-endian aperture

* while running in a big endian machine

* - offset 96K and len 32K

*/

ddi_regs_map_setup(dip, 1, (caddr_t *)&dev_addr, 96*1024, 32*1024,


/*

* Write to the screen buffer

* first 1K bytes words, each size 4 bytes

*/

ddi_rep_putl(handle, buf, dev_addr, 256, DDI_DEV_AUTOINCR);

EXAMPLE 3 Functions That Call Out the Data Word Size

The following example illustrates the use of the functions that explicitly call out the data wordsize to override the data size in the device attribute structure.



EXAMPLE 3 Functions That Call Out the Data Word Size (Continued)

struct device_blk {

ushort_t d_command; /* command register */

ushort_t d_status; /* status register */

ulong d_data; /* data register */

} *dev_blkp;

dev_info_t *dip;

caddr_t dev_addr;



uchar_t buf[256];

. . .

/*

* setup the device attribute structure for never swap,

* strict ordering and 32-bit word access.

*/


dev_attr.devacc_attr_endian_flags = DDI_NEVERSWAP_ACC;

dev_attr.devacc_attr_dataorder= DDI_STRICTORDER_ACC;

ddi_regs_map_setup(dip, 1, (caddr_t *)&dev_blkp, 0, 0,


/* write command to the 16-bit command register */

ddi_putw(handle, &dev_blkp->d_command, START_XFER);

/* Read the 16-bit status register */

status = ddi_getw(handle, &dev_blkp->d_status);

if (status & DATA_READY)

/* Read 1K bytes off the 32-bit data register */

ddi_rep_getl(handle, buf, &dev_blkp->d_data,

256, DDI_DEV_NO_AUTOINCR);




attributes(5), ddi_fm_acc_err_get(9F), ddi_getw(9F), ddi_putw(9F),ddi_regs_map_setup(9F)


Attributes

See Also



http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-fm-acc-err-get-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-getw-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-putw-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-regs-map-setup-9fhttp://www.oracle.com/pls/topic/lookup?ctx=819-3196&id=driver

ddi_dma_attr – DMA attributes structure

#include


A ddi_dma_attr_t structure describes device– and DMA engine-specific attributes necessaryto allocate DMA resources for a device. The driver might have to extend the attributes withbus-specific information, depending on the bus to which the device is connected.

uint_t dma_attr_version; /* version number */

uint64_t dma_attr_addr_lo; /* low DMA address range */

uint64_t dma_attr_addr_hi; /* high DMA address range */

uint64_t dma_attr_count_max; /* DMA counter register */

uint64_t dma_attr_align; /* DMA address alignment */

uint_t dma_attr_burstsizes; /* DMA burstsizes */

uint32_t dma_attr_minxfer; /* min effective DMA size */

uint64_t dma_attr_maxxfer; /* max DMA xfer size */

uint64_t dma_attr_seg; /* segment boundary */

int dma_attr_sgllen; /* s/g list length */

uint32_t dma_attr_granular; /* granularity of device */

uint_t dma_attr_flags; /* DMA transfer flags */

The dma_attr_version stores the version number of this DMA attribute structure. It shouldbe set to DMA_ATTR_V0.

The dma_attr_addr_lo and dma_attr_addr_hi fields specify the address range the device'sDMA engine can access. The dma_attr_addr_lo field describes the inclusive lower 64–bitboundary. The dma_attr_addr_hi describes the inclusive upper 64–bit boundary. The systemensures that allocated DMA resources are within the range specified. Seeddi_dma_cookie(9S).

The dma_attr_count_max describes an inclusive upper bound for the device's DMA counterregister. For example, 0xFFFFFF would describe a DMA engine with a 24–bit counter register.DMA resource allocation functions have to break up a DMA object into multiple DMAcookies if the size of the object exceeds the size of the DMA counter register.

The dma_attr_align specifies alignment requirements for allocated DMA resources. Thisfield can be used to force more restrictive alignment than imposed by dma_attr_burstsizesor dma_attr_minxfer, such as alignment at a page boundary. Most drivers set this field to 1,indicating byte alignment.

The dma_attr_align only specifies alignment requirements for allocated DMA resources.The buffer passed to ddi_dma_addr_bind_handle(9F) or ddi_dma_buf_bind_handle(9F)must have an equally restrictive alignment (see ddi_dma_mem_alloc(9F)).

The dma_attr_burstsizes field describes the possible burst sizes the DMA engine of a devicecan accept. The format of the data sizes is binary, encoded in terms of powers of two. When

Name

Synopsis

Interface Level

Description

StructureMembers

ddi_dma_attr(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 12 Feb 200932

http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-addr-bind-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-buf-bind-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-mem-alloc-9f

DMA resources are allocated, the system can modify the burstsizes value to reflect thesystem limits. The driver must use the allowable burstsizes to program the DMA engine. Seeddi_dma_burstsizes(9F).

The dma_attr_minxfer field describes the minimum effective DMA access size in units ofbytes. DMA resources can be modified, depending on the presence and use of I/O caches andwrite buffers between the DMA engine and the memory object. This field is used to determinealignment and padding requirements for ddi_dma_mem_alloc(9F).

The dma_attr_maxxfer field describes the maximum effective DMA access size in units ofbytes.

The dma_attr_seg field specifies segment boundary restrictions for allocated DMA resources.The system allocates DMA resources for the device so that the object does not span thesegment boundary specified by dma_attr_seg. For example, a value of 0xFFFF means DMAresources must not cross a 64–Kbyte boundary. DMA resource allocation functions mighthave to break up a DMA object into multiple DMA cookies to enforce segment boundaryrestrictions. In this case, the transfer must be performed using scatter-gather I/O or multipleDMA windows.

The dma_attr_sgllen field describes the length of the DMA scatter/gather list of a device.Possible values are as follows:

< 0 Device DMA engine is not constrained by the size, for example, withDMA chaining.

= 0 Reserved.

= 1 Device DMA engine does not support scatter/gather such as third party DMA.

> 1 Device DMA engine uses scatter/gather. The dma_attr_sgllen value is the maximumnumber of entries in the list.

The dma_attr_granular field describes the granularity of the device transfer size in units ofbytes. When the system allocates DMA resources, the size of a single segment is a multiple ofthe device granularity. If dma_attr_sgllen is larger than 1 within a window, the sum of thesizes for a subgroup of segments is a multiple of the device granularity.

All driver requests for DMA resources must be a multiple of the granularity of the devicetransfer size.

The dma_attr_flags field can be set to a combination of:

DDI_DMA_FORCE_PHYSICAL

Some platforms, such as SPARC systems, support what is called Direct Virtual MemoryAccess (DVMA). On these platforms, the device is provided with a virtual address by thesystem in order to perform the transfer. In this case, the underlying platform provides anIOMMU, which translates accesses to these virtual addresses into the proper physicaladdresses. Some of these platforms also support DMA. DDI_DMA_FORCE_PHYSICALindicates that the system should return physical rather than virtual I/O addresses if the

ddi_dma_attr(9S)


http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-burstsizes-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-mem-alloc-9f

system supports both. If the system does not support physical DMA, the return value fromddi_dma_alloc_handle(9F) is DDI_DMA_BADATTR. In this case, the driver has to clearDDI_DMA_FORCE_PHYSICAL and retry the operation.

DDI_DMA_FLAGERR

Using this value indicates that the driver is hardened: able to cope with the incorrect resultsof DMA operations that might result from an I/O fault. The value also indicates that thedriver will use ddi_fm_dma_err_get(9F) to check DMA handles for faults on a regularbasis.

If a DMA error is detected during a DMA access to an area mapped by such a handle, thesystem should not panic if possible, but should instead mark the DMA handle as havingfaulted.

This value is advisory: it tells the system that the driver can continue in the face of I/Ofaults. It does not guarantee that the system will not panic, as that depends on the nature ofthe fault and the capabilities of the system. It is quite legitimate for an implementation toignore this flag and panic anyway.

DDI_DMA_RELAXED_ORDERING

This optional flag can be set if the DMA transactions associated with this handle are notrequired to observe strong DMA write ordering among themselves, nor with DMA writetransactions of other handles.

The flag allows the host bridge to transfer data to and from memory more efficiently andmight result in better DMA performance on some platforms.

Drivers for devices with hardware support, such as marking the bus transactions relaxedordered, should not use this flag. Such drivers should use the hardware capability instead.

EXAMPLE 1 Initializing the ddi_dma_attr_t Structure

Assume a device has the following DMA characteristics:

■ Full 32-bit range addressable■ 24-bit DMA counter register■ Byte alignment■ 4– and 8-byte burst sizes support■ Minimum effective transfer size of 1 bytes■ 64 Mbyte minus 1 (26-bit) maximum transfer size limit■ Maximum segment size of 32 Kbyte■ 17 scatter/gather list elements■ 512–byte device transfer size granularity

The corresponding ddi_dma_attr_t structure is initialized as follows:

static ddi_dma_attr_t dma_attrs = {

DMA_ATTR_V0 /* version number */

(uint64_t)0x0, /* low address */

Examples

ddi_dma_attr(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 12 Feb 200934

http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-alloc-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-fm-dma-err-get-9f

EXAMPLE 1 Initializing the ddi_dma_attr_t Structure (Continued)

(uint64_t)0xffffffff, /* high address */

(uint64_t)0xffffff, /* DMA counter max */

(uint64_t)0x1 /* alignment */

0x0c, /* burst sizes */

0x1, /* minimum transfer size */

(uint64_t)0x3ffffff, /* maximum transfer size */

(uint64_t)0x7fff, /* maximum segment size */

17, /* scatter/gather list lgth */

512 /* granularity */

0 /* DMA flags */

};




attributes(5), ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F),ddi_dma_buf_bind_handle(9F), ddi_dma_burstsizes(9F), ddi_dma_mem_alloc(9F),ddi_dma_nextcookie(9F), ddi_fm_dma_err_get(9F), ddi_dma_cookie(9S)


Attributes

See Also

ddi_dma_attr(9S)


http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-addr-bind-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-alloc-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-buf-bind-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-burstsizes-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-mem-alloc-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-nextcookie-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-fm-dma-err-get-9fhttp://www.oracle.com/pls/topic/lookup?ctx=819-3196&id=driver

ddi_dma_cookie – DMA address cookie

#include

Solaris DDI specific (Solaris DDI).

The ddi_dma_cookie_t structure contains DMA address information required to program aDMA engine. The structure is filled in by a call to ddi_dma_getwin(9F),ddi_dma_addr_bind_handle(9F), or ddi_dma_buf_bind_handle(9F), to get device-specificDMA transfer information for a DMA request or a DMA window.

typedef struct {

union {

uint64_t _dmac_ll; /* 64 bit DMA add. */

uint32_t _dmac_la[2]; /* 2 x 32 bit add. */

} _dmu;

size_t dmac_size; /* DMA cookie size */

uint_t dmac_type; /* bus spec. type bits */

} ddi_dma_cookie_t;

You can access the DMA address through the #defines: dmac_address for 32-bit addressesand dmac_laddress for 64-bit addresses. These macros are defined as follows:

#define dmac_laddress _dmu._dmac_ll

#ifdef _LONG_LONG_HTOL

#define dmac_notused _dmu._dmac_la[0]

#define dmac_address _dmu._dmac_la[1]

#else

#define dmac_address _dmu._dmac_la[0]

#define dmac_notused _dmu._dmac_la[1]

#endif

dmac_laddress specifies a 64-bit I/O address appropriate for programming the device's DMAengine. If a device has a 64-bit DMA address register a driver should use this field to programthe DMA engine. dmac_address specifies a 32-bit I/O address. It should be used for devicesthat have a 32-bit DMA address register. The I/O address range that the device can addressand other DMA attributes have to be specified in a ddi_dma_attr(9S) structure.

dmac_size describes the length of the transfer in bytes.

dmac_type contains bus-specific type bits, if appropriate. For example, a device on a PCI bushas PCI address modifier bits placed here.

pci(4), sbus(4), sysbus(4), ddi_dma_addr_bind_handle(9F),ddi_dma_buf_bind_handle(9F), ddi_dma_getwin(9F), ddi_dma_nextcookie(9F),ddi_dma_attr(9S)


Name

Synopsis

Interface Level

Description

StructureMembers

See Also

ddi_dma_cookie(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 30 Sep 199636

http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-getwin-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-addr-bind-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-buf-bind-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1473&id=pci-4http://www.oracle.com/pls/topic/lookup?ctx=821-1473&id=sbus-4http://www.oracle.com/pls/topic/lookup?ctx=821-1473&id=sysbus-4http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-addr-bind-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-buf-bind-handle-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-getwin-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-nextcookie-9fhttp://www.oracle.com/pls/topic/lookup?ctx=819-3196&id=driver

ddi_dmae_req – DMA engine request structure

#include

Solaris x86 DDI specific (Solaris x86 DDI).

A device driver uses the ddi_dmae_req structure to describe the parameters for a DMAchannel. This structure contains all the information necessary to set up the channel, except forthe DMA memory address and transfer count. The defaults, as specified below, support moststandard devices. Other modes might be desirable for some devices, or to increaseperformance. The DMA engine request structure is passed to ddi_dmae_prog(9F).

The ddi_dmae_req structure contains several members, each of which controls some aspect ofDMA engine operation. The structure members associated with supported DMA engineoptions are described here.

uchar_tder_command; /* Read / Write *

/uchar_tder_bufprocess; /* Standard / Chain */

uchar_tder_path; /* 8 / 16 / 32 */

uchar_tder_cycles; /* Compat / Type A / Type B / Burst */

uchar_tder_trans; /* Single / Demand / Block */

ddi_dma_cookie_t*(*proc)(); /* address of nextcookie routine */

void*procparms; /* parameter for nextcookie call */

der_command Specifies what DMA operation is to be performed. The valueDMAE_CMD_WRITE signifies that data is to be transferred from memory tothe I/O device. The value DMAE_CMD_READ signifies that data is to betransferred from the I/O device to memory. This field must be set by thedriver before calling ddi_dmae_prog().

der_bufprocess On some bus types, a driver can set der_bufprocess to the valueDMAE_BUF_CHAIN to specify that multiple DMA cookies will be given tothe DMA engine for a single I/O transfer. This action causes ascatter/gather operation. In this mode of operation, the driver callsddi_dmae_prog() to give the DMA engine the DMA engine requeststructure and a pointer to the first cookie. The proc structure membermust be set to the address of a driver nextcookie routine. This routinetakes one argument, specified by the procparms structure member, andreturns a pointer to a structure of type ddi_dma_cookie_t that specifiesthe next cookie for the I/O transfer. When the DMA engine is ready toreceive an additional cookie, the bus nexus driver controlling that DMAengine calls the routine specified by the proc structure member to obtainthe next cookie from the driver. The driver's nextcookie routine mustthen return the address of the next cookie (in static storage) to the busnexus routine that called it. If there are no more segments in the currentDMA window, then (*proc)() must return the NULL pointer.

Name

Synopsis

Interface Level

Description

StructureMembers

ddi_dmae_req(9S)


http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dmae-prog-9f

A driver can specify the DMAE_BUF_CHAIN flag only if the particular busarchitecture supports the use of multiple DMA cookies in a single I/Otransfer. A bus DMA engine can support this feature either with afixed-length scatter/gather list, or by an interrupt chaining feature. Adriver must determine whether its parent bus nexus supports thisfeature by examining the scatter/gather list size returned in thedlim_sgllen member of the DMA limit structure returned by thedriver's call to ddi_dmae_getlim(). (See ddi_dma_lim_x86(9S).) If thesize of the scatter/gather list is 1, then no chaining is available. The drivermust not specify the DMAE_BUF_CHAIN flag in the ddi_dmae_reqstructure it passes to ddi_dmae_prog(), and the driver need not providea nextcookie routine.

If the size of the scatter/gather list is greater than 1, then DMA chainingis available, and the driver has two options. Under the first option, thedriver chooses not to use the chaining feature. In this case (a) the drivermust set the size of the scatter/gather list to 1 before passing it to theDMA setup routine, and (b) the driver must not set the DMAE_BUF_CHAINflag.

Under the second option, the driver chooses to use the chaining feature,in which case, (a) it should leave the size of the scatter/gather list alone,and (b) it must set the DMAE_BUF_CHAIN flag in the ddi_dmae_reqstructure. Before calling ddi_dmae_prog(), the driver must prefetchcookies by repeatedly calling ddi_dma_nextseg(9F) andddi_dma_segtocookie(9F) until either (1) the end of the DMA windowis reached (ddi_dma_nextseg(9F) returns NULL), or (2) the size of thescatter/gather list is reached, whichever occurs first. These cookies mustbe saved by the driver until they are requested by the nexus driver callingthe driver's nextcookie routine. The driver's nextcookie routine mustreturn the prefetched cookies in order, one cookie for each call to thenextcookie routine, until the list of prefetched cookies is exhausted.After the end of the list of cookies is reached, the nextcookie routinemust return the NULL pointer.

The size of the scatter/gather list determines how many discontiguoussegments of physical memory can participate in a single DMA transfer.ISA bus DMA engines have no scatter/gather capability, so theirscatter/gather list sizes are 1. Other finite scatter/gather list sizes wouldalso be possible. For performance reasons, drivers should use thechaining capability if it is available on their parent bus.

As described above, a driver making use of DMA chaining must prefetchDMA cookies before calling ddi_dmae_prog(). The reasons for this are:

ddi_dmae_req(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 18 Nov 200438

http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-nextseg-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-segtocookie-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-nextseg-9f

■ First, the driver must have some way to know the total I/O countwith which to program the I/O device. This I/O count must matchthe total size of all the DMA segments that will be chained togetherinto one DMA operation. Depending on the size of the scatter/gatherlist and the memory position and alignment of the DMA object, allor just part of the current DMA window might be able to participatein a single I/O operation. The driver must compute the I/O count byadding up the sizes of the prefetched DMA cookies. The number ofcookies whose sizes are to be summed is the lesser of (a) the size ofthe scatter/gather list, or (b) the number of segments remaining inthe window.

■ Second, on some bus architectures, the driver's nextcookie routinecan be called from a high-level interrupt routine. If the cookies werenot prefetched, the nextcookie routine would have to callddi_dma_nextseg() and ddi_dma_segtocookie() from a high-levelinterrupt routine, which is not recommended.

When breaking a DMA window into segments, the system arranges forthe end of every segment whose number is an integral multiple of thescatter/gather list size to fall on a device-granularity boundary, asspecified in the dlim_granular field in the ddi_dma_lim_x86(9S)structure.

If the scatter/gather list size is 1 (either because no chaining is availableor because the driver does not want to use the chaining feature), then thetotal I/O count for a single DMA operation is the size of DMA segmentdenoted by the single DMA cookie that is passed in the call toddi_dmae_prog(). In this case, the system arranges for each DMAsegment to be a multiple of the device-granularity size.

der_path Specifies the DMA transfer size. The default of zero (DMAE_PATH_DEF)specifies ISA compatibility mode. In that mode, channels 0, 1, 2, and 3are programmed in 8-bit mode (DMAE_PATH_8), and channels 5, 6, and 7are programmed in 16-bit, count-by-word mode (DMAE_PATH_16).

der_cycles Specifies the timing mode to be used during DMA data transfers. Thedefault of zero (DMAE_CYCLES_1) specifies ISA compatible timing.Drivers using this mode must also specify DMAE_TRANS_SNGL in theder_trans structure member.

der_trans Specifies the bus transfer mode that the DMA engine should expect fromthe device. The default value of zero (DMAE_TRANS_SNGL) specifies thatthe device performs one transfer for each bus arbitration cycle. Devicesthat use ISA compatible timing (specified by a value of zero, which is thedefault, in the der_cycles structure member) should use the

ddi_dmae_req(9S)


DMAE_TRANS_SNGL mode.



Architecture x86

isa(4), attributes(5), ddi_dma_segtocookie(9F), ddi_dmae(9F), ddi_dma_lim_x86(9S),ddi_dma_req(9S)

Attributes

See Also

ddi_dmae_req(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 18 Nov 200440

http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1473&id=isa-4http://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-segtocookie-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dmae-9f

ddi_dma_lim_sparc, ddi_dma_lim – SPARC DMA limits structure

#include

Solaris SPARC DDI specific (Solaris SPARC DDI). These interfaces are obsolete.

This page describes the SPARC version of the ddi_dma_lim structure. Seeddi_dma_lim_x86(9S) for a description of the x86 version of this structure.

A ddi_dma_lim structure describes in a generic fashion the possible limitations of a device'sDMA engine. This information is used by the system when it attempts to set up DMAresources for a device.

uint_t dlim_addr_lo; /* low range of 32 bit

addressing capability */

uint_t dlim_addr_hi; /* inclusive upper bound of address.

capability */

uint_t dlim_cntr_max; /* inclusive upper bound of

dma engine address limit * /

uint_t dlim_burstsizes; /* binary encoded dma burst sizes */

uint_t dlim_minxfer; /* minimum effective dma xfer size */

uint_t dlim_dmaspeed; /* average dma data rate (kb/s) */

The dlim_addr_lo and dlim_addr_hi fields specify the address range the device's DMAengine can access. The dlim_addr_lo field describes the lower 32–bit boundary of the device'sDMA engine, the dlim_addr_hi describes the inclusive upper 32–bit boundary. The systemallocates DMA resources in a way that the address for programming the device's DMA engine(see ddi_dma_cookie(9S) or ddi_dma_htoc(9F)) is within this range. For example, if yourdevice can access the whole 32–bit address range, you may use [0,0xFFFFFFFF]. If your devicehas just a 16–bit address register but will access the top of the 32–bit address range, then[0xFFFF0000,0xFFFFFFFF] is the right limit.

The dlim_cntr_max field describes an inclusive upper bound for the device's DMA engineaddress register. This handles a fairly common case where a portion of the address register isonly a latch rather than a full register. For example, the upper 8 bits of a 32–bit address registercan be a latch. This splits the address register into a portion that acts as a true address register(24 bits) for a 16 Mbyte segment and a latch (8 bits) to hold a segment number. To describethese limits, specify 0xFFFFFF in the dlim_cntr_max structure.

The dlim_burstsizes field describes the possible burst sizes the device's DMA engine canaccept. At the time of a DMA resource request, this element defines the possible DMA burstcycle sizes that the requester's DMA engine can handle. The format of the data is binaryencoding of burst sizes assumed to be powers of two. That is, if a DMA engine is capable ofdoing 1–, 2–, 4–, and 16–byte transfers, the encoding ix 0x17. If the device is an SBus deviceand can take advantage of a 64–bit SBus, the lower 16 bits are used to specify the burst size for32–bit transfers and the upper 16 bits are used to specify the burst size for 64–bit transfers. Asthe resource request is handled by the system, the burstsizes value can be modified. Prior to

Name

Synopsis

Interface Level

Description

StructureMembers

ddi_dma_lim_sparc(9S)


http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-htoc-9f

enabling DMA for the specific device, the driver that owns the DMA engine should check(using ddi_dma_burstsizes(9F)) what the allowed burstsizes have become and programthe DMA engine appropriately.

The dlim_minxfer field describes the minimum effective DMA transfer size (in units ofbytes). It must be a power of two. This value specifies the minimum effective granularity of theDMA engine. It is distinct from dlim_burstsizes in that it describes the minimum amount ofaccess a DMA transfer will effect. dlim_burstsizes describes in what electrical fashion theDMA engine might perform its accesses, while dlim_minxfer describes the minimum amountof memory that can be touched by the DMA transfer. As a resource request is handled by thesystem, the dlim_minxfer value can be modified contingent upon the presence (and use) ofI/O caches and DMA write buffers in between the DMA engine and the object that DMA isbeing performed on. After DMA resources have been allocated, the resultant minimumtransfer value can be gotten using ddi_dma_devalign(9F).

The field dlim_dmaspeed is the expected average data rate for the DMA engine (in units ofkilobytes per second). Note that this should not be the maximum, or peak, burst data rate, buta reasonable guess as to the average throughput. This field is entirely optional and can be leftas zero. Its intended use is to provide some hints about how much of the DMA resource thisdevice might need.



Interface Stability Obsolete

ddi_dma_addr_setup(9F), ddi_dma_buf_setup(9F), ddi_dma_burstsizes(9F),ddi_dma_devalign(9F), ddi_dma_htoc(9F), ddi_dma_setup(9F), ddi_dma_cookie(9S),ddi_dma_lim_x86(9S), ddi_dma_req(9S)

Attributes

See Also

ddi_dma_lim_sparc(9S)

man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 12 Oct 200542

http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-burstsizes-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-devalign-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1474&id=attributes-5http://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-addr-setup-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-buf-setup-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-burstsizes-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-devalign-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-htoc-9fhttp://www.oracle.com/pls/topic/lookup?ctx=821-1477&id=ddi-dma-setup-9f

ddi_dma_lim_x86 – x86 DMA limits structure

#include

Solaris x86 DDI specific (Solaris x86 DDI). This interface is obsolete.

A ddi_dma_lim structure describes in a generic fashion the possible limitations of a device orits DMA engine. This information is used by the system when it attempts to set up DMAresources for a device. When the system is requested to perform a DMA transfer to or from anobject, the request is broken up, if necessary, into multiple sub-requests. Each sub–requestconforms to the limitations expressed in the ddi_dma_lim structure.

This structure should

Documents

man pages section 9 DDI and DKI Properties and Data Structures · 2012. 2. 22. · thereisnoBUGSsection.Seetheintropagesformoreinformationanddetailabouteach section,andman(1)formoreinformationaboutmanpagesingeneral