ANALOG DEVICES W5.0 Service Manual

a

W5.0

Device Drivers and System Services

Manual for Blackfin

®

Processors

Revision 3.2, August 2008

Part Number

82-000430-01

Analog Devices, Inc.
One Technology Way
Norwood, Mass. 02062-9106

Copyright Information

© 2008 Analog Devices, Inc., ALL RIGHTS RESERVED. This document
may not be reproduced in any form without prior, express written consent
from Analog Devices, Inc.

Printed in the USA.

Disclaimer

Analog Devices, Inc. reserves the right to change this product without
prior notice. Information furnished by Analog Devices is believed to be
accurate and reliable. However, no responsibility is assumed by Analog
Devices for its use; nor for any infringement of patents or other rights of
third parties which may result from its use. No license is granted by impli­cation or otherwise under the patent rights of Analog Devices, Inc.

Trademark and Service Mark Notice

The Analog Devices logo and icon bar, Blackfin, the Blackfin logo,
EZ-KIT Lite, SHARC, TigerSHARC, and VisualDSP++ are registered
trademarks of Analog Devices, Inc.

All other brand and product names are trademarks or service marks of
their respective owners.

CONTENTS

PREFACE

Purpose of This Manual ............................................................... xxxi

Intended Audience ....................................................................... xxxi

Manual Contents Description ..................................................... xxxii

Technical or Customer Support .................................................. xxxiii

Supported Processors .................................................................. xxxiv

Product Information .................................................................. xxxiv

MyAnalog.com ..................................................................... xxxiv

Processor Product Information ............................................... xxxv

Related Documents .............................................................. xxxvi

Online Technical Documentation ........................................ xxxvii

Accessing Documentation From the Web ......................... xxxvii

Viewing Help Files .......................................................... xxxvii

Notation Conventions .............................................................. xxxviii

INTRODUCTION

System Services Overview .............................................................. 1-2

General ................................................................................... 1-3

Application Interface ............................................................... 1-7

VisualDSP++ 5.0 Device Drivers and System iii
Services Manual for Blackfin Processors

Contents

Dependencies .......................................................................... 1-8

Initialization ......................................................................... 1-10

Termination .......................................................................... 1-10

System Services Directory and File Structure .......................... 1-11

Accessing the System Services API ..................................... 1-11

Linking in the System Services Library .............................. 1-13

Rebuilding the System Services Library ............................. 1-15

Examples .......................................................................... 1-16

Dual-Core Considerations ................................................ 1-16

RTOS Considerations ................................................................. 1-17

Interoperability of System Services With VDK ....................... 1-17

Deployment of Services Within a Multi-Threaded

Application ........................................................................ 1-18

Device Driver Overview .............................................................. 1-19

Application Interface ............................................................. 1-20

Device Driver Architecture .................................................... 1-21

Interaction With System Services ...................................... 1-23

Initialization ......................................................................... 1-23

Termination .......................................................................... 1-24

Device Driver Directory and File Structure ............................ 1-24

Accessing the Device Driver API ....................................... 1-25

Device Driver File Locations ............................................. 1-27

Linking in the Device Driver Library ................................ 1-28

Rebuilding the Device Driver Library ................................ 1-29

Examples on Distribution ................................................. 1-30

iv VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

INTERRUPT MANAGER

Introduction ................................................................................. 2-2

Interrupt Manager Initialization .................................................... 2-4

Interrupt Manager Termination ..................................................... 2-5

Core Event Controller Functions ................................................... 2-6

adi_int_CECHook() Function ................................................. 2-6

adi_int_CECUnhook() Function ............................................. 2-8

Interrupt Handlers .................................................................. 2-8

System Interrupt Controller Functions .......................................... 2-9

adi_int_SICDisable ............................................................... 2-10

adi_int_SICEnable ................................................................ 2-10

adi_int_SICGetIVG .............................................................. 2-10

adi_int_SICInterruptAsserted ................................................ 2-10

adi_int_SICSetIVG ............................................................... 2-11

adi_int_SICWakeup .............................................................. 2-11

Protecting Critical Code Regions ................................................. 2-12

Modifying IMASK ...................................................................... 2-14

Examples .................................................................................... 2-15

File Structure .............................................................................. 2-16

Interrupt Manager API Reference ................................................ 2-17

Notation Conventions ........................................................... 2-17

adi_int_Init ........................................................................... 2-18

adi_int_Terminate ................................................................. 2-19

adi_int_CECHook ................................................................ 2-20

VisualDSP++ 5.0 Device Drivers and System v
Services Manual for Blackfin Processors

Contents

