Embedded Systems RTOS, Libraries and Drivers

Peter Thorwartl

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 The Designer’s Challenge

• What do I need to program?

• What libraries are available?

 Does the design need an operating system?

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Objectives

 Examine the Xilinx libraries for required services and features  Examine a processor’s services for required functions and features  Evaluate an IP device driver for appropriate functionality and design  Use the Board Support Package (BSP) to access system services from the software application  Determine whether your embedded system application requires a standalone system or an operating system  Describe how a Real-Time Operating System (RTOS) differs from a conventional OS

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Re-Inventing the Wheel

 Custom hardware typically requires custom software  Standard hardware often has existing software support Uart General-purpose I/O Ethernet  Certain processor functions can be complex and software support may already exist Setting up the interrupt structure Cache enabling Exception processing Memory Management Unit (MMU)

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Minimal Required Services

 C language standard services: C language construct services stdin and stdout Math library malloc  Processor support requires these services: Interrupt Cache Language environment support

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Language services are necessary when running a software application written in C. Operating Systems  Operating systems are a collection of software routines that comprise a unified and standard set of system services  The Standalone option is used when no operating system is desired Provides a minimal amount of processor and library services as previously illustrated Can be considered a minimal, non-standard operating system  Variety of third-party operating systems are available Linux – many flavors RTOS – real-time operating system; also has many flavors XilKernel – provided by Xilinx; small and simple  Operating systems are installed and become part of the Board Support Package (BSP)

 Operating system services GUI support TCP/IP services** Task management Resource management** Familiar programming services and tasks Easy connection to already written applications Ability to reload and change applications Full file system services** ** Also available as additions to the Standalone BSP

 The Standalone BSP includes the previously discussed items  Standalone system design considerations All services needed are included in the BSP The application is static—it never changes Application fits in block RAM Application is single-task based Interrupts may or may not be used

Operating System Standalone System

Requires off-FPGA memory Application can fit into FPGA block OS cost and license RAM More complex project No license costs More programming flexibility Simple software model Some OS services available – TCP/IP stack – File system

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Real-Time Operating System

 Many applications require peripheral servicing on a regular basis or with very low latency  The abstraction level of many traditional OS services can have a latency that is too great to service needed tasks Communications Hardware control  An RTOS is an operating system that specifically addresses these items Heartbeat timer via an interrupt Low instruction latency for device driver services  Functionality of RTOS system services fall between those of a Standalone BSP and an OS

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Board Support Package (BSP)

 All libraries, processor services, device drivers, and the operating system are compiled into a library  The set of software modules are combined into the libxil.a library  The software modules, routines, processes, and services can be directly called from your application  Allows you to use low-level processor core functions Enable, disable, and flush caches Read/write time-base registers  Allows you to use IP peripheral device drivers GPIO, IIC controller, PCI controller, UART  Offers glue functionality to link code against standard libraries Time, sleep Files Memory

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Board Support Package

Arbiter Primary Bus Bridge Secondary Bus Arbiter libxil.a

XEmac_mWriteReg ( … ); DDR 10/100 SPI UART Timer Intc XEmac_SendFrame ( … ); SDRAM Ethernet EEPROM ... XSpi_mSendByte ( … ); XSpi_GetStatusReg ( … ); ... xtmrctr.h XUartLite_SendByte ( … ); xemac.h XUartLite_GetStats ( … ); XTmrCtr_mWriteReg ( … ); ... XEmac_mWriteReg ( … ); XTmrCtr_IsExpired ( … ); XTmrCtr_mWriteReg ( … ); XEmac_SendFrame ( … ); ... XIntc_mEnableIntr ( … ); XTmrCtr_IsExpired ( … ); ... uartlite.h ... … XIntc_mEnableIntr ( … ); xspi.h XUartLite_SendByte ( … ); ... XUartLite_GetStats ( … ); XSpi_mSendByte ( … ); ... XSpi_GetStatusReg ( … ); ...

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

BSPs are collections of parameterized drivers for a specific processor system. Support Libraries

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The EDK libraries and device drivers provide standard C library functions, as well as functions to access peripherals. The Library Generator utility (LibGen) automatically configures the EDK libraries for every project based on the MSS file. These libraries and include files are saved in the current project’s lib and include directories, respectively. The libc library is included automatically. The -lm option should be specified for programs that access libm math functions. The Xilinx LibXil library provides block access to file systems and devices using standard calls, such as open, close, read, and write. The Memory File System (MFS) component, LibXil MFS, provides the capability for managing program memory in the form of file handles. Creating directories and including files within each directory is possible. The file system can be accessed from the high-level C language through function calls specific to the file system. The Networking library, lwIP, allows a processor to connect to the Internet. LibXilNet includes functions for handling the TCP/ IP stack protocols. It provides a simple set of Application Programming Interface (API) functions for enabling network programming. C Support Libraries

 Xilinx provides three C libraries Math library (libm)  The math library is an improvement over the newlib math library  The -lm option is used for libm functions Standard C language support (libc)  The functions of this library are automatically available Xilinx processor support library (libxil.a)  Interrupt/exception handler  Program initialization

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

 Xilinx provides four system access libraries Xilinx memory file system: LibXil Mfs Xilinx Compact Flash support: LibXil FATfs  Xilinx System ACE™ interface required Xilinx networking support: LibXil lwIP  TCP /IP stack library Intel parallel flash support: LibXil flash

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The Memory File System (MFS) component, LibXil MFS, provides the capability for managing program memory in the form of file handles. Creating directories and including files within each directory is possible. The file system can be accessed from the high-level C language through function calls specific to the file system. The Networking library, lwIP, allows a processor to connect to the Internet. LibXilNet includes functions for handling the TCP/ IP stack protocols. It provides a simple set of Application Programming Interface (API) functions for enabling network programming. Access Software Platform Settings in XPS

 Software settings can be assigned to an individual processor instance by selecting Software → Software Platform Settings or clicking  In case of multiple processors in the design, software platform settings allow you to select each processor instance and set parameters

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

