DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
TOC PREV NEXT INDEX

Table of Contents


Volume I


Abstract i

Copyright Notice ii

Acknowledgements iii

Table of Contents v

List of Reference Pages by Chapter xv

Alphabetical List of Symbols xxi

Section 1: Overview

1 Introductory Material 1-1

1.1 Introduction 1-1

1.2 Scope 1-1

1.3 Normative References 1-1

1.4 Conformance 1-2

1.4.1 Environment Conformance 1-2

1.4.2 Device Driver Conformance 1-3

2 Document Organization 2-1

2.1 Overview of UDI Documentation 2-1

2.2 Overview of the UDI Core Specification 2-2

2.2.1 Core Specification Sections 2-2

2.2.2 Core Specification Topics 2-2

3 Terminology 3-1

3.1 Introduction 3-1

3.2 Definitions 3-1

3.2.1 Directive Terms 3-1

3.2.2 Common Terms 3-2

Section 2: Architecture

4 Execution Model 4-1

4.1 Introduction 4-1

4.2 Driver Object Modules 4-1

4.3 Driver Instances 4-1

4.4 Regions 4-1

4.4.1 Driver Partitioning 4-2

4.5 Multi-Module Drivers 4-2

4.6 Channels 4-2

4.7 Driver Execution Environments 4-2

4.7.1 Non-Blocking Model 4-3

4.8 Function Call Classifications 4-4

4.8.1 Service Calls 4-4

4.8.1.1 Synchronous Service Calls 4-5

4.8.1.2 Asynchronous Service Calls 4-5

4.8.2 Channel Operations 4-5

4.9 Location Independence 4-6

4.10 Driver Faults/Recovery 4-6

4.10.1 Overview of Region-Kill 4-6

4.10.2 Improper Channel Operation Usage 4-7

4.11 Metalanguage Model 4-7

4.11.1 Metalanguage Roles 4-7

4.11.1.1 Management Metalanguage Roles 4-8

5 Data Model 5-1

5.1 Overview 5-1

5.2 Data Objects 5-2

5.2.1 Memory Objects 5-2

5.2.1.1 Using Memory Pointers with Asynchronous Service Calls 5-2

5.2.2 Control Blocks 5-3

5.2.2.1 Scratch Space 5-3

5.2.2.2 Inline Data 5-3

5.2.2.3 Control Block Groups 5-3

5.2.2.4 Control Block Synchronization 5-4

5.2.2.5 Control Block Recycling 5-4

5.2.2.6 Control Block Pointer Invariance 5-4

5.2.3 Region Data 5-5

5.3 Channel Context 5-5

5.4 Transferable Objects 5-5

5.5 Implicit MP Synchronization 5-5

6 Configuration Model 6-1

6.1 Overview 6-1

6.2 Static Configuration 6-1

6.2.1 Static Driver Properties 6-1

6.2.2 Initialization Structures 6-1

6.2.3 Building UDI Drivers 6-2

6.2.4 UDI Packaging 6-2

6.2.5 UDI Package Installation 6-2

6.3 Dynamic Configuration 6-3

6.3.1 Device Tree 6-3

6.3.2 Driver Instantiation 6-3

6.3.3 Device Node Enumeration and Attributes 6-3

6.3.4 Driver Inter-Instance Binding 6-3

7 Calling Sequence and Naming Conventions 7-1

7.1 Overview 7-1

7.2 Channel Operations 7-2

7.2.1 Channel Operation Invocations 7-2

7.2.2 Channel Operation Entry Points 7-2

7.3 Asynchronous Service Calls 7-4

7.3.1 Asynchronous Service Call Invocations 7-4

7.3.2 Associated Callback Functions 7-4

7.3.3 Control Block Type Conversion 7-5

7.4 Channel Operations Vectors 7-6

7.5 Control Block Groups 7-6

Section 3: Core Services

8 General Requirements 8-1

8.1 Versioning 8-1

8.2 Header Files 8-1

8.3 C Language Requirements 8-2

8.4 Endianness Requirements 8-2

9 Fundamental Types 9-1

9.1 Overview 9-1

9.2 Usage of Standard ISO C Data Types and Macros 9-2

9.2.1 ISO C char Type 9-2

9.2.2 ISO C void Type 9-2

9.2.2.1 Null Pointers 9-2

9.2.3 ISO C sizeof and offsetof operators 9-3

9.2.4 Varargs Types 9-3

9.3 Notation for Implementation-Dependent Types and Constants 9-3

9.4 Specific-Length Types 9-4

9.5 Abstract Types 9-6

9.5.1 Size Type 9-6

9.5.2 Index Type 9-6

9.5.2.1 Control Block Index 9-6

9.5.2.2 Metalanguage Index 9-7

9.5.2.3 Ops Index 9-7

9.5.2.4 Region Index 9-7

9.6 Opaque Types 9-8

9.6.1 Opaque Handles 9-8