adi_int_CECUnhook ............................................................ 2-22

adi_int_ClearIMaskBits ........................................................ 2-24

adi_int_EnterCriticalRegion .................................................. 2-26

adi_int_ExitCriticalRegion .................................................... 2-28

adi_int_SICDisable ............................................................... 2-29

adi_int_SICEnable ................................................................ 2-30

adi_int_SICGetIVG .............................................................. 2-31

adi_int_SICInterruptAsserted ................................................ 2-32

adi_int_SICSetIVG .............................................................. 2-33

adi_int_SetIMaskBits ............................................................ 2-34

adi_int_SICWakeup .............................................................. 2-36

POWER MANAGEMENT MODULE

Introduction ................................................................................. 3-2

PM Module Operation – Getting Started ...................................... 3-3

Dual-Core Considerations ............................................................ 3-5

Using Automatic Synchronization ........................................... 3-5

Synchronization Requirement .................................................. 3-6

Running Applications on One Core Only ................................ 3-7

Running Applications on Both Cores ....................................... 3-8

Synchronization Between Cores ............................................. 3-10

Built-In Lock Variable and Linking Considerations ................ 3-10

SDRAM Initialization Prior to Loading an Executable ................. 3-13

vi VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

Power Management API Reference .............................................. 3-15

Notation Conventions ........................................................... 3-15

adi_pwr_AdjustFreq .............................................................. 3-16

adi_pwr_Control ................................................................... 3-18

adi_pwr_GetConfigSize ......................................................... 3-20

adi_pwr_GetFreq .................................................................. 3-21

adi_pwr_GetPowerMode ....................................................... 3-22

adi_pwr_GetPowerSaving ...................................................... 3-23

adi_pwr_Init ......................................................................... 3-24

adi_pwr_LoadConfig ............................................................. 3-30

adi_pwr_Reset ....................................................................... 3-31

adi_pwr_SaveConfig .............................................................. 3-32

adi_pwr_SetFreq ................................................................... 3-33

adi_pwr_SetMaxFreqForVolt ................................................. 3-35

adi_pwr_SetPowerMode ........................................................ 3-36

adi_pwr_SetVoltageRegulator ................................................ 3-38

Public Data Types and Enumerations ........................................... 3-42

ADI_PWR_COMMAND ..................................................... 3-42

ADI_PWR_COMMAND_PAIR ........................................... 3-47

ADI_PWR_CSEL ................................................................. 3-47

ADI_PWR_DF ..................................................................... 3-48

ADI_PWR_INPUT_DELAY ................................................. 3-48

ADI_PWR_OUTPUT_DELAY ............................................. 3-48

ADI_PWR_MODE .............................................................. 3-49

VisualDSP++ 5.0 Device Drivers and System vii
Services Manual for Blackfin Processors

Contents

ADI_PWR_PACKAGE_KIND ............................................. 3-49

ADI_PWR_PCC133_COMPLIANCE .................................. 3-50

ADI_PWR_PROC_KIND .................................................... 3-50

ADI_PWR_RESULT ............................................................ 3-50

ADI_PWR_SSEL .................................................................. 3-52

ADI_PWR_VDDEXT .......................................................... 3-53

ADI_PWR_VLEV ................................................................ 3-53

ADI_PWR_VR_CANWE ..................................................... 3-54

ADI_PWR_VR_USBWE ...................................................... 3-54

ADI_PWR_VR_CKELOW ................................................... 3-54

ADI_PWR_VR_CLKBUFOE ............................................... 3-55

ADI_PWR_VR_FREQ ......................................................... 3-55

ADI_PWR_VR_GAIN ......................................................... 3-55

ADI_PWR_VR_PHYWE ..................................................... 3-56

ADI_PWR_VR_WAKE ........................................................ 3-56

PM Module Macros .................................................................... 3-56

EXTERNAL BUS INTERFACE UNIT MODULE

Introduction ................................................................................. 4-2

Using the EBIU Module ............................................................... 4-3

EBIU API Reference ................................................................... 4-10

Notation Conventions ........................................................... 4-10

adi_ebiu_AdjustSDRAM ....................................................... 4-11

adi_ebiu_Control .................................................................. 4-12

adi_ebiu_GetConfigSize ........................................................ 4-15

viii VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

adi_ebiu_Init ........................................................................ 4-16

adi_ebiu_LoadConfig ............................................................ 4-22

adi_ebiu_SaveConfig ............................................................. 4-23

Public Data Types and Enumerations ........................................... 4-24

ADI_EBIU_RESULT ............................................................ 4-24

ADI_EBIU_SDRAM_BANK_VALUE ................................... 4-27