To generate software for EDK designs using XPS: 1. Configure software platform settings. 2. View and set project options. 3. Create EDK software libraries. 4. Open or create your applications. 5. View and set application options. 6. Build the application. 7. Initialize the bitstream with the application. 8. Download and execute the application. 9. Download and debug the application by using XMD.

You can configure software settings for an EDK project by using the XPS GUI or editing the MSS file. Software Platform Settings

1 Select the Software Platform panel 2 1 2 Select the processor instance

Select the OS 3

Select the desired 3 4 libraries and their 4 versions

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

In the Software Platform Settings dialog box, you can configure the processor settings and OS and libraries settings. The default driver and its version for the processor are selected. For the chosen processor driver, all the configurable parameters are shown with their defaults. Edit the settings according to your design requirements. Default settings for OS & Library Settings are selected below Processor Settings. The bottom of the dialog box provides options for selecting libraries. OS and Libraries Settings

Select the OS and 1 Libraries panel 2 1 3 Select the processor 2 instance

Set stdin and stdout 3 devices as well as assign FPU, malloc, and 4 profiling-related parameters

Configure selected library parameters 4

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

At the top of the pane are OS configuration parameters; below are those for each library previously selected in the Software Platform pane. Initial values are the default settings for the selected OS and libraries. Edit these values according to design requirements and click OK. The Microprocessor Software Specification (MSS) file is then created or modified with your configurations. Processor Services

 Provided in the Standalone BSP  Common to MicroBlaze™ and PowerPC® processors Interrupt/exception handling Instruction/data cache handling Fast Simplex Link (FSL) interface macros and flags Pseudo-ASM macro summary Version Register (PVR) access routine and macros File handling Processor error reporting

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

For more information, please see OS and Libraries Document Collection, “Standalone Board Support Package.” Processor Services

 Provided in the Standalone BSP  Different for MicroBlaze and PowerPC processors File handling Boot code Memory management Processing Functions Specific include files for processor register referencing Time functions (PowerPC processor only) Macros for APU Fabric Co-processor Module (FCM) user-defined instructions (PowerPC processor only)  Reference: OS and Libraries Document Collection

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 PowerPC Processor: Timer Facilities  Features Time base Fixed Interval Timer (FIT) Programmable Interval Timer (PIT) Watchdog timer These timers share the same time-based clock frequency  Uses Time of day Data logging Peripherals requiring periodic service Recover from faulty hardware or firmware

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 PowerPC Processor: Sleep

 Sleep BSP library function calls unsigned int usleep(unsigned int __useconds); unsigned int sleep(unsigned int __seconds);  The sleep() or usleep() function in sleep.c delays the execution of a program by __seconds or __useconds  Remember to set CORE_CLOCK_FREQUENCY because the sleep() and usleep() functions use it to compute the delay

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The default value of the CORE_CLOCK_FREQUENCY setting is 400 MHz. This value must be set to the correct core frequency; it is set by BSB upon user choice. If BSB is not used to define the system, this value can be set in the Processor and Driver Parameters tab of the Software Platform Settings pane. PowerPC Processor: Time

 The xtime_l.c file and corresponding xtime_l.h include file provide access to the 64-bit time-base counter inside the PowerPC processor core  Each processor cycle = counter +1  Declarations void XTime_SetTime(XTime xtime); void XTime_GetTime(XTime *xtime); void XTime_TSRClearStatusBits(unsigned long Bitmask);

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The counter increases by one every processor cycle. Declarations: •void XTime_SetTime(XTime xtime); -- Sets the time-based register to the value in xtime •void XTime_GetTime(XTime *xtime); -- Writes the current value of the time-based register to variable xtime •void XTime_TSRClearStatusBits(unsigned long Bitmask); -- Used to clear bits in the Timer Status Register (TSR). The Bitmask parameter designates the bits to be cleared. A 1 in any position of the Bitmask parameter clears the corresponding bit in the TSR Software Drivers

main.c

… #define XPAR_GPIO_BASEADDR 0xFFFF0000 … The processor core XGpio_mWriteReg (XPAR_GPIO_BASEADDR, 0xABCD0123); ... communicates with the system peripherals via software drivers

Core ABus = 0xFFFF0000, DBus = 0xABCD0123 GPIO DBus 0xABCD0123 D Q ABus Arbiter Primary Bus 0xFFFF0000 CE xferAck =

xferAck decode register

GPIO

