Analog Devices ADSP-BF531, ADSP-BF534, ADSP-BF532, ADSP-BF533, ADSP-BF536 Service Manual

a

W5.0

Device Drivers and System Services

Manual for Blackfin

®

Processors

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

Revision 3.2, August 2008

Part Number

82-000430-01

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

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

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

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

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

PREFACE

Thank you for purchasing Analog Devices, Inc. development software for
Analog Devices embedded processors.

Purpose of This Manual

The VisualDSP++ 5.0 Update 4 Device Drivers and System Services Manual
for Blackfin Processors contains information about the Analog Devices

device driver model and system services library suite. Included are archi­tectural descriptions of the device driver design and each system service
component. Also included is a description of the API calls into each
library.

Intended Audience

The primary audience for this manual is a programmer who is familiar
with Analog Devices Blackfin® processors. This manual assumes the audi­ence has a working knowledge of the appropriate processor architecture
and instruction set. Programmers who are unfamiliar with Analog Devices
processors can use this manual, but should supplement it with other texts,
such as hardware reference and programming reference manuals, that
describe their target architecture.

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

Manual Contents Description

Manual Contents Description

This manual contains:

• Chapter 1, “Introduction”
Provides an overview of system services and device drivers.

• Chapter 2, “Interrupt Manager”
Describes the system interrupt controller (SIC) manager that sup­ports the general-purpose interrupt events.

• Chapter 3, “Power Management Module”
Describes the power management module that supports dynamic
power management of Blackfin processors.

• Chapter 4, “External Bus Interface Unit Module”
Describes the external bus interface unit (EBIU) module that
enables the power management module to manage the SDRAM
controller operation.

• Chapter 5, “Deferred Callback Manager”
Describes the deferred callback manager that is used by the applica­tion developer to effectively execute function calls.

• Chapter 6, “DMA Manager”
Describes direct memory access (DMA) manager API.

• Chapter 7, “Programmable Flag Service”
Describes the programmable flag service that provides interface
into the programmable flag subsystem of the Blackfin processor.

• Chapter 8, “Timer Service”
Describes the timer service that provides interface into the core,
watchdog, and general-purpose timers of the Blackfin processor.

xxxii VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Preface

• Chapter 9, “Port Control Service”
Describes the port control manager service used to assign the pro­grammable flag pins to various functions (on ADSP-BF534,
ADSP-BF536, and ADSP-BF537 processors only).

• Chapter 10, “Device Driver Manager”
Describes the device driver model used to control devices, both
internal and external, to ADI processors.

• Chapter 11, “Real-Time Clock Service”
Describes the real-time clock service within the system services
library and how to use it to enable the features of the real-time
clock on Blackfin processors.

• Chapter 12, “File System Service”
Describes the file system service (FSS), which provides access to
mass storage media from the Blackfin processor.

What’s New in This Manual

This revision (3.2) of the VisualDSP++ 5.0 Update 4 Device Drivers and
System Services Manual for Blackfin Processors contains the following

changes/additions:

• Removed obsoleted commands and added new commands to
Chapter 6,

• Added new sections “DMA Traffic Control” on page 6-31 and

“Device Manager Public Data Types and Enumerations” on
page 10-66.

• Added new commands to Chapter 12, “File System Service”.

“DMA Manager”.

• Modifications and corrections based on errata reports against the
previous revision (3.1) of the manual.

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

Technical or Customer Support

Technical or Customer Support

You can reach Analog Devices, Inc. Customer Support in the following
ways:

• Visit the Embedded Processing and DSP products Web site at

http://www.analog.com/processors/technical_support

• E-mail tools questions to

[e-mail]

• E-mail processor questions to

[e-mail] (World wide support)
[e-mail] (Europe support)
[e-mail] (China support)

• Phone questions to 1-800-ANALOGD

• Contact your Analog Devices, Inc. local sales office or authorized
distributor

• Send questions by mail to:

Analog Devices, Inc.
One Technology Way
P.O. Box 9106
Norwood, MA 02062-9106, USA

Supported Processors

The name Blackfin refers to a family of 16-bit, embedded processors.
VisualDSP++® currently supports the following Blackfin families:

ADSP-BF52x, ADSP-BF53x, ADSP-BF54x, and ADSP-BF56x

xxxiv VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Preface

Product Information

Product information can be obtained from the Analog Devices Web site,
VisualDSP++ online Help system, and a technical library CD.

Analog Devices Web Site

The Analog Devices Web site, www.analog.com, provides information
about a broad range of products—analog integrated circuits, amplifiers,
converters, and digital signal processors.

To access a complete technical library for each processor family, go to

http://www.analog.com/processors/technical_library. The manuals

selection opens a list of current manuals related to the product as well as a
link to the previous revisions of the manuals. When locating your manual
title, note a possible errata check mark next to the title that leads to the
current correction report against the manual.

Also note, MyAnalog.com is a free feature of the Analog Devices Web site
that allows customization of a Web page to display only the latest infor­mation about products you are interested in. You can choose to receive
weekly e-mail notifications containing updates to the Web pages that meet
your interests, including documentation errata against all manuals. MyAna-

log.com provides access to books, application notes, data sheets, code

examples, and more.

Visit MyAnalog.com to sign up. If you are a registered user, just log on.
Your user name is your e-mail address.

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

Product Information

VisualDSP++ Online Documentation

Online documentation comprises the VisualDSP++ Help system, software
tools manuals, hardware tools manuals, processor manuals, Dinkum
Abridged C++ library, and FLEXnet License Tools software documenta­tion. You can search easily across the entire VisualDSP++ documentation
set for any topic of interest.

For easy printing, supplementary Portable Documentation Format (.pdf)
files for all manuals are provided on the VisualDSP++ installation CD.

Each documentation file type is described as follows.

File Description

.chm Help system files and manuals in Microsoft Help format

.htm or
.html

.pdf VisualDSP++ and processor manuals in (PDF) format. Viewing and printing the

Dinkum Abridged C++ library and FLEXnet License Tools software
documentation. Viewing and printing the .html files requires a browser, such as
Internet Explorer 6.0 (or higher).

.pdf files requires a PDF reader, such as Adobe Acrobat Reader (4.0 or higher).

Technical Library CD

The technical library CD contains seminar materials, product highlights, a
selection guide, and documentation files of processor manuals, Visu­alDSP++ software manuals, and hardware tools manuals for the following
processor families: Blackfin, SHARC®, TigerSHARC®, ADSP-218x, and
ADSP-219x.

To order the technical library CD, go to http://www.analog.com/proces-

sors/technical_library, navigate to the manuals page for your

processor, click the request CD check mark, and fill out the order form.

xxxvi VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Preface

L

a

Data sheets, which can be downloaded from the Analog Devices Web site,
change rapidly, and therefore are not included on the technical library
CD. Technical manuals change periodically. Check the Web site for the
latest manual revisions and associated documentation errata.

Notation Conventions

Text conventions used in this manual are identified and described as fol­lows. Note that additional conventions, which apply only to specific
chapters, may appear throughout this document.

Example Description

{this | that} Alternative required items in syntax descriptions appear within curly

brackets and separated by vertical bars; read the example as this or

that. One or the other is required.

[this | that] Optional items in syntax descriptions appear within brackets and

separated by vertical bars; read the example as an optional this or

that.

[this,…] Optional item lists in syntax descriptions appear within brackets

delimited by commas and terminated with an ellipse; read the example
as an optional comma-separated list of

.SECTION Commands, directives, keywords, and feature names are in text with

letter gothic font.

filename Non-keyword placeholders appear in text with italic style format.

Note: For correct operation, ...
A Note provides supplementary information on a related topic. In the
online version of this book, the word Note appears instead of this
symbol.

Caution: Incorrect device operation may result if ...
Caution: Device damage may result if ...

A Caution identifies conditions or inappropriate usage of the product
that could lead to undesirable results or product damage. In the online
version of this book, the word Caution appears instead of this symbol.

this.

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

Notation Conventions

