IOS and Driver Model

1
IOS and Driver Model

• Palm OS 6 PDK Training
• December 1-5, 2003

2
Overview

• Overview of IOS / driver model
• Installing drivers
• Introduction to STREAMS
• Introduction to the device manager

3
What does IOS provide?

• An execution environment for communication stacks
  and device drivers
• A common interface for accessing services within
  the I/O process
• A protected process for restricting access to
  hardware

4
Overview of IOS and the Driver Model
5
IOS Framework

• File descriptor management
• IPC
• Driver management
• Device Name Table
• Installation / Removal
• Secure Driver Installation

6
IOS Framework (cont'd)

• Standard I/O API
• Open, Close, Read, Write, Ioctl, etc
• Installation API
• InstallDriver, RemoveDriver
• Attributes API
• This API can be used by things outside of IOS to
  locate devices based on attributes associated
  with each device name
• Specialized libraries, such as sockets, are built
  on top of the standard I/O API

7
STREAMS

• Communications stack framework
• Provides common services
• Flow Control
• Message Passing
• Interconnecting Layers
• Resource Management
• Portable
• Code can be ported from other STREAMS
  implementations

8
Device Manager

• C driver framework for low level drivers
• Replaces the monolithic HAL of Palm OS 5
• Dependency management
• Device Manager keeps track of dependency between
  drivers
• Attribute database
• Used to locate device nodes

9
IOS Context Driver

• Execution context for drivers
• Thread Pools
• Caveat Expansion Mgr and Communications device
  drivers operate in other contexts
• Bridge between IOS and device drivers

10
VFS/Expansion Manager

• VFS/Expansion manager
• Manages Volumes and cards
• File system libraries
• Used by VFS to access file system on expansion
  media
• Block devices
• Low level drivers for expansion slots
• Device manager nodes
• Operate in expansion manager thread context

11
Installing Drivers

• IOSInstallDriver
• Can be called from anywhere outside of the I/O
  process after IOS has initialized
• Installing with the Boot List
• Handle the sysLaunchCmdBoot launch code
• Call IOSInstallDriver
• Using the Automatic Driver Loader
• Only requirement is that the database type be
  drvr
• Security
• Drivers must be signed by a certificate in the
  IOS policy, if the policy exist

12
Installation Inside of IOS

• Handle the sysIOSDriverInstall launch code
• STREAMS drivers and modules
• Fill out the installation structure
• Specify the drivers name and streamtab
• Device manager drivers
• The driver just needs to start the factory for
  its node

13
STREAMS
14
Terminology

• STREAMS
• STREAMS in all caps refers to the actual
  framework
• Stream
• A bi-directional data path between layers in a
  protocol stack
• Driver
• Forms the base of a stream
• Multiplexor
• Special case of a driver
• Can handle multiple streams above and/or below
  the driver

15
Terminology (cont'd)

• Module
• Can be pushed on to or popped off of a stream
• Stream head
• Forms the top of a stream
• Converts between IOS requests and STREAMS
  messages
• Messages
• How data and control information is moved up and
  down a stream

16
Messages

• Message Passing Architecture
• All information in streams, both data and
  commands, is moved around in messages
• Message Types
• M_DATA, M_PROTO, M_FLUSH, M_IOCTL
• Priority Bands
• Can be used to expedite messages

17
Data Flow

• Queues
• Each module and driver has a read queue and a
  write queue
• Read/WritePut() Routines
• Used to receive messages passed from other
  modules or drivers.
• Can be used for immediate processing of messages

18
Data Flow (cont'd)

• Read/WriteService() routines
• Used for deferred processing of messages
• Invoked by STREAMS scheduler
• Flow Control
• Managed by STREAMS framework
• Used to regulate the flow of data between layers

19
STREAMS Example
20
Constructing a Stream

• Opening the Driver
• fd IOSOpen("IP", 0 , err)
• New Stream created
• A new stream head is allocated
• Read and Write Queues are created for the stream
  head and driver
• The queues are then linked together

21
Pushing Modules

• fd IOSOpen("IP", 0, err)
• IOSIoctl(fd, I_PUSH, "TCP", err)
• The TCP module has now been pushed onto the
  stream
• Any messages between the stream head and the IP
  driver will pass through the TCP module

22
Linking Streams

• fd1 IOSOpen("IP", 0, err)
• fd2 IOSOpen("PPP", 0, err)
• IOSIoctl(fd1, I_LINK, fd2, err)
• Stream 2 is now linked under the IP driver
• The stream head for stream 2 exists but is
  dormant.

23
Interface Standards

• STREAMS provides a framework but it does not
  define interfaces between layers
• Data Link Provider Interface (DLPI)
• Service Primitives for the layer below IP
• Used by Ethernet and PPP in PalmOS 6
• Transport Provider Interface (TPI)
• Service Primitives for use with transport layer
  modules
• Used by IRDA and Bluetooth in PalmOS 6

24
Further Reading

• Recommend reading
• Unix System V Network Programming by Stephen A.
  Rago
• Unix System V Release 4 Programmers Guide
  STREAMS

25
Device Manager Introduction
26
Terminology

• Nodes
• Device drivers are C objects and exist as nodes
  in a graph
• Interfaces
• An interface is a C class consisting of virtual
  methods
• An interface is implemented by a node to export a
  particular functionality
• Attributes
• Each node publishes attributes about itself that
  are used by other nodes to locate it
• Live Queries
• A live query is a request to the device manager
  to locate a node with the specified
  characteristics. The query remains live until it
  is cancelled

27
Factories

• A C object used to instantiate a node
• A factory is generally started when its driver is
  installed into IOS.
• Starts a query for dependencies
• The node's dependencies are given to the factory
• The factory will not instantiate a node until all
  the dependencies have been located
• No need to worry about installation order
  dependencies
• Factory Templates
• Factory templates are provided by PalmSource, Inc.

28
System Driver

• Defines the basic layout of the system hardware
• Instantiates physical layer nodes for board
  components
• Specifies physical addresses for each component
• Interrupt and Clock Requirements
• Instantiates logical layer devices that act as
  common driver services
• Interrupt Controllers
• Timers

29
Finding Nodes

• Attribute Name / value pairs
• Example
• P_DEV_INTERFACE_ATTR
• Attribute name used to specify an interface.
• P_DEV_PEN_INTERFACE.
• Attribute value for the pen interface.
• To find the pen interface you specify this string
  as the query
• P_DEV_INTERFACE_ATTR P_DEV_PEN_INTERFACE
• Attribute constants are defined in
• /headers/PDK/device/

30
Interfaces

• Provider Interfaces
• Implemented by lower level nodes for use by
  higher level nodes
• Used to send data or commands down stream
• Client Interfaces
• Implemented by a higher level nodes for use by
  lower level nodes
• Used to send data or commands up stream

31
Adding Nodes

• In the Constructor
• Called by the Factory
• Call AcquireNode() on your dependencies
• Call AddAttr() to specify your nodes attributes
• In Start()
• Called by the Factory
• Check to make sure the there were no errors
  generated during construction
• Call StartNode() to mark your node as ready

32
Opening an Interface

• OpenInterface()
• Device manager method
• A request to the device manager to open a
  particular interface on the specified node
• GetInterface()
• Device manager method
• Used when a node has multiple interfaces

33
Being Opened

• InitNode()
• Implemented by your node
• Called once just before the first call to
  OpenRequested()
• Non session based initialization
• OpenRequested()
• Each time an OpenInterface() is requested of your
  node
• Protocol Verification
• Session based initialization

34
Removal / Power Management

• The device manager monitors your node's
  dependencies
• By default the Device Manager will deallocate
  your node if your dependencies disappear
• Can override NodeStopping for greater flexibility
• Suspend()
• Implemented by your node
• Called by the Device Manager when the system is
  going to sleep
• Resume()
• Implemented by your node
• Called by the Device Manager when the system is
  waking up

35
A Driver Example
36
Physical Device Nodes

• Represents the physical hardware as a device
  node.
• Used by logical layer to access the hardware
• Reading and writing registers
• Access to interrupt controller
• Abstracts access to the hardware bus.
• Most often just the memory bus
• Can abstract more sophisticated buses, such as
  USB

37
Logical Device Nodes

• Corresponds to what would normally be considered
  a driver
• Manages the actual hardware device
• Manipulates registers
• Services Interrupts
• Provides a hardware independent interface to the
  adapter layer

38
Adapter Nodes

• Platform Independent Code
• Code common to the device category is in the
  adapter
• Interface conversion
• Converts between IOS STDIO interface to C
  device specific interface
• Example from the Serial Adapter
• The adapter receives a TIOCSETA ioctl
• TIOCSETA is converted to calls to SetBaud(),
  SetStopBits, etc. on the logical device

39
QA
For further information, see the following
documents PDK STREAMS Driver Installation and
Design Guide PDK Device Driver Design Guide
PDK System Architecture Guide I/O Services
chapter SDK Exploring Palm OS Low-Level
Communications, Part V, IOS STDIO SDK Exploring
Palm OS Memory, Databases, and Files (VFS
Manager) SDK Exploring Palm OS System
Management (Expansion Manager) This is not in
the beta PDK/SPK but will be available with the
public release of Palm OS 6
More questions on this topic? Email
PDKTraining2003_at_palmsource.com