9.6.2 Self-Contained Opaque Types 9-13

9.6.2.1 Timestamp Type 9-13

9.7 Semi-Opaque Types 9-13

9.7.1 Control Blocks 9-13

9.7.1.1 Buffers 9-13

9.8 Structures Requiring a Fixed Binary Representation 9-14

9.9 Common Derived Types 9-15

9.9.1 UDI Status 9-15

9.9.1.1 Common Status Codes 9-18

9.9.2 Data Layout Specifier 9-21

9.10 Implementation-Dependent Macros 9-27

10 Initialization 10-1

10.1 Overview 10-1

10.1.1 Per-Driver Initialization 10-1

10.1.2 Per-Instance Initialization 10-1

10.1.3 Per-Region Initialization 10-1

10.2 Per-Driver Initialization Structure 10-2

10.3 Initial Region Data Structures 10-16

11 Control Block Management 11-1

11.1 Overview 11-1

11.2 Control Block Service Calls and Macros 11-2

12 Memory Management 12-1

12.1 Overview 12-1

12.2 Memory Management Service Calls 12-2

13 Buffer Management 13-1

13.1 Overview 13-1

13.2 Buffer Type 13-2

13.3 Transfer Constraints 13-4

13.4 Buffer Management Macros 13-7

13.5 Buffer Management Service Calls 13-12

13.5.1 Buffer Usage Models 13-12

13.5.2 Buffer Recovery Mechanism 13-13

13.6 Buffer Paths 13-21

13.6.1 Buffer Path Multiplexing 13-21

13.7 Buffer Tags 13-26

13.7.1 Buffer Tag Categories 13-26

13.7.2 Buffer Tag Utilities 13-35

14 Time Management 14-1

14.1 Timer Services 14-2

14.1.1 Timed Delays 14-2

14.1.2 Timer Context 14-2

14.2 Timestamp Services 14-7

15 Instance Attribute Management 15-1

15.1 Overview 15-1

15.2 Instance Attribute Names 15-1

15.3 Persistence of Attributes 15-1

15.4 Classes of Attributes 15-2

15.4.1 Instance-Private Attributes 15-2

15.4.2 Enumeration Attributes 15-2

15.4.2.1 Generic Enumeration Attributes 15-2

15.4.2.1.1 identifier attribute 15-3

15.4.2.1.2 address_locator attribute 15-3

15.4.2.1.3 physical_locator attribute 15-3

15.4.2.1.4 physical_label attribute 15-3

15.4.2.1.5 Generic Enumeration Attribute Example 15-3

15.4.3 Sibling Group Attributes 15-4

15.4.4 Parent-Visible Attributes 15-5

15.4.5 Attribute Classification 15-5

15.5 Instance Attribute Services 15-6

16 Inter-Module Communication 16-1

16.1 Overview 16-1

16.2 Service Calls 16-1

16.3 Channel Event Indication Operation 16-9

17 Tracing and Logging 17-1

17.1 Overview 17-1

17.2 Tracing and Logging Service Calls 17-1

17.2.1 Tracing Calls 17-1

17.2.2 Logging Calls 17-1

17.2.3 Trace Event Types 17-2

18 Debugging Services 18-1

18.1 Overview 18-1

18.2 Debugging Service Calls 18-2

Volume II

Section 4: Core Utility Functions

19 Introduction to Utility Functions 19-1

19.1 Overview 19-1

20 String/Memory Utility Functions 20-1

20.1 Overview 20-1

20.2 General String/Memory Functions 20-1

20.3 String Formatting Functions 20-10

21 Queue Management Utility Functions 21-1

21.1 Overview 21-1

21.2 Queue Management 21-2

21.2.1 Queue Element Structure 21-2

21.2.2 Queuing Functions 21-4

21.2.3 Queuing Macros 21-7

22 Endianness Management Utility Functions 22-1

22.1 Overview 22-1

22.2 Endianness Management 22-2

22.2.1 Rules for C Structure Definitions 22-2

22.2.1.1 Byte-by-byte structure layout 22-2

22.2.2 Helper Macros 22-4

22.2.2.1 Bit-field Macros 22-4

22.2.3 Endian-Swapping Utilities 22-11

Section 5: Core Metalanguages

23 Introduction to UDI Metalanguages 23-1

23.1 Overview 23-1

23.2 Standard Metalanguage Functions and Parameters 23-1

23.3 Channel Operation Suffixes 23-2

23.4 General Rules for Handling Channel Operations 23-3

23.4.1 Normal Operation Handling 23-3

23.4.2 Operations That Are Not Understood 23-3

23.4.3 Operations That Are Not Supported 23-3

23.4.4 Operations Received In An Invalid State 23-3

23.4.5 Operations With Mistaken Identity 23-4

23.4.6 Extended Channel Error Handling 23-4

24 Management Metalanguage 24-1

24.1 Overview 24-1

24.2 Management Agent 24-1

24.2.1 Driver Instantiation 24-2