Software drivers/firmware gpio.vhd

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Software drivers and firmware bridge the gap between software and hardware. Device Drivers

 Xilinx device drivers Provide maximum portability  The device drivers are provided as ANSI C source code Support FPGA configurability  Supports multiple instances of the device without code duplication for each instance, while at the same time managing unique characteristics on a per-instance basis Support simple and complex use cases  A layered device driver architecture provides both of the following – Simple device drivers with minimal memory footprints – Full-featured device drivers with larger memory footprints Provide ease of use and maintenance  Xilinx uses coding standards and provides well-documented source code for developers

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Xilinx device drivers are designed to: Provide maximum portability: The device drivers are provided as ANSI C source code. ANSI C maximizes portability across processors and development tools. Source code is provided to aid designers in debugging their applications as well as modifying or optimizing the device driver if necessary. A layered device-driver architecture additionally separates device communication from processor and Real-Time Operating System (RTOS) dependencies. This provides portability of core device driver functionality across processors and operating systems. Support FPGA configurability: Because FPGA-based devices can be parameterized to provide varying functionality, the device drivers must support this varying functionality. The configurability of device drivers should be supported at compile time and at run time. Run-time configurability provides the flexibility required for future dynamic system reconfiguration. In addition, a device driver supports multiple instances of the device without code duplication for each instance, while at the same time managing unique characteristics on a per-instance basis. Support simple and complex use cases: Device drivers are required for simple tasks, such as board bring-up and testing, as well as complex embedded applications. A layered device driver architecture provides both simple device drivers with minimal memory footprints and more robust, full-featured device drivers with larger memory footprints. Be easy to use and maintain: Xilinx makes use of coding standards and provides well-documented source code to give developers a consistent view of source code that is easy to understand and maintain. In addition, the API for all device drivers is consistent to provide a similar look and feel among drivers. Xilinx Standard Drivers

 All Xilinx-provided IP device drivers follow a convention Naming  Driver name  Resource filing naming (.c, .cpp, .c++, .h) Directory and file structure Device driver API functions  Instance pointer  Reset, initialization, start, and stop  Get and clear status  Interrupt handler management  Optional functions

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

For more information, see the Device Driver Programmer Guide. Hardware IP Device Drivers

 Driver Provides an interface for the software to communicate with the hardware Designed to be portable across processor architectures and operating systems  Delivery format Delivered as source code, allowing it to be built and optimized Minimized assembly language C programming language

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Driver Settings

1 Select the Drivers panel 1 2 2 Select the drivers and versions for each device in the design

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The Drivers configuration panel lists all of the peripherals with their default driver settings selected. Edit the settings according to your design requirements. After the driver settings are configured, click OK. This creates or modifies the appropriate section of the software settings MSS file. Note that in the case of a multiple processor system, you should select the processor instance that you want the drivers to configure in the Software Platform panel first and then select the Drivers panel. Drivers: Level 0 and Level 1

 The layered architecture provides seamless integration with the following (Layer 2) RTOS adaptation layer – Provided by the OS; does not exist in a standalone system (Layer 1) High-level device drivers that are full featured and portable across operating systems and processors (Layer 0) Low-level drivers for simple use cases; direct hardware interface

Layer 2, RTOS Adaptation

Layer 1, High-Level Drivers

Layer 0, Direct Hardware Interface

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The layered architecture accommodates the many use cases of device drivers, while providing portability across operating systems, toolsets, and processors. The layered architecture also provides seamless integration with an RTOS (Layer 2), with high-level device drivers that are full featured and portable across operating systems and processors (Layer 1), and with low-level drivers for simple use cases (Layer 0). You can choose to use any and all layers. Drivers: Level 0

 Consists of low-level device drivers; direct hardware interface  Implemented as macros and functions that are designed to allow a developer to create a small system  Characteristics Small memory footprint Little to no error checking is performed Support for primary device features only No support for device configuration parameters Support for multiple instances of a device via base address parameters Polled I/O only Blocking function calls Header files have “_l” in their names (for example, xuartlite_l.h)

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Drivers: Level 1  Consists of high-level device drivers  Implemented as macros and functions and designed to allow a developer to utilize all of the features of a device  Characteristics Abstract API that isolates the API from hardware device changes Support for device configuration parameters Support for multiple instances of a device Polled and interrupt-driven I/O Non-blocking function calls to aid complex applications Possibly large memory footprint Typically, buffer interfaces for data transfers as opposed to byte interfaces Header files do not have “_l” in their names (for example, xuartlite.h)

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Comparison Example  Uartlite Level 1 XStatus XUartLite_Initialize (XUartLite *InstancePtr, Xuint16 DeviceId) void XUartLite_ResetFifos (XUartLite *InstancePtr) unsigned int XUartLite_Send (XUartLite *InstancePtr, Xuint8 *DataBufferPtr, unsigned int NumBytes) unsigned int XUartLite_Recv (XUartLite *InstancePtr, Xuint8 *DataBufferPtr, unsigned int NumBytes) Xboolean XUartLite_IsSending (XUartLite *InstancePtr) void XUartLite_GetStats (XUartLite *InstancePtr, XUartLite_Stats *StatsPtr) void XUartLite_ClearStats (XUartLite *InstancePtr) XStatus XUartLite_SelfTest (XUartLite *InstancePtr) void XUartLite_EnableInterrupt (XUartLite *InstancePtr) void XUartLite_DisableInterrupt (XUartLite *InstancePtr) void XUartLite_SetRecvHandler (XUartLite *InstancePtr, XUartLite_Handler FuncPtr, void *CallBackRef) void XUartLite_SetSendHandler (XUartLite *InstancePtr, XUartLite_Handler FuncPtr, void *CallBackRef) void XUartLite_InterruptHandler (XUartLite *InstancePtr)  Uartlite Level 0 void XUartLite_SendByte (Xuint32 BaseAddress, Xuint8 Data) Xuint8 XUartLite_RecvByte (Xuint32 BaseAddress)

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Custom Device Drivers

 Create and Import Peripheral wizard Generates device driver skeleton files during hardware specification of new peripheral Ensures proper directory structure for linkage into the BSP Creates prototypes of basic device driver functions  Custom driver is automatically compiled and entered into the BSP library  Looks and feels like any other included driver  More details covered later in presentation

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