ADI_EBIU_TIME ................................................................ 4-27

ADI_EBIU_TIMING_VALUE ............................................. 4-28

ADI_EBIU_ASYNCH_BANK_TIMING .............................. 4-29

ADI_EBIU_ASYNCH_BANK_VALUE ................................. 4-30

Setting Control Values in the EBIU Module ................................ 4-31

ADI_EBIU_COMMAND ..................................................... 4-31

ADI_EBIU_COMMAND_PAIR ........................................... 4-38

Command Value Enumerations ............................................. 4-38

ADI_EBIU_SDRAM_ENABLE ........................................ 4-38

ADI_EBIU_SDRAM_BANK_SIZE .................................. 4-39

ADI_EBIU_SDRAM_BANK_COL_WIDTH ................... 4-39

ADI_EBIU_SDRAM_MODULE_TYPE .......................... 4-39

ADI_EBIU_CMD_SET_SDRAM_SCTLE ....................... 4-40

ADI_EBIU_SDRAM_EMREN ......................................... 4-40

ADI_EBIU_SDRAM_PASR ............................................. 4-41

ADI_EBIU_SDRAM_TCSR ............................................. 4-41

ADI_EBIU_SDRAM_SRFS .............................................. 4-41

ADI_EBIU_SDRAM_EBUFE .......................................... 4-42

VisualDSP++ 5.0 Device Drivers and System ix
Services Manual for Blackfin Processors

Contents

ADI_EBIU_SDRAM_PUPSD .......................................... 4-42

ADI_EBIU_SDRAM_PSM .............................................. 4-43

ADI_EBIU_SDRAM_FBBRW ......................................... 4-43

ADI_EBIU_SDRAM_CDDBG ........................................ 4-44

ADI_EBIU_BANK_NUMBER ........................................ 4-44

ADI_EBIU_ASYNCH_BANK_ENABLE ......................... 4-45

ADI_EBIU_ASYNCH_CLKOUT .................................... 4-45

ADI_EBIU_ASYNCH_BANK_DATA_PATH .................. 4-45

ADI_EBIU_ASYNCH_BANK_ARDY_ENABLE ............. 4-46

ADI_EBIU_ASYNCH_BANK_ARDY_POLARITY ......... 4-46

ADI_EBIU_ASYNCH_HOLD_TIME ............................. 4-46

ADI_EBIU_ASYNCH_SETUP_TIME ............................. 4-47

ADI_EBIU_ASYNCH_TRANSITION_TIME ................. 4-47

DEFERRED CALLBACK MANAGER

Introduction ................................................................................. 5-1

Using the Deferred Callback Manager ........................................... 5-3

Interoperability With an RTOS ..................................................... 5-8

adi_dcb_Forward .................................................................... 5-9

adi_dcb_RegisterISR ............................................................. 5-11

Handling Critical Regions Within Callbacks .......................... 5-11

DCB Manager API Reference ...................................................... 5-12

Notation Conventions ........................................................... 5-12

adi_dcb_Close ...................................................................... 5-13

adi_dcb_Control ................................................................... 5-14

x VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

adi_dcb_Init ......................................................................... 5-17

adi_dcb_Open ...................................................................... 5-19

adi_dcb_Post ......................................................................... 5-21

adi_dcb_Remove ................................................................... 5-23

adi_dcb_Terminate ................................................................ 5-24

Public Data Types and Macros ..................................................... 5-25

ADI_DCB_CALLBACK_FN ................................................ 5-25

ADI_DCB_COMMAND_PAIR ........................................... 5-25

ADI_DCB_COMMAND ...................................................... 5-26

ADI_DCB_ENTRY_HDR .................................................... 5-26

ADI_DCB_RESULT ............................................................. 5-27

DMA MANAGER

Introduction ................................................................................. 6-2

Theory of Operation ..................................................................... 6-3

Overview ................................................................................ 6-3

DMA Manager Initialization ................................................... 6-4

DMA Manager Termination ................................................... 6-5

Memory DMA and Peripheral DMA ........................................ 6-6

Controlling Memory Streams ................................................... 6-7

Opening Memory Streams ................................................... 6-7

Memory Transfers ............................................................... 6-8

One-Dimensional Transfers (Linear Transfers) ................. 6-8

Two-Dimensional Transfers ............................................. 6-9

Closing Memory Streams .................................................. 6-10

VisualDSP++ 5.0 Device Drivers and System xi
Services Manual for Blackfin Processors

Contents

Controlling DMA Channels .................................................. 6-10

Opening DMA Channels .................................................. 6-11

Single Transfers ............................................................ 6-12

