STMicroelectronics OSPlus User Manual

UM1150

User manual

OSPlus

Introduction

OSPlus is an enhancement package for the OS20 and OS21 operating systems. It provides several new APIs that enable device drivers and I/O infrastructure.

How this document is organized

●

●

●

In this manual, OSPlus functions are divided into a number of services. Each of the major service types is described separately, using a common layout: an overview of the service and the facilities it provides a list of the macros, types and functions defined by the service header file a detailed description of each of the functions in the service

November 2012 7702033 Rev 27 1/515

www.st.com

Contents

Contents

UM1150

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1 Introduction to OSPlus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.1

OSPlus overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.2

OSPlus differences under OS20 and OS21 . . . . . . . . . . . . . . . . . . . . . . . 14

1.3

OSPlus API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2 OSPlus support library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.1

Support library overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.2

String functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.3

Endian conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.4

I/O register access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.5

ID management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.6

Name management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.7

Time management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.8

Interrupt management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.9

Cache management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.10

DMA management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.11

Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.12

Uncached memory recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.13

Memory address translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.14

List management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.15

Debug functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.16

Idempotent lock creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2.17

Read/write locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2.18

Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.18.1

Basic Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.18.2

Real time clocks and timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.19

Version management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.20

Handle management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

2/515 7702033 Rev 27

UM1150

3

4

Contents

2.21

OSPlus library header file: osplus.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

2.22

OSPlus support function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

OSPlus registry library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

3.1

Registry library overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

3.2

The registry structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

3.3

Board support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

3.4

The registry API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

3.4.1

3.4.2

Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

3.5

Registry library header file: registry.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

3.6

Registry function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

OSPlus device model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

4.1

Device model overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

4.2

Device driver application interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

4.2.1

4.2.2

4.2.3

4.2.4

4.2.5

4.2.6

Discovering devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Device types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Opening, closing and performing I/O . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Standard ioctl functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Starting and stopping devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Device attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

4.3

Device driver writer interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

4.3.1

4.3.2

4.3.3

Device classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Device instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Seek time optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

4.4

Device library header file: device.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

4.5

Device library header file: dev.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

4.6

Device library header file: ioctls/common.h . . . . . . . . . . . . . . . . . . . . . . 140

4.7

Device library header file: ioctls/keyboard.h . . . . . . . . . . . . . . . . . . . . . . 144

4.8

Device library header file: ioctls/mouse.h . . . . . . . . . . . . . . . . . . . . . . . . 144

4.9

USB device library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

4.10

Device driver ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

4.10.1

Device driver common ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . 146

4.10.2

Joystick ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

7702033 Rev 27 3/515

Contents

5

6

UM1150

4.10.3

Keyboard ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

4.10.4

Mouse ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

4.11

Device driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

4.12

Writing an OSPlus device driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

4.12.1

Device driver overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

4.12.2

Anatomy of an OSPlus device driver . . . . . . . . . . . . . . . . . . . . . . . . . . 203

4.12.3

dd_init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

4.12.4

dd_open() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

4.12.5

dd_close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

4.12.6

dd_read() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

4.12.7

dd_ioctl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

4.12.8

dd_block_read() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

4.12.9

dd_block_write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

OSPlus GPDMA driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

5.1

GPDMA driver overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

5.2

GPDMA driver transfer types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

5.3

GPDMA driver configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

5.4

GPDMA driver initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

5.5

GPDMA driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

5.5.1

5.5.2

Constructing and executing a single transfer . . . . . . . . . . . . . . . . . . . . 211

Constructing and executing a list of transfers . . . . . . . . . . . . . . . . . . . 212

5.6

GPDMA driver header file gpdma.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

5.7

GPDMA driver ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

5.8

GPDMA driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

5.9

GPDMA driver macro definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

OSPlus PCI driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

6.1

PCI driver overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

6.2

PCI driver configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

6.3

PCI driver initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

6.4

PCI driver address space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

6.5

PCI driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

6.5.1

6.5.2

Finding a PCI device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Enabling a PCI device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

4/515 7702033 Rev 27

UM1150

7

Contents

6.5.3

6.5.4

Memory mapped PCI devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

PCI device interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

6.6

PCI driver header file: pci.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

6.7

PCI driver ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

6.8

PCI driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

6.9

PCI driver macro definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

OSPlus file systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

7.1

File systems overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

7.2

Virtual file system (VFS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

7.2.1

7.2.2

7.2.3

7.2.4

7.2.5

7.2.6

7.2.7

7.2.8

Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Mount points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Files and directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Data and metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Partition types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Error numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

File system state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Large file support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

7.2.9

Timestamp support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

7.2.10

String character encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

7.2.11

VFS header file: vfs.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

7.2.12

VFS header file: vfs_fs.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

7.3

E2FS file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

7.3.1

7.3.2

7.3.3

7.3.4

7.3.5

7.3.6

Cache configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Block allocator configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Defrag configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Device write-cache configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

E2FS header file: e2fs.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

7.4

FAT12/16/32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

7.4.1

7.4.2

7.4.3

7.4.4

7.4.5

7.4.6

Free cluster count configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Defrag configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Long filename support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Cache configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

FAT header file: fat.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

7702033 Rev 27 5/515

Contents

8

9

UM1150

7.5

Linear access file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

7.5.1

LAFS header file: lafs.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

7.6

Multi-slot file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

7.6.1

MSFS header file: msfs.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

7.7

File systems function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

7.8

Adding a new file system to the VFS . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

7.8.1

7.8.2

7.8.3

7.8.4

Anatomy of a file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Service provided by the VFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

_vfs_filesystem_t method definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 310

OSPlus logical volume manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

8.1

Logical volume manager overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

8.2

Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

8.2.1

8.2.2

8.2.3

Partition types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

OSPlus supported partition types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Creating and deleting partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

8.3

Removable media devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

8.4

LVM library header file: lvm.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

8.5

LVM function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

OSPlus serial driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

9.1

Serial driver overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

9.2

Serial driver support interface types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

9.3

Serial driver configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

9.4

Serial driver initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

9.5

The serial driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

9.6

Serial driver header file: serial.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

9.7

Serial driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

9.7.1

9.7.2

Serial driver common ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Serial driver serial ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

9.8

Serial ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

9.9

Serial driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

6/515 7702033 Rev 27

UM1150

10

Contents

OSPlus ethernet drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

10.1

Ethernet drivers overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

10.2

Ethernet driver configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

10.2.1

LAN91 driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

10.2.2

LAN9x1x driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

10.2.3

STxMAC driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

10.2.4

h2heth driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

10.3

Generic PHY driver configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

10.4

Ethernet drivers initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

10.5

Generic PHY driver initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

10.6

Ethernet drivers usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

10.6.1

Reading and writing packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

10.6.2

Packet filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

10.6.3

Power management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

10.7

Generic PHY driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

10.7.1

Power management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

10.7.2

Custom PHY ops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

10.8

Ethernet drivers header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

10.8.1

LAN91 driver header file: lan91.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

10.8.2

LAN9x1x driver header file: lan9x1x.h . . . . . . . . . . . . . . . . . . . . . . . . . 377

10.8.3

STxMAC driver header file: stxmac.h . . . . . . . . . . . . . . . . . . . . . . . . . 378

10.8.4

h2heth driver header file: h2heth.h . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

10.9

Generic PHY driver header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

10.10 Ethernet driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

10.10.1 Ethernet driver common ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

10.10.2 Ethernet driver ethernet ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

10.11 Generic PHY driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

10.12 Ethernet ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

10.13 Generic PHY ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

10.14 Ethernet driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

10.14.1 LAN91 driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

10.14.2 LAN9x1x driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

10.14.3 STxMAC driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

10.14.4 Host-to-host ethernet driver function definitions . . . . . . . . . . . . . . . . . 417

10.15 Generic PHY driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . 418

7702033 Rev 27 7/515

Contents

11

12

UM1150

OSPlus storage drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

11.1

Storage drivers overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

11.2

Storage drivers supported devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

11.3

Storage drivers performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

11.4

Storage driver configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

11.4.1

ATA driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

11.4.2

SATA driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

11.4.3

SD/MMC driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

11.5

Storage drivers initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

11.6

Storage drivers usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

11.6.1

ATA and SATA driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

11.6.2

RAM disk driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

11.6.3

SD/MMC driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

11.7

Storage drivers header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

11.7.1

ATA driver header file: ata.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

11.7.2

SATA driver header file: sata.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

11.7.3

RAM disk driver header file: ramdisk.h . . . . . . . . . . . . . . . . . . . . . . . . 429

11.7.4

SD/MMC driver header file: sdmmc.h . . . . . . . . . . . . . . . . . . . . . . . . . 430

11.8

Storage driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

11.8.1

ATA and SATA driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

11.8.2

RAM disk driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

11.8.3

SD/MMC driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

11.9

Storage driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

11.9.1

ATA driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

11.9.2

SATA driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

11.9.3

SD/MMC driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

11.9.4

RAM disk driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

11.10 Storage driver ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

11.10.1 SD/MMC driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

OSPlus Flash drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

12.1

Flash drivers overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

12.2

Flash driver geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

12.3

Flash driver performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

8/515 7702033 Rev 27

UM1150 Contents

12.4

Flash driver configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

12.4.1

EMI low-level NAND driver registry options . . . . . . . . . . . . . . . . . . . . . 449

12.4.2

Flex low-level NAND driver registry options . . . . . . . . . . . . . . . . . . . . . 451

12.4.3

LAFTL driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

12.4.4

STNFTL driver registry options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

12.5

Flash drivers initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

12.5.1

Low-level NAND driver initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

12.5.2

LAFTL driver initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

12.5.3

STNFTL driver initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

12.6

Flash drivers usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

12.6.1

Low-level NAND driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . 459

12.6.2

Low-level NAND driver basic usage model . . . . . . . . . . . . . . . . . . . . . 459

12.6.3

Low-level NAND driver advanced usage model . . . . . . . . . . . . . . . . . . 460

12.6.4

EMI low-level NAND driver memory caching . . . . . . . . . . . . . . . . . . . . 461

12.6.5

Flex low-level NAND driver memory caching . . . . . . . . . . . . . . . . . . . . 461

12.6.6

LAFTL driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

12.6.7

STNFTL driver usage model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

12.7

Flash drivers header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

12.7.1

EMI low-level NAND driver header file: eminand.h . . . . . . . . . . . . . . . 463

12.7.2

Flex low-level NAND driver header file: flex.h . . . . . . . . . . . . . . . . . . . 464

12.7.3

LAFTL driver header file: laftl.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

12.7.4

STNFTL driver header file: stnftl.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

12.7.5

Flash driver header file: ioctls/nand.h . . . . . . . . . . . . . . . . . . . . . . . . . 466

12.8

Flash driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

12.8.1

Low-level NAND driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

12.8.2

LAFTL driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

12.8.3

STNFTL driver ioctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

12.9

Flash driver ioctl definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

12.10 Flash driver function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

12.10.1 EMI low-level NAND driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . 481

12.10.2 Flex low-level NAND driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . 482

12.10.3 LAFTL driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

12.10.4 STNFTL driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

7702033 Rev 27 9/515

Contents UM1150

Appendix A E2FS soft updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

Appendix B Cache coherency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491

Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

List of IOCTLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506

List of functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511

10/515 7702033 Rev 27

UM1150

Preface

Preface

Document identification and control

Each book carries a unique identifier of the form:

nnnnnnn Rev x where nnnnnnn is the document number, and x is the revision.

Whenever making comments on a document, the complete identification nnnnnnn Rev x should be quoted.

Conventions used in this guide

General notation

The notation in this document uses the following conventions:

●

●

●

●

●

Sample code

, keyboard input and file names,

Variables and code variables,

code comments

,

Screens, windows and dialog boxes,

Instructions.

Hardware notation

●

●

The following conventions are used for hardware notation:

REGISTER NAMES and FIELD NAMES,

PIN NAMES and SIGNAL NAMES.

Software notation

Syntax definitions are presented in a modified Backus-Naur Form (BNF). Briefly:

1.

Terminal strings of the language, that is, strings not built up by rules of the language, are printed in teletype font. For example, void.

2. Nonterminal strings of the language, that is, strings built up by rules of the language, are printed in italic teletype font. For example, name.

3. If a nonterminal string of the language starts with a nonitalicized part, it is equivalent to the same nonterminal string without that nonitalicized part. For example, vspace-

name

.

4. Each phrase definition is built up using a double colon and an equals sign to separate the two sides (‘::=’).

5. Alternatives are separated by vertical bars (‘|’).

6. Optional sequences are enclosed in square brackets (‘[’ and ‘]’).

7. Items which may be repeated appear in braces (‘{’ and ‘}’).

7702033 Rev 27 11/515

Preface UM1150

Acknowledgements

Microsoft

®

, MS-DOS

®

and Windows

®

are registered trademarks of Microsoft Corporation in the United States and/or other countries.

Linux

®

is a registered trademark of Linus Torvalds.

Samsung is a trademark of the Samsung Group.

12/515 7702033 Rev 27

UM1150

1 Introduction to OSPlus

Introduction to OSPlus

OSPlus is an enhancement package for the OS20 and OS21 operating systems. It delivers several new APIs that enable device drivers and I/O infrastructure.

Note:

OSPlus delivers extensions to OS20 and OS21 in the following areas:

● device driver infrastructure:

– device driver API

– device driver writer’s interface

– registry services

●

– drivers for standard devices file system infrastructure:

– top level virtual file system (VFS)

– support for FAT and Ext2 file systems

● optional OSPlus extension packages:

– USB 2.0

– TCP/IP

– IEEE 1394 (FireWire)

USB functions are covered in a separate document, OSPlus USB User Manual (8018282).

7702033 Rev 27 13/515

Introduction to OSPlus

Figure 1

shows the structure of OSPlus.

Figure 1.

OSPlus structure

Application

VFS

FAT E2FS

LVM

Device layer

TCP/IP

Registry

UM1150

Device drivers

Hardware

USB stack 1394 stack

1.2 OSPlus differences under OS20 and OS21

Although the OSPlus APIs are identical under OS20 and OS21, there are some issues to be aware of when working in the different environments of OS20 and OS21.

For the standard drivers that need to use interrupts, the operating system must be initialized and started before using the drivers. For OS21 this means both kernel_initialize() and kernel_start() must be called before using the drivers. This is also true for OS20, except that the interrupt subsystem must be initialized too. This means the following calls must be made before using the drivers: interrupt_init_controller() interrupt_init() /* For each level used */ interrupt_enable_global()

See the OS20 and OS21 documentation for a full description of how to initialize these operating systems.

14/515 7702033 Rev 27

UM1150 Introduction to OSPlus

All OSPlus APIs are C-language function calls. The success or failure of a given function call is shown by its return value. Please consult the specific API definitions for details.

If a given API call fails, it sets an error code in the errno variable. The possible values for errno

are listed in the <errno.h> file. There are some OSPlus APIs where certain errno values have been assigned a special meaning in the context of OSPlus (EAGAIN when vfs_mount()

fails for example). Consult the specific API definitions for details of any special errno values. Some of the common errno values used by OSPlus, and their

meanings, are given in

Table 1: OSPlus errno values

.

EACCESS

EAGAIN

EBADF

EBUSY

EEXIST

EINVAL

EIO

EISDIR

ENODEV

ENOMEM

ENOSPC

ENOTDIR

ENOTEMPTY

ENOTSUP

EROFS

ETIMEDOUT

Table 1.

OSPlus errno values errno value

E2BIG

Meaning

Filename too long. This can also be returned by some file system operations (for example, seeking beyond 4 Gbytes in a 32-bit file system like FAT).

Access permissions do not allow the operation

File system needs recovering with vfs_fsck()

File handle given was bad

Entity is busy and cannot be accessed

File already exists

Parameter was illegal

Non-recoverable I/O error occurred

Entity is a directory, not a file

Device does not exist

Out of memory

No space left on device

Entity is not a directory

Directory is not empty

Requested operation is not supported

File system is read-only

Operation timed out

7702033 Rev 27 15/515

OSPlus support library

2 OSPlus support library

2.1

UM1150

Support library overview

The OSPlus library provides a set of support functions to aid the writing of device drivers.

These functions provide a simple level of abstraction which allows code to be portable between OS20 and OS21.

●

●

●

The OSPlus library provides three main string functions: osplus_strdup()

duplicates a string osplus_strsep() osplus_strpre()

provides string tokenization

prepends one string on another

A further string function is provided called osplus_format_double_to_str(). This converts a double value representing a number of bytes to, for example, Kbytes or Mbytes and returns a string containing the converted value. It is useful when performing performance benchmark tests that calculate values in bits/bytes per second.

2.4

Three functions are provided that allow values to be copied with or without byte swapping. osplus_copy16()

, osplus_copy32() and osplus_copy64() copy 16-, 32- and 64-bit values respectively, with optional byte swapping.

I/O register access

The OSPlus library provides a set of macros to aid reading and writing device registers. In

Table 2

, n can be 8, 16 or 32, representing accesses in byte, word or dword sizes.

Table 2.

OSPlus I/O access macros

Macro Description

OSPLUS_READn()

OSPLUS_WRITEn()

OSPLUS_SETn()

Read from an I/O register

Write to an I/O register

Set bits in an I/O register

OSPLUS_CLEARn()

OSPLUS_INREPn()

OSPLUS_WMB()

Clear bits in an I/O register

Read multiple times from an I/O register

OSPLUS_OUTREPn()

OSPLUS_SYNC()

Write multiple times to an I/O register

OSPLUS_BIT(i)

Returns

Sync point (commit all writes to this point)

Write memory barrier

16/515 7702033 Rev 27

UM1150 OSPlus support library

OSPlus provides a simple API for the management of IDs, where IDs are defined as small integer values typically used when generating unique names for devices or handles in the system.

To use the ID manager, a new instance must be created with osplus_id_manager_create()

. An ID manager instance can be used to allocate and free unique IDs with the calls osplus_id_allocate() and osplus_id_free(). The lowest available ID from that manager is always returned when allocating an ID. ID manager instances can be deleted with the call osplus_id_manager_delete().

OSPlus provides a simple API for the generation of unique names. This API is useful when creating new device instances.

First, a name prefix is registered with the name manager, using the call osplus_name_manager_register()

. When a prefix is registered, it can be used to produce unique names based on that prefix. The unique names take the form of the prefix string followed by an integer value. For example, registering the prefix ‘foo’, would produce the unique name sequence: foo0

, foo1, foo2, foo3, and so on.

A prefix can be registered multiple times, and all the names generated from that prefix are guaranteed to be unique. The call osplus_name_allocate() generates new names from a registered prefix. The names generated with this call must be freed with the call osplus_name_free()

. Prefix strings are unregistered with the call osplus_name_manager_unregister()

.

OSPlus provides the time_ticks_per_sec() function when building with R2.0.5 of the

ST20 toolset. This call is provided by the ST20 toolset for versions R2.1.2 and later. OSPlus provides the osclock_t type under OS20, to ease portability between OS20 and OS21.

OSPlus provides the call osplus_ms_delay() which delays the caller for the number of milliseconds indicated.

Two time conversion routines, osplus_mktime()and osplus_localtime() are provided to allow conversion between the time_t and struct tm forms of time, which are also provided in the toolset.

The interrupt APIs of OS20 and OS21 are different. OSPlus provides an abstract interrupt

API which works on both platforms. Code written to use this API is portable between OS20 and OS21.

Interrupts are described by an interrupt name, an interrupt level and an interrupt trigger mode. The level and trigger mode are ignored on OS21. For OS20, interrupt names

7702033 Rev 27 17/515

OSPlus support library UM1150

correspond to OS20 interrupt numbers. For OS21, interrupt names correspond to OS21 interrupt names.

Before anything can be done with an interrupt, its handle must be retrieved. The call osplus_interrupt_handle()

takes an interrupt name, a level, and a trigger mode, and returns a handle that can be used with other OSPlus interrupt calls. Interrupt handles should be deleted when no longer needed with the osplus_interrupt_handle_delete() call.

Interrupt handlers are installed using the calls osplus_interrupt_install() and osplus_interrupt_install_shared()

. For OS20, these calls have the same effect, but for OS21, they install either an exclusive or shared handler for the given interrupt. In all cases, the interrupt handler installed should return 0 if it successfully serviced the interrupt, or -1 if it did not. Handlers are removed with the calls osplus_interrupt_uninstall() and osplus_interrupt_uninstall_shared().

Interrupts are enabled with the call osplus_interrupt_enable(), disabled with osplus_interrupt_disable()

and cleared at the controller with osplus_interrupt_clear()

. osplus_interrupt_raise() attempts to raise the given interrupt, if the hardware is able.

OSPlus adds cache_purge_data() and cache_purge_data_all() to the OS20 environment to align it with the functionality provided by OS21. cache_purge_data_all()

flushes and invalidates the entire D-cache, while cache_purge_data()

flushes and invalidates just the memory range specified.

OSPlus provides functions to help with writing cache-aware code. Knowledge of the cache geometry is needed when performing I/O or DMA operations on cached memory. osplus_cache_line_size()

returns the size of a D-cache line in bytes, and osplus_cache_alignment()

returns the alignment of cache lines, expressed as a power of 2 exponent.

The functions osplus_cache_safe_allocate() and osplus_cache_safe_allocate_timeout()

allow the allocation of memory buffers, so the buffers are aligned on a cache line boundary, and guarantee not to share cache lines with other CPU data structures. Such buffers can be used to perform I/O or DMA operations optimally. The memory buffer is allocated from the specified partition (if the partition is NULL the C run-time memory heap is used). osplus_cache_safe_allocate() fails if the allocation cannot be satisfied immediately. The timeout version allows the caller to specify the waiting behavior. The buffers allocated with these calls should be freed with the call osplus_cache_safe_deallocate()

.

18/515

OSPlus provides some functions to help device drivers which control DMA capable devices.

osplus_dma_prepare()

is used to prepare a buffer for DMA. It should be called immediately before the buffer is handed to the device which is to perform the DMA. This call determines whether or not the buffer is suitable for DMA, and if it is, the call performs any cache purging or memory barrier operations that may be necessary. Suitability for DMA is defined as the buffer is either uncached (as determined by osplus_uncached()), or starts and ends on cache line boundaries. The call fails if the buffer is unsuitable for DMA,

7702033 Rev 27

UM1150 OSPlus support library

giving the caller the opportunity to perform the operation through some other means (for example PIO or DMA through a staging buffer).

osplus_dma_complete()

is used on a buffer once a DMA operation has completed. It should be used immediately any DMA operation which has written to memory completes. Its actions are platform specific, and ensure cache coherency for the buffer.

OSPlus introduces a memory management API that allows memory to be allocated from partitions using specific alignment constraints and timeout behaviors.

Each call takes a memory partition on which to operate. If the partition is NULL the C runtime memory heap is used. osplus_allocate() allocates a memory block from the specified partition, aligned on the address given address boundary. osplus_allocate_timeout()

has the same behavior, except that if the allocation cannot be satisfied immediately, the caller can specify an amount of time to wait for memory to become available. The nontimeout version fails immediately if the allocation cannot be performed. The memory allocated with these two calls is released with the call osplus_deallocate()

.

OSPlus provides the function osplus_align() which is used to get an address aligned on a specific power of 2 boundary. This call takes a base address, and an alignment (specified as an exponent), and returns the next highest address which starts at the alignment specified. For example, this can be useful when rounding-up an address to the next cache line boundary.

2.12 Uncached memory recording

OSPlus provides an API that allows the location of uncached memory regions to be recorded. This API does not create or manage the uncached memory regions, it simply records their locations.

This API allows drivers to query whether a given region of memory is located in cached or uncached memory. This information is needed when performing bus mastering or DMA data transfers.

An uncached memory entry is created using osplus_uncached_register(), and deleted using osplus_uncached_unregister(). Memory regions can be queried to determine whether they are uncached using the osplus_uncached() function.

2.13 Memory address translation

OSPlus provides a number of macros to simplify generating cached, uncached and physical address pointers. The macro OSPLUS_CACHED_ADDR_FROM_UNCACHED() takes an uncached address and returns a cached pointer to that memory, if the architecture allows it.

OSPLUS_CACHED_ADDR()

performs the same function, and is provided for compatibility with earlier releases of OSPlus. The macro OSPLUS_CACHED_ADDR_FROM_PHYS() takes an physical address and returns a cached pointer to that memory.

The macro OSPLUS_UNCACHED_ADDR_FROM_CACHED() takes a cached address and returns an uncached pointer to that memory, if the architecture allows it.

7702033 Rev 27 19/515

OSPlus support library UM1150

OSPLUS_UNCACHED_ADDR()

performs the same function, and is provided for compatibility with earlier releases of OSPlus. The macro OSPLUS_UNCACHED_ADDR_FROM_PHYS() takes an physical address and returns an uncached pointer to that memory.

The macro OSPLUS_PHYS_ADDR() takes a virtual (CPU) address, and returns the corresponding physical address.

Note:

OSPlus provides a rich API to manage doubly-linked lists. osplus_list_init() initializes a list to be empty. osplus_list_size() returns the number of elements in a list, and osplus_list_is_empty() shows if the given list contains no elements. osplus_list_contains_node()

shows if the given list contains the given node. Nodes are added to linked lists with osplus_list_add_front() and osplus_list_add_back()

and they can be removed with osplus_list_remove(), osplus_list_delete()

, osplus_list_remove_front() or osplus_list_remove_back()

. List iterators are provided in the form of osplus_list_first()

, osplus_list_last(), osplus_list_next() and osplus_list_prev()

.

osplus_list_delete()

performs an implicit free of the node removed from the list.

20/515

OSPlus provides a set of macros to allow debug output from applications and device drivers.

Support for the debug features is controlled by the OSPLUS_DEBUG pre-processor value.

The debugging features are enabled if OSPLUS_DEBUG is set to a non-zero value when the modules are compiled.

The debug macros allow both unconditional and conditional printing of debug messages.

Conditional printing of debug messages can be based on the global debug mask, or a local debug mask. To use the local debug mask feature, modules are needed to define the

OSPLUS_DEBUG_MODULE_NAME

pre-processor symbol to a unique string value.

Output is normally sent to the console, but by specifying a log file name, it can also be logged to a file.

The debugging macros provided are given in

Table 3

.

Table 3.

OSPlus debug macros

Macro

OSPLUS_ASSERT()

OSPLUS_SET_DEBUG_MASK()

OSPLUS_SET_MY_DEBUG_MASK()

OSPLUS_SET_MODULE_DEBUG_MASK()

OSPLUS_SET_LOG_FILE()

OSPLUS_GET_LOG_FILE()

OSPLUS_MODULE_DPRINTF()

OSPLUS_DPRINTF()

Description

Abort if the given expression is false

Set the global debug mask

Set the local module debug mask

Set the debug mask for the given module

Specify the name of the log file

Get the name of the log file

Debug print, conditional on module debug mask

Debug print, conditional on global debug mask

7702033 Rev 27

UM1150 OSPlus support library

Table 3.

OSPlus debug macros (continued)

Macro

OSPLUS_MODULE_PRINTF()

OSPLUS_PRINTF()

OSPLUS_WARNING()

OSPLUS_ERROR()

OSPLUS_FATAL()

Description

Unconditional debug print

Unconditional printf

Print a warning message

Print an error message

Print a fatal error and abort

By default the output from OSPLUS_PRINTF(), OSPLUS_DPRINTF()

OSPLUS_MODULE_PRINTF()

and OSPLUS_MODULE_DPRINTF() is sent to the stdout file handle, while the output from OSPLUS_ASSERT(), OSPLUS_WARNING(),

OSPLUS_ERROR()

and OSPLUS_FATAL() is sent to the stderr file handle. This behavior can be overridden by two registry keys. Set these keys to the address of a function that takes a single string as its argument. This will cause the strings that would have been output to the given file handle to be sent to the functions specified by the keys. These user provided functions can then process the strings as desired (for example, send to a serial port, log to memory, and so forth) The registry path for the keys is “/configuration/osplus”, and the key names are “redirect stdout” and “redirect stderr”. Convenience macros for these values are provided, as shown in

Table 4

.

Table 4.

OSPlus configuration keys

Macro

OSPLUS_CONFIG_PATH

OSPLUS_REDIRECT_STDERR

OSPLUS_REDIRECT_STDOUT

Value

“/configuration/osplus”

“redirect stdout”

“redirect stderr”

7702033 Rev 27 21/515

OSPlus support library UM1150

osplus_lock_create()

is used to safely instantiate a unique binary semaphore. This call is typically used in situations where synchronization locks must be dynamically created.

This process needs memory allocation for the lock, therefore special care must be taken so only one lock is ever created, regardless of how many callers attempt to initialize a given library. The logic in this call ensures that precisely one lock only is ever created for a given library. It returns the address of a binary semaphore as its result.

In the following example, a fictitious driver is initialized by the driver_initialize() call.

It ensures only one caller ever initializes the driver by creating a binary semaphore, acquiring it, and then initializing if necessary.

void driver_initialize (void)

{

static semaphore_t *init_lock = NULL;

if (driver_state != NULL)

{

}

/* Create and acquire lock */

if (osplus_lock_create (&init_lock) == -1)

{

}

semaphore_wait (init_lock);

if (driver_state == NULL)

{

/* Initialize, creating driver_state */

}

}

semaphore_signal (init_lock);

Note:

Read/write locks are provided by OSPlus as special synchronization objects that allow efficient and safe concurrent access to shared data. Read/write locks allow an arbitrary number of reader tasks into a locked section, to the exclusion of all writers. Similarly, they allow a single writer task into a locked section, to the exclusion of all others.

The data protected by a lock (held by a reader) is guaranteed not to change while the lock is held. When a read/write lock is taken by a writer, it is guaranteed the data is not being accessed by anyone else, so modifications can be made safely.

The concepts of reader and writer are not enforced by the system. Unpredictable results occur if a read/write lock is taken by a task as a reader, which then proceeds to modify the data protected by the lock. Similarly, if the data protected by the lock is accessed without first taking the lock, the results are unpredictable.

22/515 7702033 Rev 27

UM1150 OSPlus support library

Read/write locks are created with osplus_rwlock_create(). This call returns the address of a new lock. The locks are deleted with the call osplus_rwlock_delete().

To enter a locked section of code, the call osplus_rwlock_enter() is used. This call takes the address of a read/write lock and a flag showing if the caller wants to acquire the lock with reader or writer permissions. If the lock cannot be granted immediately, the call is blocked until it can be granted. When the call returns, the lock has been taken. The call osplus_rwlock_tryenter()

has the same semantics as osplus_rwlock_enter(), with the exception the call fails if the lock cannot be granted immediately.

Read/write locks are released with osplus_rwlock_leave(). If the lock being released is a write lock, and there are queued readers and writers waiting to acquire the lock, the lock is either passed to the first waiting writer, or all the waiting readers. Whether readers or writers are selected, is decided on a fair turn-taking basis.

Read/write locks can be upgraded and downgraded. When a reader owns a lock, it can attempt to upgrade the lock to writer status with the call osplus_rwlock_tryupgrade().

This call is not guaranteed to succeed. If there are no other readers currently sharing the lock, the call succeeds. If there are other readers sharing the lock, and no writers waiting to take the lock, the task blocks and waits for all readers to release the lock. If the lock is released, the call is granted the lock in write mode and succeeds. In all other situations the upgrade is not possible.

A writer can downgrade its lock status to that of a reader with the call osplus_rwlock_downgrade()

. When the call returns, the lock is still held, but as a reader. Any tasks that were blocked, waiting to acquire the lock as readers, are granted the lock, so the lock can be shared between multiple readers.

2.18 Timers

OSPlus provides two interfaces to support timers and real-time clocks. One interface

(described in

Section 2.18.1: Basic Timers

) provides the ability to execute a callback

function after a given period, and the other interface (see

Section 2.18.2: Real time clocks and timers on page 24

) provides the ability to set and query a real-time clock.

Note:

The OSPlus basic timer interface provides a simple mechanism to execute a callback function after a certain period. OSPlus timers support both periodic and single shot timers

(osplus_timer_flags_periodic and osplus_timer_flags_one_shot).

A timer is created with osplus_timer_create() and deleted with osplus_timer_delete()

. A timer can be started by calling osplus_timer_start() and stopped using osplus_timer_stop(). The period of a timer is specified when it is created but can be retrieved using osplus_timer_period() and set using osplus_timer_period_set()

.

All timers are managed by a separate OSPlus timer task that is created with the first call to osplus_timer_create()

. When a timer expires, its associated callback function is called from the context of the OSPlus timer task.

The callback is called from the context of the OSPlus timer task and is therefore using the

OSPlus timer task’s stack. Callback functions should only be used to send a message to a user task or for very simple non-blocking actions. If the callback does block, then all timers cease to function until the callback function exits.

7702033 Rev 27 23/515

OSPlus support library UM1150

2.18.2 Real time clocks and timers

Note:

OSPlus provides support for software based real-time clocks and timers. The interface provides the ability to set and to query the current real time (wall clock time), expressed as an unsigned integer. This value is an offset from any arbitrary known date and time. The convention is to use midnight on January 1st, 1970, although a different date and time may be chosen to suit the application. The current real time is set with osplus_rtc_time_set()

. When set, the real time clock starts counting immediately. The clock can be queried with osplus_rtc_time(). Real time timers (alarm clocks) can be created with osplus_rtc_timer_create() and deleted with osplus_rtc_timer_delete()

. The alarm time for a real time timer can be set with osplus_rtc_timer_time_set()

and queried with osplus_rtc_timer_time(). Real

time timers behave just like the single shot OSPlus timers as described in

Section 2.18.1

,

but the alarm time itself is expressed as an offset in seconds from the arbitrary start point.

Real time timers are started with osplus_rtc_timer_start(), and stopped with osplus_rtc_timer_stop()

. When a real time timer fires, it calls the user specified callback provided when the timer was created. The same caveats apply to these callbacks

as were described for basic timers, in

Section 2.18.1

.

The OSPlus real time clock is purely a software implementation, based on the timer services of the underlying operating system. The accuracy cannot therefore be guaranteed. To prevent excessive timer drift, we recommend that the real time is set from a known and reliable external source once every 24 hours.

24/515

The OSPlus version management interface allows code modules to register themselves with a specified version string; this is achieved by using the function osplus_version_set().

The version strings are stored in the registry and every OSPlus component registers itself against a version string during initialization. This version string can be later retrieved by using osplus_version().

Each OSPlus module has a specified name through which the version string can be retrieved (For example, the ATA driver uses OSPLUS_ATA_MODULE). These module names are defined in

Table 3: OSPlus debug macros on page 20

.

The following example shows how to register a version string for a fictional component to retrieve the version string.

const char *module = "OSPlus Fictional Module"; const char *version = "version 1.1 2006";

/* Set the fictional module version */

if (osplus_version_set (module, version) == -1)

{

exit (-1); /* Error setting version */

}

/* Get the fictional module version */

const char *read_version = osplus_version (module); if (read_version == NULL)

{

}

exit (-1); /* Failed to get module version */

7702033 Rev 27

UM1150 OSPlus support library

The OSPlus handle management API is an aid for developers writing device drivers that provides a mechanism to hide a data structure behind an opaque handle. The osplus_handle_create()

call takes as its arguments a pointer to an item of critical driver-specific data (that is, the data structure to be hidden behind the handle) and a unique identifier for the caller. The identifier is typically the address of a function, or a piece of data unique to the caller. osplus_handle_create() then creates and returns a unique handle for the data structure pointer, and the device driver can then pass this handle back to the application.

Whenever the application calls the driver, it passes in this handle. The driver can then call osplus_handle()

with the handle and the driver's unique identifier to recover the original data pointer.

When used in debug mode, the API detects the use of illegal handles, previously closed handles, and handles that do not belong to the caller. In non-debug mode the APIs simply return the passed-in data pointer without any runtime checking performed.

A handle is destroyed by calling osplus_handle_delete().

2.21 OSPlus library header file: osplus.h

All the definitions relating to the support library are in the file osplus.h.

Table 5.

Functions defined in osplus.h

Function Description

cache_purge_data() cache_purge_data_all() osplus_align() osplus_allocate() osplus_allocate_timeout()

Purge data-cache range (OS20 only)

Purge all data-cache (OS20 only)

Align address to power of 2 boundary

Allocate an aligned memory block from the specified partition

Allocate an aligned memory block from the specified partition osplus_cache_alignment() osplus_cache_line_size() osplus_cache_safe_allocate()

Return the cache line alignment for the platform

Return the cache line size for the platform

Allocate a memory block for use as an I/O buffer osplus_cache_safe_allocate_timeout()

Allocate a memory block for use as an I/O buffer osplus_cache_safe_deallocate()

Free a block of allocated memory osplus_copy16()

Copy 2 bytes with optional byte swapping osplus_copy32() osplus_copy64()

Copy 4 bytes with optional byte swapping

Copy 8 bytes with optional byte swapping osplus_deallocate()

Free a block of allocated memory osplus_dma_complete() osplus_dma_prepare()

Perform post-DMA cleanup for a buffer

Prepare a buffer for DMA

7702033 Rev 27 25/515

OSPlus support library UM1150

Table 5.

Functions defined in osplus.h (continued)

Function Description

osplus_format_double_to_str() osplus_handle osplus_handle_create osplus_handle_delete osplus_id_allocate() osplus_id_free()

Format a double value and return a string

Convert handle to data pointer

Create a new handle to map a data pointer

Delete a handle

Allocate unique ID

Free ID

Create ID manager instance osplus_id_manager_create() osplus_id_manager_delete() osplus_interrupt_clear() osplus_interrupt_disable() osplus_interrupt_enable() osplus_interrupt_handle()

Delete ID manager instance

Clear interrupt at controller

Disable interrupt at controller

Enable interrupt at controller

Return interrupt handle for given interrupt osplus_interrupt_handle_delete() osplus_interrupt_install()

Delete interrupt handler

Install interrupt handler

Install interrupt handler on shared interrupt osplus_interrupt_install_shared() osplus_interrupt_raise()

Raise interrupt at controller

Uninstall interrupt handler osplus_interrupt_uninstall() osplus_interrupt_uninstall_shared()

Uninstall shared interrupt handler osplus_list_add_back() osplus_list_add_front()

Add node behind node in list

Add node in front of node in list

Return whether or not list contains given node osplus_list_contains_node() osplus_list_delete() osplus_list_first() osplus_list_init()

Remove node from list and free it

Return first node in list

Initialize empty list osplus_list_is_empty() osplus_list_last() osplus_list_next() osplus_list_prev() osplus_list_remove() osplus_list_remove_back()

Return if list is empty

Return last node in list

Return next node in list

Return previous node in list

Remove node from list

Remove node from back of list osplus_list_remove_front() osplus_list_size() osplus_localtime() osplus_lock_create()

Remove front node from list

Return number of nodes in list

Converts time_t

time to a struct tm representation

Atomically create a binary semaphore

26/515 7702033 Rev 27

UM1150 OSPlus support library

Table 5.

Functions defined in osplus.h (continued)

Function

osplus_mktime() osplus_ms_delay() osplus_name_allocate() osplus_name_free() osplus_name_manager_register() osplus_name_manager_unregister() osplus_rtc_time_set() osplus_rtc_time() osplus_rtc_timer_create() osplus_rtc_timer_delete() osplus_rtc_timer_time_set() osplus_rtc_time_time() osplus_rtc_time_start() osplus_rtc_time_stop() osplus_rwlock_create() osplus_rwlock_delete() osplus_rwlock_downgrade() osplus_rwlock_enter() osplus_rwlock_leave() osplus_rwlock_tryenter() osplus_rwlock_tryupgrade() osplus_strdup() osplus_strpre() osplus_strsep() osplus_timer_create() osplus_timer_delete() osplus_timer_period() osplus_timer_period_set() osplus_timer_start() osplus_timer_stop() osplus_uncached() osplus_uncached_register()

Description

Converts struct tm time to a time_t representation

Delay calling task for the specified number of milliseconds

Generate a new name from a name prefix

Free a name

Register a name prefix with the name manager

Unregister a name prefix

Set the real time for the system

Get the real time for the system

Create a real time timer

Delete a real time timer

Set the alarm time for a real time timer

Query the alarm time for a real time timer

Start a real time timer

Stop a real time timer

Create a read/write lock

Delete a read/write lock

Downgrade a writer to a reader

Acquire a read/write lock

Release a read/write lock

Try to acquire a read/write lock

Try to upgrade a reader to a writer

Duplicate string

Add prefix to string

Tokenize string

Create a timer

Delete a timer

Return the timer period

Set the timer period

Start a timer

Stop a timer

Check if a memory region is uncached

Create an uncached memory region entry

7702033 Rev 27 27/515

OSPlus support library UM1150

Table 5.

Functions defined in osplus.h (continued)

Function

osplus_uncached_unregister() time_ticks_per_sec()

Description

Delete an uncached memory region

Returns the number of ticks per second (OS20 only)

Table 6.

Macros defined in osplus.h

Macro Description

OSPLUS_*_MODULE

OSPLUS_ALIGN_*

OSPLUS_ASSERT()

OSPLUS_BIT(n)

OSPLUS_CACHED_ADDR()

OSPLUS_CACHED_ADDR_FROM_UNCACHED()

OSPLUS_CACHED_ADDR_FROM_PHYS()

OSPLUS_CLEARn()

OSPLUS_DPRINTF()

OSPLUS_ERROR()

OSPLUS_FATAL()

OSPLUS_FORMAT_*

OSPLUS_GET_LOG_FILE()

OSPLUS_INREPn()

OSPLUS_LIST_FOREACH()

OSPLUS_LIST_REMOVE_EACH()

OSPLUS_MIN_STACK_SIZE

OSPLUS_MODULE_DPRINTF()

OSPLUS_O_*

OSPLUS_OUTREPn()

OSPLUS_PHYS_ADDR()

OSPLUS_PRINTF()

OSPLUS_READn()

OSPLUS_SET_DEBUG_MASK()

OSPLUS_SET_LOG_FILE()

OSPLUS_SET_MODULE_DEBUG_MASK()

OSPLUS_SET_MY_DEBUG_MASK()

OSPlus module names for version API

Power of 2 alignment values

Abort if expression is not true

Return 2 raised to the power n

Return a cached virtual address for an uncached virtual address

Return a cached virtual address for an uncached virtual address

Return a cached virtual address for a physical address

Clear bits in I/O register

Print debug message, using global debug mask

Print error message

Print fatal error message and abort

Format specifiers for use with osplus_format_double_to_str()

Return log file name

Repeatedly read I/O register

List iterator

List iterator, removing node each iteration

Default minimum stack size for platform

Print debug message, using module debug mask

File open modes

Repeatedly write I/O register

Return physical address for a virtual address

Print debug message

Read I/O register

Set global debug mask

Specify log file name

Set module debug mask

Set local module debug mask

28/515 7702033 Rev 27

UM1150 OSPlus support library

Table 6.

Macros defined in osplus.h (continued)

OSPLUS_SETn()

Macro

OSPLUS_UNCACHED_ADDR()

OSPLUS_UNCACHED_ADDR_FROM_CACHED()

OSPLUS_UNCACHED_ADDR_FROM_PHYS()

OSPLUS_WARNING()

OSPLUS_SYNC()

OSPLUS_WMB()

OSPLUS_WRITEn()

Description

Set bits in I/O register

Return uncached virtual address for a cached virtual address

Return uncached virtual address for a cached virtual address

Return uncached virtual address for a physical address

Print warning message

Sync point (commit all writes to this point)

Write memory barrier

Write I/O register n

Table 7.

Types defined in osplus.h

Type

interrupt_handler_t interrupt_name_t interrupt_t osclock_t osplus_id_t osplus_rwlock_t osplus_timer_flags_t osplus_timer_t

Description

Interrupt handler type (OS20 systems only)

Interrupt name (OS20 systems only)

Interrupt handle (OS20 systems only)

Clock type (OS20 systems only)

ID manager instance

Read/write lock type

Timer flags enumeration

Timer instance

7702033 Rev 27 29/515

OSPlus support library UM1150

2.22 OSPlus support function definitions cache_purge_data

Purge the data cache range

Definition:

void cache_purge_data (

void *base_address,

size_t size)

Arguments:

base_address size

The start address of the range to purge.

The number of bytes to purge.

Returns:

Description:

See also:

None.

This function is provided by OSPlus on OS20 platforms only. On OS21 it is provided by OS21. This function writes any dirty data cache lines back to memory, and invalidates the data cache within the given range.

cache_purge_data_all

30/515 7702033 Rev 27

UM1150 OSPlus support library

cache_purge_data_all

Purge the data cache

Definition:

Arguments:

Returns:

Description:

See also:

void cache_purge_data_all (void)

None.

None.

This function is provided by OSPlus on OS20 platforms only. On OS21 it is provided by OS21. This function writes any dirty data cache lines back to memory, and invalidates the data cache.

cache_purge_data

7702033 Rev 27 31/515

OSPlus support library UM1150

osplus_align

Align the address given up to a power of two

Definition:

void *osplus_align (

void *addr,

unsigned int align)

Arguments:

addr align

The base address to align.

The alignment specification.

Returns:

Description:

Returns the aligned address.

The address passed by addr is aligned up to the next power of 2 as specified by align

. align is the exponent for the required power of 2 (for example, an align value of 5 aligns the address up to the next 32 byte boundary).

32/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_allocate

Allocate an aligned memory block from the specified partition

Definition:

void *osplus_allocate (

partition_t *part,

size_t size,

unsigned int alignment)

Arguments:

part size alignment

The partition to allocate from, or NULL for the C-heap.

The block size.

The address boundary for alignment.

Returns:

Description:

See also:

Returns the address of the allocated memory block, or NULL for failure.

This function allocates a memory block of size bytes from partition part, so it starts on the alignment specified. If part is NULL the C run-time memory heap is used.

The alignment value is expressed as the exponent of the required power of 2 (for example, a value of 5 aligns the buffer on a 32 boundary).

osplus_allocate_timeout

7702033 Rev 27 33/515

OSPlus support library UM1150

osplus_allocate_timeout

Allocate a memory block from the specified partition

Definition:

void *osplus_allocate_timeout (

partition_t *part,

size_t size,

unsigned int alignment,

osclock_t *timeout)

Arguments:

part size alignment timeout

The partition to allocate from, or NULL for the C-heap.

The block size.

The address boundary for alignment.

The timeout specification.

Returns:

Error values:

Description:

See also:

Returns the address of the allocated memory block, or NULL for failure.

Invalid parameters, out of memory or timeout.

This function allocates a memory block of size bytes from partition part, so it starts on the alignment specified. If part is NULL the C run-time memory heap is used.

The alignment value is expressed as the exponent of the required power of 2 (for example, a value of 5 aligns the buffer on a 32 boundary). The timeout parameter dictates the call behavior if the allocation cannot be immediately satisfied. If timeout has the value TIMEOUT_IMMEDIATE the call behaves exactly like osplus_allocate()

and fails immediately. If timeout has the value

TIMEOUT_INFINITY

the call blocks until the allocation is satisfied.

Any other value is taken to be a time expressed in clock ticks. In this case, the call waits for up to this number of ticks for memory to become available. The call fails if the allocation cannot be satisfied within this period.

osplus_allocate

34/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_cache_alignment

Return the cache line alignment for the platform

Definition:

Arguments:

Returns:

Description:

See also:

size_t osplus_cache_alignment (void)

None.

The data cache line alignment as a power of two exponent value.

This function returns the data cache line alignment for the platform. The value returned is a power of two exponent (for example, 5 would mean cache lines are aligned on 32 byte boundaries, since 2^5 = 32).

osplus_allocate

7702033 Rev 27 35/515

OSPlus support library

osplus_cache_line_size

Return the cache line size for the platform

Definition:

Arguments:

Returns:

Description:

See also:

size_t osplus_cache_line_size (void)

None.

The D-cache line size in bytes.

This function returns the D-cache line size for the platform.

osplus_cache_align

UM1150

36/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_cache_safe_allocate

Allocate a memory block for use as an I/O buffer

Definition:

void *osplus_cache_safe_allocate (

partition_t *part,

size_t size)

Arguments:

part size

The partition to allocate from or NULL for the C-heap.

The size of the memory block in bytes.

Returns:

Error values:

Description:

See also:

The address of the memory block, or NULL.

Invalid parameters, or out of memory.

This function allocates a block of memory from the given partition. The block returned is cache line aligned, and does not share cache lines with any other CPU data structures. The typical use of this function is to allocate cached memory for I/O buffers. Buffers allocated by this function offer optimal performance: CPU accesses are cached, and since the buffers are cache line aligned, no uncached copy operations are necessary when performing I/O.

osplus_cache_safe_allocate_timeout

, osplus_cache_safe_deallocate

7702033 Rev 27 37/515

OSPlus support library UM1150

osplus_cache_safe_allocate_timeout

Allocate a memory block for use as an I/O buffer

Definition:

void *osplus_cache_safe_allocate_timeout (

partition_t *part,

size_t size,

osclock_t *timeout)

Arguments:

part size timeout

The partition to allocate from or NULL for the C-heap.

The size of the memory block in bytes.

The timeout specification.

Returns:

Error values:

Description:

See also:

The address of the memory block, or NULL.

Invalid parameters, out of memory or timeout.

This function allocates a block of memory from the given partition. The block returned is cache line aligned, and does not share cache lines with any other CPU data structures. The typical use of this function is to allocate cached memory for I/O buffers. Buffers allocated by this function offer optimal performance: CPU accesses are cached, and since the buffers are cache line aligned, no uncached copy operations are necessary when performing I/O.

The timeout parameter dictates the call’s behavior if the allocation cannot be immediately satisfied. If timeout has the value TIMEOUT_IMMEDIATE the call behaves exactly like osplus_cache_safe_allocate() and fails immediately. If timeout

has the value TIMEOUT_INFINITY the call blocks until the allocation is satisfied.

Any other value is taken to be a time expressed in clock ticks. In this case, the call waits for up to this number of ticks for memory to become available. The call fails if the allocation cannot be satisfied within this period.

osplus_cache_safe_allocate

, osplus_cache_safe_deallocate

38/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_cache_safe_deallocate

Free memory allocated by osplus_cache_safe_allocate() or osplus_cache_safe_allocate_timeout()

Definition:

void osplus_cache_safe_deallocate (

partition_t *part,

void *memory)

Arguments:

part memory

The partition to free back to or NULL for the C-heap.

The memory block to free.

Returns:

Description:

See also:

None.

This function frees a memory block previously allocated by osplus_cache_safe_allocate()

or osplus_cache_safe_allocate_timeout()

back to its partition.

osplus_cache_safe_allocate

, osplus_cache_safe_allocate_timeout

7702033 Rev 27 39/515

OSPlus support library UM1150

osplus_copy16

Copy a 16-bit quantity with optional byte swapping

Definition:

void osplus_copy16 (

void *dst,

void *src,

int swap)

Arguments:

dst src swap

The destination address for copy.

The source address for copy.

Set this to 1 to enable byte swapping.

Returns:

Description:

See also:

None.

This function copies 16 bits of memory from src to dst, performing a byte swap if swap

is set to a non-zero value. This call is intended to aid extracting data fields from packed structures, which can also be of non-native endianness.

osplus_copy32

, osplus_copy64

40/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_copy32

Copy a 32-bit quantity with optional byte swapping

Definition:

void osplus_copy32 (

void *dst,

void *src,

int swap)

Arguments:

dst src swap

The destination address for copy.

The source address for copy.

Set this to 1 to enable byte swapping.

Returns:

Description:

See also:

None.

This function copies 32 bits of memory from src to dst, performing a byte swap if swap

is set to a non-zero value. This call is intended to aid extracting data fields from packed structures, which can also be of non-native endianness.

osplus_copy16

, osplus_copy64

7702033 Rev 27 41/515

OSPlus support library UM1150

osplus_copy64

Copy a 64-bit quantity with optional byte swapping

Definition:

void osplus_copy64 (

void *dst,

void *src,

int swap)

Arguments:

dst src swap

The destination address for copy.

The source address for copy.

Set this to 1 to enable byte swapping.

Returns:

Description:

See also:

None.

This function copies 64 bits of memory from src to dst, performing a byte swap if swap

is set to a non-zero value. This call is intended to aid extracting data fields from packed structures, which can also be of non-native endianness.

osplus_copy16

, osplus_copy32

42/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_dma_complete

Perform post-DMA processing for a memory buffer

Definition:

void osplus_dma_complete (

void *base_address,

size_t length)

Arguments:

base_address length

The start address of the buffer used for DMA.

The length of the buffer in bytes.

Returns:

Description:

None.

This function should be called following completion of a DMA operation. It performs any necessary post-DMA processing to ensure cache coherency for the buffer used in the transfer.

Note: This function needs to be called only if the DMA operation changed the contents of the memory buffer. For example, if data was transferred from a device into the memory buffer.

See also:

This call is not mandatory when the DMA operation is a transfer from memory to a device, as no coherency issues can arise. However, calling it causes no harm.

osplus_dma_prepare

7702033 Rev 27 43/515

OSPlus support library UM1150

osplus_dma_prepare

Prepare a memory buffer for a DMA operation

Definition:

int osplus_dma_prepare (

void *base_address,

size_t length)

Arguments:

base_address length

The start address of the buffer used for DMA.

The length of the buffer in bytes.

Returns:

Description:

See also:

Returns 0 if the buffer has been successfully prepared for DMA, otherwise -1 is returned indicating the buffer cannot be used for DMA.

This function should be called before a buffer is used for DMA. It determines whether the given buffer is suitable for DMA. If it is suitable for DMA, this call then perform any operations necessary to ensure cache coherency for the buffer before returning 0. If the buffer is unsuitable for DMA (because of its alignment in memory) this call returns

-1

. Under these circumstances, the caller must decide whether to fail the request or perform the request using a different technique (for example use a staging buffer which is suitable for DMA).

osplus_dma_complete

44/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_deallocate

Free a block of memory allocated by osplus_allocate() or osplus_allocate_timeout()

Definition:

void osplus_deallocate (

partition_t *part,

void *memory)

Arguments:

part memory

The partition to free back to, NULL for the C-heap.

The memory block to free.

Returns:

Description:

See also:

None.

This function frees a memory block previously allocated by osplus_allocate() or osplus_allocate_timeout()

back to its partition.

osplus_allocate

, osplus_allocate_timeout

7702033 Rev 27 45/515

OSPlus support library UM1150

osplus_format_double_to_str

Format the double value passed in to a string

Definition:

char *osplus_format_double_to_str (

long double size,

unsigned int format)

Arguments:

size format

The value to format.

The format to convert the value to.

Returns:

Error values:

Description:

Returns a string containing the formatted value for success, NULL for failure.

Invalid parameter.

This function converts the value passed in to a string representing the value as specified by the format parameter. For example, if the user passed a value of

100000

in and a format of OSPLUS_FORMAT_B, the string returned is 1.00MB.

Similarly, if the user passed a value of 1000000000 and a format of

OSPLUS_FORMAT_B

, the string returned is 1.00GB.

The format follows the binary prefixes standard from (IEC 60027-2, 1998), taking one

of the values as described in

Table 8

.

Table 8.

osplus_format_double_to_str() format defines

Define Description

OSPLUS_FORMAT_b

OSPLUS_FORMAT_bps

OSPLUS_FORMAT_B

OSPLUS_FORMAT_BPS

OSPLUS_FORMAT_ib

OSPLUS_FORMAT_ibps

Formats the string as decimal bits returning in: b , Kb , Mb and so on.

In this case, 1000 bits is displayed as 1Mb .

Format the string as decimal bits per second, returning in: bs , Kbs , Mbs and so on.

In this case, 1000 bits per second is displayed as

1Mbs .

Format the string as decimal bytes, returning in:

B , KB , MB , and so on.

In this case, 1000 bytes is displayed as 1MB .

Format the string as decimal bytes per second, returning in: Bs , KBs , MBs and so on.

In this case, 1000 bytes per second is displayed as

1MBS .

Format the string as binary bits returning in: b , Kib ,

Mib and so on.

In this case, 1024 bits are displayed as 1Mib .

Format the string as binary bits per second returning in: bps , Kibps , Mibps and so on.

In this case, 1024 bits per second are displayed as

1Mibs .

46/515 7702033 Rev 27

UM1150 OSPlus support library

Table 8.

osplus_format_double_to_str() format defines (continued)

Define Description

OSPLUS_FORMAT_IB

OSPLUS_FORMAT_IBPS

Format the string as binary bytes, returning in:

B , KiB , MiB and so on.

In this case, 1024 bytes are displayed as

1MiB

.

Format the string as binary bytes per second, returning in:

Bps

,

KiBps

,

MiBps

and so on.

In this case, 1024 bytes per second are displayed as

1MiBs

.

7702033 Rev 27 47/515

OSPlus support library UM1150

osplus_handle

Convert a handle to an opaque data pointer

Definition:

Arguments:

void *osplus_handle (void *h, void *c) h c

The handle to convert

Owning module identifier

Returns:

Error values:

Description:

See also:

Returns the associated data pointer, or NULL for failure.

Invalid argument if h is an invalid handle for this module

Checks that h is a valid handle for the owning module, and returns the hidden data pointer that was associated with the handle when the handle was created.

osplus_handle_create

, osplus_handle_delete

48/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_handle_create

Create a handle to hide an opaque data pointer

Definition:

Arguments:

void *osplus_handle (void *p, void *c) p c

The opaque data pointer to hide behind the new handle

Owning module identifier

Returns:

Error values:

Description:

See also:

Returns the new handle number, or NULL for failure.

Out of memory.

Creates a new handle for the given owning module, and associates the opaque data pointer p with that handle. Valid handles are non-zero unsigned integers. c should be a unique number for the calling module. It is used on subsequent osplus_handle() calls to ensure that the given handle is used only within the context of the module that created it.

osplus_handle osplus_handle_delete

7702033 Rev 27 49/515

OSPlus support library UM1150

osplus_handle_delete

Delete a handle

Definition:

Arguments:

void osplus_handle_delete (void *h, void *c) h c

The handle to delete

Owning module identifier

Returns:

Error values:

Description:

See also:

None.

None.

Deletes a handle for the given owning module. Valid handles are non-zero unsigned integers.

osplus_handle osplus_handle_create

50/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_id_allocate

Allocate a new ID from an ID manager instance

Definition:

Arguments:

int osplus_id_allocate (osplus_id_t *id) id

The ID manager instance to use.

Returns:

Error values:

Description:

See also:

Returns the new ID, or -1 for failure.

Out of memory.

Allocates a new ID from the given ID manager instance. This call returns the next available free ID. Valid IDs are non-negative integers.

osplus_id_free

7702033 Rev 27 51/515

OSPlus support library

osplus_id_free

Free an ID back to an ID manager instance

Definition:

int osplus_id_free (

osplus_id_t *id,

int num)

Arguments:

id num

The ID manager instance to use.

The ID to free.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure

Invalid parameters specified.

This function frees the ID, num, from the ID manager instance, id.

osplus_id_allocate

UM1150

52/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_id_manager_create

Create an instance of the ID manager

Definition:

Arguments:

Returns:

Description:

See also:

osplus_id_t *osplus_id_manager_create (void)

None.

Returns the pointer to the ID manager instance, or NULL.

This function creates a new ID manager instance.

osplus_id_manager_delete

, osplus_id_allocate, osplus_id_free

7702033 Rev 27 53/515

OSPlus support library UM1150

osplus_id_manager_delete

Delete an instance of the ID manager

Definition:

Arguments:

int osplus_id_manager_delete (osplus_id_t *id) id

The address of the ID manager instance to delete.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid id specified.

This function deletes the ID manager instance, id.

osplus_id_manager_create

, osplus_id_allocate, osplus_id_free

54/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_interrupt_clear

Attempt to clear an interrupt

Definition:

Arguments:

int osplus_interrupt_clear (interrupt_t *handle) handle

The handle of the interrupt to clear, obtained previously from osplus_interrupt_handle()

.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid interrupt handle, or interrupt cannot be cleared.

This function attempts to clear the specified interrupt. Many interrupts are automatically cleared when the hardware stops asserting them. Some interrupt controllers latch the interrupt; these must be cleared otherwise the interrupt remains asserted, causing the processor to take an unwanted interrupt.

osplus_interrupt_raise

7702033 Rev 27 55/515

OSPlus support library UM1150

osplus_interrupt_disable

Attempt to disable an interrupt

Definition:

Arguments:

int osplus_interrupt_disable (interrupt_t *handle) handle

The handle of the interrupt to disable, obtained previously from osplus_interrupt_handle().

Returns:

Error values:

Returns 0 for success, -1 for failure.

Invalid interrupt handle, or interrupt cannot be disabled.

Description:

See also:

This function attempts to disable the specified interrupt.

Note: Some interrupt controllers do not support disabling certain interrupts, in which case the call fails.

osplus_interrupt_enable

56/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_interrupt_enable

Attempt to enable an interrupt

Definition:

Arguments:

int osplus_interrupt_enable (interrupt_t *handle) handle

The handle of the interrupt to enable, obtained previously from osplus_interrupt_handle()

.

Returns:

Error values:

Returns 0 for success, -1 for failure.

Invalid interrupt handle, or interrupt permanently enabled.

Description:

This function attempts to enable the specified interrupt.

Note: Some interrupts on some interrupt controllers are always enabled so the call fails.

See also:

osplus_interrupt_disable

7702033 Rev 27 57/515

OSPlus support library UM1150

osplus_interrupt_handle

Obtain an interrupt handle for the specified interrupt

Definition:

interrupt_t *osplus_interrupt_handle (

interrupt_name_t *name,

int level,

interrupt_trigger_mode_t trigger)

Arguments:

name level trigger

The pointer to the interrupt name of the interrupt.

The interrupt level for this interrupt.

The required trigger mode.

Returns:

Error values:

Returns the valid interrupt handle, NULL for failure.

Invalid parameter or out of memory.

Description:

This function obtains a handle for a named interrupt. When an interrupt_t* handle has been obtained, it can be passed to the other functions to carry out actions on that interrupt.

Note: On OS20, the interrupt name and number are synonymous.

See also:

On OS21, the interrupt name and number are synonymous. The interrupt level and trigger

mode are not used in this environment, and should be set to 0. osplus_interrupt_handle_delete

58/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_interrupt_handle_delete

Delete an interrupt handle

Definition:

Arguments:

void osplus_interrupt_handle_delete (interrupt_t *handle) handle

The handle of the interrupt to delete, obtained previously from osplus_interrupt_handle()

.

Returns:

Description:

See also:

None.

This function deletes the interrupt handle, handle, previously obtained from osplus_interrupt_handle()

.

osplus_interrupt_handle

7702033 Rev 27 59/515

OSPlus support library UM1150

osplus_interrupt_install

Install a private interrupt handler

Definition:

int osplus_interrupt_install (

interrupt_t *handle,

interrupt_handler_t handler,

void *param)

Arguments:

handle handler param

The handle of the interrupt that requires a handler to be installed, obtained previously from osplus_interrupt_handle()

.

The interrupt handler to install.

The parameter to pass to the handler when invoked.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid parameters, or the interrupt has already been marked as shareable (OS21 only).

This function installs the specified user interrupt handler for the interrupt source described by handle. When the handler function is called it has its single parameter set to param. The user handler should return 0 if it handled the interrupt, otherwise it should return -1.

This call allows a single interrupt handler to be registered for the given source.

Note: On OS21, when a handler has been registered with this call, further calls to

osplus_interrupt_install()

or osplus_interrupt_install_shared()

for this handle fail. OS20 does not have the concept of shared versus non-shared interrupts.

osplus_interrupt_install_shared

, osplus_interrupt_uninstall, osplus_uninstall_shared

60/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_interrupt_install_shared

Install a shared interrupt handler

Definition:

int osplus_interrupt_install_shared (

interrupt_t *handle,

interrupt_handler_t handler,

void *param)

Arguments:

handle handler param

The handle of the interrupt that requires a handler to be installed, obtained previously from osplus_interrupt_handle()

.

The interrupt handler to install.

The parameter to pass to the handler when invoked.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid parameters, or the interrupt has already been marked as private (OS21 only).

This function installs the specified user interrupt handler for the interrupt source described by handle. When the handler function is called it has its single parameter set to param. The user handler should return 0 if it handled the interrupt, otherwise it should return -1.

This call allows multiple interrupt handlers to be registered for the given source.

Note: On OS21, when a handler has been registered with this call, subsequent calls to

osplus_interrupt_install()

for this handle fail. OS20 does not have the concept of shared versus non-shared interrupts.

osplus_interrupt_install

, osplus_interrupt_uninstall, osplus_interrupt_uninstall_shared

7702033 Rev 27 61/515

OSPlus support library UM1150

osplus_interrupt_raise

Attempt to raise an interrupt

Definition:

Arguments:

int osplus_interrupt_raise (interrupt_t *handle) handle

The handle of the interrupt to raise, obtained previously from osplus_interrupt_handle()

.

Returns:

Error values:

Returns 0 for success, -1 for failure.

Invalid interrupt handle, or the interrupt cannot be raised.

Description:

See also:

This function attempts to raise the specified interrupt. Returns 0 for success, -1 for failure.

Note: Some interrupts on some interrupt controllers cannot be raised, in these cases the call fails.

osplus_interrupt_clear

62/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_interrupt_uninstall

Uninstall an interrupt handler

Definition:

Arguments:

int osplus_interrupt_uninstall (interrupt_t *handle) handle

Uninstall the handler for the interrupt referenced by this handle. The handle was obtained previously from osplus_interrupt_handle()

.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid parameter.

This function uninstalls the interrupt handler associated with interrupt identified by handle

. Returns 0 for success, -1 for failure.

osplus_interrupt_uninstall_shared

7702033 Rev 27 63/515

OSPlus support library UM1150

osplus_interrupt_uninstall_shared

Uninstall an interrupt handler from a shared interrupt

Definition:

int osplus_interrupt_uninstall_shared (

interrupt_t *handle,

interrupt_handler_t handler,

void *param)

Arguments:

handle handler param

Uninstall the handler for the interrupt referenced by this handle. The handle was obtained previously from osplus_interrupt_handle()

.

The interrupt handler to uninstall.

The parameter passed to the interrupt handler.

Returns:

Error values:

Returns 0 for success, -1 for failure.

Invalid parameters, or if the combination of handler and param are not currently registered for the interrupt source, or if the interrupt is marked as nonshareable.

Returns 0 for success, -1 for failure.

Description:

See also:

This function uninstalls the given interrupt handler associated with the interrupt identified by handle, and called with the parameter param.

Note: OS20 does not support the concept of shared interrupt handlers, so this call defaults

to osplus_interrupt_uninstall. osplus_interrupt_uninstall

64/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_list_add_back

Add the given node to the back of the given list

Definition:

void osplus_list_add_back (

osplus_list_t *head,

osplus_list_t *node)

Arguments:

head node

The address of the list structure to update.

The address of the node to add to the list.

Returns:

Description:

See also:

None.

This function adds the specified node to the back of the given list. head can point to the head of a list, or it can point a node within a list. In the latter case, this call has the effect of adding node behind the node specified by head.

osplus_list_add_front

7702033 Rev 27 65/515

OSPlus support library UM1150

osplus_list_add_front

Add the given node to the front of the given list

Definition:

void osplus_list_add_front (

osplus_list_t *head,

osplus_list_t *node)

Arguments:

head node

The address of the list structure to update.

The address of the node to add to the list.

Returns:

Description:

See also:

None.

This function adds the specified node to the front of the given list. head can point to the head of a list, or it can point a node within a list. In the latter case this call has the effect of adding node in front of the node specified by head.

osplus_list_add_back

66/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_list_contains_node

Check if the given list contains the given node

Definition:

int osplus_list_contains_node (

osplus_list_t *head,

osplus_list_t *node)

Arguments:

head node

The address of the list structure to examine.

The address of the node to check.

Returns:

Description:

Returns 1 if the list contains the node, otherwise 0.

This function checks if the given list contains the given node. It scans the entire list to see if it contains the node. It is the caller’s responsibility to perform adequate locking to ensure the list does not change while this call is executing.

7702033 Rev 27 67/515

OSPlus support library UM1150

osplus_list_delete

Remove a node from a list, and frees the node

Definition:

void osplus_list_delete (

osplus_list_t *head,

osplus_list_t *node)

Arguments:

head node

The address of the list structure to update.

The address of the node to delete.

Returns:

Description:

See also:

None.

This function removes the specified node from the specified list, and frees off the memory used for it.

Note: node must have been previously allocated from the system memory heap to use this

call. It is most useful if node is an embedded element in a larger structure, where node

is the first element in that larger structure.

osplus_list_remove

68/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_list_first

Return the address of the first node on the given list

Definition:

Arguments:

osplus_list_t *osplus_list_first (osplus_list_t *head) head

The address of the list structure to examine.

Returns:

Description:

See also:

Returns the address of the first node in the list, or NULL.

This function returns the address of the first node in the list specified by head. If the list is empty NULL is returned.

osplus_list_last

7702033 Rev 27 69/515

OSPlus support library

osplus_list_init

Initialize an OSPlus list to be empty

Definition:

Arguments:

void osplus_list_init (osplus_list_t *head) head

The address of the list structure to initialize.

Returns:

Description:

None.

This function initializes the given list to be empty.

UM1150

70/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_list_is_empty

Check if the given list contains no nodes

Definition:

Arguments:

int osplus_list_is_empty (osplus_list_t *head) head

The address of the list structure to examine.

Returns:

Description:

See also:

Returns 1 if the list contains no nodes, otherwise 0.

This function checks the specified list to see if it contains any nodes. If the list is empty, the call returns 1, otherwise it returns 0.

osplus_list_size

7702033 Rev 27 71/515

OSPlus support library UM1150

osplus_list_last

Return the address of the last node on the given list

Definition:

Arguments:

osplus_list_t *osplus_list_last (osplus_list_t *head) head

The address of the list structure to examine.

Returns:

Description:

See also:

Returns the address of the last node in the list, or NULL.

This function returns the address of the last node in the list specified by head. If the list is empty, NULL is returned.

osplus_list_first

72/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_list_next

Return the address of the next node in a list

Definition:

osplus_list_t *osplus_list_next (

osplus_list_t *head,

osplus_list_t *node)

Arguments:

head node

The address of the list structure to examine.

The current node in the list.

Returns:

Description:

See also:

Returns the address of next node in the list, or NULL.

This function returns the address of the node following node, in the list specified by head

. If the list contains no more nodes, NULL is returned.

osplus_list_first

, osplus_list_prev, osplus_list_last

7702033 Rev 27 73/515

OSPlus support library UM1150

osplus_list_prev

Return the address of the previous node in a list

Definition:

osplus_list_t *osplus_list_prev (

osplus_list_t *head,

osplus_list_t *node)

Arguments:

head node

The address of the list structure to examine.

The current node in the list.

Returns:

Description:

See also:

Returns the address of the previous node in the list, or NULL.

This function returns the address of the node before node, in the list specified by head

. If the list contains no more nodes, NULL is returned.

osplus_list_first

, osplus_list_next, osplus_list_last

74/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_list_remove

Remove a node from a list

Definition:

void osplus_list_remove (

osplus_list_t *head,

osplus_list_t *node)

Arguments:

head node

The address of the list structure to update.

The address of the node to remove from the list.

Returns:

Description:

See also:

None.

This function removes the specified node from the specified list.

osplus_list_delete

, osplus_list_remove_front, osplus_list_remove_back

7702033 Rev 27 75/515

OSPlus support library UM1150

osplus_list_remove_back

Remove the back node from a list

Definition:

Arguments:

osplus_list_t *osplus_list_remove_back (osplus_list_t *head) head

The address of the list structure to update.

Returns:

Description:

See also:

Returns the address of the node removed, or NULL if the list is empty.

This function removes the last node from the list specified by head, and returns the address of that node. If the list is empty, NULL is returned.

osplus_list_remove_front

, osplus_list_remove

76/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_list_remove_front

Remove the front node from a list

Definition:

Arguments:

osplus_list_t *osplus_list_remove_front (osplus_list_t *head) head

The address of the list structure to update.

Returns:

Description:

See also:

Returns the address of the node removed, or NULL if the list is empty.

This function removes the first node from the list specified by head, and returns the address of that node. If the list is empty, NULL is returned.

osplus_list_remove_back

, osplus_list_remove

7702033 Rev 27 77/515

OSPlus support library UM1150

osplus_list_size

Return the number of nodes in the list

Definition:

Arguments:

int osplus_list_size (osplus_list_t *head) head

The address of the list structure to examine.

Returns:

Description:

See also:

Returns the number of nodes in the list.

This function counts the number of nodes queued in the list. It scans the entire list to calculate the number of nodes. It is the caller’s responsibility to perform adequate locking to ensure the list does not change while this call is executing.

osplus_list_is_empty

78/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_localtime

Converts from a time_t time to a struct tm representation

Definition:

struct tm *osplus_localtime (const time_t *timep, struct tm *tmp)

Arguments:

timep tmp

The address of the

time_t time to be converted.

The address of the

struct tm to be used for the result.

Returns:

Description:

Returns a pointer to the struct tm passed in on success and NULL on failure.

This function converts the time_t representation of time (seconds since 00:00:00

1/1/1970) into a fully expanded form of time contained in the struct tm.

Note: Local time zones and summer time are not supported and therefore the tm_isdst

field of the result is always set to -1.

See also:

osplus_mktime

7702033 Rev 27 79/515

OSPlus support library UM1150

osplus_lock_create

Atomically create a binary semaphore

Definition:

Arguments:

int osplus_lock_create (semaphore_t **lock) lock

The address to receive the pointer to the created semaphore.

Returns:

Description:

Returns 0 for success, -1 for failure.

This function is used to safely instantiate a unique binary semaphore. If the location pointed to by lock is non-NULL, this call does not attempt to create the semaphore, and simply returns 0 for success. If it is NULL, the call atomically creates a binary semaphore. This call guarantees to create precisely one semaphore, however many times it is called. It is typically used in initialization routines, for example: void driver_initialize (void)

{ static semaphore_t *init_lock = NULL; if (osplus_lock_create (&init_lock) == -1)

{

}

} if (driver_state == NULL)

{

/* Initialize, creating driver_state */

}

80/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_mktime

Converts from a struct tm time to a time_t representation

Definition:

Arguments:

time_t osplus_mktime (struct tm *tmp) tmp

The address of the struct tm

time to be converted.

Returns:

Description:

See also:

Returns the time_t time on success and -1 on failure

This function converts from the fully expanded struct tm representation of time to the time_t form (seconds since 00:00:00 1/1/1970).

Note: Local timezones are not supported and therefore the tm_isdst field of the

parameter is ignored.

osplus_localtime

7702033 Rev 27 81/515

OSPlus support library UM1150

osplus_ms_delay

Deschedule the calling task several milliseconds

Definition:

Arguments:

void osplus_ms_delay (int ms) ms

The number of milliseconds to delay.

Returns:

Description:

None.

This function deschedules the caller for at least the number of milliseconds specified.

It can therefore not be called from the interrupt context.

Note: This is not a busy wait.

82/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_name_allocate

Generate new names from a name prefix

Definition:

Arguments:

char *osplus_name_allocate (const char *prefix) prefix

The name prefix from which to generate the new name.

Returns:

Errors:

Description:

See also:

Returns a string consisting of the prefix and a unique number.

Invalid parameters or out of memory.

osplus_name_allocate()

generates new names from name prefixes that are registered with the name manager.

osplus_name_free

7702033 Rev 27 83/515

OSPlus support library UM1150

osplus_name_free

Free a name with the name manager

Definition:

int osplus_name_free (

const char *prefix,

char *name)

Arguments:

prefix name

The name prefix.

The name to be freed.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid parameters.

osplus_name_free()

frees a name that has been registered with the name manager and created with osplus_name_allocate().

osplus_name_allocate

84/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_name_manager_register

Register a name prefix with the name manager

Definition:

Arguments:

int osplus_name_manager_register (const char *prefix) prefix

The prefix string to be registered.

Returns:

Error values:

Description:

See also:

Returns 0 on success, -1 on failure.

Invalid parameters or out of memory

This function registers a name prefix with the name manager as the first step in generating a new name.

osplus_name_allocate

7702033 Rev 27 85/515

OSPlus support library

osplus_name_manager_unregister

Unregister a name prefix with the name manager

Definition:

Arguments:

int osplus_name_manager_register (const char *prefix) prefix

The prefix string to be registered.

Returns:

Error values:

Description:

See also:

Returns 0 for success -1 for failure.

Invalid parameter

This function unregisters a name prefix with the name manager.

osplus_name_manager_register

UM1150

86/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_rtc_time_set

Set the real time for the system

Definition:

int osplus_rtc_time_set (osplus_rtc_time_t time)

Arguments:

time

The real time, expressed as an offset in seconds from a known date and time.

Returns:

Description:

See also:

0 for success, -1 for failure.

This function sets the current real time (wall clock time) for the system. The time is expressed as an offset in seconds from a known date and time (for example, midnight on January 1st, 1970). Once set, the real time clock immediately starts keeping time.

osplus_rtc_time

7702033 Rev 27 87/515

OSPlus support library UM1150

osplus_rtc_time

Get the real time for the system

Definition:

Arguments:

osplus_rtc_time_t osplus_rtc_time (void)

None

Returns:

Description:

See also:

The current real time for the system

This function returns the current real time (wall clock time) for the system. The time is expressed as an offset in seconds from a known date and time (for example, midnight on January 1st, 1970).

osplus_rtc_time_set

88/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_rtc_timer_create

Create a real time timer

Definition:

osplus_rtc_timer_t *osplus_rtc_timer_create ( void (*callback) (osplus_rtc_timer_t *rtc_timer, void *user_param), void *user_param)

Arguments:

callback

The function to call when the timer expires user_param

User specified parameter to pass to the callback

Returns:

Description:

See also:

Address of newly created timer, or NULL for failure.

Creates a new real time timer. Real time timers are single shot timers, which need to have their alarm time set and be started in order to operate. When the timer fires, the user supplied callback is called with the given user_param parameter.

Other functions related to real time timers use the value returned by this function as a reference to the created timer.

osplus_rtc_timer_time_set

, osplus_rtc_timer_time, osplus_rtc_timer_start

, osplus_rtc_timer_stop, osplus_rtc_timer_delete

7702033 Rev 27 89/515

OSPlus support library UM1150

osplus_rtc_timer_delete

Delete a real time timer

Description:

int osplus_rtc_timer_delete (osplus_rtc_timer_t *rtc_timer)

Arguments:

rtc_timer

Timer to delete

Returns:

Description:

See also:

0 for success, -1 for failure.

Delete a real time timer. If the timer is still running, this function stops it before deleting it.

osplus_rtc_timer_time_set

, osplus_rtc_timer_time, osplus_rtc_timer_start

, osplus_rtc_timer_stop, osplus_rtc_timer_create

90/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_rtc_timer_time_set

Set the alarm time for a real time timer

Definition:

int osplus_rtc_timer_time_set ( osplus_rtc_timer_t *rtc_timer, osplus_rtc_time time)

Arguments:

rtc_timer

The timer to set the alarm time for time

The new alarm time

Returns:

Description:

See also:

0 for success, -1 for failure

Sets the alarm time for a real time timer. The time is expressed as an offset in seconds from a known date and time (for example, midnight on January 1st, 1970).

The alarm time cannot be changed on a timer whilst it is running.

osplus_rtc_timer_time

, osplus_rtc_timer_start, osplus_rtc_timer_stop

7702033 Rev 27 91/515

OSPlus support library UM1150

osplus_rtc_timer_time

Queries the alarm time for a real time timer

Definition:

int osplus_rtc_timer_time ( osplus_rtc_timer_t *rtc_timer, osplus_rtc_time *time)

Arguments:

rtc_timer

The timer to query time

Variable to receive the alarm time

Returns:

Description:

See also:

0 for success, -1 for failure.

Queries the alarm time for a real time timer. The time is expressed as an offset in seconds from a known date and time (for example, midnight on January 1st, 1970) and stored in the variable pointed to by time.

osplus_rtc_timer_time_set

, osplus_rtc_timer_start, osplus_rtc_timer_stop

92/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_rtc_timer_start

Starts a real time timer

Definition:

int osplus_rtc_timer_start (osplus_rtc_timer_t *rtc_timer)

Arguments:

rtc_timer

The timer to start

Returns:

Description:

See also:

0 for success, -1 for failure.

Starts the real time timer rtc_timer. If the timer has an alarm time that is in the past, the timer fires immediately.

osplus_rtc_timer_stop

7702033 Rev 27 93/515

OSPlus support library UM1150

osplus_rtc_timer_stop

Stops a real time timer

Definition:

Arguments:

int osplus_rtc_timer_stop (osplus_rtc_timer_t *rtc_timer) rtc_timer

The timer to stop

Returns:

Description:

See also:

0 for success, -1 for failure.

Stops the real time timer, rtc_timer.

osplus_rtc_timer_start

94/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_rwlock_create

Create a read/write lock

Definition:

Arguments:

Returns:

Error values:

Description:

See also:

osplus_rwlock_t *osplus_rwlock_create (void)

None.

Returns the address of the new read/write lock, NULL for failure.

Out of memory.

osplus_rwlock_create()

creates a new read/write lock. The address of the new lock is returned.

osplus_rwlock_delete

7702033 Rev 27 95/515

OSPlus support library UM1150

osplus_rwlock_delete

Delete a read/write lock

Definition:

Arguments:

int osplus_rwlock_delete (osplus_rwlock_t *lockp) lockp

The address of the lock to delete.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Bad lock address, or the lock is still in use.

osplus_rwlock_delete()

deletes a read/write lock, provided the lock is not already taken.

osplus_rwlock_create

96/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_rwlock_downgrade

Downgrade a lock ownership from write to read

Definition:

Arguments:

int osplus_rwlock_downgrade (osplus_rwlock_t *lockp) lockp

The address of the lock.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Bad lock address, or the caller does not own the lock as a writer.

osplus_rwlock_downgrade()

downgrades a task’s ownership of the lock from writer to reader. This allows other readers concurrent access to the lock.

osplus_rwlock_tryupgrade

7702033 Rev 27 97/515

OSPlus support library UM1150

osplus_rwlock_enter

Enter a read/write locked section

Definition:

int osplus_rwlock_enter (

osplus_rwlock_t *lockp,

int writer)

Arguments:

lockp writer

The address of the lock to acquire.

A flag indicating whether the caller wants read or write access.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Bad lock address.

osplus_rwlock_enter()

acquires the given read/write lock as either a reader or a writer. The writer parameter should be 0 to acquire the lock as a reader, or nonzero to acquire it as a writer. If the lock is not immediately available, the caller is blocked until the lock is available.

osplus_rwlock_leave

, osplus_rwlock_tryenter

98/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_rwlock_leave

Exit a read/write locked section

Definition:

Arguments:

int osplus_rwlock_leave (osplus_rwlock_t *lockp) lockp

The address of the lock to release.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid lock specified.

osplus_rwlock_leave()

causes the caller to exit a read/write lock protected region. The lock is given to any tasks that are waiting to acquire the lock, following the rules of read/write lock ownership. If both readers and writers are waiting to acquire the lock, the decision to pass the lock to the readers or the first writer is made on a fair turn-taking basis.

osplus_rwlock_enter

7702033 Rev 27 99/515

OSPlus support library UM1150

osplus_rwlock_tryenter

Try to enter a read/write locked section

Definition:

int osplus_rwlock_tryenter (

osplus_rwlock_t *lockp,

int writer)

Arguments:

lockp writer

The address of the lock to acquire.

A flag indicating whether the caller wants read or write access.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Bad lock address or lock is not immediately available.

osplus_rwlock_tryenter()

attempts to acquire the given read/write lock as either a reader or writer. If the lock is not immediately available the call fails. The writer

parameter should be 0 to acquire the lock as a reader, or non-zero to acquire it as a writer.

osplus_rwlock_enter

, osplus_rwlock_leave

100/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_rwlock_tryupgrade

Attempt to upgrade a read/write lock acquisition from read to write

Definition:

Arguments:

int osplus_rwlock_tryupgrade (osplus_rwlock_t *lockp) lockp

The address of the lock to upgrade.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid lock address, or upgrade is not possible.

osplus_rwlock_tryupgrade()

attempts to upgrade a read/write lock (held by the caller as a reader) to a lock held as a writer. If the lock is held only by the caller, or there are no waiting writers, the upgrade is possible.

osplus_rwlock_downgrade

7702033 Rev 27 101/515

OSPlus support library UM1150

osplus_strdup

Duplicate the given string

Definition:

Arguments:

char *osplus_strdup (const char *original) original

The string to duplicate.

Returns:

Error values:

Description:

See also:

Returns the address of the duplicated string, or NULL.

Out of memory.

This function duplicates the given string. It is the caller’s responsibility to free the memory used for the duplicated string when it is no longer needed.

osplus_strpre

, osplus_strsep

102/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_strpre

Create a new string by prepending one string on another

Definition:

char *osplus_strpre (

const char *str,

const char *prefix)

Arguments:

str prefix

The string on which to prepend prefix.

The prefix string.

Returns:

Error values:

Description:

See also:

Returns the address of the new string, or NULL.

Out of memory.

This function creates a new string by prepending prefix onto str. It is the caller’s responsibility to free the memory used for the new string when it is no longer needed.

osplus_strdup

, osplus_strsep

7702033 Rev 27 103/515

OSPlus support library UM1150

osplus_strsep

Tokenize the given string

Definition:

char *osplus_strsep (

char **source,

const char *delimiter)

Arguments:

source delimiter

The string to tokenize.

The string containing the delimiter characters.

Returns:

Description:

See also:

Returns the address of the next token, or NULL if the source string is exhausted.

This function returns the next token from a source string (the token can be an empty string). Each token is separated by a character in the delimiter string. The delimiter

string must not be empty but may change between calls. The source string is overwritten by this function (each delimiter found is replaced by NULL, and source

is updated to point to the next character after the NULL). If there are no more tokens to be returned from the source string, NULL is returned.

osplus_strdup

, osplus_strpre

104/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_timer_create

Create a timer

Definition:

osplus_timer_t *osplus_timer_create (

void (*callback)(osplus_timer_t *, void *),

osclock_t period,

osplus_timer_flags_t flags,

void *cookie)

Arguments:

callback period flags cookie

The function to call when the timer expires.

The period of the timer.

The timer flag indicating a periodic or single shot timer.

The user-supplied parameter to pass to the callback event.

Returns:

Description:

See also:

Returns the created timer on success, or NULL on failure.

This function creates a new timer with the specified period and flags and stores the callback address and associated cookie. If the create fails, NULL is returned.

Valid flags values are osplus_timer_flags_periodic and osplus_timer_flags_one_shot

. The callback function is called with the timer id and user provided cookie when the timer expires.

Note: This function does not start the timer, this must be done with a separate call to

osplus_timer_start()

.

osplus_timer_delete

, osplus_timer_start

7702033 Rev 27 105/515

OSPlus support library

osplus_timer_delete

Delete a timer

Definition:

Arguments:

void osplus_timer_delete (osplus_timer_t *timer) timer

The timer to delete.

Returns:

Description:

See also:

None.

This function stops the timer if it is running and deletes the timer handle.

osplus_timer_create

UM1150

106/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_timer_period

Return the timer period

Definition:

Arguments:

osclock_t osplus_timer_period (osplus_timer_t *timer) timer

The timer.

Returns:

Description:

See also:

Returns the current period of the timer, or 0 on failure.

This function returns the current period of the specified timer or 0 on failure.

osplus_timer_period_set

7702033 Rev 27 107/515

OSPlus support library UM1150

osplus_timer_period_set

Set the timer period

Definition:

osclock_t osplus_timer_period_set (

osplus_timer_t *timer,

osclock_t period)

Arguments:

timer

The timer.

period

The new period.

Returns:

Description:

See also:

Returns the old period of the timer, or 0 on failure.

This function sets the period of the timer to the new period value and returns the old value or 0 on failure.

osplus_timer_period

108/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_timer_start

Start a timer

Definition:

Arguments:

void osplus_timer_start (osplus_timer_t *timer) timer

The timer to start.

Returns:

Description:

See also:

None.

This function starts the timer. The callback routine that was specified when the timer was created is called when the timer expires. The parameters passed to this routine are the timer id and the user provided cookie that was specified at timer creation.

Periodic timers are automatically restarted each time they expire and therefore only require a single call to osplus_timer_start().

osplus_timer_create

, osplus_timer_stop

7702033 Rev 27 109/515

OSPlus support library

osplus_timer_stop

Stop a timer

Definition:

Arguments:

void osplus_timer_stop (osplus_timer_t *timer) timer

The timer to stop.

Returns:

Description:

See also:

None.

This function stops the timer.

osplus_timer_start

UM1150

110/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_uncached

Determine whether the memory region is uncached

Definition:

int osplus_uncached (

void *address,

size_t size)

Arguments:

address size

The address of the memory region.

The size of the memory region.

Returns:

Description:

See also:

Returns 0 if the memory region is cached, or 1 if the region is uncached.

This function looks through a list of all uncached memory regions registered with the uncached manager and checks if the memory region specified is contained within one of those regions. If the region is identified as wholly fitting within an uncached region the function returns 1. If the region does not wholly fit into a registered uncached memory region then 0 is returned. If an uncached region has not been registered, then a call to this function is invalid.

osplus_uncached_register

, osplus_uncached_unregister

7702033 Rev 27 111/515

OSPlus support library UM1150

osplus_uncached_register

Register an uncached memory region

Definition:

int osplus_uncached_register (

void *address,

size_t size)

Arguments:

address size

The address of the memory region.

The size of the memory region.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Out of memory.

This function registers an uncached memory region. When registered, a buffer in this memory region can be identified as uncached through the osplus_uncached() call.

osplus_uncached

, osplus_uncached_unregister

112/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_uncached_unregister

Unregister an uncached memory region

Definition:

int osplus_uncached_unregister (

void *address,

size_t size)

Arguments:

address size

The address of the memory region.

The size of the memory region.

Returns:

Error values:

Description:

See also:

Returns 0 for success, -1 for failure.

Invalid parameters.

This function unregisters an uncached memory region. When unregistered, buffers in the memory region are no longer identifiable as uncached through the osplus_uncached()

call.

osplus_uncached_register

, osplus_uncached

7702033 Rev 27 113/515

OSPlus support library UM1150

osplus_version

Description:

Definition:

Arguments:

Get the specified component version string const char *osplus_version (const char *module) module

Get the version for the module with this name.

Returns:

Error values:

Description:

See also:

Returns a string consisting of the specified module version, or NULL on error.

Invalid parameters or out of memory.

Get the version string for the module with the specified name. If the version number has not been set for the module then NULL is returned. osplus_version_set

114/515 7702033 Rev 27

UM1150 OSPlus support library

osplus_version_set

Set the specified component version string

Definition:

int osplus_version_set (

const char *module,

const char *version)

Arguments:

module version

Set the version for the module with this name.

The version string for the module.

Returns:

Error values:

Returns 0 for success, -1 for failure.

Invalid parameters or out of memory.

Description:

Sets the version string for the module with the specified name. If the version number already exists, it is overwritten.

Note: A list of the OSPlus module names can be found in include/osplus/version.h.

See also:

osplus_version

7702033 Rev 27 115/515

OSPlus support library UM1150

time_ticks_per_sec

Return the number of clock ticks per second

Definition:

Arguments:

Returns:

Description:

osclock_t time_ticks_per_sec (void)

None.

Returns the number of ticks.

This function is provided on OS20 platforms only, and is provided for compatibility with OS21. It returns the number of clock ticks per second.

116/515 7702033 Rev 27

UM1150

3 OSPlus registry library

3.1

OSPlus registry library

Registry library overview

The OSPlus registry library provides a mechanism so name/value pairs can be freely stored and queried.

3.2 The registry structure

The registry presents a tree of nodes. A node can contain an arbitrary collection of keys

(name/value pairs) and child nodes. Registry nodes are addressed by a slash-separated path name, just like files in a file system. Registry path names exist in their own namespace, separate from any file systems. All node paths used in the API are absolute, this means they must start with a /.

The data stored in registry keys can be either a literal value (such as an integer) or a block of memory. When using memory block type keys, the data stored in the key is copied into an internal registry buffer when the key’s value is set. It is copied out of the registry’s internal buffer into a user buffer when the key’s value is queried.

There is a unique registry library provided for each supported platform. Because each variant of the registry contains many platform-specific values, it is essential the correct version of the registry library is used when linking an application.

3.4 The registry API

3.4.1 Nodes

Nodes in the registry are created with the registry_node_create() call, and destroyed with registry_node_delete(). registry_node_delete() not only deletes the node, it also deletes all its keys and any nodes that are children of the node. The existence of a given node can be queried with the registry_node() call. It is also possible to wait for a node to come into existence with the registry_node_timeout() call. It is possible to iterate over the child nodes of a particular node with the registry_node_next() call.

3.4.2 Keys

Keys can be created in a node with the registry_key_set() and registry_key_data_set()

calls. registry_key_set() allows a literal value to be used as the value for a key, and registry_key_data_set() allows a block of memory to be used as the value for a key. Where a block of memory is used as the key value, the registry allocates its own internal buffer and copies the user data into that buffer.

Keys can be removed from a registry node with the registry_key_delete() call. If the value of the key was a block of memory, the internal memory buffer is freed at this point. The existence of a literal value key, and its value can be found with the registry_key() call.

The registry_key_data() call does the same job for keys that have a memory block

7702033 Rev 27 117/515

OSPlus registry library UM1150

value. Both these calls fail if the key does not exist. registry_key_timeout() and registry_key_data_timeout()

can be used instead, to wait for the key to come into existence if it does not currently exist.

It is possible to iterate over all the keys within a given node with registry_key_next().

3.5 Registry library header file: registry.h

All definitions relating to the registry are in the file registry.h.

Table 9.

Functions defined in registry.h

Function

registry_key() registry_key_data() registry_key_data_set() registry_key_data_timeout() registry_key_delete() registry_key_next() registry_key_set() registry_key_timeout() registry_load_data() registry_node() registry_node_create() registry_node_delete() registry_node_next() registry_node_timeout()

Description

Return the value of a literal key

Return the value of a memory block key

Set the value of a memory block key

Return the value of a memory block key, waiting if it does not exist

Delete a key

Return the name of the next key in a given node

Set the value of a literal key

Return the value of a literal key, waiting if it does not exist

Load a table of data into the registry

Query whether a node exists

Create a node

Delete a node

Return the next child node of a given node

Wait with a timeout for a node to exist

The data type definitions are shown in

Table 10

and the macros are in

Table 11

.

Table 10.

Types defined in registry.h

Type

registry_key_data_t registry_data_t

Description

Type to hold a registry key, value pair

Type to hold a registry node path and list of key, value pairs

118/515 7702033 Rev 27

UM1150 OSPlus registry library

Table 11.

Macros defined in registry.h

Macro

registry_key_null_terminator registry_key_data registry_key_value registry_data_null_terminator

Description

Terminates a list of registry_key_t

Specifies a registry key containing data

Specifies a registry key containing a value

Terminates a list of registry_data_t

7702033 Rev 27 119/515

OSPlus registry library UM1150

3.6 Registry function definitions registry_key

Read the value of a literal value type key

Definition:

int registry_key (

const char *path,

const char *key,

void **value)

Arguments:

path key value

The name of the registry node to read.

The name of the key to read.

The location to receive the value of the key.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

registry_key()

reads the value of the key from the registry node called path, and places its value in the location pointed to by value. If value is NULL, then only the existence of the key is checked. If the specified key does not exist when the call is made, it returns -1. The call also fails if the key exists, but is a memory block type key rather than a literal value type key.

registry_key_timeout

, registry_key_set

120/515 7702033 Rev 27

UM1150 OSPlus registry library

registry_key_data

Read the value of a memory block type key

Definition:

int registry_key_data (

const char *path,

const char *key,

void *data,

size_t *size)

Arguments:

path key data size

The name of the registry node to read.

The name of the key to read.

Buffer to receive a copy of the value of key, or NULL.

Pointer to a value that gives the size of data on entry, and gets the number of bytes copied out on exit, or gets the size of the memory block if data is NULL.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

registry_key_data()

copies the memory block that is the value of key, from the registry node called path, into the buffer pointed to by data. If data is NULL, then only the existence of the key is checked, and the size of the stored memory block is returned through the size parameter. If the specified key does not exist when the call is made, it returns -1. The call also fails if the key exists, but is a literal value type key rather than a memory block type key.

registry_key_data_timeout

, registry_key_data_set

7702033 Rev 27 121/515

OSPlus registry library UM1150

registry_key_data_set

Store a block of memory in a key

Definition:

int registry_key_data_set (

const char *path,

const char *key,

void *data,

size_t size)

Arguments:

path key data size

The name of the registry node to set the key.

The name of the key to write.

The memory buffer to copy into the key.

The size of data in bytes.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

registry_key_data_set()

sets the value of key, in the registry node called path

, to be a copy of the data in the buffer called data. If the node or key do not already exist, they are created. registry_key_data

, registry_key_data_timeout

122/515 7702033 Rev 27

UM1150 OSPlus registry library

registry_key_data_timeout

Read the value of a memory block type key

Definition:

int registry_key_data_timeout (

const char *path,

const char *key,

void *data,

size_t *size,

osclock_t *timeout)

Arguments:

path key data size timeout

The name of the registry node to read.

The name of the key to read.

Buffer to receive a copy of the value of key, or NULL.

Pointer to a value that gives the size of data on entry, and gets the number of bytes copied out on exit, or the gets the size of the memory block if data is NULL.

The timeout specification.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

registry_key_data_timeout()

copies the memory block that is the value of key

from the registry node called path, into the buffer pointed to by data. If data is

NULL

, then only the existence of the key is checked, and the size of the stored memory block is returned through the size parameter. If the specified key does not exist when the call is made, the behavior of the call is determined by the timeout parameter. If timeout is the value TIMEOUT_IMMEDIATE, the call immediately returns -1. If the timeout value is TIMEOUT_INFINITY, the call waits indefinitely for the key to be created. Any other value is taken to be a pointer to an absolute time, beyond which the call will not wait. The call fails if the key exists, but is a literal value type of key rather than a memory block type of key.

registry_key_data

, registry_key_data_set

7702033 Rev 27 123/515

OSPlus registry library UM1150

registry_key_delete

Delete a key from a registry node

Definition:

int registry_key_delete (

const char *path,

const char *key)

Arguments:

path key

The name of the registry node where the key exists.

The name of the key to delete.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

registry_key_delete()

deletes an existing key from an existing registry node.

registry_key_set

, registry_key_data_set

124/515 7702033 Rev 27

UM1150 OSPlus registry library

registry_key_next

Return the next registry key from a node

Definition:

const char *registry_key_next (

const char *path,

const char *key)

Arguments:

path key

The name of the registry node to iterate over.

The name of the last key, or NULL.

Returns:

Description:

Returns the name of the next key or NULL.

registry_key_next()

is used to iterate over all the keys within a node. If the value of key is passed in as NULL, the name of the first key is returned. The function returns NULL when all keys have been returned.

7702033 Rev 27 125/515

OSPlus registry library UM1150

registry_key_set

Set a key to a literal value

Definition:

int registry_key_set (

const char *path,

const char *key,

void *value)

Arguments:

path key value

The name of the registry node to set the key.

The name of the key to write.

The value to write to the key.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

registry_key_set()

sets the value of key, in the registry node called path, to be value

. If the node or key do not already exist, they are created. This call is used to store a literal value as the value for a registry key.

registry_key

, registry_key_timeout

126/515 7702033 Rev 27

UM1150 OSPlus registry library

registry_key_timeout

Read the value of a literal value type key

Definition:

int registry_key_timeout (

const char *path,

const char *key,

void **value,

osclock_t *timeout)

Arguments:

path key value timeout

The name of the registry node to read.

The name of the key to read.

The location to receive the value of key.

The timeout specification.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

registry_key_timeout()

reads the value of a literal value key called key, from the registry node called path, and places its value in the location pointed to by value

. If the key specified does not exist when the call is made, the behavior of the call is determined by the timeout parameter. If timeout is the value

TIMEOUT_IMMEDIATE

, the call immediately returns -1. If the timeout value is

TIMEOUT_INFINITY

, the call waits indefinitely for the key to be created. Any other value is taken to be a pointer to an absolute time beyond which the call will not wait.

registry_key

, registry_key_set

7702033 Rev 27 127/515

OSPlus registry library UM1150

registry_load_data

Load a list of nodes into the registry

Definition:

Arguments:

int registry_load_data (registry_data_t *data) data

A null terminated list of registry node data.

Returns:

Description:

Returns 0 for success, -1 for failure.

registry_load_data()

is used to load one or more complete registry nodes into the registry. The data passed in is a null terminated list of registry node paths and key value pairs associated with the node. The data is defined by the type registry_data_t

which has the following format: typedef struct registry_data_s { const char *path;

} registry_data_t;

The fields are described in

Table 12

.

Table 12.

registry_data_t fields

path keys

Field name Description

Registry node path

Null terminated list of keys

Each entry in the registry node data list contains a null terminated list of key value pairs. This is represented by the type registry_key_data_t which has the following format: typedef struct registry_key_data_s {

128/515

} registry_key_data_t;

The fields are described in

Table 13

.

Table 13.

registry_key_data_t fields

Field name

linkage key value size attr

Description

Key list linkage - should be 0 (zero)

Key name

Value for key

Size of value if not a pointer/integer

Attribute associated with key - must be 0 (zero)

For more details about using this function, see the OSPlus custom registry example provided with the OSPlus distribution.

7702033 Rev 27

UM1150 OSPlus registry library

registry_node

Determine whether a registry node exists

Definition:

Arguments:

int registry_node (const char *path) path

The name of registry node to check.

Returns:

Description:

See also:

Returns 0 if the node exists, -1 if it does not.

registry_node()

returns whether or not the node specified by path exists. If the node does not exist when the call is made -1 is returned.

registry_node_timeout

7702033 Rev 27 129/515

OSPlus registry library UM1150

registry_node_create

Description:

Definition:

Arguments:

Create a node within the registry int registry_node_create (const char *path) path

The registry path name of the node to create.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

registry_node_create()

is used to create a new node within the registry. The path

specified must be a valid registry node name, that is, a fully qualified / (forward slash) separated name. For example:

/software/application/data

The call fails if the node already exists, the path name is invalid, or an internal error occurs. Otherwise the node is created, and initialized to contain no keys or children.

registry_node_delete

130/515 7702033 Rev 27

UM1150 OSPlus registry library

registry_node_delete

Delete an existing registry node

Definition:

Arguments:

int registry_node_delete (const char *path) path

The name of the node to delete.

Returns:

Description:

Returns 0 for success, -1 for failure.

registry_node_delete()

deletes an existing node from the registry, together with all its children and keys. If the node or any of its children have tasks waiting, the call fails.

7702033 Rev 27 131/515

OSPlus registry library UM1150

registry_node_next

Return the next child node for a parent node

Definition:

const char *device_node_next (

const char *path,

const char *child)

Arguments:

path child

The registry path name to the parent node.

The name of the current child node.

Returns:

Description:

See also:

The name of the next child node or NULL.

register_node_next()

returns the next child node within an existing registry node. The call fails if the indicated node does not exist. If the child parameter is

NULL

, this call returns the first child node, otherwise it returns the next child node.

When all children have been exhausted the call returns NULL.

registry_key_next

132/515 7702033 Rev 27

UM1150 OSPlus registry library

registry_node_timeout

Description:

Definition:

Determine whether a registry node exists int registry_node_timeout (

const char *path,

osclock_t *timeout)

Arguments:

path timeout

The name of the registry node to check.

The timeout specification.

Returns:

Description:

See also:

Returns 0 if the node exists, -1 if it does not.

registry_node_timeout()

returns whether or not the name specified by path exists. If the node does not exist when the call is made, the behavior of the call is determined by the timeout parameter. If timeout is the value

TIMEOUT_IMMEDIATE

, the call immediately returns -1. If the timeout value is

TIMEOUT_INFINITY

, the call waits indefinitely for the node to be created. Any other value is taken to be a pointer to an absolute time beyond which the call will not wait.

registry_node

7702033 Rev 27 133/515

OSPlus device model

4 OSPlus device model

4.1

UM1150

Device model overview

The OSPlus device model provides applications with a uniform view of all devices connected to the system. All the API entry points return a value indicating success or failure.

If there is a failure errno is set to an appropriate value indicating the cause of the failure.

4.2 Device driver application interface

The OSPlus device layer presents applications with a simple API for accessing devices. This

API follows the conventional open, close, read, write, ioctl style seen in many other systems.

Devices appear to the application as uniquely named entities. A device using a known name, allows an application to use the device_open_timeout() call with the timeout parameter set to TIMEOUT_INFINITY. This opens the device when its named entity comes into existence.

Alternatively, the application can be notified about a device being created or destroyed through a callback. When an application receives notification that a device has been created, it can open the device using device_open() or device_open_timeout().

Refer to

Section 4.2.3: Opening, closing and performing I/O on page 136

.

OSPlus calls register callback routines whenever a device is created or deleted.

Applications can register for these callback notifications using the call, device_callback_attach()

.

When registering for device callbacks, the application can request to be brought up to date’ with all known devices in the system. So even if devices were created before the application registered for device create/destroy callbacks, the registered callback routine is called with information describing all the currently known devices, as if they had all just been created.

An application can unregister for device callback notifications with the call device_callback_detach()

.

Note: 1 The thread context in which the callback is made is usually unknown. For notifications of normal device creation and deletion events, the context is that of the thread that created or deleted the device. For ‘sync up’ notifications (which are due to registering for callbacks with

the synchronize flag set to 1) the callback is in the context of the thread that called device_callback_attach()

. For these reasons, minimal processing should be performed on receipt of a callback notification.

2 Care must be taken with locking strategies to avoid potential deadlock situations.

STMicroelectronics recommend strongly that callback routines simply duplicate the notification information into a message, which is then sent to a message queue. A separate listener thread can then receive this notification message and process it appropriately.

134/515 7702033 Rev 27

UM1150 OSPlus device model

Note:

All devices have a type. This type is used to help distinguish between classes of devices, and therefore what a given device can do. Device types are known within OSPlus by a unique name, and an associated unique numeric value.

OSPlus defines several standard types as shown in

Table 14

.

Table 14.

Standard OSPlus device types

Device type symbolic name

OSPLUS_DEVICE_TYPE_CABLE_MODEM

OSPLUS_DEVICE_TYPE_ETHERNET

OSPLUS_DEVICE_TYPE_FIXED_STORAGE

OSPLUS_DEVICE_TYPE_KEYBOARD

OSPLUS_DEVICE_TYPE_MODEM

OSPLUS_DEVICE_TYPE_MOUSE

OSPLUS_DEVICE_TYPE_PRINTER

OSPLUS_DEVICE_TYPE_REMOVABLE_STORAGE

OSPLUS_DEVICE_TYPE_SERIAL

OSPLUS_DEVICE_TYPE_VOLUME

Device type name

"cable modem"

"ethernet"

"mass storage"

"keyboard"

"modem"

"mouse"

"printer"

"removable media storage"

"serial"

"logical volume"

USB device types are defined in the document, OSPlus USB User Manual (8018282).

The numeric value bound to a particular device type name is guaranteed to be unique for the life of the system. To discover which type value has been bound to a given device type name, the call device_type() is used. For example:

{

device_type_t disk_type;

disk_type = device_type (DEVICE_TYPE_FIXED_STORAGE);

...

}

The type for a particular device can be queried from two standard device attributes for that device, as shown in

Table 15

.

Table 15.

Device type attributes

Device attribute name

"type_name"

"type"

Attribute value

Type name for the device

Bound type value for the device

7702033 Rev 27 135/515

OSPlus device model

4.2.3

UM1150

Opening, closing and performing I/O

●

●

●

●

●

●

●

For an application to access a device it must first open that device with the device_open()

or device_open_timeout() call. These calls return a device handle to the application. The application can then use the device handle to perform I/O to the device.

When the application has finished with a device, it can close the device handle with a call to device_close()

. I/O can be performed on an open device handle with the following calls: device_read() device_write() device_ioctl() device_block_read() device_block_write() device_streaming_read() device_streaming_write()

All of the read and write calls are synchronous, that is, the caller is blocked until the requested I/O operation has completed. The blocking semantics of device_ioctl() are defined by the individual device drivers.

device_read()

and device_write() provide character oriented read and write access to devices. device_block_read(), device_block_write(), device_streaming_read()

and device_streaming_write() provide block oriented access to devices. Drivers do not need to support all these access methods. Devices are typically either character or block oriented, and so their drivers only implement the I/O access methods that are appropriate for the device. If an application calls one of these I/O routines, and the specific driver does not support that type of access, the call fails returning

-1

and errno is set to ENOTSUP.

Some types of device (for instance some ATAPI-7 compliant devices) support a special form of block I/O known as streaming. This is similar to normal block I/O access, except the device attempts to read or write its I/O data as fast as possible, or by a given deadline. Error recovery is sacrificed in favor of fast access, so the data returned may have errors in it. This is typically used when reading or writing streams of video data where occasional errors are acceptable, but long pauses in the delivery of data is not. If a block device does not support this type of access method, the driver can safely implement streaming accesses as normal block accesses.

OSPlus specifies several standard ioctl functions for block devices, ethernet devices, keyboard devices, mouse devices and serial devices, as well as several ioctls common to all device classes. By including device.h, all common ioctls are available. To use the ethernet, keyboard, mouse and serial ioctls, you must include ioctls/ethernet.h, ioctls/keyboard.h

, ioctls/mouse.h, and ioctls/serial.h respectively.

More information about ioctls is given the specific device chapters, and in

Section 4.10:

Device driver ioctl definitions on page 146

.

136/515 7702033 Rev 27

UM1150 OSPlus device model

4.2.5 Starting stopping devices

Some devices support hot plugging (the ability to insert or remove the device into a running system), for example USB devices. The device_stop() and device_stop_timeout() calls allow for safe extraction to take place. These calls prevent further opens of the device in question, and return when all open handles on the device have been closed (or a timeout occurs using device_stop_timeout()). Following the successful return of one of these calls, the device can be safely removed. While in the stopped state, it is not possible to open the device. It can be restarted with the device_start() call, which permits subsequent opens of the device to succeed.

Information about a device is held in the form of device attributes. These are stored as arbitrary name/value pairs in the registry. They can either have literal values (such as an integer value), or have memory block values (such as a string). The value of a device attribute is retrieved with device_attribute() for literal value attributes, and device_attribute_data()

for memory block attributes. Use device_attribute_set()

to set an attribute’s value to be a literal. Use device_attribute_data_set()

to set an attribute’s value to be a block of memory. An attribute is destroyed with device_attribute_delete(). All attributes associated with a device are implicitly deleted when the device is deleted.

Standard device attributes

OSPlus automatically creates two standard device attributes whenever a new device instance is created: type_name a memory block type attribute, giving the type name associated with the class of device type a literal value type attribute, giving the type value bound to the type name

The type or type name for any device instance can be discovered simply by querying that instance’s type or type_name attribute.

Whether a given device instance supports any other device attributes, depends on the device driver which instantiated the device, or other code in the system.

7702033 Rev 27 137/515

OSPlus device model

4.3

UM1150

Device driver writer interface

The OSPlus device driver layer allows for an arbitrary number of device drivers to register with it to present device instances to the client application. The calls in this interface are prefixed with ‘dev_’ instead of ‘device_’ to differentiate them from the standard user API calls.

An OSPlus device class is used to describe a device driver to the device layer. The call dev_class_create()

is used to create and register a device class with the device driver layer. This call takes two parameters, an ASCII representation of the device type this driver provides (one of the predefined DEVICE_TYPE_* macros, or a driver defined value) and a structure describing the methods provided by the device driver and some optional information the device driver layer can use to optimize seek access times on block devices.

Device classes can be destroyed by the dev_class_delete() call.

A successful call to dev_create_class() returns the address of a new device class structure. This can then be used in subsequent calls to dev_instance_create() to create new instances of this device class. An instantiation of a device class through this call creates a device instance, which the user application is notified of through the callback mechanism. In addition to the device class, dev_instance_create() also takes the name by which the new device is to be known and an opaque value that is passed to the device driver’s create method. The device driver layer attaches no special meaning to this third parameter, so device drivers can use it for their own purposes (for example, pointer to instance data).

Device instances can be destroyed with calls to dev_instance_delete(), which simply takes the name of the device instance to destroy. Any registered device callback routines are notified of the device’s demise by this call.

Devices that support block I/O access can request the device driver layer performs seek order optimization of all I/O requests that it receives. This is done using the elevator parameters portion of the parameter information passed into dev_class_create(). Seek optimization can yield significant performance advantages if the device being accessed (for example, a hard disk drive) has relatively poor seek performance compared to I/O performance. See

Section : dev_class_create on page 174

for details of setting up seek optimization for a device.

138/515 7702033 Rev 27

UM1150

4.4

OSPlus device model

Device library header file: device.h

All the definitions relating to the user interface to device drivers are in the file device.h.

The functions defined in device.h are explained in

Section 4.11: Device driver function definitions on page 174

.

Table 16.

Functions defined in device.h

Function

device_attribute() device_attribute_data() device_attribute_delete() device_attribute_set() device_attribute_data_set() device_block_read() device_block_write() device_callback_attach() device_callback_detach() device_close() device_ioctl() device_open() device_open_timeout() device_read() device_start() device_stop() device_stop_timeout() device_streaming_read() device_streaming_write() device_type() device_write()

Description

Reads the named attribute for a device

Reads the named attribute for a device

Deletes the named attribute from a device

Sets the value of the named attribute for a device

Sets the value of the named attribute for a device

Reads blocks from the device

Writes blocks to the device

Registers a callback with the device library

Unregisters a callback with the device library

Closes the named device

Performs a function on the device

Opens the named device

Opens the named device, waiting if it does not exist

Reads characters from the device

Allows I/O to the named device

Checks to see if the device has no open handles

Waits for the device to be fully closed or for a timeout

Streams blocks from the device

Streams blocks to the device

Gets the bound type value for a given type name

Write characters to the device

Table 17.

Types defined in device.h

Type

device_callback_t device_event_t device_handle_t device_notify_t device_type_t lba_t

Description

Prototype for user callback function

Events for which callbacks are made

Handle to an open device instance

Description of callback notification

Value bound to a given device type name

Logical block address

7702033 Rev 27 139/515

OSPlus device model

Table 18.

Macros defined in device.h

Macro

OSPLUS_DEVICE_TYPE_*

Description

OSPlus type names, see

Table 14 on page 135

UM1150

4.5 Device library header file: dev.h

All the definitions relating to the device driver writer’s interface are in the file dev.h. The functions defined in dev.h are explained in

Section 4.11: Device driver function definitions on page 174

.

Table 19.

Functions defined in dev.h

Function

dev_class_create() dev_class_delete() dev_instance_create() dev_instance_delete()

Description

Create a new driver class

Delete a driver class

Create a device instance

Delete a device instance

Table 20.

Types defined in dev.h

Type

dev_class_t dev_elevator_params_t dev_handle_t dev_instance_t dev_ops_t dev_params_t

Description

Device class

Elevator seek options for a device driver

Device handle

Device instance

Method table for a device driver

Description of new device class

4.6 Device library header file: ioctls/common.h

The device library defines a set of ioctls that are used by ethernet devices. These ioctls are

in the file ioctls/common.h. For the ioctl definitions, see

Section 4.10.1 on page 146

.

Table 21.

Ioctls defined in ioctls/common.h

Ioctl

OSPLUS_IOCTL_ABORT_RD

OSPLUS_IOCTL_ABORT_WR

OSPLUS_IOCTL_ATA_PASS_THROUGH

OSPLUS_IOCTL_BLOCK_SIZE

OSPLUS_IOCTL_CHECK_MEDIA

OSPLUS_IOCTL_CLR_ERROR

Description

Abort any current read operation

Abort any current write operation

Issue an ATA pass-through command

Query the size in bytes of the logical blocks supported by the device

Query the status of the media

Clear the error information for a device

140/515 7702033 Rev 27

UM1150 OSPlus device model

Table 21.

Ioctls defined in ioctls/common.h (continued)

Ioctl Description

OSPLUS_IOCTL_CLR_STATUS

OSPLUS_IOCTL_FLUSH

OSPLUS_IOCTL_GET_ERRORS

OSPLUS_IOCTL_GET_FEATURES

OSPLUS_IOCTL_GET_PID

OSPLUS_IOCTL_GET_PID_STR

OSPLUS_IOCTL_GET_RD_MODE

OSPLUS_IOCTL_GET_RD_TIMEOUT

OSPLUS_IOCTL_GET_SERIAL

OSPLUS_IOCTL_GET_STATUS

OSPLUS_IOCTL_GET_VID

OSPLUS_IOCTL_GET_VID_STR

OSPLUS_IOCTL_GET_WR_MODE

OSPLUS_IOCTL_GET_WR_TIMEOUT

OSPLUS_IOCTL_NUM_BLOCKS

OSPLUS_IOCTL_POST_WRITES

OSPLUS_IOCTL_PURGE

OSPLUS_IOCTL_SET_RD_MODE

OSPLUS_IOCTL_SET_RD_TIMEOUT

OSPLUS_IOCTL_SET_WR_MODE

OSPLUS_IOCTL_SET_WR_TIMEOUT

OSPLUS_IOCTL_WAIT

OSPLUS_IOCTL_WC_CONTROL

OSPLUS_IOCTL_WR_PROTECTED

OSPLUS_IOCTL_PREF_IO_SIZE

OSPLUS_IOCTL_GET_POWER_MODE

OSPLUS_IOCTL_SET_POWER_MODE

OSPLUS_IOCTL_SPIN_REQUESTS

OSPLUS_IOCTL_SPIN_UP

OSPLUS_IOCTL_SPIN_DOWN

Clear the status information for a device

Perform a flush on a device

Return a device specific structure containing error information

Query the device feature set

Query the device product ID

Query the device product name

Return the current mode (blocking or non-blocking) for read operations

Return the timeout value for blocking read operations

Query the device serial number

Return a device specific structure containing device status information

Query the device vendor ID

Query the device vendor name

Return the current mode (blocking or non-blocking) for write operations

Return the timeout value for blocking write operations

Query the number of logically addressable blocks the device supports

Specify if driver performs synchronous or asynchronous writes

Perform a purge on a device

Set the mode for read operations to blocking or nonblocking

Set the timeout value for blocking read operations

Set the mode for write operations to blocking or nonblocking

Set the timeout value for blocking write operations

Block waiting for the device to receive an event

Enable or disable write caching on a device.

Query whether the device media is write protected

Query the device preferred IO size

Query the currently set device power mode

Set the power mode of a device

Query if device supports spin requests

Request device to spin up

Request device to spin down

7702033 Rev 27 141/515

OSPlus device model UM1150

Table 22.

OSPlus check media macros defined in ioctls/common.h

Macro Description

OSPLUS_MEDIA_CHANGED

OSPLUS_MEDIA_NOT_PRESENT

OSPLUS_MEDIA_PRESENT

The media has been changed in the device

The media has been removed from the device

The media is present in the device

Table 23.

OSPlus get/set read/write mode macros defined in ioctls/common.h

Macro Description

OSPLUS_MODE_BLOCKING

OSPLUS_MODE_NONBLOCKING

Set the read/write mode to blocking

Set the read/write mode to non-blocking

Table 24.

OSPlus flush/purge buffer macros defined in ioctls/common.h

Macro Description

OSPLUS_READ_BUFFER

OSPLUS_WRITE_BUFFER

Select the device read buffers

Select the device write buffers

Table 25.

Types defined in ioctls/common.h

Type

osplus_str_t

String type

Description

This device library defines a set of ioctls that are used by joystick devices. These ioctls are

in the file ioctls/joystick.h. For the ioctl definitions, refer to

Section 4.10.2 on page

157

.

Table 26.

Ioctls defined in ioctls/joystick.h

Ioctl

OSPLUS_IOCTL_JOYSTICK_GET_X

OSPLUS_IOCTL_JOYSTICK_GET_X_BND

OSPLUS_IOCTL_JOYSTICK_GET_Y

OSPLUS_IOCTL_JOYSTICK_GET_Y_BND

OSPLUS_IOCTL_JOYSTICK_GET_Z

OSPLUS_IOCTL_JOYSTICK_GET_Z_BND

OSPLUS_IOCTL_JOYSTICK_GET_RX

OSPLUS_IOCTL_JOYSTICK_GET_RX_BND

OSPLUS_IOCTL_JOYSTICK_GET_RY

OSPLUS_IOCTL_JOYSTICK_GET_RY_BND

OSPLUS_IOCTL_JOYSTICK_GET_RZ

OSPLUS_IOCTL_JOYSTICK_GET_RZ_BND

OSPLUS_IOCTL_JOYSTICK_SLIDER

OSPLUS_IOCTL_JOYSTICK_SLIDER_BND

Description

Get the joystick X value

Get the range of joystick X value

Get the joystick Y value

Get the range of the joystick Y value

Get the joystick Z value

Get the range of joystick Z value

Get the joystick rX value

Get the range of joystick rX value

Get the joystick rYvalue

Get the range of joystick rY value

Get the joystick rZ value

Get the range of joystick rZ value

Get the joystick slider value

Get the range of joystick slider value

142/515 7702033 Rev 27

UM1150 OSPlus device model

Table 26.

Ioctls defined in ioctls/joystick.h

Ioctl

OSPLUS_IOCTL_JOYSTICK_HAT_SWITCH

OSPLUS_IOCTL_JOYSTICK_BTN_COUNT

OSPLUS_IOCTL_JOYSTICK_BTN_BITMAP

OSPLUS_IOCTL_JOYSTICK_ALL_

VALUES

OSPLUS_IOCTL_JOYSTICK_SET_RUMBLE

Description

Get the joystick hat switch value

Get the number of buttons on the joystick

Get the bitmap of what buttons are pressed

Fill an array with all joystick values

Set the amount of force feedback

Table 27.

OSPlus joystick feature defines in ioctls/joystick.h

Macro Description

OSPLUS_FEATURE_JOYSTICK_X

OSPLUS_FEATURE_JOYSTICK_Y

Joystick has X axis

Joystick has Y axis

Joystick has Z axis

OSPLUS_FEATURE_JOYSTICK_Z

OSPLUS_FEATURE_JOYSTICK_XYZ

OSPLUS_FEATURE_JOYSTICK_RX

OSPLUS_FEATURE_JOYSTICK_RY

OSPLUS_FEATURE_JOYSTICK_RZ

OSPLUS_FEATURE_JOYSTICK_RXRYRZ

Joystick has X, Y and Z axis

Joystick has rX axis

Joystick has rY axis

Joystick has rZ axis

Joystick has rX, rY and rZ axis

OSPLUS_FEATURE_JOYSTICK_SLIDER

Joystick has a slider

OSPLUS_FEATURE_JOYSTICK_HAT_SWITCH

Joystick has a hat switch

OSPLUS_FEATURE_JOYSTICK_BUTTONS

Joystick has buttons

OSPLUS_FEATURE_JOYSTICK_RUMBLE

Joystick has force feedback (rumble)

Table 28.

OSPlus joystick hat switch defines in ioctls/joystick.h

Macro Description

OSPLUS_HAT_SWITCH_UP

OSPLUS_HAT_SWITCH_UP_RIGHT

OSPLUS_HAT_SWITCH_RIGHT

OSPLUS_HAT_SWITCH_DOWN_RIGHT

OSPLUS_HAT_SWITCH_DOWN

OSPLUS_HAT_SWITCH_DOWN_LEFT

OSPLUS_HAT_SWITCH_LEFT

OSPLUS_HAT_SWITCH_UP_LEFT

Hat switch is pressed up

Hat switch is pressed up and right

Hat switch is pressed right

Hat switch is pressed down and right

Hat switch is pressed down

Hat switch is pressed down and left

Hat switch is pressed left

Hat switch is pressed up and left

Table 29: OSPlus miscellaneous defines in ioctls/joystick.h

Macro Description

OSPLUS_JOYSTICK_BUTTON_x(x)

OSPLUS_JOYSTICK_SET_RUMBLE(l,r)

Bit position corresponding to button x

Encode left and right rumble values

7702033 Rev 27 143/515

OSPlus device model

4.7

UM1150

Device library header file: ioctls/keyboard.h

This device library defines the set of ioctls used by keyboard devices. These ioctls are in the

file ioctls/keyboard.h. For the ioctl definitions, refer to

Section 4.10.3 on page 162

.

Table 30.

Ioctls defined in ioctls/keyboard.h

Ioctl

OSPLUS_IOCTL_KEYBOARD_COUNT

OSPLUS_IOCTL_KEYBOARD_GETKEY

Description

Return the number of key presses buffered

Return a key press

4.8 Device library header file: ioctls/mouse.h

This device library defines a set of ioctls that are used by mouse devices. These ioctls are in the file ioctls/mouse.h. For the ioctl definitions, see

Section 4.10.4 on page 163

.

Table 31.

Ioctls defined in ioctls/mouse.h

Ioctl Description

OSPLUS_IOCTL_MOUSE_GET_X

OSPLUS_IOCTL_MOUSE_SET_X

OSPLUS_IOCTL_MOUSE_GET_X_BND

OSPLUS_IOCTL_MOUSE_SET_X_BND

OSPLUS_IOCTL_MOUSE_GET_Y

OSPLUS_IOCTL_MOUSE_SET_Y

OSPLUS_IOCTL_MOUSE_GET_Y_BND

OSPLUS_IOCTL_MOUSE_SET_Y_BND

Get the mouse X axis position

Set the mouse X axis position

Get the mouse X axis bounds

Set the mouse X axis bounds

Get the mouse Y axis position

Set the mouse Y axis position

Get the mouse Y axis bounds

Set the mouse Y axis bounds

Get the mouse X and Y axis position

OSPLUS_IOCTL_MOUSE_GET_XY

OSPLUS_IOCTL_MOUSE_SET_XY

OSPLUS_IOCTL_MOUSE_GET_XY_BND

OSPLUS_IOCTL_MOUSE_SET_XY_BND

Set the mouse X and Y axis position

Get the mouse X and Y axis bounds

Set the mouse X and Y axis bounds

OSPLUS_IOCTL_MOUSE_GET_WHEEL

OSPLUS_IOCTL_MOUSE_SET_WHEEL

Get the mouse wheel position

Set the mouse wheel position

Get the mouse wheel bounds

OSPLUS_IOCTL_MOUSE_GET_WHEEL_BND

OSPLUS_IOCTL_MOUSE_SET_WHEEL_BND

OSPLUS_IOCTL_MOUSE_GET_TWHEEL

OSPLUS_IOCTL_MOUSE_SET_TWHEEL

Set the mouse wheel bounds

Get the mouse tilt wheel position

Set the mouse tilt wheel position

OSPLUS_IOCTL_MOUSE_GET_TWHEEL_BND

Get the mouse tilt wheel bounds

OSPLUS_IOCTL_MOUSE_SET_TWHEEL_BND

Set the mouse tilt wheel bounds

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

Get the mouse button count

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

Get the mouse button press bitmap

144/515 7702033 Rev 27

UM1150 OSPlus device model

Table 31.

Ioctls defined in ioctls/mouse.h (continued)

Ioctl Description

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

Get the mouse button press and release data

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

Clear the mouse button press and release data

Get the mouse button press data

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

Clear the mouse button press data

OSPLUS_IOCTL_MOUSE_GET_BTN_RELEASE

Get the mouse button release data

OSPLUS_IOCTL_MOUSE_CLR_BTN_RELEASE

Clear the mouse button release data

OSPLUS_IOCTL_MOUSE_GET_ALL_VALUES

Get all mouse values for X, Y, wheel, tilt wheel and button bitmap

Table 32.

OSPlus mouse features defined in ioctls/mouse.h

Ioctl Description

OSPLUS_FEATURE_MOUSE_X

OSPLUS_FEATURE_MOUSE_Y

OSPLUS_FEATURE_MOUSE_XY

OSPLUS_FEATURE_MOUSE_WHEEL

OSPLUS_FEATURE_MOUSE_TILT_WHEEL

OSPLUS_FEATURE_MOUSE_BUTTONS

Mouse has X axis

Mouse has Y axis

Mouse has X and Y axis

Mouse has a wheel

Mouse has a tilt wheel

Mouse has buttons

4.9 USB device library

The USB device library is covered in the document, OSPlus USB User Manual (8018282).

7702033 Rev 27 145/515

OSPlus device model UM1150

4.10 Device driver ioctl definitions

4.10.1 Device driver common ioctl definitions

Note:

These common ioctl definitions relate to the device_ioctl() call. See

device_ioctl on page 192

for more details.

Not all devices support every common ioctl. Refer to the appropriate device chapter for a list of supported ioctls.

OSPLUS_IOCTL_ABORT_RD

Abort the current read operation

Arguments:

Returns:

Description:

See also:

None.

Returns 0 for success, -1 for failure.

This ioctl attempts to abort any current read operation on the device.

OSPLUS_IOCTL_ABORT_WR

OSPLUS_IOCTL_ABORT_WR

Abort the current write operation

Arguments:

Returns:

Description:

See also:

None.

Returns 0 for success, -1 for failure.

This ioctl attempts to abort any current write operation on the device.

OSPLUS_IOCTL_ABORT_RD

146/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_ATA_PASS_THROUGH

Issue an ATA pass-through command

Arguments:

Returns:

Description:

The address of an osplus_ata_pass_through_t structure containing the command to send.

Returns 0 for success, -1 for failure.

This ioctl allows the user to issue an ATA pass-through command to a device. The osplus_ata_pass_through_t

passed in contains the details of the ATA command and whether it is a read or write. The spin_down example shows how to use this ioctl.

The parameter structure has the following format: typedef struct osplus_ata_pass_through_s { unsigned char operation; unsigned char unsigned char parameters[2]; features; unsigned char unsigned char unsigned char unsigned char sector_count; lba[3]; device; command; unsigned char unsigned char int void reserved; control; direction;

*buffer; unsigned int

} osplus_ata_pass_through_t; length;

Table 33

describes the fields in this structure.

Table 33.osplus_ata_pass_through_s fields

Field name Description

operation parameters features sector_count lba device command reserved control direction buffer length

Set to OSPLUS_ATA_PASS_THROUGH.

Defined in the ATA Pass-Through specification.

Defined in the ATA Pass-Through specification.

Defined in the ATA Pass-Through specification.

Defined in the ATA Pass-Through specification.

Defined in the ATA Pass-Through specification.

Defined in the ATA Pass-Through specification.

Set to 0.

Defined in the ATA Pass-Through specification.

Indicates whether the operation is a write or a read.

A pointer to the buffer to read from or write to. If there is no data, then this must be null.

The length of the buffer passed in. If the buffer is null, then this must be 0.

Note: The ATA Pass-Through specification is available from www.t10.org/ftp/t10/document.04/04-262r8.pdf

7702033 Rev 27 147/515

OSPlus device model UM1150

OSPLUS_IOCTL_BLOCK_SIZE

Query the size in bytes of the logical blocks

Arguments:

Returns:

Description:

See also:

A pointer to an integer in memory to receive the size in bytes of the logical blocks.

Returns 0 for success, -1 for failure.

This ioctl queries the size in bytes of the logical blocks supported by the device.

OSPLUS_IOCTL_NUM_BLOCKS

OSPLUS_IOCTL_CHECK_MEDIA

Query the status of the media

Arguments:

Returns:

Description:

A pointer to an integer in memory to receive the status of the media.

Returns 0 for success, -1 for failure.

This ioctl queries the status of the media. This can be:

OSPLUS_MEDIA_CHANGED

The media has been changed in the device

OSPLUS_MEDIA_NOT_PRESENT

The media has been removed from the device

OSPLUS_MEDIA_PRESENT

The media is present in the device

See also:

OSPLUS_IOCTL_WR_PROTECTED

OSPLUS_IOCTL_CLR_ERRORS

Reset the current device error information to its initial values

Arguments:

Returns:

Description:

See also:

None.

Returns 0 for success, -1 for failure.

This ioctl resets the error information associated with a device to its default state.

OSPLUS_IOCTL_GET_ERRORS

OSPLUS_IOCTL_CLR_STATUS

Reset the current device specific status information to its initial values

Arguments:

Returns:

Description:

None.

Returns 0 for success, -1 for failure.

This ioctl resets the specific status information associated with a device to its default state.

See also:

OSPLUS_IOCTL_GET_STATUS

148/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_FLUSH

Flush any device buffers

Arguments:

Returns:

Description:

See also:

An integer value of OSPLUS_READ_BUFFER to flush any read buffer or an integer value of OSPLUS_WRITE_BUFFER to flush any write buffer.

Returns 0 for success, -1 for failure.

This ioctl flushes all data from either the device read or write buffers, if available.

OSPLUS_IOCTL_PURGE

OSPLUS_IOCTL_GET_ERRORS

Return the current device error information

Arguments:

Returns:

Description:

A void pointer to a device specific structure to receive the error information.

Returns 0 for success, -1 for failure.

This ioctl retrieves the error information associated with a device. If a device supports this ioctl, the error information returned is device specific.

See also:

OSPLUS_IOCTL_CLR_ERRORS

OSPLUS_IOCTL_GET_FEATURES

Return the current device supported feature set

Arguments:

Returns:

Description:

A pointer to an integer in memory to receive a bitmap containing the device feature set.

Returns 0 for success, -1 for failure.

This ioctl retrieves a bitmap of supported features associated with a device. If a device supports this ioctl, the bitmap of supported features returned is device specific.

OSPLUS_IOCTL_GET_PID

Get the device product ID

Arguments:

Returns:

Description:

The address of a word in memory to receive the product ID.

Returns 0 for success, -1 for failure.

This ioctl passes back the device’s product ID. Where supported, this is a number assigned by the product vendor to uniquely identify the device.

OSPLUS_IOCTL_GET_PID_STR

Get the device product string

Arguments:

Returns:

Description:

The address of an osplus_str_t to receive the product string.

Returns 0 for success, -1 for failure.

This ioctl passes back the device’s product string. The osplus_str_t passed in receives the string length (0..255), and a copy of the string. Where supported, the product string is an ASCII description of the device.

7702033 Rev 27 149/515

OSPlus device model UM1150

OSPLUS_IOCTL_GET_POWER_MODE

Get the current power mode level

Arguments:

Returns:

Description:

A pointer to an integer in memory to receive the power mode level value.

Returns 0 for success, -1 for failure.

This ioctl returns the currently set power mode. For non-OS21 systems this is a driver specific value, and for OS21 systems this is one of the following:

OS21_POWER_LEVEL_ON

Power is on

OS21_POWER_LEVEL_ACTIVE

_STANDBY

All devices that are capable of low power mode are in low power mode (for example, an ethernet device may be in “wake on lan” mode)

OS21_POWER_LEVEL_PASSIVE

_STANDBY

All devices are powered down

See also:

OSPLUS_IOCTL_SET_POWER_MODE

OSPLUS_IOCTL_GET_RD_MODE

Retrieve the blocking mode associated with a read operation

Arguments:

Returns:

Description:

A pointer to an integer in memory to receive the blocking mode value.

Returns 0 for success, -1 for failure.

This ioctl copies the blocking mode associated with a read operation, supported by the device to the integer whose address in memory is passed in. This can be:

OSPLUS_MODE_NONBLOCKING

The device reads are non-blocking.

OSPLUS_MODE_BLOCKING

The device reads are blocking.

See also:

OSPLUS_IOCTL_SET_RD_MODE

, OSPLUS_IOCTL_GET_WR_MODE,

OSPLUS_IOCTL_SET_WR_MODE

OSPLUS_IOCTL_GET_RD_TIMEOUT

Return the timeout associated with a read operation

Arguments:

Returns:

Description:

See also:

A pointer to an osclock_t in memory to receive the timeout value.

Returns 0 for success, -1 for failure.

This ioctl returns the timeout associated with a read operation, supported by the device.

OSPLUS_IOCTL_SET_RD_TIMEOUT

, OSPLUS_IOCTL_GET_WR_TIMEOUT,

OSPLUS_IOCTL_SET_WR_TIMEOUT

150/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_GET_SERIAL

Get the device serial number

Arguments:

Returns:

Description:

The address of an osplus_str_t to receive the serial number.

Returns 0 for success, -1 for failure.

This ioctl passes back the device’s serial number. The osplus_str_t passed in receives the string length (0..255), and a copy of the string. Where supported, the serial number is an ASCII string assigned by the device vendor.

OSPLUS_IOCTL_GET_STATUS

Return the current device specific status information

Arguments:

Returns:

Description:

A void pointer to a device specific structure to receive the status information.

Returns 0 for success, -1 for failure.

This ioctl retrieves status information associated with a device. For example, the receive/transmit statistics of an ethernet device.

See also:

OSPLUS_IOCTL_CLR_STATUS

OSPLUS_IOCTL_GET_VID

Get the device vendor ID

Arguments:

Returns:

Description:

The address of a word in memory to receive the vendor ID.

Returns 0 for success, -1 for failure.

This ioctl passes back the device’s vendor ID. Where supported, the vendor ID is a number which uniquely identifies the device’s vendor.

OSPLUS_IOCTL_GET_VID_STR

Get the device vendor string

Arguments:

Returns:

Description:

The address of an osplus_str_t to receive the vendor string.

Returns 0 for success, -1 for failure.

This ioctl passes back the device’s vendor string. The osplus_str_t passed in receives the string length (0..255), and a copy of the string. Where supported, the vendor string is the ASCII name of the device’s vendor.

7702033 Rev 27 151/515

OSPlus device model UM1150

OSPLUS_IOCTL_GET_WR_MODE

Retrieve the blocking mode associated with a write operation

Arguments:

Returns:

Description:

A pointer to an integer in memory to receive the blocking mode value.

Returns 0 for success, -1 for failure.

This ioctl copies the blocking mode associated with a write operation, supported by the device to the integer whose address in memory is passed in. This can be:

OSPLUS_MODE_NONBLOCKING

The device writes are non-blocking.

OSPLUS_MODE_BLOCKING

The device writes are blocking.

See also:

OSPLUS_IOCTL_GET_RD_MODE

, OSPLUS_IOCTL_SET_RD_MODE,

OSPLUS_IOCTL_SET_WR_MODE

OSPLUS_IOCTL_GET_WR_TIMEOUT

Return the timeout associated with a write operation

Arguments:

Returns:

Description:

See also:

A pointer to an osclock_t in memory to receive the timeout value.

Returns 0 for success, -1 for failure.

This ioctl returns the timeout associated with a write operation, supported by the device.

OSPLUS_IOCTL_GET_RD_TIMEOUT

, OSPLUS_IOCTL_SET_RD_TIMEOUT,

OSPLUS_IOCTL_SET_WR_TIMEOUT

OSPLUS_IOCTL_NUM_BLOCKS

Query the number of logically addressable blocks the device supports

Arguments:

Returns:

Description:

See also:

A pointer to an integer in memory to receive the number of logically addressable blocks.

Returns 0 for success, -1 for failure.

This ioctl queries the number of logically addressable blocks the device supports.

OSPLUS_IOCTL_BLOCK_SIZE

152/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_POST_WRITES

Set a network device to perform synchronous or asynchronous writes

Arguments:

Returns:

Description:

The value 1 or 0, to enable or disable posting writes

Returns 0 for success, -1 for failure.

By default all network devices perform synchronous writes; that is, they wait until the write has completed before returning. This ensures the packet written has really been written to the network. It does however prevent queuing of multiple writes, and therefore limits the bandwidth available on writes.

By enabling write posting (call this ioctl with a parameter of 1), the network adapter initiates the write, but does not wait for it to complete. The buffer passed for the write can be immediately re-used when the write call returns. The call returns with the write still ongoing (the driver copies the data into another buffer internally). This enables the calling software to prepare and send subsequent writes, while the original is still being written.

This can greatly increase the write performance on the network interface.

Note: Not all network devices support this ioctl.

OSPLUS_IOCTL_SET_POWER_MODE

Set the current power mode level

Arguments:

Returns:

Description:

An integer set to the power mode level value.

Returns 0 for success, -1 for failure.

This ioctl sets the power mode. For non-OS21 systems, this is a driver specific value, but for OS21 systems it is one of the following:

OS21_POWER_LEVEL_ON

Power is on

OS21_POWER_LEVEL_ACTIVE

_STANDBY

All devices that are capable of low power mode are put into low power mode (for example, an ethernet device may be put into “wake on lan” mode)

OS21_POWER_LEVEL_PASSIVE

_STANDBY

All devices are powered down

See also:

OSPLUS_IOCTL_GET_POWER_MODE

OSPLUS_IOCTL_PURGE

Purge any device buffers

Arguments:

Returns:

Description:

See also:

An integer value of OSPLUS_READ_BUFFER to purge any read buffer or an integer value of OSPLUS_WRITE_BUFFER to purge any write buffer.

Returns 0 for success, -1 for failure.

This ioctl purges all data from either the device read or write buffers, if available.

OSPLUS_IOCTL_FLUSH

7702033 Rev 27 153/515

OSPlus device model UM1150

OSPLUS_IOCTL_SET_RD_MODE

Set the blocking mode associated with a read operation

Arguments:

Returns:

Description:

A integer containing the blocking mode value.

Returns 0 for success, -1 for failure.

This ioctl sets the blocking mode associated with a read operation, supported by the device to the mode passed in. This can be:

OSPLUS_MODE_NONBLOCKING

The device reads are non-blocking.

OSPLUS_MODE_BLOCKING

The device reads are blocking.

See also:

OSPLUS_IOCTL_GET_RD_MODE

, OSPLUS_IOCTL_GET_WR_MODE,

OSPLUS_IOCTL_SET_WR_MODE

OSPLUS_IOCTL_SET_RD_TIMEOUT

Set the timeout associated with a read operation

Arguments:

Returns:

Description:

See also:

A pointer to an osclock_t in memory containing the timeout value.

Returns 0 for success, -1 for failure.

This ioctl sets the timeout associated with a read operation, supported by the device to the timeout contained in the osclock_t passed in.

OSPLUS_IOCTL_GET_RD_TIMEOUT

, OSPLUS_IOCTL_GET_WR_TIMEOUT,

OSPLUS_IOCTL_SET_WR_TIMEOUT

OSPLUS_IOCTL_SET_WR_MODE

Set the blocking mode associated with a write operation

Arguments:

Returns:

Description:

A integer containing the blocking mode value.

Returns 0 for success, -1 for failure.

This ioctl sets the blocking mode associated with a write operation, supported by the device to the mode passed in. This can be:

OSPLUS_MODE_NONBLOCKING

The device reads are non-blocking.

OSPLUS_MODE_BLOCKING

The device reads are blocking.

See also:

OSPLUS_IOCTL_GET_WR_MODE

, OSPLUS_IOCTL_GET_RD_MODE,

OSPLUS_IOCTL_SET_RD_MODE

154/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_SET_WR_TIMEOUT

Set the timeout associated with a write operation

Arguments:

Returns:

Description:

See also:

A pointer to an osclock_t in memory containing the timeout value.

Returns 0 for success, -1 for failure.

This ioctl sets the timeout associated with a write operation, supported by the device to the timeout contained in the osclock_t passed in.

OSPLUS_IOCTL_GET_RD_TIMEOUT

, OSPLUS_IOCTL_SET_RD_TIMEOUT,

OSPLUS_IOCTL_GET_WR_TIMEOUT

OSPLUS_IOCTL_SPIN_REQUESTS

Query if the device supports spin up and spin down

Arguments:

Returns:

Comments:

See also:

None.

Returns 0 for success, -1 for failure.

This ioctl queries the device to see if it supports spin up and spin down requests.

OSPLUS_IOCTL_SPIN_UP

, OSPLUS_IOCTL_SPIN_DOWN

OSPLUS_IOCTL_SPIN_UP

Request that the device spins up

Arguments:

Returns:

Comments:

See also:

None.

Returns 0 for success, -1 for failure.

This ioctl requests that the device spins up.

OSPLUS_IOCTL_SPIN_REQUESTS

, OSPLUS_IOCTL_SPIN_DOWN

OSPLUS_IOCTL_SPIN_DOWN

Request that the device spins down

Arguments:

Returns:

Comments:

See also:

None.

Returns 0 for success, -1 for failure.

This ioctl requests that the device spins down.

OSPLUS_IOCTL_SPIN_REQUESTS

, OSPLUS_IOCTL_SPIN_UP

OSPLUS_IOCTL_WAIT

Block waiting for the device to receive an event

Arguments:

Returns:

Description:

A pointer to an osclock_t in memory containing the timeout value.

Returns 0 for success or -1 when the timeout expires.

This ioctl blocks for the specific timeout, waiting for the device to receive an event. For a keyboard device this event can be a key press.

7702033 Rev 27 155/515

OSPlus device model UM1150

OSPLUS_IOCTL_WC_CONTROL

Enable or disable write caching on a device

Arguments:

Returns:

A value of zero to disable write caching, or non-zero to enable write caching.

Returns 0 for success, -1 for failure.

Description:

This ioctl controls write caching on a device. Write caching is used by devices like hard disk drives to greatly speed up write performance. Write caching is vulnerable to data loss in the event of power loss, if the written data has not been committed to the device’s non-volatile storage medium. It is recommended the write caching is disabled on any devices that are used to store critical data.

Note: Not all devices have write caches, or allow control of their write caches.

There is often a large performance penalty on writes when the write cache is disabled.

OSPLUS_IOCTL_WR_PROTECTED

Query whether the device media is write protected

Arguments:

Returns:

Description:

A pointer to an integer in memory to receive the write protect status of the media.

Returns 0 for success, -1 for failure.

This ioctl queries the write protect status of the media. This can be:

OSPLUS_MEDIA_NOT_PROTECTED

The media is not write protected.

OSPLUS_MEDIA_WR_PROTECTED

The media is write protected..

See also:

OSPLUS_IOCTL_CHECK_MEDIA

156/515 7702033 Rev 27

UM1150 OSPlus device model

These joystick device specific ioctl definitions relate to the device_ioctl() call. See

device_ioctl on page 192

for more details.

OSPLUS_IOCTL_JOYSTICK_GET_X

Return the joystick X axis value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the X axis value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the joystick X axis.

OSPLUS_IOCTL_JOYSTICK_GET_Y

, OSPLUS_IOCTL_JOYSTICK_GET_Z

OSPLUS_IOCTL_JOYSTICK_GET_X_BND

Return the joystick minimum and maximum X axis values

Arguments:

Returns:

Description:

See also:

The address of a two integer array to store the X axis minimum value followed by the

X axis maximum value.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the X axis may have. The first element of the array stores the X axis minimum and the second the X axis maximum.

OSPLUS_IOCTL_JOYSTICK_GET_Y_BND

,

OSPLUS_IOCTL_JOYSTICK_GET_Z_BND

OSPLUS_IOCTL_JOYSTICK_GET_Y

Return the joystick Y axis value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the Y axis value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the joystick Y axis.

OSPLUS_IOCTL_JOYSTICK_GET_X

, OSPLUS_IOCTL_JOYSTICK_GET_Z

OSPLUS_IOCTL_JOYSTICK_GET_Y_BND

Return the joystick minimum and maximum Y axis values

Arguments:

Returns:

Description:

See also:

The address of a two integer array to store the Y axis minimum value followed by the

Y axis maximum value.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the Y axis may have. The first element of the array stores the Y axis minimum and the second the Y axis maximum.

OSPLUS_IOCTL_JOYSTICK_GET_X_BND

,

OSPLUS_IOCTL_JOYSTICK_GET_Z_BND

7702033 Rev 27 157/515

OSPlus device model UM1150

OSPLUS_IOCTL_JOYSTICK_GET_Z

Return the joystick Z axis value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the Z axis value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the joystick Z axis.

OSPLUS_IOCTL_JOYSTICK_GET_X

, OSPLUS_IOCTL_JOYSTICK_GET_Y

OSPLUS_IOCTL_JOYSTICK_GET_Z_BND

Return the joystick minimum and maximum Z axis values

Arguments:

Returns:

Description:

See also:

The address of a two integer array to store the Z axis minimum value followed by the

Z axis maximum value.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the Z axis may have. The first element of the array stores the Z axis minimum and the second the Z axis maximum.

OSPLUS_IOCTL_JOYSTICK_GET_X_BND

,

OSPLUS_IOCTL_JOYSTICK_GET_Y_BND

OSPLUS_IOCTL_JOYSTICK_GET_RX

Return the joystick rX axis value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the rX axis value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the joystick rX axis.

OSPLUS_IOCTL_JOYSTICK_GET_RY

, OSPLUS_IOCTL_JOYSTICK_GET_RZ

OSPLUS_IOCTL_JOYSTICK_GET_RX_BND

Return the joystick minimum and maximum rX axis values

Arguments:

Returns:

Description:

See also:

The address of a two integer array to store the rX axis minimum value followed by the rX axis maximum value.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the rX axis may have. The first element of the array stores the rX axis minimum and the second the rX axis maximum.

OSPLUS_IOCTL_JOYSTICK_GET_RY_BND

,

OSPLUS_IOCTL_JOYSTICK_GET_RZ_BND

158/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_JOYSTICK_GET_RY

Return the joystick rY axis value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the rY axis value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the joystick rY axis.

OSPLUS_IOCTL_JOYSTICK_GET_RX

, OSPLUS_IOCTL_JOYSTICK_GET_RZ

OSPLUS_IOCTL_JOYSTICK_GET_RY_BND

Return the joystick minimum and maximum rY axis values

Arguments:

Returns:

Description:

See also:

The address of a two integer array to store the rY axis minimum value followed by the rY axis maximum value.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the rY axis can be given. The first element of the array stores the rY axis minimum and the second the rY axis maximum.

OSPLUS_IOCTL_JOYSTICK_GET_RX_BND

,

OSPLUS_IOCTL_JOYSTICK_GET_RZ_BND

OSPLUS_IOCTL_JOYSTICK_GET_RZ

Return the joystick rZ axis value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the rZ axis value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the joystick rZ axis.

OSPLUS_IOCTL_JOYSTICK_GET_RX

, OSPLUS_IOCTL_JOYSTICK_GET_RY

OSPLUS_IOCTL_JOYSTICK_GET_RZ_BND

Return the joystick minimum and maximum rZ axis values

Arguments:

Returns:

Description:

See also:

The address of a two integer array to store the rZ axis minimum value followed by the rZ axis maximum value.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the rZ axis can be given. The first element of the array stores the rZ axis minimum and the second the rZ axis maximum.

OSPLUS_IOCTL_JOYSTICK_GET_RX_BND

,

OSPLUS_IOCTL_JOYSTICK_GET_RY_BND

7702033 Rev 27 159/515

OSPlus device model UM1150

OSPLUS_IOCTL_JOYSTICK_GET_SLIDER

Return the joystick slider value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the slider value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the joystick slider.

OSPLUS_IOCTL_JOYSTICK_GET_SLIDER_BND

OSPLUS_IOCTL_JOYSTICK_GET_SLIDER_BND

Return the joystick minimum and maximum slider values

Arguments:

Returns:

Description:

The address of a two integer array to store the slider minimum value followed by the slider maximum value.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the slider may have. The first element of the array stores the slider minimum and the second the slider maximum.

See also:

OSPLUS_IOCTL_JOYSTICK_GET_SLIDER

OSPLUS_IOCTL_JOYSTICK_GET_HAT_SWITCH

Return the joystick hat switch value

Arguments:

Returns:

Description:

The address of an integer to store the slider value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the joystick hat switch. to determine the indicated direction, the hat switch value can be ANDed with the defines shown in

Table 28:

OSPlus joystick hat switch defines in ioctls/joystick.h on page 143

.

OSPLUS_IOCTL_JOYSTICK_GET_BTN_COUNT

Return the number of buttons the joystick supports

Arguments:

Returns:

Description:

The address of an integer to store the number of buttons.

Returns 0 for success, -1 for failure.

This ioctl returns the number of buttons the joystick supports. A joystick supports a maximum of 32 buttons.

See also:

OSPLUS_IOCTL_JOYSTICK_GET_BTN_BITMAP

160/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_JOYSTICK_GET_BTN_BITMAP

Return a bitmap of the joystick button state

Arguments:

Returns:

Description:

See also:

The address of an unsigned integer to store the number of buttons.

Returns 0 for success, -1 for failure.

This ioctl returns a bitmap of the joystick button state. If a bit is set the button is pressed, that is if bit 0 is set the joystick button 0 is pressed. Bit positions for the buttons can be generated using the macro OSPLUS_JOYSTICK_BUTTON_x(x).

OSPLUS_IOCTL_JOYSTICK_GET_BTN_COUNT

OSPLUS_IOCTL_JOYSTICK_GET_ALL_VALUES

Return all the joystick information in an array

Arguments:

Returns:

Description:

See also:

The address of a integer array with nine elements to store all joystick values.

Returns 0 for success, -1 for failure.

This ioctl returns all the joystick information in an array. Starting with the lowest indexable element the information is copied to the array in the following order: X axis value, Y axis value, Z axis value, rX axis value, rY axis value, rZ axis value, slider value, hatswitch value, and button bitmap.

OSPLUS_IOCTL_JOYSTICK_GET_X

, OSPLUS_IOCTL_JOYSTICK_GET_Y,

OSPLUS_IOCTL_JOYSTICK_GET_Z

, OSPLUS_IOCTL_JOYSTICK_GET_RX,

OSPLUS_IOCTL_JOYSTICK_GET_RY

, OSPLUS_IOCTL_JOYSTICK_GET_RZ,

OSPLUS_IOCTL_JOYSTICK_GET_SLIDER

,

OSPLUS_IOCTL_JOYSTICK_GET_HAT_SWITCH

,

OSPLUS_IOCTL_JOYSTICK_GET_BTN_BITMAP

OSPLUS_IOCTL_JOYSTICK_SET_RUMBLE

Set the amount of force feedback (rumble)

Arguments:

Returns:

Description:

This ioctl sets the amount of force feedback that the user feels when holding the joystick or gamepad. Left and right feedback channels are supported. The amount of force feedback to apply to a channel is an unsigned integer in the range 0...255. The argument to this ioctl encodes both left and right channel values as an unsigned short. The macro JOYSTICK_SET_RUMBLE(l,r) can be used to encode the left and right values into the argument.

Note: Not all joysticks or gamepads support force feedback, and of those that do, not all support dual channel feedback.

See also:

Unsigned short integer, specifying magnitude of force feedback to apply.

Returns 0 for success, -1 for failure.

7702033 Rev 27 161/515

OSPlus device model UM1150

These keyboard device specific ioctl definitions relate to the device_ioctl() call. See

device_ioctl on page 192

for more details.

OSPLUS_IOCTL_KEYBOARD_COUNT

Return the number of key presses in the keyboard buffer

Arguments:

Returns:

Description:

See also:

The address of an integer to store the number of key presses.

Returns 0 for success, -1 for failure.

This ioctl returns the number of key presses in the keyboard buffer.

OSPLUS_IOCTL_KEYBOARD_GETKEY

OSPLUS_IOCTL_KEYBOARD_GETKEY

Return a key press from the keyboard buffer

Arguments:

Returns:

Description:

The address of an integer to store the key press.

Returns 0 for success, -1 for failure.

This ioctl returns a key press from the keyboard buffer. If the keyboard buffer is empty, this function returns -1. On success, the integer whose address is passed-in contains the keypress, and 0 is returned.

See also:

OSPLUS_IOCTL_KEYBOARD_COUNT

162/515 7702033 Rev 27

UM1150 OSPlus device model

These mouse device specific ioctl definitions relate to the device_ioctl() call. See

device_ioctl on page 192

for more details.

OSPLUS_IOCTL_MOUSE_GET_X

Return the mouse X axis value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the X axis value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the mouse X axis.

OSPLUS_IOCTL_MOUSE_GET_Y

, OSPLUS_IOCTL_MOUSE_GET_XY,

OSPLUS_IOCTL_MOUSE_GET_WHEEL

, OSPLUS_IOCTL_MOUSE_GET_TWHEEL

OSPLUS_IOCTL_MOUSE_SET_X

Set the mouse X axis value

Arguments:

Returns:

Description:

See also:

A signed integer containing the X axis value to set.

Returns 0 for success, -1 for failure.

This ioctl sets the value of the mouse X axis. If the mouse X axis value is not within the new range, it is adjusted to be so.

OSPLUS_IOCTL_MOUSE_SET_Y

, OSPLUS_IOCTL_MOUSE_SET_XY,

OSPLUS_IOCTL_MOUSE_SET_WHEEL

, OSPLUS_IOCTL_MOUSE_SET_TWHEEL

OSPLUS_IOCTL_MOUSE_GET_X_BND

Return the mouse minimum and maximum X axis values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array to store the X axis minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the mouse X axis may have. The first element of the array stores the X axis minimum and the second the X axis maximum.

OSPLUS_IOCTL_MOUSE_GET_Y_BND

, OSPLUS_IOCTL_MOUSE_GET_XY_BND,

OSPLUS_IOCTL_MOUSE_GET_WHEEL_BND

, OSPLUS_IOCTL_GET_TWHEEL_BND

7702033 Rev 27 163/515

OSPlus device model UM1150

OSPLUS_IOCTL_MOUSE_SET_X_BND

Set the mouse minimum and maximum X axis values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array containing the X axis minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl sets the minimum and maximum values the mouse X axis may have. The first element of the array contains the X axis minimum and the second element, the X axis maximum. This changes the current mouse X axis value if it is not within the new range.

OSPLUS_IOCTL_MOUSE_SET_Y_BND

, OSPLUS_IOCTL_MOUSE_SET_XY_BND,

OSPLUS_IOCTL_MOUSE_SET_WHEEL_BND

, OSPLUS_IOCTL_SET_TWHEEL_BND

OSPLUS_IOCTL_MOUSE_GET_Y

Return the mouse Y axis value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the Y axis value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the mouse Y axis.

OSPLUS_IOCTL_MOUSE_GET_X

, OSPLUS_IOCTL_MOUSE_GET_XY,

OSPLUS_IOCTL_MOUSE_GET_WHEEL

, OSPLUS_IOCTL_MOUSE_GET_TWHEEL

OSPLUS_IOCTL_MOUSE_SET_Y

Set the mouse Y axis value

Arguments:

Returns:

Description:

See also:

A signed integer containing the Y axis value to set.

Returns 0 for success, -1 for failure.

This ioctl sets the value of the mouse Y axis. If the mouse Y axis value is not within the new range, it is adjusted to be so.

OSPLUS_IOCTL_MOUSE_SET_X

, OSPLUS_IOCTL_MOUSE_SET_XY,

OSPLUS_IOCTL_MOUSE_SET_WHEEL

, OSPLUS_IOCTL_MOUSE_SET_TWHEEL

OSPLUS_IOCTL_MOUSE_GET_Y_BND

Return the mouse minimum and maximum Y axis values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array to store the Y axis minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the mouse Y axis may have. The first element of the array stores the Y axis minimum and the second element the Y axis maximum.

OSPLUS_IOCTL_MOUSE_GET_X_BND

, OSPLUS_IOCTL_MOUSE_GET_XY_BND,

OSPLUS_IOCTL_MOUSE_GET_WHEEL_BND

, OSPLUS_IOCTL_GET_TWHEEL_BND

164/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_MOUSE_SET_Y_BND

Set the mouse minimum and maximum Y axis values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array containing the Y axis minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl sets the minimum and maximum values the mouse Y axis may have. The first element of the array contains the Y axis minimum and the second element the Y axis maximum. If it is not within the new range, this changes the current mouse Y axis value.

OSPLUS_IOCTL_MOUSE_SET_X_BND

, OSPLUS_IOCTL_MOUSE_SET_XY_BND,

OSPLUS_IOCTL_MOUSE_SET_WHEEL_BND

, OSPLUS_IOCTL_SET_TWHEEL_BND

OSPLUS_IOCTL_MOUSE_GET_XY

Return the mouse X and Y axis values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array to store the X and Y axis values.

Returns 0 for success, -1 for failure.

This ioctl returns the values of the mouse X and Y axes. The first element of the array stores the X axis value, and the second element stores the Y axis value.

OSPLUS_IOCTL_MOUSE_GET_X

, OSPLUS_IOCTL_MOUSE_GET_Y,

OSPLUS_IOCTL_MOUSE_GET_WHEEL

, OSPLUS_IOCTL_MOUSE_GET_TWHEEL

OSPLUS_IOCTL_MOUSE_SET_XY

Set the mouse X and Y axis values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array containing the X and Y axis values to set.

Returns 0 for success, -1 for failure.

This ioctl sets the value of the mouse X and Y axis values. The first element of the array contains the X axis value, and the second element contains the Y axis value. If the mouse X or Y axis values are not within the new range, they are adjusted to be in the range.

OSPLUS_IOCTL_MOUSE_SET_X

, OSPLUS_IOCTL_MOUSE_SET_Y,

OSPLUS_IOCTL_MOUSE_SET_WHEEL

, OSPLUS_IOCTL_MOUSE_SET_TWHEEL

7702033 Rev 27 165/515

OSPlus device model UM1150

OSPLUS_IOCTL_MOUSE_GET_XY_BND

Return the mouse minimum and maximum X and Y axis values

Arguments:

Returns:

Description:

See also:

The address of a four element signed integer array to store the X and Y axis minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the mouse X and Y axis may have. The first element of the array stores the X axis minimum and the second element stores the X axis maximum. The third element stores the Y axis minimum and the fourth element stores the Y axis maximum.

OSPLUS_IOCTL_MOUSE_GET_X_BND

, OSPLUS_IOCTL_MOUSE_GET_Y_BND,

OSPLUS_IOCTL_MOUSE_GET_WHEEL_BND

, OSPLUS_IOCTL_GET_TWHEEL_BND

OSPLUS_IOCTL_MOUSE_SET_XY_BND

Set the mouse minimum and maximum X and Y axis values

Arguments:

Returns:

Description:

See also:

The address of a four element signed integer array containing the X and Y axis minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl sets the minimum and maximum values the mouse X and Y axis may have.

The first element of the array contains the X axis minimum and the second element contains the X axis maximum. The third element contains the Y axis minimum and the fourth element the Y axis maximum. If they are not within the new ranges, this changes the current mouse X and Y axis values.

OSPLUS_IOCTL_MOUSE_SET_X_BND

, OSPLUS_IOCTL_MOUSE_SET_Y_BND,

OSPLUS_IOCTL_MOUSE_SET_WHEEL_BND

, OSPLUS_IOCTL_SET_TWHEEL_BND

OSPLUS_IOCTL_MOUSE_GET_WHEEL

Return the mouse wheel value

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the wheel value.

Returns 0 for success, -1 for failure.

This ioctl returns the value of the mouse wheel.

OSPLUS_IOCTL_MOUSE_GET_X

, OSPLUS_IOCTL_MOUSE_GET_Y,

OSPLUS_IOCTL_MOUSE_GET_XY

, OSPLUS_IOCTL_MOUSE_GET_TWHEEL

166/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_MOUSE_SET_WHEEL

Set the mouse wheel value

Arguments:

Returns:

Description:

See also:

A signed integer containing the wheel value to set.

Returns 0 for success, -1 for failure.

This ioctl sets the value of the mouse wheel. If the mouse wheel value is not within the new range, it is adjusted to become within the range.

OSPLUS_IOCTL_MOUSE_SET_X

, OSPLUS_IOCTL_MOUSE_SET_Y,

OSPLUS_IOCTL_MOUSE_SET_XY

, OSPLUS_IOCTL_MOUSE_SET_TWHEEL

OSPLUS_IOCTL_MOUSE_GET_WHEEL_BND

Return the mouse minimum and maximum wheel values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array to store the wheel minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the mouse wheel may have. The first element of the array stores the wheel minimum and the second element stores the wheel maximum.

OSPLUS_IOCTL_MOUSE_GET_X_BND

, OSPLUS_IOCTL_MOUSE_GET_Y_BND,

OSPLUS_IOCTL_MOUSE_GET_XY_BND

, OSPLUS_IOCTL_GET_TWHEEL_BND

OSPLUS_IOCTL_MOUSE_SET_WHEEL_BND

Set the mouse minimum and maximum wheel values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array containing the wheel minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl sets the minimum and maximum values for the mouse wheel. The first element contains the wheel minimum and the second element the wheel maximum. If it is not within the new range, this changes the current mouse wheel value.

OSPLUS_IOCTL_MOUSE_SET_X_BND

, OSPLUS_IOCTL_MOUSE_SET_Y_BND,

OSPLUS_IOCTL_MOUSE_SET_XY_BND

, OSPLUS_IOCTL_SET_TWHEEL_BND

OSPLUS_IOCTL_MOUSE_GET_TWHEEL

Return the mouse tilt wheel value

Arguments:

Returns:

The address of a signed integer to store the tilt wheel value.

Returns 0 for success, -1 for failure.

Description:

See also:

This ioctl returns the value of the mouse tilt wheel.

OSPLUS_IOCTL_MOUSE_GET_X

, OSPLUS_IOCTL_MOUSE_GET_Y,

OSPLUS_IOCTL_MOUSE_GET_XY

, OSPLUS_IOCTL_MOUSE_GET_WHEEL

7702033 Rev 27 167/515

OSPlus device model UM1150

OSPLUS_IOCTL_MOUSE_SET_TWHEEL

Set the mouse tilt wheel value

Arguments:

Returns:

Description:

See also:

A signed integer containing the tilt wheel value to be set.

Returns 0 for success, -1 for failure.

This ioctl sets the value of the mouse tilt wheel. If the mouse tilt wheel value is outside the new range, it is adjusted to become within the range.

OSPLUS_IOCTL_MOUSE_SET_X

, OSPLUS_IOCTL_MOUSE_SET_Y,

OSPLUS_IOCTL_MOUSE_SET_XY

, OSPLUS_IOCTL_MOUSE_SET_WHEEL

OSPLUS_IOCTL_MOUSE_GET_TWHEEL_BND

Return the mouse minimum and maximum tilt wheel values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array to store the tilt wheel minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl returns the minimum and maximum values the mouse tilt wheel may have.

The first element of the array stores the tilt wheel minimum and the second stores the tilt wheel maximum.

OSPLUS_IOCTL_MOUSE_GET_X_BND

, OSPLUS_IOCTL_MOUSE_GET_Y_BND,

OSPLUS_IOCTL_MOUSE_GET_XY_BND

, OSPLUS_IOCTL_GET_WHEEL_BND

OSPLUS_IOCTL_MOUSE_SET_TWHEEL_BND

Set the mouse minimum and maximum tilt wheel values

Arguments:

Returns:

Description:

See also:

The address of a two-element signed-integer array containing the tilt wheel minimum and maximum values.

Returns 0 for success, -1 for failure.

This ioctl sets the minimum and maximum values the mouse tilt wheel may have. The first element of the array contains the tilt wheel minimum and the second contains the tilt wheel maximum. This changes the current mouse tilt wheel value if it is not within the new range.

OSPLUS_IOCTL_MOUSE_SET_X_BND

, OSPLUS_IOCTL_MOUSE_SET_Y_BND,

OSPLUS_IOCTL_MOUSE_SET_XY_BND

, OSPLUS_IOCTL_SET_WHEEL_BND

168/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

Return the number of mouse buttons

Arguments:

Returns:

Description:

See also:

The address of a signed integer to store the number of mouse buttons.

Returns 0 for success, -1 for failure.

This ioctl returns the number of mouse buttons. A mouse only supports up to

32 buttons.

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

,

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

Return a bitmap of the current mouse button state

Arguments:

Returns:

Description:

See also:

The address of an unsigned integer to store the mouse button state.

Returns 0 for success, -1 for failure.

This ioctl returns a bitmap of the mouse button state. If a bit is set the button is pressed, for example if bit 0 is set then mouse button 1 is pressed.

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

,

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL

7702033 Rev 27 169/515

OSPlus device model UM1150

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

Return the mouse button data for a specified button

Arguments:

The address of a seven-element integer array to identify the mouse button data to retrieve and store the button data.

Returns 0 for success, -1 for failure.

Returns:

Description:

This ioctl returns the mouse button data for the button number specified in first element of the array. The second to seventh elements of the array are populated with the following data in the following order: last press X axis value, last press Y axis value, number of presses since data was reset, last release X axis value, last release

Y axis value, number of releases since data was reset.

Note: Mouse buttons must start at one, not at zero.

See also:

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

,

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

Clear the mouse button data for the specified button

Arguments:

Returns:

Description:

See also:

A signed integer containing the mouse button number to clear the data for.

Returns 0 for success, -1 for failure.

This ioctl clears all mouse button data for the specified button.

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

,

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

,

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL

170/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

Return the mouse button press data for a specified button

Arguments:

The address of a four element integer array to identify the mouse button data to retrieve and store the button press data.

Returns 0 for success, -1 for failure.

Returns:

Description:

This ioctl returns the mouse button press data for the button number specified in first element of the array. The second to fourth elements of the array are populated with the following data in the following order: last press X axis value, last press Y axis value, and number of presses since the data was reset.

Note: Mouse buttons must start at one not at zero.

See also:

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

,

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

,

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

Clear the mouse button press data for the specified button

Arguments:

Returns:

Description:

See also:

A signed integer containing the mouse button number, to clear the press data for that button.

Returns 0 for success, -1 for failure.

This ioctl clears all mouse button press data for the specified button.

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

,

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

,

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL

7702033 Rev 27 171/515

OSPlus device model UM1150

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

Return the mouse button release data for a specified button

Arguments:

Returns:

Description:

See also:

The address of a four-element integer array to identify the mouse button data, to retrieve and store the button release data.

Returns 0 for success, -1 for failure.

This ioctl returns the mouse button release data for the button number specified in first element of the array. The second to fourth elements of the array are populated with the following data in the following order:

1.last release X axis value

2. last release Y axis value

3. number of releases since the data was reset

Note: Mouse buttons must start at one not zero.

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

,

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

,

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL

Clear the mouse button release data for the specified button

Arguments:

Returns:

Description:

See also:

A signed integer containing the mouse button number, to clear the release data for that button.

Returns 0 for success, -1 for failure.

This ioctl clears all mouse button release data for the specified button.

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT

,

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

,

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA

,

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS

,

OSPLUS_IOCTL_MOUSE_GET_BTN_REL

172/515 7702033 Rev 27

UM1150 OSPlus device model

OSPLUS_IOCTL_MOUSE_GET_ALL_VALUES

Return all the mouse information in an array

Arguments:

Returns:

Description:

See also:

The address of a integer array with five elements to store all mouse values.

Returns 0 for success, -1 for failure.

This ioctl returns all the mouse information in an array. Starting with the lowest indexable element the information is copied to the array in the following order: X axis value, Y axis value, wheel value, tilt wheel value, and button bitmap.

OSPLUS_IOCTL_MOUSE_GET_X

,

OSPLUS_IOCTL_MOUSE_GET_Y

,

OSPLUS_IOCTL_MOUSE_GET_WHEEL

,

OSPLUS_IOCTL_MOUSE_GET_TWHEEL

,

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP

7702033 Rev 27 173/515

OSPlus device model UM1150

4.11 Device driver function definitions dev_class_create

Create a new driver class

Definition:

dev_class_t *dev_class_create (

const char *type,

dev_params_t *params)

Arguments:

type params

The type of device being registered.

The address of the parameter information for this device class.

Returns:

Description:

Returns a pointer to the newly created device class, NULL for failure.

dev_class_create()

registers a new device class with the device library. It creates a new device class structure, to record the type of the device and its method table. This can then be used by the dev_instance_create() API to create device instances of this class.

The information from the parameter structure is copied into the class structure, and the type string is duplicated. This means the class structure maintains ownership of all memory associated with the class.

The parameter structure has the following format: typedef struct

{

} dev_params_t; ops

must point to a valid dev_ops_t structure, but elevator_params can be

NULL

if seek time optimization is not needed.

174/515 7702033 Rev 27

UM1150 OSPlus device model

The dev_ops_t method table defines the methods given in

Table 34

.

Table 34.

dev_ops_t fields

Method name

create destroy open close read write ioctl block_read block_write streaming_read streaming_write

Description

Device create method

Device deletion method

Device open method

Device close method

Character read method

Character write method

I/O control method

Block read method

Block write method

Streaming block read method

Streaming block write method

The device driver populates the method table with pointers to its own functions, or

NULL

if that facility is not supported. These methods are called by the device library entry points when vectoring a request to a specific driver class.

Note: It is mandatory for all drivers to support the create and destroy methods.

create destroy open close

This method is called when a device of this class is created by a call to dev_instance_create(). It is passed in a parameter param which is private data the method uses to create the device instance. It should return an instance pointer for the newly created device instance.

This method is called when a device instance of this class is deleted with a call to dev_instance_delete(). It is passed the instance pointer returned when the device was created.

This call should destroy the memory associated with the device instance.

This method is passed the instance pointer created when the device was created, and a mode specifying the sort of access needed (read/write). It is responsible for creating an open device handle, and returning this to the device library. If the open cannot be satisfied, the open method should return

NULL

.

This method is passed the handle to an open device instance, previously returned by a call to the open method. It is responsible for tearing down any data structures it had associated with the open device handle. It should return 0 for success, -1 for failure.

7702033 Rev 27 175/515

OSPlus device model UM1150

read write ioctl block_read block_write

This method performs a character oriented read of the device.

If a device does not support this type of access, its read method should be NULL in the method table. It is passed the handle to an open device instance, a destination buffer and a length. It should return the number of bytes read for success, -

1

for failure.

This method performs a character oriented write to the device.

If a device does not support this type of access, its write method should be NULL in the method table. It is passed the handle to an open device instance, a source buffer and a length. It should return the number of bytes written for success, -1 for failure.

This method performs device control operations. If a device does not support this type of access, its ioctl method should be NULL in the method table. It is passed the handle to an open device instance, a function to perform and an associated parameter. It should return -1 for failure.

This method performs a block oriented read from the device. If a device does not support this type of access, its block read method should be NULL in the method table. It is passed the handle to an open device instance, a destination buffer, a logical block address, and a length expressed as several blocks to read. It should return the number of blocks read for success, -1 for failure.

This method performs a block oriented write to the device. If a device does not support this type of access, its block write method should be NULL in the method table. It is passed the handle to an open device instance, a source buffer, a logical block address, and a length expressed as several blocks to write. It should return the number of blocks written for success,

-1

for failure.

streaming_read

This method is a streaming version of the block read method.

If a device does not support streaming style accesses, simply map this method to the block read method or NULL. Only certain devices (for example, some ATAPI-7 hard disks) support streaming accesses.

streaming_write

This method is a streaming version of the block write method.

If a device does not support streaming style accesses, simply map this method to the block write method. Only certain devices (for example, some ATAPI-7 hard disks) support streaming accesses.

The elevator parameters field can be NULL if elevator seek ordering is not needed by the device class (for example, it is not a block device, or it implements its own scheme). The elevator seek ordering implemented by the device library is designed to minimize head seek time, and so reduce overall latency.

176/515 7702033 Rev 27

UM1150 OSPlus device model

The dev_elevator_params_t structure has the following format: typedef struct {

See also:

} dev_elevator_params_t;

The fields are described in

Table 35

.

Table 35.

dev_elevator_params_t fields

Field

max_concurrent_io queue_length queue_timeout type

Description

The maximum number of outstanding I/O requests the device can support.

The maximum length of the seek order queue the device library should maintain per device.

The maximum time (in seconds) an I/O should wait before being scheduled. This is intended to eliminate corner cases where one task swamps the device with I/O, preventing other

I/O requests from being scheduled.

The type of elevator algorithm to use. It can be dev_elevator_unidir or dev_elevator_bidir .

The former unidirectional version sweeps the disk in monotonically increasing logical block address (LBA) order.

Seek times can be minimized, but I/O at the far extents can experience twice the average latency. The bidirectional version alternates between sweeping up and down the drive, giving minimum seek times and uniform average latencies.

dev_class_delete

7702033 Rev 27 177/515

OSPlus device model UM1150

dev_class_delete

Delete a device class

Definition:

Arguments:

int dev_class_delete (dev_class_t *class) class

The class to delete.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

dev_class_delete()

deletes a device class within the device library. It frees the memory associated with the device class, providing there are no existing device instances of that class.

dev_class_create

178/515 7702033 Rev 27

UM1150 OSPlus device model

dev_instance_create

Create a device instance

Definition:

int dev_instance_create (

dev_class_t *class,

const char *name,

void *param)

Arguments:

class name param

The class of device instance to create.

The name of device instance to create.

Private information used to create the device instance.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

dev_instance_create()

creates an instance of a device class. On successful completion a device instance is created and bound to the name given. This can then be opened and used for I/O. The parameter param is passed to the device creation method, and used to uniquely identify the device being created.

dev_instance_delete

, device_open

7702033 Rev 27 179/515

OSPlus device model UM1150

dev_instance_delete

Delete a device instance

Definition:

Arguments:

int dev_instance_delete (const char *name) name

The name of the device instance to delete.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

dev_instance_delete()

deletes an instance of a device class.

Note: To support hot plugging, it is possible to delete a device even if it has open handles.

dev_instance_create

180/515 7702033 Rev 27

UM1150 OSPlus device model

device_attribute

Get the value of the given attribute for the given device

Definition:

int device_attribute (

const char *name,

const char *attr,

void **value)

Arguments:

name attr value

The name of the device.

The name of the attribute to query.

The pointer to the location to receive value.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

device_attribute()

passes back the value of the named attribute for the specified device. If the device or attribute does not exist, the calls fails and returns -1.

The value of the attribute is stored in the location pointed to by value. This call is used for querying literal value type attributes.

device_attribute_set

, device_attribute_delete

7702033 Rev 27 181/515

OSPlus device model UM1150

device_attribute_data

Get the value of the given attribute for the given device

Definition:

int device_attribute_data (

const char *name,

const char *attr,

void *data,

size_t *size)

Arguments:

name attr data size

The name of the device.

The name of the attribute to query.

The memory buffer to receive the value.

Size of data on entry, the number of bytes copied out on exit.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

device_attribute_data()

copies out the memory block that is the value of the named attribute for the specified device. If the device or attribute does not exist, the calls fails and returns -1. The value of the attribute is stored in the location pointed to by data, and the number of bytes copied out is stored in size. This call is used for querying memory block type attributes. If data is set to NULL when this call is made, then just the size of the memory block is passed back through size.

device_attribute_data_set

, device_attribute_delete

182/515 7702033 Rev 27

UM1150 OSPlus device model

device_attribute_delete

Delete the given attribute on the given device

Definition:

int device_attribute_delete (

const char *name,

const char *attr)

Arguments:

name attr

The name of the device.

The name of the attribute.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

device_attribute_delete()

deletes the given attribute from the given device, freeing any memory that was allocated to store the value.

device_attribute

, device_attribute_set

7702033 Rev 27 183/515

OSPlus device model UM1150

device_attribute_set

Set the value of a given attribute for a given device

Definition:

int device_attribute_set (

const char *name,

const char *attr,

void *value)

Arguments:

name attr value

The name of the device.

The name of the attribute to set.

The value to store.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

device_attribute_set()

stores the given literal value in the attribute specified for the named device. Failures occur if the device does not exist, or the system runs out of memory. device_attribute

, device_attribute_delete

184/515 7702033 Rev 27

UM1150 OSPlus device model

device_attribute_data_set

Set the value of a given attribute for a given device

Definition:

int device_attribute_set (

const char *name,

const char *attr,

void *value,

size_t size)

Arguments:

name attr value size

The name of the device.

The name of the attribute to set.

The value to store.

The size of value in bytes.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

device_attribute_data_set()

copies the memory block specified by value and size into the attribute specified for the named device. Failures occur if the device does not exist, or the system runs out of memory.

device_attribute_data

, device_attribute_delete

7702033 Rev 27 185/515

OSPlus device model UM1150

device_block_read

Perform a block oriented read of a device

Definition:

int device_block_read (

device_handle_t *handle,

void *buffer,

lba_t lba,

size_t size)

Arguments:

handle buffer lba size

The handle of the device to read.

The destination buffer for data.

The logical block address of the first block to read from on the device.

The number of blocks to read.

Returns:

Description:

See also:

Returns the number of blocks read for success, -1 for failure.

device_block_read()

performs a block oriented read of an open device instance.

The device driver’s block read method is used to implement the block read operation.

device_block_write

, device_streaming_write, device_streaming_read

186/515 7702033 Rev 27

UM1150 OSPlus device model

device_block_write

Perform a block oriented write to a device

Definition:

int device_block_write (

device_handle_t *handle,

void *buffer,

lba_t lba,

size_t size)

Arguments:

handle buffer lba size

The handle of the device to write to.

The source buffer for data.

The logical block address of the first block to write to on the device.

The number of blocks to write.

Returns:

Description:

See also:

Returns the number of blocks written for success, -1 for failure.

device_block_write()

performs a block oriented write to an open device instance. The device driver’s block write method is used to implement the block write operation.

device_block_read

, device_streaming_read, device_streaming_write

7702033 Rev 27 187/515

OSPlus device model UM1150

device_callback_attach

Declare a function to be called when certain events occur in the device library

Definition:

int device_callback_attach (

device_callback_t function,

void *cookie,

int synchronize)

Arguments:

function cookie synchronize

The function to call when the event occurs.

The parameter to pass to the callback event.

A flag to synchronize callback with the current state of the system.

Returns:

Errors:

Description:

Returns 0 for success, -1 for failure.

Out of memory or the callback function is already registered.

device_callback_attach()

registers a function with the device library to be called when certain events occur within the device library. If the synchronize flag is set to a non-zero value, the callback is immediately called with information describing the current state of the system, that is, all existing devices appear to the callback as if they have just been created.

The callback function should be of the type device_callback_t, which has the following prototype: void callback_fn (

188/515

The event parameter identifies the nature of the event that led to the callback being called (device_created for created or device_deleted for deleted). The device_event_t

structure has the following format: typedef enum

{

device_created,

device_deleted

} device_event_t;

The notifications parameter is the address of an array of pointers to device_notify_t

structures; the number of entries in this array is given by the num_notifications

parameter. A device_notify_t structure has the following format: typedef struct

{ const char *device_name; const char *type_name;

} device_notify_t;

7702033 Rev 27

UM1150 OSPlus device model

The fields are described in

Table 36

.

See also:

Table 36.

device_notify_t fields

Field name

device_name type_name type

Description

The name of the device

The name of the device type

The type of device

The cookie parameter is the cookie passed in when the callback was registered. No meaning is assigned to this parameter, and the application can use it as required.

Note: The callback is made in the context of the task that created or destroyed a device instance (or the in case of a synchronizing attach call, the task that called

device_callback_attach()

). It is called with the device library lock held.

Minimize the processing performed when servicing notification callbacks. This is because the call stack size cannot be guaranteed. There is the risk of deadlock unless care is taken with locking strategies. It is highly recommended that callback routines simply duplicate the notification information into a message, which is then sent to a message queue. A separate listener thread can then receive this notification message and process it appropriately.

device_callback_detach

7702033 Rev 27 189/515

OSPlus device model UM1150

device_callback_detach

Detach a device notification callback

Definition:

int device_callback_detach (

device_callback_t function,

void *cookie)

Arguments:

function cookie

The function to unregister.

The value that was specified when the callback was attached.

Returns:

Errors:

Description:

See also:

Returns 0 for success, -1 for failure.

The callback function with the given cookie is not registered.

device_callback_detach()

unregisters a callback function that was previously registered with the device library.

device_callback_attach

190/515 7702033 Rev 27

UM1150 OSPlus device model

device_close

Close a device instance

Definition:

Arguments:

int device_close (device_handle_t *handle) handle

The handle of the device to close.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

device_close()

closes an open device handle. Following a successful close, the handle is no longer valid, and cannot have I/O performed on it. The device driver’s close method is called to perform device-specific activities.

device_open

7702033 Rev 27 191/515

OSPlus device model UM1150

device_ioctl

Definition:

Issue control commands to a device

int device_ioctl (

device_handle_t *handle,

int function,

void *parameter)

Arguments:

Returns:

Description:

See also:

handle function parameter

The handle of the device.

The command to the device.

The associated parameter.

Returns the device specific return code.

device_ioctl()

issues a device control command to an open device instance. The device driver’s ioctl method is used to implement the operation.

device_read

, device_write

192/515 7702033 Rev 27

UM1150 OSPlus device model

device_open

Open a device instance

Definition:

device_handle_t *device_open (

const char *name,

int mode)

Arguments:

name mode

The name of device to open.

The access mode.

Returns:

Description:

Returns the address of the open device handle, NULL for failure.

device_open()

opens a device instance. On success it returns a valid open device handle that can have I/O performed on it. The device driver’s open method is called to perform device specific activities. If the device does not exist when the call is made, the call returns immediately with failure.

The access mode specifies the read/write access needed for the device, and any other specific attributes. The mode parameter is a collection of bit fields that can be

OR’ed together. The supported mode values are defined in osplus.h. The

meaningful values for devices are given in

Table 37

.

Table 37.

Open modes for devices

Mode value

OSPLUS_O_RDONLY

OSPLUS_O_WRONLY

OSPLUS_O_RDWR

OSPLUS_O_EXCL

Read-only access

Write-only access

Read/write access

Exclusive access

Meaning

See also:

device_open

, device_close

7702033 Rev 27 193/515

OSPlus device model UM1150

device_open_timeout

Open a device instance

Definition:

device_handle_t *device_open_timeout (

const char *name,

int mode,

osclock_t *timeout)

Arguments:

name mode timeout

The name of the device to open.

The access mode.

The timeout specification.

Returns:

Description:

See also:

Returns the address of the open device handle, NULL for failure.

device_open_timeout()

opens a device instance. On success, it returns a valid open device handle that can have I/O performed on it. The device driver’s open method is called to perform device specific activities.

If the device does not exist when the call is made, the timeout parameter is used to determine what should be done. If timeout is set to TIMEOUT_IMMEDIATE the call returns immediately with failure, if it is set to TIMEOUT_INFINITY the call blocks the caller indefinitely or until the device comes into existence. Any other value is taken to be a pointer to a timeout definition, which is an absolute time. In this case the call blocks until either the time specified passes (in which case the call fails) or the device comes into existence (in which case the device is opened).

The mode specifies the read/write access needed for the device, and any other specific attributes. The mode parameter is a collection of bit fields that can be OR’ed together. The supported mode values are defined in osplus.h. The meaningful values for devices are given in

Table 37 on page 193

. device_open

, device_close

194/515 7702033 Rev 27

UM1150 OSPlus device model

device_read

Definition:

Read characters from a device

int device_read (

device_handle_t *handle,

void *buffer,

size_t size)

Arguments:

handle buffer size

The handle of the device to read.

The destination buffer for data read from the device.

The number of bytes to read.

Returns:

Description:

See also:

Returns the number of bytes read for success, -1 for failure.

device_read()

performs a character oriented read of an open device instance. The device driver’s read method is used to implement the read operation.

device_write

7702033 Rev 27 195/515

OSPlus device model UM1150

device_start

Allow I/O to occur to a device

Definition:

Arguments:

int device_start (const char *name) name

The name of the device to start.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

device_start()

allows I/O to be performed to a device that has previously been stopped with device_stop() or device_stop_timeout().

Note: This does not need to be called if device_stop() or device_stop_timeout()

have not been called.

device_stop

, device_stop_timeout

196/515 7702033 Rev 27

UM1150 OSPlus device model

device_stop

Definition:

Arguments:

Stop I/O being allowed to a specific device

int device_stop (const char *name) name

The name of the device to stop.

Returns:

Errors:

Description:

See also:

Returns 0 for success, -1 for failure.

Device had open handles.

device_stop()

checks to see if a device can be safely removed from the system and, if so, prevents the device from being opened. A device is deemed safe to be removed if it has no open handles. If the device has open handles, the call fails.

Following a successful device_stop(), the device can be safely removed and deleted, or device_start() can used to allow more I/O to it.

device_stop_timeout

, device_start

7702033 Rev 27 197/515

OSPlus device model UM1150

device_stop_timeout

Stop I/O being allowed to a specific device

Definition:

int device_stop_timeout (

const char *name,

osclock_t *timeout)

Arguments:

name timeout

The name of the device to stop.

The timeout specification.

Returns:

Errors:

Description:

See also:

Returns 0 for success, -1 for failure.

Device had open handles.

A device is deemed safe to be removed if it has no open handles. device_stop_timeout()

checks to see if a device can be safely removed from the system and, if so, prevents the device from being opened. If the device has open handles, the call waits (based on the timeout specification) for all existing open handles to be closed. The call fails if there are any open handles at the end of the timeout period.

If there are open handles on the device, and timeout is set to

TIMEOUT_IMMEDIATE

, the call returns immediately with failure. If timeout is set to

TIMEOUT_INFINITY

, the caller is blocked indefinitely or until all the open handles have been closed. Any other value is taken to be a pointer to a timeout definition which is an absolute time. In this case, the call blocks until after the specified time (in which case the call fails) or all handles have been closed, in which case the device is stopped.

Following a successful device_stop_timeout(), the device can be safely removed and deleted, or device_start() can be used to allow more I/O to it.

device_stop

, device_start

198/515 7702033 Rev 27

UM1150 OSPlus device model

device_streaming_read

Perform a streaming block oriented read of a device

Definition:

int device_streaming_read (

device_handle_t *handle,

void *buffer,

lba_t lba,

size_t size)

Arguments:

handle buffer lba size

The handle of the device to read.

The destination buffer for data.

The logical block address from which to start the read.

The number of blocks to read.

Returns:

Description:

See also:

Returns the number of blocks read for success, -1 for failure.

device_streaming_read() performs a streaming block oriented read of an open device instance. The device driver’s streaming read method is used to implement the streaming read operation.

device_block_read

, device_streaming_write, device_block_write

7702033 Rev 27 199/515

OSPlus device model UM1150

device_streaming_write

Perform a streaming block oriented write to a device

Definition:

int device_streaming_write (

device_handle_t *handle,

void *buffer,

lba_t lba,

size_t size)

Arguments:

handle buffer lba size

The handle of the device to write to.

The source buffer for data.

The logical block address for the start of the write.

The number of blocks to write.

Returns:

Description:

See also:

Returns the number of blocks written for success, -1 for failure.

device_streaming_write()

performs a streaming block oriented write to an open device instance. The device driver’s streaming write method is used to implement the streaming block write operation.

device_block_read

, device_streaming_read, device_block_write

200/515 7702033 Rev 27

UM1150 OSPlus device model

device_type

Definition:

Arguments:

Return the type value for a given type name

device_type_t device_type (const char *name) name

The name of the type.

Returns:

Description:

Returns the device type, or -1 for failure.

device_type()

returns the type associated with the type name specified. If no type of that name exists when the call is made, it creates a new type and binds it to the specified name.

Note: device.h defines standard device type names, as listed in

Table 14: Standard

OSPlus device types on page 135 .

7702033 Rev 27 201/515

OSPlus device model UM1150

device_write

Write characters to a device

Definition:

int device_write (

device_handle_t *handle,

void *buffer,

size_t size)

Arguments:

handle buffer size

The handle of the device to write to.

The source buffer to write data.

The number of bytes to write.

Returns:

Description:

See also:

The number of bytes written for success, -1 for failure.

device_write()

performs a character oriented write to an open device instance.

The device driver’s write method is used to implement the write operation.

device_read

202/515 7702033 Rev 27

UM1150 OSPlus device model

4.12 Writing an OSPlus device driver

4.12.1 Device driver overview

Note:

All device drivers are different, but many have similarities. They present an abstraction of particular resources or hardware, to provide access methods allowing an application to use those resources. Device drivers frequently must handle interrupts from the devices they control, and provide I/O access which is generally either character or block oriented. For example, a serial port is a character-oriented device; its device drivers provide a characteroriented I/O interface. Hard disk drives are block oriented, and so disk device drivers provide block I/O interfaces.

The OSPlus device model does not specify that a device driver must be either block or character. It is possible to write a hybrid driver which presents both block and character interfaces.

This section provides an example of how to write a device driver for a fictitious piece of hardware. This device primarily supports block access, but the driver also has a character oriented aspect. There can be any number of these devices in a system, and the driver must support them all.

4.12.2 Anatomy of an OSPlus device driver

OSPlus device drivers typically export a single initialization entry point. The main application must be aware of this routine, and its calling convention. For the fictional driver, declare the entry point as follows: int dd_init (void); dd_init()

is the single exported function from the device driver (it is the only exported symbol). Therefore, for an application to use this driver, it only has to know the entry point and the device type name this driver uses for its devices. The details of the entry point and the type name (if it is not one of the standard OSPlus type names) should be put in the public header file, dd.h. This file should also contain details of any I/O control (ioctl) functions supported by the driver, with the associated data types used.

To invoke dd_init(), the application should be linked with the OSPlus library, and call dd_init()

when the operating system (OS20 or OS21) has been completely started. The following example shows the code required under OS21.

dd.h

int dd_init (void);

#define DD_TYPE "device type"

#define DD_IOCTL_ARM 0xA53DE21C

test.c

#include <os21.h>

#include "dd.h" static device_type_t dd_type; int main (void)

{

kernel_initialize (NULL);

7702033 Rev 27 203/515

OSPlus device model UM1150

Note:

}

kernel_start ();

dd_init ();

dd_type = device_type (DD_TYPE);

...

The ordering of dd_init() and the discovery of dd_type is not important. The first call to device_type()

with a given type name creates the name/value binding and any subsequent calls specifying the same type name always get the same value back.

4.12.3 dd_init()

The initialization routine is responsible for starting the device driver. This normally consists of the following steps.

1.

Create the device classes to be used by the device driver.

2. Discover all instances of the hardware or resources managed by this device driver.

3. Create device instances for each of the discovered entities.

To create a device class, the initialization routine has to call dev_class_create(). This call takes two parameters - the type name associated with devices of this class, and a structure containing information detailing the access methods supported by the driver and some optional information specifically for block-oriented devices.

The type name can be one of the standard OSPlus device types (defined in osplus/device.h

), or a unique string defined by the driver.

The device parameters argument consists primarily of the method table for the device. This is the list of entry points which OSPlus invokes in response to application calls to routines like device_instance_create(), device_open() or device_read().

The fictional driver fills in the method table as shown in

Table 38

.

Table 38.

Fictional device dev_ops_t fields

Method name Value specified

create destroy open close read write ioctl block_read block_write streaming_read streaming_write dd_create dd_delete dd_open dd_close dd_read

NULL dd_ioctl dd_block_read dd_block_write dd_block_read dd_block_write

Description

Device create method

Device delete method

Device open method

Device close method

Character read method

Character write method

I/O control method

Block read method

Block write method

Streaming block read method

Streaming block write method

The create, destroy, open and close method pointers cannot be NULL, as this causes dev_class_create()

to disallow the class creation. Any of the other method pointers can

204/515 7702033 Rev 27

UM1150

Note:

OSPlus device model

be NULL. This informs OSPlus the device does not support accesses of that type (like the character write method).

The fictional device has no concept of streaming accesses, therefore the streaming methods point to the same routines as the normal block methods.

The second part of the device parameters argument specifies information to OSPlus regarding any head movement optimizations the OSPlus device library can perform on block

I/O requests. For simplicity, assume the fictional device is not mechanical, and all blocks can be accessed with equal latency. This means there is no need to perform head movement optimization, and this part of the parameters structure can be set to NULL. The following shows the first part of dd_init(): dev_class_t *dd_class; int dd_init (void)

{

dev_ops_t method_table =

{

dd_create, dd_delete, dd_open, dd_close, dd_read, NULL,

dd_ioctl, dd_block_read, dd_block_write, dd_block_read, dd_block_write

};

dev_params_t dd_params =

{

};

}

dd_class = dev_class_create (DD_TYPE, &dd_params);

...

This example relies on the user only calling dd_init() once as there is no form of initialization locking. If it is called more than once, the subsequent calls should be ignored.

To do this, the initialization routine must be atomic. A lock needs to be created and taken before the decision of whether to initialize can be made. However, this process is inherently pre-emptable causing two separate callers of the routine to believe they have to create the lock. To avoid this, the OSPlus call osplus_lock_create() can be used. This call guarantees the creation of precisely one lock. However many times it is called, the same lock address is returned. The safety logic is as shown as follows (error checking omitted for clarity): static semaphore_t *init_lock = NULL; static int need_to_init = 1; int dd_init (void)

{

if (init_lock == NULL)

{

{

...

7702033 Rev 27 205/515

OSPlus device model UM1150

/* Do all initialization, create class */

need_to_init = 0;

}

}

}

●

●

When the device class has been created, the initialization routine searches for all instances of the fictional device and creates device instances for them. This can be achieved in a variety of driver-specific ways as follows: the driver can probe known I/O addresses

● there may be some static entries in the registry which the driver uses to know device positions the calling application can pass parameters to the initialization routine which describes the devices present

● any other appropriate strategy can be used

When the driver has discovered the device instances it is going to support, it creates device instances for them. This is done with the dev_instance_create() call. This call takes a device name, the device class pointer, and an opaque data pointer as its parameters.

The device name must be unique, and is used to name the device instance. Either the driver can be responsible for guaranteeing the uniqueness of names it chooses, or it can use the

OSPlus ID manager API. This API generates unique identifiers which can be suffixed to a standard name template.

The class pointer is the value previously returned from dev_class_create().

The opaque data pointer is a value which is passed directly to the device’s create method

(dd_create() in this case). The purpose of the data pointer is to act as an instance identifier (something which the device driver can use to uniquely identify a given piece of hardware). This could be as simple as its I/O base address, or the address of a driverdefined structure containing lots of state information about the device. If successful, the create method should return an instance pointer (a pointer to a structure which is used to manage that specific piece of hardware). The OSPlus device layer stores this value and passes it to subsequent open method calls (dd_open() in this case), as its means of identifying the device being opened.

For example, if the dd_init() routine discovers one device, at a given base address, it would create the device instance as follows: int dd_init (void)

{

void *base_address;

...

}

/* Discover device at base_address */

dev_instance_create ("dd0", dd_class, base_address);

The following is an example of the driver’s create methods: dev_instance_t *dd_create (void *v)

{

dd_instance_t *instance = malloc(sizeof(dd_instance_t));

instance->base_address = v;

...

206/515 7702033 Rev 27

UM1150 OSPlus device model

}

/* Fill in other state information */

return (dev_instance_t*)instance;

The corresponding delete method (called when device_instance_delete() is called) could then be as simple as: void dd_delete (void *v)

{

free (v);

}

4.12.4 dd_open()

This method is called every time a device instance is opened. It is called with two parameters, a pointer to the device instance data (as returned from a previous call to dd_create()

) and the mode in which the device is being opened. The open method returns a private device handle, through which the fictional driver knows about the open instance. This is the handle which is passed into all the other driver methods. The following gives an example of dd_open(): dev_handle_t *dd_open (dev_instance_t *instance, int mode)

{

dd_hdl_t *hdl = (dd_hdl_t*)malloc(sizeof(dd_hdl_t));

hdl->instance = instance;

...

/* Fill in rest of handle */

}

return (dev_handle_t*)hdl;

4.12.5 dd_close()

This method is called every time a device instance is closed. It is called with one parameter, the device handle as returned from a previous call to dd_open(). The close method should perform any closedown necessary, and destroy the handle. The following gives an example of dd_close(): int dd_close (dev_handle_t *handle)

{

dd_hdl_t *hdl = (dd_hdl_t*)handle;

...

/* Specific closedown actions on hdl */

}

free (hdl);

return 0;

7702033 Rev 27 207/515

OSPlus device model UM1150

4.12.6 dd_read()

The fictional device is block oriented. Normally a driver for such a device would not support character-oriented I/O, however, this driver uses the character read interface to pass out a status string. The call should return the number of characters read, or -1 for failure. The following simple example passes out a fixed status message; a real implementation would record more information, derived from the state of the specific handle and its associated instance information.

int dd_read (dev_handle_t *handle, char *buffer, size_t len)

{

char status[256];

int total;

}

sprintf (status, "Driver OK\n");

total = min(len, strlen(status));

memcpy (buffer, status, total);

return total;

4.12.7 dd_ioctl()

The ioctl method implements ‘everything else’. That is, everything the driver can do, which is not characterized as a block or character read or write operation. The ioctl method can be tasked with doing anything specified by the device driver author.

OSPlus defines ioctl to be a call that takes a single integer value and an opaque pointer value. The single integer value encodes the ioctl function being requested. The opaque pointer value can be used as the servicing method sees fit, for example, it could be used as a literal value or it could be interpreted as a pointer to a parameter or a results structure.

Ioctl routines are typically coded as large switch statements which dispatch the request. The return value is defined by the device driver, but it is normal practice to return -1 for failure.

The following gives an example of dd_ioctl(): int dd_ioctl (dev_handle_t *handle, int request, void *arg)

{

switch (request)

{

case DD_IOCTL_ARM:

return dd_arm ((dd_hdl_t*)handle, arg);

...

/* More cases here */

default:

}

}

208/515 7702033 Rev 27

UM1150 OSPlus device model

4.12.8 dd_block_read()

This method is responsible for performing reads of contiguous logical blocks from a device.

Given the handle to an open device, a logical block address, a buffer and several blocks to read, this call has to program the device to make the transfer occur. It should return -1 for failure, or else return the number of blocks read successfully.

int dd_block_read (dev_handle_t *handle, void *buf,

{

dd_hdl_t *hdl = (dd_hdl_t*)handle;

}

return dd_blk_read (handle->instance, buf, lba, len);

4.12.9 dd_block_write()

This method is responsible for performing writes of contiguous logical blocks to a device.

Given the handle to an open device, a logical block address, a buffer and several blocks to write, this call has to program the device to make the transfer occur. It should return -1 for failure, or else return the number of blocks written successfully.

int dd_block_write (dev_handle_t *handle, void *buf,

{

dd_hdl_t *hdl = (dd_hdl_t*)handle;

}

return dd_blk_write (handle->instance, buf, lba, len);

7702033 Rev 27 209/515

OSPlus GPDMA driver

5 OSPlus GPDMA driver

5.1

UM1150

GPDMA driver overview

The OSPlus general purpose direct memory access (GPDMA) driver provides an interface to the GPDMA hardware to perform data transfers while leaving the main CPU free to continue running application code. The GPDMA hardware presents itself as several channels, each of which can be used for general purpose data transfers. The GPDMA driver keeps to the OSPlus driver model, with a new GDPMA device being registered for each channel.

The GPDMA driver is supported on a limited number of ST20, ST40 and ST200 based platforms, and usually has five independent channels that can be used for general data transfers.

5.2

5.3

5.4

GPDMA driver transfer types

The GPDMA driver supports two distinct types of data transfer. The first is a single transfer that copies data in memory from one location to another. The second supported memory transfer type is scatter gather, which allows several single transfers to be chained together and executed as if the chain were one single data transfer.

●

●

●

The GDPMA driver supports the transfer of up to 4 Gbytes of data to and from aligned or non-aligned data structures in memory, organized as follows: a single location (0D) incrementing or decrementing linear arrays (1D) incrementing or decrementing rectangular arrays (2D)

Each data transfer can specify a transfer unit of 1, 2, 4, 8, 16 or 32 bytes, as well as timing characteristics including triggered, paced or free running. For more information on the features supported by the GPDMA hardware, see the appropriate system architecture document.

GPDMA driver configuration

The GPDMA driver does not presently support any user configuration options.

GPDMA driver initialization

The GPDMA driver is initialized by calling the function gpdma_initialize(). On initialization, the driver allocates and initializes its internal state, then queries the registry to determine whether the current platform supports the GPDMA hardware.

If the platform supports the GPDMA hardware, the settings (for example, base address and interrupt information) for each GPDMA channel are read from the registry. Each channel is then initialized to a known default state and registered with the device library with the prefix gpdma

and post fixed with the channel number. So the first GPDMA channel is registered as gpdma0

, the second gpdma1, and so on.

210/515 7702033 Rev 27

UM1150 OSPlus GPDMA driver

During initialization, at least one transfer structure is pre-allocated for each GPDMA channel and placed in a free pool. This caching of transfer structures helps reduce the overhead when setting up a new data transfer. On completion of the data transfer, the transfer structure is normally returned to the free pool. If the free pool is exhausted, new transfer structures are created as required.

5.5

5.5.1

GPDMA driver usage model

The GPDMA driver is written to conform to the OSPlus device model. Therefore w when the

GPDMA driver is initialized, and all GPDMA channels are registered with the device library, a GPDMA channel can be manipulated using the standard device library open, close, and ioctl functions. See

Chapter 4: OSPlus device model on page 134

for more detail on using the device library.

GPDMA channels are not represented as character or block devices. So there is no support for performing character or block orientated reads and writes. Instead, all communication with the GPDMA channels is handled through ioctls.

To help build the data transfers, several macros are defined. For a description of these macros, and how to use them see

Section 5.9: GPDMA driver macro definitions on page 217

. It is recommended that all data transfers are constructed and configured using these macros.

Constructing and executing a single transfer

To perform a single data transfer using the GPDMA, a free transfer structure must first be claimed from the free pool using the OSPLUS_IOCTL_GPDMA_CLAIM ioctl. If the transfer structure free pool is empty, then providing sufficient memory is available, a new transfer structure is created.

When the transfer structure has been claimed, it must be initialized ready to perform the transfer. As a first step, the macro GPDMA_TRANSFER_CONTROL is used to set the various control options, such as timing characteristics, and source and destination transfer type and unit size. Next, the macros GPDMA_TRANSFER_SAR and GPDMA_TRANSFER_DAR are used to set the source and destination attributes respectively. These attributes consist of the addresses in memory to be used for the transfer, and the length and stride of the memory.

Finally the macro GPDMA_TRANSFER_COUNT should be used to specify how many bytes should be transferred.

For simple transfers several macros are defined, of the form

GPDMA_INIT_x_y_TRANSFER

. When these macros are used in place of the

GPDMA_TRANSFER_*

macros, they initialize a transfer structure to default values. These macros need only be supplied with a source address, destination address, and the number of bytes to transfer.

When a transfer structure is initialized, it is placed on the GPDMA channel ready queue for processing. This is done using the OSPLUS_IOCTL_GPDMA_START ioctl, and passing the address of the transfer structure as a parameter. When on the ready queue, the transfer structure is processed at the earliest opportunity. To wait for the transfer to complete, the

OSPLUS_IOCTL_GPDMA_WAIT

ioctl is used, passing the address of the transfer structure.

When a transfer has been processed, the transfer structure should be returned to the free pool ready for reuse. This is done using OSPLUS_IOCTL_GPDMA_FREE and passing the address of the transfer.

7702033 Rev 27 211/515

OSPlus GPDMA driver

5.5.2

Note:

UM1150

Constructing and executing a list of transfers

To construct a scatter-gather transfer, each individual component of the transfer should be constructed as if it were a single transfer. When the individual transfer components have been constructed, one of them is chosen as the head transfer structure. All other components of the transfer should then be chained to this head transfer structure using the macro GPDMA_CHAIN_TRANSFER.

As with a single transfer, when all individual component transfers are chained together, the chained transfer can be queued using the OSPLUS_IOCTL_GPDMA_START ioctl, waited on using the OSPLUS_IOCTL_GPDMA_WAIT ioctl and freed using the

OSPLUS_IOCTL_GPDMA_FREE

ioctl. In all cases the address of the head transfer structure is passed.

It is not possible to wait on a single transfer within a list to be completed. Wait on all transfers in the list completing.

5.6 GPDMA driver header file gpdma.h

All the definitions relating to the GPDMA driver are in the file gpdma.h. The functions defined in gpdma.h are explained in

Section 5.8 on page 216

, the ioctls are explained in

Section 5.7 on page 214

and the macros are explained in

Section 5.9 on page 217

.

Table 39.

Functions defined in gpdma.h

Function

gpdma_initialize()

Description

Initialize the GPDMA driver

Table 40.

Types defined in gpdma.h

Type

gpdma_linked_list_entry_t gpdma_transfer_t gpdma_transfer_timing_t gpdma_transfer_type_t gpdma_transfer_unit_t

Description

GPDMA memory mapped registers

GPDMA transfer structure

Enumeration of supported GPDMA timing options

Enumeration of supported GPDMA transfer types

Enumeration of supported GPDMA transfer unit sizes

212/515 7702033 Rev 27

UM1150 OSPlus GPDMA driver

Table 41.

Macros defined in gpdma.h

Macro

GPDMA_CHAIN_TRANSFER

GPDMA_INIT_0D_0D_TRANSFER

GPDMA_INIT_0D_1DI_TRANSFER

GPDMA_INIT_1DI_0D_TRANSFER

GPDMA_INIT_1DI_1DI_TRANSFER

GPDMA_TRANSFER_CONTROL

GPDMA_TRANSFER_COUNT

GPDMA_TRANSFER_DAR

GPDMA_TRANSFER_SAR

Description

Chain two transfers together

Initialize a basic 0D to 0D transfer

Initialize a basic 0D to 1D transfer

Initialize a basic 1D to 0D transfer

Initialize a basic 1D to 1D transfer

Set the transfer control options

Set the transfer size

Set the transfer destination information

Set the transfer source information

Table 42.

Ioctls defined in gpdma.h

Ioctl

OSPLUS_IOCTL_GPDMA_CLAIM

OSPLUS_IOCTL_GPDMA_FREE

OSPLUS_IOCTL_GPDMA_START

OSPLUS_IOCTL_GPDMA_WAIT

Description

Claim a transfer from the free pool

Return a transfer to the free pool

Queue a transfer to be performed

Wait until a transfer has completed

7702033 Rev 27 213/515

OSPlus GPDMA driver UM1150

5.7 GPDMA driver ioctl definitions

These ioctl definitions relate to the device_ioctl() function, see

device_ioctl on page 192

for more details.

OSPLUS_IOCTL_GPDMA_CLAIM

Claim a transfer from the GPDMA channel free pool

Arguments:

Returns:

The address of a transfer pointer.

Returns 0 for success, -1 for failure.

Description:

See also:

This ioctl claims a transfer from the GPDMA channel free transfer pool and sets the address of the transfer pointer passed into the claimed transfer. The claimed transfer can then be initialized ready to perform a DMA operation.

Note: The user can access the GPDMA transfer internals, however this is strongly discouraged. The GPDMA transfer internals are likely to change and should only be accessed through the supplied macros and API.

OSPLUS_IOCTL_GPDMA_FREE

OSPLUS_IOCTL_GPDMA_FREE

Free the transfer or chain of transfers

Arguments:

Returns:

Description:

See also:

The address of an individual transfer or the head of a list of chained transfers.

Returns 0 for success, -1 for failure.

This ioctl releases the transfer or list of chained transfers back to the GPDMA channel free transfer pool ready for reuse.

OSPLUS_IOCTL_GPDMA_CLAIM

OSPLUS_IOCTL_GPDMA_START

Queue a transfer ready to be processed by the GPDMA channel

Arguments:

Returns:

See also:

The address of an individual transfer or the head of a list of chained transfers.

Returns 0 for success, -1 for failure.

This ioctl queues the transfer or list of chained transfers on the end of the GPDMA channel ready queue. The transfer is then processed automatically.

OSPLUS_IOCTL_GPDMA_WAIT

214/515 7702033 Rev 27

UM1150 OSPlus GPDMA driver

OSPLUS_IOCTL_GPDMA_WAIT

Wait on a transfer that has been queued to be processed

Arguments:

Returns:

Description:

See also:

The address of an individual transfer or the head of a list of chained transfers.

Returns 0 for success, -1 for failure.

This ioctl waits on the transfer, or list of chained transfers, to be processed by the

GPDMA channel.

OSPLUS_IOCTL_GPDMA_START

7702033 Rev 27 215/515

OSPlus GPDMA driver UM1150

5.8 GPDMA driver function definitions gpdma_initialize

Initialize the GPDMA driver

Definition:

Arguments:

Returns:

Description:

int gpdma_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the GPDMA driver. When initialized, the GPDMA driver creates a new device instance and registers it with the device library for each GPDMA channel that is supported on the platform.

216/515 7702033 Rev 27

UM1150 OSPlus GPDMA driver

5.9 GPDMA driver macro definitions

GPDMA_CHAIN_TRANSFER

Chain two transfers together

Definition:

#define GPDMA_CHAIN_TRANSFER (

head,

tail)

Arguments:

head tail

The address of a GPDMA transfer to be the head of the chain.

The address of a GPDMA transfer to be the tail of the chain.

Description:

This macro links the two valid transfers specified. One transfer is the head, the other the tail. The tail transfer should be a single transfer and not a list.

GPDMA_INIT_0D_0D_TRANSFER

Initialize a 0D to 0D transfer

Definition:

#define GPDMA_INIT_0D_0D_TRANSFER (

transfer,

src,

dst,

count)

Arguments:

transfer src dst count

The address of a valid GPDMA transfer.

The transfer source address.

The transfer destination address.

The number of bytes to transfer.

Description:

See also:

This macro initializes the transfer specified to be a free-running transfer with a single location source and a single location destination. The address of the single location source is specified by the src parameter and should be an unsigned integer. The address of the single location destination is specified by dst and should be an unsigned integer. The number of bytes to transfer is specified by the count parameter and should be an unsigned integer.

GPDMA_INIT_0D_1DI_TRANSFER

, GPDMA_INIT_1DI_0D_TRANSFER,

GPDMA_INIT_1DI_1DI_TRANSFER

7702033 Rev 27 217/515

OSPlus GPDMA driver UM1150

GPDMA_INIT_0D_1DI_TRANSFER

Initialize a 0D to 1D incrementing transfer

Definition:

#define GPDMA_INIT_0D_1DI_TRANSFER (

transfer,

src,

dst,

count)

Arguments:

transfer src dst count

The address of a valid GPDMA transfer.

The transfer source address.

The transfer destination address.

The number of bytes to transfer.

Description:

See also:

This macro initializes the transfer specified to be a free-running transfer with a single location source and a 1D incrementing linear array destination. The address of the single location source is specified by the src parameter and should be an unsigned integer. The address of the 1D incrementing linear array destination is specified by dst

and should be an unsigned integer. The number of bytes to transfer is specified by the count parameter and should be an unsigned integer.

GPDMA_INIT_1DI_0D_TRANSFER

, GPDMA_INIT_0D_0D_TRANSFER,

GPDMA_INIT_1DI_1DI_TRANSFER

GPDMA_INIT_1DI_0D_TRANSFER

Initialize a 1D to 0D incrementing transfer

Definition:

#define GPDMA_INIT_1DI_0D_TRANSFER (

transfer,

src,

dst,

count)

Arguments:

transfer src dst count

The address of a valid GPDMA transfer.

The transfer source address.

The transfer destination address.

The number of bytes to transfer.

Description:

See also:

This macro initializes the transfer specified to be a free-running transfer with a 1D incrementing linear array source and a single location destination. The address of the

1D incrementing linear array source is specified by the src parameter and should be an unsigned integer. The address of the single location destination is specified by dst

and should be an unsigned integer. The number of bytes to transfer is specified by the count parameter and should be an unsigned integer.

GPDMA_INIT_0D_1DI_TRANSFER

, GPDMA_INIT_0D_0D_TRANSFER,

GPDMA_INIT_1DI_1DI_TRANSFER

218/515 7702033 Rev 27

UM1150 OSPlus GPDMA driver

GPDMA_INIT_1DI_1DI_TRANSFER

Initialize a 1D to 1D incrementing transfer

Definition:

#define GPDMA_INIT_1DI_1DI_TRANSFER (

transfer,

src,

dst,

count)

Arguments:

transfer src dst count

The address of a valid GPDMA transfer.

The transfer source address.

The transfer destination address.

The number of bytes to transfer.

Description:

See also:

This macro initializes the transfer specified to be a free-running transfer with a 1D incrementing linear array source and a 1D incrementing linear array destination. The address of the source is specified by the src parameter and should be an unsigned integer. The address of the destination is specified by dst and should be an unsigned integer. The number of bytes to transfer is specified by the count parameter and should be an unsigned integer.

GPDMA_INIT_0D_1DI_TRANSFER

, GPDMA_INIT_1DI_0D_TRANSFER,

GPDMA_INIT_0D_0D_TRANSFER

7702033 Rev 27 219/515

OSPlus GPDMA driver UM1150

GPDMA_TRANSFER_CONTROL

Initialize the control options for a GPDMA transfer

Definition:

#define GPDMA_TRANSFER_CONTROL (

transfer,

timing,

stype,

sunits,

dtype,

dunits)

Arguments:

transfer timing stype sunits dtype dunits

The address of a valid GPDMA transfer.

The timing characteristics of the transfer.

The transfer source type.

The transfer source unit size.

The transfer destination type.

The transfer destination unit size.

Description:

This macro sets the control options for the transfer specified, consisting of a timing mode taken from gpdma_transfer_timing_t, source and destination types taken from gpdma_transfer_type_t and source and destination unit sizes taken from gpdma_transfer_unit_t

. See

Table 43

,

Table 44

and

Table 45

for details of the

possible values.

Table 43.

gpdma_transfer_timing_t values

Enumeration name

GPDMA_TIMING_FREE

GPDMA_TIMING_PACED_DST

GPDMA_TIMING_PACED_SRC

GPDMA_TIMING_TRIGGERED

Description

Transfer is free running

Transfer is paced to the destination

Transfer is paced to the source

Transfer is triggered

Table 44.

gpdma_transfer_type_t values

Enumeration name

GPDMA_TRANSFER_0D

GPDMA_TRANSFER_1D_DEC

GPDMA_TRANSFER_1D_INC

GPDMA_TRANSFER_2D_DEC

GPDMA_TRANSFER_2D_INC

Description

Transfer is a single location

Transfer is a decrementing linear array

Transfer is an incrementing linear array

Transfer is a decrementing rectangular array

Transfer is an incrementing rectangular array

220/515 7702033 Rev 27

UM1150 OSPlus GPDMA driver

See also:

Table 45.

gpdma_transfer_unit_t values

Enumeration name

GPDMA_UNIT_1

GPDMA_UNIT_2

GPDMA_UNIT_4

GPDMA_UNIT_8

GPDMA_UNIT_16

GPDMA_UNIT_32

1-byte units

2-byte units

4-byte units

8-byte units

16-byte units

32-byte units

Description

GPDMA_TRANSFER_SAR

, GPDMA_TRANSFER_DAR, GPDMA_TRANSFER_COUNT

7702033 Rev 27 221/515

OSPlus GPDMA driver UM1150

GPDMA_TRANSFER_COUNT

Initialize the number of bytes to transfer in a GPDMA transfer

Definition:

#define GPDMA_TRANSFER_COUNT (

transfer,

size)

Arguments:

transfer size

The address of a valid GPDMA transfer.

The number of bytes to transfer.

Description:

See also:

This macro sets the number of bytes to be transferred. The maximum number of bytes that can be transferred is 4 Gbytes.

GPDMA_TRANSFER_CONTROL

, GPDMA_TRANSFER_SAR, GPDMA_TRANSFER_DAR

GPDMA_TRANSFER_DAR

Initialize the destination options for a GPDMA transfer

Definition:

#define GPDMA_TRANSFER_DAR (

transfer,

addr,

length,

stride)

Arguments:

transfer addr length stride

The address of a valid GPDMA transfer.

The address of the transfer source.

The 2D structure line length.

The 2D structure stride.

Description:

See also:

This macro sets the transfer destination configuration. The address of the transfer destination should be specified as an unsigned integer. For 2D transfers involving rectangular arrays, the length of one line of the array and the stride between lines must be specified as unsigned integers. For 0D or 1D transfers these parameters can be 0.

GPDMA_TRANSFER_CONTROL

, GPDMA_TRANSFER_SAR, GPDMA_TRANSFER_COUNT

222/515 7702033 Rev 27

UM1150 OSPlus GPDMA driver

GPDMA_TRANSFER_SAR

Initialize the source options for a GPDMA transfer

Definition:

#define GPDMA_TRANSFER_SAR (

transfer,

addr,

length,

stride)

Arguments:

transfer addr length stride

The address of a valid GPDMA transfer.

The address of the transfer source.

The 2D structure line length.

The 2D structure stride.

Description:

See also:

This macro sets the transfer source configuration. The address of the transfer source should be specified as an unsigned integer. For 2D transfers involving rectangular arrays, the length of one line of the array and the stride between lines must be specified as unsigned integers. For 0D or 1D transfers, these parameters can be 0.

GPDMA_TRANSFER_CONTROL

, GPDMA_TRANSFER_DAR, GPDMA_TRANSFER_COUNT

7702033 Rev 27 223/515

OSPlus PCI driver

6 OSPlus PCI driver

UM1150

The OSPlus PCI driver provides support for PCI based peripherals on a PCI v2.1 compliant

PCI bus. The PCI driver detects peripherals attached to the PCI bus and correctly configures and maps them into memory. The PCI driver also provides a management interface to the PCI peripheral for retrieving peripheral information, such as memory base address and interrupt information, and for controlling the peripheral. The PCI driver is currently supported on a limited number of ST20 and ST40 based platforms.

The PCI driver does not presently support any user configuration options.

The PCI driver is initialized by calling the function pci_initialize(). On initialization the driver first checks the registry to determine whether the current platform supports a PCI bus; if so, the PCI driver allocates and initializes its internal state. Next the PCI driver reads all required settings from the registry and initializes the PCI controller and associated hardware to a known working default state.

When the PCI driver has been initialized, probing for devices begins. Up to a maximum of

255 PCI buses can be probed, with each bus containing a maximum of 32 PCI slots, and each slot containing a maximum of one device capable of supporting a maximum of eight separate functions. In practice there is usually no more than one or two buses with each containing no more than five slots.

While probing, a device header is read from the configuration space registers for each PCI peripheral found. The information in the device header is used to determine whether the device function, its interrupt pin, and the PCI peripheral is a multifunction device. If the PCI peripheral is a multifunction device, further device headers are read for each device function supported. All supported device functions are configured and mapped into the PCI address space, and a PCI device is registered with the device library.

If the PCI peripheral is a bridge between two PCI buses, the probe routine recurses and probes the new bus for PCI peripherals. On completion of the probe, the bridge chip is mapped into PCI address space and registered with the device library.

When all buses and devices have been probed, configured and registered with the device library, initialization of the PCI driver is complete.

Each PCI device function that is found is registered with the device library with the prefix pci

and postfixed with the device function instance number. So the first device function is named pci0, the next pci1, and so on.

224/515 7702033 Rev 27

UM1150

6.4

Note:

OSPlus PCI driver

PCI driver address space

The PCI driver maps PCI memory and PCI IO address space to CPU address space to allow memory mapped access to PCI peripherals.

The PCI controllers found on some devices do not support CPU access to memory mapped

I/O MBARS. Therefore, the recommended method to access a PCI card’s I/O registers is by using the ioctl methods described in

Section 6.7 on page 229

.

6.5

6.5.1

PCI driver usage model

The PCI driver has been written to conform to the OSPlus device model. Therefore when the PCI driver has been initialized, and all PCI devices registered with the device library, a

PCI device can be accessed using the standard device library open, close, and ioctl functions. See

Chapter 4: OSPlus device model on page 134

for more details on using the

device library.

PCI devices are not represented as character block devices. So there is no support for performing character or block orientated reads and writes. Instead all communications with

PCI devices are handled through ioctls.

Finding a PCI device

Because of the naming convention, there is no easy way to know which PCI device corresponds to a particular PCI peripheral. The solution is to loop the opening of each PCI device separately, and read the vendor and product identifiers, to compare with those for the device being searched for. If the opening of a device fails, the value of errno should be checked. If the value of errno is set to ENODEV, this means there are no more PCI devices to open.

The following code example shows a function that can be used to find the first PCI device matching particular vendor and device identifiers. On finding the first matching PCI device, the PCI device instance number is returned. If no match is found, -1 is returned.

int find_pci_device (unsigned short vid, unsigned short did)

{

int i;

char name[16];

device_handle_t *dev;

pci_info_t info;

for (i = 0; ; i++)

{

/* Generate the name of the PCI device to attempt to open */

sprintf (name, "pci%0d", i);

/* Attempt to open the PCI device */

if ((dev = device_open (name, OSPLUS_O_RDWR)) == NULL)

{

/* If error, then continue to next device */

if (errno != ENODEV)

{

7702033 Rev 27 225/515

OSPlus PCI driver UM1150

} continue;

/* No more devices and no match found! */

}

/* Get device information */

if (device_ioctl (dev, OSPLUS_IOCTL_PCI_INFO,

{

/* Check device vendor and device IDs */

if ((info.vid == vid) && (info.did == did))

{

/* There is a match, close and return device number */

6.5.2

6.5.3

}

}

/* Close the device */

}

}

/* This should not be reached */

return -1;

Enabling a PCI device

Before a PCI device can be used, it must be enabled. This allows the PCI device to begin decoding memory and IO accesses, and permits the device to generate bus master cycles.

To enable or disable a PCI device the ioctl named OSPLUS_IOCTL_PCI_ENABLE should be used.

Memory mapped PCI devices

When a PCI device has been registered with the device library and enabled, it can be accessed like any other memory-mapped peripheral. The CPU address at which the device can be accessed can be found by querying the device memory base address register

(MBAR) start address, end address and attributes with the ioctl named

OSPLUS_IOCTL_PCI_GET_MBAR

.

Each MBAR on the device is mapped into the PCI memory address space. A device can have more than one MBAR, but usually, the first MBAR is of most interest. The number of

MBARs can be queried using OSPLUS_IOCTL_PCI_GET_MBAR, in which case the structure passed in should have the mbar field set to -1. On return, the mbar field of the structure is set to the maximum number of MBARs on the device.

After obtaining the start address, end address and attributes of the required MBAR, use the start address as the device base address for accessing the device’s MBAR, as for any other memory-mapped peripheral.

226/515 7702033 Rev 27

UM1150

Note:

OSPlus PCI driver

The PCI controllers found on some devices do not support CPU access to memory mapped

I/O MBARS. Therefore, the recommended method to access a PCI card’s I/O registers is by using the ioctl methods described in

Section 6.7 on page 229

.

During the PCI device function initialization, the device interrupt pin number is determined, if it exists. This is combined with the slot number of the PCI device and is then used to query the registry for an interrupt name and level; it is then stored as part of the PCI device information structure. A copy of this structure can be retrieved using the

OSPLUS_IOCTL_PCI_INFO

ioctl.

When the PCI device information structure has been retrieved, the interrupt name should be checked to ensure it is non-null. If it is null, the device is not interrupt driven.

An application can use the interrupt name and the interrupt level to install an interrupt handler for the device, using the OSPlus interrupt API. When installing an interrupt handler, osplus_interrupt_install_shared()

should be used because not every interrupt pin for every device is unique. When the interrupt handler fires, check the expected device asserted the interrupt. If not, the interrupt handler should return -1 to allow any further chained handler to execute.

PCI device interrupts are usually non-maskable on the ST20 and ST40 and by default not enabled at the hardware level. The PCI driver provides an ioctl named

OSPLUS_IOCTL_PCI_INTERRUPT

to enable or disable a device interrupt. The PCI driver sets up any required hardware to allow the device interrupt through to the CPU. This usually takes the form of programming an EPLD on the board.

A PCI device interrupt should only be enabled after the PCI device has been enabled and an interrupt handler for it installed.

7702033 Rev 27 227/515

OSPlus PCI driver

6.6

UM1150

PCI driver header file: pci.h

All the definitions relating to the PCI driver are in the file pci.h. The functions defined in pci.h

are explained in

Section 6.8 on page 236

and the macros are explained in

Section 6.9 on page 237

.

Table 46.

Functions defined in pci.h

Function

pci_initialize()

Description

Initialize the PCI driver

Table 47.

Types defined in pci.h

Type

pci_cfg_rw_t pci_io_rw_t pci_info_t pci_mbar_t

Table 48.

Macros in pci.h

Macro

CPU_TO_PCI

PCI_TO_CPU

Description

Read/write to PCI configuration space

Read/write to PCI I/O space

PCI device information

PCI memory base address register type

Description

Convert a CPU address to a PCI address

Convert a PCI address to a CPU address

Table 49.

Ioctls defined in pci.h

Ioctl

OSPLUS_IOCTL_PCI_CFG_RW

OSPLUS_IOCTL_PCI_IO_RW

OSPLUS_IOCTL_PCI_ENABLE

OSPLUS_IOCTL_PCI_GEN_MADIM

OSPLUS_IOCTL_PCI_GET_MBAR

OSPLUS_IOCTL_PCI_INFO

OSPLUS_IOCTL_PCI_INTERRUPT

Description

Read/write a configuration space register

Read/write an I/O space register

Enable/disable a PCI device

Generate a master abort (MADIM) interrupt

Get a memory base address register

Return details of a PCI device

Enable/disable a PCI device interrupt

228/515 7702033 Rev 27

UM1150 OSPlus PCI driver

6.7 PCI driver ioctl definitions

These ioctl definitions relate to the device_ioctl() call. See

device_ioctl on page 192

for

more details.

OSPLUS_IOCTL_PCI_CFG_RW

Perform a PCI configuration space read or write

Arguments:

Returns:

Description:

The address of a PCI configuration read/write structure.

Returns 0 for success, -1 for failure.

This ioctl performs a device configuration space read or write access. The PCI configuration read/write structure passed in must specify whether the access is a read or a write, what offset the access should occur at and how many bytes should be read or written (this must be 1, 2, or 4 bytes). If the access is a write the value to write should be supplied. If the access is a read, the value read is written to the structure.

The PCI configuration read/write structure has the following format: typedef struct

{ unsigned int rw; unsigned int offset; unsigned int nob; unsigned int value;

} pci_cfg_rw_t;

These fields are described in

Table 50

.

Table 50.

pci_cfg_rw_t fields

Field name

rw offset nob value

Description

Specify if the access is a read or write, using:

PCI_CFG_READ

to specify a configuration space read,

PCI_CFG_WRITE

to specify a configuration space write

Offset into configuration space to perform access

Number of bytes to read/write (1, 2, or 4)

Value read or value to write

7702033 Rev 27 229/515

OSPlus PCI driver UM1150

The configuration space offset required for the access, can be specified using one of the symbolic names in

Table 51

.

Table 51.

PCI configuration header offsets

Symbolic name

PCI_CFG_VID

PCI_CFG_DID

PCI_CFG_CMD

PCI_CFG_STATUS

PCI_CFG_RID

PCI_CFG_PROGIF

PCI_CFG_SUBCLASS

PCI_CFG_CLASS

PCI_CFG_CLS

PCI_CFG_MLT

PCI_CFG_HDR

PIC_CFG_BIST

PCI_CFG_MBAR_START

Type 0 offsets

PCI_CFG_HT0_CBCISP

PCI_CFG_HT0_SSVID

PCI_CFG_HT0_SSDID

PCI_CFG_HT0_ROMBAR

PCI_CFG_HT0_CAPPTR

PCI_CFG_HT0_INTLINE

PCI_CFG_HT0_INTPIN

PCI_CFG_HT0_MINGNT

PCI_CFG_HT0_MAXLAT

Type 1 offsets

PCI_CFG_HT1_PRIBUS

PCI_CFG_HT1_SECBUS

PCI_CFG_HT1_SUBBUS

PCI_CFG_HT1_SECLATTM

PCI_CFG_HT1_IOBASEL

PCI_CFG_HT1_IOLIMITL

PCI_CFG_HT1_SECSTAT

PCI_CFG_HT1_MEMBASE

PCI_CFG_HT1_MEMLIMIT

Description

Vendor ID register

Device ID register

Command register

Status register

Revision register

Programming interface register

Subclass code register

Class code register

Cache line size register

Latency register

Header type register

Built In software test register

First MBAR register

Card Bus CIS pointer register

Subsystem vendor ID register

Subsystem device ID register

Expansion ROM base address register

Capability pointer register

Interrupt line register

Interrupt pin register

Minimum grant register

Maximum latency register

Primary bus register

Secondary bus register

Subordinate bus number register

Secondary latency timer register

I/O base register

I/O limit register

Secondary status register

Memory base register

Memory limit register

230/515 7702033 Rev 27

UM1150 OSPlus PCI driver

Table 51.

PCI configuration header offsets (continued)

Symbolic name Description

PCI_CFG_HT1_PFMEMBASEL

PCI_CFG_HT1_PFMEMLIMITL

PCI_CFG_HT1_PFMEMBASEH

PCI_CFG_HT1_PFMEMLIMITH

PCI_CFG_HT1_IOBASEH

PCI_CFG_HT1_IOLIMITH

PCI_CFG_HT1_CAPPTR

PCI_CFG_HT1_ROMBAR

PCI_CFG_HT1_INTLINE

PCI_CFG_HT1_INTPIN

PCI_CFG_HT1_BRGCTL

Prefhable memory base register

Prefhable memory limit register

Prefhable memory base register

Prefhable memory limit register

I/O base register

I/O limit register

Capability pointer register

Expansion ROM base address register

Interrupt line register

Interrupt pin register

Bridge control register

OSPLUS_IOCTL_PCI_IO_RW

Perform a PCI I/O space read or write

Arguments:

Returns:

Description:

The address of a PCI I/O read/write structure.

Returns 0 for success, -1 for failure.

This ioctl performs a device I/O space read or write access. The PCI I/O read/write structure passed in must specify whether the access is a read or a write, the address where the access occurs and how many bytes are to be read or written (this must be

1, 2, or 4 bytes). If the access is a write, then the application provides the value to write in the value field. If the access is a read, then the ioctl writes the value read to the structure.

This API allows PCI I/O accesses on controllers that do not allow CPU access to I/O

MBARS. The address specified is a CPU address within a PCI device’s I/O MBAR window. This API works on all PCI controllers, whereas direct CPU access to a memory mapped I/O MBAR may not work, depending on the controller.

The PCI I/O read/write structure has the following format: typedef struct

{ void *address;

} pci_io_rw_t;

These fields are described in

Table 52

.

7702033 Rev 27 231/515

OSPlus PCI driver UM1150

Table 52.

pci_io_rw_t fields

Field name

rw address

Description

Specify if the access is a read or write, using:

– PCI_IO_READ to specify a configuration space read

– PCI_IO_WRITE to specify a configuration space write

CPU address to access. This should be within the device’s I/O MBAR window.

Number of bytes to read/write (1, 2, or 4)

Value read or value to write nob value

OSPLUS_IOCTL_PCI_ENABLE

Enable or disable a PCI device

Arguments:

Returns:

Description:

See also:

An integer value where 0 specifies enable the PCI device and 1 specifies disable the

PCI device.

Returns 0 for success, -1 for failure.

This ioctl enables or disables the PCI device.

OSPLUS_IOCTL_PCI_INTERRUPT

OSPLUS_IOCTL_PCI_GEN_MADIM

Generate a master abort interrupt

Arguments:

Returns:

Description:

None.

Returns 0 for success, -1 for failure.

This ioctl generates a master abort interrupt.

232/515 7702033 Rev 27

UM1150 OSPlus PCI driver

OSPLUS_IOCTL_PCI_GET_MBAR

Get the start address, end address and attributes of a memory base address register

Arguments:

Returns:

Description:

The address of the MBAR structure to populate with the MBAR details.

Returns 0 for success, -1 for failure.

This ioctl reads the start address, end address and attributes of a PCI device MBAR

(memory base address register). The MBAR structure has the following format: typedef struct

{

} pci_mbar_t;

Table 53.

pci_mbar_t fields

Field name

mbar start end flags

MBAR details to read

MBAR start

MBAR end

MBAR attributes

Description

To read an MBAR, the MBAR structure must have mbar set to the MBAR to be read.

If the MBAR is set to -1, the number of MBARs for the device are written to mbar. If the MBAR does not exist, errors are returned.

7702033 Rev 27 233/515

OSPlus PCI driver

OSPLUS_IOCTL_PCI_INFO

Return the basic information about a PCI device

Arguments:

Returns:

Description:

The address of the PCI device information structure to populate.

Returns 0 for success, -1 for failure.

This ioctl populates the addressed structure with the PCI device information.

The PCI device information structure has the following format: typedef struct

{

UM1150

unsigned short vid; unsigned short did; unsigned char rid; unsigned char progif; unsigned char sub_class; unsigned char pci_class;

} pci_info_t;

These fields are described in

Table 54

.

Table 54.

pci_info_t fields

Field name

bus slot func vid did rid progif sub_class pci_class intr_name intr_level

Description

Bus number of device

Slot number of device

Function number of device

Vendor ID

Device ID

Revision ID

Programming interface

Subclass

Class

Interrupt name, or NULL if interrupts are not used

Interrupt level

234/515 7702033 Rev 27

UM1150 OSPlus PCI driver

OSPLUS_IOCTL_PCI_INTERRUPT

Enable or disable a PCI device interrupt

Arguments:

Returns:

Description:

An integer value where 0 specifies enable the PCI device interrupt and 1 specifies disable the PCI device interrupt.

Returns 0 for success, -1 for failure.

This ioctl enables or disables the PCI interrupts for the device at a hardware level. PCI interrupts are usually nonmaskable with the standard OSPlus interrupt API and must therefore be controlled at the hardware level.

See also:

OSPLUS_IOCTL_PCI_ENABLE

7702033 Rev 27 235/515

OSPlus PCI driver UM1150

6.8 PCI driver function definitions pci_initialize

Initialize the PCI driver

Definition:

Arguments:

Returns:

Description:

int pci_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the PCI driver. When initialized, the PCI driver creates a new device instance and registers it with the device library for each PCI device supported on the platform.

236/515 7702033 Rev 27

UM1150 OSPlus PCI driver

6.9 PCI driver macro definitions

CPU_TO_PCI

Convert a CPU hardware address to a PCI hardware address

Definition:

Arguments:

#define CPU_TO_PCI (address) address

The CPU hardware address from which to convert.

Description:

See also:

This macro converts a CPU hardware address to the equivalent PCI hardware address.

PCI_TO_CPU

PCI_TO_CPU

Convert a PCI hardware address to a CPU hardware address

Definition:

Arguments:

#define PCI_TO_CPU (address) address

The PCI hardware address from which to convert.

Description:

See also:

This macro converts a PCI hardware address to the equivalent CPU hardware address. This macro would be used, for instance, to convert the address of a PCI device MBAR starting address to an address the CPU can read and write to.

CPU_TO_PCI

7702033 Rev 27 237/515

OSPlus file systems

7 OSPlus file systems

UM1150

OSPlus provides support for file systems through a generic top-level virtual file system

(VFS) layer and several subordinate file systems.

The subordinate file systems currently supported are:

●

●

●

●

●

●

E2FS (compatible with ext2)

FAT12

FAT16

FAT32

LAFS

MSFS

The VFS provides the generic top-level functions called by user applications. The subordinate file systems provide the lower level specific implementations.

By separating the application interface and the specific implementations, new file systems can be integrated seamlessly in the future.

The subordinate file systems use the generic device library to communicate with the real hardware, so it is possible to support file systems on any device that supports block read/write.

7.2 Virtual file system (VFS)

The VFS provides the top-level generic functions called by the user-level application. These functions provide an interface similar to typical C file I/O operations.

Supported operations include: open/close, read/write, seek/tell/rewind, unlink, chmod

, stat and flush for both files and directories.

7.2.1 Initialization

Note:

Registering the first subordinate file system automatically initializes the VFS. This happens when the user application calls the subordinate file systems initialization routine, for example, e2fs_vfs_init(), fat_vfs_init() or lafs_vfs_init().

At least one subordinate file system must be registered before VFS functions can be called.

After the VFS is initialized it is possible to create mount points using the vfs_mount() function and delete them with vfs_umount(). A mount point associates a logical directory name and a subordinate file system type with a volume on a physical device, such as a logical volume device. Once a mount point is created, the files and directories on the device can be accessed by specifying a full path that starts with the mount point’s root directory name. The VFS manages the mount points but the subordinate file system performs the actions requested.

238/515 7702033 Rev 27

UM1150

7.2.3

7.2.4

OSPlus file systems

There are restrictions to the mount points naming conventions. See

vfs_mount on page 289

for details.

Files and directories

A file is a named collection of related data. Files are stored in a hierarchical list where each node is called a directory. A directory contains directory entries, which can represent files or subdirectories.

When a directory is first created it automatically has two directory entries called ‘.’ and ‘..’, which point to the directory and its parent directory respectively. A directory can have only one parent but can have one or more files and subdirectories.

Data and metadata

A file contains data. Data is accessed using functions such as vfs_read() and vfs_write()

. A file also has metadata associated with it that is specific to the subordinate file type used. Both the data and metadata are present on the physical device. The metadata might not be updated following a write and is not updated until the file is flushed or closed. If a particular write operation is for critical data, it may be necessary to follow the write with a vfs_fflush() or vfs_sync() to ensure the metadata is also written to the physical device.

The VFS and subordinate file systems can be used with any device that supports block oriented read and write operations, that is, device_block_read(), device_block_write()

, device_streaming_read() or device_streaming_write()

. For mass storage devices managed by the LVM, the subordinate file system performs additional validation using the partition raw_type (see

Section 8.2.2: OSPlus supported partition types on page 326

).

When a VFS function fails it sets the threads errno variable with a value indicating the nature of the error. These values are defined in the errno.h file supplied with the toolset. errno

values specific to a function are described in the function description. Generic errno

values returned by most VFS functions are described in

Table 55

.

E2BIG

EACCES

EBADF

EBUSY

EEXIST

EINVAL

EIO

EISDIR

Table 55.

VFS generic errno values

Errno value Description

Number is too large.

Permission denied.

Bad handle.

Device or volume is being used by another task.

File or directory already exists.

A parameter passed to the function is invalid.

An I/O error occurred.

Is a directory.

7702033 Rev 27 239/515

OSPlus file systems UM1150

Table 55.

VFS generic errno values (continued)

Errno value

ENODEV

ENOENT

ENOMEM

ENOSPC

ENOTDIR

ENOTEMPTY

ENOTSUP

ENXIO

EROFS

ENAMETOOLONG

Description

The specified device does not exist.

No such file or directory.

A memory allocation failed.

The volume is full.

Is not a directory.

Is not empty.

Operation not supported.

No such device or address.

Write operation attempted on a read-only file system.

The file name given is too long for the file system.

Many subordinate file systems perform caching to improve performance and therefore need to track whether the on-disk structure is in a consistent state.

When the volume is first mounted, with vfs_mount(), it is clean. Any partial writes or unwritten cached data means that it may be dirty or inconsistent until the cache is flushed.

The vfs_sync() and vfs_sync_all() functions flush the cache and mark the volume as clean. When the volume is unmounted, using vfs_umount(), the cache is flushed and the volume is marked as clean.

Many file systems record the current state in the on-disk structures and this value is one of the things checked by the vfs_mount() function. If the volume is dirty the vfs_mount() fails with errno set to EAGAIN to signify the volume needs vfs_fsck() to be run to restore it to a consistent state.

The standard VFS functions contain 32-bit variables for file sizes and therefore limit the total file size to 4 Gbytes (depending on the underlying file system). Files larger than 4 Gbytes are supported through additional 64-bit versions of the VFS functions, in particular vfs_fseek64()

, vfs_fstat64(), vfs_ftell64(), vfs_resize64() and vfs_stat64()

. Where the toolset for a particular core doesn’t have native 64-bit support

(for example, ST20-C1 and ST20-C2), alternative prototypes using two 32-bit values are provided. If any of the parameters to a 64-bit function call exceeds the largest value supported by the subordinate file system, the function fails with errno set to E2BIG.

The VFS provides a registry key that can be set by the user, with the address of a function that returns the current real time expressed as seconds since 00:00:00 1/1/1970. If timestamps are supported by a subordinate file system, the file system can call the usersupplied function to read the current time. Most subordinate file systems read this key only once at mount time and copy the address for subsequent calls.

240/515 7702033 Rev 27

UM1150

Note:

OSPlus file systems

To set the time function use: registry_key_set (

VFS_REGISTRY_NODE,

VFS_REGISTRY_GET_TIME,

(void **)your_get_time_fn);

The VFS does not use this registry key or the supplied function, it is only provided at the

VFS level to avoid duplication when multiple subordinate file systems are in use.

The VFS API is based on ASCII strings and therefore does not support Unicode characters.

Subordinate file systems may support alternate methods to retrieve any on-disk information in other character encoding schemes by using special ioctls (refer to

Section 7.4.4: Long filename support on page 254

).

7.2.11 VFS header file: vfs.h

All the definitions relating to the VFS interface are in the file vfs.h. The functions defined in vfs.h

are explained in

Section 7.7: File systems function definitions on page 258

.

vfs_chmod() vfs_close() vfs_closedir() vfs_creat() vfs_dcntl vfs_defrag() vfs_fchmod() vfs_fclose() vfs_fcntl() vfs_feof() vfs_fflush() vfs_fgetc() vfs_fgetpos() vfs_fgets() vfs_fopen() vfs_format() vfs_fprintf() vfs_fputc() vfs_fputs() vfs_fread()

Table 56.

Functions defined in vfs.h

Function Description

Change the access permissions on a file or directory

Close a file

Close a directory

Create a new file

Issue control commands for a directory

Defragment a volume

Change the access permissions on a file

Close a file

Issue control commands for a file

Check the EOF flag

Write any cached data (and metadata) for the file to disk

Get a single character from a file

Get the current file position

Get a string from the file

Open a file

Format a device with a new file system

Print a formatted string to a file

Write a single character to a file

Write a string to a file

Read data from a file

7702033 Rev 27 241/515

OSPlus file systems UM1150

vfs_fsck () vfs_fscntl() vfs_fseek() vfs_fseek64() vfs_fsetpos() vfs_fstat() vfs_fstat64() vfs_ftell() vfs_ftell64() vfs_fwrite() vfs_lseek() vfs_mkdir() vfs_mount() vfs_open() vfs_opendir() vfs_read() vfs_readdir() vfs_rename() vfs_resize() vfs_resize64() vfs_rewind() vfs_rewinddir() vfs_rmdir() vfs_seekdir() vfs_stat() vfs_stat64() vfs_sync() vfs_sync_all() vfs_telldir() vfs_umount()

Table 56.

Functions defined in vfs.h (continued)

Function

vfs_umount_all() vfs_unlink() vfs_vfprintf() vfs_write()

Description

Perform a file system check

Issue control commands for a file system

Move to a new position in a file

Move to a new position in a file (64-bit version)

Set the file position

Get detailed information for a file

Get detailed information for a file (64-bit version)

Get the current file position

Get the current file position (64-bit version)

Write data to a file

Move to a new position in a file

Create a new directory

Mount the file system on a device

Open a file

Open a directory for reading

Read data from a file

Read a directory entry

Rename a file or directory

Change the size of a file

Change the size of a file (64-bit version)

Rewind the position to the beginning of the file

Rewind to the start of a directory

Remove a directory

Move to a new position in a directory

Get detailed information for a file or directory

Get detailed information for a file or directory (64-bit version)

Flush all open files and metadata on a volume

Flush all open files and metadata on all volumes

Get a reference to the current location in a directory

Unmount a volume

Unmount all volumes after closing all file and directory handles

Remove a file

Print a formatted string to a file

Write data to a file

242/515 7702033 Rev 27

UM1150 OSPlus file systems

Table 57.

Types defined in vfs.h

Type

vfs_defrag_info_t vfs_defrag_prog_info_t vfs_defrag_option_t vfs_dir_t vfs_dirent_t vfs_file_t vfs_longlong_t vfs_stat_t vfs_stat64_t vfs_fs_type_t vfs_info_t

Description

Defragmentation information for a volume.

Defragmentation progress information for a volume.

Enumerated type for defragmentation options.

A directory

A directory entry

A file

64-bit type

Statistics for a file or directory

Statistics for a file or directory (64-bit version)

Enumerated type of the underlying file system

Information on the underlying file system

Table 58.

Macros defined in vfs.h

Macro Description

VFS_DIRENT_NAME_LEN_MAX

Maximum length of a directory entry name

Get defragmentation information

VFS_FSCNTL_DEFRAG_INFO

VFS_FSCNTL_DEFRAG_PROG_INFO

Get defragmentation progress information

VFS_FSCNTL_INFO_GET

VFS_FSCNTL_VOL_ID_GET

Get file system info

Get the volume ID

Set the volume ID

VFS_FSCNTL_VOL_ID_SET

VFS_FSCNTL_VOL_LABEL_GET

Get the volume label

Set the volume label

VFS_FSCNTL_VOL_LABEL_SET

VFS_FSCNTL_VOL_ATIME_ENABLE

Control access time logging

VFS_MODE_DIR

VFS_MODE_HIDDEN

VFS_MODE_R

VFS_MODE_RW

VFS_MODE_W

VFS_REGISTRY_NODE

VFS_REGISTRY_GET_TIME

A directory

A hidden file (FAT only)

A readable file or directory

A readable/writable file or directory

A writable file or directory

Name of VFS registry node

Registry key for user-supplied get current time function

7702033 Rev 27 243/515

OSPlus file systems UM1150

7.2.12 VFS header file: vfs_fs.h

All the definitions relating to the VFS subordinate file system interface are in the file vfs_fs.h

. The functions defined in vfs_fs.h are defined in

Section 7.7: File systems function definitions on page 258

. For more information on these functions see

Section 7.8:

Adding a new file system to the VFS on page 305

.

Table 59.

Functions defined in vfs_fs.h

Function

vfs_register() vfs_unregister()

Description

Register a new file system with the VFS

Unregister a file system from the VFS

Table 60.

Types defined in vfs_fs.h

Type

_vfs_dir_t

_vfs_file_t

_vfs_filesystem_t

_vfs_mount_t

A directory

A file

A file system

A mount

Description

chmod() close() closedir() dcntl() defrag() eof() fchmod() fcntl() flush() format() fsck() fscntl() fstat() fstat64() mkdir() mount() open() opendir() read()

Table 61.

_vfs_filesystem_t functions defined in vfs_fs.h

Function Description

Change permissions on a file or directory

Close a file

Close a directory

Perform a directory control

Defragment a volume

Check if end-of-file condition is true

Change permissions on a file

Perform a file control

Flush any unwritten information for a file

Format a device

Perform a file system check on a device

Perform a file system control

Get file information

Get file information (64-bit version)

Make a new directory

Mount a device

Open a file

Open a directory for reading

Read from a file

244/515 7702033 Rev 27

UM1150 OSPlus file systems

readdir() rename() resize() resize64() rewinddir() rmdir() seek() seek64() seekdir() stat() stat64() sync() tell() tell64() telldir() umount() unlink() write()

Table 61.

_vfs_filesystem_t functions defined in vfs_fs.h (continued)

Function Description

Read the next directory entry

Rename a file or directory

Resize a file

Resize a file (64-bit version)

Rewind to the start of a directory

Remove a directory

Set the file pointer

Set the file pointer (64-bit version)

Set directory pointer

Get file or directory information

Get file or directory information (64-bit version)

Write all unwritten data and metadata for the device

Get the current file pointer

Get the current file pointer (64-bit version)

Get current directory pointer

Unmount a device

Remove a file

Write to a file

7.3 E2FS file system

The second extended file system (Ext2) was first introduced to the Linux community in 1994 and has become the most widely used Linux file system. It is an efficient, robust and powerful file system suited to many different types of applications.

E2FS, the implementation of Ext2 in OSPlus, fully supports most features of the Linux Ext2 file system.

In E2FS, the physical device is broken down to a series of logical data blocks. These blocks can be 1024, 2048, 4096, 8192, 16384 or 32768 bytes in length and the value is set when the volume is formatted.

Each file and directory on the volume has an associated Inode object that stores information about the location, size and access permissions.

Files are stored on the volume as a series of data blocks where each block belongs to only one file. Therefore if a file is 1 byte long it occupies an entire data block of 1024, 2048, 4096,

8192, 16384 or 32768 bytes.

Directories are implemented as a special sort of file which can contain multiple directory entries. Each entry represents a file or subdirectory and has a reference to an Inode object.

For more detailed information about the on-disk structure, see

Section A.3: E2FS on-disk format on page 485

.

7702033 Rev 27 245/515

OSPlus file systems UM1150

A file system block cache is implemented as part of E2FS to improve the file system performance. A separate cache is created for each mounted volume and the cache grows dynamically up to a configurable maximum size. The cache has separate regions for file data, metadata and bitmap values to avoid cache flooding for certain activities. The cache is deleted when the volume is unmounted.

Several cache modes are supported as described in

Table 62

.

Table 62.

E2FS cache modes

Cache mode

e2fs_cache_mode_write_back e2fs_cache_mode_write_thru e2fs_cache_mode_soft_update e2fs_cache_mode_soft_update_ journaled

Description

Dirty cache entries are only written to disk when evicted or on a flush. The order writes are committed depends on the access pattern and is not guaranteed to be safe. This means the volume is marked as dirty until the entire cache is flushed.

Dirty entries are written to disk (almost) immediately in a safe order.

Dependencies between dirty cache entries are tracked and all writes are committed in a safe order. See

Appendix A: E2FS soft updates on page 485

for more

information.

Default mode. Dependencies between dirty cache entries are tracked and all writes are committed in a safe order. In addition, all changes are staged using an on-disk journal, which ensures all updates are atomic. This mode provides maximum resilience. See

Appendix A: E2FS soft updates on page 485

for more information.

The default cache size (in Kbytes) and the default cache mode are defined in the e2fs.h

header file and can be changed by setting the appropriate registry keys. See

Table 69 on page 250

for the node names and key values.

To set the default cache size to 512 Kbytes use: registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_CACHE_SIZE,

(void *)512);

246/515 7702033 Rev 27

UM1150 OSPlus file systems

To set the default cache mode to write back use: registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_CACHE_MODE,

(void *)e2fs_cache_mode_write_back);

The cache mode and cache sizes can also be changed dynamically once a volume is mounted. See

vfs_fscntl on page 276

.

When E2FS needs to increase the size of a file or directory, a new free block to be used.

This involves searching the disk for a free block in the block bitmaps and can incur some processing overhead. When non-contiguous blocks are selected the file access time can be affected. E2FS supports two block allocation modes, as shown in

Table 63

.

Table 63.

E2FS block allocation modes

Allocation mode

e2fs_alloc_mode_first e2fs_alloc_mode_contig

Description

Select the first block free after the last one allocated for this file.

Search for contiguous space large enough to accommodate all the blocks being allocated for the current operation. If none are found then revert to the first free block.

The two modes supported represent a trade-off between time to allocate the block and potential access time of the file. Depending on the access pattern for the particular volume, selecting the first free block may increase the fragmentation of the files and therefore further degrade performance.

The allocation mode e2fs_alloc_mode_contig provides several additional configurable parameters used by E2FS, as shown in

Table 64

.

Table 64.

E2FS block allocator configurable parameters

Configurable parameter Description

dir_min file_min max_blks prescan

Minimum number of blocks to add to a directory.

Minimum number of blocks to add to a file.

Maximum number of contiguous blocks searched for.

Larger allocations can be split if the contiguous space is not available on the disk.

Search the block bitmaps for the largest contiguous space at mount time. This is used to speed up the first allocation operation.

The default allocation mode and the default values for the other configurable parameters are defined in the e2fs.h header file, and can be changed by setting the appropriate registry

keys. See

Table 69

for the node names and key values.

7702033 Rev 27 247/515

OSPlus file systems UM1150

To set the default allocation mode to e2fs_alloc_mode_contig: registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_ALLOC_MODE,

(void *)e2fs_alloc_mode_contig);

To set the default directory minimum to 2 blocks: registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_ALLOC_DIR_MIN,

(void *)2);

To set the default file minimum to 8 blocks: registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_ALLOC_FILE_MIN,

(void *)8);

To set the default maximum blocks to 2048 blocks: registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_ALLOC_MAX_BLKS,

(void *)2048);

To set the default pre-scan to enabled: registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_ALLOC_PRESCAN,

(void *)1);

After a volume is mounted, the allocation mode and other configurable parameters can also

be changed dynamically. See

vfs_fscntl on page 276

.

Table 65

shows the values you can change that affect how the defragmentation is carried out.

Table 65.

Configurable parameters used when defragmenting a volume

Configurable parameter Description

Buffer size

Number of transfers

Size of the buffer to use when copying files from one location to another (specified in KBytes where

128 = 128 KB).

Number of transfers (of buffer size) per partial file step.

The default buffer size and number of transfers are defined in the e2fs.h header file, and can

be changed by setting the appropriate registry keys. See

Table 69: Defined values in e2fs.h on page 250

for the node and key names.

248/515 7702033 Rev 27

UM1150 OSPlus file systems

To set the default buffer size to 512 KBytes:

registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_DEFRAG_BUFSIZE,

(void *)512);

To set the default number of transfers to 20:

registry_key_set (

E2FS_REGISTRY_NODE,

E2FS_REGISTRY_DEFRAG_NUM_TFRS,

(void *)20);

After a volume is mounted, use the fscntl VFS_FSCNTL_DEFRAG_PROG_INFO to query the values. See

vfs_fscntl on page 276

.

When in soft update mode, E2FS has the ability to control how the device write-cache is configured. Disabling the write-cache guarantees the ordering of writes to the device.

However it often badly degrades the performance of the device. For this reason E2Fs will performs flushes by preference, and will only consider disabling the write-cache if the device does not support flush. Disabling the write-cache is under the control of the registry key

E2FS_REGISTRY_DISABLE_WC

in E2FS_REGISTRY_NODE. If this key exists, and is set to a non-zero value, E2FS will try to disable the device write-cache. By default this key is not set, so E2FS will not disable write-caches by default: it is assumed that the device will honour write ordering, and in the event of a power loss it will not lose write data for which it is has previously given a successful completion.

7.3.5 Timestamps

E2FS supports the standard Ext2 style inode timestamps for file and directories, as shown in

Table 66

.

.

Table 66.

E2FS inode timestamps

Inode timestamp field

Access

Change

Modify

Description

Last date and time the file or directory was read by the user. Mapped to the st_atime field of the vfs_stat_t structure.

Last date and time the file or directory had it’s status changed by the user, such as size or mode. Mapped to the st_ctime

field of the vfs_stat_t structure.

Last date and time the file or directory had its contents modified by the user. Mapped to the st_mtime field of the vfs_stat_t

structure.

7702033 Rev 27 249/515

OSPlus file systems

7.3.6

UM1150

E2FS header file: e2fs.h

All the definitions relating to the E2FS interface are in the file e2fs.h.

Table 67.

Functions defined in e2fs.h

Function

e2fs_vfs_init() e2fs_vfs_init_p() e2fs_vfs_shutdown()

Initialize E2FS

Initialize E2FS

Shutdown E2FS

Table 68.

Types defined in e2fs.h

Type

e2fs_alloc_info_t e2fs_alloc_mode_t e2fs_cache_get_info_t e2fs_cache_mode_t e2fs_cache_set_info_t e2fs_format_t

Table 69.

Defined values in e2fs.h

Define

Description

Description

Allocation information structure

Block allocator mode

Get cache configuration structure

Cache mode

Set cache configuration structure

Format parameters

E2FS_NAME

E2FS_FSCNTL_ALLOC_INFO_GET

E2FS_FSCNTL_ALLOC_INFO_SET

E2FS_FSCNTL_CACHE_INFO_GET

E2FS_FSCNTL_CACHE_INFO_SET

E2FS_REGISTRY_NODE

E2FS_REGISTRY_ALLOC_DIR_MIN

E2FS_REGISTRY_ALLOC_FILE_MIN

E2FS_REGISTRY_ALLOC_MAX_BLKS

E2FS_REGISTRY_ALLOC_MODE

E2FS_REGISTRY_ALLOC_PRESCAN

E2FS_REGISTRY_CACHE_SIZE

E2FS_REGISTRY_CACHE_MODE

Description

Defined name of E2FS to be used with vfs_mount() , vfs_fsck() and vfs_format()

.

FSCNTL to get current block allocator config.

FSCNTL to set current block allocator config.

FSCNTL to get current cache config.

FSCNTL to set cache config.

Name of E2FS registry node.

Name of E2FS registry key for default minimum directory blocks.

Name of E2FS registry key for default minimum file blocks.

Name of E2FS registry key for default maximum contiguous blocks allocated.

Name of E2FS registry key for default block allocator mode.

Name of E2FS registry key for default bitmap prescan behavior.

Name of E2FS registry key for default cache size.

Name of E2FS registry key for default cache mode.

250/515 7702033 Rev 27

UM1150 OSPlus file systems

Table 69.

Defined values in e2fs.h (continued)

Define

E2FS_REGISTRY_DEFRAG_BUFSIZE

E2FS_REGISTRY_DEFRAG_NUM_TFRS

E2FS_REGISTRY_DISABLE_WC

E2FS_DEFAULT_ALLOC_DIR_MIN

E2FS_DEFAULT_ALLOC_FILE_MIN

E2FS_DEFAULT_ALLOC_MAX_BLKS

E2FS_DEFAULT_ALLOC_MODE

E2FS_DEFAULT_ALLOC_PRESCAN

E2FS_DEFAULT_CACHE_SIZE

E2FS_DEFAULT_CACHE_MODE

E2FS_DEFAULT_DEFRAG_BUFSIZE

E2FS_DEFAULT_DEFRAG_NUM_TFRS

Description

Name of E2FS registry key for default defrag buffer size.

Name of E2FS registry key for default number of transfers per partial step.

Set to non-zero value to allow E2FS to disable device write-cache when in soft update mode

Default value for minimum directory blocks allocated when operating in e2fs_alloc_mode_contig .

Currently set to

1

.

Default value for minimum file blocks allocated when operating in e2fs_alloc_mode_contig

.

Currently set to 1 .

Default value for maximum contiguous blocks allocated when operating in e2fs_alloc_mode_contig

. Currently 1024.

Default value for block allocator mode, currently set to e2fs_alloc_mode_first

.

Default value for pre-scan of bitmaps at mount time, currently 1 (enabled).

Default value for cache size. Currently 512 Kbytes.

Default value for cache mode, currently set to e2fs_cache_mode_write_back .

Default size for the defrag buffer. Currently 128 KB.

Default number of transfers per defrag partial step.

Currently 8.

7702033 Rev 27 251/515

OSPlus file systems UM1150

7.4 FAT12/16/32

The FAT file system was supported by the Microsoft MS-DOS operating system, originally designed for floppy disks in the late 1970s and early 1980s. FAT stands for File Allocation

Table, a data structure that controls allocation of “clusters”. A cluster is a collection of consecutive blocks (also called “sectors”) on the raw device.

The FAT file system has evolved to support bigger and bigger media. Three variants currently exist, FAT12, FAT16 and FAT32. The numbers refer to the number of bits for each entry in the File Allocation Table. OSPlus supports all three variants of FAT.

To improve write performance, the OSPlus FAT driver maintains a count of free clusters for each group of clusters in the FAT. This enables the driver to allocate free clusters more efficiently.

By default, the FAT driver makes an initial count of free clusters when the volume is mounted. As this operation has to examine all the clusters in the FAT, this count can take a significant amount of time, blocking the mounting of the volume until it is complete.

This behavior can be modified by setting a registry key.

There are three methods that the FAT driver uses to initialize the free cluster count. These are defined in the fat.h header file.

Count on mount method

This is the default behavior if no registry key is supplied.

The following call forces this behavior (although as it is the default method, the call is not necessary).

registry_key_set (FAT_REGISTRY_NODE,

FAT_REGISTRY_FREE_COUNT_METHOD,

FAT_FREE_COUNT_METHOD_ON_MOUNT);

This method blocks mount requests of FAT volumes until the whole FAT has been read and the free cluster counts initialized.

Although this delays the mount request for a period of time, subsequent write performance is improved, particularly on volumes that are close to full.

On FAT32 volumes, the driver uses more memory to speed up the reading of the FAT.

When the volume has been mounted, the fscntl VFS_FSCNTL_INFO_GET request does not need to block until all of the free clusters in the FAT have been counted, as they have been counted during the mounting of the volume.

Count on background method

The following call forces this behavior.

registry_key_set (FAT_REGISTRY_NODE,

FAT_REGISTRY_FREE_COUNT_METHOD,

FAT_FREE_COUNT_METHOD_BACKGROUND);

252/515 7702033 Rev 27

UM1150 OSPlus file systems

This method creates a low priority task to count the free clusters. Whilst the count is proceeding, write performance may be affected. Since this method requires a background task, more memory is required to hold the task state.

The task is deleted only when the volume is unmounted, or when a fscntl

VFS_FSCNTL_INFO_GET

request is made. This fscntl also blocks until all of the free clusters in the FAT have been counted.

Defer method

The following call forces this behavior.

registry_key_set (FAT_REGISTRY_NODE,

FAT_REGISTRY_FREE_COUNT_METHOD,

FAT_FREE_COUNT_METHOD_DEFER);

This method only counts the free clusters when the FAT is accessed. Until all of the free clusters in the FAT have been counted, which is when all of the FAT has been accessed, write performance may be affected.

The fscntl VFS_FSCNTL_INFO_GET request blocks until all of the free clusters in the FAT have been counted.

Table 70

shows the values you can change which affect how the defragmentation is done.

Table 70.

Configurable parameter used when defragmenting a volume

Configurable parameter Description

Buffer Size

Number of transfers

Size of the buffer used when copying files from one location to another (specified in KBytes, where 128 = 128 KB).

Number of transfers (of buffer size) per partial file step.

The default buffer size and number of transfers are defined in the fat.h header file, and can be changed by setting the appropriate registry keys. See

Table 74 on page 255

for the

node and key names.

To set the default buffer size to 512 KBytes:

registry_key_set (

FAT_REGISTRY_NODE,

FAT_REGISTRY_DEFRAG_BUFSIZE,

(void *)512);

To set the default number of transfers to 20:

registry_key_set (

FAT_REGISTRY_NODE,

FAT_REGISTRY_DEFRAG_BUFSIZE,

(void *)20);

After a volume is mounted, use the fscntl VFS_FSCNTL_DEFRAG_PROG_INFO to query the values. See

vfs_fscntl on page 276

.

7702033 Rev 27 253/515

OSPlus file systems UM1150

7.4.3 Timestamps

FAT supports the standard DOS FAT style dirent timestamps for file and directories as

shown in

Table 71

.

.

Table 71.

FAT dirent timestamps

Dirent timestamp field

Create

Last Access

Write

Description

Date and time the file or directory was created. Not mapped to the vfs_stat_t struct.

Last date the file or directory was accessed by the user.

Mapped to the st_atime field in the vfs_stat_t struct.

Last date and time the file or directory contents were written. Mapped to the st_ctime and st_mtime fields in the vfs_stat_t struct.

The original Microsoft FAT design only supported filenames as uppercase ASCII with a maximum length of 11 characters in the 8.3 format, such as filename.txt.

To remove this limitation Microsoft later added long filenames through a special encoding scheme so the entry also has a short filename. The short filename is generated automatically when the entry is created and is still uppercase ASCII in the 8.3 format. The long filename however is stored as UTF16 and can be up to 255 tokens in length. OSPlus does not support the creation of files with long file names. However, files that already exist and have a long filename can be opened using that name.

The VFS API only supports ASCII strings, so any directory entry that contains non-ASCII characters in its longname is only accessible using its shortname. However, it is possible to retrieve the longname using FAT_FCNTL_GET_UTF16NAME for files and

FAT_DCNTL_GET_UTF16NAME

for directories. Refer to

vfs_dcntl on page 264

and

vfs_fcntl on page 267

.

7.4.6

The FAT file system maintains a block cache per file, in order to improve efficiency. By default, this cache is two cache lines in size, 32 disk blocks per cache line. If necessary, the number of disk blocks per cache line can be changed by setting the registry key

FAT_REGISTRY_BLOCKS_PER_LINE

in FAT_REGISTRY_NODE to a number between 1 and 32.

FAT header file: fat.h

All the definitions relating to the FAT interface are in the file fat.h.

Table 72.

Functions defined in fat.h

Function

fat_vfs_init() fat_vfs_init_p() fat_vfs_shutdown()

Initialize FAT

Initialize FAT

Shutdown FAT

Description

254/515 7702033 Rev 27

UM1150 OSPlus file systems

Table 73.

Types defined in fat.h

Type

fat_format_t fat_type_t

Table 74.

Defined values in fat.h

Define

FAT_NAME

FAT_FCNTL_GET_UTF16NAME

FAT_DCNTL_GET_UTF16NAME

FAT_REGISTRY_NODE

FAT_REGISTRY_DEFRAG_BUFSIZE

FAT_REGISTRY_DEFRAG_NUM_TFRS

FAT_REGISTRY_BLOCKS_PER_LINE

FAT_DEFAULT_DEFRAG_BUFSIZE

FAT_DEFAULT_DEFRAG_NUM_TFRS

Format parameters

Enum of fat types

Description

Description

Defined name of FAT to be used with vfs_mount()

, vfs_fsck() and vfs_format() .

FCNTL to get the on-disk UTF16 long name.

DCNTL to get the on-disk UTF16 long name.

Name of FAT registry node.

Name of FAT registry key for default defrag buffer size.

Name of FAT registry key for default number of transfers per partial step.

Number of disk blocks per cache line.

Default size for the defrag buffer. Currently 128 KB.

Default number of transfers per defrag partial step.

Currently 8.

7.5 Linear access file system

The Linear access file system (LAFS) was introduced in OSPlus 3.0.1 as part of a support framework for Digital Video Recorder (DVR) timeshift functions. LAFS has very limited functionality, and is not intended as a general purpose file store in the manner of FAT or

E2FS. LAFS does not provide permanent storage – its contents are lost between unmounts and power cycles. LAFS can be mounted on any block-addressable storage device, but its intended media is NAND Flash that is managed the LAFTL Flash translation layer.

When a device has been mounted with LAFS, it is immediately ready to use. It does not require formatting or consistency checking. LAFS presents the device’s contents as a single file called file.dat, located in the mount point. This file represents a direct mapping of the underlying media’s blocks. LAFS does not support the creation of any other files or directories, nor can this single file be deleted. LAFS allows this file to be concurrently opened twice only. One open must be for exclusive reading, and the other open must be for exclusive writing. Random seeking on the read handle is permitted, but only complete rewinds are permitted on the write handle.

7702033 Rev 27 255/515

OSPlus file systems

7.5.1 LAFS header file: lafs.h

All the definitions relating to LAFS are in lafs.h.

Table 75.

Functions defined in lafs.h

Function

lafs_vfs_init() lafs_vfs_init_p() lafs_vfs_shutdown()

Initialize LAFS

Initialize LAFS

Shutdown LAFS

Description

Table 76.

Defined values in lafs.h

Define

LAFS_NAME

LAFS_FSCNTL_PREF_IO_SIZE

Description

Defined name of LAFS to be used with vfs_mount()

FSCNTL to get preferred I/O size

7.6

UM1150

Multi-slot file system

The Multi-slot file system (MSFS) was introduced in OSPlus 3.2 as an extension of the support framework for Digital Video Recorder (DVR) applications. Its intended use is for a targeted advertising file store, or Video-On-Demand (VOD) push storage. MSFS is more flexible than LAFS, but still has limited functionality when compared to FAT or E2FS. MSFS should be used on NAND Flash that is managed by the LAFTL Flash translation layer.

MSFS and LAFTL take care of bad block remapping and wear leveling between themselves.

Unlike LAFS, MSFS provides permanent storage, so the file system and its contents survive across unmounts and power cycles. MSFS manages the underlying NAND Flash as a number of fixed sized slots, each of which can contain a file. An MSFS file system must be formatted before it can be used. Formatting determines the number of slots, and hence the maximum file size.

When a NAND Flash has been mounted with MSFS it is ready to use. It never requires consistency checking with vfs_fsck. MSFS presents the Flash memory’s contents as a number of files located in the root of the mount point. Like LAFS, MSFS does not support sub-directories. Unlike LAFS, the application is free to create and delete files in the root of the mount point, and has a free choice of the file names to use.

MSFS allows files to be opened concurrently. Any number of opens for reading are allowed, but only one open for exclusive writing is permitted. Random seeking on the read handles is possible, but only complete rewinds are permitted on the write handle. Each open must be for either reading or writing.

256/515 7702033 Rev 27

UM1150

7.6.1

OSPlus file systems

MSFS header file: msfs.h

All the definitions relating to MSFS are in msfs.h.

Table 77.

Functions defined in msfs.h

Function

msfs_vfs_init() msfs_vfs_init_p() msfs_vfs_shutdown()

Initialize MSFS

Initialize MSFS

Shutdown MSFS

Description

Table 78.

Types defined in msfs.h

Function

msfs_format_t

Format parameters

Description

Table 79.

Defined values in msfs.h

Define

MSFS_NAME

MSFS_MAX_SLOTS

MSFS_MAX_NAME

MSFS_FSCNTL_PREF_IO_SIZE

MSFS_FSCNTL_NUM_SLOTS

MSFS_CNTL_SLOT_SIZE

Description

Defined name of MSFS to be used with vfs_mount()

Maximum number of slots that an MSFS file system can contain

Maximum length of an MSFS file name

FSCNTL to get preferred I/O size

FSCNTL to get the number of slots

FSCNTL to get the size of a slot in bytes

7702033 Rev 27 257/515

OSPlus file systems UM1150

7.7 File systems function definitions e2fs_vfs_init

Initialize the E2FS subsystem to use the C run-time heap

Definition:

Arguments:

Returns:

Description:

int e2fs_vfs_init (void)

None.

Returns 0 for success, -1 for failure.

e2fs_vfs_init()

initializes the E2FS subsystem and registers it with the VFS.

E2FS allocates all internal buffers from the C run-time memory heap when initialized with this call.

See also:

e2fs_vfs_init_p

e2fs_vfs_init_p

Initialize the E2FS subsystem to use a specific memory partition

Definition:

Arguments:

int e2fs_vfs_init_p (partition_t *partition) partition

Memory partition to use

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

e2fs_vfs_init_p()

initializes the E2FS subsystem and registers it with the VFS.

When initialized with this call, E2FS allocates internal buffers used for I/O from the memory partition specified while other buffers are still allocated from the C run-time memory heap.

e2fs_vfs_init

258/515 7702033 Rev 27

UM1150 OSPlus file systems

e2fs_vfs_shutdown

Shutdown the E2FS subsystem

Definition:

Arguments:

Returns:

Description:

int e2fs_vfs_shutdown (void)

None.

Returns 0 for success, -1 for failure.

e2fs_vfs_shutdown()

closes the E2FS subsystem and unregisters it with the

VFS.

fat_vfs_init

Definition:

Arguments:

Returns:

Description:

See also:

Initialize the FAT subsystem to use the C run-time memory heap

int fat_vfs_init (void)

None.

Returns 0 for success, -1 for failure.

fat_vfs_init()

initializes the FAT subsystem and registers it with the VFS. FAT allocates all internal buffers from the C run-time memory heap when initialized with this call.

fat_vfs_init_p

fat_vfs_init_p

Initialize the FAT subsystem to use a specific memory partition

Definition:

Arguments:

int fat_vfs_init_p (partition_t *partition) partition

Memory partition to use

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

fat_vfs_init_p()

initializes the FAT subsystem and registers it with the VFS.

When initialized with this call, FAT allocates internal buffers used for I/O from the memory partition specified while other buffers are still allocated from the C run-time memory heap.

fat_vfs_init

fat_vfs_shutdown

Shutdown the FAT subsystem

Definition:

Arguments:

Returns:

Description:

int fat_vfs_shutdown (void)

None.

Returns 0 for success, -1 for failure.

fat_vfs_shutdown()

closes the FAT subsystem and unregisters it with the VFS.

7702033 Rev 27 259/515

OSPlus file systems UM1150

lafs_vfs_init

Definition:

Arguments:

Returns:

Description:

See also:

Initialize the LAFS subsystem to use the C run-time memory heap

int lafs_vfs_init (void)

None.

Returns 0 for success, -1 for failure.

lafs_vfs_init()

initializes the LAFS subsystem and registers it with the VFS.

LAFS allocates all internal buffers from the C run-time memory heap when initialized with this call.

lafs_vfs_init_p

lafs_vfs_init_p

Initialize the LAFS subsystem to use a specific memory partition

Definition:

Arguments:

int lafs_vfs_init_p (partition_t *partition) partition

Memory partition to use

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

lafs_vfs_init_p()

initializes the LAFS subsystem and registers it with the VFS.

When initialized with this call, LAFS allocates internal buffers used for I/O from the specified memory partition. All other buffers are allocated from the C run-time memory heap.

lafs_vfs_init

lafs_vfs_shutdown

Shutdown the LAFS subsystem

Definition:

Arguments:

Returns:

Description:

int lafs_vfs_shutdown (void)

None.

Returns 0 for success, -1 for failure.

lafs_vfs_shutdown()

closes the LAFS subsystem and unregisters it with the

VFS.

260/515 7702033 Rev 27

UM1150 OSPlus file systems

msfs_vfs_init

Initialize the MSFS subsystem to use the C run-time memory heap

Definition:

Arguments:

Returns:

Description:

See also:

int msfs_vfs_init (void)

None.

Returns 0 for success, -1 for failure.

msfs_vfs_init()

initializes the MSFS subsystem and registers it with the VFS.

MSFS allocates all internal buffers from the C run-time memory heap when initialized with this call.

msfs_vfs_init_p

msfs_vfs_init_p

Initialize the MSFS subsystem to use a specific memory partition

Definition:

Arguments:

int msfs_vfs_init_p (partition_t *partition) partition

Memory partition to use

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

msfs_vfs_init_p()

initializes the MSFS subsystem and registers it with the VFS.

When initialized with this call, MSFS allocates internal buffers used for I/O from the specified memory partition. All other buffers are allocated from the C run-time memory heap.

msfs_vfs_init

msfs_vfs_shutdown

Shutdown the MSFS subsystem

Definition:

Arguments:

Returns:

Description:

int msfs_vfs_shutdown (void)

None.

Returns 0 for success, -1 for failure.

msfs_vfs_shutdown()

closes the MSFS subsystem and unregisters it with the

VFS.

7702033 Rev 27 261/515

OSPlus file systems UM1150

vfs_chmod

Definition:

Change the access mode of the file

int vfs_chmod (

const char *path,

const unsigned int mode)

Arguments:

Returns:

Description:

See also:

path mode

The file to change.

The mode to set.

Returns 0 for success, -1 for failure.

vfs_chmod()

changes the mode of the file or directory at location path. Supported modes are VFS_MODE_R, VFS_MODE_W and VFS_MODE_RW for E2FS and

VFS_MODE_R

, VFS_MODE_RW and VFS_MODE_HIDDEN for FAT.

vfs_fchmod

vfs_close

Definition:

Arguments:

Close a file

int vfs_close (vfs_file_t *file)

Returns:

Description:

See also:

file

The open file to close.

Returns 0 for success, -1 for failure.

vfs_close()

flushes any outstanding data (and metadata), closes the open file specified and deletes the file handle object.

vfs_open

262/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_closedir

Definition:

Arguments:

Close a directory

int vfs_closedir (vfs_dir_t *dir) dir

The directory to close.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

vfs_closedir()

closes the open directory and deletes the directory handle object.

vfs_opendir

vfs_creat

Definition:

Arguments:

Create a file

vfs_file_t *vfs_creat (const char *filename)

Returns:

Errors:

filename

The full path and filename to create.

Returns a pointer to the newly opened file, or NULL for failure.

Description:

ENOSPC

The volume is full.

vfs_creat()

creates a write-only file in the location specified and returns a pointer to a newly-created file handle object. If the filename exists it is truncated to a length of zero bytes. The file is opened with flags of OSPLUS_O_CREAT, OSPLUS_O_TRUNC and OSPLUS_O_WRONLY. See

vfs_open on page 290

.

7702033 Rev 27 263/515

OSPlus file systems

vfs_dcntl

Definition:

Issue control commands for a directory

int vfs_dcntl (

vfs_dir_t *dir,

const int request,

const void *param)

Arguments:

Returns:

Description:

See also:

.

UM1150

dir request param

The directory which the command is sent to.

The command.

The associated command parameters or a buffer for the result.

Returns 0 for success, -1 for failure.

vfs_dcntl()

issues a control command to an open directory on a mounted system.

The command is specific to the directory and implemented by the underlying file system. All supported generic commands are contained in the vfs.h header file, and all file system specific commands are in e2fs.h or fat.h.

Currently VFS and E2FS do not support any DCNTL commands.

Table 80

shows the FAT specific commands supported by OSPlus.

Table 80.

FAT DCNTL commands

Request

FAT_DCNTL_GET_UTF16NAME

Description

Get the UTF16 encoded long filename. Returns the result in the user-supplied buffer pointed to by the param field, which must be big enough to hold the entire long filename. If the entry does not have a long filename the buffer is NULL terminated in the first character position.

vfs_fcntl, vfs_fscntl

264/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_defrag

Definition:

Defragment a volume

int vfs_defrag (

const char * root,

const vfs_defrag_option_t option)

Arguments:

Returns:

Errors:

root option

Root directory of mounted volume to defragment.

Defragmentation option.

Returns 0 for successful completion, 1 for partial completion and -1 for failure.

Description:

EBUSY

ENOSPC

Volume has files/directories open.

Volume can not be defragmented due to lack of free space.

vfs_defrag()

defragments a specified volume. The volume must be mounted and there must not be any open file or directory handles. Two configurable parameters are

supported through registry settings, as described in E2FS

Section 7.3.3: Defrag configuration on page 248

and FAT

Section 7.4.2: Defrag configuration on page 253

.

Table 81

shows the options supported.

Table 81.

vfs_defrag() options

Option

vfs_defrag_stop vfs_defrag_entire_volume vfs_defrag_entire_file vfs_defrag_partial_file

Description

Stop any defragment currently in progress on the volume and free any memory used.

Defragment the entire volume.

Defragment the next file.

Defragment the next part of the current/next file.

Depending on the size of the volume and the number of files, it can take a long time to defragment the entire volume. For this reason the options vfs_defrag_entire_file

and vfs_defrag_partial_file have been added.

These two options allow fine-grained control over the defragmentation process but to defragment the whole volume vfs_defrag has to be called repeatedly.

vfs_defrag performs the requested defragmentation operation and returns 1 if more defragmentation is needed, or 0 if defragmentation of the volume is complete.

When vfs_defrag returns 1, call vfs_defrag again with the same parameters to do the next piece of defragmentation. Alternatively, call vfs_defrag with the option set to vfs_defrag_stop to stop the defragmentation process and free the resources that were being used. No file or directory handles can be opened while the defragmentation is in progress.

Some free space is required on the volume for the defragmentation process to work.

If there is not enough free space available, the call to vfs_defrag fails by returning

-1

and setting errno to ENOSPC. The amount of free space required depends on the underlying file system but is typically three times the size of the largest file.

7702033 Rev 27 265/515

OSPlus file systems UM1150

vfs_fchmod

Definition:

Change the access modes for the file

int vfs_fchmod (

vfs_file_t *file,

const unsigned int mode)

Arguments:

Returns:

Description:

See also:

file mode

The file to change.

The mode to set.

Returns 0 for success, -1 for failure.

vfs_fchmod()

changes the mode of the file. Supported modes are VFS_MODE_R,

VFS_MODE_W

and VFS_MODE_RW for E2FS and VFS_MODE_R, VFS_MODE_RW and

VFS_MODE_HIDDEN

for FAT.

vfs_chmod

vfs_fclose

Definition:

Arguments:

Close a file

int vfs_fclose (vfs_file_t *file)

Returns:

Description:

See also:

file

The file to close.

Returns 0 for success, -1 for failure.

vfs_fclose()

flushes any outstanding data and then closes the open file. The file handle object is also deleted.

vfs_close

266/515 7702033 Rev 27

UM1150

vfs_fcntl

OSPlus file systems

Definition:

Issue control commands for a file

int vfs_fcntl (

vfs_file_t *file,

const int request,

const void *param)

Arguments:

Returns:

Description:

See also:

.

file request param

The file to be sent the command.

The command.

The associated command parameters or a buffer for the result.

Returns 0 for success, -1 for failure.

vfs_fcntl()

issues a control command to an open file on a mounted system. The command is specific to the file and implemented by the underlying file system. All supported generic commands are contained in the vfs.h header file, and all file system specific commands are in e2fs.h or fat.h.

Currently VFS and E2FS do not support any FCNTL commands.

Table 82

lists the FAT specific commands supported by OSPlus.

Table 82.

FAT FCNTL commands

Request

FAT_FCNTL_GET_UTF16NAME

Description

Get the UTF16 encoded long filename. Returns the result in the user-supplied buffer pointed to by the param field, which must be big enough to hold the entire long filename. If the entry does not have a long filename the buffer is NULL terminated in the first character position.

vfs_dcntl, vfs_fscntl

7702033 Rev 27 267/515

OSPlus file systems UM1150

vfs_feof

Definition:

Arguments:

Check the EOF flag

int vfs_feof (vfs_file_t *file)

Returns:

Description:

vfs_fflush

file

The file to check.

Returns 1 if EOF is true, 0 otherwise.

vfs_feof()

returns 1 if the file position is at the end of the file.

Definition:

Arguments:

Write any outstanding data to a file

int vfs_fflush (vfs_file_t *file)

Returns:

Description:

file

The file to flush.

Returns 0 for success, -1 for failure.

vfs_fflush()

writes any outstanding data (and metadata) for this file to the physical device.

vfs_fgetc

Definition:

Arguments:

Get a single character from a file

int vfs_fgetc (vfs_file_t *file)

Returns:

Description:

See also:

file

The file from which to get the character.

Returns the character read encoded as an integer, or -1 for failure.

vfs_fgetc()

reads one character from the file and returns it encoded as an integer.

The file position is incremented by one byte.

vfs_fgets

, vfs_fputc

268/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_fgetpos

Definition:

Get the current file position

int vfs_fgetpos (

vfs_file_t *file,

size_t *pos)

Arguments:

Returns:

Description:

See also:

file pos

The file from which to get the position.

The value returned.

Returns 0 for success, -1 for failure.

vfs_fgetpos()

returns the current file position in pos.

vfs_ftell

, vfs_fsetpos

vfs_fgets

Definition:

Get a string from a file

unsigned char *vfs_fgets (

unsigned char *s,

const size_t size,

vfs_file_t *file)

Arguments:

Returns:

Description:

See also:

s size file

The buffer to write the string to.

The number of bytes.

The file to read from.

Returns the string read, or NULL for failure.

vfs_fgets()

reads a string from file into s with a maximum length of size but stops earlier if an end-of-line character or EOF is encountered. The file position is incremented to the next byte after the last one read.

vfs_fgetc

, vfs_fputs

7702033 Rev 27 269/515

OSPlus file systems

vfs_fopen

Definition:

Open a file

vfs_file_t *vfs_fopen (

const char *file,

const char *mode)

Arguments:

Returns:

Errors:

file mode

The file name.

The access mode.

Returns a pointer to the newly opened file, or NULL for failure.

Description:

See also:

UM1150

ENOSPC

EISDIR

EROFS

Creation of a new file failed as the volume is full.

The value of file is a directory.

The volume was mounted as read-only.

vfs_fopen()

converts the mode to its equivalent OSPLUS_O_* style flags (see

vfs_open on page 290

), then opens the file. It returns a pointer to a newly-created file handle object.

The mode values are converted as follows:

OSPLUS_O_RDWR r+ r w+ w a+ a vfs_open

OSPLUS_O_RDONLY

OSPLUS_O_CREAT

| OSPLUS_O_TRUNC | OSPLUS_O_RDWR

OSPLUS_O_CREAT

| OSPLUS_O_TRUNC | OSPLUS_O_WRONLY

OSPLUS_O_CREAT

| OSPLUS_O_APPEND | OSPLUS_O_RDWR

OSPLUS_O_CREAT

| OSPLUS_O_APPEND | OSPLUS_O_WRONLY

270/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_format

Definition:

Format a device with a new file system

int vfs_format (

const char *device_name,

const char *fs_name,

void *param)

Arguments:

Returns:

Errors:

device_name fs_name param

The name of the device.

The file system type.

An optional parameter list.

Returns 0 for success, -1 for failure.

Description:

ENODEV

EBUSY

EINVAL

If the device is a logical volume device, the partition raw_type

was not compatible with the file system, otherwise the device does not exist.

The device is used by another mount point.

One of the parameters is invalid or not supported for the device.

vfs_format()

formats a device for use with the specified file system type. Any data previously on the volume is lost, and after formatting the volume is empty. When a device is formatted it can then be mounted and used.

The fs_name argument must match one of the registered subordinate file system types or it can be NULL for logical volume devices. If the fs_name argument is NULL, the partition raw_type is used to direct the call to the correct subordinate file system.

The param argument allows the user to specify certain values that are dependent on the file system type. If param is set to NULL, default values are used for all parameters. To use this optional feature, it is necessary to specify the file systems type using fs_name, create an object of type e2fs_format_t, or fat_format_t, and fill in the values. When passed to vfs_format() the instantiated object needs to be cast as a void *.

When formatting a device with a FAT file system, if the param is NULL the device must have an associated raw_type. If the type field of the fat_format_t is set to

FAT_TYPE_ANY

then the raw_type is used if possible, otherwise the type is selected automatically based on the volume size.

7702033 Rev 27 271/515

OSPlus file systems UM1150

The e2fs_format_t structure has the following format. The fields are described in

Table 83

.

typedef struct

{ unsigned char volume_id[16]; unsigned char volume_label[16];

} e2fs_format_t

Table 83.

e2fs_format_t fields

Field name

block_size lba_count inode_ratio delete_all volume_id volume_label

Description

Desired block size (1024, 2048, 4096, 8192, 16384 or

32768 bytes)

Not used

Ratio of blocks to inodes, value between 1 and 100

Completely erase contents of disk before format

1 for true, 0 for false

Unique 16 byte hexadecimal identifier for the volume

Volume name

The fat_format_t structure has the following format. The fields are described in

Table 84

.

typedef struct fat_format_s

{

} fat_format_t;

Table 84.

fat_format_t fields

Field name

type delete_all

Description

Type of FAT to be used, one of

FAT_TYPE_FAT12

,

FAT_TYPE_FAT16 , FAT_TYPE_FAT32 or

FAT_TYPE_ANY

Completely erase contents of disk before format

1

for true,

0

for false

272/515 7702033 Rev 27

UM1150 OSPlus file systems

The msfs_format_t structure has the following format. The fields are described in

Table 85

.

typedef struct

{

} msfs_format_t;

Table 85.

ms_format_t fields

Field name

slots

Description

Divide the NAND Flash into this number of slots. Must be between 1 and MSFS_MAX_SLOTS.

vfs_fprintf

Definition:

Print a formatted string to a file

int vfs_fprintf (

vfs_file_t *file,

const char *fmt,

...)

Arguments:

Returns:

Description:

See also:

vfs_fputc

file fmt

The file to write to.

The format string.

Returns the number of bytes written on success, -1 for failure.

vfs_fprintf()

is identical to the standard C library fprintf() except the output is written to a VFS file.

vfs_vfprintf

Definition:

Write a single character to a file

int vfs_fputc (

const unsigned int c,

vfs_file_t *file)

Arguments:

Returns:

Description:

See also:

c file

The character to write.

The file to write to.

Returns the character written on success, or -1 for failure.

vfs_fputc()

writes one character to the file. The file position is incremented by one byte.

vfs_fgetc

, vfs_fputs

7702033 Rev 27 273/515

OSPlus file systems

vfs_fputs

Definition:

Write a string to a file

int vfs_fputs (

const char *s,

vfs_file_t *file)

Arguments:

Returns:

Description:

See also:

vfs_fread

UM1150

s file

The string to write.

The file to write to.

Returns the number of bytes written on success, or -1 for failure.

vfs_fputs()

writes the string to the file. The file position is incremented to the next byte after the last one written.

vfs_fgets

, vfs_fputc

Definition:

Read data from a file

int vfs_fread (

void *ptr,

const size_t size,

const size_t nmemb,

vfs_file_t *file)

Arguments:

Returns:

Description:

See also:

ptr size nmemb file

The buffer to place data.

The size of each element.

The number of elements to read.

The file to read from.

Returns the number of elements read, or -1 for failure.

vfs_fread()

reads nmemb elements of size from the file to the buffer ptr. The file position is incremented to the next byte after the last one read.

vfs_fwrite

274/515 7702033 Rev 27

UM1150

vfs_fsck

Definition:

Arguments:

Returns:

Errors:

Description:

OSPlus file systems

Check the file system

int vfs_fsck (

const char *device_name,

const char *fs_name) device_name fs_name

The name of the device.

The name of the file system type.

Returns 0 for success, -1 for failure.

ENODEV

EAGAIN

If the device is a logical volume device and the fs_name was specified, the partition raw_type was not compatible with the file system, otherwise the device does not exist.

The file system on device is severely corrupted and cannot be recovered.

vfs_fsck()

checks the integrity of the underlying file system and repairs any corruption where possible. The volume is marked as clean if successful.

The fs_name argument must match one of the registered file system types or it can be NULL for logical volume devices. If fs_name is NULL, the partition raw_type is used to direct the call to the correct subordinate file system.

7702033 Rev 27 275/515

OSPlus file systems UM1150

vfs_fscntl

Definition:

Issue control commands to a file system

int vfs_fscntl (

const char *root,

const int request,

const void *param)

Arguments:

Returns:

Description:

root request param

The root directory of the file system to be sent the command.

The command to the file system.

The associated command parameters or a buffer for the result.

Returns 0 for success, or -1 for failure.

vfs_fscntl()

issues a file system control command to a mounted file system. The command applies to the entire mounted volume and is handled by the underlying file system. All supported generic commands are contained in the vfs.h header file, and all file system specific commands are in e2fs.h or fat.h.

When a particular request needs the additional command parameters (param) the user is responsible for creating the structure and casting it as a void * in the call to vfs_fscntl()

.

Table 86

lists the generic commands supported by OSPlus.

Table 86.

Generic fscntl requests

Request

VFS_FSCNTL_DEFRAG_INFO

VFS_FSCNTL_DEFRAG_PROG_INFO

VFS_FSCNTL_INFO_GET

VFS_FSCNTL_VOL_ID_GET

VFS_FSCNTL_VOL_ID_SET

VFS_FSCNTL_VOL_LABEL_GET

VFS_FSCNTL_VOL_LABEL_SET

VFS_FSCNTL_VOL_ATIME_ENABLE

Description

Get the defragment information.

Get the defragment progress information.

Get the type, free, total and native block sizes of the underlying file system.

Get the volume ID

Set the volume ID

Get the volume label

Set the volume label

Control access time recording

276/515 7702033 Rev 27

UM1150 OSPlus file systems

The vfs_defrag_info_t structure has the following format. The fields are described in

Table 87

.

typedef struct vfs_defrag_info_s {

} vfs_defrag_info_t;

Table 87.

vfs_defrag_info_t fields

Field name

percent_file_frag percent_file_blks_frag percent_vol_blks_frag defrag_possible

Description

Percent of files on volume that are fragmented.

Percent of blocks used by files that are fragmented.

Percent of blocks on volume that are fragmented.

Indication whether volume can be defragmented.

The vfs_defrag_prog_info_t structure has the following format. The fields are described in

Table 88

.

typedef struct vfs_defrag_prog_info_s { unsigned int current_blk; unsigned int total_blks; unsigned int total_file_blks; unsigned int total_files; int buffer_size; int num_tfrs; int in_progress;

} vfs_defrag_prog_info_t;

Table 88.

vfs_defrag_prog_info_t fields

Field name

current_blk total_blks total_file_blks total_files buffer_size num_tfrs in_progress

Description

Current block being defragmented.

Total number of blocks.

Total number of blocks used by files.

Total number of files (including dirs).

Defrag buffer size.

Number of transfers per partial step.

Defrag is currently in progress (== 1).

7702033 Rev 27 277/515

OSPlus file systems UM1150

The vfs_info_t structure has the following format. The fields are described in

Table 89

.

typedef struct vfs_info_s{ unsigned int free_blocks; unsigned int allocation_unit;

} vfs_info_t;

Table 89.

vfs_info_t fields

fs_type

Field name

free_blocks allocation_unit

Description

The type of the underlying file system. This can be

0 (None), 12 (FAT12), 16 (FAT16), 32 (FAT32),

226 (E2FS) or 2001 (Unknown).

Number of physical blocks that are free on the storage device.

The size of the file system’s allocation unit, in physical blocks.

Total size of the volume in physical blocks.

total_size

The vfs_vol_id_t structure has the following format. The fields are described in

Table 90.

typedef struct vfs_vol_id_s{ unsigned char *buffer; size_t

} vfs_vol_id_t;

size;

Table 90.

vfs_vol_id_t fields

Field name

buffer size

Description

Buffer for ID, or NULL

Size of buffer in bytes

If the buffer field is set to NULL when retrieving the volume ID with

VFS_FSCNTL_VOL_ID_GET

, this call sets the size field to the value required to hold a volume ID for this file system. This size varies between file systems.

278/515 7702033 Rev 27

UM1150 OSPlus file systems

The vfs_vol_label_t structure has the following format. The fields are described

in

Table 91.

.

typedef struct vfs_vol_label_s{ char *buffer;

} vfs_vol_label_t;

Table 91.

vfs_vol_label_t fields

Field name

buffer size

Description

Buffer for label, or NULL

Size of buffer in bytes

If the buffer field is set to NULL when retrieving the volume label with

VFS_FSCNTL_VOL_LABEL_GET

, this call sets the size field to the value required to hold a volume label for this file system. This size varies between file systems. The volume label is a zero terminated string, and the size includes the trailing zero byte.

Use VFS_FSCNTL_VOL_ATIME_ENABLE to control whether or not read access times are recorded for files. This is only applicable if timestamp support has been enabled

(see

Section 7.2.9: Timestamp support

). If the parameter passed is non-zero, then

read access times are always recorded. If the parameter is zero, read access times are recorded.

Table 92

lists the commands specific to E2FS, contained in the e2fs.h header file.

Table 92.

E2FS fscntl requests

Request

E2FS_FSCNTL_ALLOC_INFO_GET

E2FS_FSCNTL_ALLOC_INFO_SET

E2FS_FSCNTL_CACHE_INFO_GET

E2FS_FSCNTL_CACHE_INFO_SET

Description

Get the current E2FS block allocator configuration.

Set the E2FS block allocator configuration.

Get the current E2FS cache configuration.

Set the E2FS cache configuration.

The e2fs_alloc_info_t structure has the following format. The fields are described in

Table 93

.

typedef struct e2fs_alloc_info_s{

} e2fs_alloc_info_t;

7702033 Rev 27 279/515

OSPlus file systems UM1150

Table 93.

e2fs_alloc_info_t fields

mode

Field name Description

New allocation mode. See

Table 63: E2FS block allocation modes on page 247

.

dir_min, file_min, max_blks, prescan

Configurable parameters. See

Table 64: E2FS block allocator configurable parameters on page 247

.

The e2fs_cache_get_info_t structure has the following format. The fields are described in

Table 94

.

typedef struct e2fs_cache_get_info_s{

280/515

} e2fs_cache_get_info_t;

Table 94.

e2fs_cache_get_info_t fields

Field name

data_cache_max, meta_cache_max, bitm_cache_max data_cache_current, meta_cache_current, bit_cache_current data_cache_blk_size, meta_cache_blk_size, bitm_cache_blk_size

Description

Maximum number of entries in each cache.

Current number of entries in each cache.

Block size for each cache in allocation units

(512 bytes).

max_total_size current_total_size mode

Maximum size in allocation units (512 bytes) if all caches grow to their maximum size.

Current total size in allocation units (512 bytes).

Current cache mode. See

Table 62: E2FS cache modes on page 246

.

7702033 Rev 27

UM1150 OSPlus file systems

The e2fs_cache_set_info_t structure has the following format. The fields are described in

Table 95

.

typedef struct e2fs_cache_set_info_s{

} e2fs_cache_set_info_t;

Table 95.

e2fs_cache_set_info_t fields

data_cache_max, meta_cache_max, bitm_cache_max mode

Field name Description

Maximum number of entries in each cache. If the given values are less than the minimum usable size, the minimum size is used instead.

New cache mode. See

Table 62: E2FS cache modes on page 246

.

7702033 Rev 27 281/515

OSPlus file systems

vfs_fseek

Definition:

Move to a new position in the file

int vfs_fseek (

vfs_file_t *file,

const int offset,

const int whence)

Arguments:

Returns:

Description:

See also:

UM1150

file offset whence

The open file.

The offset in to the file.

The method of seeking.

Returns 0 for success, -1 for failure.

vfs_fseek()

changes the current file position to a value based on the offset and whence

parameters, as defined in

Table 96

.

Table 96.

Values of whence parameters

Value

OSPLUS_SEEK_SET

OSPLUS_SEEK_CUR

OSPLUS_SEEK_END

Action

Move to the absolute position of offset .

Move offset bytes from the current position

Move offset bytes from the end of the file.

vfs_lseek

, vfs_fsetpos

282/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_fseek64

Definition:

Move to a new position in the file (64-bit version)

Without native 64-bit support: int vfs_fseek64 ( const int offset_high, const int whence)

With native 64-bit support: int vfs_fseek64 ( const vfs_longlong_t offset, const int whence)

Arguments:

Returns:

Errors:

file offset offset_high offset_low whence

The open file.

The offset in to the file (64-bit).

The upper 32-bit offset in to the file.

The lower 32-bit offset in to the file.

The method of seeking.

Returns 0 for success, -1 for failure.

Description:

E2BIG

The 64-bit offset is not supported on this file system vfs_fseek64()

changes the current file position to a value based on the offset

(or offset_high and offset_low on systems without native 64-bit support) and whence

parameters. See

Table 96 on page 282

.

7702033 Rev 27 283/515

OSPlus file systems UM1150

vfs_fsetpos

Definition:

Set the file position

int vfs_fsetpos (

vfs_file_t *file,

size_t *pos)

Arguments:

Returns:

Description:

See also:

file pos

The file for which to set the position.

The new position values.

Returns 0 for success, -1 for failure.

vfs_fsetpos()

sets the current file position to the value of pos.

vfs_fseek

, vfs_lseek

vfs_fstat

Definition:

Get detailed information for a file

int vfs_fstat (

vfs_file_t *file,

vfs_stat_t *buf)

Arguments:

Returns:

Description:

file buf

The open file.

The structure to return values.

Returns 0 for success, -1 for failure.

vfs_fstat()

gets the detailed file information for an open file and stores it in buf.

See

vfs_stat on page 297

for the format of the vfs_stat_t buffer.

284/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_fstat64

Definition:

Get detailed information for a file (64-bit version)

int vfs_fstat64 (

vfs_file_t *file,

vfs_stat64_t *buf)

Arguments:

Returns:

Description:

file buf

The open file.

The structure to return values.

Returns 0 for success, -1 for failure.

vfs_fstat64()

gets the detailed file information for an open file and stores it in buf

. See

vfs_stat64 on page 298

for the format of the vfs_stat64_t buffer.

vfs_ftell

Definition:

Arguments:

Get the current file position

int vfs_ftell (vfs_file_t *file)

Returns:

Description:

See also:

file

The file from which to get the position.

Returns the current file position, or -1 for failure.

vfs_ftell()

returns the current byte position of the file.

vfs_fgetpos

7702033 Rev 27 285/515

OSPlus file systems

vfs_ftell64

Definition:

Get the current file position (64-bit version)

Without native 64-bit support: int vfs_ftell64 (

UM1150

Arguments:

Returns:

Description:

With native 64-bit support: vfs_longlong_t vfs_ftell64 (vfs_file_t *file) file size_high size_low

The file from which to get the position.

The upper 32 bits of the position.

The lower 32 bits of the position.

Returns the current file position (or 0 for success on systems without native 64-bit support), or -1 for failure.

vfs_ftell64()

returns the current byte position of the file (in size_high and size_low

on systems without native 64-bit support).

286/515 7702033 Rev 27

UM1150

vfs_fwrite

OSPlus file systems

Definition:

Arguments:

ptr size nmemb file

The buffer that contains the data.

The size of each element.

The number of elements to write.

The file to write to.

Returns the number of elements written, or -1 for failure.

Returns:

Errors:

Description:

See also:

vfs_lseek

ENOSPC

ENOMEM

The volume is full.

A memory allocation failed.

vfs_fwrite()

writes nmemb elements of size from the buffer ptr to the file.

The file position is incremented to the next byte after the last one written.

vfs_fread

Definition:

Move to a new position in the file

int vfs_lseek (

vfs_file_t *file,

const int offset,

const int whence)

Arguments:

Write data to a file

int vfs_fwrite (

const void *ptr,

const size_t size,

const size_t nmemb,

vfs_file_t *file)

Returns:

Description:

See also:

file offset whence

The open file.

The offset in to the file.

The method of seeking.

Returns 0 for success, -1 for failure.

vfs_lseek()

changes the current file position to a value based on the offset and whence

parameters. See

vfs_fseek on page 282

for the valid values for the whence parameter.

vfs_fseek

, vfs_fsetpos

7702033 Rev 27 287/515

OSPlus file systems

vfs_mkdir

Definition:

Arguments:

Create a directory

int vfs_mkdir (const char *pathname)

Returns:

Errors:

pathname

The directory to create.

Returns 0 for success, -1 for failure.

Description:

See also:

ENOSPC

ENOMEM

The volume is full.

A memory allocation failed.

vfs_mkdir()

creates a directory at the location pathname.

vfs_rmdir

UM1150

288/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_mount

Definition:

Mount a volume

int vfs_mount (

const char *device_name,

const char *dir,

const char *fs_name,

const int flags)

Arguments:

Returns:

Errors:

device_name dir fs_name flags

The name of the device.

The root directory.

The name of the file system type.

The access permission flags.

Returns 0 for success, -1 for failure.

Description:

See also:

EBUSY

ENODEV

EAGAIN

ENOMEM

The root directory, or the device, is used by another mount point.

If the device is a logical volume device, the partition raw_type

was not compatible with the file system, otherwise the device does not exist.

The volume is corrupted and needs to have vfs_fsck() run on it.

A memory allocation failed.

vfs_mount()

creates a mount point that associates the logical directory dir of type fs_name

, with the device device_name. It also opens a device handle on the device.

When mounted, the new volume can be accessed using the other VFS functions. It is referenced using its mount point as the start of any paths. For example, if a volume is mounted with dir set to /apple then any paths passed to vfs_open(), that start with /apple are assumed to reside on that specific volume.

The dir must have a leading / and consist of valid alphanumeric characters excluding any additional / characters. Therefore /ABCD is valid but /AB/CD/ is not.

This also means that it is not possible to cascade mount points.

The valid flags parameters are OSPLUS_O_RDONLY or OSPLUS_O_RDWR. See

vfs_open on page 290

.

The fs_name argument should match one of the registered subordinate file system types or if the device is a logical volume device it can be NULL. If fs_name is NULL the partition raw_type is used to find the correct subordinate file system. If fs_name is not NULL and the device is a logical volume device the partition raw_type must be compatible with the file system.

If the volume is in an inconsistent state and needs vfs_fsck() run on it, then vfs_mount()

fails with errno set to EAGAIN.

vfs_umount

, vfs_fsck

7702033 Rev 27 289/515

OSPlus file systems

vfs_open

Definition:

Open a file

vfs_file_t *vfs_open (

const char *file,

const int flags)

Arguments:

Returns:

Errors:

file flags

The file to open, including the path.

The access permission flags.

Returns a pointer to the newly-opened file, or NULL for failure.

Description:

See also:

UM1150

ENOSPC

EISDIR

EROFS

Creation of a new file failed as the volume is full.

The value of file is a directory.

The volume was mounted as read-only.

vfs_open()

opens a file using the specified flags and returns a pointer to a newlycreated file handle object. The flags argument is a bitmap with the values defined in

Table 97

.

Table 97.

Open modes for file systems

Flag

OSPLUS_O_RDONLY

OSPLUS_O_WRONLY

OSPLUS_O_RDWR

OSPLUS_O_APPEND

OSPLUS_O_TRUNC

OSPLUS_O_CREAT

OSPLUS_O_EXCL

Description

Open for reading only.

Open for writing only.

Open for reading and writing.

Set file position to the end of the file.

Set the file size to zero.

If file does not exist then create it.

If OSPLUS_O_CREAT is also set and the file does not already exist, then create it, otherwise fail.

It is also possible to use combinations, for example OSPLUS_O_RDWR |

OSPLUS_O_APPEND

.

vfs_creat

, vfs_close

290/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_opendir

Definition:

Arguments:

Open a directory for reading

vfs_dir_t *vfs_opendir (const char *name)

Returns:

Errors:

name

The name of the directory to open.

Returns a pointer to the opened directory, or NULL for failure.

ENOTDIR

The value of name is not a directory.

Description:

See also:

vfs_opendir()

opens the directory for reading and returns a newly created directory handle object. The directory position is set to the first entry of the directory.

Note: No assumption is made about the ordering of directory entries, as this is dependent on the subordinate file system implementation.

vfs_closedir

vfs_read

Definition:

Read data from a file

int vfs_read (

vfs_file_t *file,

void *buffer,

const size_t count)

Arguments:

Returns:

Description:

See also:

file buffer count

The open file.

The buffer in to which to read the data.

The number of bytes to read.

Returns the number of bytes read, or -1 for failure.

vfs_read()

reads the specified number of bytes from the given open file and places them in the buffer provided. It returns the number of bytes read and sets the file position to point to the next byte after the last one read.

vfs_write

7702033 Rev 27 291/515

OSPlus file systems UM1150

vfs_readdir

Definition:

Read a directory

int vfs_readdir (

vfs_dir_t *dir,

vfs_dirent_t *dirent)

Arguments:

Returns:

Description:

dir dirent

The directory to read.

The dirent to read values into.

Returns 0 on success, or -1 for failure.

vfs_readdir()

reads the next entry in the directory and stores the name in the d_name

field and the mode in the mode field of the vfs_dirent_t structure. The directory position is then incremented to the next valid entry.

The vfs_dirent_t structure has the following format: typedef struct

{

} vfs_dirent_t

Table 98.

vfs_dirent_t fields

Field name

d_name mode

Description

The directory name

The directory mode, VFS_MODE_W, VFS_MODE_R or

VFS_MODE_RW

.

The

VFS_MODE_DIR

bit is also set

292/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_register

Definition:

Arguments:

Register a file system with VFS

int vfs_register (_vfs_filesystem_t *type);

Returns:

Errors:

type

The file system information.

Returns 0 for success, -1 for failure.

Description:

See also:

EEXIST

The name is already used.

The vfs_register() function validates the _vfs_filesystem_t structure and copies the contents for later use. Any function pointers not provided, that are subsequently needed by a VFS function, cause an assertion in the debug libraries and an exception in the non-debug libraries. It is therefore safer to provide a stub function that returns -1 and sets errno to ENOTSUP for unsupported functions.

vfs_unregister

vfs_rename

Definition:

Rename a file

int vfs_rename (

const char *oldpath,

const char *newpath)

Arguments:

Returns:

Errors:

oldpath newpath

The current name of the file or directory.

The new name and location of the file.

Returns 0 for success, -1 for failure.

Description:

ENOTSUP

Renaming to a path on a different volume is not supported.

vfs_rename()

renames a file or directory from oldpath to newpath. Both the old and new names must reside on the same physical volume.

If oldpath is a file or directory, the newpath must not already exist and is created respectively as a file or directory with the contents of oldpath.

7702033 Rev 27 293/515

OSPlus file systems UM1150

vfs_resize

Definition:

Change the size of a file

int vfs_resize (

vfs_file_t *file,

const size_t new_size)

Arguments:

file new_size

The open file to be resized.

The new size of the file.

Returns 0 for success, -1 for failure.

Returns:

Errors:

Definition:

ENOSPC

ENOMEM

Not enough space to satisfy request.

A memory allocation failed.

vfs_resize()

changes the size of the file to the size given in new_size, adding or removing on-disk storage structures as needed.

vfs_resize64

Change the size of a file (64-bit version)

Definition:

Without native 64-bit support: int vfs_resize64 (

Arguments:

Returns:

Errors:

Description:

With native 64-bit support: int vfs_resize64 ( const vfs_longlong_t new_size) file new_size new_high new_low

The open file to be resized.

The new size of the file (64-bit).

The upper 32 bits of the new size.

The lower 32 bits of the new size.

Returns 0 for success, -1 for failure.

ENOSPC

E2BIG

Not enough space to satisfy request.

The 64-bit offset is not supported on this file system.

vfs_resize64()

changes the file size according to new_size (or new_high and new_low

on systems without native 64-bit support), adding or removing on-disk storage structures as needed.

294/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_rewind

Definition:

Arguments:

Move the file position to the start of the file

int vfs_rewind (vfs_file_t *file)

Returns:

Description:

file

The file to rewind.

Returns 0 for success, -1 for failure.

vfs_rewind()

moves the file position back to the start of the file.

vfs_rewinddir

Set the directory position back to the first entry

Definition:

Arguments:

int vfs_rewinddir (vfs_dir_t *dir) dir

The directory to rewind.

Returns:

Description:

Returns 0 for success, -1 for failure.

vfs_rewinddir()

sets the directory position back to its first entry.

7702033 Rev 27 295/515

OSPlus file systems UM1150

vfs_rmdir

Definition:

Arguments:

Remove a directory

int vfs_rmdir (const char *pathname)

Returns:

Errors:

pathname

The directory to remove.

Returns 0 for success, -1 for failure.

Description:

ENOTEMPTY

The directory still has files or directories.

vfs_rmdir()

removes the directory at location pathname.

vfs_seekdir

Definition:

Move to a new position in a directory

int vfs_seekdir (

vfs_dir_t *dir,

const int offset)

Arguments:

Returns:

Description:

See also:

dir

The offset position.

Returns 0 for success, -1 for failure.

vfs_seekdir()

moves the directory’s position to the value specified by offset which was obtained by a previous call to vfs_telldir(). If an invalid or modified value of offset is passed in the behavior is undefined.

vfs_telldir

296/515 7702033 Rev 27

UM1150

vfs_stat

Definition:

Arguments:

Returns:

Description:

OSPlus file systems

Get detailed information for a file or directory

int vfs_stat (

const char *file,

vfs_stat_t *buf) file buf

The file or directory name.

The structure to return values.

Returns 0 for success, -1 for failure.

vfs_stat()

gets detailed information about the file or directory and returns the values in the vfs_stat_t buffer that was allocated by the user before calling this function.

The vfs_stat_t structure has the following format: typedef struct

{

} vfs_stat_t

The fields are described in

Table 99

.

Table 99.

vfs_stat_t fields

Field name Description

st_mode

The access mode, VFS_MODE_W, VFS_MODE_R,

VFS_MODE_RW

or VFS_MODE_HIDDEN. If the entry is a directory the VFS_MODE_DIR bit is set.

The size of the file in bytes st_size st_blksize

The size of the logical blocks for this particular volume st_atime of st_mtime st_ctime

The time of the last contents modification

The time of the last status change

See also:

Note: The st_atime, st_mtime, st_ctime fields are implementation dependent and

their meaning varies slightly between file system types. For details regarding E2FS refer to

Section 7.3.5 on page 249

and for details regarding FAT refer to

Section 7.4.3 on page 254 .

vfs_fstat

7702033 Rev 27 297/515

OSPlus file systems

vfs_stat64

Definition:

UM1150

Get detailed information for a file or directory (64-bit version)

int vfs_stat64 (

const char *file,

vfs_stat64_t *buf)

Arguments:

Returns:

Description:

file buf

The file or directory name.

The structure to return values.

Returns 0 for success, -1 for failure.

vfs_stat64()

gets detailed information about the file or directory and returns the values in the vfs_stat64_t buffer that was allocated by the user before calling this function.

The vfs_stat64_t structure has the following format when 64-bit is not supported natively: typedef struct

{

} vfs_stat64_t

The vfs_stat64_t structure has the following format when 64-bit is supported natively: typedef struct

{

} vfs_stat64_t

298/515 7702033 Rev 27

UM1150 OSPlus file systems

The fields are described in

Table 100

.

Table 100.

vfs_stat64_t fields

Field name Description

st_mode st_size st_size_high st_size_low st_blksize

The access mode, VFS_MODE_W, VFS_MODE_R, or

VFS_MODE_RW

. If the entry is a directory the

VFS_MODE_DIR

bit is set.

The size of the file in bytes (64-bit)

The upper 32 bits of the file size in bytes

The lower 32 bits of the file size in bytes

The size of the logical blocks for this particular volume st_atime of st_mtime st_ctime

The time of the last contents modification

The time of the last status change

See also:

Note: The st_atime, st_mtime, st_ctime fields are implementation dependent and

their meaning varies slightly between file system types. For details regarding E2FS refer to

Section 7.3.5 on page 249

and for details regarding FAT refer to

Section 7.4.3 on page 254 .

vfs_fstat64

7702033 Rev 27 299/515

OSPlus file systems UM1150

vfs_sync

Definition:

Arguments:

Flush all open files and metadata on a volume

int vfs_sync (const char *root)

Returns:

Description:

root

The root directory of the mounted volume.

Returns 0 for success, or -1 for failure.

vfs_sync()

flushes all unwritten file data and metadata to the volume and marks it as clean.

vfs_sync_all

See also:

vfs_sync_all

Flush all open files and metadata on all volumes

Definition:

Returns:

Description:

See also:

int vfs_sync_all (void)

Returns 0 on success, or -1 for failure.

vfs_sync_all()

flushes all unwritten file data and metadata to the volumes for all mounted volumes and marks them as clean.

vfs_sync

300/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_telldir

Definition:

Arguments:

Get a reference to the current location in a directory

int vfs_telldir (vfs_dir_t *dir)

Returns:

Description:

See also:

dir

The directory for which to get the position.

Returns an integer reference to the current position, or -1 for failure.

vfs_telldir()

returns an integer reference for the current position in the directory.

Unlike the value returned from vfs_ftell(), the reference is not an absolute value and therefore any modification by the user invalidates its later use in vfs_seekdir()

.

vfs_ftell

, vfs_seekdir

vfs_umount

Definition:

Arguments:

Unmount a volume

int vfs_umount (const char *dir)

Returns:

Errors:

dir directory.

Returns 0 for success, -1 for failure.

Description:

See also:

EBUSY

The volume still has open files or directories.

vfs_umount()

deletes the mount point that has the dir as its root directory, and closes the device handle. Any unwritten file data and metadata is flushed and the volume is marked as clean. It fails if there are any open files or directories.

vfs_mount

, vfs_umount_all

7702033 Rev 27 301/515

OSPlus file systems UM1150

vfs_umount_all

Unmount all volumes after closing all file and directory handles

Definition:

Returns:

Description:

See also:

int vfs_umount_all (void)

Returns 0 for success, -1 for failure.

vfs_umount_all()

closes all file and directory handles and then unmounts all volumes. This functions is thread safe and waits for any currently executing VFS functions to complete before starting. Once this function is in progress, any concurrent calls to other VFS functions wait for it to complete.

Note: If this function closes a file or directory a small portion of the handle remains in

memory until the associated vfs_close() or vfs_closedir() function is called. vfs_mount

, vfs_umount, vfs_close, vfs_closedir

vfs_unlink

Definition:

Arguments:

Unlink a file

int vfs_unlink (const char *pathname)

Returns:

Errors:

pathname

The file to unlink.

Returns 0 for success, -1 for failure.

Description:

EBUSY

The file is being used by another open file handle.

vfs_unlink()

removes the file from the physical volume.

302/515 7702033 Rev 27

UM1150 OSPlus file systems

vfs_unregister

Unregister a file system from the VFS

Definition:

Arguments:

int vfs_unregister (char *fs_name); fs_name

Name of file system to unregister.

Returns:

Errors:

Returns 0 for success, -1 for failure.

Description:

See also:

ENOENT

EBUSY

The name does not exist.

The file system is used by a mount.

vfs_unregister()

searches for a registered file system with the given name, check if it is being used by any active mounts and if not then remove it.

vfs_register

vfs_vfprintf

Definition:

Print a formatted string to a file

int vfs_vfprintf (

vfs_file_t *file,

const char *fmt,

va_list args)

Arguments:

Returns:

Description:

See also:

file

The file to write to.

fmt string.

args

The argument list.

Returns the number of bytes written on success, -1 for failure.

vfs_vfprintf()

is identical to the standard C library vfprintf() except the output is written to a VFS file.

vfs_fprintf

7702033 Rev 27 303/515

OSPlus file systems

vfs_write

Definition:

Write to a file

int vfs_write (

vfs_file_t *file,

const void *buffer,

const size_t count)

Arguments:

Returns:

Errors:

file file.

buffer count

The buffer containing the data.

The number of bytes to write.

Returns the number of bytes written, or -1 for failure.

Description:

See also:

UM1150

ENOSPC

ENOMEM

The volume is full.

A memory allocation failed.

vfs_write()

writes the specified number of bytes to the open file at the current file position and returns the number of bytes written. The file position is set to point to the next byte after the last one written.

vfs_read

304/515 7702033 Rev 27

UM1150

7.8

7.8.1

OSPlus file systems

Adding a new file system to the VFS

The OSPlus VFS is a self-contained module that sits on top of subordinate file systems. The subordinate file systems are responsible for all communication between file system data storage devices and with any other modules in the system, for example, the logical volume manager.

The VFS supports arbitrary subordinate file systems. It therefore makes no assumptions about the underlying structure of the subordinate file system.

The interface between the VFS and a subordinate file system consists of a registered structure (_vfs_filesystem_t) that contains method pointers and associated information. A subordinate file system registers and unregisters with the VFS through the vfs_register()

and vfs_unregister() functions. The structure and the prototypes for these calls are contained in the vfs_fs.h header file.

Anatomy of a file system

●

●

●

●

Subordinate file systems should provide a header file containing: the prototypes for initialization and shutdown functions the subordinate file system name a structure for use with the vfs_format() function any specific commands for use with vfs_fscntl() or vfs_fcntl()

The subordinate file system should implement all of the necessary functionality and interact with other modules and device drivers as needed.

Initialization and shutdown

The subordinate file system must provide an initialization function that will call vfs_register()

to register the file system with the VFS. A function to shut down the file system and call vfs_unregister() to unregister it from the VFS must also be provided.

Subordinate file system name

The subordinate file system should provide a file system name string that uniquely identifies the file system. It is this name used in calls to vfs_mount(), vfs_format() and vfs_fsck()

. This string should also be used as the name parameter in the

_vfs_filesystem_t

structure used in the call to vfs_register(). The name is usually provided as a #define. For example:

#define E2FS_NAME "E2FS"

Format structure

Each subordinate file system must provide its own specific format structure for use with vfs_format()

. This structure must provide any parameters that are needed by the file system to complete the format operation. Typical parameters might be block sizes, cluster sizes and a flag to signify whether to blank all blocks on the device. If the parameters are optional, the subordinate file system format() function should accept a NULL value for the format structure pointer.

7702033 Rev 27 305/515

OSPlus file systems

7.8.2

UM1150

vfs_fscntl() and vfs_fcntl() commands

Generic commands for vfs_fscntl() and vfs_fcntl() that are supported by all subordinate file systems are contained in the vfs.h header file. Any commands specific to the subordinate file system should be defined in its own header file.

Buffers and caches

The subordinate file system is responsible for all memory management of its internal buffers and caches.

As the physical devices that host the file system are block-oriented devices, any reads or writes that are less than one block in size, or that are not block aligned, need to be staged through a temporary buffer.

The on-disk data and metadata is usually located in different parts of the device so it is common practice to provide a level of caching to reduce the device head movement. As some metadata is usually accessed regularly, caching can also improve the overall performance of the file system.

Partition types

Devices managed by the logical volume manager (LVM, see

Chapter 8: OSPlus logical volume manager on page 325

) have an associated partition raw_type that should be used

as part of the validation steps for the mount(), format() and fsck() methods. It depends on the subordinate file system to choose an appropriate value for the file system it is implementing. The raw_type is retrieved using the lvm_partition_info() function

(see

lvm_partition_info on page 336

) and if the device is not a volume managed by the LVM,

for example a raw device, this call would return -1 and set errno to EINVAL.

Locking

Once a device is mounted it can be accessed by any task in the system, so it is important the subordinate file system implements some form of locking to protect critical sections of code from being accessed by multiple threads at the same time. It is common practice to make each read and write atomic even when they involve accessing multiple blocks on the disk.

Service provided by the VFS

●

●

The VFS provides several top-level services that include:

●

●

●

● normalization of paths lists of open mounts, file and directories enforcement of file handle permissions searching for the correct subordinate file system for vfs_mount(), vfs_format() and vfs_fsck() operations string, character and buffer operations support for the “hidden” file attribute (FAT only)

306/515 7702033 Rev 27

UM1150 OSPlus file systems

Normalization of paths

●

●

●

●

The VFS normalizes any path names by removing: embedded . entries excess / characters

/ABC/..

instances the mount point’s root directory from the front of the path

For example, if the device was mounted with the dir parameter set to /FOO call to vfs_open()

with the path /FOO/.//ABC///DEF/../XYZ results in the subordinate’s open()

method being called with the path /ABC/XYZ.

List management

The VFS maintains lists of open mounts, files and directories. It uses these lists to control certain operations. For example vfs_umount() cannot be called on a device that still has open file or directory handles, and the same device cannot have two active mounts.

File handle permissions

The VFS restricts access to vfs_write(), vfs_fchmod(), vfs_resize() and vfs_flush()

for files opened read-only (OSPLUS_O_RDONLY) and to vfs_read() for files opened write-only (OSPLUS_O_WRONLY).

Mount permissions

The VFS only allows mounts to be read/write (OSPLUS_O_RDWR) or read-only

(OSPLUS_O_RDONLY). If the mount is read-only, the VFS rejects any operations that need write permission, including vfs_open(), vfs_rename(), vfs_mkdir(), vfs_rmdir(), vfs_unlink()

and vfs_chmod().

Searching for the correct subordinate file system

When the file system type is not specified for calls to vfs_mount(), vfs_fsck() or vfs_format()

, the VFS calls each registered subordinate file system until one of the calls succeeds. It is the responsibility of the subordinate file system to check whether the device being used is a logical volume, and if so check the volume has an appropriate raw_type

(using lvm_partition_info()). If it is not, the method should return -1 and set errno to

ENODEV

.

Char, string and buffer operations

The VFS supports a large number of API functions that include string, character and buffer style operations (for example, vfs_putc(), vfs_fprintf()), but all of these are mapped to the read() or write() methods provided by the subordinate file systems.

Large file support

Large files are supported by additional 64-bit versions of various VFS functions. These functions are duplicated in the VFS/subordinate interface in the form of fstat64(), resize64()

, seek64(), stat64() and tell64(). On cores that don’t support native

64-bit operations (for example, ST20-C1 and ST20-C2), alternative versions that use two

32-bit values are provided.

7702033 Rev 27 307/515

OSPlus file systems UM1150

7.8.3 Types

The types defined in the vfs_fs.h header file are used for sharing information between the

VFS and the subordinate file systems. Each of the defined types contains a void* pointer, called desc. This can be used by the subordinate file system to hold its own specific information. This pointer should be populated by the subordinate file system in the mount()

, open() or opendir() methods.

The _vfs_mount_t structure

typedef struct _vfs_mount_s {

void *desc;

char *device_name;

int flags;

} _vfs_mount_t;

Table 101.

_vfs_mount_t fields

Field name Description

desc void*

pointer for use by subordinate file system device_name device flags

Mount flags, either OSPLUS_O_RDWR or

OSPLUS_O_RDONLY

.

The _vfs_mount_t structure is created as part of the vfs_mount() process and is passed as a parameter to the following subordinate file system methods: mount(), umount()

, open(), rename(), opendir(), stat(), stat64(), mkdir(), rmdir(), unlink()

, chmod(), fscntl() and sync().

The _vfs_file_t structure

typedef struct _vfs_file_s {

int flags;

void *desc;

} _vfs_file_t;

Table 102.

_vfs_file_t fields

Field name

flags

Description

File open flags (see

Table 97: Open modes for file systems on page 290

) void*

pointer for use by subordinate file system desc

The _vfs_file_t structure is created during the vfs_open() process and is passed as a parameter to all file related methods, including: open(), read(), write(), close(), tell()

, tell64(), seek(), seek64(), eof(), fstat(), fstat64(), flush(), fchmod()

, resize() and resize64().

308/515 7702033 Rev 27

UM1150 OSPlus file systems

The _vfs_dir_t structure

typedef struct _vfs_dir_s {

void *desc;

} _vfs_dir_t;

Table 103.

_vfs_dir_t fields

Field name Description

void*

pointer for use by subordinate file system desc

The _vfs_dir_t structure is created as part of the vfs_opendir() process and is passed to all directory related methods, including: opendir(), closedir(), readdir(), rewinddir()

, telldir() and seekdir().

The _vfs_filesystem_t structure

typedef struct _vfs_filesystem_s {

char name[VFS_FILESYSTEM_NAME_LEN_MAX];

int (*mount) (_vfs_mount_t *mount);

...

...

int (*fsck) (const char *device_name);

} _vfs_filesysem_t;

Table 104.

_vfs_filesystem_t fields

Field name Description

name int (*mount)()

...

int (*fsck)()

Name of file system

Method pointers

The _vfs_filesystem_t structure is passed in as a parameter to the vfs_register() function by the subordinate file system’s initialization routine. The name field should match the defined name in the subordinate file system’s header file. The function pointers are

described in more detail in

Section 7.8.4

.

7702033 Rev 27 309/515

OSPlus file systems UM1150

chmod

Definition:

Change permissions on a file or directory

int (*chmod) (_vfs_mount_t *mount,

const char *path,

const unsigned int mode);

Arguments:

Returns:

Description:

mount path mode

The mount handle.

The file or directory name.

The new permissions.

Returns 0 for success, -1 for failure.

Change the mode of a file or directory. VFS rejects chmod operations on file systems that are mounted read-only. Possible values of mode are VFS_MODE_W, VFS_MODE_R and VFS_MODE_RW.

close

Definition:

Arguments:

Close a file

int (*close) (_vfs_file_t *file); file

The file handle.

Returns:

Returns 0 for success, -1 for failure.

Description:

To close the file handle:

1.

Flush any unwritten data and metadata to the device.

2. Delete the internal representation of the file handle stored in the desc field of the

_vfs_file_t

structure.

closedir

Definition:

Arguments:

Close a directory

int (*closedir) (_vfs_dir_t *dir);

Returns:

Description:

dir

The directory handle.

Returns 0 for success, -1 for failure.

Close a directory handle and delete the internal representation stored in the desc field of the _vfs_dir_t structure.

310/515 7702033 Rev 27

UM1150

dcntl

Definition:

Arguments:

OSPlus file systems

Perform a directory control

int (*dcntl) (_vfs_dir_t *dir,

const int request,

void *param); dir

The directory handle.

request

A param

The optional parameters or a buffer for the result.

Returns 0 for success, -1 for failure.

Perform a directory-control (ioctl) on the open directory handle.

Returns:

Description:

defrag

Definition:

Arguments:

Returns:

Errors:

Description:

Defragment a volume

int defrag ( _vfs_mount_t *mount,

const vfs_defrag_option_t option); mount option

The mount handle.

The defragmentation option.

Returns 0 for successful completion, 1 for partial completion and -1 for failure.

EBUSY

ENOSPC volume has files/dirs open.

volume can not be defragmented due to lack of free space.

To defragment a volume:

1.Check there are no open file or directory handles.

2. Check there is sufficient free space on the volume.

3. Defragment the volume.

4. Stop after each file or partial file if the option is set to vfs_defrag_entire_file or vfs_defrag_partial_file.

5. Once finished (or if called with vfs_defrag_stop), free any memory used and return the volume to a state in which it can be used for normal I/O operations.

7702033 Rev 27 311/515

OSPlus file systems

eof

Definition:

Arguments:

Check end-of-file condition

int (*eof) (_vfs_file_t *file);

Returns:

Description:

fchmod

file

The file handle.

Returns 1 if EOF is true, 0 otherwise.

Check if the end-of-file condition is true.

Definition:

Arguments:

Change permissions for a file

int (*fchmod) (_vfs_file_t *file,

const unsigned int mode);

Returns:

Description:

UM1150

file mode

The file handle.

The new permissions.

Returns 0 for success, -1 for failure.

Change the mode of an open file handle. VFS rejects fchmod operations on files that are opened read-only.

fcntl

Definition:

Perform a file control

int (*fcntl) (_vfs_file_t *file,

const int request,

void *param);

Arguments:

Returns:

Description:

file handle.

request

A param

The optional parameters or a buffer for the result.

Returns 0 for success, -1 for failure.

Perform a file-control (ioctl) on the open file handle.

312/515 7702033 Rev 27

UM1150

flush

Definition:

Arguments:

Returns:

Description:

fsck

Definition:

Arguments:

Returns:

Errors:

Description:

OSPlus file systems

Flush any unwritten information for a file

int (*flush) (_vfs_file_t *file); file

The file handle.

Returns 0 for success, -1 for failure.

Flush any unwritten data and metadata for the open file handle. VFS rejects a flush on a file that is opened read-only.

format

Definition:

Arguments:

Returns:

Errors:

Description:

Format a device

int (*format) (const char *device_name,

void *param); device_name param

The device name.

The file system specific format parameters.

Returns 0 for success, -1 for failure.

ENODEV

Volume type is not supported by this file system.

To enable the device to be formatted:

1.Check the logical volume of the device is the correct type.

2. Initialize the on-disk structures and mark the device as clean.

Perform a file system check on the device

int (*fsck) (const char *device_name); device_name

The device name.

Returns 0 for success, -1 for failure.

ENODEV

Volume type is not supported by this file system.

To enable a file system check to be run on the device:

1.Check the logical volume of the device is the correct type.

2. Ensure the on-disk structures are in a coherent state.

3. Mark the file system on the device as clean.

7702033 Rev 27 313/515

OSPlus file systems

fscntl

Definition:

Perform a file system control

int (*fscntl) (_vfs_mount_t *mount,

const int request,

void *param);

Arguments:

Returns:

Description:

fstat

mount request param

The mount handle.

A command.

The optional parameters or a buffer for the result.

Returns 0 for success, -1 for failure.

Perform a file-system-control (ioctl) on the file system.

Definition:

Arguments:

Get file information

int (*fstat) (_vfs_file_t *file,

vfs_stat_t *buffer);

Returns:

Description:

fstat64

file buffer

The file handle.

The VFS stat buffer.

Returns 0 for success, -1 for failure.

Get the open file handles stats and store them in the buffer provided.

Definition:

Arguments:

Get file information (64-bit version)

int (*fstat64) (_vfs_file_t *file,

vfs_stat64_t *buffer);

Returns:

Description:

file buffer

The file handle.

The VFS stat buffer.

Returns 0 for success, -1 for failure.

Get the open file handles stats and store them in the buffer provided.

UM1150

314/515 7702033 Rev 27

UM1150 OSPlus file systems

mkdir

Definition:

Make a new directory

int (*mkdir) (_vfs_mount_t *mount,

const char *dir);

Arguments:

Returns:

Description:

mount dir

The mount handle.

The directory name.

Returns 0 for success, -1 for failure.

Make a new directory. VFS rejects mkdir operations on file systems that are mounted read-only.

mount

Definition:

Arguments:

Mount a device

int (*mount) (_vfs_mount_t *mount);

Returns:

Errors:

mount

The mount handle.

Returns 0 for success, -1 for failure.

EAGAIN

ENODEV

File system may be corrupt and needs to have vfs_fsck() run on it.

Volume type is not supported by this file system.

Description:

To mount a device for use by the VFS:

1.Open the device to be mounted.

2. If the device is a logical volume, check the volume is of the correct type.

3. Check the file system on the device is in a clean state and does not need to have vfs_fsck()

run on it.

4. Create the internal representation of the file system and store the value in the desc

field of the _vfs_mount_t structure.

VFS ensures the device is not mounted twice.

7702033 Rev 27 315/515

OSPlus file systems

open

Definition:

Open a file

int (*open) (_vfs_mount_t *mount,

const char *filename,

_vfs_file_t *file);

Arguments:

Returns:

Description:

UM1150

mount filename file

The mount handle.

Name of the file.

The file handle.

Returns 0 for success, -1 for failure.

To open a file for access:

1.Validate the flags.

2. Check permissions on the parent directory.

3. Find the file or create it if OSPLUS_O_CREAT is set.

4. Create the internal representation of the file handle and store it in the desc field of the _vfs_file_t structure.

5. Set the file pointer to the beginning of the file.

VFS ensures certain flag combinations are rejected, including write access on a device that is mounted read-only.

opendir

Definition:

Open a directory for reading

int (*opendir) (_vfs_mount_t *mount,

const char *dirname,

_vfs_dir_t *dir);

Arguments:

Returns:

Description:

mount dirname dir

The mount handle.

The directory name.

The directory handle.

Returns 0 for success, -1 for failure.

Opens a directory for reading, creating the internal representation of the directory handle and storing it in the desc field of the _vfs_dir_t structure.

316/515 7702033 Rev 27

UM1150

read

Definition:

Arguments:

Returns:

Description:

OSPlus file systems

Read from a file

int (*read) (_vfs_file_t *file,

void *buffer,

const size_t count); file buffer count

The file handle.

The buffer to use.

The number of bytes.

Returns 0 for success, -1 for failure.

Read data from file and update the file pointer position. VFS rejects read operations on files that are opened write-only.

readdir

Definition:

Arguments:

Read the next directory entry

int (*readdir) (_vfs_dir_t *dir,

vfs_dirent_t *dirent); dir dirent

The directory handle.

The VFS direct structure.

Returns 0 for success, -1 for failure.

Read the next valid directory entry.

Returns:

Description:

rename

Definition:

Arguments:

Returns:

Description:

Rename a file or directory

int (*rename) (_vfs_mount_t *mount,

const char *oldpath,

cont char *newpath); mount oldpath newpath

The mount handle.

The old file or directory name.

The new file or directory name.

Returns 0 for success, -1 for failure.

Rename a file or directory. VFS rejects rename operations on read-only file systems, or if the oldpath and newpath are on different file systems.

7702033 Rev 27 317/515

OSPlus file systems

resize

Definition:

Arguments:

Resize a file

int (*resize) (_vfs_file_t *file,

const size_t new_size);

Returns:

Description:

UM1150

file new_size

The file handle.

The new size.

Returns 0 for success, -1 for failure.

Resize a file, allocating or de-allocating the on-disk storage as needed. VFS rejects resize

operations on files that are opened read-only.

resize64

Definition:

Resize a file (64-bit version)

Without native 64-bit support: int (*resize64) (_vfs_file_t *file,

Arguments:

Returns:

Description:

With native 64-bit support: int (*resize64) (_vfs_file_t *file, const vfs_longlong_t new_size); file new_size new_high new_low

The file handle.

The new size (64-bit).

The upper 32-bits of the new size.

The lower 32-bits of the new size.

Returns 0 for success, -1 for failure.

Resize a file, allocating or de-allocating the on-disk storage as needed. VFS rejects resize

operations on files that are opened read-only.

rewinddir

Definition:

Arguments:

Returns:

Description:

Rewind to the start of the directory

int (*rewinddir) (_vfs_dir_t *dir); dir

The directory handle.

Returns 0 for success, -1 for failure.

Set the directory pointer to the first entry.

318/515 7702033 Rev 27

UM1150

rmdir

Definition:

Arguments:

Returns:

Description:

OSPlus file systems

Remove a directory

int (*rmdir) (_vfs_mount_t *mount,

const char *dir); mount dir

The mount handle.

The directory name.

Returns 0 for success, -1 for failure.

Remove an existing directory. VFS rejects rmdir operations on file systems that are mounted read-only.

seek

Definition:

Arguments:

Returns:

Description:

Set the file pointer

int (*seek) (_vfs_file_t *file,

const int offset,

const int whence); file offset whence

The file handle.

The file offset.

The method of seeking.

Returns 0 for success, -1 for failure.

Set the file pointer value and check it has not wrapped around to the beginning of the file. See

Table 96: Values of whence parameters on page 282

for a description of the

offset

and whence rules.

7702033 Rev 27 319/515

OSPlus file systems

seek64

Definition:

Set the file pointer (64-bit version)

Without native 64-bit support: int (*seek64) (_vfs_file_t *file, const int offset_high, const int whence);

With native 64-bit support: int (*seek64) (_vfs_file_t *file, const vfs_longlong_t offset, const int whence);

Arguments:

Returns:

Description:

UM1150

file offset offset_high offset_low whence

The file handle.

The file offset (64-bit).

The upper 32-bits of the file offset.

The lower 32-bits of the file offset.

The method of seeking.

Returns 0 for success, -1 for failure.

Set the file pointer value and check it has not wrapped around to the beginning of the file. See

Table 96: Values of whence parameters on page 282

for a description of the

offset

and whence rules.

seekdir

Definition:

Arguments:

Set the directory pointer

int (*seekdir) (_vfs_dir_t *dir,

const int offset);

Returns:

Description:

dir offset

The directory handle.

The new position.

Returns 0 for success, -1 for failure.

Set the directory pointer to a value previous retrieved using the telldir() method.

320/515 7702033 Rev 27

UM1150

stat

Definition:

Arguments:

OSPlus file systems

Get file or directory information

int (*stat) (_vfs_mount_t *mount,

const char *path,

vfs_stat_t *buffer); mount path buffer

The mount handle.

The file or directory name.

The VFS stat buffer.

Returns 0 for success, -1 for failure.

Get the file or directory stats and store them in the buffer provided.

Returns:

Description:

stat64

Definition:

Arguments:

Returns:

Description:

Get file or directory information (64-bit version)

int (*stat64) (_vfs_mount_t *mount,

const char *path,

vfs_stat64_t *buffer); mount path buffer

The mount handle.

The file or directory name.

The VFS stat buffer.

Returns 0 for success, -1 for failure.

Get the file or directory stats and store them in the buffer provided.

7702033 Rev 27 321/515

OSPlus file systems

sync

Definition:

Arguments:

Write all unwritten information for the device

int (*sync) (_vfs_mount_t *mount);

Returns:

Description:

UM1150

mount

The mount handle.

Returns 0 for success, -1 for failure.

Flush all unwritten data and metadata for the file system to the underlying device and mark the volume as clean.

tell

Definition:

Arguments:

Get current file pointer

int (*tell) (_vfs_file_t *file);

Returns:

Description:

tell64

file

The file handle.

Returns file pointer value for success, -1 for failure.

Return the current file pointer value as an integer.

Definition:

Get current file pointer (64-bit version)

Without native 64-bit support: int (*tell64) (_vfs_file_t *file,

Arguments:

Returns:

Description:

With native 64-bit support: vfs_longlong_t (*tell64) (_vfs_file_t *file); file size_high size_low

The file handle.

The upper 32-bits of the file size.

The lower 32-bits of the file size.

Returns file pointer value (or 0 for systems without native 64-bit support) for success,

-1

for failure.

Return the current file pointer value (in size_high and size_low for systems without native 64-bit support).

322/515 7702033 Rev 27

UM1150

telldir

Definition:

Arguments:

Returns:

Description:

umount

Definition:

Arguments:

Returns:

Description:

OSPlus file systems

Get the current directory pointer value

int (*telldir) (_vfs_dir_t *dir); dir

The directory handle.

Returns an integer reference to the current position, or -1 for failure.

Get the current directory pointer as an integer.

Unmount a device

int (*umount) (_vfs_mount_t *mount); mount

The mount handle.

Returns 0 for success, -1 for failure.

To unmount the device:

1.Flush any unwritten data to the device.

2. Mark the file system as clean on the device.

3. Close the device.

4. Delete the internal representation of the file system stored in the desc field of the

_vfs_mount_t

structure.

VFS ensures there are no open file or directory handles.

unlink

Definition:

Arguments:

Returns:

Description:

Remove a file

int (*unlink) (_vfs_mount_t *mount,

cons char *pathname); mount pathname

The mount handle.

The file name.

Returns 0 for success, -1 for failure.

Remove an existing file. VFS rejects unlink operations on file systems that are mounted read-only, or on files that are currently open.

7702033 Rev 27 323/515

OSPlus file systems

write

Definition:

Write to a file

int (*write) (_vfs_file_t *file,

const char *buffer,

const size_t count);

Arguments:

Returns:

Description:

UM1150

file buffer count

The file handle.

The buffer to use.

The number of bytes.

Returns 0 for success, -1 for failure.

Write data to the file and update the file pointer position. If the file was opened with the OSPLUS_O_APPEND flag set then all writes must go to the end of the file. If the write is beyond the current end of the file, the file size must be increased if possible.

VFS rejects write operations on files that are opened read-only.

324/515 7702033 Rev 27

UM1150

8 OSPlus logical volume manager

OSPlus logical volume manager

8.1 Logical volume manager overview

The OSPlus logical volume manager (LVM) library manages mass storage devices (for example, hard disk drives) and removable media devices (for example, card readers and

DVD drives).

8.2 Partitions

Some mass storage devices (like hard disk drives and memory cards) are partitioned into multiple logical devices. The LVM automatically detects any partitions on these devices, and presents them as logical volume devices to the applications.

The application can use the logical volume devices to mount the file systems they contain. It is expected that applications will only ever use logical volumes for performing I/O to block devices. They should not typically need direct access to the raw block devices.

The LVM’s use of partitions is fully compatible with MS-DOS and Windows. Therefore, any partition that the LVM creates on a device should be accessible by MS-DOS, Windows or

Linux.

Each logical volume device is a block device, just like a disk. It is addressable from LBA 0 onwards. The LVM takes care of mapping these accesses to the correct position on the physical device. Logical volume devices support all the standard OSPlus ioctls for block devices, as well as any specific ioctls supported by the underlying raw device.

The LVM also provides an API, allowing the partition table to be manipulated on partitionable devices.

There are three types of partition which can appear on a mass storage device:

●

●

● primary partitions extended partitions logical partitions

There can be up to four primary partitions, or three primary partitions and one extended partition. An extended partition can support an arbitrary number of logical partitions.

The LVM presents partitions with the lvm_partition_t type which has the following format: typedef struct

{

lba_t start_lba;

size_t size;

lvm_partition_type_t type;

unsigned char raw_type;

char volume_name[LVM_MAX_VOL_NAME_LEN];

} lvm_partition_t;

7702033 Rev 27 325/515

OSPlus logical volume manager UM1150

The fields are described in

Table 105

.

Table 105.

lvm_partition_t fields

Field name

start_lba size type raw_type

Description

Start address on disk. This depends on the value of type .

For lvm_free_area, lvm_primary_partition and lvm_extended_partition partitions, it is the absolute address on the parent mass storage device of the first block of the partition or free area.

For lvm_logical_partition and

lvm_extended_free_area

partitions, it is its position within the extended partition (that is, relative to the first block of the extended partition).

Size in blocks

LVM logical type. This can be: lvm_free_area

, a region of unallocated blocks outside of an extended partition, lvm_extended_free_area

, a region of unallocated blocks within an extended partition, lvm_primary_partition

, a primary partition, lvm_extended_partition

, an extended partition, lvm_logical_partition

, a logical partition.

Low-level partition type from the on-disk structures. The

LVM recognizes three extended partition types (see

Table 106

).

Associated logical volume (if any) volume_name

The function lvm_partitions() returns an array of lvm_partition_ts (an lvm_partitions_t

) describing all the partitions and free areas on the given device.

OSPlus supports the fundamental partition types given in

Table 106

, as used in the

raw_type

field in the lvm_partition_t structure.

Table 106.

lvm_partition_t raw_type

Partition description

FAT12

FAT16

FAT32

E2FS

MS-DOS extended partition

Windows 95 extended partition

Linux extended partition

raw_type value

0x01

, 0x11

0x04

, 0x06, 0x0E, 0x14, 0x16, 0x1E

0x0B

, 0x0C, 0x1B, 0x1C

0x83

0x05

0x0F

0x85

326/515 7702033 Rev 27

UM1150

8.2.3

Note:

Note:

OSPlus logical volume manager

Creating and deleting partitions

Partitions can be created with lvm_partition_create() and lvm_partition_create_adv()

. These calls take a device name and an lvm_partition_t

as parameters and attempt to create the partition on the device. lvm_partition_create()

assumes traditional MS-DOS geometries (63 sectors per track and 255 heads per cylinder). lvm_partition_create_adv() allows the caller to specify the number of heads per cylinder and sectors per track, thus giving finer control of partition alignment. For instance, to create a partition which is aligned to 1 megabyte boundaries, set the number of sectors per track to be 2048 and the number of heads per cylinder to be 1. This example yields the same partition alignment as used by Windows 7, and is particularly suitable for “Advanced Format” HDDs (4 k sectored devices) and solid state storage devices (SSDs).

The size of the resulting partition can be larger or smaller than requested. This is because the LVM aligns the partition within the specified or implied disk geometry.

lvm_partition_create()

needs the caller to specify the exact nature and location of the partition. A simpler way to create a partition is to use the lvm_volume_create() or lvm_volume_create_adv()

calls. For these calls, the caller specifies only the size of the desired partition and its raw type, and the LVM itself tries to find a suitable location on the device for the partition. These calls can only create primary or logical partitions, and create a logical partition over a primary partition by preference. To create a logical partition, an extended partition must exist on the device. lvm_volume_create() assumes default

MS-DOS geometry (63 sectors per track and 255 heads per cylinder) whilst lvm_volume_create_adv()

allows the caller to specify the number of sectors per track and heads per cylinder in order to achieve the desired alignment.

Before mounting a file system on a newly-created partition, the partition must first be formatted with an appropriate call to vfs_format().

All partitions on a device can be deleted with lvm_partition_delete_all(). This call must be used with care.

Individual partitions can be deleted with lvm_partition_delete(). If a partition matching the given description exists on the given device, it is deleted including any associated logical volume. If an extended partition is deleted, all logical partitions within it are also deleted. A simpler way to delete a partition is to use the call lvm_volume_delete()

. For this call, just the name of the logical volume is used and the

LVM unmounts the volume, finds the relevant partition and deletes it on the device.

8.3 Removable media devices

Some removable media devices do not support partitions (for example, CD-ROMs, DVDs and floppy disks). For these devices, the LVM maps the whole of the raw device with a single logical volume device.

The LVM can optionally monitor removable media devices for media change events. To detect media changes, the LVM must periodically open the devices and poll them. If the application does not want this polling to occur, it can prevent the LVM from doing it, and then handle media change detection itself. The LVM provides an API where the application can inform the LVM of media insertions and removals that it has detected.

7702033 Rev 27 327/515

OSPlus logical volume manager

8.4

UM1150

LVM library header file: lvm.h

All the definitions relating to the LVM are in the file lvm.h. The functions defined in lvm.h

are explained in

Section 8.5: LVM function definitions on page 329

.

Table 107.

Functions defined in lvm.h

Function

lvm_initialize() lvm_media_inserted() lvm_media_removed() lvm_partition_create() lvm_partition_create_adv() lvm_partition_delete() lvm_partition_delete_all() lvm_partition_info() lvm_partitions() lvm_volume_create() lvm_volume_create_adv() lvm_volume_delete() lvm_volumes()

Description

Initialize the LVM

Inform the LVM of a media insertion event

Inform the LVM of a media removal event

Create a new partition on the given device

Create a new partition on the given device

Delete the partition indicated

Delete all logical volumes from a raw device

Return details for the specified logical volume

Return a list of the all the partitions on the device

Create a logical volume

Create a logical volume

Delete a logical volume

Return the names of all logical volumes on a device

Table 108.

Types defined in lvm.h

Type

lvm_partition_t lvm_partition_type_t lvm_partitions_t lvm_volumes_t

Description

A description of a partition

The different types of partition

An array of partitions

An array of volumes

Table 109.

Macros defined in lvm.h

Macro

LVM_CONFIG_NOTIFICATION_PRI

LVM_CONFIG_PATH

LVM_CONFIG_TASK_PRI

LVM_MAX_VOL_NAME_LEN

Description

Registry key name of the option to set the LVM notification task priority

Path to the registry node containing LVM configuration options

Registry key name of the option to set the LVM removable media task priority

Maximum length of a logical volume name

328/515 7702033 Rev 27

UM1150 OSPlus logical volume manager

8.5 LVM function definitions lvm_initialize

Initialize the library

Definition:

Arguments:

int lvm_initialize (int polling_hz) polling_hz

The frequency to check removable media devices for media change.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

This call initializes the LVM. The parameter polling_hz specifies the frequency with which the LVM monitors removable media devices for media change events. Setting this value to 0 disables this feature, and the application has to handle media change sensing for itself. When initialized, the LVM monitors device insertions and extractions, and automatically probes the partition tables, creating logical volumes as required.

Note: To set the priority of the LVM tasks, configuration information should be written to the

registry before lvm_initialize() is called. The LVM configuration node in the

registry is given by LVM_CONFIG_PATH. The keys to set are given by

LVM_CONFIG_TASK_PRI

and LVM_CONFIG_NOTIFICATION_PRI. If one of these

keys is not set, then a default task priority of MAX_USER_PRIORITY is used. lvm_media_inserted

, lvm_media_removed

7702033 Rev 27 329/515

OSPlus logical volume manager UM1150

lvm_media_inserted

Notify LVM that a device has had new media inserted

Definition:

Arguments:

int lvm_media_inserted (const char *device_name) device_name

The name of the device which has new media.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

This call notifies the LVM that new media has been inserted in the named device. It probes the media, and mounts any logical volumes that it detects. If the LVM has polling enabled, this call does not need to be made.

lvm_media_removed

330/515 7702033 Rev 27

UM1150 OSPlus logical volume manager

lvm_media_removed

Notify LVM that a device has had its media removed

Definition:

Arguments:

int lvm_media_removed (const char *device_name) device_name

The name of the device which has had its media removed.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

This call tells the LVM the named device has had its media removed. The LVM deletes any logical volumes it mounted on the device. If the LVM has polling enabled, this call is not needed.

lvm_media_inserted

7702033 Rev 27 331/515

OSPlus logical volume manager UM1150

lvm_partition_create

Create a new partition on the given device

Definition:

int lvm_partition_create (

const char *device_name,

lvm_partition_t *partition)

Arguments:

device_name partition

The device on which to create the partition.

The details of the partition.

Returns:

Description:

Returns 0 for success, -1 for failure.

This call creates a new partition on the given device. If the partition is a primary or logical partition, it mounts it as a logical volume, returning the logical volume name in the partition structure. This call assumes default MS-DOS disk geometry (63 sectors per track and 255 heads per cylinder). The resulting partition is aligned to this geometry.

On exit, the details of the new partition are in partition.

Table 110

describes the lvm_partition_t fields at both the input and output stage.

Table 110.

lvm_partition_t fields for lvm_partition_create()

Field name

start_lba size type raw_type volume_name

Desired start LBA

Desired size in blocks

LVM logical type

Partition physical type

Ignored

Input Output

Actual start LBA of partition

Actual size of partition in blocks

LVM logical type

Partition physical type

Associated logical volume name for primary and logical partitions

See also:

lvm_partition_create_adv, lvm_partition_delete

332/515 7702033 Rev 27

UM1150 OSPlus logical volume manager

lvm_partition_create_adv

Create a new partition on the given device

Definition:

int lvm_partition_create_adv (

const char *device_name,

lvm_partition_t *partition,

size_t sectors_per_track,

size_t heads_per_cylinder)

Arguments:

device_name partition

The device on which to create the partition.

The details of the partition.

sectors_per_track

The number of sectors per track heads_per_cylinder

The number of heads per cylinder

Returns:

Description:

Returns 0 for success, -1 for failure.

This call creates a new partition on the given device. If the partition is a primary or logical partition, the call mounts it as a logical volume, returning the logical volume name in the partition structure. This call allows the disk geometry to be specified, so the alignment of the resulting partition can be specified. For instance, setting sectors_per_track

to 2048, and heads_per_cylinder to 1 aligns the partition on a one megabyte boundary.

On exit, the details of the new partition are in partition.

Table 111

describes the lvm_partition_t fields at both the input and output stage.

Table 111.

lvm_partition_t fields for lvm_partition_create()

Field name

start_lba size type raw_type volume_name

Desired start LBA

Desired size in blocks

LVM logical type

Partition physical type

Ignored

Input Output

Actual start LBA of partition

Actual size of partition in blocks

LVM logical type

Partition physical type

Associated logical volume name for primary and logical partitions

See also:

lvm_partition_create, lvm_partition_delete

7702033 Rev 27 333/515

OSPlus logical volume manager UM1150

lvm_partition_delete

Delete a partition

Definition:

int lvm_partition_delete (

const char *device_name,

lvm_partition_t *partition)

Arguments:

device_name partition

The device that contains the partition to delete.

The details of the partition to delete.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

This call deletes the partition specified on the given device. If an extended partition is deleted, all logical partitions within the extended partition are also deleted.

The logical volumes associated with any deleted partitions are also removed.

lvm_partition_create

, lvm_partition_delete_all

334/515 7702033 Rev 27

UM1150 OSPlus logical volume manager

lvm_partition_delete_all

Delete all partitions from a raw device

Definition:

Arguments:

int lvm_partition_delete_all (const char *device_name) device_name

The device that contains the partitions to delete.

Returns:

Description:

Returns 0 for success, -1 for failure.

This call deletes all partitions from a raw device. The logical volumes associated with any deleted partitions are also removed. This call must be used with care.

7702033 Rev 27 335/515

OSPlus logical volume manager UM1150

lvm_partition_info

Return partition details for the specified logical volume

Definition:

int lvm_partition_info (

const char *volume_name,

lvm_partition_t *partition)

Arguments:

volume_name partition

The name of the logical volume for which to return the partition information.

The partition information structure to be filled in.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

This function fills in the details of the partition structure for the specified logical volume. The lvm_partition_t structure is a collection of partition information for the disk, see

Section 7.2.5: Partition types on page 239

.

lvm_partitions

336/515 7702033 Rev 27

UM1150 OSPlus logical volume manager

lvm_partitions

Return a list of all the partitions on the device

Definition:

Arguments:

lvm_partitions_t *lvm_partitions (const char *device_name) device_name

The name of the device for which to return the partitions.

Returns:

Description:

Returns a collection of partition information for success, or NULL for failure.

This call returns a list of all the partitions on the device. The caller is responsible for freeing the memory returned.

The lvm_partitions_t structure returned is a collection of partition information for the disk and has the following format: typedef struct

{

} lvm_partitions_t;

These fields are described in

Table 112

.

Table 112.

lvm_partitions_t fields

Field name

length partitions

Description

Number of elements in partitions

An array of partitions (one or more)

7702033 Rev 27 337/515

OSPlus logical volume manager UM1150

lvm_volume_create

Create a logical volume

Definition:

int lvm_volume_create (

const char *device_name,

lvm_partition_t *partition)

Arguments:

device_name partition

The device on which to create the logical volume.

The details of the volume.

Returns:

Description:

Returns 0 for success, -1 for failure.

This call creates a partition on the device and mounts it as a logical volume. It finds room on the device for a partition of the specified size and creates it, mounting the result as a logical volume. It returns details of the partition in the partition structure. If possible, the partition is created as a logical partition; if it is not possible, it is created as a primary partition. This call assumes default MS-DOS disk geometry

(63 sectors per track and 255 heads per cylinder). The resulting partition is aligned to this geometry.

Table 113

describes the lvm_partition_t fields at both the input and output stage.

Table 113.

lvm_partition_t fields for lvm_volume_create()

Field name

start_lba size type raw_type volume_name

Ignored

Desired size in block

Ignored

Partition physical type

Ignored

Input Output

Start LBA for partition

Size of partition in blocks

LVM logical type

Partition physical type

Associated logical volume name for primary and logical partitions

See also:

lvm_volume_create_adv, lvm_volume_delete

338/515 7702033 Rev 27

UM1150 OSPlus logical volume manager

lvm_volume_create_adv

Create a logical volume

Definition:

int lvm_volume_create_adv (

const char *device_name,

lvm_partition_t *partition,

size_t sectors_per_track,

size_t heads_per_cylinder)

Arguments:

device_name partition

The device on which to create the logical volume.

The details of the volume.

sectors_per_track

The number of sectors per track heads_per_cylinder

The number of heads per cylinder

Returns:

Description:

Returns 0 for success, -1 for failure.

This call creates a partition on the device and mounts it as a logical volume. It finds room on the device for a partition of the specified size and creates it, mounting the result as a logical volume. It returns details of the partition in the partition structure. If possible, the partition is created as a logical partition, but if this is not possible, it is created as a primary partition instead. This call allows the disk geometry to be specified, so the alignment of the resulting partition can be specified. For instance, setting sectors_per_track to 2048, and heads_per_cylinder to 1 aligns the partition on a one megabyte boundary.

Table 114

describes the lvm_partition_t fields at both the input and output stage.

Table 114.

lvm_partition_t fields for lvm_volume_create_adv()

Field name Input Output

start_lba size type raw_type volume_name

Ignored

Desired size in block

Ignored

Partition physical type

Ignored

Start LBA for partition

Size of partition in blocks

LVM logical type

Partition physical type

Associated logical volume name for primary and logical partitions

See also:

lvm_volume_create, lvm_volume_delete

7702033 Rev 27 339/515

OSPlus logical volume manager UM1150

lvm_volume_delete

Delete a logical volume

Definition:

Arguments:

int lvm_volume_delete (const char *volume_name) volume_name

The name of the volume to delete.

Returns:

Description:

See also:

Returns 0 for success, -1 for failure.

This call unmounts the logical volume specified and deletes the partition on the device. lvm_volume_create

340/515 7702033 Rev 27

UM1150 OSPlus logical volume manager

lvm_volumes

Return the names of all logical volumes mounted on a mass storage device

Definition:

Arguments:

lvm_volumes_t *lvm_volumes (const char *device_name) device_name

The name of the mass storage device.

Returns:

Description:

Returns a list of all logical volumes on the named device for success, or NULL for failure.

This call returns a list of all the logical volumes on the named device. The caller is responsible for freeing the memory returned.

The lvm_volumes_t structure returned is a collection of volume names on the device and has the following format: typedef struct

{ int length;

.

} lvm_volumes_t;

These fields are described in

Table 115

.

Table 115.

lvm_volumes_t fields

Field name

length volumes

Description

Number of elements in volumes

Array of volume names

7702033 Rev 27 341/515

OSPlus serial driver

9 OSPlus serial driver

9.1

UM1150

Serial driver overview

The OSPlus serial driver provides an interface to conveniently configure, read from and write to serial communication type interfaces. The serial driver is structured in a modular fashion as a generic API layer with hardware abstraction modules to the underlying serial interface types. This allows future interface types to be supported easily using an additional hardware abstraction module.

9.2

9.3

9.4

9.5

Serial driver support interface types

The serial driver supports the two most common serial interfaces. These are asynchronous serial controller (ASC also referred to as the UART interface) and serial communication interface with FIFO (SCIF).

When the serial driver is used, the underlying type of serial interface is completely transparent to the user. The most common configurations are supported by both types of interface, but some of the more esoteric configurations (such as 9-bit data) are not.

Therefore, it is recommended that, where the underlying serial interface type is not known, only the more common configurations are used for maximum portability.

Serial driver configuration

The serial driver does not currently support any user configuration options.

Serial driver initialization

The serial driver is initialized by calling the function serial_initialize()

. On initialization, the driver allocates and initializes its internal state, then queries the registry to determine how many serial interfaces the current platform supports. Each serial interface is then, in turn, initialized using settings read from the registry before it is registered with the device library with the prefix serial

, and post fixed with the serial interface instance number. So the first serial interface is registered as serial0

, the second serial1

, and so on. If an error occurs during initialization, serial_initialize()

returns

-1

and sets errno

.

The serial driver usage model

As the serial driver is written to conform to the OSPlus device model, when the serial driver is initialized and all serial interfaces are registered with the device library, a serial interface can then be accessed using the standard device library open, close, read, write and ioctl functions. See

Chapter 4: OSPlus device model on page 134

for more details on using the

device library.

The serial driver presents each serial interface as a character device, so there is no support for performing block-orientated input or output.

342/515 7702033 Rev 27

UM1150

Note:

OSPlus serial driver

When opening a serial interface with device_open(), the serial driver honors the open flags passed in. This means if the serial interface is opened for read only, it is not possible to open the interface again to write.

On the first open call to a serial interface, the interface is configured to 9600 baud with 8-bit data, one stop bit and no parity by default. Exclusive access is required to the serial interface to change the configuration using the

OSPLUS_IOCTL_SERIAL_SET_CONFIG

ioctl.

Therefore any reads or writes currently in progress must first complete. Exclusive access to the serial interface is obtained by using read and write locks. Each lock has a timeout associated with it, which by default is

TIMEOUT_INFINITY

. The timeout can be changed for each lock using either the

OSPLUS_IOCTL_SET_RD_TIMEOUT

or the

OSPLUS_IOCTL_SET_WR_TIMEOUT

ioctls. If one of the locks cannot be obtained within its specified timeout, the configure fails and an error returned through errno

.

The read and write locks are also used to provide a blocking or non-blocking mode of operation. When the read and write timeouts are set to

TIMEOUT_IMMEDIATE

the serial driver implements a non-blocking mode of operation; therefore on the next read or write, the serial driver attempts to take the appropriate lock. If the lock cannot be obtained immediately, the read or write is not performed and

0

is returned as the number of bytes read or written. If the lock is successfully taken, then as much data as possible is read from or written to the serial interface buffers. The read or write then completes, the lock is released and the number of bytes read or written is returned.

When the read and write timeouts are set to

TIMEOUT_INFINITY

or a specific timeout, for example, ten seconds, then a blocking mode of operation is used. Therefore on a read or write, the serial driver waits for as long as it takes (or until the timeout expires) to obtain the read or write lock. When the lock has been obtained, as much data as possible is read or written to the serial interface buffers. The serial driver then waits as long as required (or until the timeout expires) to read more data from or write more data to the serial interface buffer.

This continues until the specified number of bytes have been read from or written to the serial interface buffer, the lock is released and the total number of bytes read or written is returned. If at any point the timeout expires, the number of bytes read or written, up to the timeout point, are returned.

A write is considered complete when the specified data has been written to the serial interface buffer. To ensure the data has been transmitted by the serial interface, the

OSPLUS_IOCTL_FLUSH

ioctl can be used; this blocks until all data has been transmitted.

9.6 Serial driver header file: serial.h

All the definitions relating to the serial driver are in the file serial.h

.

Table 116.

Defines in serial.h

Define

SERIAL_DEFAULT_CONFIG

Description

Default serial interface configuration - 9600 baud, 8-bit data, one stop bit and no parity

Table 117.

Types defined in serial.h

Type

serial_error_t

Description

Structure holding various error statistics

7702033 Rev 27 343/515

OSPlus serial driver

Table 118.

Functions defined in serial.h

Function

serial_initialize()

Description

Initialize the serial driver

UM1150

9.7

9.7.1

Serial driver ioctls

These ioctls relate to the device_ioctl()

call; see

device_ioctl on page 192

for more

details. The ioctl definitions are given in

Section 4.10: Device driver ioctl definitions on page 146

.

Serial driver common ioctls

The serial driver supports a subset of the common ioctls as defined in the include file ioctls/common.h

and described in

Section 4.6: Device library header file: ioctls/common.h on page 140

. This subset is shown in

Table 119

.

Table 119.

Serial driver supported common ioctls

Ioctl

OSPLUS_IOCTL_ABORT_RD

OSPLUS_IOCTL_ABORT_WR

OSPLUS_IOCTL_CLR_ERRORS

OSPLUS_IOCTL_FLUSH

OSPLUS_IOCTL_GET_ERRORS

OSPLUS_IOCTL_GET_RD_TIMEOUT

OSPLUS_IOCTL_GET_WR_TIMEOUT

OSPLUS_IOCTL_PURGE

OSPLUS_IOCTL_SET_RD_TIMEOUT

OSPLUS_IOCTL_SET_WR_TIMEOUT

Description

Abort the current read operation

Abort the current write operation

Clear the serial error information

Flush a serial buffer (only flushing the write buffer is supported by the serial driver)

Return the serial error information

Get the timeout used for serial reads

Get the timeout used for serial writes

Purge a serial buffer

Set the timeout to be used for serial reads

Set the timeout to be used for serial writes

For a full description of how to use the common ioctls with the device_ioctl()

function see

Section 4.10.1: Device driver common ioctl definitions on page 146

.

The serial driver implementation of

OSPLUS_IOCTL_GET_ERRORS uses the following error statistics parameter: typedef struct

{

unsigned int overrun;

unsigned int parity;

unsigned int rx;

unsigned int framing;

unsigned int brk;

} serial_error_t;

344/515 7702033 Rev 27

UM1150

9.7.2

OSPlus serial driver

Table 120.

serial_error_t fields

Field name

overrun parity rx framing brk

Description

Number of overrun errors detected

Number of parity errors detected

Number of receive errors detected

Number of frame errors detected

Number of break errors detected

Serial driver serial ioctls

The serial driver supports all of the common device driver ioctls defined in the include file ioctls/serial.h

.

The defines associated with these ioctls are listed in

Table 121

and the ioctls are listed in

Table 122

.

Table 121.

Defines in ioctls/serial.h

Define

SERIAL_BAUD_300

SERIAL_BAUD_600

SERIAL_BAUD_1200

SERIAL_BAUD_2400

SERIAL_BAUD_4800

SERIAL_BAUD_9600

SERIAL_BAUD_19200

SERIAL_BAUD_38400

SERIAL_BAUD_57600

SERIAL_BAUD_76800

SERIAL_BAUD_115200

SERIAL_BAUD_230400

SERIAL_BAUD_460800

SERIAL_DATA_5

SERIAL_DATA_6

SERIAL_DATA_7

SERIAL_DATA_8

SERIAL_DATA_9

SERIAL_MODE_FLOW_CNTRL

SERIAL_MODE_LOOPBACK

SERIAL_PARITY_EVEN

SERIAL_PARITY_MARK

Description

300 bit/s baud rate

600 bit/s baud rate

1200 bit/s baud rate

2400 bit/s baud rate

4800 bit/s baud rate

9600 bit/s baud rate

19200 bit/s baud rate

38400 bit/s baud rate

57600 bit/s baud rate

76800 bit/s baud rate

115200 bit/s baud rate

230400 bit/s baud rate

460800 bit/s baud rate

5 bits of data

6 bits of data

7 bits of data

8 bits of data

9 bits of data

Enable flow control

Loopback mode

Even parity checking

Mark parity checking

7702033 Rev 27 345/515

OSPlus serial driver UM1150

Table 121.

Defines in ioctls/serial.h (continued)

Define

SERIAL_PARITY_NONE

SERIAL_PARITY_ODD

SERIAL_PARITY_SPACE

SERIAL_STOP_0_5

SERIAL_STOP_1

SERIAL_STOP_1_5

SERIAL_STOP_2

Description

No parity checking

Odd parity checking

Space parity checking

1/2 stop bits

1 stop bit

1 1/2 stop bits

2 stop bits

Table 122.

Ioctls defined in ioctls/serial.h

Ioctl

OSPLUS_IOCTL_SERIAL_GET_BAUD

OSPLUS_IOCTL_SERIAL_GET_CONFIG

OSPLUS_IOCTL_SERIAL_GET_DATA

OSPLUS_IOCTL_SERIAL_GET_MODE

OSPLUS_IOCTL_SERIAL_GET_PARITY

OSPLUS_IOCTL_SERIAL_GET_STOP

OSPLUS_IOCTL_SERIAL_SET_BAUD

OSPLUS_IOCTL_SERIAL_SET_CONFIG

OSPLUS_IOCTL_SERIAL_SET_DATA

OSPLUS_IOCTL_SERIAL_SET_MODE

OSPLUS_IOCTL_SERIAL_SET_PARITY

OSPLUS_IOCTL_SERIAL_SET_STOP

Description

Get the serial port current baud rate

Get the serial port current configuration

Get the serial port current data bit size

Get the serial port current mode

Get the serial port current data parity

Get the serial port current stop bits

Set the serial port baud rate

Set the serial port configuration

Set the serial port data bit size

Set the serial port mode

Set the serial port data parity

Set the serial port stop bits

For a full description of how to use these serial ioctls with the device_ioctl()

function see

Section 9.8: Serial ioctl definitions on page 347

.

346/515 7702033 Rev 27

UM1150 OSPlus serial driver

9.8 Serial ioctl definitions

These serial device specific ioctl definitions relate to the device_ioctl()

call. See

device_ioctl on page 192

for more details.

OSPLUS_IOCTL_SERIAL_GET_BAUD

Return the serial interface current baud rate

Arguments:

Returns:

Description:

See also:

The address of an unsigned integer to store the serial interface current baud rate.

Returns

0

for success,

-1

for failure.

This ioctl returns the selected serial interface current baud rate as a bit mask in the unsigned integer whose address is passed in. The baud rate can be queried by

ANDing with the serial baud rate defines in

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_GET_CONFIG

,

OSPLUS_IOCTL_SERIAL_GET_DATA

,

OSPLUS_IOCTL_SERIAL_GET_STOP

,

OSPLUS_IOCTL_SERIAL_GET_PARITY

,

OSPLUS_IOCTL_SERIAL_GET_MODE

OSPLUS_IOCTL_SERIAL_GET_CONFIG

Return the serial interface current configuration

Arguments:

Returns:

Description:

See also:

The address of an unsigned integer to store the serial interface configuration bit mask.

Returns

0

for success,

-1

for failure.

This ioctl stores the current serial interface configuration as a bit mask in the addressed unsigned integer. The configuration consists of the selected serial interface parity, bits per character, number of stop bits, baud rate, loop-back control and flow control. These bits can be queried by ANDing a particular bit with a define from

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_GET_BAUD

,

OSPLUS_IOCTL_SERIAL_GET_DATA

,

OSPLUS_IOCTL_SERIAL_GET_STOP

,

OSPLUS_IOCTL_SERIAL_GET_PARITY

,

OSPLUS_IOCTL_SERIAL_GET_MODE

OSPLUS_IOCTL_SERIAL_GET_DATA

Return the serial interface current data bit size

Arguments:

Returns:

Description:

See also:

The address of an unsigned integer to store the serial interface current data bit size.

Returns

0

for success,

-1

for failure.

This ioctl returns the selected serial interface current data bit size as a bit mask in the unsigned integer whose address is passed in. The data bit size can be queried by

ANDing with the serial data bit size defines in

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_GET_CONFIG

,

OSPLUS_IOCTL_SERIAL_GET_BAUD

,

OSPLUS_IOCTL_SERIAL_GET_STOP

,

OSPLUS_IOCTL_SERIAL_GET_PARITY

,

OSPLUS_IOCTL_SERIAL_GET_MODE

7702033 Rev 27 347/515

OSPlus serial driver UM1150

OSPLUS_IOCTL_SERIAL_GET_MODE

Return the serial interface current mode

Arguments:

Returns:

Description:

See also:

The address of an unsigned integer to store the serial interface current mode.

Returns

0

for success,

-1

for failure.

This ioctl returns the selected serial interface current mode as a bit mask in the unsigned integer whose address is passed in. The mode can be queried by ANDing with the serial mode defines in

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_GET_CONFIG

,

OSPLUS_IOCTL_SERIAL_GET_BAUD

,

OSPLUS_IOCTL_SERIAL_GET_DATA

,

OSPLUS_IOCTL_SERIAL_GET_STOP

,

OSPLUS_IOCTL_SERIAL_GET_PARITY

OSPLUS_IOCTL_SERIAL_GET_PARITY

Return the serial interface current parity bits

Arguments:

Returns:

Description:

See also:

The address of an unsigned integer to store the serial interface current parity bits.

Returns

0

for success,

-1

for failure.

This ioctl returns the selected serial interface current parity bits as a bit mask in the unsigned integer whose address is passed in. The parity can be queried by ANDing with the serial parity defines in

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_GET_CONFIG

,

OSPLUS_IOCTL_SERIAL_GET_BAUD

,

OSPLUS_IOCTL_SERIAL_GET_DATA

,

OSPLUS_IOCTL_SERIAL_GET_STOP

,

OSPLUS_IOCTL_SERIAL_GET_MODE

OSPLUS_IOCTL_SERIAL_GET_STOP

Return the serial interface current number of stop bits

Arguments:

Returns:

Description:

See also:

The address of an unsigned integer to store the serial interface current number of stop bits.

Returns

0

for success,

-1

for failure.

This ioctl returns the selected serial interface current number of stop bits as a bit mask in the unsigned integer whose address is passed in. The data bit size can be

queried by ANDing with the serial stop bit defines in

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_GET_CONFIG

,

OSPLUS_IOCTL_SERIAL_GET_BAUD

,

OSPLUS_IOCTL_SERIAL_GET_DATA

,

OSPLUS_IOCTL_SERIAL_GET_PARITY

,

OSPLUS_IOCTL_SERIAL_GET_MODE

348/515 7702033 Rev 27

UM1150 OSPlus serial driver

OSPLUS_IOCTL_SERIAL_SET_BAUD

Configure the serial interface baud rate

Arguments:

Returns:

Description:

See also:

An unsigned integer bit mask containing the desired baud rate with which to configure the serial interface.

Returns

0

for success,

-1

for failure.

This ioctl configures the selected serial interface baud rate. No other serial interface settings are modified. The parameter is an unsigned integer bit mask containing a

baud rate value taken from

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_SET_CONFIG

,

OSPLUS_IOCTL_SERIAL_SET_DATA

,

OSPLUS_IOCTL_SERIAL_SET_STOP

,

OSPLUS_IOCTL_SERIAL_SET_PARITY

,

OSPLUS_IOCTL_SERIAL_SET_MODE

OSPLUS_IOCTL_SERIAL_SET_CONFIG

Configure the serial interface

Arguments:

Returns:

Description:

See also:

An unsigned integer bit mask of serial interface configuration options.

Returns

0

for success,

-1

for failure.

This ioctl configures the selected serial interface parity, bits per character, number of stop bits, baud rate, loop-back control and flow control.

The configuration options are specified by OR’ing together a collection of the defines given in

Table 121: Defines in ioctls/serial.h on page 345

. A valid configuration consists of a parity bit, data bit, stop bit, baud bit and mode bit OR’ed together.

OSPLUS_IOCTL_SERIAL_SET_BAUD

,

OSPLUS_IOCTL_SERIAL_SET_DATA

,

OSPLUS_IOCTL_SERIAL_SET_STOP

,

OSPLUS_IOCTL_SERIAL_SET_PARITY

,

OSPLUS_IOCTL_SERIAL_SET_MODE

OSPLUS_IOCTL_SERIAL_SET_DATA

Configure the serial interface data bit size

Arguments:

Returns:

Description:

See also:

An unsigned integer bit mask containing the desired data bit size with which to configure the serial interface.

Returns

0

for success,

-1

for failure.

This ioctl configures the selected serial interface data bit size. No other serial interface settings are modified. The parameter is an unsigned integer bit mask containing a data bit size value taken from

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_SET_CONFIG

,

OSPLUS_IOCTL_SERIAL_SET_BAUD

,

OSPLUS_IOCTL_SERIAL_SET_STOP

,

OSPLUS_IOCTL_SERIAL_SET_PARITY

,

OSPLUS_IOCTL_SERIAL_SET_MODE

7702033 Rev 27 349/515

OSPlus serial driver UM1150

OSPLUS_IOCTL_SERIAL_SET_MODE

Configure the serial interface mode

Arguments:

Returns:

Description:

See also:

An unsigned integer bit mask containing the desired mode with which to configure the serial interface.

Returns

0

for success,

-1

for failure.

This ioctl configures the selected serial interface mode. No other serial interface settings are modified. The parameter is an unsigned integer bit mask containing a

mode value taken from

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_SET_CONFIG

,

OSPLUS_IOCTL_SERIAL_SET_BAUD

,

OSPLUS_IOCTL_SERIAL_SET_DATA

,

OSPLUS_IOCTL_SERIAL_SET_STOP

,

OSPLUS_IOCTL_SERIAL_SET_PARITY

OSPLUS_IOCTL_SERIAL_SET_PARITY

Configure the serial interface parity bits

Arguments:

Returns:

Description:

See also:

An unsigned integer bit mask containing the desired parity bits with which to configure the serial interface.

Returns

0

for success,

-1

for failure.

This ioctl configures the selected serial interface parity bits. No other serial interface settings are modified. The parameter is an unsigned integer bit mask containing a parity value taken from

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_SET_CONFIG

,

OSPLUS_IOCTL_SERIAL_SET_BAUD

,

OSPLUS_IOCTL_SERIAL_SET_DATA

,

OSPLUS_IOCTL_SERIAL_SET_STOP

,

OSPLUS_IOCTL_SERIAL_SET_MODE

OSPLUS_IOCTL_SERIAL_SET_STOP

Configure the serial interface number of stop bits

Arguments:

Returns:

Description:

See also:

An unsigned integer bit mask containing the desired number of stop bits with which to configure the serial interface.

Returns

0

for success,

-1

for failure.

This ioctl configures the selected serial interface number of stop bits. No other serial interface settings are modified. The parameter is an unsigned integer bit mask

containing a stop bit value taken from

Table 121: Defines in ioctls/serial.h on page 345

.

OSPLUS_IOCTL_SERIAL_SET_CONFIG

,

OSPLUS_IOCTL_SERIAL_SET_BAUD

,

OSPLUS_IOCTL_SERIAL_SET_DATA

,

OSPLUS_IOCTL_SERIAL_SET_PARITY

,

OSPLUS_IOCTL_SERIAL_SET_MODE

350/515 7702033 Rev 27

UM1150 OSPlus serial driver

9.9 Serial driver function definitions serial_initialize

Initialize the serial driver

Definition:

Arguments:

Returns:

Description:

int serial_initialize (void)

None.

Returns

0

for success,

-1

for failure.

This call initializes the serial driver. When initialized, the serial driver creates a new device instance and registers it with the device library for each serial interface that is supported on the platform.

7702033 Rev 27 351/515

OSPlus ethernet drivers

10 OSPlus ethernet drivers

UM1150

10.1 Ethernet drivers overview

●

●

●

The OSPlus ethernet drivers are currently LAN91, LAN9x1x, and STxMAC. Collectively, these drivers provide support for the following ethernet devices commonly found on

STMicroelectronics hardware:

SMSC LAN91C111

SMSC LAN9115/LAN9116/LAN9117/LAN9118/LAN9215/LAN9218

STMAC110/STGMAC

The ethernet drivers interface to a generic ethernet PHY driver to allow common PHY code to be decoupled from the main driver. The result of this is that board designers have greater freedom to use a wider selection of PHY devices without the problems associated with having to modify their software to work with each new PHY.

In addition to the on-board ethernet devices, OSPlus supports USB ethernet devices. Also an ethernet wrapper to the USB host-to-host class is provided. This wrapper is named h2heth and allows a USB host-to-host device to be treated as if it is an ethernet device, but only with limited functionality. USB ethernet and host-to-host devices are fully detailed in the

OSPlus USB User Manual (8018282).

The OSPlus ethernet drivers all adhere to the OSPlus driver model and are platform independent libraries built for the ST20, ST40 and ST200 CPUs. Support for a specific ethernet device on a specific platform consists of the platform having the ethernet interface either on-board (such as SMSC LAN91C111 on the STm8000-Demo board) or connected using a STEM interface (for example, SMSC LAN91C111 on the STi5528-M board) and the appropriate registry settings being available.

All OSPlus ethernet drivers are supported by the NexGen TCP/IP stack through a common interface driver named ngNetDrv_osplus_ethernet. For an example of how to use the

OSPlus ethernet drivers with the NexGen TCP/IP stack, see any of the OSPlus NexGen examples.

352/515

The OSPlus ethernet drivers each support several driver-specific configuration options.

These can be used to override any platform specific defaults, or allow the driver to function on a platform that does not yet have a specific set of registry settings.

All options for each ethernet driver are fully configurable allowing them to be tuned to suit a specific platform. For example, the LAN91 driver can be selectively configured with DMA supported on those platforms with a GPDMA. By default the GPDMA acceleration is not enabled as the overhead involved with setting up each transfer out-weighs the benefit when handling small packets.

The driver configuration options are read during the ethernet driver initialization. Therefore, any options specified after the ethernet driver has been called/initialized are not seen or used.

To specify an ethernet driver configuration option, a registry key must be written. The name of the registry key for a specific configuration option is given by configuration option defines,

7702033 Rev 27

UM1150 OSPlus ethernet drivers

found in each ethernet driver include file. The registry path at which the registry keys are written can also be found in the ethernet driver include file.

The following example shows a configuration option being to set to configure a user-defined

MAC address for the LAN91 driver. The configuration options for all ethernet drivers are set in a similar manner.

registry_key_set (

LAN91_CONFIG_PATH,

LAN91_CONFIG_MAC_ADDRESS,

(void *) macAddress);

Examples of how to create registry settings for each of the OSPlus ethernet drivers are shown in the OSPlus custom_registry example, in the OSPlus software installation package.

10.2.1 LAN91 driver registry options

●

●

●

The LAN91 configuration options are separated into logical groups each specified under its own registry path. The groups are: basic driver options device address functions advanced driver options

A summary of the LAN91 driver registry options are shown in

Table 138: Configuration option defines in LAN91.h on page 376

.

Basic driver options

The LAN91 driver basic options are stored in the registry at the node specified by

LAN91_CONFIG_PATH

. These options specify items such as the LAN91 base address and interrupt information.

Table 123.

Basic driver options defined in lan91.h

Define

LAN91_CONFIG_INIT_FN

LAN91_CONFIG_BASE

LAN91_CONFIG_INTR

LAN91_CONFIG_ALT_INTR

LAN91_CONFIG_INTR_LEVEL

LAN91_CONFIG_INTR_TRIGGER

Description

Specifies a pointer to a function to initialize the LAN91 controller hardware, including initializing any system registers, and performing any required interrupt routing. The function should have the following prototype: int lan91_config_init_fn (void *, void *);

On successful initialization of the LAN91 controller hardware this function returns 0 . Otherwise -1 is returned.

Both parameters should be NULL.

Specifies the base address at which the LAN91 controller is mapped into memory.

Specifies the interrupt that detects LAN91 controller interrupts. If this option is not set, the option

LAN91_CONFIG_ALT_INTR

must be specified

LAN91 controller alternative interrupt

These specify the interrupt level and trigger to program for the LAN91 controller interrupts on OS20 based systems.

For OS21 based systems these options should be set to

0

.

7702033 Rev 27 353/515

OSPlus ethernet drivers UM1150

Table 123.

Basic driver options defined in lan91.h (continued)

Define Description

LAN91_CONFIG_INTR_ENB_FN

LAN91_CONFIG_MAC_ADDRESS

LAN91_CONFIG_MAC_MTU

LAN91_CONFIG_MAC_PKT_FILTER

LAN91_CONFIG_MAC_LINK_CB

LAN91_CONFIG_PHY_NAME

LAN91_CONFIG_PHY_LINK

This specifies a pointer to a function that is called after the

LAN91 interrupt handler is installed but before it is enabled.

The function should have the following prototype: int lan91_config_intr_enb_fn (void);

On successful initialization of the LAN91 controller hardware this function returns 0 . Otherwise -1 is returned.

By default this option is NULL.

If specified this option contains a pointer to a 6-byte usersupplied MAC address. On initialization the LAN91 controller sets its MAC address to this MAC address. If this option is not specified the default address contained in the hardware is used.

This option defines the MTU size for the LAN91 driver. If not defined, the default 1518 bytes is used.

This option specifies the initial packet filtering settings to use when LAN91 is initialized using the defines from

Table 153: Ethernet packet filter type defines in ioctls/ethernet.h on page 383

. The default setting is

promiscuous mode.

Specifies an optional pointer to a function called with the current link settings each time they change. The function must have the prototype: int lan91_config_mac_link_cb

(ethernet_device_t *, unsigned int);

The first parameter should be a pointer to the ethernet_device_t and the second parameter is an unsigned integer that contains the current link settings comprised from

Table 159: Power management wake-on-

LAN settings defined in ioctls/ethernet.h on page 388

.

This function should return 0 .

This option specifies the name of the ethernet PHY device that manages the LAN91 PHY. If no name is specified, a default of /phy0 is used.

This option specifies the PHY driver link settings to use at startup. The link settings can be set to auto-negotiate or use a specific speed and duplex using the defines from

Table 159: Power management wake-on-LAN settings defined in ioctls/ethernet.h on page 388

. By default the link is set to auto-negotiate.

354/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

Device address function options

The LAN91 driver device address function options are stored in the registry at the node specified by LAN91_CONFIG_PATH_FUDGE. These functions are used to determine the correct address to access the SMSC LAN91C111 device at for 8-, 16- or 32-bit accesses.

Table 124.

Device address function options defined in lan91.h

Define Description

LAN91_CONFIG__8BIT_FN

LAN91_CONFIG_16BIT_FN

LAN91_CONFIG_32BIT_FN

Specifies a pointer to a function that takes the index of the

LAN91 controller register to access as an 8-bit register, and returns the address at which the register can be accessed.

The function should have the following prototype: unsigned int lan91_config_8bit_fn (unsigned int);

Specifies a pointer to a function that takes the index of the

LAN91 controller register to access as an 16-bit register, and returns the address at which the register can be accessed. The function should have the following prototype: unsigned int lan91_config_16bit_fn (unsigned int);

Specifies a pointer to a function that takes the index of the

LAN91 controller register to access as an 32-bit register, and returns the address at which the register can be accessed. The function should have the following prototype: unsigned int lan91_config_32bit_fn (unsigned int);

7702033 Rev 27 355/515

OSPlus ethernet drivers UM1150

Advanced driver options

The LAN91 driver advanced options are stored in the registry at the node specified by

LAN91_CONFIG_PATH_FLAGS

. These options are used to control the use of DMA acceleration using a GPDMA and various driver options such as auto-releasing packets after transmission and entering power saving mode.

Table 125.

Advanced driver options defined in lan91.h

Define Description

LAN91_CONFIG_32BIT

LAN91_CONFIG_AUTO_REL

LAN91_CONFIG_POWER_SAVE

LAN91_CONFIG_TX_ERR_REL

LAN91_CONFIG_USE_DMA

Specifies if data can be written to the LAN91 controller in

32-bit quantities (value 1 ) or not (value 0 ). This option is platform specific.

Specifies if transmitted packets should auto-release after they are sent (value

1

) or not (value

0

). By default autorelease is enabled.

Specifies if the LAN91 controller should attempt to use a power saving mode (value 1 ) or not (value 0 ). By default power saving is off

Specifies if the LAN91 controller should release a transmitted packet on error (value

1

) or attempt to resend the packet (value 0 ). Default is on ( 1 ).

Specifies if the LAN91 controller should enable DMA speedup if available (value 1 ) or not (value 0 ). Default is off

( 0 ).

10.2.2 LAN9x1x driver registry options

A summary of the LAN9x1x driver registry options are shown in

Table 140: Configuration option defines in lan9x1x.h on page 377

.

The LAN9x1x driver options are stored in the registry at the node specified by

LAN9X1X_CONFIG_PATH

. The LAN9x1x driver supports multiple controllers using the registry key LAN9X1X_CONFIG_HOST_COUNT. This key contains an integer that specifies how many controllers there are settings for. The settings for each controller are stored in a sub-node with the name consisting of an integer starting from 0. For example, the settings for controller 0 are stored at registry path LAN9X1X_CONFIG_PATH"/0" and for controller 1 at LAN9X1X_CONFIG_PATH"/1".

356/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

Basic driver options

These options specify such things as the LAN9x1x base address and interrupt information.

Table 126.

Basic driver options defined in lan9x1x.h

Define Description

LAN9X1X_CONFIG_INIT_FN

LAN9X1X_CONFIG_BASE

LAN9X1X_CONFIG_INTR

LAN9X1X_CONFIG_ALT_INTR

LAN9X1X_CONFIG_INTR_LEVEL

LAN9X1X_CONFIG_INTR_TRIGGER

LAN9X1X_CONFIG_INTR_ENB_FN

LAN9X1X_CONFIG_INTR_MODE

LAN9X1X_CONFIG_RX_OFFSET

Specifies a pointer to a function that when called initializes the LAN9x1x controller hardware, including initializing any system registers, and performing any required interrupt routing. The function should have the following prototype: int lan9x1x_config_init_fn (void *, void *);

On successful initialization of the LAN9x1x controller hardware this function returns

0

. Otherwise

-1

is returned.

Both parameters should be NULL .

Specifies the base address at which the LAN9x1x controller is mapped into memory.

Specifies the interrupt that detects LAN9x1x controller interrupts. If this option is not set, the option

LAN9X1X_CONFIG_ALT_INTR

must be specified

LAN9x1x controller alternative interrupt

These specify the interrupt level and trigger to program for the LAN9x1x controller interrupts on OS20 based systems.

For OS21 based systems these options should be set to

0

.

This specifies a pointer to a function that is called after the

LAN9x1x interrupt handler is installed but before it is enabled. The function should have the following prototype: int lan9x1x_config_intr_enb_fn (void);

On successful initialization of the LAN9x1x controller hardware this function returns 0 . Otherwise -1 is returned.

By default this option is NULL .

Specifies the LAN9x1x controller’s interrupt mode. By default this is LAN9X1X_INTR_MODE_OPEN_DRAIN, but can be changed to LAN9X1X_INTR_MODE_PUSH_PULL to allow the interrupt polarity to be configured as active high.

LAN9X1X_CONFIG_INTR_POLARITY

Specifies the LAN9x1x controller’s interrupt polarity. By default this is LAN9X1X_INTR_POLARITY_ACTIVE_LOW, but can be changed to

LAN9X1X_INTR_POLARITY_ACTIVE_HIGH

when pushpull mode is set.

When reading packets, the LAN9x1x driver must know in advance the alignment of the buffers passed into it. This option specifies an integer corresponding to the buffer alignment (in bytes) when reading packets. By default the

LAN9x1x driver expects only 32-bit buffers to be passed in and has a RX offset of

0

. NexGen only ever passes 16-bit aligned buffers to the LAN9x1x driver. Therefore the RX offset should be set to 2 . There are no restrictions on the alignment of buffers when sending packets.

7702033 Rev 27 357/515

OSPlus ethernet drivers UM1150

Table 126.

Basic driver options defined in lan9x1x.h (continued)

Define Description

LAN9X1X_CONFIG_RX_END_ALIGN

LAN9X1X_CONFIG_RX_READ_FN

LAN9X1X_CONFIG_TX_WRITE_FN

LAN9X1X_CONFIG_TX_FIFO_SZ

When reading packets, the LAN9x1x driver must know in advance the end alignment of the buffers passed into it. This option specifies an integer corresponding to the buffer end alignment (in bytes) when reading packets. By default the

LAN9x1x driver has a RX end align of

0

. This may be changed to LAN9X1X_RX_END_ALIGN_4_BYTE,

LAN9X1X_RX_END_ALIGN_16_BYTE

, or

LAN9X1X_RX_END_ALIGN_32_BYTE

.

Optionally specifies a pointer to a function to be used to read data from the LAN9x1x controller. This allows the default code to be replaced with DMA accelerated code.

The function must have the following prototype: int lan9x1x_config_rx_read_fn (unsigned int, unsigned int *, int);

The first parameter contains the address at which to read data from. The second parameter is a pointer to a 32-bit aligned buffer to read the data into. The third parameter is the number of 32-bit quantities to read.

On success the function returns 0 , otherwise -1 on error.

Optionally specifies a pointer to a function to be used to write data to the LAN9x1x controller. This allows the default code to be replaced with DMA accelerated code. The function must have the following prototype: int lan9x1x_config_tx_write_fn (unsigned int, unsigned int *, int);

The first parameter contains the address at which to write data to. The second parameter is a pointer to a 32-bit aligned buffer to read the data from. The third parameter is the number of 32-bit quantities to write.

On success the function returns 0 , otherwise -1 on error.

Specifies an integer which corresponds to the size of TX

FIFO buffer in 1 Kbyte chunks. The default is 5 for 5 Kbytes but this option can be set to any value between

2

and

14

.

MAC settings

These options specify the LAN9x1x MAC address and Maximum Transmissible Unit (MTU).

Table 127.

MAC options defined in lan9x1x.h

Define

LAN9X1X_CONFIG_MAC_ADDRESS

LAN9X1X_CONFIG_MAC_MTU

Description

This option contains a pointer to a 6-byte user-supplied

MAC address. During hardware initialization, the LAN9x1x controller MAC address is set to this value. If this option is not specified the default address contained in the hardware is used.

This option defines the MTU size for the LAN9x1x driver. If not defined, the default 1518 bytes is used.

358/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

Table 127.

MAC options defined in lan9x1x.h

Define

LAN9X1X_CONFIG_MAC_PKT_

FILTER

LAN9X1X_CONFIG_MAC_LINK_CB

Description

This option specifies the initial packet filtering settings to use when LAN9x1x is initialized using the defines from

Table 153: Ethernet packet filter type defines in ioctls/ethernet.h on page 383

. The default setting is

promiscuous mode.

Specifies an optional pointer to a function called with the current link settings each time they change. The function must have the prototype: int lan9x1x_config_mac_link_cb

(ethernet_device_t *, unsigned int);

The first parameter should be a pointer to the ethernet_device_t and the second parameter is an unsigned integer that contains the current link settings comprised from

Table 159: Power management wake-on-

LAN settings defined in ioctls/ethernet.h on page 388

.

This function should return 0 .

PHY settings

These options specify options related to the LAN9x1x PHY.

Table 128.

PHY options defined in lan9x1x.h

Define

LAN9X1X_CONFIG_PHY_NAME

LAN9X1X_CONFIG_PHY_LINK

LAN9X1X_CONFIG_PHY_EXTERNAL

Description

This option specifies the name of the ethernet PHY device that manages the LAN9x1x PHY. If no name is specified, a default of /phy0 is used.

This option specifies the link settings to use at startup. The link settings can be set to auto-negotiate or use a specific speed and duplex using the defines from

Table 159: Power management wake-on-LAN settings defined in ioctls/ethernet.h on page 388

. By default the link is set to

auto-negotiate.

Specifies whether the LAN9x1x should use an external PHY instead of the internal one. By default the internal PHY is selected.

A summary of the STxMAC driver registry options are shown in

Table 142: Configuration option defines in stxmac.h on page 378

.

The STxMAC driver options for STMAC/STMAC110 devices are stored in the registry at the node specified by STMAC_CONFIG_PATH and the STxMAC driver options for STGMAC devices are stored in the registry at the node specified by STGMAC_CONFIG_PATH. The

STxMAC driver supports multiple controllers using the registry key

STXMAC_CONFIG_HOST_COUNT

. This key contains an integer that specifies the number of controllers for which there are settings. The settings for each controller are stored in a subnode with the name consisting of an integer starting from 0. For example, the settings for

STMAC controller 0 are stored at registry path STMAC_CONFIG_PATH"/0" and for

7702033 Rev 27 359/515

OSPlus ethernet drivers UM1150

controller 1 at STMAC_CONFIG_PATH"/1". Similarly, the settings for STGMAC controller 0 are stored at registry path STGMAC_CONFIG_PATH"/0" and for controller 1 at

STGMAC_CONFIG_PATH"/1"

.

Basic driver options

Table 129

lists the basic hardware initialization options.

Table 129.

Basic options defined in stxmac.h

Define

STXMAC_CONFIG_INIT_FN

STXMAC_CONFIG_INIT_ARG

STXMAC_CONFIG_BASE

Description

Specifies a pointer to a function to initialize the STxMAC controller hardware, including initializing any system registers, and performing any required interrupt routing. The function should have the following prototype: int stxmac_config_init_fn (void *, void *);

The first parameter points to the STxMAC device structure, and is currently unused. The second parameter is used to specify an argument that determines the mode that the

STxMAC PHY should operate in. See

STXMAC_CONFIG_INIT_ARG

for details.

On successful initialization of the STxMAC controller hardware this function returns 0 . Otherwise, -1 is returned.

Specifies the mode in which the PHY should operate. Not all platforms support all modes. The modes are:

0 : The PHY should operate in MII mode.

1 : The PHY should operate in RMII mode using an internal clock.

2: The PHY should operate in RMII mode using an external clock.

Specifies the base address at which the STxMAC controller is mapped into memory.

360/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

DMA settings

These options specify details about the STxMAC DMA controller that is used to transfer packets to or from the STxMAC.

Table 130.

DMA options defined in stxmac.h

Define Description

STXMAC_CONFIG_DMA_INTR

STXMAC_CONFIG_DMA_ALT_INTR

Specifies the interrupt for the STxMAC DMA controller. If this option is not set, the option

STXMAC_CONFIG_ALT_INTR

must be specified

STxMAC DMA controller alternative interrupt

STXMAC_CONFIG_DMA_INTR_LEVEL

STXMAC_CONFIG_DMA_INTR_

TRIGGER

For OS20 based systems, these specify the interrupt level and trigger to program for the STxMAC DMA controller interrupt. For OS21 based systems, set these options to 0 .

STXMAC_CONFIG_DMA_INTR_ENB_

FN

This specifies a pointer to a function that is called after the

STxMAC interrupt handler is installed but before it is enabled. The function should have the following prototype: int stxmac_config_intr_enb_fn (void);

On successful initialization of the STxMAC controller hardware this function returns

0

. Otherwise

-1

is returned.

By default this option is NULL .

STXMAC_CONFIG_DMA_BURST_LEN_

FN

Specifies a pointer to a function that is called to determine the correct DMA burst length required for the current chip/platform revision. The function should have the following prototype: int stxmac_config_dma_burst_len_fn (void *, void *);

The first parameter should point to the STxMAC device structure, but is currently unused. The second parameter should point to an unsigned integer that is set to the correct

DMA burst length value.

If the DMA burst length is determined the function returns

0

.

Otherwise -1 is returned.

STXMAC_CONFIG_DMA_RX_DESC

STXMAC_CONFIG_DMA_TX_DESC

Specifies the number of packet receive descriptors the

STxMAC DMA should use. By default, there are 8.

Increasing this value may result in better ethernet receive performance in asynchronous mode at the expense of memory. The minimum number of receive descriptors is 2, and the maximum is 1024.

Specifies the number of packet transmit descriptors the

STxMAC DMA should use. By default, there are 8.

Increasing this value may result in better ethernet transmit performance in asynchronous mode at the expense of memory. The minimum number of transmit descriptors is 2 and the maximum is 1024.

7702033 Rev 27 361/515

OSPlus ethernet drivers UM1150

MAC settings

These options specify the STxMAC MAC address and Maximum Transmissible Unit.

Table 131.

MAC options defined in stxmac.h

Define Description

STXMAC_CONFIG_MAC_ADDRESS

This option contains a pointer to a 6-byte user supplied

MAC address. During initialization, the STxMAC controller sets its MAC address to this MAC address. If this option is not specified, the default address contained in the hardware is used.

STXMAC_CONFIG_MAC_MTU

STXMAC_CONFIG_MAC_PKT_FILTER

This option defines the Maximum Transmissible Unit (MTU) size for the STxMAC driver. If not defined the default value of 1518 bytes is used. The MTU must not be larger than

1518 bytes.

This option specifies the initial packet filtering settings to use when STxMAC is initialized using the defines from

Table 153: Ethernet packet filter type defines in ioctls/ethernet.h on page 383

. The default setting is

promiscuous mode.

STXMAC_CONFIG_MAC_LINK_CB

Specifies an optional pointer to a function called with the current link settings each time they change. The function must have the prototype: int stxmac_config_mac_link_cb

(ethernet_device_t *, unsigned int);

The first parameter should be a pointer to the ethernet_device_t

and the second parameter is an unsigned integer that contains the current link settings comprised from

Table 159: Power management wake-on-

LAN settings defined in ioctls/ethernet.h on page 388

.

This function should return

0

.

362/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

MMC settings

These options specify the STxMAC MMC configuration.

Table 132.

MMC options defined in stxmac.h

Define Description

STXMAC_CONFIG_MMC_FREEZE

STXMAC_CONFIG_MMC_ROLLOVER

STXMAC_CONFIG_MMC_RST_ON_RD

STXMAC_CONFIG_MMC_COUNTER_CB

This option specifies if the MMC counters should be frozen, that is, they are not updated. The default is the MMC counters are not frozen. This option is only supported for

STGMAC devices.

This option specifies if the MMC counters should rollover when the maximum is reached. The default is to not rollover.

This option specifies if the MMC counters should be reset after each read. The default is to not reset on read.

Specifies an optional pointer to an ethernet_callback_t

structure containing a callback to be executed each time one of the MMC counters reaches half maximum value.

PHY settings

These options specify options related to the STxMAC PHY.

Table 133.

PHY options defined in stxmac.h

Define

STXMAC_CONFIG_PHY_DISABLE

STXMAC_CONFIG_PHY_NAME

STXMAC_CONFIG_PHY_LINK

Description

Specifies if the STxMAC should disable all PHY operations.

It is unusual for the STxMAC to not be connected to a PHY so usually this option is set to 0 by default.

This option specifies the name of the ethernet PHY device that manages the STxMAC PHY. If no name is specified, a default of /phy0 is used.

This option specifies the link settings to use at startup. The link settings can be set to auto-negotiate or use a specific speed and duplex using the defines from

Table 159: Power management wake-on-LAN settings defined in ioctls/ethernet.h on page 388

. By default the link is set to

auto-negotiate.

7702033 Rev 27 363/515

OSPlus ethernet drivers UM1150

Power management options

These options specify options related to STxMAC power management activities.

Table 134.

Power management options defined in stxmac.h

Define Description

STXMAC_CONFIG_PMT_DISABLE

STXMAC_CONFIG_PMT_CB_ORDER

This per device key controls whether or not an instance of the driver participates in the OS21 power management transitions. If the key is not present, or if it is set to 0, the driver participates. If set to 1, it does not.

This driver level configuration option specifies the position in in the OS21 power management chain where the driver registers its power management callback. If not specified, the driver uses a default value of

OS21_POWER_CALLBACK_ORDER_LAST-1

.

The OSPlus h2heth driver does not support any user configurable options.

364/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

10.3 Generic PHY driver configuration

The OSPlus ethernet generic PHY driver supports several driver-specific configuration options. These can be used to override any platform specific defaults, or allow the driver to function on a platform that does not yet have a specific set of registry settings.

All options for the generic PHY driver are fully configurable allowing them to be tuned to suit a specific platform or application.

The driver configuration options are read during the ethernet driver initialization. Therefore, any options specified after the ethernet driver has been called or initialized are not seen or used.

As with all the ethernet drivers, a registry key must be written to specify a PHY driver option.

The name of the registry key for a specific configuration option is given by configuration option defines, found in the PHY driver include file. The registry path at which the registry keys are written can also be found in the PHY driver include file.

A summary of the PHY driver registry options are shown in

Table 145: Configuration option defines in phy.h on page 379

.

The generic PHY driver options are stored in the registry at the node specified by

PHY_CONFIG_PATH.

The generic PHY driver supports multiple PHY devices using the registry key PHY_CONFIG_COUNT. This key contains an integer that specifies the number of

PHY devices for which there are settings. The settings for each device are stored in a subnode with the name consisting of an integer starting from 0. For example, the settings for

PHY device 0 are stored at registry path PHY_CONFIG_PATH"/0" and for device 1 at

PHY_CONFIG_PATH"/1"

.

PHY basic driver options

Table 135

lists the basic driver initialization options.

Table 135.

PHY basic options defined in phy.h

Define

PHY_CONFIG_INIT_FN

PHY_CONFIG_INIT_ARG

PHY_CONFIG_ADDRESS

Description

Specifies a pointer to a function to initialize the PHY device hardware, including performing PIO setup. The function must have the following prototype: int phy_config_init_fn (void *, void *);

The first parameter points to the PHY device structure, and is currently unused. The second parameter specifies an argument that determines the mode in which the PHY should operate. See PHY_CONFIG_INIT_ARG for details.

On successful initialization of the PHY hardware this function returns

0

. Otherwise,

-1

is returned.

Specifies the mode in which the PHY should operate. Not all platforms support all modes. See

Table 146: Configuration argument defines in phy.h on page 380

for supported

values.

Specifies the address at which the PHY device can be found and ranges from 0 to 31.

7702033 Rev 27 365/515

OSPlus ethernet drivers UM1150

PHY link settings

The options listed in

Table 136

specify details about the PHY device link settings.

Table 136.

PHY link options defined in phy.h

Define

PHY_CONFIG_LINK

PHY_CONFIG_LINK_TIMEOUT

PHY_CONFIG_LINK_TASK_PRI

PHY_CONFIG_LINK_TASK_DELAY

PHY_CONFIG_ANEG_10MBPS

PHY_CONFIG_ANEG_100MBPS

PHY_CONFIG_ANEG_1000MBPS

Description

Specifies the initial link settings that the PHY is to be configured with.

Specifies the timeout for auto-negotiation to complete. The default is 15 seconds. Valid values are in a range from 1 to

60 seconds.

Specifies the priority at which the link status check task should run. Default is MAX_USER_PRIORITY..

This specifies how frequently the link status check task should execute. The default is 2 seconds. Valid values are in a range from 1 to 60 seconds.

Specifies if auto-negotiation should advertise 10 Mbps (if supported) speed. Default is 1 to advertise, set to 0 to not advertise.

Specifies if auto-negotiation should advertise 100 Mbps (if supported) speed. Default is 1 to advertise, set to 0 to not advertise.

Specifies if auto-negotiation should advertise 1000 Mbps (if supported) speed. Default is 1 to advertise, set to 0 to not advertise.

PHY ops settings

These options specify any custom PHY device operations to use.

Table 137.

PHY ops options defined in phy.h

Define

PHY_CONFIG_PHY_OPS

Description

This specifies a pointer to a phy_ops_t structure containing a set of custom operations for controlling those

PHYs that cannot be controlled using the generic operations.

366/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

10.4 Ethernet drivers initialization

Note:

Each ethernet driver is initialized independently by calling its initialize function.

●

●

●

For the LAN91 driver, this function is named lan91_initialize().

For the LAN9x1x driver, this function is named lan9x1x_initialize().

●

For the STxMAC driver, the function is named stmac_initialize() to initialize for

STMAC/STMAC110

Alternatively, to initialize for STGMAC, the function is named stgmac_initialize().

You may only initialize the driver in one STxMAC mode or the other - not both.

●

For the h2heth driver, this function is named h2heth_initialize().

The ethernet driver allocates and initializes its internal state and then queries the registry for the driver settings specific to the current platform (for example, memory base address, interrupt number and trigger mode). If the current platform does not support the ethernet device, the initialization fails and an error is returned through errno. If the current platform does support the ethernet device, any hardware initialization is performed and the ethernet chip is probed for, and the PHY device associated with the ethernet device is opened and configured.

On successfully completing the probe for the ethernet chip, it is initialized (along with the remainder of the ethernet driver) and a new ethernet device is registered with the device library using the prefix ethernet and postfixed with the device instance number. If this is the first device to be registered with the prefix ethernet, the device name is ethernet0. If other ethernet devices are already registered with the device library, the device name can be ethernet1 or ethernet2, and so on.

It makes no difference if the ethernet device is present on-board or on a USB/ENET-STEM module (for example, a SMSC LAN91C111 device on a db558 STEM, or SMSC LAN9x1x device on a db641 STEM), provided it has been mapped into memory using the appropriate configuration settings.

7702033 Rev 27 367/515

OSPlus ethernet drivers UM1150

10.5 Generic PHY driver initialization

The PHY driver is initialized by calling function phy_initialize(). This function allocates and initializes the generic PHY driver internal state and queries the registry for the driver settings specific to the current platform (for example, the number of PHY device instances to manage, the address of each PHY and any custom PHY code). If the current platform does not have any registry entries for any PHY devices, then the PHY driver implicitly creates two dummy device instances.

A new PHY device is registered with the device library using the prefix phy and postfixed with the device instance number. If this is the first device to be registered with the prefix phy, the device name is phy0. If other ethernet devices are already registered with the device library, the device name may be phy1 or phy2, and so on.

You do not need to call phy_initialize() directly, as each of the ethernet drivers ensure that it has been called before they attempt to open a PHY device.

10.6 Ethernet drivers usage model

As the ethernet drivers conform to the OSPlus driver model, when the ethernet driver has been initialized, and a new ethernet device registered with the device library, the ethernet device can be accessed using the standard device library open, close, read, write and ioctl functions. See

Chapter 4: OSPlus device model on page 134

for more details on using the

device library.

The ethernet drivers present the ethernet devices as character devices. This means there is no support for performing block-orientated input and output.

The ethernet drivers are primarily intended for use with a TCP/IP stack. The usage model for the ethernet drivers are almost identical to that for USB ethernet devices, but with several subtle differences.

After successfully opening the ethernet device, it is ready to read and write packets. To use the driver effectively, a small amount of setup is usually needed. This usually involves reading the hardware MAC address using the OSPlus ethernet ioctl

OSPLUS_IOCTL_ETH_GET_MAC

and registering it with the TCP/IP stack for use when processing TCP/IP packets. Alternatively the ethernet driver supports user specified MAC hardware addresses and an address can be set using the OSPlus ethernet ioctl

OSPLUS_IOCTL_ETH_SET_MAC

.

The status of the ethernet device can be retrieved at any time using the OSPlus ethernet ioctl OSPLUS_IOCTL_ETH_GET_STATUS. This status indicates whether the ethernet device is enabled, has a valid link and if the device is in loopback mode. On any read or write error it is advisable to query the ethernet device status to determine if the error was due to the link being down, in which case all further reads and writes can be suspended until the link is back up.

The ethernet driver updates a set of statistics after every TCP/IP packet read or write. These statistics include the number of packets and bytes successfully sent and received as well as the number of errors, and so on. The statistics can be retrieved using the OSPlus ethernet ioctl OSPLUS_IOCTL_ETH_GET_STATISTICS.

For details of all supported ethernet driver ioctls, see

Section 10.10: Ethernet driver ioctls on page 381

.

368/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

10.6.1 Reading and writing packets

Synchronous operation

All ethernet devices support synchronous packet reading and writing using the device_read()

and device_write() functions. device_read() blocks until a packet is available from the device or the read timeout is reached, and device_write() blocks until the packet is written to the device, or until the write timeout is reached. By default, all synchronous reads and writes have a timeout of 5 seconds. On reaching the timeout the function fails with -1 and sets errno to ETIMEDOUT. The read and write timeouts are set with the ioctls OSPLUS_IOCTL_SET_RD_TIMEOUT and

OSPLUS_IOCTL_SET_WR_TIMEOUT

respectively. The current read and write timeout are obtained with the ioctls OSPLUS_IOCTL_GET_RD_TIMEOUT and

OSPLUS_IOCTL_GET_WR_TIMEOUT

.

It is recommended that a dedicated task is used to read TCP/IP packets from the ethernet device. The read blocks indefinitely, allowing TCP/IP packets to be read as they arrive without the need for polling the device and consuming valuable CPU time. On each read operation there is no way to determine the size of the TCP/IP packet that is read. Therefore the device_read() function must be supplied with a buffer large enough to hold the maximum sized packet. The maximum sized packet can be determined by issuing the

OSPlus ethernet ioctl OSPLUS_IOCTL_ETH_GET_INFO. Failure to provide a buffer large enough to hold the maximum sized packet results in the packet being dropped. On a successful read, the size of the packet is returned. The task reading the TCP/IP packets then passes the packet to the TCP/IP stack for processing, before attempting to read the next packet.

All TCP/IP packets are written to the ethernet device using the device_write() function.

Before the ethernet device can be closed, all further reads and writes should be prevented.

Attempting to close an ethernet device while a read or write is in progress causes the read or write to fail.

After any read from or write to the ethernet device, it is important to check for an error. On error, errno is set to a value that indicates the nature of the problem.

Asynchronous operation

Some ethernet drivers (like the STxMAC and some USB ethernet devices) also support asynchronous packet reading and writing. The asynchronous interface is provided using device_ioctl()

calls, and allows for much higher data throughput, since multiple I/O requests can be queued to the device.

The OSPLUS_IOCTL_ETH_ASYNC_READ_SUPPORTED ioctl allows an application to determine if an ethernet device supports asynchronous reads. The

OSPLUS_IOCTL_ETH_ASYNC_WRITE_SUPPORTED

ioctl does the same for writes. If the device indicates that it supports asynchronous packet reading, the application can read packets from the device with the OSPLUS_IOCTL_ETH_ASYNC_READ ioctl rather than with the device_read() interface. Similarly if the device supports asynchronous packet writes, packets can be written to the device with the OSPLUS_IOCTL_ETH_ASYNC_WRITE ioctl rather than with the device_write() interface.

7702033 Rev 27 369/515

OSPlus ethernet drivers

Note:

UM1150

The asynchronous packet read and packet write ioctls both take a pointer to an ethernet_async_t

structure as their argument. This structure is defined as: typedef struct ethernet_async_s { void (*callback)(struct ethernet_async_s*); unsigned char *buffer; size_t length; void *bufp; void *statep;

} ethernet_async_t; callback

is a pointer to a function that is called when the I/O completes. This routine may be called from an interrupt context, so the processing performed in this routine should be limited to those operations that are permissible in this context. buffer is a pointer to the raw packet buffer and length is the length of the buffer. bufp and statep are generic pointers that are used when interfacing to a TCP/IP stack. bufp should be used to record the TCP/IP stack’s buffer structure that is associated with the I/O, and statep can be used for any purpose.

When an ethernet_async_t is successfully submitted to an ethernet driver, the ioctl completes immediately, with the I/O still outstanding. Completion is signalled by the callback routine being called for that structure.

●

●

●

Asynchronous reads and writes do not time out and remain outstanding until one of the following occurs: the operation completes the ethernet device enters a standby power mode the ethernet device closes

On entering a standby power mode or closing the ethernet device, all asynchronous reads and writes are aborted. However, when all asynchronous reads or writes are outstanding, attempting to add another read or write returns -1 with errno set to ETIMEDOUT.

Once an ethernet_async_t structure has been passed to an ethernet driver, the

structure remains owned by that driver until the callback routine is called passing the structure back to the application. Unpredictable results occur if the structure is freed or otherwise changed while it is owned by the driver.

Using the asynchronous packet write interface

●

●

When an ethernet packet is to be written using the asynchronous interface, the application should perform the following steps: allocate an ethernet_async_t structure store the TCP/IP stack’s buffer structure pointer in the bufp field of the ethernet_async_t

structure

●

● from the information in the TCP/IP stack’s buffer structure, set up the buffer and length

fields in the ethernet_async_t structure set the callback pointer in the ethernet_async_t structure to the packet write callback function

● submit the ethernet_async_t structure to the driver with the

OSPLUS_IOCTL_ETH_ASYNC_WRITE

ioctl

370/515 7702033 Rev 27

UM1150

Note:

OSPlus ethernet drivers

The packet write completion function should do the following:

● check the length field in the ethernet_async_t structure to see how many bytes were transferred

●

● using the bufp field in the structure, release the TCP/IP stack’s buffer structure back to the TCP/IP stack release the ethernet_async_t structure

Using the asynchronous packet read interface

●

●

When an ethernet packet is to be read using the asynchronous interface, the application should perform the following steps: allocate an ethernet_async_t structure store the TCP/IP stack’s buffer structure pointer in the bufp field of the ethernet_async_t

structure

●

● from the information in the TCP/IP stack’s buffer structure, set up the buffer and length

fields in the ethernet_async_t structure to be big enough to hold the largest expected packet set the callback pointer in the ethernet_async_t structure to the packet read callback function

● submit the structure to the driver with the OSPLUS_IOCTL_ETH_ASYNC_READ ioctl.

The packet read completion function should do the following:

● check the length field in the ethernet_async_t structure to see how many bytes were transferred

●

● using the bufp field in the ethernet_async_t structure, inject the packet into the

TCP/IP stack release the ethernet_async_t structure

The synchronous and asynchronous interfaces of some ethernet drivers assume that the memory up to one cache line immediately before and after the packet buffers is also part of the packet buffers. This allows the drivers to add any pre- or post-headers that may be required in-situ, and eliminates data copies. If this is the case, it is up to the application to ensure that the memory used by the TCP/IP stack for its packet buffers meets this requirement. Failure to do this may result in unpredictable behavior.

This does not apply to the STxMAC driver.

All OSPlus ethernet drivers (except h2heth) support a range of packet filtering options.

Packet filtering helps the ethernet devices achieve greater performance efficiency by only receiving those packets that the application wants. The packet filtering options are set by

OR'ing the desired packet filtering options together and passing the value as a parameter to the ioctl OSPLUS_IOCTL_ETH_SET_PKT_FILTER.

Not all ethernet drivers support the same set of packet filtering options, but as a rule all drivers support the promiscuous, broadcast and multicast hash filters. If a driver does not support a particular filter it returns -1 and sets errno to EINVAL.

7702033 Rev 27 371/515

OSPlus ethernet drivers UM1150

Promiscuous packet filter

The promiscuous filter causes all packets received from the network to be passed to the application regardless of whether the packet was meant for the application or not. By default, the packet filtering is set to promiscuous during the ethernet driver initialization. If the packet filters are updated, then promiscuous mode may be enabled by specifying

OSPLUS_ETH_FILTER_PROMISCUOUS

as a parameter to the

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

ioctl. No other filters are enabled with the promiscuous filter.

Directed packet filter

The directed packet filter causes only those packets with a destination address the same as the currently configured ethernet device MAC address to be received and passed to the application. The directed packet filter is enabled by specifying

OSPLUS_ETH_FILTER_DIRECTED

as a parameter to the

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

ioctl. It is possible to also receive broadcast packets by specifying the broadcast filter in conjunction with this filter. This filter is only supported on the LAN9x1x and STxMAC drivers.

Inverse packet filter

The inverse packet filter allows all packets with a destination address that is not the same as the currently configured ethernet device MAC address to be received and passed to the application. The filter is set by specifying OSPLUS_ETH_FILTER_INVERSE as a parameter to the OSPLUS_IOCTL_ETH_SET_PKT_FILTER ioctl. No other filters should be enabled with the inverse filter. This filter is only supported on the LAN9x1x and STxMAC drivers.

Broadcast filter

The broadcast filter controls the reception of broadcast packets. When set by specifying

OSPLUS_ETH_FILTER_BROADCAST

as a parameter to the

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

ioctl, all broadcast packets are passed to the application. All ethernet devices support the broadcast filter; however, only a few ethernet devices such as the LAN9x1x and STxMAC drivers support disabling the broadcast filter.

The broadcast filter can be used in conjunction with the directed and multicast filters.

Multicast hash filter

The multicast hash filter uses a 64-bit hash table loaded on the ethernet device for group packet filtering. As each multicast packet is received by the ethernet device, a hash value is calculated. This hash value is defined as the six most significant bits of the CRC of the destination address. The filter interprets the three most significant bits of the hash value to be the byte of the hash table to access (0-7), and it interprets the next three most significant bits as the bit within the byte. If the appropriate bit in the table is set then the packet is received, otherwise it is dropped.

The hash table can be loaded directly to the ethernet device using the ioctl

OSPLUS_IOCTL_ETH_SET_MCAST_HASH_TABLE

or retrieved using the ioctl

OSPLUS_IOCTL_ETH_GET_MCAST_HASH_TABLE

. Note that when using these ioctls, it is the responsibility of the application to calculate the hash table manually. A better solution is to use the ioctl OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS to set the hash table or the ioctl OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS to add to the hash table. These ioctls are passed an ethernet_mcasts_t structure, which is initialized to contain a number of hardware destination addresses; these are then used to calculate the hash table values.

372/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

The benefit of this approach is that the application can then easily get the multicast filters currently in use by using the ioctl OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS.

The application enables the multicast hash filter by specifying

OSPLUS_ETH_FILTER_MULTICAST

as a parameter to the

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

ioctl. The broadcast filter can be used in conjunction with the multicast hash filter to control reception of broadcast packets.

By default, when the multicast hash filter is active, those packets with a physical address are perfect filtered, that is, they are only received if they match the ethernet device MAC address. By also specifying the OSPLUS_ETH_FILTER_HASH_PHYSICAL filter, the application can cause those packets with a physical address to be hash filtered also.

All ethernet devices support the multicast hash filter with physical address perfect filtering.

Only the LAN9x1x and STxMAC support the multicast hash filter with physical address hash filtering

All multicast hash filter

The all multicast hash filter causes any multicast packet to be received by the ethernet device and passed to the application, regardless of whether the multicast packet passes the multicast hash filter or not. The application enables the all multicast hash filter by specifying

OSPLUS_ETH_FILTER_ALL_MULTICAST

as a parameter to the

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

ioctl. The broadcast filter may be used in conjunction with the all multicast hash filter to control reception of broadcast packets.

By default when the all multicast hash filter is active, those packets with a physical address are perfect filtered. By also specifying the OSPLUS_ETH_FILTER_HASH_PHYSICAL filter, the application can cause those packets with a physical address to also be hash filtered.

All ethernet devices support the all multicast hash filter with physical address perfect filtering. Only the LAN9x1x and STxMAC support the multicast hash filter with physical address hash filtering

Currently only the STxMAC driver supports power management features and only when used with STGMAC hardware. The supported features include wake-on-LAN, where the ethernet device is placed into a low power state and monitors incoming frames and, if a frame matching the current wake-on-LAN mode is received, the ethernet device powers back up. Setting a particular power mode level, in which the ethernet device is either powered up or down, is also supported.

The currently set power mode can be determined using the ioctl

OSPLUS_IOCTL_ETH_GET_STATUS

.

Power level

●

●

Power level support allows an application to set the desired power mode. The supported power levels are:

on (device and PHY are fully powered)

●

active standby (device must be in wake-on-LAN mode where it is is partially powered, and PHY is fully powered)

passive standby (device must not be in wake-on-LAN mode, both device and PHY are powered down)

7702033 Rev 27 373/515

OSPlus ethernet drivers UM1150

When in standby or powered down, the ethernet device consumes minimal or no power and remains non-functioning (that is, it cannot read or write packets) until it is powered back up.

Wake-on-LAN

Wake-on-LAN is supported when the power level is set to active standby. In this configuration, the ethernet device is mostly shut down but the PHY remains powered. This allows special packets to be received (which are only received by the ethernet driver – no packets are passed to the application) and the ethernet device fully woken up.

Two wake-on-LAN modes of operation are supported. This first mode is “magic packet”, using Advanced Micro Devices Magic Packet technology. In magic packet mode, the ethernet device sleeps until it receives a magic packet destined for that device. A magic packet is defined as a broadcast ethernet frame that contains sixteen repetitions of the selected ethernet device’s MAC address.

The second wake-on-LAN mode is global unicast. When set, this mode allows reception of any unicast packet successfully filtered by the ethernet device to be recognized as a wakeup frame.

10.7 Generic PHY driver usage model

The generic PHY driver conforms to the OSPlus driver model. When the generic PHY driver has been initialized, and a new PHY device registered with the device library, the PHY device can be accessed using the standard device library open, close and ioctl functions.

See

Chapter 4: OSPlus device model on page 134

for more details on using the device library.

The PHY driver does not support any character or block-orientated input and output. The

PHY driver is not intended to be used directly by the user application, but by ethernet drivers instead.

When a PHY device has been successfully opened, the ethernet driver issues the OSPlus

PHY ioctl OSPLUS_IOCTL_PHY_PROBE, passing the address of a phy_probe_t structure.

This structure contains any cookie and pointers to functions for reading and writing the PHY registers. This ioctl then attempts to detect a valid PHY device. On successful detection, it returns 0.

When the probing of the PHY is successful, the ethernet device next registers a PHY status change callback using the OSPlus PHY ioctl OSPLUS_IOCTL_PHY_SET_CALLBACK. The purpose of this callback is to provide a mechanism to communicate any PHY link status changes and have the ethernet driver alter its configuration based on the current link.

When the PHY status change callback has been registered, the ethernet driver finally sets the current link settings with the OSPlus PHY ioctl OSPLUS_IOCTL_PHY_SET_LINK. From this point on there is nothing more for the ethernet driver to configure.

For details of all supported generic PHY driver ioctls, see

Section 10.11: Generic PHY driver ioctls on page 393

.

374/515

The generic PHY driver currently only supports power on or power off. Power control is handled by the standard OSPLUS_IOCTL_SET_POWER and OSPLUS_IOCTL_GET_POWER ioctls.

7702033 Rev 27

UM1150 OSPlus ethernet drivers

Note:

The generic PHY driver provides a common set of operations that are sufficient to manage most PHYs, but there are some PHYs that require some additional programming. This requirement is supported through the use of custom PHY ops.

Custom PHY ops must be specified using the registry before calling phy_initialize().

As the PHY initialize function may not be called directly, but instead indirectly from one of the ethernet initialize functions, it is important to ensure that all relevant registry keys are set up before any of the ethernet drivers are initialized.

To set custom PHY ops, you must create and initialize a structure of type phy_ops_t with the custom PHY ops required by the application. Where no custom op is required, the driver should use the generic op. For example, if an application wishes to use a PHY that has a specific ID and requires some specialist setup code, you only need to write the probe and setup PHY ops: int phy_op_custom_probe (phy_device_t *phy)

{

/* Do some specific probing */

} int phy_op_custom_setup (phy_device_t *phy)

{

/* Do some specific setup */

}

The phy_ops_t structure can then be initialized as follows: phy_ops_t custom_ops = { phy_ops_custom_probe, phy_ops_generic_reset, phy_ops_custom_setup, phy_ops_generic_power, phy_ops_generic_loopback, phy_ops_generic_aneg_link, phy_ops_generic_aneg_status,

}; phy_ops_generic_force_link, phy_ops_generic_force_status

To register the custom ops named in this structure with the PHY driver, write a registry key: registry_key_set (PHY_CONFIG_PATH,

PHY_CONFIG_PHY_OPS"Custom",

&custom_ops);

When the PHY driver is opened and the probe performed, the custom PHY ops are tested to see if they control the PHY. If not, the PHY driver defaults to the generic ops.

There is no limit to the number of custom PHY ops that may be specified. The general rule is that PHY ops are used in the order they are specified, and if no custom ops can handle the

PHY, it is left for the generic ops to manage it.

It is also possible to overwrite existing custom PHY ops with new custom ops with the same name.

7702033 Rev 27 375/515

OSPlus ethernet drivers UM1150

10.8 Ethernet drivers header files

Each OSPlus ethernet driver has its own header file. This header file contains all configuration options supported by the driver. The configuration options supported by each driver are documented in the following sections.

10.8.1 LAN91 driver header file: lan91.h

All the definitions relating to the LAN91 driver are in the file lan91.h.

Table 138.

Configuration option defines in LAN91.h

Define

LAN91_CONFIG_PATH

LAN91_REGISTRY_PATH_ROOT

Description

Registry path to LAN91 user override basic configuration entries.

Registry path to LAN91 platform specific basic configuration entries.

LAN91_CONFIG_INIT_FN

LAN91_CONFIG_BASE

LAN91_CONFIG_INTR

LAN91_CONFIG_ALT_INTR

LAN91_CONFIG_INTR_LEVEL

LAN91_CONFIG_INTR_TRIGGER

LAN91_CONFIG_INTR_ENB_FN

LAN91_CONFIG_MAC_ADDRESS

LAN91_CONFIG_MAC_MTU

LAN91_CONFIG_MAC_PKT_FILTER

LAN91_CONFIG_MAC_LINK_CB

LAN91_CONFIG_PHY_NAME

LAN91_CONFIG_PHY_LINK

Refer to

Table 123: Basic driver options defined in lan91.h on page 353

.

LAN91_CONFIG_PATH_FUDGE

LAN91_REGISTRY_PATH_FUDGE

Registry path to LAN91 addressing user override configuration entries.

Registry path to LAN91 platform specific addressing configuration entries.

LAN91_CONFIG__8BIT_FN

LAN91_CONFIG_16BIT_FN

LAN91_CONFIG_32BIT_FN

Refer to

Table 124: Device address function options defined in lan91.h on page 355

.

LAN91_CONFIG_PATH_FLAGS

LAN91_REGISTRY_PATH_FLAGS

Registry path to LAN91 user override configuration option entries.

Registry path to LAN91 platform specific configuration option entries.

LAN91_CONFIG_32BIT

LAN91_CONFIG_AUTO_REL

LAN91_CONFIG_POWER_SAVE

LAN91_CONFIG_TX_ERR_REL

LAN91_CONFIG_USE_DMA

Refer to

Table 125: Advanced driver options defined in lan91.h on page 356

.

Table 139.

Functions defined in LAN91.h

Function

lan91_initialize()

Description

Initialize the LAN91 driver.

376/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

10.8.2 LAN9x1x driver header file: lan9x1x.h

The LAN9x1x driver definitions are in the file lan9x1x.h. The functions are explained in

Section 10.14.2: LAN9x1x driver function definitions on page 415

.

Table 140.

Configuration option defines in lan9x1x.h

Define

LAN9X1X_CONFIG_PATH

LAN9X1X_REGISTRY_PATH_ROOT

LAN9X1X_CONFIG_COUNT

Description

Registry path to LAN9x1x user override configuration entries.

Registry path to LAN9x1x platform specific configuration entries.

Registry key to hold an integer corresponding to the number of LAN9x1x devices present in the system.

LAN9X1X_CONFIG_INIT_FN

LAN9X1X_CONFIG_BASE

LAN9X1X_CONFIG_INTR

LAN9X1X_CONFIG_ALT_INTR

LAN9X1X_CONFIG_INTR_LEVEL

LAN9X1X_CONFIG_INTR_TRIGGER

LAN9X1X_CONFIG_INTR_ENB_FN

LAN9X1X_CONFIG_INTR_MODE

LAN9X1X_CONFIG_INTR_POLARITY

LAN9X1X_CONFIG_RX_OFFSET

LAN9X1X_CONFIG_RX_END_ALIGN

LAN9X1X_CONFIG_RX_READ_FN

LAN9X1X_CONFIG_TX_WRITE_FN

LAN9X1X_CONFIG_TX_FIFO_SZ

LAN9X1X_CONFIG_MAC_ADDRESS

LAN9X1X_CONFIG_MAC_MTU

LAN9X1X_CONFIG_MAC_PKT_FILTER

LAN9X1X_CONFIG_MAC_LINK_CB

LAN9X1X_CONFIG_PHY_NAME

LAN9X1X_CONFIG_PHY_LINK

LAN9X1X_CONFIG_PHY_EXTERNAL

Refer to

Table 126: Basic driver options defined in lan9x1x.h on page 357

.

Refer to

Table 127: MAC options defined in lan9x1x.h on page 358

.

Refer to

Table 128: PHY options defined in lan9x1x.h on page 359

.

Table 141.

Functions defined in lan9x1x.h

Function

lan9x1x_initialize()

Description

Initialize the LAN9x1x driver.

7702033 Rev 27 377/515

OSPlus ethernet drivers UM1150

10.8.3 STxMAC driver header file: stxmac.h

All the definitions relating to the STxMAC driver are in the file stxmac.h. The functions defined in stmac110.h are explained in

Section 10.14.3: STxMAC driver function definitions on page 416

.

Table 142.

Configuration option defines in stxmac.h

Define

STMAC_CONFIG_PATH

STMAC_REGISTRY_PATH_ROOT

STGMAC_CONFIG_PATH

STGMAC_REGISTRY_PATH_ROOT

STXMAC_CONFIG_COUNT

Description

Registry path to STMAC user override configuration entries.

Registry path to STMAC platform specific configuration entries.

Registry path to STGMAC user override configuration entries.

Registry path to STGMAC platform specific configuration entries.

Registry key to hold an integer corresponding to the number of STxMAC controllers present in the system.

STXMAC_CONFIG_INIT_FN

STXMAC_CONFIG_INIT_ARG

STXMAC_CONFIG_BASE

STXMAC_CONFIG_DMA_BURST_LEN_FN

STXMAC_CONFIG_DMA_INTR

STXMAC_CONFIG_DMA_ALT_INTR

STXMAC_CONFIG_DMA_INTR_LEVEL

STXMAC_CONFIG_DMA_INTR_TRIGGER

STXMAC_CONFIG_DMA_INTR_ENB_FN

STXMAC_CONFIG_DMA_RX_DESC

STXMAC_CONFIG_DMA_TX_DESC

STXMAC_CONFIG_MAC_ADDRESS

STXMAC_CONFIG_MAC_MTU

STXMAC_CONFIG_MAC_PKT_FILTER

STXMAC_CONFIG_MAC_LINK_CB

STXMAC_CONFIG_MMC_FREEZE

STXMAC_CONFIG_MMC_ROLLOVER

STXMAC_CONFIG_MMC_RST_ON_RD

STXMAC_CONFIG_MMC_COUNTER_CB

STXMAC_CONFIG_PHY_DISABLE

STXMAC_CONFIG_PHY_NAME

STXMAC_CONFIG_PHY_LINK

Refer to

Table 129: Basic options defined in stxmac.h on page 360

.

Refer to

Table 130: DMA options defined in stxmac.h on page 361

.

Refer to

Table 131: MAC options defined in stxmac.h on page 362

.

Refer to

Table 132: MMC options defined in stxmac.h on page 363

.

Refer to

Table 133: PHY options defined in stxmac.h on page 363

.

378/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

Table 143.

Functions defined in stxmac.h

Function

stmac_initialize() stgmac_initialize()

Description

Initialize the STxMAC driver for use with

STMAC/STMAC110 devices.

Initialize the STxMAC driver for use with STGMAC devices.

All the definitions relating to the h2heth driver are in the file h2heth.h. The functions

defined in h2heth.h are explained in

Section 10.14.4: Host-to-host ethernet driver function definitions on page 417

.

Table 144.

Functions defined in h2heth.h

Function

h2heth_initialize()

Description

Initialize the h2heth driver.

10.9 Generic PHY driver header file

The OSPlus generic ethernet PHY driver has its own header file containing all configuration options supported by the driver.

The PHY driver definitions are in the file phy.h. The functions are explained in

Section 10.15: Generic PHY driver function definitions on page 418

.

Table 145.

Configuration option defines in phy.h

Define

PHY_CONFIG_PATH

PHY_REGISTRY_PATH_ROOT

PHY_CONFIG_COUNT

Description

Registry path to PHY user override configuration entries.

Registry path to PHY platform specific configuration entries.

Registry key to hold an integer corresponding to the number of PHY devices present in the system.

PHY_CONFIG_INIT_FN

PHY_CONFIG_INIT_ARG

PHY_CONFIG_ADDRESS

PHY_CONFIG_LINK

PHY_CONFIG_LINK_TIMEOUT

PHY_CONFIG_LINK_TASK_PRI

PHY_CONFIG_LINK_TASK_DELAY

PHY_CONFIG_ANEG_10MBPS

PHY_CONFIG_ANEG_100MBPS

PHY_CONFIG_ANEG_1000MBPS

Refer to

Table 135: PHY basic options defined in phy.h on page 365

.

Refer to

Table 136: PHY link options defined in phy.h on page 366

.

PHY_CONFIG_PHY_OPS

Refer to

Table 137: PHY ops options defined in phy.h on page 366

.

7702033 Rev 27 379/515

OSPlus ethernet drivers UM1150

Table 146.

Configuration argument defines in phy.h

Define

PHY_INIT_ARG_MII_MODE

PHY_INIT_ARG_RMII_MODE_1

PHY_INIT_ARG_RMII_MODE_2

Description

Initialize in MII mode

Initialize in RMII mode with internal clock

Initialize in RMII mode with external clock

Table 147.

Types defined in phy.h

Types

phy_device_t phy_ops_t

Description

An opaque type encompassing a PHY device

Type holding a series of operations specific to a given PHY.

Table 148.

Functions defined in phy.h

Function

phy_ops_get_addr() phy_ops_set_addr() phy_ops_get_reg() phy_ops_set_reg() phy_ops_generic_probe() phy_ops_generic_reset() phy_ops_generic_setup() phy_ops_generic_power() phy_ops_generic_loopback() phy_ops_generic_aneg_link() phy_ops_generic_aneg_status() phy_ops_generic_force_link() phy_ops_generic_force_status() phy_initialize()

Description

Get the PHY address. This is only intended for use with PHYs that require custom operations.

Set the PHY address. This is only intended for use with PHYs that require custom operations.

Read a PHY register. This is only intended for use with PHYs that require custom operations.

Write a PHY register. This is only intended for use with PHYs that require custom operations.

Generic function to probe for a PHY

Generic function to reset a PHY

Generic function to set up a PHY for use

Generic function to power up or power down a PHY

Generic function to enabled or disable loopback

Generic function to program link auto-negotiation

Generic function to return the status of autonegotiation

Generic function to force specific link settings

Generic function to return the status of a forced link

Initialize the PHY driver.

380/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

10.10.1 Ethernet driver common ioctls

The OSPlus LAN91, LAN9x1x and STxMAC ethernet drivers support only the common ioctls for getting and setting synchronous read and write timeouts. These ioctls are in the file ioctls/common.h

and are listed in

Table 149

. For the ioctl definitions, see

Section 4.6:

Device library header file: ioctls/common.h on page 140

.

Table 149.

Ioctls defined in ioctls/common.h

Ioctl

OSPLUS_IOCTL_GET_RD_TIMEOUT

OSPLUS_IOCTL_SET_RD_TIMEOUT

OSPLUS_IOCTL_GET_WR_TIMEOUT

OSPLUS_IOCTL_SET_WR_TIMEOUT

Description

Set the timeout value for blocking read operations

Return the timeout value for blocking read operations

Return the timeout value for blocking write operations

Set the timeout value for blocking read operations

The device library defines a set of ioctls specifically to be used by ethernet devices. These

ioctls are in the file ioctls/ethernet.h and are listed in

Table 150

. For the ioctl

definitions, see

Section 10.12 on page 395

.

Details of the ioctls supported by specific drivers are given in

Section 10.10.2: Ethernet driver ethernet ioctls on page 390

.

Table 150.

Ioctls defined in ioctls/ethernet.h

Ioctl Description

OSPLUS_IOCTL_ETH_SET_MAC

Set the MAC address

OSPLUS_IOCTL_ETH_GET_MAC

Get the MAC address

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS

Set the multicast filter addresses

OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS

Get the multicast filter addresses

OSPLUS_IOCTL_ETH_ADD_MCAST_

FILTERS

OSPLUS_IOCTL_ETH_SET_MCAST_HASH_

TABLE

OSPLUS_IOCTL_ETH_GET_MCAST_HASH_

TABLE

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

Add one or more multicast filter addresses

Set the multicast hash table

Get the multicast hash table

OSPLUS_IOCTL_ETH_GET_PKT_FILTER

OSPLUS_IOCTL_ETH_SET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_STATUS

OSPLUS_IOCTL_ETH_GET_INFO

Set the ethernet packet filtering options

Get the current ethernet packet filtering options

Set loopback mode to MAC, PHY or off.

Get loopback mode.

Get the ethernet status

Return the ethernet device information (for example, MTU and maximum number of multicast filters)

7702033 Rev 27 381/515

OSPlus ethernet drivers UM1150

Table 150.

Ioctls defined in ioctls/ethernet.h (continued)

Ioctl Description

OSPLUS_IOCTL_ETH_ANEG_ON

OSPLUS_IOCTL_ETH_ANEG_OFF

OSPLUS_IOCTL_ETH_SET_LINK

OSPLUS_IOCTL_ETH_ASYNC_READ_

SUPPORTED

OSPLUS_IOCTL_ETH_ASYNC_WRITE_

SUPPORTED

OSPLUS_IOCTL_ETH_ASYNC_READ

Turn auto-negotiation on

Turn auto-negotiation off

Set the link settings when auto-negotiation disabled

Determine if driver supports async read interface.

This is deprecated, use

OSPLUS_IOCTL_ETH_GET_INFO

.

Determine if driver supports async write interface.

This is deprecated, use

OSPLUS_IOCTL_ETH_GET_INFO

.

Read a packet through async interface

Write a packet through async interface

Set power management wake-on-LAN options

OSPLUS_IOCTL_ETH_ASYNC_WRITE

OSPLUS_IOCTL_ETH_SET_PMT_WOL

OSPLUS_IOCTL_ETH_GET_PMT_WOL

OSPLUS_IOCTL_ETH_SET_MMC_CONFIG

Get power management wake-on-LAN options

Set the MMC configuration

OSPLUS_IOCTL_ETH_GET_MMC_CONFIG

Get the MMC configuration

OSPLUS_IOCTL_ETH_SET_MMC_CALLBACK

Set the MMC callback function

OSPLUS_IOCTL_ETH_GET_MMC_CALLBACK

Set the MMC callback function

OSPLUS_IOCTL_ETH_CLR_MMC_COUNTER

Clear a specific MMC counter value

OSPLUS_IOCTL_ETH_GET_MMC_COUNTER

OSPLUS_IOCTL_ETH_SET_CRC_OFFLOAD

OSPLUS_IOCTL_ETH_GET_CRC_OFFLOAD

Get a specific MMC counter value

Turn CRC offload (if supported) on or off

Get the current CRC offload status

Table 151.

Features defined in ioctls/ethernet.h

Ioctl

OSPLUS_ETH_FEATURE_ASYNC_READ

OSPLUS_ETH_FEATURE_ASYNC_WRITE

OSPLUS_ETH_FEATURE_CRC_OFFLOAD

OSPLUS_ETH_FEATURE_PMT

OSPLUS_ETH_FEATURE_PMT_WOL

Description

Asynchronous read supported

Asynchronous write supported

CRC offload is supported

Power management is supported

Power management wake-on-LAN is supported

Table 152.

asynchronous flags defined in ioctls/ethernet.h

Ioctl Description

OSPLUS_ETH_ASYNC_FLAG_CRC_

OFFLOAD

Enable CRC offload for asynchronous transfer

382/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

Table 153.

Ethernet packet filter type defines in ioctls/ethernet.h

Defines Description

OSPLUS_ETH_FILTER_ALL_MULTICAST

OSPLUS_ETH_FILTER_BROADCAST

OSPLUS_ETH_FILTER_DIRECTED

OSPLUS_ETH_FILTER_HASH_PHYSICAL

OSPLUS_ETH_FILTER_INVERSE

OSPLUS_ETH_FILTER_MULTICAST

OSPLUS_ETH_FILTER_PROMISCUOUS

All multicast packet filter type

Broadcast packet filter type

Directed packet filter type

Hash physical address filter type

Inverse packet filter type

Multicast packet filter type

Promiscuous packet filter type

Table 154.

Ethernet MMC statistics code defines in ioctls/ethernet.h

Defines Description

OSPLUS_ETH_MMC_RX_64_OCTETS_GB

Number of good and bad frames received with length 64 bytes.

OSPLUS_ETH_MMC_RX_65_TO_127_

OCTETS_GB

Number of good and bad frames received with length 65 to 127 bytes.

OSPLUS_ETH_MMC_RX_128_TO_255_

OCTETS_GB

Number of good and bad frames received with length 128 to 255 bytes.

OSPLUS_ETH_MMC_RX_256_TO_511_

OCTETS_GB

OSPLUS_ETH_MMC_RX_512_TO_1023_

OCTETS_GB

Number of good and bad frames received with length 256 to 511 bytes.

Number of good and bad frames received with length 512 to 1023 bytes.

OSPLUS_ETH_MMC_RX_1024_TO_MAX_

OCTETS_GB

Number of good and bad frames received with length 1024 bytes or more

OSPLUS_ETH_MMC_RX_ALIGNMENT_ERROR

Number of frames received with alignment errors

OSPLUS_ETH_MMC_RX_BROADCAST_

FRAMES_G

OSPLUS_ETH_MMC_RX_CRC_ERROR

Number of good broadcast frames received

OSPLUS_ETH_MMC_RX_FIFO_OVERFLOW

OSPLUS_ETH_MMC_RX_FRAME_COUNT_G

OSPLUS_ETH_MMC_RX_FRAME_COUNT_GB

OSPLUS_ETH_MMC_RX_ICMP_ERR_FRMS

OSPLUS_ETH_MMC_RX_ICMP_ERR_OCTETS

OSPLUS_ETH_MMC_RX_ICMP_GD_FRMS

OSPLUS_ETH_MMC_RX_ICMP_GD_OCTETS

OSPLUS_ETH_MMC_RX_IPV4_FRAG_FRMS

Number of frames received with CRC errors

Number of missed received frames due to FIFO overflow

Number of good frames received

Number of good and bad frames received

Number of good IP datagram frames whose ICMP payload has a checksum error

Number of bytes received in an ICMP segment with checksum errors

Number of good IP datagrams with good ICMP payload

Number of bytes received in good ICMP segments

Number of good IPv4 frames with fragmentation

7702033 Rev 27 383/515

OSPlus ethernet drivers UM1150

Table 154.

Ethernet MMC statistics code defines in ioctls/ethernet.h (continued)

Defines Description

OSPLUS_ETH_MMC_RX_IPV4_FRAG_OCTETS

OSPLUS_ETH_MMC_RX_IPV4_GD_FRMS

Number of bytes received in fragmented IPv4 datagrams

Number of good IPv4 frames received

OSPLUS_ETH_MMC_RX_IPV4_GD_OCTETS

OSPLUS_ETH_MMC_RX_IPV4_HDRERR_FRMS

Number of bytes received in good IPv4 datagrams

Number of IPv4 datagrams received with length errors

OSPLUS_ETH_MMC_RX_IPV4_HDRERR_

OCTETS

OSPLUS_ETH_MMC_RX_IPV4_NOPAY_FRMS

OSPLUS_ETH_MMC_RX_IPV4_NOPAY_

OCTETS

Number of bytes received in IPv4 datagrams with header errors

Number of IPv4 datagrams received without payload

Number of bytes received in IPv4 datagrams without payload

OSPLUS_ETH_MMC_RX_IPV4_UDSBL_

FRMS

OSPLUS_ETH_MMC_RX_IPV4_UDSBL_

OCTETS

Number of good IP datagrams received that had a

UDP payload with checksum disabled

Number of bytes received in a UDP segment that had the UDP checksum disabled

Number of good IPv6 frames received

Number of bytes received in good IPv6 datagrams

OSPLUS_ETH_MMC_RX_IPV6_GD_FRMS

OSPLUS_ETH_MMC_RX_IPV6_GD_OCTETS

OSPLUS_ETH_MMC_RX_IPV6_HDRERR_FRMS

Number of IPv6 datagrams received with length errors

OSPLUS_ETH_MMC_RX_IPV6_HDRERR_

OCTETS

Number of bytes received in IPv6 datagrams with header errors

OSPLUS_ETH_MMC_RX_IPV6_NOPAY_FRMS

OSPLUS_ETH_MMC_RX_IPV6_NOPAY_

OCTETS

OSPLUS_ETH_MMC_RX_JABBER_ERROR

OSPLUS_ETH_MMC_RX_LENGTH_ERROR

Number of IPv6 datagrams received without payload

Number of bytes received in IPv6 datagrams without payload

Number of frames received with jabber errors

Number of frames received with length errors

OSPLUS_ETH_MMC_RX_MULTICAST_

FRAMES_G

Number of good multicast frames received

OSPLUS_ETH_MMC_RX_OCTET_COUNT_G

OSPLUS_ETH_MMC_RX_OCTET_COUNT_GB

OSPLUS_ETH_MMC_RX_OUT_OF_RANGE_

TYPE

OSPLUS_ETH_MMC_RX_OVERSIZE_G

OSPLUS_ETH_MMC_RX_PAUSE_FRAMES

OSPLUS_ETH_MMC_RX_RUNT_ERROR

Number of bytes received, exclusive of preamble, only in good frames

Number of bytes received, exclusive of preamble, in good and bad frames

Number of frames received with length field not equal to the valid frame size

Number of frames received with length greater than max size

Number of pause frames received

Number of frames received with runt errors

384/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

Table 154.

Ethernet MMC statistics code defines in ioctls/ethernet.h (continued)

Defines Description

OSPLUS_ETH_MMC_RX_TCP_ERR_FRMS

OSPLUS_ETH_MMC_RX_TCP_ERR_OCTETS

OSPLUS_ETH_MMC_RX_TCP_GD_FRMS

OSPLUS_ETH_MMC_RX_TCP_GD_OCTETS

OSPLUS_ETH_MMC_RX_UDP_ERR_FRMS

OSPLUS_ETH_MMC_RX_UDP_ERR_OCTETS

Number of frames received with TCP payload and checksum error

Number of bytes received in a TCP segment with checksum error

Number of frames received with good TCP payload

Number of bytes received in good TCP segment

Number of frames received with UDP payload and checksum error

Number of bytes received in a UDP segment with checksum error

Number of frames received with good UDP payload

Number of bytes received in good UDP segment

OSPLUS_ETH_MMC_RX_UDP_GD_FRMS

OSPLUS_ETH_MMC_RX_UDP_GD_OCTETS

OSPLUS_ETH_MMC_RX_UNDERSIZE_G

OSPLUS_ETH_MMC_RX_VLAN_FRAMES_G

Number of frames received with length less than 64 bytes

OSPLUS_ETH_MMC_RX_UNICAST_FRAMES_G

Number of good unicast frames received

OSPLUS_ETH_MMC_RX_UNSUP_CTRL_FRMS

Number of unsupported control frames received

Number of good VLAN frames received

OSPLUS_ETH_MMC_RX_VLAN_FRAMES_GB

Number of good and bad VLAN frames received

OSPLUS_ETH_MMC_RX_WATCHDOG_ERROR

OSPLUS_ETH_MMC_TX_64_OCTETS_GB

OSPLUS_ETH_MMC_TX_65_TO_127_

OCTETS_GB

Number of frames received with error due to watchdog timeout errors

Number of good and bad frames transmitted with length 64 bytes.

Number of good and bad frames transmitted with length 65 to 127 bytes.

OSPLUS_ETH_MMC_TX_128_TO_255_

OCTETS_GB

OSPLUS_ETH_MMC_TX_256_TO_511_

OCTETS_GB

OSPLUS_ETH_MMC_TX_512_TO_1023_

OCTETS_GB

OSPLUS_ETH_MMC_TX_1024_TO_MAX_

OCTETS_GB

Number of good and bad frames transmitted with length 128 to 255 bytes.

Number of good and bad frames transmitted with length 256 to 511 bytes.

Number of good and bad frames transmitted with length 512 to 1023 bytes.

Number of good and bad frames transmitted with length 1024 bytes or more

Number of frames aborted during transmission

OSPLUS_ETH_MMC_TX_ABORTED_FRMS

OSPLUS_ETH_MMC_TX_BROADCAST_

FRAMES_G

OSPLUS_ETH_MMC_TX_BROADCAST_

FRAMES_GB

OSPLUS_ETH_MMC_TX_CARRIER_ERROR

Number of good broadcast frames transmitted

Number of good and bad broadcast frames transmitted

Number of frames aborted due to carrier sense errors

7702033 Rev 27 385/515

OSPlus ethernet drivers UM1150

Table 154.

Ethernet MMC statistics code defines in ioctls/ethernet.h (continued)

Defines Description

OSPLUS_ETH_MMC_TX_DEFERRED

OSPLUS_ETH_MMC_TX_EXCESS_COL

OSPLUS_ETH_MMC_TX_EXCESS_DEF

OSPLUS_ETH_MMC_TX_FRAME_

COUNT_B

OSPLUS_ETH_MMC_TX_FRAME_

COUNT_G

Number of bad frames transmitted

Number of good frames transmitted

OSPLUS_ETH_MMC_TX_FRAME_

COUNT_GB

Number of good and bad frames transmitted

OSPLUS_ETH_MMC_TX_LATE_COL

OSPLUS_ETH_MMC_TX_MULTICAST_

FRAMES_G

OSPLUS_ETH_MMC_TX_MULTICAST_

FRAMES_GB

OSPLUS_ETH_MMC_TX_MULTI_

COL_G

Number of aborted due to late collision

Number of good multicast frames transmitted

Number of good and bad multicast frames transmitted

Number of frames successfully transmitted after a multiple collision error

OSPLUS_ETH_MMC_TX_OCTET_

COUNT_G

OSPLUS_ETH_MMC_TX_OCTET_

COUNT_GB

OSPLUS_ETH_MMC_TX_PAUSE_FRAMES

Number of bytes transmitted, only in good frames

Number of bytes transmitted, in good and bad frames

Number of good pause frames transmitted

OSPLUS_ETH_MMC_TX_SINGLE_COL_G

Number of frames successfully transmitted after a single carrier error

OSPLUS_ETH_MMC_TX_UNDERFLOW_ERROR

Number of frames aborted due to underflow errors

OSPLUS_ETH_MMC_TX_UNICAST_FRAMES_G

Number of good unicast frames transmitted

OSPLUS_ETH_MMC_TX_UNICAST_FRAMES_

GB

OSPLUS_ETH_MMC_TX_VLAN_FRAMES_G

OSPLUS_ETH_MMC_UNSUPPORTED

OSPLUS_ETH_MMC_MAXIMUM_COUNTER

Number of frames successfully transmitted after deferred error

Number of frames aborted due to excessive collisions

Number of frames aborted due to excessive deferrals

Number of good and bad unicast frames transmitted

Number of good VLAN frames transmitted

Unsupported counter

Maximum number of counters

Table 155.

Ethernet loopback defines in ioctls/ethernet.h

Defines Description

OSPLUS_ETH_LOOPBACK_OFF

OSPLUS_ETH_LOOPBACK_MAC

OSPLUS_ETH_LOOPBACK_PHY

Disable loopback

Enable loopback at the MAC level

Enable loopback at the PHY level

386/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

Table 156.

Ethernet status defines in ioctls/ethernet.h

Defines

OSPLUS_ETH_STATUS_ENABLED

OSPLUS_ETH_STATUS_LINK_UP

OSPLUS_ETH_STATUS_LOOPBACK

OSPLUS_ETH_STATUS_PMT_PWR_ON

OSPLUS_ETH_STATUS_PMT_PWR_ACT

OSPLUS_ETH_STATUS_PMT_PWR_PAS

OSPLUS_ETH_STATUS_PMT_PWR_STBY

OSPLUS_ETH_STATUS_PMT_PWR_ANY

OSPLUS_ETH_STATUS_PMT_WOL

OSPLUS_ETH_STATUS_CRC_OFFLOAD

OSPLUS_ETH_STATUS_10MBPS

OSPLUS_ETH_STATUS_100MBPS

OSPLUS_ETH_STATUS_1000MBPS

OSPLUS_ETH_STATUS_SPEED

OSPLUS_ETH_STATUS_HDX

OSPLUS_ETH_STATUS_FDX

OSPLUS_ETH_STATUS_DUPLEX

OSPLUS_ETH_STATUS_ANEG_ON

Description

Ethernet device is enabled

Ethernet device has a valid link

Ethernet device is in loopback mode

Ethernet device power management power on mode

Ethernet device power management power in active standby mode

Ethernet device power management power in passive standby mode

Bitmask of power management standby modes.

Bitmask of power management mode

Ethernet device will enable wake-on-LAN mode when in power management mode

Ethernet device has enabled CRC offload

Ethernet device is in 10 Mbit/s mode

Ethernet device is in 100 Mbit/s mode

Ethernet device is in 1000 Mbit/s mode

Ethernet device speed mask

Ethernet device is in half duplex mode

Ethernet device is in full duplex mode

Ethernet device duplex mask

Ethernet device is auto-negotiation mode

Table 157.

Ethernet link defines in ioctls/ethernet.h

Defines

OSPLUS_ETH_LINK_10MBPS

OSPLUS_ETH_LINK_100MBPS

OSPLUS_ETH_LINK_1000MBPS

OSPLUS_ETH_LINK_SPEED

OSPLUS_ETH_LINK_HDX

OSPLUS_ETH_LINK_FDX

OSPLUS_ETH_LINK_DUPLEX

OSPLUS_ETH_LINK_ANEG_ON

OSPLUS_ETH_LINK_ALL

Description

Specify 10 Mbit/s mode

Specify 100 Mbit/s mode

Specify 1000 Mbit/s mode

Ethernet device speed mask

Specify half duplex mode

Specify full duplex mode

Ethernet device duplex mask

Specify auto-negotiation mode

Bitmask of all valid link settings

7702033 Rev 27 387/515

OSPlus ethernet drivers UM1150

Table 158.

Power management level settings defined in ioctls/ethernet.h

Defines Description

OSPLUS_ETH_PMT_LEVEL_ON

OSPLUS_ETH_PMT_LEVEL_ACTIVE_

STANDBY

OSPLUS_ETH_PMT_LEVEL_PASSIVE_

STANDBY

Set power to on

Set power to active standby (wake-on-LAN if configured)

Set power to passive standby (off)

Table 159.

Power management wake-on-LAN settings defined in ioctls/ethernet.h

Defines Description

OSPLUS_ETH_PMT_WOL_MODE_NONE

OSPLUS_ETH_PMT_WOL_MODE_MAGIC

OSPLUS_ETH_PMT_WOL_MODE_UCAST

Wake-on-LAN is not configured

Wake-on-LAN using magic packet

Wake-on-LAN using unicast packet

Table 160.

MMC (MAC Management Counter) settings defined in ioctls/ethernet.h

Defines Description

OSPLUS_ETH_MMC_CONFIG_RESET

OSPLUS_ETH_MMC_CONFIG_FREEZE

OSPLUS_ETH_MMC_CONFIG_ROLLOVER

OSPLUS_ETH_MMC_CONFIG_RESET_ON_

READ

OSPLUS_ETH_MMC_CONFIG_ALL_VALID

Reset the MMC counters

Freeze the MMC counters

Counters rollover when reach maximum

Counters are reset on read

Bitmask of valid MMC settings

Table 161.

CRC offload settings defined in ioctls/ethernet.h

Types Description

OSPLUS_ETH_CRC_OFFLOAD_NONE

OSPLUS_ETH_CRC_OFFLOAD_FULL

CRC offload is disabled

Full CRC offload is enabled

Table 162.

Types defined in ioctls/ethernet.h

Types

ethernet_addr_t ethernet_async_t ethernet_callback_t ethernet_hash_t ethernet_info_t ethernet_mcasts_t ethernet_mmc_t ethernet_pmt_wol_t ethernet_statistic_t

Description

Ethernet hardware address type

Ethernet device asynchronous I/O type

Ethernet standard callback type

Ethernet hash table type

Ethernet device information type

Ethernet multicast filter addresses type

Ethernet MMC statistics type

Ethernet power management wake-on-LAN type

Ethernet statistics type

388/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

h2heth driver common ioctls

The h2heth driver supports the subset of OSPlus common ioctls listed in

Table 163

.

Table 163.

Host-to-host device ethernet wrapper supported OSPlus common ioctls

Ioctl Description

OSPLUS_IOCTL_GET_RD_TIMEOUT

OSPLUS_IOCTL_GET_WR_TIMEOUT

OSPLUS_IOCTL_POST_WRITES

OSPLUS_IOCTL_SET_RD_TIMEOUT

OSPLUS_IOCTL_SET_WR_TIMEOUT

Return the timeout value for blocking read operations.

Return the timeout value for blocking write operations.

Specify if driver performs synchronous or asynchronous writes.

Set the timeout value for blocking read operations.

Set the timeout value for blocking write operations.

7702033 Rev 27 389/515

OSPlus ethernet drivers UM1150

Each ethernet driver supports a subset of the OSPlus ethernet ioctls, as described in the following subsections.

For a full description on how to use the ethernet ioctls with the device_ioctl() function

see

Section 10.12: Ethernet ioctl definitions on page 395

.

LAN91 driver ethernet ioctls

Table 164

lists the subset of OSPlus ethernet ioctls supported by the LAN91 driver.

Table 164.

LAN91 driver support ethernet ioctls

Ioctl Description

OSPLUS_IOCTL_ETH_SET_MAC

Set the MAC address

Get the MAC address

OSPLUS_IOCTL_ETH_GET_MAC

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS

Set the multicast filter addresses

OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS

Get the multicast filter addresses

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

Add one or more multicast filter addresses

OSPLUS_IOCTL_ETH_SET_MCAST_

HASH_TABLE

OSPLUS_IOCTL_ETH_GET_MCAST_

HASH_TABLE

Set the multicast hash table

Get the multicast hash table

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

OSPLUS_IOCTL_ETH_GET_PKT_FILTER

OSPLUS_IOCTL_ETH_SET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_STATUS

OSPLUS_IOCTL_ETH_GET_INFO

OSPLUS_IOCTL_ETH_ANEG_ON

OSPLUS_IOCTL_ETH_ANEG_OFF

OSPLUS_IOCTL_ETH_SET_LINK

OSPLUS_IOCTL_ETH_ASYNC_READ_

SUPPORTED

OSPLUS_IOCTL_ETH_ASYNC_WRITE_

SUPPORTED

OSPLUS_IOCTL_ETH_SET_MMC_CONFIG

OSPLUS_IOCTL_ETH_GET_MMC_CONFIG

OSPLUS_IOCTL_ETH_CLR_MMC_COUNTER

OSPLUS_IOCTL_ETH_GET_MMC_COUNTER

Set the ethernet packet filtering options

Get the current ethernet packet filtering options

Set loopback mode to MAC, PHY or off.

Get loopback mode.

Get the ethernet status

Return the ethernet device information (for example,

MTU and maximum number of multicast filters)

Turn auto-negotiation on

Turn auto-negotiation off

Set the link settings when auto-negotiation disabled

Determine if driver supports async read interface.

This is deprecated, use

OSPLUS_IOCTL_ETH_GET_INFO

.

Determine if driver supports async write interface.

This is deprecated, use

OSPLUS_IOCTL_ETH_GET_INFO

.

Set the MMC configuration

Get the MMC configuration

Clear a specific MMC counter value

Get a specific MMC counter value

390/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

LAN9x1x driver ethernet ioctls

Table 165

lists the subset of OSPlus ethernet ioctls supported by the LAN9x1x driver.

Table 165.

LAN9x1x driver support ethernet ioctls

Ioctl Description

OSPLUS_IOCTL_ETH_SET_MAC

Set the MAC address

OSPLUS_IOCTL_ETH_GET_MAC

Get the MAC address

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS

Set the multicast filter addresses

OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS

Get the multicast filter addresses

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

Add one or more multicast filter addresses

OSPLUS_IOCTL_ETH_SET_MCAST_

HASH_TABLE

OSPLUS_IOCTL_ETH_GET_MCAST_

HASH_TABLE

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

Set the multicast hash table

Get the multicast hash table

OSPLUS_IOCTL_ETH_GET_PKT_FILTER

OSPLUS_IOCTL_ETH_SET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_STATUS

Set the ethernet packet filtering options

Get the current ethernet packet filtering options

Set loopback mode to MAC, PHY or off.

Get loopback mode.

Get the ethernet status

OSPLUS_IOCTL_ETH_GET_INFO

OSPLUS_IOCTL_ETH_ANEG_ON

OSPLUS_IOCTL_ETH_ANEG_OFF

OSPLUS_IOCTL_ETH_SET_LINK

OSPLUS_IOCTL_ETH_ASYNC_READ_

SUPPORTED

OSPLUS_IOCTL_ETH_ASYNC_WRITE_

SUPPORTED

OSPLUS_IOCTL_ETH_SET_MMC_CONFIG

OSPLUS_IOCTL_ETH_GET_MMC_CONFIG

OSPLUS_IOCTL_ETH_CLR_MMC_COUNTER

OSPLUS_IOCTL_ETH_GET_MMC_COUNTER

Return the ethernet device information (for example,

MTU and maximum number of multicast filters)

Turn auto-negotiation on

Turn auto-negotiation off

Set the link settings when auto-negotiation disabled

Determine if driver supports async read interface.

This is deprecated, use

OSPLUS_IOCTL_ETH_GET_INFO

.

Determine if driver supports async write interface.

This is deprecated, use

OSPLUS_IOCTL_ETH_GET_INFO

.

Set the MMC configuration

Get the MMC configuration

Clear a specific MMC counter value

Get a specific MMC counter value

7702033 Rev 27 391/515

OSPlus ethernet drivers UM1150

STxMAC driver ethernet ioctls

Table 166

lists the subset of OSPlus ethernet ioctls supported by the STxMAC driver.

Table 166.

STxMAC driver support ethernet ioctls

Ioctl Description

OSPLUS_IOCTL_ETH_SET_MAC

Set the MAC address

OSPLUS_IOCTL_ETH_GET_MAC

Get the MAC address

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS

Set the multicast filter addresses

OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS

Get the multicast filter addresses

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

Add one or more multicast filter addresses

OSPLUS_IOCTL_ETH_SET_MCAST_

HASH_TABLE

OSPLUS_IOCTL_ETH_GET_MCAST_

HASH_TABLE

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

Set the multicast hash table

Get the multicast hash table

OSPLUS_IOCTL_ETH_GET_PKT_FILTER

OSPLUS_IOCTL_ETH_SET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_STATUS

Set the ethernet packet filtering options

Get the current ethernet packet filtering options

Set loopback mode to MAC, PHY or off.

Get loopback mode.

Get the ethernet status

OSPLUS_IOCTL_ETH_GET_INFO

OSPLUS_IOCTL_ETH_ANEG_ON

OSPLUS_IOCTL_ETH_ANEG_OFF

Return the ethernet device information (for example,

MTU and maximum number of multicast filters)

Turn auto-negotiation on

Turn auto-negotiation off

Set the link settings when auto-negotiation disabled

OSPLUS_IOCTL_ETH_SET_LINK

OSPLUS_IOCTL_ETH_ASYNC_READ_

SUPPORTED

OSPLUS_IOCTL_ETH_ASYNC_WRITE_

SUPPORTED

OSPLUS_IOCTL_ETH_ASYNC_READ

Determine if driver supports async read interface.

This is deprecated, use

OSPLUS_IOCTL_ETH_GET_INFO

.

Determine if driver supports async write interface.

This is deprecated, use

OSPLUS_IOCTL_ETH_GET_INFO

.

Read a packet through async interface

OSPLUS_IOCTL_ETH_ASYNC_WRITE

OSPLUS_IOCTL_ETH_SET_PMT_WOL

Write a packet through async interface

Set power management wake-on-LAN options

Get power management wake-on-LAN options

OSPLUS_IOCTL_ETH_GET_PMT_WOL

OSPLUS_IOCTL_ETH_SET_MMC_CONFIG

Set the MMC configuration

OSPLUS_IOCTL_ETH_GET_MMC_CONFIG

Get the MMC configuration

OSPLUS_IOCTL_ETH_SET_MMC_CALLBACK

Set the MMC callback function

OSPLUS_IOCTL_ETH_GET_MMC_CALLBACK

Get the MMC callback function

OSPLUS_IOCTL_ETH_CLR_MMC_COUNTER

Clear a specific MMC counter value

OSPLUS_IOCTL_ETH_GET_MMC_COUNTER

Get a specific MMC counter value

392/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

Table 166.

STxMAC driver support ethernet ioctls (continued)

Ioctl Description

OSPLUS_IOCTL_ETH_SET_CRC_OFFLOAD

OSPLUS_IOCTL_ETH_GET_CRC_OFFLOAD

Turn CRC offload (if supported) on or off

Get the current CRC offload status

h2heth driver ethernet ioctls

Table 167

lists the subset of OSPlus ethernet ioctls supported by the h2heth driver.

Table 167.

Host-to-host device ethernet wrapper supported ethernet ioctls

Ioctl Description

OSPLUS_IOCTL_ETH_GET_INFO

OSPLUS_IOCTL_ETH_GET_MAC

OSPLUS_IOCTL_ETH_GET_PKT_FILTER

OSPLUS_IOCTL_ETH_GET_STATUS

OSPLUS_IOCTL_ETH_SET_MAC

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

Return the ethernet device information (for example,

MTU)

Get the MAC address

Get the current ethernet packet filtering options

Get the ethernet status

Set the MAC address

Set the ethernet packet filtering options

10.11 Generic PHY driver ioctls

The OSPlus LAN91, LAN9x1x and STxMAC ethernet drivers do not support any of the common ioctls as defined in the include file ioctls/common.h and described in

Section 4.6: Device library header file: ioctls/common.h on page 140

.

Instead, the device library defines a set of ioctls specifically to be used by ethernet devices.

These ioctls are in the file ioctls/ethernet.h and are listed in

Table 151

. For the ioctl

definitions, see

Section 10.12 on page 395

.

Details of the ioctls supported by specific drivers are given in

Section 10.10.2: Ethernet driver ethernet ioctls on page 390

Table 168.

Ioctls defined in ioctls/phy.h

Ioctl

OSPLUS_IOCTL_PHY_PROBE

OSPLUS_IOCTL_PHY_RESET

OSPLUS_IOCTL_PHY_UPDATE

OSPLUS_IOCTL_PHY_GET_REG

OSPLUS_IOCTL_PHY_SET_REG

OSPLUS_IOCTL_PHY_GET_LINK

OSPLUS_IOCTL_PHY_SET_LINK

OSPLUS_IOCTL_PHY_GET_STATUS

OSPLUS_IOCTL_PHY_GET_LOOPBACK

Description

Probe for the PHY device

Reset the PHY device

Force a status update in the PHY

Read a PHY device register

Write a PHY device register

Get the currently configured PHY device link

Set the PHY device link

Get the PHY device status

Get the PHY device loopback status

7702033 Rev 27 393/515

OSPlus ethernet drivers UM1150

Table 168.

Ioctls defined in ioctls/phy.h (continued)

Ioctl

OSPLUS_IOCTL_PHY_SET_LOOPBACK

OSPLUS_IOCTL_PHY_GET_CALLBACK

OSPLUS_IOCTL_PHY_SET_CALLBACK

Description

Set the PHY device loopback status to on or off

Get the currently configured PHY device status change callback details

Set the PHY device status change callback

Table 169.

PHY power levels defined in ioctls/phy.h

Defines

OSPLUS_PHY_POWER_LEVEL_ON

OSPLUS_PHY_POWER_LEVEL_OFF

Description

Enable power to the PHY

Disable power to the PHY

Table 170.

loopback modes defined in ioctls/phy.h

Defines

OSPLUS_PHY_LOOPBACK_MODE_ON

OSPLUS_PHY_LOOPBACK_MODE_OFF

Description

Enable loopback mode

Disable loopback mode

Table 171.

Types defined in ioctls/phy.h

Types

phy_probe_t phy_reg_t phy_callback_t

Description

Type containing details required for probe

Type encapsulating register access details

Callback type

394/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

10.12 Ethernet ioctl definitions

These ethernet device specific ioctl definitions relate to the device_ioctl() call. See

device_ioctl on page 192

for more details.

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

Set the multicast filter addresses

Arguments:

Returns:

Description:

The address of an ethernet_mcasts_t structure containing the multicast addresses to add.

Returns 0 for success, -1 for failure.

This ioctl adds the multicast addresses specified in the passed-in ethernet_mcasts_t

structure to the multicast filter hash tables. The ethernet_mcasts_t

structure specifies the number of addresses to set and points to a buffer containing the multicast addresses.

If the multicast filters have been set with either

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

or

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS

, you must not directly manipulate the multicast hash table with the ioctl OSPLUS_IOCTL_ETH_SET_MCAST_HASH_TABLE.

If you do so, then the cached copy of the multicast addresses used by the

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

or

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS ioctls is zeroed.

See also:

OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS,

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS

7702033 Rev 27 395/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_ETH_ANEG_OFF

Turn off the ethernet driver link auto-negotiation feature

Arguments:

Returns:

Description:

See also:

None.

Returns 0 for success, -1 for failure.

This ioctl turns off the link auto-negotiation feature of the ethernet device if it is currently enabled. By default all ethernet devices have link auto-negotiation enabled.

If link auto-negotiation is disabled this ioctl does nothing. When auto-negotiation is disabled, the existing link settings are retained until they are set manually with the

OSPLUS_IOCTL_ETH_SET_LINK

ioctl. This ioctl has the same function as passing valid link settings to the OSPLUS_IOCTL_ETH_SET_LINK ioctl.

Note: When auto-negotiation is disabled, the ethernet driver sets the default link settings to

100Mbps full duplex.

OSPLUS_IOCTL_ETH_ANEG_ON, OSPLUS_IOCTL_ETH_SET_LINK

OSPLUS_IOCTL_ETH_ANEG_ON

Turn on the ethernet driver link auto-negotiation feature

Arguments:

Returns:

Description:

None.

Returns 0 for success, -1 for failure.

This ioctl turns on the link auto-negotiation feature of the ethernet device if it is currently disabled. By default all ethernet devices have link auto-negotiation enabled.

If link auto-negotiation is already enabled this ioctl does nothing. When autonegotiation is enabled, the existing link settings may change if the link autonegotiation determines that a faster link is possible. This ioctl has the same function as passing the OSPLUS_ETH_LINK_ANEGO_ON link setting to the

OSPLUS_IOCTL_ETH_SET_LINK

ioctl.

See also:

OSPLUS_IOCTL_ETH_ANEG_OFF, OSPLUS_IOCTL_ETH_SET_LINK

396/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

OSPLUS_IOCTL_ETH_ASYNC_READ

Read a packet using the asynchronous packet read interface

Arguments:

Returns:

Description:

The address of an ethernet_async_t structure

Returns 0 for success, -1 for failure.

This ioctl is used to initiate the reading of a packet from the network using the asynchronous read interface. If this ioctl succeeds, the ethernet_async_t structure passed in remains under the ownership of the ethernet driver until the operation completes, and the completion callback is called for that structure.

The ethernet_async_t structure has the following format: typedef struct ethernet_async_s { void (*callback)(struct ethernet_async_s*); unsigned char *buffer; size_t length; void *bufp; void *statep; unsigned int flags;

} ethernet_async_t;

All the fields must be set up before issuing the ioctl, and are explained in

Table 172

.

See also:

Table 172.

ethernet_async_t fields

callback buffer length bufp statep flags

Field name Description

Address of a function to call when the packet read completes

The address of the raw packet buffer to read in to

The length of the raw packet buffer

TCP/IP stack’s buffer structure pointer

Pointer for application use

Flags for the transfer such as use CRC offload

The buffer field should point to the memory where the packet is to be placed, and the length field should be set to the size of the largest expected packet. When the callback

routine is called, the length field should be examined to see how many bytes were actually read in.

Note: Some ethernet drivers assume that the memory up to one cache line immediately before and after the packet buffer is also part of the packet buffer. This allows the drivers to add any pre- or post-headers that may be required in-situ, and eliminates data copies. If this is the case, it is up to the application to ensure that the memory used by the TCP/IP stack for its packet buffers meets this requirement. Failure to do this may result in unpredictable behavior.

This does not apply to the STxMAC driver.

OSPLUS_IOCTL_ETH_ASYNC_READ_SUPPORTED,

OSPLUS_IOCTL_ETH_ASYNC_WRITE

7702033 Rev 27 397/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_ETH_ASYNC_READ_SUPPORTED

Determine if a driver supports the asynchronous packet read interface

Arguments:

Returns:

Description:

None

Returns 0 for success, -1 for failure.

This ioctl is used to determine if a driver supports the asynchronous packet read interface. If this ioctl succeeds, the driver supports this interface, otherwise it does not.

See also:

OSPLUS_IOCTL_ETH_ASYNC_WRITE_SUPPORTED,

OSPLUS_IOCTL_ETH_ASYNC_READ, OSPLUS_IOCTL_ETH_ASYNC_WRITE

OSPLUS_IOCTL_ETH_ASYNC_WRITE

Write a packet using the asynchronous packet write interface

Arguments:

Returns:

Description:

The address of an ethernet_async_t structure

Returns 0 for success, -1 for failure.

This ioctl is used to initiate the writing of a packet from the network using the asynchronous write interface. If this ioctl succeeds, the ethernet_async_t structure passed in remains under the ownership of the ethernet driver until the operation completes, and the completion callback is called for that structure.

The ethernet_async_t structure is defined in

OSPLUS_IOCTL_ETH_ASYNC_READ on page 397

. All the fields must be set up before issuing the ioctl, and are explained in

Table 172: ethernet_async_t fields on page 397

.

The buffer field should point to the memory containing the packet, and the length field should be set to the size of the packet. When the callback routine is called, the length field should be examined to see how many bytes were actually read in.

Note: Some ethernet drivers assume that the memory up to one cache line immediately before and after the packet buffer is also part of the packet buffer. This allows the drivers to add any pre- or post-headers that may be required in-situ, and eliminates data copies. If this is the case, it is up to the application to ensure that the memory used by the TCP/IP stack for its packet buffers meets this requirement. Failure to do this may result in unpredictable behavior.

This does not apply to the STxMAC driver.

See also:

OSPLUS_IOCTL_ETH_ASYNC_WRITE_SUPPORTED,

OSPLUS_IOCTL_ETH_ASYNC_READ

398/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

OSPLUS_IOCTL_ETH_ASYNC_WRITE_SUPPORTED

Determine if a driver supports the asynchronous packet write interface

Arguments:

Returns:

Description:

None

Returns 0 for success, -1 for failure.

This ioctl is used to determine if a driver supports the asynchronous packet write interface. If this ioctl succeeds, then driver supports this interface, otherwise it does not.

See also:

OSPLUS_IOCTL_ETH_ASYNC_READ_SUPPORTED,

OSPLUS_IOCTL_ETH_ASYNC_READ, OSPLUS_IOCTL_ETH_ASYNC_WRITE

OSPLUS_IOCTL_ETH_CLR_MMC_COUNTER

Reset an ethernet MMC counter to zero

Arguments:

Returns:

Description:

The address of an ethernet_mmc_t structure.

Returns 0 for success, -1 for failure.

This ioctl clears the ethernet device MMC counter whose code is specified in the ethernet_mmc_t

structure whose address is passed in.

The ethernet_mmc_t structure has the following format: typedef struct ethernet_mmc_s

{

unsigned int counter;

unsigned int value;

} ethernet_mmc_t;

The fields are explained in

Table 173

.

See also:

Table 173.

ethernet_mmc_t fields

Field name

counter value

Description

The code of the counter to retrieve

The value of the counter

Valid ethernet MMC counter codes are listed in

Table 154: Ethernet MMC statistics code defines in ioctls/ethernet.h on page 383

. Not all codes are valid for every ethernet driver.

OSPLUS_IOCTL_ETH_GET_MMC_COUNTER

7702033 Rev 27 399/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_ETH_GET_CRC_OFFLOAD

Get the CRC offload configuration

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with the CRC offload configuration.

Returns 0 for success, -1 for failure.

This ioctl retrieves the CRC offload configuration and populates the unsigned integer whose address is passed in. Valid values for the CRC offload can be found in

Table 161: CRC offload settings defined in ioctls/ethernet.h on page 388

.

See also:

OSPLUS_IOCTL_ETH_SET_CRC_OFFLOAD

OSPLUS_IOCTL_ETH_GET_INFO

Return ethernet device information

Arguments:

Returns:

Description:

The address of an ethernet_info_t structure to be populated with the information.

Returns 0 for success, -1 for failure.

This ioctl populates the ethernet_info_t structure whose address is passed in with the ethernet device information.

The ethernet_info_t structure has the following format: typedef struct ethernet_info_s

{

unsigned int max_packet_size;

unsigned int max_multicast_filters;

unsigned int features;

} ethernet_info_t;

The fields are explained in

Table 174

.

Table 174.

ethernet_info_t fields

Field name

max_packet_size max_multicast_filters features

Description

The maximum packet size supported by the device

The maximum number of multicasts supported by the device

A bitmask of features supported by the device. See

Table 151: Features defined in ioctls/ethernet.h on page 382

See also:

OSPLUS_IOCTL_ETH_GET_STATUS

400/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

OSPLUS_IOCTL_ETH_GET_LOOPBACK

Get the current ethernet loopback mode

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with the current loopback mode.

Returns 0 for success, -1 for failure.

This ioctl returns the current loopback mode. The ethernet device loopback values

are defined in

Table 155: Ethernet loopback defines in ioctls/ethernet.h on page 386

.

See also:

OSPLUS_IOCTL_ETH_SET_LOOPBACK

OSPLUS_IOCTL_ETH_GET_MAC

Return the interface MAC address

Arguments:

Returns:

Description:

The address of an ethernet_addr_t to hold the MAC address read from the ethernet interface.

Returns 0 for success, -1 for failure.

This ioctl reads the ethernet device MAC address into the ethernet_addr_t passed in.

See also:

OSPLUS_IOCTL_ETH_SET_MAC

OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS

Get the multicast filter addresses

Arguments:

Returns:

Description:

The address of an ethernet_mcasts_t structure to be populated with the multicast addresses.

Returns 0 for success, -1 for failure.

This ioctl retrieves the multicast addresses used to filter incoming packets and populate the ethernet_mcasts_t structure whose address is passed in.

The ethernet_mcasts_t structure has the following format: typedef struct ethernet_mcasts_s

{

unsigned int number;

ethernet_addr_t addresses[OSPLUS_MAX_ETH_MULTICASTS];

} ethernet_mcasts_t;

See also:

Table 175.

ethernet_multicast_t fields

number addresses

Field name Description

The number of multicast filters

A buffer to hold the multicast addresses. Each address is 6 bytes in length. Up to 64 addresses can be held.

The number of multicast address filters is returned in the number field.

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS,

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

7702033 Rev 27 401/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_ETH_GET_MCAST_HASH_TABLE

Get the multicast filters hash table

Arguments:

Returns:

Description:

See also:

The address of an ethernet_hash_t to hold the multicast filter hash table read form the ethernet interface.

Returns 0 for success, -1 for failure.

This ioctl reads the 8-byte ethernet device multicast filters hash table into the ethernet_hash_t

passed in.

OSPLUS_IOCTL_ETH_SET_MCAST_HASH_TABLE

OSPLUS_IOCTL_ETH_GET_MMC_CALLBACK

Get the MMC callback

Arguments:

Returns:

Description:

The address of an ethernet_callback_t structure to be populated with the callback information.

Returns 0 for success, -1 for failure.

This ioctl retrieves the currently set MMC callback and populates the ethernet_callback_t

whose address is passed in.

The ethernet_callback_t structure has the following format: typedef struct ethernet_callback_s

{ void *cookie; int (*callback) (void *, unsigned int);

} ethernet_callback_t;

The fields are explained in

Table 174

.

Table 176.

ethernet_callback_t fields

cookie callback

Field name Description

A cookie that is passed to the callback each time it executes

A pointer to a function that accepts a cookie as it’s parameter.

See also:

OSPLUS_IOCTL_ETH_SET_MMC_CALLBACK

402/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

OSPLUS_IOCTL_ETH_GET_MMC_CONFIG

Get the MMC configuration

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with the MMC configuration.

Returns 0 for success, -1 for failure.

This ioctl retrieves the MMC configuration and populates the unsigned integer whose address is passed in. The MMC configuration can be determined by performing a

logical AND of the bit mask returned and the values defined in

Table 160: MMC (MAC

Management Counter) settings defined in ioctls/ethernet.h on page 388

.

See also:

OSPLUS_IOCTL_ETH_SET_MMC_CALLBACK

OSPLUS_IOCTL_ETH_GET_MMC_COUNTER

Return an ethernet MMC counter

Arguments:

Returns:

Description:

The address of an ethernet_mmc_t structure.

Returns 0 for success, -1 for failure.

This ioctl reads a specified ethernet device MMC counter into the ethernet_mmc_t structure whose address is passed in. Before the ioctl is issued, the code for the ethernet MMC counter must be set in the ethernet_mmc_t structure. Valid codes

are found in

Table 154: Ethernet MMC statistics code defines in ioctls/ethernet.h on page 383

.

See also:

OSPLUS_IOCTL_ETH_CLR_MMC_COUNTER

OSPLUS_IOCTL_ETH_GET_PKT_FILTER

Get the ethernet packet filtering options

Arguments:

Returns:

Description:

The address of an unsigned integer to receive the current packet filter bit mask.

Returns 0 for success, -1 for failure.

This ioctl reads the ethernet device current packet filtering bit mask into the unsigned integer whose address is passed-in. The currently enabled packet filters can be

determined by AND’ing the bit mask returned with the values defined in

Table 153:

Ethernet packet filter type defines in ioctls/ethernet.h on page 383

.

See also:

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

7702033 Rev 27 403/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_ETH_GET_PMT_WOL

Get the current power management wake-on-LAN mode

Arguments:

Returns:

Description:

Definition:

The address of an ethernet_pmt_wol_t structure.

Returns 0 for success, -1 for failure.

This ioctl returns the currently configured power management wake-on-LAN mode.

The ethernet_pmt_wol_t structure passed in is filled in with the current wake-on-

LAN mode, cookie and callback to be executed when the ethernet device wakes.

The ethernet_pmt_wol_t structure has the following format: typedef struct ethernet_pmt_wol_s { unsigned int mode; void *cookie; void (*callback)(void*, unsigned int);

} ethernet_pmt_wol_t;

All the fields must be set up before issuing the ioctl, and are explained in

Table 177

.

Table 177.

ethernet_pmt_wol_t fields

mode cookie callback

Field name Description

Wake-on-LAN mode currently set. See

Table 159 on page 388

Pointer to application supplied cookie.

Address of a function to call when the ethernet device is woken. The callback is passed the cookie supplied in this structure and the wake mode.

See also:

OSPLUS_IOCTL_ETH_SET_PMT_WOL

OSPLUS_IOCTL_ETH_GET_STATUS

Get the ethernet device status

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with a bitmask of the current ethernet status.

Returns 0 for success, -1 for failure.

This ioctl reads the ethernet device status bit mask into the unsigned integer whose address is passed in. The ethernet device status can be determined by AND’ing the bit mask returned with the values defined in

Table 156: Ethernet status defines in ioctls/ethernet.h on page 387

.

See also:

OSPLUS_IOCTL_ETH_GET_INFO

404/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

OSPLUS_IOCTL_ETH_SET_CRC_OFFLOAD

Set the CRC offload configuration

Arguments:

Returns:

Description:

An unsigned integer specifying the CRC offload configuration.

Returns 0 for success, -1 for failure.

This ioctl configures the CRC offload configuration. Valid values for the CRC offload can be found in

Table 161: CRC offload settings defined in ioctls/ethernet.h on page 388

.

See also:

OSPLUS_IOCTL_ETH_GET_CRC_OFFLOAD

OSPLUS_IOCTL_ETH_SET_LINK

Manually configure the ethernet device link settings

Arguments:

Returns:

Description:

An unsigned integer containing the bitmask of ethernet link settings.

Returns 0 for success, -1 for failure.

This ioctl sets the ethernet device link settings to those specified in the unsigned integer bitmask passed in. The ethernet device link settings bitmask can be set by

ORing the values defined in

Table 159: Power management wake-on-LAN settings defined in ioctls/ethernet.h on page 388

. This ioctl can also be used to turn autonegotiation on or off. When enabling auto-negotiation, link speed and duplex settings cannot be specified.

See also:

OSPLUS_IOCTL_ETH_ANEG_ON, OSPLUS_IOCTL_ETH_ANEG_OFF,

OSPLUS_IOCTL_ETH_GET_STATUS

OSPLUS_IOCTL_ETH_SET_LOOPBACK

Turn on ethernet loopback mode

Arguments:

Returns:

Description:

An unsigned integer containing the loopback settings.

Returns 0 for success, -1 for failure.

This ioctl sets the ethernet device loopback mode to one of the values defined in

Table 155: Ethernet loopback defines in ioctls/ethernet.h on page 386

.

See also:

OSPLUS_IOCTL_ETH_GET_LOOPBACK

OSPLUS_IOCTL_ETH_SET_MAC

Set the interface MAC address

Arguments:

Returns:

Description:

See also:

Address of an ethernet_addr_t containing the MAC address to set.

Returns 0 for success, -1 for failure.

This ioctl sets the MAC address for the ethernet interface. No checking is performed on the validity of the MAC address.

OSPLUS_IOCTL_ETH_GET_MAC

7702033 Rev 27 405/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS

Set the multicast filter addresses

Arguments:

Returns:

Description:

The address of an ethernet_mcasts_t structure to contain the multicast addresses.

Returns 0 for success, -1 for failure.

This ioctl sets the multicast filter hash tables from the multicast addresses specified in the ethernet_mcasts_t structure whose address is passed-in. The ethernet_mcasts_t

structure should specify the number of addresses to set and point to a buffer containing the multicast addresses.

If the multicast filters have been set with either

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

or

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS

, you must not directly manipulate the multicast hash table with the ioctl OSPLUS_IOCTL_ETH_SET_MCAST_HASH_TABLE.

If you do so, then the cached copy of the multicast addresses used by the

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

or

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS ioctls is zeroed.

See also:

OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS,

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS

OSPLUS_IOCTL_ETH_SET_MCAST_HASH_TABLE

Set the multicast filters hash table

Arguments:

Returns:

Description:

The address of an ethernet_hash_t holding the multicast filters hash table to set for the ethernet interface.

Returns 0 for success, -1 for failure.

This ioctl sets the 8-byte ethernet device multicast filters hash table from the ethernet_hash_t

passed in. Do not use this ioctl if the application already uses the OSPLUS_IOCTL_ETH_ADD_MCAST_FILTER or

OSPLUS_IOCTL_ETH_SET_MCAST_FILTER ioctls.

See also:

OSPLUS_IOCTL_ETH_GET_MCAST_HASH_TABLE

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

Set the ethernet packet filtering options

Arguments:

Returns:

Description:

An unsigned integer containing the bit mask of specified packet filtering options.

Returns 0 for success, -1 for failure.

This ioctl sets the ethernet device packet filtering options from the bit mask contained in the unsigned integer passed in. For valid packet filtering options to be used to build the bit mask see

Table 153: Ethernet packet filter type defines in ioctls/ethernet.h on page 383

.

See also:

OSPLUS_IOCTL_ETH_SET_PKT_FILTER

406/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

OSPLUS_IOCTL_ETH_SET_PMT_WOL

Set the power management wake-on-LAN mode

Arguments:

Returns:

Description:

The address of an ethernet_pmt_wol_t structure.

Returns 0 for success, -1 for failure.

This ioctl is used to configure the power management wake-on-LAN mode. The ethernet_pmt_wol_t

structure passed in contains the wake-on-LAN mode to set and callback to be executed when the ethernet device wakes. If disabling wake-on-

LAN, then neither cookie nor callback need be specified.

Definition:

Note: Power management wake-on-LAN mode is designed to be used only when setting the power level to OSPLUS_ETH_PM_LEVEL_ACTIVE_STANDBY.

The ethernet_pmt_wol_t structure has the following format: typedef struct ethernet_pmt_wol_s { unsigned int mode; void *cookie; void (*callback)(void*, unsigned int);

} ethernet_pmt_wol_t;

All the fields must be set up before issuing the ioctl, and are explained in

Table 178

.

Table 178.

ethernet_pmt_wol_t fields

mode cookie callback

Field name Description

wake-on-LAN mode to set. See

Table 159 on page 388

Pointer to application supplied cookie.

Address of a function to call when the ethernet device is woken. The callback is passed the cookie supplied in this structure and the wake mode.

See also:

OSPLUS_IOCTL_ETH_GET_PMT_WOL

7702033 Rev 27 407/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_ETH_SET_MMC_CALLBACK

Set the MMC callback

Arguments:

Returns:

Description:

The address of an ethernet_callback_t structure to be populated with the callback information.

Returns 0 for success, -1 for failure.

This ioctl sets MMC callback from the ethernet_callback_t, the address of which is passed in. The MMC callback executes when any of the MMC counters reaches half of the maximum value to either read the MMC counters or reset them.

The callback is executed in interrupt context so should not perform much processing.

See also:

OSPLUS_IOCTL_ETH_GET_MMC_CALLBACK

OSPLUS_IOCTL_ETH_SET_MMC_CONFIG

Set the MMC configuration

Arguments:

Returns:

Description:

An unsigned integer containing a bitmask of the MMC configuration settings.

Returns 0 for success, -1 for failure.

This ioctl sets the ethernet device MMC configuration options from the bit mask contained in the unsigned integer passed in. For valid MMC configuration options to be used to build the bit mask see

Table 160: MMC (MAC Management Counter) settings defined in ioctls/ethernet.h on page 388

.

See also:

OSPLUS_IOCTL_ETH_GET_MMC_CALLBACK

408/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

10.13 Generic PHY ioctl definitions

These ethernet device specific ioctl definitions relate to the device_ioctl() call. See

device_ioctl on page 192

for more details.

OSPLUS_IOCTL_PHY_PROBE

Probe for a PHY device

Arguments:

Returns:

Description:

Description:

The address of an phy_probe_t structure.

Returns 0 for success, -1 for failure.

This ioctl probes a PHY device to ensure there is some hardware present. The phy_probe_t

structure whose address is passed in contains a cookie and pointers to functions supplied by an ethernet driver that gets and sets the PHY registers.

The phy_probe_t structure has the following format: typedef struct phy_probe_t { void *cookie; int (*get_reg_fn) (void *, int, int, unsigned short *); int (*set_reg_fn) (void *, int, int, unsigned short *);

} phy_probe_t;

All the fields must be set up before issuing the ioctl. They are explained in

Table 179

.

Table 179.

phy_probe_t fields

Field name

cookie get_reg_fn set_reg_fn

Description

Pointer to application supplied cookie.

Address of a function to call in order to read a PHY register.

Address of a function to call in order to write a PHY register.

OSPLUS_IOCTL_PHY_RESET

Reset the PHY

Arguments:

Returns:

Description:

None.

Returns 0 for success, -1 for failure.

This ioctl resets the PHY device.

7702033 Rev 27 409/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_PHY_UPDATE

Force an update of the PHY link status

Arguments:

Returns:

Description:

See also:

None.

Returns 0 for success, -1 for failure.

This ioctl forces the PHY link status to be updated.

OSPLUS_IOCTL_PHY_GET_STATUS

OSPLUS_IOCTL_PHY_GET_REG

Read a PHY register

Arguments:

Returns:

Description:

The address of an phy_reg_t structure containing the register offset to read.

Returns 0 for success, -1 for failure.

This ioctl reads the PHY register with the offset specified in the phy_reg_t structure whose address is passed in. The value read is also written to the structure. The phy_reg_t

structure has the following format: typedef struct phy_reg_t { unsigned short offset; unsigned short value;

} phy_reg_t;

All the fields must be set up before issuing the ioctl. They are explained in

Table 180

.

Table 180.

phy_reg_t fields

Field name

offset value

Description

Offset of the PHY register to read

Value of the PHY register read

See also:

OSPLUS_IOCTL_PHY_SET_REG

OSPLUS_IOCTL_PHY_SET_REG

Write a PHY register

Arguments:

Returns:

Description:

The address of an phy_reg_t structure containing the register offset and value to write.

Returns 0 for success, -1 for failure.

This ioctl writes the PHY register whose offset is specified in the phy_reg_t structure whose address is passed in with the specified value.

See also:

OSPLUS_IOCTL_PHY_GET_REG

410/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

OSPLUS_IOCTL_PHY_GET_LINK

Get the current link settings

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with a bitmask of the current link settings.

Returns 0 for success, -1 for failure.

This ioctl reads the PHY device link bit mask into the unsigned integer whose address is passed in. The PHY device link can be determined by performing a logical AND of the bit mask returned with the values defined in

Table 157: Ethernet link defines in ioctls/ethernet.h on page 387

.

See also:

OSPLUS_IOCTL_PHY_SET_LINK, OSPLUS_IOCTL_PHY_GET_STATUS

OSPLUS_IOCTL_PHY_SET_LINK

Manually configure the link settings

Arguments:

Returns:

Description:

An unsigned integer containing the bitmask of link settings.

Returns 0 for success, -1 for failure.

This ioctl sets the PHY device link settings to those specified in the unsigned integer bitmask passed in. The ethernet device link settings bitmask can be set by performing

a logical OR of the values defined in

Table 157: Ethernet link defines in ioctls/ethernet.h on page 387

. This ioctl can also be used to turn auto-negotiation on or off. When enabling auto-negotiation, link speed and duplex settings cannot be specified.

See also:

OSPLUS_IOCTL_PHY_GET_LINK, OSPLUS_IOCTL_PHY_GET_STATUS

OSPLUS_IOCTL_PHY_GET_STATUS

Get the PHY status

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with a bitmask of the current status.

Returns 0 for success, -1 for failure.

This ioctl reads the PHY device status bit mask into the unsigned integer whose address is passed in. The ethernet device status can be determined by performing a

logical AND of the bit mask returned with the values defined in

Table 156: Ethernet status defines in ioctls/ethernet.h on page 387

.

See also:

OSPLUS_IOCTL_PHY_UPDATE, OSPLUS_IOCTL_PHY_GET_LINK

7702033 Rev 27 411/515

OSPlus ethernet drivers UM1150

OSPLUS_IOCTL_PHY_GET_LOOPBACK

Get the current loopback mode

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with the current loopback mode.

Returns 0 for success, -1 for failure.

This ioctl returns the current loopback mode. The ethernet device loopback values

are defined in

Table 170: loopback modes defined in ioctls/phy.h on page 394

See also:

OSPLUS_IOCTL_PHY_SET_LOOPBACK

OSPLUS_IOCTL_PHY_SET_LOOPBACK

Turn on or off loopback mode

Arguments:

Returns:

Description:

An unsigned integer containing the loopback settings.

Returns 0 for success, -1 for failure.

This ioctl sets the PHY device loopback mode to one of the values are defined in

Table 170: loopback modes defined in ioctls/phy.h on page 394

.

See also:

OSPLUS_IOCTL_PHY_GET_LOOPBACK

OSPLUS_IOCTL_PHY_GET_CALLBACK

Get the current status change callback details

Arguments:

Returns:

Description:

The address of an phy_callback_t structure to populate with the current status change callback details.

Returns 0 for success, -1 for failure.

This ioctl returns the current status change callback details by populating the phy_callback_t

structure whose address is passed in. The phy_callback_t structure has the following format: typedef struct phy_callback_s { void *cookie; int (*callback_fn) (void *cookie, unsigned int status);

} phy_callback_t;

All the fields must be set up before issuing the ioctl, and are explained in

Table 171

.

Table 181.

phy_callback_t fields

Field name

cookie callback_fn

Description

Application specific cookie

Pointer to function to be executed on callback

See also:

OSPLUS_IOCTL_PHY_SET_CALLBACK

412/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

OSPLUS_IOCTL_PHY_SET_CALLBACK

Set the status change callback

Arguments:

Returns:

Description:

The address of an phy_callback_t structure containing status change callback details.

Returns 0 for success, -1 for failure.

This ioctl sets the status change callback using the details specified in the phy_callback_t

structure whose address is passed in. The status change callback is executed every time the PHY device detects link status changes.

See also:

OSPLUS_IOCTL_PHY_GET_CALLBACK

7702033 Rev 27 413/515

OSPlus ethernet drivers UM1150

10.14 Ethernet driver function definitions

Every OSPlus ethernet driver has just one directly callable function. This function is the driver initialize function.

lan91_initialize

Initialize the LAN91 driver

Definition:

Arguments:

Returns:

Description:

int lan91_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the LAN91 driver on a supported platform. When initialized, the

LAN91 driver creates and registers a new ethernet device instance with the device library.

414/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

10.14.2 LAN9x1x driver function definitions lan9x1x_initialize

Initialize the LAN9x1x driver

Definition:

Arguments:

Returns:

Definition:

int lan9x1x_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the LAN9x1x driver on a supported platform. When initialized, the

LAN9x1x driver creates and registers a new ethernet device instance with the device library.

7702033 Rev 27 415/515

OSPlus ethernet drivers UM1150

stmac_initialize

Initialize the STxMAC driver for use with STMAC device

Definition:

Arguments:

Returns:

Description:

int stmac_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the STxMAC driver on a supported platform for use with

STMAC/STMAC110 devices. When initialized, the STxMAC driver creates and registers a new ethernet device instance with the device library.

stgmac_initialize

Initialize the STxMAC driver for use with STGMAC device

Definition:

Arguments:

Returns:

Description:

int stgmac_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the STxMAC driver on a supported platform for use with STGMAC devices. When initialized, the STxMAC driver creates and registers a new ethernet device instance with the device library.

416/515 7702033 Rev 27

UM1150 OSPlus ethernet drivers

h2heth_initialize

Initialize the host-to-host ethernet driver

Definition:

Arguments:

Returns:

Description:

int h2heth_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the host-to-host ethernet driver on a supported platform. The USB host-to-host class driver is treated as a USB ethernet device by using the h2heth ethernet wrapper driver. When initialized, the host-to-host ethernet driver creates and registers a new ethernet device instance with the device library.

7702033 Rev 27 417/515

OSPlus ethernet drivers UM1150

10.15 Generic PHY driver function definitions

The OSPlus ethernet generic PHY driver has just one directly callable function. This function is the driver initialize function.

phy_initialize

Initialize the generic PHY driver

Definition:

Arguments:

Returns:

Description:

int phy_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the generic PHY driver on a supported platform. When initialized, the generic PHY driver creates and registers a new PHY device instance with the device library.

418/515 7702033 Rev 27

UM1150

11 OSPlus storage drivers

OSPlus storage drivers

11.1 Storage drivers overview

OSPlus has storage drivers for ATA, SATA, RAM disk and SD/MMC devices, allowing applications to permanently or temporarily store and retrieve data on STMicroelectronics hardware platforms.

The OSPlus storage drivers all adhere to the OSPlus driver model, which is a platform independent library built for all supported CPUs. The ATA and SATA drivers are supported only on platforms based on the STi7100 and STi7109 CPUs. For example, STb7100-

Mboard (mb411) and STb7109-Ref board (mb442). The SD/MMC driver is supported on the

STi5206 and STi5289 platforms. The RAM disk driver has no hardware dependencies and is available for any ARM, ST20, ST40 or ST200 based platform.

Each storage driver provides an interface to a storage device to be used either with the LVM and E2FS or FAT file systems. Alternatively, they can be used as a raw block device.

11.2 Storage drivers supported devices

The OSPlus ATA and SATA drivers support only hard disks using the ATA command set. The

ATA driver supports up to two hard disks attached to each ATA controller; the SATA driver supports only one hard disk attached to each SATA controller. The hard disks must at a minimum support PIO mode 4. The ATA and SATA drivers have been tested using a variety of Maxtor and Seagate hard disks.

The OSPlus ATA and SATA drivers do not support removable drives based on the ATAPI command set (such as CD/DVD-ROM drives). Support for these devices is provided in future releases.

The RAM disk driver is purely a software device which can be configured to present a storage device with user defined characteristics. This allows it to emulate a fixed or removable disk or a totally custom device type.

The SD/MMC driver supports SD cards adhering to SD specification v2.0 (SD cards with capacity of up to 2GB and SDHC cards with capacity from 4GB to 32GB) and MMC cards and eMMC devices adhering to MMC specification v4.4. There is no support for SDIO cards.

11.3 Storage drivers performance

When designing the storage needs for an application, the varied performance of the OSPlus storage drivers should be considered. The ATA driver allows access large amounts of data on disk, but due to the lack of DMA support, manages PIO data transfer performances of only about 4 Mbyte/s.

The SATA driver allows access to large amounts of data on disk and provides support for the

STb7100/STb7109 DMA controller delivering upwards of 40 Mbyte/s on data transfers.

The RAM disk driver uses system memory and therefore should only be used to on small amounts of temporary data. The performance on an ST40 based system is around

70 Mbyte/s.

7702033 Rev 27 419/515

OSPlus storage drivers UM1150

The performance of the SD/MMC driver depends on the speed of the card being used. On a class 6 SDHC card you can expect a transfer rate in excess of 12 Mbytes/s.

11.4 Storage driver configuration

The ATA and SATA storage drivers can be manually configured for details such as base address and interrupt information. These configurations are used to override platform specific defaults or allow the drivers to function on a platform that does not yet have a specific set of registry settings. The RAM disk driver provides a comprehensive API that can be used to create RAM disks of differing sizes and types.

The driver configuration options are read during driver initialization. Therefore, all configurations must be specified before the storage driver initialize function is called. Only configurations specified before the driver has been initialized are used.

To specify a storage driver configuration option, a registry key must be written. The name of the registry key for a specific option is given by configuration option defines, found in each storage driver include file. The registry path at which the registry keys are written can also be found in the storage driver include file.

registry_key_set (

ATA_CONFIG_PATH"/0",

ATA_CONFIG_BASE,

(void *) 0xb8000000);

Examples of how to create registry settings for each of the OSPlus storage drivers can be found in the OSPlus custom_registry example.

11.4.1 ATA driver registry options

A summary of the ATA driver registry options are shown in

Section 11.8: Storage driver ioctls on page 431

.

The ATA driver options are stored in the registry at the node specified by

ATA_CONFIG_PATH

. The ATA driver supports multiple controllers, this node has a registry key ATA_CONFIG_HOST_COUNT. This key contains an integer that specifies how many controllers there are settings for. The settings for each controller are stored in a sub-node with the name consisting of an integer starting from 0. For example, the settings for controller 0 are stored at registry path ATA_CONFIG_PATH"/0" and for controller 1 at

ATA_CONFIG_PATH"/1"

.

The configuration options defined in ata.h are shown in

Table 182

.

420/515 7702033 Rev 27

UM1150 OSPlus storage drivers

Table 182.

Configuration options defined in ata.h

Define

ATA_CONFIG_INIT_FN

ATA_CONFIG_DEINIT_FN

ATA_CONFIG_BASE

ATA_CONFIG_REG_ALT_STATUS

ATA_CONFIG_REG_COMMAND

ATA_CONFIG_REG_DATA_PORT

ATA_CONFIG_REG_DATA

ATA_CONFIG_REG_DEVICE

ATA_CONFIG_REG_CONTROL

ATA_CONFIG_REG_ERROR

ATA_CONFIG_REG_FEATURES

ATA_CONFIG_REG_LBA_HIGH

ATA_CONFIG_REG_LBA_LOW

ATA_CONFIG_REG_LBA_MID

ATA_CONFIG_REG_SECTOR_COUNT

ATA_CONFIG_REG_STATUS

Description

Specifies a pointer to initialize the ATA controller hardware according to the following prototype: int ata_config_init_fn (void *arg1, void

*arg2);

This performs the steps required to initialize the system for use with the ATA controller, including initializing any system registers, and performing any required interrupt routing. The arguments to this function are not used.

Successful initialization of the ATA controller hardware returns 0 . Otherwise -1 .

Specifies (if supplied), a pointer to a function that can de-initialize the ATA controller hardware according to the prototype, ATA_CONFIG_INIT_FN. The arguments to this function are not used.

Successful de-initialization of the ATA controller hardware returns 0 . Otherwise -1 .

Specifies the base address at which the ATA controller is mapped into memory.

Specifies the address at which the ATA controller alternative status register is mapped

Specifies the address at which the ATA controller command register is mapped.

Specifies the address at which the ATA controller data port is mapped.

Specifies the address at which the ATA controller data register is mapped.

Specifies the address at which the ATA controller device register is mapped.

Specifies the address at which the ATA controller control register is mapped.

Specifies the address at which the ATA controller error register is mapped.

Specifies the address at which the ATA controller features register is mapped.

Specifies the address at which the ATA controller LBA high register is mapped.

Specifies the address at which the ATA controller LBA low register is mapped.

Specifies the address at which the ATA controller LBA mid register is mapped.

Specifies the address at which the ATA controller sector count register is mapped.

Specifies the address at which the ATA controller status register is mapped.

7702033 Rev 27 421/515

OSPlus storage drivers UM1150

Table 182.

Configuration options defined in ata.h (continued)

Define Description

ATA_CONFIG_INTR

ATA_CONFIG_ALT_INTR

ATA_CONFIG_INTR_LEVEL

ATA_CONFIG_INTR_TRIGGER

ATA_CONFIG_INTR

ATA_CONFIG_PIO_TIMING_FN

ATA_CONFIG_DMA_TIMING_FN

ATA_CONFIG_DMA_CAPABLE

Specifies the interrupt that detects ATA controller interrupts. If this option is not set, the option

ATA_CONFIG_ALT_INTR

must be specified.

ATA controller alternative interrupt

On OS20 based systems, these specify the interrupt trigger to program for the ATA controller interrupts. For

OS21 based systems it should be set to

0

.

ATA controller interrupt level for OS20 based systems

Specifies a pointer to a function to set the device

PIO timings according to the following prototype: int ata_pio_timing_fn (unsigned int mode)

Successful setting returns 0 . Otherwise, -1 is returned.

This option need not be specified when there are no timings to set.

Specifies a pointer to a function to set DMA timings according to the following prototype: int ata_dma_timing_fn (unsigned int mode);

This function initializes the DMA timings for the mode specified as a parameter. This option need not be specified if there are no timings to set.

Successful setting returns 0 . Otherwise, -1 is returned.

Specifies if the ATA controller is DMA capable, but should always be set to 0 as, the ATA driver does not support DMA.

11.4.2 SATA driver registry options

The SATA driver options are all stored in the registry at the node whose path is specified by

SATA_CONFIG_PATH

. As the SATA driver supports multiple controllers, this node has a registry key named SATA_CONFIG_HOST_COUNT. This key contains an integer specifying the number of controllers for which there are settings. The settings for each controller are stored in a sub-node with the name consisting of an integer starting from 0. For example, the settings for controller 0 are stored at registry path SATA_CONFIG_PATH"/0" and for controller 1 at SATA_CONFIG_PATH"/1".

422/515 7702033 Rev 27

UM1150 OSPlus storage drivers

Table 183.

Configuration options defined in sata.h

Define

SATA_CONFIG_INIT_FN

SATA_CONFIG_DEINIT_FN

SATA_CONFIG_BASE

SATA_CONFIG_ALT_INTR

SATA_CONFIG_INTR_LEVEL

SATA_CONFIG_INTR_TRIGGER

SATA_CONFIG_INTR

SATA_CONFIG_DMA_CHANNELS

Description

This specifies a pointer to a function called to initialize the

SATA controller hardware. The function should have the following prototype: int sata_config_init_fn (unsigned int

*phycr, unsigned int *only_32bit)

The function initializes the system for use with the SATA controller. Necessary steps include initializing any system registers, performing any required interrupt routing and setting the parameters passed-in to the current platform chip revision specific values.

The phycr parameter sets the SATA PHY Control Register initialization value.

The parameter only_32bit

is set to

1

when the current platform supports only 32-bit reads to the SATA shadow registers. Successful setting of the SATA controller hardware returns 0 . Otherwise, -1 is returned.

When supplied, this option specifies a pointer to a function to de-initialize the SATA controller hardware. The function should have the same prototype as

SATA_CONFIG_INIT_FN

, except the parameters passedin are not used. Successful de-initialization of the SATA controller hardware returns 0 . Otherwise, -1 is returned.

Specifies the interrupt used to detect SATA controller interrupts. If this option is not set the

SATA_CONFIG_ALT_INTR

option must be specified.

Specifies an alternate interrupt to be used on some platforms to detect SATA controller interrupts. An alternate interrupt need only be specified when SATA_CONFIG_INTR is not set.

These specify the interrupt level for the SATA controller interrupts on OS20 based systems. For OS21 based systems it should be set to 0 .

SATA controller interrupt level for OS20 based systems.

This specifies the number of DMA channels available on the

SATA controller and is optional. When not specified the default number of channels is used.

7702033 Rev 27 423/515

OSPlus storage drivers UM1150

11.4.3 SD/MMC driver registry options

All the SD/MMC driver options are stored in the registry at the node with a path specified by

SDMMC_CONFIG_PATH

. The SD/MMC driver supports multiple controllers, so this node has a registry key named SDMMC_CONFIG_COUNT. This key contains an integer specifying the number of controllers for which there are settings. The settings for each controller are stored in a sub-node with the name consisting of an integer starting from 0. For example, the settings for controller 0 are stored at registry path SDMMC_CONFIG_PATH"/0" and for controller 1 at SDMMC_CONFIG_PATH"/1"

Table 184: Configuration options defined in sdmmc.h

Define Description

SDMMC_CONFIG_INIT_FN

SDMMC_CONFIG_BASE

SDMMC_CONFIG_INTR

SDMMC_CONFIG_ALT_INTR

SDMMC_CONFIG_INTR_LEVEL

SDMMC_CONFIG_INTR_TRIGGER

SDMMC_CONFIG_INTR_ENB_FN

This specifies a pointer to a function called to initialize the

SD/MMC controller hardware. The function should have the following prototype: int sdmmc_config_init_fn (void)

The function initializes the system for use with the SD/MMC controller. Necessary steps include initializing any system registers, performing any required interrupt routing and setting the parameters passed-in to the current platform chip revision specific values.

Successful initialization of the SD/MMC controller hardware returns 0 . Otherwise, -1 is returned.

Specifies the interrupt used to detect SD/MMC controller interrupts. If this option is not set the

SDMMC_CONFIG_ALT_INTR

option must be specified.

SD/MMC controller interrupt level for OS20 based systems.

Specifies an alternate interrupt to be used on some platforms to detect SD/MMC controller interrupts. An alternate interrupt need only be specified when

SDMMC_CONFIG_INTR

is not set.

These specify the interrupt level for the SD/MMC controller interrupts on OS20 based systems. For OS21 based systems it should be set to 0 .

This optionally specifies a pointer to a function called to enable the SD/MMC controller interrupt hardware. The function should have the following prototype: int sdmmc_config_intr_enb_fn (void)

The function enables the SD/MMC controller interrupt.

Successful enabling of the SD/MMC controller interrupt returns 0 . Otherwise, -1 is returned.

424/515 7702033 Rev 27

UM1150 OSPlus storage drivers

11.5 Storage drivers initialization

The ATA, SATA and SD/MMC drivers require explicit initialization; the RAM disk driver is implicitly initialized when creating a RAM disk using the driver create API. The ATA, SATA and SD/MMC drivers are initialized by calling the functions ata_initialize(), sata_initialize()

and sdmmc_initialize() respectively.

On initialization, the ATA and SATA drivers allocate and initialize the internal state. The driver then queries the registry to get the number of ATA or SATA controllers supported on the current platform. If a controller is supported, the registry is queried again; this time, to read the settings particular to the controller. If the current platform does not support any controllers, the initialization fails and an error is returned through errno. If the current platform supports the controller, the controller hardware is initialized.

After initializing the ATA or SATA controller, a probe is performed to determine what devices are attached. For an ATA controller, both master and slave devices are probed. SATA supports only a master device. The driver identifies the type of device found and if it is supported. A supported device is registered as a block device with the device library using the prefix /ata/hdisk for devices attached to an ATA controller. The prefix /sata/hdisk is used for devices attached to an SATA controller, and postfixed with the device instance number. The first attached device is named /ata/hdisk0, the second /ata/hdisk1 and so on.

ATA and SATA drivers do not support hot plugging. If the device is not attached when the driver is initialized it will never be detected.

When specifying a RAM disk name, the caller must ensure the name is not in use.

The SD/MMC driver supports hot plugging. When initialized, a removable media storage device is created whenever a card is inserted. If the card inserted is a SD card, the device has the prefix /sd/rdisk and the postfix of the device instance. If the card inserted is a

MMC card, the device has the prefix /mmc/rdisk and the postfix of the device instance.

11.6 Storage drivers usage model

11.6.1 ATA and SATA driver usage model

The device block size and number of blocks are found by opening the ATA or SATA device and issuing the OSPlus common ioctls OSPLUS_IOCTL_BLOCK_SIZE and

OSPLUS_IOCTL_NUM_BLOCKS

. Data can then be read or written using the device_block_read()

and device_block_write() functions. The number of blocks on the device should be used to ensure the read or write does not exceed the number of blocks on the device. Reads or writes must also be multiples of the device block size.

After each read or write, the return code must be checked for error. On error errno is set. If errno

is set to ENODEV, the mass storage class device has been unplugged and all further reads and writes are prevented. The device can only be closed.

Each read or write is handled in the most efficient manner.

●

If the user buffer passed-in is determined to be uncached memory (using the OSPlus

API described in

Section 2.12: Uncached memory recording on page 19

) and 32-bit aligned, it is used directly.

●

If the buffer is not in uncached memory, but is cache line aligned, the buffer is purged from the cache and used directly during the read or write.

7702033 Rev 27 425/515

OSPlus storage drivers UM1150

In all other cases, the user buffer must be staged through an internal buffer. So for maximum efficiency, all read and write buffers should be 32-bit aligned and located in a region of uncached memory registered with the OSPlus uncached memory manager. If this is not possible, buffers should at least be allocated with the cache safe allocator, described in

Section 2.9: Cache management on page 18

.

Generally, the raw ATA or SATA attached device is not accessed directly. Most often it contains several partitions each with a file system. The LVM creates logical volumes for each partition on the device. These volumes are mounted with VFS as either a FAT or E2FS file system and all file input and output handled by the VFS.

If the LVM does not detect any partitions on the device, it is up to the application to create or mount a file system on the device.

11.6.2 RAM disk driver usage model

A RAM disk is created using RAM disk driver create API functions. The simplest of the create functions is ramdisk_create(). This creates a RAM disk of type

OSPLUS_DEVICE_TYPE_RAMDISK_STORAGE

and registers it with the OSPlus device library. The caller may optionally specify a unique name for the RAM disk. If no name is specified a default name is provided. The default name begins with the prefix

/ramdisk/disk

, and postfixed with the device instance number. The first device is

/ramdisk/disk0

, the second /ramdisk/disk1 and so-on. The caller may also optionally specify a pointer to the memory to use for the RAM disk. This memory must be large enough to prevent data corruption. If no memory pointer is specified then a memory buffer large enough for the RAM disk is allocated from the memory heap.

The created RAM disk can be used in the same way as an ATA or SATA attached device with the following enhancements. The RAM disk can be saved to an image file on the host file system using the function ramdisk_image_save(). Similarly, ramdisk_image_load() loads a saved RAM disk from the host file system overwriting the existing RAM disk. To prevent data corruption when saving or loading a RAM disk image, the RAM disk should not be in use. Any mounted file systems should be unmounted.

After a RAM disk is no longer required it can be deleted using ramdisk_delete(). Before it is deleted, any mounted file system should be unmounted as deleting a RAM disk destroys all data contained therein.

11.6.3 SD/MMC driver usage model

The SD/MMC driver supports the hot plugging of SD/MMC cards. Every time a card is inserted, the SD/MMC driver creates a new device with the type

OSPLUS_DEVICE_TYPE_REMOVABLE_STORAGE

and registers it with the OSPlus device library. SD cards are named with the prefix /sd/rdisk, and postfixed with the device instance number (for example, the first SD card is /sd/rdisk0). MMC cards and eMMC devices are named with the prefix /mmc/rdisk, and postfixed with the device instance number (for example, /mmc/rdisk0).

The created SD/MMC device can be used in the same way as any ATA or SATA attached device. As the SD/MMC device is a removable device, it also supports the OSPlus common ioctls OSPLUS_IOCTL_CHECK_MEDIA and OSPLUS_IOCTL_WR_PROTECTED to check if the media is present and to query its write protect status.

426/515 7702033 Rev 27

UM1150 OSPlus storage drivers

SD/MMC devices support additional driver-specific ioctls, but these are limited to returning device information, such as the device status, device bus width, bus speed and power settings.

Generally, the raw SD/MMC card is accessed directly, although it is possible that the card may contain a partition, in which case the LVM creates logical volumes for each partition on the card. These volumes are mounted with VFS as either a FAT or E2FS file system and all file input and output handled by the VFS.

11.7 Storage drivers header files

Each OSPlus storage driver has its own header file. This contains all configuration options, types and function definitions supported by the driver.

11.7.1 ATA driver header file: ata.h

All the definitions relating to the ATA driver are in the file ata.h. The functions defined in ata.h

are explained in

Section 11.9.1: ATA driver functions on page 434

.

Table 185.

Configuration options defined in ata.h

Define

ATA_CONFIG_PATH

ATA_CONFIG_COUNT

ATA_CONFIG_INIT_FN

ATA_CONFIG_DEINIT_FN

ATA_CONFIG_BASE

ATA_CONFIG_REG_ALT_STATUS

ATA_CONFIG_REG_COMMAND

ATA_CONFIG_REG_DATA_PORT

ATA_CONFIG_REG_DATA

ATA_CONFIG_REG_DEVICE

ATA_CONFIG_REG_CONTROL

ATA_CONFIG_REG_ERROR

ATA_CONFIG_REG_FEATURES

ATA_CONFIG_REG_LBA_HIGH

ATA_CONFIG_REG_LBA_LOW

ATA_CONFIG_REG_LBA_MID

ATA_CONFIG_REG_SECTOR_COUNT

ATA_CONFIG_REG_STATUS

ATA_CONFIG_INTR

Description

Registry path to ATA configuration entries.

Registry key to hold an integer corresponding to the number of ATA host controllers present in the system.

Registry key to contain the address of a function to perform board-specific initialization.

Registry key to contain the address of a function to perform board-specific de-initialization.

Base address of ATA controller

Address of the ATA controller alternative status register

Address of the ATA controller command register

Address of the ATA controller data port register

Address of the ATA controller data register

Address of the ATA controller device register

Address of the ATA controller control register

Address of the ATA controller error register

Address of the ATA controller features register

Address of the ATA controller LBA high register

Address of the ATA controller LBA low register

Address of the ATA controller LBA mid register

Address of the ATA controller sector count register

Address of the ATA controller status register

ATA controller interrupt

7702033 Rev 27 427/515

OSPlus storage drivers UM1150

Table 185.

Configuration options defined in ata.h (continued)

Define Description

ATA_CONFIG_ALT_INTR

ATA_CONFIG_INTR_LEVEL

ATA_CONFIG_INTR

ATA_CONFIG_PIO_TIMING_FN

ATA_CONFIG_DMA_TIMING_FN

ATA_CONFIG_DMA_CAPABLE

ATA controller alternative interrupt

ATA controller interrupt level for OS20 based systems.

ATA controller interrupt level for OS20 based systems

Function to set any timings based on device PIO mode.

Function to set any timings based on device DMA mode.

Indicate if the ATA controller is DMA capable. This should be set to 0 .

Table 186.

Functions defined in ata.h

Function

ata_initialize()

Description

Initialize the ATA driver

11.7.2 SATA driver header file: sata.h

All definitions relating to the SATA driver are in the file sata.h. The functions defined in sata.h

are explained in

Section 11.9.2: SATA driver functions on page 435

.

Table 187.

Configuration options defined in sata.h

Define

SATA_CONFIG_PATH

SATA_CONFIG_COUNT

SATA_CONFIG_INIT_FN

SATA_CONFIG_DEINIT_FN

SATA_CONFIG_BASE

SATA_CONFIG_INTR

SATA_CONFIG_ALT_INTR

SATA_CONFIG_INTR_LEVEL

SATA_CONFIG_INTR

SATA_CONFIG_DMA_CHANNELS

Description

Registry path to SATA configuration entries.

Registry key to hold an integer corresponding to the number of SATA host controllers present in the system.

Registry key to contain the address of a function to perform board-specific initialization.

Registry key to contain the address of a function to perform board-specific de-initialization.

Base address of SATA controller

SATA controller interrupt

SATA controller alternative interrupt

SATA controller interrupt level for OS20 based systems.

SATA controller interrupt level for OS20 based systems

The number of DMA channels on the SATA controller

Table 188.

Functions defined in sata.h

Function

sata_initialize()

Description

Initialize the SATA driver.

428/515 7702033 Rev 27

UM1150 OSPlus storage drivers

11.7.3 RAM disk driver header file: ramdisk.h

The RAM disk driver does not support registry configuration options.

All the definitions relating to the SATA driver are in the file ramdisk.h. The functions defined in ramdisk.h are explained in

Section 11.9.4: RAM disk driver functions on page 437

.

Table 189.

Types defined in ramdisk.h

Type

ramdisk_t

Description

Private structure returned by the RAM disk create API and used in all other API functions

Table 190.

RAM disk minimum block sizes defined in ramdisk.h

Define Description

RAMDISK_MIN_HDISK_BLOCKS

RAMDISK_MIN_RDISK_BLOCKS

The minimum number of blocks required for the RAM disk driver to emulate a fixed disk device.

This is approximately 7.81 MBytes.

The minimum number of blocks required for the RAM disk driver to emulate a removable disk device.

This is approximately 188 KBytes.

Table 191.

Functions defined in ramdisk.h

Function

ramdisk_create() ramdisk_create_custom() ramdisk_create_hdisk() ramdisk_create_rdisk() ramdisk_delete() ramdisk_image_load() ramdisk_image_save()

Description

Create a simple RAM disk

Create a RAM disk with custom parameters

Create a RAM disk that emulates a fixed disk

Create a RAM disk that emulates a removable disk

Delete a RAM disk

Load a previously saved RAM disk image file from the host file system

Save a RAM disk as an image file to the host file system

7702033 Rev 27 429/515

OSPlus storage drivers UM1150

11.7.4 SD/MMC driver header file: sdmmc.h

All the definitions relating to the SD/MMC driver are in the file sdmmc.h. The functions defined in sdmmc.h are explained in

Section 11.9.3: SD/MMC driver functions on page 436

.

Table 192.

Configuration options defined in sdmmc.h

Define Description

SDMMC_CONFIG_PATH

SDMMC_CONFIG_COUNT

SDMMC_CONFIG_INIT_FN

SDMMC_CONFIG_BASE

SDMMC_CONFIG_INTR

SDMMC_CONFIG_ALT_INTR

SDMMC_CONFIG_INTR_LEVEL

SDMMC_CONFIG_INTR_TRIGGER

SDMMC_CONFIG_INTR_ENB_FN

Registry path to SD/MMC configuration entries.

Registry key to hold an integer corresponding to the number of SD/MMC host controllers present in the system.

This specifies a pointer to a function called to initialize the SD/MMC controller hardware.

Specifies the interrupt used to detect SD/MMC controller interrupts.

SD/MMC controller interrupt level for OS20 based systems.

Specifies an alternate interrupt to be used on some platforms to detect SD/MMC controller interrupts. An alternate interrupt need only be specified when

SDMMC_CONFIG_INTR

is not set.

These specify the interrupt level for the SD/MMC controller interrupts on OS20 based systems. For OS21 based systems it should be set to 0 .

This optionally specifies a pointer to a function called to enable the SD/MMC controller interrupt hardware.

Table 193.

Functions defined in sdmmc.h

Function

sdmmc_initialize()

Description

Initialize the SD/MMC card driver.

430/515 7702033 Rev 27

UM1150 OSPlus storage drivers

11.8 Storage driver ioctls

The ioctls in this section relate to the device library device_ioctl() function. For more

details of how to use the ioctls in this section, see

Section 4.10: Device driver ioctl definitions on page 146

.

11.8.1 ATA and SATA driver ioctls

The OSPlus ATA and SATA storage drivers support a subset of the common ioctls as defined in the include file ioctls/common.h and described in

Section 4.6: Device library header file: ioctls/common.h on page 140

. This subset of ioctls is shown in

Table 194

.

Table 194.

ATA and SATA driver supported ioctls

Ioctl

OSPLUS_IOCTL_BLOCK_SIZE

OSPLUS_IOCTL_CHECK_MEDIA

OSPLUS_IOCTL_GET_FIRMWARE

OSPLUS_IOCTL_GET_MODEL

OSPLUS_IOCTL_GET_RD_TIMEOUT

OSPLUS_IOCTL_GET_SERIAL

OSPLUS_IOCTL_GET_WR_TIMEOUT

OSPLUS_IOCTL_NUM_BLOCKS

OSPLUS_IOCTL_SET_RD_TIMEOUT

OSPLUS_IOCTL_WR_PROTECTED

OSPLUS_IOCTL_SET_WR_TIMEOUT

OSPLUS_IOCTL_SPIN_REQUESTS

OSPLUS_IOCTL_SPIN_UP

OSPLUS_IOCTL_SPIN_DOWN

Description

Get the size of each block on the device

Query the device media state

Get the device firmware version string

Get the device model string

Get the read time-out value

Get the device serial number string

Get the write time-out value

Get the number of blocks on the device

Set the read time-out value

Query the device media write protect state

Set the write time-out value

Query if device supports spin requests

Request device to spin up

Request device to spin down

11.8.2 RAM disk driver ioctls

The OSPlus RAM disk storage driver supports a subset of the common ioctls as defined in

the include file ioctls/common.h and described in

Section 4.6: Device library header file: ioctls/common.h on page 140

. This subset of ioctls is shown in

Table 195

.

Table 195.

RAM disk driver supported ioctls

Ioctl

OSPLUS_IOCTL_NUM_BLOCKS

OSPLUS_IOCTL_BLOCK_SIZE

OSPLUS_IOCTL_CHECK_MEDIA

OSPLUS_IOCTL_WR_PROTECTED

Description

Get the number of blocks on the device

Get the size of each block on the device

Query the device media state

Query the device media write protect state

7702033 Rev 27 431/515

OSPlus storage drivers UM1150

11.8.3 SD/MMC driver ioctls

The OSPlus SD/MMC driver supports a subset of the common ioctls as defined in the

include file ioctls/common.h and described in

Section 4.6: Device library header file: ioctls/common.h on page 140

. This subset of ioctls is shown in

Table 196

.

Table 196.

SD/MMC driver supported common ioctls

Ioctl

OSPLUS_IOCTL_NUM_BLOCKS

OSPLUS_IOCTL_BLOCK_SIZE

OSPLUS_IOCTL_CHECK_MEDIA

OSPLUS_IOCTL_WR_PROTECTED

Description

Get the number of blocks on the device

Get the size of each block on the device

Query the device media state

Query the device media write protect state

This SD/MMC driver also supports a number of driver specific ioctls to query the device status as defined in ioctls/sdmmc.h and defined in

Table 197

,

Table 198

and

Table 199

.

Details of the ioctls supported by specific drivers are given in

Section 11.10.1: SD/MMC driver ioctls on page 444

.

Table 197.

Ioctls defined in ioctls/sdmmc.h

Ioctl Description

OSPLUS_IOCTL_SDMMC_CARD_GET_STATUS

Get the SD/MMC card status.

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_

WIDTH

Get the SD/MMC card current bus width.

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_

SPEED

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_

POWER

OSPLUS_IOCTL_SDMMC_

SELECT_PARTITION

Get the SD/MMC card current bus speed in Hz.

Get the SD/MMC card current bus power.

Select the card partition to acess for subsequent read and write operations.

Table 198.

SD/MMC status defines in ioctls/sdmmc.h

Defines Description

OSPLUS_SDMMC_CARD_STATUS_MMC

OSPLUS_SDMMC_CARD_STATUS_SD

Card is of type MMC

Card is of type SD

Card is of type SDIO

OSPLUS_SDMMC_CARD_STATUS_SDIO

OSPLUS_SDMMC_CARD_STATUS_TYPE

Mask for card type

OSPLUS_SDMMC_CARD_STATUS_MMC_V4_X

Card adheres to MMC specification v4.x

OSPLUS_SDMMC_CARD_STATUS_SD_V1_XX

Card adheres to SD specification v1.xx

OSPLUS_SDMMC_CARD_STATUS_SD_V2_00

Card adheres to SD specification v2.00

OSPLUS_SDMMC_CARD_STATUS_VERSION

Mask for card version

OSPLUS_SDMMC_CARD_STATUS_SC

Card is of standard capacity (up to 4GB)

OSPLUS_SDMMC_CARD_STATUS_HC

Card is of high capacity (4GB to 32GB)

432/515 7702033 Rev 27

UM1150 OSPlus storage drivers

Table 198.

SD/MMC status defines in ioctls/sdmmc.h (continued)

Defines Description

OSPLUS_SDMMC_CARD_STATUS_XC

Card is of extended capacity (greater than 32GB)

OSPLUS_SDMMC_CARD_STATUS_CAPACITY

Mask for card capacity

OSPLUS_SDMMC_CARD_STATUS_NS

OSPLUS_SDMMC_CARD_STATUS_HS

OSPLUS_SDMMC_CARD_STATUS_SPEED

Card is normal speed (MMC: up to 26MHz, SD: up to 25MHz)

Card is high speed (MMC: over 26MHz, SD: over

25MHz)

Mask for card speed

OSPLUS_SDMMC_CARD_STATUS_1BIT

Card uses a 1-bit bus

Card uses a 4-bit bus

OSPLUS_SDMMC_CARD_STATUS_4BIT

OSPLUS_SDMMC_CARD_STATUS_8BIT

Card uses a 8-bit bus

OSPLUS_SDMMC_CARD_STATUS_BUS_WIDTH

Mask of card bus width

OSPLUS_SDMMC_CARD_STATUS_LV

Card is low voltage (1.65v to 1.95v)

OSPLUS_SDMMC_CARD_STATUS_HV

OSPLUS_SDMMC_CARD_STATUS_DV

Card is high voltage (2.7v to 3.6v)

Card is dual voltage

Mask of card voltage

OSPLUS_SDMMC_CARD_STATUS_VOLTAGE

OSPLUS_SDMMC_CARD_STATUS_WRITE_

PROTECT

Card is write protect

Table 199.

SD/MMC partition definitions in ioctls/sdmmc.h

Defines Description

OSPLUS_SDMMC_USER_PARTITION

OSPLUS_SDMMC_BOOT1_PARTITION

OSPLUS_SDMMC_BOOT2_PARTITION

Specify that accesses should go to the user partition.

Specify that accesses should go to the boot 1 partition.

Specify that accesses should go to the boot 2 partition.

7702033 Rev 27 433/515

OSPlus storage drivers UM1150

11.9.1 ATA driver functions ata_initialize

Initialize the ATA storage driver

Definition:

Arguments:

Returns:

Description:

int ata_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the ATA storage driver on a supported platform. The initialized ATA driver creates and registers with the device library, a new device instance for each supported device attached to the ATA interface.

434/515 7702033 Rev 27

UM1150 OSPlus storage drivers

sata_initialize

Initialize the SATA storage driver

Definition:

Arguments:

Returns:

Description:

int sata_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the SATA storage driver on a supported platform. When initialized, the SATA driver creates and registers a new device instance for each supported device attached to the SATA interface with the device library.

7702033 Rev 27 435/515

OSPlus storage drivers UM1150

11.9.3 SD/MMC driver functions sdmmc_initialize

Initialize the SD/MMC driver

Definition:

Arguments:

Returns:

Description:

int sdmmc_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the SD/MMC driver on a supported platform. When initialized, the

SD/MMC driver creates and registers a new device for each inserted SD/MMC card with the device library.

436/515 7702033 Rev 27

UM1150 OSPlus storage drivers

11.9.4 RAM disk driver functions ramdisk_create

Create a RAM disk

Definition:

ramdisk_t ramdisk_create (

char *name,

void *memory,

size_t block_count)

Arguments:

name memory block_count

Name to give the RAM disk.

Memory to use for RAM disk.

Size of the RAM disk in 512-byte blocks.

Returns:

Description:

See also:

Returns a pointer to a ramdisk_t for success, NULL for failure.

This call creates a RAM disk with the specified number of blocks. If the name parameter is not NULL, the RAM disk is created with this name. Otherwise, the default

/ramdisk/diskn

is used (where n is a number starting from 0).

When memory parameter is NULL, a buffer large enough to contain the RAM disk is allocated from the memory heap. When memory parameter is not NULL, it is assumed the buffer is large enough to hold the RAM disk. The RAM disk is created with a device type of OSPLUS_DEVICE_TYPE_RAMDISK_STORAGE.

Success returns a pointer to a private ramdisk_t structure. Failure returns NULL.

The returned ramdisk_t structure must be used on further RAM disk API calls.

ramdisk_create_hdisk

, ramdisk_create_rdisk, ramdisk_create_custom

, ramdisk_delete

7702033 Rev 27 437/515

OSPlus storage drivers UM1150

ramdisk_create_hdisk

Create a RAM disk that emulates a fixed disk

Definition:

ramdisk_t ramdisk_create_hdisk (

char *name,

void *memory,

size_t block_count)

Arguments:

name memory block_count

Name to give the RAM disk.

Memory to use for RAM disk.

Size of the RAM disk in 512-byte blocks.

Returns:

Description:

See also:

Returns a pointer to a ramdisk_t for success, NULL for failure.

This call creates a RAM disk with the specified number of blocks that appears as a fixed disk. If the name parameter is not NULL, the RAM disk is created with this name.

Otherwise, the default name /ramdisk/diskn is used (where n is a number starting from 0).

If the memory parameter is NULL, a buffer large enough to contain the RAM disk is allocated from the memory heap. If the memory parameter is not NULL, then it is assumed it points to a buffer large enough to contain the RAM disk. It is created with a device type of OSPLUS_DEVICE_TYPE_FIXED_STORAGE.

Success returns a pointer to a private ramdisk_t structure. Failure, returns NULL.

The ramdisk_t structure must be used on further RAM disk driver API calls.

ramdisk_create

, ramdisk_create_rdisk, ramdisk_create_custom, ramdisk_delete

438/515 7702033 Rev 27

UM1150 OSPlus storage drivers

ramdisk_create_rdisk

Create a RAM disk that emulates a removable disk

Definition:

ramdisk_t ramdisk_create_rdisk (

char *name,

void *memory,

size_t block_count)

Arguments:

name memory block_count

Name to give the RAM disk.

Memory to use for RAM disk.

Size of the RAM disk in 512-byte blocks.

Returns:

Description:

See also:

Returns a pointer to a ramdisk_t for success, NULL for failure.

This call creates a RAM disk with the specified number of blocks that appears as a removable disk. If the name parameter is not NULL, the RAM disk is created with this name. Otherwise, the default name /ramdisk/diskn is used (where n is a number starting from 0).

If the memory parameter is NULL, a buffer large enough to contain the RAM disk is allocated from the memory heap. If the memory parameter is not NULL, then it is assumed it points to a buffer large enough to contain the RAM disk. It is created with a device type of OSPLUS_DEVICE_TYPE_REMOVABLE_STORAGE.

Success returns a pointer to a private ramdisk_t structure. Failure, returns NULL.

The ramdisk_t structure must be used on further RAM disk driver API calls.

ramdisk_create

, ramdisk_create_hdisk, ramdisk_create_custom, ramdisk_delete

7702033 Rev 27 439/515

OSPlus storage drivers UM1150

ramdisk_create_custom

Create a RAM disk with customized parameters

Definition:

ramdisk_t ramdisk_create_custom (

char *name,

void *memory,

char *dev_type,

size_t block_size,

size_t block_count)

Arguments:

name memory dev_type block_size block_count

Name to give the RAM disk.

Memory to use for RAM disk.

Device type to use for RAM disk.

Size of the RAM disk blocks.

Size of the RAM disk in 512-byte blocks.

Returns:

Description:

See also:

Returns a pointer to a ramdisk_t for success, NULL for failure.

This call creates a RAM disk with the specified number of blocks, block size and device type. If the name parameter is not NULL, the RAM disk is created with this name. Otherwise, the default name /ramdisk/diskn is used (where n is a number starting from 0).

If the memory parameter is NULL, a buffer large enough to contain the RAM disk is allocated from the memory heap. If the memory parameter is not NULL, it is assumed it points to a buffer large enough to contain the RAM disk. The RAM disk is created with the user supplied device type.

Success returns a pointer to a private ramdisk_t structure. Failure, returns NULL.

The ramdisk_t structure must be used on further RAM disk driver API calls.

ramdisk_create

, ramdisk_create_hdisk, ramdisk_create_rdisk, ramdisk_delete

440/515 7702033 Rev 27

UM1150 OSPlus storage drivers

ramdisk_delete

Delete a RAM disk

Definition:

Arguments:

int ramdisk_delete (ramdisk_t *ramdisk) ramdisk

Structure returned from a RAM disk create API call.

Returns:

Description:

See also:

Returns an integer of 0 for success, -1 for failure.

This call deletes a previously created RAM disk. The RAM disk is deleted from the

OSPlus device library and any memory allocated for the RAM disk is freed.

ramdisk_create

, ramdisk_create_hdisk, ramdisk_create_rdisk, ramdisk_create_custom

7702033 Rev 27 441/515

OSPlus storage drivers UM1150

ramdisk_image_load

Load a RAM disk as an image to file

Definition:

int ramdisk_image_load (

ramdisk_t *ramdisk,

cnst char *filename)

Arguments:

ramdisk filename

Structure returned from a RAM disk create API call.

Name of the RAM disk image file.

Returns:

Description:

See also:

Returns an integer of 0 for success, -1 for failure.

This call loads a RAM disk image from a file stored on the host file system with the file name given by the parameter filename. To load the image, the RAM disk image must be the same size as the RAM disk. The RAM disk is overwritten by the image file.

ramdisk_image_save

442/515 7702033 Rev 27

UM1150 OSPlus storage drivers

ramdisk_image_save

Save a RAM disk as an image to file

Definition:

int ramdisk_image_save (

ramdisk_t *ramdisk,

cnst char *filename)

Arguments:

ramdisk filename

Structure returned from a RAM disk create API call.

Name to give the image file.

Returns:

Description:

See also:

Returns an integer of 0 for success, -1 for failure.

This call saves a RAM disk image to a file with the file name given by the parameter filename

to the host file system. A pre-existing file with the same name is overwritten.

ramdisk_image_load

7702033 Rev 27 443/515

OSPlus storage drivers UM1150

11.10 Storage driver ioctl definitions

11.10.1 SD/MMC driver ioctls

OSPLUS_IOCTL_SDMMC_GET_STATUS

Get the SD/MMC card status

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with a bitmask of the current

SD/MMC status.

Returns 0 for success, -1 for failure.

This ioctl reads the SD/MMC card status bit mask into the unsigned integer whose address is passed in. The SD/MMC card status can be determined by performing a logical AND between the bit mask returned and the values defined in

Table 198:

SD/MMC status defines in ioctls/sdmmc.h on page 432

.

See also:

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_WIDTH,

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_SPEED,

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_POWER

OSPLUS_IOCTL_SDMMC_GET_BUS_WIDTH

Get the SD/MMC card bus width

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with the current bus width

Returns 0 for success, -1 for failure.

This ioctl reads the SD/MMC card bus width into the unsigned integer whose address is passed in. The SD/MMC card bus width is 1, 4, or 8 bits.

See also:

OSPLUS_IOCTL_SDMMC_CARD_GET_STATUS,

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_SPEED,

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_POWER

OSPLUS_IOCTL_SDMMC_GET_BUS_SPEED

Get the SD/MMC card bus speed

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with the current bus speed.

Returns 0 for success, -1 for failure.

This ioctl reads the SD/MMC card bus speed into the unsigned integer whose address is passed in. The SD/MMC card bus speed is given as Hz.

See also:

OSPLUS_IOCTL_SDMMC_CARD_GET_STATUS,

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_WIDTH,

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_POWER

444/515 7702033 Rev 27

UM1150 OSPlus storage drivers

OSPLUS_IOCTL_SDMMC_GET_BUS_POWER

Get the SD/MMC card status

Arguments:

Returns:

Description:

The address of an unsigned integer to be populated with the current bus power.

Returns 0 for success, -1 for failure.

This ioctl reads the SD/MMC card bus power into the unsigned integer whose address is passed in. The SD/MMC card bus power is returned as 180 for 1.80v, 300 for 3.00v and 330 for 3.3v.

See also:

OSPLUS_IOCTL_SDMMC_CARD_GET_STATUS,

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_WIDTH,

OSPLUS_IOCTL_SDMMC_CARD_GET_BUS_SPEED

OSPLUS_IOCTL_SDMMC_CARD_SELECT_PARTITION

Select the MMC card partition to access

Arguments:

Returns:

Comments:

An unsigned integer, specifying the partition to access.

Returns 0 for sucess, -1 for failure.

This IOCTL selects the card partition to access for subsequent read and write operations. The default partition is the user partition. The parameter should be one of the following:

–

OSPLUS_SDMMC_USER_PARTITION

–

OSPLUS_SDMMC_BOOT1_PARTITION

–

OSPLUS_SDMMC_BOOT2_PARTITION

OSPLUS_IOCTL_SDMMC_CARD_SELECT_BOOT_PARTITION

Select the MMC card partition for booting

Arguments:

Returns:

Comments:

An unsigned integer, specifying which partition to use for booting.

Returns 0 for sucess, -1 for failure.

This IOCTL selects the MMC card partition to be booted from if the MMC device is configured as the boot device. The parameter should be one of the following:

–

OSPLUS_SDMMC_USER_PARTITION

–

OSPLUS_SDMMC_BOOT1_PARTITION

–

OSPLUS_SDMMC_BOOT2_PARTITION

–

OSPLUS_SDMMC_BOOT_DISABLED

The parameter selects either which partition the device should present when it is in boot mode, or if boot mode should be disabled.

7702033 Rev 27 445/515

OSPlus storage drivers UM1150

OSPLUS_IOCTL_SDMMC_CARD_QUERY_PARTITION

Arguments:

Returns:

Comments:

Query the current active partition for an MMC card

A pointer to an unsigned integer.

Returns 0 for success, -1 for failure.

This IOCTL queries the currently selected partition on an MMC device to find out what type of partition it is. This is the partition that is read from or written to if any I/O is performed on the device. The argument must be the address of the unsigned integer that will receive the details of the currently active partition on successful completion. Possible values are:

–

OSPLUS_SDMMC_USER_PARTITION

–

OSPLUS_SDMMC_BOOT1_PARTITION

–

OSPLUS_SDMMC_BOOT2_PARTITION

If the device being addressed does not support partitions, then the IOCTL call will fail.

OSPLUS_IOCTL_SDMMC_CARD_QUERY_BOOT_PARTITION

Query the current boot partition for an MMC card

Arguments:

Returns:

Comments:

A pointer to an unsigned integer.

Returns 0 for success, -1 for failure.

This IOCTL queries the currently selected partition on an MMC device to find out what type of partition it is. This is the partition that is read from or written to if any I/O is performed on the device. The argument must be the address of the unsigned integer that will receive the details of the currently active partition on successful completion. Possible values are:

–

OSPLUS_SDMMC_USER_PARTITION

–

OSPLUS_SDMMC_BOOT1_PARTITION

–

OSPLUS_SDMMC_BOOT2_PARTITION

–

OSPLUS_SDMMC_BOOT_DISABLED

If the device being addressed does not support partitions, then the IOCTL call will fail.

OSPLUS_IOCTL_SDMMC_CARD_PARTITIONS_SUPPORTED

Arguments:

Returns:

Comments:

Query if the MMC device supports partitions

None.

Returns 0 for success, -1 for failure.

This IOCTL queries the device to see if it supports MMC partitions. If the device is not an MMC card, or the MMC card does not support partitions, then the call will fail. The call will succeed only if the card does support partitions.

446/515 7702033 Rev 27

UM1150

12 OSPlus Flash drivers

OSPlus Flash drivers

12.1 Flash drivers overview

OSPlus provides Flash drivers for NAND Flash, enabling applications on

STMicroelectronics hardware platforms to store and retrieve data. OSPlus supplies two varieties of Flash driver: low-level and high-level. The low-level drivers create raw Flash devices that handle basic page read and program duties. The high-level Flash translation layer drivers manage partitions created on the raw Flash devices and implement bad block management and wear levelling within each partition.

The OSPlus Flash drivers all adhere to the OSPlus driver model, which is a platform independent library built for all supported CPUs. The Flash drivers are only supported on those platforms with on-board NAND Flash or NAND Flash connected using a STEM.

Each low-level Flash driver provides an interface to a raw Flash device that is designed to be used with the Flash translation layers.

The ST NAND Flash Translation Layer (STNFTL) driver provides a standard block device interface for the LVM and E2FS or FAT file systems, or can alternatively be used as a raw block device. STNFTL provides a traditional “write in place” view of the Flash, essentially making it appear as a normal disk drive.

The Linear Access Flash Translation Layer (LAFTL) also provides a standard block device interface to the underlying Flash, but it imposes certain restrictions. LAFTL only supports accesses that are a multiple of a given number of blocks, and aligned on those block boundaries. It allows reads from anywhere within the Flash partition, provided that the previous restrictions are met. Writes must also observe these restrictions. In addition, writes must always be made to successive block addresses that increase in fixed increments, or to block 0.

LAFTL is intended to work in conjunction with the LAFS file system to provide a highly efficient “timeshift” function for DVR applications.

12.2 Flash driver geometry

This section describes the physical organization of the NAND Flash devices. This information is useful for optimally programming the NAND Flash device.

NAND Flash is generally organized as a number of planes, each containing an equal number of blocks, which in turn contain an equal number of pages and spares. The actual number of planes is either one, or number that is a power of two (2, 4, 8, and so forth). The size of each plane in blocks is calculated as the total number of blocks on the NAND Flash divided by the total number of planes.

One benefit of organizing NAND Flash chips into planes is that it is often possible to issue multi-plane commands where a number of pages can be read or written, or a number of blocks can be erased concurrently, as long as each page or block is on a different (but usually adjacent) plane.

A common method of doubling Flash capacity is by using a process known as stacking, where two identical Flash chips are bonded one on top of the other into a single chip package and connected with some glue logic. When this happens, rather than the size of each plane doubling, the actual number of planes doubles. This enables a technique called

7702033 Rev 27 447/515

OSPlus Flash drivers UM1150

interleaving to be used to increase the Flash throughput, as each chip in the stack can be programmed concurrently as long as the program accesses the same planes on each chip.

The flex NAND driver supports combining multiple banks of Flash containing identical

NAND Flash devices into a single large device. This single large device can be thought of as essentially a stacked device allowing concurrent operations over all banks, but rather than a single chip package, each “stack” is a separate NAND Flash bank.

The low-level Flash drivers provide both a basic and an advanced API. The basic API hides the concept of planes so that the NAND Flash device appears as only containing blocks.

The advanced API exposes the planes, allowing optimal access to the memory.

12.3 Flash driver performance

When the EMI NAND driver and flex driver operate in standard mode, they read and write every byte using the CPU, which means, for certain applications, that the performance may not be at an acceptable level. The EMI NAND driver can be accelerated to a certain degree by configuring registry options for specifying alternative functions to read and write data in place of the default functions. The registry options for configuring these functions are

described in

Section 12.4.1: EMI low-level NAND driver registry options on page 449

.

The flex driver can be configured for advanced mode, in which case the FDMA is used for all data transfers. For applications where the performance of the low-level Flash drivers is critical, it is recommended that you use the flex driver in advanced mode. The registry

options for configuring the flex driver in advanced mode are described in

Section 12.4.2:

Flex low-level NAND driver registry options on page 451

.

12.4 Flash driver configuration

The configuration of the low-level Flash drivers includes details such as base address and

NAND device characteristics. This information overrides platform specific defaults, or enables the drivers to operate on a platform that does not yet have a specified set of registry settings.

The configuration of the LAFTL and STNFTL drivers includes information relating to the selection of low-level Flash driver device instances and how to partition the device.

All driver configuration options are read during driver initialization. Therefore, all configuration details must be specified before calling the appropriate driver initialize function. The driver can use only those details that are specified before initialization.

Each Flash driver configuration option is specified by writing its associated registry key. The include file for the Flash driver contains a series of defines that provide the names for all registry keys for that driver. The Flash driver include file also contains the registry path where the registry keys are written. The configuration options for all Flash drivers are set in a similar manner.

registry_key_set (

FLEX_CONFIG_PATH,

FLEX_CONFIG_BASE,

(void *) 0x01234567);

448/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

Examples of how to create registry settings for each of the OSPlus Flash drivers can be found in the OSPlus custom_registry example in the OSPlus software installation package.

12.4.1 EMI low-level NAND driver registry options

Table 204: Configuration options defined in eminand.h on page 463

provides a summary of the EMI NAND driver registry options.

The EMI NAND driver options are stored in the registry at the node specified by

EMINAND_CONFIG_PATH

. As the EMI NAND driver supports multiple Flash devices, this node has a registry key EMINAND_CONFIG_COUNT. This key contains an integer that specifies the number of Flash devices for which there are settings. The settings for each controller are stored in a sub-node with the name consisting of an integer starting from 0.

For example, the settings for Flash device 0 are stored at registry path

EMINAND_CONFIG_PATH"/0"

and for Flash device 1 at EMINAND_CONFIG_PATH"/1".

The configuration options defined in eminand.h are shown in

Table 200

.

Table 200.

Configuration options defined in eminand.h

Define Description

EMINAND_CONFIG_PATH

EMINAND_CONFIG_COUNT

EMINAND_CONFIG_INIT_FN

EMINAND_CONFIG_CMD_ADDR

EMINAND_CONFIG_ADDR_ADDR

EMINAND_CONFIG_DATA_ADDR

EMINAND_CONFIG_BUS_WIDTH

EMINAND_CONFIG_PAGE_SIZE

Registry path to EMI NAND configuration entries.

Registry key to hold an integer corresponding to the number of EMI NAND devices present in the system.

Registry key to hold a pointer to a function that, if supplied, is called to initialize the hardware, including configuring any PIO or system registers to enable the

NAND device to accessed. The function should have the following prototype: int eminand_init_fn (void);

On successful initialization of the hardware this function returns 0, otherwise it returns -1 .

Registry key to hold the address at which commands are written to the NAND Flash device. If the board design uses an EMI address line to assert the CLE signal, then this address line must be set in the address given here.

Registry key to hold the address at which addresses are written to the NAND Flash device. If the board design uses an EMI address line to assert the ALE signal, then this address line must be set in the address given here.

Registry key to hold the address at which data is read from and written to the NAND Flash device.

Registry key specifying the width in bits of the bus to the

NAND Flash device. This is usually 8-bit or 16-bit and must be supplied.

Registry key specifying the page data size in bytes of the NAND Flash device. This is usually set to either

512 bytes or 2048 bytes. If the NAND Flash device can be auto-detected then this key need not be specified.

7702033 Rev 27 449/515

OSPlus Flash drivers UM1150

Table 200.

Configuration options defined in eminand.h (continued)

Define Description

EMINAND_CONFIG_SPARE_SIZE

EMINAND_CONFIG_BLOCK_SIZE

EMINAND_CONFIG_BLOCK_COUNT

EMINAND_CONFIG_INREP_FN

EMINAND_CONFIG_OUTREP_FN

EMINAND_CONFIG_ALE_FN

EMINAND_CONFIG_CLE_FN

Registry key specifying the page spare area size in bytes of the NAND Flash device. This is usually

16 bytes for 512-byte pages, or 64 bytes for 2048-byte pages. If the NAND Flash device can be auto-detected then this key need not be specified.

Registry key specifying the block size in pages of the

NAND Flash device. If the NAND Flash device can be auto-detected then this key need not be specified.

Registry key specifying the number of blocks on the

NAND Flash device. If the NAND Flash device can be auto-detected then this key need not be specified.

Registry key specifying a pointer to a function that reads data from a given address. The function should have the following prototype: int inrep (unsigned int address, void

*buffer, int length);

The function returns the number of bytes read or -1 on error. When the bus of the Flash is 8 bits wide, this function must read data in 8-bit quantities. Similarly if the bus is 16 bits wide this function must read data in

16-bit quantities.

Registry key specifying a pointer to a function that writes data to a given address. The function should have the following prototype: int outrep (unsigned int address, void

*buffer, int length);

The function returns the number of bytes written or -1 on error. When the bus of the Flash is 8 bits wide, this function must write data in 8-bit quantities. Similarly if the bus is 16 bits wide, this function must write data in

16-bit quantities.

Optional registry key to provide a function which can set or clear the ALE signal to the Flash device. Most boards use an EMI address line to perform this task, so this key is not needed. Others use a board specific PIO signal, in which case the function provided by this key is required to toggle the PIO signal. The function takes one parameter, which is either 1 or 0, and indicates the required state that the ALE signal should be put into.

Optional registry key to provide a function which can set or clear the CLE signal to the Flash device. Most boards use an EMI address line to perform this task, so this key is not needed. Others use a board specific PIO signal, in which case the function provided by this key is required to toggle the PIO signal. The function takes one parameter, which is either 1 or 0, and indicates the required state that the CLE signal should be put into.

450/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

Table 206: Configuration options defined in flex.h on page 464

provides a summary of the

flex NAND driver registry options.

The flex driver options are stored in the registry at the node specified by

FLEX_CONFIG_PATH

. As the flex driver supports multiple controllers, this node has a registry key named FLEX_CONFIG_COUNT. This key contains an integer specifying the number of flex controllers for which there are settings. The settings for each flex controller are stored in a sub-node with a name consisting of an integer starting from 0. For example, the settings for flex controller 0 are stored at registry path FLEX_CONFIG_PATH"/0" and for flex controller 1 at FLEX_CONFIG_PATH"/1".

Table 201.

Configuration options defined in flex.h

Define

FLEX_CONFIG_PATH

FLEX_CONFIG_COUNT

FLEX_CONFIG_INIT_FN

FLEX_CONFIG_BASE

FLEX_CONFIG_INTR

FLEX_CONFIG_ALT_INTR

FLEX_CONFIG_INTR_LEVEL

FLEX_CONFIG_INTR_TRIGGER

FLEX_CONFIG_INTR_ENB_FN

Description

Registry path to flex NAND configuration entries.

Registry key to hold an integer corresponding to the number of flex NAND devices present in the system.

Registry key to hold a pointer to a function that, if supplied, is called to initialize the hardware, including the configuration of any PIO or system registers to enable the

NAND device to be accessed. The function has the following prototype: int flex_init_fn (void);

On successful initialization of the hardware this function returns 0, otherwise -1 if an error is detected.

Registry key specifying the base address of the flex registers

Registry key specifying the flex interrupt. If this key is null, then the driver checks the key FLEX_CONFIG_ALT_INTR for an alternate interrupt. If this key is not specified then no interrupts are configured.

Registry key specifying an alternate flex interrupt.

These specify the interrupt level and trigger to program for the flex interrupts on OS20 based systems. For OS21 based systems these options must be set to 0 .

Registry key specifying a pointer to an optional function that is called after the flex interrupt handler is installed and enabled. The function should have the following prototype: int flex_intr_enb_fn (void);

On successful enable of the flex interrupt this function returns 0 . If an error occurs, -1 is returned.

7702033 Rev 27 451/515

OSPlus Flash drivers UM1150

Table 201.

Configuration options defined in flex.h (continued)

Define Description

FLEX_CONFIG_INREP_FN

FLEX_CONFIG_OUTREP_FN

FLEX_CONFIG_FLAGS

FLEX_CONFIG_CTRL_TIMING

FLEX_CONFIG_WEN_TIMING

FLEX_CONFIG_REN_TIMING

FLEX_CONFIG_ADVANCED_MODE

FLEX_CONFIG_FDMA_SETUP

FLEX_CONFIG_FDMA_WAIT

Registry key specifying a pointer to a function that reads data from a given address. The function should have the following prototype: int inrep (unsigned int address, void

*buffer, int length);

The function returns the number of bytes read, or -1 on error. This function must read in 32-bit quantities and can be used to provide accelerated reading from Flash in flex mode. By default the flex driver uses OSPLUS_INREP32().

Registry key specifying a pointer to a function that writes data to a given address. The function should have the following prototype: int outrep (unsigned int address, void

*buffer, int length);

The function returns the number of bytes written, or -1 on error. This function must write in 32-bit quantities and can be used to provide accelerated writing to Flash in flex mode.

By default the flex driver uses OSPLUS_OUTREP32().

Registry key specifying a bitmask of flags to control various behavior. This is currently unused.

Registry key specifying the control timing to use. This is board specific and must be specified.

Registry key specifying the write enable timing to use. This is board specific and must be specified.

Registry key specifying the read enable timing to use. This is board specific and must be specified.

Registry key specifying that the flex driver is operating in advanced mode (set to 1) or not (set to 0). To operate in advanced mode, the FLEX_CONFIG_FDMA_* keys must be specified.

Use this key only when operating in advanced flex mode. It specifies a function callback to be executed to configure the

FDMA to transfer a page to or from the NAND Flash. The callback function has the following prototype: int flex_fdma_setup_fn (flex_afm_regs_t *);

On successful setup of the FDMA transfer this function returns 0, otherwise 1 if the page transferred contains an unfixed ECC error, and -1 if a different error is detected.

Use this key only when operating in advanced flex mode. It specifies a function callback to be executed to wait on the completion of a previously setup FDMA transfer. The callback function has the following prototype: int flex_fdma_wait_fn (void);

On successful setup of the FDMA transfer this function returns

0,

otherwise

-1

if an error is detected.

452/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

Table 201.

Configuration options defined in flex.h (continued)

Define Description

FLEX_CONFIG_FDMA_ABORT

FLEX_CONFIG_NAND_DEVICES

FLEX_CONFIG_BANK_COUNT

Use this key only when operating in advanced flex mode. It specifies a function callback to be executed to abort the current outstanding FDMA transfer. The callback function has the following prototype: int flex_fdma_abort_fn (void);

On successful setup of the FDMA transfer this function returns

0,

otherwise

-1

if an error is detected.

Registry key specifying how many NAND devices the flex controller manages. For each device, there is a sub-node from the current controller registry path containing the flex configuration options. That is, for controller 0 NAND device

0 the registry path is:

FLEX_CONFIG_PATH"/0/device/0"

For controller 0 NAND device 1 the registry path is:

FLEX_CONFIG_PATH"/0/device/1"

Registry key specifying the number of banks that the flex driver represents as a single logical low-level NAND device.

If more than one bank is combined to create a single large logical low-level NAND device, then each bank must contain an identical NAND Flash chip. If the chips in each bank are not identical, then they must be configured as individual low-level NAND devices.

FLEX_CONFIG_BANK_MUX_CFG

FLEX_CONFIG_BANK_CSN_ALT_CFG

FLEX_CONFIG_BANK_CS

FLEX_CONFIG_BUS_WIDTH

This registry key should be considered a prefix for reading in an array of bank mux configuration values. If

FLEX_CONFIG_BANK_COUNT is set to 2, then there must be two entries in the array of bank mux configuration values.

For example:

FLEX_CONFIG_BANK_MUX_CFG”[0]”

and

FLEX_CONFIG_BANK_MUX_CFG”[1]”

.

The bank mux configuration value actually determines the mux configuration for the specified NAND device. If the single logical low-level NAND device consists of two NAND devices in bank 1 and 2, then we should set the following values:

FLEX_CONFIG_BANK_MUX_CFG”[0]”

is 2

FLEX_CONFIG_BANK_MUX_CFG”[1]”

is 4

This registry key should be considered a prefix for reading in an array of bank CSn alternate values. Each entry in the array specifies the CSn alternate value for the NAND device bank. This key is similar in operation to

FLEX_CONFIG_BANK_CSN_ALT_CFG

. This key is optional.

Registry key specifying the number of chip selects per bank of Flash. If no value is specified, the driver will default to one.

Registry key specifying the width in bits of the bus to the

NAND Flash device. This is usually 8-bit or 16-bit. If not set, it defaults to 8-bit.

7702033 Rev 27 453/515

OSPlus Flash drivers UM1150

Table 201.

Configuration options defined in flex.h (continued)

Define Description

FLEX_CONFIG_INTERNAL_CHIPS

FLEX_CONFIG_CELL_LEVELS

FLEX_CONFIG_INTERLEAVE

FLEX_CONFIG_SIM_READ

FLEX_CONFIG_SIM_PROGRAM

FLEX_CONFIG_SIM_ERASE

FLEX_CONFIG_PAGE_SIZE

FLEX_CONFIG_SPARE_SIZE

FLEX_CONFIG_BLOCK_SIZE

FLEX_CONFIG_PLANE_SIZE

FLEX_CONFIG_PLANE_COUNT

Registry key specifying the number of internal chips in each

NAND device. Valid values are powers of two (1, 2, 4, and so forth). If not set, the flex driver attempts to auto-detect by reading the NAND device electronic signature.

Registry key specifying the number of cell levels in each

NAND device. Valid values are powers of two (1, 2, 4, and so forth). If not set, the flex driver attempts to auto-detect by reading the NAND device electronic signature.

Registry key specifying the number of interleaves in each

NAND device. Valid values are powers of two (1, 2, 4, and so forth). If not set, the flex driver attempts to auto-detect by reading the NAND device electronic signature.

Interleaving allows data reads/writes to be performed concurrently.

Registry key specifying the number of planes in each NAND device that can be simultaneously read. Valid values are powers of two (1, 2, 4, and so forth). If not set, the flex driver defaults to reading from a single plane at a time.

Registry key specifying the number of planes in each NAND device that can be simultaneously programmed. Valid values are powers of two (1, 2, 4, and so forth). If not set, the flex driver attempts to auto-detect by reading the NAND device electronic signature

Registry key specifying the number of planes in each NAND device that can be simultaneously erased. Valid values are powers of two (1, 2, 4, and so forth). If not set, the flex driver defaults to erasing a single plane at a time.

Registry key specifying the page data size in bytes of the

NAND Flash device. This is usually set to either 512 bytes or 2048 bytes. If the NAND Flash device can be auto-detected then this key need not be specified. Note that advanced flex mode only operates on large page devices.

Registry key specifying the page spare area size in bytes of the NAND Flash device. This is usually 16 bytes for

512-byte pages, or 64 bytes for 2048-byte pages. If the

NAND Flash device can be auto-detected then this key need not be specified.

Registry key specifying the block size in pages of the NAND

Flash device. If the NAND Flash device can be auto-detected then this key need not be specified.

Registry key specifying the size of each plane on the NAND

Flash device in blocks. If the NAND Flash device can be auto-detected then this key need not be specified.

Registry key specifying the number of planes on the NAND

Flash device. If the NAND Flash device can be auto-detected then this key need not be specified.

454/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

12.4.3 LAFTL driver registry options

Table 209: Configuration options defined in laftl.h on page 465

provides a summary of the

LAFTL driver registry options.

The LAFTL driver options are stored in the registry at the node specified by

LAFTL_CONFIG_PATH

. As the LAFTL driver supports multiple partitions on multiple raw devices, this node has a registry key named LAFTL_CONFIG_COUNT. This key contains an integer specifying the number of partitions for which there are settings. The settings for each partition are stored in a sub-node with the name consisting of an integer starting from 0. For example, the settings for partition 0 are stored at registry path LAFTL_CONFIG_PATH"/0" and for partition 1 at LAFTL_CONFIG_PATH"/1".

Table 202.

Configuration options defined in laftl.h

Define

LAFTL_CONFIG_DEVICE_NAME

LAFTL_CONFIG_DEVICE_FLAGS

LAFTL_CONFIG_PART_START_BLOCK

LAFTL_CONFIG_PART_BLOCK_COUNT

LAFTL_CONFIG_PART_FORCE_INIT

Description

Registry key specifying the name of the raw Flash device to open and use with LAFTL. If no device name is specified then /flash/nand0 is used.

Registry key specifying the flags to use when opening the raw Flash device. If no flags are specified then the raw device is opened with mode OSPLUS_O_RDWR.

Registry key specifying the block on the raw Flash device where the LAFTL managed partition starts. If no block is specified then block 0 is used.

Registry key specifying the number of blocks that the

LAFTL managed partition contains. If this option is not specified, or if set to 0 blocks, then the number of blocks the partition contains is calculated from the raw Flash device size to be as large as possible.

Registry key specifying whether or not to force initialization of the device. If set to 1, LAFTL does not attempt to recover the previous state of the Flash, but instead performs a new bad block scan and re-initializes the device. If not set (or set to 0), the LAFTL recovers the stored state of the Flash and uses that.

7702033 Rev 27 455/515

OSPlus Flash drivers UM1150

Table 211: Configuration options defined in stnftl.h on page 465

provides a summary of the

STNFTL driver registry options.

The STNFTL driver options are stored in the registry at the node specified by

STNFTL_CONFIG_PATH

. As the STNFTL driver supports multiple partitions on multiple raw devices, this node has a registry key named STNFTL_CONFIG_COUNT. This key contains an integer specifying the number of partitions for which there are settings. The settings for each partition are stored in a sub-node with the name consisting of an integer starting from 0. For example, the settings for partition 0 are stored at registry path

STNFTL_CONFIG_PATH"/0"

and for partition 1 at STNFTL_CONFIG_PATH"/1".

Table 203.

Configuration options defined in stnftl.h

Define Description

STNFTL_CONFIG_DEVICE_NAME

STNFTL_CONFIG_DEVICE_FLAGS

Registry key specifying the name of the raw Flash device to open and use with STNFTL. If no device name is specified then /flash/nand0 is used.

Registry key specifying the flags to use when opening the raw Flash device. If no flags are specified then the raw device is opened with mode OSPLUS_O_RDWR.

STNFTL_CONFIG_PART_START_BLOCK

Registry key specifying the block on the raw Flash device where the STNFTL managed partition starts. If no block is specified then block 0 is used.

STNFTL_CONFIG_PART_BLOCK_COUNT

Registry key specifying the number of blocks that the

STNFTL managed partition contains. If this option is not specified, or if set to 0 blocks, then the number of blocks the partition contains is calculated from the raw Flash device size to be as large as possible.

STNFTL_CONFIG_PART_FILL_FACTOR

Registry key to specify how many blocks to reserve in the partition for use by STNFTL. The minimum number of blocks is 2. If this option is not specified, or if set to 0 blocks, then the number of blocks to reserve is calculated based on the partition block count. The number of blocks reserved is approximately 1% of the total partition size but never less than 2.

STNFTL_CONFIG_PART_ERASE_FIRST

Registry key specifying whether to erase the raw Flash before creating an STNFTL partition. Set this option to 1 to erase the raw Flash. By default this option is set to 0.

Only those blocks used by the STNFTL partition are erased on the raw device. All other blocks are left intact.

456/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

12.5 Flash drivers initialization

12.5.1 Low-level NAND driver initialization

The OSPlus low-level Flash drivers require explicit initialization. The EMI NAND driver is initialized by calling eminand_initialize() and the flex driver is initialized by calling flex_initialize()

.

Upon initialization, the low-level drivers set the driver version and allocate and initialize the internal state. The drivers then query the registry to determine the number of Flash controllers to be supported on the current platform. Each EMI NAND Flash controller is able to support one NAND Flash device, whilst each flex Flash controller may support multiple

NAND Flash devices. For each Flash controller supported, the registry is further queried to retrieve the base address and other details of the controller before probing for a connected

NAND Flash device. If the current platform does not support any controllers then the initialization fails and an error returned through errno.

Before each Flash controller can probe the connected NAND Flash device, the low-level drivers must read the Flash device configuration. For the EMI NAND driver, this consists of only the Flash device bus width (which is usually either 8-bits or 16-bits), and the Flash geometry settings. For the flex NAND driver, the driver must read the bus width, the Flash geometry and additional information such as the number of banks of Flash to control and the configuration of each bank.

When the Flash device configuration has been determined, the driver reads the NAND device electronic signature. It uses this electronic signature to lookup pre-determined information about the NAND Flash device including the NAND Flash device page data size, block size and block count. The spare size is determined from the page data size using the simple formula: spare size = (page data size / 512) * 16;

If any part of the NAND Flash device configuration is specified in the registry, the registry values are used in preference to the values contained in the look up table.

●

●

If the NAND Flash device is not found in the lookup table, or the lookup table does not contain all of the information, the low-level drivers attempt to autodetect the missing settings from the electronic signature bytes. A basic electronic signature consists of two bytes and holds the manufacturer and device identifiers. If the electronic signature is longer, then the additional bytes can also be decoded.

●

The third electronic signature byte provides chip features such as number of internal cells, interleave, and number of simultaneously programmable pages.

The fourth electronic signature byte provides the page and block sizes.

The fifth electronic signature byte provides the number if planes on the chip and their size.

If any of the page data size, block size and block count cannot be determined from the lookup table or from the electronic signature, then the low-level drivers expect the values to be specified in the registry settings. If the driver fails to find this information, then initialization fails with an error.

When the NAND Flash device has been probed, the low-level drivers create a new raw

Flash device with the type OSPLUS_DEVICE_TYPE_RAW_FLASH_STORAGE and register it with the device library using the prefix /flash/nand and postfixed with the device instance number. If this is the first device to be registered with the prefix /flash/nand, the device

7702033 Rev 27 457/515

OSPlus Flash drivers UM1150

name is /flash/nand0. If other raw Flash devices are already registered with the device library, the device name can be /flash/nand1 or /flash/nand2, and so on.

The low-level Flash drivers do not support hot plugging. If the Flash device is not attached when the driver is initialized it can never be detected.

12.5.2 LAFTL driver initialization

The LAFTL driver requires explicit initialization by calling laftl_initialize(). Because the LAFTL driver is designed to work with the raw Flash devices created by the low-level

NAND Flash drivers, a low-level driver must be initialized before the LAFTL driver. Failure to do this results in the LAFTL not initializing and returning an error.

●

●

●

●

●

Upon initialization, the LAFTL driver sets the driver version and then allocates and initializes the internal state. The driver queries the registry to determine the number of partitions that it manages on the current platform. Each partition may be on a separate raw Flash device, or each raw Flash device may contain more than one partition. For each partition to be supported, the driver queries the registry further to retrieve the following: the name of the raw Flash device to host the partition the flags to be applied when opening the device start block address of the partition number of blocks in the partition whether or not to force a re-initialization of the Flash device

If the current platform does not support partitions, then initialization fails and the driver returns an error through errno.

As each partition is initialized, the LAFTL attempts to retrieve the journal of information that was previously stored on the partition. This journal permanently records information about bad blocks, wear-levelling and other meta-data. If the registry key

LAFTL_CONFIG_PART_FORCE_INIT

is set to 1, then this operation is not performed; instead the LAFTL driver re-initializes the partition. This causes the driver to lose any previous knowledge that it had stored on evolved bad blocks, wear levelling and so forth.

When the Flash partition has been setup and initialized, the LAFTL driver creates a new

Flash device with the type OSPLUS_DEVICE_TYPE_FLASH_STORAGE and registers it with the device library using the prefix /flash/laftl and postfixed with the device instance number. If this is the first device to be registered with the prefix /flash/laftl, the device name is /flash/laftl0. If other LAFTL Flash devices are already registered with the device library, the device name can be /flash/laftl1 or /flash/laftl2, and so on, so that every device is registered with a unique prefix.

12.5.3 STNFTL driver initialization

The STNFTL driver requires explicit initialization by calling stnftl_initialize().

Because the STNFTL driver is designed to work with the raw Flash devices created by the low-level NAND Flash drivers, any low-level driver should be initialized before the STNFTL driver. Failure to do this results in the STNFTL not initializing and returning an error.

Upon initialization, the STNFTL driver sets the driver version and then allocates and initializes the internal state. The driver queries the registry to determine the number of partitions that it manages on the current platform. Each partition may be on a separate raw

Flash device, or each raw Flash device may contain more than one partition. For each partition to be supported the registry is further queried to retrieve the raw Flash device name

458/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

to host the partition and the flags with which to open it, and the partition details including start block, and number of blocks. If the current platform does not support any partitions then initialization fails and an error is returned through errno.

As each partition is initialized, the blocks on the underlying raw Flash device are scanned to initialize the wear levelling and bad block management. The driver assumes that the blocks that store the partition on the underlying raw Flash device have been previously initialized. If this is not the case, then they must first be erased and any bad blocks marked. The underlying blocks that the partition uses can be erased automatically if the registry option

STNFTL_CONFIG_PART_ERASE_FIRST

is set to 1. Only those blocks used by the partition are erased; all others are left as is.

When the Flash partition has been setup and initialized, the STNFTL driver creates a new

Flash device with the type OSPLUS_DEVICE_TYPE_FLASH_STORAGE and registers it with the device library using the prefix /flash/stnftl and postfixed with the device instance number. If this is the first device to be registered with the prefix /flash/stnftl, the device name is /flash/stnftl0. If other STNFTL Flash devices are already registered with the device library, the device name can be /flash/stnftl1 or /flash/stnftl2, and so on, so that each device is registered with a unique prefix. An application can then use the Flash device as any normal storage device.

12.6 Flash drivers usage model

The low-level NAND Flash drivers are not designed to be used directly by end user applications. Because Flash has a finite number of write cycles, it requires some higher level interface that can provide wear levelling, to ensure that each block or page on the Flash is evenly used, and bad block management to cope in the cases where a block or page can no longer be read or programmed. Data is stored in the NAND Flash device pages, whereas information regarding wear levelling and bad blocks is usually stored in the spare area associated with each page.

It is expected that an application only accesses the raw NAND Flash device if, for example, it implements its own wear levelling and bad block management. In this scenario there are many pieces of information that must be known, including the page data size, spare area size, block size, block count, page count, plane size and plane count. All of this information is returned by issuing the OSPLUS_IOCTL_NAND_READ_INFO ioctl. This ioctl will also return if the advanced API is supported to provide greater performance.

The low-level NAND drivers may be used with small page (512 bytes), large page

(2048 bytes) and very large page (4096 bytes) flash devices.

12.6.2 Low-level NAND driver basic usage model

In the low-level NAND driver basic usage model, the whole of the NAND Flash device is treated as a single large device with blocks and pages. Reading and writing the NAND Flash device occurs a single page at a time, and erasing the NAND Flash device occurs a single block at a time.

To read and write a page or spare on the NAND Flash device we would normally use the ioctls OSPLUS_IOCTL_NAND_READ, and OSPLUS_IOCTL_NAND_PROGRAM. The application passes a structure to these ioctls to specify the option flags, the page to access and the

7702033 Rev 27 459/515

OSPlus Flash drivers UM1150

data buffer. The option flags specify whether to access only the page data, only the spare area, or both.

Often, when a page is written, the spare area associated with the page is also written with management information, such as the number of times the page has been written or an error correcting code (ECC) value. Using the option flags we can write to both the page and spare in one operation or in two operations - one to write the page data and the other to write the spare area.

If no option flags are specified for the read or write, then the driver assumes that the spare area is not used by the application. In this case, if the low-level driver supports automatic

ECC, it may use the spare internally to store ECC data. In such a scenario, reads and writes with and without option flags being specified should not be mixed, as the ECC data may become corrupt. It is recommended that when operating in this manner, all pages are read and written using the device_block_read() and device_block_write() functions.

The lba parameter specifies the first page to access, the buffer parameter points at the data to read or write and the size parameter contains the number of pages to access.

Under normal usage, a page or spare area may only be written once. To re-write a currently written page or spare area, the page or spare area must first be erased. It is not possible to erase a single, individual page or spare area at a time; instead, the application must erase a complete block of pages and spare areas in a single operation. Use the ioctl

OSPLUS_IOCTL_NAND_BLOCK_ERASE

to erase a block. Erasing a block resets every page and spare area in the block to 0xFF and any programmed bad block information is lost.

12.6.3 Low-level NAND driver advanced usage model

Before using the low-level NAND driver advanced usage model, first check that the NAND device supports the advanced API. This is done by passing a nand_info_t structure pointer to the ioctl OSPLUS_IOCTL_NAND_READ_INFO and checking that the structure member adv_ioctls is set to 1. If the NAND device does not support the advanced API, your application must follow the basic usage model. Currently, the advanced APIs are only supported when using the flex NAND driver in advanced mode on large page NAND Flash devices.

The advanced API operates on each individual plane on the NAND device in parallel.

Therefore, it is imperative to know the total number of planes and the size of each plane in blocks on the device.

The advanced API may:

● concurrently read one page on every plane using the ioctl

OSPLUS_IOCTL_NAND_ADV_READ

●

● concurrently write one page on every plane using the ioctl

OSPLUS_IOCTL_NAND_ADV_PROGRAM concurrently erase one block on every plane using the ioctl

OSPLUS_IOCTL_NAND_ADV_ERASE

.

The low-level driver attempts to make use of any NAND device multi-plane commands available to optimally program the operation. The advanced API does not provide any way for an application to read or write spares. The spares are used internally to provide automatic ECC checking.

To get maximum concurrency from the advanced API, operate on the same page or block on each plane wherever possible. For example, write to page 0, block 0 on all planes. To operate on a single plane or a subset of the total planes on the NAND device only, then the

460/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

page and block address for all planes not being operated upon is set to 0xFFFFFFFF.

Failure to do this may result in undefined behavior.

12.6.4 EMI low-level NAND driver memory caching

By default, the EMI NAND driver uses the CPU to read and write data to the NAND Flash device. This means that data is correctly read from or written to the NAND Flash device, regardless of whether it is in uncached memory or not.

If the EMI NAND driver inrep or outrep function registry options are specified to DMA accelerate the data transfers, then it is the responsibility of these functions to ensure that the read or write is handled in the most efficient manner.

●

If the user buffer passed-in is determined to be uncached memory (using the OSPlus

API described in

Section 2.12: Uncached memory recording on page 19

) and 32-bit aligned, it may be used directly.

● If the buffer is not in uncached memory, but is cache line aligned, the buffer must be purged from the cache before it may be used directly during the read or write.

In all other cases, the user buffer must be staged through an internal buffer. Therefore, for maximum efficiency, all read and write buffers should be 32-bit aligned and located in a region of uncached memory registered with the OSPlus uncached memory manager. If this is not possible, buffers must at least be allocated with the cache safe allocator, described in

Section 2.9: Cache management on page 18

.

12.6.5 Flex low-level NAND driver memory caching

When the flex NAND driver is operating in standard mode, it uses the CPU to read and write data to the NAND Flash device. This means that data is correctly read from or written to the

NAND Flash device, regardless of whether it is in uncached memory or not. The only restriction on the data buffers is that they must be 32-bit aligned.

When operating in advanced mode, callbacks must have been specified in the registry options to control the FDMA. Because of this, all data transfers in advanced mode are handled by the FDMA hardware. The FDMA has a restriction that all buffers must be 64-byte aligned, but the buffers may be in cached or uncached memory. If required, the driver can correctly purge the buffer from the cache before use, if the buffers are correctly aligned.

Failure to correctly align buffers results in an error being returned on any read or write operations.

12.6.6 LAFTL driver usage model

An application determines the device block size and number of blocks by opening the

LAFTL device and issuing the OSPlus common ioctls OSPLUS_IOCTL_BLOCK_SIZE and

OSPLUS_IOCTL_NUM_BLOCKS

. It can also query the supported I/O size with the OSPlus common ioctl OSPLUS_IOCTL_PREF_IO_SIZE. All I/O requests to the LAFTL must be aligned to this number of blocks, and be a multiple of this number of blocks. The application reads or writes data using the device_block_read() and device_block_write() functions. Obtaining the number of blocks on the device ensures that the read or write does not exceed the number of blocks available. After each read or write, the application must check the return code for error; on error, errno is set. Reads are allowed to be from any block address that is aligned with the preferred I/O size. Writes, however, must be to successive block addresses that increase in fixed increments on the device (or block address 0) such that the block address is always a multiple of the preferred I/O size.

7702033 Rev 27 461/515

OSPlus Flash drivers UM1150

Generally, the LAFTL device is not accessed directly, but is instead mounted with VFS as an

LAFS file system and all file input and output handled by the VFS.

The LAFTL driver may be used with large page (2048 bytes) and very large page

(4096 bytes) flash devices only.

12.6.7 STNFTL driver usage model

The device block size and number of blocks are found by opening the STNFTL device and issuing the OSPlus common ioctls OSPLUS_IOCTL_BLOCK_SIZE and

OSPLUS_IOCTL_NUM_BLOCKS

. Data can then be read or written using the device_block_read()

and device_block_write() functions. Obtaining the number of blocks on the device ensures the read or write does not exceed the number of blocks available. Reads and writes must also be multiples of the device block size. After each read or write, the return code must be checked for error; on error, errno is set.

Generally, the STNFTL device is not accessed directly, but is instead mounted with VFS as either a FAT or E2FS file system and all file input and output handled by the VFS.

The STNFTL driver may be used with small page (512 bytes) and large page (2048 bytes) flash devices only. As the E2FS file system only supports 512 byte blocks,

STMicroelectronics recommend that it is not used with the STNFTL driver because the file system is not supported on large page devices. Instead, we recommend that the FAT file system is used with STNFTL, as this file system does support 512 byte and 2048 byte blocks.

462/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

12.7 Flash drivers header files

Each OSPlus storage driver has its own header file. This contains all configuration options, types and function definitions supported by the driver.

12.7.1 EMI low-level NAND driver header file: eminand.h

All the definitions relating to the EMI NAND driver are in the file eminand.h. The functions defined in eminand.h are explained in

Section 12.10.1: EMI low-level NAND driver functions on page 481

.

Table 204.

Configuration options defined in eminand.h

Define Description

EMINAND_CONFIG_PATH

EMINAND_CONFIG_COUNT

Registry path to EMI NAND configuration entries.

Registry key to hold an integer corresponding to the number of EMI NAND devices present in the system.

EMINAND_CONFIG_INIT_FN

EMINAND_CONFIG_CMD_ADDR

EMINAND_CONFIG_ADDR_ADDR

EMINAND_CONFIG_DATA_ADDR

EMINAND_CONFIG_ALE_FN

EMINAND_CONFIG_CLE_FN

EMINAND_CONFIG_BUS_WIDTH

EMINAND_CONFIG_PAGE_SIZE

EMINAND_CONFIG_SPARE_SIZE

EMINAND_CONFIG_BLOCK_SIZE

EMINAND_CONFIG_BLOCK_COUNT

EMINAND_CONFIG_INREP_FN

EMINAND_CONFIG_OUTREP_FN

Refer to

Table 200: Configuration options defined in eminand.h on page 449

.

Table 205.

Functions defined in eminand.h

Function

eminand_initialize()

Description

Initialize the EMI NAND driver

7702033 Rev 27 463/515

OSPlus Flash drivers UM1150

464/515

All the definitions relating to the flex NAND driver are in the file flex.h. The functions defined in flex.h are explained in

Section 12.10.2: Flex low-level NAND driver functions on page 482

.

Table 206.

Configuration options defined in flex.h

Define

FLEX_CONFIG_PATH

FLEX_CONFIG_COUNT

Description

Registry path to flex NAND configuration entries.

Registry key to hold an integer corresponding to the number of flex NAND devices present in the system.

FLEX_CONFIG_INIT_FN

FLEX_CONFIG_BASE

FLEX_CONFIG_INTR

FLEX_CONFIG_ALT_INTR

FLEX_CONFIG_INTR_LEVEL

FLEX_CONFIG_INTR_TRIGGER

FLEX_CONFIG_INTR_ENB_FN

FLEX_CONFIG_INREP_FN

FLEX_CONFIG_OUTREP_FN

FLEX_CONFIG_FLAGS

FLEX_CONFIG_FLEX_BANK

FLEX_CONFIG_CTRL_TIMING

FLEX_CONFIG_WEN_TIMING

FLEX_CONFIG_REN_TIMING

FLEX_CONFIG_ADVANCED_MODE

FLEX_CONFIG_FDMA_SETUP

FLEX_CONFIG_FDMA_WAIT

FLEX_CONFIG_FDMA_ABORT

FLEX_CONFIG_NAND_DEVICES

FLEX_CONFIG_BLOCK_SIZE

FLEX_CONFIG_BANK_COUNT

FLEX_CONFIG_BANK_MUX_CFG

FLEX_CONFIG_BANK_CSN_ALT_CFG

FLEX_CONFIG_BANK_CS

FLEX_CONFIG_BUS_WIDTH

FLEX_CONFIG_INTERNAL_CHIPS

FLEX_CONFIG_CELL_LEVELS

FLEX_CONFIG_INTERLEAVE

FLEX_CONFIG_SIM_READ

FLEX_CONFIG_SIM_PROGRAM

FLEX_CONFIG_SIM_ERASE

FLEX_CONFIG_PAGE_SIZE

FLEX_CONFIG_SPARE_SIZE

FLEX_CONFIG_BLOCK_SIZE

FLEX_CONFIG_PLANE_SIZE

FLEX_CONFIG_PLANE_COUNT

Refer to

Table 201: Configuration options defined in flex.h on page 451

.

Table 207.

Types defined in flex.h

Type

flex_afm_regs_t

Description

Type used in flex advanced mode containing FDMA setup.

7702033 Rev 27

UM1150 OSPlus Flash drivers

Table 208.

Functions defined in flex.h

Function

flex_initialize()

Initialize the flex driver

Description

12.7.3 LAFTL driver header file: laftl.h

All the definitions relating to the STNFTL driver are in the file stnftl.h. The functions defined in stnftl.h are explained in

Section 12.10.3: LAFTL driver functions on page 483

.

Table 209.

Configuration options defined in laftl.h

Define

LAFTL_CONFIG_PATH

LAFTL_CONFIG_COUNT

Description

Registry path to LAFTL configuration entries.

Registry key to hold an integer corresponding to the number of NAND devices the LAFTL should manage.

LAFTL_CONFIG_DEVICE_NAME

LAFTL_CONFIG_DEVICE_FLAGS

LAFTL_CONFIG_PART_START_BLOCK

LAFTL_CONFIG_PART_BLOCK_COUNT

LAFTL_CONFIG_PART_FORCE_INIT

Refer to

Table 202: Configuration options defined in laftl.h on page 455

.

Table 210.

Functions defined in laftl.h

Function

laftl_initialize()

Description

Initialize the LAFTL driver

12.7.4 STNFTL driver header file: stnftl.h

All the definitions relating to the STNFTL driver are in the file stnftl.h. The functions defined in stnftl.h are explained in

Section 12.10.4: STNFTL driver functions on page 484

.

Table 211.

Configuration options defined in stnftl.h

Define Description

STNFTL_CONFIG_PATH

STNFTL_CONFIG_COUNT

Registry path to STNFTL configuration entries.

Registry key to hold an integer corresponding to the number of NAND devices the STNFTL should manage.

STNFTL_CONFIG_DEVICE_NAME

STNFTL_CONFIG_DEVICE_FLAGS

STNFTL_CONFIG_PART_START_BLOCK

STNFTL_CONFIG_PART_BLOCK_COUNT

STNFTL_CONFIG_PART_FILL_FACTOR

STNFTL_CONFIG_PART_ERASE_FIRST

Refer to

Table 203: Configuration options defined in stnftl.h on page 456

.

Table 212.

Functions defined in stnftl.h

Function

stnftl_initialize()

Description

Initialize the STNFTL driver

7702033 Rev 27 465/515

OSPlus Flash drivers UM1150

466/515

The Flash drivers define a set of ioctls used by the low-level NAND Flash devices. These ioctls are in the file ioctls/nand.h. For the ioctl definitions, see

Section 12.8 on page

469

.

Table 213.

Ioctls defined in ioctls/nand.h

Ioctl Description

OSPLUS_IOCTL_NAND_READ_ID

OSPLUS_IOCTL_NAND_READ_INFO

OSPLUS_IOCTL_NAND_READ

Read the NAND Flash device electronic signature

Return the NAND Flash device information

Read a page/spare/both on the NAND Flash device

Advanced read a page on the NAND Flash device

OSPLUS_IOCTL_NAND_ADV_READ

OSPLUS_IOCTL_NAND_PROGRAM

OSPLUS_IOCTL_NAND_ADV_PROGRAM

Program a page/spare/both on the NAND Flash device

Advanced program a page on the NAND Flash device

Erase a block on the NAND Flash device

OSPLUS_IOCTL_NAND_BLOCK_ERASE

OSPLUS_IOCTL_NAND_ADV_BLOCK_ERASE

Advanced erase a block on the NAND Flash device

OSPLUS_IOCTL_NAND_IS_A_BAD_BLOCK

Check if a block on the NAND Flash device is bad

OSPLUS_IOCTL_NAND_TEST_BAD_BLOCK

Test if a block on the NAND Flash device is bad

OSPLUS_IOCTL_NAND_MARK_BAD_BLOCK

Mark a block on the NAND Flash device as bad

Table 214.

Electronic signature manufacturer defines in ioctls/nand.h

Defines Description

OSPLUS_NAND_MANUFACTURER_FUJITSU

OSPLUS_NAND_MANUFACTURER_HYNIX

Device is manufactured by Fujitsu

Device is manufactured by Hynix

OSPLUS_NAND_MANUFACTURER_MICRON

Device is manufactured by Micron

OSPLUS_NAND_MANUFACTURER_NATIONAL

Device is manufactured by National Semiconductor

OSPLUS_NAND_MANUFACTURER_RENESAS

Device is manufactured by Renesas

OSPLUS_NAND_MANUFACTURER_SAMSUNG

OSPLUS_NAND_MANUFACTURER_STMICRO

Device is manufactured by Samsung

Device is manufactured by STMicroelectronics

OSPLUS_NAND_MANUFACTURER_TOSHIBA

Device is manufactured by Toshiba

Table 215.

Electronic signature defines in ioctls/nand.h

Defines Description

OSPLUS_NAND_ID_3_INT_CHIP

OSPLUS_NAND_ID_3_INT_CHIP_1

OSPLUS_NAND_ID_3_INT_CHIP_2

OSPLUS_NAND_ID_3_INT_CHIP_4

OSPLUS_NAND_ID_3_INT_CHIP_8

Internal chip number mask

Internal chip number 1

Internal chip number 2

Internal chip number 4

Internal chip number 8

7702033 Rev 27

UM1150 OSPlus Flash drivers

Table 215.

Electronic signature defines in ioctls/nand.h (continued)

Defines Description

OSPLUS_NAND_ID_3_CELL

OSPLUS_NAND_ID_3_CELL_2_LEVEL

OSPLUS_NAND_ID_3_CELL_4_LEVEL

OSPLUS_NAND_ID_3_CELL_8_LEVEL

OSPLUS_NAND_ID_3_CELL_16_LEVEL

OSPLUS_NAND_ID_3_SIM_PRO_PAGE

OSPLUS_NAND_ID_3_SIM_PRO_PAGE_1

OSPLUS_NAND_ID_3_SIM_PRO_PAGE_2

OSPLUS_NAND_ID_3_SIM_PRO_PAGE_4

OSPLUS_NAND_ID_3_SIM_PRO_PAGE_8

OSPLUS_NAND_ID_3_INTERLEAVE_PROG

Cell type mask

2 level cell

4 level cell

8 level cell

16 level cell

Number of simultaneously programmed pages

1 simultaneously programmed page

2 simultaneously programmed pages

4 simultaneously programmed pages

8 simultaneously programmed pages

Interleave program between multiple chips supported

OSPLUS_NAND_ID_3_CACHE_PROG

OSPLUS_NAND_ID_4_PAGE_SIZE

OSPLUS_NAND_ID_4_PAGE_SIZE_1KB

OSPLUS_NAND_ID_4_PAGE_SIZE_2KB

Cache program supported

Page size (without redundant data) mask

1 Kbyte page size

2 Kbytes page size

4 Kbytes page size

8 Kbytes page size

OSPLUS_NAND_ID_4_PAGE_SIZE_4KB

OSPLUS_NAND_ID_4_PAGE_SIZE_8KB

OSPLUS_NAND_ID_4_SPARE_SIZE

OSPLUS_NAND_ID_4_SPARE_SIZE_8

Spare size (redundant data) mask

8 bytes per 512 bytes

16 bytes per 512 bytes

OSPLUS_NAND_ID_4_SPARE_SIZE_16

OSPLUS_NAND_ID_4_SEQ_ACCESS

Serial access minimum mask

OSPLUS_NAND_ID_4_SEQ_ACCESS_3050NS

30/50 ns

OSPLUS_NAND_ID_4_SEQ_ACCESS_25NS

25 ns

OSPLUS_NAND_ID_4_BLOCK_SIZE

Block size mask

64 Kbytes block size

OSPLUS_NAND_ID_4_BLOCK_SIZE_64KB

OSPLUS_NAND_ID_4_BLOCK_SIZE_128KB

128 Kbytes block size

OSPLUS_NAND_ID_4_BLOCK_SIZE_256KB

256 Kbytes block size

OSPLUS_NAND_ID_4_BLOCK_SIZE_512KB

512 Kbytes block size

OSPLUS_NAND_ID_5_PLANE_NUMBER

Plane number mask

OSPLUS_NAND_ID_5_PLANE_NUMBER_1

OSPLUS_NAND_ID_5_PLANE_NUMBER_2

OSPLUS_NAND_ID_5_PLANE_NUMBER_4

OSPLUS_NAND_ID_5_PLANE_NUMBER_8

OSPLUS_NAND_ID_5_PLANE_SIZE

1 plane

2 planes

4 planes

8 planes

Plane size mask

7702033 Rev 27 467/515

OSPlus Flash drivers

Table 215.

Electronic signature defines in ioctls/nand.h (continued)

Defines Description

OSPLUS_NAND_ID_5_PLANE_SIZE_64MB

64-Mbit plane

OSPLUS_NAND_ID_5_PLANE_SIZE_128MB

128-Mbit plane

OSPLUS_NAND_ID_5_PLANE_SIZE_256MB

256-Mbit plane

OSPLUS_NAND_ID_5_PLANE_SIZE_512MB

512-Mbit plane

OSPLUS_NAND_ID_5_PLANE_SIZE_1GB

1 Gbit plane

OSPLUS_NAND_ID_5_PLANE_SIZE_2GB

OSPLUS_NAND_ID_5_PLANE_SIZE_4GB

2 Gbit plane

4 Gbit plane

OSPLUS_NAND_ID_5_PLANE_SIZE_8GB

8 Gbit plane

Table 216.

IO access defines in ioctls/nand.h

Defines

OSPLUS_NAND_IO_NONE

OSPLUS_NAND_IO_PAGE

OSPLUS_NAND_IO_SPARE

OSPLUS_NAND_IO_BOTH

Description

Access page data with automatic ECC

Access page data

Access spare area

Access both page data and spare area

Table 217.

Types defined in ioctls/nand.h

Types

nand_info_t nand_id_t nand_io_t nand_adv_io_t nand_adv_erase_t

Description

NAND device information type

Electronic signature type

Page/spare read/program details type

Advanced page read/program details type

Advanced erase details type

UM1150

468/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

12.8 Flash driver ioctls

The ioctls in this section relate to the device library device_ioctl() function. For more

details of how to use the ioctls in this section, see

Section 4.10: Device driver ioctl definitions on page 146

.

The low-level NAND drivers support a subset of the common ioctls as defined in the include file ioctls/common.h and described in

Section 4.6: Device library header file: ioctls/common.h on page 140

. This subset of ioctls is shown in

Table 218

.

Both the EMI NAND and flex drivers also support all of the standard ioctls defined in file ioctls/nand.h

and described in table

Table 219

.

Table 218.

Low-level NAND driver supported ioctls

Ioctl

OSPLUS_IOCTL_NUM_BLOCKS

OSPLUS_IOCTL_BLOCK_SIZE

OSPLUS_IOCTL_CHECK_MEDIA

OSPLUS_IOCTL_WR_PROTECTED

OSPLUS_IOCTL_PREF_IO_SIZE

Description

Get the number of blocks on the device

Get the size of each block on the device

Query the device media state

Query the device media write protect state

Get the preferred IO size

Table 219.

EMI and flex NAND driver supported ioctls

Ioctl Description

OSPLUS_IOCTL_NAND_READ_ID

OSPLUS_IOCTL_NAND_READ_INFO

OSPLUS_IOCTL_NAND_READ

OSPLUS_IOCTL_NAND_ADV_READ

This ioctl retrieves the manufacturer code and device code from the NAND Flash device. Some NAND Flash devices also return additional codes that indicate the

NAND Flash device page size, block size and block count.

This ioctl returns the NAND Flash device information including bus width, page, block, plane sizes and counts and so forth.

This ioctl performs a read of one of the following:

– a page with automatic ECC

– a page without automatic ECC

– a spare

– both a page and a spare from the NAND Flash device

This ioctl performs an advanced page read with automatic ECC from the NAND Flash device where one page from each plane is read in parallel.

7702033 Rev 27 469/515

OSPlus Flash drivers UM1150

Table 219.

EMI and flex NAND driver supported ioctls (continued)

Ioctl Description

OSPLUS_IOCTL_NAND_PROGRAM

OSPLUS_IOCTL_NAND_ADV_PROGRAM

OSPLUS_IOCTL_NAND_BLOCK_ERASE

This ioctl performs a write of one of the following:

– a page with automatic ECC

– a page without automatic ECC

– a spare

– both a page and a spare from the NAND Flash device

This ioctl performs an advanced page write with automatic ECC to the NAND Flash device where one page from each plane is written in parallel.

This ioctl erases a user specified block, destroying all data contained in every page and spare in the block.

OSPLUS_IOCTL_NAND_ADV_BLOCK_

ERASE

This ioctl erases a user specified block on every plane that the NAND device supports in parallel, destroying all data contained in every page and spare in the blocks.

OSPLUS_IOCTL_NAND_IS_A_BAD_BLOCK

This ioctl checks a user specified block to determine if it has been marked bad. If the block is marked as bad, then it must not be used for storing data. The low-level

Flash drivers detect blocks that have been marked bad using either the STMicroelectronics and Samsung methods. OSPlus determines the method to use based on the NAND Flash manufacturer.

OSPLUS_IOCTL_NAND_TEST_BAD_BLOCK

This ioctl attempts to program data to every page in a specified block in order to determine if the block is bad

(that is, not reliable). The data is verified by being read back. When each page has been programmed and read, the block is erased. If the any program or read operation fails, then the block is deemed as bad. Any data in the block is destroyed.

OSPLUS_IOCTL_NAND_MARK_BAD_BLOCK

This ioctl marks a user specified block as bad so that no data can be stored in it. The low-level Flash drivers can mark blocks bad using the STMicroelectronics and

Samsung methods. OSPlus determines the method to use based on the NAND Flash manufacturer.

470/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

12.8.2 LAFTL driver ioctls

The OSPlus LAFTL driver supports a subset of the common ioctls as defined in the include file ioctls/common.h and described in

Section 4.6: Device library header file: ioctls/common.h on page 140

. This subset of ioctls is shown in

Table 220

.

Table 220.

LAFTL driver supported ioctls

Ioctl

OSPLUS_IOCTL_NUM_BLOCKS

OSPLUS_IOCTL_BLOCK_SIZE

OSPLUS_IOCTL_PREF_IO_SIZE

OSPLUS_IOCTL_CHECK_MEDIA

OSPLUS_IOCTL_WR_PROTECTED

Description

Get the number of blocks on the device

Get the size of each block on the device

Get the preferred I/O size in blocks for the device

Query the device media state

Query the device media write protect state

12.8.3 STNFTL driver ioctls

The OSPlus STNFTL driver supports a subset of the common ioctls as defined in the

include file ioctls/common.h and described in

Section 4.6: Device library header file: ioctls/common.h on page 140

. This subset of ioctls is shown in

Table 221

.

Table 221.

STNFTL driver supported ioctls

Ioctl

OSPLUS_IOCTL_NUM_BLOCKS

OSPLUS_IOCTL_BLOCK_SIZE

OSPLUS_IOCTL_CHECK_MEDIA

OSPLUS_IOCTL_WR_PROTECTED

Description

Get the number of blocks on the device

Get the size of each block on the device

Query the device media state

Query the device media write protect state

7702033 Rev 27 471/515

OSPlus Flash drivers UM1150

These NAND device specific ioctl definitions relate to the device_ioctl() call. See

device_ioctl on page 192

for more details.

OSPLUS_IOCTL_NAND_READ_ID

Read the NAND Flash electronic signature

Arguments:

Returns:

Description:

The address of an nand_id_t structure to receive the electronic signature.

Returns 0 for success, -1 for failure.

This ioctl reads the electronic signature of the NAND Flash device into the nand_id_t

structure, the address of which is passed to the ioctl.

The nand_id_t structure has the following format: typedef struct nand_id_s { int bytes; unsigned char data[OSPLUS_NAND_ID_MAXIMUM_SIZE];

} nand_id_t;

All the fields must be set up before issuing the ioctl. They are explained in

Table 222

.

The electronic signature bytes are decoded using the defines in

Table 214 on page 466

.

Table 222.

nand_id_t fields

Field name

bytes data

Description

Length of the electronic signature in bytes

Array containing electronic signature bytes

472/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

OSPLUS_IOCTL_NAND_READ_INFO

Read the NAND Flash device information

Arguments:

Returns:

Description:

The address of an nand_info_t structure to receive the device information.

Returns 0 for success, -1 for failure.

This ioctl reads the configuration information of the NAND Flash device into the nand_info_t

structure, the address of which is passed to the ioctl.

The nand_info_t structure has the following format: typedef struct nand_id_s { unsigned int bus_width; unsigned int page_size; unsigned int page_count; unsigned int page_total; unsigned int spare_size; unsigned int block_size; unsigned int block_count; unsigned int block_total; unsigned int plane_size; unsigned int plane_count; unsigned int plane_total; unsigned int bank_count; unsigned int adv_mode; unsigned int adv_ioctls;

} nand_info_t;

All the fields must be set up before issuing the ioctl. They are described in

Table 223

.

Table 223.

nand_info_t fields

Field name

bus_width page_size page_count page_total spare_size block_size block_count block_total plane_size plane_count plane_total bank_count

Description

Bus width in bits

Page size in bytes

Number of pages in each bank of the device

Total number of pages in all banks of the device

Spare size in bytes

Block size in pages

Number of blocks in each bank of the device

Total number of blocks in all banks of the device

Plane size in blocks

Number of planes in each bank of device

Total number of planes in all banks of the device

Number of banks used by the device

7702033 Rev 27 473/515

OSPlus Flash drivers UM1150

Table 223.

nand_info_t fields

Field name

adv_mode adv_ioctls

Description

Set to 1 if the flex driver is running in advanced mode, else set to 0

Set to 1 if the advanced ioctls are supported, else set to 0

474/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

OSPLUS_IOCTL_NAND_READ

Read from the NAND Flash device

Arguments:

Description:

The address of a nand_io_t structure containing the read details.

This ioctl reads from the NAND Flash device one of the following:

– a page with automatic ECC checking

– page data only

– spare area only

– both page data and spare area

Note: If the low-level driver does not support reading a page with automatic ECC, then it reads the page normally, without ECC.

The nand_io_t structure passed in contains the access flags, page number to read, and the buffer to read the data into.

The nand_io_t structure has the following format: typedef struct nand_io_s { unsigned int flags; unsigned int page; void *buffer;

} nand_io_t;

All the fields must be set up before issuing the ioctl. The fields are described in

Table 224

and

Table 225

.

Table 224.

nand_io_t fields

Field name

flags page buffer

Table 225.

nand_io_t flags

Field name

Description

Flags indicating what to read, see

Table 225

Page or spare number to read

Buffer to read data into or write data from

OSPLUS_NAND_IO_NONE

OSPLUS_NAND_IO_PAGE

OSPLUS_NAND_IO_SPARE

OSPLUS_NAND_IO_BOTH

Description

Access page data and use an automatic ECC check, spare is assumed to be managed by the low-level driver and contains ECC data.

Access page data only. No automatic ECC.

Access spare area only.

Access both page data (without automatic ECC) and spare area.

See also:

OSPLUS_IOCTL_NAND_ADV_READ, OSPLUS_IOCTL_NAND_PAGE_PROGRAM,

OSPLUS_IOCTL_NAND_PAGE_ADV_PROGRAM

7702033 Rev 27 475/515

OSPlus Flash drivers UM1150

OSPLUS_IOCTL_NAND_ADV_READ

Read from the NAND Flash device

Arguments:

Description:

The address of a nand_adv_io_t structure containing the read details.

This ioctl reads a page with automatic ECC checking from each plane on the NAND

Flash device. The nand_adv_io_t structure passed in contains the page number to read on each plane, and buffer to read the data into. If no page is to be read on a given plane then the page number to read must be set to 0xFFFFFFFF for that plane.

The nand_adv_io_t structure has the following format: typedef struct nand_adv_io_s { unsigned int page[OSPLUS_NAND_MAXIMUM_TOTAL_PLANES]; void *buffer;

} nand_adv_io_t;

All the fields must be set up before issuing the ioctl. They are described in

Table 226

.

For optimal performance the same page on each plane should be read.

Table 226.

nand_adv_io_t fields

Field name

page buffer

Description

Array containing the page numbers to read indexed by plane. If no page is to be read for a given plane then set the page for that plane to 0xFFFFFFFF.

Buffer to read data into

See also:

OSPLUS_IOCTL_NAND_READ, OSPLUS_IOCTL_NAND_PAGE_PROGRAM,

OSPLUS_IOCTL_NAND_PAGE_ADV_PROGRAM

476/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

OSPLUS_IOCTL_NAND_PROGRAM

Write to the NAND Flash device

Arguments:

Description:

The address of a nand_io_t structure containing the write details.

This ioctl writes to the NAND Flash device one of the following:

– a page with automatic ECC checking

– page data only

– spare area only

– both page data and spare area

Note: If the low-level driver does not support writing a page with automatic ECC, then it writes a normal page without ECC.

The nand_io_t structure passed in contains the page access flags, page number to write, and buffer to write the data from.

All the fields of the nand_io_t structure must be set up before issuing the ioctl, and

are explained in

Table 224: nand_io_t fields on page 475

and

Table 225: nand_io_t flags on page 475

.

See also:

OSPLUS_IOCTL_NAND_ADV_PROGRAM, OSPLUS_IOCTL_NAND_PAGE_READ,

OSPLUS_IOCTL_NAND_PAGE_ADV_READ

7702033 Rev 27 477/515

OSPlus Flash drivers UM1150

OSPLUS_IOCTL_NAND_ADV_PROGRAM

Write to the NAND Flash device

Arguments:

Description:

The address of a nand_adv_io_t structure containing the write details.

This ioctl writes a page with automatic ECC checking to each plane on the NAND

Flash device. The nand_adv_io_t structure passed in contains the page number to write on each plane, and buffer to write the data from. If no page is to be written on a given plane then the page number to write must be set to 0xFFFFFFFF for that plane.

All the fields must be set up before issuing the ioctl, and are explained in

Table 226: nand_adv_io_t fields on page 476

.

For optimal performance the same page on each plane should be written.

See also:

OSPLUS_IOCTL_NAND_PROGRAM, OSPLUS_IOCTL_NAND_PAGE_READ,

OSPLUS_IOCTL_NAND_PAGE_ADV_READ

OSPLUS_IOCTL_NAND_BLOCK_ERASE

Erase a block on the NAND Flash device

Arguments:

Returns:

Description:

An unsigned integer containing the block number to erase.

Returns 0 for success, -1 for failure.

This ioctl erases the block specified by the parameter passed in. All data in the block, including any bad block information, is erased. When a block is erased, all pages and spare areas are set to 0xFF.

See also:

OSPLUS_IOCTL_NAND_ADV_BLOCK_ERASE

478/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

OSPLUS_IOCTL_NAND_ADV_BLOCK_ERASE

Erase a block on the NAND Flash device

Arguments:

Returns:

Description:

The address of a nand_adv_erase_t structure containing the block to erase on each plane.

Returns 0 for success, -1 for failure.

This ioctl erases a block on each plane on the NAND Flash device. All data in the block including any bad block information is erased. When a block is erased, all pages and spare areas are set to 0xff.

The nand_adv_erase_t structure has the following format: typedef struct nand_adv_erase_s { unsigned int block[OSPLUS_NAND_MAXIMUM_TOTAL_PLANES];

} nand_adv_erase_t;

All the fields must be set up before issuing the ioctl. They are described in

Table 227

.

Table 227.

nand_adv_erase_t fields

block

Field name Description

Array containing the block number to erase indexed by plane. If no block should be accessed on a plane then set the block for that plane index to

0xFFFFFFFF

.

See also:

OSPLUS_IOCTL_NAND_BLOCK_ERASE

OSPLUS_IOCTL_NAND_IS_A_BAD_BLOCK

Check if a block on the NAND Flash device is marked as bad

Arguments:

Returns:

Description:

An unsigned integer containing the block number to check for being bad.

Returns 0 if the block is not marked bad, 1 if the block is marked bad, and -1 for failure.

This ioctl checks the block specified for being bad. NAND Flash devices manufactured by STMicroelectronics and others can be checked for being marked bad in accordance with the manufacturer’s specifications.

See also:

OSPLUS_IOCTL_NAND_TEST_BAD_BLOCK,

OSPLUS_IOCTL_NAND_MARK_BAD_BLOCK

7702033 Rev 27 479/515

OSPlus Flash drivers UM1150

OSPLUS_IOCTL_NAND_TEST_BAD_BLOCK

Test if a block on the NAND Flash device is bad

Arguments:

Returns:

Description:

An unsigned integer containing the block number to test for being bad.

Returns 0 if block is not bad, -1 if block is bad or on failure.

This ioctl attempts to test if the block specified is bad. All data in the block is destroyed. After testing for a bad block, the block is erased.

See also:

OSPLUS_IOCTL_NAND_IS_A_BAD_BLOCK,

OSPLUS_IOCTL_NAND_MARK_BAD_BLOCK

OSPLUS_IOCTL_NAND_MARK_BAD_BLOCK

Mark a block on the NAND Flash device as bad

Arguments:

Returns:

Description:

An unsigned integer containing the block number to mark as bad.

Returns 0 for success, -1 for failure.

This ioctl attempts to mark the block specified as bad. NAND Flash devices manufactured by STMicroelectronics and others can be marked bad in accordance with the manufacturer’s method.

See also:

OSPLUS_IOCTL_NAND_IS_A_BAD_BLOCK,

OSPLUS_IOCTL_NAND_TEST_BAD_BLOCK

480/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

12.10 Flash driver function definitions

12.10.1 EMI low-level NAND driver functions eminand_initialize

Initialize the EMI low-level NAND Flash driver

Definition:

Arguments:

Returns:

Description:

int eminand_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the EMI NAND Flash driver on a supported platform. The initialized

Flash driver creates and registers with the device library, a new device instance for each supported NAND Flash device.

7702033 Rev 27 481/515

OSPlus Flash drivers UM1150

flex_initialize

Initialize the flex low-level NAND Flash driver

Definition:

Arguments:

Returns:

Description:

int flex_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the flex NAND Flash driver on a supported platform. The initialized

Flash driver creates and registers with the device library, a new device instance for each supported NAND Flash device.

482/515 7702033 Rev 27

UM1150 OSPlus Flash drivers

laftl_initialize

Initialize the LAFTL driver

Definition:

Arguments:

Returns:

Description:

int laftl_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the LAFTL driver on a supported platform. When initialized, the

LAFTL driver creates and registers a new device instance for each partition it manages.

7702033 Rev 27 483/515

OSPlus Flash drivers UM1150

12.10.4 STNFTL driver functions stnftl_initialize

Initialize the STNFTL driver

Definition:

Arguments:

Returns:

Description:

int stnftl_initialize (void)

None.

Returns 0 for success, -1 for failure.

This call initializes the STNFTL driver on a supported platform. When initialized, the

STNFTL driver creates and registers a new device instance for each partition it manages.

484/515 7702033 Rev 27

UM1150

Appendix A E2FS soft updates

A.1

Note:

E2FS soft updates

E2FS soft updates overview

Soft updates is a technique where dependencies between metadata blocks are tracked and any writes are committed in a safe order to ensure the on-disk structure is always in a consistent state. This technique has the added advantage of reducing the need to run a file system check (fsck) to a periodic background activity.

The implementation of soft updates in the E2FS file system uses a combination of safe write ordering and delayed metadata writes to provide an interrupt tolerant system, while still providing a reasonable level of performance and low memory usage in an embedded environment.

Two forms of soft update are supported: journaled and non-journaled. Journaling provides the maximum level of resilience, with the cost of additional disk writes whenever metadata updates are performed. The journal ensures that all metadata updates are completely atomic, and it provides protection against disk block corruption caused by powering down a disk drive in the middle of writing blocks.

The journaling performed by E2FS is completely different to the journaling performed by the

Linux ext3 filesystem.

A.3

Soft updates relies on writes to a volume being committed to the storage medium in the order that they were written out by E2FS. If the device has a write cache or does write reordering, soft updates may not work. This could mean that the file system becomes corrupt in the event of a power failure.

When E2FS mounts a volume in soft update mode, it tries to establish the storage device’s characteristics. If the device supports flushing via the ioctl OSPLUS_IOCTL_FLUSH, E2FS will ensure that the device is flushed after each critical meta data write. If flushes are not supported, then E2FS will check the registry key E2FS_REGISTRY_DISABLE_WC in

E2FS_REGISTRY_NODE

, to see if disabling the device’s write cache is permitted. If the key exists, and has a non-zero value, E2FS will attempt to disable the write cache via the ioctl

OSPLUS_IOCTL_WC_CONTROL

.

In the event that the device does not support flush, and disabling the write cache is either not supported or prevented by the registry key setting, E2FS assumes that the device will guarantee write ordering. E2FS also assumes that any writes that have been successfully completed back by the device will not be lost in the event of a power loss.

E2FS on-disk format

The E2FS on-disk format is identical to the format used for the Linux Ext2 file system. By default, Linux only supports block sizes of 1, 2 and 4 Kbytes whereas E2FS support block sizes of 1, 2, 4, 8, 16 and 32 Kbytes.

The on-disk structure consists of several groups, where each group can contain a superblock and group descriptors and always contains a block bitmap, inode bitmap, inode table and data region. See

Figure 2: Volumes and groups

.

7702033 Rev 27 485/515

E2FS soft updates

Figure 2.

Volumes and groups

group 0 group 1 group 2

VOLUME

....

group X-1 group X

UM1150

sb gd bbm ibm it

GROUP data

The first group on the disk is referred to as Group 0 and contains the primary superblock and group descriptors. There are also backup copies of the superblock and group descriptors in groups 1, 3, 5, 7, 3

2

,5

2

,7

2

, and so on.

The final group on the disk may only be a partial group depending on the actual volume size.

It contains the block bitmap, inode bitmap, inode table and possibly a backup copy of the superblock and group descriptors. The data region may be smaller than the other groups.

A.4 Groups

The volume is subdivided into several fixed size groups depending on the block size. The final group may have a reduced data region if the volume size is not an exact multiple of the group size. The size of each group depends on the block size and is summarized in

Table 228

.

Table 228.

Group size

Block size

1 Kbyte

2 Kbytes

4 Kbytes

8 Kbytes

16 Kbytes

32 Kbytes

8 Mbytes

32 Mbytes

128 Mbytes

512 Mbytes

1 Gbyte

2 Gbytes

Group size

486/515 7702033 Rev 27

UM1150 E2FS soft updates

A.5 Superblock

The primary superblock in group 0 is always located at lba 2 and although it is 1024 bytes in length, it always occupies a complete block on the disk (that is, either 1, 2, 4, 8, 16 or

32 Kbytes, depending on the block size).

It contains several critical fields including:

●

●

●

●

●

●

● block size blocks per group inodes per group total number of blocks total number of inodes free block count free inode count

The superblock also contains the current state of the volume (clean or dirty) and various other useful fields including the volume label and UUID.

If the superblock becomes corrupted, it can be recovered during the file system check

(fsck) by reading the backup copies.

The group descriptor array is contained in the block immediately following the superblock on the disk. It consists of a 32 byte group descriptor entry for each group on the volume. The total number of blocks used depends on the number of groups but is always rounded up to a multiple of a full block in size, that is: 1, 2, 4, 8, 16 or 32 Kbytes.

Each group descriptor contains the following fields:

●

●

●

●

●

● block bitmap location inode bitmap location inode table start location number of free blocks in the group number of free inodes in the group number of used directories

If the group descriptors become corrupted they can be recovered during the file system check (fsck) by reading the backup copies.

The block bitmap is exactly one block in size and is present in every group on the disk. It contains a bitmap representing the free state of each block in the group where a 1 represents used and a 0 represents free.

The inode bitmap is exactly one block in size and is present in every group on the disk. It contains a bitmap representing the free state of each inode in the group where a 1 represents used and a 0 represents free.

7702033 Rev 27 487/515

E2FS soft updates UM1150

The inode table contains several inodes as defined in the inodes per group field of the superblock. The inode table is always a multiple of the block size in length.

A.6.4 Inodes

Each file and directory on the volume is represented by an inode. Each inode is 128 bytes in length and contains various fields including size, mode, block count and the data block pointers.

The data block pointers are stored in a 15 entry array where the first 12 entries point directly to the first 12 blocks of the file or directory.

The 13th entry is an indirect block that contains the address of another block that contains pointers to the actual data blocks. The maximum number of entries in this indirect block depends on the block size, but each entry is 4 bytes in length, meaning a 1 Kbyte block contains 256 entries whereas a 32 Kbyte block contains 8192 entries.

The 14th entry is a double indirect block that contains the address of a block that contains the addresses of further indirect blocks. The 15th entry is a triple indirect block that contains the address of a block that contains the addresses of double indirect blocks.

A.6.5 Directories

A directory is a file with a special mode value. The directory file contains several directory entries where the first entry is ‘.’ and points to itself and the second entry is ‘..’ and points to the parent directory. The remaining entries may be empty or contain pointers to other files and subdirectories. Any single entry does not span the border between consecutive blocks.

●

●

●

●

●

A directory entry is of variable size. It contains a reference to an inode and its name. The name can be up to 255 characters in length. The directory entry contains the following fields: inode number entry length name length file type name

488/515 7702033 Rev 27

UM1150 E2FS soft updates

By writing metadata changes in a particular order, it is possible to guarantee the on-disk structures are always in a consistent state, even if the set of changes is interrupted by, for example, a power loss.

The “safe write” order guarantees that any item referenced by another piece of metadata is already present on the disk.

To create a file, perform the following steps:

1.

Select inode.

4. Write directory entry in parent directory.

To add new blocks to a file, perform the following steps:

1.

Select block(s).

2. Write file data.

4. Add block(s) to metadata (write metadata).

A.7.3 Deleting a file (unlink)

To delete a file, perform the following steps:

1.

Set inode size to zero.

2. Remove directory entry from parent.

3. Free all blocks (write block bitmap).

4. Free inode (write inode bitmap).

To delete blocks from a file, perform the following steps:

1.

Set inode size to new value.

2. Remove block(s) from metadata (write metadata).

3. Free blocks (write block bitmap).

A.7.5 Rename

To move a file/dir to a new location, perform the following steps:

1.

Remove old directory entry.

2. Create new directory entry.

7702033 Rev 27 489/515

E2FS soft updates

A.7.6 Creating a directory (mkdir)

To create a new directory, perform the following steps:

1.

Select inode.

UM1150

A.7.7

7. Create directory entry in parent dir.

Removing a directory (rmdir)

To remove a directory, perform the following steps:

1.

Remove directory entry from parent.

2. Set inode size to zero.

3. Free all blocks (write block bitmap).

4. Free inode (write inode bitmap).

To ensure an acceptable level of performance, it is necessary to use some level of caching in order to avoid accessing the disk multiple times for the same block. If cache entries are left ‘dirty’ (that is, not yet flushed), it is important to ensure that the cache uses safe write ordering when they are evicted.

When evicting (or flushing) cache entries, write the data in the following sequence:

1.

File data.

4. Double indirect metadata.

6. Inode.

If the write order for a particular operation is not compatible with the above sequence, the operation flushes the critical entries directly to the disk so that they are no longer present in the cache as ‘dirty’ entries.

490/515

If journaled soft updates are used, then the file system will automatically create a journal file in the root directory of the volume. The existence of this file is hidden from the user. It is a small file, and is never deleted or moved around the volume. The location of the file is also recorded in the superblock. When a volume is mounted, the journal is checked, and if it contains an outstanding disk update, that disk update is performed. This ensures that the last attempted metadata write is always successful.

7702033 Rev 27

UM1150

Appendix B Cache coherency

Cache coherency

B.1 Overview

The STMicroelectronics’ CPUs supported by OSPlus have relatively slow access paths to main memory and therefore use data caches to optimize performance when accessing memory. The data cache sits between the CPU and the system bus, providing the CPU with very fast access to its contents. The data cache is a local memory that contains a copy of data from the main memory, recently accessed by the CPU. Any changes the CPU writes to cacheable memory are initially written only to the data cache. Main memory is left unaltered and updated at some future time. In the meantime, the data cache contains uncommitted changes; it is said to be incoherent with memory. This incoherency is normally invisible to the CPU, provided the CPU consistently accesses these memory locations through the data cache

(1)

. However the incoherency can be visible to other bus master devices

(2)

. This is a side effect of the way caches operate, but quite normal. Incoherency only becomes an issue when the CPU is required to share data with another CPU or I/O device.

B.2 How data caches work

The following is a generalized description of data caches. Specific CPU datasheets provide full descriptions of how a particular STMicroelectronics data cache is implemented. Some have configurable caches with different operating modes (for example, write-through or write-back). Others have only basic functionality.

Data caches view memory in fixed sized chunks known as cache lines. When the cache accesses memory, this achieves good data bus utilization allowing fast implementation.

Cache lines are a power of 2 in size (16 or 32 bytes on current STMicroelectronics CPUs).

Internally, the cache maintains a store of cache lines. Each location in the cache’s store can contain one or more cache lines, each of which has some state information recorded with it.

For example, the memory address to which the cache line corresponds and its state. The state of each cache line can be invalid, clean or dirty. An invalid cache line contains no data.

A clean cache line has not been written to by the CPU ( so, should be an exact copy of the data in memory at that location). A dirty cache line has been written to by the CPU, but the cache has not yet written those changes back to memory.

When each location in the data cache can hold exactly one cache line, the data cache is said to be a direct mapped. When each location can store n cache lines (where n is usually

2

or 4), the cache is said to be multi-way or n-way set associative.

When the CPU makes a memory access to cacheable memory, the data cache uses the address being accessed to decide where to find the corresponding cache line. It then checks to see if any of the cache lines stored at this location match this address. If one does, the CPU request is satisfied with that stored cache line. If it is not, the cache selects one of the cache lines at that location, and if it is dirty writes its contents back to memory. It

1.

On some CPUs it is possible to have both cached and uncached views of the same memory locations. Where this is possible, changes written to memory through one view, may not be visible through the other view, and the software has to accommodate this incoherency issue.

2.

Some (non-STMicroelectronics) architectures contain specialized hardware to ensure cache coherency with memory is maintained through ‘snooping’. No current STMicroelectronics parts have this hardware, so coherency has to be maintained by software.

7702033 Rev 27 491/515

Cache coherency UM1150

then reads in the desired cache line from memory, marks it as clean, records the memory address of this cache line and satisfies the CPU request with this new cache line.

For direct mapped caches there is only one line per store location, therefore there is no selection process for which line to evict. For muti-way caches, the selection of which cache line to evict and replace with the incoming cache line is typically made on a least-recentlyused (LRU) basis.

When the cache cannot satisfy a CPU data request, there is a small performance penalty compared with accessing memory directly without updating the cache. There is also the issue of managing cache coherency. However, the overall performance benefits gained by holding the most-often-used data in a fast local data cache far outweigh these disadvantages.

B.2.2

Data caches provide several operations which allow the manipulation of their contents.

Typically these operations are invalidate, flush and purge. However, not all caches implement all of these functions. Some allow the operations to be applied to specific cache lines, while others apply the operation to the entire cache contents.

Invalidate

Invalidation is the operation of discarding cache lines without writing back to memory. If the lines were dirty the data is lost.

Flush

Flushing is the operation of writing dirty cache lines back to memory. Once a flush is complete, the cache lines are coherent with memory (that is, the data in the cache matches the data in memory), but the cache lines are now marked as clean.

Purge

Purging writes any dirty cache lines back to memory and then invalidates the affected cache lines. Following a purge, the data cache no longer contains any of the cache lines in that range, and so cannot be incoherent.

How incoherency occurs

Cache incoherency occurs when the contents of a data cache line are different from the values in memory for that location. Incoherency can occur as follows:

● CPU writes to cacheable memory

This is the normal way incoherency occurs and is expected behavior. Whenever the

CPU writes to a cacheable memory location, the data cache holds the changed data without writing it back to memory. Until the data is written back to memory, the cache lines are incoherent with memory. This should only be an issue when the data in the cache needs to be passed to another device, such as an I/O device or another CPU.

When this occurs, coherency has to be ensured by immediately purging any dirty lines from the cache. This is normal behavior and how the software manages incoherency. It is only eliminated when strictly necessary.

●

Another bus master writing to memory

This occurs when the data cache contains a copy of memory locations that are being updated by another device, such as an I/O device or another CPU. This incoherency is

492/515 7702033 Rev 27

UM1150

B.3

Cache coherency

the result of a programming error. If a memory location is being updated by another device, that location cannot be allowed to be in the CPU data cache. If it is, the CPU cannot see the changes written by the other device.

How to work with cache incoherency

The management of cache incoherency should only be an issue that concerns device driver writers. Correct handling of cache incoherency within the system ensures correct system operation and optimal performance. The options are that cache incoherency can be avoided or managed.

All data that is to be shared with other devices is only ever accessed by the CPU through uncached memory. This avoids all issues of cache incoherency, since no cache is involved.

This unlikely to be the optimal solution. Main memory is slow, so it only makes sense if the data is not going to be used directly by the CPU, or the data is seldom accessed by the

CPU. A typical example of the first case would be streaming data into memory, where it is to be processed by another device, e.g a hardware codec. Since the data is never going to be accessed by the CPU, it makes no sense to make it cacheable. The second case often occurs where a driver is maintaining in-memory data structures that are used to control an

I/O device. As the CPU seldom accesses the data structures, or possibly only ever writes to the structures, there is no performance penalty in having the data uncacheable.

If the data is to be manipulated by the CPU, using uncacheable memory gives poor performance. In this case it is better to keep the data in cacheable memory, and manage the incoherency when doing I/O.

However, even when using uncached memory, programmers must remain aware of cache coherency issues. All CPUs do some level of ‘write posting’, allowing a write to memory to be completed before the data being written has reached the memory. There is the potential that an uncached write to memory will not have completed when an I/O operation which uses that memory has been started. Should this occur the I/O device would read memory before the write has reached it, resulting in stale data being read. This situation can be avoiding by using a write memory barrier. Some CPUs provide a specific instruction for this purpose. On those that do not, it is sufficient to issue an uncached memory read before starting the I/O operation.

Subject to a set of simple rules, this is often the optimal solution. It allows the CPU to operate on the data at full speed, by virtue of having the data cacheable, yet it still allows the data to be shared with other devices. The rules are derived from the way that data caches work, and use the concept of data “ownership”. If the CPU “owns” the data, the data is allowed to reside inside the CPU data cache, and no other device can access the data in memory. If another device “owns” the data then no part of that data can reside in the CPU data cache. The CPU cannot access it until ownership returns to the CPU. Normally the

CPU owns the data until an I/O operation is started, at which point data ownership transfers to the other device. Ownership remains with the device while the I/O operation is in progress, and it only returns to the CPU when the I/O operation completes.

7702033 Rev 27 493/515

Cache coherency UM1150

Rule 1: Purge I/O buffers before starting I/O

Before starting an I/O operation, the CPU data cache must purge any cache lines that are involved in the I/O. It is not sufficient to flush; the operation must guarantee that all CPU updates to the data have been committed to memory, and the affected cache lines are no longer in the CPU data cache.

Rule 2: CPU cannot access I/O buffers while I/O is in progress

The CPU has no visibility of the I/O progress, so cannot know which parts of the buffer are old data and which parts are new. The processor therefore must not reference the affected part of the I/O buffer while an I/O is in progress. If this is allowed to happen, old data can be placed in the CPU cache. When the I/O device finally signals completion, the CPU then sees old data in the cache (or even a mix of old and new data). It does not correctly see the data recently placed in memory by the I/O device.

Rule 3: I/O buffers cannot share cache line with other data

Even if rules 1 and 2 are strictly followed, accidental incoherency can still occur if the I/O buffer shares cache lines with CPU data structures. In this situation incoherency occurs when the CPU accesses a shared data buffer while an I/O using that buffer is in progress.

This brings the affected cache line in to the data cache, and therefore part of the I/O buffer.

The effect is the same as if Rule 2 had not been followed.

Rule 4: Purge I/O buffers at the end of the I/O operation (ST220/ST231 only)

This post-I/O purge affects only the ST220 and ST231 CPUs, and then only if speculation is enabled. These processors can perform speculative (sometimes called dismissible) loads.

These instructions can have the effect of silently pulling ‘random’ cache lines into the cache, so can violate rule 2. The post-I/O purge ensures that any affected cache lines are discarded before the I/O buffer is given back to the CPU.

B.4 APIs to handle cache incoherency

OSPlus and the underlying RTOS provide several APIs to ease the management of cache incoherency issues.

cache_purge_data()

Purges all cache lines from the data cache that fall within the given memory range.

osplus_cache_alignment()

Returns the alignment required for cache lines on this CPU (an OSPLUS_ALIGN_x value).

osplus_cache_line_size()

Returns the size of a cache line for this CPU.

osplus_cache_safe_allocate()/osplus_cache_safe_allocate_timeout()

Allocates a buffer in cacheable memory that is guaranteed not to share cache lines with anything else.

osplus_dma_prepare()

Prepares a buffer for DMA. This call checks if the memory is cacheable (or not) using osplus_uncached()

, and acts accordingly. For uncacheable memory, it performs a

494/515 7702033 Rev 27

UM1150 Cache coherency

write memory barrier, and returns 0 to indicate the buffer is ready for DMA. If it is a cacheable buffer, the call checks to see if the buffer starts and ends on a cache line boundary, if it does the buffer is purged from the data cache and returns 0. If the cacheable buffer is not suitably aligned, the call returns -1 to indicate the buffer is unsuitable for DMA. The caller should then use a fallback strategy for handling the I/O - for instance staging it through an uncached scratch buffer.

osplus_dma_complete()

This call purges the given buffer from the data cache if the buffer is cacheable, and the

CPU supports speculative loads.

osplus_uncached_register()

This call registers a memory region with OSPlus as an uncached region.

osplus_uncached()

This call determines if the given region is cacheable (or not).

7702033 Rev 27 495/515

Revision history

Revision history

UM1150

Table 229.

Document revision history

Date Revision

12-Nov-2012

12-Sep-2012

01-Nov-2011

14-Feb-2011

29-Sep-2010

27

26

25

X

W

Changes

Updated

OSPLUS_IOCTL_SDMMC_CARD_SELECT_PARTITION on page 445

.

Added

OSPLUS_IOCTL_SDMMC_CARD_SELECT_BOOT_PARTITION on page 445

,

OSPLUS_IOCTL_SDMMC_CARD_QUERY_PARTITION on page 446

,

OSPLUS_IOCTL_SDMMC_CARD_QUERY_BOOT_PARTITION on page 446

and

OSPLUS_IOCTL_SDMMC_CARD_PARTITIONS_SUPPORTED on page 446

.

Corrected an error in

Section 10.6.2: Packet filtering on page 371

.

Updated

Table 197: Ioctls defined in ioctls/sdmmc.h on page 432

.

Added

Table 198: SD/MMC status defines in ioctls/sdmmc.h on page 432

.

Added

OSPLUS_IOCTL_SDMMC_CARD_SELECT_PARTITION on page 445

.

Updated

dev_class_create on page 174

.

Changed default cache mode in

Table 62: E2FS cache modes on page 246

.

Minor changes made to page footers in some chapters.

Added

OSPLUS_IOCTL_ATA_PASS_THROUGH on page 147

.

Added VFS_MODE_HIDDEN to

Table 58: Macros defined in vfs.h on page 243

.

Updated typedef vfs_info_s for

vfs_fscntl on page 276

and

updated

Table 89: vfs_info_t fields on page 278

.

Updated

Section 7.8.2: Service provided by the VFS on page 306

.

In

Chapter 4: OSPlus device model on page 134

: updated str_t to

osplus_str_t

.

Added ioctl

OSPLUS_IOCTL_SPIN_REQUESTS on page 155

.

Added ioctl

OSPLUS_IOCTL_SPIN_UP on page 155

.

Added ioctl

OSPLUS_IOCTL_SPIN_DOWN on page 155

.

Added

Section 7.4.1: Free cluster count configuration on page 252

.

Updated

Table 201: Configuration options defined in flex.h on page 451

.

Updated

Table 206: Configuration options defined in flex.h on page 464

496/515 7702033 Rev 27

UM1150 Revision history

Table 229.

Document revision history (continued)

Date Revision Changes

22-Apr-2010

04-Feb-2010

09-Nov-2009

18-Sep-2009

V

U

T

S

Updated

Section 8.2: Partitions on page 325

.

Updated

Section 8.2.3: Creating and deleting partitions on page 327

.

Updated

lvm_partition_create on page 332

and

lvm_volume_create on page 338

.

Added

lvm_partition_create_adv on page 333

and

lvm_volume_create_adv on page 339

.

Added

Power management options

to

Section 10.2.3: STxMAC driver registry options on page 359

.

Updated

Section 10.6.1: Reading and writing packets on page 369

.

Updated

Section 10.6.3: Power management on page 373

.

Updated

Section 10.10.1: Ethernet driver common ioctls on page 381

.

Minor corrections to clarify possible confusion between E2FS and

ext2 in

Section 7.1: File systems overview on page 238

and

Section 7.3: E2FS file system on page 245

.

Added

Section 7.4.5: Cache configuration on page 254

.

Updated

OSPLUS_IOCTL_GET_POWER_MODE on page 150

.

Updated

OSPLUS_IOCTL_SET_POWER_MODE on page 153

.

Added

Section 7.6: Multi-slot file system on page 256

.

Added functions

msfs_vfs_init

,

msfs_vfs_init_p

and

msfs_vfs_shutdown on page 261

.

Added

Section 2.20: Handle management on page 25

.

Added the following new functions to

Section 2.21: OSPlus library header file: osplus.h on page 25

:

osplus_handle

,

osplus_handle_create

and

osplus_handle_delete

.

Added the IOCTL

OSPLUS_IOCTL_JOYSTICK_SET_RUMBLE

to

Section 4.6: Device library header file: ioctls/common.h on page 140

together with several associated defines.

Updated the following sections relating to the SD/MCC driver:

Section 11.4.3: SD/MMC driver registry options on page 424

,

Section 11.6.3: SD/MMC driver usage model on page 426

,

Section 11.7.4: SD/MMC driver header file: sdmmc.h on page 430

,

Section 11.8.3: SD/MMC driver ioctls on page 432

,

Section 11.9.3:

SD/MMC driver functions on page 436

and added

Section 11.10.1:

SD/MMC driver ioctls on page 444

.

Added information on Flash device page sizes in

Chapter 12:

OSPlus Flash drivers on page 447

.

7702033 Rev 27 497/515

Revision history UM1150

Table 229.

Document revision history (continued)

Date Revision Changes

07-July-2009 R

Throughout: a number of minor amendments.

Updated error messages returned by specific APIs in

Chapter 7:

OSPlus file systems on page 238

.

Added

MMC settings

to

Section 10.2.3: STxMAC driver registry options on page 359

.

Added

Section 10.3: Generic PHY driver configuration on page 365

.

Added

Section 10.5: Generic PHY driver initialization on page 368

.

Updated note in

Chapter 10.6.1: Reading and writing packets on page 369

to clarify that this does not apply to all ethernet drivers.

Updates made to

Section 10.6.3: Power management on page 373

for new power management features in OS21.

Added

Section 10.7: Generic PHY driver usage model on page 374

.

Updates to

Table 138: Configuration option defines in LAN91.h on page 376

.

Updates to

Table 140: Configuration option defines in lan9x1x.h on page 377

.

Updates to

Table 142: Configuration option defines in stxmac.h on page 378

.

Added

Section 10.9: Generic PHY driver header file on page 379

.

Added

Table 151: Features defined in ioctls/ethernet.h on page 382

Added

Table 152: asynchronous flags defined in ioctls/ethernet.h on page 382

.

498/515 7702033 Rev 27

UM1150 Revision history

Table 229.

Document revision history (continued)

Date Revision Changes

R

(continued)

Added

Table 154: Ethernet MMC statistics code defines in ioctls/ethernet.h on page 383

.

Added

Table 155: Ethernet loopback defines in ioctls/ethernet.h on page 386

.

Added

Table 157: Ethernet link defines in ioctls/ethernet.h on page 387

.

Added

Table 158: Power management level settings defined in ioctls/ethernet.h on page 388

.

Added

Table 160: MMC (MAC Management Counter) settings defined in ioctls/ethernet.h on page 388

.

Added

Table 161: CRC offload settings defined in ioctls/ethernet.h on page 388

.

Added

Table 166: STxMAC driver support ethernet ioctls on page 392

.

Added

Section 10.11: Generic PHY driver ioctls on page 393

.

Added the following IOCTLs to

Section 10.12: Ethernet ioctl definitions on page 395

:

OSPLUS_IOCTL_ETH_CLR_MMC_COUNTER

,

OSPLUS_IOCTL_ETH_GET_CRC_OFFLOAD

,

OSPLUS_IOCTL_ETH_GET_LOOPBACK

,

OSPLUS_IOCTL_ETH_GET_MMC_CALLBACK

,

OSPLUS_IOCTL_ETH_GET_MMC_CONFIG

,

OSPLUS_IOCTL_ETH_GET_MMC_COUNTER

,

OSPLUS_IOCTL_ETH_SET_CRC_OFFLOAD

,

OSPLUS_IOCTL_ETH_SET_LOOPBACK

,

OSPLUS_IOCTL_ETH_SET_MMC_CALLBACK

, and

OSPLUS_IOCTL_ETH_SET_MMC_CALLBACK

.

Added

Section 10.13: Generic PHY ioctl definitions on page 409

.

Added

Section 10.15: Generic PHY driver function definitions on page 418

.

Updates to

Table 200: Configuration options defined in eminand.h on page 449

.

Updates to

Table 201: Configuration options defined in flex.h on page 451

.

Updates to

Table 204: Configuration options defined in eminand.h on page 463

.

Updates to

Table 206: Configuration options defined in flex.h on page 464

.

Update to

OSPLUS_IOCTL_NAND_READ_INFO on page 473

.

7702033 Rev 27 499/515

Revision history UM1150

Table 229.

Document revision history (continued)

Date Revision Changes

03-Dec-2008

22-Oct-2008

03-Sep-2008

13-Feb-2008

18-Nov-2007

06-Jun-2007

Q

P

O

N

M

L

Added the ioctls

OSPLUS_IOCTL_GET_POWER_MODE on page 150

and

OSPLUS_IOCTL_SET_POWER_MODE on page 153

.

Updated E2FS cache modes in

Section 7.3.1: Cache configuration on page 246

.

Added

Section 10.6.3: Power management on page 373

and the

associated ioctls

OSPLUS_IOCTL_ETH_GET_PMT_WOL on page 404

and

OSPLUS_IOCTL_ETH_SET_PMT_WOL on page 407

.

Updated

Section 12.4.1: EMI low-level NAND driver registry options on page 449

with new options.

Added information on journaling in

Appendix A: E2FS soft updates on page 485

.

Added new Real time timers API in

Section 2.18: Timers on page 23

.

The functions for this API are documented in

Section 2.22: OSPlus support function definitions on page 30

.

Added details of VFS_FSCNTL_VOL_ATIME_ENABLE to

vfs_fscntl on page 276

.

Updated

Chapter 12: OSPlus Flash drivers on page 447

.

For linear access file system and linear access Flash translation layer, added the following sections:

–

Section 7.5: Linear access file system on page 255

.

–

Section 7.5.1: LAFS header file: lafs.h on page 256

.

–

Section 12.4.3: LAFTL driver registry options on page 455

.

–

Section 12.6.6: LAFTL driver usage model on page 461

.

–

Section 12.7.3: LAFTL driver header file: laftl.h on page 465

.

–

Section 12.10.3: LAFTL driver functions on page 483

Moved details of ioctls/ethernet.h from

Chapter 4: OSPlus device model

to

Section 10.10: Ethernet driver ioctls on page 381

.

Moved details of ioctls/serial.h from

Chapter 4: OSPlus device model

to

Section 9.7: Serial driver ioctls on page 344

.

Updated

Chapter 10: OSPlus ethernet drivers

to include stmac and stgmac in place of stmac110.

Complete rewrite of

Chapter 12: OSPlus Flash drivers

.

Updated to new corporate template

Added information to

Chapter 11: OSPlus storage drivers

in relation

to SD/MMC cards.

New chapter added:

Chapter 12: OSPlus Flash drivers

New ioctl

OSPLUS_IOCTL_WC_CONTROL

added.

Amendments made to

Section 2.13: Memory address translation

and

Section 2.15: Debug functions

.

Amendments made in respect to E2FS in

Section 7.3: E2FS file system

.

500/515 7702033 Rev 27

UM1150 Revision history

Table 229.

Document revision history (continued)

Date Revision Changes

K

J

I

OSPlus support library: Changes to support virtual memory.

OSPlus device model: Ethernet driver synch additions.

OSPlus file systems: Timestamps, VFS, long filename support, formatting, vfs_dcntl, dcntl.

OSPlus ethernet drivers: Read and write packets, auto negotiation, asynch read/write, added:

OSPLUS_IOCTL_ETH_ASYNC_READ

,

OSPLUS_IOCTL_ETH_ASYNC_READ_SUPPORTED

,

OSPLUS_IOCTL_ETH_ASYNC_WRITE

,

OSPLUS_IOCTL_ETH_ASYNC_WRITE_SUPPORTED

.

Appendix: E2FS soft updates. ioctl for low-level device driver to ensure cache writes are properly stored in power fail conditions.

USB information moved to OSPlus USB User Manual (8018282).

Functions, ioctls and macros merged into relevant chapters

Added new sections on DMA management, Version management and Idempotent lock creation. Added the functions osplus_dma_complete()

, osplus_dma_prepare(), osplus_format_double_to_str()

, osplus_version(), osplus_version_set()

.

The appendix “Writing an OSPlus device driver” has been moved into “OSPlus device model”.

OSPlus file systems: Added new section on Block allocator configuration. The appendix Adding a new file system to the VFS has been moved into this chapter.

OSPlus ethernet drivers: This chapter has been completely updated to contain the latest information.

OSPlus storage drivers: New chapter added.

Cache coherency: New appendix added.

OSPlus support library: Added the Timers section. Updated the list of functions defined in osplus.h and the list of types defined in osplus.h.

OSPlus file systems: Added the function vfs_umount_all().

OSPlus ethernet drivers: Updated the list of configuration option defines in stmac110.h.

OSPlus serial driver: Added OSPLUS_IOCTL_ABORT_RD and

OSPLUS_IOCTL_ABORT_WR

to the list of serial driver supported common ioctls.

OSPlus USB driver: Added OSPLUS_IOCTL_FLUSH to the list of serial device supported OSPlus common ioctls.

OSPlus function definitions: Added the functions osplus_timer_create()

, osplus_timer_delete(), osplus_timer_period()

, osplus_timer_period_set(), osplus_timer_start()

, osplus_timer_stop(), vfs_umount_all()

.

7702033 Rev 27 501/515

Revision history UM1150

Table 229.

Document revision history (continued)

Date Revision Changes

H

G

Restructured document to move ioctl, function and macro definitions to a reference section.

OSPlus device model: Added the OSPLUS_IOCTL_POST_WRITES common ioctl. Updated the lists of ethernet device library defines.

Updated the lists of USB device library defines. Renamed the ENCM statistics code

OSPLUS_USB_ENCM_STATS_OSPLUS_USB_ENCM_STATS_OSPLUS

_USB_ENCM_STATS_XMIT_OK

to

OSPLUS_USB_ENCM_STATS_XMIT_OK

.

OSPlus file systems: Updated the Error numbers section to include a list of the VFS generic errno values. Added the Large file support section. Added the functions vfs_fseek64(), vfs_fstat64(), vfs_ftell64()

, vfs_resize64() and vfs_stat64(). Added the types vfs_longlong_t, vfs_stat64_t, e2fs_cache_get_info_t

, e2fs_cache_mode_t, e2fs_cache_set_info_t

. Added the list of E2FS defined values.

Added the Cache configuration section.

OSPlus ethernet drivers: New chapter replacing OSPlus LAN91 driver and OSPlus LAN9118 driver chapters. Added details of

STMAC110 and h2heth.

OSPlus USB driver: Updated the USB driver configuration section.

Updated the USB communications class devices as the cable modem communications class devices are now supported by the

ENCM wrapper. Updated the supported USB ethernet devices.

Added the section on USB unsupported devices. Updated the USB driver device usage model. Updated the configuration macros defined in usblink.h.

OSPlus USB driver: Added joystick.h, keyboard.h, mouse.h, serial.h, usb.h, comm.h, acm.h, encm.h, h2h.h, hub.h

OSPlus device model: Updated USB ioctls: keyboard, mouse, joystick, ethernet, serial devices, communications, host-to-host, hub, acm, encm.

Updated ioctls: keyboard, mouse, joystick, ethernet.

Revisions to text for consistency and readability.

502/515 7702033 Rev 27

UM1150 Revision history

Table 229.

Document revision history (continued)

Date Revision Changes

F

E

D

OSPlus device model: Added

OSPLUS_DEVICE_TYPE_USB_JOYSTICK

to the list of Standard

OSPlus device types. Added the type str_t. Added the following common ioctls: OSPLUS_IOCTL_GET_PID,

OSPLUS_IOCTL_GET_PID_STR

, OSPLUS_IOCTL_GET_SERIAL,

OSPLUS_IOCTL_GET_VID

, OSPLUS_IOCTL_GET_VID_STR.

OSPlus file systems: Added the File system state section. Added the e2fs_vfs_init_p()

and fat_vfs_init_p() functions.

Updated the format of the e2fs_format_t structure. Updated the definitions of vfs_fsck, vfs_mount and vfs_umount, and added definitions for vfs_sync and vfs_sync_all.

OSPlus LAN91 driver: Updated the list of configuration option defines in lan91.h.

OSPlus LAN9118 driver: New chapter added.

OSPlus USB driver: Added joystick as a supported device. Added the keyboard ioctls

Adding a new file system to the VFS : New appendix added.

OSPlus file systems chapter: VFS Partition types section has been rewritten. The functions vfs_format(), vfs_fsck() and vfs_mount()

have been updated.

Major book revision: Chapters 2 through 11 revised and reordered.

OSPlus file systems chapter: Added vfs_fsck(), bigger block sizes, size_t errnos.

Added sections on partition types and error numbers.

OSPlus device model chapter: Added the ioclts defined in the files

ioctls/common.h

, ioctls/keyboard.h, ioctls/mouse.h,

ioctls/serial.h

.

OSPlus LAN91 driver chapter: Added the sections: LAN91 driver configuration, LAN91 driver initialization, LAN91 driver usage model.

Added the definitions relating to the LAN91 driver listed in the file

lan91.h

.

OSPlus PCI driver chapter: Added the sections: PCI driver configuration, PCI driver initialization, PCI driver address space, PCI usage model.

OSPlus serial driver chapter: Added the sections: OSPlus serial driver configuration, OSPlus serial driver initialization, OSPlus serial driver usage model.

7702033 Rev 27 503/515

Revision history UM1150

Table 229.

Document revision history (continued)

Date Revision Changes

D

C

Added support for the subset of common ioctls as defined in the include file ioctls/common.h

OSPlus USB driver chapter: Added the sections: OSPlus USB driver configuration, OSPlus USB driver initialization, OSPlus USB driver enumeration.

Added the subsections: USB communication class devices, USB cable modem devices, USB ethernet devices, USB host-to-host devices, USB hub devices, USB keyboard devices, USB mass storage devices, USB mouse devices, USB serial devices.

Added support for: SoftConnex generic ioctls, SoftConnex ACM ioctls, SoftConnex ENCM ioctls, USB cable modem device ioctl, USB ethernet device ioctls, USB host-to-host device ioctls, USB hub device ioctls, USB keyboard device ioctls, USB mass storage device ioctls, USB mouse device ioctls, USB serial device ioctls.

OSPlus logical volume manager chapter: Updated lvm_partition_t raw_type table in the OSPlus supported partition types section.

Added LVM_CONFIG_PATH and LVM_CONFIG_TASK_PRI to the list of macros.

Updated lvm_initialize().

OSPlus support library chapter: Added descriptions to the table of functions in osplus.h

OSPlus PCI driver chapter: The ioctls have been renamed to have an OSPLUS_ prefix.

OSPlus serial driver chapter: The ioctls have been renamed to have an OSPLUS_ prefix.

OSPlus GPDMA driver chapter: The ioctls have been renamed to have an OSPLUS_ prefix.

OSPlus USB driver chapter: Added table of macros defined in usblink.h

.

Updated definition of USBLINK_Initialize().

504/515 7702033 Rev 27

UM1150 Revision history

Table 229.

Document revision history (continued)

Date Revision Changes

Undated

B

A

OSPlus device model chapter: Added new sections, Device library header file: ioctls/ethernet.h and Device driver ethernet ioctl definitions.

OSPlus registry library chapter: New function added:

registry_load_data()

.

New data types added: registry_key_data_t and registry_node_data_t

.

OSPlus logical volume manager chapter: New function added:

lvm_partition_info()

.

New section added: OSPlus supported partition types.

OSPlus support library chapter: Description of

OSPLUS_INREPn() and OSPLUS_OUTREPn()changed.

New sections added: Name management, List management, Cache management

New functions added: osplus_rwlock_create(), osplus_rwlock_delete()

, osplus_rwlock_downgrade(), osplus_rwlock_enter()

, osplus_rwlock_leave(), osplus_rwlock_tryenter()

, osplus_rwlock_tryupgrade()

OSPlus PCI driver chapter: Address mapping changed in PCI device details section.

Macro names changed from PCI_CPU_TO_PCI and

PCI_PCI_TO_CPU

to CPU_TO_PCI and PCI_TO_CPU respectively.

OSPlus LAN91 driver chapter: New chapter added

OSPlus file systems chapter: Function fat_init() name changed to fat_vfs_init().

New functions added: vfs_fcntl(), vfs_fscntl(), vfs_resize()

.

New macro definition added: VFS_FCNTL_OPT_BLK_SIZE.

New type definitions added: fat_format_t, fat_type_e

OSPlus USB driver: Changed definition of

USBLINK_Initialize()

.

Initial release.

7702033 Rev 27 505/515

List of IOCTLs

List of IOCTLs

UM1150

OSPLUS_IOCTL_ABORT_RD. . . . . . . . . . . . . . . . 146

OSPLUS_IOCTL_ABORT_WR . . . . . . . . . . . . . . . 146

OSPLUS_IOCTL_ATA_PASS_THROUGH . . . . . . 147

OSPLUS_IOCTL_BLOCK_SIZE . . . . . . . . . . . . . . 148

OSPLUS_IOCTL_CHECK_MEDIA . . . . . . . . . . . . 148

OSPLUS_IOCTL_CLR_ERRORS . . . . . . . . . . . . . 148

OSPLUS_IOCTL_CLR_STATUS . . . . . . . . . . . . . . 148

OSPLUS_IOCTL_ETH_ADD_MCAST_FILTERS . 395

OSPLUS_IOCTL_ETH_ANEG_OFF . . . . . . . . . . . 396

OSPLUS_IOCTL_ETH_ANEG_ON . . . . . . . . . . . . 396

OSPLUS_IOCTL_ETH_ASYNC_READ. . . . . . . . . 397

OSPLUS_IOCTL_ETH_ASYNC_READ_

SUPPORTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

OSPLUS_IOCTL_ETH_ASYNC_WRITE . . . . . . . . 398

OSPLUS_IOCTL_ETH_ASYNC_WRITE_

SUPPORTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

OSPLUS_IOCTL_ETH_CLR_MMC_COUNTER . . 399

OSPLUS_IOCTL_ETH_GET_CRC_OFFLOAD . . . 400

OSPLUS_IOCTL_ETH_GET_INFO . . . . . . . . . . . . 400

OSPLUS_IOCTL_ETH_GET_LOOPBACK . . . . . . 401

OSPLUS_IOCTL_ETH_GET_MAC . . . . . . . . . . . . 401

OSPLUS_IOCTL_ETH_GET_MCAST_FILTERS . 401

OSPLUS_IOCTL_ETH_GET_MCAST_HASH_

TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

OSPLUS_IOCTL_ETH_GET_MMC_CALLBACK . 402

OSPLUS_IOCTL_ETH_GET_MMC_CONFIG . . . . 403

OSPLUS_IOCTL_ETH_GET_MMC_COUNTER . . 403

OSPLUS_IOCTL_ETH_GET_PKT_FILTER . . . . . 403

OSPLUS_IOCTL_ETH_GET_PMT_WOL . . . . . . . 404

OSPLUS_IOCTL_ETH_GET_STATUS . . . . . . . . . 404

OSPLUS_IOCTL_ETH_SET_CRC_OFFLOAD . . . 405

OSPLUS_IOCTL_ETH_SET_LINK . . . . . . . . . . . . 405

OSPLUS_IOCTL_ETH_SET_LOOPBACK . . . . . . 405

OSPLUS_IOCTL_ETH_SET_MAC . . . . . . . . . . . . 405

OSPLUS_IOCTL_ETH_SET_MCAST_FILTERS. . 406

OSPLUS_IOCTL_ETH_SET_MCAST_HASH_

TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

OSPLUS_IOCTL_ETH_SET_MMC_CALLBACK. . 408

OSPLUS_IOCTL_ETH_SET_MMC_CONFIG . . . . 408

OSPLUS_IOCTL_ETH_SET_PKT_FILTER. . . . . . 406

OSPLUS_IOCTL_ETH_SET_PMT_WOL . . . . . . . 407

OSPLUS_IOCTL_FLUSH. . . . . . . . . . . . . . . . . . . . 149

OSPLUS_IOCTL_GET_ERRORS . . . . . . . . . . . . . 149

OSPLUS_IOCTL_GET_FEATURES . . . . . . . . . . . 149

OSPLUS_IOCTL_GET_PID . . . . . . . . . . . . . . . . . . 149

OSPLUS_IOCTL_GET_PID_STR . . . . . . . . . . . . . 149

OSPLUS_IOCTL_GET_POWER_MODE. . . . . . . . 150

OSPLUS_IOCTL_GET_RD_MODE . . . . . . . . . . . . 150

OSPLUS_IOCTL_GET_RD_TIMEOUT . . . . . . . . . 150

OSPLUS_IOCTL_GET_SERIAL . . . . . . . . . . . . . . 151

OSPLUS_IOCTL_GET_STATUS. . . . . . . . . . . . . . 151

OSPLUS_IOCTL_GET_VID . . . . . . . . . . . . . . . . . . 151

OSPLUS_IOCTL_GET_VID_STR . . . . . . . . . . . . . 151

OSPLUS_IOCTL_GET_WR_MODE . . . . . . . . . . . .152

OSPLUS_IOCTL_GET_WR_TIMEOUT . . . . . . . . .152

OSPLUS_IOCTL_GPDMA_CLAIM . . . . . . . . . . . . .214

OSPLUS_IOCTL_GPDMA_FREE . . . . . . . . . . . . . .214

OSPLUS_IOCTL_GPDMA_START . . . . . . . . . . . . .214

OSPLUS_IOCTL_GPDMA_WAIT . . . . . . . . . . . . . .215

OSPLUS_IOCTL_JOYSTICK_GET_ALL_

VALUES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

OSPLUS_IOCTL_JOYSTICK_GET_BTN_

BITMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

OSPLUS_IOCTL_JOYSTICK_GET_BTN_

COUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

OSPLUS_IOCTL_JOYSTICK_GET_HAT_

SWITCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

OSPLUS_IOCTL_JOYSTICK_GET_RX . . . . . . . . .158

OSPLUS_IOCTL_JOYSTICK_GET_RX_BND . . . .158

OSPLUS_IOCTL_JOYSTICK_GET_RY . . . . . . . . .159

OSPLUS_IOCTL_JOYSTICK_GET_RY_BND . . . .159

OSPLUS_IOCTL_JOYSTICK_GET_RZ . . . . . . . . .159

OSPLUS_IOCTL_JOYSTICK_GET_RZ_BND. . . . .159

OSPLUS_IOCTL_JOYSTICK_GET_SLIDER . . . . .160

OSPLUS_IOCTL_JOYSTICK_GET_SLIDER_

BND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160

OSPLUS_IOCTL_JOYSTICK_GET_X. . . . . . . . . . .157

OSPLUS_IOCTL_JOYSTICK_GET_X_BND . . . . . .157

OSPLUS_IOCTL_JOYSTICK_GET_Y. . . . . . . . . . .157

OSPLUS_IOCTL_JOYSTICK_GET_Y_BND . . . . . .157

OSPLUS_IOCTL_JOYSTICK_GET_Z. . . . . . . . . . .158

OSPLUS_IOCTL_JOYSTICK_GET_Z_BND . . . . . .158

OSPLUS_IOCTL_JOYSTICK_SET_RUMBLE . . . .161

OSPLUS_IOCTL_KEYBOARD_COUNT . . . . . . . . .162

OSPLUS_IOCTL_KEYBOARD_GETKEY . . . . . . . .162

OSPLUS_IOCTL_MOUSE_CLR_BTN_DATA. . . . .170

OSPLUS_IOCTL_MOUSE_CLR_BTN_PRESS . . .171

OSPLUS_IOCTL_MOUSE_CLR_BTN_REL . . . . . .172

OSPLUS_IOCTL_MOUSE_GET_ALL_VALUES. . .173

OSPLUS_IOCTL_MOUSE_GET_BTN_BITMAP. . .169

OSPLUS_IOCTL_MOUSE_GET_BTN_COUNT . . .169

OSPLUS_IOCTL_MOUSE_GET_BTN_DATA. . . . .170

OSPLUS_IOCTL_MOUSE_GET_BTN_PRESS . . .171

OSPLUS_IOCTL_MOUSE_GET_BTN_REL . . . . . .172

OSPLUS_IOCTL_MOUSE_GET_TWHEEL . . . . . .167

OSPLUS_IOCTL_MOUSE_GET_TWHEEL_BND. .168

OSPLUS_IOCTL_MOUSE_GET_WHEEL. . . . . . . .166

OSPLUS_IOCTL_MOUSE_GET_WHEEL_BND . . .167

OSPLUS_IOCTL_MOUSE_GET_X . . . . . . . . . . . . .163

OSPLUS_IOCTL_MOUSE_GET_X_BND . . . . . . . .163

OSPLUS_IOCTL_MOUSE_GET_XY. . . . . . . . . . . .165

OSPLUS_IOCTL_MOUSE_GET_XY_BND . . . . . . .166

OSPLUS_IOCTL_MOUSE_GET_Y . . . . . . . . . . . . .164

OSPLUS_IOCTL_MOUSE_GET_Y_BND . . . . . . . .164

OSPLUS_IOCTL_MOUSE_SET_TWHEEL. . . . . . .168

OSPLUS_IOCTL_MOUSE_SET_TWHEEL_BND . .168

506/515 7702033 Rev 27

UM1150 List of IOCTLs

OSPLUS_IOCTL_MOUSE_SET_WHEEL . . . . . . . 167

OSPLUS_IOCTL_MOUSE_SET_WHEEL_BND . . 167

OSPLUS_IOCTL_MOUSE_SET_X . . . . . . . . . . . . 163

OSPLUS_IOCTL_MOUSE_SET_X_BND . . . . . . . 164

OSPLUS_IOCTL_MOUSE_SET_XY . . . . . . . . . . . 165

OSPLUS_IOCTL_MOUSE_SET_XY_BND . . . . . . 166

OSPLUS_IOCTL_MOUSE_SET_Y . . . . . . . . . . . . 164

OSPLUS_IOCTL_MOUSE_SET_Y_BND . . . . . . . 165

OSPLUS_IOCTL_NAND_ADV_BLOCK_ERASE . 479

OSPLUS_IOCTL_NAND_ADV_PROGRAM . . . . . 478

OSPLUS_IOCTL_NAND_ADV_READ. . . . . . . . . . 476

OSPLUS_IOCTL_NAND_BLOCK_ERASE . . . . . . 478

OSPLUS_IOCTL_NAND_IS_A_BAD_BLOCK. . . . 479

OSPLUS_IOCTL_NAND_MARK_BAD_BLOCK . . 480

OSPLUS_IOCTL_NAND_PROGRAM . . . . . . . . . . 477

OSPLUS_IOCTL_NAND_READ . . . . . . . . . . . . . . 475

OSPLUS_IOCTL_NAND_READ_ID. . . . . . . . . . . . 472

OSPLUS_IOCTL_NAND_READ_INFO . . . . . . . . . 473

OSPLUS_IOCTL_NAND_TEST_BAD_BLOCK . . . 480

OSPLUS_IOCTL_NUM_BLOCKS . . . . . . . . . . . . . 152

OSPLUS_IOCTL_PCI_CFG_RW. . . . . . . . . . . . . . 229

OSPLUS_IOCTL_PCI_ENABLE . . . . . . . . . . . . . . 232

OSPLUS_IOCTL_PCI_GEN_MADIM. . . . . . . . . . . 232

OSPLUS_IOCTL_PCI_GET_MBAR. . . . . . . . . . . . 233

OSPLUS_IOCTL_PCI_INFO . . . . . . . . . . . . . . . . . 234

OSPLUS_IOCTL_PCI_INTERRUPT . . . . . . . . . . . 235

OSPLUS_IOCTL_PCI_IO_RW. . . . . . . . . . . . . . . . 231

OSPLUS_IOCTL_PHY_GET_CALLBACK. . . . . . . 412

OSPLUS_IOCTL_PHY_GET_LINK . . . . . . . . . . . . 411

OSPLUS_IOCTL_PHY_GET_LOOPBACK . . . . . . 412

OSPLUS_IOCTL_PHY_GET_REG . . . . . . . . . . . . 410

OSPLUS_IOCTL_PHY_GET_STATUS . . . . . . . . . 411

OSPLUS_IOCTL_PHY_PROBE . . . . . . . . . . . . . . 409

OSPLUS_IOCTL_PHY_RESET . . . . . . . . . . . . . . . 409

OSPLUS_IOCTL_PHY_SET_CALLBACK . . . . . . . 413

OSPLUS_IOCTL_PHY_SET_LINK . . . . . . . . . . . . 411

OSPLUS_IOCTL_PHY_SET_LOOPBACK . . . . . . 412

OSPLUS_IOCTL_PHY_SET_REG . . . . . . . . . . . . 410

OSPLUS_IOCTL_PHY_UPDATE . . . . . . . . . . . . . 410

OSPLUS_IOCTL_POST_WRITES. . . . . . . . . . . . . 153

OSPLUS_IOCTL_PURGE . . . . . . . . . . . . . . . . . . . 153

OSPLUS_IOCTL_SDMMC_CARD_PARTITIONS_

SUPPORTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

OSPLUS_IOCTL_SDMMC_CARD_QUERY_

BOOT_PARTITION . . . . . . . . . . . . . . . . . . . . . . . 446

OSPLUS_IOCTL_SDMMC_CARD_QUERY_

PARTITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

OSPLUS_IOCTL_SDMMC_CARD_SELECT_

BOOT_PARTITION . . . . . . . . . . . . . . . . . . . . . . . 445

OSPLUS_IOCTL_SDMMC_CARD_SELECT_

PARTITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

OSPLUS_IOCTL_SDMMC_GET_BUS_POWER . 445

OSPLUS_IOCTL_SDMMC_GET_BUS_SPEED . . 444

OSPLUS_IOCTL_SDMMC_GET_BUS_WIDTH . . 444

OSPLUS_IOCTL_SDMMC_GET_STATUS . . . . . . 444

OSPLUS_IOCTL_SERIAL_GET_BAUD . . . . . . . . 347

OSPLUS_IOCTL_SERIAL_GET_CONFIG . . . . . . 347

OSPLUS_IOCTL_SERIAL_GET_DATA . . . . . . . . .347

OSPLUS_IOCTL_SERIAL_GET_MODE . . . . . . . . .348

OSPLUS_IOCTL_SERIAL_GET_PARITY. . . . . . . .348

OSPLUS_IOCTL_SERIAL_GET_STOP . . . . . . . . .348

OSPLUS_IOCTL_SERIAL_SET_BAUD . . . . . . . . .349

OSPLUS_IOCTL_SERIAL_SET_CONFIG . . . . . . .349

OSPLUS_IOCTL_SERIAL_SET_DATA. . . . . . . . . .349

OSPLUS_IOCTL_SERIAL_SET_MODE . . . . . . . . .350

OSPLUS_IOCTL_SERIAL_SET_PARITY . . . . . . . .350

OSPLUS_IOCTL_SERIAL_SET_STOP . . . . . . . . .350

OSPLUS_IOCTL_SET_POWER_MODE. . . . . . . . .153

OSPLUS_IOCTL_SET_RD_MODE . . . . . . . . . . . . .154

OSPLUS_IOCTL_SET_RD_TIMEOUT . . . . . . . . . .154

OSPLUS_IOCTL_SET_WR_MODE . . . . . . . . . . . .154

OSPLUS_IOCTL_SET_WR_TIMEOUT. . . . . . . . . .155

OSPLUS_IOCTL_SPIN_DOWN . . . . . . . . . . . . . . .155

OSPLUS_IOCTL_SPIN_REQUESTS . . . . . . . . . . .155

OSPLUS_IOCTL_SPIN_UP. . . . . . . . . . . . . . . . . . .155

OSPLUS_IOCTL_WAIT . . . . . . . . . . . . . . . . . . . . . .155

OSPLUS_IOCTL_WC_CONTROL . . . . . . . . . . . . .156

OSPLUS_IOCTL_WR_PROTECTED . . . . . . . . . . .156

7702033 Rev 27 507/515

List of functions

List of functions

UM1150

ata_initialize . . . . . . . . . . . . . . . . . . . . . . . . . .434

cache_purge_data . . . . . . . . . . . . . . . . . . . . . .30

cache_purge_data_all . . . . . . . . . . . . . . . . . . . .31

chmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310

close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310

closedir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310

CPU_TO_PCI . . . . . . . . . . . . . . . . . . . . . . . . .237

dcntl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311

defrag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311

dev_class_create . . . . . . . . . . . . . . . . . . . . . .174

dev_class_delete . . . . . . . . . . . . . . . . . . . . . .178

dev_instance_create . . . . . . . . . . . . . . . . . . . .179

dev_instance_delete . . . . . . . . . . . . . . . . . . . .180

device_attribute . . . . . . . . . . . . . . . . . . . . . . . .181

device_attribute_data . . . . . . . . . . . . . . . . . . .182

device_attribute_data_set . . . . . . . . . . . . . . . .185

device_attribute_delete . . . . . . . . . . . . . . . . . .183

device_attribute_set . . . . . . . . . . . . . . . . . . . .184

device_block_read . . . . . . . . . . . . . . . . . . . . .186

device_block_write . . . . . . . . . . . . . . . . . . . . .187

device_callback_attach . . . . . . . . . . . . . . . . . .188

device_callback_detach . . . . . . . . . . . . . . . . .190

device_close . . . . . . . . . . . . . . . . . . . . . . . . . .191

device_ioctl . . . . . . . . . . . . . . . . . . . . . . . . . . .192

device_open . . . . . . . . . . . . . . . . . . . . . . . . . .193

device_open_timeout . . . . . . . . . . . . . . . . . . .194

device_read. . . . . . . . . . . . . . . . . . . . . . . . . . .195

device_start . . . . . . . . . . . . . . . . . . . . . . . . . . .196

device_stop . . . . . . . . . . . . . . . . . . . . . . . . . . .197

device_stop_timeout . . . . . . . . . . . . . . . . . . . .198

device_streaming_read . . . . . . . . . . . . . . . . . .199

device_streaming_write . . . . . . . . . . . . . . . . .200

device_type . . . . . . . . . . . . . . . . . . . . . . . . . . .201

device_write . . . . . . . . . . . . . . . . . . . . . . . . . .202

e2fs_vfs_init . . . . . . . . . . . . . . . . . . . . . . . . . .258

e2fs_vfs_init_p . . . . . . . . . . . . . . . . . . . . . . . .258

e2fs_vfs_shutdown . . . . . . . . . . . . . . . . . . . . .259

eminand_initialize . . . . . . . . . . . . . . . . . . . . . .481

eof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312

fat_vfs_init . . . . . . . . . . . . . . . . . . . . . . . . . . . .259

fat_vfs_init_p . . . . . . . . . . . . . . . . . . . . . . . . . .259

fat_vfs_shutdown . . . . . . . . . . . . . . . . . . . . . .259

fchmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312

fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312

flex_initialize . . . . . . . . . . . . . . . . . . . . . . . . . .482

flush. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

fsck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

fscntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314

fstat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 fstat64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

GPDMA_CHAIN_TRANSFER . . . . . . . . . . . . 217

GPDMA_INIT_0D_0D_TRANSFER . . . . . . . . 217

GPDMA_INIT_0D_1DI_TRANSFER . . . . . . . 218

GPDMA_INIT_1DI_0D_TRANSFER . . . . . . . 218

GPDMA_INIT_1DI_1DI_TRANSFER . . . . . . . 219

gpdma_initialize . . . . . . . . . . . . . . . . . . . . . . . 216

GPDMA_TRANSFER_CONTROL . . . . . . . . . 220

GPDMA_TRANSFER_COUNT . . . . . . . . . . . 222

GPDMA_TRANSFER_DAR . . . . . . . . . . . . . . 222

GPDMA_TRANSFER_SAR . . . . . . . . . . . . . . 223

h2heth_initialize . . . . . . . . . . . . . . . . . . . . . . . 417

lafs_vfs_init. . . . . . . . . . . . . . . . . . . . . . . . . . . 260 lafs_vfs_init_p. . . . . . . . . . . . . . . . . . . . . . . . . 260 lafs_vfs_shutdown . . . . . . . . . . . . . . . . . . . . . 260

laftl_initialize . . . . . . . . . . . . . . . . . . . . . . . . . . 483

lan91_initialize . . . . . . . . . . . . . . . . . . . . . . . . 414

lan9x1x_initialize . . . . . . . . . . . . . . . . . . . . . . 415

lvm_initialize . . . . . . . . . . . . . . . . . . . . . . . . . . 329

lvm_media_inserted . . . . . . . . . . . . . . . . . . . . 330

lvm_media_removed . . . . . . . . . . . . . . . . . . . 331

lvm_partition_create . . . . . . . . . . . . . . . . . . . . 332

lvm_partition_create_adv . . . . . . . . . . . . . . . . 333

lvm_partition_delete . . . . . . . . . . . . . . . . . . . . 334

lvm_partition_delete_all . . . . . . . . . . . . . . . . . 335

lvm_partition_info . . . . . . . . . . . . . . . . . . . . . . 336

lvm_partitions . . . . . . . . . . . . . . . . . . . . . . . . . 337

lvm_volume_create . . . . . . . . . . . . . . . . . . . . 338

lvm_volume_create_adv. . . . . . . . . . . . . . . . . 339

lvm_volume_delete. . . . . . . . . . . . . . . . . . . . . 340

lvm_volumes. . . . . . . . . . . . . . . . . . . . . . . . . . 341

mkdir. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

msfs_vfs_init. . . . . . . . . . . . . . . . . . . . . . . . . . 261 msfs_vfs_init_p. . . . . . . . . . . . . . . . . . . . . . . . 261 msfs_vfs_shutdown . . . . . . . . . . . . . . . . . . . . 261

open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 opendir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

osplus_align . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

osplus_allocate. . . . . . . . . . . . . . . . . . . . . . . . . 33

osplus_allocate_timeout . . . . . . . . . . . . . . . . . . 34

osplus_cache_alignment . . . . . . . . . . . . . . . . . 35

osplus_cache_line_size . . . . . . . . . . . . . . . . . . 36

osplus_cache_safe_allocate . . . . . . . . . . . . . . 37

osplus_cache_safe_allocate_timeout. . . . . . . . 38

osplus_cache_safe_deallocate . . . . . . . . . . . . 39

osplus_copy16 . . . . . . . . . . . . . . . . . . . . . . . . . 40

osplus_copy32 . . . . . . . . . . . . . . . . . . . . . . . . . 41

508/515 7702033 Rev 27

UM1150 List of functions

osplus_copy64 . . . . . . . . . . . . . . . . . . . . . . . . .42

osplus_deallocate . . . . . . . . . . . . . . . . . . . . . . .45

osplus_dma_complete . . . . . . . . . . . . . . . . . . .43

osplus_dma_prepare . . . . . . . . . . . . . . . . . . . .44

osplus_format_double_to_str . . . . . . . . . . . . . .46

osplus_handle . . . . . . . . . . . . . . . . . . . . . . . . . .48

osplus_handle_create . . . . . . . . . . . . . . . . . . . .49

osplus_handle_delete . . . . . . . . . . . . . . . . . . . .50

osplus_id_allocate. . . . . . . . . . . . . . . . . . . . . . .51

osplus_id_free . . . . . . . . . . . . . . . . . . . . . . . . . .52

osplus_id_manager_create . . . . . . . . . . . . . . . .53

osplus_id_manager_delete . . . . . . . . . . . . . . . .54

osplus_interrupt_clear . . . . . . . . . . . . . . . . . . . .55

osplus_interrupt_disable . . . . . . . . . . . . . . . . . .56

osplus_interrupt_enable . . . . . . . . . . . . . . . . . .57

osplus_interrupt_handle . . . . . . . . . . . . . . . . . .58

osplus_interrupt_handle_delete . . . . . . . . . . . .59

osplus_interrupt_install . . . . . . . . . . . . . . . . . . .60

osplus_interrupt_install_shared . . . . . . . . . . . .61

osplus_interrupt_raise . . . . . . . . . . . . . . . . . . . .62

osplus_interrupt_uninstall . . . . . . . . . . . . . . . . .63

osplus_interrupt_uninstall_shared . . . . . . . . . .64

osplus_list_add_back . . . . . . . . . . . . . . . . . . . .65

osplus_list_add_front . . . . . . . . . . . . . . . . . . . .66

osplus_list_contains_node . . . . . . . . . . . . . . . .67

osplus_list_delete . . . . . . . . . . . . . . . . . . . . . . .68

osplus_list_first . . . . . . . . . . . . . . . . . . . . . . . . .69

osplus_list_init . . . . . . . . . . . . . . . . . . . . . . . . . .70

osplus_list_is_empty . . . . . . . . . . . . . . . . . . . . .71

osplus_list_last . . . . . . . . . . . . . . . . . . . . . . . . .72

osplus_list_next. . . . . . . . . . . . . . . . . . . . . . . . .73

osplus_list_prev . . . . . . . . . . . . . . . . . . . . . . . .74

osplus_list_remove . . . . . . . . . . . . . . . . . . . . . .75

osplus_list_remove_back . . . . . . . . . . . . . . . . .76

osplus_list_remove_front . . . . . . . . . . . . . . . . .77

osplus_list_size . . . . . . . . . . . . . . . . . . . . . . . . .78

osplus_localtime . . . . . . . . . . . . . . . . . . . . . . . .79

osplus_lock_create . . . . . . . . . . . . . . . . . . . . . .80

osplus_mktime . . . . . . . . . . . . . . . . . . . . . . . . .81

osplus_ms_delay . . . . . . . . . . . . . . . . . . . . . . .82

osplus_name_allocate . . . . . . . . . . . . . . . . . . .83

osplus_name_free. . . . . . . . . . . . . . . . . . . . . . .84

osplus_name_manager_register. . . . . . . . . . . .85

osplus_name_manager_unregister. . . . . . . . . .86

osplus_rtc_time . . . . . . . . . . . . . . . . . . . . . . . . .88

osplus_rtc_time_set . . . . . . . . . . . . . . . . . . . . .87

osplus_rtc_timer_create . . . . . . . . . . . . . . . . . .89

osplus_rtc_timer_delete . . . . . . . . . . . . . . . . . .90

osplus_rtc_timer_start . . . . . . . . . . . . . . . . . . . .93

osplus_rtc_timer_stop . . . . . . . . . . . . . . . . . . . .94

osplus_rtc_timer_time . . . . . . . . . . . . . . . . . . . .92

osplus_rtc_timer_time_set . . . . . . . . . . . . . . . .91

osplus_rwlock_create . . . . . . . . . . . . . . . . . . . . 95

osplus_rwlock_delete . . . . . . . . . . . . . . . . . . . . 96

osplus_rwlock_downgrade . . . . . . . . . . . . . . . . 97

osplus_rwlock_enter. . . . . . . . . . . . . . . . . . . . . 98

osplus_rwlock_leave . . . . . . . . . . . . . . . . . . . . 99

osplus_rwlock_tryenter. . . . . . . . . . . . . . . . . . 100

osplus_rwlock_tryupgrade . . . . . . . . . . . . . . . 101

osplus_strdup . . . . . . . . . . . . . . . . . . . . . . . . . 102

osplus_strpre . . . . . . . . . . . . . . . . . . . . . . . . . 103

osplus_strsep . . . . . . . . . . . . . . . . . . . . . . . . . 104

osplus_timer_create . . . . . . . . . . . . . . . . . . . . 105

osplus_timer_delete . . . . . . . . . . . . . . . . . . . . 106

osplus_timer_period . . . . . . . . . . . . . . . . . . . . 107

osplus_timer_period_set . . . . . . . . . . . . . . . . 108

osplus_timer_start . . . . . . . . . . . . . . . . . . . . . 109

osplus_timer_stop . . . . . . . . . . . . . . . . . . . . . 110

osplus_uncached . . . . . . . . . . . . . . . . . . . . . . 111

osplus_uncached_register . . . . . . . . . . . . . . . 112

osplus_uncached_unregister . . . . . . . . . . . . . 113

osplus_version . . . . . . . . . . . . . . . . . . . . . . . . 114

osplus_version_set. . . . . . . . . . . . . . . . . . . . . 115

pci_initialize . . . . . . . . . . . . . . . . . . . . . . . . . . 236

PCI_TO_CPU . . . . . . . . . . . . . . . . . . . . . . . . . 237

phy_initialize . . . . . . . . . . . . . . . . . . . . . . . . . . 418

ramdisk_create . . . . . . . . . . . . . . . . . . . . . . . . 437

ramdisk_create_custom . . . . . . . . . . . . . . . . . 440

ramdisk_create_hdisk. . . . . . . . . . . . . . . . . . . 438

ramdisk_create_rdisk . . . . . . . . . . . . . . . . . . . 439

ramdisk_delete . . . . . . . . . . . . . . . . . . . . . . . . 441

ramdisk_image_load . . . . . . . . . . . . . . . . . . . 442

ramdisk_image_save . . . . . . . . . . . . . . . . . . . 443

read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 readdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

registry_key . . . . . . . . . . . . . . . . . . . . . . . . . . 120

registry_key_data . . . . . . . . . . . . . . . . . . . . . . 121

registry_key_data_set . . . . . . . . . . . . . . . . . . 122

registry_key_data_timeout . . . . . . . . . . . . . . . 123

registry_key_delete . . . . . . . . . . . . . . . . . . . . 124

registry_key_next . . . . . . . . . . . . . . . . . . . . . . 125

registry_key_set . . . . . . . . . . . . . . . . . . . . . . . 126

registry_key_timeout . . . . . . . . . . . . . . . . . . . 127

registry_load_data . . . . . . . . . . . . . . . . . . . . . 128

registry_node . . . . . . . . . . . . . . . . . . . . . . . . . 129

registry_node_create . . . . . . . . . . . . . . . . . . . 130

registry_node_delete . . . . . . . . . . . . . . . . . . . 131

registry_node_next . . . . . . . . . . . . . . . . . . . . . 132

registry_node_timeout . . . . . . . . . . . . . . . . . . 133

rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 resize64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 rewinddir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

rmdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

7702033 Rev 27 509/515

List of functions UM1150

sata_initialize. . . . . . . . . . . . . . . . . . . . . . . . . .435

sdmmc_initialize . . . . . . . . . . . . . . . . . . . . . . .436

seek. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319

seek64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320

seekdir. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320

serial_initialize . . . . . . . . . . . . . . . . . . . . . . . . .351

stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321

stat64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321

stgmac_initialize . . . . . . . . . . . . . . . . . . . . . . .416

stmac_initialize . . . . . . . . . . . . . . . . . . . . . . . .416

stnftl_initialize . . . . . . . . . . . . . . . . . . . . . . . . .484

sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322

tell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322

tell64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322

telldir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323

time_ticks_per_sec . . . . . . . . . . . . . . . . . . . . .116

umount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323

unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323

vfs_chmod . . . . . . . . . . . . . . . . . . . . . . . . . . . .262

vfs_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262

vfs_closedir . . . . . . . . . . . . . . . . . . . . . . . . . . .263

vfs_creat . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263

vfs_dcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264

vfs_defrag . . . . . . . . . . . . . . . . . . . . . . . . . . . .265

vfs_fchmod . . . . . . . . . . . . . . . . . . . . . . . . . . .266

vfs_fclose . . . . . . . . . . . . . . . . . . . . . . . . . . . .266

vfs_fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267

vfs_feof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268

vfs_fflush . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268

vfs_fgetc . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268

vfs_fgetpos . . . . . . . . . . . . . . . . . . . . . . . . . . .269

vfs_fgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269

vfs_fopen. . . . . . . . . . . . . . . . . . . . . . . . . . . . .270

vfs_format . . . . . . . . . . . . . . . . . . . . . . . . . . . .271

vfs_fprintf. . . . . . . . . . . . . . . . . . . . . . . . . . . . .273

vfs_fputc . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273

vfs_fputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274

vfs_fread . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274

vfs_fsck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275

vfs_fscntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276

vfs_fseek . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282

vfs_fseek64 . . . . . . . . . . . . . . . . . . . . . . . . . . .283

vfs_fsetpos . . . . . . . . . . . . . . . . . . . . . . . . . . .284

vfs_fstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284

vfs_fstat64 . . . . . . . . . . . . . . . . . . . . . . . . . . . .285

vfs_ftell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285

vfs_ftell64 . . . . . . . . . . . . . . . . . . . . . . . . . . . .286

vfs_fwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287

vfs_lseek . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287

vfs_mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288

vfs_mount . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

vfs_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290

vfs_opendir . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 vfs_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

vfs_readdir . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

vfs_register . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 vfs_rename. . . . . . . . . . . . . . . . . . . . . . . . . . . 293

vfs_resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 vfs_resize64 . . . . . . . . . . . . . . . . . . . . . . . . . . 294

vfs_rewind . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 vfs_rewinddir . . . . . . . . . . . . . . . . . . . . . . . . . 295

vfs_rmdir. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 vfs_seekdir . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

vfs_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

vfs_stat64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

vfs_sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 vfs_sync_all . . . . . . . . . . . . . . . . . . . . . . . . . . 300

vfs_telldir . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 vfs_umount . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

vfs_umount_all . . . . . . . . . . . . . . . . . . . . . . . . 302 vfs_unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

vfs_unregister . . . . . . . . . . . . . . . . . . . . . . . . . 303 vfs_vfprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

vfs_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

510/515 7702033 Rev 27

UM1150

Index

Index

A

addresses align to power of 2

. . . . . . . . . . . . . . . . . . . . .32

alarm clock

. . . . . . . . . . . . . . . . . . . . . . . . . . . .24

B

Backus-Naur Form

. . . . . . . . . . . . . . . . . . . . . .11

block oriented I/O interfaces

. . . . . . . . . . . . .203

read

. . . . . . . . . . . . . . . . . . . . . . . . . . .176

,

186

streaming read

. . . . . . . . . . . . . . . . . .176

,

199

streaming write

. . . . . . . . . . . . . . . . . .176

,

200

write

. . . . . . . . . . . . . . . . . . . . . . . . . . .176

,

187

BNF. See Backus-naur Form.

C

cache line alignment

. . . . . . . . . . . . . . . . . . . .35

cache line size

. . . . . . . . . . . . . . . . . . . . . . . . .36

callback timer controlled

. . . . . . . . . . . . . . . . . . . . . . .23

character oriented I/O interfaces

. . . . . . . . . .203

read

. . . . . . . . . . . . . . . . . . . . . . . . . . .176

,

195

write

. . . . . . . . . . . . . . . . . . . . . . . . . . .176

,

202

common.h

. . . . . . . . . . . . . . . . . . 140

,

381

,

393

control commands

. . . . . . . . . . . . . . . . . . . . .192

CPU hardware address convert from PCI hardware address

. . . . . .237

convert to PCI hardware address

. . . . . . . .237

D

data cache purge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

-

31

Defragment a volume

. . . . . . . . . . . . . . . . . . .265

dev.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140

device block oriented read

. . . . . . . . . . . . . . .176

,

186

block oriented write

. . . . . . . . . . . . . . .176

,

187

character oriented read

. . . . . . . . . . . .176

,

195

character oriented write

. . . . . . . . . . . .176

,

202

close instance

. . . . . . . . . . . . . . . . . . . . . . .191

create a partition

. . . . . . . . . . . . . . . . . 332

-

333

create driver class

. . . . . . . . . . . . . . . . . . . .174

create instance

. . . . . . . . . . . . . . . . . . . . . .179

delete all volumes

. . . . . . . . . . . . . . . . . . . .335

delete attribute

. . . . . . . . . . . . . . . . . . . . . .183

delete driver class

. . . . . . . . . . . . . . . . . . . .178

delete instance

. . . . . . . . . . . . . . . . . . . . . .180

delete partition

. . . . . . . . . . . . . . . . . . . . . . 334

issue control command

. . . . . . . . . . . . . . . 192

list all partitions

. . . . . . . . . . . . . . . . . . . . . . 337

notification callback

. . . . . . . . . . . . . . 188

,

190

open instance

. . . . . . . . . . . . . . . . . . . 193

-

194

retrieve attribute

. . . . . . . . . . . . . . . . . . . . . 181

retrieve data attribute

. . . . . . . . . . . . . . . . . 182

set attribute

. . . . . . . . . . . . . . . . . . . . . . . . . 184

set data attribute

. . . . . . . . . . . . . . . . . . . . . 185

start I/O

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

stop I/O

. . . . . . . . . . . . . . . . . . . . . . . . 197

-

198

streaming block oriented read

. . . . . . 176

,

199

streaming block oriented write

. . . . . . 176

,

200

types

. . . . . . . . . . . . . . . . . . . . . . . . . . 135

,

201

write characters

. . . . . . . . . . . . . . . . . . . . . 202

device instance close

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

create

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

delete

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

open

. . . . . . . . . . . . . . . . . . . . . . . . . . 193

-

194

device model

. . . . . . . . . . . . . . . . . . . . . 134

-

209

device.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Digital Video Recorder

. . . . . . . . . . . . . 255

-

256

directory close

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

create

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

current location

. . . . . . . . . . . . . . . . . . . . . . 301

get information

. . . . . . . . . . .284

-

285

,

297

-

298

new position

. . . . . . . . . . . . . . . . . . . . . . . . 296

open for reading

. . . . . . . . . . . . . . . . . . . . . 291

read

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

remove

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

set position to first entry

. . . . . . . . . . . . . . . 295

E

E2FS

. . . . . . . . . . . . . . . . . . . 238

,

245

,

485

,

491

initialize

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

shutdown

. . . . . . . . . . . . . . . . . . . . . . . . . . 259

e2fs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

EMI NAND driver

. . . . . . . . . . . . . . . . . . . . . . 457

endian conversion byte swapping

. . . . . . . . . . . . . . . . . . . . 40

-

42

ethernet drivers

. . . . . . . . . . . 352

-

417

,

419

,

447

ethernet.h

. . . . . . . . . . . . . . . . . . . . . . . 381

,

393

Ext2

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

,

245

7702033 Rev 27 511/515

Index UM1150

F

FAT

. . . . . . . . . . . . . . . . . . . . . . . . . . . .238

,

252

initialize

. . . . . . . . . . . . . . . . . . . . . . . . . . . .259

shutdown

. . . . . . . . . . . . . . . . . . . . . . . 259

-

261

fat.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254

FAT12, FAT16, FAT32

see FAT

file position

. . . . . . . . . . . . . . . 269

,

282

-

287

,

295

file system

. . . . . . . . . . . . . . . . . . . . . . . . . . .238

anatomy

. . . . . . . . . . . . . . . . . . . . . . . . . . .305

files change access mode

. . . . . . . . . . . . .262

,

266

change the size

. . . . . . . . . . . . . . . . . . . . . .294

check EOF flag

. . . . . . . . . . . . . . . . . . . . . .268

close

. . . . . . . . . . . . . . . . . . . . . . . . . .262

,

266

create

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .263

format new file system

. . . . . . . . . . . . . . . .271

formatted string

. . . . . . . . . . . . . . . . . .273

,

303

get character

. . . . . . . . . . . . . . . . . . . . . . . .268

get file information

. . . . . . . . . . . . . . . . 284

-

285

get position

. . . . . . . . . . . . . . . . . 269

,

285

-

286

get string

. . . . . . . . . . . . . . . . . . . . . . . . . . .269

information

. . . . . . . . . . . . . . . . . . . . . 297

-

298

issue control commands

. . . . . . . . . . .264

,

267

issue control commands to a file system

. .276

move position

. . . . . . . . . . . 282

-

283

,

287

,

295

open

. . . . . . . . . . . . . . . . . . . . . . . . . .270

,

290

print string

. . . . . . . . . . . . . . . . . . . . . .273

,

303

read data

. . . . . . . . . . . . . . . . . . . . . . .274

,

291

rename

. . . . . . . . . . . . . . . . . . . . . . . . . . . .293

set position

. . . . . . . . . . . . . . . . . . . . . . . . .284

unlink

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302

write

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304

write character

. . . . . . . . . . . . . . . . . . . . . . .273

write data

. . . . . . . . . . . . . . . . . . . . . . .268

,

287

write string

. . . . . . . . . . . . . . . . . . . . . . . . . .274

Flash drivers configuration

. . . . . . . . . . . . . . . . . . . . . . . .448

geometry

. . . . . . . . . . . . . . . . . . . . . . . . . . .447

performance

. . . . . . . . . . . . . . . . . . . . . . . .448

flex.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .464

G

GPDMA chain transfers

. . . . . . . . . . . . . . . . . . . . . . .217

claim transfer

. . . . . . . . . . . . . . . . . . . . . . . .214

free transfers

. . . . . . . . . . . . . . . . . . . . . . . .214

initialize driver

. . . . . . . . . . . . . . . . . . . . . . .216

initialize number of bytes to transfer

. . . . . .222

initialize transfer control options

. . . . . . . . .220

initialize transfer destination options

. . . . . .222

initialize transfer source options

. . . . . . . . . 223

initialize transfers

. . . . . . . . . . . . . . . . 217

-

219

queue transfers

. . . . . . . . . . . . . . . . . . . . . 214

wait on transfer

. . . . . . . . . . . . . . . . . . . . . . 215

GPDMA driver

. . . . . . . . . . . . . . . . . . . . 210

-

223

gpdma.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

H

h2heth.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

handle management API

. . . . . . . . . . . . . . . . . 25

header file ata.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

dev.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

device.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . 139

e2fs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

eminand.h

. . . . . . . . . . . . . . . . . . . . . . . . . . 463

fat.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

flex.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

gpdma.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . 212

h2heth.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . 379

ioctls/common.h

. . . . . . . . . . . . . 140

,

381

,

393

ioctls/ethernet.h

. . . . . . . . . . . . . . . . . 381

,

393

ioctls/joystick.h

. . . . . . . . . . . . . . . . . . . . . . 142

ioctls/keyboard.h

. . . . . . . . . . . . . . . . . . . . 144

ioctls/mouse.h

. . . . . . . . . . . . . . . . . . . . . . 144

ioctls/nand.h

. . . . . . . . . . . . . . . . . . . . . . . . 466

ioctls/phy.h

. . . . . . . . . . . . . . . . . . . . . . . . . 393

lafs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

laftl.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

lan91.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

lan9118.h

. . . . . . . . . . . . . . . . . . . . . . . . . . 377

lvm.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

mmc.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

msfs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

osplus.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

pci.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

phy.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

ramdisk.h

. . . . . . . . . . . . . . . . . . . . . . . . . . 429

registry.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . 118

sata.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

serial.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

stnftl.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

stxmac.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . 378

vfs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

vfs_fs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

hot plugging

. . . . . . . . . . . . . . . . . . . . . . . . . . 137

I

I/O performing

. . . . . . . . . . . . . . . . . . . . . . . . . 136

start device

. . . . . . . . . . . . . . . . . . . . . . . . . 196

512/515 7702033 Rev 27

UM1150 Index

stop device

. . . . . . . . . . . . . . . . . . . . . 197

-

198

ID manager allocate ID

. . . . . . . . . . . . . . . . . . . . . . . . . . .51

create instance

. . . . . . . . . . . . . . . . . . . . . . .53

delete instance

. . . . . . . . . . . . . . . . . . . . . . .54

free ID

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

initialize host-to-host ethernet driver

. . . . . . .417

initialize LAN91 driver

. . . . . . . . . . . . . .414

,

418

initialize LAN9118 driver

415

,

434

-

436

,

481

-

484

initialize STMAC110 driver

. . . . . . . . . . . . . . .416

interrupt handler install private

. . . . . . . . . . . . . . . . . . . . . . . . .60

install shared

. . . . . . . . . . . . . . . . . . . . . . . . .61

uninstall

. . . . . . . . . . . . . . . . . . . . . . . . . . 63

-

64

interrupts clear

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55

delete handle

. . . . . . . . . . . . . . . . . . . . . . . . .59

disable

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

enable

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57

install private interrupt handler

. . . . . . . . . . .60

install shared interrupt handler

. . . . . . . . . . .61

obtain handle

. . . . . . . . . . . . . . . . . . . . . . . . .58

private interrupt handler

. . . . . . . . . . . . . . . .60

raise

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62

shared interrupt

. . . . . . . . . . . . . . . . . . . . . . .64

shared interrupt handler

. . . . . . . . . . . . . . . .61

uninstall interrupt handler

. . . . . . . . . . . . 63

-

64

J

joystick.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . .142

K

keyboard.h

. . . . . . . . . . . . . . . . . . . . . . . . . . .144

L

lafs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256

laftl.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .465

lan91.h

. . . . . . . . . . . . . . . . . . 376

,

427

-

428

,

463

lan9118.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . .377

linear access file system

. . . . 255

,

260

-

261

,

447

linear access Flash translation layer

. . 255

-

256

,

447

,

. . . . . . . . . . . . . . . . . . . . . . . 455

,

458

,

461

lists add node

. . . . . . . . . . . . . . . . . . . . . . . . . 65

-

66

check for node

. . . . . . . . . . . . . . . . . . . . . . . .67

initialize empty

. . . . . . . . . . . . . . . . . . . . . . . .70

remove node

. . . . . . . . . . . . . . . . . . . . . . . . .68

lock create

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

delete

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

downgrade ownership

. . . . . . . . . . . . . . . . . 97

enter a locked section

. . . . . . . . . . . . . 98

,

100

exit a locked section

. . . . . . . . . . . . . . . . . . . 99

upgrade a lock acquisition

. . . . . . . . . . . . . 101

logical volume manager

see LVM

low level NAND Flash driver

. . . . . 457

,

459

,

469

EMI

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

flex

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

LVM

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

-

341

compatibility

. . . . . . . . . . . . . . . . . . . . . . . . 325

create a new partition

. . . . . . . . . . . . . 332

-

333

create logical volume

. . . . . . . . . . . . . 338

-

339

delete a partition

. . . . . . . . . . . . . . . . . . . . . 334

delete all logical volumes

. . . . . . . . . . . . . . 335

delete logical volume

. . . . . . . . . . . . . . . . . 340

get list of all partitions

. . . . . . . . . . . . . . . . . 337

get volume names

. . . . . . . . . . . . . . . . . . . 341

initialize library

. . . . . . . . . . . . . . . . . . . . . . 329

notify of new media

. . . . . . . . . . . . . . . . . . 330

notify of removed media

. . . . . . . . . . . . . . . 331

return partition details

. . . . . . . . . . . . . . . . . 336

lvm.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

M

master abort interrupt

. . . . . . . . . . . . . . . . . . 232

memory allocate a block as I/O buffer

. . . . . . . . . 37

-

38

allocate memory block

. . . . . . . . . . . . . . 33

-

34

copy 16-bit quantity

. . . . . . . . . . . . . . . . . . . 40

copy 32-bit quantity

. . . . . . . . . . . . . . . . . . . 41

copy 64-bit quantity

. . . . . . . . . . . . . . . . . . . 42

free block of memory

. . . . . . . . . . . . . . . 39

,

45

uncached memory region

. . . . . . . . . . 111

-

113

memory base address register

. . . . . . . . . . . 233

mouse.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

msfs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

N

name manager free a name

. . . . . . . . . . . . . . . . . . . . . . . . . 84

generate a new name

. . . . . . . . . . . . . . . . . . 83

register name prefix

. . . . . . . . . . . . . . . . . . . 85

unregister name prefix

. . . . . . . . . . . . . . . . . 86

nand.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

O

osplus.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

7702033 Rev 27 513/515

Index UM1150

P

partition allocate memory block

. . . . . . . . . . . . . . 33

-

34

PCI convert CPU hardware address to PCI hardware address

. . . . . . . . . . . . . . . . .237

convert PCI hardware address to CPU hardware address

. . . . . . . . . . . . . . . . .237

device information

. . . . . . . . . . . . . . . . . . . .234

disable device

. . . . . . . . . . . . . . . . . . . . . . .232

disable device interrupt

. . . . . . . . . . . . . . . .235

enable device

. . . . . . . . . . . . . . . . . . . . . . .232

enable device interrupt

. . . . . . . . . . . . . . . .235

initialize driver

. . . . . . . . . . . . . . . . . . . . . . .236

master abort interrupt

. . . . . . . . . . . . . . . . .232

MBAR

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .233

memory base address register

. . . . . . . . . .233

read configuration space

. . . . . . . . . . .229

,

231

write configuration space

. . . . . . . . . . . . . .229

PCI driver

. . . . . . . . . . . . . . . . . . . . . . . . 224

-

237

pci.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228

periodic timer

. . . . . . . . . . . . . . . . . . . . . . . . . .23

phy.h

. . . . . . . . . . . . . . . . . . . . . . . . . . .379

,

393

R

read/write lock

. . . . . . . . . . . . . . . 95

-

96

,

98

-

101

real time clock

. . . . . . . . . . . . . . . . . . . . . . . . .24

registry check for node

. . . . . . . . . . . . . . . . . . .129

,

133

child nodes

. . . . . . . . . . . . . . . . . . . . .117

,

132

create node

. . . . . . . . . . . . . . . . . . . . . . . . .130

delete node

. . . . . . . . . . . . . . . . . . . . . . . . .131

keys

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117

load list of nodes

. . . . . . . . . . . . . . . . . . . . .128

name/value pairs

. . . . . . . . . . . . . . . . . . . . .117

nodes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .117

parent node

. . . . . . . . . . . . . . . . . . . . . . . . .132

registry library

. . . . . . . . . . . . . . . . . . . . . 117

-

133

registry.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . .118

S

SD/MMC card

. . . . . . . . . . . . . . . . . . . . .419

,

425

serial driver

. . . . . . . . . . . . . . . . . . . . . . . 342

-

351

serial interface baud rate

. . . . . . . . . . . . . . . . . . . . . . . 347

-

350

configure

. . . . . . . . . . . . . . . . . . . . . . . . . . .349

current configuration

. . . . . . . . . . . . . . . . . .347

data bit size

. . . . . . . . . . . . . . . . . . . . . . . . .349

initialize driver

. . . . . . . . . . . . . . . . . . . . . . .351

serial.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343

single shot timer

. . . . . . . . . . . . . . . . . . . . . . . 23

ST NAND Flash translation layer

447

,

456

,

458

,

462

stnftl.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

stxmac.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

SuperH SH-Series documentation suite notation

. . . . . . . . . . . . . . . . . . . . . . . . . . . 11

T

timer interface

. . . . . . . . . . . . . . . . . . . . . . . . . 23

timers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

-

24

V

VFS

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

-

324

services

. . . . . . . . . . . . . . . . . . . . . . . . . . . 306

VFS types

_vfs_dir_t

. . . . . . . . . . . . . . . . . . . . . . . . . . 309

_vfs_file_t

. . . . . . . . . . . . . . . . . . . . . . . . . . 308

_vfs_filesystem_t

. . . . . . . . . . . . . . . . . . . . 309

_vfs_mount_t

. . . . . . . . . . . . . . . . . . . . . . . 308

vfs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

vfs_fs.h

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

virtual file system

see VFS

volume mount

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

unmount

. . . . . . . . . . . . . . . . . . . . . . . 301

-

302

514/515 7702033 Rev 27

UM1150

Please Read Carefully:

Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any time, without notice.

All ST products are sold pursuant to ST’s terms and conditions of sale.

Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no liability whatsoever relating to the choice, selection or use of the ST products and services described herein.

No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property contained therein.

UNLESS OTHERWISE SET FORTH IN ST’S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED

WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS

OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.

UNLESS EXPRESSLY APPROVED IN WRITING BY TWO AUTHORIZED ST REPRESENTATIVES, ST PRODUCTS ARE NOT

RECOMMENDED, AUTHORIZED OR WARRANTED FOR USE IN MILITARY, AIR CRAFT, SPACE, LIFE SAVING, OR LIFE SUSTAINING

APPLICATIONS, NOR IN PRODUCTS OR SYSTEMS WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY,

DEATH, OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE. ST PRODUCTS WHICH ARE NOT SPECIFIED AS "AUTOMOTIVE

GRADE" MAY ONLY BE USED IN AUTOMOTIVE APPLICATIONS AT USER’S OWN RISK.

Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any liability of ST.

ST and the ST logo are trademarks or registered trademarks of ST in various countries.

Information in this document supersedes and replaces all information previously supplied.

The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.

© 2012 STMicroelectronics - All rights reserved

STMicroelectronics group of companies

Australia - Belgium - Brazil - Canada - China - Czech Republic - Finland - France - Germany - Hong Kong - India - Israel - Italy - Japan -

Malaysia - Malta - Morocco - Philippines - Singapore - Spain - Sweden - Switzerland - United Kingdom - United States of America

www.st.com

7702033 Rev 27 515/515