To add peripherals, use the Create and Import Peripheral wizard or to apply the bus protocols, naming conventions, and the formats of special interface files required by the EDK. When importing peripherals, certain interface files and directory structures are required to make your peripheral visible to the various tools in the EDK. Any custom peripheral that connects to the PLB bus must: •Comply with the PLB protocol •Meet the requirements of the Platform Generator This allows you to take advantage of the simple automated flow that generates a system-level architecture. Generate BSP

 The Board Support Package contains C libraries, processor services and device drivers  Executes the LibGen program via Generate Libraries and BSPs  Typically only executed once after the hardware has been designed and the software options set  Select Software → Clean Software whenever the OS changes  Several OS-specific files and directories are created

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Software Platform Design Flow

The Library Generator (LibGen) utility generates the necessary libraries and drivers for the embedded soft processors

LibGen takes a Microprocessor Software Specification (MSS) file created by the user as input. The MSS file defines the drivers associated with peripherals, standard input/output devices, and other related software features

XPS generates the MSS file using the specified software settings

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

LibGen command line options: •-h, -help (Help): Causes LibGen to display the usage menu and exit. •-v (display version information): Displays the version number of LibGen. •-log logfile[.log]: Specifies the log file. Default is libgen.log. •-p family_name (architecture family): Defines the target architecture family. •-od output_dir (specify the output directory): Default is the current directory. •-sd source_dir (specify the source directory): Default is the current working directory. •-lp library_path (specify the library path for user peripherals and driver repositories). -mhs mhsfile.mhs (specify the Microprocessor Hardware Specification [MHS] file to be used). •-lib: Copies libraries and drivers but does not compile them. LibGen

 code directory LibGen-Generated Directories A repository for EDK executables Creates xmdstub.elf for MB here project_directory  include directory processor instance directory C header files that are required by drivers code directory xparameters.h include directory  Defines base and high addresses of the peripherals in the system lib directory  Defines the peripheral IDs required by libsrc directory the drivers and user programs  Defines the function prototypes

Note: The number of generated processor instance directories is related to the number of processor instances present in the system

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

In general, LibGen is the first tool to use to configure libraries and device drivers. LibGen takes a Microprocessor Software Specification (MSS) file created by the user as input. The MSS file defines the drivers associated with the peripherals, standard input/output devices, and other related software features. The EDK offers a RevUp tool to convert an old MSS file format into a new MSS format. LibGen generates directories and files in the USER_PROJECT directory. For every processor instance in the MSS file, LibGen generates a directory with the name of the processor instance. Within each processor instance directory, LibGen generates the following directories and files: • The code directory is used as a repository for EDK executables. LibGen creates the xmdstub.elf file (for MicroBlaze processor on-board debug) in this directory. • The include directory contains the C header files that are required by the drivers. The xparameters.h include file is also created through LibGen in this directory. This file defines base addresses of the peripherals in the system, #define statements required by the drivers, libraries, user programs, and function prototypes. The Microprocessor Driver Definition (MDD) file for each driver specifies the definitions that must be customized for each peripheral that uses the driver. LibGen

LibGen Generated Directories  lib directory libc.a, libm.a, and libxil.a libraries project_directory  The libxil library contains driver functions that the particular processor can access processor instance directory  libsrc directory code directory Intermediate files and makefiles that include directory compile the libraries and drivers  lib directory Peripheral-specific driver files that are copied from the EDK and user driver libsrc directory directories

Note: The content in the processor instance directories is overwritten every time LibGen is run

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The lib directory contains libc.a, libm.a, and libxil.a libraries. The libxil library contains driver functions that the particular processor can access. The libsrc directory contains intermediate files and makefiles that are required to compile the libraries and drivers. This directory contains peripheral-specific driver files and library files that are copied from the EDK and user driver/library directories. IMPORTANT: LibGen removes all of the above directories every time the tool is run. You must put your sources, executables, or any other files in a user-created area. Xilinx Micro Kernel

 A lightweight kernel supporting basic scheduling and inter-process communication  PowerPC and MicroBlaze processor support  Threads use priority and round-robin scheduling (up to 256 priorities)  Semaphores, queues, and shared memory  Debug by using a single executable for kernel and user applications currently supported  Optional POSIX-compliant interface level for common software compatibility  malloc supported in two levels Lightweight with no free function Full-featured with free function support (uses more system resources)  The LwIP networking library can be integrated with XMK to provide a complete sockets interface

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Generating XMK BSP  In the Software Platform panel, select xilkernel for the selected processor instance  Select the libraries  In the OS and Libraries panel, select the STDOUT and STDIN devices, as well as the system interrupt controller

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 XMK Options Configuration

 Fully configurable on many dimensions for complete control of code size versus function

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

For more information, see the OS and Libraries Document Collection. XMK BSP Generation