24.3 Management Metalanguage Considerations 24-5

24.4 Initialization 24-6

24.4.1 Tracing Control Operations 24-6

24.4.2 Resource Management 24-6

24.5 Enumeration Operations 24-13

24.5.1 Enumeration Attributes 24-13

24.5.2 Child ID 24-13

24.5.3 Enumeration Filters 24-13

24.5.4 Parent ID 24-14

24.5.5 Dynamic Enumeration (Hot Plug) 24-14

24.5.6 Unenumeration 24-15

24.5.7 Directed Enumeration 24-15

24.6 Device Management Operations 24-27

24.6.1 Prepare To Suspend 24-27

24.6.2 Suspend 24-28

24.6.3 Shutdown 24-28

24.6.4 Parent Suspended 24-29

24.6.5 Resume 24-29

24.6.6 Abrupt Unbind 24-29

24.7 Metalanguage-Specific Trace Events 24-36

24.8 Management Metalanguage States 24-37

24.8.1 Management Metalanguage States 24-39

24.8.1.1 Operational Sub-States 24-39

25 Generic I/O Metalanguage 25-1

25.1 Overview 25-1

25.1.1 Versioning 25-2

25.1.2 Roles 25-2

25.2 Metalanguage Bindings 25-2

25.2.1 Bindings for Static Driver Properties 25-2

25.2.2 Bindings for Instance Attributes 25-2

25.2.2.1 Enumeration Attributes 25-3

25.2.2.2 Filter Attributes 25-3

25.2.2.3 Generic Enumeration Attributes 25-3

25.2.3 Enumeration Attribute Ranking 25-4

25.2.4 Bindings for Trace Events 25-4

25.3 Metalanguage State Diagram 25-5

25.3.1 GIO Metalanguage States 25-5

25.4 Channel Ops Vectors 25-7

25.5 Binding and Unbinding Operations 25-10

25.6 Data Transfer and Control Operations 25-16

25.7 Event Handling Operations 25-24

26 Diagnostics Support 26-1

26.1 Diagnostics State 26-1

Section 6: MEI Services

27 Introduction to MEI 27-1

27.1 Overview 27-1

27.2 Requirements on Metalanguage Specifications 27-2

27.2.1 General Requirements & Conventions 27-2

27.2.2 Bindings to the Core Specification 27-2

27.2.2.1 Bindings for Static Driver Properties 27-2

27.2.2.2 Bindings for Instance Attributes 27-2

27.2.2.3 Bindings for Custom Parameters 27-3

27.2.2.4 Bindings for Trace Events 27-3

27.2.2.5 Abortable Ops 27-3

27.2.2.6 Recoverable Ops 27-3

27.2.3 Operation Ordering Requirements 27-3

27.2.4 State Diagram 27-4

28 Metalanguage-to-Environment Interface 28-1

28.1 Overview 28-1

28.1.1 Versioning 28-1

28.2 Initialization Structures 28-2

28.3 Marshalling 28-12

28.4 MEI Stubs 28-13

28.5 MEI Stub Implementation 28-19

Section 7: Packaging and Distribution

29 Introduction to Packaging and Distribution 29-1

29.1 Introduction 29-1

30 Static Driver Properties 30-1

30.1 Overview 30-1

30.1.1 UDI Modules 30-1

30.2 Basic Syntax 30-3

30.3 Property Declaration Syntax 30-4

30.4 Common Property Declarations 30-5

30.5 Property Declarations for Libraries 30-10

30.6 Property Declarations for Drivers 30-13

30.7 Build-Only Properties 30-23

30.8 Sample Static Driver Properties File 30-25

31 Packaging & Distribution Format 31-1

31.1 Overview 31-1

31.2 Packaging Format 31-1

31.2.1 Directory Structure 31-1

31.3 Archive Format 31-2

31.4 Distribution Format 31-3

31.4.1 Floppy Storage Format 31-3

31.4.2 CD-ROM Storage Format 31-3

32 Build & Packaging Utility Programs 32-1

32.1 Overview 32-1

32.2 The udibuild Utility 32-1

32.3 The udimkpkg Utility 32-1

32.4 The udisetup Utility 32-2

Section 8: ABI Bindings

33 Introduction to ABI Bindings 33-1

33.1 Introduction 33-1

33.2 Processor Architecture 33-1

33.3 Runtime Architecture 33-2

33.4 Binary Bindings to the Source-Level Specifications 33-2

33.4.1 Sizes of UDI Data Types 33-2

33.4.2 Implementation-Dependent Macros 33-3

33.4.3 UDI Functions implemented as macros 33-4

33.4.4 Miscellaneous Binary Bindings 33-4

33.5 Building the Driver Object 33-4

33.5.1 Object File Format 33-4

33.5.2 Static Driver Properties Encapsulation 33-4

Section 9: Appendices

A Glossary A-1

Index X-1


TOC PREV NEXT INDEX