Circular Transfers ......................................................... 6-14

Large Descriptor Chaining Model ................................. 6-16

Small Descriptor Chaining Model ................................. 6-20

Arrays of Descriptors .................................................... 6-20

Configuring a DMA Channel ........................................... 6-20

Closing a DMA Channel .................................................. 6-21

Transfer Completions ............................................................ 6-21

Polling ............................................................................. 6-22

Callbacks .......................................................................... 6-22

Memory Stream Callbacks ............................................ 6-22

Circular Transfer Callbacks ........................................... 6-23

Descriptor Callbacks ..................................................... 6-23

Descriptor-Based Sub-Modes ................................................. 6-24

Loopback Sub-Mode ......................................................... 6-24

Streaming Sub-Mode ........................................................ 6-25

DMA Channel to Peripheral Mapping ................................... 6-26

Sensing a Mapping ........................................................... 6-27

Setting a Mapping ............................................................ 6-27

xii VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

Interrupts .............................................................................. 6-27

Hooking Interrupts ........................................................... 6-28

Unhooking Interrupts ....................................................... 6-28

Two-Dimensional DMA ........................................................ 6-29

DMA Traffic Control ........................................................... 6-31

DMA Manager API Reference ..................................................... 6-32

Notation Conventions ........................................................... 6-32

adi_dma_Buffer ..................................................................... 6-34

adi_dma_Close ...................................................................... 6-36

adi_dma_Control .................................................................. 6-37

adi_dma_GetMapping ........................................................... 6-39

adi_dma_Init ........................................................................ 6-40

adi_dma_MemoryClose ......................................................... 6-41

adi_dma_MemoryCopy ......................................................... 6-42

adi_dma_MemoryCopy2D .................................................... 6-44

adi_dma_MemoryOpen ......................................................... 6-46

adi_dma_Open ..................................................................... 6-48

adi_dma_Queue .................................................................... 6-50

adi_dma_SetMapping ............................................................ 6-51

adi_dma_Terminate ............................................................... 6-52

VisualDSP++ 5.0 Device Drivers and System xiii
Services Manual for Blackfin Processors

Contents

Public Data Structures, Enumerations, and Macros ...................... 6-53

Data Types ............................................................................ 6-54

ADI_DMA_CHANNEL_HANDLE ................................. 6-54

ADI_DMA_DESCRIPTOR_UNION and ADI_DMA_

DESCRIPTOR_HANDLE ............................................ 6-54

ADI_DMA_STREAM_HANDLE .................................... 6-55

Data Structures ..................................................................... 6-55

ADI_DMA_2D_TRANSFER ........................................... 6-55

ADI_DMA_CONFIG_REG ............................................ 6-56

ADI_DMA_DESCRIPTOR_ARRAY ................................ 6-56

ADI_DMA_DESCRIPTOR_LARGE ............................... 6-56

ADI_DMA_DESCRIPTOR_SMALL ............................... 6-57

ADI_DMA_TC_SET ....................................................... 6-57

ADI_DMA_TC_GET ...................................................... 6-58

General Enumerations ........................................................... 6-58

ADI_DMA_CHANNEL_ID ............................................ 6-58

ADI_DMA_EVENT ........................................................ 6-58

ADI_DMA_MODE ......................................................... 6-59

ADI_DMA_PMAP ........................................................... 6-60

ADI_DMA_RESULT ....................................................... 6-60

ADI_DMA_STREAM_ID ............................................... 6-60

ADI_DMA_TC_PARAMETER ........................................ 6-61

ADI_DMA_CONFIG_REG Field Values .............................. 6-61

ADI_DMA_DMA2D ....................................................... 6-61

ADI_DMA_DI_EN ......................................................... 6-61

xiv VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

ADI_DMA_DI_SEL ......................................................... 6-61

ADI_DMA_EN ................................................................ 6-62

ADI_DMA_WDSIZE ....................................................... 6-62

ADI_DMA_WNR ............................................................ 6-62

DMA Commands .................................................................. 6-62

PROGRAMMABLE FLAG SERVICE

Introduction ................................................................................. 7-2

Operation ..................................................................................... 7-3

Initialization ............................................................................ 7-3

Termination ............................................................................ 7-4

Flag IDs .................................................................................. 7-4

Flag Control Functions ............................................................ 7-5

adi_flag_Open .................................................................... 7-5

adi_flag_Close .................................................................... 7-5

adi_flag_SetDirection .......................................................... 7-5

adi_flag_Set ........................................................................ 7-5

adi_flag_Clear ..................................................................... 7-6

adi_flag_Toggle ................................................................... 7-6