XMK-specific include directories

XMK-specific library source files

OS HW  Technology for customization of libraries and Design BSPs Selection Generates a BSP that is tailored to specific OS requirements OS  Source XPS MLD Files Customization is enabled via a data-driven Files methodology: MLD

 MLD files consists of RTOS HW Data definition file (.mld) BSP Netlist Data generation file (.tcl)  Tcl: Tool command language To To RTOS IDE ISE

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

An MLD file contains directives for customizing software libraries and generating board support packages for operating systems. For all EDK libraries and operating systems, the user does not need to peruse this document. User-written libraries and operating systems that need to be configured by the LibGen tool will use the MLD. Microprocessor Library Definition

 MLD files are used to List hardware drivers required by the service Expose configurable constants for the service List the header files exported to the application List the constants exported to the application

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Each OS/library has an MLD file and a Tcl file associated with it. The MLD file is used by the Tcl file to customize the OS/ library depending on different options in the MSS file. The OS/library source files and the MLD file for each OS/library must be located at specific directories in order for LibGen to find the files and the libraries. Disclaimer

 Developing an embedded Linux operating system from open sources, often referred to as “rolling your own,” is an attractive alternative to buying an expensive commercial distribution  Sometimes there is no choice because the commercial distributions do not have what you need  Embedded designers may not realize the level of expertise that open-source development demands or the time it adds to the development cycle. These aspects have their costs, too

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Building your own operating system from a free, open source tree requires that you build your own toolchain as well as customize the kernel. The level of Linux expertise required for such a development effort—and remember that the system will require support and maintenance post-product release—creates considerable downstream costs that offset the original upfront savings. Viewed from this perspective, purchasing a commercial distribution or engaging consultants may be the most economical and timely solution. Benefits of Linux

 Memory manager  File system  Networking support (TCP/IP stack, ARP, ...)  Protected memory  Peripheral support  Application support

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Linux provides the user with a memory manager that can allocate and release chunks of memory on the fly. It also provides a file system to allow the user to read/write and store data. It provides networking support to allow the user to easily connect with other endpoints. It provides a segmented memory space (kernel space and user space) so that third-party or user applications can be run safely on the system without breaking it. Using peripherals from the long list of those that Linux supports can save you significant development time. You can save additional time by making use of the many applications and libraries available that run on the platform. Linux also has wide peripheral support, which includes connectivity and network stacks for running Web servers. Linux Kernel Structure

Application Normal Program Kernel System Call Interface

Virtual file system Sockets management Memory Process Manager Manager File System Drivers TCP/IP stack

LED Driver Ethernet Drivers Kernel Hardware LEDs Ethernet MAC

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Whenever an application needs a service from the kernel—for instance, to talk to a device, allocate memory, or create a new task—it executes a system call. The system call interface is the only way that an application can talk with the kernel. When the Linux kernel receives a system call, it calls the appropriate functions. The system call interface stays reasonably stable between major releases of the Linux kernel (2.6.x). Not every Xilinx peripheral is supported in Linux. Check the distribution for available drivers. Open-Source Software

 Source code is always available!  Licensing  Designing products with Linux and other open-source software does not mean that you have to make your software open source. The use of loadable modules and LGPL libraries protects your intellectual property  Alternative: commercial distributions Tools Support Maintenance

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Commercial Linux companies typically obtain their source from the open-source community. Some push source code back to the open source, but many do not. They may add value with: •Gcc tools, prebuilt binaries •BSPs •Documentation •Testing •Support Companies that provide a Linux distribution are paid to maintain all the versions of drivers and BSPs. µCLinux for the MicroBlaze Processor

 Initial port done at the University of Queensland www.itee.uq.edu.au/~jwilliams/mblaze-uclinux Based on version 2.4 of µCLinux Does not support memory protection or MMU-flat memory model New: Supported by www.petalogix.com  Debugging though GDB running on the target under Linux Kernel debugging through XMD is available

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Third-Party Ecosystem

QNX MiSPO LYNUXWORKS WIND RIVER Micrium Codetronix montavista Celoxica Agilent eSOL impulse Technologies

express logic Embedded Tools Co-design Tools OSE RTOS Middleware ESL Tools, and IDE/Debug Tools Co-Verification more TEAMf1 Inc. Computex petalogix SEAMLESS Bluespec Treck Inc. LAUTERBACH Mentor Prevas BINACHIP Green Hills mind Graphics

ETAS

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Xilinx partner alliances offer a wide range of offerings in compilers, debuggers, operating systems, and other tools and support for the embedded systems developer. For more information, go to the www.xilinx.com → Technology Solutions → Embedded Processing → Third-Party Ecosystem link. PPC405/440 Ecosystem

Third Party MicroBlaze Processor v7

Mentor Nucleus

LynuxWorks Linux 2.6 (w MMU) Linux 2.6 (wo MMU) Petalogix uCLinux 2.4 (wo MMU) uCLinux 2.6 (wo MMU) Express Logic ThreadX

Micrium uC/OS-II

Mispo uIRON eSOL uITRON

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Summary  Xilinx Platform Studio supports many operating systems, including standalone and commercial and open-source distributions  The Xilinx Micro Kernel is a very basic OS that supports multitasking  The Standalone package provides processor system services and C library language extensions, xilprintf(), for example  Device drivers are provided for all included IP peripherals, or you can write custom device drivers for your own or existing bus peripheral IP  The LibGen tool compiles all of the above into a user library Board Support Package (BSP)  A BSP provides the necessary peripheral definitions, software support, and utilities to support the user’s needs  You can use a Microprocessor Library Definition (MLD)-based file with Tcl to support a third-party operating system that is not supported under the standard EDK installation