[

Example Description

Warn in g: Injury to device users may result if ...

A Warning identifies conditions or inappropriate usage of the product
that could lead to conditions that are potentially hazardous for devices
users. In the online version of this book, the word Warn ing appears
instead of this symbol.

xxxviii VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

1 INTRODUCTION

This manual describes the system services and device driver architecture
for Analog Devices embedded processors.

The system services form a collection of functions that are commonly
found in embedded systems. Each system service focuses on a specific set
of functionality such as direct memory access (DMA), power management
(PM), interrupt control (IC), and so on. Collectively, the system services
provide a wealth of pre-built, optimized code that simplifies software
development, allowing you to get Blackfin processor-based designs to
market more quickly.

The device driver model provides a simple, clean and familiar interface
into device drivers for Blackfin processors. The primary objective of the
device driver model is to create a concise, effective, and easy-to-use
interface through which applications can communicate with device
drivers. Secondarily, the model and device manager software significantly
simplifies the development of device drivers, making the development of
new device drivers very straightforward.

Currently, the system services and device drivers are available for use with
the following Blackfin families: ADSP-BF531/532/533,
ADSP-BF534/536/537, ADSP-BF538/539,
ADSP-BF542/544/547/548/549, ADSP-BF522/524/526,
ADSP-BF532/525/527, and ADSP-BF561.

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

System Services Overview

This chapter contains:

• “System Services Overview” on page 1-2

• “Device Driver Overview” on page 1-19

System Services Overview

The system services overview covers the following topics:

• “General” on page 1-3

• “Application Interface” on page 1-7

• “Dependencies” on page 1-8

• “Initialization” on page 1-10

• “Termination” on page 1-10

• “System Services Directory and File Structure” on page 1-11

1-2 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

General

The current revision of the system services library consists of the following
services:

• Interrupt Control Service – The interrupt control service allows

the application to control and leverage the event and interrupt pro
cessing of the processor more effectively. Specific functionality
allows the application to:

• Set and detect the mappings of the interrupt priority levels
to peripherals.

• Use standard C functions as interrupt handlers.

-

• Hook and unhook multiple interrupt handlers to the same
interrupt priority level using both nesting and non-nesting
capabilities.

• Detect if a system interrupt is being asserted.

• Protect and unprotect critical regions of code in a portable
manner.

• Power Management Service – The power management service

allows the application to control the dynamic power management
capabilities of a Blackfin processor. Specific functionality allows
the application to:

• Set core and system clock operating frequencies with a func­tion call.

• Set and detect the internal voltage regulator settings.

• Transition the processor among the various operating
modes including, full-on, active, sleep, and so on.

VisualDSP++ 5.0 Device Drivers and System 1-3
Services Manual for Blackfin Processors

System Services Overview

• External Bus Interface Unit Control Service (EBIU) – The EBIU

control service provides a collection of routines to set up the exter­nal interfaces of the Blackfin processor, including the SDRAM
controller. This functionality enables you to:

• Adjust SDRAM refresh and timing rates to optimal values
for given system clock frequencies.

• Set individual bus interface settings.

• Complete single function setup for known configurations,
such as the Blackfin EZ-KIT Lite platforms.

• Deferred Callback Service – The deferred callback service allows

the application to be notified of asynchronous events outside of
high-priority interrupt service routines. Using deferred callbacks
typically improves the overall I/O capacity of the system while at
the same time reducing interrupt latency. Specific functionality
allows the application to:

• Define how many callbacks can be pending at any point in
time.

• Define the interrupt priority level at which the callback ser­vice executes.

• Create multiple callback services, each operating at a differ­ent interrupt priority level.

• Post callbacks to a callback service with a relative priority
among all other callbacks posted to the same callback
service.

• DMA Management Service – The DMA management service

provides access into the DMA controller of a Blackfin processor.
The DMA management service allows the application to schedule

1-4 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

DMA operations, both peripheral and memory DMA, supporting
both linear and two-dimensional transfer types. Specific function­ality allows the application to:

• Set and detect the mapping of DMA channels to
peripherals.

• Configure individual DMA channels for inbound/outbound
traffic using circular (autobuffered) DMA or descrip­tor-based DMA.

• Command the DMA manager to issue live or deferred
callbacks upon DMA completions.

• Queue descriptors, intermixing linear and two-dimensional
transfers on DMA channels.

• Enable the DMA manager to loopback on descriptor chains
automatically.

• Stream data continuously into or out of a memory stream or
peripheral.

• Initiate linear and two-dimensional memory DMA transfers
with simple C-like, memcpy-type functions.

• Programmable Flag Service – The programmable flag service

provides a simple interface into the programmable flags, sometimes
called general-purpose I/O, of the Blackfin processor. This allows

VisualDSP++ 5.0 Device Drivers and System 1-5
Services Manual for Blackfin Processors

System Services Overview

the application to access and control the programmable flags
through a clean and consistent interface. The programmable flag
service allows the application to:

• Configure the direction, either input or output, of any flag.

• Set, clear, and toggle the value of all output flags.

• Sense the value of input flags.

• Install callbacks, including live and deferred callbacks when
specific trigger conditions occur on a flag.

• Timer Service – The timer service provides applications, drivers,

and a simple mechanism to control general-purpose, core, and
watchdog timers of the Blackfin processor. The timer service allows
the application to:

• Configure and control any timer within the processor,
including general-purpose, core, and watchdog timers.

• Install callbacks, including both “live” and deferred
callbacks, when timers expire or trigger.

• Port Control Service – (available only on the ADSP-BF534,

ADSP-BF536, and ADSP-BF537 processors) The port control
service configures the pin muxing hardware appropriately to ensure
proper operation of the peripherals that share common input and
output pins. All system services and device drivers automatically
make the appropriate calls into the port control service to seam
lessly configure the pin muxing hardware without any end-user or
application interaction, other than initialization of the service.

-

1-6 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

• Device Manager – The device driver model is used to control

devices, both internal and external to Analog Devices processors.
Specific functionality allow the application to:

• Open and close devices used by the application.

• Configure and control devices.

• Receive and transmit data through the devices using a vari­ety of dataflow methods.

Application Interface

Each system service exports an application programming interface (API)
that defines the interface into that service. Application software makes
calls into the API of the system service to access the functionality that is to
be controlled.

Each API can be called using the standard calling interface of the
development toolset’s C run-time model. The API of each service can be
called by any C or assembly language program that adheres to the calling
conventions and register usage of the C run-time model.

In addition to the application software using the API to make calls into a
system service, some system services make calls into the API of other sys­tem services. For the most part, each service is independent of the other
services; however, redundancies are eliminated by allowing one service to
access the functionality of another service.

For example, does the application need to be notified when a DMA
descriptor has completed processing, and the application has requested
deferred callbacks? In this case, the DMA management service invokes the
deferred callback service to effect the callback into the application.

Another example of combined operation between services involves the
power management and EBIU services. Assume that the system has
SDRAM and the application needs to conserve power by turning down

VisualDSP++ 5.0 Device Drivers and System 1-7
Services Manual for Blackfin Processors

System Services Overview

Port Control

Deferred Callback

DMA Manager

Interrupt Manager

Dynamic Power

EBIU (SDRAM)

Flag Control Timer Control

the core and system clock frequencies. When the application calls the
power management service to lower the operating frequencies, the power
management service automatically invokes the EBIU service, which
adjusts the SDRAM refresh rate to compensate for the reduced system
clock frequency.

Figure 1-1 illustrates the current collection of system services and the API

interactions among them.

Figure 1-1. System Services and API Interactions

Dependencies

With few constraints, applications can use any individual service

combination of services within their application. Applications do not

or
have to all the services. Further, each service does not need all the
resources associated with the system that the service is controlling.

1-8 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

For example, the DMA manager does not need control over all DMA
channels. The system can be configured for the DMA manager to control
some channels, leaving the application or other software to control other
DMA channels. (See the individual service chapters for more information
on each service.) There are, however, dependencies within the services of
which the application developer should be aware.

All current services, except the EBIU service, invoke the interrupt control
service for the management of interrupt processing. The DMA manager,
deferred callback, and power management services each depend on the
interrupt control service to manage interrupt processing for them.

If directed by the application to adjust SDRAM timing automatically, the
power management service uses the EBIU control service to affect
SDRAM timing parameter changes when the power/operating speed
profile of the processor is changed.

When configured to use deferred callbacks (as opposed to live or
interrupt-time callbacks) the DMA manager leverages the capabilities of
the deferred callback service to provide deferred callbacks to the applica­tion. However, when configured for live callbacks, the DMA manager
does not use the deferred callback service.

The development toolset automatically determines these dependencies
and links into the executable only those services that are required by the
application. Because each service is built as its own object file within the
system services library file, you can further reduce the code size of the final
executable by commanding the linker to eliminate unused objects. Refer
to the development toolset documentation for more information.

VisualDSP++ 5.0 Device Drivers and System 1-9
Services Manual for Blackfin Processors

System Services Overview

Initialization

Some system services rely on other system services; thus, there is a
preferred initialization sequence. Usually it is preferable to initialize all
services at one time, typically when the whole system is being initialized,
rather than spreading out the initialization of various services at different
times.

Most applications find the initialization sequence listed below to be opti­mal. Any service in the sequence that is not used by the application can
simply be omitted from the sequence.

1. Interrupt control service

2. External bus interface unit

3. Power management service

4. Port control (ADSP-BF534/536/537 processors only)

5. Deferred callback service

6. DMA manager service

7. Programmable flag service

8. Timer service

Termination

Many embedded systems operate continuously in an endless loop and may
never need to call the termination function of a service. Applications that
do not have a need to terminate a service can save memory by never calling
the termination function.

For applications that need to terminate services, as with the initialization
sequence, there is a preferred sequence of terminating the services.

1-10 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

Most application find the termination sequence listed below to be opti­mal. Any service in the sequence that is not used by the application can
simply be omitted from the sequence.

1. Timer service

2. Programmable flag service

3. DMA manager service

4. Deferred callback service

5. Port control (ADSP-BF534/536/537 processors only)

6. Power management service

7. External bus interface unit

8. Interrupt control service

System Services Directory and File Structure

All files for the system services are contained within the Blackfin
directory tree. In VisualDSP++ installations, this directory is used for core
development tools. Other development toolsets may use other directory
names for their toolkits, but the system services can always be found
within the

To use the system services, applications need only include a single include
file in their source code, and link with a single system services library
module that is appropriate for their configuration.

Accessing the System Services API

Blackfin directory tree.

Applications using system services should include the

Blackfin/include/services directory in the (compiler and/or assembler)

preprocessor search path. User source files that access any of the system

VisualDSP++ 5.0 Device Drivers and System 1-11
Services Manual for Blackfin Processors

System Services Overview

services APIs should simply include the services.h file, located in the

Blackfin/include/services directory. User files do not need to include

any other files to use the system services API.

The system services API and functionality are uniform and consistent
across all Blackfin processors, including all single- and multi-core devices.
Application software does not have to change, regardless of the Blackfin
processor is being targeted. For example, application software running on
a single-core ADSP-BF533 processor can operate unchanged on a
multi-core ADSP-BF561 processor.

In order to provide this consistent API to the application, the system
services API must be aware of the specific processor variant being targeted.
You must ensure that the processor definition macro for the processor
variant being targeted is defined when including the services.h include
file.

The VisualDSP++ toolset automatically sets the processor definition
macro when building projects. Application developers using the
VisualDSP++ toolset need do nothing further to ensure the processor
definition macro is defined.

Application developers using other toolsets, however, should ensure the
processor definition macro is appropriately defined. The services.h file
enumerates the specific processor variants that are supported. These
processor variants include:

__ADSPBF531__ The ADSP-BF531 processor

__ADSPBF532__ The ADSP-BF532 processor

__ADSPBF533__ The ADSP-BF533 processor

__ADSPBF534__ The ADSP-BF534 processor

__ADSPBF535__ The ADSP-BF535 processor

__ADSPBF536__ The ADSP-BF536 processor

__ADSPBF537__ The ADSP-BF537 processor

1-12 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

__ADSPBF538__ The ADSP-BF538 processor

__ADSPBF539__ The ADSP-BF539 processor

__ADSPBF561__ The ADSP-BF561 processor

The services.h file contains the full and complete list of processor vari­ants that are supported.

Although the API of the system services does not change between

L

processor variants, the internals of the system services differ,
depending on the specific processor variant and processor revision
number being targeted. For example, the number of DMA
channels for a ADSP-BF533 processor differs from the number of
DMA channels for a ADSP-BF561 processor. Further, a
workaround within the services for revision x.y of a processor may
not be needed for revision x.y of that same processor. These differ­ences are accounted for in the system service library module. See

“System Services Overview” for more information.

Linking in the System Services Library

All object code for the system services is included in the system services
library file. This file is found in the Blackfin/lib directory. This direc­tory provides a system services library file for each processor variant and
processor revision that is supported. You should ensure that the appropri­ate library is included in the list of object files for the linker.

VisualDSP++ 5.0 Device Drivers and System 1-13
Services Manual for Blackfin Processors

System Services Overview

All system service library files are of the form libsslxxx_yyyz.dlb where:

• xxx represents the processor variant – This is typically a three-digit
number that identifies the processor variant, such as 532 for the
ADSP-BF532 processor, 534 for the ADSP-BF534 processor, and
so on.

• _yyy represents the operating environment – This suffix represents
the targeted operating environment, such as vdk for VDK-based
systems, uCOS for uCOS-based systems, and so on. Libraries built
for standalone, specifically non-RTOS environments, do not
include the _yyy suffix.

• z represents any special conditions for the library – The following
combinations are used:

• y – The library is built to avoid all known anomalies for all
revisions of silicon.

• blank – A library without any additional suffix does not
contain workarounds to any anomalies.

Located within the Blackfin/lib directory are subdirectories for
individual silicon revisions. The libraries in these subdirectories are
built for specific silicon revisions of the Blackfin processors.

One system services library file only should be included for the linker to
process. Choose the correct library based on the processor variant,
operating environment, and processor revision number for your system.

For example, an application targeting silicon revision 0.2 of the
ADSP-BF532 processor without an RTOS should link with the

libss1532.dlb file from the Blackfin/lib/bf532_rev_0.2 subdirectory.

As another example, an application developer who wants a version of the

1-14 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

system services library to run on any revision of ADSP-BF532 silicon and
uses the VDK, should link with the libss1532_vdky.dlb file from the

Blackfin/lib directory.

It is strongly recommended you use the debug versions of the

L

Specify the use of debug versions of the libraries by selecting Use Debug
System libraries on the Link:Processor page of the Project Options dialog

box.

Rebuilding the System Services Library

system services library during development because the built-in
error-checking code within the library can save countless hours of
development time.

Under normal situations, there is no need to rebuild the system services
library. However, to accommodate unforeseen circumstances and provide
developers with the ability to tailor the system services to their particular
needs, all source code and include files necessary to rebuild the system
services library are provided. In addition, VisualDSP++ project files are
included for application developers using the VisualDSP++ development
toolset.

All code for the system services library is located in the following
directories:

• Blackfin/lib – This directory contains the Analog Devices built
versions of the system service library files (

• Blackfin/lib/src/services – This directory contains all the
source code files and non-API include files for the system services.
This directory also contains the VisualDSP++ project files that can
be used to rebuild the libraries.

*.dlb).

• Blackfin/include/services – This directory contains all API
include files for the system services.

VisualDSP++ 5.0 Device Drivers and System 1-15
Services Manual for Blackfin Processors

System Services Overview

VisualDSP++ users can simply rebuild the system services library by using
the build command after opening the appropriate VisualDSP++ project
file.

To rebuild the libraries using other development toolsets:

1. Set the preprocessor include path to include

Blackfin/include/services and blackfin/lib/src/services.

2. Define the processor variant according to the definitions in the

services.h file.

3. Define the silicon revision macro, __SILICON_REVISION__, to the
proper value. Refer to the description of the _si_revision switch
in your processor’s C/C++ Compiler and Library manual for more
information.

4. Compile/assemble all files in the Blackfin/lib/src/services
directory.

5. Link the appropriate compiled/assembled objects into a library.
Include all object files without any operating environment exten­sion (such as VDK) and all object files with the appropriate operating
environment extension specific for the environment being targeted
(such as VDK).

Examples

The system services distribution includes many examples that illustrate
how to use the system services. Refer to these examples for additional
information on how to use the system services effectively.

Dual-Core Considerations

For information on how to use the system services on dual-core
ADSP-BF561 processors, see

“Dual-Core Considerations” on page 3-5.

1-16 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

RTOS Considerations

Deployment of system services and the device driver model within an
application based around an RTOS, such as VDK, is highly recom­mended. However, observe these considerations to avoid conflict with the
RTOS and to successfully deploy the system services and device drivers
within a multi-threaded application.

The following discussion, which is limited to VDK, is also relevant

L

Interoperability of System Services With VDK

to other RTOS environments.

There are three major considerations to keep in mind when deploying sys­tem services and the device driver model within a VDK-based application.

• Interrupt handling – The interrupt manager is a cornerstone of the
system services and the device driver model. The interrupt manager
is designed to manage only the interrupt vector groups (IVG) that
it is requested to manage, as dictated by each call to

adi_int_CECHook(), leaving the other IVG levels to be handled as

per the user’s requirements. Thus, VDK-managed interrupts can
easily coexist alongside those managed by system services, provided
that neither method manages the same IVG levels as the other. It is
not possible to have a VDK ISR and an interrupt manager chain
assigned to the same IVG level, as one will overwrite the other in
the event vector table (EVT).

All DMA channels and device drivers use the default IVG levels as
defined in the
(that is, during the call to adi_dev_Open()).

SIC_IARx registers at the time of device initialization

• Prohibited interrupt levels – Appendix A of the VisualDSP++ 5.0
Kernel (VDK) User’s Guide details four interrupt levels [EVT3

(EVX), EVT6 (IVTMR), IVG14, and IVG15] which are reserved

VisualDSP++ 5.0 Device Drivers and System 1-17
Services Manual for Blackfin Processors

RTOS Considerations

for exclusive use by VDK and must not be managed by the inter­rupt manager. IVG15 is also excluded from most VisualDSP++
applications as it is used to run the applications in supervisor
mode.

• Deferred callbacks – The deferred callback manager offers a simi­lar service to the VDK process running at IVG14. It is highly
recommended that the VDK variant of the system services library is
used (and indeed the default VDK .ldf files ensure its use). This
variant essentially passes callbacks posted to the DCB manager to
the VDK level 14 process. In this mode of operation, only one call­back queue can be used. If the standalone library variant is used,
several queues can be managed but none of them can be assigned to
the IVG 14 level as this would conflict with the VDK process run­ning at that level.

Deployment of Services Within a Multi-Threaded
Application

Bear in mind these two major considerations when deploying system ser­vices and the device driver model within a multi-threaded application.

• Critical regions – System services and device drivers use critical
regions where atomicity of a code segment is required. These
regions are managed through calls to the

adi_int_EnterCriticalRegion function and the
adi_int_ExitCriticalRegion function, which are defined in the
adi_int_xxx.c files within the installation. (For more information,

see “Interrupt Manager” on page 2-1.) It is advised that the above

functions are used within threads that use system services rather
than the VDK push/pop critical region functions.

• Initialization – Initialization of system services and the device
manager is performed only once per application. Since their use
may be required in several threads, it is important that the

1-18 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

initialization is performed prior to any subsequent use. In addition,
all device drivers that need to adjust their timing values according
to the peripheral clock (SCLK) frequency must employ a call to

adi_pwr_GetFreq() to determine the frequency (in Hz). The power

management module must be initialized prior to the opening of
any device driver.

There are basically three approaches that can be adopted:

• Define a function to initialize the system services and device
manager and call it from a user-modifiable section of the
“start” routine in <Project>_basiccrt.s.

• Assign the initialization to the highest-priority boot thread.

• Use a separate boot thread to perform the initialization and
set it at the highest priority and let it yield to other threads
once completed or be destroyed. Use global and not thread
memory to initialize the system services and device manager
in this way.

Device Driver Overview

Device drivers provide a mechanism for applications to control a device
effectively. Devices may be on-chip or off-chip hardware devices, or even
software modules that are best managed as virtual devices. Device drivers
are typically constructed such that the application is insulated from the
nuances of the hardware (or software) being controlled. In this way, both
the device drivers and the devices that are being controlled can be updated
or replaced without affecting the application.

The Analog Devices device driver model provides a simple, convenient
method for applications to control devices commonly found in and
around Analog Devices processors. It has also provides a simple and effi­cient mechanism for the creation of new device drivers.

VisualDSP++ 5.0 Device Drivers and System 1-19
Services Manual for Blackfin Processors

Device Driver Overview

The system services overview covers the following topics:

• “Application Interface” on page 1-20

• “Device Driver Architecture” on page 1-21

• “Initialization” on page 1-23

• “Termination” on page 1-24

• “Device Driver Directory and File Structure” on page 1-24

Application Interface

The device driver model provides a consistent, simple, and familiar appli­cation programming interface (API) for device drivers. All devices drivers
that conform to the model use the same simple interface into the driver.

Most devices receive and/or transmit data, sometimes transforming the
data in the process. This data is encapsulated in a buffer. The buffer may
contain small bits of data, such as for a UART-type device that processes
one character at a time, or large pieces of data, such as a video device that
processes NTSC frames of approximately 1 MB in size. Applications typi­cally provide the buffers to the device, though it is possible for devices to
pass buffers from one device to another without any application
involvement.

The actual API is a model-compliant driver that consists of the following
basic functions:

• adi_dev_Open() – Opens a device for use.

• adi_dev_Close() – Closes down a device.

• adi_dev_Read() – Provides a device with buffers for inbound data.

1-20 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

• adi_dev_Write() – Provides a device with buffers for outbound
data.

• adi_dev_Control() – Sets/detects control and status parameters for
a device.

Similar to the system service APIs, the device driver API is designed to be
called using the standard calling interface of the development toolset’s C
run-time model. The device driver API can be called by any C or assembly
language program that adheres to the calling conventions and register
usage of the C run-time model.

Device Driver Architecture

The device driver model separates the functionality of device drivers into
two main components: the device manager and the physical drivers.

The device manager is a software component that provides much of the
functionality common to the vast majority of device drivers. For example,
depending on how the application wants the device driver to operate, the
application may command a device driver to operate in synchronous mode
or asynchronous mode.

In synchronous mode, when the application calls the adi_dev_Read() or

adi_dev_Write() API function to read data from or send data to the

device, the API function does not return to the application until the oper
ation has completed. In asynchronous mode, the API function returns
immediately to the application, while the data is moved in the back­ground. It would be wasteful to force each physical driver to provide logic
that operates both synchronously and asynchronously. The device man

­ager provides this functionality, relieving each physical driver from
reimplementing this capability.

-

VisualDSP++ 5.0 Device Drivers and System 1-21
Services Manual for Blackfin Processors

Device Driver Overview

APPLICATION

DEVICE MANAGER

RTOS (OPTIONAL)

DEVICE
DRIVER

COMPONENTS

PHYSICAL

DRIVER

PHYSICAL

DRIVER

PHYSICAL

DRIVER

SYSTEM SERVICES

The device manager architecture is illustrated in Figure 1-2.

1-22 VisualDSP++ 5.0 Device Drivers and System

Figure 1-2. Device Manager Architecture

The device manager also provides the API to the application for each
device driver. This ensures that the application has the same consistent
interface regardless of the peculiarities of each device.

While there is only one device manager in a system, there can be any num­ber of physical drivers in a system. A physical driver is that component of a
device driver that accesses and controls the physical device. The physical
driver is responsible for all the “bit banging” and control and status regis­ter manipulations of the physical device. All device-specific information is
contained and isolated in the physical driver.

Services Manual for Blackfin Processors

Introduction

Interaction With System Services

As shown in Figure 1-2, the device driver model leverages the capabilities
of the system services. Each software component in the system (whether it
is the application, RTOS (if present), the device manager, or each physical
driver) can access and call into the system services API.

The benefits of using this approach are enormous. In addition to code size
and data memory savings, this approach provides each software compo­nent with access to the resources of the system and processor in a
cooperative manner. Further, the amount of development effort for physi­cal drivers is substantially reduced because each driver does not have to
reimplement any of the functionality provided by the device manager or
system services.

Initialization

Prior to accessing any individual driver, the device manager must first be
initialized. The initialization function, adi_dev_Init(), is called by the
application to set up and initialize the device manager.

Though the device driver model is dependent upon system services, the
initialization function of the device manager does not rely on any of the
system services. As such, the current revision of the device manager can be
initialized before or after the system services initialization.

However, future versions of the device manager initialization function
may require some of the system services capabilities. As such, it is good
practice to initialize the required system services prior to initializing the
device manager. Refer to the “Initialization” on page 1-10 for information
on system services initialization.

VisualDSP++ 5.0 Device Drivers and System 1-23
Services Manual for Blackfin Processors

Device Driver Overview

Termination

The API of the device driver model includes a termination function that
may be called by the application if the device drivers are no longer
required. The termination function, adi_dev_Terminate(), is called to
free up the resources used by the device manager and any open physical
drivers. Many embedded systems run in an endless operating loop and
never call the termination function of the device manager. An application
that operates in an endless loop can save program memory by not calling
the terminate function.

As part of the termination function processing, the device manager closes
all open physical drivers. The physical drivers are closed in an abrupt man­ner. If a more graceful shutdown is needed, the application may prefer to
close any open physical drivers first, and then call the termination
function.

Note that because of the reliance on the system services, the termination
function of the device manager should be called prior to any termination
functions of the system services. This ensures that the system services can
be called by the device manager and/or physical drivers as part of their
shutdown procedure.

After the device manager has been terminated, it must be reinitialized
before any of its functionality can be accessed again.

Device Driver Directory and File Structure

All files for the device driver model are contained within the Blackfin
directory tree. In VisualDSP++ installations, this is the directory that
stores the core development tools. Other development toolsets may use
other directory names for their toolkits, but the device driver files can
always be found within the

Blackfin directory tree.

1-24 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

To use the device drivers, applications need only to use include files in
their source code, and link with a device driver library and a system ser­vices library module.

Accessing the Device Driver API

User source files accessing the device manager API should include the files

services.h and adi_dev.h, located in the Blackfin/include/services

and Blackfin/include/drivers directories, respectively. In addition, your
source file should use the include file of the physical driver that will be
accessed.

For example, user code that accesses the Analog Devices parallel peripheral
interface (PPI) driver would include the following lines in their source file
(in order):

#include <services/services.h> // system services
#include <drivers/adi_dev.h> // device manager
#include <drivers/ppi/adi_ppi.h> // PPI physical driver

The device driver API and functionality is uniform and consistent across
all Blackfin processors, including all single- and multi-core devices.
Regardless of the Blackfin processor being targeted, application software
does not change. For example, application software running on a sin­gle-core ADSP-BF533 processor can operate unchanged on a multi-core
ADSP-BF561 processor.

In order to provide this consistent API to the application, the system ser­vices, device manager, and physical drivers need to be aware of the specific
processor variant being targeted. You must ensure that the processor defi­nition macro for the processor variant being targeted is defined when
including the system services (

services.h), device manager (adi_dev.h),

and physical driver include files.

VisualDSP++ 5.0 Device Drivers and System 1-25
Services Manual for Blackfin Processors

Device Driver Overview

The VisualDSP++ toolset automatically sets the processor definition
macro when building projects. Application developers using the
VisualDSP++ toolset need do nothing further to ensure the processor def­inition macro is defined.

Application developers using other toolsets, however, should ensure that
the processor definition macro is appropriately defined. The services.h
file enumerates the specific processor variants that are supported. These
processor variants include:

__ADSPBF531__ The ADSP-BF531 processor

__ADSPBF532__ The ADSP-BF532 processor

__ADSPBF533__ The ADSP-BF533 processor

__ADSPBF534__ The ADSP-BF534 processor

__ADSPBF535__ The ADSP-BF535 processor

__ADSPBF536__ The ADSP-BF536 processor

__ADSPBF537__ The ADSP-BF537 processor

__ADSPBF538__ The ADSP-BF538 processor

__ADSPBF539__ The ADSP-BF539 processor

__ADSPBF561__ The ADSP-BF561 processor

The services.h file contains the full and complete list of processor vari­ants that are supported by the system services. The adi_dev.h file contains
the list of processor families that are supported by the device driver model.

1-26 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

Device Driver File Locations

Device drivers for on-chip peripherals are provided in the libdrvxxx.dlb
library for the various processor derivatives, silicon revisions, and so on.
Device drivers for off-chip peripherals are not provided within the library,
but rather must be included separately with the application. Include files
for off-chip peripheral drivers are included in following subdirectories:

$ADI_DSP\Blackfin\include\drivers

where $ADI_DSP is the location of your VisualDSP installation, which is,
by default, located at:

C:\Program Files\Analog Devices\VisualDSP <version>

Source files for off-chip peripheral drivers are included in subdirectories:

$ADI_DSP\Blackfin\lib\src\drivers

When creating applications that include off-chip device drivers, the appli­cation should include the .h file for the driver. This is typically done with
something like this:

#include <drivers\codec\adi_ad1836.h>

The source code for an off-chip peripheral driver should be included in
the source file list of the VisualDSP++ project. For example, if using the
AD1836 device driver, the file

$ADI_DSP\Blackfin\lib\src\drivers\codec\adi_ad1836.c

should be included in the source file list.

VisualDSP++ 5.0 Device Drivers and System 1-27
Services Manual for Blackfin Processors

Device Driver Overview

Linking in the Device Driver Library

All object code for the device manager and Analog Devices-supplied phys­ical drivers is included in the device driver library file. This file is found in
the Blackfin/lib directory. In this directory is a device driver library file
for each supported processor variant. You should ensure that the appropri­ate library is included in the list of object files for the linker.

The device driver library file is of the form libdrvxxxz.dlb where:

• xxx represents the processor variant – This is typically a three-digit

number that identifies the processor variant, such as 532 for the
ADSP-BF532 processor, 534 for the ADSP-BF534 processor, and
so on.

• z represents any special conditions for the library – The following

combinations are used:

• y – The library is built to avoid all known anomalies for all
revisions of silicon.

• blank – A library without an additional suffix does not con­tain workarounds to any anomalies.

Located within the Blackfin/library directory are subdirectories for
individual silicon revisions. The libraries in these subdirectories are built
for specific silicon revisions of the processors.

One device driver library file should be included for the linker to process.
Choose the correct library based on the processor variant for your system.

For example, an application developer targeting silicon revision 0.2 of the
ADSP-BF532 processor should link with the

Blackfin/lib/bf532_rev_0.2 subdirectory. As another example, the

libdrv532.dlb file from the

1-28 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Introduction

application developer who wants a version of the device driver library that
will run on any revision of ADSP-BF532 silicon should link with the

libdrv532y.dlb file from the Blackfin/lib directory.

It is strongly recommended that you use the debug versions of the

L

Specify the use of debug versions of the libraries by selecting Use Debug
System libraries on the Link:Processor page of the Project Options dialog

box.

Rebuilding the Device Driver Library

device driver library during development, because built-in,
error-checking code within the library can save countless hours of
development time.

Under normal situations, there is no need to rebuild the device driver
library. However, to accommodate unforeseen circumstances and provide
the ability to tailor the implementation to a user’s particular needs, all
source code and include files necessary to rebuild the device driver library
are provided. In addition, VisualDSP++ project files are included for
application developers who use the VisualDSP++ development toolset.

All code for the device driver library is located in the following directories:

• Blackfin/lib – This directory contains the Analog Devices-built
versions of the device driver library files (

• Blackfin/lib/src/drivers – This directory contains all the source
code files and non-API include files for the device manager and
Analog Devices-provided physical drivers. Also in this directory are
VisualDSP++ project files that can be used to rebuild the libraries.

• Blackfin/include/drivers – This directory contains the device
manager API include file and the include files for all Analog
Devices-provided physical drivers.

*.dlb).

VisualDSP++ 5.0 Device Drivers and System 1-29
Services Manual for Blackfin Processors

Device Driver Overview

VisualDSP++ users can rebuild the device driver library by using the build
command after opening the appropriate VisualDSP++ project file.

To rebuild the libraries using other development toolsets:

1. Set the preprocessor include path to include

Blackfin/include/drivers and Blackfin/lib/src/drivers.

2. Define the processor variant according to the definitions in the

services.h file.

3. Define the silicon revision macro, __SILICON_REVISION__, to the
proper value. Refer to the compiler’s -si-revision switch for more
information.

4. Compile/assemble all files in the Blackfin/lib/src/drivers
directory.

5. Link the appropriate compiled/assembled objects including all
object files into a library.

Examples on Distribution

The device driver distribution includes examples that illustrate how to use
the device drivers. Refer to these examples for additional information on
how to use the device drivers effectively.

1-30 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

2 INTERRUPT MANAGER

This chapter describes the interrupt manager that controls and manages
the interrupt and event operations of the Blackfin processor.

This chapter contains:

• “Introduction” on page 2-2

• “Interrupt Manager Initialization” on page 2-4

• “Interrupt Manager Termination” on page 2-5

• “Core Event Controller Functions” on page 2-6

• “System Interrupt Controller Functions” on page 2-9

• “Protecting Critical Code Regions” on page 2-12

• “Modifying IMASK” on page 2-14

• “Examples” on page 2-15

• “File Structure” on page 2-16

• “Interrupt Manager API Reference” on page 2-17

VisualDSP++ 5.0 Device Drivers and System 2-1
Services Manual for Blackfin Processors

Introduction

Introduction

The Blackfin processor employs a two-tiered mechanism for controlling
interrupts and events. System-level interrupts are controlled by the system
interrupt controller (SIC). All peripheral interrupt signals are routed
through the system interrupt controller and then, depending on the set­tings of the system interrupt controller, routed to the core event controller
(CEC). The core event controller processes these events and, depending
on the settings of the core event controller, vectors the processor to handle
the events.

The interrupt manager provides functions that allow the application to
control every aspect of the system interrupt controller and the core event
controller. It does this so that events and interrupts are handled and pro­cessed in an efficient, yet cooperative, manner.

The Blackfin processor provides 16 levels of interrupt and events. These
levels, called interrupt vector groups (IVG), are numbered from 0 to 15,
with the lowest number having the highest priority. Some IVG levels are
dedicated to certain events, such as emulation, reset, non-maskable inter-
rupt (NMI, and so on. Other IVG levels, specifically levels 7 through 15,
are considered general-purpose events and are typically used for system­level (peripheral) interrupts or software interrupts.

All IVG processing is performed in the CEC. When a specific IVG is trig­gered, assuming the event is enabled, the CEC looks up the appropriate
entry in the event vector table and vectors execution to the address in the
table where the event is processed.

All system or peripheral interrupts are first routed through the SIC.
Assuming the SIC has been programmed, peripheral interrupts are then
routed to the CEC for processing. The SIC provides a rich set of function
ality for the processing and handling of peripheral interrupts. In addition
to allowing/disallowing peripheral interrupts to be routed to the CEC, the

-

2-2 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

SIC allows peripheral interrupts to be mapped to any of the CEC’s
general-purpose IVG levels and controls whether these interrupts wake the
processor from an idled operating mode.

In systems that employ Blackfin processors, often there are more potential
interrupt sources than IVG levels. As stated above, some events (such as
NMI) map one-to-one to an IVG level. Other events, typically infrequent
interrupts such as peripheral error interrupts, are often “ganged” in a sin­gle IVG level.

The interrupt manager allows the application to execute complete control
over how interrupts are handled, whether they are masked or unmasked,
whether they mapped one-to-one or ganged together, whether the proces­sor should be awakened to service an interrupt, and so on. The interrupt
manager also allows the creation of interrupt handler chains. An interrupt
handler is a C-callable function that is provided by the application to pro­cess an interrupt. Through the interrupt manager, the application can
hook in any number of interrupt handlers for any IVG level. When
multiple events are ganged to a single IVG level, this allows each handler
to be designed independently from any other and allows the application to
process these interrupts in a straightforward manner.

Further, the interrupt manager processes only those IVG levels and system
interrupts that the application directs the interrupt manager to control.
This allows the application developer to have complete unfettered access
to any IVG level or system interrupt to manually control interrupts.

Multi-core Blackfin processors extend this capability by including one sys­tem interrupt controller and one core event controller for each core. This
provides maximum flexibility by allowing application developers to decide
how to map interrupts to individual cores, multiple cores, and so on.
When using multi-core Blackfin processors, typically one interrupt man­ager for each core is used. Because there is no reason to provide multiple
interrupt managers on single-core devices, this service is not supported.
Application developers should not attempt to instantiate more than one
interrupt manager per core.

VisualDSP++ 5.0 Device Drivers and System 2-3
Services Manual for Blackfin Processors

Interrupt Manager Initialization

Following the convention of all the system services, the interrupt manager
uses a unique and unambiguous naming convention to guard against con­flicts. All enumeration values, typedef statements and macros use the

ADI_INT_ prefix, while all functions within the interrupt manager use the
adi_int_ prefix.

All interrupt manager API functions return the ADI_INT_RESULT return
code. See the adi_int.h file for the list of return codes. Like all system
services, the return code that signals successful completion,

ADI_INT_RESULT_SUCCESS for the interrupt manager, is defined to be 0.

This allows applications to quickly and easily determine whether any
errors occurred in processing.

Interrupt Manager Initialization

To use the interrupt manager, a function must initialize the interrupt
manager. The function that initializes the interrupt manager is called

adi_int_Init. The application that calls adi_int_Init passes an argu-

ment defining the memory that the interrupt manager uses when
operating.

The amount of memory provided depends on the number of secondary
handlers used by the application. When using interrupt handler chaining,
the interrupt manager considers the first interrupt handler that is hooked
into an IVG level to be the primary interrupt handler. Any additional
interrupt handlers that hooked into that same IVG level are considered
secondary handlers. Without any additional memory from the applica­tion, the interrupt manager can support one primary interrupt handler for
each IVG level. If the application never has more than one interrupt han­dler on each IVG level (that is, only the primary interrupt handler and no
secondary handlers are present), the application does not need to provide
memory to the interrupt manager’s initialization function. However, if the
application hooks in secondary interrupt handlers, the application must
provide additional memory to support the secondary handlers.

2-4 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

The ADI_INT_SECONDARY_MEMORY macro is defined to be the amount of
memory (in bytes) required to support a single secondary handler. Thus,
the application should provide to the initialization function “n” times

ADI_INT_SECONDARY_MEMORY, where “n” is the number of secondary

handlers that are supported.

Another parameter passed to the initialization function is the parameter
that the interrupt manager passes to the adi_int_EnterCriticalRegion()
function. This value depends upon the operating environment of the
application. See the adi_int_EnterCriticalRegion function for more
information.

When called, the initialization function initializes its internal data struc­tures and returns. No changes are made to the CEC or SIC during
initialization. After initialization, any other interrupt manager API
functions may be called.

Interrupt Manager Termination

When the functionality of the interrupt manager is no longer required, the
application can call the termination function of the interrupt manager,

adi_int_Terminate(). Many applications operate in an endless loop and

never call the termination function.

When called, the termination function unhooks all interrupt handlers,
masking off (disabling) all interrupts the that the interrupt manager was
controlling. After calling the termination function, any memory provided
to the initialization function may be reused by the application. No other
interrupt manager functions can be called after termination. If interrupt
manager services are required after the termination function is called, the
application must reinitialize interrupt manager services by calling the

adi_pwr_Init function.

VisualDSP++ 5.0 Device Drivers and System 2-5
Services Manual for Blackfin Processors

Core Event Controller Functions

Core Event Controller Functions

Only two functions are necessary to provide complete control over the
core event controller (CEC): adi_int_CECHook() and

adi_int_CECUnhook(), as described next.

adi_int_CECHook() Function

The adi_int_CECHook() function is used to hook an interrupt handler
into the handler chain for an IVG level. When called, the application
passes in the IVG number to be handled, the address of the handler func­tion, a parameter that the interrupt manager automatically passes back to
the interrupt handler when the interrupt handler is invoked, and a flag
indicating whether interrupt nesting should be enabled for this IVG level.

The handler function itself is a simple C-callable function that conforms
to the ADI_INT_HANDLER_FN typedef. The interrupt handler is not an
interrupt service routine (ISR) but a standard C-callable function. When
the IVG level triggers it, the interrupt manager calls the interrupt handler
to process the event. The interrupt manager passes the client argument
that was passed to the interrupt manager via the adi_int_CECHook()
function to the interrupt handler. The interrupt handler takes whatever
action is necessary to process the interrupt, then returns with either the

ADI_INT_RESULT_PROCESSED or ADI_INT_RESULT_NOT_PROCESSED return

code.

Interrupt handlers should be written such that they interrogate the system
quickly when determining whether the event that triggered the interrupt
should be processed by the interrupt handler. If the event that caused the
interrupt is not the event the interrupt handler was expecting, it should
immediately return with the

ADI_INT_RESULT_NOT_PROCESSED return code.

The interrupt manager then automatically invokes the next interrupt han
dler, if any, that is hooked into the same IVG level. If the event that

-

2-6 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

caused the interrupt is expected by the interrupt handler, the interrupt
handler performs whatever processing is necessary and should return the

ADI_INT_RESULT_PROCESSED return code.

The nesting flag parameter is of significance only when the first interrupt
handler is hooked into an IVG chain. The first interrupt handler that
hooks into an IVG chain is called the primary handler. Any additional
handlers that are hooked into that same IVG chain are called secondary
handlers. When the primary handler is hooked into the chain, the inter­rupt manager loads an ISR into the appropriate entry of the event vector
table (EVT). If the nesting flag is set, the ISR that the interrupt manager
loads is one that supports interrupt nesting. If the nesting flag is clear, the
ISR that the interrupt manager loads is one that does not support inter­rupt nesting. When secondary handlers are hooked into an IVG chain, the
nesting flag is ignored.

Lastly, the adi_int_CECHook() function unmasks the appropriate bit in
the CEC’s IMASK register, thereby enabling the interrupt to be processed.

In most applications, users take great care to optimize the processing that
occurs for the highest frequency and highest urgency interrupts. Typically,
the highest frequency or highest urgency interrupts are assigned their own
IVG level, and less frequent or lower urgency interrupts (such as error
processing) are ganged together on a single IVG level.

The interrupt manager continues that thinking and has been optimized to
allow extremely efficient processing for primary interrupt handlers.
Though still efficient, secondary handlers are called after the primary han­dler. Secondary handlers are hooked into the IVG chain in a stacked or
last-in, first-out (LIFO) fashion. This means that when an event is trig­gered, after calling the primary handler (and assuming the primary
handler did not return the

ADI_INT_RESULT_PROCESSED return code), the

interrupt manager calls the last secondary handler that was hooked,
followed by the second to last installed handler, and so on.

VisualDSP++ 5.0 Device Drivers and System 2-7
Services Manual for Blackfin Processors

Core Event Controller Functions

To ensure optimal performance, the application developer should manage
which interrupt handlers are hooked as primaries and which are hooked as
secondary handlers.

adi_int_CECUnhook() Function

The adi_int_CECUnhook() function is used to unhook an interrupt
handler from the interrupt handler chain for a particular IVG level. When
called, the application passes in the IVG number and the address of the
interrupt handler function to be unhooked from the chain.

The function removes the interrupt handler from the chain of handlers for
the given IVG level. If the primary handler is being removed, the last sec­ondary handler that was hooked becomes the new primary handler. If,
after removing the given interrupt handler, no interrupt handlers are left
in the IVG chain, the adi_int_CECUnhook() function masks the
appropriate bit in the CEC’s IMASK register, thereby disabling the
interrupt.

Interrupt Handlers

Since the interrupt handlers registered with the interrupt manager are
invoked from within the built-in IVG interrupt service routine (and there
may be several interrupts pending for the same IVG level), individual
interrupt handlers must not invoke the
Instead, they should return using the
handlers are in fact nothing more than typical C-callable subroutines.

Therrefore, each peripheral interrupt handler must conform to the
following template,

ADI_INT_HANDLER(mjk_SPORT_RX_handler)
{

... ... // user code

}

RTI instruction on completion.

RTS return function. Interrupt

2-8 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

where the ADI_INT_HANDLER macro is defined as

#define ADI_INT_HANDLER(NAME) \

void (*NAME)(void *ClientArg)

System Interrupt Controller Functions

The following functions are provided to give the application complete
control over the system interrupt controller:

• adi_int_SICEnable – Enables peripheral interrupts to be passed to
the CEC.

• adi_int_SICDisable – Disables peripheral interrupts from being
passed to the CEC.

• adi_int_SICSetIVG – Sets the IVG level to which a peripheral
interrupt is mapped.

• adi_int_SICGetIVG – Detects the IVG level to which a peripheral
interrupt is mapped.

• adi_int_SICWakeup – Establishes whether a peripheral interrupt
wakes up the processor from an idled state.

• adi_int_SICInterruptAsserted – Detects whether a peripheral
interrupt is asserted.

All SIC functions take as a parameter an enumeration value that uniquely
identifies a peripheral interrupt. The

ADI_INT_PERIPHERAL_ID enumera-

tion identifies each possible peripheral interrupt source for the processor.
This enumeration is defined in the adi_int.h file. Refer to this header file
for the complete list of values for each supported Blackfin processor.

VisualDSP++ 5.0 Device Drivers and System 2-9
Services Manual for Blackfin Processors

System Interrupt Controller Functions

adi_int_SICDisable

The adi_int_SICDisable() function is used to disable a peripheral inter­rupt from being passed to the core event controller. When called, this
function programs the appropriate SIC IMASK register to disable the given
peripheral interrupt.

adi_int_SICEnable

The adi_int_SICEnable() function is used to enable a peripheral inter­rupt to be passed to the core event controller. When called, this function
programs the appropriate SIC IMASK register to enable the given peripheral
interrupt.

adi_int_SICGetIVG

The adi_int_SICGetIVG() function is used to detect the IVG level to
which a peripheral interrupt is mapped.

In addition to the ADI_INT_PERIPHERAL_ID parameter, this function is
passed pointer-to-memory location information. The function interro­gates the proper field of the appropriate SIC interrupt assignment register
and stores the IVG level (0 to 15) to which the given peripheral interrupt
is mapped into the memory location.

adi_int_SICInterruptAsserted

The adi_int_SICInterruptAsserted() function is used to detect whether
the given peripheral interrupt is asserted. Though it can be called at any
time, it is intended that this function is called immediately by the applica
tion’s interrupt handlers to determine if a given peripheral interrupt is
being asserted, allowing the interrupt handler to determine if its periph
eral is asserting the interrupt.

-

-

2-10 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

Instead of using the usual ADI_INT_RESULT_SUCCESS return code, this func­tion returns the ADI_INT_RESULT_ASSERTED or

ADI_INT_RESULT_NOT_ASSERTED return code upon a successful completion.

If errors are detected with the calling parameters, this function may return
a different error code.

adi_int_SICSetIVG

The adi_int_SICSetIVG() function is used to set the IVG level to which a
peripheral interrupt is mapped. Upon power-up, the Blackfin processor
invokes a default mapping of peripheral interrupts to the IVG level. This
function alters that mapping. In addition to the ADI_INT_PERIPHERAL_ID
parameter, this function is passed to the IVG level (0 to 15) to which the
peripheral interrupt should be mapped. The function modifies the proper
field within the appropriate SIC interrupt assignment register to the new
mapping.

adi_int_SICWakeup

The adi_int_SICWakeup() function is used to enable or disable a periph­eral interrupt from waking up the core when the interrupt trigger and the
core are in an idled state. In addition to the ADI_INT_PERIPHERAL_ID
parameter, this function is passed a TRUE/FALSE flag. If the flag is TRUE, the
SIC interrupt wakeup register is programmed such that the given periph
eral interrupt wakes up the core when the interrupt is triggered. If the flag

FALSE, the SIC interrupt wakeup register is programmed such that the

is
given peripheral interrupt does not wake up the core when the interrupt is
triggered.

Note that this function does not enable or disable interrupt processing.
Also note that it is possible to configure the SIC so that a peripheral inter­rupt wakes up the core from an idled state but does not process the
interrupt. This may or may not be the intended operation.

-

VisualDSP++ 5.0 Device Drivers and System 2-11
Services Manual for Blackfin Processors

Protecting Critical Code Regions

Protecting Critical Code Regions

In embedded systems, it is often necessary to protect a critical region of
code while it is being executed. This is often necessary while one logical
programming sequence is updating or modifying a piece of data. In these
cases, another logical programming sequence, such as interrupt processing
in one system (or different thread in an RTOS-based system) is prevented
from interfering while the critical data is being updated.

To that end, the interrupt manager provides two functions that can be
used to bracket a critical region of code: adi_int_EnterCriticalRegion()
and adi_int_ExitCriticalRegion(). The application calls the

adi_int_EnterCriticalRegion() function at the beginning of the critical

section of code, and then calls the adi_int_ExitCriticalRegion()
function at the end of the critical section. These functions must be used in
pairs.

The actual implementation of these functions varies from operating envi­ronment to operating environment. For example, in a standalone system
(systems without any RTOS), what actually happens in these functions
may be different than the version of these functions for an RTOS-based
system. The principle and usage, however, are the same, regardless of
implementation. In this way, application code always operates the same
way, and does not change, regardless of the operating environment.

2-12 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

The adi_int_EnterCriticalRegion() function is passed an argument of
type void * and returns an argument of type void *. The value returned
from the adi_int_EnterCriticalRegion() function must always be passed
to the corresponding adi_int_ExitCriticalRegion() function. For exam­ple, examine the following code sequence:

...
Value = adi_int_EnterCriticalRegion(pArg);
... // critical section of code
adi_int_ExitCriticalRegion(Value);
...

The value returned from the adi_int_EnterCriticalRegion() function
must be passed to the corresponding adi_int_ExitCriticalRegion()
function. Although nesting of calls to these functions is allowed, the appli­cation developer minimizes the use of these functions to only those critical
sections of code, and realizes that in all likelihood, the processor is being
placed in some altered state. This could affect the performance of the sys­tem, while in the critical regions.

For example, it could be that interrupts are disabled in the critical region.
The application developer typically does not want to have interrupts
disabled for long periods of time. These functions should be used spar­ingly and judiciously.

Nesting of these calls is allowed. For example, consider the following code
sequence that makes a call to the
of code. The

...
Value = adi_int_EnterCriticalRegion(pArg);
... // critical section of code
Foo(); // call to Foo()
adi_int_ExitCriticalRegion(Value);
...

Foo() function also has a critical region of code.

Foo() function while in a critical section

VisualDSP++ 5.0 Device Drivers and System 2-13
Services Manual for Blackfin Processors

Modifying IMASK

void Foo(void) {
void *Value;
...
Value = adi_int_EnterCriticalRegion(pArg);
... // critical section of code
adi_int_ExitCriticalRegion(Value);
...
}

This practice is allowed; however, the application developer is cautioned
that overuse of these functions can affect system performance.

The pArg value passed into the adi_int_EnterCriticalRegion() function
depends upon the actual implementation for the given operating environ­ment. In some operating environments, the value is not used and can be
NULL. For more information on the pArg parameter, check the source file
for the specific operating environment, adi_int_xxx.c, in the Black-

fin/lib/src/services directory where xxx is the operating environment.

All system services and device drivers use these functions exclu-

L

sively to protect critical regions of code. Application software
should also use these functions exclusively to protect critical
regions of code within the application.

Modifying IMASK

Though applications rarely need to have the processor’s IMASK register
value modified, the interrupt manager itself modifies the IMASK register
value to control the CEC properly. In some RTOS-based operating envi
ronments, the RTOS controls the IMASK register tightly and provides
functions that allow the manipulation of

In order to ensure compatibility across all operating environments, the
interrupt manager provides functions that allow bits within the IMASK reg­ister to be set or cleared. Depending on the operating environment, these

IMASK.

-

2-14 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

functions may modify the IMASK value directly, or use the RTOS-provided

IMASK manipulation functions. Regardless of how the IMASK value is

changed, the interrupt manager API provides a uniform and consistent
mechanism for this.

Two operating environment implementation-dependent functions are
provided to set and clear bits in the IMASK register: adi_int_SetIMASKBits
and adi_int_ClearIMASKBits. These functions take as a parameter a value
that corresponds to the IMASK register of the targeted processor. When the

adi_int_SetIMASKBits() function is called, the function sets to 1 those

bits in the IMASK register that have a 1 in the corresponding bit position of
the value passed in. When the adi_int_ClearIMASKBits() function is
called, the function clears those bits (to 0) in the IMASK register that have a
1 in the corresponding bit position of the value passed in.

Consider the following example code. Assume that IMASK is a 32-bit value
and contains 0x00000000 upon entry into the code:

...
... // IMASK = 0x00000000
ReturnCode = adi_int_SetIMASKBits(0x00000003);
... // IMASK now equals 0x00000003
ReturnCode = adi_int_ClearIMASKBits(0x00000001);
... // IMASK now equals 0x00000002
ReturnCode = adi_int_ClearIMASKBits(0x00000002);
... // IMASK now equals 0x00000000

While it is very unlikely that the application will ever need to control
individual IMASK bit values, the interrupt manager uses these functions to
control the CEC.

Examples

Examples demonstrating use of the interrupt manager can be found in the

Blackfin/EZ-Kits subdirectories.

VisualDSP++ 5.0 Device Drivers and System 2-15
Services Manual for Blackfin Processors

File Structure

File Structure

The API for the interrupt manager is defined in the adi_int.h header file.
This file is located in the Blackfin/include/services subdirectory and is
automatically included by the services.h file in that same directory. Only
the services.h file should be included in the application code.

Applications should link with only one of the system services library files.
These files are located in the Blackfin/lib directory. See the approprite
section in Chapter 6, DMA Manager, for more information on selecting
the proper library file.

For convenience, all source code for the interrupt manager is located in
the Blackfin/lib/src/services directory. All operating environ­ment-dependent code is located in the file adi_int_xxx.c, where xxx is
the operating environment being targeted. These files should never be
linked into an application because the appropriate system services library
file contains all required object code.

2-16 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

Interrupt Manager API Reference

This section provides descriptions of the interrupt manager module’s
application programming interface (API) functions.

Notation Conventions

The reference pages for the API functions use the following format:

Name – Name and purpose of the function

Description – Function specification

Prototype – Required header file and functional prototype

Arguments – Description of function arguments

Return Value – Description of function return values

VisualDSP++ 5.0 Device Drivers and System 2-17
Services Manual for Blackfin Processors

Interrupt Manager API Reference

adi_int_Init

Description

This function sets aside and initializes memory for the interrupt manager.
It also initializes other tables and vectors within the interrupt manager.
This function is only called once per core. Separate memory areas are
assigned for each core.

Prototype

ADI_INT_RESULT adi_int_Init(
void *pMemory,
const size_t MemorySize,
u32 *pMaxEntries,
void *pEnterCriticalArg
);

Arguments

*pMemory Pointer to an area of memory used by the interrupt manager

MemorySize Size, in bytes, of memory supplied for the interrupt manager

*pMaxEntries On return, this argument contains the number of secondary

handler entries that the interrupt manager can support given the
memory supplied.

*pEnterCriticalArg Parameter passed to the adi_int_EnterCriticalRegion

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS Successfully initialized.

2-18 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

adi_int_Terminate

Description

This function closes down the interrupt manager. All memory used by the
interrupt manager is freed up, all handlers are unhooked, and all interrupt
vector groups (IVG) that were enabled and controlled by the interrupt
manager are disabled.

The adi_int_Terminate function does not alter the system inter-

L

rupt controller settings. Should changes to the SIC be required, the
application should make the appropriate calls into the relevant SIC
control functions before calling adi_int_Terminate().

Prototype

ADI_INT_RESULT adi_int_Terminate(void);

Arguments

None

Return Value

The function returns ADI_INT_RESULT_SUCCESS if successful. Any other
value indicates an error.

VisualDSP++ 5.0 Device Drivers and System 2-19
Services Manual for Blackfin Processors

Interrupt Manager API Reference

adi_int_CECHook

Description

This function instructs the interrupt manager to hook (insert) the given
interrupt handler into the interrupt handler chain for the given IVG.

On a return from this call, the core event controller is programmed such
that the given IVG is unmasked (enabled) and the system is properly con­figured to service the interrupt via the interrupt manager’s built-in ISRs.
The ISRs then invoke the interrupt handler supplied by the caller.
Depending on the state of the NestingFlag parameter, the interrupt man­ager installs its built-in interrupt service routine with interrupt nesting,
either enabled or disabled.

On the first call for a given IVG level, the interrupt manager registers its
built-in IVG interrupt service routine against that level and establishes the
supplied interrupt handler as the primary interrupt handler for the given
IVG level. Subsequent calls to adi_int_CECHook for the same IVG level
create a chain of secondary interrupt handlers for the IVG level. When the
interrupt for the IVG level is triggered, the primary interrupt handler is
called first, and then if present, each secondary interrupt handler is
subsequently called.

The ClientArg parameter provided in the adi_int_CECHook function is
passed to the interrupt handler as an argument when the interrupt handler
is called in response to interrupt generation.

Prototype

ADI_INT_RESULT adi_int_CECHook(
u32 IVG,
ADI_INT_HANDLER_FN Handler,
void *ClientArg,
u32 NestingFlag
);

2-20 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

Arguments

IVG Interrupt vector group number being addressed

Handler Client’s interrupt handler inserted into the chain for the

given IVG

ClientArg A void * value that is passed to the interrupt handler

NestingFlag Argument that selects whether nesting of interrupts is

allowed or disallowed for the IVG (TRUE/FALSE)

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS Interrupt handler was successfully hooked into the

chain.

ADI_INT_RESULT_NO_MEMORY Insufficient memory is available to insert the handler

into the chain.

ADI_INT_RESULT_INVALID_IVG IVG level is invalid.

VisualDSP++ 5.0 Device Drivers and System 2-21
Services Manual for Blackfin Processors

Interrupt Manager API Reference

adi_int_CECUnhook

Description

This function instructs the interrupt manager to unhook (remove) the
given interrupt handler from the interrupt handler chain for the given
IVG.

If the given interrupt handler is the only interrupt handler in the chain,
the CEC is programmed to disable (mask) the given IVG, and the inter­rupt manager built-in interrupt service routine is removed from the IVG
entry within the event vector table.

If the chain for the given IVG contains multiple interrupt handlers, the
given interrupt handler is simply purged from the chain. If the primary
interrupt handler is removed and there are secondary interrupt handlers
present in the chain, one of the secondary interrupt handlers becomes the
primary interrupt handler.

Prototype

ADI_INT_RESULT adi_int_CECUnhook(
u32 IVG,
ADI_INT_HANDLER_FN Handler,
void *ClientArg
);

2-22 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

Arguments

IVG Interrupt vector group number being addressed

Handler Client’s interrupt handler removed from the chain for

the given IVG

ClientArg A void * value that is passed to the interrupt handler.

To remove the interrupt handler successfully, match this
value to the
the adi_int_CECHook() function when the interrupt
handler was hooked into the chain.

ClientArg parameter that was passed to

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS Interrupt handler was successfully unhooked from the

chain.

ADI_INT_RESULT_INVALID_IVG IVG level is invalid.

VisualDSP++ 5.0 Device Drivers and System 2-23
Services Manual for Blackfin Processors

Interrupt Manager API Reference

adi_int_ClearIMaskBits

Description

This function is used by the interrupt manager to clear bits in the IMASK
register. Though it can also be called by the application, the application
should not attempt to modify bits in the IMASK register that represent
interrupt vector groups that are under the control of the interrupt
manager.

The implementation of this function depends upon the operating environ­ment. In the standalone version of the service, this function detects
whether the processor is within a protected region of code (refer to the

adi_int_EnterCriticalRegion and adi_int_ExitCriticalRegion

functions, respectively). If it is, the saved value of IMASK is updated
accordingly and the current “live” IMASK value is left unchanged.

When the outermost adi_int_ExitCriticalRegion function is called, the
saved IMASK value with the new bit settings is restored. Upon entering this
function, if the processor is not within a protected region of code, the
“live” IMASK register is updated accordingly.

Information on the implementation details for this function in other oper­ating environments can be found in the file adi_int_xxx.h, located in the

Blackfin/include/services/ directory, where xxx is the operating

environment.

Regardless of the implementation details, the API is consistent from envi­ronment to operating environment. Changes to application software are
not required when code is moved to a different operating environment.

Prototype

void adi_int_ClearIMASKBits(
ADI_INT_IMASK BitsToClear
);

2-24 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

Arguments

BitsToClear Replica of the IMASK register containing bits that are to

be cleared in the real IMASK register. A bit with a value of
‘1’ clears the corresponding bit in the IMASK register. A
bit with the value of ‘0’ leaves the corresponding bit in the
IMASK register unchanged.

Return Value

None

VisualDSP++ 5.0 Device Drivers and System 2-25
Services Manual for Blackfin Processors

Interrupt Manager API Reference

adi_int_EnterCriticalRegion

Description

This function creates a condition that protects a critical region of code.
The companion function, adi_int_ExitCriticalRegion, removes the
condition. These functions are used to bracket a section of code that
requires protection from other processing. These functions are used in
pairs sparingly and only when critical regions of code needs to be
protected.

The return value from this function should be passed to the corresponding

adi_int_ExitCriticalRegion function.

The actual condition that is created depends upon the operating environ­ment. In the standalone version of the service, this function effectively
disables interrupts, saving the current value of IMASK to a temporary loca­tion. The adi_int_ExitCriticalRegion function restores the original

IMASK value. These functions employ a usage counter so that they can be

nested. When nested, the IMASK value is altered only at the outermost lev­els. In the standalone version, the pArg parameter to the

adi_int_EnterCriticalRegion is meaningless.

Information on the implementation details for this function in other oper­ating environments can be found in the file adi_int_xxx.h, located in the

Blackfin/include/services/ directory, where xxx is the operating

environment.

Regardless of the implementation details, the API is consistent from envi­ronment to operating environment and from processor to processor.
Application software does not need to change when moving to a different
operating environment or moving from one Blackfin derivative to
another.

2-26 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

Prototype

void *adi_int_EnterCriticalRegion(
void *pArg
);

Arguments

pArg Implementation dependent. Refer to the adi_int_xxx.h

file for details on this parameter for the xxx environment.

Return Value

The return value from this function should always be passed to the
corresponding adi_int_ExitCriticalRegion function.

VisualDSP++ 5.0 Device Drivers and System 2-27
Services Manual for Blackfin Processors

Interrupt Manager API Reference

adi_int_ExitCriticalRegion

Description

This function removes the condition that was established by the

adi_int_EnterCriticalRegion to protect a critical region of code. These

functions are used to bracket a section of code that needs protection from
other processing. These functions are used sparingly and only when criti­cal regions of code require protection.

The pArg parameter that is passed to this function should always be the
return value from the corresponding adi_int_EnterCriticalRegion
function.

See the adi_int_EnterCriticalRegion function for more information.

Prototype

void adi_int_ExitCriticalRegion(
void *pArg
);

Arguments

pArg Return value from the corresponding

adi_int_EnterCriticalRegion() function call

Return Value

None

2-28 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

adi_int_SICDisable

Description

This function configures the system interrupt controller to disable the
given interrupt and prevent it from being passed to the core event
controller.

The adi_int_SICDisable function simply programs the system interrupt
mask register to mask interrupts from the given peripheral, thereby pre­venting them from being passed to the core event controller.

Prototype

ADI_INT_RESULT adi_int_SICDisable(
const ADI_INT_PERIPHERAL_ID PeripheralID
);

Arguments

PeripheralID ADI_INT_PERIPHERAL_ID enumeration value that identi-

fies an interrupt source

Return Value

ADI_INT_RESULT_SUCCESS System interrupt controller has been success-

fully configured.

ADI_INT_RESULT_INVALID_PERIPHERALID Peripheral ID specified is invalid.

VisualDSP++ 5.0 Device Drivers and System 2-29
Services Manual for Blackfin Processors

Interrupt Manager API Reference

adi_int_SICEnable

Description

This function configures the system interrupt controller to enable the
given interrupt and allow it to pass to the core event controller.

The adi_int_SICEnable function simply programs the system interrupt
mask register to allow interrupts from the given peripheral to be passed to
the core event controller.

Prototype

ADI_INT_RESULT adi_int_SICEnable(
const ADI_INT_PERIPHERAL_ID PeripheralID,
);

Arguments

PeripheralID ADI_INT_PERIPHERAL_ED enumeration value that identi-

fies a peripheral interrupt source

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS System interrupt controller has been success-

fully configured.

ADI_INT_RESULT_INVALID_PERIPHERAL_ID Peripheral ID specified is invalid.

2-30 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors

Interrupt Manager

adi_int_SICGetIVG

Description

This function detects the mapping of a peripheral interrupt source to an
IVG level. When called, this function reads the appropriate system inter­rupt assignment register(s) of the given peripheral and stores the IVG level
to which the peripheral is mapped into the location provided by the appli­cation. This function does not modify any parameters of the interrupt
controller.

Prototype

ADI_INT_RESULT adi_int_SICSetIVG(
const ADI_INT_PERIPHERAL_ID PeripheralID,
u32 *pIVG
);

Arguments

PeripheralID ADI_INT_PERIPHERAL_ID enumeration value that identi-

fies a peripheral interrupt source

*pIVG Pointer to an unsigned 32-bit memory location into which

the function writes the IVG level to which the given
peripheral is mapped

Return Value

The function returns ADI_INT_RESULT_SUCCESS if successful. Other possi­ble return values include:

ADI_INT_RESULT_INVALID_PERIPHERAL_ID Peripheral ID specified is invalid.

ADI_INT_RESULT_INVALID_IVG Interrupt vector group level is invalid.

VisualDSP++ 5.0 Device Drivers and System 2-31
Services Manual for Blackfin Processors

Interrupt Manager API Reference

adi_int_SICInterruptAsserted

Description

This function determines whether a given peripheral interrupt source is
asserting an interrupt. This function is typically called in an application’s
interrupt handler to determine whether the peripheral in question is
asserting an interrupt. This function does not modify any parameters of
the interrupt controller but simply interrogates the appropriate interrupt
status register(s).

Prototype

ADI_INT_RESULT adi_int_SICInterruptAsserted(
const ADI_INT_PERIPHERAL_ID PeripheralID
);

Arguments

PeripheralID ADI_INT_PERIPHERAL_ID enumeration value that identi-

fies a peripheral interrupt source

Return Value

The function returns one of the following values:

ADI_INT_RESULT_INVALID_PERIPHERAL_ID Peripheral ID specified is invalid.

ADI_INT_RESULT_ASSERTED Specified peripheral is asserting an interrupt.

ADI_INT_RESULT_NOT_ASSERTED Specified peripheral is not asserting an interrupt.

2-32 VisualDSP++ 5.0 Device Drivers and System

Services Manual for Blackfin Processors