adi_flag_Sense .................................................................... 7-6

Callbacks ................................................................................ 7-6

adi_flag_InstallCallback ...................................................... 7-7

adi_flag_RemoveCallback ................................................... 7-8

adi_flag_SuspendCallbacks .................................................. 7-9

VisualDSP++ 5.0 Device Drivers and System xv
Services Manual for Blackfin Processors

Contents

adi_flag_ResumeCallbacks .................................................. 7-9

adi_flag_SetTrigger ............................................................. 7-9

Coding Example ..................................................................... 7-9

Initialization ..................................................................... 7-10

Opening a Flag ................................................................. 7-11

Setting Flag Direction ....................................................... 7-11

Controlling an Output Flag .............................................. 7-11

Sensing the Value of a Flag ................................................ 7-12

Installing a Callback Function ........................................... 7-12

Suspending and Resuming Callbacks ................................. 7-13

Removing Callbacks ......................................................... 7-13

Termination ..................................................................... 7-14

Flag Service API Reference .......................................................... 7-15

Notation Conventions ........................................................... 7-15

adi_flag_Clear ....................................................................... 7-16

adi_flag_Close ...................................................................... 7-17

adi_flag_Init ......................................................................... 7-18

adi_flag_Open ...................................................................... 7-20

adi_flag_SetDirection ............................................................ 7-21

adi_flag_Terminate ............................................................... 7-22

adi_flag_Set .......................................................................... 7-23

adi_flag_Toggle ..................................................................... 7-24

adi_flag_Sense ...................................................................... 7-25

adi_flag_InstallCallback ........................................................ 7-26

xvi VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

adi_flag_RemoveCallback ...................................................... 7-28

adi_flag_SuspendCallbacks .................................................... 7-29

adi_flag_ResumeCallbacks ..................................................... 7-30

adi_flag_SetTrigger ................................................................ 7-31

Public Data Types, Enumerations, and Macros ............................. 7-32

ADI_FLAG_ID ..................................................................... 7-32

Associated Macros ............................................................. 7-33

ADI_FLAG_RESULT ........................................................... 7-33

ADI_FLAG_EVENT ............................................................ 7-34

ADI_FLAG_TRIGGER ........................................................ 7-35

ADI_FLAG_DIRECTION ................................................... 7-35

TIMER SERVICE

Introduction ................................................................................. 8-2

Operation ..................................................................................... 8-3

Initialization ............................................................................ 8-3

Termination ............................................................................ 8-3

Timer IDs ............................................................................... 8-4

Basic Timer Functions ............................................................. 8-4

adi_tmr_Open .................................................................... 8-4

adi_tmr_Close .................................................................... 8-4

adi_tmr_Reset ..................................................................... 8-5

General-Purpose Timer Functions ............................................ 8-5

adi_tmr_GPControl ............................................................ 8-5

adi_tmr_GPGroupEnable ................................................... 8-5

VisualDSP++ 5.0 Device Drivers and System xvii
Services Manual for Blackfin Processors

Contents

Core Timer Functions ............................................................. 8-6

adi_tmr_CoreControl ......................................................... 8-6

Watchdog Timer Functions ..................................................... 8-6

adi_tmr_WatchdogControl ................................................. 8-6

Peripheral Timer Functions ..................................................... 8-7

adi_tmr_GetPeripheralID ................................................... 8-7

Callbacks ................................................................................ 8-7

adi_tmr_InstallCallback ...................................................... 8-8

adi_tmr_RemoveCallback ................................................... 8-9

Coding Example ..................................................................... 8-9

Initialization ..................................................................... 8-10

Opening a Timer .............................................................. 8-10

Configuring a Timer ......................................................... 8-10

Enabling and Disabling Timers ......................................... 8-12

Installing a Callback Function ........................................... 8-13

Removing Callbacks ......................................................... 8-14

Termination ..................................................................... 8-15

Timer Service API Reference ....................................................... 8-15

Notation Conventions ........................................................... 8-15

adi_tmr_Init ......................................................................... 8-16

adi_tmr_Open ...................................................................... 8-17

adi_tmr_Terminate ............................................................... 8-18

adi_tmr_Close ...................................................................... 8-19

adi_tmr_Reset ....................................................................... 8-20

xviii VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

adi_tmr_CoreControl ............................................................ 8-21

adi_tmr_WatchdogControl .................................................... 8-22

adi_tmr_GPControl .............................................................. 8-23

adi_tmr_GPGroupEnable ...................................................... 8-24

adi_tmr_InstallCallback ......................................................... 8-26

adi_tmr_RemoveCallback ...................................................... 8-28