Structuring peripheral interfacing so that the application is device- independent

Incorporating a device driver into the BSP

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

How to “unstructure” or decouple device driver code from application code and how to make it generic. •Adding a device driver to the BSP. Objectives

 Apply system considerations when developing device drivers  Use the Create and Import Peripheral wizard to create a device driver skeleton  Integrate a custom device driver into the BSP  Create the LibGen device driver-dependent files  Describe the Xilinx device driver implementation standard  Write proper device drivers for Xilinx embedded systems

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Writing a Device Driver

 Requirements for Xilinx embedded processor systems Understand the device hardware operation Plan the device driver system services Generate a skeleton program structure with the Create and Import Peripheral wizard Write the code Ensure inclusion into the BSP via LibGen Access the device driver from the application program

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Device driver design mechanisms, accessing semantics, operating behaviors, and run-time performance can be crucial to the operating system architecture and total system performance. Know the Device Hardware

 Control registers  Status registers  Device parameter registers  Data structures  Interrupts  Event occurrence Synchronous Asynchronous Atomic  Multi-threaded (software safe)  Re-entrant capable

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

While data structures, multi-threading, and re-entrant capabilities are typically software issues, they can be affected by the hardware design. Planning the Services

 Degree of sophistication Macro calls Level 0, 1, 2  Make it easy to perform popular operations—minimal parameters  Character versus buffer  Passing data structures  Interrupt services  Error reporting  Initialization and reset  Needed #define statements  Documentation

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Degree of sophistication: Local calls may need only macros and Levels 0 and 1; Level 2 may be needed for operating systems. Character versus buffer: Do you feed it data in streams or blocks? Passing data structures: How will you pass data structures to and from the device? Error reporting: Will there be error conditions? How will you handle them? Initialization and reset: Boundary conditions. #define statements: Make a list of the needed #define statements for those who search after you. #define statements appear in xparameters.h or a .h file. Documentation: You can encode documentation in the .c and .h files. Adding the Driver

 One-time use Include a driver in the software application Not part of the BSP No special considerations  Include in the BSP Preferred method for software reuse Source code compiled only when the BSP is generated by LibGen Requires a specific directory structure and control files Use the Create and Import Peripheral wizard to include in the BSP  Provides a starting point and driver skeleton  Requires completion of needed control files

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Software Peripherals Files

 Three ways to integrate your own device drivers Locally in the XPS project: subdirectory\drivers  \src\ Requires .c and .h files  \data\ Requires Microprocessor Driver Description (MDD) and Tcl files

Global search path (project) XPS: Select Project Options → Project Peripheral Repository  Path setting required two levels upper than \drivers\  Same directory and file structure as above

Global search path (host) XPS: Select Edit Preferences → Global Peripheral Repository  Requires MPD and PAO files  Same directory and file structure as above

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 XPS Directory Structure

 Required directory structure for LibGen recognition The drivers directory is typically in the project root The device driver-named directory is the counterpart of the same named hardware directory in the pcores directory Device driver source code is in the src directory The data directory contains files used by LibGen to include the device driver in the BSP  This structure can be built the most easily via the Create and Import Peripheral wizard

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Starting the IP Wizard

You can launch the Create and Import Peripheral Wizard after creating a project and selecting Hardware → Create or Import Peripheral. This is done when the wizard is engaged to generate the hardware

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

You can start the Create and Import Peripheral wizard after creating a new project or opening an existing project in XPS. Selecting for Device Driver Skeleton Generation

Optional Support: - Implementation Project - Driver Template

Select skeleton device driver creation by selecting the Generate template driver files option in the Peripheral Implementation Support dialog box, the second-to-last wizard window when you are creating a peripheral

 The required, properly named directory structure is created  Skeleton files created data subdirectory  .mdd  .tcl src subdirectory  .c  _selftest.c  .h  Makefile

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

To add the driver: • Add a directory under drivers. • Define the driver interface in the MDD file. List any required PARAMETERS List any dependencies List the supported hardware cores • Create the instance interface in the Tcl script. • Bind the driver to a hardware Microprocessor Hardware Specification (MHS) instance in the Microprocessor Software Specification (MSS) file. • Copy the source code and makefile into the src directory. Required LibGen Files

 LibGen requires the following files for proper device driver inclusion in BSD Makefile  Automatically generated by the wizard in the src directory  Includes *.c and *.h files .mdd  Automatically generated by the wizard in the data directory  User adds the needed options and parameters .tcl  Automatically generated by the wizard in the data directory  Contains instructions for LibGen BSP creation system.mss  XPS system file  Tells LibGen to include software driver instance in the BSP

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The MSS file already exists for the project and contains an instance of the device driver. MDD File

 Microprocessor Device Description (MDD) files are used to Associate a driver with a type of core Expose configurable constants for the driver List the header files exported to the application List the constants exported to the application  The driver name is based on the directory structure

.mdd data drivers .tcl

Makefile .c .h src

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 MDD File

OPTION psf_version = 2.1;

