Edk Libs Ref Guide
Content
EDK OS and Libraries Reference Guide
Embedded Development Kit EDK 6.2i
UG114 (v3.0) June 22, 2004
R
R
"Xilinx" and the Xilinx logo shown above are registered trademarks of Xilinx, Inc. Any rights not expressly granted herein are reserved. CoolRunner, RocketChips, Rocket IP, Spartan, StateBENCH, StateCAD, Virtex, XACT, XC2064, XC3090, XC4005, and XC5210 are registered trademarks of Xilinx, Inc.
The shadow X shown above is a trademark of Xilinx, Inc. ACE Controller, ACE Flash, A.K.A. Speed, Alliance Series, AllianceCORE, Bencher, ChipScope, Configurable Logic Cell, CORE Generator, CoreLINX, Dual Block, EZTag, Fast CLK, Fast CONNECT, Fast FLASH, FastMap, Fast Zero Power, Foundation, Gigabit Speeds...and Beyond!, HardWire, HDL Bencher, IRL, J Drive, JBits, LCA, LogiBLOX, Logic Cell, LogiCORE, LogicProfessor, MicroBlaze, MicroVia, MultiLINX, NanoBlaze, PicoBlaze, PLUSASM, PowerGuide, PowerMaze, QPro, Real-PCI, RocketIO, SelectIO, SelectRAM, SelectRAM+, Silicon Xpresso, Smartguide, Smart-IP, SmartSearch, SMARTswitch, System ACE, Testbench In A Minute, TrueMap, UIM, VectorMaze, VersaBlock, VersaRing, Virtex-II Pro, Virtex-II EasyPath, Wave Table, WebFITTER, WebPACK, WebPOWERED, XABEL, XACTFloorplanner, XACT-Performance, XACTstep Advanced, XACTstep Foundry, XAM, XAPP, X-BLOX +, XC designated products, XChecker, XDM, XEPLD, Xilinx Foundation Series, Xilinx XDTV, Xinfo, XSI, XtremeDSP and ZERO+ are trademarks of Xilinx, Inc. The Programmable Logic Company is a service mark of Xilinx, Inc. All other trademarks are the property of their respective owners. Xilinx, Inc. does not assume any liability arising out of the application or use of any product described or shown herein; nor does it convey any license under its patents, copyrights, or maskwork rights or any rights of others. Xilinx, Inc. reserves the right to make changes, at any time, in order to improve reliability, function or design and to supply the best product possible. Xilinx, Inc. will not assume responsibility for the use of any circuitry described herein other than circuitry entirely embodied in its products. Xilinx provides any design, code, or information shown or described herein "as is." By providing the design, code, or information as one possible implementation of a feature, application, or standard, Xilinx makes no representation that such implementation is free from any claims of infringement. You are responsible for obtaining any rights you may require for your implementation. Xilinx expressly disclaims any warranty whatsoever with respect to the adequacy of any such implementation, including but not limited to any warranties or representations that the implementation is free from claims of infringement, as well as any implied warranties of merchantability or fitness for a particular purpose. Xilinx, Inc. devices and products are protected under U.S. Patents. Other U.S. and foreign patents pending. Xilinx, Inc. does not represent that devices shown or products described herein are free from patent infringement or from any other third party right. Xilinx, Inc. assumes no obligation to correct any errors contained herein or to advise any user of this text of any correction if such be made. Xilinx, Inc. will not assume any liability for the accuracy or correctness of any engineering or software support or assistance provided to a user. Xilinx products are not intended for use in life support appliances, devices, or systems. Use of a Xilinx product in such applications without the written consent of the appropriate Xilinx officer is prohibited. The contents of this manual are owned and copyrighted by Xilinx. Copyright 1994-2004 Xilinx, Inc. All Rights Reserved. Except as stated herein, none of the material may be copied, reproduced, distributed, republished, downloaded, displayed, posted, or transmitted in any form or by any means including, but not limited to, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Xilinx. Any unauthorized use of any material contained in this manual may violate copyright laws, trademark laws, the laws of privacy and publicity, and communications regulations and statutes.
EDK OS and Libraries Reference Guide
www.xilinx.com 1-800-255-7778
UG114 (v3.0) June 22, 2004
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
The following table shows the revision history for this document.
Version
01/30/04 03/12/04 03/19/04 06/22/04 2.0 3.0 1.0 Initial release for EDK 6.2i. Updated for service pack release. Updated for service pack release. Updated for service pack release.
Revision
UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide
EDK OS and Libraries Reference Guide
www.xilinx.com 1-800-255-7778
UG114 (v3.0) June 22, 2004
R
Preface
About This Guide
This book describes the software packages provided by the Embedded Development Kit (EDK).
Guide Contents
This book contains the following chapters.
x x x x x x x x x x
Chapter 1, “Introduction” Chapter 2, “Xilinx Microkernel (XMK)” Chapter 3, “LibXil Standard C Libraries” Chapter 4, “Standalone Board Support Package” Chapter 5, “Xilkernel” Chapter 6, “LibXil Net” Chapter 7, “LibXil File” Chapter 8, “LibXil FATFile System (FATfs)” Chapter 9, “LibXil Memory File System (MFS)” Chapter 10, “LibXil Profile”
Additional Resources
For additional information, go to http://support.xilinx.com. The following table lists some of the resources you can access from this website. You can also directly access these resources using the provided URLs.
Resource
EDK Home
Description/URL
Embedded Development Kit home page, FAQ and tips. http://www.xilinx.com/edk
EDK Examples Tutorials
A set of complete EDK examples. http://www.xilinx.com/ise/embedded/edk_examples.htm Tutorials covering Xilinx design flows, from design entry to verification and debugging http://support.xilinx.com/support/techsup/tutorials/index.htm
Answer Browser
Database of Xilinx solution records http://support.xilinx.com/xlnx/xil_ans_browser.jsp
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
5
R
Preface: About This Guide
Resource
Application Notes
Description/URL
Descriptions of device-specific design techniques and approaches http://support.xilinx.com/apps/appsweb.htm
Data Sheets
Device-specific information on Xilinx device characteristics, including readback, boundary scan, configuration, length count, and debugging http://support.xilinx.com/xlnx/xweb/xil_publications_index.jsp
Problem Solvers Tech Tips
Interactive tools that allow you to troubleshoot your design issues http://support.xilinx.com/support/troubleshoot/psolvers.htm Latest news, design tips, and patch information for the Xilinx design environment http://www.support.xilinx.com/xlnx/xil_tt_home.jsp The entire set of GNU manuals http://www.gnu.org/manual
GNU Manuals
Conventions
This document uses the following conventions. An example illustrates each convention.
Typographical
The following typographical conventions are used in this document:
Convention
Courier font
Meaning or Use
Messages, prompts, and program files that the system displays Literal commands that you enter in a syntactical statement Commands that you select from a menu Keyboard shortcuts Variables in a syntax statement for which you must supply values
Example
speed grade: - 100
Courier bold
ngdbuild design_name
Helvetica bold
File o Open Ctrl+C
ngdbuild design_name See the Development System Reference Guide for more information. If a wire is drawn so that it overlaps the pin of a symbol, the two nets are not connected.
Italic font
References to other manuals
Emphasis in text
6
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Conventions
R
Convention
Meaning or Use
An optional entry or parameter. However, in bus specifications, such as bus[7:0], they are required. A list of items from which you must choose one or more
Example
ngdbuild [option_name] design_name
Square brackets [ ]
Braces { } Vertical bar |
lowpwr ={on|off} lowpwr ={on|off} IOB #1: Name = QOUT’ IOB #2: Name = CLKIN’ . . . allow block block_name loc1 loc2 ... locn;
Separates items in a list of choices
Vertical ellipsis . . . Horizontal ellipsis . . .
Repetitive material that has been omitted
Repetitive material that has been omitted
Online Document
The following conventions are used in this document:
Convention
Meaning or Use
Cross-reference link to a location in the current document Cross-reference link to a location in another document Hyperlink to a website (URL)
Example
See the section “Additional Resources” for details. Refer to “Title Formats” in Chapter 1 for details. See Figure 2-5 in the Virtex-II Handbook. Go to http://www.xilinx.com for the latest speed files.
Blue text
Red text Blue, underlined text
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
7
R
Preface: About This Guide
8
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Table of Contents
Preface: About This Guide
Guide Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Typographical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Online Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1: Introduction Chapter 2: Xilinx Microkernel (XMK)
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 XMK Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 3: LibXil Standard C Libraries
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard C Library (libc.a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilinx C Library (libxil.a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input/Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21 21 22 22
23 MicroBlaze Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 PowerPC 405 Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 23 23 24 24 24 24
Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MicroBlaze Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer Arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerPC 405 Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer Arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 4: Standalone Board Support Package
MicroBlaze BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_enable_interrupts(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_disable_interrupts(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Instruction Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_enable_icache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_disable_icache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_update_icache (int tag, int instr, int lock_valid) . . . . . . . . . . . . . . . . . void microblaze_init_icache_range (int cache_addr, int cache_size) . . . . . . . . . . . . . . . Data Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_enable_dcache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_disable_dcache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 25 25 25 25 26 26 26 26 26 26
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
9
R
void microblaze_update_dcache (int tag, int data, int lock_valid) . . . . . . . . . . . . . . . . . 27 void microblaze_init_dcache_range (int cache_addr, int cache_size) . . . . . . . . . . . . . . . 27
Fast Simplex Link Interface Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_bread_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_bwrite_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_nbread_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_nbwrite_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_bread_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_bwrite_cntlfsl(val, id). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_nbread_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_nbwrite_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Boot Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . boot.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . crt0.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . eabi.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_WriteCCR0(unsigned int val);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_EnableDCache(unsigned int regions);. . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_DisableDCache(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_FlushDCacheLine(unsigned int adr); . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_StoreDCacheLine(unsigned int adr);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_EnableICache(unsigned int regions); . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_DisableICache(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_InvalidateICache(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_InvalidateICacheLine(unsigned int adr); . . . . . . . . . . . . . . . . . . . . . . . . . Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XExc_Init(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27 27 27 27 27 27 27 28 28 28 28 28 28 28 29 29 29 29 29 29 29 30 30 30 30
PowerPC BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
void XExc_RegisterHandler(Xuint8 ExceptionId, XExceptionHandler Handler, void *DataPtr);31 void XExc_RemoveHandler(Xuint8 ExceptionId). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 void XExc_mEnableExceptions (EnableMask); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 void XExc_mDisableExceptions (DisableMask); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int read(int fd, char *buf, int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int write(int fd, char *buf, int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int isatty(int fd); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . char *sbrk(int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processor-Specific Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . typedef unsigned long long XTime; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_SetTime(XTime xtime); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_GetTime(XTime *xtime); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_TSRClearStatusBits(unsigned long Bitmask); . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITSetInterval(unsigned long interval); . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITEnableInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITDisableInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITEnableAutoReload(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITDisableAutoReload(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITClearInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unsigned int usleep(unsigned int __useconds); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unsigned int sleep(unsigned int __seconds); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32 32 32 32 33 33 33 33 33 33 33 33 33 34 34 35 35 35 35 35 36
10
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
int nanosleep(const struct timespec *rqtp, struct timespec *rmtp); . . . . . . . . . . . . . . . . . 36
Chapter 5: Xilkernel
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Xilkernel Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel Process Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel Scheduling Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mutex Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic Block Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 37 38 39 39 41 42 43 43 45 50 55 59 62 65
Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Kernel Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Customizing STDIN and STDOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing User Initialization Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Message Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Pthread Mutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Dynamic Block Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Linker Script (PPC405) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring System Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Debug Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copy Kernel Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 71 72 73 73 74 74 74 75 75 76 77 77 77 78 78 78 79 79 80 80 80 80
Debugging Xilkernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Footprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel File Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Future Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Xilkernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 6: LibXil Net
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 LibXilNet Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
11
R
Quick Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Protocols Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Library Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Protocol Function Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Media Access Layer (MAC) Drivers Wrapper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ethernet Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ARP (RFC 826) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IP (RFC 791) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ICMP (RFC 792) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UDP (RFC 768) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TCP (RFC 793) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 87 87 87 87 87 88 88 88
Current Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Functions of LibXilNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Using XilNet in Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Chapter 7: LibXil File
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Libgen Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
101 101 101
104 LibXil File Instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Chapter 8: LibXil FATFile System (FATfs)
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 XilFatfs Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Detailed Description of XilFatfsFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Chapter 9: LibXil Memory File System (MFS)
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 MFS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Quick Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Detailed summary of MFS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-like access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
120 121 121 121
Chapter 10: LibXil Profile
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
12
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Profiling Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing xilprofile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
123 124 124
124 Application Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Generating GPROF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 XilProfile Code Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Chapter 11: lwIP Library
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerPC System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MicroBlaze System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up lwIP in EDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
129 129 130 131
131 libgen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Initializing lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 lwIP Raw API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Designing an lwIP Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Raw APO Functions for TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Example lwIP Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
PowerPC based Echo Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MicroBlaze-Based Echo Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 135 150 150
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
13
R
14
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 1
Introduction
This book describes the software packages that are provided by the Embedded Development Kit. EDK supplies libraries, board support packages, and complete operating systems, in addition to the drivers for the peripherals, to help the user develop a software platform. The following is the distribution of the software packages available for the user to include in his platform:
x
Xilinx Micro-Kernel (XMK) - XMK is the entity representing the collective software system formed by the following components,
i i i i i i i
Standard C Libraries (libc, libm) Xilkernel - An embedded kernel Standalone Board Support Package (BSP) LibXil Net - A networking library LibXil MFS - A Memory File System LibXil File - A file I/O library LibXil Drivers - Device drivers for supported peripherals
x
VxWorks Operating System
The software platform can be defined using XPS’s Software Platform Settings dialog box. Figure 1-1 shows a snapshot of the dialog box. In this example, the user is choosing the Xilnet and Xilfile libraries, along with the Xilkernel operating system. This guide documents the Xilinx Micro-kernel, its constituent libraries and the Standalone board-support package. Documentation for the other operating systems can be found in their respective reference guides. Device drivers are documented along with the corresponding peripheral’s documentation.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
15
R
Chapter 1: Introduction
Figure 1-1: Software Platform Settings in XPS
16
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 2
Xilinx Microkernel (XMK)
This chapter describes the organization of Xilinx Microkernel, its constituent component libraries and the interactions between them and the user application. The chapter contains the following sections.
x x
“Overview” “XMK Organization”
Overview
There are three distinct software entities in XMK, with which user applications can interface - Standard C and Math libraries, LibXil libraries and Xilkernel or Standalone operating systems. The Standard C support library consists of the newlib libc, which contains the standard C functions such as stdio, stdlib and string routines. The math library is an enhancement over the newlib math library libm and provides the standard math routines. The LibXil libraries consist of,
x x x x x
LibXil Driver - Xilinx device drivers LibXil Net - Xilinx networking support LibXil File - Xilinx file I/O functions LibXil MFS - Xilinx memory file system LibXil Profile - Xilinx profiling support
The Xilinx Standalone Board Support Package (BSP) and Xilkernel are the two operating system choices that are provided, in XMK, that can be included in the user application’s software platform. Most of the routines in the library are written in C and can be ported to any platform. The Library Generator (LibGen) configures the libraries for an embedded processor, using the attributes defined in the Microprocessor Software Specification (MSS) file.
XMK Organization
The structure of XMK is outlined in Figure 2-1. As shown in the figure, the user application can interface with the XMK components in a variety of ways. The libraries are independent of each other, except for a few interactions and dependencies between each other. For example, Xilkernel internally uses the standalone BSP and LibXil File can optionally work with the LibXil MFS. The LibXil Drivers and the standalone BSP form the lowermost hardware abstraction layer. All the library and OS components of XMK rely on standard C library components. The math library, libm.a is also available for linking with the user
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
17
R
Chapter 2: Xilinx Microkernel (XMK)
applications. Users can mix and match the component libraries, but there may be some restrictions and implications. This will be described in the reference guides of each component.
User Application
libc
stdio stdlib
Xil Kernel
LibXil Net
LibXil File
LibXil Mfs
LibXil Profile
string Other
libm
Standalone BSP LibXil Driver
Hardware
X10143
Figure 2-1: XMK Structure
The Standalone Board Support Package (BSP) is a bare-bones kernel. It provides a very thin interface to the hardware, offering minimal functionality that will be required by applications. Some typical functions offered by the standalone BSP include setting up the interrupt system, exception system, configuring caches and other hardware specific functions. Certain standalone board support files such as the crt0.S, boot.S and eabi.S are required for the powerpc processor. These files are provided in the EDK. For a detailed description, refer to Chapter 4, “Standalone Board Support Package.” LibXil Driver refers to the device drivers that are included in the software platform to provide an interface to the peripherals in the system. These drivers are provided along with EDK and are configured by libgen. This book contains a chapter that briefly discusses the concept of device drivers and the way they fit in with the software platform, in EDK. Refer to the “Device Drivers Programmer Guide” chapter in the Processor IP Reference Guide for this documentation. Device Drivers are documented in further detail, with information about functionality, interface, configuration and headers file information, in the Xilinx Device Drivers Reference Guide. Xilkernel (1) is a simple embedded processor kernel, which can be customized to a great degree for a given system. Xilkernel has the key features of an embedded kernel like multitasking, priority-driven preemptive scheduling, inter-process communication, synchronization facilities, interrupt handling etc. It is small, modular, user customizable and can be used in different system configurations. It is different from the other libraries, (as indicated in Figure 2-1 in that, it can be in a separate executable file from the user application. The user application can dynamically link with Xilkernel through a system call interface. Applications can also statically link with Xilkernel, in a different mode, and form a single executable. Complete details are available in Chapter 5, “Xilkernel.” LibXil Net provides networking support using a simple TCP/IP stack based library, which can be used for network related projects. For complete details, refer to Chapter 6, “LibXil Net.”
1. Previous EDK releases supported the library version of Xilkernel, which is now deprecated. Refer to Chapter 5, “Xilkernel” for documentation on LibXilkernel.
18
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
XMK Organization
R
LibXil File provides stream based file system and device access through interfaces such as open, close, read and write. The standard newlib libc contains dummy functions for most of the operating system specific function calls such as open, close, read, write. These routines are included in the libgloss component of the standard libc library. The LibXil File module contains routines to overwrite these dummy functions. The routines interact with file systems such as Xilinx Memory File System and peripheral devices such as UART, UARTLITE and GPIO. For complete details refer to Chapter 7, “LibXil File.” LibXil MFS provides a simple memory based file system, which allows easy access to data using file based input-output. This system can be easily configured to meet project requirements by changing the source provided in the installation area. This module is discussed in detail in Chapter 9, “LibXil Memory File System (MFS).” LibXil Profile provides a mechanism to perform call-graph and histogram profiling and produces the profile data in a format that can be analyzed using GNU gprof. For details refer to Chapter 10, “LibXil Profile.” User applications will need to include appropriate headers and link with required libraries for proper compilation and inclusion of required functionality. These libraries and their corresponding include files are created in the processor’s lib and include directories, under the current project, respectively. The -I and -L options of the compiler being used should be leveraged to add these directories to the search paths. Libgen is used to tailor the compilation of each software component described above. Refer to the chapters on Libgen and Microprocessor Software Specification in the Embedded Systems Tools Reference Guide for more information.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
19
R
Chapter 2: Xilinx Microkernel (XMK)
20
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 3
LibXil Standard C Libraries
This chapter describes the software libraries available for the embedded processors. The chapter contains the following sections.
x x x x x x
“Overview” “Standard C Library (libc.a)” “Xilinx C Library (libxil.a)” “Input/Output Functions” “Memory Management Functions” “Arithmetic Operations”
Overview
The Embedded Processor Design Kit (EDK) libraries and device drivers provide standard C library functions, as well as functions to access peripherals. The EDK libraries are automatically configured by libgen for every project based upon the Microprocessor Software Specification file. These libraries and include files are saved in the current project’s lib and include directories respectively. The -I and -L options of mb-gcc should be used to add these directories to its library search paths.
Standard C Library (libc.a)
The standard C library libc.a contains the standard C functions compiled for MicroBlaze or PowerPC. For a list of all the supported functions refer to the following files in XILINX_EDK/gnu/processor/platform/include where
x x x
processor = powerpc-eabi or microblaze platform = sol, nt or lin XILINX_EDK = Installation directory
_ansi.h _syslist.h ar.h assert.h ctype.h dirent.h errno.h fastmath.h fcntl.h float.h grp.h ieeefp.h limits.h locale.h machine/ malloc.h math.h paths.h process.h pthread.h pwd.h reent.h regdef.h setjmp.h signal.h stdarg.h stddef.h stdio.h stdlib.h string.h sys/ termios.h time.h unctrl.h unistd.h utime.h utmp.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
21
R
Chapter 3: LibXil Standard C Libraries
Programs accessing standard C library functions must be compiled as follows: For MicroBlaze
mb-gcc C files
For PowerPC
powerpc-eabi-gcc C files
The libc library is included automatically. The -lm option should be specified for programs that access libm math functions. Refer to “MicroBlaze Application Binary Interface,” (ABI) in the MicroBlaze Processor Reference Guide for information on the C Runtime Library
Xilinx C Library (libxil.a)
The Xilinx C library libxil.a contains the following functions for the MicroBlaze embedded processor:
_exception_handler.o _interrupt_handler.o _program_clean.o _program_init.o xil_malloc.o xil_sbrk.o
Default exception and interrupt handlers are provided. A memory management targeted for embedded systems is provided in the xil_malloc.o file. The libxil.a library is included automatically. Programs accessing Xilinx C library functions must be compiled as follows:
mb-gcc C files
Input/Output Functions
The EDK libraries contains standard C functions for I/O, such as printf and scanf. These are large and may not be suitable for embedded processors. In addition, the EDK processors (MicroBlaze and PowerPC405) library provides the following smaller I/O functions:
void print (char *)
This function prints a string to the peripheral designated as standard output in the MSS file. This function outputs the passed string as is and there is no interpretation of the string passed. For example, a “\n” passed is interpreted as a new line character and not as a carriage return and a new line as is the case with ANSI C printf function.
void putnum (int)
This function converts an integer to a hexadecimal string and prints it to the peripheral designated as standard output in the MSS file.
void xil_printf (const *char ctrl1, ...)
This function is similar to printf but much smaller in size (only 1KB). It does not have support for floating point numbers. xil_printf also does not support printing of long long (i.e 64 bit numbers). The prototypes for these functions are in stdio.h.
22
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Memory Management Functions
R
Please refer to the “Microprocessor Software Specification (MSS)” chapter in the Embedded System Tools Guide for information on setting the standard input and standard output devices for a system.
Memory Management Functions
MicroBlaze Processor
Memory management routines such as malloc, calloc and free can run the gamut of high functionality (with associated large size) to low functionality (and small size). By default, the MicroBlaze processor library only supports a simple, small malloc, and a dummy free. Hence when memory is allocated using malloc, this memory cannot be reused. In addition to the simple version, we have now extended the standalone BSP to include xil_malloc, xil_free and xil_calloc function. In the Standalone OS block, if the PARAMETER need_xil_malloc is set to TRUE, calls to malloc result in a call to xil_malloc and the same for free and calloc. These functions are a lighter version of the newlib based malloc and free, but have the same functionality. The _STACK_SIZE option to mb-gcc specifies the total memory allocated to stack and heap. The stack is used for function calls, register saves, and local variables. All calls to malloc allocate memory from heap. The stack pointer initially points to the bottom (high end) of memory, and grows toward low memory; the heap pointer starts at low memory and grows toward high memory. The size of the heap cannot be increased at runtime. The return value of malloc must always be checked to ensure that it could actually allocate the memory requested. Please note that whereas malloc checks that the memory it allocates does not overwrite the current stack pointer, updates to the stack pointer do not check if the heap is being overwritten. Increasing the _STACK_SIZE may be one way to solve unexpected program behavior. Refer to “Linker Options” in the “GNU Compiler Tools” chapter of the Embedded System Tools Guide for more information on increasing the stack size.
PowerPC 405 Processor
PowerPC 405 processor supports all standard C library memory management functions such as malloc(), calloc(), free().Similar to MicroBlaze, the lighter version of malloc and free i.e xil_malloc and xil_free can be used for PowerPC when the standalone BSP package is used.
Arithmetic Operations
MicroBlaze Processor
Integer Arithmetic
Integer addition and subtraction operations are provided in hardware. By default, integer multiplication is done in software using the library function mulsi3_proc. Integer multiplication is done in hardware if the mb-gcc option -mno-xl-soft-mul is specified.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
23
R
Chapter 3: LibXil Standard C Libraries
Integer divide and mod operations are done in software using the library functions divsi3_proc and modsi3_proc. MicroBlaze processor can also be customized to use a hard divider, in which case the div instruction is used in place of the divsi3_proc library routine. Double precision multiplication, division and mod functions are carried out by the library functions muldi3_proc, divdi3_proc and moddi3_proc respectively.
Floating Point Arithmetic
All floating point addition, subtraction, multiplication and division operations are also implemented using software functions in the C library.
PowerPC 405 Processor
Integer Arithmetic
Integer addition and subtraction operations are provided in hardware. Hence no specific software library is available for the PowerPC processor.
Floating Point Arithmetic
The PowerPC processor supports all floating point arithmetic implemented in the standard C library.
24
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 4
Standalone Board Support Package
The Board Support Package (BSP) is a set of software modules used to access processor specific functions. The standalone BSP is used when an application accesses board/processor features directly (without an intervening Operating System layer). This chapter contains the following sections.
x x
“MicroBlaze BSP” “PowerPC BSP”
MicroBlaze BSP
When the user system contains a MicroBlaze processor and no Operating System, the Library Generator automatically builds the standalone BSP in the project library libxil.a.
Interrupt Handling
The microblaze_enable_interrupts.s and microblaze_disable_interrupts.s files contain functions to enable and disable interrupts on the MicroBlaze.
void microblaze_enable_interrupts(void)
This function enables interrupts on the MicroBlaze. When the MicroBlaze starts up, interrupts are disabled. Interrupts must be explicitly turned on using this function.
void microblaze_disable_interrupts(void)
This function disables interrupts on the MicroBlaze. This function may be called when entering a critical section of code where a context switch is undesirable.
Instruction Cache Handling
The microblaze_enable_icache.s and microblaze_disable_icache.s files contain functions to enable and disable the instruction cache on MicroBlaze.
void microblaze_enable_icache(void)
This functions enables the instruction cache on MicroBlaze. When MicroBlaze starts up, the instruction cache is disabled. The ICache must be explicitly turned on using this function.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
25
R
Chapter 4: Standalone Board Support Package
void microblaze_disable_icache(void)
This function disables the instruction cache on MicroBlaze.
void microblaze_update_icache (int tag, int instr, int lock_valid)
This function updates the cache tag with the appropriate instr. The function disables the cache before updating the tag line. The MSR is restored back to its original value after the cache is updated. This function can also be used to invalidate and lock the cache depending on the value of the lock_valid parameter. The effect of this parameter is summarized in Table 4-1.
Table 4-1: Lock
0 0
Effect of lock_valid parameter Valid
0 1
lock_valid
0 1 Invalidate Cache
Effect
Valid, but unlocked cacheline. The same cacheline can be used for more than one addresses, if required.The previous address will be swapped out of the cache and written to the memory Invalidate Cache, No effect of lock bit Valid cache and locked cacheline. The cacheline is now locked to a particular address. Other addresses cannot use this cacheline.
1 1
0 1
2 3
void microblaze_init_icache_range (int cache_addr, int cache_size)
The icache can be initialized using the function microblaze_init_icache_range. This function can be used for initializing the entire icache or only a part of it. The parameter cache_addr indicate the beginning of the cache location, which is to be initialized. The cache_size represents the size from cache_addr, which needs to be initialized. For example, microblaze_init_icache_range (0x00000300, 0x100) will initialize the instruction cache region between 0x300 to 0x3ff (0x100 bytes of cache memory is cleared starting from 0x300).
Data Cache Handling
The microblaze_enable_dcache.s and microblaze_disable_dcache.s files contain functions to enable and disable the data cache on MicroBlaze.
void microblaze_enable_dcache(void)
This functions enables the data cache on MicroBlaze. When MicroBlaze starts up, the data cache is disabled. The Dcache must be explicitly turned on using this function.
void microblaze_disable_dcache(void)
This function disables the instruction cache on MicroBlaze.
26
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
MicroBlaze BSP
R
void microblaze_update_dcache (int tag, int data, int lock_valid)
This function updates the cache tag with the appropriate data. The function disables the cache before updating the tag line. The MSR is restored back to its original value after the cache is updated. This function can also be used to invalidate and lock the cache, depending on the value of the lock_valid parameter. The effect of this parameter is summarized in Table 4-1.
void microblaze_init_dcache_range (int cache_addr, int cache_size)
The icache can be initialized using the function microblaze_init_dcache_range. This function can be used for initializing the entire icache or only a part of it. The parameter cache_addr indicate the beginning of the cache location, which is to be initialized. The cache_size represents the size from cache_addr, which needs to be initialized. For example, microblaze_init_dcache_range (0x00000300, 0x100) will initialize the data cache region between 0x300 to 0x3ff (0x100 bytes of cache memory is cleared starting from 0x300).
Fast Simplex Link Interface Macros
The Fast Simplex Link (FSL) interfaces on MicroBlaze can be used in several ways.
microblaze_bread_datafsl(val, id)
This macro performs a blocking data get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_bwrite_datafsl(val, id)
This macro performs a blocking data put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_nbread_datafsl(val, id)
This macro performs a non-blocking data get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_nbwrite_datafsl(val, id)
This macro performs a non- blocking data put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_bread_cntlfsl(val, id)
This macro performs a blocking control get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_bwrite_cntlfsl(val, id)
This macro performs a blocking control put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
27
R
Chapter 4: Standalone Board Support Package
microblaze_nbread_cntlfsl(val, id)
This macro performs a non-blocking control get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_nbwrite_cntlfsl(val, id)
This macro performs a non-blocking data control function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
PowerPC BSP
When the user system contains a PowerPC, and no Operating System, the Library Generator automatically builds the Stand-Alone BSP in the project library libxil.a. The Stand-Alone BSP contains boot code, cache, file and memory management, configuration, exception handling, time and processor specific include functions.
Boot Code
The boot.S, crt0.S, and eabi.S files contain a minimal set of code for initializing the processor and starting an application.
boot.S
Code in the boot.S consists of the two sections boot and boot0. The boot section contains only one instruction that is labeled with _boot. During the link process, this instruction is mapped to the reset vector and the _boot label marks the application’s entry point. The boot instruction is a jump to the _boot0 label. The _boot0 label must reside within a ±23-bit address space of the _boot label. It is defined in the boot0 section. The code in the boot0 section calculates the 32-bit address of the _start label and jumps to it.
crt0.S
Code in the crt0.S file starts executing at the _start label. It initializes the .sbss and .bss sections to zero, as required by the ANSI C specification, sets up the stack, initializes some processor registers, and calls the main() function. The program remains in an endless loop on return from main().
eabi.S
When an application is compiled and linked with the -msdata=eabi option, GCC inserts a call to the __eabi label at the beginning of the main() function. This is the place where register R13 must be set to point to the .sdata and .sbss data sections and register R2 must be set to point to the .sdata2 read-only data section. Code in eabi.S sets these two registers to the correct values. The _SDA_BASE_ and _SDA2_BASE_ labels are generated by the linker.
Cache
The xcache_l.c file and corresponding xcache_l.h include file provide access to cache and cache-related operations.
28
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
PowerPC BSP
R
void XCache_WriteCCR0(unsigned int val);
The XCache_WriteCCR0() function writes an integer value to the CCR0 register. Below is a sample code sequence. Before writing to this register, the instruction cache must be enabled to prevent a lockup of the processor core. After writing the CCR0, the instruction cache can be disabled, if not needed.
... XCache_EnableICache(0x80000000) /* enable instruction cache for first 128 MB memory region */ XCache_WriteCCR0(0x2700E00) /* enable 8 word pre-fetching */ XCache_DisableICache() /* disable instruction cache */ ...
void XCache_EnableDCache(unsigned int regions);
The XCache_EnableDCache() function enables the data cache for a specific memory region. Each bit in the regions parameter represents 128 MB of memory. A value of 0x80000000 enables the data cache for the first 128 MB of memory (0 - 0x7FFFFFF). A value of 0x1 enables the data cache for the last 128 MB of memory (0xF8000000 - 0xFFFFFFFF).
void XCache_DisableDCache(void);
The XCache_DisableDCache() function disables the data cache for all memory regions.
void XCache_FlushDCacheLine(unsigned int adr);
The XCache_FlushDCacheLine() function flushes and invalidates the data cache line that contains the address specified by the adr parameter. A subsequent data access to this address results in a cache miss and a cache line refill.
void XCache_StoreDCacheLine(unsigned int adr);
The XCache_StoreDCacheLine() function stores in memory the data cache line that contains the address specified by the adr parameter. A subsequent data access to this address results in a cache hit if the address was already cached; otherwise, it results in a cache miss and cache line refill.
void XCache_EnableICache(unsigned int regions);
The XCache_EnableICache() function enables the instruction cache for a specific memory region. Each bit in the regions parameter represents 128 MB of memory. A value of 0x80000000 enables the instruction cache for the first 128 MB of memory (0 - 0x7FFFFFF). A value of 0x1 enables the instruction cache for the last 128 MB of memory (0xF8000000 - 0xFFFFFFFF).
void XCache_DisableICache(void);
The XCache_DisableICache() function disables the instruction cache for all memory regions.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
29
R
Chapter 4: Standalone Board Support Package
void XCache_InvalidateICache(void);
The XCache_InvalidateICache() function invalidates the whole instruction cache. Subsequent instructions produce cache misses and cache line refills.
void XCache_InvalidateICacheLine(unsigned int adr);
The XCache_InvalidateICacheLine() function invalidates the instruction cache line that contains the address specified by the adr parameter. A subsequent instruction to this address produces a cache miss and a cache line refill.
Exception Handling
This section documents the exception handling API that is provided in the Board Support Package. For an in-depth explanation on how exceptions and interrupts work on the PPC405, please refer to the chapter “Exceptions and Interrupts” in the PPC User’s Manual. The exception handling API consists of a set of the files xvectors.S, xexception_l.c, and the corresponding header file xexception_l.h.
void XExc_Init(void);
This function sets up the interrupt vector table and registers a “do nothing” function for each exception. This function has no parameters and does not return a value. This function must be called before registering any exception handlers or enabling any interrupts. When using the exception handler API, this function should be called at the beginning of your main() routine. IMPORTANT: If you are not using the default linker script, you need to reserve memory space for storing the vector table in your linker script. The memory space must begin on a 64k boundary. The linker script entry should look like this example:
.vectors : { . = ALIGN(64k); *(.vectors) }
For further information on linker scripts, please refer to the Linker documentation.
30
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
PowerPC BSP
R
void XExc_RegisterHandler(Xuint8 ExceptionId, XExceptionHandler Handler, void *DataPtr);
This function is used to register an exception handler for a specific exception. It does not return a value. Please refer to Table 4-2 for a list of parameters.
Table 4-2:
Exception Handler Parameters Parameter Type
Xuint8
Parameter Name
ExceptionId
Description
Exception to which this handler should be registered. The type and the values are defined in the header file xexception_l.h. Please refer to Table 4-3 for possible values. Pointer to the exception handling function User value to be passed when the handling function is called
Handler DataPtr
XExceptionHandler void *
Table 4-3:
Registered Exception Types and Values Exception Type Value
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
XEXC_ID_JUMP_TO_ZERO XEXC_ID_MACHINE_CHECK XEXC_ID_CRITICAL_INT XEXC_ID_DATA_STORAGE_INT XEXC_ID_INSTUCTION_STORAGE_INT XEXC_ID_NON_CRITICAL_INT XEXC_ID_ALIGNMENT_INT XEXC_ID_PROGRAM_INT XEXC_ID_FPU_UNAVAILABLE_INT XEXC_ID_SYSTEM_CALL XEXC_ID_APU_AVAILABLE XEXC_ID_PIT_INT XEXC_ID_FIT_INT XEXC_ID_WATCHDOG_TIMER_INT XEXC_ID_DATA_TLB_MISS_INT XEXC_ID_INSTRUCTION_TLB_MISS_INT XEXC_ID_DEBUG_INT
The function provided as the Handler parameter must have the following function prototype:
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
31
R
Chapter 4: Standalone Board Support Package
typedef void (*XExceptionHandler)(void * DataPtr);
This prototype is declared in the xexception_l.h header file. When this exception handler function is called, the parameter DataPtr will contain the same value as you provided when you registered the handler.
void XExc_RemoveHandler(Xuint8 ExceptionId)
This function is used to deregister a handler function for a given exception. For possible values of parameter ExceptionId, please refer to Table 4-3.
void XExc_mEnableExceptions (EnableMask);
This macro is used to enable exceptions. It must be called after initializing the vector table with function exception_Init and registering exception handlers with function XExc_RegisterHandler. The parameter EnableMask is a bitmask for exceptions to be enabled. The EnableMask parameter may have the values XEXC_CRITICAL, XEXC_NON_CRITICAL or XEXC_ALL.
void XExc_mDisableExceptions (DisableMask);
This macro is called to disable exceptions. The parameter DisableMask is a bitmask for exceptions to be disabled.The DisableMask parameter may have the values XEXC_CRITICAL, XEXC_NON_CRITICAL or XEXC_ALL.
Files
File support is limited to the stdin and stdout streams. In such an environment, the following functions do not make much sense:
x x x x x
open() (in open.c) close() (in close.c) fstat() (in fstat.c) unlink() (in unlink.c) lseek() (in lseek.c)
These files are included for completeness and because they are referenced by the C library.
int read(int fd, char *buf, int nbytes);
The read() function in read.c reads nbytes bytes from the standard input by calling inbyte(). It blocks until all characters are available, or the end of line character is read. Read() returns the number of characters read. The parameter fd is ignored.
int write(int fd, char *buf, int nbytes);
The write() function in write.c writes nbytes bytes to the standard output by calling outbyte(). It blocks until all characters have been written. Write() returns the number of characters written. The parameter fd is ignored.
int isatty(int fd);
The isatty() function in isatty.c reports if a file is connected to a tty. This function always returns 1, since only the stdin and stdout streams are supported.
32
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
PowerPC BSP
R
Memory Management
char *sbrk(int nbytes);
The sbrk() function in the sbrk.c file allocates nbytes of heap and returns a pointer to that piece of memory. This function is called from the memory allocation functions of the C library.
Process
The functions getpid() in getpid.c and kill() in kill.c are included for completeness and because they are referenced by the C library.
Processor-Specific Include Files
The xreg405.h include file contains the register numbers and the register bits for the PPC 405 processor. The xpseudo-asm.h include file contains the definitions for the most often used inline assembler instructions. These inline assembler instructions can be used from drivers and user applications written in C.
Time
The xtime_l.c file and corresponding xtime_l.h include file provide access to the 64bit time base counter inside the PowerPC core. The counter increases by one at every processor cycle. The sleep.c file and corresponding sleep.h include file implement functions for tired programs. All sleep functions are implemented as busy loops.
typedef unsigned long long XTime;
The XTime type in xtime_l.h represents the Time Base register. This struct consists of the Time Base Low (TBL) and Time Base High (TBH) registers, each of which is a 32-bit wide register. The definition of XTime is as follows:
typedef unsigned long long XTime;
void XTime_SetTime(XTime xtime);
The XTime_SetTime() function in xtime_l.c sets the time base register to the value in xtime.
void XTime_GetTime(XTime *xtime);
The XTime_GetTime() function in xtime_l.c writes the current value of the time base register to variable xtime.
void XTime_TSRClearStatusBits(unsigned long Bitmask);
The XTime_TSRClearStatusBits() function in xtime_l.c is used to clear bits in the Timer Status Register (TSR). The parameter Bitmask designates the bits to be cleared. A one in any
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
33
R
Chapter 4: Standalone Board Support Package
position of the Bitmask parameter clears the corresponding bit in the TSR. This function does not return a value. The header file xreg405.h defines the following values for the Bitmask parameter:
Table 4-4:
Bitmask Parameter Values Name Value
0x80000000 0x40000000
Description
Clearing this bit disables the watchdog timer event. Clears the Watchdog Timer Interrupt Status bit. This bit is set after a watchdog interrupt occurred, or could have occurred had it been enabled. Clears the Watchdog Timer Reset Status bits. These bits Specify the kind of reset that occurred as a result of a watchdog timer event. Clears the Programmable Interval Timer Status bit. This bit is set after a PIT interrupt has occurred. Clears the Fixed Interval Timer Status bit. This bit is set after a FIT interrupt has occurred. Clears all bits in the TSR. After a Reset, the content of the TSR is not specified. Use this Bitmask to clear all bits in the TSR.
XREG_TSR_WDT_ENABLE_NEXT_WATCHDOG XREG_TSR_WDT_INTERRUPT_STATUS
XREG_TSR_WDT_RESET_STATUS_11
0x30000000
XREG_TSR_PIT_INTERRUPT_STATUS
0x08000000
XREG_TSR_FIT_INTERRUPT_STATUS
0x04000000
XREG_TSR_CLEAR_ALL
0xFFFFFFFF
Example:
XTime_TSRClearStatusBits(TSR_CLEAR_ALL);
void XTime_PITSetInterval(unsigned long interval);
The XTime_PITSetInterval() function in xtime_l.c is used to load a new value into the Programmable-Interval Timer Register. This register is a 32-bit decrementing counter clocked at the same frequency as the time-base register. Depending on the AutoReload setting the PIT is automatically reloaded with the last written value or has to be reloaded manually. This function does not return a value.
Example:
XTime_PITSetInterval(0x00ffffff);
void XTime_PITEnableInterrupt(void);
The XTime_PITEnableInterrupt() function in xtime_l.c enables the generation of PIT interrupts. An interrupt occurs when the PIT register contains a value of 1, and is then decremented. This function does not return a value. XExc_Init() must be called, the PIT interrupt handler must be registered, and exceptions must be enabled before calling this function.
34
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
PowerPC BSP
R
Example:
XTime_PITEnableInterrupt();
void XTime_PITDisableInterrupt(void);
The XTime_PITDisableInterrupt() function in xtime_l.c disables the generation of PIT interrupts. It does not return a value.
Example:
XTime_PITDisableInterrupt();
void XTime_PITEnableAutoReload(void);
The XTime_PITEnableAutoReload() function in xtime_l.c enables the auto-reload function of the PIT Register. When auto-reload is enabled the PIT Register is automatically reloaded with the last value loaded by calling the XTime_PITSetInterval function when the PIT Register contains a value of 1 and is decremented. When auto-reload is enabled, the PIT Register never contains a value of 0. This function does not return a value.
Example:
XTime_PITEnableAutoReload();
void XTime_PITDisableAutoReload(void);
The XTime_PITDisableAutoReload() function in xtime_l.c disables the auto-reload feature of the PIT Register. When auto-reload is disabled the PIT decrements from 1 to 0. If it contains a value of 0 it stops decrementing until it is loaded with a non-zero value. This function does not return a value.
Example:
XTime_PITDisableAutoReload();
void XTime_PITClearInterrupt(void);
The XTime_PITClearInterrupt() function in xtime_l.c is used to clear PIT-Interrupt-Status bit in the Timer-Status Register. This bit specifies whether a PIT interrupt occurred. You must call this function in your interrupt-handler to clear the Status bit, otherwise another PIT interrupt will occur immediately after exiting the interrupt –handler function. This function does not return a value. Calling this function is equivalent to calling XTime_TSRClearStatusBits(XREG_TSR_PIT_INTERRUPT_STATUS).
Example:
XTime_PITClearInterrupt();
unsigned int usleep(unsigned int __useconds);
The usleep() function in sleep.c delays the execution of a program by __useconds microseconds. It always returns zero. This function requires that the processor frequency (in Hz) is defined. The default value of this variable is 400MHz. This value can be overwritten in the MSS file as follows:
BEGIN PROCESSOR
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
35
R
Chapter 4: Standalone Board Support Package
PARAMETER PARAMETER PARAMETER PARAMETER END
HW_INSTANCE = PPC405_i DRIVER_NAME = cpu_ppc405 DRIVER_VER = 1.00.a CORE_CLOCK_FREQ_HZ = 20000000
The file xparameters.h can also be modified with the correct value, as follows:
#define XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ 20000000
unsigned int sleep(unsigned int __seconds);
The sleep() function in sleep.c delays the execution of a program by __seconds seconds. It always returns zero.This function requires that the processor frequency (in Hz) is defined. The default value of this variable is 400MHz. This value can be overwritten in the MSS file as follows:
BEGIN PROCESSOR PARAMETER HW_INSTANCE = PPC405_i PARAMETER DRIVER_NAME = cpu_ppc405 PARAMETER DRIVER_VER = 1.00.a PARAMETER CORE_CLOCK_FREQ_HZ = 20000000 END
The file xparameters.h can also be modified with the correct value, as follows:
#define XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ 20000000
int nanosleep(const struct timespec *rqtp, struct timespec *rmtp);
The nanosleep() function in sleep.c is currently not implemented. It is a placeholder for linking applications against the C library. It always returns zero.
36
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 5
Xilkernel
This chapter describes Xilkernel, a kernel for the Xilinx embedded processors. The chapter contains the following sections.
x x x x x x x x x x x x x x x x x x
“Overview” “Key Features” “Xilkernel Blocks” “Xilkernel Modes” “Building Xilkernel Applications” “Xilkernel Process Model” “Xilkernel Scheduling Model” “Xilkernel API” “Interrupt Handling” “Kernel Customization” “Debugging Xilkernel” “Memory Footprint” “Xilkernel File Organization” “System Initialization” “Limitations” “Future Enhancements” “Modifying Xilkernel” “User Guide”
Overview
Xilkernel is a small, robust and modular kernel that allows a very high degree of customization, letting users tailor the kernel to an optimal level both in terms of size and functionality. It supports the core features required in an embedded/real-time kernel, with a POSIX API. Xilkernel works on both the MicroBlaze and PowerPC processors. Xilkernel IPC services can be used to implement higher level services like networking, video, audio and subsequently, run applications using these services.
Key Features
Xilkernel has the following notable features:
x
An API closely supporting a subset of POSIX that targets embedded kernels.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
37
R
Chapter 5: Xilkernel
x
Kernel implementation of core functionality, such as
i i i i i i
Process Management Thread Management Synchronization services - Semaphores and Mutex Locks IPC services - Message Queues and Shared Memory Dynamic Block Memory Allocation User level interrupt handling API
x x x x x
Highly scalable kernel that can be accommodated into a given system through the inclusion or exclusion of functionality as required. Easy kernel configuration with XPS, MLD, and MSS mechanisms. Support for static task undesired specification. Configurable scheduling - priority-driven preemptive scheduling or round-robin scheduling. System call interface to the kernel.
Xilkernel Blocks
The kernel is highly modular in design. The user can select and customize the kernel modules that are needed for the application at hand. Customizing the kernel is discussed in detail in the “Kernel Customization” section (1). Figure 5-1 shows the various modules of Xilkernel.
Xilkernel Modules
User Application Eg. Webserver User Interrupts
System Call Library
Timer Interrupt for Context Switch
Xilkernel System Call Handler Thread Management Message Queue Scheduler Process Management Shared Memory Interrupt Handler
Semaphores Dynamic Buffer Management
X10131
Figure 5-1:
Xilernel Modules
1. Some of these features might not be fully supported in a given release of xilkernel
38
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel Modes
R
Xilkernel Modes
Xilkernel and user applications can be built in two different modes:
x
Separate Executable mode In this mode, the user applications and kernel can be built as separate executables. Application entry points can be specified as addresses in the MSS process/pthreads configuration, using the parameters separate_exec_process_table and separate_exec_pthread_table in libgen configuration. Applications can get services from the kernel using the system call interface. These system call wrappers can be obtained by linking the application with libsyscall.a.This mode provides the flexibility of developing and dynamically loading each application separately. The stack for the user application will have to be separately setup as a part of each elf file and the kernel does no special stack setup. xilkernel.elf is generated only if the process contexts are not configured in the next mode in the OS specification.
x
Kernel Bundled Executable mode In this mode, the user applications and kernel are bundled and built together as a single executable elf file. The entry point for an application is a function name that is specified using parameters kernel_bundled_process_table and kernel_bundled_pthread_table in the MSS. Building xilkernel using libgen generates libxilkernel.a library. This can be linked with all the user applications which need to run on xilkernel, to generate a single kernel bundled executable. Since all the user applications are part of a single executable, symbol names, such as global variables and function names, should be unique. Though user applications can directly call the sys_ prefixed system calls, they would have to lock and unlock the kernel before calling the system calls. To simplify this process, applications in single executable mode have access to a thin library layer of system call wrappers that lock the kernel, execute the system call and then unlock the kernel. Stack is setup by the kernel on behalf of the single elf applications.The kernel bundled executable mode is a superset of the separate executable mode. Applications that are separate executables can still interface with the single executable kernel image dynamically, using the system call API in libsyscall.a. These system calls will be handled by the system call handlers that are present in the kernel image.Building and linking applications in the two xilkernel modes is illustrated in Figure 5-2.
Building Xilkernel Applications
x
Applications should define __XMK__ when being compiled. Defining this flag makes available certain definitions and declarations from the GNU include files that are required by Xilkernel and applications. Therefore, -D__XMK__ should accompany the compiler flags of any user applications. In the separate executable mode, microblaze applications should use the linker flag xl-mode-xilkernel to prevent their crt code from overwriting the interrupt and exception vectors, setup by Xilkernel, in memory. In PowerPC, a different linker script other than the default linker script, must be used to prevent the crt from overwriting Xilkernel sections. This linker script should basically look to not include the boot section in the elf image. In the kernel bundle mode, Microblaze applications should use one of the two linker flags, -xl-mode-executable or -xl-mode-xmdstub, to link the final application image. The two choices depend on if XMDSTUB is used for debugging or not. In PowerPC, kernel bundle applications must use the same top-level linker script that is present in the Xilkernel source folder, within the main processor folder. For e.g if the processor
x
x
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
39
R
Chapter 5: Xilkernel
instance is called ppc405_0, then the application must use ppc405_0/libsrc/xilkernel_v2_00_a/src/linker_script.sh when forming the final kernel bundle image. This is because, this linker script configures the vectors, code and data sections, either according to the linker script configuration in the MSS, or using default values. Refer to the Xilkernel user guide and the accompanying design examples for specific illustrations of the above concepts.
Kernel Sources
Separate Executable Mode
Kernel Bundled Executable Mode
libsyscall.a xilkernel.elf
libxilkernel.a
User Sources + + libsyscall.a libsyscall.a Executable Executable
User Sources + libxilkernel.a
Kernel and Application .elf files
Kernel Bundled Application
X10129
Figure 5-2: Building Applications for Xilkernel
The system call interface for both these xilkernel modes are illustrated in Figure 5-3. Applications that are a part of the kernel image have the advantage of relatively smaller system call latency as compared to those in separate executable mode, which requires another layer of indirection in the system call handler level.
40
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel Process Model
R
Pure Separate Executable Mode Scenario User Space
Kernel Bundled Executable Mode Scenario User Space
Proc1
Proc2
Proc3
Proc4
Proc5
Proc6
System Call Handler
Proc1 Proc2 Proc3
System Call Handler
System Call Wrappers
xilkernel.elf
libxilkernel.a
Kernel Image
Kernel Image
X10128
Figure 5-3: Xilkernel System Call Interface
Debugging applications in the two modes is different. See the “Debugging Xilkernel” section for more details about debugging the applications and the kernel.
Xilkernel Process Model
Xilkernel supports the concepts of, both, processes and threads. Processes as well as threads are multiplexed on top of process contexts in the kernel. Scheduling is done at the process context level. Therefore threads and processes contend among each other for getting scheduled on the processor. The only distinction between threads and processes in Xilkernel is that, except for pthread_create, all other pthread_ calls, are valid only from within threads. This includes the basic pthread interfaces and the pthread_mutex interfaces that are supported by Xilkernel. All the other interfaces work exactly the same irrespective of whether they are invoked from threads or processes. Both threads and processes could be statically created from separate elf files or from locations within a single elf file. Threads are not light-weight in any respect, as compared to processes. There is no protection between memory segments and therefore both processes and threads can share each other’s memory. The only other difference processes and threads is that processes that are created dynamically are assumed to be elf files that have a stack allocated as a part of the elf file image. Depending on the programming model that the user employs, either processes or threads or a mixture of both might be chosen for the system design. From henceforth in this document, the term processes would encompass both threads and processes, while threads would refer to pthreads alone.
Note:
1. The total number of process context structures that are allocated statically in the kernel depends on the sum of the configured maximum number of processes and threads. i.e. maximum number of process contexts allowed in the system. 2. Xilkernel does not feature a loader when creating new processes and threads. It creates process and thread contexts to start of from memory images assumed to be initialized. Therefore, if any elf file depends on initialized data sections, then the next time the same memory image is used to create a
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
41
R
Chapter 5: Xilkernel
process, the initialized sections will be invalid, unless some external mechanism is used to reload the elf image before creating the process.
Xilkernel Scheduling Model
Xilkernel supports either priority-driven preemptive scheduling (SCHED_PRIO) or round-robin (SCHED_RR) scheduling. This must be configured statically at kernel generation time. In SCHED_RR, there is a single ready queue and each process context executes for a configured time slice before yielding execution to the next process context in the queue. In SCHED_PRIO there are as many ready queues as there are priority levels. Priority 0 is the highest priority in the system and higher values mean lower priority. As shown in Figure 5-4, the process that is at the head of the highest priority ready queue always scheduled to execute next. Within the same priority level, scheduling is round robin. Empty ready queue levels are skipped and the next ready queue level is examined for schedulable processes. Blocked processes are off their ready queues and in their appropriate wait queues. The number of priority levels can be configured for SCHED_PRIO. For both the scheduling models, the length of the ready queue can also be configured. If there are wait queues inside the kernel (in semaphores, message queues etc.), they are configured as priority queues if scheduling mode is SCHED_PRIO.
Active 0 1 2 B C D (Blocked) A
Priority
13 14 15
E F G (Blocked)
X10132
Figure 5-4:
Priority Driven Scheduling
Each process context is in any of the following five states:
x x x x x
PROC_NEW PROC_READY PROC_RUN PROC_WAIT PROC_DEAD
The process context state diagram is shown in Figure 5-5.
42
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
Activated
Terminated
PROC_NEW
PROC_RUN
PROC_DEAD
Sc he du led
in
d cke Blo
ou t
Sc he du led
PROC_READY
PROC_WAIT
in Te at ed
Unblocked
rm
Te rm ina
ted
c blo Un d ke
X10130
Figure 5-5:
Process Context States
Xilkernel API
Process Management
A process is created and handled using the following interfaces.Some of the functions are optional and can be configured in during system initialization. Refer to the “Customizing Process Management” section for more details. Currently, a specific process_exit call is required at the end of the process’s code to allow the operating system to reclaim the process’s resources.
int process_create (unsigned int start_addr, int priority)
Parameters
start_addr is the start address of the process priority is the starting priority of the process in the system.
Returns
Returns the PID of the new process on success. Returns -1 on failure.
Description
Creates a new process. Allocates a new PID and Process Control Block (PCB) for the process.The process is placed in the appropriate ready queue. Calls the scheduler if scheduling is priority driven. sys/process.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
43
R
Chapter 5: Xilkernel
int process_exit (void)
Parameters Returns Description
None None Removes the process from the system. Schedules the next process in the system.
Caution! Do not use this to terminate a thread (described later on).
Includes sys/process.h
int process_kill (char pid)
Parameters Returns
pid is the PID of process to kill Returns 0 on success. Returns -1 on failure.
Description Note Includes
Removes the process with pid from the system. No indication is given to other processes that depend on this process. This function is optionally configured using CONFIG_PROCESS_KILL sys/process.h
int process_status (int pid, p_stat *ps)
Parameters
pid is the PID of process ps is the buffer where the process status is returned
Returns
Returns process status in ps on success Returns NULL in ps on failure. Get the status of the process or thread, whose pid is pid. The status is returned in structure p_stat which has the following fields:
i i
Description
pid is the process ID state is the current state of the process
The contents of p_stat are defined in the <sys/ktypes.h> header. Includes sys/process.h
int process_yield (void)
Parameters Returns Description
None None Yields the processor to the next process or thread.The current process goes to PROC_READY state and is put at the end of the ready queue. This function is optionally configured using CONFIG_PROCESS_YIELD. sys/process.h
Note Includes
44
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int process_setpriority (int priority)
Parameters Returns
priority is the new priority of the process. On success, return 0 On failure, return -1
Description Includes
Sets the priority of current process or thread to new value. sys/process.h
int process_getpriority (void)
Parameters Returns Description Includes
None Priority of the current process. Gets the priority of the current process or thread. sys/process.h
int get_currentPID (void)
Parameters Returns Description Includes
None Process ID of current process or thread.
Gets the Process ID of process context that is executing currently.
sys/process.h
Thread Management
Xilkernel supports the basic POSIX threads API. A thread is scheduled and allocated in the same way as a process. Threads created in the system have a kernel wrapper to which they return control to when they terminate. Therefore a specific exit function is not required at the end of the thread’s code. Thread stack is allocated on the thread’s behalf from a pool of bss memory that is statically allocated depending on the maximum number of threads in the system. Therefore, threads created dynamically are not required to be associated with an elf file. The entire thread module is optional and can be configured in or out as a part of the software specification. See the “Customizing Thread Management” section for more
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
45
R
Chapter 5: Xilkernel
details on customizing this module. The thread management interface is summarized below.
int pthread_create (pthread_t thread, pthread_attr_t* attr, void* (*start_func)(void*), void* param)
Parameters
thread is the location to store the created thread’s identifier. attr is the pointer to thread creation attributes structure. start_func is the start address of the function from which the thread needs to execute param is the pointer argument to the thread function
Returns
Returns 0 and thread id of the created thread in *thread, on success. Returns -1 if thread refers to an invalid location. Returns EINVAL if attr refers to invalid attributes. Returns EAGAIN if resources unavailable to create the thread.
Description
The pthread_create() function creates a new thread, with attributes specified by attr, within a process. If attr is NULL, the default attributes are used. If the attributes specified by attr are modified later, the thread’s attributes are not be affected. Upon successful completion, pthread_create() stores the ID of the created thread in the location referenced by thread. The thread is created executing start_routine with arg as its sole argument. If the start_routine returns, the effect is as if there was an implicit call to pthread_exit() using the return value of start_routine as the exit status. This exit behavior is slightly different for the main thread. This is explained in the pthread_exit description.
Includes
pthread.h
void pthread_exit (void *value_ptr)
Parameters Returns Description
value_ptr is a pointer to the return value of the thread. None The pthread_exit() function will terminate the calling thread and make the value value_ptr available to any successful join with the terminating thread. Thread termination releases process context resources, including, but not limited to, memory and attributes. An implicit call to pthread_exit() is made when a returns from the start routine that was used to create it. The function’s return value serves as the thread’s exit status.
Caution! There is no implicit thread exit invoked at the end of a
thread created out of an elf file by specifying the start address of the executable instructions in the elf file. Control returns to an exit stub which loops indefinitely. Therefore, to terminate such threads an explicit call to this thread exit routine is required.
Includes
pthread.h
46
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int pthread_join (pthread_t thread, void **value_ptr)
Parameters Returns
value_ptr is a pointer to the return value of the thread. 0 on success Returns ESRCH if the target thread is not in a joinable state or is an invalid thread. Returns EINVAL if the target thread already has someone waiting to join with it.
Description
The pthread_join() function suspends execution of the calling thread until the target thread terminates, unless the target thread has already terminated. On return from a successful pthread_join() call with a non-NULL value_ptr argument, the value passed to pthread_exit() by the terminating thread is made available in the location referenced by value_ptr. When a pthread_join() returns successfully, the target thread has been terminated. The results of multiple simultaneous calls to pthread_join() specifying the same target thread are that only one thread succeeds and the others fail with EINVAL.
Note: No deadlock detection is provided.
Includes pthread.h
pthread_t pthread_self (void)
Parameters Returns
None On success, returns thread identifier of current thread. Error behavior not defined. The pthread_self() function returns the thread ID of the calling thread. pthread.h
Description Includes
int pthread_detach (pthread_t target)
Parameters Returns
target is the target thread to detach. Returns 0 on success. Returns ESRCH if target thread cannot be found.
Description
The pthread_detach() function indicates to the implementation that storage for the thread thread can be reclaimed when that thread terminates. If thread has not terminated, pthread_detach() will not cause it to terminate. The effect of multiple pthread_detach() calls on the same target thread is unspecified. pthread.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
47
R
Chapter 5: Xilkernel
int pthread_equal (pthread_t t1, pthread_t t2)
Parameters Returns
t1 and t2 are the two thread identifiers to compare. Returns 1 if t1 and t2 refer to threads that are equal. Returns 0 otherwise.
Description
The pthread_equal() function returns a non-zero value if t1 and t2 are equal; otherwise, zero is returned.If either t1 or t2 are not valid thread IDs, zero is returned. pthread.h
attr)
Includes
int pthread_attr_init (pthread_attr_t*
Parameters Returns
attr is a pointer to the attribute structure to be initialized. Returns 0 on success, 1 on failure. Returns EINVAL on invalid attr parameter.
Description
The pthread_attr_init() function initializes a thread attributes object attr with the default value for all of the individual attributes used by a given implementation. The contents of pthread_attr_t are defined in the <sys/types.h> header.
Note: This does not make a call into the kernel.
Includes pthread.h
attr)
int pthread_attr_destroy (pthread_attr_t*
Parameters Returns
attr is a pointer to the thread attributes that have to be destroyed. Returns 0 on success. Returns EINVAL on errors.
Description
The pthread_attr_destroy() function destroys a thread attributes object. The implementation causes pthread_attr_destroy() to set attr to an implementation-defined invalid value. A destroyed attr attributes object can be re-initialized using pthread_attr_init(); the results of otherwise referencing the object after it has been destroyed are undefined.
Note: This does not make a call into the kernel.
Includes pthread.h
48
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int pthread_attr_setdetachstate
(pthread_attr_t*
attr, int
dstate)
Parameters
attr is the attribute structure on which the operation is to be performed. dstate is the detachstate required.
Returns
Returns 0 on success. Returns EINVAL on invalid parameters. The detachstate attribute controls whether the thread is created in a detached state. If the thread is created detached, then when the thread exits, the thread’s resources are detached without requiring a pthread_join() or a call pthread_detach().The application can set detachstate to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.
Description
Note: This does not make a call into the kernel.
Includes pthread.h
(pthread_attr_t* attr, int *dstate)
int pthread_attr_getdetachstate
Parameters
attr is the attribute structure on which the operation is to be performed. dstate is the location to store the detachstate in.
Returns
Returns 0 on success. Returns EINVAL on invalid parameters.
Description
The implementation stores either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE in dstate, if the value of detachstate was valid in attr.
Note: This does not make a call into the kernel.
Includes pthread.h
attr, struct
int pthread_attr_setschedparam (pthread_attr_t* sched_param *schedpar)
Parameters
attr is the attribute structure on which the operation is to be performed. schedpar is the location of the structure that contains the scheduling parameters.
Returns
Returns 0 on success. Returns EINVAL on invalid parameters. Returns ENOTSUP for invalid scheduling parameters.
Description
The pthread_attr_setschedparam() functions sets the scheduling parameter attributes in the attr argument. The contents of the sched_param structure are defined in the <sched.h> header.
Note: This does not make a call into the kernel.
Includes pthread.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
49
R
Chapter 5: Xilkernel
int pthread_attr_getschedparam sched_param* schedpar)
(pthread_attr_t*
attr, struct
Parameters
attr is the attribute structure on which the operation is to be performed. schedpar is the location to store the sched_param structure in. Returns 0 on success. Returns EINVAL on invalid parameters.
Returns
Description
The pthread_attr_getschedparam() gets the scheduling parameter attributes in the attr argument. The contents of the param structure are defined in the <sched.h> header.
Note: This does not make a call into the kernel.
Includes pthread.h
Semaphores
Xilkernel supports kernel allocated POSIX semaphores that can be used for synchronization. POSIX semaphores are counting semaphores that also count below zero (a negative value indicates the number of processes blocked on the semaphore). Xilkernel also supports a few interfaces for working with named semaphores. The number of semaphores allocated in the kernel and the length of semaphore wait queues can be configured during system initialization. Refer to the “Customizing Semaphore” section for more details.The semaphore module is optional and can be configured in or out during system initialization. The message queue module, described later on in this document, uses semaphores. Therefore this module needs to be included if message queues are to be used. The Xilkernel semaphore interface is described below.
int sem_init (sem_t *sem, int pshared, unsigned value)
Parameters
sem is the location to store the created semaphore’s identifier. pshared indicates sharing status of the semaphore, between processes. value is the initial count of the semaphore.
Note: pshared is unused currently.
Returns Returns 0 on success. Returns -1 on failure. Description The sem_init() function initializes the unnamed semaphore referred to by sem. The value of the initialized semaphore is value. Following a successful call to sem_init(), the semaphore may be used in subsequent calls to sem_wait(), sem_trywait(), sem_post(), and sem_destroy(). This semaphore remains usable until the semaphore is destroyed. Only sem itself may be used for performing synchronization. The result of referring to copies of sem in calls to sem_wait(), sem_trywait(), sem_post(), and sem_destroy() is undefined. Attempting to initialize an already initialized semaphore results in undefined behavior. semaphore.h
Includes
50
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int sem_destroy (sem_t* sem)
Parameters Returns
sem is the semaphore to be destroyed. Returns 0 on success. Returns -1 on failure.
Description
The sem_destroy() function destroys the unnamed semaphore indicated by sem. Only a semaphore that was created using sem_init() may be destroyed using sem_destroy(); the effect of calling sem_destroy() with a named semaphore is undefined. The effect of subsequent use of the semaphore sem is undefined until sem is reinitialized by another call to sem_init(). semaphore.h
Includes
int sem_getvalue (sem_t* sem, int* value)
Parameters
sem is the semaphore identifier value is the location where the semaphore value is stored.
Returns
Returns 0 on success and value appropriately filled in. Returns -1 on failure. The sem_getvalue() function updates the location referenced by the sval argument to have the value of the semaphore referenced by sem without affecting the state of the semaphore. The updated value represents an actual semaphore value that occurred at some unspecified time during the call, but it need not be the actual value of the semaphore when it is returned to the calling process. If sem is locked, then the object to which sval points is set to a negative number whose absolute value represents the number of processes waiting for the semaphore at some unspecified time during the call.
Description
Includes
semaphore.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
51
R
Chapter 5: Xilkernel
int sem_wait (sem_t* sem)
Parameters Returns
sem is the semaphore identifier. Returns 0 on success and the semaphore in a locked state. Returns -1 on failure.
Description
The sem_wait() function locks the semaphore referenced by sem by performing a semaphore lock operation on that semaphore. If the semaphore value is currently zero, then the calling thread does not return from the call to sem_wait() until it either locks the semaphore or the semaphore is forcibly destroyed. Upon successful return, the state of the semaphore is locked and remains locked until the sem_post() function is executed and returns successfully.
Note: When a process is unblocked within the sem_wait call, where it blocked due to unavailability of the semaphore, the semaphore may have been destroyed forcibly. In such a case, -1 is returned. Semaphores maybe forcibly destroyed due to destroying message queues which internally use semaphores. No deadlock detection is provided.
Includes semaphore.h
int sem_trywait (sem_t* sem)
Parameters Returns
sem is the semaphore identifier. Returns 0 on success. Returns -1 on failure.
Description
The sem_trywait() function locks the semaphore referenced by sem only if the semaphore is currently not locked; that is, if the semaphore value is currently positive. Otherwise, it does not lock the semaphore and returns -1. semaphore.h
Includes
52
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int sem_post (sem_t* sem)
Parameters Returns
sem is the semaphore identifier Returns 0 on success. Returns -1 on failure.
Description
The sem_post() function unlocks the semaphore referenced by sem by performing a semaphore unlock operation on that semaphore. If the semaphore value resulting from this operation is positive, then no threads were blocked waiting for the semaphore to become unlocked; the semaphore value is simply incremented. If the value of the semaphore resulting from this operation is zero or negative, then one of the threads blocked waiting for the semaphore is allowed to return successfully from its call to sem_wait(). This is either the first thread on the queue, if scheduling mode is SCHED_RR or, it is the highest priority thread in the queue, if scheduling mode is SCHED_PRIO.
Note: If an unlink operation had been requested on the semaphore, the unlink is performed if the post operation sees that no more processes are waiting on the semaphore.
Includes semaphore.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
53
R
Chapter 5: Xilkernel
sem_t* sem_open (const char* name, int oflag, ...)
Parameters
name points to a string naming a semaphore object. oflag is the flag that controls the semaphore creation.
Returns
Returns a pointer to the created/existing semaphore identifier. Returns SEM_FAILED on failures. The sem_open() function establishes a connection between a named semaphore and a process. Following a call to sem_open() with semaphore name name, the process may reference the semaphore associated with name using the address returned from the call. This semaphore may be used in subsequent calls to sem_wait(), sem_trywait(), sem_post(), and sem_close(). The semaphore remains usable by this process until the semaphore is closed by a successful call to sem_close(). The oflag argument controls whether the semaphore is created or merely accessed by the call to sem_open(). The following flag bits may be set in oflag: O_CREAT This flag is used to create a semaphore if it does not already exist. If O_CREAT is set and the semaphore already exists, then O_CREAT has no effect, except as noted under O_EXCL. Otherwise, sem_open() creates a named semaphore. The O_CREAT flag requires a third and a fourth argument: mode, which is of type mode_t, and value, which is of type unsigned. The semaphore is created with an initial value of value. After the semaphore named name has been created by sem_open() with the O_CREAT flag, other processes can connect to the semaphore by calling sem_open() with the same value of name. O_EXCL If O_EXCL and O_CREAT are set, sem_open() fails if the semaphore name exists. The check for the existence of the semaphore and the creation of the semaphore if it does not exist are atomic with respect to other processes executing sem_open() with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, the effect is undefined. If flags other than O_CREAT and O_EXCL are specified in the oflag parameter, an error is signalled. If a process makes multiple successful calls to sem_open() with the same value for name, the same semaphore address is returned for each such successful call, provided that there have been no calls to sem_unlink() for this semaphore.
Description
Note: The mode argument is unused currently.
Includes semaphore.h
54
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int sem_close (sem_t* sem)
Parameters Returns
sem is the semaphore identifier Returns 0 on success. Returns -1 on failure.
Description
The sem_close() function indicates that the calling process is finished using the named semaphore sem. The sem_close() function deallocates (that is, make available for reuse by a subsequent sem_open() by this process) any system resources allocated by the system for use by this process for this semaphore. The effect of subsequent use of the semaphore indicated by sem by this process is undefined. The name mapping for this named semaphore is also destroyed. The call fails if the semaphore is currently locked. semaphore.h
Includes
int sem_unlink (const char* name)
Parameters Returns
name is the name that refers to the semaphore Returns 0 on success. Returns -1 on failure.
Description
The sem_unlink() function removes the semaphore named by the string name. If the semaphore named by name has processes blocked on it, then sem_unlink() has no immediate effect on the state of the semaphore. The destruction of the semaphore is postponed until all blocked and locking processes relinquish the semaphore. Calls to sem_open() to recreate or reconnect to the semaphore refer to a new semaphore after sem_unlink() is called. The sem_unlink() call does not block until all references relinquish the semaphore; it returns immediately.
Note: If an unlink operation had been requested on the semaphore, the unlink is performed on a post operation that sees that no more processes waiting on the semaphore.
Includes semaphore.h
Message Queues
Xilkernel supports kernel allocated XSI message queues. XSI is the X/Open System Interface which is a set of optional interfaces under POSIX. Message queues can be used as an IPC mechanism. The message queues can take in arbitrary sized messages. However, buffer memory allocation must be configured appropriately for the memory blocks required for the messages, as a part of system malloc initialization.The number of message queue structures allocated in the kernel and the length of the message queues can be also be configured during system initialization. The message queue module is optional and can be configured in/out. Refer to the “Customizing Message Queue” section for more details. This module depends on the semaphore module and the dynamic block memory
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
55
R
Chapter 5: Xilkernel
allocation module being present in the system. The Xilkernel message queue interface is described below.
int msgget( key_t key, int msgflg )
Parameters
key is a unique identifier for referring to the message queue. msgflg specifies the message queue creation options.
Returns
Returns a unique non-negative integer message queue identifier. Returns -1 on failure.
Description
The msgget() function returns the message queue identifier associated with the argument key. A message queue identifier, associated message queue, and data structure (see <sys/kmsg.h>), are created for the argument key if the argument key does not already have a message queue identifier associated with it, and (msgflg & IPC_CREAT) is non-zero. Upon creation, the data structure associated with the new message queue identifier is initialized as follows:
x x
msg_qnum, msg_lspid, msg_lrpid are set equal to 0. msg_qbytes is set equal to the system limit (MSGQ_MAX_BYTES).
The msgget() function fails if a message queue identifier exists for the argument key but ((msgflg & IPC_CREAT) && (msgflg & IPC_EXCL)) is non-zero.
Note: IPC_PRIVATE is not supported. Also, messages in the message queue are not required to be of the form shown below. There is no support for message type based message receives and sends in this implementation.
struct mymsg { long mtype; /* Message type. */ char mtext[some_size]; /* Message text. */ }
Includes
sys/msg.h sys/ipc.h
56
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int msgctl (int msqid, int cmd, struct msqid_ds* buf)
Parameters
msqid is the message queue identifier. cmd is the command. buf is the data buffer
Returns
Returns 0 on success. Status is returned in buf for IPC_STAT Returns -1 on failure.
Description
The msgctl() function provides message control operations as specified by cmd. The following values for cmd, and the message control operations they specify, are: IPC_STAT Place the current value of each member of the msqid_ds data structure associated with msqid into the structure pointed to by buf. The contents of this structure are defined in <sys/msg.h>. IPC_SET - Unsupported. IPC_RMID Remove the message queue identifier specified by msqid from the system and destroy the message queue and msqid_ds data structure associated with it. The remove operation forcibly destroys the semaphores used internally and unblocks processes that are blocked on the semaphore. It also deallocates memory allocated for the messages in the queue.
Includes
sys/msg.h sys/ipc.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
57
R
Chapter 5: Xilkernel
int msgsnd (int msqid, const void *msgp, size_t msgsz, int msgflg)
Parameters
msqid is the message queue identifier. msgp is a pointer to the message buffer. nbytes is the size of the message msgflg is used to specify message send options.
Returns
Returns 0 on success. Returns -1 on failure.
Description
The msgsnd() function sends a message to the queue associated with the message queue identifier specified by msqid. The argument msgflg specifies the action to be taken if the message queue is full: If (msgflg & IPC_NOWAIT) is non-zero, the message is not sent and the calling thread returns immediately. If (msgflg & IPC_NOWAIT) is 0, the calling thread suspends execution until one of the following occurs:
x The condition responsible for the suspension no longer exists, in which case the message is sent. x The message queue identifier msqid is removed from the system; when this occurs -1 is returned.
The send fails if it is unable to allocate memory to store the message inside the kernel. On a successful send operation, the msg_lspid and msg_qnum members of the message queues are appropriately set. Includes sys/msg.h sys/ipc.h
58
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
ssize_t msgrcv (int msqid, void *msgp, size_t nbytes, long msgtyp, int msgflg
Parameters
msqid is the message queue identifier. msgp is the buffer where the received message is to be copied. nbytes specifies the size of the message that the buffer can hold. msgtyp is unsupported currently. msgflg is used to control the message receive operation.
Returns
Returns 0 on success and stores received message in user buffer. Returns -1 on failure.
Description
The msgrcv() function reads a message from the queue associated with the message queue identifier specified by msqid and places it in the user-defined buffer pointed to by msgp. The argument msgsz specifies the size in bytes of the message. The received message is truncated to msgsz bytes if it is larger than msgsz and (msgflg & MSG_NOERROR) is non-zero. The truncated part of the message is lost and no indication of the truncation is given to the calling process. If MSG_NOERROR is not specified and the received message is larger than nbytes, -1 is returned signalling error. The argument msgflg specifies the action to be taken if a message is not on the queue. These are as follows: If (msgflg & IPC_NOWAIT) is non-zero, the calling thread returns immediately with a return value of -1. If (msgflg & IPC_NOWAIT) is 0, the calling thread suspends execution until one of the following occurs:
i A message is placed on the queue. i The message queue identifier msqid is removed from the
system; when this occurs -1 is returned. Upon successful completion, the following actions are taken with respect to the data structure associated with msqid:
i msg_qnum is decremented by 1. i msg_lrpid is set equal to the process ID of the calling process.
Includes
sys/msg.h sys/ipc.h
Shared Memory
Xilkernel supports kernel allocated XSI shared memory. XSI is the X/Open System Interface which is a set of optional interfaces under POSIX. Shared memory is a common, low-latency IPC mechanism. Shared memory blocks required during run-time must be identified and specified during the system configuration.From this specification, buffer memory is allocated to each shared memory region. Shared memory is currently not allocated dynamically at run-time. This module is optional and can be configured in or out during system specification. Refer to the “Customizing Shared Memory” section for more details. The Xilkernel shared memory interface is described below.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
59
R
Chapter 5: Xilkernel
Caution! The memory buffers allocated by the shared memory API might not be aligned at
word boundaries. Therefore, structures should not be arbitrarily mapped to shared memory segments, without checking if alignment requirements are met. int shmget (key_t key, size_t size, int shmflg)
Parameters
key is used to uniquely identify the shared memory region. size is the requested size of the shared memory segment shmflg is used to specify segment creation options
Returns
Returns unique non-negative shared memory identifier on success. Returns -1 on failure.
Description
The shmget() function returns the shared memory identifier associated with key. A shared memory identifier, associated data structure, and shared memory segment of at least size bytes (see <sys/shm.h>) are created for key if one of the following is true:
x The argument key is equal to IPC_PRIVATE. x The argument key does not already have a shared memory identifier associated with it and (shmflg &IPC_CREAT) is nonzero.
Upon creation, the data structure associated with the new shared memory identifier shall be initialized.The value of shm_segsz is set equal to the value of size.The values of shm_lpid, shm_nattch, shm_cpid are all initialized appropriately.When the shared memory segment is created, it is initialized with all zero values
Note: At least one of the shared memory segments available in the system must EXACTLY match the requested size for the call to succeed. key IPC_PRIVATE is not supported.
Includes sys/shm.h sys/ipc.h
60
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int shmctl (int shmid, int cmd, struct shmid_ds *buf)
Parameters
shmid is the shared memory segment identifier. cmd is the command to the control function. buf is the buffer where the status is returned.
Returns
Returns 0 on success. Status is returned in buffer for IPC_STAT. Returns -1 on failure.
Description
The shmctl() function provides a variety of shared memory control operations as specified by cmd. The following values for cmd are available: IPC_STAT Place the current value of each member of the shmid_ds data structure associated with shmid into the structure pointed to by buf. The contents of the structure are defined in <sys/shm.h> IPC_SET is not supported IPC_RMID Remove the shared memory identifier specified by shmid from the system and destroy the shared memory segment and shmid_ds data structure associated with it. No notification is sent to processes still attached to the segment.
Includes
sys/shm.h sys/ipc.h
void* shmat (int shmid, const void *shmaddr, int flag)
Parameters
shmid is the shared memory segment identifier. shmaddr is used to specify the location, to attach shared memory segment. This is unused currently. flag is used to specify SHM attach options.
Returns
Returns the start address of the shared memory segment on success. Returns NULL on failure. shmat() increments the value of shm_nattch in the data structure associated with the shared memory ID of the attached shared memory segment and returns the segment’s start address. shm_lpid is also appropriately set.
Description
Note: shmaddr and flag arguments are not used.
Includes sys/shm.h sys/ipc.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
61
R
Chapter 5: Xilkernel
int shm_dt (void *shmaddr)
Parameters Returns
shmaddr is the shared memory segment address that is to be detached. Returns 0 on success. Returns -1 on failure.
Description
The shmdt() function detaches the shared memory segment located at the address specified by shmaddr from the address space of the calling process.The value of shm_nattch is also decremented.The memory segment is not removed from the system and can be attached to again. sys/shm.h sys/ipc.h
Includes
Mutex Locks
Xilkernel provides support for kernel allocated POSIX thread mutex locks. This synchronization mechanism can be used alongside of the pthread_ API. The number of mutex locks and the length of the mutex lock wait queue can be configured during system
62
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
specification. This module is also optional and can be configured in or out during system specification. Please refer to the “Customizing Shared Memory”section for more details.
int pthread_mutex_init (pthread_mutex_t* pthread_mutexattr_t* attr) mutex, const
Parameters
mutex is the location where the newly created mutex lock’s identifier is to be stored. attr is the mutex creation attributes structure.
Returns
Returns 0 on success and mutex identifier in *mutex. Returns EAGAIN if system out of resources. The pthread_mutex_init() function initializes the mutex referenced by mutex with attributes specified by attr. If attr is NULL, the default mutex attributes are used; the effect shall be the same as passing the address of a default mutex attributes object. Upon successful initialization, the state of the mutex becomes initialized and unlocked. Only mutex itself may be used for performing synchronization. The result of referring to copies of mutex in calls to pthread_mutex_lock(), pthread_mutex_trylock(), pthread_mutex_unlock(), and pthread_mutex_destroy() is undefined. Attempting to initialize an already initialized mutex results in undefined behavior.In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated. The effect shall be equivalent to dynamic initialization by a call to pthread_mutex_init() with parameter attr specified as NULL, except that no error checks are performed. For example,
static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER;
Description
Note: The mutex locks allocated by xilkernel follow the semantics of PTHREAD_MUTEX_DEFAULT mutex locks. i.e attempting to recursively lock the mutex results in undefined behavior. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behavior. Attempting to unlock the mutex if it is not locked results in undefined behavior.
Includes pthread.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
63
R
Chapter 5: Xilkernel
int pthread_mutex_destroy (pthread_mutex_t*
mutex)
Parameters Returns
mutex is the mutex identifier. Returns 0 on success. Returns EINVAL if mutex refers to an invalid identifier.
Description
The pthread_mutex_destroy() function destroys the mutex object referenced by mutex; the mutex object becomes, in effect, uninitialized. A destroyed mutex object can be reinitialized using pthread_mutex_init(); the results of otherwise referencing the object after it has been destroyed are undefined.
Note: Mutex lock/unlock state disregarded during destroy. No consideration is given for waiting processes.
Includes pthread.h
mutex)
int pthread_mutex_lock (pthread_mutex_t*
Parameters Returns
mutex is the mutex identifier. Returns 0 on success and mutex in a locked state. Returns EINVAL on invalid mutex reference and -1 on unhandled errors.
Description
The mutex object referenced by mutex is locked by the thread calling pthread_mutex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mutex object referenced by mutex in the locked state. pthread.h
mutex)
Includes
int pthread_mutex_trylock (pthread_mutex_t*
Parameters Returns
mutex is the mutex identifier. Returns 0 on success and mutex in a locked state. Returns EINVAL on invalid mutex reference, EBUSY if mutex is already locked and -1 on unhandled errors.
Description
The mutex object referenced by mutex is locked by the thread calling pthread_mutex_trlock(). If the mutex is already locked, the calling thread returns immediately with EBUSY. Otherwise, the mutex is locked on behalf of the calling thread becomes available. pthread.h
Includes
64
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int pthread_mutex_unlock (pthread_mutex_t*
mutex)
Parameters Returns
mutex is the mutex identifier. Returns 0 on success. Returns EINVAL on invalid mutex reference and -1 on undefined errors.
Description
The pthread_mutex_unlock() function shall release the mutex object referenced by mutex. If there are threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy shall determine which thread shall acquire the mutex. If it is SCHED_RR, then the thread that is at the head of the mutex wait queue is unblocked and allowed to lock the mutex. pthread.h
attr)
Includes
int pthread_mutexattr_init (pthread_mutexattr_t*
Parameters Returns
attr is the location of the attributes structure. Returns 0 on success. Returns EINVAL if attr refers to an invalid location.
Description
The pthread_mutexattr_init() function initializes a mutex attributes object attr with the default value for all of the attributes defined by the implementation.
Note: Refer to <sys/types.h> for the contents of the pthread_mutexattr
structure.This routine does not involve a call into the kernel.
Includes
pthread.h
attr)
int pthread_mutexattr_destroy (pthread_mutexattr_t*
Parameters Returns
attr is the location of the attributes structure. Returns 0 on success. Returns EINVAL if attr refers to an invalid location. The pthread_mutexattr_destroy() function destroys a mutex attributes object; the object becomes, in effect, uninitialized.
Description
Note: This routine does not involve a call into the kernel.
Includes pthread.h
Dynamic Block Memory Management
The kernel provides a simple block memory allocation scheme, which can be used by applications that need dynamic memory allocation. The application can also use the standard ‘C’ memory allocation routines.The user can select different memory blocks sizes and number of such memory blocks required for the application. The memory blocks and the total memory needed by the system is allocated statically and can be configured by the user. Refer to the “Customizing Dynamic Block Memory Management” section for more details.This method of buffer management is relatively simple, small and a fast way of
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
65
R
Chapter 5: Xilkernel
allocating memory. The following are the block memory allocation interfaces. This module is optional and can be included during system initialization.
Caution! The memory buffers allocated by the block memory allocation API might not be
aligned at word boundaries. Therefore, structures should not be arbitrarily mapped to memory allocated this way, without checking if alignment requirements are ment. void* bufmalloc (unsigned int size)
Parameters Returns
size is the size of memory block requested. Returns the start address of the memory block on success. Return NULL on failure. Allocate memory to the user process sys/mem.h
Description Includes
void buffree (void* mem)
Parameters Returns Description Includes
mem is the address of the memory block. None Free the memory allocated by bufmalloc. sys/mem.h
Interrupt Handling
Xilkernel abstracts away the basic interrupt handling requirements of the kernel during initialization. Even though the kernel will be functional without any interrupts, it makes sense for the system to be at least driven by a single timer pulse for scheduling. In this case the kernel handles the main timer interrupt, using it as the kernel tick to perform scheduling. The timer interrupt is initialized and tied to the vectoring code during system initialization. For MicroBlaze xilkernels, the system specification requires that a timer device specification is present. MicroBlaze systems must use either the standard Xilinx FIT or PIT timers. The timer tick interval can be customized by the user based on the
66
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Interrupt Handling
R
application if the PIT is used in MicroBlaze systems and always, in PPC405 systems. Refer to the “Configuring System Timer” section for more details.
Interrupts/ Exceptions Enabled Task Code Interrupted Interrupts/ Exceptions Disabled Save volatile registers interrupt vectoring code
timer_int_handler( ) process_scheduler( ); IF context switch required THEN XMK_CONTEXT_SWITCH( );
Interrupts/ Exceptions Enabled Next Task Proceeds
Restore volatile registers
Return in the context of the "next" task
X10141
Figure 5-6: Basic Interrupt Service in Xilkernel
The interrupt service in this scenario with a single timer interrupt in the system is sketched in Figure 5-6. Upon an interrupt, the volatile registers (defined by the EABI of the processor) are saved onto the interrupted task’s stack. The interrupt is then vectored to a handler that is registered at system startup. In Xilkernel’s case, the timer_int_handler() routine, is the registered handler. This routine invokes process_scheduler() to request a rescheduling operation. If the reschedule operation switched tasks, a context switch is performed. If a programmable interval timer is present in the system (always present in PPC) then its counter is reset to the interval defined at system startup. After the context switch, execution will resume in the context of the switched-to process. Since volatile registers were saved on the stack during an interrupt, they are again restored appropriately from the stack of whatever process gets to execute. Xilkernel can also work with multiple interrupts in the system, handled through an interrupt controller. See the “Configuring Interrupt Handling” section for more details on configuring Xilkernel for multiple external interrupt handling. Figure 5-7 illustrates the service sequence when interrupts are handled through an interrupt controller. The interrupt controller’s handler services all interrupt requests. However, the timer_int_handler() does not immediately perform a context switch, in this configuration. It sets a flag indicating if a context switch is required. The interrupt controller’s handler recognizes a pending context switch and performs the actual context switch at the end of the service routine. The rest of the flow is similar to the basic service routine. The flow is slightly different from PPC systems, since there is a dedicated interrupt notification for the internal PIT device. In other words, the handlers for the system timer interrupt and other external interrupts are different and hence the interrupt controller’s handler follows this
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
67
R
Chapter 5: Xilkernel
sequence of actions, without the scheduling portion, while the timer_int_handler() performs the same sequence of actions as the basic service routine.
IE = 1 Task Code Gets Interrupted IE = 0
_ _interrupt_handler( ) save volatile registers intc_device_interrupt_handler( );
intc_device_interrupt_handler( ) 1. Determine source of interrupts 2. Service ALL interrupt requests 3. IF process_scheduler( ) invoked on a timer interrupt THEN Do a context switch if required
Return in the context of the "next" task
Restore saved registers IE = 1 Next Task Proceeds IE = 1
X10140
Figure 5-7: Extended Interrupt Service in Xilkernel
There are certain limitations on the operations that can be performed inside the user-level interrupt handlers. Since, technically, the system is still executing the ISR in the context of the task that was interrupted, invoking any kind of API that may cause a rescheduling operation can potentially cause the system to enter an invalid state. The advantage of letting the system still be in the context of the process that was interrupted, in an ISR, is that on an interrupt, the entire context of the process need not be saved. This can provide significant reduction in the actual interrupt service response time. However, it imposes the restriction described above. The actual context switch, due to a rescheduling operation by the kernel, occurs at the end of servicing all the ISRs. Xilkernel support for multiple interrupts has been designed to work with the opb_intc peripheral that is a part of the standard EDK distribution. Other interrupt controllers will need the relevant support routines in the mb-hw.c, ppc-hw.c and the intr.c,h files, modified accordingly. Xilkernel also recognizes only interrupts connected through only one level of
68
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Interrupt Handling
R
interrupt controllers. Cascaded interrupt controllers are not supported. The Xilkernel userlevel interrupt handling API, is described below.
unsigned int register_int_handler (int_id_t id, void (*handler)(void*), void *callback)
Parameters
id is the zero-based numeric id of the interrupt. handler is the user-level handler. callback is a callback value that can be delivered to the user-level handler.
Returns
Returns XST_SUCCESS on success. Returns error codes defined in <xstatus.h>.
Description
The register_int_handler() function registers the specified user level interrupt handler as the handler for a specified interrupt. The user level routine will be invoked asynchronously upon being serviced by an interrupt controller in the system. The routine returns an error on MicroBlaze systems, if id is the identifier for the system timer interrupt. PPC systems have a dedicated hardware timer interrupt that exists separately from the other interrupts in the system. Therefore, this check is not performed for a PPC system. <sys/intr.h>
Includes
void unregister_int_handler (int_id_t id)
Parameters Returns Description
id is the zero-based numeric id of the interrupt. None The unregister_int_handler() function unregisters the registered user level interrupt handler as the handler for the specified interrupt. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt. <sys/intr.h>
Includes
void enable_interrupt (int_id_t id)
Parameters Returns Description
id is the zero-based numeric id of the interrupt. None The enable_interrupt() function enables the specified interrupt in the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt. <sys/intr.h>
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
69
R
Chapter 5: Xilkernel
void disable_interrupt (int_id_t id)
Parameters Returns Description
id is the zero-based numeric id of the interrupt. None The disable_interrupt() function disables the specified interrupt in the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt. <sys/intr.h>
Includes
void acknowledge_interrupt (int_id_t id)
Parameters Returns Description
id is the zero-based numeric id of the interrupt. None The acknowledge_interrupt() function acknowledges handling the specified interrupt to the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt. <sys/intr.h>
Includes
Kernel Customization
Xilkernel is highly customizable. As described in previous sections, modules and individual parameters can be changed to suit the user application. The XPS GUI system provides excellent support for easy configuration of parameters of Xilkernel, using the software platform settings dialog. Refer to Chapter 2, “Xilinx Platform Studio (XPS)” in the Embedded Systems Tools Guide for more details. In order to customize a module in the kernel, a parameter with the name of the category set to true must be defined in the MSS. For example, to customize the pthread module,
parameter config_pthread_support = true
is required in the OS specification. Not defining a configurable module’s config_ parameter will mean that the module will be configured out. An MSS snippet for configuring OS Xilkernel for a PPC system is given below:
PARAMETER os_name = xilkernel PARAMETER os_ver = 2.00.a PARAMETER stdin = RS232 PARAMETER stdout = RS232 PARAMETER proc_instance = ppc405_0 PARAMETER linker_script_specification = PARAMETER vec_mem_start = 0xffff0000 PARAMETER vec_mem_size = 16k PARAMETER data_mem_start = 0xffff4000 PARAMETER data_mem_size = 20k PARAMETER code_mem_start = 0xffff9000 PARAMETER code_mem_size = 28k PARAMETER config_process = true PARAMETER sched_type = 2 PARAMETER config_shm = true PARAMETER shm_table = (100)
true
70
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Kernel Customization
R
PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER end
config_msgq = true msgq_capacity = 5 config_sema = true multi_elf_process_table = ((0xf8000000,31)) max_procs = 5 max_readyq = 5 config_pthread_support = true max_pthreads = 5 config_pthread_mutex = true config_malloc = true mem_table = ((4,10), (3,10),(8,10)) pit_interval = 0xffffff copyoutfiles = true copyfromdir = . copytodir = /usr/kernelsrc
The values in the snippet show above are only sample values, targeting a hypothetical board. The configuration directives in the MSS specification have the corresponding implication on memory and code size of the resultant Xilkernel image. This is especially true for kernel allocated structures, whose count can be configured through the MSS. For e.g. The maximum number of process context structures allocated in the kernel is determined by the sum of two parameters; max_procs and max_pthreads. If a process context structures occupies x bytes of bss memory, then the total bss memory requirement for process contexts will be (max_procs + max_pthreads)*x bytes. Therefore, such parameters should be carefully tuned, and the final kernel image should be examined with the GNU size utility to make sure that memory requirements are met. To get an idea of the contribution of each kernel allocated structures memory requirements, please take a look at the corresponding header file. The specification in the MSS gets translated by libgen and the Xilkernel TCL files into C-language configuration directives in two header files os_config.h and config_init.h. Interested users should take a look at these two files, which are generated in the main processor include directory, to get an idea of how the specification gets translated.
Customizing STDIN and STDOUT
The standard input and output peripherals can be configured for Xilkernel. Xilkernel can work without a standard input and output too. These peripherals are the targets of inputoutput API like print, outbyte, inbyte etc.
Table 5-1:
STDIN/STDOUT configuration parameters Description
Instance name of stdin peripheral Instance name of stdout peripheral
Attribute
stdin stdout
Type
string string
Defaults
none none
Customizing User Initialization Routine
A user initialization routine can be optionally invoked as a part of Xilkernel initialization with this parameter. The routine must be named as user_init. Note that the user_init routine should be present within the symbolic scope of the kernel. Therefore, it can be a
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
71
R
Chapter 5: Xilkernel
part of an application that is in the kernel bundle mode. If there are no kernel bundle applications, then it should be in one of the compiled kernel sources.
Table 5-2:
User initialization routine parameters Description
Invoke user_init during system initialization.
Attribute
user_init
Type
boolean
Defaults
false
Customizing Process Management
The user can select the maximum number of processes in the system and the different functions needed to handle processes. The processes and threads that are present in the system on system startup can be configured statically.
Table 5-3:
Process management parameters Attribute Description
Need process management Maximum number of processes in the system Maximum size of Ready queue for each priority Include process_kill() function Include process_kill() function Include process_sleep() function Configure startup processes that are separate executable files. This is defined to be an array with each element containing the parameters process_start and process_prio. Configure startup processes that are a part of the kernel bundle. This is defined to be an array with each element containing the parameters process_start_func, process_prio, and process_stack_size. Process start address Process start function Process priority Size of the process’s stack
Type
boolean numeric numeric boolean boolean boolean
Defaults
true 10 10 false false false
config_process max_procs max_readyq config_process_kill config_process_kill config_process_sleep separate_exec_process_table
array of 2tuples
none
kernel_bundled_process_table
array of 3tuples
none
process_start process_start_func process_prio process_stack_size
address string numeric numeric
none none none none
72
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Kernel Customization
R
Customizing Scheduling
The user can configure the type of scheduler used and the number of priorities used for the Scheduler module. The configurable parameters are given below.
Table 5-4:
Scheduling parameters Description
Configure scheduler module Type of Scheduler to be used. Allowed values
Attribute
config_sched sched_type
Type
boolean
Defaults
true
x 2 - SCHED_RR x 3 - SCHED_PRIO
n_prio Number of priority levels if scheduling is SCHED_PRIO.
numeric
2 (SCHED_RR)
numeric
32
Customizing Thread Management
The user can optionally select to include thread support, the maximum number of threads and size of the thread stack etc. The configurable parameters are given below.
Table 5-5:
Thread module parameters Attribute Description
Need pthread module Maximum number of threads Stack size for dynamically created threads (in bytes) Configure startup threads that are also separate executable files. This is defined to be an array with each element containing the parameters pthread_start and pthread_prio. Configure startup threads that are a part of the kernel bundle. This is defined to be an array with each element containing the parameters pthread_start_func and pthread_prio. Thread start address
Type
boolean numeric numeric
Defaults
false 5 600
config_pthread_support max_pthreads pthread_stack_size separate_exec_pthread_table
array of 2-tuples
none
kernel_bundled_pthread_table
array of 2-tuples
none
pthread_start
address
none
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
73
R
Chapter 5: Xilkernel
Table 5-5:
Thread module parameters Attribute Description
Thread start function Thread priority
Type
string numeric
Defaults
none none
pthread_start_func process_prio
Customizing Semaphore
The user can optionally select to include semaphores, maximum number of semaphores and semaphore queue length. The following are the parameters used for configuration.
Table 5-6:
Semaphore module parameters Description
Need Semaphore module Maximum number of Semaphores Semaphore Wait Queue Length
Attribute
config_sema max_sem max_sem_waitq
Type
boolean numeric numeric
Defaults
false 10 10
Customizing Message Queue
The user can optionally select to include message queue module, number of message queues and the size of each message queue. The message queue module depends on both the semaphore module and the malloc module.The following parameters definitions are used for configuration. Memory for messages must be explicitly specified in the malloc customization.
Table 5-7:
Message queue module parameters Description
Need Message Queue module Number of message queues in the system Maximum number of messages in the queue
Attribute
config_msgq num_msgqs msgq_capacity
Type
boolean numeric numeric
Defaults
false 10 10
Customizing Shared Memory
The user can optionally select to include shared memory and size of each shared memory segment. All the shared memory segments that will ever be needed must be specified in these parameters.The following parameters are used for configuration.
74
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Kernel Customization
R
Table 5-8: Attribute
Shared Memory Module Parameters Description
Need Shared Memory module Shared Memory table. This is defined as an array with each element having shm_size parameter Shared Memory size Number of Shared Memories Size of the shm_table array.
Type
boolean
Defaults
false
config_shm shm_table
array of 1-tuples
none
shm_size num_shm
numeric numeric
none none
Customizing Pthread Mutex
The user can optionally select to include the pthread mutex module, number of mutex locks and the size of the wait queue for the mutex locks.The following parameter are used for configuration.
Table 5-9:
Pthread mutex Module Parameters Attribute Description
Need pthread mutex module Maximum number of pthread mutex locks available in the system. Length of each the mutex lock wait queue.
Type
boolean
Defaults
false
config_pthread_mutex max_pthread_mutex
numeric
5
max_pthread_mutex_ waitq
numeric
10
Customizing Dynamic Block Memory Management
The user can optionally select to include the dynamic block memory management module, size of memory blocks and number of memory blocks. The following parameters are used for configuration.
Table 5-10:
Memory Management module parameters Description
Need Memory Management Memory block table. This is defined as an array with each element having mem_bsize, mem_nblks parameters. Memory block size.
Attribute
config_malloc mem_table
Type
boolean
Defaults
false
array of 2-tuples
none
mem_bsize
numeric
none
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
75
R
Chapter 5: Xilkernel
Table 5-10:
Memory Management module parameters Description
Number of memory blocks of a size Number of memory blocks configurations - Size of mem_table array
Attribute
mem_nblks n_malloc_blocks
Type
numeric
Defaults
none
numeric
none
Customizing Linker Script (PPC405)
Building Xilkernel for PPC requires a linker script to specify the location of the vectors section in the image. The user can customize the default linker script (linker_include.sh and linker_script.sh) files for building PowerPC kernel. If configuring, the user must specify the start address and size of three program sections - vector table, code section and data section. The following parameters are used for configuration.
Table 5-11:
Linker Script Configuration parameters in PPC405 Description
Need Custom Linker Script specification Start address of Vector Table Program section. Size of Vector table section. Specify as xK. Start address of Code section. Size of Code section. Specify as xK. Start address of Data section. Size of Data section. Specify as xK.
Attribute
linker_script_specification vect_mem_start vect_mem_size code_mem_start code_mem_size data_mem_start data_mem_size
Type
boolean address numericsize address numericsize address numericsize
Defaults
false 0x0 9K 0xffffd000 12K 0x2400 9K
76
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Kernel Customization
R
Configuring System Timer
The user can configure the timer device in the system for MicroBlaze kernels. Additionally, he can configure the timer interval for PPC and for MicroBlaze, if the MicroBlaze system includes a PIT timer. The following parameters are used.
Table 5-12:
Attributes for Copying Kernel Source Files Description
A tuple specifying the timer device instance name and the timer type. For example, (system_timer, PIT). PIT and FIT are the only supported timer type strings. Specify the count down interval for the PIT timer in PPC and the PIT timer in MicroBlaze, if so configured.
Attribute
systmr_spec (MicroBlaze only)
Type
Defaults
2-tuple of (string, string)
null
pit_interval
numeric
0xffffff
Configuring Interrupt Handling
The user can configure the interrupt controller device in the system kernels. Adding this parameter, automatically configures multiple interrupt support and the user-level interrupt handling API in the kernel. The following parameters are used.
Table 5-13:
Attributes for Copying Kernel Source files Description
Specify the instance name of the interrupt controller device connected to the external interrupt port.
Attribute
sysintc_spec
Type
Defaults
string
null
Configuring Debug Messages
The user can configure that the kernel outputs debug/diagnostic messages through its execution flow. Enabling the following parameters makes available the DBG_PRINT macro and subsequently its output to the standard output device.
Attribute
debug_mode
Description
Turn on debug messages from the kernel.
Type
boolean
Defaults
false
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
77
R
Chapter 5: Xilkernel
Copy Kernel Source Files
The user can copy the configured kernel source files to his repository for further editing and using them for building the kernel. The following parameters are used.
Table 5-14:
Attributes for Copying Kernel Source files Description
Need to Copy source files The Kernel source directory path. The path is relative to <project_direc>/<systemname>/ libsrc/xilkernel_v2_00_a/src directory User repository directory. The path is relative to <project_direc>/<systemname>/ libsrc/xilkernel_v2_00_a/src directory
Attribute
copyoutfiles copyfromdir
Type
boolean
Defaults
false
path string
“.”
copytodir
path string
"../../../copyof lib"
Debugging Xilkernel
In kernel bundled executable mode, there is a single file that can serve as the target for debugging. Therefore all kernel bundled user applications can be debugged together using GDB. However this is not the case for separate executable mode. Therefore, separate executable applications can currently, not be debugged with XMD and GDB.
Memory Footprint
The size of Xilkernel depends on the user configuration. It is small in size and can fit in different configurations. The following is the memory size output from GNU size utility for the kernel. The image for the PPC version of Xilkernel includes the code for the exception and interrupt vectors, which is by design entitled to occupy 8 Kb of text space. Therefore the text sizes reported below include this 8 Kb of vector code space. Xilkernel has been tested with the GCC optimization flag of -O2, These numbers below are also from the same optimization level.
Table 5-15:
User Configuration and Xilkernel Size MicroBlaze (in Kb)
~4.4K ~4.5
Configuration
Barebones kernel Basic kernel functionality with only multi-processing (no threads)
PPC (in Kb)
~12.4 ~12.5
78
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel File Organization
R
Table 5-15:
User Configuration and Xilkernel Size MicroBlaze (in Kb)
~7.4
Configuration
Basic kernel functionality with multi-tasking and multi-threading. Full kernel functionality with all modules (processes,
threads, support for both separate and kernel bundled applications, IPC, synchronization constructs, malloc, interrupt handling, drivers for interrupt controller and timer)
PPC (in Kb)
~15.7
~19.3
24.1
Xilkernel File Organization
Xilkernel sources are organized in the following manner. The root level contains the data and the src folders. The data folder contains the MLD and the TCL files, that determine the configuration of Xilkernel. The src folder contains all the sources. src has a sub-folder src, which contains non-header source files, categorized into arch, sys and ipc folders. arch contains architecture specific sources, while sys contains system-level sources. ipc contains all the sources implementing the IPC functionality. The header files are contained under the include folder of the top-level src folder. The header files are also organized in a way similar to src. There is also a test folder, that contains internal test cases that can be used to get an idea of how Xilkernel functionality can be used.
System Initialization
The entry point for the kernel is the main() routine defined in main.c. The first action performed is hardware specific initialization. This includes registering the interrupt handlers and configuring the system timer. This portion of the initialization depends upon the kind of hardware that is present in the system. Interrupts/exceptions are not enabled after completing hw_init(). If the user has required user_init() to be invoked as a part of the system initialization, then user_init() is invoked next (This applies only if the user_init routine is within the symbolic scope of the rest of the kernel). The sys_init() routine is entered next. This routine performs initialization of each module such as processes, threads, etc. Specifically, it initializes the following things, in order. 1. 2. 3. 4. 5. 6. 7. 8. 9. Internal process context structures Ready queues Pthread module Semaphore module Message Queue module Shared memory module Memory allocation module Idle task creation Static separate executable process creation
10. Static kernel bundled process creation
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
79
R
Chapter 5: Xilkernel
11. Static separate executable pthread creation 12. Static kernel bundled pthread creation After these steps, interrupts and exceptions are enabled and the kernel loops infinitely (blocks), enabling the scheduler to start scheduling a process.
Limitations
Xilkernel currently has the following limitations.
x x x x
The PPC xilkernel image size is contributed significantly (8 Kb) to by the exception vector code. In general, Xilkernel can be further optimized for size. Timer support is not complete in both versions of Xilkernel. POSIX error reporting structure is not fully complete. Therefore, the errno feature is not supported in the POSIX calls. There is restriction on rescheduling tasks within an interrupt handler (described in earlier sections). This means that usage of semaphores, mutex locks, message queues and creating or manipulating processes and threads cannot occur within interrupt handlers.
Future Enhancements
Apart from overcoming the above limitations, future enhancements will focus on supporting the following features.
x x x x x x x
Memory protection (with some hardware support). Better memory allocation and memory mapping functionality. Preventing priority inversion with priority inheritance. Supporting debugging of separate executable applications with GDB. Alarms and Timers. Migrating to POSIX scheduling schemes (SCHED_FIFO and SCHED_RR schemes in a common priority based implementation). POSIX signals.
Modifying Xilkernel
Users can further customize Xilkernel by changing the actual code base. To work with a custom copy of Xilkernel, users first copy the Xilkernel source folder (xilkernel_v2_00_a) from within the EDK installation and place it under the bsp folder of the project folder. For example, <..../myproject/bsp/xilkernel_v2_00_a>. Libgen now picks up this source folder of Xilkernel for compilation, since it looks for Xilkernel sources first under the bsp folder before picking it up from the standard installation. Refer to “Xilkernel File Organization” for more information on the organization of the Xilkernel sources. Xilkernel sources have been written in an elementary and intuitive style and include comment blocks above each significant function. Each source file also carries a comment block indicating its role.
User Guide
Refer to the “Using Xilkernel” chapter in the Platform Studio User Guide for detailed steps on configuring and using Xilkernel. Information on how to develop, build, and download
80
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
User Guide
R
applications is also present in that chapter. Some example systems and applications are illustrated. These design examples illustrate all the features of Xilkernel and therefore will be very useful for users who would like to quickly get started with Xilkernel.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
81
R
Chapter 5: Xilkernel
82
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 6
LibXil Net
This chapter describes the network library for Embedded processors, libXilNet. The library includes functions to support the TCP/IP stack and the higher level application programming interface (Socket APIs). The chapter contains the following sections.
x x x x x x x x x
“Overview” “LibXilNet Functions” “Protocols Supported” “Library Architecture” “Protocol Function Description” “Current Restrictions” “Functions of LibXilNet” “LibGen Customization” “Using XilNet in Application”
Overview
The Embedded Development Kit (EDK) networking library, libXilNet, allows a processor to connect to the internet. LibXilNet includes functions for handling the TCP/IP stack protocols. It also provides a simple set of Sockets Application Programming Interface (APIs) functions enabling network programming. Lib Xil Net supports multiple connections (through Sockets interface) and hence enables multiple client support. This chapter describes the various functions of LibXilNet.
LibXilNet Functions
Quick Glance
Table 6-1 presents a list of functions provided by the LibXilNet at a glance.
Table 6-1:
LibXilNet functions at a glance Functions
int xilsock_init (void) void xilsock_rel_socket (int sd) int xilsock_socket (int domain, int type, int proto)
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
83
R
Chapter 6: LibXil Net
Table 6-1:
LibXilNet functions at a glance Functions
int xilsock_bind (int sd, struct sockaddr* addr, int addrlen) int xilsock_listen (int sd, int backlog) int xilsock_accept (int sd, struct sockaddr* addr, int* addrlen) int xilsock_recvfrom (int s, unsigned char* buf, unsigned int len, struct sockaddr* from, unsigned int* fromlen) int xilsock_sendto (int s, unsigned char* buf, int len, struct sockaddr* to, unsigned int tolen) int xilsock_recv (int s, unsigned char* buf, unsigned int len) int xilsock_send (int s, unsigned char* buf, unsigned int len) void xilsock_close (int s) void xilnet_mac_init (unsigned int baseaddr) int xilnet_eth_find_old_entry(void) void xilnet_eth_init_hw_addr(unsigned char *addr) int xilnet_eth_recv_frame (unsigned char* frame, int len) int xilnet_eth_send_frame (unsigned char* frame, int len, void* daddr, unsigned short type) void xilnet_eth_update_hw_tbl (unsigned char* frame, int proto) void xilnet_eth_add_hw_tbl_entry (unsigned char* ip, unsigned char* hw) int xilnet_eth_get_hw_addr (unsigned char* ip) int xilnet_eth_init_hw_addr_tbl (void) int xilnet_arp (unsigned char* buf, int len) void xilnet_arp_reply (unsigned char* buf, int len) void xilnet_ip_init (unsigned char* ip_addr) int xilnet_ip (unsigned char* buf, int len) void xilnet_ip_header (unsigned char* buf, int len, int proto, unsigned char* peer_ip_addr) unsigned short xilnet_ip_calc_chksum (unsigned char* buf, int len) int xilnet_udp (unsigned char* buf, int len) void xilnet_udp_header (struct xilnet_udp_conn* conn, unsigned char* buf, int len) unsigned short xilnet_tcp_udp_calc_chksum (unsigned char* buf, int len, unsigned char* saddr, unsigned char* daddr, unsigned short proto)
84
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Protocols Supported
R
Table 6-1:
LibXilNet functions at a glance Functions
void xilnet_udp_init_conns (void) int xilnet_udp_open_conn (unsigned short port) int xilnet_udp_close_conn (struct xilnet_udp_conn* conn) int xilnet_tcp (unsigned char* buf, int len) void xilnet_tcp_header (struct xilnet_tcp_conn* conn, unsigned char* buf, int len, unsigned char flags) void xilnet_tcp_send_pkt (struct xilnet_tcp_conn* conn, unsigned char* buf, int len, unsigned char flags) void xilnet_tcp_init_conns (void) int xilnet_tcp_open_conn (unsigned short port) int xilnet_tcp_close_conn (struct xilnet_tcp_conn* conn) int xilnet_icmp (unsigned char* buf, int len) void xilnet_icmp_echo_reply (usigned char* buf, unsigned int len)
Protocols Supported
LibXilNet supports drivers and functions for the Sockets API and protocols of TCP/IP stack. The following list enumerates them.
x x x x x x x
Ethernet Encapsulation (RFC 894) Address Resolution Protocol (ARP - RFC 826) Internet Protocol (IP - RFC 791) Internet Control Management Protocol (ICMP - RFC 792) Transmission Control Protocol (TCP - RFC 793) User Datagram Protocol (UDP - RFC 768) Sockets API
Library Architecture
Figure 6-1 gives the architecture of libXilNet. Higher Level applications like HTTP server, TFTP (Trivial File Transfer Protocol), PING etc., uses API functions to use the libXilNet library
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
85
R
Chapter 6: LibXil Net
PING Application
HTTP Server Application
TFTP Application
Xilinx Sockets Interface Demultiplexing based on connections
ICMP
TCP
UDP
ARP
IP
Demultiplexing based on protocal value in IP Header
Demultiplexing based on frame type in Ethernet Header Ethernet Driver Incoming Frame MAC Driver
From PHY Interface LibXilNet Architecture
UG111_07_111903
Figure 6-1:
Schematic Diagram of LibXilNet Architecture
86
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Protocol Function Description
R
Protocol Function Description
A detailed description of the drivers and the protocols supported is given below.
Media Access Layer (MAC) Drivers Wrapper
MAC drivers wrapper initializes the base address of the mac instance specified by the user.This base address is used to send and receive frames. This initialization must be done before using other functionalites of LibXil Net library. The details of the function prototype is defined in the section“Functions of LibXilNet.”
Ethernet Drivers
Ethernet drivers perform the encapsulation/removal of ethernet headers on the payload in accordance with the RFC 894. Based on the type of payload (IP or ARP), the drivers call the corresponding protocol callback function. A Hardware Address Table is maintained for mapping 48-bits ethernet address to 32-bits IP address.
ARP (RFC 826)
Functions are provided for handling ARP requests. An ARP request (for the 48-bit hardware address) is acknowledged with the 48-bit ethernet address in the ARP reply. Currently, ARP request generation for a desired IP address is not supported. The Hardware address table is updated with the new IP/Ethernet address pair if the ARP request is destined for the processor.
IP (RFC 791)
IPv4 datagrams are used by the higher level protocols like ICMP, TCP, and UDP for receiving/sending data. A callback function is provided for ethernet drivers which is invoked whenever there is an IP datagram as a payload in an ethernet frame. Minimal processing of the source IP address check is performed before the corresponding higher level protocol (ICMP, TCP, UDP) is called. Checksum is calculated on all the outgoing IP datagrams before calling the ethernet callback function for sending the data. An IP address for a Embedded Processor needs to be programmed before using it for communication. An IP address initializing function is provided. Refer to the table describing the various routines for further details on the function. Currently no IP fragmentation is performed on the outgoing datagrams. The Hardware address table is updated with the new IP/Ethernet address pair if an IP packet was destined for the processor.
ICMP (RFC 792)
ICMP functions handling only the echo requests (ping requests) are provided. Echo requests are issued as per the appropriate requirements of the RFC (Requests For Comments).
UDP (RFC 768)
UDP is a connectionless protocol. The UDP callback function, called from the IP layer, performs the minimal check of source port and strips off the UDP header. It demultiplexes from the various open UDP connections. A UDP connection can be opened with a given source port number through Socket functions. Checksum calculation is performed on the
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
87
R
Chapter 6: LibXil Net
outgoing UDP datagram. The number of UDP connections that can be supported simultaneously is configurable.
TCP (RFC 793)
TCP is a connection-oriented protocol. Callback functions are provided for sending and receiving TCP packets. TCP maintains connections as a finite state machine. On receiving a TCP packet, minimal check of source port correctness is done, before demultiplexing the TCP packet from the various TCP connections. Necessary action for the demultiplexed connection is taken based on the current machine state. A status flag is returned to indicate the kind of TCP packet received to support connection management. Connection management has to be done at the application level using the status flag received from TCP. Checksum is calculated on all outgoing TCP packets. The number of TCP connections that can be supported simultaneously is configurable.
Sockets API
Functions for creating sockets (TCP/UDP), managing sockets, sending and receiving data on UDP and TCP sockets are provided. High level network applications need to use these functions for performing data communication. Refer to Table 6-1 for further details.
Buffer Management
XiNet stack is geared to work with smaller FPGA devices and hence minimal buffer management is provided. The stack uses two global buffers - sendbuf, recvbuf - to send and receive ethernet frames. User code can either allocate a buffer or use sendbuf to send packets from the application. When sendbuf is used to transmit packets, user code is responsible to place the application data at the right offset from start of sendbuf accounting for all layers of stack starting from ethernet header.
Current Restrictions
Certain restrictions apply to the EDK libXilNet library software. These are
x x x
Only server functionalities for ARP - This means ARP requests are not being generated from the processor Only server functionalities in libXilNet - This means no client application development support provided in libXilNet. No timers in TCP - Since there are no timers used, every "send" over a TCP connection waits for an "ack" before performing the next "send".
Functions of LibXilNet
The following table gives the list of functions in libXilNet and their descriptions
88
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
int xilsock_init (void) Parameters Returns Description Includes None 1 for success and 0 for failure Initialize the xilinx internal sockets for use. xilsock.h
void xilsock_rel_socket (int sd) Parameters Returns Description Includes sd is the socket to be released. None Free the system level socket given by the socket descriptor sd xilsock.h
int xilsock_socket (int domain, int type, int proto) Parameters domain: Socket Domain type: Socket Type proto: Protocol Family Returns On success, return socket descriptor On failure, return -1 Description Create a socket of type, domain and protocol proto and returns the socket descriptor. The type of sockets can be: SOCK_STREAM (TCP socket) SOCK_DGRAM (UDP socket) domain value currently is AF_INET proto refers to the protocol family which is typically the same as the domain. Includes xilsock.h
int xilsock_bind (int sd, struct sockaddr* addr, int addrlen) Parameters sd: Socket descriptor addr: Pointer to socket structure addrlen: Size of the socket structure Returns On success, return 1 On failure, return -1 Description Bind socket given the descriptor sd to the ip address/port number pair given in structure pointed to by addr of len addrlen. addr is the typical socket structure. xilsock.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
89
R
Chapter 6: LibXil Net
int xilsock_accept (int sd, struct sockaddr* addr, int *addrlen) Parameters sd: Socket descriptor addr: Pointer to socket structure addrlen: Pointer to the size of the socket structure Returns On success, return socket descriptor On failure, return -1 Description Accepts new connections on socket sd. If a new connection request arrives, it creates a new socket nsd, copies properties of sd to nsd, returns nsd. If a packet arrives for an existing connection, returns 0 and sets the xilsock_status_flag global variable. The various values of the is flag are: XILSOCK_NEW_CONN XILSOCK_CLOSE_CONN XILSOCK_TCP_ACK for new connection, closed a connection and acknowledgment for data sent for a connection correspondingly. This function implicitly polls/waits on a packet from MAC. Arguments addr and addrlen are in place to support the standard Socket accept function signature. At present, they are not used in the accept function. Includes xilsock.h
int xilsock_recvfrom (int s, unsigned char* buf, int len) Parameters s: UDP socket descriptor buf: Buffer to receive data len: Buffer size Returns Number of bytes received Receives data (maximum length of len) from the UDP socket s in buf and returns the number of bytes received. xilsock.h
Description Includes
int xilsock_sendto (int s, unsigned char* buf, int len) Parameters s: UDP socket descriptor buf: Buffer containing data to be sent len: Buffer size Returns Description Includes Number of bytes received Sends data of length len in buf on the UDP socket s and returns the number of bytes sent. xilsock.h
90
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
int xilsock_recv (int s, unsigned char* buf, int len) Parameters s: TCP socket descriptor buf: Buffer to receive data len: Buffer size Returns Description Includes Number of bytes received Receives data (maximum length of len) from the TCP socket s in buf and returns the number of bytes received. xilsock.h
int xilsock_send (int s, unsigned char* buf, int len) Parameters s: TCP socket descriptor buf: Buffer containing data to be sent len: Buffer size Returns Description Includes Number of bytes received Sends data of length len in buf on the UDP socket s and returns the number of bytes sent. xilsock.h
void xilsock_close (int s) Parameters Returns Description s: socket descriptor None Closes the socket connection given by the descriptor s. This function has to be called from the application for a smooth termination of the connection after a connection is done with the communication. xilsock.h
Includes
void xilnet_mac_init (unsigned int baseaddr) Parameters Returns Description baseaddr: Base address of the MAC instance used in a system None Initialize the MAC base address used in the libXil Net library to baseaddr. This function has to be called at the start of a user program with the base address used in the MHS file for ethernet before starting to use other functions of libXil Net library. mac.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
91
R
Chapter 6: LibXil Net
void xilnet_eth_init_hw_addr (unsigned char* addr) Parameters Returns Description addr: 48-bit colon separated hexa decimal ethernet address string None Initialize the source ethernet address used in the libXil Net library to addr. This function has to be called at the start of a user program with a 48-bit, colon separated, hexa decimal ethernet address string for source ethernet address before starting to use other functions of libXil Net library. This address will be used as the source ethernet address in all the ethernet frames. xilsock.h mac.h int xilnet_eth_recv_frame (unsigned char* frame, int len) Parameters frame: Buffer for receiving an ethernet frame len: Buffer size Returns Description Number of bytes received Receives an ethernet frame from the MAC, strips the ethernet header and calls either ip or arp callback function based on frame type. This function is called from accept /receive socket functions. The function receives a frame of maximum length len in buffer frame. xilsock.h mac.h void xilnet_eth_send_frame (unsigned char* frame, int len, unsigned char* dipaddr, void *dhaddr, unsigned short type) Parameters frame: Buffer for sending a ethernet frame len: Buffer size dipaddr: Pointer to the destination ip address dhaddr: Pointer to the destination ethernet address type: Ethernet Frame type (IP or ARP) Returns Description None Creates an ethernet header for payload frame of length len, with destination ethernet address dhaddr, and frame type, type. Sends the ethernet frame to the MAC. This function is called from receive/send (both versions) socket functions. xilsock.h mac.h
Includes
Includes
Includes
92
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
void xilnet_eth_update_hw_tbl (unsigned char* frame, int proto) Parameters frame: Buffer containing an ethernet frame proto: Ethernet Frame type (IP or ARP) Returns Description None Updates the hardware address table with ipaddress/hardware address pair from the ethernet frame pointed to by frame. proto is used in identifying the frame (ip/arp) to get the ip address from the ip/arp packet., xilsock.h mac.h void xilnet_eth_add_hw_tbl_entry (unsigned char* ip, unsigned char* hw) Parameters ip: Buffer contains ip address hw: Buffer containing hardware address Returns Description Includes None Add an ip/hardware pair entry given by ip/hw into the hardware address table xilsock.h mac.h int xilnet_eth_get_hw_addr (unsigned char* ip) Parameters Returns Description ip: Buffer containing ip address Index of entry in the hardware address table that matches the ip address Receives an ethernet frame from the MAC, strips the ethernet header and calls either ip or arp callback function based on the frame type. This function is called from accept /receive socket functions. The function receives a frame of maximum length len in buffer frame. xilsock.h mac.h
Includes
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
93
R
Chapter 6: LibXil Net
void xilnet_eth_init_hw_addr_tbl (void) Parameters Returns Description Includes None None Initializes Hardware Address Table. This function must be called in the user program before using other functions of LibXilNet. xilsock.h mac.h int xilnet_arp (unsigned char* buf, int len) Parameters buf: Buffer for holding the ARP packet len: Buffer size Returns Description 0 This is the arp callback function. It gets called by the ethernet driver for arp frame type. The arp packet is copied onto the buf of length len. xilsock.h
Includes
void xilnet_arp_reply (unsigned char* buf, int len) Parameters buf: Buffer containing the ARP reply packet len: Buffer size Returns Description None This function sends the arp reply, present in buf of length len, for arp requests. It gets called from the arp callback function for arp requests. xilsock.h
Includes
void xilnet_ip_init (unsigned char* ip_addr) Parameters Returns Description ip_addr: Array of four bytes holding the ip address to be configured None This function initializes the ip address for the processor to the address represented in ip_addr as a dotted decimal string. This function must be called in the application before any communication. xilsock.h
Includes
94
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
int xilnet_ip (unsigned char* buf, int len) Parameters buf: Buffer for holding the IP packet len: Buffer size Returns Description 0 This is the ip callback function. It gets called by the ethernet driver for ip frame type. The ip packet is copied onto the buf of length len. This function calls in the appropriate protocol callback function based on the protocol type. xilsock.h
Includes
void xilnet_ip_header (unsigned char* buf, int len, int proto) Parameters buf: Buffer for the ip packet len: Length of the ip packet proto: Protocol Type in IP packet Returns Description None This function fills in the ip header from the start of buf. The ip packet is of length len and proto is used to fill in the protocol field of ip header. This function is called from the receive/send (both versions) functions. xilsock.h
Includes
unsigned short xilnet_ip_calc_chksum (unsigned char* buf, int len, int proto) Parameters buf: Buffer containing ip packet len: Length of the ip packet Returns Description checksum calculated for the given ip packet This function calculates the checksum for the ip packet buf of length len. This function is called from the ip header creation function. xilsock.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
95
R
Chapter 6: LibXil Net
int xilnet_udp (unsigned char* buf, int len) Parameters buf: Buffer containing the UDP packet len: Length of the UDP packet Returns Description Length of the data if packet is destined for any open UDP connections else returns 0 This is the udp callback function which is called when ip receives a udp packet. This function checks for a valid udp port, strips the udp header, and demultiplexes from the various UDP connections to select the right connection. xilsock.h
Includes
void xilnet_udp_header (struct xilnet_udp_conn conn, unsigned char* buf, int len) Parameters conn: UDP connection buf: Buffer containing udp packet len: Length of udp packet Description This function fills in the udp header from the start of buf for the UDP connection conn. The udp packet is of length len. This function is called from the receivefrom/sendto socket functions. xilsock.h
Includes
unsigned short xilnet_udp_tcp_calc_chksum (unsigned char* buf, int len, unsigned char* saddr, unsigned char* daddr, unsigned short proto) Parameters buf: Buffer containing UDP/TCP packet len: Length of udp/tcp packet saddr: IP address of the source daddr: Destination IP address proto: Protocol Type (UDP or TCP) Returns the Returns Description Checksum calculated for the given udp/tcp packet This function calculates and fills the checksum for the udp/tcp packet buf of length len. The source ip address (saddr), destination ip address(daddr) and protocol (proto) are used in the checksum calculation for creating the pseudo header. This function is called from either the udp header or the tcp header creation function. xilsock.h
Includes
96
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
void xilnet_udp_init_conns (void ) Parameters Returns Description Includes None None Initialize all UDP connections so that the states of all the connections specify that they are usable. xilsock.h
int xilnet_udp_open_conn (unsigned short port) Parameters Returns Description Includes port: UDP port number Connection index if able to open a connection. If not returns -1. Open a UDP connection with port number port. xilsock.h
int xilnet_udp_close_conn (struct xilnet_udp_conn *conn) Parameters Returns Description Includes conn: UDP connection 1 if able to close else returns -1. Close a UDP connection conn. xilsock.h
int xilnet_tcp (unsigned char* buf, int len) Parameters buf: Buffer containing the TCP packet len: Length of the TCP packet Returns Description A status flag based on the state of the connection for which the packet has been received This is the tcp callback function which is called when ip receives a tcp packet. This function checks for a valid tcp port and strips the tcp header. It maintains a finite state machine for all TCP connections. It demultiplexes from existing TCP open/listening connections and performs an action corresponding to the state of the connection. It returns a status flag which identifies the type of TCP packet received (data or ack or fin). xilsock.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
97
R
Chapter 6: LibXil Net
void xilnet_tcp_header (struct xilnet_tcp_conn conn, unsigned char* buf, int len) Parameters conn: TCP connection buf: Buffer containing tcp packet len: Length of tcp packet Returns Description None This function fills in the tcp header from the start of buf for the TCP connection conn. The tcp packet is of length len. It sets the flags in the tcp header. xilsock.h
Includes
void xilnet_tcp_send_pkt (struct xilnet_tcp_conn conn, unsigned char* buf, int len, unsigned char flags) Parameters conn: TCP connection buf: Buffer containing TCP packet len: Length of tcp packet Returns Description Includes The checksum calculated for the given udp/tcp packet This function sends a tcp packet, given by buf of length len, with flags (ack/rst/fin/urg/psh) from connection conn. xilsock.h
void xilnet_tcp_init_conns (void ) Parameters Returns Description Includes None None Initialize all TCP connections so that the states of all the connections specify that they are usable. xilsock.h
int xilnet_tcp_open_conn (unsigned short port) Parameters Returns Description Includes port: TCP port number Connection index if able to open a connection. If not returns -1. Open a TCP connection with port number port. xilsock.h
98
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
LibGen Customization
R
int xilnet_tcp_close_conn (struct xilnet_tcp_conn *conn) Parameters Returns Description Includes conn: TCP connection 1 if able to close else returns -1. Close a TCP connection conn. xilsock.h
int xilnet_icmp (unsigned char* buf, int len) Parameters buf: Buffer containing ICMP packet len: Length of the ICMP packet Returns Description 0 This is the icmp callback function which is called when ip receives a icmp echo request packet (ping request). This function checks only for a echo request and sends in an icmp echo reply. xilsock.h
Includes
void xilnet_icmp_echo_reply (unsigned char* buf, int len) Parameters buf: Buffer containing ICMP echo reply packet len: Length of the ICMP echo reply packet Returns Description None This functions fills in the icmp header from the start of buf. The icmp packet is of length len. It sends the icmp echo reply by calling the ip, ethernet send functions. This function is called from the icmp callback function. xilsock.h
Includes
LibGen Customization
XilNet library is customized through LibGen tool. Here is a snippet from system.mss file for specifying LibXilNet.
BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilnet PARAMETER LIBRARY_VER = 1.00.a PARAMETER device_type = ethernet PARAMETER emac_type = emac END
LibXilNet has the infrastructure to support different networking devices. The parameter device_type can take - ethernet, serial, host as values. Currently however ethernet is the device type that has been tested. With ethernet device type, LibXilNet can be used with either the regular ethernet core or the lite version, ethernetlite.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
99
R
Chapter 6: LibXil Net
The parameter emac_type can take - emac, emaclite as values. This configures XilNet to be used with either Emac of EmacLite driver.
Table 6-2:
Configurable Parameters for XilNet in MSS Description
Networking Device type used in the system Possible values are ethernet, serial, host. Type of ethernet core used. Possible values are emac, emaclite
Parameter
device_type emac_type
Using XilNet in Application
Libgen generates a configuration file xilnet_config.h based on the parameter selection in MSS file. In order to use the XilNet functions in your application, you need to do the following:
x x
Define “#include <net/xilnet_config.h>” in your C-file. Define “#include <net/xilsock.h>” in your C-file.
100
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 7
LibXil File
Xilinx libraries provide block access to file systems and devices using standard calls such as open, close, read, and write. These routines form the LibXil File module of the libraries. A system can be configured to use the LibXil File module, using the Library Generator (libgen). This chapter contains the following sections.
x x x x x
“Overview” “Module Usage” “Module Routines” “Libgen Support” “Limitations”
Overview
The LibXil library provides block access to files and devices through the LibXil File module. This module provides standard routines such as open, close, read, and write to access file systems and devices. The module LibXil File can also be easily modified to incorporate additional file systems and devices. This module implements a subset of operating system level functions.
Module Usage
A file or a device is opened for read and write using the open call in the library. The library maintains a list of open files and devices. Read and write commands can be issued to access blocks of data from the open files and devices.
Module Routines
Functions
int open (const char *name, int flags, int mode) int close (int fd) int read (int fd, char* buf, int nbytes) int write (int fd, char* buf, int nbytes)
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
101
R
Chapter 7: LibXil File
Functions
long lseek (int fd, long offset, int whence) int chdir (const char *buf) const char* getcwd (void) int open (const char *name, int flags, int mode) Parameters name refers to the name of the device/file. flags refers to the permissions of the file. This field does not have any meaning for a device. mode indicates whether the stream is opened in read, write or append mode. Returns Description file/device descriptor fd assigned by LibXil File This call registers the device or the file in the local device table and calls the underlying open function for that particular file or a device. xilfile.h xparameters.h int close (int fd) Parameters Returns fd refers to the file descriptor assigned during by open() If a file is being closed, returns the status returned by the underlying file system. For devices, it returns 1, since devices can not be closed. 0 indicates success in closing a file. Any other value indicates error Description Includes Close the file/device with the fd. xilfile.h xparameters.h int read (int fd, char* buf, int nbytes) Parameters fd refers to the file descriptor assigned by open() buf refers to the destination buffer where the contents of the stream should be copied nbytes: Number of bytes to be copied Returns Description Includes The number of bytes read. Read nbytes from the file/device pointed by the file descriptor fd and store it in the destination pointed by buf. xilfile.h xparameters.h
Includes
102
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Module Routines
R
int write (int fd, char* buf, int nbytes) Parameters fd: refers to the file descriptor assigned by open() buf: refers to the source buffer nbytes: Number of bytes to be copied Returns Description Includes The number of bytes written to the file. Write nbytes from the buffer, buf to the file pointed by the file descriptor fd xilfile.h xparameters.h long lseek (int fd, long offset, int whence) Parameters fd: file descriptor returned by open offset: Number of bytes to seek whence: Location to seek from. This parameter depends on the underlying File System being used. Returns Description Includes New file pointer location The lseek() system call moves the file pointer for fd by offset bytes from whence. xilfile.h xparameters.h int chdir (char* newdir) Parameters Returns Description Includes newdir: Destination directory The same value as returned by the underlying file system. -1 for failure. Change the current directory to newdir xilfile.h xparameters.h const char* getcwd (void) Parameters Returns Description Includes None The current working directory. Get the absolute path for the current working directory. xilfile.h xparameters.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
103
R
Chapter 7: LibXil File
Libgen Support
LibXil File Instantiation
The users can write application to either interact directly with the underlying file systems and devices or make use of the LibXil File module to integrate with file systems and devices. In order to instantiate LibXil File module in your system, use the following code in your MSS file.
BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilfile PARAMETER LIBRARY_VER = 1.00.a PARAMETER peripherals = ( ("<peripheral 1 instance name>", "<mount 1>") , ("<peripheral 2 instance name>", "<mount 2>") ) PARAMETER filesys = (( "<Filesystem 1 name>" , "<mount 1>" ), ( "<Filesystem 2 name>" , "<mount 2>" )) END
where
i i i
<peripheral 1 name> : Instance name of the peripheral you need to access through XilFile. <mount 1> : Mount name for the <peripheral 1> or <filesystem 1> <filesystem 1 name> : Name of the filesystem, you need to access through XilFile.
(1)
For example, to access two uarts ( myuart1 and myuart2) and the memory file system ( xilmfs ) , use the following code snippet.
BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilfile PARAMETER LIBRARY_VER = 1.00.a PARAMETER peripherals = ( ("myuart", "/dev/myuart") , ("myuart2", "/dev/myuart2") ) PARAMETER filesys = (( "xilmfs" , "/dev/mfs" )) END
System Initialization
LibGen also generates the system initialization file, which is compiled into the LibXil library. This file initialized the data structure required by the LibXil File module, such as the Device tables and the File System table. This routine also initializes STDIN, STDOUT and STDERR, if present.
Limitations
LibXil File module currently enforces the following restrictions:
1. Note that there is no instance name for filesystem and other Xilinx Microkernel modules. Hence, the name of the filesystem should be used instead of the instance name.
104
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Limitations
R
x x x x
Only one instance of a File System can be mounted. This file system and the mount point has to be indicated in the Microprocessor Software Specification (MSS) file. Files cannot have names starting with /dev, since it is a reserved word to be used only for accessing devices. Currently LibXil File has support only for 1 file system (LibXil Memory File System) and 3 devices (UART, UARTlite and GPIO). Only devices can be assigned as STDIN, STDOUT and STDERR.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
105
R
Chapter 7: LibXil File
106
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 8
LibXil FATFile System (FATfs)
This chapter describes the XilFatfs FATfile system access library. This library provides read/write access to files stored on a Xilinx SystemAce compact flash or microdrive device. The chapter contains the following sections.
x x x
“Overview” “XilFatfs Functions” “LibGen Customization”
Overview
The XilFatfs filesystem access library provides read/write access to files stored on a Xilinx SystemACE CompactFlash or IBM microdrive device. This library requires the underlying hardware platform to contain all of the following:
x x x
OPB SYSACE Interface Controller - Logicore module SystemACE controller and CompactFlash connector 128MB or 256MB CompactFlash card formatted with a FAT16, FAT12 or FAT32 file system or an IBM microdrive formatted with a FAT16, FAT12 or FAT32 file system
Caution! FAT16 is required for SystemACE to directly configure the FPGA but the XilFatfs
library can work with the SystemACE hardware to support FAT12 and FAT32 as well.
See the documentation on OPB SYSACE Interface Controller in the Processor IP Reference Guide for more details on the hardware. If this library is to be used in a MicroBlaze system, and speed is of concern, it is recommended that the MicroBlaze processor be configured to include a hardware barrel shifter. See the MicroBlaze documentation for more information on including the barrel shifter. Users can easily copy files to the flash device from their PC by plugging the flash or microdrive into a suitable USB adapter or similar device.
XilFatfs Functions
This section presents a list of functions provided by the XilFatfs. Table 8-1 provides the function names with signature at a glance.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
107
R
Chapter 8: LibXil FATFile System (FATfs)
Table 8-1:
XilFatfs Functions at a Glance Functions
void *sysace_fopen (const char *file, const char *mode) int sysace_fread (void *buffer, int size, int count, void *stream) int sysace_fwrite (void *buffer, int size, int count, void *stream) int sysace_fclose (void *stream) void *sysace_mkdir (const char *path) void *sysace_chdir (const char *path)
Detailed Description of XilFatfsFunctions
void *sysace_fopen (const char *file, const char *mode)
Parameters file is the name of the file on the flash device. address is the starting(base) address of the file system memory mode is restricted to “r” in this version Returns A non zero file handle on success 0 for failure Description The file name should follow the Microsoft 8.3 naming standard with a file name of up to 8 characters, followed by a ‘.’ and a 3 character extension. In this version of the library, the 3 character extension is mandatory so a sample file might be called test.txt This function returns a file handle that has to be used for subsequent calls to read or close the file If the named file does not exist on the device 0 is returned Includes sysace_stdio.h
108
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
XilFatfs Functions
R
int sysace_fread (void *buffer, int size, int count, void *stream) Parameters buffer is a pre allocated buffer that is passed in to this procedure, and is used to return the characters read from the device size is restricted to 1 count is the number of characters to be read stream is the file handle returned by sysace_fopen Returns Non zero number of characters actually read, for success 0 for failure Description The preallocated buffer is filled with the characters that are read from the device. The return value indicates the actual number of characters read, while count specifies the maximum number of characters to read. The buffer size must be at least count. stream should be a valid file handle returned by a call to sysace_fopen. sysace_stdio.h
Includes
int sysace_fwrite (void *buffer, int size, int count, void *stream) Parameters buffer is a pre allocated buffer that is passed in to this procedure, and contains the characters to be written to the device size is restricted to 1 count is the number of characters to be written stream is the file handle returned by sysace_fopen Returns Non zero number of characters actually written, for success 0 or -1 for failure Description The preallocated buffer is filled (by the caller) with the characters that are to be written to the device. The return value indicates the actual number of characters written, while count specifies the maximum number of characters to write. The buffer size must be at least count. stream should be a valid file handle returned by a call to sysace_fopen. sysace_stdio.h
Includes
int sysace_fclose (void *stream) Parameters Returns stream: File handle returned by sysace_fopen 1 On success 0 On failure Description Includes Closes an open file sysace_stdio.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
109
R
Chapter 8: LibXil FATFile System (FATfs)
int sysace_mkdir (const char *path) Parameters Returns path: path name of new directory 0 On success -1On failure Description Create a new directory specified by path. The directory name can be either absolute or relative, and must follow the 8.3 file naming convention. Examples: a:\\dirname, a:\\dirname.dir, a:\\dir1\\dirnew, dirname, dirname.dir If a relative path is specified, and the current working directory is not already set, the current working directory defaults to the root directory. Includes sysace_stdio.h
int sysace_chdir (const char *path) Parameters Returns path: path name of new directory 0 On success -1On failure Description Create a new directory specified by path. The directory name can be either absolute or relative, and must follow the 8.3 file naming convention. Examples: a:\\dirname, a:\\dirname.dir, a:\\dir1\\dirnew, dirname, dirname.dir If a relative path is specified, and the current working directory is not already set, the current working directory defaults to the root directory. Includes sysace_stdio.h
LibGen Customization
XilFatfs file system can be integrated with a system using the following snippet in the mss file. There are
BEGIN LIBRARY parameter LIBRARY_NAME = xilfatfs parameter LIBRARY_VER = 1.10.a # The following 3 parameters are optional and their default value is ‘n’ parameter CONFIG_WRITE = y parameter CONFIG_DIR_SUPPORT = y parameter CONFIG_FAT12 = y END
The CONFIG_WRITE parameter when set to ‘y’, adds write capabilities to the library.
110
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
LibGen Customization
R
The CONFIG_DIR_SUPPORT parameter when set to ‘y’, adds the mkdir and chdir functions to the library. The CONFIG_FAT12 parameter when set to ‘y’ configures the library to work with FAT12 file systems. Otherwise the library works with both FAT16 and FAT32 file systems.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
111
R
Chapter 8: LibXil FATFile System (FATfs)
112
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 9
LibXil Memory File System (MFS)
This chapter describes the Memory File System (MFS). This file system resides in RAM/ROM/Flash memory and can be accessed through the LibXil File module or directly. The Memory File System is integrated with a system using the Library Generator. The chapter contains the following sections.
x x x x x x
“Overview” “MFS Functions” “Utility Functions” “Additional Utilities” “C-like access” “LibGen Customization”
Overview
The Memory File System (MFS) component, LibXil MFS, provides users the capability to manage program memory in the form of file handles. Users can create directories, and can have files within each directory. The file system can be accessed from the high level C-language through function calls specific to the file system. Alternatively, users can also manage files through the standard C language functions like open provided in XilFile.
MFS Functions
Quick Glance
This section presents a list of functions provided by the MFS. Table 9-1 provides the function names with signature at a glance.
Table 9-1:
MFS Functions at a Glance Functions
void mfs_init_fs (int numbytes, char *address, int status) int mfs_change_dir (char *newdir) int mfs_get_current_dir_name (char *dirname) int mfs_create_dir (char *newdir) int mfs_delete_dir (char *newdir)
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
113
R
Chapter 9: LibXil Memory File System (MFS)
Table 9-1:
MFS Functions at a Glance Functions
int mfs_exists_file (char *filename) int mfs_delete_file (char *filename) int mfs_rename_file (char *from_file, char *to_file) int mfs_get_usage(int *num_blocks_used, int *num_blocks_free) int mfs_dir_open (char *dirname) int mfs_dir_close (int fd) int mfs_dir_read (int fd, char **filename, int *filesize, int *filetype) int mfs_file_open (char *filename, int mode) int mfs_file_read (int fd, char *buf, int buflen) int mfs_file_write (int fd, char *buf, int buflen) int mfs_file_close(int fd) long mfs_file_lseek (int fd, long offset, int whence) int mfs_ls (void) int mfs_cat (char *filename) int mfs_copy_stdin_to_file (char *filename) int mfs_file_copy (char *from_file, char *to_file)
114
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
MFS Functions
R
Detailed summary of MFS Functions
int mfs_init_fs (int numbytes, char *address, int status) Parameters numbytes is the number of bytes of memory available for the file system address is the starting(base) address of the file system memory status is one of MFSINIT_NEW, MFSINIT_IMAGE or MFSINIT_ROM_IMAGE
Returns
1 for success 0 for failure
Description
Initialize the memory file system. This function must be called before any file system operation. The status/mode parameter determines certain filesystem properties: MFSINIT_NEW creates a new, empty file system for read/write MFSINIT_IMAGE initializes a filesystem whose data has been previously loaded into memory at the base address MFSINIT_ROM_IMAGE initializes a Read-Only filesystem whose data has been previously loaded into memory at the base address
Includes
xilmfs.h
int mfs_change_dir (char *newdir) Parameters Returns newdir is the chdir destination. 1 for success 0 for failure Description Includes If newdir exists, make it the current directory of MFS. Current directory is not modified in case of failure. xilmfs.h
int mfs_create_dir (char *newdir) Parameters Returns newdir: Directory name to be created On success, return index of new directory in the file system On failure, return 0 Description Includes Create a new empty directory called newdir inside the current directory. xilmfs.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
115
R
Chapter 9: LibXil Memory File System (MFS)
int mfs_delete_dir (char *dirname) Parameters Returns dirname: Directory to be deleted On success, return index of new directory in the file system On failure, return 0 Description Includes Delete the directory dirname, if it exists and is empty, xilmfs.h
int mfs_get_current_dir_name (char *dirname) Parameters Returns dirname: Current directory name is returned in this pointer On Success return 0 On failure return 1 Description Return the name of the current directory in a pre allocated buffer, dirname, of at least 16 chars.Note that it does not return the absolute path name of the current directory, but just the name of the current directory xilmfs.h
Includes
int mfs_delete_file (char *filename) Parameters Returns filename: file to be deleted 1 for success 0 for failure Description Includes Delete filename from its directory. xilmfs.h
int mfs_rename_file (char *from_file, char *to_file) Parameters from_file: Original filename to_file: New file name Returns On success, return 1 On failure, return 0 Description Includes Rename from_file to to_file. Rename works for directories as well as files. Function fails if to_file already exists. xilmfs.h
116
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
MFS Functions
R
int mfs_exists_file (char *filename) Parameters Returns filename: file/directory to be checked for existence 0: if filename does not exist 1: if filename is a file 2: if filename is a directory Description Includes Check if the file/directory is present in current directory. xilmfs.h
int mfs_get_usage (int *num_blocks_used, int *num_blocks_free) Parameters num_blocks_used: Number of blocks used num_blocks_free: Number of free blocks Returns On Success return 0 On failure return 1 Description Includes Get the number of used blocks and the number of free blocks in the file system through pointers. xilmfs.h
int mfs_dir_open (char *dirname) Parameters Returns Description Includes dirname: directory to be opened for reading The index of dirname in the array of open files or -1 on failure. Open directory dirname for reading. Reading a directory is done using mfs_dir_read() xilmfs.h
int mfs_dir_close (int fd) Parameters Returns fd: File descriptor return by open On success return 1 On failure return 1 Description Includes Close the dir pointed by fd. The file system regains the fd and uses it for new files. xilmfs.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
117
R
Chapter 9: LibXil Memory File System (MFS)
int mfs_dir_read (int fd, char **filename, int *filesize, int *filetype) Parameters fd: File descriptor return by open; passed to this function by caller filename: Pointer to file name at the current position in the directory in MFS; this value is filled in by this function filesize: Pointer to a value filled in by this function: Size in bytes of filename, if it is a regular file; Number of directory entries if filename is a directory filetype: Pointer to a value filled in by this function: MFS_BLOCK_TYPE_FILE if filename is a regular file; MFS_BLOCK_TYPE_DIR if filename is a directory Returns On Success return number of bytes read. On Failure return 1 Description Read the current directory entry and advance the internal pointer to the next directory entry. filename, filetype and filesize are pointers to values stored in the current directory entry xilmfs.h
Includes
int mfs_file_open (char *filename, int mode) Parameters filename: file to be opened mode: Read/Write or Create mode. Returns Description The index of filename in the array of open files or -1 on failure. Open file filename with given mode. The function should be used for files and not directories: MODE_READ, no error checking is done (if file or directory). MODE_CREATE creates a file and not a directory. MODE_WRITE fails if the specified file is a DIR. Includes xilmfs.h
int mfs_file_read (int fd, char *buf, int buflen) Parameters fd: File descriptor return by open buf: Destination buffer for the read buflen: Length of the buffer Returns On Success return number of bytes read. On Failure return 1 Description Read buflen number bytes and place it in buf. fd should be a valid index in “open files” array, pointing to a file, not a directory. buf should be a pre-allocated buffer of size buflen or more. If fewer than buflen chars are available then only that many chars are read. xilmfs.h
Includes
118
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
MFS Functions
R
int mfs_file_write (int fd, char *buf, int buflen) Parameters fd: File descriptor return by open buf: Source buffer from where data is read buflen: Length of the buffer Returns On Success return 1 On Failure return 1 Description Write buflen number of bytes from buf to the file. fd should be a valid index in open_files array. buf should be a pre-allocated buffer of size buflen or more. xilmfs.h
Includes
int mfs_file_close (int fd) Parameters Returns fd: File descriptor return by open On success return 1 On failure return 1 Description Includes Close the file pointed by fd. The file system regains the fd and uses it for new files. xilmfs.h
long mfs_file_lseek (int fd, long offset, int whence) Parameters fd: File descriptor return by open offset: Number of bytes to seek whence: File system dependent mode: If whence is MFS_SEEK_END, the offset can be either 0 or negative, otherwise offset should be non-negative. If whence is MFS_SEEK_CURR, the offset is calculated from the current location If whence is MFS_SEEK_SET, the offset is calculated from the start of the file Returns On success, return offset from the beginning of the file to the current location On failure, return -1; the current location is not modified Description Seek to a given offset within the file at location fd in open_files array. It is an error to seek before beginning of file or after the end of file. Includes xilmfs.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
119
R
Chapter 9: LibXil Memory File System (MFS)
Utility Functions
The following few functions are utility functions that can be used along with Xilinx MFS. These functions are defined in mfs_filesys_util.c and are not declared in xilmfs.h. They must be declared by the user if needed. int mfs_ls (void) Parameters Returns None On success return 1 On failure return 0 Description Includes List contents of current directory on STDOUT. xilmfs.h
int mfs_cat (char *filename) Parameters Returns filename: File to be displayed On success return 1 On failure return 0 Description Includes Print the file to STDOUT. xilmfs.h
int mfs_copy_stdin_to_file (char *filename) Parameters Returns filename: Destination file. On success return 1 On failure return 0 Description Includes Copy from STDIN to named file. xilmfs.h
int mfs_file_copy (char *from_file, char *to_file) Parameters Returns from_file: Source file to_file: Destination file On success return 1 On failure return 0 Description Includes Copy from_file to to_file. It fails if to_file already exists, or if either could not be opened. xilmfs.h
120
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Additional Utilities
R
Additional Utilities
A program called mfsgen is provided along with the MFS library. mfsgen can be used to create an MFS memory image on a host system that can subsequently be downloaded to the embedded system memory. mfsgen itself links to libXilMFS and is compiled to run on the host machine rather than the target MicroBlaze or PowerPC system. Conceptually, this is similar to the familiar zip or tar programs. The source code for mfsgen is provided in the file mfsgen.c in the utils sub-directory. The executable image should be in the path. An entire directory hierarchy on the host system can be copied to a local MFS file image using mfsgen. This file image can then be downloaded on to the memory of the embedded system for creating a pre-loaded file system. A few test programs are included to show how this is done. More information can be found in the readme.txt file in the utils subdirectory and the “Using XilMFS” chapter in the Platform Studio User Guide. Usage: mfsgen -txcvsbf [mfs_filename] [num_blocks] <filelist> Specify exactly one of c,t,x modes t: list the files in the mfs file system image c: create an mfs file system image using the list of files specified on the command line Directories specified in this list are traversed recursively x: extract the mfs file system from image to host file system v: verbose mode f: specify the host file name (mfs_filename) where the mfs file system image is stored If the f option is specified the mfs filename should be specified If the f option is omitted the default file name is filesystem.mfs
s: switch endianness b: number of blocks - should be more than 2 If the b option is specified the num_blocks value should be specifed If the b option is omitted the default value of num_blocks is 5000 The b option is meaningful only when used in conjunction with the c option
C-like access
The user can choose not to deal with the details of the file system by using the standard Clike interface provided by Xil File. It provides the basic C stdio functions like open, close, read, write, and seek. These functions have identical signature as those in the standard ANSI-C. Thus any program with file operations performed using these functions can be easily ported to MFS by interfacing the MFS in conjunction with library Xilfile.
LibGen Customization
Memory file system can be integrated with a system using the following snippet in the mss file. The memory file system should be instantiated with the name xilmfs. The attributes used by libgen and their descriptions are given in Table 9-2.
BEGIN LIBRARY parameter LIBRARY_NAME = xilmfs parameter LIBRARY_VER = 1.00.a
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
121
R
Chapter 9: LibXil Memory File System (MFS)
parameter parameter parameter parameter END
numbytes= 50000 base_address = 0xffe00000 init_type = MFSINIT_NEW need_utils = false
Table 9-2:
Attributes for including Memory File System Description
Number of bytes allocated for file system. Starting address for file system memory MFSINIT_NEW (default) or MFSINIT_IMAGE or MFSINIT_ROM_IMAGE MFSINIT_NEW creates a new, empty file system MFSINIT_ROM_IMAGE creates a file system based on a preloaded memory image loaded in memory of size numbytes at starting address base_address. This memory is considered readonly and modification of the file system is not allowed. MFS_INIT_IMAGE is similar to the previous option except that the file system can be modified, and the memory is considered to be readable and writeable.
Attributes
numbytes base_address init_type
need_utils
true or false (default = false) If true, this causes stdio.h to be included from mfs_config.h. The functions described in the “Utility Functions” section require stdin or stdout to be defined, and setting need_utils to true causes stdio.h to be included.
Caution! The underlying software and hardware platforms must
support stdin and stdout peripherals for these utility functions to compile and link correctly.
122
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 10
LibXil Profile
This chapter describes the profiling library for embedded processors, libXil Profile. The chapter contains the following sections:
x x x x x x x x
“Overview” “Features” “Profiling Model” “Customizing xilprofile” “Building Applications” “Generating GPROF Files” “XilProfile Code Description” “Limitations”
Overview
Profiling a program running on hardware (board), provides insight into program execution and identifies where it spends most time. Profiling on hardware is faster and the interaction of program with memory and other peripherals can be more accurately captured. LibXil Profile is a software intrusive profile library that generates Call Graph and Histogram information of program running on board. Executing the program on hardware generates the profiling information which is stored on the hardware. XMD generates output file from the data, which can be read by GNU gprof tools (mb-gprof) to generate the profiling information.Profiling is supported for the MicroBlaze processor.
Features
LibXil Profile library has the following features:
x
Provides Histogram (flat profile) and Call Graph information.
i i
Histogram: Shows how much time the program spent in each function and how many times the function was called. Call Graph: Shows for each function, which functions called it, which other functions it called and how many times.
x x
Profiling parameters are configurable - Sampling Frequency, Histogram Bin Size and Timer to use. Memory location and size to store profiling is flexible and configurable based on program requirements.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
123
R
Chapter 10: LibXil Profile
Profiling Model
The libxil profile library, libxilprofile.a is generated and customized for software platform by instantiating the xilprofile library. Running LibGen will create this library. For more details of Profiling flow refer to the “Profiling Embedded Designs” chapter in the Platform Studio User Guide. When the profile option -pg is specified to the compiler (mb-gcc and powerpc-eabi-gcc), this library is automatically linked with the application to profile. The generated executable file contains code to generate profile information. When the program is executed on board, the profile information is stored at the memory location specified by the user. XMD is profile library “aware” and generates the gprof compatible output file based on profile data.
Note: The xilprofile library does not have any explicit application API. The library is linked due to profile calls (_mcount) introduced by gcc for profiling. The are some global variables that need to be set in the application for using the library. This is explained in the later sections.
Customizing xilprofile
The xilprofile library can be customized for an application. Following is the list of PARAMETERS for the library.
Table 10-1:
xilprofile custom PARAMETERS Name Type
int
Defaults
4
Description
For Histogram calculation, the program is divided into equal sized bins. This parameter specifies the bin size in bytes. This depends on function size. Frequency of sampling for histogram calculation. This determines the accuracy of histogram calculation. The opb_timer instance name to use for profiling in the system. If there is no function pointer in the program, xilprofile uses a method which requires less memory. Setting this parameter to TRUE enables this mode of operation.
histogram_binsize
histogram_sample_freq_hz
int
100,000
histogram_timer callgraph_no_funcptr
peripheral instance name boolean
none false
Building Applications
The memory needed for storing profile information is allocated in the user application. The memory can be either an array allocated in program or any memory in the hardware system. The latter gives the flexibility to specify any available memory in the system without changing the program’s size or custom linker script. This memory is specified to xilprofile library by two pointer variables in the application.
x x
char *memstart - Points to start of memory location. char *memend - Points to end of memory location.
124
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Generating GPROF Files
R
Application Memory Requirements
The memory needed for profiling is dependent on the program’s text section size, number of function calls, and presence of function calls. The user can calculate the memory required for profiling by using the TCL file calc_profilemem.tcl Syntax: calc_profilemem.tcl -target <mblaze> -elf <Executable File compiled without pg option> -bin <Histogram BIN Size> Usage: xmd calc_profilemem.tcl -target mblaze -elf executable.elf -bin 4 xilprofile library assumes that the amount of memory allocated is correct and sufficient for the application. This is done to conserve valuable memory. XMD uses the same algorithm to perform memory testing during program download.
Generating GPROF Files
XMD helps in the generation of output files that can be read by GNU gprof tools. XMD does the following functions for profiling. 1. 2. Test if the amount of memory is sufficient for profiling. This test is done when the ELF file is downloaded and is compiled with the -pg option. Read the stored profile information from hardware and generate output files. This is done by the following XMD command. Syntax: profile out [-o <Output gmon filename> If output gmon file is not specified, file gmon.out is generated. Sample Profiling Session using XMD:
Xilinx Microprocessor Debug (XMD) Engine Xilinx EDK 6.2 Build EDK_Gm.8 Copyright (c) 1995-2002 Xilinx, Inc. All rights reserved. XMD% mbconnect mdm JTAG chain configuration -------------------------------------------------Device ID Code IR Length Part Name 1 0124a093 10 XC2VP7 Assuming, Device No: 1 contains the MicroBlaze system Connected to the JTAG MicroBlaze Debug Module (MDM) No of processors = 1 MicroBlaze Configuration : -------------------------Version............................2.00.a No of PC Breakpoints...............4 No of Read Addr/Data Watchpoints...1 No of Write Addr/Data Watchpoints..1 Instruction Cache Support..........off Data Cache Support.................off Connected to MicroBlaze "mdm" target. id = 0 Starting GDB server for "mdm" target (id = 0) at TCP port no 1234 XMD% dow microblaze_0/code/executable.elf **************************************************************** ** Profiling Memory Test ** Executable: microblaze_0/code/executable.elf ** Memory Allocated: 4200
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
125
R
Chapter 10: LibXil Profile
** Profile Type: PROFILE_FUNCPTR ** Histogram BinSize: 4 **************************************************************** Program Text Size........................5232 No. of Func. Calls.......................33 No. of Func. Ptr. Calls..................3 Memory Histogram Tables..................654 Memory Call Graph Tables.................864 Total Profile Memory required............1518[SUCCESS] XMD% bps 0x470 Setting breakpoint at 0x00000470 XMD% con Processor started. Type "stop" to stop processor RUNNING> stop XMD% profile out Processor stopped at PC: 0x0000177c Profile data written to gmon.out XMD%
GNU gprof tool (mb-gprof) tools can be used to read the output file. Refer to the Manual page of gprof for more information on usage.
XilProfile Code Description
XilProfile source code is located at $XILINX_EDK/sw/lib/sw_services/xilprofile_v1_00_a directory. Some of the important functions are:
x
_program_init - This function is called before function main of an application. This function does memory and timer initialization. It allocates memory for histogram (inferred from symbols _ftext and _etext) and call graph based on xilprofile parameters. It initializes the timer routine, registers timer handler accordingly based on timer used and connection to processor and starts the timer. The TCL routine of xilprofile library figures the timer type and connection to processor and generates the #defines. Refer to the “Microprocessor Library Definition (MLD)” chapter in the Embedded System Tools Guide. mcount - This function is called by _mcount function, which is inserted at every function start by gcc. This function records the caller and callee information (Instruction address), which is used to generate call graph information. Based on whether function pointers are present or not, different information is stored. This is done to decrease memory needed for profiling if there are no function pointers in the application. profile_intr_handler - This is the interrupt handler for the profiling timer. The timer is set to sample the executing application for PC values at fixed intervals and increment the Bin count. This is used to generate the histogram information.
x
x
To generate profile output, XMD needs to read xilprofile customization parameters value, profile memory location on the hardware, and actual profile data. XMD does this with the help of global variables in the xilprofile code. The following are the variables used.
x x x x
memstart, memend - determines the profile memory used. binsize - determines the Histogram BIN size used. sample_freq_hz - determines the Sampling Frequency used. profile_no_funcptr - determines the method used for call graph.
126
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Limitations
R
x
_gmonparam - Data stored during profiling and information about the data. Refer profile.h file for more details on this structure.
Limitations
The profiled program (text section) should exist as contiguous memory.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
127
R
Chapter 10: LibXil Profile
128
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 11
lwIP Library
Overview
This chapter describes the Embedded Development Kit (EDK) port of the third party network library, Light Weight IP (lwIP), for embedded processors. The chapter details the port of the lwIP library for PowerPC and MicroBlaze processors. It contains the following sections:
x x x x x x
“Overview” “PowerPC System” “MicroBlaze System” “Setting Up lwIP in EDK” “Designing an lwIP Application” “Example lwIP Application”
lwIP is an open source implementation of the TCP/IP protocol suite. The lwIP library supports two interfaces - raw API, BSD style Sockets API. EDK has been ported to work with the raw API interface of the library. The features of the lwIP library are :
x x x x x
IP (Internet Protocol) including packet forwarding on multiple interfaces ICMP (Internet Control Message Protocl) UDP (User Datagram Protocol) TCP (Transmission Control Protocol) .Raw API interface support for applications
The raw API provided by lwIP is the lowest level interface of the stack. It has two modes of operation : Event and Callback. The EDK port uses the Callback mode. lwIP stack maintains internal timers for TCP round trip calculations, retransmissions and other TCP facilities. For this purpose, the lwIP timer functions must be called periodically. This is achieved by using the 64-bit hardware timer in PowerPC. For MicroBlaze an external timer is required. The system design involved for both MicroBlaze and PowerPC are discussed in the following sections.
PowerPC System
Figure 11-1 shows an example hardware design of a PowerPC based system for lwIP. The system requires a 10/100 ethernet core for performing the network transactions. The builtin hardware timer is used to call the lwIP timer functions periodically.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
129 Embedded Development Kit
R
Chapter 11: lwIP Library
PLB SDRAM MEMC
OPB 10/100 Ethernet
DSPLB ISPLB INT
BRAM MEMC PPC405 Non-Crit INTC
32 KB BRAM PLB2OPB BRIDGE
UART 16450
GPIO
UG114_11_01_051404
Figure 11-1: PowerPC System Design for lwIP-Based Echo Server
MicroBlaze System
MicroBlaze does not supoprt an in-built timer. An OPB based timer provides the timer functionality. The system uses the OPB based 10/100 regular ethernet core. A diagram of an example MicroBlaze system design is shown in Figure 11-2.
OPB SDRAM MEMC ILMB DLMB 10/100 Ethernet MDM
MICROBLAZE
ILMB DLMB IOPB DOPB Interrupt
GPIO UART 16550 OPB TIMER
UG114_11_02_051404
BRAM MEMC
32K BRAM
BRAM MEMC
Figure 11-2:
MicroBlaze System Design for lwIP-Based Echo Server
130 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Memory Management
R
Memory Management
There are two types of memory management in lwIP; the heap memory (mem) and the static memory pools (memp). The pbuf management is a hybrid since it both manages its own memory (th pbuf pool) and uses the heap (mem). The mem is a heap memory manager, such as the C malloc/free manager. A block of memory is requsted with a call to mem_malloc( ) and the memory is freed with a call to mem_free( ). This is used by code that allocates memory of diffrent sizes. An example is when contents of a packet needs to be copied into a buffer - since the size of the packet isn’t known beforehand, the memory is allocated from the heap. The memp, on the other hand, uses a set of pools of fixed size memory blocks. This is used by the lwIP stack code to allocate predefined memory blocks. An example is for lwIP stack to allocate memory for TCP protocol control blocks. The pbufs are used to hold packet data. These are to be used by a network device driver who needs to allocate buffers quickly. The memory options are defined in lwipopts.h file. The memory options in lwipopts.h are as follows:
Table 11-1:
Memory Option Settings for lwIP Option Name Description
The size of the heap. If the application will send a lot of data that needs to be copied, this should be set high. The number of memp struct pbufs. If the application sends a lot of data out of ROM (or other static memory), this should be set high. The number of UDP protocol control blocks. One per active UDP "connection." The number of simulatenously active TCP connections. The number of listening TCP connections. The number of simultaneously queued TCP segments.
MEM_SIZE
MEMP_NUM_PBUF
MEMP_NUM_UDP_PCB MEMP_NUM_TCP_PCB MEMP_NUM_TCP_PCB_LISTEN MEMP_NUM_TCP_SEG
Setting Up lwIP in EDK
lwIP is customized using the libgen tool. lwIP supports multiple 10/100 ethernet network interfaces. The 48-bit MAC addresses associated with each of the interfaces are given alongwith the ethernet instances used in the MHS file. In order to set up lwIP library in XPS, open the software settings dialog. Select lwip 1.00.a library and click on the Library/OS Parameters tab. Enter the 10/100 ethernet instance names from the MHS file that would be used with the lwIP library. For each of the ethernet instance, a 48-bit MAC address is also specified. The following is an MSS snippet for lwIP library :
BEGIN LIBRARY PARAMETER LIBRARY_NAME = lwip PARAMETER LIBRARY_VER = 1.00.a PARAMETER EMAC_INSTANCES = ((my_opb_ethernet,0x00,0x00,0x00,0x00,0x22,0x38))
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
131 Embedded Development Kit
R
Chapter 11: lwIP Library
END
Running libgen tool in XPS generates liblwip4.a library in <processor_instance_name>/lib directory in the project area. Applications designed with lwIP should link with this library to get the lwIP functionality. To link a library, open the Compiler options for the application and in the Linker Options, set lwip4 as a library to be used for linking.
libgen Customization
lwIP library is customized through libgen tool. Here is a snippet from system.mss file for specifying lwIP library.
BEGIN LIBRARY PARAMETER LIBRARY_NAME = lwip PARAMETER LIBRARY_VER = 1.00.a PARAMETER EMAC_INSTANCES = ((my_opb_ethernet,0x00,0x0A,0x35,0x00,0x22,0x20)) END
lwIP has the infrastructure to support multiple ethernet interfaces. The parameter emac_instances is an array. It takes in the instance name of an ethernet core (specified in the MHS file) and the 48-bit MAC address corresponding to it. This configures lwIP to use a particular ethernet instance with the 48-bit MAC address.
Table 11-2:
Configurable Parameters for lwIP in MSS Parameter Name Description
This is an array with parameters emac_instname and the ethernet addresses.This is a list of ethernet instances that are to be used with lwIP.
emac_instances
emac_instname eth_addr0 eth_addr1 eth_addr2 eth_addr3 eth_addr4 eth_addr5
Name of the ethernet instance from the MHS file First byte of the 6-byte MAC address Second byte of the 6-byte MAC address Third byte of the 6-byte MAC address Fourth byte of the 6-byte MAC address Fifth byte of the 6-byte MAC address Sixth byte of the 6-byte MAC address
Designing an lwIP Application
Software applications using lwIP should follow certain structure. As mentioned in the previous sections, the lwIP stack requires its timer functon to be called periodically. For PowerPC, the in-build timer is used to calculate the time period. In case of MicroBlaze an external timer is used for providing fixed time periods. For more information on lwIP refer : http://savannah.nongu.org/projects/lwip.
132 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Designing an lwIP Application
R
Initializing lwIP
lwIP requires the application to call several initialization routines. The following is a code snippet that illustrates the initialization routines required for lwIP.
/*************************************************************** * CalllwIP Initialization Routines *****************************************************************/ sys_init(); mem_init(); memp_init(); pbuf_init(); netif_init(); tcp_init(); /*************************************************************** * Setup our 1 network interface (netif)*************************************************************** **/ netif = netif_add(&ip_addr, &net_mask, &gw, &XEmacIF_ConfigTable[0], xemacif_init, ip_input); netif_set_default(netif);
An example application is discussed in later sections to illustrate these requirements
lwIP Raw API
The raw API of lwIP is the lowest leve interface to the stack. It is also the most efficient interface because it provides direct access to the stack rather than providing extra buffering and message passing features. The following sections describe the most used interface functions. A more detailed description of the raw API is found in the lwIP source tree ($XILINX_EDK/sw/lib/sw_services/lwip_v1_00_a/src/lwip/doc/rawapi.txt). Asynchronous network events (data received, connection established etc.) are communicated to the application through callback functions. These callbacks are registered during the initialization of the TCP connection using the raw API. Table 6-2 lists the events and associated callback routines.
Table 11-3:
TCP Events, Callbacks, and Hot to Register Callback Events Event Callback
*accept() *sent() *recv()
Register with lwIP
tcp_accept() tcp_sent() tcp_recv()
TCP connection established TCP Data Acknowledged by Remote Host TCP Data Received
The following section, “Raw APO Functions for TCP,” lists a subset of TCP related functions. For a complete list of functions for other protocols, see: ($XILINX_EDK/sw/lib/sw_services/lwip_v1_00_a/src/lwip/doc/rawapi.txt)
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
133 Embedded Development Kit
R
Chapter 11: lwIP Library
Raw APO Functions for TCP
void* tcp_init ()
This function must be called first to initialize the lwIP stack
void tcp_tmr()
This function must be called every TCP_TMR_INTERVAL milliseconds (defined in file lwipopts.h). There are two lower level timer functions which are called inside tcp_tmr( ). The example application calls these functions directly - they are: tcp_slowtmr( ) and tcp_fasttmr( ).
struct tcp_pcb * tcp_new()
tcp_new creates a new TCP Protocol Control Block (PCB) structure. void tcp_arg (struct tcp_pcb* pcb, void* arg) tcp_arg Allows the application to register an argument that will be passed back to the application for all callback functions. This argument, arg, is usually used as a pointer to a structure that holds application state information.
err_t tcp_bind (struct tcp_pcb* pcb, struct ip_addr* ip_addr, u16_t port)
Binds the pcb to an IP address, ip_addr and TCP port number port
struct tcp_pcb* tcp_listen (struct tcp_pcb* pcb)
The tcp_listen function instructs the lwIP stack to put the pcb in listen state. The pcb will start to listen for connections on the IP address and port number specified in tcp_bind. When a new connection is established, lwIP calls the callback application function specified using the tcp_accept function.
void tcp_accept (struct tcp_pcb* pcb, err_t (*accept)(void* arg, struct tcp_pcb* newpcb, err_t err))
The tcp_accept function allows the application to register a callback function, accept. The lwIP stack calls the accept function when a new connection is established on a pcb that is in the listening state.
134 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
err_t tcp_write (struct tcp_pcb* pcb, void* dataptr, u16_t len, u8_t copy)
The tcp_write function will write len bytes of data from dataptr to the transmit queue. The copy argument specifies whether or not the stack should copy the data or reference it using the pointer dataptr.
void tcp_sent (struct tcp_pcb* pcb, err_t (*sent)(void* arg, struct tcp_pcb* tpcb, u16_t len))
The tcp_sent function registers the sent callback function. The lwIP stack calls the sent function when data is acknowledged by the remote host. The len argument indicates the number of bytes acknowledged. Once the bytes are acknowledged, the bytes are removed from the transmit buffer creating more space. This is useful when trying to send large amount of data using lwIP. If the tcp_write function fails because the transmit buffer is full, this callback function allows the application to write additional data once buffer space becomes available.
void tcp_recv (struct tcp_pcb* pcb, err_t (*recv)(void* arg, struct tcp_pcb* tpcb, struct pbuf* p, err_t err))
The tcp_recv function registers the recv callback function. The lwIP stack calls the recv function when new data arrives on the connection. The p argument is NULL when the connection is closed.
Example lwIP Application
The following is a simple TCP based echo server application. The echo server is listening for connections on port 7, and echoes the data sent by the client. The following sections discuss the application run on both PowerPC and MicroBlaze.
PowerPC based Echo Server
The hardware system for the example is shown in Figure 11-1. Assign drivers to each of these peripherals. Select lwip library as shown before and configure the library with the ethernet instance name and the 6-byte MAC address. The lwip library, liblwip4.a, gets generated in <PROCESSOR_INSTANCE_NAME>/lib/ directory once libgen is run.
C Program
The application is split among the following C and headerf files.
FileName : echo_main.c
/* . . * XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
135 Embedded Development Kit
R
Chapter 11: lwIP Library
. . . . . . . . . . . . .
* XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION * * * * * * * * * * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. *
* (c) Copyright 2002, 2003 Xilinx, Inc. * All rights reserved. * */
/* . * Copyright (c) 2001, 2002, 2003 Swedish Institute of Computer Science. . * All rights reserved. *
. * Redistribution and use in source and binary forms, with or without . * modification, are permitted provided that the following conditions . * are met: * . * 1. Redistributions of source code must retain the above copyrightnotice, . * this list of conditions and the following disclaimer.
. * 2. Redistributions in binary form must reproduce the above copyright notice, . * this list of conditions and the following disclaimer in the documentation . * and/or other materials provided with the distribution.
. * 3. The name of the author may not be used to endorse or promoteproducts . * derived from this software without specific prior written
permission. * . * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS OR . * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES
136 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN . * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,INCIDENTAL, . * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOTLIMITED . * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR . * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF . * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING . * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS . * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */
/* Xilinx Includes */ #include "xuartns550_l.h" #include "xtime_l.h" #include "xparameters.h" #include "xcache_l.h" #include "xgpio_l.h" /* lwIP Includes */ #include "netif/xemacif.h" #include "lwip/tcp.h" #include "lwip/memp.h" #include "netif/etharp.h" #include "echo.h" #define UART_BASEADDR XPAR_MYUART_16550_BASEADDR #define UART_CLOCK (XPAR_XUARTNS550_CLOCK_HZ) #define UART_BAUDRATE (115200) #define LWIP_TIMER_CYCLES (XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ / 1000 \ * TCP_TMR_INTERVAL ) // Upper 6 bytes of MAC #define XILINX_MAC_OUI0 #define XILINX_MAC_OUI1 #define XILINX_MAC_OUI2
- Xilinx Ethernet OUI = 00-0A-35 0x00 0x00 0x00
static void show_dotted_decimal( char * address_array); static void show_dashed_hex( int bytes, char *address_array); // Static Global Variables static u8_t my_timer = 0; // External Global Variables /* defined in lwip/src/core/tcp.c */ extern u32_t tcp_ticks;
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
137 Embedded Development Kit
R
Chapter 11: lwIP Library
/* defined in EDK generated xemacif_g.c file */ extern XEmacIf_Config XEmacIf_ConfigTable[]; /*------------------------------------------------------------------*/ * show dotted decimal prints a dotted decimal address to the UART*-----------------------------------------------------------------*/ static void show_dotted_decimal( char *address_array) { int bb; char temp; for(bb=0;bb<4;bb++) { temp = address_array[bb]; if(bb!=0) xil_printf("."); xil_printf("%d", (int) temp); } } /*------------------------------------------------------------------*/ /* show dashed hex prints a dashed hex address to the UART */ /*------------------------------------------------------------------*/ static void show_dashed_hex( int bytes, char *address_array) { //Assumes the caller passes the correct number of bytes int bb; for(bb=0;bb<bytes;bb++) { if(bb !=0) xil_printf("-"); xil_printf("%02X", (int) address_array[bb]); } } /*------------------------------------------------------------------*/ /* my_tmr - Called Periodically to dispatch TCP and ARP timers */ /*------------------------------------------------------------------*/ void my_tmr(void) { ++my_timer; if(my_timer == 10) { my_timer = 0; } if(my_timer & 1) { /* Call tcp_fasttmr() every 2 ms, i.e., * every other timer my_tmr() is called. */
138 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
tcp_fasttmr(); } if(my_timer == 0 || my_timer == 5) { /* Call tcp_slowtmr() every 5 ms, i.e., * every fifth timer my_tmr() is called. */ tcp_slowtmr(); if (tcp_ticks%2000 == 0) /* Call etharp_tmr() every 20th call to tcp_slowtmr(). * tcp_ticks is a global var defined in core/tcp.c */ etharp_tmr(); } } /*------------------------------------------------------------------*/ /* print_app_header - prints the legal header */ /*------------------------------------------------------------------*/ void print_app_header() { xil_printf("\n\n\n\n\n\n\n\n\n"); xil_printf("########################################################## ########## \n"); xil_printf("# Xilinx TCP/IP Demo Application (ECHO Server) #\n"); xil_printf("# \n"); xil_printf("# XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION ’AS IS’ #\n"); xil_printf("# SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR # \n"); xil_printf("# XILINX DEVICES. # \n"); xil_printf("# # \n"); xil_printf("# (c) Copyright 2003, 2003 Xilinx, Inc. # \n"); xil_printf("# All rights reserved. # \n"); xil_printf("# # \n"); xil_printf("########################################################## ########## \n"); } /*------------------------------------------------------------------*/ /* main function */ /*------------------------------------------------------------------*/ int main_main ()
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
139 Embedded Development Kit
R
Chapter 11: lwIP Library
{ struct tcp_pcb *gddpp_pcb; struct ip_addr ipaddr, netmask, gw; struct netif *default_netif; char menu_select = 0; XTime ml_base, ml_new, ml_offset; int waiting_for_timer = 1; char low_mac[3] = {0x00,0x22,0x38}; char fullmac[6] = {XILINX_MAC_OUI0, XILINX_MAC_OUI1, XILINX_MAC_OUI2, low_mac[0], low_mac[2], low_mac[3]}; char ip[4] = {149,199,6,108}; char subnet[4] = {255,255,255,0}; char gateway[4] = {149,199,6,254}; unsigned int init_wait = 15000000; /*---------------------------------------------------------------* Uart Init* *---------------------------------------------------------------*/ /* Disable Interrupts */ XIo_Out8(UART_BASEADDR + XUN_LCR_OFFSET, 0UL); XIo_Out8(UART_BASEADDR + XUN_IER_OFFSET, 0UL); /* Clear Latches */ XIo_In8(UART_BASEADDR + XUN_LSR_OFFSET); XIo_In8(UART_BASEADDR + XUN_IIR_OFFSET); XIo_In8(UART_BASEADDR + XUN_MSR_OFFSET); /* Disable FIFOs (16450) */ XIo_Out8(UART_BASEADDR + XUN_FCR_OFFSET, 0UL); /* Normal ABQ level 0 driver inits */ XUartNs550_SetBaud(UART_BASEADDR, UART_CLOCK, UART_BAUDRATE); XUartNs550_mSetLineControlReg(UART_BASEADDR, XUN_LCR_8_DATA_BITS); /* Sets DTR, RTS, and OUT2 in the MCR */ XIo_Out8(UART_BASEADDR + XUN_MCR_OFFSET, XUN_MCR_OUT_2 | XUN_MCR_RTS | XUN_MCR_DTR); xil_printf("\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n"); xil_printf("Starting Up... \n"); xil_printf("Console: 16550 initialized. \n"); /*---------------------------------------------------------------*/ /* Timer Inits */ /*---------------------------------------------------------------*/ ml_offset = LWIP_TIMER_CYCLES;
140 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
/*---------------------------------------------------------------*/ /* Do LWIP System Inits */ /*---------------------------------------------------------------*/ #ifdef STATS stats_init(); #endif /* STATS */ xil_printf("Initializing Memory Structures."); sys_init(); mem_init(); xil_printf("."); memp_init(); xil_printf("."); pbuf_init(); xil_printf(" done. \n"); // clear UART Receive Buffer while (XUartNs550_mIsReceiveData(UART_BASEADDR)) { XUartNs550_RecvByte(UART_BASEADDR); } // set GPIO I/O Mask XGpio_mSetDataDirection(XPAR_MYGPIO_BASEADDR, 0x00000FFF); // Turn on 4 LEDs (Active Low) XGpio_mSetDataReg(XPAR_MYGPIO_BASEADDR, 0x00000000); /*---------------------------------------------------------------*/ /* Initial Header and Menus. Do this before the netif_init() so */ /* we can change the MAC Address and IP addresses if needed */ /*---------------------------------------------------------------*/ while(init_wait--); print_app_header(); fullmac[0] = XILINX_MAC_OUI0; fullmac[1] = XILINX_MAC_OUI1; fullmac[2] = XILINX_MAC_OUI2; fullmac[3] = low_mac[0]; fullmac[4] = low_mac[1]; fullmac[5] = low_mac[2]; /*---------------------------------------------------------------*/ /* Set host addresses */ /*---------------------------------------------------------------*/ xemacif_setmac(0, (u8_t *) fullmac); //Set MAC IP4_ADDR(&gw, gateway[0],gateway[1],gateway[2],gateway[3]); //Set gateway IP4_ADDR(&ipaddr, ip[0],ip[1],ip[2],ip[3]); //Set ip IP4_ADDR(&netmask,subnet[0],subnet[1],subnet[2],subnet[3]); //Set subnet msk /*---------------------------------------------------------------*/ /* Show some host boot stuff and parameters */ /*---------------------------------------------------------------*/
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
141 Embedded Development Kit
R
Chapter 11: lwIP Library
xil_printf(" \nStarting Network Interface... \n"); xil_printf(" MAC Address: "); show_dashed_hex(6, fullmac); xil_printf(" \n"); xil_printf(" IP Address: "); show_dotted_decimal(ip); xil_printf(" \n"); xil_printf(" Subnet Mask: "); show_dotted_decimal(subnet); xil_printf(" \n"); xil_printf(" Gateway IP: "); show_dotted_decimal(gateway); xil_printf(" \n"); xil_printf(" Echo Port: 7 \n"); /*---------------------------------------------------------------*/ /* Initialize netif */ /*---------------------------------------------------------------*/ netif_init(); /*---------------------------------------------------------------*/ /* Initialize TCP Stack */ /*---------------------------------------------------------------*/ tcp_init(); /*---------------------------------------------------------------*/ /* Set up the lwIP network interface... */ /*---------------------------------------------------------------*/ default_netif = netif_add(&ipaddr, &netmask, &gw, &XEmacIf_ConfigTable[0], xemacif_init, ip_input ); netif_set_default(default_netif); /*---------------------------------------------------------------*/ /* create new tcp pcb and start applications */ /*---------------------------------------------------------------*/ // Start the Server xil_printf("Echo Server Running ... "); xil_printf("
142 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
\n"); echo_init(); // Get the current Time-Base Register Value // offset it by ml_offset XTime_SetTime(0); XTime_GetTime(&ml_base); ml_base += ml_offset; while (1) { while (waiting_for_timer) { xemacif_input(default_netif); XTime_GetTime(&ml_new); if ( ml_new >= ml_base ) { waiting_for_timer = 0; ml_base = ml_new + ml_offset; } } // Call my_tmr() every ml_offset cycles my_tmr(); waiting_for_timer = 1; } return (1); } int main () { /*---------------------------------------------------------------*/ /* Enable instruction and data cache -this must be done first because */ /* the Memec Design Virtex-II Dev Boards (rev1 and rev2) have the SDRAM */ /* byte enables tied together on the board. Enabling the caches */ /* guarantees that all memory accesses are 32-bit aligned. */ /*---------------------------------------------------------------*/ XCache_EnableICache(0x80000001); XCache_EnableDCache(0x80000001); return main_main(); }
FileName : echo.c
/* . . * Copyright (c) 2001-2003 Swedish Institute of Computer Science. * All rights reserved. *
. * Redistribution and use in source and binary forms, with or withoutmodification,
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
143 Embedded Development Kit
R
Chapter 11: lwIP Library
.
* are permitted provided that the following conditions are met: *
. * 1. Redistributions of source code must retain the above copyrightnotice, . * this list of conditions and the following disclaimer.
. * 2. Redistributions in binary form must reproduce the above copyright notice, . * this list of conditions and the following disclaimer in the documentation . * and/or other materials provided with the distribution.
. * 3. The name of the author may not be used to endorse or promoteproducts . * derived from this software without specific prior written
permission. * . * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS OR IMPLIED . * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF . * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT . * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,SPECIAL, . * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT . * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ORBUSINESS . * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN . * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OROTHERWISE) ARISING . * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THEPOSSIBILITY . . . * */ * OF SUCH DAMAGE. * * This file is part of the lwIP TCP/IP stack. * * Author: Adam Dunkels <[email protected]>
144 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
#include #include #include #include #include
"lwip/debug.h" "lwip/stats.h" "lwip/tcp.h" "xparameters.h" "echo.h"
struct echo_state { struct pbuf *p; u8_t failed; #define FAILED_MAX 8 }; /*------------------------------------------------------------------*/ static void echo_err(void *arg, err_t err) { struct echo_state *es = arg; xil_printf("echo_err \n"); if(arg != NULL) { pbuf_free(es->p); mem_free(arg); } } /*------------------------------------------------------------------*/ static void close_conn(struct tcp_pcb *pcb, struct echo_state *es) { tcp_arg(pcb, NULL); tcp_sent(pcb, NULL); tcp_recv(pcb, NULL); if(es != NULL) { pbuf_free(es->p); mem_free(es); } tcp_close(pcb); xil_printf("Connection Closed \n"); } /*------------------------------------------------------------------*/ static void send_buf(struct tcp_pcb *pcb, struct echo_state *es) { struct pbuf *q; do { q = es->p; es->p = pbuf_dechain(q); if(tcp_write(pcb, q->payload, q->len, 1) == ERR_MEM) {
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
145 Embedded Development Kit
R
Chapter 11: lwIP Library
pbuf_chain(q, es->p); es->p = q; return; } tcp_recved(pcb, q->len); pbuf_free(q); } while(es->p != NULL); } /*------------------------------------------------------------------*/ static err_t echo_poll(void *arg, struct tcp_pcb *pcb) { struct echo_state *es; if(arg == NULL) { return tcp_close(pcb); } es = arg; if(es->failed >= FAILED_MAX) { close_conn(pcb, es); tcp_abort(pcb); return ERR_ABRT; } if(es->p != NULL) { ++es->failed; send_buf(pcb, es); } return ERR_OK; } /*------------------------------------------------------------------*/ static err_t echo_sent(void *arg, struct tcp_pcb *pcb, u16_t len) { struct echo_state *es; es = arg; if(es != NULL && es->p != NULL) { send_buf(pcb, es); } return ERR_OK; } /*------------------------------------------------------------------*/ static err_t echo_recv(void *arg, struct tcp_pcb *pcb, struct pbuf *p, err_t err) {
146 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
struct echo_state *es; es = arg; if(p == NULL) { close_conn(pcb, es); return ERR_OK; } if(es->p != NULL) { pbuf_chain(es->p, p); } else { es->p = p; } send_buf(pcb, es); return ERR_OK; } /*------------------------------------------------------------------*/ static err_t echo_accept(void *arg, struct tcp_pcb *pcb, err_t err) { struct echo_state *es; tcp_setprio(pcb, TCP_PRIO_MIN); /* Allocate memory for the structure that holds the state of the connection. */ es = mem_malloc(sizeof(struct echo_state)); if(es == NULL) { xil_printf("could not malloc memory for echo_state \n"); return ERR_MEM; } /* Initialize the structure. */ es->p = NULL; es->failed = 0; /* Tell TCP that this is the structure we wish to be passed for our callbacks. */ tcp_arg(pcb, es); /* Tell TCP that we wish to be informed of incoming data by a call to the http_recv() function. */ tcp_recv(pcb, echo_recv); tcp_err(pcb, echo_err); tcp_poll(pcb, echo_poll, 1); xil_printf("Connection Established \n");
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
147 Embedded Development Kit
R
Chapter 11: lwIP Library
return ERR_OK; } /*------------------------------------------------------------------*/ void echo_init(void) { struct tcp_pcb *pcb; pcb = tcp_new(); tcp_bind(pcb, IP_ADDR_ANY, ECHO_PORT); pcb = tcp_listen(pcb); tcp_accept(pcb, echo_accept); } /*------------------------------------------------------------------*/
FileName : echo.h
#ifndef LWIP_ECHO_H #define LWIP_ECHO_H #define ECHO_PORT 7 void echo_init(void); #endif
Linker script
The linker script used with the above example. /********************************************************************* * . . . . . . * XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR * XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION * OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS * IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,
. * AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE . . . . * FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY * WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE * IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR * REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF
148 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
. . * . . *
* INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * FOR A PARTICULAR PURPOSE.
* (c) Copyright 2003 Xilinx, Inc. * All rights reserved.
*********************************************************************/ _STACK_SIZE = 1024k; _HEAP_SIZE = 1024k; MEMORY { sdram : ORIGIN = 0x00000000, LENGTH = 32M bram : ORIGIN = 0xFFFF8000, LENGTH = 32K - 4 boot : ORIGIN = 0xfffffffc, LENGTH = 4 } STARTUP(boot.o) ENTRY(_boot) GROUP(libxil.a libc.a) SECTIONS { .vectors : { *(.vectors) } > sdram .text : { *(.text) } > sdram .data : { *(.data) *(.got2) *(.rodata) *(.fixup) } > sdram /* small data area (read/write): keep together! */ .sdata : { *(.sdata) } > sdram .sbss : { . = ALIGN(4); *(.sbss) . = ALIGN(4);
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
149 Embedded Development Kit
R
Chapter 11: lwIP Library
} > sdram __sbss_start = ADDR(.sbss); __sbss_end = ADDR(.sbss) + SIZEOF(.sbss); /* small data area 2 (read only) */ .sdata2 : { *(.sdata2) } > sdram .bss : { . = ALIGN(4); *(.bss) *(COMMON) . = ALIGN(4); __bss_end = .; /* add stack and align to 16 byte boundary */ . = . + _STACK_SIZE; . = ALIGN(16); __stack = .; _heap_start = .; . = . + _HEAP_SIZE; . = ALIGN(16); _heap_end = .; } > sdram __bss_start = ADDR(.bss); .boot0 : { *(.boot0) _end = .; } > sdram .boot : { *(.boot) } > boot }
MicroBlaze-Based Echo Server
The hardware system for the example is shown in Figure 11-2. Assign drivers to each of these peripherals. Select lwip library as shown before and configure the library with the ethernet instance name and the 6-byte MAC address. The lwip library, liblwip4.a, gets generated in <PROCESSOR_INSTANCE_NAME>/lib/ directory once libgen is run.
C Program
The application is split among the following C and headerf files.
FileName : echo_main.c
/*
150 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
. . . . . . . . . . . . . . .
* XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR * XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION * * * * * * * * * * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. *
* (c) Copyright 2002, 2003 Xilinx, Inc. * All rights reserved. * */
/* . * Copyright (c) 2001, 2002, 2003 Swedish Institute of Computer Science. . * All rights reserved. *
. * Redistribution and use in source and binary forms, with or without . * modification, are permitted provided that the following conditions . * are met: * . * 1. Redistributions of source code must retain the above copyrightnotice, . * this list of conditions and the following disclaimer.
. * 2. Redistributions in binary form must reproduce the above copyright notice, . * this list of conditions and the following disclaimer in the documentation . * and/or other materials provided with the distribution.
. * 3. The name of the author may not be used to endorse or promoteproducts . * derived from this software without specific prior written
permission. * . * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS OR . * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
151 Embedded Development Kit
R
Chapter 11: lwIP Library
. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN . * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,INCIDENTAL, . * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOTLIMITED . * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR . * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF . * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING . * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS . * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */
/* Xilinx Includes */ #include "xuartns550_l.h" #include "xparameters.h" #include "xgpio_l.h" #include "xtmrctr_l.h" /* lwIP Includes */ #include "netif/xemacif.h" #include "lwip/tcp.h" #include "lwip/memp.h" #include "netif/etharp.h" #include "echo.h" #define UART_BASEADDR XPAR_MYUART_16550_BASEADDR #define UART_CLOCK (XPAR_XUARTNS550_CLOCK_HZ) #define UART_BAUDRATE (115200) #define LWIP_TIMER_CYCLES (XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ / 1000 \ * TCP_TMR_INTERVAL ) // Upper 6 bytes of MAC #define XILINX_MAC_OUI0 #define XILINX_MAC_OUI1 #define XILINX_MAC_OUI2
- Xilinx Ethernet OUI = 00-0A-35 0x00 0x00 0x00
static void show_dotted_decimal( char * address_array); static void show_dashed_hex( int bytes, char *address_array); // Static Global Variables static u8_t my_timer = 0; static int waiting_for_timer = 1; /* defined in lwip/src/core/tcp.c */ extern u32_t tcp_ticks;
152 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
/* defined in EDK generated xemacif_g.c file */ extern XEmacIf_Config XEmacIf_ConfigTable[]; /*------------------------------------------------------------------*/ // show dotted decimal prints a dotted decimal address to the UART /*------------------------------------------------------------------*/ static void show_dotted_decimal( char *address_array) { int bb; unsigned char temp; for(bb=0;bb<4;bb++) { temp = address_array[bb]; if(bb!=0) xil_printf("."); xil_printf("%d", temp); } } /*------------------------------------------------------------------*/ /* show dashed hex prints a dashed hex address to the UART */ /*------------------------------------------------------------------*/ static void show_dashed_hex( int bytes, char *address_array) { //Assumes the caller passes the correct number of bytes int bb; for(bb=0;bb<bytes;bb++) { if(bb !=0) xil_printf("-"); xil_printf("%02X", (int) address_array[bb]); } } /*------------------------------------------------------------------*/ /* my_tmr - Called Periodically to dispatch TCP and ARP timers */ /*------------------------------------------------------------------*/ void my_tmr(void) { ++my_timer; if(my_timer == 10) { my_timer = 0; } if(my_timer & 1) { /* Call tcp_fasttmr() every 2 ms, i.e., * every other timer my_tmr() is called. */ tcp_fasttmr(); }
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
153 Embedded Development Kit
R
Chapter 11: lwIP Library
if(my_timer == 0 || my_timer == 5) { /* Call tcp_slowtmr() every 5 ms, i.e., * every fifth timer my_tmr() is called. */ tcp_slowtmr(); if (tcp_ticks%2000 == 0) /* Call etharp_tmr() every 20th call to tcp_slowtmr(). * tcp_ticks is a global var defined in core/tcp.c */ etharp_tmr(); } } /*------------------------------------------------------------------*/ /* print_app_header - prints the legal header */ /*------------------------------------------------------------------*/ void print_app_header() { xil_printf("\n\n\n\n\n\n\n\n \n"); xil_printf("########################################################## ########## \n"); xil_printf("# Xilinx TCP/IP Demo Application (ECHO Server) # \n"); xil_printf("# # \n"); xil_printf("# XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION ’AS IS’ # \n"); xil_printf("# # \n"); xil_printf("# # \n"); xil_printf("# \n"); xil_printf("# # \n"); xil_printf("# # \n"); xil_printf("# \n");
SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR
XILINX DEVICES.
# (c) Copyright 2003, 2003 Xilinx, Inc.
All rights reserved.
#
xil_printf("########################################################## ########## \n");
154 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
} /*------------------------------------------------------------------*/ /* main function */ /*------------------------------------------------------------------*/ int main_main () { struct tcp_pcb *gddpp_pcb; struct ip_addr ipaddr, netmask, gw; struct netif *default_netif; char menu_select = 0; char low_mac[3] = {0x00,0x22,0x38}; char fullmac[6] = {XILINX_MAC_OUI0, XILINX_MAC_OUI1, XILINX_MAC_OUI2, low_mac[0], low_mac[2], low_mac[3]}; char ip[4] = {149,199,6,108}; char subnet[4] = {255,255,255,0}; char gateway[4] = {149,199,6,254}; int app_running = 0; unsigned int init_wait = 15000000; /*-----------------------------* Enable microblaze interrupts *-------------------------------*/ microblaze_enable_interrupts(); /*---------------------------------------------------------------. * Timer and Intc Init * . * Set the Timer to interrupt for every 100ms *--------------------------------------------------------------*/
/* set the number of cycles the timer counts before interrupting */ /* 100 Mhz clock => 100 us for 1 clk tick. For 100ms, 1000 clk ticks need to elapse */ XTmrCtr_mSetLoadReg(XPAR_OPB_TIMER_1_BASEADDR, 0, 10000); /* reset the timers, and clear interrupts */ XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0, XTC_CSR_INT_OCCURED_MASK | XTC_CSR_LOAD_MASK ); /* start the timers */ XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0, XTC_CSR_ENABLE_TMR_MASK | XTC_CSR_ENABLE_INT_MASK | XTC_CSR_AUTO_RELOAD_MASK | XTC_CSR_DOWN_COUNT_MASK); /*----------------------------------------------------------------
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
155 Embedded Development Kit
R
Chapter 11: lwIP Library
* Uart Init*------------------------------------------------------------------*/ /* Disable Interrupts */ XIo_Out8(UART_BASEADDR + XUN_LCR_OFFSET, 0UL); XIo_Out8(UART_BASEADDR + XUN_IER_OFFSET, 0UL); /* Clear Latches */ XIo_In8(UART_BASEADDR + XUN_LSR_OFFSET); XIo_In8(UART_BASEADDR + XUN_IIR_OFFSET); XIo_In8(UART_BASEADDR + XUN_MSR_OFFSET); /* Disable FIFOs (16450) */ XIo_Out8(UART_BASEADDR + XUN_FCR_OFFSET, 0UL); /* Normal ABQ level 0 driver inits */ XUartNs550_SetBaud(UART_BASEADDR, UART_CLOCK, UART_BAUDRATE); XUartNs550_mSetLineControlReg(UART_BASEADDR, XUN_LCR_8_DATA_BITS); /* Sets DTR, RTS, and OUT2 in the MCR */ XIo_Out8(UART_BASEADDR + XUN_MCR_OFFSET, XUN_MCR_OUT_2 | XUN_MCR_RTS | XUN_MCR_DTR); xil_printf("\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n"); xil_printf("Starting Up... \n"); xil_printf("Console: 16550 initialized. \n"); /*------------------------------------------------------------------*/ /* Do LWIP System Inits */ /*---------------------------------------------------------------*/ #ifdef STATS stats_init(); #endif /* STATS */ xil_printf("Initializing Memory Structures."); sys_init(); mem_init(); xil_printf("."); memp_init(); xil_printf("."); pbuf_init(); xil_printf(" done. \n");
156 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
// set GPIO I/O Mask XGpio_mSetDataDirection(XPAR_MYGPIO_BASEADDR, 0x00000FFF); // Turn on 4 LEDs (Active Low) XGpio_mSetDataReg(XPAR_MYGPIO_BASEADDR, 0x00000000); /*---------------------------------------------------------------*/ /* Initial Header and Menus. Do this before the netif_init() so we can */ /* change the MAC Address and IP addresses if needed */ /*---------------------------------------------------------------*/ while(init_wait--); print_app_header(); fullmac[0] = XILINX_MAC_OUI0; fullmac[1] = XILINX_MAC_OUI1; fullmac[2] = XILINX_MAC_OUI2; fullmac[3] = low_mac[0]; fullmac[4] = low_mac[1]; fullmac[5] = low_mac[2]; /*---------------------------------------------------------------*/ /* Set host addresses */ /*---------------------------------------------------------------*/ xemacif_setmac(0, (u8_t *) fullmac); //Set MAC IP4_ADDR(&gw, gateway[0],gateway[1],gateway[2],gateway[3]); //Set gateway IP4_ADDR(&ipaddr, ip[0],ip[1],ip[2],ip[3]); //Set ip IP4_ADDR(&netmask,subnet[0],subnet[1],subnet[2],subnet[3]); //Set subnet msk /*---------------------------------------------------------------*/ /* Show some host boot stuff and parameters */ /*---------------------------------------------------------------*/ xil_printf(" \nStarting Network Interface... \n"); xil_printf(" MAC Address: "); show_dashed_hex(6, fullmac); xil_printf(" \n"); xil_printf(" IP Address: "); show_dotted_decimal(ip); xil_printf(" \n"); xil_printf(" Subnet Mask: "); show_dotted_decimal(subnet); xil_printf(" \n"); xil_printf(" Gateway IP: "); show_dotted_decimal(gateway); xil_printf(" \n");
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
157 Embedded Development Kit
R
Chapter 11: lwIP Library
xil_printf(" Echo Port: 7 \n"); /*---------------------------------------------------------------*/ /* Initialize netif */ /*---------------------------------------------------------------*/ netif_init(); /*---------------------------------------------------------------*/ /* Initialize TCP Stack */ /*---------------------------------------------------------------*/ tcp_init(); /*---------------------------------------------------------------*/ /* Set up the lwIP network interface... */ /*---------------------------------------------------------------*/ default_netif = netif_add(&ipaddr, &netmask, &gw, &XEmacIf_ConfigTable[0], xemacif_init, ip_input ); netif_set_default(default_netif); /*---------------------------------------------------------------*/ /* create new tcp pcb and start applications */ /*---------------------------------------------------------------*/ // Start the Server xil_printf("Echo Server Running ... "); xil_printf(" \n"); echo_init(); app_running = 1; while (1) { while (waiting_for_timer) { xemacif_input(default_netif); } my_tmr(); waiting_for_timer = 1; } return (1); } int main () { /*---------------------------------------------------------------*/ /* Enable instruction and data cache-this must be done first because
158 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
*/ /* the Memec Design Virtex-II Dev Boards (rev1 and rev2) have the SDRAM */ /* byte enables tied together on the board. Enabling the caches */ /* guarantees that all memory accesses are 32-bit aligned. */ /*---------------------------------------------------------------*/ return main_main(); } void mytimer_int_handler (void* baseaddr_p) { int baseaddr = *(int *)baseaddr_p; unsigned int csr; unsigned int gpio_data; /* Read timer 0 CSR to see if it raised the interrupt */ csr = XTmrCtr_mGetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0); if (csr & XTC_CSR_INT_OCCURED_MASK) { //xil_printf("Timer Handler ...\n"); waiting_for_timer = 0; /* Clear the timer interrupt */ XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0, csr); } } FileName : echo.c echo.h These are the same files as used in the PowerPC example described above.
For MicroBlaze design, the echo server application is set to start at 0x86000000 which is the start address of SDRAM. The entire design runs off the external memory.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
159 Embedded Development Kit
R
Chapter 11: lwIP Library
160 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Embedded Development Kit EDK 6.2i
UG114 (v3.0) June 22, 2004
R
R
"Xilinx" and the Xilinx logo shown above are registered trademarks of Xilinx, Inc. Any rights not expressly granted herein are reserved. CoolRunner, RocketChips, Rocket IP, Spartan, StateBENCH, StateCAD, Virtex, XACT, XC2064, XC3090, XC4005, and XC5210 are registered trademarks of Xilinx, Inc.
The shadow X shown above is a trademark of Xilinx, Inc. ACE Controller, ACE Flash, A.K.A. Speed, Alliance Series, AllianceCORE, Bencher, ChipScope, Configurable Logic Cell, CORE Generator, CoreLINX, Dual Block, EZTag, Fast CLK, Fast CONNECT, Fast FLASH, FastMap, Fast Zero Power, Foundation, Gigabit Speeds...and Beyond!, HardWire, HDL Bencher, IRL, J Drive, JBits, LCA, LogiBLOX, Logic Cell, LogiCORE, LogicProfessor, MicroBlaze, MicroVia, MultiLINX, NanoBlaze, PicoBlaze, PLUSASM, PowerGuide, PowerMaze, QPro, Real-PCI, RocketIO, SelectIO, SelectRAM, SelectRAM+, Silicon Xpresso, Smartguide, Smart-IP, SmartSearch, SMARTswitch, System ACE, Testbench In A Minute, TrueMap, UIM, VectorMaze, VersaBlock, VersaRing, Virtex-II Pro, Virtex-II EasyPath, Wave Table, WebFITTER, WebPACK, WebPOWERED, XABEL, XACTFloorplanner, XACT-Performance, XACTstep Advanced, XACTstep Foundry, XAM, XAPP, X-BLOX +, XC designated products, XChecker, XDM, XEPLD, Xilinx Foundation Series, Xilinx XDTV, Xinfo, XSI, XtremeDSP and ZERO+ are trademarks of Xilinx, Inc. The Programmable Logic Company is a service mark of Xilinx, Inc. All other trademarks are the property of their respective owners. Xilinx, Inc. does not assume any liability arising out of the application or use of any product described or shown herein; nor does it convey any license under its patents, copyrights, or maskwork rights or any rights of others. Xilinx, Inc. reserves the right to make changes, at any time, in order to improve reliability, function or design and to supply the best product possible. Xilinx, Inc. will not assume responsibility for the use of any circuitry described herein other than circuitry entirely embodied in its products. Xilinx provides any design, code, or information shown or described herein "as is." By providing the design, code, or information as one possible implementation of a feature, application, or standard, Xilinx makes no representation that such implementation is free from any claims of infringement. You are responsible for obtaining any rights you may require for your implementation. Xilinx expressly disclaims any warranty whatsoever with respect to the adequacy of any such implementation, including but not limited to any warranties or representations that the implementation is free from claims of infringement, as well as any implied warranties of merchantability or fitness for a particular purpose. Xilinx, Inc. devices and products are protected under U.S. Patents. Other U.S. and foreign patents pending. Xilinx, Inc. does not represent that devices shown or products described herein are free from patent infringement or from any other third party right. Xilinx, Inc. assumes no obligation to correct any errors contained herein or to advise any user of this text of any correction if such be made. Xilinx, Inc. will not assume any liability for the accuracy or correctness of any engineering or software support or assistance provided to a user. Xilinx products are not intended for use in life support appliances, devices, or systems. Use of a Xilinx product in such applications without the written consent of the appropriate Xilinx officer is prohibited. The contents of this manual are owned and copyrighted by Xilinx. Copyright 1994-2004 Xilinx, Inc. All Rights Reserved. Except as stated herein, none of the material may be copied, reproduced, distributed, republished, downloaded, displayed, posted, or transmitted in any form or by any means including, but not limited to, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Xilinx. Any unauthorized use of any material contained in this manual may violate copyright laws, trademark laws, the laws of privacy and publicity, and communications regulations and statutes.
EDK OS and Libraries Reference Guide
www.xilinx.com 1-800-255-7778
UG114 (v3.0) June 22, 2004
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
The following table shows the revision history for this document.
Version
01/30/04 03/12/04 03/19/04 06/22/04 2.0 3.0 1.0 Initial release for EDK 6.2i. Updated for service pack release. Updated for service pack release. Updated for service pack release.
Revision
UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide
EDK OS and Libraries Reference Guide
www.xilinx.com 1-800-255-7778
UG114 (v3.0) June 22, 2004
R
Preface
About This Guide
This book describes the software packages provided by the Embedded Development Kit (EDK).
Guide Contents
This book contains the following chapters.
x x x x x x x x x x
Chapter 1, “Introduction” Chapter 2, “Xilinx Microkernel (XMK)” Chapter 3, “LibXil Standard C Libraries” Chapter 4, “Standalone Board Support Package” Chapter 5, “Xilkernel” Chapter 6, “LibXil Net” Chapter 7, “LibXil File” Chapter 8, “LibXil FATFile System (FATfs)” Chapter 9, “LibXil Memory File System (MFS)” Chapter 10, “LibXil Profile”
Additional Resources
For additional information, go to http://support.xilinx.com. The following table lists some of the resources you can access from this website. You can also directly access these resources using the provided URLs.
Resource
EDK Home
Description/URL
Embedded Development Kit home page, FAQ and tips. http://www.xilinx.com/edk
EDK Examples Tutorials
A set of complete EDK examples. http://www.xilinx.com/ise/embedded/edk_examples.htm Tutorials covering Xilinx design flows, from design entry to verification and debugging http://support.xilinx.com/support/techsup/tutorials/index.htm
Answer Browser
Database of Xilinx solution records http://support.xilinx.com/xlnx/xil_ans_browser.jsp
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
5
R
Preface: About This Guide
Resource
Application Notes
Description/URL
Descriptions of device-specific design techniques and approaches http://support.xilinx.com/apps/appsweb.htm
Data Sheets
Device-specific information on Xilinx device characteristics, including readback, boundary scan, configuration, length count, and debugging http://support.xilinx.com/xlnx/xweb/xil_publications_index.jsp
Problem Solvers Tech Tips
Interactive tools that allow you to troubleshoot your design issues http://support.xilinx.com/support/troubleshoot/psolvers.htm Latest news, design tips, and patch information for the Xilinx design environment http://www.support.xilinx.com/xlnx/xil_tt_home.jsp The entire set of GNU manuals http://www.gnu.org/manual
GNU Manuals
Conventions
This document uses the following conventions. An example illustrates each convention.
Typographical
The following typographical conventions are used in this document:
Convention
Courier font
Meaning or Use
Messages, prompts, and program files that the system displays Literal commands that you enter in a syntactical statement Commands that you select from a menu Keyboard shortcuts Variables in a syntax statement for which you must supply values
Example
speed grade: - 100
Courier bold
ngdbuild design_name
Helvetica bold
File o Open Ctrl+C
ngdbuild design_name See the Development System Reference Guide for more information. If a wire is drawn so that it overlaps the pin of a symbol, the two nets are not connected.
Italic font
References to other manuals
Emphasis in text
6
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Conventions
R
Convention
Meaning or Use
An optional entry or parameter. However, in bus specifications, such as bus[7:0], they are required. A list of items from which you must choose one or more
Example
ngdbuild [option_name] design_name
Square brackets [ ]
Braces { } Vertical bar |
lowpwr ={on|off} lowpwr ={on|off} IOB #1: Name = QOUT’ IOB #2: Name = CLKIN’ . . . allow block block_name loc1 loc2 ... locn;
Separates items in a list of choices
Vertical ellipsis . . . Horizontal ellipsis . . .
Repetitive material that has been omitted
Repetitive material that has been omitted
Online Document
The following conventions are used in this document:
Convention
Meaning or Use
Cross-reference link to a location in the current document Cross-reference link to a location in another document Hyperlink to a website (URL)
Example
See the section “Additional Resources” for details. Refer to “Title Formats” in Chapter 1 for details. See Figure 2-5 in the Virtex-II Handbook. Go to http://www.xilinx.com for the latest speed files.
Blue text
Red text Blue, underlined text
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
7
R
Preface: About This Guide
8
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Table of Contents
Preface: About This Guide
Guide Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Typographical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Online Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1: Introduction Chapter 2: Xilinx Microkernel (XMK)
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 XMK Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 3: LibXil Standard C Libraries
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard C Library (libc.a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilinx C Library (libxil.a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input/Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21 21 22 22
23 MicroBlaze Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 PowerPC 405 Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 23 23 24 24 24 24
Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MicroBlaze Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer Arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerPC 405 Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer Arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 4: Standalone Board Support Package
MicroBlaze BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_enable_interrupts(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_disable_interrupts(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Instruction Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_enable_icache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_disable_icache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_update_icache (int tag, int instr, int lock_valid) . . . . . . . . . . . . . . . . . void microblaze_init_icache_range (int cache_addr, int cache_size) . . . . . . . . . . . . . . . Data Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_enable_dcache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void microblaze_disable_dcache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 25 25 25 25 26 26 26 26 26 26
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
9
R
void microblaze_update_dcache (int tag, int data, int lock_valid) . . . . . . . . . . . . . . . . . 27 void microblaze_init_dcache_range (int cache_addr, int cache_size) . . . . . . . . . . . . . . . 27
Fast Simplex Link Interface Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_bread_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_bwrite_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_nbread_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_nbwrite_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_bread_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_bwrite_cntlfsl(val, id). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_nbread_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . microblaze_nbwrite_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Boot Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . boot.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . crt0.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . eabi.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_WriteCCR0(unsigned int val);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_EnableDCache(unsigned int regions);. . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_DisableDCache(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_FlushDCacheLine(unsigned int adr); . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_StoreDCacheLine(unsigned int adr);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_EnableICache(unsigned int regions); . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_DisableICache(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_InvalidateICache(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XCache_InvalidateICacheLine(unsigned int adr); . . . . . . . . . . . . . . . . . . . . . . . . . Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XExc_Init(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27 27 27 27 27 27 27 28 28 28 28 28 28 28 29 29 29 29 29 29 29 30 30 30 30
PowerPC BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
void XExc_RegisterHandler(Xuint8 ExceptionId, XExceptionHandler Handler, void *DataPtr);31 void XExc_RemoveHandler(Xuint8 ExceptionId). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 void XExc_mEnableExceptions (EnableMask); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 void XExc_mDisableExceptions (DisableMask); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int read(int fd, char *buf, int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int write(int fd, char *buf, int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . int isatty(int fd); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . char *sbrk(int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processor-Specific Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . typedef unsigned long long XTime; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_SetTime(XTime xtime); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_GetTime(XTime *xtime); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_TSRClearStatusBits(unsigned long Bitmask); . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITSetInterval(unsigned long interval); . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITEnableInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITDisableInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITEnableAutoReload(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITDisableAutoReload(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . void XTime_PITClearInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unsigned int usleep(unsigned int __useconds); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unsigned int sleep(unsigned int __seconds); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32 32 32 32 33 33 33 33 33 33 33 33 33 34 34 35 35 35 35 35 36
10
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
int nanosleep(const struct timespec *rqtp, struct timespec *rmtp); . . . . . . . . . . . . . . . . . 36
Chapter 5: Xilkernel
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Xilkernel Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel Process Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel Scheduling Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mutex Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic Block Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 37 38 39 39 41 42 43 43 45 50 55 59 62 65
Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Kernel Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Customizing STDIN and STDOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing User Initialization Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Message Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Pthread Mutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Dynamic Block Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Linker Script (PPC405) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring System Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Debug Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copy Kernel Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 71 72 73 73 74 74 74 75 75 76 77 77 77 78 78 78 79 79 80 80 80 80
Debugging Xilkernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Footprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xilkernel File Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Future Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Xilkernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 6: LibXil Net
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 LibXilNet Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
11
R
Quick Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Protocols Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Library Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Protocol Function Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Media Access Layer (MAC) Drivers Wrapper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ethernet Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ARP (RFC 826) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IP (RFC 791) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ICMP (RFC 792) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UDP (RFC 768) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TCP (RFC 793) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 87 87 87 87 87 88 88 88
Current Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Functions of LibXilNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Using XilNet in Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Chapter 7: LibXil File
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Module Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Libgen Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
101 101 101
104 LibXil File Instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Chapter 8: LibXil FATFile System (FATfs)
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 XilFatfs Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Detailed Description of XilFatfsFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Chapter 9: LibXil Memory File System (MFS)
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 MFS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Quick Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Detailed summary of MFS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-like access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
120 121 121 121
Chapter 10: LibXil Profile
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
12
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Profiling Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing xilprofile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
123 124 124
124 Application Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Generating GPROF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 XilProfile Code Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Chapter 11: lwIP Library
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerPC System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MicroBlaze System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up lwIP in EDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
129 129 130 131
131 libgen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Initializing lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 lwIP Raw API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Designing an lwIP Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Raw APO Functions for TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Example lwIP Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
PowerPC based Echo Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MicroBlaze-Based Echo Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 135 150 150
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
13
R
14
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 1
Introduction
This book describes the software packages that are provided by the Embedded Development Kit. EDK supplies libraries, board support packages, and complete operating systems, in addition to the drivers for the peripherals, to help the user develop a software platform. The following is the distribution of the software packages available for the user to include in his platform:
x
Xilinx Micro-Kernel (XMK) - XMK is the entity representing the collective software system formed by the following components,
i i i i i i i
Standard C Libraries (libc, libm) Xilkernel - An embedded kernel Standalone Board Support Package (BSP) LibXil Net - A networking library LibXil MFS - A Memory File System LibXil File - A file I/O library LibXil Drivers - Device drivers for supported peripherals
x
VxWorks Operating System
The software platform can be defined using XPS’s Software Platform Settings dialog box. Figure 1-1 shows a snapshot of the dialog box. In this example, the user is choosing the Xilnet and Xilfile libraries, along with the Xilkernel operating system. This guide documents the Xilinx Micro-kernel, its constituent libraries and the Standalone board-support package. Documentation for the other operating systems can be found in their respective reference guides. Device drivers are documented along with the corresponding peripheral’s documentation.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
15
R
Chapter 1: Introduction
Figure 1-1: Software Platform Settings in XPS
16
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 2
Xilinx Microkernel (XMK)
This chapter describes the organization of Xilinx Microkernel, its constituent component libraries and the interactions between them and the user application. The chapter contains the following sections.
x x
“Overview” “XMK Organization”
Overview
There are three distinct software entities in XMK, with which user applications can interface - Standard C and Math libraries, LibXil libraries and Xilkernel or Standalone operating systems. The Standard C support library consists of the newlib libc, which contains the standard C functions such as stdio, stdlib and string routines. The math library is an enhancement over the newlib math library libm and provides the standard math routines. The LibXil libraries consist of,
x x x x x
LibXil Driver - Xilinx device drivers LibXil Net - Xilinx networking support LibXil File - Xilinx file I/O functions LibXil MFS - Xilinx memory file system LibXil Profile - Xilinx profiling support
The Xilinx Standalone Board Support Package (BSP) and Xilkernel are the two operating system choices that are provided, in XMK, that can be included in the user application’s software platform. Most of the routines in the library are written in C and can be ported to any platform. The Library Generator (LibGen) configures the libraries for an embedded processor, using the attributes defined in the Microprocessor Software Specification (MSS) file.
XMK Organization
The structure of XMK is outlined in Figure 2-1. As shown in the figure, the user application can interface with the XMK components in a variety of ways. The libraries are independent of each other, except for a few interactions and dependencies between each other. For example, Xilkernel internally uses the standalone BSP and LibXil File can optionally work with the LibXil MFS. The LibXil Drivers and the standalone BSP form the lowermost hardware abstraction layer. All the library and OS components of XMK rely on standard C library components. The math library, libm.a is also available for linking with the user
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
17
R
Chapter 2: Xilinx Microkernel (XMK)
applications. Users can mix and match the component libraries, but there may be some restrictions and implications. This will be described in the reference guides of each component.
User Application
libc
stdio stdlib
Xil Kernel
LibXil Net
LibXil File
LibXil Mfs
LibXil Profile
string Other
libm
Standalone BSP LibXil Driver
Hardware
X10143
Figure 2-1: XMK Structure
The Standalone Board Support Package (BSP) is a bare-bones kernel. It provides a very thin interface to the hardware, offering minimal functionality that will be required by applications. Some typical functions offered by the standalone BSP include setting up the interrupt system, exception system, configuring caches and other hardware specific functions. Certain standalone board support files such as the crt0.S, boot.S and eabi.S are required for the powerpc processor. These files are provided in the EDK. For a detailed description, refer to Chapter 4, “Standalone Board Support Package.” LibXil Driver refers to the device drivers that are included in the software platform to provide an interface to the peripherals in the system. These drivers are provided along with EDK and are configured by libgen. This book contains a chapter that briefly discusses the concept of device drivers and the way they fit in with the software platform, in EDK. Refer to the “Device Drivers Programmer Guide” chapter in the Processor IP Reference Guide for this documentation. Device Drivers are documented in further detail, with information about functionality, interface, configuration and headers file information, in the Xilinx Device Drivers Reference Guide. Xilkernel (1) is a simple embedded processor kernel, which can be customized to a great degree for a given system. Xilkernel has the key features of an embedded kernel like multitasking, priority-driven preemptive scheduling, inter-process communication, synchronization facilities, interrupt handling etc. It is small, modular, user customizable and can be used in different system configurations. It is different from the other libraries, (as indicated in Figure 2-1 in that, it can be in a separate executable file from the user application. The user application can dynamically link with Xilkernel through a system call interface. Applications can also statically link with Xilkernel, in a different mode, and form a single executable. Complete details are available in Chapter 5, “Xilkernel.” LibXil Net provides networking support using a simple TCP/IP stack based library, which can be used for network related projects. For complete details, refer to Chapter 6, “LibXil Net.”
1. Previous EDK releases supported the library version of Xilkernel, which is now deprecated. Refer to Chapter 5, “Xilkernel” for documentation on LibXilkernel.
18
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
XMK Organization
R
LibXil File provides stream based file system and device access through interfaces such as open, close, read and write. The standard newlib libc contains dummy functions for most of the operating system specific function calls such as open, close, read, write. These routines are included in the libgloss component of the standard libc library. The LibXil File module contains routines to overwrite these dummy functions. The routines interact with file systems such as Xilinx Memory File System and peripheral devices such as UART, UARTLITE and GPIO. For complete details refer to Chapter 7, “LibXil File.” LibXil MFS provides a simple memory based file system, which allows easy access to data using file based input-output. This system can be easily configured to meet project requirements by changing the source provided in the installation area. This module is discussed in detail in Chapter 9, “LibXil Memory File System (MFS).” LibXil Profile provides a mechanism to perform call-graph and histogram profiling and produces the profile data in a format that can be analyzed using GNU gprof. For details refer to Chapter 10, “LibXil Profile.” User applications will need to include appropriate headers and link with required libraries for proper compilation and inclusion of required functionality. These libraries and their corresponding include files are created in the processor’s lib and include directories, under the current project, respectively. The -I and -L options of the compiler being used should be leveraged to add these directories to the search paths. Libgen is used to tailor the compilation of each software component described above. Refer to the chapters on Libgen and Microprocessor Software Specification in the Embedded Systems Tools Reference Guide for more information.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
19
R
Chapter 2: Xilinx Microkernel (XMK)
20
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 3
LibXil Standard C Libraries
This chapter describes the software libraries available for the embedded processors. The chapter contains the following sections.
x x x x x x
“Overview” “Standard C Library (libc.a)” “Xilinx C Library (libxil.a)” “Input/Output Functions” “Memory Management Functions” “Arithmetic Operations”
Overview
The Embedded Processor Design Kit (EDK) libraries and device drivers provide standard C library functions, as well as functions to access peripherals. The EDK libraries are automatically configured by libgen for every project based upon the Microprocessor Software Specification file. These libraries and include files are saved in the current project’s lib and include directories respectively. The -I and -L options of mb-gcc should be used to add these directories to its library search paths.
Standard C Library (libc.a)
The standard C library libc.a contains the standard C functions compiled for MicroBlaze or PowerPC. For a list of all the supported functions refer to the following files in XILINX_EDK/gnu/processor/platform/include where
x x x
processor = powerpc-eabi or microblaze platform = sol, nt or lin XILINX_EDK = Installation directory
_ansi.h _syslist.h ar.h assert.h ctype.h dirent.h errno.h fastmath.h fcntl.h float.h grp.h ieeefp.h limits.h locale.h machine/ malloc.h math.h paths.h process.h pthread.h pwd.h reent.h regdef.h setjmp.h signal.h stdarg.h stddef.h stdio.h stdlib.h string.h sys/ termios.h time.h unctrl.h unistd.h utime.h utmp.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
21
R
Chapter 3: LibXil Standard C Libraries
Programs accessing standard C library functions must be compiled as follows: For MicroBlaze
mb-gcc C files
For PowerPC
powerpc-eabi-gcc C files
The libc library is included automatically. The -lm option should be specified for programs that access libm math functions. Refer to “MicroBlaze Application Binary Interface,” (ABI) in the MicroBlaze Processor Reference Guide for information on the C Runtime Library
Xilinx C Library (libxil.a)
The Xilinx C library libxil.a contains the following functions for the MicroBlaze embedded processor:
_exception_handler.o _interrupt_handler.o _program_clean.o _program_init.o xil_malloc.o xil_sbrk.o
Default exception and interrupt handlers are provided. A memory management targeted for embedded systems is provided in the xil_malloc.o file. The libxil.a library is included automatically. Programs accessing Xilinx C library functions must be compiled as follows:
mb-gcc C files
Input/Output Functions
The EDK libraries contains standard C functions for I/O, such as printf and scanf. These are large and may not be suitable for embedded processors. In addition, the EDK processors (MicroBlaze and PowerPC405) library provides the following smaller I/O functions:
void print (char *)
This function prints a string to the peripheral designated as standard output in the MSS file. This function outputs the passed string as is and there is no interpretation of the string passed. For example, a “\n” passed is interpreted as a new line character and not as a carriage return and a new line as is the case with ANSI C printf function.
void putnum (int)
This function converts an integer to a hexadecimal string and prints it to the peripheral designated as standard output in the MSS file.
void xil_printf (const *char ctrl1, ...)
This function is similar to printf but much smaller in size (only 1KB). It does not have support for floating point numbers. xil_printf also does not support printing of long long (i.e 64 bit numbers). The prototypes for these functions are in stdio.h.
22
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Memory Management Functions
R
Please refer to the “Microprocessor Software Specification (MSS)” chapter in the Embedded System Tools Guide for information on setting the standard input and standard output devices for a system.
Memory Management Functions
MicroBlaze Processor
Memory management routines such as malloc, calloc and free can run the gamut of high functionality (with associated large size) to low functionality (and small size). By default, the MicroBlaze processor library only supports a simple, small malloc, and a dummy free. Hence when memory is allocated using malloc, this memory cannot be reused. In addition to the simple version, we have now extended the standalone BSP to include xil_malloc, xil_free and xil_calloc function. In the Standalone OS block, if the PARAMETER need_xil_malloc is set to TRUE, calls to malloc result in a call to xil_malloc and the same for free and calloc. These functions are a lighter version of the newlib based malloc and free, but have the same functionality. The _STACK_SIZE option to mb-gcc specifies the total memory allocated to stack and heap. The stack is used for function calls, register saves, and local variables. All calls to malloc allocate memory from heap. The stack pointer initially points to the bottom (high end) of memory, and grows toward low memory; the heap pointer starts at low memory and grows toward high memory. The size of the heap cannot be increased at runtime. The return value of malloc must always be checked to ensure that it could actually allocate the memory requested. Please note that whereas malloc checks that the memory it allocates does not overwrite the current stack pointer, updates to the stack pointer do not check if the heap is being overwritten. Increasing the _STACK_SIZE may be one way to solve unexpected program behavior. Refer to “Linker Options” in the “GNU Compiler Tools” chapter of the Embedded System Tools Guide for more information on increasing the stack size.
PowerPC 405 Processor
PowerPC 405 processor supports all standard C library memory management functions such as malloc(), calloc(), free().Similar to MicroBlaze, the lighter version of malloc and free i.e xil_malloc and xil_free can be used for PowerPC when the standalone BSP package is used.
Arithmetic Operations
MicroBlaze Processor
Integer Arithmetic
Integer addition and subtraction operations are provided in hardware. By default, integer multiplication is done in software using the library function mulsi3_proc. Integer multiplication is done in hardware if the mb-gcc option -mno-xl-soft-mul is specified.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
23
R
Chapter 3: LibXil Standard C Libraries
Integer divide and mod operations are done in software using the library functions divsi3_proc and modsi3_proc. MicroBlaze processor can also be customized to use a hard divider, in which case the div instruction is used in place of the divsi3_proc library routine. Double precision multiplication, division and mod functions are carried out by the library functions muldi3_proc, divdi3_proc and moddi3_proc respectively.
Floating Point Arithmetic
All floating point addition, subtraction, multiplication and division operations are also implemented using software functions in the C library.
PowerPC 405 Processor
Integer Arithmetic
Integer addition and subtraction operations are provided in hardware. Hence no specific software library is available for the PowerPC processor.
Floating Point Arithmetic
The PowerPC processor supports all floating point arithmetic implemented in the standard C library.
24
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 4
Standalone Board Support Package
The Board Support Package (BSP) is a set of software modules used to access processor specific functions. The standalone BSP is used when an application accesses board/processor features directly (without an intervening Operating System layer). This chapter contains the following sections.
x x
“MicroBlaze BSP” “PowerPC BSP”
MicroBlaze BSP
When the user system contains a MicroBlaze processor and no Operating System, the Library Generator automatically builds the standalone BSP in the project library libxil.a.
Interrupt Handling
The microblaze_enable_interrupts.s and microblaze_disable_interrupts.s files contain functions to enable and disable interrupts on the MicroBlaze.
void microblaze_enable_interrupts(void)
This function enables interrupts on the MicroBlaze. When the MicroBlaze starts up, interrupts are disabled. Interrupts must be explicitly turned on using this function.
void microblaze_disable_interrupts(void)
This function disables interrupts on the MicroBlaze. This function may be called when entering a critical section of code where a context switch is undesirable.
Instruction Cache Handling
The microblaze_enable_icache.s and microblaze_disable_icache.s files contain functions to enable and disable the instruction cache on MicroBlaze.
void microblaze_enable_icache(void)
This functions enables the instruction cache on MicroBlaze. When MicroBlaze starts up, the instruction cache is disabled. The ICache must be explicitly turned on using this function.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
25
R
Chapter 4: Standalone Board Support Package
void microblaze_disable_icache(void)
This function disables the instruction cache on MicroBlaze.
void microblaze_update_icache (int tag, int instr, int lock_valid)
This function updates the cache tag with the appropriate instr. The function disables the cache before updating the tag line. The MSR is restored back to its original value after the cache is updated. This function can also be used to invalidate and lock the cache depending on the value of the lock_valid parameter. The effect of this parameter is summarized in Table 4-1.
Table 4-1: Lock
0 0
Effect of lock_valid parameter Valid
0 1
lock_valid
0 1 Invalidate Cache
Effect
Valid, but unlocked cacheline. The same cacheline can be used for more than one addresses, if required.The previous address will be swapped out of the cache and written to the memory Invalidate Cache, No effect of lock bit Valid cache and locked cacheline. The cacheline is now locked to a particular address. Other addresses cannot use this cacheline.
1 1
0 1
2 3
void microblaze_init_icache_range (int cache_addr, int cache_size)
The icache can be initialized using the function microblaze_init_icache_range. This function can be used for initializing the entire icache or only a part of it. The parameter cache_addr indicate the beginning of the cache location, which is to be initialized. The cache_size represents the size from cache_addr, which needs to be initialized. For example, microblaze_init_icache_range (0x00000300, 0x100) will initialize the instruction cache region between 0x300 to 0x3ff (0x100 bytes of cache memory is cleared starting from 0x300).
Data Cache Handling
The microblaze_enable_dcache.s and microblaze_disable_dcache.s files contain functions to enable and disable the data cache on MicroBlaze.
void microblaze_enable_dcache(void)
This functions enables the data cache on MicroBlaze. When MicroBlaze starts up, the data cache is disabled. The Dcache must be explicitly turned on using this function.
void microblaze_disable_dcache(void)
This function disables the instruction cache on MicroBlaze.
26
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
MicroBlaze BSP
R
void microblaze_update_dcache (int tag, int data, int lock_valid)
This function updates the cache tag with the appropriate data. The function disables the cache before updating the tag line. The MSR is restored back to its original value after the cache is updated. This function can also be used to invalidate and lock the cache, depending on the value of the lock_valid parameter. The effect of this parameter is summarized in Table 4-1.
void microblaze_init_dcache_range (int cache_addr, int cache_size)
The icache can be initialized using the function microblaze_init_dcache_range. This function can be used for initializing the entire icache or only a part of it. The parameter cache_addr indicate the beginning of the cache location, which is to be initialized. The cache_size represents the size from cache_addr, which needs to be initialized. For example, microblaze_init_dcache_range (0x00000300, 0x100) will initialize the data cache region between 0x300 to 0x3ff (0x100 bytes of cache memory is cleared starting from 0x300).
Fast Simplex Link Interface Macros
The Fast Simplex Link (FSL) interfaces on MicroBlaze can be used in several ways.
microblaze_bread_datafsl(val, id)
This macro performs a blocking data get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_bwrite_datafsl(val, id)
This macro performs a blocking data put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_nbread_datafsl(val, id)
This macro performs a non-blocking data get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_nbwrite_datafsl(val, id)
This macro performs a non- blocking data put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_bread_cntlfsl(val, id)
This macro performs a blocking control get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_bwrite_cntlfsl(val, id)
This macro performs a blocking control put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
27
R
Chapter 4: Standalone Board Support Package
microblaze_nbread_cntlfsl(val, id)
This macro performs a non-blocking control get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
microblaze_nbwrite_cntlfsl(val, id)
This macro performs a non-blocking data control function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.
PowerPC BSP
When the user system contains a PowerPC, and no Operating System, the Library Generator automatically builds the Stand-Alone BSP in the project library libxil.a. The Stand-Alone BSP contains boot code, cache, file and memory management, configuration, exception handling, time and processor specific include functions.
Boot Code
The boot.S, crt0.S, and eabi.S files contain a minimal set of code for initializing the processor and starting an application.
boot.S
Code in the boot.S consists of the two sections boot and boot0. The boot section contains only one instruction that is labeled with _boot. During the link process, this instruction is mapped to the reset vector and the _boot label marks the application’s entry point. The boot instruction is a jump to the _boot0 label. The _boot0 label must reside within a ±23-bit address space of the _boot label. It is defined in the boot0 section. The code in the boot0 section calculates the 32-bit address of the _start label and jumps to it.
crt0.S
Code in the crt0.S file starts executing at the _start label. It initializes the .sbss and .bss sections to zero, as required by the ANSI C specification, sets up the stack, initializes some processor registers, and calls the main() function. The program remains in an endless loop on return from main().
eabi.S
When an application is compiled and linked with the -msdata=eabi option, GCC inserts a call to the __eabi label at the beginning of the main() function. This is the place where register R13 must be set to point to the .sdata and .sbss data sections and register R2 must be set to point to the .sdata2 read-only data section. Code in eabi.S sets these two registers to the correct values. The _SDA_BASE_ and _SDA2_BASE_ labels are generated by the linker.
Cache
The xcache_l.c file and corresponding xcache_l.h include file provide access to cache and cache-related operations.
28
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
PowerPC BSP
R
void XCache_WriteCCR0(unsigned int val);
The XCache_WriteCCR0() function writes an integer value to the CCR0 register. Below is a sample code sequence. Before writing to this register, the instruction cache must be enabled to prevent a lockup of the processor core. After writing the CCR0, the instruction cache can be disabled, if not needed.
... XCache_EnableICache(0x80000000) /* enable instruction cache for first 128 MB memory region */ XCache_WriteCCR0(0x2700E00) /* enable 8 word pre-fetching */ XCache_DisableICache() /* disable instruction cache */ ...
void XCache_EnableDCache(unsigned int regions);
The XCache_EnableDCache() function enables the data cache for a specific memory region. Each bit in the regions parameter represents 128 MB of memory. A value of 0x80000000 enables the data cache for the first 128 MB of memory (0 - 0x7FFFFFF). A value of 0x1 enables the data cache for the last 128 MB of memory (0xF8000000 - 0xFFFFFFFF).
void XCache_DisableDCache(void);
The XCache_DisableDCache() function disables the data cache for all memory regions.
void XCache_FlushDCacheLine(unsigned int adr);
The XCache_FlushDCacheLine() function flushes and invalidates the data cache line that contains the address specified by the adr parameter. A subsequent data access to this address results in a cache miss and a cache line refill.
void XCache_StoreDCacheLine(unsigned int adr);
The XCache_StoreDCacheLine() function stores in memory the data cache line that contains the address specified by the adr parameter. A subsequent data access to this address results in a cache hit if the address was already cached; otherwise, it results in a cache miss and cache line refill.
void XCache_EnableICache(unsigned int regions);
The XCache_EnableICache() function enables the instruction cache for a specific memory region. Each bit in the regions parameter represents 128 MB of memory. A value of 0x80000000 enables the instruction cache for the first 128 MB of memory (0 - 0x7FFFFFF). A value of 0x1 enables the instruction cache for the last 128 MB of memory (0xF8000000 - 0xFFFFFFFF).
void XCache_DisableICache(void);
The XCache_DisableICache() function disables the instruction cache for all memory regions.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
29
R
Chapter 4: Standalone Board Support Package
void XCache_InvalidateICache(void);
The XCache_InvalidateICache() function invalidates the whole instruction cache. Subsequent instructions produce cache misses and cache line refills.
void XCache_InvalidateICacheLine(unsigned int adr);
The XCache_InvalidateICacheLine() function invalidates the instruction cache line that contains the address specified by the adr parameter. A subsequent instruction to this address produces a cache miss and a cache line refill.
Exception Handling
This section documents the exception handling API that is provided in the Board Support Package. For an in-depth explanation on how exceptions and interrupts work on the PPC405, please refer to the chapter “Exceptions and Interrupts” in the PPC User’s Manual. The exception handling API consists of a set of the files xvectors.S, xexception_l.c, and the corresponding header file xexception_l.h.
void XExc_Init(void);
This function sets up the interrupt vector table and registers a “do nothing” function for each exception. This function has no parameters and does not return a value. This function must be called before registering any exception handlers or enabling any interrupts. When using the exception handler API, this function should be called at the beginning of your main() routine. IMPORTANT: If you are not using the default linker script, you need to reserve memory space for storing the vector table in your linker script. The memory space must begin on a 64k boundary. The linker script entry should look like this example:
.vectors : { . = ALIGN(64k); *(.vectors) }
For further information on linker scripts, please refer to the Linker documentation.
30
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
PowerPC BSP
R
void XExc_RegisterHandler(Xuint8 ExceptionId, XExceptionHandler Handler, void *DataPtr);
This function is used to register an exception handler for a specific exception. It does not return a value. Please refer to Table 4-2 for a list of parameters.
Table 4-2:
Exception Handler Parameters Parameter Type
Xuint8
Parameter Name
ExceptionId
Description
Exception to which this handler should be registered. The type and the values are defined in the header file xexception_l.h. Please refer to Table 4-3 for possible values. Pointer to the exception handling function User value to be passed when the handling function is called
Handler DataPtr
XExceptionHandler void *
Table 4-3:
Registered Exception Types and Values Exception Type Value
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
XEXC_ID_JUMP_TO_ZERO XEXC_ID_MACHINE_CHECK XEXC_ID_CRITICAL_INT XEXC_ID_DATA_STORAGE_INT XEXC_ID_INSTUCTION_STORAGE_INT XEXC_ID_NON_CRITICAL_INT XEXC_ID_ALIGNMENT_INT XEXC_ID_PROGRAM_INT XEXC_ID_FPU_UNAVAILABLE_INT XEXC_ID_SYSTEM_CALL XEXC_ID_APU_AVAILABLE XEXC_ID_PIT_INT XEXC_ID_FIT_INT XEXC_ID_WATCHDOG_TIMER_INT XEXC_ID_DATA_TLB_MISS_INT XEXC_ID_INSTRUCTION_TLB_MISS_INT XEXC_ID_DEBUG_INT
The function provided as the Handler parameter must have the following function prototype:
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
31
R
Chapter 4: Standalone Board Support Package
typedef void (*XExceptionHandler)(void * DataPtr);
This prototype is declared in the xexception_l.h header file. When this exception handler function is called, the parameter DataPtr will contain the same value as you provided when you registered the handler.
void XExc_RemoveHandler(Xuint8 ExceptionId)
This function is used to deregister a handler function for a given exception. For possible values of parameter ExceptionId, please refer to Table 4-3.
void XExc_mEnableExceptions (EnableMask);
This macro is used to enable exceptions. It must be called after initializing the vector table with function exception_Init and registering exception handlers with function XExc_RegisterHandler. The parameter EnableMask is a bitmask for exceptions to be enabled. The EnableMask parameter may have the values XEXC_CRITICAL, XEXC_NON_CRITICAL or XEXC_ALL.
void XExc_mDisableExceptions (DisableMask);
This macro is called to disable exceptions. The parameter DisableMask is a bitmask for exceptions to be disabled.The DisableMask parameter may have the values XEXC_CRITICAL, XEXC_NON_CRITICAL or XEXC_ALL.
Files
File support is limited to the stdin and stdout streams. In such an environment, the following functions do not make much sense:
x x x x x
open() (in open.c) close() (in close.c) fstat() (in fstat.c) unlink() (in unlink.c) lseek() (in lseek.c)
These files are included for completeness and because they are referenced by the C library.
int read(int fd, char *buf, int nbytes);
The read() function in read.c reads nbytes bytes from the standard input by calling inbyte(). It blocks until all characters are available, or the end of line character is read. Read() returns the number of characters read. The parameter fd is ignored.
int write(int fd, char *buf, int nbytes);
The write() function in write.c writes nbytes bytes to the standard output by calling outbyte(). It blocks until all characters have been written. Write() returns the number of characters written. The parameter fd is ignored.
int isatty(int fd);
The isatty() function in isatty.c reports if a file is connected to a tty. This function always returns 1, since only the stdin and stdout streams are supported.
32
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
PowerPC BSP
R
Memory Management
char *sbrk(int nbytes);
The sbrk() function in the sbrk.c file allocates nbytes of heap and returns a pointer to that piece of memory. This function is called from the memory allocation functions of the C library.
Process
The functions getpid() in getpid.c and kill() in kill.c are included for completeness and because they are referenced by the C library.
Processor-Specific Include Files
The xreg405.h include file contains the register numbers and the register bits for the PPC 405 processor. The xpseudo-asm.h include file contains the definitions for the most often used inline assembler instructions. These inline assembler instructions can be used from drivers and user applications written in C.
Time
The xtime_l.c file and corresponding xtime_l.h include file provide access to the 64bit time base counter inside the PowerPC core. The counter increases by one at every processor cycle. The sleep.c file and corresponding sleep.h include file implement functions for tired programs. All sleep functions are implemented as busy loops.
typedef unsigned long long XTime;
The XTime type in xtime_l.h represents the Time Base register. This struct consists of the Time Base Low (TBL) and Time Base High (TBH) registers, each of which is a 32-bit wide register. The definition of XTime is as follows:
typedef unsigned long long XTime;
void XTime_SetTime(XTime xtime);
The XTime_SetTime() function in xtime_l.c sets the time base register to the value in xtime.
void XTime_GetTime(XTime *xtime);
The XTime_GetTime() function in xtime_l.c writes the current value of the time base register to variable xtime.
void XTime_TSRClearStatusBits(unsigned long Bitmask);
The XTime_TSRClearStatusBits() function in xtime_l.c is used to clear bits in the Timer Status Register (TSR). The parameter Bitmask designates the bits to be cleared. A one in any
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
33
R
Chapter 4: Standalone Board Support Package
position of the Bitmask parameter clears the corresponding bit in the TSR. This function does not return a value. The header file xreg405.h defines the following values for the Bitmask parameter:
Table 4-4:
Bitmask Parameter Values Name Value
0x80000000 0x40000000
Description
Clearing this bit disables the watchdog timer event. Clears the Watchdog Timer Interrupt Status bit. This bit is set after a watchdog interrupt occurred, or could have occurred had it been enabled. Clears the Watchdog Timer Reset Status bits. These bits Specify the kind of reset that occurred as a result of a watchdog timer event. Clears the Programmable Interval Timer Status bit. This bit is set after a PIT interrupt has occurred. Clears the Fixed Interval Timer Status bit. This bit is set after a FIT interrupt has occurred. Clears all bits in the TSR. After a Reset, the content of the TSR is not specified. Use this Bitmask to clear all bits in the TSR.
XREG_TSR_WDT_ENABLE_NEXT_WATCHDOG XREG_TSR_WDT_INTERRUPT_STATUS
XREG_TSR_WDT_RESET_STATUS_11
0x30000000
XREG_TSR_PIT_INTERRUPT_STATUS
0x08000000
XREG_TSR_FIT_INTERRUPT_STATUS
0x04000000
XREG_TSR_CLEAR_ALL
0xFFFFFFFF
Example:
XTime_TSRClearStatusBits(TSR_CLEAR_ALL);
void XTime_PITSetInterval(unsigned long interval);
The XTime_PITSetInterval() function in xtime_l.c is used to load a new value into the Programmable-Interval Timer Register. This register is a 32-bit decrementing counter clocked at the same frequency as the time-base register. Depending on the AutoReload setting the PIT is automatically reloaded with the last written value or has to be reloaded manually. This function does not return a value.
Example:
XTime_PITSetInterval(0x00ffffff);
void XTime_PITEnableInterrupt(void);
The XTime_PITEnableInterrupt() function in xtime_l.c enables the generation of PIT interrupts. An interrupt occurs when the PIT register contains a value of 1, and is then decremented. This function does not return a value. XExc_Init() must be called, the PIT interrupt handler must be registered, and exceptions must be enabled before calling this function.
34
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
PowerPC BSP
R
Example:
XTime_PITEnableInterrupt();
void XTime_PITDisableInterrupt(void);
The XTime_PITDisableInterrupt() function in xtime_l.c disables the generation of PIT interrupts. It does not return a value.
Example:
XTime_PITDisableInterrupt();
void XTime_PITEnableAutoReload(void);
The XTime_PITEnableAutoReload() function in xtime_l.c enables the auto-reload function of the PIT Register. When auto-reload is enabled the PIT Register is automatically reloaded with the last value loaded by calling the XTime_PITSetInterval function when the PIT Register contains a value of 1 and is decremented. When auto-reload is enabled, the PIT Register never contains a value of 0. This function does not return a value.
Example:
XTime_PITEnableAutoReload();
void XTime_PITDisableAutoReload(void);
The XTime_PITDisableAutoReload() function in xtime_l.c disables the auto-reload feature of the PIT Register. When auto-reload is disabled the PIT decrements from 1 to 0. If it contains a value of 0 it stops decrementing until it is loaded with a non-zero value. This function does not return a value.
Example:
XTime_PITDisableAutoReload();
void XTime_PITClearInterrupt(void);
The XTime_PITClearInterrupt() function in xtime_l.c is used to clear PIT-Interrupt-Status bit in the Timer-Status Register. This bit specifies whether a PIT interrupt occurred. You must call this function in your interrupt-handler to clear the Status bit, otherwise another PIT interrupt will occur immediately after exiting the interrupt –handler function. This function does not return a value. Calling this function is equivalent to calling XTime_TSRClearStatusBits(XREG_TSR_PIT_INTERRUPT_STATUS).
Example:
XTime_PITClearInterrupt();
unsigned int usleep(unsigned int __useconds);
The usleep() function in sleep.c delays the execution of a program by __useconds microseconds. It always returns zero. This function requires that the processor frequency (in Hz) is defined. The default value of this variable is 400MHz. This value can be overwritten in the MSS file as follows:
BEGIN PROCESSOR
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
35
R
Chapter 4: Standalone Board Support Package
PARAMETER PARAMETER PARAMETER PARAMETER END
HW_INSTANCE = PPC405_i DRIVER_NAME = cpu_ppc405 DRIVER_VER = 1.00.a CORE_CLOCK_FREQ_HZ = 20000000
The file xparameters.h can also be modified with the correct value, as follows:
#define XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ 20000000
unsigned int sleep(unsigned int __seconds);
The sleep() function in sleep.c delays the execution of a program by __seconds seconds. It always returns zero.This function requires that the processor frequency (in Hz) is defined. The default value of this variable is 400MHz. This value can be overwritten in the MSS file as follows:
BEGIN PROCESSOR PARAMETER HW_INSTANCE = PPC405_i PARAMETER DRIVER_NAME = cpu_ppc405 PARAMETER DRIVER_VER = 1.00.a PARAMETER CORE_CLOCK_FREQ_HZ = 20000000 END
The file xparameters.h can also be modified with the correct value, as follows:
#define XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ 20000000
int nanosleep(const struct timespec *rqtp, struct timespec *rmtp);
The nanosleep() function in sleep.c is currently not implemented. It is a placeholder for linking applications against the C library. It always returns zero.
36
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 5
Xilkernel
This chapter describes Xilkernel, a kernel for the Xilinx embedded processors. The chapter contains the following sections.
x x x x x x x x x x x x x x x x x x
“Overview” “Key Features” “Xilkernel Blocks” “Xilkernel Modes” “Building Xilkernel Applications” “Xilkernel Process Model” “Xilkernel Scheduling Model” “Xilkernel API” “Interrupt Handling” “Kernel Customization” “Debugging Xilkernel” “Memory Footprint” “Xilkernel File Organization” “System Initialization” “Limitations” “Future Enhancements” “Modifying Xilkernel” “User Guide”
Overview
Xilkernel is a small, robust and modular kernel that allows a very high degree of customization, letting users tailor the kernel to an optimal level both in terms of size and functionality. It supports the core features required in an embedded/real-time kernel, with a POSIX API. Xilkernel works on both the MicroBlaze and PowerPC processors. Xilkernel IPC services can be used to implement higher level services like networking, video, audio and subsequently, run applications using these services.
Key Features
Xilkernel has the following notable features:
x
An API closely supporting a subset of POSIX that targets embedded kernels.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
37
R
Chapter 5: Xilkernel
x
Kernel implementation of core functionality, such as
i i i i i i
Process Management Thread Management Synchronization services - Semaphores and Mutex Locks IPC services - Message Queues and Shared Memory Dynamic Block Memory Allocation User level interrupt handling API
x x x x x
Highly scalable kernel that can be accommodated into a given system through the inclusion or exclusion of functionality as required. Easy kernel configuration with XPS, MLD, and MSS mechanisms. Support for static task undesired specification. Configurable scheduling - priority-driven preemptive scheduling or round-robin scheduling. System call interface to the kernel.
Xilkernel Blocks
The kernel is highly modular in design. The user can select and customize the kernel modules that are needed for the application at hand. Customizing the kernel is discussed in detail in the “Kernel Customization” section (1). Figure 5-1 shows the various modules of Xilkernel.
Xilkernel Modules
User Application Eg. Webserver User Interrupts
System Call Library
Timer Interrupt for Context Switch
Xilkernel System Call Handler Thread Management Message Queue Scheduler Process Management Shared Memory Interrupt Handler
Semaphores Dynamic Buffer Management
X10131
Figure 5-1:
Xilernel Modules
1. Some of these features might not be fully supported in a given release of xilkernel
38
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel Modes
R
Xilkernel Modes
Xilkernel and user applications can be built in two different modes:
x
Separate Executable mode In this mode, the user applications and kernel can be built as separate executables. Application entry points can be specified as addresses in the MSS process/pthreads configuration, using the parameters separate_exec_process_table and separate_exec_pthread_table in libgen configuration. Applications can get services from the kernel using the system call interface. These system call wrappers can be obtained by linking the application with libsyscall.a.This mode provides the flexibility of developing and dynamically loading each application separately. The stack for the user application will have to be separately setup as a part of each elf file and the kernel does no special stack setup. xilkernel.elf is generated only if the process contexts are not configured in the next mode in the OS specification.
x
Kernel Bundled Executable mode In this mode, the user applications and kernel are bundled and built together as a single executable elf file. The entry point for an application is a function name that is specified using parameters kernel_bundled_process_table and kernel_bundled_pthread_table in the MSS. Building xilkernel using libgen generates libxilkernel.a library. This can be linked with all the user applications which need to run on xilkernel, to generate a single kernel bundled executable. Since all the user applications are part of a single executable, symbol names, such as global variables and function names, should be unique. Though user applications can directly call the sys_ prefixed system calls, they would have to lock and unlock the kernel before calling the system calls. To simplify this process, applications in single executable mode have access to a thin library layer of system call wrappers that lock the kernel, execute the system call and then unlock the kernel. Stack is setup by the kernel on behalf of the single elf applications.The kernel bundled executable mode is a superset of the separate executable mode. Applications that are separate executables can still interface with the single executable kernel image dynamically, using the system call API in libsyscall.a. These system calls will be handled by the system call handlers that are present in the kernel image.Building and linking applications in the two xilkernel modes is illustrated in Figure 5-2.
Building Xilkernel Applications
x
Applications should define __XMK__ when being compiled. Defining this flag makes available certain definitions and declarations from the GNU include files that are required by Xilkernel and applications. Therefore, -D__XMK__ should accompany the compiler flags of any user applications. In the separate executable mode, microblaze applications should use the linker flag xl-mode-xilkernel to prevent their crt code from overwriting the interrupt and exception vectors, setup by Xilkernel, in memory. In PowerPC, a different linker script other than the default linker script, must be used to prevent the crt from overwriting Xilkernel sections. This linker script should basically look to not include the boot section in the elf image. In the kernel bundle mode, Microblaze applications should use one of the two linker flags, -xl-mode-executable or -xl-mode-xmdstub, to link the final application image. The two choices depend on if XMDSTUB is used for debugging or not. In PowerPC, kernel bundle applications must use the same top-level linker script that is present in the Xilkernel source folder, within the main processor folder. For e.g if the processor
x
x
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
39
R
Chapter 5: Xilkernel
instance is called ppc405_0, then the application must use ppc405_0/libsrc/xilkernel_v2_00_a/src/linker_script.sh when forming the final kernel bundle image. This is because, this linker script configures the vectors, code and data sections, either according to the linker script configuration in the MSS, or using default values. Refer to the Xilkernel user guide and the accompanying design examples for specific illustrations of the above concepts.
Kernel Sources
Separate Executable Mode
Kernel Bundled Executable Mode
libsyscall.a xilkernel.elf
libxilkernel.a
User Sources + + libsyscall.a libsyscall.a Executable Executable
User Sources + libxilkernel.a
Kernel and Application .elf files
Kernel Bundled Application
X10129
Figure 5-2: Building Applications for Xilkernel
The system call interface for both these xilkernel modes are illustrated in Figure 5-3. Applications that are a part of the kernel image have the advantage of relatively smaller system call latency as compared to those in separate executable mode, which requires another layer of indirection in the system call handler level.
40
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel Process Model
R
Pure Separate Executable Mode Scenario User Space
Kernel Bundled Executable Mode Scenario User Space
Proc1
Proc2
Proc3
Proc4
Proc5
Proc6
System Call Handler
Proc1 Proc2 Proc3
System Call Handler
System Call Wrappers
xilkernel.elf
libxilkernel.a
Kernel Image
Kernel Image
X10128
Figure 5-3: Xilkernel System Call Interface
Debugging applications in the two modes is different. See the “Debugging Xilkernel” section for more details about debugging the applications and the kernel.
Xilkernel Process Model
Xilkernel supports the concepts of, both, processes and threads. Processes as well as threads are multiplexed on top of process contexts in the kernel. Scheduling is done at the process context level. Therefore threads and processes contend among each other for getting scheduled on the processor. The only distinction between threads and processes in Xilkernel is that, except for pthread_create, all other pthread_ calls, are valid only from within threads. This includes the basic pthread interfaces and the pthread_mutex interfaces that are supported by Xilkernel. All the other interfaces work exactly the same irrespective of whether they are invoked from threads or processes. Both threads and processes could be statically created from separate elf files or from locations within a single elf file. Threads are not light-weight in any respect, as compared to processes. There is no protection between memory segments and therefore both processes and threads can share each other’s memory. The only other difference processes and threads is that processes that are created dynamically are assumed to be elf files that have a stack allocated as a part of the elf file image. Depending on the programming model that the user employs, either processes or threads or a mixture of both might be chosen for the system design. From henceforth in this document, the term processes would encompass both threads and processes, while threads would refer to pthreads alone.
Note:
1. The total number of process context structures that are allocated statically in the kernel depends on the sum of the configured maximum number of processes and threads. i.e. maximum number of process contexts allowed in the system. 2. Xilkernel does not feature a loader when creating new processes and threads. It creates process and thread contexts to start of from memory images assumed to be initialized. Therefore, if any elf file depends on initialized data sections, then the next time the same memory image is used to create a
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
41
R
Chapter 5: Xilkernel
process, the initialized sections will be invalid, unless some external mechanism is used to reload the elf image before creating the process.
Xilkernel Scheduling Model
Xilkernel supports either priority-driven preemptive scheduling (SCHED_PRIO) or round-robin (SCHED_RR) scheduling. This must be configured statically at kernel generation time. In SCHED_RR, there is a single ready queue and each process context executes for a configured time slice before yielding execution to the next process context in the queue. In SCHED_PRIO there are as many ready queues as there are priority levels. Priority 0 is the highest priority in the system and higher values mean lower priority. As shown in Figure 5-4, the process that is at the head of the highest priority ready queue always scheduled to execute next. Within the same priority level, scheduling is round robin. Empty ready queue levels are skipped and the next ready queue level is examined for schedulable processes. Blocked processes are off their ready queues and in their appropriate wait queues. The number of priority levels can be configured for SCHED_PRIO. For both the scheduling models, the length of the ready queue can also be configured. If there are wait queues inside the kernel (in semaphores, message queues etc.), they are configured as priority queues if scheduling mode is SCHED_PRIO.
Active 0 1 2 B C D (Blocked) A
Priority
13 14 15
E F G (Blocked)
X10132
Figure 5-4:
Priority Driven Scheduling
Each process context is in any of the following five states:
x x x x x
PROC_NEW PROC_READY PROC_RUN PROC_WAIT PROC_DEAD
The process context state diagram is shown in Figure 5-5.
42
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
Activated
Terminated
PROC_NEW
PROC_RUN
PROC_DEAD
Sc he du led
in
d cke Blo
ou t
Sc he du led
PROC_READY
PROC_WAIT
in Te at ed
Unblocked
rm
Te rm ina
ted
c blo Un d ke
X10130
Figure 5-5:
Process Context States
Xilkernel API
Process Management
A process is created and handled using the following interfaces.Some of the functions are optional and can be configured in during system initialization. Refer to the “Customizing Process Management” section for more details. Currently, a specific process_exit call is required at the end of the process’s code to allow the operating system to reclaim the process’s resources.
int process_create (unsigned int start_addr, int priority)
Parameters
start_addr is the start address of the process priority is the starting priority of the process in the system.
Returns
Returns the PID of the new process on success. Returns -1 on failure.
Description
Creates a new process. Allocates a new PID and Process Control Block (PCB) for the process.The process is placed in the appropriate ready queue. Calls the scheduler if scheduling is priority driven. sys/process.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
43
R
Chapter 5: Xilkernel
int process_exit (void)
Parameters Returns Description
None None Removes the process from the system. Schedules the next process in the system.
Caution! Do not use this to terminate a thread (described later on).
Includes sys/process.h
int process_kill (char pid)
Parameters Returns
pid is the PID of process to kill Returns 0 on success. Returns -1 on failure.
Description Note Includes
Removes the process with pid from the system. No indication is given to other processes that depend on this process. This function is optionally configured using CONFIG_PROCESS_KILL sys/process.h
int process_status (int pid, p_stat *ps)
Parameters
pid is the PID of process ps is the buffer where the process status is returned
Returns
Returns process status in ps on success Returns NULL in ps on failure. Get the status of the process or thread, whose pid is pid. The status is returned in structure p_stat which has the following fields:
i i
Description
pid is the process ID state is the current state of the process
The contents of p_stat are defined in the <sys/ktypes.h> header. Includes sys/process.h
int process_yield (void)
Parameters Returns Description
None None Yields the processor to the next process or thread.The current process goes to PROC_READY state and is put at the end of the ready queue. This function is optionally configured using CONFIG_PROCESS_YIELD. sys/process.h
Note Includes
44
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int process_setpriority (int priority)
Parameters Returns
priority is the new priority of the process. On success, return 0 On failure, return -1
Description Includes
Sets the priority of current process or thread to new value. sys/process.h
int process_getpriority (void)
Parameters Returns Description Includes
None Priority of the current process. Gets the priority of the current process or thread. sys/process.h
int get_currentPID (void)
Parameters Returns Description Includes
None Process ID of current process or thread.
Gets the Process ID of process context that is executing currently.
sys/process.h
Thread Management
Xilkernel supports the basic POSIX threads API. A thread is scheduled and allocated in the same way as a process. Threads created in the system have a kernel wrapper to which they return control to when they terminate. Therefore a specific exit function is not required at the end of the thread’s code. Thread stack is allocated on the thread’s behalf from a pool of bss memory that is statically allocated depending on the maximum number of threads in the system. Therefore, threads created dynamically are not required to be associated with an elf file. The entire thread module is optional and can be configured in or out as a part of the software specification. See the “Customizing Thread Management” section for more
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
45
R
Chapter 5: Xilkernel
details on customizing this module. The thread management interface is summarized below.
int pthread_create (pthread_t thread, pthread_attr_t* attr, void* (*start_func)(void*), void* param)
Parameters
thread is the location to store the created thread’s identifier. attr is the pointer to thread creation attributes structure. start_func is the start address of the function from which the thread needs to execute param is the pointer argument to the thread function
Returns
Returns 0 and thread id of the created thread in *thread, on success. Returns -1 if thread refers to an invalid location. Returns EINVAL if attr refers to invalid attributes. Returns EAGAIN if resources unavailable to create the thread.
Description
The pthread_create() function creates a new thread, with attributes specified by attr, within a process. If attr is NULL, the default attributes are used. If the attributes specified by attr are modified later, the thread’s attributes are not be affected. Upon successful completion, pthread_create() stores the ID of the created thread in the location referenced by thread. The thread is created executing start_routine with arg as its sole argument. If the start_routine returns, the effect is as if there was an implicit call to pthread_exit() using the return value of start_routine as the exit status. This exit behavior is slightly different for the main thread. This is explained in the pthread_exit description.
Includes
pthread.h
void pthread_exit (void *value_ptr)
Parameters Returns Description
value_ptr is a pointer to the return value of the thread. None The pthread_exit() function will terminate the calling thread and make the value value_ptr available to any successful join with the terminating thread. Thread termination releases process context resources, including, but not limited to, memory and attributes. An implicit call to pthread_exit() is made when a returns from the start routine that was used to create it. The function’s return value serves as the thread’s exit status.
Caution! There is no implicit thread exit invoked at the end of a
thread created out of an elf file by specifying the start address of the executable instructions in the elf file. Control returns to an exit stub which loops indefinitely. Therefore, to terminate such threads an explicit call to this thread exit routine is required.
Includes
pthread.h
46
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int pthread_join (pthread_t thread, void **value_ptr)
Parameters Returns
value_ptr is a pointer to the return value of the thread. 0 on success Returns ESRCH if the target thread is not in a joinable state or is an invalid thread. Returns EINVAL if the target thread already has someone waiting to join with it.
Description
The pthread_join() function suspends execution of the calling thread until the target thread terminates, unless the target thread has already terminated. On return from a successful pthread_join() call with a non-NULL value_ptr argument, the value passed to pthread_exit() by the terminating thread is made available in the location referenced by value_ptr. When a pthread_join() returns successfully, the target thread has been terminated. The results of multiple simultaneous calls to pthread_join() specifying the same target thread are that only one thread succeeds and the others fail with EINVAL.
Note: No deadlock detection is provided.
Includes pthread.h
pthread_t pthread_self (void)
Parameters Returns
None On success, returns thread identifier of current thread. Error behavior not defined. The pthread_self() function returns the thread ID of the calling thread. pthread.h
Description Includes
int pthread_detach (pthread_t target)
Parameters Returns
target is the target thread to detach. Returns 0 on success. Returns ESRCH if target thread cannot be found.
Description
The pthread_detach() function indicates to the implementation that storage for the thread thread can be reclaimed when that thread terminates. If thread has not terminated, pthread_detach() will not cause it to terminate. The effect of multiple pthread_detach() calls on the same target thread is unspecified. pthread.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
47
R
Chapter 5: Xilkernel
int pthread_equal (pthread_t t1, pthread_t t2)
Parameters Returns
t1 and t2 are the two thread identifiers to compare. Returns 1 if t1 and t2 refer to threads that are equal. Returns 0 otherwise.
Description
The pthread_equal() function returns a non-zero value if t1 and t2 are equal; otherwise, zero is returned.If either t1 or t2 are not valid thread IDs, zero is returned. pthread.h
attr)
Includes
int pthread_attr_init (pthread_attr_t*
Parameters Returns
attr is a pointer to the attribute structure to be initialized. Returns 0 on success, 1 on failure. Returns EINVAL on invalid attr parameter.
Description
The pthread_attr_init() function initializes a thread attributes object attr with the default value for all of the individual attributes used by a given implementation. The contents of pthread_attr_t are defined in the <sys/types.h> header.
Note: This does not make a call into the kernel.
Includes pthread.h
attr)
int pthread_attr_destroy (pthread_attr_t*
Parameters Returns
attr is a pointer to the thread attributes that have to be destroyed. Returns 0 on success. Returns EINVAL on errors.
Description
The pthread_attr_destroy() function destroys a thread attributes object. The implementation causes pthread_attr_destroy() to set attr to an implementation-defined invalid value. A destroyed attr attributes object can be re-initialized using pthread_attr_init(); the results of otherwise referencing the object after it has been destroyed are undefined.
Note: This does not make a call into the kernel.
Includes pthread.h
48
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int pthread_attr_setdetachstate
(pthread_attr_t*
attr, int
dstate)
Parameters
attr is the attribute structure on which the operation is to be performed. dstate is the detachstate required.
Returns
Returns 0 on success. Returns EINVAL on invalid parameters. The detachstate attribute controls whether the thread is created in a detached state. If the thread is created detached, then when the thread exits, the thread’s resources are detached without requiring a pthread_join() or a call pthread_detach().The application can set detachstate to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.
Description
Note: This does not make a call into the kernel.
Includes pthread.h
(pthread_attr_t* attr, int *dstate)
int pthread_attr_getdetachstate
Parameters
attr is the attribute structure on which the operation is to be performed. dstate is the location to store the detachstate in.
Returns
Returns 0 on success. Returns EINVAL on invalid parameters.
Description
The implementation stores either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE in dstate, if the value of detachstate was valid in attr.
Note: This does not make a call into the kernel.
Includes pthread.h
attr, struct
int pthread_attr_setschedparam (pthread_attr_t* sched_param *schedpar)
Parameters
attr is the attribute structure on which the operation is to be performed. schedpar is the location of the structure that contains the scheduling parameters.
Returns
Returns 0 on success. Returns EINVAL on invalid parameters. Returns ENOTSUP for invalid scheduling parameters.
Description
The pthread_attr_setschedparam() functions sets the scheduling parameter attributes in the attr argument. The contents of the sched_param structure are defined in the <sched.h> header.
Note: This does not make a call into the kernel.
Includes pthread.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
49
R
Chapter 5: Xilkernel
int pthread_attr_getschedparam sched_param* schedpar)
(pthread_attr_t*
attr, struct
Parameters
attr is the attribute structure on which the operation is to be performed. schedpar is the location to store the sched_param structure in. Returns 0 on success. Returns EINVAL on invalid parameters.
Returns
Description
The pthread_attr_getschedparam() gets the scheduling parameter attributes in the attr argument. The contents of the param structure are defined in the <sched.h> header.
Note: This does not make a call into the kernel.
Includes pthread.h
Semaphores
Xilkernel supports kernel allocated POSIX semaphores that can be used for synchronization. POSIX semaphores are counting semaphores that also count below zero (a negative value indicates the number of processes blocked on the semaphore). Xilkernel also supports a few interfaces for working with named semaphores. The number of semaphores allocated in the kernel and the length of semaphore wait queues can be configured during system initialization. Refer to the “Customizing Semaphore” section for more details.The semaphore module is optional and can be configured in or out during system initialization. The message queue module, described later on in this document, uses semaphores. Therefore this module needs to be included if message queues are to be used. The Xilkernel semaphore interface is described below.
int sem_init (sem_t *sem, int pshared, unsigned value)
Parameters
sem is the location to store the created semaphore’s identifier. pshared indicates sharing status of the semaphore, between processes. value is the initial count of the semaphore.
Note: pshared is unused currently.
Returns Returns 0 on success. Returns -1 on failure. Description The sem_init() function initializes the unnamed semaphore referred to by sem. The value of the initialized semaphore is value. Following a successful call to sem_init(), the semaphore may be used in subsequent calls to sem_wait(), sem_trywait(), sem_post(), and sem_destroy(). This semaphore remains usable until the semaphore is destroyed. Only sem itself may be used for performing synchronization. The result of referring to copies of sem in calls to sem_wait(), sem_trywait(), sem_post(), and sem_destroy() is undefined. Attempting to initialize an already initialized semaphore results in undefined behavior. semaphore.h
Includes
50
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int sem_destroy (sem_t* sem)
Parameters Returns
sem is the semaphore to be destroyed. Returns 0 on success. Returns -1 on failure.
Description
The sem_destroy() function destroys the unnamed semaphore indicated by sem. Only a semaphore that was created using sem_init() may be destroyed using sem_destroy(); the effect of calling sem_destroy() with a named semaphore is undefined. The effect of subsequent use of the semaphore sem is undefined until sem is reinitialized by another call to sem_init(). semaphore.h
Includes
int sem_getvalue (sem_t* sem, int* value)
Parameters
sem is the semaphore identifier value is the location where the semaphore value is stored.
Returns
Returns 0 on success and value appropriately filled in. Returns -1 on failure. The sem_getvalue() function updates the location referenced by the sval argument to have the value of the semaphore referenced by sem without affecting the state of the semaphore. The updated value represents an actual semaphore value that occurred at some unspecified time during the call, but it need not be the actual value of the semaphore when it is returned to the calling process. If sem is locked, then the object to which sval points is set to a negative number whose absolute value represents the number of processes waiting for the semaphore at some unspecified time during the call.
Description
Includes
semaphore.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
51
R
Chapter 5: Xilkernel
int sem_wait (sem_t* sem)
Parameters Returns
sem is the semaphore identifier. Returns 0 on success and the semaphore in a locked state. Returns -1 on failure.
Description
The sem_wait() function locks the semaphore referenced by sem by performing a semaphore lock operation on that semaphore. If the semaphore value is currently zero, then the calling thread does not return from the call to sem_wait() until it either locks the semaphore or the semaphore is forcibly destroyed. Upon successful return, the state of the semaphore is locked and remains locked until the sem_post() function is executed and returns successfully.
Note: When a process is unblocked within the sem_wait call, where it blocked due to unavailability of the semaphore, the semaphore may have been destroyed forcibly. In such a case, -1 is returned. Semaphores maybe forcibly destroyed due to destroying message queues which internally use semaphores. No deadlock detection is provided.
Includes semaphore.h
int sem_trywait (sem_t* sem)
Parameters Returns
sem is the semaphore identifier. Returns 0 on success. Returns -1 on failure.
Description
The sem_trywait() function locks the semaphore referenced by sem only if the semaphore is currently not locked; that is, if the semaphore value is currently positive. Otherwise, it does not lock the semaphore and returns -1. semaphore.h
Includes
52
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int sem_post (sem_t* sem)
Parameters Returns
sem is the semaphore identifier Returns 0 on success. Returns -1 on failure.
Description
The sem_post() function unlocks the semaphore referenced by sem by performing a semaphore unlock operation on that semaphore. If the semaphore value resulting from this operation is positive, then no threads were blocked waiting for the semaphore to become unlocked; the semaphore value is simply incremented. If the value of the semaphore resulting from this operation is zero or negative, then one of the threads blocked waiting for the semaphore is allowed to return successfully from its call to sem_wait(). This is either the first thread on the queue, if scheduling mode is SCHED_RR or, it is the highest priority thread in the queue, if scheduling mode is SCHED_PRIO.
Note: If an unlink operation had been requested on the semaphore, the unlink is performed if the post operation sees that no more processes are waiting on the semaphore.
Includes semaphore.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
53
R
Chapter 5: Xilkernel
sem_t* sem_open (const char* name, int oflag, ...)
Parameters
name points to a string naming a semaphore object. oflag is the flag that controls the semaphore creation.
Returns
Returns a pointer to the created/existing semaphore identifier. Returns SEM_FAILED on failures. The sem_open() function establishes a connection between a named semaphore and a process. Following a call to sem_open() with semaphore name name, the process may reference the semaphore associated with name using the address returned from the call. This semaphore may be used in subsequent calls to sem_wait(), sem_trywait(), sem_post(), and sem_close(). The semaphore remains usable by this process until the semaphore is closed by a successful call to sem_close(). The oflag argument controls whether the semaphore is created or merely accessed by the call to sem_open(). The following flag bits may be set in oflag: O_CREAT This flag is used to create a semaphore if it does not already exist. If O_CREAT is set and the semaphore already exists, then O_CREAT has no effect, except as noted under O_EXCL. Otherwise, sem_open() creates a named semaphore. The O_CREAT flag requires a third and a fourth argument: mode, which is of type mode_t, and value, which is of type unsigned. The semaphore is created with an initial value of value. After the semaphore named name has been created by sem_open() with the O_CREAT flag, other processes can connect to the semaphore by calling sem_open() with the same value of name. O_EXCL If O_EXCL and O_CREAT are set, sem_open() fails if the semaphore name exists. The check for the existence of the semaphore and the creation of the semaphore if it does not exist are atomic with respect to other processes executing sem_open() with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, the effect is undefined. If flags other than O_CREAT and O_EXCL are specified in the oflag parameter, an error is signalled. If a process makes multiple successful calls to sem_open() with the same value for name, the same semaphore address is returned for each such successful call, provided that there have been no calls to sem_unlink() for this semaphore.
Description
Note: The mode argument is unused currently.
Includes semaphore.h
54
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int sem_close (sem_t* sem)
Parameters Returns
sem is the semaphore identifier Returns 0 on success. Returns -1 on failure.
Description
The sem_close() function indicates that the calling process is finished using the named semaphore sem. The sem_close() function deallocates (that is, make available for reuse by a subsequent sem_open() by this process) any system resources allocated by the system for use by this process for this semaphore. The effect of subsequent use of the semaphore indicated by sem by this process is undefined. The name mapping for this named semaphore is also destroyed. The call fails if the semaphore is currently locked. semaphore.h
Includes
int sem_unlink (const char* name)
Parameters Returns
name is the name that refers to the semaphore Returns 0 on success. Returns -1 on failure.
Description
The sem_unlink() function removes the semaphore named by the string name. If the semaphore named by name has processes blocked on it, then sem_unlink() has no immediate effect on the state of the semaphore. The destruction of the semaphore is postponed until all blocked and locking processes relinquish the semaphore. Calls to sem_open() to recreate or reconnect to the semaphore refer to a new semaphore after sem_unlink() is called. The sem_unlink() call does not block until all references relinquish the semaphore; it returns immediately.
Note: If an unlink operation had been requested on the semaphore, the unlink is performed on a post operation that sees that no more processes waiting on the semaphore.
Includes semaphore.h
Message Queues
Xilkernel supports kernel allocated XSI message queues. XSI is the X/Open System Interface which is a set of optional interfaces under POSIX. Message queues can be used as an IPC mechanism. The message queues can take in arbitrary sized messages. However, buffer memory allocation must be configured appropriately for the memory blocks required for the messages, as a part of system malloc initialization.The number of message queue structures allocated in the kernel and the length of the message queues can be also be configured during system initialization. The message queue module is optional and can be configured in/out. Refer to the “Customizing Message Queue” section for more details. This module depends on the semaphore module and the dynamic block memory
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
55
R
Chapter 5: Xilkernel
allocation module being present in the system. The Xilkernel message queue interface is described below.
int msgget( key_t key, int msgflg )
Parameters
key is a unique identifier for referring to the message queue. msgflg specifies the message queue creation options.
Returns
Returns a unique non-negative integer message queue identifier. Returns -1 on failure.
Description
The msgget() function returns the message queue identifier associated with the argument key. A message queue identifier, associated message queue, and data structure (see <sys/kmsg.h>), are created for the argument key if the argument key does not already have a message queue identifier associated with it, and (msgflg & IPC_CREAT) is non-zero. Upon creation, the data structure associated with the new message queue identifier is initialized as follows:
x x
msg_qnum, msg_lspid, msg_lrpid are set equal to 0. msg_qbytes is set equal to the system limit (MSGQ_MAX_BYTES).
The msgget() function fails if a message queue identifier exists for the argument key but ((msgflg & IPC_CREAT) && (msgflg & IPC_EXCL)) is non-zero.
Note: IPC_PRIVATE is not supported. Also, messages in the message queue are not required to be of the form shown below. There is no support for message type based message receives and sends in this implementation.
struct mymsg { long mtype; /* Message type. */ char mtext[some_size]; /* Message text. */ }
Includes
sys/msg.h sys/ipc.h
56
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int msgctl (int msqid, int cmd, struct msqid_ds* buf)
Parameters
msqid is the message queue identifier. cmd is the command. buf is the data buffer
Returns
Returns 0 on success. Status is returned in buf for IPC_STAT Returns -1 on failure.
Description
The msgctl() function provides message control operations as specified by cmd. The following values for cmd, and the message control operations they specify, are: IPC_STAT Place the current value of each member of the msqid_ds data structure associated with msqid into the structure pointed to by buf. The contents of this structure are defined in <sys/msg.h>. IPC_SET - Unsupported. IPC_RMID Remove the message queue identifier specified by msqid from the system and destroy the message queue and msqid_ds data structure associated with it. The remove operation forcibly destroys the semaphores used internally and unblocks processes that are blocked on the semaphore. It also deallocates memory allocated for the messages in the queue.
Includes
sys/msg.h sys/ipc.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
57
R
Chapter 5: Xilkernel
int msgsnd (int msqid, const void *msgp, size_t msgsz, int msgflg)
Parameters
msqid is the message queue identifier. msgp is a pointer to the message buffer. nbytes is the size of the message msgflg is used to specify message send options.
Returns
Returns 0 on success. Returns -1 on failure.
Description
The msgsnd() function sends a message to the queue associated with the message queue identifier specified by msqid. The argument msgflg specifies the action to be taken if the message queue is full: If (msgflg & IPC_NOWAIT) is non-zero, the message is not sent and the calling thread returns immediately. If (msgflg & IPC_NOWAIT) is 0, the calling thread suspends execution until one of the following occurs:
x The condition responsible for the suspension no longer exists, in which case the message is sent. x The message queue identifier msqid is removed from the system; when this occurs -1 is returned.
The send fails if it is unable to allocate memory to store the message inside the kernel. On a successful send operation, the msg_lspid and msg_qnum members of the message queues are appropriately set. Includes sys/msg.h sys/ipc.h
58
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
ssize_t msgrcv (int msqid, void *msgp, size_t nbytes, long msgtyp, int msgflg
Parameters
msqid is the message queue identifier. msgp is the buffer where the received message is to be copied. nbytes specifies the size of the message that the buffer can hold. msgtyp is unsupported currently. msgflg is used to control the message receive operation.
Returns
Returns 0 on success and stores received message in user buffer. Returns -1 on failure.
Description
The msgrcv() function reads a message from the queue associated with the message queue identifier specified by msqid and places it in the user-defined buffer pointed to by msgp. The argument msgsz specifies the size in bytes of the message. The received message is truncated to msgsz bytes if it is larger than msgsz and (msgflg & MSG_NOERROR) is non-zero. The truncated part of the message is lost and no indication of the truncation is given to the calling process. If MSG_NOERROR is not specified and the received message is larger than nbytes, -1 is returned signalling error. The argument msgflg specifies the action to be taken if a message is not on the queue. These are as follows: If (msgflg & IPC_NOWAIT) is non-zero, the calling thread returns immediately with a return value of -1. If (msgflg & IPC_NOWAIT) is 0, the calling thread suspends execution until one of the following occurs:
i A message is placed on the queue. i The message queue identifier msqid is removed from the
system; when this occurs -1 is returned. Upon successful completion, the following actions are taken with respect to the data structure associated with msqid:
i msg_qnum is decremented by 1. i msg_lrpid is set equal to the process ID of the calling process.
Includes
sys/msg.h sys/ipc.h
Shared Memory
Xilkernel supports kernel allocated XSI shared memory. XSI is the X/Open System Interface which is a set of optional interfaces under POSIX. Shared memory is a common, low-latency IPC mechanism. Shared memory blocks required during run-time must be identified and specified during the system configuration.From this specification, buffer memory is allocated to each shared memory region. Shared memory is currently not allocated dynamically at run-time. This module is optional and can be configured in or out during system specification. Refer to the “Customizing Shared Memory” section for more details. The Xilkernel shared memory interface is described below.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
59
R
Chapter 5: Xilkernel
Caution! The memory buffers allocated by the shared memory API might not be aligned at
word boundaries. Therefore, structures should not be arbitrarily mapped to shared memory segments, without checking if alignment requirements are met. int shmget (key_t key, size_t size, int shmflg)
Parameters
key is used to uniquely identify the shared memory region. size is the requested size of the shared memory segment shmflg is used to specify segment creation options
Returns
Returns unique non-negative shared memory identifier on success. Returns -1 on failure.
Description
The shmget() function returns the shared memory identifier associated with key. A shared memory identifier, associated data structure, and shared memory segment of at least size bytes (see <sys/shm.h>) are created for key if one of the following is true:
x The argument key is equal to IPC_PRIVATE. x The argument key does not already have a shared memory identifier associated with it and (shmflg &IPC_CREAT) is nonzero.
Upon creation, the data structure associated with the new shared memory identifier shall be initialized.The value of shm_segsz is set equal to the value of size.The values of shm_lpid, shm_nattch, shm_cpid are all initialized appropriately.When the shared memory segment is created, it is initialized with all zero values
Note: At least one of the shared memory segments available in the system must EXACTLY match the requested size for the call to succeed. key IPC_PRIVATE is not supported.
Includes sys/shm.h sys/ipc.h
60
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int shmctl (int shmid, int cmd, struct shmid_ds *buf)
Parameters
shmid is the shared memory segment identifier. cmd is the command to the control function. buf is the buffer where the status is returned.
Returns
Returns 0 on success. Status is returned in buffer for IPC_STAT. Returns -1 on failure.
Description
The shmctl() function provides a variety of shared memory control operations as specified by cmd. The following values for cmd are available: IPC_STAT Place the current value of each member of the shmid_ds data structure associated with shmid into the structure pointed to by buf. The contents of the structure are defined in <sys/shm.h> IPC_SET is not supported IPC_RMID Remove the shared memory identifier specified by shmid from the system and destroy the shared memory segment and shmid_ds data structure associated with it. No notification is sent to processes still attached to the segment.
Includes
sys/shm.h sys/ipc.h
void* shmat (int shmid, const void *shmaddr, int flag)
Parameters
shmid is the shared memory segment identifier. shmaddr is used to specify the location, to attach shared memory segment. This is unused currently. flag is used to specify SHM attach options.
Returns
Returns the start address of the shared memory segment on success. Returns NULL on failure. shmat() increments the value of shm_nattch in the data structure associated with the shared memory ID of the attached shared memory segment and returns the segment’s start address. shm_lpid is also appropriately set.
Description
Note: shmaddr and flag arguments are not used.
Includes sys/shm.h sys/ipc.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
61
R
Chapter 5: Xilkernel
int shm_dt (void *shmaddr)
Parameters Returns
shmaddr is the shared memory segment address that is to be detached. Returns 0 on success. Returns -1 on failure.
Description
The shmdt() function detaches the shared memory segment located at the address specified by shmaddr from the address space of the calling process.The value of shm_nattch is also decremented.The memory segment is not removed from the system and can be attached to again. sys/shm.h sys/ipc.h
Includes
Mutex Locks
Xilkernel provides support for kernel allocated POSIX thread mutex locks. This synchronization mechanism can be used alongside of the pthread_ API. The number of mutex locks and the length of the mutex lock wait queue can be configured during system
62
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
specification. This module is also optional and can be configured in or out during system specification. Please refer to the “Customizing Shared Memory”section for more details.
int pthread_mutex_init (pthread_mutex_t* pthread_mutexattr_t* attr) mutex, const
Parameters
mutex is the location where the newly created mutex lock’s identifier is to be stored. attr is the mutex creation attributes structure.
Returns
Returns 0 on success and mutex identifier in *mutex. Returns EAGAIN if system out of resources. The pthread_mutex_init() function initializes the mutex referenced by mutex with attributes specified by attr. If attr is NULL, the default mutex attributes are used; the effect shall be the same as passing the address of a default mutex attributes object. Upon successful initialization, the state of the mutex becomes initialized and unlocked. Only mutex itself may be used for performing synchronization. The result of referring to copies of mutex in calls to pthread_mutex_lock(), pthread_mutex_trylock(), pthread_mutex_unlock(), and pthread_mutex_destroy() is undefined. Attempting to initialize an already initialized mutex results in undefined behavior.In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated. The effect shall be equivalent to dynamic initialization by a call to pthread_mutex_init() with parameter attr specified as NULL, except that no error checks are performed. For example,
static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER;
Description
Note: The mutex locks allocated by xilkernel follow the semantics of PTHREAD_MUTEX_DEFAULT mutex locks. i.e attempting to recursively lock the mutex results in undefined behavior. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behavior. Attempting to unlock the mutex if it is not locked results in undefined behavior.
Includes pthread.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
63
R
Chapter 5: Xilkernel
int pthread_mutex_destroy (pthread_mutex_t*
mutex)
Parameters Returns
mutex is the mutex identifier. Returns 0 on success. Returns EINVAL if mutex refers to an invalid identifier.
Description
The pthread_mutex_destroy() function destroys the mutex object referenced by mutex; the mutex object becomes, in effect, uninitialized. A destroyed mutex object can be reinitialized using pthread_mutex_init(); the results of otherwise referencing the object after it has been destroyed are undefined.
Note: Mutex lock/unlock state disregarded during destroy. No consideration is given for waiting processes.
Includes pthread.h
mutex)
int pthread_mutex_lock (pthread_mutex_t*
Parameters Returns
mutex is the mutex identifier. Returns 0 on success and mutex in a locked state. Returns EINVAL on invalid mutex reference and -1 on unhandled errors.
Description
The mutex object referenced by mutex is locked by the thread calling pthread_mutex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mutex object referenced by mutex in the locked state. pthread.h
mutex)
Includes
int pthread_mutex_trylock (pthread_mutex_t*
Parameters Returns
mutex is the mutex identifier. Returns 0 on success and mutex in a locked state. Returns EINVAL on invalid mutex reference, EBUSY if mutex is already locked and -1 on unhandled errors.
Description
The mutex object referenced by mutex is locked by the thread calling pthread_mutex_trlock(). If the mutex is already locked, the calling thread returns immediately with EBUSY. Otherwise, the mutex is locked on behalf of the calling thread becomes available. pthread.h
Includes
64
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel API
R
int pthread_mutex_unlock (pthread_mutex_t*
mutex)
Parameters Returns
mutex is the mutex identifier. Returns 0 on success. Returns EINVAL on invalid mutex reference and -1 on undefined errors.
Description
The pthread_mutex_unlock() function shall release the mutex object referenced by mutex. If there are threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy shall determine which thread shall acquire the mutex. If it is SCHED_RR, then the thread that is at the head of the mutex wait queue is unblocked and allowed to lock the mutex. pthread.h
attr)
Includes
int pthread_mutexattr_init (pthread_mutexattr_t*
Parameters Returns
attr is the location of the attributes structure. Returns 0 on success. Returns EINVAL if attr refers to an invalid location.
Description
The pthread_mutexattr_init() function initializes a mutex attributes object attr with the default value for all of the attributes defined by the implementation.
Note: Refer to <sys/types.h> for the contents of the pthread_mutexattr
structure.This routine does not involve a call into the kernel.
Includes
pthread.h
attr)
int pthread_mutexattr_destroy (pthread_mutexattr_t*
Parameters Returns
attr is the location of the attributes structure. Returns 0 on success. Returns EINVAL if attr refers to an invalid location. The pthread_mutexattr_destroy() function destroys a mutex attributes object; the object becomes, in effect, uninitialized.
Description
Note: This routine does not involve a call into the kernel.
Includes pthread.h
Dynamic Block Memory Management
The kernel provides a simple block memory allocation scheme, which can be used by applications that need dynamic memory allocation. The application can also use the standard ‘C’ memory allocation routines.The user can select different memory blocks sizes and number of such memory blocks required for the application. The memory blocks and the total memory needed by the system is allocated statically and can be configured by the user. Refer to the “Customizing Dynamic Block Memory Management” section for more details.This method of buffer management is relatively simple, small and a fast way of
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
65
R
Chapter 5: Xilkernel
allocating memory. The following are the block memory allocation interfaces. This module is optional and can be included during system initialization.
Caution! The memory buffers allocated by the block memory allocation API might not be
aligned at word boundaries. Therefore, structures should not be arbitrarily mapped to memory allocated this way, without checking if alignment requirements are ment. void* bufmalloc (unsigned int size)
Parameters Returns
size is the size of memory block requested. Returns the start address of the memory block on success. Return NULL on failure. Allocate memory to the user process sys/mem.h
Description Includes
void buffree (void* mem)
Parameters Returns Description Includes
mem is the address of the memory block. None Free the memory allocated by bufmalloc. sys/mem.h
Interrupt Handling
Xilkernel abstracts away the basic interrupt handling requirements of the kernel during initialization. Even though the kernel will be functional without any interrupts, it makes sense for the system to be at least driven by a single timer pulse for scheduling. In this case the kernel handles the main timer interrupt, using it as the kernel tick to perform scheduling. The timer interrupt is initialized and tied to the vectoring code during system initialization. For MicroBlaze xilkernels, the system specification requires that a timer device specification is present. MicroBlaze systems must use either the standard Xilinx FIT or PIT timers. The timer tick interval can be customized by the user based on the
66
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Interrupt Handling
R
application if the PIT is used in MicroBlaze systems and always, in PPC405 systems. Refer to the “Configuring System Timer” section for more details.
Interrupts/ Exceptions Enabled Task Code Interrupted Interrupts/ Exceptions Disabled Save volatile registers interrupt vectoring code
timer_int_handler( ) process_scheduler( ); IF context switch required THEN XMK_CONTEXT_SWITCH( );
Interrupts/ Exceptions Enabled Next Task Proceeds
Restore volatile registers
Return in the context of the "next" task
X10141
Figure 5-6: Basic Interrupt Service in Xilkernel
The interrupt service in this scenario with a single timer interrupt in the system is sketched in Figure 5-6. Upon an interrupt, the volatile registers (defined by the EABI of the processor) are saved onto the interrupted task’s stack. The interrupt is then vectored to a handler that is registered at system startup. In Xilkernel’s case, the timer_int_handler() routine, is the registered handler. This routine invokes process_scheduler() to request a rescheduling operation. If the reschedule operation switched tasks, a context switch is performed. If a programmable interval timer is present in the system (always present in PPC) then its counter is reset to the interval defined at system startup. After the context switch, execution will resume in the context of the switched-to process. Since volatile registers were saved on the stack during an interrupt, they are again restored appropriately from the stack of whatever process gets to execute. Xilkernel can also work with multiple interrupts in the system, handled through an interrupt controller. See the “Configuring Interrupt Handling” section for more details on configuring Xilkernel for multiple external interrupt handling. Figure 5-7 illustrates the service sequence when interrupts are handled through an interrupt controller. The interrupt controller’s handler services all interrupt requests. However, the timer_int_handler() does not immediately perform a context switch, in this configuration. It sets a flag indicating if a context switch is required. The interrupt controller’s handler recognizes a pending context switch and performs the actual context switch at the end of the service routine. The rest of the flow is similar to the basic service routine. The flow is slightly different from PPC systems, since there is a dedicated interrupt notification for the internal PIT device. In other words, the handlers for the system timer interrupt and other external interrupts are different and hence the interrupt controller’s handler follows this
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
67
R
Chapter 5: Xilkernel
sequence of actions, without the scheduling portion, while the timer_int_handler() performs the same sequence of actions as the basic service routine.
IE = 1 Task Code Gets Interrupted IE = 0
_ _interrupt_handler( ) save volatile registers intc_device_interrupt_handler( );
intc_device_interrupt_handler( ) 1. Determine source of interrupts 2. Service ALL interrupt requests 3. IF process_scheduler( ) invoked on a timer interrupt THEN Do a context switch if required
Return in the context of the "next" task
Restore saved registers IE = 1 Next Task Proceeds IE = 1
X10140
Figure 5-7: Extended Interrupt Service in Xilkernel
There are certain limitations on the operations that can be performed inside the user-level interrupt handlers. Since, technically, the system is still executing the ISR in the context of the task that was interrupted, invoking any kind of API that may cause a rescheduling operation can potentially cause the system to enter an invalid state. The advantage of letting the system still be in the context of the process that was interrupted, in an ISR, is that on an interrupt, the entire context of the process need not be saved. This can provide significant reduction in the actual interrupt service response time. However, it imposes the restriction described above. The actual context switch, due to a rescheduling operation by the kernel, occurs at the end of servicing all the ISRs. Xilkernel support for multiple interrupts has been designed to work with the opb_intc peripheral that is a part of the standard EDK distribution. Other interrupt controllers will need the relevant support routines in the mb-hw.c, ppc-hw.c and the intr.c,h files, modified accordingly. Xilkernel also recognizes only interrupts connected through only one level of
68
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Interrupt Handling
R
interrupt controllers. Cascaded interrupt controllers are not supported. The Xilkernel userlevel interrupt handling API, is described below.
unsigned int register_int_handler (int_id_t id, void (*handler)(void*), void *callback)
Parameters
id is the zero-based numeric id of the interrupt. handler is the user-level handler. callback is a callback value that can be delivered to the user-level handler.
Returns
Returns XST_SUCCESS on success. Returns error codes defined in <xstatus.h>.
Description
The register_int_handler() function registers the specified user level interrupt handler as the handler for a specified interrupt. The user level routine will be invoked asynchronously upon being serviced by an interrupt controller in the system. The routine returns an error on MicroBlaze systems, if id is the identifier for the system timer interrupt. PPC systems have a dedicated hardware timer interrupt that exists separately from the other interrupts in the system. Therefore, this check is not performed for a PPC system. <sys/intr.h>
Includes
void unregister_int_handler (int_id_t id)
Parameters Returns Description
id is the zero-based numeric id of the interrupt. None The unregister_int_handler() function unregisters the registered user level interrupt handler as the handler for the specified interrupt. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt. <sys/intr.h>
Includes
void enable_interrupt (int_id_t id)
Parameters Returns Description
id is the zero-based numeric id of the interrupt. None The enable_interrupt() function enables the specified interrupt in the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt. <sys/intr.h>
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
69
R
Chapter 5: Xilkernel
void disable_interrupt (int_id_t id)
Parameters Returns Description
id is the zero-based numeric id of the interrupt. None The disable_interrupt() function disables the specified interrupt in the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt. <sys/intr.h>
Includes
void acknowledge_interrupt (int_id_t id)
Parameters Returns Description
id is the zero-based numeric id of the interrupt. None The acknowledge_interrupt() function acknowledges handling the specified interrupt to the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt. <sys/intr.h>
Includes
Kernel Customization
Xilkernel is highly customizable. As described in previous sections, modules and individual parameters can be changed to suit the user application. The XPS GUI system provides excellent support for easy configuration of parameters of Xilkernel, using the software platform settings dialog. Refer to Chapter 2, “Xilinx Platform Studio (XPS)” in the Embedded Systems Tools Guide for more details. In order to customize a module in the kernel, a parameter with the name of the category set to true must be defined in the MSS. For example, to customize the pthread module,
parameter config_pthread_support = true
is required in the OS specification. Not defining a configurable module’s config_ parameter will mean that the module will be configured out. An MSS snippet for configuring OS Xilkernel for a PPC system is given below:
PARAMETER os_name = xilkernel PARAMETER os_ver = 2.00.a PARAMETER stdin = RS232 PARAMETER stdout = RS232 PARAMETER proc_instance = ppc405_0 PARAMETER linker_script_specification = PARAMETER vec_mem_start = 0xffff0000 PARAMETER vec_mem_size = 16k PARAMETER data_mem_start = 0xffff4000 PARAMETER data_mem_size = 20k PARAMETER code_mem_start = 0xffff9000 PARAMETER code_mem_size = 28k PARAMETER config_process = true PARAMETER sched_type = 2 PARAMETER config_shm = true PARAMETER shm_table = (100)
true
70
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Kernel Customization
R
PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER PARAMETER end
config_msgq = true msgq_capacity = 5 config_sema = true multi_elf_process_table = ((0xf8000000,31)) max_procs = 5 max_readyq = 5 config_pthread_support = true max_pthreads = 5 config_pthread_mutex = true config_malloc = true mem_table = ((4,10), (3,10),(8,10)) pit_interval = 0xffffff copyoutfiles = true copyfromdir = . copytodir = /usr/kernelsrc
The values in the snippet show above are only sample values, targeting a hypothetical board. The configuration directives in the MSS specification have the corresponding implication on memory and code size of the resultant Xilkernel image. This is especially true for kernel allocated structures, whose count can be configured through the MSS. For e.g. The maximum number of process context structures allocated in the kernel is determined by the sum of two parameters; max_procs and max_pthreads. If a process context structures occupies x bytes of bss memory, then the total bss memory requirement for process contexts will be (max_procs + max_pthreads)*x bytes. Therefore, such parameters should be carefully tuned, and the final kernel image should be examined with the GNU size utility to make sure that memory requirements are met. To get an idea of the contribution of each kernel allocated structures memory requirements, please take a look at the corresponding header file. The specification in the MSS gets translated by libgen and the Xilkernel TCL files into C-language configuration directives in two header files os_config.h and config_init.h. Interested users should take a look at these two files, which are generated in the main processor include directory, to get an idea of how the specification gets translated.
Customizing STDIN and STDOUT
The standard input and output peripherals can be configured for Xilkernel. Xilkernel can work without a standard input and output too. These peripherals are the targets of inputoutput API like print, outbyte, inbyte etc.
Table 5-1:
STDIN/STDOUT configuration parameters Description
Instance name of stdin peripheral Instance name of stdout peripheral
Attribute
stdin stdout
Type
string string
Defaults
none none
Customizing User Initialization Routine
A user initialization routine can be optionally invoked as a part of Xilkernel initialization with this parameter. The routine must be named as user_init. Note that the user_init routine should be present within the symbolic scope of the kernel. Therefore, it can be a
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
71
R
Chapter 5: Xilkernel
part of an application that is in the kernel bundle mode. If there are no kernel bundle applications, then it should be in one of the compiled kernel sources.
Table 5-2:
User initialization routine parameters Description
Invoke user_init during system initialization.
Attribute
user_init
Type
boolean
Defaults
false
Customizing Process Management
The user can select the maximum number of processes in the system and the different functions needed to handle processes. The processes and threads that are present in the system on system startup can be configured statically.
Table 5-3:
Process management parameters Attribute Description
Need process management Maximum number of processes in the system Maximum size of Ready queue for each priority Include process_kill() function Include process_kill() function Include process_sleep() function Configure startup processes that are separate executable files. This is defined to be an array with each element containing the parameters process_start and process_prio. Configure startup processes that are a part of the kernel bundle. This is defined to be an array with each element containing the parameters process_start_func, process_prio, and process_stack_size. Process start address Process start function Process priority Size of the process’s stack
Type
boolean numeric numeric boolean boolean boolean
Defaults
true 10 10 false false false
config_process max_procs max_readyq config_process_kill config_process_kill config_process_sleep separate_exec_process_table
array of 2tuples
none
kernel_bundled_process_table
array of 3tuples
none
process_start process_start_func process_prio process_stack_size
address string numeric numeric
none none none none
72
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Kernel Customization
R
Customizing Scheduling
The user can configure the type of scheduler used and the number of priorities used for the Scheduler module. The configurable parameters are given below.
Table 5-4:
Scheduling parameters Description
Configure scheduler module Type of Scheduler to be used. Allowed values
Attribute
config_sched sched_type
Type
boolean
Defaults
true
x 2 - SCHED_RR x 3 - SCHED_PRIO
n_prio Number of priority levels if scheduling is SCHED_PRIO.
numeric
2 (SCHED_RR)
numeric
32
Customizing Thread Management
The user can optionally select to include thread support, the maximum number of threads and size of the thread stack etc. The configurable parameters are given below.
Table 5-5:
Thread module parameters Attribute Description
Need pthread module Maximum number of threads Stack size for dynamically created threads (in bytes) Configure startup threads that are also separate executable files. This is defined to be an array with each element containing the parameters pthread_start and pthread_prio. Configure startup threads that are a part of the kernel bundle. This is defined to be an array with each element containing the parameters pthread_start_func and pthread_prio. Thread start address
Type
boolean numeric numeric
Defaults
false 5 600
config_pthread_support max_pthreads pthread_stack_size separate_exec_pthread_table
array of 2-tuples
none
kernel_bundled_pthread_table
array of 2-tuples
none
pthread_start
address
none
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
73
R
Chapter 5: Xilkernel
Table 5-5:
Thread module parameters Attribute Description
Thread start function Thread priority
Type
string numeric
Defaults
none none
pthread_start_func process_prio
Customizing Semaphore
The user can optionally select to include semaphores, maximum number of semaphores and semaphore queue length. The following are the parameters used for configuration.
Table 5-6:
Semaphore module parameters Description
Need Semaphore module Maximum number of Semaphores Semaphore Wait Queue Length
Attribute
config_sema max_sem max_sem_waitq
Type
boolean numeric numeric
Defaults
false 10 10
Customizing Message Queue
The user can optionally select to include message queue module, number of message queues and the size of each message queue. The message queue module depends on both the semaphore module and the malloc module.The following parameters definitions are used for configuration. Memory for messages must be explicitly specified in the malloc customization.
Table 5-7:
Message queue module parameters Description
Need Message Queue module Number of message queues in the system Maximum number of messages in the queue
Attribute
config_msgq num_msgqs msgq_capacity
Type
boolean numeric numeric
Defaults
false 10 10
Customizing Shared Memory
The user can optionally select to include shared memory and size of each shared memory segment. All the shared memory segments that will ever be needed must be specified in these parameters.The following parameters are used for configuration.
74
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Kernel Customization
R
Table 5-8: Attribute
Shared Memory Module Parameters Description
Need Shared Memory module Shared Memory table. This is defined as an array with each element having shm_size parameter Shared Memory size Number of Shared Memories Size of the shm_table array.
Type
boolean
Defaults
false
config_shm shm_table
array of 1-tuples
none
shm_size num_shm
numeric numeric
none none
Customizing Pthread Mutex
The user can optionally select to include the pthread mutex module, number of mutex locks and the size of the wait queue for the mutex locks.The following parameter are used for configuration.
Table 5-9:
Pthread mutex Module Parameters Attribute Description
Need pthread mutex module Maximum number of pthread mutex locks available in the system. Length of each the mutex lock wait queue.
Type
boolean
Defaults
false
config_pthread_mutex max_pthread_mutex
numeric
5
max_pthread_mutex_ waitq
numeric
10
Customizing Dynamic Block Memory Management
The user can optionally select to include the dynamic block memory management module, size of memory blocks and number of memory blocks. The following parameters are used for configuration.
Table 5-10:
Memory Management module parameters Description
Need Memory Management Memory block table. This is defined as an array with each element having mem_bsize, mem_nblks parameters. Memory block size.
Attribute
config_malloc mem_table
Type
boolean
Defaults
false
array of 2-tuples
none
mem_bsize
numeric
none
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
75
R
Chapter 5: Xilkernel
Table 5-10:
Memory Management module parameters Description
Number of memory blocks of a size Number of memory blocks configurations - Size of mem_table array
Attribute
mem_nblks n_malloc_blocks
Type
numeric
Defaults
none
numeric
none
Customizing Linker Script (PPC405)
Building Xilkernel for PPC requires a linker script to specify the location of the vectors section in the image. The user can customize the default linker script (linker_include.sh and linker_script.sh) files for building PowerPC kernel. If configuring, the user must specify the start address and size of three program sections - vector table, code section and data section. The following parameters are used for configuration.
Table 5-11:
Linker Script Configuration parameters in PPC405 Description
Need Custom Linker Script specification Start address of Vector Table Program section. Size of Vector table section. Specify as xK. Start address of Code section. Size of Code section. Specify as xK. Start address of Data section. Size of Data section. Specify as xK.
Attribute
linker_script_specification vect_mem_start vect_mem_size code_mem_start code_mem_size data_mem_start data_mem_size
Type
boolean address numericsize address numericsize address numericsize
Defaults
false 0x0 9K 0xffffd000 12K 0x2400 9K
76
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Kernel Customization
R
Configuring System Timer
The user can configure the timer device in the system for MicroBlaze kernels. Additionally, he can configure the timer interval for PPC and for MicroBlaze, if the MicroBlaze system includes a PIT timer. The following parameters are used.
Table 5-12:
Attributes for Copying Kernel Source Files Description
A tuple specifying the timer device instance name and the timer type. For example, (system_timer, PIT). PIT and FIT are the only supported timer type strings. Specify the count down interval for the PIT timer in PPC and the PIT timer in MicroBlaze, if so configured.
Attribute
systmr_spec (MicroBlaze only)
Type
Defaults
2-tuple of (string, string)
null
pit_interval
numeric
0xffffff
Configuring Interrupt Handling
The user can configure the interrupt controller device in the system kernels. Adding this parameter, automatically configures multiple interrupt support and the user-level interrupt handling API in the kernel. The following parameters are used.
Table 5-13:
Attributes for Copying Kernel Source files Description
Specify the instance name of the interrupt controller device connected to the external interrupt port.
Attribute
sysintc_spec
Type
Defaults
string
null
Configuring Debug Messages
The user can configure that the kernel outputs debug/diagnostic messages through its execution flow. Enabling the following parameters makes available the DBG_PRINT macro and subsequently its output to the standard output device.
Attribute
debug_mode
Description
Turn on debug messages from the kernel.
Type
boolean
Defaults
false
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
77
R
Chapter 5: Xilkernel
Copy Kernel Source Files
The user can copy the configured kernel source files to his repository for further editing and using them for building the kernel. The following parameters are used.
Table 5-14:
Attributes for Copying Kernel Source files Description
Need to Copy source files The Kernel source directory path. The path is relative to <project_direc>/<systemname>/ libsrc/xilkernel_v2_00_a/src directory User repository directory. The path is relative to <project_direc>/<systemname>/ libsrc/xilkernel_v2_00_a/src directory
Attribute
copyoutfiles copyfromdir
Type
boolean
Defaults
false
path string
“.”
copytodir
path string
"../../../copyof lib"
Debugging Xilkernel
In kernel bundled executable mode, there is a single file that can serve as the target for debugging. Therefore all kernel bundled user applications can be debugged together using GDB. However this is not the case for separate executable mode. Therefore, separate executable applications can currently, not be debugged with XMD and GDB.
Memory Footprint
The size of Xilkernel depends on the user configuration. It is small in size and can fit in different configurations. The following is the memory size output from GNU size utility for the kernel. The image for the PPC version of Xilkernel includes the code for the exception and interrupt vectors, which is by design entitled to occupy 8 Kb of text space. Therefore the text sizes reported below include this 8 Kb of vector code space. Xilkernel has been tested with the GCC optimization flag of -O2, These numbers below are also from the same optimization level.
Table 5-15:
User Configuration and Xilkernel Size MicroBlaze (in Kb)
~4.4K ~4.5
Configuration
Barebones kernel Basic kernel functionality with only multi-processing (no threads)
PPC (in Kb)
~12.4 ~12.5
78
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Xilkernel File Organization
R
Table 5-15:
User Configuration and Xilkernel Size MicroBlaze (in Kb)
~7.4
Configuration
Basic kernel functionality with multi-tasking and multi-threading. Full kernel functionality with all modules (processes,
threads, support for both separate and kernel bundled applications, IPC, synchronization constructs, malloc, interrupt handling, drivers for interrupt controller and timer)
PPC (in Kb)
~15.7
~19.3
24.1
Xilkernel File Organization
Xilkernel sources are organized in the following manner. The root level contains the data and the src folders. The data folder contains the MLD and the TCL files, that determine the configuration of Xilkernel. The src folder contains all the sources. src has a sub-folder src, which contains non-header source files, categorized into arch, sys and ipc folders. arch contains architecture specific sources, while sys contains system-level sources. ipc contains all the sources implementing the IPC functionality. The header files are contained under the include folder of the top-level src folder. The header files are also organized in a way similar to src. There is also a test folder, that contains internal test cases that can be used to get an idea of how Xilkernel functionality can be used.
System Initialization
The entry point for the kernel is the main() routine defined in main.c. The first action performed is hardware specific initialization. This includes registering the interrupt handlers and configuring the system timer. This portion of the initialization depends upon the kind of hardware that is present in the system. Interrupts/exceptions are not enabled after completing hw_init(). If the user has required user_init() to be invoked as a part of the system initialization, then user_init() is invoked next (This applies only if the user_init routine is within the symbolic scope of the rest of the kernel). The sys_init() routine is entered next. This routine performs initialization of each module such as processes, threads, etc. Specifically, it initializes the following things, in order. 1. 2. 3. 4. 5. 6. 7. 8. 9. Internal process context structures Ready queues Pthread module Semaphore module Message Queue module Shared memory module Memory allocation module Idle task creation Static separate executable process creation
10. Static kernel bundled process creation
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
79
R
Chapter 5: Xilkernel
11. Static separate executable pthread creation 12. Static kernel bundled pthread creation After these steps, interrupts and exceptions are enabled and the kernel loops infinitely (blocks), enabling the scheduler to start scheduling a process.
Limitations
Xilkernel currently has the following limitations.
x x x x
The PPC xilkernel image size is contributed significantly (8 Kb) to by the exception vector code. In general, Xilkernel can be further optimized for size. Timer support is not complete in both versions of Xilkernel. POSIX error reporting structure is not fully complete. Therefore, the errno feature is not supported in the POSIX calls. There is restriction on rescheduling tasks within an interrupt handler (described in earlier sections). This means that usage of semaphores, mutex locks, message queues and creating or manipulating processes and threads cannot occur within interrupt handlers.
Future Enhancements
Apart from overcoming the above limitations, future enhancements will focus on supporting the following features.
x x x x x x x
Memory protection (with some hardware support). Better memory allocation and memory mapping functionality. Preventing priority inversion with priority inheritance. Supporting debugging of separate executable applications with GDB. Alarms and Timers. Migrating to POSIX scheduling schemes (SCHED_FIFO and SCHED_RR schemes in a common priority based implementation). POSIX signals.
Modifying Xilkernel
Users can further customize Xilkernel by changing the actual code base. To work with a custom copy of Xilkernel, users first copy the Xilkernel source folder (xilkernel_v2_00_a) from within the EDK installation and place it under the bsp folder of the project folder. For example, <..../myproject/bsp/xilkernel_v2_00_a>. Libgen now picks up this source folder of Xilkernel for compilation, since it looks for Xilkernel sources first under the bsp folder before picking it up from the standard installation. Refer to “Xilkernel File Organization” for more information on the organization of the Xilkernel sources. Xilkernel sources have been written in an elementary and intuitive style and include comment blocks above each significant function. Each source file also carries a comment block indicating its role.
User Guide
Refer to the “Using Xilkernel” chapter in the Platform Studio User Guide for detailed steps on configuring and using Xilkernel. Information on how to develop, build, and download
80
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
User Guide
R
applications is also present in that chapter. Some example systems and applications are illustrated. These design examples illustrate all the features of Xilkernel and therefore will be very useful for users who would like to quickly get started with Xilkernel.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
81
R
Chapter 5: Xilkernel
82
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 6
LibXil Net
This chapter describes the network library for Embedded processors, libXilNet. The library includes functions to support the TCP/IP stack and the higher level application programming interface (Socket APIs). The chapter contains the following sections.
x x x x x x x x x
“Overview” “LibXilNet Functions” “Protocols Supported” “Library Architecture” “Protocol Function Description” “Current Restrictions” “Functions of LibXilNet” “LibGen Customization” “Using XilNet in Application”
Overview
The Embedded Development Kit (EDK) networking library, libXilNet, allows a processor to connect to the internet. LibXilNet includes functions for handling the TCP/IP stack protocols. It also provides a simple set of Sockets Application Programming Interface (APIs) functions enabling network programming. Lib Xil Net supports multiple connections (through Sockets interface) and hence enables multiple client support. This chapter describes the various functions of LibXilNet.
LibXilNet Functions
Quick Glance
Table 6-1 presents a list of functions provided by the LibXilNet at a glance.
Table 6-1:
LibXilNet functions at a glance Functions
int xilsock_init (void) void xilsock_rel_socket (int sd) int xilsock_socket (int domain, int type, int proto)
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
83
R
Chapter 6: LibXil Net
Table 6-1:
LibXilNet functions at a glance Functions
int xilsock_bind (int sd, struct sockaddr* addr, int addrlen) int xilsock_listen (int sd, int backlog) int xilsock_accept (int sd, struct sockaddr* addr, int* addrlen) int xilsock_recvfrom (int s, unsigned char* buf, unsigned int len, struct sockaddr* from, unsigned int* fromlen) int xilsock_sendto (int s, unsigned char* buf, int len, struct sockaddr* to, unsigned int tolen) int xilsock_recv (int s, unsigned char* buf, unsigned int len) int xilsock_send (int s, unsigned char* buf, unsigned int len) void xilsock_close (int s) void xilnet_mac_init (unsigned int baseaddr) int xilnet_eth_find_old_entry(void) void xilnet_eth_init_hw_addr(unsigned char *addr) int xilnet_eth_recv_frame (unsigned char* frame, int len) int xilnet_eth_send_frame (unsigned char* frame, int len, void* daddr, unsigned short type) void xilnet_eth_update_hw_tbl (unsigned char* frame, int proto) void xilnet_eth_add_hw_tbl_entry (unsigned char* ip, unsigned char* hw) int xilnet_eth_get_hw_addr (unsigned char* ip) int xilnet_eth_init_hw_addr_tbl (void) int xilnet_arp (unsigned char* buf, int len) void xilnet_arp_reply (unsigned char* buf, int len) void xilnet_ip_init (unsigned char* ip_addr) int xilnet_ip (unsigned char* buf, int len) void xilnet_ip_header (unsigned char* buf, int len, int proto, unsigned char* peer_ip_addr) unsigned short xilnet_ip_calc_chksum (unsigned char* buf, int len) int xilnet_udp (unsigned char* buf, int len) void xilnet_udp_header (struct xilnet_udp_conn* conn, unsigned char* buf, int len) unsigned short xilnet_tcp_udp_calc_chksum (unsigned char* buf, int len, unsigned char* saddr, unsigned char* daddr, unsigned short proto)
84
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Protocols Supported
R
Table 6-1:
LibXilNet functions at a glance Functions
void xilnet_udp_init_conns (void) int xilnet_udp_open_conn (unsigned short port) int xilnet_udp_close_conn (struct xilnet_udp_conn* conn) int xilnet_tcp (unsigned char* buf, int len) void xilnet_tcp_header (struct xilnet_tcp_conn* conn, unsigned char* buf, int len, unsigned char flags) void xilnet_tcp_send_pkt (struct xilnet_tcp_conn* conn, unsigned char* buf, int len, unsigned char flags) void xilnet_tcp_init_conns (void) int xilnet_tcp_open_conn (unsigned short port) int xilnet_tcp_close_conn (struct xilnet_tcp_conn* conn) int xilnet_icmp (unsigned char* buf, int len) void xilnet_icmp_echo_reply (usigned char* buf, unsigned int len)
Protocols Supported
LibXilNet supports drivers and functions for the Sockets API and protocols of TCP/IP stack. The following list enumerates them.
x x x x x x x
Ethernet Encapsulation (RFC 894) Address Resolution Protocol (ARP - RFC 826) Internet Protocol (IP - RFC 791) Internet Control Management Protocol (ICMP - RFC 792) Transmission Control Protocol (TCP - RFC 793) User Datagram Protocol (UDP - RFC 768) Sockets API
Library Architecture
Figure 6-1 gives the architecture of libXilNet. Higher Level applications like HTTP server, TFTP (Trivial File Transfer Protocol), PING etc., uses API functions to use the libXilNet library
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
85
R
Chapter 6: LibXil Net
PING Application
HTTP Server Application
TFTP Application
Xilinx Sockets Interface Demultiplexing based on connections
ICMP
TCP
UDP
ARP
IP
Demultiplexing based on protocal value in IP Header
Demultiplexing based on frame type in Ethernet Header Ethernet Driver Incoming Frame MAC Driver
From PHY Interface LibXilNet Architecture
UG111_07_111903
Figure 6-1:
Schematic Diagram of LibXilNet Architecture
86
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Protocol Function Description
R
Protocol Function Description
A detailed description of the drivers and the protocols supported is given below.
Media Access Layer (MAC) Drivers Wrapper
MAC drivers wrapper initializes the base address of the mac instance specified by the user.This base address is used to send and receive frames. This initialization must be done before using other functionalites of LibXil Net library. The details of the function prototype is defined in the section“Functions of LibXilNet.”
Ethernet Drivers
Ethernet drivers perform the encapsulation/removal of ethernet headers on the payload in accordance with the RFC 894. Based on the type of payload (IP or ARP), the drivers call the corresponding protocol callback function. A Hardware Address Table is maintained for mapping 48-bits ethernet address to 32-bits IP address.
ARP (RFC 826)
Functions are provided for handling ARP requests. An ARP request (for the 48-bit hardware address) is acknowledged with the 48-bit ethernet address in the ARP reply. Currently, ARP request generation for a desired IP address is not supported. The Hardware address table is updated with the new IP/Ethernet address pair if the ARP request is destined for the processor.
IP (RFC 791)
IPv4 datagrams are used by the higher level protocols like ICMP, TCP, and UDP for receiving/sending data. A callback function is provided for ethernet drivers which is invoked whenever there is an IP datagram as a payload in an ethernet frame. Minimal processing of the source IP address check is performed before the corresponding higher level protocol (ICMP, TCP, UDP) is called. Checksum is calculated on all the outgoing IP datagrams before calling the ethernet callback function for sending the data. An IP address for a Embedded Processor needs to be programmed before using it for communication. An IP address initializing function is provided. Refer to the table describing the various routines for further details on the function. Currently no IP fragmentation is performed on the outgoing datagrams. The Hardware address table is updated with the new IP/Ethernet address pair if an IP packet was destined for the processor.
ICMP (RFC 792)
ICMP functions handling only the echo requests (ping requests) are provided. Echo requests are issued as per the appropriate requirements of the RFC (Requests For Comments).
UDP (RFC 768)
UDP is a connectionless protocol. The UDP callback function, called from the IP layer, performs the minimal check of source port and strips off the UDP header. It demultiplexes from the various open UDP connections. A UDP connection can be opened with a given source port number through Socket functions. Checksum calculation is performed on the
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
87
R
Chapter 6: LibXil Net
outgoing UDP datagram. The number of UDP connections that can be supported simultaneously is configurable.
TCP (RFC 793)
TCP is a connection-oriented protocol. Callback functions are provided for sending and receiving TCP packets. TCP maintains connections as a finite state machine. On receiving a TCP packet, minimal check of source port correctness is done, before demultiplexing the TCP packet from the various TCP connections. Necessary action for the demultiplexed connection is taken based on the current machine state. A status flag is returned to indicate the kind of TCP packet received to support connection management. Connection management has to be done at the application level using the status flag received from TCP. Checksum is calculated on all outgoing TCP packets. The number of TCP connections that can be supported simultaneously is configurable.
Sockets API
Functions for creating sockets (TCP/UDP), managing sockets, sending and receiving data on UDP and TCP sockets are provided. High level network applications need to use these functions for performing data communication. Refer to Table 6-1 for further details.
Buffer Management
XiNet stack is geared to work with smaller FPGA devices and hence minimal buffer management is provided. The stack uses two global buffers - sendbuf, recvbuf - to send and receive ethernet frames. User code can either allocate a buffer or use sendbuf to send packets from the application. When sendbuf is used to transmit packets, user code is responsible to place the application data at the right offset from start of sendbuf accounting for all layers of stack starting from ethernet header.
Current Restrictions
Certain restrictions apply to the EDK libXilNet library software. These are
x x x
Only server functionalities for ARP - This means ARP requests are not being generated from the processor Only server functionalities in libXilNet - This means no client application development support provided in libXilNet. No timers in TCP - Since there are no timers used, every "send" over a TCP connection waits for an "ack" before performing the next "send".
Functions of LibXilNet
The following table gives the list of functions in libXilNet and their descriptions
88
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
int xilsock_init (void) Parameters Returns Description Includes None 1 for success and 0 for failure Initialize the xilinx internal sockets for use. xilsock.h
void xilsock_rel_socket (int sd) Parameters Returns Description Includes sd is the socket to be released. None Free the system level socket given by the socket descriptor sd xilsock.h
int xilsock_socket (int domain, int type, int proto) Parameters domain: Socket Domain type: Socket Type proto: Protocol Family Returns On success, return socket descriptor On failure, return -1 Description Create a socket of type, domain and protocol proto and returns the socket descriptor. The type of sockets can be: SOCK_STREAM (TCP socket) SOCK_DGRAM (UDP socket) domain value currently is AF_INET proto refers to the protocol family which is typically the same as the domain. Includes xilsock.h
int xilsock_bind (int sd, struct sockaddr* addr, int addrlen) Parameters sd: Socket descriptor addr: Pointer to socket structure addrlen: Size of the socket structure Returns On success, return 1 On failure, return -1 Description Bind socket given the descriptor sd to the ip address/port number pair given in structure pointed to by addr of len addrlen. addr is the typical socket structure. xilsock.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
89
R
Chapter 6: LibXil Net
int xilsock_accept (int sd, struct sockaddr* addr, int *addrlen) Parameters sd: Socket descriptor addr: Pointer to socket structure addrlen: Pointer to the size of the socket structure Returns On success, return socket descriptor On failure, return -1 Description Accepts new connections on socket sd. If a new connection request arrives, it creates a new socket nsd, copies properties of sd to nsd, returns nsd. If a packet arrives for an existing connection, returns 0 and sets the xilsock_status_flag global variable. The various values of the is flag are: XILSOCK_NEW_CONN XILSOCK_CLOSE_CONN XILSOCK_TCP_ACK for new connection, closed a connection and acknowledgment for data sent for a connection correspondingly. This function implicitly polls/waits on a packet from MAC. Arguments addr and addrlen are in place to support the standard Socket accept function signature. At present, they are not used in the accept function. Includes xilsock.h
int xilsock_recvfrom (int s, unsigned char* buf, int len) Parameters s: UDP socket descriptor buf: Buffer to receive data len: Buffer size Returns Number of bytes received Receives data (maximum length of len) from the UDP socket s in buf and returns the number of bytes received. xilsock.h
Description Includes
int xilsock_sendto (int s, unsigned char* buf, int len) Parameters s: UDP socket descriptor buf: Buffer containing data to be sent len: Buffer size Returns Description Includes Number of bytes received Sends data of length len in buf on the UDP socket s and returns the number of bytes sent. xilsock.h
90
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
int xilsock_recv (int s, unsigned char* buf, int len) Parameters s: TCP socket descriptor buf: Buffer to receive data len: Buffer size Returns Description Includes Number of bytes received Receives data (maximum length of len) from the TCP socket s in buf and returns the number of bytes received. xilsock.h
int xilsock_send (int s, unsigned char* buf, int len) Parameters s: TCP socket descriptor buf: Buffer containing data to be sent len: Buffer size Returns Description Includes Number of bytes received Sends data of length len in buf on the UDP socket s and returns the number of bytes sent. xilsock.h
void xilsock_close (int s) Parameters Returns Description s: socket descriptor None Closes the socket connection given by the descriptor s. This function has to be called from the application for a smooth termination of the connection after a connection is done with the communication. xilsock.h
Includes
void xilnet_mac_init (unsigned int baseaddr) Parameters Returns Description baseaddr: Base address of the MAC instance used in a system None Initialize the MAC base address used in the libXil Net library to baseaddr. This function has to be called at the start of a user program with the base address used in the MHS file for ethernet before starting to use other functions of libXil Net library. mac.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
91
R
Chapter 6: LibXil Net
void xilnet_eth_init_hw_addr (unsigned char* addr) Parameters Returns Description addr: 48-bit colon separated hexa decimal ethernet address string None Initialize the source ethernet address used in the libXil Net library to addr. This function has to be called at the start of a user program with a 48-bit, colon separated, hexa decimal ethernet address string for source ethernet address before starting to use other functions of libXil Net library. This address will be used as the source ethernet address in all the ethernet frames. xilsock.h mac.h int xilnet_eth_recv_frame (unsigned char* frame, int len) Parameters frame: Buffer for receiving an ethernet frame len: Buffer size Returns Description Number of bytes received Receives an ethernet frame from the MAC, strips the ethernet header and calls either ip or arp callback function based on frame type. This function is called from accept /receive socket functions. The function receives a frame of maximum length len in buffer frame. xilsock.h mac.h void xilnet_eth_send_frame (unsigned char* frame, int len, unsigned char* dipaddr, void *dhaddr, unsigned short type) Parameters frame: Buffer for sending a ethernet frame len: Buffer size dipaddr: Pointer to the destination ip address dhaddr: Pointer to the destination ethernet address type: Ethernet Frame type (IP or ARP) Returns Description None Creates an ethernet header for payload frame of length len, with destination ethernet address dhaddr, and frame type, type. Sends the ethernet frame to the MAC. This function is called from receive/send (both versions) socket functions. xilsock.h mac.h
Includes
Includes
Includes
92
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
void xilnet_eth_update_hw_tbl (unsigned char* frame, int proto) Parameters frame: Buffer containing an ethernet frame proto: Ethernet Frame type (IP or ARP) Returns Description None Updates the hardware address table with ipaddress/hardware address pair from the ethernet frame pointed to by frame. proto is used in identifying the frame (ip/arp) to get the ip address from the ip/arp packet., xilsock.h mac.h void xilnet_eth_add_hw_tbl_entry (unsigned char* ip, unsigned char* hw) Parameters ip: Buffer contains ip address hw: Buffer containing hardware address Returns Description Includes None Add an ip/hardware pair entry given by ip/hw into the hardware address table xilsock.h mac.h int xilnet_eth_get_hw_addr (unsigned char* ip) Parameters Returns Description ip: Buffer containing ip address Index of entry in the hardware address table that matches the ip address Receives an ethernet frame from the MAC, strips the ethernet header and calls either ip or arp callback function based on the frame type. This function is called from accept /receive socket functions. The function receives a frame of maximum length len in buffer frame. xilsock.h mac.h
Includes
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
93
R
Chapter 6: LibXil Net
void xilnet_eth_init_hw_addr_tbl (void) Parameters Returns Description Includes None None Initializes Hardware Address Table. This function must be called in the user program before using other functions of LibXilNet. xilsock.h mac.h int xilnet_arp (unsigned char* buf, int len) Parameters buf: Buffer for holding the ARP packet len: Buffer size Returns Description 0 This is the arp callback function. It gets called by the ethernet driver for arp frame type. The arp packet is copied onto the buf of length len. xilsock.h
Includes
void xilnet_arp_reply (unsigned char* buf, int len) Parameters buf: Buffer containing the ARP reply packet len: Buffer size Returns Description None This function sends the arp reply, present in buf of length len, for arp requests. It gets called from the arp callback function for arp requests. xilsock.h
Includes
void xilnet_ip_init (unsigned char* ip_addr) Parameters Returns Description ip_addr: Array of four bytes holding the ip address to be configured None This function initializes the ip address for the processor to the address represented in ip_addr as a dotted decimal string. This function must be called in the application before any communication. xilsock.h
Includes
94
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
int xilnet_ip (unsigned char* buf, int len) Parameters buf: Buffer for holding the IP packet len: Buffer size Returns Description 0 This is the ip callback function. It gets called by the ethernet driver for ip frame type. The ip packet is copied onto the buf of length len. This function calls in the appropriate protocol callback function based on the protocol type. xilsock.h
Includes
void xilnet_ip_header (unsigned char* buf, int len, int proto) Parameters buf: Buffer for the ip packet len: Length of the ip packet proto: Protocol Type in IP packet Returns Description None This function fills in the ip header from the start of buf. The ip packet is of length len and proto is used to fill in the protocol field of ip header. This function is called from the receive/send (both versions) functions. xilsock.h
Includes
unsigned short xilnet_ip_calc_chksum (unsigned char* buf, int len, int proto) Parameters buf: Buffer containing ip packet len: Length of the ip packet Returns Description checksum calculated for the given ip packet This function calculates the checksum for the ip packet buf of length len. This function is called from the ip header creation function. xilsock.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
95
R
Chapter 6: LibXil Net
int xilnet_udp (unsigned char* buf, int len) Parameters buf: Buffer containing the UDP packet len: Length of the UDP packet Returns Description Length of the data if packet is destined for any open UDP connections else returns 0 This is the udp callback function which is called when ip receives a udp packet. This function checks for a valid udp port, strips the udp header, and demultiplexes from the various UDP connections to select the right connection. xilsock.h
Includes
void xilnet_udp_header (struct xilnet_udp_conn conn, unsigned char* buf, int len) Parameters conn: UDP connection buf: Buffer containing udp packet len: Length of udp packet Description This function fills in the udp header from the start of buf for the UDP connection conn. The udp packet is of length len. This function is called from the receivefrom/sendto socket functions. xilsock.h
Includes
unsigned short xilnet_udp_tcp_calc_chksum (unsigned char* buf, int len, unsigned char* saddr, unsigned char* daddr, unsigned short proto) Parameters buf: Buffer containing UDP/TCP packet len: Length of udp/tcp packet saddr: IP address of the source daddr: Destination IP address proto: Protocol Type (UDP or TCP) Returns the Returns Description Checksum calculated for the given udp/tcp packet This function calculates and fills the checksum for the udp/tcp packet buf of length len. The source ip address (saddr), destination ip address(daddr) and protocol (proto) are used in the checksum calculation for creating the pseudo header. This function is called from either the udp header or the tcp header creation function. xilsock.h
Includes
96
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Functions of LibXilNet
R
void xilnet_udp_init_conns (void ) Parameters Returns Description Includes None None Initialize all UDP connections so that the states of all the connections specify that they are usable. xilsock.h
int xilnet_udp_open_conn (unsigned short port) Parameters Returns Description Includes port: UDP port number Connection index if able to open a connection. If not returns -1. Open a UDP connection with port number port. xilsock.h
int xilnet_udp_close_conn (struct xilnet_udp_conn *conn) Parameters Returns Description Includes conn: UDP connection 1 if able to close else returns -1. Close a UDP connection conn. xilsock.h
int xilnet_tcp (unsigned char* buf, int len) Parameters buf: Buffer containing the TCP packet len: Length of the TCP packet Returns Description A status flag based on the state of the connection for which the packet has been received This is the tcp callback function which is called when ip receives a tcp packet. This function checks for a valid tcp port and strips the tcp header. It maintains a finite state machine for all TCP connections. It demultiplexes from existing TCP open/listening connections and performs an action corresponding to the state of the connection. It returns a status flag which identifies the type of TCP packet received (data or ack or fin). xilsock.h
Includes
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
97
R
Chapter 6: LibXil Net
void xilnet_tcp_header (struct xilnet_tcp_conn conn, unsigned char* buf, int len) Parameters conn: TCP connection buf: Buffer containing tcp packet len: Length of tcp packet Returns Description None This function fills in the tcp header from the start of buf for the TCP connection conn. The tcp packet is of length len. It sets the flags in the tcp header. xilsock.h
Includes
void xilnet_tcp_send_pkt (struct xilnet_tcp_conn conn, unsigned char* buf, int len, unsigned char flags) Parameters conn: TCP connection buf: Buffer containing TCP packet len: Length of tcp packet Returns Description Includes The checksum calculated for the given udp/tcp packet This function sends a tcp packet, given by buf of length len, with flags (ack/rst/fin/urg/psh) from connection conn. xilsock.h
void xilnet_tcp_init_conns (void ) Parameters Returns Description Includes None None Initialize all TCP connections so that the states of all the connections specify that they are usable. xilsock.h
int xilnet_tcp_open_conn (unsigned short port) Parameters Returns Description Includes port: TCP port number Connection index if able to open a connection. If not returns -1. Open a TCP connection with port number port. xilsock.h
98
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
LibGen Customization
R
int xilnet_tcp_close_conn (struct xilnet_tcp_conn *conn) Parameters Returns Description Includes conn: TCP connection 1 if able to close else returns -1. Close a TCP connection conn. xilsock.h
int xilnet_icmp (unsigned char* buf, int len) Parameters buf: Buffer containing ICMP packet len: Length of the ICMP packet Returns Description 0 This is the icmp callback function which is called when ip receives a icmp echo request packet (ping request). This function checks only for a echo request and sends in an icmp echo reply. xilsock.h
Includes
void xilnet_icmp_echo_reply (unsigned char* buf, int len) Parameters buf: Buffer containing ICMP echo reply packet len: Length of the ICMP echo reply packet Returns Description None This functions fills in the icmp header from the start of buf. The icmp packet is of length len. It sends the icmp echo reply by calling the ip, ethernet send functions. This function is called from the icmp callback function. xilsock.h
Includes
LibGen Customization
XilNet library is customized through LibGen tool. Here is a snippet from system.mss file for specifying LibXilNet.
BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilnet PARAMETER LIBRARY_VER = 1.00.a PARAMETER device_type = ethernet PARAMETER emac_type = emac END
LibXilNet has the infrastructure to support different networking devices. The parameter device_type can take - ethernet, serial, host as values. Currently however ethernet is the device type that has been tested. With ethernet device type, LibXilNet can be used with either the regular ethernet core or the lite version, ethernetlite.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
99
R
Chapter 6: LibXil Net
The parameter emac_type can take - emac, emaclite as values. This configures XilNet to be used with either Emac of EmacLite driver.
Table 6-2:
Configurable Parameters for XilNet in MSS Description
Networking Device type used in the system Possible values are ethernet, serial, host. Type of ethernet core used. Possible values are emac, emaclite
Parameter
device_type emac_type
Using XilNet in Application
Libgen generates a configuration file xilnet_config.h based on the parameter selection in MSS file. In order to use the XilNet functions in your application, you need to do the following:
x x
Define “#include <net/xilnet_config.h>” in your C-file. Define “#include <net/xilsock.h>” in your C-file.
100
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 7
LibXil File
Xilinx libraries provide block access to file systems and devices using standard calls such as open, close, read, and write. These routines form the LibXil File module of the libraries. A system can be configured to use the LibXil File module, using the Library Generator (libgen). This chapter contains the following sections.
x x x x x
“Overview” “Module Usage” “Module Routines” “Libgen Support” “Limitations”
Overview
The LibXil library provides block access to files and devices through the LibXil File module. This module provides standard routines such as open, close, read, and write to access file systems and devices. The module LibXil File can also be easily modified to incorporate additional file systems and devices. This module implements a subset of operating system level functions.
Module Usage
A file or a device is opened for read and write using the open call in the library. The library maintains a list of open files and devices. Read and write commands can be issued to access blocks of data from the open files and devices.
Module Routines
Functions
int open (const char *name, int flags, int mode) int close (int fd) int read (int fd, char* buf, int nbytes) int write (int fd, char* buf, int nbytes)
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
101
R
Chapter 7: LibXil File
Functions
long lseek (int fd, long offset, int whence) int chdir (const char *buf) const char* getcwd (void) int open (const char *name, int flags, int mode) Parameters name refers to the name of the device/file. flags refers to the permissions of the file. This field does not have any meaning for a device. mode indicates whether the stream is opened in read, write or append mode. Returns Description file/device descriptor fd assigned by LibXil File This call registers the device or the file in the local device table and calls the underlying open function for that particular file or a device. xilfile.h xparameters.h int close (int fd) Parameters Returns fd refers to the file descriptor assigned during by open() If a file is being closed, returns the status returned by the underlying file system. For devices, it returns 1, since devices can not be closed. 0 indicates success in closing a file. Any other value indicates error Description Includes Close the file/device with the fd. xilfile.h xparameters.h int read (int fd, char* buf, int nbytes) Parameters fd refers to the file descriptor assigned by open() buf refers to the destination buffer where the contents of the stream should be copied nbytes: Number of bytes to be copied Returns Description Includes The number of bytes read. Read nbytes from the file/device pointed by the file descriptor fd and store it in the destination pointed by buf. xilfile.h xparameters.h
Includes
102
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Module Routines
R
int write (int fd, char* buf, int nbytes) Parameters fd: refers to the file descriptor assigned by open() buf: refers to the source buffer nbytes: Number of bytes to be copied Returns Description Includes The number of bytes written to the file. Write nbytes from the buffer, buf to the file pointed by the file descriptor fd xilfile.h xparameters.h long lseek (int fd, long offset, int whence) Parameters fd: file descriptor returned by open offset: Number of bytes to seek whence: Location to seek from. This parameter depends on the underlying File System being used. Returns Description Includes New file pointer location The lseek() system call moves the file pointer for fd by offset bytes from whence. xilfile.h xparameters.h int chdir (char* newdir) Parameters Returns Description Includes newdir: Destination directory The same value as returned by the underlying file system. -1 for failure. Change the current directory to newdir xilfile.h xparameters.h const char* getcwd (void) Parameters Returns Description Includes None The current working directory. Get the absolute path for the current working directory. xilfile.h xparameters.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
103
R
Chapter 7: LibXil File
Libgen Support
LibXil File Instantiation
The users can write application to either interact directly with the underlying file systems and devices or make use of the LibXil File module to integrate with file systems and devices. In order to instantiate LibXil File module in your system, use the following code in your MSS file.
BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilfile PARAMETER LIBRARY_VER = 1.00.a PARAMETER peripherals = ( ("<peripheral 1 instance name>", "<mount 1>") , ("<peripheral 2 instance name>", "<mount 2>") ) PARAMETER filesys = (( "<Filesystem 1 name>" , "<mount 1>" ), ( "<Filesystem 2 name>" , "<mount 2>" )) END
where
i i i
<peripheral 1 name> : Instance name of the peripheral you need to access through XilFile. <mount 1> : Mount name for the <peripheral 1> or <filesystem 1> <filesystem 1 name> : Name of the filesystem, you need to access through XilFile.
(1)
For example, to access two uarts ( myuart1 and myuart2) and the memory file system ( xilmfs ) , use the following code snippet.
BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilfile PARAMETER LIBRARY_VER = 1.00.a PARAMETER peripherals = ( ("myuart", "/dev/myuart") , ("myuart2", "/dev/myuart2") ) PARAMETER filesys = (( "xilmfs" , "/dev/mfs" )) END
System Initialization
LibGen also generates the system initialization file, which is compiled into the LibXil library. This file initialized the data structure required by the LibXil File module, such as the Device tables and the File System table. This routine also initializes STDIN, STDOUT and STDERR, if present.
Limitations
LibXil File module currently enforces the following restrictions:
1. Note that there is no instance name for filesystem and other Xilinx Microkernel modules. Hence, the name of the filesystem should be used instead of the instance name.
104
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Limitations
R
x x x x
Only one instance of a File System can be mounted. This file system and the mount point has to be indicated in the Microprocessor Software Specification (MSS) file. Files cannot have names starting with /dev, since it is a reserved word to be used only for accessing devices. Currently LibXil File has support only for 1 file system (LibXil Memory File System) and 3 devices (UART, UARTlite and GPIO). Only devices can be assigned as STDIN, STDOUT and STDERR.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
105
R
Chapter 7: LibXil File
106
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 8
LibXil FATFile System (FATfs)
This chapter describes the XilFatfs FATfile system access library. This library provides read/write access to files stored on a Xilinx SystemAce compact flash or microdrive device. The chapter contains the following sections.
x x x
“Overview” “XilFatfs Functions” “LibGen Customization”
Overview
The XilFatfs filesystem access library provides read/write access to files stored on a Xilinx SystemACE CompactFlash or IBM microdrive device. This library requires the underlying hardware platform to contain all of the following:
x x x
OPB SYSACE Interface Controller - Logicore module SystemACE controller and CompactFlash connector 128MB or 256MB CompactFlash card formatted with a FAT16, FAT12 or FAT32 file system or an IBM microdrive formatted with a FAT16, FAT12 or FAT32 file system
Caution! FAT16 is required for SystemACE to directly configure the FPGA but the XilFatfs
library can work with the SystemACE hardware to support FAT12 and FAT32 as well.
See the documentation on OPB SYSACE Interface Controller in the Processor IP Reference Guide for more details on the hardware. If this library is to be used in a MicroBlaze system, and speed is of concern, it is recommended that the MicroBlaze processor be configured to include a hardware barrel shifter. See the MicroBlaze documentation for more information on including the barrel shifter. Users can easily copy files to the flash device from their PC by plugging the flash or microdrive into a suitable USB adapter or similar device.
XilFatfs Functions
This section presents a list of functions provided by the XilFatfs. Table 8-1 provides the function names with signature at a glance.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
107
R
Chapter 8: LibXil FATFile System (FATfs)
Table 8-1:
XilFatfs Functions at a Glance Functions
void *sysace_fopen (const char *file, const char *mode) int sysace_fread (void *buffer, int size, int count, void *stream) int sysace_fwrite (void *buffer, int size, int count, void *stream) int sysace_fclose (void *stream) void *sysace_mkdir (const char *path) void *sysace_chdir (const char *path)
Detailed Description of XilFatfsFunctions
void *sysace_fopen (const char *file, const char *mode)
Parameters file is the name of the file on the flash device. address is the starting(base) address of the file system memory mode is restricted to “r” in this version Returns A non zero file handle on success 0 for failure Description The file name should follow the Microsoft 8.3 naming standard with a file name of up to 8 characters, followed by a ‘.’ and a 3 character extension. In this version of the library, the 3 character extension is mandatory so a sample file might be called test.txt This function returns a file handle that has to be used for subsequent calls to read or close the file If the named file does not exist on the device 0 is returned Includes sysace_stdio.h
108
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
XilFatfs Functions
R
int sysace_fread (void *buffer, int size, int count, void *stream) Parameters buffer is a pre allocated buffer that is passed in to this procedure, and is used to return the characters read from the device size is restricted to 1 count is the number of characters to be read stream is the file handle returned by sysace_fopen Returns Non zero number of characters actually read, for success 0 for failure Description The preallocated buffer is filled with the characters that are read from the device. The return value indicates the actual number of characters read, while count specifies the maximum number of characters to read. The buffer size must be at least count. stream should be a valid file handle returned by a call to sysace_fopen. sysace_stdio.h
Includes
int sysace_fwrite (void *buffer, int size, int count, void *stream) Parameters buffer is a pre allocated buffer that is passed in to this procedure, and contains the characters to be written to the device size is restricted to 1 count is the number of characters to be written stream is the file handle returned by sysace_fopen Returns Non zero number of characters actually written, for success 0 or -1 for failure Description The preallocated buffer is filled (by the caller) with the characters that are to be written to the device. The return value indicates the actual number of characters written, while count specifies the maximum number of characters to write. The buffer size must be at least count. stream should be a valid file handle returned by a call to sysace_fopen. sysace_stdio.h
Includes
int sysace_fclose (void *stream) Parameters Returns stream: File handle returned by sysace_fopen 1 On success 0 On failure Description Includes Closes an open file sysace_stdio.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
109
R
Chapter 8: LibXil FATFile System (FATfs)
int sysace_mkdir (const char *path) Parameters Returns path: path name of new directory 0 On success -1On failure Description Create a new directory specified by path. The directory name can be either absolute or relative, and must follow the 8.3 file naming convention. Examples: a:\\dirname, a:\\dirname.dir, a:\\dir1\\dirnew, dirname, dirname.dir If a relative path is specified, and the current working directory is not already set, the current working directory defaults to the root directory. Includes sysace_stdio.h
int sysace_chdir (const char *path) Parameters Returns path: path name of new directory 0 On success -1On failure Description Create a new directory specified by path. The directory name can be either absolute or relative, and must follow the 8.3 file naming convention. Examples: a:\\dirname, a:\\dirname.dir, a:\\dir1\\dirnew, dirname, dirname.dir If a relative path is specified, and the current working directory is not already set, the current working directory defaults to the root directory. Includes sysace_stdio.h
LibGen Customization
XilFatfs file system can be integrated with a system using the following snippet in the mss file. There are
BEGIN LIBRARY parameter LIBRARY_NAME = xilfatfs parameter LIBRARY_VER = 1.10.a # The following 3 parameters are optional and their default value is ‘n’ parameter CONFIG_WRITE = y parameter CONFIG_DIR_SUPPORT = y parameter CONFIG_FAT12 = y END
The CONFIG_WRITE parameter when set to ‘y’, adds write capabilities to the library.
110
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
LibGen Customization
R
The CONFIG_DIR_SUPPORT parameter when set to ‘y’, adds the mkdir and chdir functions to the library. The CONFIG_FAT12 parameter when set to ‘y’ configures the library to work with FAT12 file systems. Otherwise the library works with both FAT16 and FAT32 file systems.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
111
R
Chapter 8: LibXil FATFile System (FATfs)
112
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 9
LibXil Memory File System (MFS)
This chapter describes the Memory File System (MFS). This file system resides in RAM/ROM/Flash memory and can be accessed through the LibXil File module or directly. The Memory File System is integrated with a system using the Library Generator. The chapter contains the following sections.
x x x x x x
“Overview” “MFS Functions” “Utility Functions” “Additional Utilities” “C-like access” “LibGen Customization”
Overview
The Memory File System (MFS) component, LibXil MFS, provides users the capability to manage program memory in the form of file handles. Users can create directories, and can have files within each directory. The file system can be accessed from the high level C-language through function calls specific to the file system. Alternatively, users can also manage files through the standard C language functions like open provided in XilFile.
MFS Functions
Quick Glance
This section presents a list of functions provided by the MFS. Table 9-1 provides the function names with signature at a glance.
Table 9-1:
MFS Functions at a Glance Functions
void mfs_init_fs (int numbytes, char *address, int status) int mfs_change_dir (char *newdir) int mfs_get_current_dir_name (char *dirname) int mfs_create_dir (char *newdir) int mfs_delete_dir (char *newdir)
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
113
R
Chapter 9: LibXil Memory File System (MFS)
Table 9-1:
MFS Functions at a Glance Functions
int mfs_exists_file (char *filename) int mfs_delete_file (char *filename) int mfs_rename_file (char *from_file, char *to_file) int mfs_get_usage(int *num_blocks_used, int *num_blocks_free) int mfs_dir_open (char *dirname) int mfs_dir_close (int fd) int mfs_dir_read (int fd, char **filename, int *filesize, int *filetype) int mfs_file_open (char *filename, int mode) int mfs_file_read (int fd, char *buf, int buflen) int mfs_file_write (int fd, char *buf, int buflen) int mfs_file_close(int fd) long mfs_file_lseek (int fd, long offset, int whence) int mfs_ls (void) int mfs_cat (char *filename) int mfs_copy_stdin_to_file (char *filename) int mfs_file_copy (char *from_file, char *to_file)
114
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
MFS Functions
R
Detailed summary of MFS Functions
int mfs_init_fs (int numbytes, char *address, int status) Parameters numbytes is the number of bytes of memory available for the file system address is the starting(base) address of the file system memory status is one of MFSINIT_NEW, MFSINIT_IMAGE or MFSINIT_ROM_IMAGE
Returns
1 for success 0 for failure
Description
Initialize the memory file system. This function must be called before any file system operation. The status/mode parameter determines certain filesystem properties: MFSINIT_NEW creates a new, empty file system for read/write MFSINIT_IMAGE initializes a filesystem whose data has been previously loaded into memory at the base address MFSINIT_ROM_IMAGE initializes a Read-Only filesystem whose data has been previously loaded into memory at the base address
Includes
xilmfs.h
int mfs_change_dir (char *newdir) Parameters Returns newdir is the chdir destination. 1 for success 0 for failure Description Includes If newdir exists, make it the current directory of MFS. Current directory is not modified in case of failure. xilmfs.h
int mfs_create_dir (char *newdir) Parameters Returns newdir: Directory name to be created On success, return index of new directory in the file system On failure, return 0 Description Includes Create a new empty directory called newdir inside the current directory. xilmfs.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
115
R
Chapter 9: LibXil Memory File System (MFS)
int mfs_delete_dir (char *dirname) Parameters Returns dirname: Directory to be deleted On success, return index of new directory in the file system On failure, return 0 Description Includes Delete the directory dirname, if it exists and is empty, xilmfs.h
int mfs_get_current_dir_name (char *dirname) Parameters Returns dirname: Current directory name is returned in this pointer On Success return 0 On failure return 1 Description Return the name of the current directory in a pre allocated buffer, dirname, of at least 16 chars.Note that it does not return the absolute path name of the current directory, but just the name of the current directory xilmfs.h
Includes
int mfs_delete_file (char *filename) Parameters Returns filename: file to be deleted 1 for success 0 for failure Description Includes Delete filename from its directory. xilmfs.h
int mfs_rename_file (char *from_file, char *to_file) Parameters from_file: Original filename to_file: New file name Returns On success, return 1 On failure, return 0 Description Includes Rename from_file to to_file. Rename works for directories as well as files. Function fails if to_file already exists. xilmfs.h
116
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
MFS Functions
R
int mfs_exists_file (char *filename) Parameters Returns filename: file/directory to be checked for existence 0: if filename does not exist 1: if filename is a file 2: if filename is a directory Description Includes Check if the file/directory is present in current directory. xilmfs.h
int mfs_get_usage (int *num_blocks_used, int *num_blocks_free) Parameters num_blocks_used: Number of blocks used num_blocks_free: Number of free blocks Returns On Success return 0 On failure return 1 Description Includes Get the number of used blocks and the number of free blocks in the file system through pointers. xilmfs.h
int mfs_dir_open (char *dirname) Parameters Returns Description Includes dirname: directory to be opened for reading The index of dirname in the array of open files or -1 on failure. Open directory dirname for reading. Reading a directory is done using mfs_dir_read() xilmfs.h
int mfs_dir_close (int fd) Parameters Returns fd: File descriptor return by open On success return 1 On failure return 1 Description Includes Close the dir pointed by fd. The file system regains the fd and uses it for new files. xilmfs.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
117
R
Chapter 9: LibXil Memory File System (MFS)
int mfs_dir_read (int fd, char **filename, int *filesize, int *filetype) Parameters fd: File descriptor return by open; passed to this function by caller filename: Pointer to file name at the current position in the directory in MFS; this value is filled in by this function filesize: Pointer to a value filled in by this function: Size in bytes of filename, if it is a regular file; Number of directory entries if filename is a directory filetype: Pointer to a value filled in by this function: MFS_BLOCK_TYPE_FILE if filename is a regular file; MFS_BLOCK_TYPE_DIR if filename is a directory Returns On Success return number of bytes read. On Failure return 1 Description Read the current directory entry and advance the internal pointer to the next directory entry. filename, filetype and filesize are pointers to values stored in the current directory entry xilmfs.h
Includes
int mfs_file_open (char *filename, int mode) Parameters filename: file to be opened mode: Read/Write or Create mode. Returns Description The index of filename in the array of open files or -1 on failure. Open file filename with given mode. The function should be used for files and not directories: MODE_READ, no error checking is done (if file or directory). MODE_CREATE creates a file and not a directory. MODE_WRITE fails if the specified file is a DIR. Includes xilmfs.h
int mfs_file_read (int fd, char *buf, int buflen) Parameters fd: File descriptor return by open buf: Destination buffer for the read buflen: Length of the buffer Returns On Success return number of bytes read. On Failure return 1 Description Read buflen number bytes and place it in buf. fd should be a valid index in “open files” array, pointing to a file, not a directory. buf should be a pre-allocated buffer of size buflen or more. If fewer than buflen chars are available then only that many chars are read. xilmfs.h
Includes
118
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
MFS Functions
R
int mfs_file_write (int fd, char *buf, int buflen) Parameters fd: File descriptor return by open buf: Source buffer from where data is read buflen: Length of the buffer Returns On Success return 1 On Failure return 1 Description Write buflen number of bytes from buf to the file. fd should be a valid index in open_files array. buf should be a pre-allocated buffer of size buflen or more. xilmfs.h
Includes
int mfs_file_close (int fd) Parameters Returns fd: File descriptor return by open On success return 1 On failure return 1 Description Includes Close the file pointed by fd. The file system regains the fd and uses it for new files. xilmfs.h
long mfs_file_lseek (int fd, long offset, int whence) Parameters fd: File descriptor return by open offset: Number of bytes to seek whence: File system dependent mode: If whence is MFS_SEEK_END, the offset can be either 0 or negative, otherwise offset should be non-negative. If whence is MFS_SEEK_CURR, the offset is calculated from the current location If whence is MFS_SEEK_SET, the offset is calculated from the start of the file Returns On success, return offset from the beginning of the file to the current location On failure, return -1; the current location is not modified Description Seek to a given offset within the file at location fd in open_files array. It is an error to seek before beginning of file or after the end of file. Includes xilmfs.h
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
119
R
Chapter 9: LibXil Memory File System (MFS)
Utility Functions
The following few functions are utility functions that can be used along with Xilinx MFS. These functions are defined in mfs_filesys_util.c and are not declared in xilmfs.h. They must be declared by the user if needed. int mfs_ls (void) Parameters Returns None On success return 1 On failure return 0 Description Includes List contents of current directory on STDOUT. xilmfs.h
int mfs_cat (char *filename) Parameters Returns filename: File to be displayed On success return 1 On failure return 0 Description Includes Print the file to STDOUT. xilmfs.h
int mfs_copy_stdin_to_file (char *filename) Parameters Returns filename: Destination file. On success return 1 On failure return 0 Description Includes Copy from STDIN to named file. xilmfs.h
int mfs_file_copy (char *from_file, char *to_file) Parameters Returns from_file: Source file to_file: Destination file On success return 1 On failure return 0 Description Includes Copy from_file to to_file. It fails if to_file already exists, or if either could not be opened. xilmfs.h
120
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Additional Utilities
R
Additional Utilities
A program called mfsgen is provided along with the MFS library. mfsgen can be used to create an MFS memory image on a host system that can subsequently be downloaded to the embedded system memory. mfsgen itself links to libXilMFS and is compiled to run on the host machine rather than the target MicroBlaze or PowerPC system. Conceptually, this is similar to the familiar zip or tar programs. The source code for mfsgen is provided in the file mfsgen.c in the utils sub-directory. The executable image should be in the path. An entire directory hierarchy on the host system can be copied to a local MFS file image using mfsgen. This file image can then be downloaded on to the memory of the embedded system for creating a pre-loaded file system. A few test programs are included to show how this is done. More information can be found in the readme.txt file in the utils subdirectory and the “Using XilMFS” chapter in the Platform Studio User Guide. Usage: mfsgen -txcvsbf [mfs_filename] [num_blocks] <filelist> Specify exactly one of c,t,x modes t: list the files in the mfs file system image c: create an mfs file system image using the list of files specified on the command line Directories specified in this list are traversed recursively x: extract the mfs file system from image to host file system v: verbose mode f: specify the host file name (mfs_filename) where the mfs file system image is stored If the f option is specified the mfs filename should be specified If the f option is omitted the default file name is filesystem.mfs
s: switch endianness b: number of blocks - should be more than 2 If the b option is specified the num_blocks value should be specifed If the b option is omitted the default value of num_blocks is 5000 The b option is meaningful only when used in conjunction with the c option
C-like access
The user can choose not to deal with the details of the file system by using the standard Clike interface provided by Xil File. It provides the basic C stdio functions like open, close, read, write, and seek. These functions have identical signature as those in the standard ANSI-C. Thus any program with file operations performed using these functions can be easily ported to MFS by interfacing the MFS in conjunction with library Xilfile.
LibGen Customization
Memory file system can be integrated with a system using the following snippet in the mss file. The memory file system should be instantiated with the name xilmfs. The attributes used by libgen and their descriptions are given in Table 9-2.
BEGIN LIBRARY parameter LIBRARY_NAME = xilmfs parameter LIBRARY_VER = 1.00.a
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
121
R
Chapter 9: LibXil Memory File System (MFS)
parameter parameter parameter parameter END
numbytes= 50000 base_address = 0xffe00000 init_type = MFSINIT_NEW need_utils = false
Table 9-2:
Attributes for including Memory File System Description
Number of bytes allocated for file system. Starting address for file system memory MFSINIT_NEW (default) or MFSINIT_IMAGE or MFSINIT_ROM_IMAGE MFSINIT_NEW creates a new, empty file system MFSINIT_ROM_IMAGE creates a file system based on a preloaded memory image loaded in memory of size numbytes at starting address base_address. This memory is considered readonly and modification of the file system is not allowed. MFS_INIT_IMAGE is similar to the previous option except that the file system can be modified, and the memory is considered to be readable and writeable.
Attributes
numbytes base_address init_type
need_utils
true or false (default = false) If true, this causes stdio.h to be included from mfs_config.h. The functions described in the “Utility Functions” section require stdin or stdout to be defined, and setting need_utils to true causes stdio.h to be included.
Caution! The underlying software and hardware platforms must
support stdin and stdout peripherals for these utility functions to compile and link correctly.
122
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 10
LibXil Profile
This chapter describes the profiling library for embedded processors, libXil Profile. The chapter contains the following sections:
x x x x x x x x
“Overview” “Features” “Profiling Model” “Customizing xilprofile” “Building Applications” “Generating GPROF Files” “XilProfile Code Description” “Limitations”
Overview
Profiling a program running on hardware (board), provides insight into program execution and identifies where it spends most time. Profiling on hardware is faster and the interaction of program with memory and other peripherals can be more accurately captured. LibXil Profile is a software intrusive profile library that generates Call Graph and Histogram information of program running on board. Executing the program on hardware generates the profiling information which is stored on the hardware. XMD generates output file from the data, which can be read by GNU gprof tools (mb-gprof) to generate the profiling information.Profiling is supported for the MicroBlaze processor.
Features
LibXil Profile library has the following features:
x
Provides Histogram (flat profile) and Call Graph information.
i i
Histogram: Shows how much time the program spent in each function and how many times the function was called. Call Graph: Shows for each function, which functions called it, which other functions it called and how many times.
x x
Profiling parameters are configurable - Sampling Frequency, Histogram Bin Size and Timer to use. Memory location and size to store profiling is flexible and configurable based on program requirements.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
123
R
Chapter 10: LibXil Profile
Profiling Model
The libxil profile library, libxilprofile.a is generated and customized for software platform by instantiating the xilprofile library. Running LibGen will create this library. For more details of Profiling flow refer to the “Profiling Embedded Designs” chapter in the Platform Studio User Guide. When the profile option -pg is specified to the compiler (mb-gcc and powerpc-eabi-gcc), this library is automatically linked with the application to profile. The generated executable file contains code to generate profile information. When the program is executed on board, the profile information is stored at the memory location specified by the user. XMD is profile library “aware” and generates the gprof compatible output file based on profile data.
Note: The xilprofile library does not have any explicit application API. The library is linked due to profile calls (_mcount) introduced by gcc for profiling. The are some global variables that need to be set in the application for using the library. This is explained in the later sections.
Customizing xilprofile
The xilprofile library can be customized for an application. Following is the list of PARAMETERS for the library.
Table 10-1:
xilprofile custom PARAMETERS Name Type
int
Defaults
4
Description
For Histogram calculation, the program is divided into equal sized bins. This parameter specifies the bin size in bytes. This depends on function size. Frequency of sampling for histogram calculation. This determines the accuracy of histogram calculation. The opb_timer instance name to use for profiling in the system. If there is no function pointer in the program, xilprofile uses a method which requires less memory. Setting this parameter to TRUE enables this mode of operation.
histogram_binsize
histogram_sample_freq_hz
int
100,000
histogram_timer callgraph_no_funcptr
peripheral instance name boolean
none false
Building Applications
The memory needed for storing profile information is allocated in the user application. The memory can be either an array allocated in program or any memory in the hardware system. The latter gives the flexibility to specify any available memory in the system without changing the program’s size or custom linker script. This memory is specified to xilprofile library by two pointer variables in the application.
x x
char *memstart - Points to start of memory location. char *memend - Points to end of memory location.
124
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Generating GPROF Files
R
Application Memory Requirements
The memory needed for profiling is dependent on the program’s text section size, number of function calls, and presence of function calls. The user can calculate the memory required for profiling by using the TCL file calc_profilemem.tcl Syntax: calc_profilemem.tcl -target <mblaze> -elf <Executable File compiled without pg option> -bin <Histogram BIN Size> Usage: xmd calc_profilemem.tcl -target mblaze -elf executable.elf -bin 4 xilprofile library assumes that the amount of memory allocated is correct and sufficient for the application. This is done to conserve valuable memory. XMD uses the same algorithm to perform memory testing during program download.
Generating GPROF Files
XMD helps in the generation of output files that can be read by GNU gprof tools. XMD does the following functions for profiling. 1. 2. Test if the amount of memory is sufficient for profiling. This test is done when the ELF file is downloaded and is compiled with the -pg option. Read the stored profile information from hardware and generate output files. This is done by the following XMD command. Syntax: profile out [-o <Output gmon filename> If output gmon file is not specified, file gmon.out is generated. Sample Profiling Session using XMD:
Xilinx Microprocessor Debug (XMD) Engine Xilinx EDK 6.2 Build EDK_Gm.8 Copyright (c) 1995-2002 Xilinx, Inc. All rights reserved. XMD% mbconnect mdm JTAG chain configuration -------------------------------------------------Device ID Code IR Length Part Name 1 0124a093 10 XC2VP7 Assuming, Device No: 1 contains the MicroBlaze system Connected to the JTAG MicroBlaze Debug Module (MDM) No of processors = 1 MicroBlaze Configuration : -------------------------Version............................2.00.a No of PC Breakpoints...............4 No of Read Addr/Data Watchpoints...1 No of Write Addr/Data Watchpoints..1 Instruction Cache Support..........off Data Cache Support.................off Connected to MicroBlaze "mdm" target. id = 0 Starting GDB server for "mdm" target (id = 0) at TCP port no 1234 XMD% dow microblaze_0/code/executable.elf **************************************************************** ** Profiling Memory Test ** Executable: microblaze_0/code/executable.elf ** Memory Allocated: 4200
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
125
R
Chapter 10: LibXil Profile
** Profile Type: PROFILE_FUNCPTR ** Histogram BinSize: 4 **************************************************************** Program Text Size........................5232 No. of Func. Calls.......................33 No. of Func. Ptr. Calls..................3 Memory Histogram Tables..................654 Memory Call Graph Tables.................864 Total Profile Memory required............1518[SUCCESS] XMD% bps 0x470 Setting breakpoint at 0x00000470 XMD% con Processor started. Type "stop" to stop processor RUNNING> stop XMD% profile out Processor stopped at PC: 0x0000177c Profile data written to gmon.out XMD%
GNU gprof tool (mb-gprof) tools can be used to read the output file. Refer to the Manual page of gprof for more information on usage.
XilProfile Code Description
XilProfile source code is located at $XILINX_EDK/sw/lib/sw_services/xilprofile_v1_00_a directory. Some of the important functions are:
x
_program_init - This function is called before function main of an application. This function does memory and timer initialization. It allocates memory for histogram (inferred from symbols _ftext and _etext) and call graph based on xilprofile parameters. It initializes the timer routine, registers timer handler accordingly based on timer used and connection to processor and starts the timer. The TCL routine of xilprofile library figures the timer type and connection to processor and generates the #defines. Refer to the “Microprocessor Library Definition (MLD)” chapter in the Embedded System Tools Guide. mcount - This function is called by _mcount function, which is inserted at every function start by gcc. This function records the caller and callee information (Instruction address), which is used to generate call graph information. Based on whether function pointers are present or not, different information is stored. This is done to decrease memory needed for profiling if there are no function pointers in the application. profile_intr_handler - This is the interrupt handler for the profiling timer. The timer is set to sample the executing application for PC values at fixed intervals and increment the Bin count. This is used to generate the histogram information.
x
x
To generate profile output, XMD needs to read xilprofile customization parameters value, profile memory location on the hardware, and actual profile data. XMD does this with the help of global variables in the xilprofile code. The following are the variables used.
x x x x
memstart, memend - determines the profile memory used. binsize - determines the Histogram BIN size used. sample_freq_hz - determines the Sampling Frequency used. profile_no_funcptr - determines the method used for call graph.
126
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Limitations
R
x
_gmonparam - Data stored during profiling and information about the data. Refer profile.h file for more details on this structure.
Limitations
The profiled program (text section) should exist as contiguous memory.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
127
R
Chapter 10: LibXil Profile
128
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
R
Chapter 11
lwIP Library
Overview
This chapter describes the Embedded Development Kit (EDK) port of the third party network library, Light Weight IP (lwIP), for embedded processors. The chapter details the port of the lwIP library for PowerPC and MicroBlaze processors. It contains the following sections:
x x x x x x
“Overview” “PowerPC System” “MicroBlaze System” “Setting Up lwIP in EDK” “Designing an lwIP Application” “Example lwIP Application”
lwIP is an open source implementation of the TCP/IP protocol suite. The lwIP library supports two interfaces - raw API, BSD style Sockets API. EDK has been ported to work with the raw API interface of the library. The features of the lwIP library are :
x x x x x
IP (Internet Protocol) including packet forwarding on multiple interfaces ICMP (Internet Control Message Protocl) UDP (User Datagram Protocol) TCP (Transmission Control Protocol) .Raw API interface support for applications
The raw API provided by lwIP is the lowest level interface of the stack. It has two modes of operation : Event and Callback. The EDK port uses the Callback mode. lwIP stack maintains internal timers for TCP round trip calculations, retransmissions and other TCP facilities. For this purpose, the lwIP timer functions must be called periodically. This is achieved by using the 64-bit hardware timer in PowerPC. For MicroBlaze an external timer is required. The system design involved for both MicroBlaze and PowerPC are discussed in the following sections.
PowerPC System
Figure 11-1 shows an example hardware design of a PowerPC based system for lwIP. The system requires a 10/100 ethernet core for performing the network transactions. The builtin hardware timer is used to call the lwIP timer functions periodically.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
129 Embedded Development Kit
R
Chapter 11: lwIP Library
PLB SDRAM MEMC
OPB 10/100 Ethernet
DSPLB ISPLB INT
BRAM MEMC PPC405 Non-Crit INTC
32 KB BRAM PLB2OPB BRIDGE
UART 16450
GPIO
UG114_11_01_051404
Figure 11-1: PowerPC System Design for lwIP-Based Echo Server
MicroBlaze System
MicroBlaze does not supoprt an in-built timer. An OPB based timer provides the timer functionality. The system uses the OPB based 10/100 regular ethernet core. A diagram of an example MicroBlaze system design is shown in Figure 11-2.
OPB SDRAM MEMC ILMB DLMB 10/100 Ethernet MDM
MICROBLAZE
ILMB DLMB IOPB DOPB Interrupt
GPIO UART 16550 OPB TIMER
UG114_11_02_051404
BRAM MEMC
32K BRAM
BRAM MEMC
Figure 11-2:
MicroBlaze System Design for lwIP-Based Echo Server
130 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Memory Management
R
Memory Management
There are two types of memory management in lwIP; the heap memory (mem) and the static memory pools (memp). The pbuf management is a hybrid since it both manages its own memory (th pbuf pool) and uses the heap (mem). The mem is a heap memory manager, such as the C malloc/free manager. A block of memory is requsted with a call to mem_malloc( ) and the memory is freed with a call to mem_free( ). This is used by code that allocates memory of diffrent sizes. An example is when contents of a packet needs to be copied into a buffer - since the size of the packet isn’t known beforehand, the memory is allocated from the heap. The memp, on the other hand, uses a set of pools of fixed size memory blocks. This is used by the lwIP stack code to allocate predefined memory blocks. An example is for lwIP stack to allocate memory for TCP protocol control blocks. The pbufs are used to hold packet data. These are to be used by a network device driver who needs to allocate buffers quickly. The memory options are defined in lwipopts.h file. The memory options in lwipopts.h are as follows:
Table 11-1:
Memory Option Settings for lwIP Option Name Description
The size of the heap. If the application will send a lot of data that needs to be copied, this should be set high. The number of memp struct pbufs. If the application sends a lot of data out of ROM (or other static memory), this should be set high. The number of UDP protocol control blocks. One per active UDP "connection." The number of simulatenously active TCP connections. The number of listening TCP connections. The number of simultaneously queued TCP segments.
MEM_SIZE
MEMP_NUM_PBUF
MEMP_NUM_UDP_PCB MEMP_NUM_TCP_PCB MEMP_NUM_TCP_PCB_LISTEN MEMP_NUM_TCP_SEG
Setting Up lwIP in EDK
lwIP is customized using the libgen tool. lwIP supports multiple 10/100 ethernet network interfaces. The 48-bit MAC addresses associated with each of the interfaces are given alongwith the ethernet instances used in the MHS file. In order to set up lwIP library in XPS, open the software settings dialog. Select lwip 1.00.a library and click on the Library/OS Parameters tab. Enter the 10/100 ethernet instance names from the MHS file that would be used with the lwIP library. For each of the ethernet instance, a 48-bit MAC address is also specified. The following is an MSS snippet for lwIP library :
BEGIN LIBRARY PARAMETER LIBRARY_NAME = lwip PARAMETER LIBRARY_VER = 1.00.a PARAMETER EMAC_INSTANCES = ((my_opb_ethernet,0x00,0x00,0x00,0x00,0x22,0x38))
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
131 Embedded Development Kit
R
Chapter 11: lwIP Library
END
Running libgen tool in XPS generates liblwip4.a library in <processor_instance_name>/lib directory in the project area. Applications designed with lwIP should link with this library to get the lwIP functionality. To link a library, open the Compiler options for the application and in the Linker Options, set lwip4 as a library to be used for linking.
libgen Customization
lwIP library is customized through libgen tool. Here is a snippet from system.mss file for specifying lwIP library.
BEGIN LIBRARY PARAMETER LIBRARY_NAME = lwip PARAMETER LIBRARY_VER = 1.00.a PARAMETER EMAC_INSTANCES = ((my_opb_ethernet,0x00,0x0A,0x35,0x00,0x22,0x20)) END
lwIP has the infrastructure to support multiple ethernet interfaces. The parameter emac_instances is an array. It takes in the instance name of an ethernet core (specified in the MHS file) and the 48-bit MAC address corresponding to it. This configures lwIP to use a particular ethernet instance with the 48-bit MAC address.
Table 11-2:
Configurable Parameters for lwIP in MSS Parameter Name Description
This is an array with parameters emac_instname and the ethernet addresses.This is a list of ethernet instances that are to be used with lwIP.
emac_instances
emac_instname eth_addr0 eth_addr1 eth_addr2 eth_addr3 eth_addr4 eth_addr5
Name of the ethernet instance from the MHS file First byte of the 6-byte MAC address Second byte of the 6-byte MAC address Third byte of the 6-byte MAC address Fourth byte of the 6-byte MAC address Fifth byte of the 6-byte MAC address Sixth byte of the 6-byte MAC address
Designing an lwIP Application
Software applications using lwIP should follow certain structure. As mentioned in the previous sections, the lwIP stack requires its timer functon to be called periodically. For PowerPC, the in-build timer is used to calculate the time period. In case of MicroBlaze an external timer is used for providing fixed time periods. For more information on lwIP refer : http://savannah.nongu.org/projects/lwip.
132 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Designing an lwIP Application
R
Initializing lwIP
lwIP requires the application to call several initialization routines. The following is a code snippet that illustrates the initialization routines required for lwIP.
/*************************************************************** * CalllwIP Initialization Routines *****************************************************************/ sys_init(); mem_init(); memp_init(); pbuf_init(); netif_init(); tcp_init(); /*************************************************************** * Setup our 1 network interface (netif)*************************************************************** **/ netif = netif_add(&ip_addr, &net_mask, &gw, &XEmacIF_ConfigTable[0], xemacif_init, ip_input); netif_set_default(netif);
An example application is discussed in later sections to illustrate these requirements
lwIP Raw API
The raw API of lwIP is the lowest leve interface to the stack. It is also the most efficient interface because it provides direct access to the stack rather than providing extra buffering and message passing features. The following sections describe the most used interface functions. A more detailed description of the raw API is found in the lwIP source tree ($XILINX_EDK/sw/lib/sw_services/lwip_v1_00_a/src/lwip/doc/rawapi.txt). Asynchronous network events (data received, connection established etc.) are communicated to the application through callback functions. These callbacks are registered during the initialization of the TCP connection using the raw API. Table 6-2 lists the events and associated callback routines.
Table 11-3:
TCP Events, Callbacks, and Hot to Register Callback Events Event Callback
*accept() *sent() *recv()
Register with lwIP
tcp_accept() tcp_sent() tcp_recv()
TCP connection established TCP Data Acknowledged by Remote Host TCP Data Received
The following section, “Raw APO Functions for TCP,” lists a subset of TCP related functions. For a complete list of functions for other protocols, see: ($XILINX_EDK/sw/lib/sw_services/lwip_v1_00_a/src/lwip/doc/rawapi.txt)
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
133 Embedded Development Kit
R
Chapter 11: lwIP Library
Raw APO Functions for TCP
void* tcp_init ()
This function must be called first to initialize the lwIP stack
void tcp_tmr()
This function must be called every TCP_TMR_INTERVAL milliseconds (defined in file lwipopts.h). There are two lower level timer functions which are called inside tcp_tmr( ). The example application calls these functions directly - they are: tcp_slowtmr( ) and tcp_fasttmr( ).
struct tcp_pcb * tcp_new()
tcp_new creates a new TCP Protocol Control Block (PCB) structure. void tcp_arg (struct tcp_pcb* pcb, void* arg) tcp_arg Allows the application to register an argument that will be passed back to the application for all callback functions. This argument, arg, is usually used as a pointer to a structure that holds application state information.
err_t tcp_bind (struct tcp_pcb* pcb, struct ip_addr* ip_addr, u16_t port)
Binds the pcb to an IP address, ip_addr and TCP port number port
struct tcp_pcb* tcp_listen (struct tcp_pcb* pcb)
The tcp_listen function instructs the lwIP stack to put the pcb in listen state. The pcb will start to listen for connections on the IP address and port number specified in tcp_bind. When a new connection is established, lwIP calls the callback application function specified using the tcp_accept function.
void tcp_accept (struct tcp_pcb* pcb, err_t (*accept)(void* arg, struct tcp_pcb* newpcb, err_t err))
The tcp_accept function allows the application to register a callback function, accept. The lwIP stack calls the accept function when a new connection is established on a pcb that is in the listening state.
134 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
err_t tcp_write (struct tcp_pcb* pcb, void* dataptr, u16_t len, u8_t copy)
The tcp_write function will write len bytes of data from dataptr to the transmit queue. The copy argument specifies whether or not the stack should copy the data or reference it using the pointer dataptr.
void tcp_sent (struct tcp_pcb* pcb, err_t (*sent)(void* arg, struct tcp_pcb* tpcb, u16_t len))
The tcp_sent function registers the sent callback function. The lwIP stack calls the sent function when data is acknowledged by the remote host. The len argument indicates the number of bytes acknowledged. Once the bytes are acknowledged, the bytes are removed from the transmit buffer creating more space. This is useful when trying to send large amount of data using lwIP. If the tcp_write function fails because the transmit buffer is full, this callback function allows the application to write additional data once buffer space becomes available.
void tcp_recv (struct tcp_pcb* pcb, err_t (*recv)(void* arg, struct tcp_pcb* tpcb, struct pbuf* p, err_t err))
The tcp_recv function registers the recv callback function. The lwIP stack calls the recv function when new data arrives on the connection. The p argument is NULL when the connection is closed.
Example lwIP Application
The following is a simple TCP based echo server application. The echo server is listening for connections on port 7, and echoes the data sent by the client. The following sections discuss the application run on both PowerPC and MicroBlaze.
PowerPC based Echo Server
The hardware system for the example is shown in Figure 11-1. Assign drivers to each of these peripherals. Select lwip library as shown before and configure the library with the ethernet instance name and the 6-byte MAC address. The lwip library, liblwip4.a, gets generated in <PROCESSOR_INSTANCE_NAME>/lib/ directory once libgen is run.
C Program
The application is split among the following C and headerf files.
FileName : echo_main.c
/* . . * XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
135 Embedded Development Kit
R
Chapter 11: lwIP Library
. . . . . . . . . . . . .
* XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION * * * * * * * * * * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. *
* (c) Copyright 2002, 2003 Xilinx, Inc. * All rights reserved. * */
/* . * Copyright (c) 2001, 2002, 2003 Swedish Institute of Computer Science. . * All rights reserved. *
. * Redistribution and use in source and binary forms, with or without . * modification, are permitted provided that the following conditions . * are met: * . * 1. Redistributions of source code must retain the above copyrightnotice, . * this list of conditions and the following disclaimer.
. * 2. Redistributions in binary form must reproduce the above copyright notice, . * this list of conditions and the following disclaimer in the documentation . * and/or other materials provided with the distribution.
. * 3. The name of the author may not be used to endorse or promoteproducts . * derived from this software without specific prior written
permission. * . * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS OR . * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES
136 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN . * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,INCIDENTAL, . * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOTLIMITED . * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR . * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF . * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING . * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS . * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */
/* Xilinx Includes */ #include "xuartns550_l.h" #include "xtime_l.h" #include "xparameters.h" #include "xcache_l.h" #include "xgpio_l.h" /* lwIP Includes */ #include "netif/xemacif.h" #include "lwip/tcp.h" #include "lwip/memp.h" #include "netif/etharp.h" #include "echo.h" #define UART_BASEADDR XPAR_MYUART_16550_BASEADDR #define UART_CLOCK (XPAR_XUARTNS550_CLOCK_HZ) #define UART_BAUDRATE (115200) #define LWIP_TIMER_CYCLES (XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ / 1000 \ * TCP_TMR_INTERVAL ) // Upper 6 bytes of MAC #define XILINX_MAC_OUI0 #define XILINX_MAC_OUI1 #define XILINX_MAC_OUI2
- Xilinx Ethernet OUI = 00-0A-35 0x00 0x00 0x00
static void show_dotted_decimal( char * address_array); static void show_dashed_hex( int bytes, char *address_array); // Static Global Variables static u8_t my_timer = 0; // External Global Variables /* defined in lwip/src/core/tcp.c */ extern u32_t tcp_ticks;
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
137 Embedded Development Kit
R
Chapter 11: lwIP Library
/* defined in EDK generated xemacif_g.c file */ extern XEmacIf_Config XEmacIf_ConfigTable[]; /*------------------------------------------------------------------*/ * show dotted decimal prints a dotted decimal address to the UART*-----------------------------------------------------------------*/ static void show_dotted_decimal( char *address_array) { int bb; char temp; for(bb=0;bb<4;bb++) { temp = address_array[bb]; if(bb!=0) xil_printf("."); xil_printf("%d", (int) temp); } } /*------------------------------------------------------------------*/ /* show dashed hex prints a dashed hex address to the UART */ /*------------------------------------------------------------------*/ static void show_dashed_hex( int bytes, char *address_array) { //Assumes the caller passes the correct number of bytes int bb; for(bb=0;bb<bytes;bb++) { if(bb !=0) xil_printf("-"); xil_printf("%02X", (int) address_array[bb]); } } /*------------------------------------------------------------------*/ /* my_tmr - Called Periodically to dispatch TCP and ARP timers */ /*------------------------------------------------------------------*/ void my_tmr(void) { ++my_timer; if(my_timer == 10) { my_timer = 0; } if(my_timer & 1) { /* Call tcp_fasttmr() every 2 ms, i.e., * every other timer my_tmr() is called. */
138 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
tcp_fasttmr(); } if(my_timer == 0 || my_timer == 5) { /* Call tcp_slowtmr() every 5 ms, i.e., * every fifth timer my_tmr() is called. */ tcp_slowtmr(); if (tcp_ticks%2000 == 0) /* Call etharp_tmr() every 20th call to tcp_slowtmr(). * tcp_ticks is a global var defined in core/tcp.c */ etharp_tmr(); } } /*------------------------------------------------------------------*/ /* print_app_header - prints the legal header */ /*------------------------------------------------------------------*/ void print_app_header() { xil_printf("\n\n\n\n\n\n\n\n\n"); xil_printf("########################################################## ########## \n"); xil_printf("# Xilinx TCP/IP Demo Application (ECHO Server) #\n"); xil_printf("# \n"); xil_printf("# XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION ’AS IS’ #\n"); xil_printf("# SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR # \n"); xil_printf("# XILINX DEVICES. # \n"); xil_printf("# # \n"); xil_printf("# (c) Copyright 2003, 2003 Xilinx, Inc. # \n"); xil_printf("# All rights reserved. # \n"); xil_printf("# # \n"); xil_printf("########################################################## ########## \n"); } /*------------------------------------------------------------------*/ /* main function */ /*------------------------------------------------------------------*/ int main_main ()
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
139 Embedded Development Kit
R
Chapter 11: lwIP Library
{ struct tcp_pcb *gddpp_pcb; struct ip_addr ipaddr, netmask, gw; struct netif *default_netif; char menu_select = 0; XTime ml_base, ml_new, ml_offset; int waiting_for_timer = 1; char low_mac[3] = {0x00,0x22,0x38}; char fullmac[6] = {XILINX_MAC_OUI0, XILINX_MAC_OUI1, XILINX_MAC_OUI2, low_mac[0], low_mac[2], low_mac[3]}; char ip[4] = {149,199,6,108}; char subnet[4] = {255,255,255,0}; char gateway[4] = {149,199,6,254}; unsigned int init_wait = 15000000; /*---------------------------------------------------------------* Uart Init* *---------------------------------------------------------------*/ /* Disable Interrupts */ XIo_Out8(UART_BASEADDR + XUN_LCR_OFFSET, 0UL); XIo_Out8(UART_BASEADDR + XUN_IER_OFFSET, 0UL); /* Clear Latches */ XIo_In8(UART_BASEADDR + XUN_LSR_OFFSET); XIo_In8(UART_BASEADDR + XUN_IIR_OFFSET); XIo_In8(UART_BASEADDR + XUN_MSR_OFFSET); /* Disable FIFOs (16450) */ XIo_Out8(UART_BASEADDR + XUN_FCR_OFFSET, 0UL); /* Normal ABQ level 0 driver inits */ XUartNs550_SetBaud(UART_BASEADDR, UART_CLOCK, UART_BAUDRATE); XUartNs550_mSetLineControlReg(UART_BASEADDR, XUN_LCR_8_DATA_BITS); /* Sets DTR, RTS, and OUT2 in the MCR */ XIo_Out8(UART_BASEADDR + XUN_MCR_OFFSET, XUN_MCR_OUT_2 | XUN_MCR_RTS | XUN_MCR_DTR); xil_printf("\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n"); xil_printf("Starting Up... \n"); xil_printf("Console: 16550 initialized. \n"); /*---------------------------------------------------------------*/ /* Timer Inits */ /*---------------------------------------------------------------*/ ml_offset = LWIP_TIMER_CYCLES;
140 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
/*---------------------------------------------------------------*/ /* Do LWIP System Inits */ /*---------------------------------------------------------------*/ #ifdef STATS stats_init(); #endif /* STATS */ xil_printf("Initializing Memory Structures."); sys_init(); mem_init(); xil_printf("."); memp_init(); xil_printf("."); pbuf_init(); xil_printf(" done. \n"); // clear UART Receive Buffer while (XUartNs550_mIsReceiveData(UART_BASEADDR)) { XUartNs550_RecvByte(UART_BASEADDR); } // set GPIO I/O Mask XGpio_mSetDataDirection(XPAR_MYGPIO_BASEADDR, 0x00000FFF); // Turn on 4 LEDs (Active Low) XGpio_mSetDataReg(XPAR_MYGPIO_BASEADDR, 0x00000000); /*---------------------------------------------------------------*/ /* Initial Header and Menus. Do this before the netif_init() so */ /* we can change the MAC Address and IP addresses if needed */ /*---------------------------------------------------------------*/ while(init_wait--); print_app_header(); fullmac[0] = XILINX_MAC_OUI0; fullmac[1] = XILINX_MAC_OUI1; fullmac[2] = XILINX_MAC_OUI2; fullmac[3] = low_mac[0]; fullmac[4] = low_mac[1]; fullmac[5] = low_mac[2]; /*---------------------------------------------------------------*/ /* Set host addresses */ /*---------------------------------------------------------------*/ xemacif_setmac(0, (u8_t *) fullmac); //Set MAC IP4_ADDR(&gw, gateway[0],gateway[1],gateway[2],gateway[3]); //Set gateway IP4_ADDR(&ipaddr, ip[0],ip[1],ip[2],ip[3]); //Set ip IP4_ADDR(&netmask,subnet[0],subnet[1],subnet[2],subnet[3]); //Set subnet msk /*---------------------------------------------------------------*/ /* Show some host boot stuff and parameters */ /*---------------------------------------------------------------*/
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
141 Embedded Development Kit
R
Chapter 11: lwIP Library
xil_printf(" \nStarting Network Interface... \n"); xil_printf(" MAC Address: "); show_dashed_hex(6, fullmac); xil_printf(" \n"); xil_printf(" IP Address: "); show_dotted_decimal(ip); xil_printf(" \n"); xil_printf(" Subnet Mask: "); show_dotted_decimal(subnet); xil_printf(" \n"); xil_printf(" Gateway IP: "); show_dotted_decimal(gateway); xil_printf(" \n"); xil_printf(" Echo Port: 7 \n"); /*---------------------------------------------------------------*/ /* Initialize netif */ /*---------------------------------------------------------------*/ netif_init(); /*---------------------------------------------------------------*/ /* Initialize TCP Stack */ /*---------------------------------------------------------------*/ tcp_init(); /*---------------------------------------------------------------*/ /* Set up the lwIP network interface... */ /*---------------------------------------------------------------*/ default_netif = netif_add(&ipaddr, &netmask, &gw, &XEmacIf_ConfigTable[0], xemacif_init, ip_input ); netif_set_default(default_netif); /*---------------------------------------------------------------*/ /* create new tcp pcb and start applications */ /*---------------------------------------------------------------*/ // Start the Server xil_printf("Echo Server Running ... "); xil_printf("
142 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
\n"); echo_init(); // Get the current Time-Base Register Value // offset it by ml_offset XTime_SetTime(0); XTime_GetTime(&ml_base); ml_base += ml_offset; while (1) { while (waiting_for_timer) { xemacif_input(default_netif); XTime_GetTime(&ml_new); if ( ml_new >= ml_base ) { waiting_for_timer = 0; ml_base = ml_new + ml_offset; } } // Call my_tmr() every ml_offset cycles my_tmr(); waiting_for_timer = 1; } return (1); } int main () { /*---------------------------------------------------------------*/ /* Enable instruction and data cache -this must be done first because */ /* the Memec Design Virtex-II Dev Boards (rev1 and rev2) have the SDRAM */ /* byte enables tied together on the board. Enabling the caches */ /* guarantees that all memory accesses are 32-bit aligned. */ /*---------------------------------------------------------------*/ XCache_EnableICache(0x80000001); XCache_EnableDCache(0x80000001); return main_main(); }
FileName : echo.c
/* . . * Copyright (c) 2001-2003 Swedish Institute of Computer Science. * All rights reserved. *
. * Redistribution and use in source and binary forms, with or withoutmodification,
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
143 Embedded Development Kit
R
Chapter 11: lwIP Library
.
* are permitted provided that the following conditions are met: *
. * 1. Redistributions of source code must retain the above copyrightnotice, . * this list of conditions and the following disclaimer.
. * 2. Redistributions in binary form must reproduce the above copyright notice, . * this list of conditions and the following disclaimer in the documentation . * and/or other materials provided with the distribution.
. * 3. The name of the author may not be used to endorse or promoteproducts . * derived from this software without specific prior written
permission. * . * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS OR IMPLIED . * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF . * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT . * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,SPECIAL, . * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT . * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ORBUSINESS . * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN . * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OROTHERWISE) ARISING . * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THEPOSSIBILITY . . . * */ * OF SUCH DAMAGE. * * This file is part of the lwIP TCP/IP stack. * * Author: Adam Dunkels <[email protected]>
144 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
#include #include #include #include #include
"lwip/debug.h" "lwip/stats.h" "lwip/tcp.h" "xparameters.h" "echo.h"
struct echo_state { struct pbuf *p; u8_t failed; #define FAILED_MAX 8 }; /*------------------------------------------------------------------*/ static void echo_err(void *arg, err_t err) { struct echo_state *es = arg; xil_printf("echo_err \n"); if(arg != NULL) { pbuf_free(es->p); mem_free(arg); } } /*------------------------------------------------------------------*/ static void close_conn(struct tcp_pcb *pcb, struct echo_state *es) { tcp_arg(pcb, NULL); tcp_sent(pcb, NULL); tcp_recv(pcb, NULL); if(es != NULL) { pbuf_free(es->p); mem_free(es); } tcp_close(pcb); xil_printf("Connection Closed \n"); } /*------------------------------------------------------------------*/ static void send_buf(struct tcp_pcb *pcb, struct echo_state *es) { struct pbuf *q; do { q = es->p; es->p = pbuf_dechain(q); if(tcp_write(pcb, q->payload, q->len, 1) == ERR_MEM) {
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
145 Embedded Development Kit
R
Chapter 11: lwIP Library
pbuf_chain(q, es->p); es->p = q; return; } tcp_recved(pcb, q->len); pbuf_free(q); } while(es->p != NULL); } /*------------------------------------------------------------------*/ static err_t echo_poll(void *arg, struct tcp_pcb *pcb) { struct echo_state *es; if(arg == NULL) { return tcp_close(pcb); } es = arg; if(es->failed >= FAILED_MAX) { close_conn(pcb, es); tcp_abort(pcb); return ERR_ABRT; } if(es->p != NULL) { ++es->failed; send_buf(pcb, es); } return ERR_OK; } /*------------------------------------------------------------------*/ static err_t echo_sent(void *arg, struct tcp_pcb *pcb, u16_t len) { struct echo_state *es; es = arg; if(es != NULL && es->p != NULL) { send_buf(pcb, es); } return ERR_OK; } /*------------------------------------------------------------------*/ static err_t echo_recv(void *arg, struct tcp_pcb *pcb, struct pbuf *p, err_t err) {
146 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
struct echo_state *es; es = arg; if(p == NULL) { close_conn(pcb, es); return ERR_OK; } if(es->p != NULL) { pbuf_chain(es->p, p); } else { es->p = p; } send_buf(pcb, es); return ERR_OK; } /*------------------------------------------------------------------*/ static err_t echo_accept(void *arg, struct tcp_pcb *pcb, err_t err) { struct echo_state *es; tcp_setprio(pcb, TCP_PRIO_MIN); /* Allocate memory for the structure that holds the state of the connection. */ es = mem_malloc(sizeof(struct echo_state)); if(es == NULL) { xil_printf("could not malloc memory for echo_state \n"); return ERR_MEM; } /* Initialize the structure. */ es->p = NULL; es->failed = 0; /* Tell TCP that this is the structure we wish to be passed for our callbacks. */ tcp_arg(pcb, es); /* Tell TCP that we wish to be informed of incoming data by a call to the http_recv() function. */ tcp_recv(pcb, echo_recv); tcp_err(pcb, echo_err); tcp_poll(pcb, echo_poll, 1); xil_printf("Connection Established \n");
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
147 Embedded Development Kit
R
Chapter 11: lwIP Library
return ERR_OK; } /*------------------------------------------------------------------*/ void echo_init(void) { struct tcp_pcb *pcb; pcb = tcp_new(); tcp_bind(pcb, IP_ADDR_ANY, ECHO_PORT); pcb = tcp_listen(pcb); tcp_accept(pcb, echo_accept); } /*------------------------------------------------------------------*/
FileName : echo.h
#ifndef LWIP_ECHO_H #define LWIP_ECHO_H #define ECHO_PORT 7 void echo_init(void); #endif
Linker script
The linker script used with the above example. /********************************************************************* * . . . . . . * XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR * XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION * OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS * IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,
. * AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE . . . . * FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY * WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE * IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR * REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF
148 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
. . * . . *
* INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * FOR A PARTICULAR PURPOSE.
* (c) Copyright 2003 Xilinx, Inc. * All rights reserved.
*********************************************************************/ _STACK_SIZE = 1024k; _HEAP_SIZE = 1024k; MEMORY { sdram : ORIGIN = 0x00000000, LENGTH = 32M bram : ORIGIN = 0xFFFF8000, LENGTH = 32K - 4 boot : ORIGIN = 0xfffffffc, LENGTH = 4 } STARTUP(boot.o) ENTRY(_boot) GROUP(libxil.a libc.a) SECTIONS { .vectors : { *(.vectors) } > sdram .text : { *(.text) } > sdram .data : { *(.data) *(.got2) *(.rodata) *(.fixup) } > sdram /* small data area (read/write): keep together! */ .sdata : { *(.sdata) } > sdram .sbss : { . = ALIGN(4); *(.sbss) . = ALIGN(4);
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
149 Embedded Development Kit
R
Chapter 11: lwIP Library
} > sdram __sbss_start = ADDR(.sbss); __sbss_end = ADDR(.sbss) + SIZEOF(.sbss); /* small data area 2 (read only) */ .sdata2 : { *(.sdata2) } > sdram .bss : { . = ALIGN(4); *(.bss) *(COMMON) . = ALIGN(4); __bss_end = .; /* add stack and align to 16 byte boundary */ . = . + _STACK_SIZE; . = ALIGN(16); __stack = .; _heap_start = .; . = . + _HEAP_SIZE; . = ALIGN(16); _heap_end = .; } > sdram __bss_start = ADDR(.bss); .boot0 : { *(.boot0) _end = .; } > sdram .boot : { *(.boot) } > boot }
MicroBlaze-Based Echo Server
The hardware system for the example is shown in Figure 11-2. Assign drivers to each of these peripherals. Select lwip library as shown before and configure the library with the ethernet instance name and the 6-byte MAC address. The lwip library, liblwip4.a, gets generated in <PROCESSOR_INSTANCE_NAME>/lib/ directory once libgen is run.
C Program
The application is split among the following C and headerf files.
FileName : echo_main.c
/*
150 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
. . . . . . . . . . . . . . .
* XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR * XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION * * * * * * * * * * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. *
* (c) Copyright 2002, 2003 Xilinx, Inc. * All rights reserved. * */
/* . * Copyright (c) 2001, 2002, 2003 Swedish Institute of Computer Science. . * All rights reserved. *
. * Redistribution and use in source and binary forms, with or without . * modification, are permitted provided that the following conditions . * are met: * . * 1. Redistributions of source code must retain the above copyrightnotice, . * this list of conditions and the following disclaimer.
. * 2. Redistributions in binary form must reproduce the above copyright notice, . * this list of conditions and the following disclaimer in the documentation . * and/or other materials provided with the distribution.
. * 3. The name of the author may not be used to endorse or promoteproducts . * derived from this software without specific prior written
permission. * . * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS OR . * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
151 Embedded Development Kit
R
Chapter 11: lwIP Library
. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN . * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,INCIDENTAL, . * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOTLIMITED . * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR . * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF . * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING . * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS . * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */
/* Xilinx Includes */ #include "xuartns550_l.h" #include "xparameters.h" #include "xgpio_l.h" #include "xtmrctr_l.h" /* lwIP Includes */ #include "netif/xemacif.h" #include "lwip/tcp.h" #include "lwip/memp.h" #include "netif/etharp.h" #include "echo.h" #define UART_BASEADDR XPAR_MYUART_16550_BASEADDR #define UART_CLOCK (XPAR_XUARTNS550_CLOCK_HZ) #define UART_BAUDRATE (115200) #define LWIP_TIMER_CYCLES (XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ / 1000 \ * TCP_TMR_INTERVAL ) // Upper 6 bytes of MAC #define XILINX_MAC_OUI0 #define XILINX_MAC_OUI1 #define XILINX_MAC_OUI2
- Xilinx Ethernet OUI = 00-0A-35 0x00 0x00 0x00
static void show_dotted_decimal( char * address_array); static void show_dashed_hex( int bytes, char *address_array); // Static Global Variables static u8_t my_timer = 0; static int waiting_for_timer = 1; /* defined in lwip/src/core/tcp.c */ extern u32_t tcp_ticks;
152 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
/* defined in EDK generated xemacif_g.c file */ extern XEmacIf_Config XEmacIf_ConfigTable[]; /*------------------------------------------------------------------*/ // show dotted decimal prints a dotted decimal address to the UART /*------------------------------------------------------------------*/ static void show_dotted_decimal( char *address_array) { int bb; unsigned char temp; for(bb=0;bb<4;bb++) { temp = address_array[bb]; if(bb!=0) xil_printf("."); xil_printf("%d", temp); } } /*------------------------------------------------------------------*/ /* show dashed hex prints a dashed hex address to the UART */ /*------------------------------------------------------------------*/ static void show_dashed_hex( int bytes, char *address_array) { //Assumes the caller passes the correct number of bytes int bb; for(bb=0;bb<bytes;bb++) { if(bb !=0) xil_printf("-"); xil_printf("%02X", (int) address_array[bb]); } } /*------------------------------------------------------------------*/ /* my_tmr - Called Periodically to dispatch TCP and ARP timers */ /*------------------------------------------------------------------*/ void my_tmr(void) { ++my_timer; if(my_timer == 10) { my_timer = 0; } if(my_timer & 1) { /* Call tcp_fasttmr() every 2 ms, i.e., * every other timer my_tmr() is called. */ tcp_fasttmr(); }
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
153 Embedded Development Kit
R
Chapter 11: lwIP Library
if(my_timer == 0 || my_timer == 5) { /* Call tcp_slowtmr() every 5 ms, i.e., * every fifth timer my_tmr() is called. */ tcp_slowtmr(); if (tcp_ticks%2000 == 0) /* Call etharp_tmr() every 20th call to tcp_slowtmr(). * tcp_ticks is a global var defined in core/tcp.c */ etharp_tmr(); } } /*------------------------------------------------------------------*/ /* print_app_header - prints the legal header */ /*------------------------------------------------------------------*/ void print_app_header() { xil_printf("\n\n\n\n\n\n\n\n \n"); xil_printf("########################################################## ########## \n"); xil_printf("# Xilinx TCP/IP Demo Application (ECHO Server) # \n"); xil_printf("# # \n"); xil_printf("# XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION ’AS IS’ # \n"); xil_printf("# # \n"); xil_printf("# # \n"); xil_printf("# \n"); xil_printf("# # \n"); xil_printf("# # \n"); xil_printf("# \n");
SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR
XILINX DEVICES.
# (c) Copyright 2003, 2003 Xilinx, Inc.
All rights reserved.
#
xil_printf("########################################################## ########## \n");
154 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
} /*------------------------------------------------------------------*/ /* main function */ /*------------------------------------------------------------------*/ int main_main () { struct tcp_pcb *gddpp_pcb; struct ip_addr ipaddr, netmask, gw; struct netif *default_netif; char menu_select = 0; char low_mac[3] = {0x00,0x22,0x38}; char fullmac[6] = {XILINX_MAC_OUI0, XILINX_MAC_OUI1, XILINX_MAC_OUI2, low_mac[0], low_mac[2], low_mac[3]}; char ip[4] = {149,199,6,108}; char subnet[4] = {255,255,255,0}; char gateway[4] = {149,199,6,254}; int app_running = 0; unsigned int init_wait = 15000000; /*-----------------------------* Enable microblaze interrupts *-------------------------------*/ microblaze_enable_interrupts(); /*---------------------------------------------------------------. * Timer and Intc Init * . * Set the Timer to interrupt for every 100ms *--------------------------------------------------------------*/
/* set the number of cycles the timer counts before interrupting */ /* 100 Mhz clock => 100 us for 1 clk tick. For 100ms, 1000 clk ticks need to elapse */ XTmrCtr_mSetLoadReg(XPAR_OPB_TIMER_1_BASEADDR, 0, 10000); /* reset the timers, and clear interrupts */ XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0, XTC_CSR_INT_OCCURED_MASK | XTC_CSR_LOAD_MASK ); /* start the timers */ XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0, XTC_CSR_ENABLE_TMR_MASK | XTC_CSR_ENABLE_INT_MASK | XTC_CSR_AUTO_RELOAD_MASK | XTC_CSR_DOWN_COUNT_MASK); /*----------------------------------------------------------------
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
155 Embedded Development Kit
R
Chapter 11: lwIP Library
* Uart Init*------------------------------------------------------------------*/ /* Disable Interrupts */ XIo_Out8(UART_BASEADDR + XUN_LCR_OFFSET, 0UL); XIo_Out8(UART_BASEADDR + XUN_IER_OFFSET, 0UL); /* Clear Latches */ XIo_In8(UART_BASEADDR + XUN_LSR_OFFSET); XIo_In8(UART_BASEADDR + XUN_IIR_OFFSET); XIo_In8(UART_BASEADDR + XUN_MSR_OFFSET); /* Disable FIFOs (16450) */ XIo_Out8(UART_BASEADDR + XUN_FCR_OFFSET, 0UL); /* Normal ABQ level 0 driver inits */ XUartNs550_SetBaud(UART_BASEADDR, UART_CLOCK, UART_BAUDRATE); XUartNs550_mSetLineControlReg(UART_BASEADDR, XUN_LCR_8_DATA_BITS); /* Sets DTR, RTS, and OUT2 in the MCR */ XIo_Out8(UART_BASEADDR + XUN_MCR_OFFSET, XUN_MCR_OUT_2 | XUN_MCR_RTS | XUN_MCR_DTR); xil_printf("\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n \n"); xil_printf("Starting Up... \n"); xil_printf("Console: 16550 initialized. \n"); /*------------------------------------------------------------------*/ /* Do LWIP System Inits */ /*---------------------------------------------------------------*/ #ifdef STATS stats_init(); #endif /* STATS */ xil_printf("Initializing Memory Structures."); sys_init(); mem_init(); xil_printf("."); memp_init(); xil_printf("."); pbuf_init(); xil_printf(" done. \n");
156 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
// set GPIO I/O Mask XGpio_mSetDataDirection(XPAR_MYGPIO_BASEADDR, 0x00000FFF); // Turn on 4 LEDs (Active Low) XGpio_mSetDataReg(XPAR_MYGPIO_BASEADDR, 0x00000000); /*---------------------------------------------------------------*/ /* Initial Header and Menus. Do this before the netif_init() so we can */ /* change the MAC Address and IP addresses if needed */ /*---------------------------------------------------------------*/ while(init_wait--); print_app_header(); fullmac[0] = XILINX_MAC_OUI0; fullmac[1] = XILINX_MAC_OUI1; fullmac[2] = XILINX_MAC_OUI2; fullmac[3] = low_mac[0]; fullmac[4] = low_mac[1]; fullmac[5] = low_mac[2]; /*---------------------------------------------------------------*/ /* Set host addresses */ /*---------------------------------------------------------------*/ xemacif_setmac(0, (u8_t *) fullmac); //Set MAC IP4_ADDR(&gw, gateway[0],gateway[1],gateway[2],gateway[3]); //Set gateway IP4_ADDR(&ipaddr, ip[0],ip[1],ip[2],ip[3]); //Set ip IP4_ADDR(&netmask,subnet[0],subnet[1],subnet[2],subnet[3]); //Set subnet msk /*---------------------------------------------------------------*/ /* Show some host boot stuff and parameters */ /*---------------------------------------------------------------*/ xil_printf(" \nStarting Network Interface... \n"); xil_printf(" MAC Address: "); show_dashed_hex(6, fullmac); xil_printf(" \n"); xil_printf(" IP Address: "); show_dotted_decimal(ip); xil_printf(" \n"); xil_printf(" Subnet Mask: "); show_dotted_decimal(subnet); xil_printf(" \n"); xil_printf(" Gateway IP: "); show_dotted_decimal(gateway); xil_printf(" \n");
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
157 Embedded Development Kit
R
Chapter 11: lwIP Library
xil_printf(" Echo Port: 7 \n"); /*---------------------------------------------------------------*/ /* Initialize netif */ /*---------------------------------------------------------------*/ netif_init(); /*---------------------------------------------------------------*/ /* Initialize TCP Stack */ /*---------------------------------------------------------------*/ tcp_init(); /*---------------------------------------------------------------*/ /* Set up the lwIP network interface... */ /*---------------------------------------------------------------*/ default_netif = netif_add(&ipaddr, &netmask, &gw, &XEmacIf_ConfigTable[0], xemacif_init, ip_input ); netif_set_default(default_netif); /*---------------------------------------------------------------*/ /* create new tcp pcb and start applications */ /*---------------------------------------------------------------*/ // Start the Server xil_printf("Echo Server Running ... "); xil_printf(" \n"); echo_init(); app_running = 1; while (1) { while (waiting_for_timer) { xemacif_input(default_netif); } my_tmr(); waiting_for_timer = 1; } return (1); } int main () { /*---------------------------------------------------------------*/ /* Enable instruction and data cache-this must be done first because
158 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
Example lwIP Application
R
*/ /* the Memec Design Virtex-II Dev Boards (rev1 and rev2) have the SDRAM */ /* byte enables tied together on the board. Enabling the caches */ /* guarantees that all memory accesses are 32-bit aligned. */ /*---------------------------------------------------------------*/ return main_main(); } void mytimer_int_handler (void* baseaddr_p) { int baseaddr = *(int *)baseaddr_p; unsigned int csr; unsigned int gpio_data; /* Read timer 0 CSR to see if it raised the interrupt */ csr = XTmrCtr_mGetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0); if (csr & XTC_CSR_INT_OCCURED_MASK) { //xil_printf("Timer Handler ...\n"); waiting_for_timer = 0; /* Clear the timer interrupt */ XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0, csr); } } FileName : echo.c echo.h These are the same files as used in the PowerPC example described above.
For MicroBlaze design, the echo server application is set to start at 0x86000000 which is the start address of SDRAM. The entire design runs off the external memory.
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
www.xilinx.com 1-800-255-7778
159 Embedded Development Kit
R
Chapter 11: lwIP Library
160 Embedded Development Kit
www.xilinx.com 1-800-255-7778
EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004