adi_tmr_GetPeripheralID ...................................................... 8-29

Public Data Types, Enumerations, and Macros ............................. 8-30

Timer IDs ............................................................................. 8-30

Associated Macros ............................................................. 8-31

ADI_TMR_RESULT ............................................................ 8-32

ADI_TMR_EVENT ............................................................. 8-33

ADI_TMR_CORE_CMD ..................................................... 8-33

ADI_TMR_WDOG_CMD .................................................. 8-34

ADI_TMR_GP_CMD .......................................................... 8-35

PORT CONTROL SERVICE

Introduction ................................................................................. 9-2

Using the Port Control Manager .................................................... 9-3

Port Control Manager API Reference ............................................. 9-5

Notation Conventions ............................................................. 9-5

adi_ports_Init ......................................................................... 9-6

adi_ports_Terminate ................................................................ 9-7

adi_ports_EnablePPI ............................................................... 9-8

adi_ports_EnableSPI ............................................................... 9-9

VisualDSP++ 5.0 Device Drivers and System xix
Services Manual for Blackfin Processors

Contents

adi_ports_EnableSPORT ...................................................... 9-10

adi_ports_EnableUART ........................................................ 9-11

adi_ports_EnableCAN .......................................................... 9-12

adi_ports_EnableTimer ......................................................... 9-13

adi_ports_EnableGPIO ......................................................... 9-15

Public Data Types, Enumerations, and Macros ............................ 9-16

ADI_PORTS_RESULT ........................................................ 9-16

Directive Enumeration Values ............................................... 9-17

DEVICE DRIVER MANAGER

Device Driver Model Overview ................................................... 10-3

Using the Device Manager .......................................................... 10-6

Device Manager Overview ..................................................... 10-6

Theory of Operation ............................................................. 10-7

Data ................................................................................. 10-7

Initializing the Device Manager ........................................ 10-8

Device Manager Termination ............................................ 10-9

Opening a Device ........................................................... 10-10

Configuring a Device ...................................................... 10-11

Dataflow Method ....................................................... 10-12

Enabling Dataflow ...................................................... 10-15

Providing Buffers to a Device .......................................... 10-15

Closing a Device ............................................................. 10-16

Callbacks ........................................................................ 10-16

xx VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

Initialization Sequence .................................................... 10-17

Stackable Drivers ............................................................ 10-17

Deciding on a Dataflow Method ............................................... 10-18

Chained Without Loopback ................................................ 10-18

Chained With Loopback ..................................................... 10-18

Circular .............................................................................. 10-18

Sequential With and Without Loopback .............................. 10-19

Creating One-Dimensional Buffers ............................................ 10-19

Creating Two-Dimensional Buffers ............................................ 10-23

Creating Circular Buffers .......................................................... 10-26

Creating Sequential One-Dimensional Buffers ........................... 10-28

Device Manager Design ............................................................ 10-30

Device Manager API Description ......................................... 10-30

Memory Usage Macros .................................................... 10-31

Handles .......................................................................... 10-31

Dataflow Enumerations ................................................... 10-31

Command IDs ................................................................ 10-32

Callback Events .............................................................. 10-32

Return Codes .................................................................. 10-32

Circular Buffer Callback Options .................................... 10-33

Buffer Data Types ........................................................... 10-33

Physical Driver Entry Point ............................................. 10-34

API Function Definitions ................................................ 10-34

VisualDSP++ 5.0 Device Drivers and System xxi
Services Manual for Blackfin Processors

Contents

Device Manager Code ......................................................... 10-34

Data Structures ............................................................... 10-34

Static Data ..................................................................... 10-34

Static Function Declarations ........................................... 10-35

API Functional Description ............................................ 10-35

adi_dev_Init Functional Description ........................... 10-35

adi_dev_Open Functional Description ........................ 10-36

adi_dev_Close Functional Description ........................ 10-36

adi_dev_Read Functional Description ......................... 10-37

adi_dev_Write Functional Description ........................ 10-38

adi_dev_Control Functional Description ..................... 10-38

Static Functions .............................................................. 10-41

PDDCallback ............................................................. 10-41

DMACallback ............................................................ 10-42

PrepareBufferList ........................................................ 10-43

SetDataflow ................................................................ 10-44

Physical Driver Design .............................................................. 10-45

Physical Driver Design Overview ......................................... 10-45

Physical Device Driver API Description ............................... 10-47

Physical Driver Include File (“xxx.h”) .................................. 10-48

Extensible Definitions .................................................... 10-48

ADI_DEV_PDD_ENTRY_POINT ................................ 10-50

xxii VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