BEGIN driver uartlite OPTION supported_peripherals = (opb_uartlite opb_jtag_uart opb_mdm); Format Version OPTION driver_state = ACTIVE; OPTION depends = (common_v1_00_a); OPTION copyfiles = all; Driver Name BEGIN INTERFACE stdin PROPERTY header = xuartlite_l.h; FUNCTION name = inbyte, value = XUartLite_RecvByte; END INTERFACE Peripherals

BEGIN INTERFACE stdout PROPERTY header = xuartlite_l.h; FUNCTION name = outbyte, value = XUartLite_SendByte; END INTERFACE Interfaces

BEGIN INTERFACE stdio PROPERTY header = xuartlite_l.h; FUNCTION name = inbyte, value = XUartLite_RecvByte; FUNCTION name = outbyte, value = XUartLite_SendByte; END INTERFACE

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 MDD Options and Parameters

 Example options OPTION supported_peripherals = (plb_tft_cntlr_ref); OPTION driver_state = ACTIVE; OPTION depends = (common_v1_00_a); OPTION copyfiles = all;

 Example parameters PARAM name = level, desc = "Driver Level", type = int, default = 0, range = (0, 1); PARAM name = BUFFER, desc = “Double Buffer Option", type = int, default = 0; BEGIN BLOCK, dep = (level = 0) OPTION depends = (common_v1_00_a); OPTION copyfiles = (xtft_l.c xtft_l.h xtft_charcode.c xtft_charcode.h Makefile); END BLOCK

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

You can group functionality into blocks based on design criteria. In this case, the criterion is based on the required level of complexity provided by the driver. Interfaces can be provided based on requests by the user. In this case, any Linux-specific features would be included in the interface defined at the end. Parameters are: •name: The name given to the parameter. •desc: Short description of the parameter to be displayed by the GUI tools. •type: The parameter type (bool, int, string, enum). •default: The default value of the parameter if one is not provided. •range: A list of possible values for the parameter. Options are: •psf_version: psf tool version number. •drc: Global driver name. •copyfiles: The files to be copied for the driver/library. •depends: The list of directories that are needed by the driver. •help: Help file that describes the driver. •supported_peripherals: Cores that use this driver. •requires_interface: List of interface names. psf_version is an exceptional option because it is defined globally. Example: OPTION supported_peripherals = (plb_tft_cntlr_ref); OPTION driver_state = ACTIVE; OPTION depends = (common_v1_00_a); OPTION copyfiles = all; Tcl file

 Same format as the Microprocessor Software Specification (MSS) file  The tools call _drc to perform boundary checking  The tools call generate to output the required files  Provides hooks that are called by the tool

_drc{handle} – used for parameter checking generate{handle} – generate the #define statements passed up to the include file

 These functions can call any other functions provided by Tcl

 The data model API is located in \data\datastructure \data\libgen

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

Design Rule Check (DRC) proc mydrc { handle } { } The DRC function could be any Tcl code which checks your parameters for correctness. The DRC procedures can access (read- only) the Platform Specification Format database (built by the LibGen tool using the MHS and the MSS files) to read the parameter values that you set. The “handle” is a handle to the current driver in the database. The DRC procedure can get the driver parameters from this handle. It can also get any other parameter from the database by first requesting for a handle and using the handle to get the parameters. For errors, DRC procedures would call the Tcl error command error "error msg", which displays in an error dialog box. For warnings, DRC procedures return a string value which can be printed on the console. On success, DRC procedures just return without any value.

Driver Generation (Generate) Section proc mygenerate { handle } { } Generate could be any Tcl code which reads your parameters and generates configuration files for the driver. The configuration files can be C files, header files, or makefiles. The generate procedures can access (read-only) the Platform Specification Format database (built by the LibGen tool using the MHS and the MSS files) to read the parameter values of the driver that you set. The “handle” is a handle to the current driver in the database. The generate procedure can get the driver parameters from this handle. It can also get any other parameter from the database, by first requesting for a handle and using the handle to get the parameter. Tcl File

Example: UartLite Driver C:\xilinx\10.1\EDK\sw\XilinxProcessorIPLib\drivers\uartlite_v2_1_0\data\uartlite_v2_1_0.tcl

proc generate {drv_handle} Software Driver: { Script inserts into xdefine_include_file $drv_handle "xparameters.h" xparameters.h "XUartLite" "NUM_INSTANCES" "C_BASEADDR" "C_HIGHADDR" "DEVICE_ID" "C_BAUDRATE" "C_USE_PARITY" "C_ODD_PARITY" "C_DATA_BITS“ xdefine_config_file $drv_handle "xuartlite_g.c" Include "XUartLite" "DEVICE_ID" "C_BASEADDR" Hardware Parameters "C_BAUDRATE" "C_USE_PARITY" "C_ODD_PARITY" "C_DATA_BITS" } Configure Hardware Parameters

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

For more information about the Tcl file, see the Development System Reference Guide, Chapter 3, “Tcl” (in the ISE tool, select Help → Software Manuals). Tcl Example

proc Ethernet_drc {handle} { set sw_processor [xget_libgen_proc_handle] set processor [xget_handle $sw_processor "IPINST"] set periphs_list [xget_proc_slave_periphs $processor] set found 0 foreach periph $periphs_list { set periphname [xget_value $periph] if {$periphname == "plb_temac"} { set found 1 } if {$periphname == "opb_emac"} { set found 1 } if {$periphname == "opb_emaclite"} { set found 1 } } if {$found == 0} { error "Ethernet module not present \n" "" "MDT_ERROR" return } }

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

This script verifies the presence of the device controller before installing the driver. In this case, it did not find one.

Note to Facilitator: This slide is best suited for advanced students. System Development Flow

Standard Embedded Software Flow Standard Embedded Hardware Flow Source Code (C code) MHS File Source Code Processor IP system.mhs (VHDL/Verilog) MPD Files MSS File Driver MDD Compile system.mss Files PlatGen Synthesis

LibGen Object Files Board EDIF Library MLD XBD Files IP Netlists Files Link Libraries FPGA Implementation system.ucf (ISE/Xflow)

Executable Data2Mem Create FPGA Programming (system.bit)

download.bit

Hardware

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

MDD and Tcl files define reusable driver interfaces. These are combined in an MSS file to generate the drivers automatically. Cores can be reconfigured without changing the driver. MSS Drivers and Libraries

 A driver is listed for every MHS core instance If a driver is not required, then a generic driver is defined  Parameters can be defined for each parameter listed in the Microprocessor Driver Description (MDD) or Microprocessor Library Definition (MLD) file  If a parameter is not listed, then the default value defined on the MDD or MLD file is used  The relationship of the MSS to the MDD is similar to that of the MHS to the Microprocessor Peripheral Description (MPD) Similar in syntax MDD contains default values; an MSS entry will override

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

When you instantiate the hardware, the system generates the MSS file. MSS File

 The MSS file ties together the hardware definition, drivers, and libraries to provide a single API for the application developer  The MSS file lists elements in the following order Global parameters  The version is the only global parameter currently defined Driver instances Library instances OS instances  The MSS file is auto-generated by PlatGen if it does not already exist

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77

The MSS file can: •Attach drivers to hardware cores •Specify high-level library functions to be provided to the application developer •Resolve dependencies between libraries and hardware or drivers •Specify OS support required by the application MSS Example

PARAMETER VERSION = 2.2.0 BEGIN OS PARAMETER OS_NAME = standalone PARAMETER OS_VER = 1.00.a PARAMETER PROC_INSTANCE = ppc405_0 PARAMETER stdin = RS232_Uart PARAMETER stdout = RS232_Uart END BEGIN DRIVER PARAMETER DRIVER_NAME = generic PARAMETER DRIVER_VER = 1.00.a PARAMETER HW_INSTANCE = opb_v20_0 END BEGIN LIBRARY PARAMETER LIBRARY_NAME = Ethernet PARAMETER LIBRARY_VER = 1.00.a PARAMETER ARP_TABLE_SIZE = 10 PARAMETER ARP_TIMEOUT = 2 PARAMETER DHCP_TIMEOUT = 5 PARAMETER DHCP_ENABLE = 1 END

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Tips for Writing a Driver  Follow API and naming conventions Symbol names Files names Service names  Use the Xilinx-standard configuration parameters xparameters.h  Driver infrastructure standards Source code documentation Driver versions Primitive data types Error handling Communication with the application Interrupt management

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Tips for Writing a Driver

 Use Xilinx-provided data types and #define statements xbasic_types.h xstatus.h xio.h  Take advantage of the provided microprocessor services that are also part of the BSP  Leverage some of the more simple Xilinx-provided device drivers as examples and information when writing your own UartLite GPIO Both and more are located in C:\xilinx\10.1\EDK\sw\XilinxProcessorIPLib\drivers

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 API and Naming Conventions

 External identifiers – preceded by an X X_VariableName X_FunctionName(ArgumentType Argument) X_TypeName  File names x.c Main source x_functionality.c Secondary source x.h Layer 1 public interface x_l.h (or _hw.h) Layer 0/hardware x_i.h Internal interface

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Configuration Parameters

 Device information required by driver routines Contained in xparameters.h Number of devices Device ID Base address of the device in memory  Configuration data structure necessary for an instance of a device Contained in x_g.c typedef struct { u16 DeviceID; u32 BaseAddress; /* Other device dependent data attributes */ } X_Config;

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Apply Your Knowledge

 1) List the two file types that are required for LibGen to properly include a device driver into a BSP

 2) How are device driver user parameters inserted into xparameters.h by LibGen?

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Apply Your Knowledge

 3) How does the MSS file fit in when you are writing a device driver?

 4) What benefit does the Create and Import Peripheral wizard provide?

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Summary

 Plan for the requirements of device drivers at the system level  Take advantage of the Create and Import Peripheral wizard to set up a skeleton structure as a starting point for writing a driver  Leverage information and examples in existing Xilinx drivers C:\xilinx\10.1\EDK\sw\XilinxProcessorIPLib\drivers\uartlite_v2_1_0\*.*  Follow Xilinx-standard API and naming conventions  Use Xilinx data types from xbasic_types.h

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Apply Your Knowledge

 1) What services does XMD provide for the GDB debugger?

 2) Why is it recommended to set compiler optimization to none when debugging?

 3) Debuggers provide visibility into which parts of the design?

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77 Apply Your Knowledge

 4) What is profiling? What are the different targets supported in the EDK?

 5) What kind of information does the profiling library provide?

08_so_emb_rtos_libraries_drivers.odp Date Oct 31, 2009 Page SO-LOGIC electronic consulting Lustkandlg 52, Vienna, Austria, Europe, World www.so-logic.net +43-1-315 77 77