Physical Driver Source (“xxx.c”) ........................................... 10-50

adi_pdd_Open Functional Description ............................ 10-51

adi_pdd_Control Functional Description ........................ 10-52

adi_pdd_Read Functional Description ............................. 10-53

adi_pdd_Write Functional Description ............................ 10-55

adi_pdd_Close Functional Description ............................ 10-56

Device Manager API Reference .................................................. 10-57

Notation Conventions ......................................................... 10-57

adi_dev_Close ..................................................................... 10-58

adi_dev_Control ................................................................. 10-59

adi_dev_Init ........................................................................ 10-60

adi_dev_Open ..................................................................... 10-61

adi_dev_Read ...................................................................... 10-63

adi_dev_Terminate .............................................................. 10-64

adi_dev_Write ..................................................................... 10-65

Device Manager Public Data Types and Enumerations ............... 10-66

ADI_DEV_BUFFER_TYPE ................................................ 10-66

ADI_DEV_MODE ............................................................. 10-67

ADI_DEV_DIRECTION ................................................... 10-67

CALLBACK EVENTS ........................................................ 10-68

RESULT CODES ............................................................... 10-69

COMMAND IDs ............................................................... 10-72

ADI_DEV_1D_BUFFER .................................................... 10-75

ADI_DEV_2D_BUFFER .................................................... 10-76

VisualDSP++ 5.0 Device Drivers and System xxiii
Services Manual for Blackfin Processors

Contents

ADI_DEV_CIRCULAR_BUFFER ..................................... 10-77

ADI_DEV_SEQ_1D_BUFFER .......................................... 10-78

ADI_DEV_BUFFER_PAIR ................................................ 10-78

ADI_DEV_DMA_INFO .................................................... 10-79

ADI_DEV_DMA_ACCESS ................................................ 10-79

ADI_DEV_FREQUENCIES .............................................. 10-80

ADI_DEV_ACCESS_REGISTER ....................................... 10-80

ADI_DEV_ACCESS_REGISTER_BLOCK ........................ 10-81

ADI_DEV_ACCESS_REGISTER_FIELD .......................... 10-81

ADI_DEV_BUFFER .......................................................... 10-82

Physical Driver API Reference ................................................... 10-83

Notation Conventions ......................................................... 10-83

adi_pdd_Close .................................................................... 10-84

adi_pdd_Control ................................................................ 10-85

adi_pdd_Open .................................................................... 10-86

adi_pdd_Read ..................................................................... 10-88

adi_pdd_Write .................................................................... 10-89

Examples .................................................................................. 10-90

REAL-TIME CLOCK SERVICE

Introduction ............................................................................... 11-1

Operation .................................................................................. 11-2

Initialization ......................................................................... 11-2

Termination .......................................................................... 11-3

Setting and Reading the Date and Time ................................ 11-4

xxiv VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

Real-Time Clock Events ........................................................ 11-5

One Second Periodic Event ............................................... 11-5

One Minute Periodic Event ............................................... 11-6

Hourly Periodic Event ....................................................... 11-6

Daily Periodic Event ......................................................... 11-6

Periodic or One-Shot Stopwatch Event .............................. 11-7

Once Only Alarm Event .................................................... 11-7

Each Day Alarm Event ...................................................... 11-7

Pending Writes Complete Event ........................................ 11-8

Callbacks .............................................................................. 11-8

The Callback List ............................................................. 11-9

Installing a Callback ......................................................... 11-9

Removing a Callback ..................................................... 11-10

The Real-Time Clock Service Interrupt Handler .............. 11-10

Using the ClientHandle Parameter in a Callback .............. 11-10

Coding Example ................................................................. 11-11

RTC Service Application Programming Interface (API) .............. 11-16

Notation and Naming Conventions ..................................... 11-16

RTC Service API Functions ................................................. 11-17

adi_rtc_Init() ...................................................................... 11-18

adi_rtc_Terminate() ............................................................ 11-19

adi_rtc_SetDateTime() ....................................................... 11-20

adi_ rtc_GetDateTime() ...................................................... 11-21

adi_rtc_InstallCallback() ..................................................... 11-22

VisualDSP++ 5.0 Device Drivers and System xxv
Services Manual for Blackfin Processors

Contents

adi_rtc_RemoveCallback() .................................................. 11-24

adi_rtc_EnableWakeup() ..................................................... 11-25

adi_rtc_DisableWakeup() .................................................... 11-26

adi_rtc_ResetStopwatch() .................................................... 11-27

Real-Time Clock Service API Data Types and Enumerations ...... 11-28

tm structure ....................................................................... 11-28

Event IDs ........................................................................... 11-29

Result Codes ....................................................................... 11-30

Interdependencies ..................................................................... 11-31

Interrupt Manager Service ................................................... 11-31

Deferred Callback Service ................................................... 11-31

FILE SYSTEM SERVICE

Introduction ............................................................................... 12-2

Getting Started ........................................................................... 12-3

Initialization ......................................................................... 12-4

Termination .......................................................................... 12-7

System Service Requirements ...................................................... 12-7

Interrupt Manager Service ..................................................... 12-8

Deferred Callback Service ..................................................... 12-9

DMA Service ...................................................................... 12-10

Semaphore Service .............................................................. 12-10

Real-Time Clock Service ..................................................... 12-11

Device Manager .................................................................. 12-11

xxvi VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

Advanced Configuration ........................................................... 12-12

Custom Configuration of Device Drivers ............................. 12-12

Dynamic Memory Usage ..................................................... 12-13

File Cache ........................................................................... 12-16

File System Service API Reference ............................................. 12-17

Notation and Naming Conventions ..................................... 12-17

adi_fss_Init ......................................................................... 12-19

adi_fss_Terminate .............................................................. 12-21

adi_fss_Control ................................................................... 12-22

adi_fss_FileOpen ................................................................. 12-24

adi_fss_FileClose ................................................................. 12-26

adi_fss_FileWrite ................................................................. 12-27

adi_fss_FileRead .................................................................. 12-28

adi_fss_FileSeek .................................................................. 12-29

adi_fss_FileTell .................................................................... 12-31

adi_fss_IsEOF ..................................................................... 12-32

adi_fss_FileRemove ............................................................. 12-33

adi_fss_FileRename ............................................................. 12-34

adi_fss_DirOpen ................................................................. 12-35

adi_fss_DirClose ................................................................. 12-36

adi_fss_DirRead .................................................................. 12-37

adi_fss_DirSeek ................................................................... 12-38

adi_fss_DirTell .................................................................... 12-39

adi_fss_DirRewind .............................................................. 12-40

VisualDSP++ 5.0 Device Drivers and System xxvii
Services Manual for Blackfin Processors

Contents

adi_fss_DirChange ............................................................. 12-41

adi_fss_GetCurrentDir ...................................................... 12-42

adi_fss_DirCreate ............................................................... 12-43

adi_fss_DirRemove ............................................................. 12-44

File System Service API Data Types and Enumerations .............. 12-45

ADI_FSS_WCHAR ............................................................ 12-45

ADI_FSS_VOLUME_IDENT ............................................ 12-45

ADI_FSS_FILE_HANDLE ................................................. 12-45

ADI_FSS_DIR_HANDLE .................................................. 12-46

ADI_FSS_CMD_VALUE_PAIR ......................................... 12-46

ADI_FSS_DIR_ENTRY ..................................................... 12-47

ADI_FSS_DEVICE_DEF ................................................... 12-47

Result Codes ............................................................................ 12-49

The Standard C I/O Interface Functions ................................... 12-51

fopen .................................................................................. 12-52

fclose .................................................................................. 12-53

fwrite .................................................................................. 12-54

fread ................................................................................... 12-55

fprintf ................................................................................. 12-56

fscanf .................................................................................. 12-57

fgetc ................................................................................... 12-58

fgets ................................................................................... 12-59

fputc ................................................................................... 12-60

fputs ................................................................................... 12-61

xxviii VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Contents

fseek ................................................................................... 12-62

ftell ..................................................................................... 12-63

feof ..................................................................................... 12-64

Additional POSIX Functions Supported by the FSS ................... 12-65

opendir ............................................................................... 12-66

closedir ............................................................................... 12-67

readdir ................................................................................ 12-68

readdir_r ............................................................................. 12-69

rewinddir ............................................................................ 12-70

seekdir ................................................................................ 12-71

telldir .................................................................................. 12-72

mkdir .................................................................................. 12-73

rmdir .................................................................................. 12-74

rename ................................................................................ 12-75

remove ................................................................................ 12-76

Extensibility .............................................................................. 12-77

Examples .................................................................................. 12-77

HardDiskAccess .................................................................. 12-78

Description ..................................................................... 12-78

Configuration ................................................................. 12-79

HardDiskFormat ................................................................. 12-79

Description ..................................................................... 12-80

Configuration ................................................................ 12-80

VisualDSP++ 5.0 Device Drivers and System xxix
Services Manual for Blackfin Processors

Contents

Shell_Browser ..................................................................... 12-80

Description .................................................................... 12-80

Configuration ................................................................ 12-81

INDEX

xxx VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors