Home

Z8 Encore! ZiLOG Standard Library API Reference Manual

1. char init _ports void open Port A in default mode open PortA configure Port A pins for open drain mode if GPIOERR_INVALIDPINS setmodeOpenDrain_ PortA PORTPIN ALL return 1 open Port B in default input mode open _PortB configure Port B pins for open drain mode if GPIOERR_INVALIDPINS setmodeOpenDrain_PortB PORTPIN ALL return 1 ZSL GPIO API Description RM003805 0508 void write _ports void Write to Port A pins these pins PAOUT datal Write to Port B pins these pins PBOUT data2 RM003805 0508 Zilog Standard Library API Reference Manual pull ups are connected to pull ups are connected to ZSL GPIO API Description 27 28 Zilog Standard Library API Z8 Encore Family of Microcontrollers 77 IIt A AN IJL lE V YY setmodeHighDrive_Portx Prototype char setmodeHighDrive_Portx uchar pins Description The setmodeHighDrive_ Portx API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to high drive mode open source mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the high drive mode for Port A Pin 7 PA7 is set by the values contained in registers PA ADDR and PA_CTL 7 To set Pin 1 of Port A into high drive mode call this API by specifying the b
2. ZSL GPIO API Description Write to Port A pins pull downs are connected to these pins wes PAOUT datal Write to Port B pins pull downs are connected to these pins eg PBOUT data2 RM003805 0508 Zilog Standard Library API Reference Manual setmodeStopRecovery_Portx Prototype char setmodeStopRecovery Portx uchar pins Description The setmodeStopRecovery_ Portx API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the stop recovery mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the stop recovery mode for Port A Pin 7 PA7 is set by the values contained in registers PA ADDR and PA _CTL 7 To set Pin 1 of Port A into stop recovery mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeStopRecovery PortA PORTPIN_ONE Similarly more than one pin is set to stop recovery mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into stop recovery mode the API is used as given below setmodeStopRecovery PortA PORTPIN_FIVE PORTPIN_SEVEN i gt Note This API does not alter states of other pins RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers r 32 Z l O g Argument s pins The bitwise
3. GPIOERR_INVALIDPINS setmodeInterrupt_ PortD_F1680 PORTPIN TWO EDGE RISING INTPRIORITY NOMINAL return 1 ZSL GPIO API Description 58 Zilog Standard Library API Z8 Encore Family of Microcontrollers 77 I E A AN EJL E V s setmodeAltFuncSet1_Portx Prototype char setmodeAltFuncSet1 Portx uchar pins Description The setmodeAltFuncSet1_Portx API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the alternate function set 1 mode The mode for each pin is controlled by set ting each register bit pertinent to the pin to be configured For example the alternate function set 1 mode for Port B Pin 7 PB7 is set by the values in the registers PB_ ADDR and PB_CTL 7 To set pin 1 of Port B into alternate function set 1 mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeAltFuncSet1 PortB PORTPIN_ONE Similarly more than one pin is set to alternate function set 1 mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port B into alternate function mode the API is used as given below setmodeAltFuncSet1_ PortB PORTPIN FIVE PORTPIN_SEVEN gt Note Alternate function mode set I is supported only in Ports B and C of the Z8F04 XP Series ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual Argument s
4. ZDS II interface to choose the device and to specify the device ZSL Overview RM003805 0508 Zilog Standard Library API Reference Manual parameters For information on using ZSL from within ZDS II refer to the Zilog Developer Studio II Z8 Encore User Manual UM0130 available with the ZDS II tool package or on www zilog com ZDS II copies the Zilog Standard Library device initialization file zsldevinit asm into the user project when ZSL is selected from within ZDS II The initialization file contains the open_periphdevice function that calls the initialization routines for all devices used in the user application The open periphdevice routine is invoked from the startup routine before the main function is called Depending on the device selected ZDS II defines specific macros for each device For details on initialization of the specific devices see chapters on the API descriptions of the specific devices The user application initializes the required device s to their default values without calling the startup routine To do so the user application must call the open _periphdevice function before making any specific calls to the device s Zilog Standard Library API Overview This section provides a brief overview on topics related to the APIs provided by ZSL to write applications which use the peripheral devices on Z8 Encore microcontrollers Standard Data Types ZSL makes use of the user define
5. ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_ SUCCESS Indicates that the port was configured to the stop recovery mode successfully Example include lt ez8 h gt char init _ports void open Port A in default mode open PortA configure Port A pins for stop recovery source mode if GPIOERR_INVALIDPINS setmodeStopRecovery PortA PORTPIN ALL return 1 open Port B in default input mode open PortB configure Port B pins for stop recovery source mode if GPIOERR_INVALIDPINS setmodeStopRecovery PortB PORTPIN ALL return 1 ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual setmodePullUp_Portx Prototype char setmodePullUp_ Portx uchar pins Description The setmodePullUp_ Portx API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the pull up mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the pull up mode for Port A Pin 7 PA7 is set by the values in the registers PA ADDR and PA_CTL 7 To set Pin 1 of Port A into pull up mode call this API by specifying the bit corresponding t
6. Resets all those Port B pins as specified by the bit pattern in x define SETBITPC x Sets all those Port C pins as specified by the bit pattern in x define RESETBITPC PCOUT x x Resets all those Port C pins as specified by the bit pattern in x define SETBITPD x Sets all those Port D pins as specified by the bit pattern in x define RESETBITPD PDOUT x x Resets all those Port D pins as specified by the bit pattern in x define SETBITPE x Sets all those Port E pins as specified by the bit pattern in x define RESETBITPE PEOUT x x Resets all those Port E pins as specified by the bit pattern in x define SETBITPF x Sets all those Port F pins as specified by the bit pattern in x define RESETBITPF PFOUT x x Resets all those Port F pins as specified by the bit pattern in x define SETBITPG x Sets all those Port G pins as specified by the bit pattern in x define RESETBITPG PGOUT x x Resets all those Port G pins as specified by the bit pattern in x define SETBITPH x Sets all those Port H pins as specified by the bit pattern in x define RESETBITPH PHOUT x RM003805 0508 x Resets all those Port H pins as specified by the bit pattern in x ZSL GPIO API Description Zilog Standard Library API Z8 Encore Fami
7. a setmodeinterrupt_PortA_8Pn Prototype char setmodeInterrupt_PortA_8Pn uchar pins uchar edge uchar priority Description gt Note The setmodeInterrupt PortA_8Pn API is used to configure one or more pins of GPIO Port A on the Z8 Encore Z8F04 8 pin series of microcontroller to the interrupt mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured The API also provides an option to set the type of triggering to either falling or rising edge along with the priority for the interrupt For example to set pin 1 of Port A to falling edge with a low priority call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below char setmodeInterrupt PortA 8Pn PORTPIN ONE EDGE FALLING INTPRIORITY LOW 7 Similarly more than one pin is set to interrupt mode by ORing the pins in the API call For example to set Pin 5 and pin 7 of Port A into interrupt mode the API is used as given below setmodeInterrupt_PortA_8Pn PORTPIN FIVE PORTPIN SEVEN EDGE RISING INTPRIORITY_ LOW This API does not alter states of other pins RM003805 0508 ZSL GPIO API Description 43 Zilog Standard Library API Z8 Encore Family of Microcontrollers u Zilog Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file edge The type of edge triggering for the interrupts Valid values are EDGE_F
8. as defined in the gpio h file RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the alternate function mode successfully Example include lt ez8 h gt char init _ports void open Port A in default mode open PortA configure Port A pins for alternate function mode if GPIOERR_INVALIDPINS setmodeAltFunc_PortA PORTPIN ALL return 1 Port A pins are now available for alternate function mode open Port B in default input mode open _PortB configure Port B pins for alternate function mode i1f GPIOERR_INVALIDPINS setmodeAltFunc_PortB PORTPIN ALL return 1 Port B pins are now available for alternate function mode ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual g 37 j LIA i lj I E V setmodelnterrupt_PortC Prototype char setmodeInterrupt_PortC uchar pins uchar priority Description The setmodeInterrupt_PortC API is used to configure one or more pins of the GPIO Port C of Z8 Encore microcontroller to the interrupt mode The mode for each pin is controlled by setting each register b
9. becomes available The API calls the underlying read_UARTx API If there is any error in the received data byte an error code is set in the g_ recverr0 global variable The application determines the error by updating the g_recverr0 global variable with a known value before calling the API and then reading the g_recverro global variable again to determine whether that value changed For a list of possible errors see read UARTx API on page 92 Argument s None Return Value s Returns the character received Example include lt ez8 h gt void get_input void int ch printf Type a character n ch getch if ch n printf A new line is entered n ZSL UART API Description RM003805 0508 Zilog Standard Library API Reference Manual J 77 putch Prototype int putch int ich Description The putch API writes a data byte into the default UART transmit buffer If the data byte written is a newline character then the putch API writes an additional carriage return character into the UART transmit buffer Argument s ich Character to be written in the transmit buffer Return Value s ich Indicates success EOF Indicates failure Example include lt ez8 h gt void get_input void int ch printf Type a character n ch getch if ch n printf A new line is entered n else printf You entered putch
10. information speed optimization ZS1F1680U0LTD 1ib Drivers for applications with a Large memory model and using sTatic frames with Debug information no optimization RM003805 0508 ZSL Overview 5 Zilog Standard Library API Z8 Encore Family of Microcontrollers s ZI ZSL Overview Table 6 lists the library files to place ISRs for UART1 in PRAM Table 6 Library Files to place ISRs for F1680 Series UART1 in PRAM Library Name Description ZS1F1680U1SY 1lib Drivers for applications with a Small memory model and using dYnamic frames no debug information speed optimization ZS1F1680U1SYD 1ib Drivers for applications with a Small memory model and using dYnamic frames with Debug information no optimization ZS1F1680U1ST 1lib Drivers for applications with a Small memory model and using sTatic frames no debug information speed optimization ZS1F1680U1STD 1lib Drivers for applications with a Small memory model and using sTatic frames with Debug information no optimization ZS1F1680U1LY 1lib Drivers for applications with a Large memory model and using dYnamic frames no debug information speed optimization ZS1F1680U1LYD 1ib Drivers for applications with a Large memory model and using dYnamic frames with Debug information no optimization ZS1F1680U1LT 1ib Drivers for applications with a Large memory model and using sTatic frames no debug information spe
11. interrupt mode if GPIOERR_INVALIDPINS setmodeInterrupt PortD F64 PORTPIN TWO EDGE RISING INTPRIORITY NOMINAL return 1 ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual p A ZILO y O p 55 setmodelnterrupt_Portx_F1680 Prototype char setmodeInterrupt_Portx_F1680 uchar pins uchar edge uchar priority Description The setmodeInterrupt_Portx_F1680 API is used to configure one or more pins of the selected GPIO ports Z8 Encore Z8F1680 series of microcontroller to the interrupt mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured The API also provides an option to set the type of triggering to either falling or rising edge along with the priority for the interrupt For example to set pin 1 of Port A to falling edge with a low priority call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below char setmodeInterrupt_PortA_F1680 PORTPIN ONE EDGE FALLING INTPRIORITY_ LOW Similarly more than one pin is set to interrupt mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into interrupt mode the API is used as given below setmodeInterrupt_PortA_F1680 PORTPIN FIVE PORTPIN SEVEN EDGE RISING INTPRIORITY_ LOW RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Fami
12. mode successfully Example include lt ez8 h gt pragma interrupt void isr_PA1 void Handle PA1 interrupt here char init _ports void open Port A in default mode open PortA RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers set the interrupt vector for Port A bit one SETVECTOR PA1l IVECT isr_PAl configure Port A pin 1 for interrupt mode i GPIOERR_INVALIDPINS setmodeInterrupt_PortA_4K PORTPIN ONE EDGE FALLING INTPRIORITY HIGH return 1 ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual eg Z lon I t OU Ly 49 setmodelnterrupt_PortA_F08 Prototype char setmodeInterrupt_PortA_F08 uchar pins uchar edge uchar priority Description The setmodeInterrupt PortA _F08 API is used to configure one or more pins of the selected GPIO ports Z8 Encore Z8F08 series of microcontroller to the interrupt mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured The API also provides an option to set the type of triggering to either falling or rising edge along with the priority for the interrupt For example to set Pin 1 of Port A to falling edge with a low priority call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below char setmodeInt
13. page 9 Argument s parity Specifies the new parity value parity disable valid values PAR_NOPARITY PAR_ODPARITY PAR_EVPARITY Return Value s UART_ERROR_NONE No error UART_ERR_INVPARITY Error due to invalid parity values ZSL UART API Description RM003805 0508 Zilog Standard Library API Reference Manual setstopbits_UARTx Prototype uchar setstopbits UARTx uchar stopbits Description The setstopbits_UARTx API sets the stop bits for the VARTx device If the debug version of ZSL is used the API checks the validity of the parameters passed Otherwise the API configures the UARTx with the value passed in the stopbits parameter For more information see ZSL Debug and Release Version on page 9 Argument s stopbits Number of valid stop bits set stopbits gt 2 valid values 1 2 Return Value s UART_ERROR_NONE No error UART_ERR_INVSTOPBITS Error due to invalid stop bits RM003805 0508 ZSL UART API Description 88 Zilog Standard Library API Z8 Encore Family of Microcontrollers LIAN ZILOQ I write _UARTx Prototype uchar write_UARTx char pData uint16 nbytes Description The write UARTx API writes data bytes into the UARTx device The API accepts a pointer to the buffer containing data to be transmitted and the number of bytes to be transmitted The API behaves differently depending on the mode in which the UARTx device is configured as follows Writing in Poll
14. pins of the selected GPIO port of Z8 Encore microcontroller to the alternate function set 2 mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the alternate function set 2 mode for Port A Pin 7 PA7 is set by the val ues contained in registers PA ADDR and PA CTL 7 To set Pin 1 of Port A into alternate function set 2 mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeAltFuncSet2 PortA PORTPIN ONE Similarly more than one pin is set to alternate function set 1 mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into alternate function mode the API is used as given below setmodeAltFuncSet2 PortA PORTPIN FIVE PORTPIN_SEVEN This API does not alter states of other pins Alternate function mode set 2 is supported only in Port A of Z8F04 8 pin devices and Ports B and C of Z8F04 XP and 4K Series RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In debug mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the alternate function mode
15. setmodeAltFuncSet3 PortA PORTPIN_ THREE return 1 Port A pin 3 is now available for alternate function set 3 mode Namely T1IN for pin 3 RM003805 0508 ZSL GPIO API Description 66 Zilog Standard Library API Z8 Encore Family of Microcontrollers 77 I E A AN EJL E V s setmodeAltFuncSet4_PortA Prototype char setmodeAltFuncSet4 PortA uchar pins Description The setmodeAltFuncSet4 PortA API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the alternate function set 4 mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the alternate function set 4 mode for Port A Pin 7 PA7 is set by the values in the registers PA ADDR and PA_CTL 7 To set Pin 1 of Port A into alternate function set 4 mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeAltFuncSet4 PortA PORTPIN_ONE Similarly more than one pin is set to alternate function set 1 mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into alternate function mode the API is used as given below setmodeAltFuncSet4 PortA PORTPIN FIVE PORTPIN_SEVEN gt Note This API does not alter states of other pins Alternate function mode set 4 is supported only in Port A of the Z8F04 8 pin devices ZSL GPIO API Descript
16. successfully Example include lt ez8 h gt char init _ports void open Port C in default mode open PortC configure Port C pins 0 and 1 for alternate function set 2 mode if GPIOERR_INVALIDPINS setmodeAltFuncSet2_ PortcC PORTPIN ZERO PORTPIN ONE return 1 Port C pins 0 and 1 are now available for alternate function set 2 mode Namely ANA4 CINP LED and ANA5 CINN LED However the CINP LED and CINN LED alternate functions are available on XP series only ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual open Port B in default input mode open PortB configure Port B pins for alternate function set 2 mode if GPIOERR_INVALIDPINS setmodeAltFuncSet2_PortB PORTPIN ALL return 1 Port B pins are now available for alternate function set 2 mode Namely ANAO ANA1 ANA2 ANA3 etc ar RM003805 0508 ZSL GPIO API Description 64 Zilog Standard Library API Z8 Encore Family of Microcontrollers 77 I E A AN EJL E V s setmodeAltFuncSet3_PortA Prototype char setmodeAltFuncSet3 PortA uchar pins Description The setmodeAltFuncSet3_ PortA API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the alternate function set 3 mode The mode for each pin is controlled by setting each register bit pertinent to t
17. the Z8 Encore microcontroller UART peripheral s and details of the APIs provided to interface with it Related Documents In addition to this manual you must be familiar with the documents listed in Table 1 Table 1 Related Documents Document Document Title Number Zilog Developer Studio II Z8 Encore User Manual UM0130 ZPAKII Debug Interface Tool Product User Guide PUG0015 Z8 Encore XP F0822 Series Flash MCU Evaluation Kit QS0025 Quick Start Guide Z8 Encore XP F64XX Series Development Kit Quick QS0028 Start Guide eZ8 CPU User Manual UM0128 Latest software and updated documents are available for download at www zilog com Introduction RM003805 0508 Zilog Standard Library API Reference Manual ae vii Abbreviations and Expansion Table 2 lists the abbreviations acronyms used in this document Table 2 Abbreviations and Expansion Abbreviations Acronyms Expansion ADDR Address Register ANSI American National Standards Institute API Application Program Interface CTL Control Register DMA Direct Memory Access EOF End of File a macro defined in the stdio h file GPIO General Purpose Input Output IDE Integrated Development Environment ISR Interrupt Service Routine PA GPIO Port A PB GPIO Port B PC GPIO Port C PD GPIO Port D PE GPIO Port E PF GPIO Port F PG GPIO Port G PH GPIO Port H PRAM Program RAM RTL AN
18. two kinds of GPIO APIs e Common APIs For features that are common across all devices in the Z8 Encore family Table 9 lists common APIs with hyperlinks to their descriptions Target Specific APIs For features that are present only on some variants of Z8 Encore family Table 10 on page 15 lists specific APIs with applicable target devices and ports In addition to APIs ZSL defines a number of GPIO related macros For more information see ZSL GPIO Macros on page 70 Table 9 ZSL Common GPIO APIs API Name Description open_Portx Opens a specified GPIO Port control_ Portx Configures a specified GPIO Port setmodelnput_Portx Sets Port bits for Input mode setmodeOutput_Portx Sets Port bits for Output mode setmodeOpendrain_Portx Sets Port bits for Open Drain mode setmodeHighDrive_Portx Sets Port bits to a High Drive enable mode setmodeStopRecovery_Portx Sets Port bits to a Stop Recovery mode close_Portx Closes a specified GPIO Port ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual Zilog Table 10 ZSL Target Specific GPIO APIs API Name setmodePullUp_Portx Description and Valid Z8 Encore Devices Ports Set port bits to PullUp mode F08 Series Ports A B and C XP Series Ports A B C and D 4 K Series Ports A B and C setmodeAltFunc_Portx Set port bits to Alternate function mode F04 Series Port A F64XX S
19. 1 void write_ports void Write to Port A pins PAOUT datal Write to Port B pins PBOUT data2 ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual setmodeAltFunc_Portx Prototype char setmodeAltFunc_ Portx uchar pins Description The setmodeAltFunc_Portx API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the alternate function mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the alternate function mode for Port A Pin 7 PA7 is set by the values in the registers PA ADDR and PA_CTL 7 To set Pin 1 of Port A into alternate function mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeAltFunc_PortA PORTPIN ONE Similarly more than one pin is set to alternate function mode by ORing the pins in the call to the API For example to set Pin 5 and Pin 7 of Port A into alternate function mode the API is used as given below setmodeAltFunc_PortA PORTPIN FIVE PORTPIN SEVEN gt Note This API does not alter states of other pins The alternate func tion mode is supported in Port A of the Z8F04 Series Ports A B C D and H of the Z8F64XX Series and in Ports A B and C of all other targets Argument s pins The bitwise ORed value indicating the pins of a port
20. 35 58 61 64 66 API UART 79 asterisks viii asynchronous interrupt mode compile option 74 overview 73 read status 95 read UART 92 write status 91 write UART 88 audience manual v B batch files 9 baud rate 74 84 boot related files 8 building ZSL libraries 9 C caution text viii RM003805 0508 Zilog Standard Library API Reference Manual close Portx API 70 close UARTx API 96 common GPIO APIs 14 compile time options UART 73 74 configure GPIO pins 19 control register CTL vii control registers UART 80 control Portx API 18 control UARTx API 81 conventions viii courier typeface viii Customer Information 101 customize library files 9 D data types 11 debug version 9 defaults UART 73 defines h 11 definitions terminology vii device driver 1 device initialization 11 DEVICE PARAMETER CHECKING macro 9 direct memory access DMA 74 88 directory structure 7 documents related vi dynamic frames 2 3 5 6 Index Zilog Standard Library API Z8 Encore Family of Microcontrollers electrostatic discharge ESD ix end of file EOF vii error checking 74 F flow control hardware 75 frames dynamic 2 3 5 6 G get rxstatus UARTx API 95 get txstatus UARTx API 91 getch API 76 GPIO port initialization 13 GPIO port x Px vii GPIO configure pins 19 GPIO specific APIs 14 grounding strap 1x H hardware flow control 75 header files 8 hexadecimal value
21. 3805 0508 Zilog Standard Library API Reference Manual 53 Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file edge The type of edge triggering for the interrupts Valid values are EDGE_FALLING EDGE_RISING priority The priority of the interrupt The valid values are INTPRIORITY_LOW INTPRIORITY_NOMINAL INTPRIORITY_HIGH Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the interrupt mode successfully Example include lt ez8 h gt pragma interrupt void isr_PA1 void Handle PA1 interrupt here pragma interrupt void isr_PD2 void Handle PD2 interrupt here RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers char init _ports void open Port A in default mode open PortA set the interrupt vector for Port A bit one SETVECTOR PA1l IVECT isr_PAl1 configure Port A pin 1 for interrupt mode if GPIOERR_INVALIDPINS setmodeInterrupt PortA_F64 PORTPIN_ ONE EDGE FALLING INTPRIORITY_HIGH return 1 open port D in default mode open PortD set the interrupt vector for port D bit two SETVECTOR PD2_ IVECT isr_PD2 configure port D pin 2 for
22. 81 control_UARTx Prototype uchar control UARTx UART pUART Description The control_UARTx API is used to configure the UARTx device with the values specified by the pointer to the UART structure passed as the parameter The values in the structure are used to write into the appropriate UARTx device Control registers If the debug version of ZSL is used the API checks the validity of the parameters passed Otherwise the API configures the UARTx with the value passed in the pUART parameter For more information see ZSL Debug and Release Version on page 9 RM003805 0508 ZSL UART API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers Argument s pUART Pointer to a structure of type UART as defined in uart h file baudrate 57600 valid values 9600 19200 38400 57600 115200 stop bits 2 valid values 1 2 parity disable valid values PAR_NOPARITY PAR_ODPARITY PAR_EVPARITY Return Value s UART_ERROR_NONE No error UART_ERR_INVBAUDRATE Error due to invalid baud rate value passed UART_ERR_INVSTOPBITS Error due to invalid stop bits value passed UART_ERR_INVPARITY Error due to invalid parity value passed Example 1 include lt ez8 h gt void init devices void UART uart char stat UART_ERR_NONE configure UARTO with 9600 baud 1 stop bits and no parity uart baudRate BAUD 9600 uart stopBits STOPBITS 1 uart parity PA
23. ALLING EDGE_RISING priority The priority of the interrupt The valid values are INTPRIORITY_LOW INTPRIORITY_NOMINAL INTPRIORITY_HIGH Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the interrupt mode successfully Example include lt ez8 h gt pragma interrupt void isr_PA1 void Handle PA1 interrupt here char init _ports void open Port A in default mode open PortA ZSL GPIO API Description RM003805 0508 RM003805 0508 Zilog Standard Library API Reference Manual ce fr C e s 45 l set the interrupt vector for Port A bit one SETVECTOR PA1_IVECT isr PAL configure Port A pin 1 for interrupt mode return 1 if GPIOERR_INVALIDPINS setmodeInterrupt PortA_8Pn PORTPIN ONE EDGE FALLING INTPRIORITY HIGH ZSL GPIO API Description 46 Zilog Standard Library API Z8 Encore Family of Microcontrollers 4 a I A FN ITAN Z L U g setmodelnterrupt_PortA_4K Prototype char setmodeInterrupt_PortA_4K uchar pins uchar edge uchar priority Description gt Note The setmodeInterrupt_PortA_4K API is used to configure one or more pins of GPIO Port A on the Z8 Encore Z8F04 4K series of microcontroller to the interrupt mode The mode for
24. ART_ERR_PARITYERR Indicates that a parity error occurred in the byte received UART_ERR_OVERRUNERR Indicates an overrun error occurred in the byte received UART_ERR_BREAKINDICATION Indicates that a break condition is set include lt ez8 h gt int compute _sum int int void r RM003805 0508 ead_data int vall val2 UART uart char stat UART_ERR_NONE configure UARTO with 9600 baud 1 stop bits and no parity uart baudRate BAUD 9600 uart stopBits STOPBITS 1 ZSL UART API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers a ZILOg uart parity PAR_NOPARITY Configure the UART stat control UARTO amp uart if UART_ERR_NONE stat stat read_UARTO readdata amp len if UART_ERR_NONE stat return close UARTO return block here while receiver is busy while UART_IO PENDING get_rxstatus_UARTO close UARTO j ZSL UART API Description RM003805 0508 Zilog Standard Library API Reference Manual get_rxstatus_UARTx Prototype uchar get_rxstatus_UARTx void Description The get_rxstatus UARTx API is used to get the status of the asynchronous read operation in the UARTx device This API must be called by the application to know the status of the read operation during INTERRUPT mode During INTERRUPT mode data transmission the read_UARTx API returns immediately allowing t
25. ECTOR PA1l IVECT isr_PAl configure Port A pin 1 for interrupt mode if GPIOERR_INVALIDPINS setmodeInterrupt_PortA_F08 PORTPIN ONE EDGE FALLING INTPRIORITY_HIGH return 1 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers 4 a I A FN IIAN Z L U g setmodelnterrupt_Portx_F64 Prototype char setmodeInterrupt_Portx_F64 uchar pins uchar edge uchar priority Description The setmodeInterrupt Portx F64 API is used to configure one or more pins of the selected GPIO ports Z8 Encore Z8F64XX series of microcontroller to the interrupt mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured The API also provides an option to set the type of triggering to either falling or rising edge along with the priority for the interrupt For example to set Pin 1 of Port A to falling edge with a low priority call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below char setmodeInterrupt PortA F64 PORTPIN ONE EDGE FALLING INTPRIORITY_LOW Similarly more than one pin is set to interrupt mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into interrupt mode the API is used as given below setmodeInterrupt_PortA_F64 PORTPIN_FIVE PORTPIN SEVEN EDGE RISING INTPRIORITY_ LOW ZSL GPIO API Description RM00
26. EDs void Write to Port C pins PCOUT datal RM003805 0508 ZSL GPIO API Description 70 Zilog Standard Library API Z8 Encore Family of Microcontrollers zilog close_Portx Prototype void close Portx void Description The close _Portx API resets all the selected Port registers and configures the port as a standard digital input pin However this API does not reset the GPIO interrupt settings if already configured Argument s None Return Value s None ZSL GPIO Macros The ZSL GPIO macro definitions are listed in Table 11 Table 11 ZSL GPIO Macro Definitions define Description define RESETBIT x y x amp BYTE OxFF y Resets all those bits in x as specified by the bit pattern in y define SETBIT x BYTE y y x Sets all those bits in x as specified by the bit pattern in y define SETBITPA x SETBIT PAOUT Sets all those Port A pins as specified x by the bit pattern in x define RESETBITPA x RESETBIT Resets all those Port A pins as PAOUT x specified by the bit pattern in x define SETBITPB x SETBIT PBOUT Sets all those Port B pins as specified x by the bit pattern in x ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual Zi Table 11 ZSL GPIO Macro Definitions Continued define Description define RESETBITPB PBOUT x x
27. NOT ASSUME LIABILITY FOR INTELLECTUAL PROPERTY INFRINGEMENT RELATED IN ANY MANNER TO USE OF INFORMATION DEVICES OR TECH NOLOGY DESCRIBED HEREIN OR OTHERWISE The information contained within this document has been verified according to the general principles of electrical and mechanical engineering Z8 Encore and Z8 Encore XP are registered trademarks of Zilog Inc All other product or service names are the property of their respective owners RM003805 0508 Zilog Standard Library API Reference Manual ZI Revision History Each instance in Revision History reflects a change to this document from its previous revision For more details refer to the corresponding pages and appropriate links in the table below Revision Date Level Description Page No May 2008 05 Updated UART Initialization inthe 72 74 Startup Routine Table 12 replaced ZDS II v4 10 1 with ZDS II v4 11 0 April 2008 04 Updated Zilog logo Zilog text All Disclaimer section and implemented Style Guide Updated Building the Zilog Standard Libraries section October 2006 03 Updated for Z8 Encore XP F1680 All Series library files RM003805 0508 Revision History iv Zilog Standard Library API Z8 Encore Family of Microcontrollers ZI Table of Contents Introduction ou sae ee eo cae isle ei deel oe bi nnana v About This Manual nananana aaan V Intended Audience 20000 cece eee ee eee Vv Manual Organization
28. PIN_ SEVEN EDGE RISING INTPRIORITY LOW This API does not alter states of other pins ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual 41 Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file edge The type of edge triggering for the interrupts Valid values are EDGE_FALLING EDGE_RISING priority The priority of the interrupt The valid values are INTPRIORITY_LOW INTPRIORITY_NOMINAL INTPRIORITY_HIGH Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the interrupt mode successfully Example include lt ez8 h gt pragma interrupt void isr_PA1 void Handle PA1 interrupt here char init _ports void open Port A in default mode open PortA RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers set the interrupt vector for Port A bit one SETVECTOR PA1l IVECT isr_PAl configure Port A pin 1 for interrupt mode if GPIOERR_INVALIDPINS setmodeInterrupt_PortA_XP PORTPIN ONE EDGE FALLING INTPRIORITY HIGH return 1 ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual NANN I t OU CJ adi
29. R NOPARITY Configure the UART stat control UARTO amp uart if UART_ERR_NONE stat ZSL UART API Description RM003805 0508 Example 2 RM003805 0508 Zilog Standard Library API Reference Manual close UARTO return ntestcase include lt ez8 h gt void init devices void UART uart char stat UART_ERR_NONE configure UARTO with 1200 invalid baud 1 stop bit and no parity uart baudRate 1200 uart stopBits STOPBITS 1 uart parity PAR _NOPARITY Configure the UART stat control UARTO amp uart if UART_ERR_NONE stat 1 if stat UART_ERR_INVBAUDRATE global_err TRUE close UARTO j ZSL UART API Description 84 Zilog Standard Library API Z8 Encore Family of Microcontrollers setbaud_UARTx Prototype uchar setbaud_UARTx int32 baud Description The setbaud_UARTx API configures the baud rate for the UARTx device with the specified value If the debug version of ZSL is used the API checks the validity of the parameters passed Otherwise the API configures the UARTx with the value passed in the baud parameter For more information see ZSL Debug and Release Version on page 9 Argument s baud Specifies the new baudrate to be set This value along with the target clock frequency value set in the zsldevinit asm file is used to calculate the value for Baudrate Generator registers baud va
30. SI C Run Time Library UART Universal Asynchronous Receiver Transmitter RM003805 0508 Introduction Zilog Standard Library API Z8 Encore Family of Microcontrollers A N viii Z ItLJ g Table 2 Abbreviations and Expansion Continued Abbreviations Acronyms Expansion ZDS Il Zilog Developer Studio II ZSL Zilog Standard Library Conventions The following assumptions and conventions are adopted to provide clarity and ease of use Courier Typeface Commands code lines and fragments bits equations hexadecimal addresses and various executable items are distinguished from general text by the use of the Courier typeface Hexadecimal Values Hexadecimal values are designated by a lowercase h and appear in the Courier typeface Example STAT is set to F8h Asterisks An asterisk preceding a parameter denotes the parameter as a pointer Safeguards It is important that you understand the following safety terms which are defined here AN Caution This symbol means a procedure or file can become corrupted if you do not follow directions Introduction RM003805 0508 Zilog Standard Library API Reference Manual fN i land ZILOG ha ix In general when using ZSL in conjunction with the ZDS II IDE and any one of Zilog s development platforms follow the precautions listed below to avoid permanent damage to the platform UN Caution Always use a grounding strap to prevent damage resul
31. T 1lib Drivers for applications with a Large memory model and using sTatic frames no debug information speed optimization zslLTD 1ib Drivers for applications with a Large memory model and using sTatic frames with Debug information no optimization ZSL Overview RM003805 0508 Zilog Standard Library API Reference Manual Zi ZSL also provides various libraries for Z8 Encore XP F1680 Series each of which is used for a specific memory model and configuration Table 4 describes each of the library files for Z8 Encore XP F1680 Series Table 4 ZSL Library Files for Z8 Encore XP F1680 Series Library Name Description zslF1680SY lib Drivers for applications with a Small memory model and using dYnamic frames no debug information speed optimization zslF1680SYD lib Drivers for applications with a Small memory model and using dYnamic frames with Debug information no optimization zslF1680ST lib Drivers for applications with a Small memory model and using sTatic frames no debug information speed optimization zslF1680STD lib Drivers for applications with a Small memory model and using sTatic frames with Debug information no optimization zslF1680LY lib Drivers for applications with a Large memory model and using dYnamic frames no debug information speed optimization zslF1680LYD lib Drivers for applications with a Large memory model and using dYnamic frames with Debu
32. TC when UART is selected These ports are initialized to mode 2 in the zsldevinit asn file All standard RTL I O functions putch getch and kbhit are mapped to the default UART device implying that the standard RTL I O functions invoke the default UART device APIs In ZSL dis ZSL UART API Description RM003805 0508 Zilog Standard Library API Reference Manual j Tf l L U g 73 tribution UARTO is configured as the default device To use UART1 as the default device in uartcontrol h file change the value of macro DEFAULT_UART from UARTO to UART1 and rebuild the library 4 The UART driver operates in two modes SYNCHRONOUS mode and ASYNCHRONOUS mode In SYNCHRONOUS mode the data is transmitted and received by polling on the UARTx transmit and receive registers Thus in polling mode the read_UARTx and write _UARTx API are blocking in nature Asynchronous communication is interrupt driven In ASYNCHRO NOUS mode the data transfer both transmit and receive happens in the interrupt service routines of the UARTx devices at the same time when the application is running So the read_UARTx and write _UARTx APIs are non blocking in nature they return immedi ately to allow the application to run However some Z8 Encore Series such as EZ8F64XX data transfer transmission only also hap pens through Direct Memory Access DMA The EZ8F64XX series MCUs have dedicated DMA 1 for data transmission which is used by UARTx dev
33. _UARTx Sets parity bit option for the UARTx device setstopbits UARTx Sets stop bits for the UARTx device write_UARTx Writes data bytes to the UARTx device get_txstatus_ UARTx Gets the status of an asynchronous transmission read_UARTx Reads data bytes from the UARTx device get_rxstatus UARTx Gets the status of an asynchronous receive close_UARTx Closes the UARTx device The detailed descriptions of each of the UARTx APIs begin on the next page RM003805 0508 ZSL UART API Description 80 Zilog Standard Library API Z8 Encore Family of Microcontrollers fj A AN ZILOOQ I open_UARTx Prototype void open _UARTx Description The open_UARTx API opens the UARTx device by initializing the UARTx Control registers with default values This API configures the appropriate port registers for alternate functions The following default values are set e UARTx mode interrupt mode Baud rate 38400 e Data bits 8 e Stop bits 1 e Parity disabled e Hardware flow control disabled Argument s None Return Value s None Example include lt ez8 h gt void init devices void initialize uartO with default values open _UARTO Print welcome message printf Welcome to Zilog n close _UARTO close the uart ZSL UART API Description RM003805 0508 Zilog Standard Library API Reference Manual j Z IIO PLU YU a
34. ber of stop bits to be used for UARTx 1 stop bit communication Valid values are listed in the uart h file UARTX_PARITY Parity to be used in UARTx transmission PAR_NOPARITY The valid values are listed in the uart h file UARTX_ERRORCHECKING ZSL UART API Description Selects whether read_UARTx must Error checking check for any error in the incoming data disabled RM003805 0508 Zilog Standard Library API Reference Manual ZI Table 12 ZSL UART API Compile Time Options Continued 75 Parameter Description Default value UARTXx_HWFLOW_CTL Selects whether hardware flow control is HW flow control enabled for the transmitter disabled UARTx_RX_INT_PRIORITY Selects the interrupt priority for UARTx INTPRIORITY_ UARTX_TX_INT_PRIORITY jnterrupts Valid values are defined in NOMINAL defines h Generic UART APIs Table 13 lists the generic UART APIs with hyperlinks to their description Table 13 Generic UART APIs APIs Descriptions getch Reads data byte from the UART device putch Writes data byte into the UART transmit buffer kbhit Detects keystrokes on the UART device RM003805 0508 ZSL UART API Description 76 Zilog Standard Library API Z8 Encore Family of Microcontrollers LIAN ZILOQ I getch Prototype int getch void Description The getch API reads a data byte from the default UART device If there is no data in the UART device the API blocks till the data
35. ch RM003805 0508 ZSL UART API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers ZILOG I kbhit Prototype uchar kbhit void Description The kbhit API checks for any keystrokes on the default UART device If a keystroke is detected the kbhit function returns 1 otherwise it returns 0 The API returns immediately without blocking when the UART is configured to work either in POLL mode or in the interrupt mode gt Note The API does not read the data but only returns the status The application then calls getch to get the keystroke Argument s None Return Value s 1 Indicates that a key was hit 0 Indicates that no keystrokes were detected Example include lt ez8 h gt void get_input void printf Type any character to display menu n while kbhit display menu ZSL UART API Description RM003805 0508 Zilog Standard Library API Reference Manual 79 UARTx APIs The UARTx APIs listed in this section are used for either UARTO or UARTI devices on the Z8 Encore microcontrollers The x in the UARTx signifies 0 or 1 for the UARTO or UART device respectively Table 14 provides the hyperlinks to the description of VARTx APIs Table 14 UARTx APIs APIs Descriptions open_UARTx Initializes the UARTx device control_UARTx Configures the UARTx device setbaud_UARTXx Sets baud rate for the UARTx device setparity
36. d data types in all APIs These user defined data types are defined in the header file defines h located in the following directory lt ZDS installation dir gt include zilog API Definition Format Descriptions for each ZSL API follows a standard format In this document header file names are listed at the top of each page followed by the API description A brief discussion of the format for each API description follows RM003805 0508 ZSL Overview Zilog Standard Library API Z8 Encore Family of Microcontrollers Prototype This section contains the declaration of the API call Description This section describes the API Argument s This section describes the arguments if any to the API Return Value s This section describes the return value of the API if any Example s This section provides examples of how the API function is called Table 8 lists the Z8 Encore devices for which ZSL APIs are provided with the current release of ZDS II Z8 Encore v4 11 0 Table 8 List of ZSL APIs for Z8 Encore On Chip Devices Device Name Type of APIs Description UART UART Generic APIs These APIs are the standard RTL I O routines UARTx APIs These APIs are specific for a particular UART device either UARTO or UART1 The x in the API name represents the selected UART device GPIO ZSL Overview GPIOx APIs These APIs are specific for the GPIO Ports A B C D E F G and H The x in the API name represe
37. de with 3 milliamperes call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeLEDDrive PortC PORTPIN_ SEVEN DRIVELEVEL 3MA Similarly more than one pin is set to LED drive mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 the API is used as given below setmodeLEDDrive PortC PORTPIN_FIVE PORTPIN_ SEVEN DRIVELEVEL 3MA gt Note This API does not alter states of other pins LED drive mode is supported only in Port C of the Z8F04 XP Series Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file drivelevels The current drive level in milliamperes for each pin being configured The valid values are DRIVELEVEL_3MA DRIVELEVEL_7MA DRIVELEVEL_13MA DRIVELEVEL_20MA ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the LED drive mode successfully Example include lt ez8 h gt char init _ports void open Port C in default input mode open PortC configure Port C pins for LED Drive mode 1 GPIOERR_INVALIDPINS setmodeLEDDrive PortC PORTPIN ALL DRIVELEVEL 13MA return 1 void write _L
38. default ZSL libraries are in ZS1F1680XXX 1ib files The following functions are placed in PRAM segment within each libraries ZS1F1680U0XXX 1ib void isr_UARTO RX void void isr_UARTO TX void ZS1F1680U1XXX 1ib void isr_UART1_RX void void isr_UART1_TX void Table 5 lists library files to place ISRs for UARTO in PRAM RM003805 0508 Zilog Standard Library API Reference Manual ZI Table 5 Library Files to place ISRs for F1680 Series UARTO in PRAM Library Name Description zSlF1680U0SY 1ib Drivers for applications with a Small memory model and using dYnamic frames no debug information speed optimization zS1F1680U0SYD 1ib Drivers for applications with a Small memory model and using dYnamic frames with Debug information no optimization zSl1F1680U0ST 1ib Drivers for applications with a Small memory model and using sTatic frames no debug information speed optimization zS1F1680U0STD 1ib Drivers for applications with a Small memory model and using sTatic frames with Debug information no optimization zSl1F1680U0LY 1ib Drivers for applications with a Large memory model and using dYnamic frames no debug information speed optimization zS1F1680U0LYD 1ib Drivers for applications with a Large memory model and using dYnamic frames with Debug information no optimization ZS1F1680U0LT 1ib Drivers for applications with a Large memory model and using sTatic frames no debug
39. each pin is controlled by setting each register bit pertinent to the pin to be configured The API also provides an option to set the type of triggering to either falling or rising edge along with the priority for the interrupt For example to set Pin 1 of Port A to falling edge with a low priority call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below char setmodeInterrupt_PortA_4K PORTPIN ONE EDGE FALLING INTPRIORITY_LOW Similarly more than one pin is set to interrupt mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into interrupt mode the API is used as given below setmodeInterrupt_PortA_4K PORTPIN FIVE PORTPIN_ SEVEN EDGE RISING INTPRIORITY LOW This API does not alter states of other pins ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual 47 Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file edge The type of edge triggering for the interrupts Valid values are EDGE_FALLING EDGE_RISING priority The priority of the interrupt The valid values are INTPRIORITY_LOW INTPRIORITY_NOMINAL INTPRIORITY_HIGH Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the interrupt
40. ect and invoke other script files add_gpio projectfiles scr and add_uart projectfiles scr to add all the source files relevant to the library Generating Make files From the project generated in step 1 make files for both debug and release versions are generated using a batch file and a ZDS II script file The batch file gen_zsl_project bat invokes a ZDS II script file gen_zsl1_makefiles scr to create both the debug and release versions of the make files Generating libraries The make files generated in step 2 are used along with ZDS II to finally generate the debug and release versions of the library The libraries are automatically copied to the repository under the lt ZDS installation dir gt lib zilog directory The batch file process _zsl_makefiles bat generates all the librar ies as listed in Table 3 on page 2 The batch file buildal1zs1 bat allows you to build all libraries for ZSL The ZSL fast call libraries register parameter passing are named with an extension F in the name For example the fast call lib for ZS1LY libis zsl1LYF liband zs1LYD libis zs1LYFD 1ib Also note that these libraries will be included automatically when register parameter passing is selected Startup Routine The ZSL is integrated with ZDS II which allows you to choose the device s required for the user application and also specifies some of the device dependent parameters Select Project gt Settings gt ZSL in
41. ed optimization ZS1F1680U1LTD 1ib Drivers for applications with a Large memory model and using sTatic frames with Debug information no optimization RM003805 0508 Zilog Standard Library API Reference Manual Zilog Zilog Standard Library Directory Structure Figure 2 displays the directory structure of ZSL Table 7 lists the files contained in each sub directory E AzS installation dir gt E 9 include 5 std zlog C 78Encore_FOdKa Ci 78Encore_FoaX i 78Encore_F640 5 z5Encore Fedex 3 lib Ei std i 2ilog E sre E C boot im common gpio E rtl y uart Figure 2 ZSL Directory Structure gt Note Figure 2 lt zps installation dir gt specifies the root directory of ZDS II installation for example ZDSII Z8 Encore 4 11 0 RM003805 0508 ZSL Overview Zilog Standard Library API Z8 Encore Family of Microcontrollers Table 7 ZSL Directory Structure Description Path Folder Description include Contains subfolders that contain the include files include std Contains all the header files relevant to the C Run Time Library RTL include zilog Contains header files relevant to ZSL device drivers include zilog lt seri Contains boot related files specific to each Z8 Encore es gt series lib Contains subfolders that contain the libraries files lib std Contains all the library files relevant to the C Run T
42. eries ports A B C D and H 4K Series Port A All other Z8 Encore devices Ports A B and C setmodelnterrupt_PortC Set Port C bits 0 to 3 bits to Interrupt mode All Z8 Encore devices Port C setmodelnterrupt_PortA_XP Set Port A bits to Interrupt mode setmodelnterrupt_PortA_8Pn Set Port A bits to Interrupt mode setmodelnterrupt_PortA_4K Set Port A bits to Interrupt mode setmodelnterrupt_PortA_F08 Set Port A bits to Interrupt mode 8 K series Port A setmodelnterrupt_Portx_F64 Set Port bits to Interrupt mode 64 K series ports A and D setmodelnterrupt_Portx_F1680 Set Port bits to Interrupt mode F1860 series ports A and D setmodeAltFuncSet1_Portx Set Port bits to Alternate Function Set 1 mode XP series ports B and C RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers zilo Table 10 ZSL Target Specific GPIO APIs Continued Description and Valid Z8 Encore API Name Devices Ports setmodeAltFuncSet2_Portx Set Port bits to Alternate Function Set 2 mode XP series ports B and C 4 K series ports B and C 8 Pin Devices Port A setmodeAltFuncSet3_PortA Set Port A bits to Alternate Function Set 3 mode 8 Pin Devices Port A setmodeAltFuncSet4_PortA Set Port A bits to Alternate Function Set 4 mode 8 Pin Devices Port A setmodeLEDDrive_PortC Set Port C bits
43. errupt_PortA_F08 PORTPIN ONE EDGE FALLING INTPRIORITY_ LOW Similarly more than one pin is set to interrupt mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into interrupt mode the API is used as given below setmodeInterrupt_PortA_F08 PORTPIN FIVE PORTPIN SEVEN EDGE RISING INTPRIORITY_ LOW RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file edge The type of edge triggering for the interrupts Valid values are EDGE_FALLING EDGE_RISING priority The priority of the interrupt The valid values are INTPRIORITY_LOW INTPRIORITY_NOMINAL INTPRIORITY_HIGH Return Value s GPIOERR_INVALIDPINS In debug mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the interrupt mode successfully Example include lt ez8 h gt pragma interrupt void isr_PA1 void char init _ports void Handle PA1 interrupt here open Port A in default mode open PortA set the interrupt vector for Port A bit one ZSL GPIO API Description RM003805 0508 RM003805 0508 Zilog Standard Library API Reference Manual zil gt i J gt 7 51 medi l SETV
44. formation on return values see Return Value s on page 93 Reading in Interrupt mode The data reception in INTERRUPT mode is asynchronous in nature In the INTERRUPT mode read_UARTx API uses the UARTx receive interrupt to read data bytes The read_UARTx API enables the receive interrupt of the UARTx device and returns immediately The data reading then happens in the interrupt service routine of the UARTx device The caller of the API determines the status of the read operation by using the API get_rxstatus_UARTx which returns ART_IO COMPLETE indicating the completion of the read operation or UART_IO_PENDING indicating that reading is still in progress If the API is compiled using UARTx_ERRORHANDLING macro any error in the received data byte is reported when get_rxstatus_UARTx is called ZSL UART API Description RM003805 0508 Argument s pData nbyte Return Value s Example Zilog Standard Library API Reference Manual ZILO g Pointer to a buffer to receive data s Pointer to an integer which indicates the number of bytes to read When the API returns this variable contains the actual number of bytes read However in INTERRUPT mode this value is valid only if get_rxstatus_UARTx returns UART_IO_ COMPLETE or any error return value listed on page 95 UART_ERROR_NONE Indicates that the read was successful UART_ERR_FRAMINGERR Indicates that a framing error occurred in the byte received U
45. g information no optimization ZS1F1680LT 1lib Drivers for applications with a Large memory model and using sTatic frames no debug information speed optimization ZS1F1680LTD 1lib Drivers for applications with a Large memory model and using sTatic frames with Debug information no optimization RM003805 0508 ZSL Overview Zilog Standard Library API Z8 Encore Family of Microcontrollers gt Note ZSL Overview Z8 Encore XP F1680 Series implements a new feature of user con trolled Program RAM PRAM area to store Interrupt Service Routines ISRs of high frequency interrupts The PRAM mechanism ensures low average current and quick response for high frequency interrupts To avail this feature the ISRs in ZSL UART must be provided with the option of being placed in the PRAM segment To enable this the ZDS II IDE pro vides a check box in ZSL tab named Place ISR into PRAM When you select this check box ZDS II addresses the library zs1F1680U0XXX 1ib or zs1F1680U1XXX lib or both to place ISRs for UARTO and UARTI in PRAM Place ISR into PRAM feature is effective only when the UART is set in interrupt mode To set the UART in interrupt mode edit the header file include zilog uartcontrol h by defining the symbol UARTO_MODE UART1_MODE as MODE INTERRUPT and rebuild the libraries For more information on rebuilding ZSL see Building the Zilog Standard Libraries on page 9 For Z8 Encore XP F1680 Series the
46. he calling application to perform other tasks when data reception is in progress The calling application then knows the status of the transmission by calling the get_rxstatus_UARTx API Argument s None Return Value s UART_IO_PENDING Indicates that data transmission in the UARTx device is still in progress UART_IO_COMPLETE Indicates that data transmission in the UARTx device is complete UART_ERR_FRAMINGERR Indicates that a framing error occurred in the byte received UART_ERR_PARITYERR Indicates that a parity error occurred in the byte received UART_ERR_OVERRUNERR Indicates an overrun error occurred in the byte received UART_ERR_BREAKINDICATION Indicates that a break condition is set RM003805 0508 ZSL UART API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers ZILOG close_UARTx Prototype void close UARTx void Description The close UARTx API is used to close the UARTx device Calling this API disables the interrupts related to the default UART device and clears all the control registers to render the UART device non functional after the call The user application uses the UART again only after mak ing a call to the open_UARTx API Argument s None Return Value s None ZSL UART API Description RM003805 0508 Index Symbols _ZSL_DEVICE_PORTx macro 13 A abbreviations vii about this manual v alternate function mode GPIO
47. he pin to be configured For example the alternate function set 3 mode for Port A Pin 7 PA7 is set by the values contained in registers PA_ADDR and PA_CTL 7 To set Pin 1 of Port A into alternate function set 3 mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeAltFuncSet3 PortA PORTPIN ONE Similarly more than one pin is set to alternate function set 1 mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into alternate function mode the API is used as given below setmodeAltFuncSet3 PortA PORTPIN FIVE PORTPIN SEVEN gt Note This API does not alter states of other pins Alternate function mode set 3 is supported only in Port A of the Z8F04 8 pin devices ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In debug mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the alternate function mode successfully Example include lt ez8 h gt char init _ports void open Port A in default mode open PortA configure Port A pin 3 for alternate function set 3 mode if GPIOERR_INVALIDPINS
48. i lt ic2sd20c00e Lodwavarene segs eda Vv Related Documents 0 020200 eee ee ee eee vi Abbreviations and Expansion 22200055 vii Conventions 4 uvisk Gadd kokere paipu ot ke n ee ea viii Safeguards oie ce Sine Fixes erate wena a Sea gonctee ee racaciiea oracgok da teel viii Online Information 0 0000 eee eee ix ZSL OVEIVICOW ices ose eb eee Serie ecawieee aes e aad wm acne 1 Zilog Standard Library Architecture 045 1 Zilog Standard Library Directory Structure 7 Building the Zilog Standard Libraries 9 Startup Routine 0 0 0 ce 10 Zilog Standard Library API Overview 11 ZSL GPIO API Description 000 13 GPIO Port Initialization in the Startup Routine 13 BGAOF PIG 3 s soa sh tipio whan nee aed Sead a a ea E E 14 ZSL GPIO Macros anaana 70 ZSL UART API Description 0000 ee ee eee eee 72 UART Initialization in the Startup Routine 72 Generic UART APIs 0000 cece eee 75 UARIXAPIS sain anene ee teeeredoeed E Beason Desa aes 79 INGOX ois Se eee ee eet es Eee ak bebe eae wie ars 97 Customer Support 00 eee 101 Table of Contents RM003805 0508 Zilog Standard Library API Reference Manual Introduction This reference manual describes Zilog Standard Library ZSL and ZSL application programming interfaces APIs ZSL is avai
49. ices ZSL provides a compile time control to enable or disable DMA for data transmission For more information see write UARTx API on page 88 5 Modify the default values to suit user application specifications by making appropriate changes in the device specific source code files All the compile time configurations are listed in uartcontrol h file Table 12 on page 74 summarizes the compile time options avail able If any of these parameters are modified the library must be rebuilt RM003805 0508 ZSL UART API Description 74 Zilog Standard Library API Z8 Encore Family of Microcontrollers Zilog Table 12 ZSL UART API Compile Time Options Parameter UARTx_MODE Description Default value Selects the UARTx mode of operation MODE POLL either asynchronous interrupt or synchronous poll For more details see read_UARTx and write_UARTx APIs Valid values are MODE_INTERRUPT Interrupt mode MODE _POLL Polling mode DMA1 CTL Enables DMA1 to be used with the DMA _ DISABLED specified UART during data transmission by write_UARTx This option is only used in interrupt mode Valid values are DMA_UARTO Use UARTO with DMA1 DMA_UART1 Use UART1 with DMA1 DMA_DISABLED Do not use DMA gt Note DMA is available only on EZ8F64XX series MCUs UARTX_BAUDRATE Baud rate to be used for UARTx BAUD_38600 communication The valid values are listed in the uart h file UARTX_STOPBITS Num
50. ime Library RTL lib zilog Contains all the library files relevant to the device drivers sre Contains subfolder which contains source for each of the device sre boot common Contains boot related files common to all targets src lt device gt common Contains device related files common to all targets Note lt series gt denotes the Z8 Encore series lt device gt denotes the on chip peripheral device for example GPIO or UART ZSL Overview RM003805 0508 Zilog Standard Library API Reference Manual ZSL Debug and Release Version There are two ZSL versions the debug and release version available for each Z8 Encore on chip peripheral or device The debug version of the library is built to contain debug information without any optimizations whereas the release version is built to contain no debug information and is optimized for speed The debug version of the library is built with the macro DEVICE PARAMETER _CHECKING defined where DEVICE is any device such as UART or GPIO which is used by some of the APIs to check for the validity of the parameters passed This macro is absent in ZSL release version which does not perform any check on the API parameters Thus there is a significant difference in overall size of the generated library from the two versions See individual APIs in this man ual to check whether an API uses the DEVICE_PARAMETER_CHECKING macro or not Building the Zilog Standard Librarie
51. ion RM003805 0508 Zilog Standard Library API Reference Manual Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the alternate function mode successfully Example include lt ez8 h gt char init _ports void open Port A in default mode open PortA configure Port A pin 3 for alternate function set 4 mode if GPIOERR_INVALIDPINS setmodeAltFuncSet4 PortA PORTPIN THREE return 1 Port A pin 3 is now available for alternate function set 4 mode Namely Analog Functions for pin 3 RM003805 0508 ZSL GPIO API Description 68 Zilog Standard Library API Z8 Encore Family of Microcontrollers 9 IIt A AN Baere BGS YY setmodeLEDDrive_PortC Prototype char setmodeLEDDrive PortC uchar pins byte drivelev els Description The setmodeLEDDrive PortC API is used to configure one or more pins of the GPIO Port C of Z8 Encore microcontroller to LED drive mode The mode for each pin is controlled by setting each register bit per tinent to the pin to be configured This API also gives an option to set the current drive levels for each pin configured For example to set pin 7 into LED drive mo
52. it pertinent to the pin to be configured For example to set Pin 1 of Port C into interrupt mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below char setmodeInterrupt_PortC PORTPIN FIVE INTPRIORITY NOMINAL Similarly more than one pin is set to alternate function mode by ORing the pins the API call For example to set Pin 5 and Pin 7 of Port C into interrupt mode the API is used as given below setmodeInterrupt_PortC PORTPIN FIVE PORTPIN SEVEN INTPRIORITY HIGH 1 RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file priority The priority of the interrupt The valid values are INTPRIORITY_LOW INTPRIORITY_NOMINAL INTPRIORITY_HIGH Return Value s GPIOERR_INVALIDPINS In debug mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_ SUCCESS Indicates that the port was configured to the Example interrupt mode successfully include lt ez8 h gt pragma interrupt void isr_PC1 void Handle PC1 interrupt here char init _ports void open Port C in default mode open PortC set the interrupt vector for Port C bit one SETVECTOR PCl_ IVECT isr_PC1 1 configure Po
53. it Zilog s Technical Support at http support zilog com RM003805 0508 Customer Support
54. it corresponding to the pin by using the definitions in gpio h as given below setmodeHighDrive PortA PORTPIN ONE Similarly more than one pin is set to input mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into input mode the API is used as given below setmodeHighDrive PortA PORTPIN FIVE PORTPIN SEVEN gt Note This API does not alter states of other pins ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the high drive mode successfully Example include lt ez8 h gt char init _ports void open Port A in default mode open PortA configure Port A pins for high drive mode if GPIOERR_INVALIDPINS setmodeHighDrive PortA PORTPIN ALL return 1 open Port B in default input mode open PortB configure Port B pins for high drive mode if GPIOERR_INVALIDPINS setmodeHighDrive PortB PORTPIN ALL return 1 void write ports void RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers
55. lable as part of the Zilog Developer Studio II Integrated Development Environment ZDS I IDE v4 11 0 release for Zilog s Z8 Encore product line of microcontrollers ZSL is a set of library files that provides an interface between user appli cation and on chip peripherals of Z8 Encore microcontrollers Z8 Encore XP products include F64XX F0822 F042A series of micro controllers with 1 KB to 64 KB memory sizes About This Manual Zilog recommends you to read and understand this manual completely before using the product This manual is designed to be used as a refer ence guide for ZSL APIs Intended Audience This document provides relevant information on ZSL implementation This reference manual serves as a guide for interfacing the user applica tion with on chip peripherals of the Z8 Encore microcontrollers Manual Organization This manual is divided into three chapters as described briefly below ZSL Overview This chapter provides an overview of ZSL ZSL directory structure and ZSL release and debug versions ZSL GPIO API Description This chapter provides information on how to interface a user application with the Z8 Encore microcontroller GPIO peripheral and details of the APIs provided to interface with it RM003805 0508 Introduction Zilog Standard Library API Z8 Encore Family of Microcontrollers ZSL UART API Description This chapter provides information on how to interface a user application with
56. les provided with ZSL release to modify the libraries to suit specific requirements Zilog Standard Library Architecture Figure 1 displays a block diagram of ZSL architecture User Application Zilog Standard Library On Chip Peripherals UART GPIO Figure 1 Block Diagram of ZSL Architecture RM003805 0508 ZSL Overview Zilog Standard Library API Z8 Encore Family of Microcontrollers ZSL for Z8 Encore consists of various libraries each of which is used for a specific memory model and configuration Table 3 describes each of these libraries Table 3 Z8 Encore ZSL Constituent Libraries Library Name Description zslSY lib Drivers for applications with a Small memory model and using dYnamic frames no debug information speed optimization zslSYD 1ib Drivers for applications with a Small memory model and using dYnamic frames with Debug information no optimization zslST 1lib Drivers for applications with a Small memory model and using sTatic frames no debug information speed optimization zslSTD 1lib Drivers for applications with a Small memory model and using sTatic frames with Debug information no optimization zslLY 1lib Drivers for applications with a Large memory model and using dYnamic frames no debug information speed optimization zslLYD 1ib Drivers for applications with a Large memory model and using dYnamic frames with Debug information no optimization zslL
57. lid values 9600 19200 38400 rate 57600 115200 gt Note Not all devices in the Z8 Encore family work with all the abov baud rates Check the appropriate device documentation for working values Return Value s UART_ERROR_NONE No error UART_ERR_INVBAUDRATE Error due to invalid baud rate value passed Example include lt ez8 h gt void init devices void UART uart ZSL UART API Description RM003805 0508 RM003805 0508 Zilog Standard Library API Reference Manual ZILOd ss char stat UART_ERR_NONE configure UARTO with 9600 baud 1 stop bits and no parity uart baudRate BAUD_9600 uart stopBits STOPBITS 1 uart parity PAR _NOPARITY Configure the UART stat control _UARTO amp uart if UART_ERR_NONE stat Change the baud rate to 115200 stat setbaud_UARTO BAUD 115200 if UART_ERR_NONE stat close UARTO j return return ZSL UART API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers Zilog setparity_UARTx Prototype uchar setparity UARTx uchar parity Description The setparity_UARTx API configures the parity for the UARTx device If the debug version of ZSL is used the API checks the validity of the parameters passed Otherwise the API configures the UARTx with the value passed in the parity parameter For more information see ZSL Debug and Release Version on
58. ly UART_ERR_BUSY_ Transmission is already in progress The UARTx device is still servicing a previous write UARTx Call at the time when this write UARTx Call is made Example include lt ez8 h gt int compute _sum int int char msg Welcome to the world of Encore microcontrollers from ZiLOG void init int vall val2 UART uart char stat UART_ERR_NONE configure UARTO with 9600 baud 1 stop bits and no parity uart baudRate BAUD_9600 uart stopBits STOPBITS 1 uart parity PAR _NOPARITY Configure the UART stat control UARTO amp uart if UART_ERR_NONE stat return 1 f write UARTO msg strlen msg UART_ERROR_NONE if compute_sum vall val2 gt 10 RM003805 0508 ZSL UART API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers 90 ES close UARTO j ZSL UART API Description Update global variable global_threshold Now check whether the transmission is complete while UART_IO PENDING S5 get_txstatus_UARTO 10 RM003805 0508 Zilog Standard Library API Reference Manual get_txstatus_UARTx Prototype uchar get_txstatus_UARTx void Description The get_txstatus UARTx API is used to get the status of asynchronous data transmission in the UARTx device This API must be called by the application to know the status of the data transmission during INTERRUPT mode transfers Du
59. ly of Microcontrollers ZIlog ZSL UART API Description This chapter provides detailed descriptions of Zilog Standard Library ZSL UART APIs To use ZSL UART APIs the header file ez8 h must be included in the application program The ez8 h file is placed in the include zilog folder under the root installation directory as displayed in Figure 2 on page 7 The application must also include the uart h file UART Initialization in the Startup Routine ZSL is integrated with ZDS II allowing you to select or deselect Z8 Encore MCU UARTs see Startup Routine on page 10 When initializing the UART devices in the Startup routine the following points must be considered l When a UART device is selected in ZDS II interface using Project Settings gt ZSL the ZDS II generates a compiler pre define _ZSL_DEVICE_UARTx for open periphdevice routine The open periphdevice routine uses open_UARTx function to initialize the UARTx device with default values when the _ZSL_DEVICE_UARTx symbol is supplied Therefore the user appli cation program uses the APIs directly to drive any UART device without making a specific call to the init _UARTx routine To use the UARTO device GPIO Port A is required to be initialized UARTI device requires Port D to be initialized These GPIO ports must be initialized before initializing the UART ZDS II defines the macro ZSL DEVICE _PORTD when UARTO0 is selected and _ZSL_DEVICE_POR
60. ly of Microcontrollers Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file edge The type of edge triggering for the interrupts Valid values are EDGE_FALLING EDGE_RISING priority The priority of the interrupt The valid values are INTPRIORITY_LOW INTPRIORITY_NOMINAL INTPRIORITY_HIGH Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the interrupt mode successfully Example include lt ez8 h gt pragma interrupt void isr_PA1 void pragma interrupt void isr_PD2 void Handle PA1 interrupt here Handle PD2 interrupt here ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual ZIlOd char init _ports void RM003805 0508 open Port A in default mode open PortA set the interrupt vector for Port A bit one SETVECTOR PA1 IVECT isr_PA1 configure Port A pin 1 for interrupt mode i GPIOERR_INVALIDPINS setmodeInterrupt_PortA_F1680 PORTPIN_ ONE EDGE FALLING INTPRIORITY_HIGH return 1 open port D in default mode open PortD set the interrupt vector for port D bit two SETVECTOR PD2_IVECT isr_PD2 configure port D pin 2 for interrupt mode if
61. mode In POLL mode the data transmission is synchronous in nature In POLL mode the write _UARTx API transmits the data bytes by polling on the UARTx transmit register The API does not return until all the bytes are transmitted Writing in Interrupt mode The data transmission in INTERRUPT mode is asynchronous in nature In INTERRUPT mode write _UARTx API uses the UARTx transmit interrupt to transmit the data bytes The write _UARTx API simply enables the transmit interrupt and returns immediately The data transfer then takes place in the interrupt service routine of the UARTx device The caller of the API determines the status of the write operation by using get_txstatus_ UARTx which returns either UART_IO PENDING or UART_IO_ COMPLETE depending on the transmission status If the API is compiled by enabling Direct Memory Access DMA for data transmission then the write _UARTx API uses DMA for data transfer Now the write UARTx API sets up the DMA registers for transmission of data and returns immediately The completion of data transfer is indicated by a DMA interrupt to the caller in the form of UART_IO_COMPLETE when a call to get_txstatus_UARTx is made ZSL UART API Description RM003805 0508 Zilog Standard Library API Reference Manual 89 Argument s pData Pointer to a buffer containing the data to transmit nbytes Number of bytes to transmit Return Value s UART_ERR_NONE_ The data is transmitted successful
62. nts the selected GPIO Port RM003805 0508 Zilog Standard Library API Reference Manual ZILO g 48 ZSL GPIO API Description This chapter provides detailed descriptions of the Zilog Standard Library ZSL general purpose input output GPIO APIs To use ZSL GPIO APIs the file gpio h must be included in the applica tion program GPIO Port Initialization in the Startup Routine ZSL is integrated with ZDS II allowing you to select or deselect Z8 Encore MCU GPIO ports see Startup Routine on page 10 When a GPIO port is selected in ZDS II interface using Project Settings gt ZSL ZDS II generates a compiler pre define ZSL_ DEVICE _PORTx where x is any one of the A B C D E F G or H GPIO ports ZDS II also adds a device initialization file zsldevinit asm into the user project The zsldevinit asm file uses compiler pre defines macros to initialize the ports to their default state The function _open_ periphdevice in zsldevinit asm calls the ZSL GPIO API open_Portx function for each of the ports selected from within the ZDS II interface RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers GPIO APIs Z8 Encore family of microcontrollers support eight different ports named Port A through Port H However not all the ports are available on all devices in the Z8 Encore family A given port can have different features on different devices So there are
63. o the pin by using the definitions in gpio h as given below setmodePullUp PortA PORTPIN ONE Similarly more than one pin is set to pull up mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into pull up mode the API is used as given below setmodePullUp PortA PORTPIN FIVE PORTPIN_SEVEN gt Notes 1 This API does not alter states of other pins 2 Pull up mode is supported only in Ports A B and C of the Z8 Encore F08 Series and in Ports A B C and D of the Z8 Encore XP Series Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the pull up mode successfully Example include lt ez8 h gt char init _ports void open Port A in default mode open PortA configure Port A pins for weak pull up mode if GPIOERR_INVALIDPINS setmodePullUp_ PortA PORTPIN ALL open Port B in default input mode open PortB return 1 configure Port B pins for weak pull up mode if GPIOERR_INVALIDPINS setmodePullUp PortB PORTPIN ALL return
64. open PortA configure Port A pins for input mode if GPIOERR_INVALIDPINS setmodeInput_PortA PORTPIN ALL return 1 open Port B in default input mode open PortB configure Port B pins for input mode if GPIOERR_INVALIDPINS setmodeInput_PortB PORTPIN ALL return 1 void get_ports void ZSL GPIO API Description RM003805 0508 RM003805 0508 Zilog Standard Library API Reference Manual fl a fN Z ILOU 24 Read Port A pins datal PAIN Read Port B pins data2 PBIN ZSL GPIO API Description 22 Zilog Standard Library API Z8 Encore Family of Microcontrollers 77 IIt A AN ELJI B amp Q YY setmodeOutput_Portx Prototype char setmodeOutput_Portx uchar pins Description The setmodeOutput_Portx API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the output mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the output mode for Port A Pin 7 PA7 is set by the values contained in registers PA ADDR and PA _CTL 7 To set Pin 1 of Port A into output mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeOutput_PortA PORTPIN ONE Similarly more than one pin is set to output mode by ORing the pins in the API call For example to se
65. pe char setmodeOpendrain Portx uchar pins Description The setmodeOpendrain_Portx API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the open drain mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the open drain mode for Port A Pin 7 PA7 is set by the values contained in registers PA ADDR and PA _CTL 7 To set Pin 1 of Port A into open drain mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeOpendrain PortA PORTPIN ONE Similarly more than one pin is set to input mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into input mode the API is used as given below setmodeOpendrain_PortA PORTPIN_FIVE PORTPIN_SEVEN gt Note This API does not alter states of other pins RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers r 26 Z l O g Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the open drain mode successfully Example include lt ez8 h gt
66. pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the alternate function mode successfully Example include lt ez8 h gt char init _ports void open Port C in default mode open PortC configure Port C pin 3 for alternate function set 1 mode if GPIOERR_INVALIDPINS setmodeAltFuncSet1 PortC PORTPIN_ THREE return 1 Port C pin 3 is now available for alternate function set 1 mode Namely COUT for pin 3 af open Port B in default input mode open PortB RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers 60 Z ILO g P configure Port B pin 3 for alternate function set 1 mode if GPIOERR_INVALIDPINS setmodeAltFuncSet1 PortB PORTPIN_THREE return 1 Port B pin 3 is now available for alternate function set 1 mode Namely CLKIN for pin 3 ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual setmodeAltFuncSet2_Portx Prototype char setmodeAltFuncSet2 Portx uchar pins Description gt Note The setmodeAltFuncSet2_Portx API is used to configure one or more
67. ring INTERRUPT mode data transmission write UARTx API returns immediately allowing the calling application to perform other tasks while the data transmission is in progress The calling application then knows the status of the transmis sion by calling the get_txstatus_UARTx API Argument s None Return Value s UART_IO PENDING Indicates that data transmission in the UARTx device is still in progress UART_IO COMPLETE Indicates that data transmission in the UARTx device is complete Example For more information see the example for write UARTx on page 88 RM003805 0508 ZSL UART API Description 92 Zilog Standard Library API Z8 Encore Family of Microcontrollers j A AN Z i l U l I read_UARTx Prototype uchar read_UARTx char pData uint16 nbytes Description The read_UARTx API reads data bytes from the UARTx device This API accepts a pointer to a buffer for storing data bytes received and the number of bytes to be read The API behaves differently depending on the mode in which the UARTx device is configured as follows Reading in Poll mode In poll mode the data reception is synchronous in nature In the poll mode the read_UARTx API receives the data bytes by polling the UARTx receive register The API does not return until all the bytes are received If the API is compiled using the UARTx_ERRORHANDLING macro any error in the communication is reported as a return value For more in
68. rive_Portx 28 setmodeInput_Portx API 19 setmodelInterrupt PortA F08 49 setmodelInterrupt PortC 37 setmodelInterrupt Portx_F64 52 55 setmodelInterrupt_Portx_XP 40 43 46 setmodeLEDDrive PortC 68 setmodeOpendrain_ Portx 25 setmodeOutput_Portx 22 setmodePullUp_Portx 33 setmodeStopRecovery_ Portx 31 setparity UARTx API 86 setstopbits UARTx API 87 specific GPIO APIs 14 speed optimization 2 3 5 6 startup routine 10 static frames 2 3 5 6 status asynchronous read 95 asynchronous write 91 stop bits 74 87 stop recovery mode GPIO 31 Index Zilog Standard Library API Z8 Encore Family of Microcontrollers subfolders 8 synchronous poll mode compile option 74 overview 73 read UART 92 write UART 88 T terminology vii U UART API overview 72 UART defaults 73 UART options 73 74 UARTx APIs 79 UARTXx control registers 80 UART Initialization 72 user defined types 11 W write UARTx API 88 Z zdsroot directory 7 Zilog standard library 1 Zilog TCP IP Software Suite 101 ZSL GPIO macro definitions 70 zsXXXX lib library files 2 3 5 6 Index RM003805 0508 Zilog Standard Library API Reference Manual Customer Support For answers to technical questions about the product documentation or any other issues with Zilog s offerings please visit Zilog s Knowledge Base at http www zilog com kb For any comments detail technical questions or reporting problems please vis
69. rt C pin 1 for interrupt mode ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual ie ZILOOG a 39 i1 GPIOERR_INVALIDPINS setmodeInterrupt PortC PORTPIN ONE INTPRIORITY HIGH return 1 RM003805 0508 ZSL GPIO API Description 40 Zilog Standard Library API Z8 Encore Family of Microcontrollers 4 a I A FN ITAN Z L U g setmodelnterrupt_PortA_XP Prototype char setmodeInterrupt_PortA_XP uchar pins uchar edge uchar priority Description gt Note The setmodeInterrupt_PortA_XP API is used to configure one or more pins of GPIO Port A on the Z8 Encore Z8F04 XP Series of microcontroller to the interrupt mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured The API also provides an option to set the type of triggering to either falling or rising edge along with the priority for the interrupt For example to set Pin 1 of Port A to falling edge with a low priority call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below char setmodeInterrupt_PortA_XP PORTPIN ONE EDGE FALLING INTPRIORITY_LOW Similarly more than one pin is set to interrupt mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into interrupt mode the API is used as given below setmodeInterrupt_PortA_XP PORTPIN FIVE PORT
70. s You can develop applications using the APIs provided for specific peripherals and make use of the Zilog Standard Library to interface with the peripherals on the Z8 Encore microcontrollers However for those who require to customize the library files by modifying the source code this section describes how the modified library is built using the batch files and ZDS II script files As a general rule when the batch files are executed the libraries for each on chip peripheral or device are rebuilt and copied into the lt ZDS installation dir gt lib zilog folder The source directory con tains one single batch file to build all the libraries of all the devices Fol low the steps below to build the library 1 Generating ZDS II project file In this step a ZDS II project is created for the specific target microcontroller using a ZDS II script file The script file used for this purpose has the same name as the calling batch file with a scr extension The script file creates a ZDS II project and configures the project settings for both the debug RM003805 0508 ZSL Overview 10 Zilog Standard Library API Z8 Encore Family of Microcontrollers gt Notes 1 and release versions of the library The script then calls other script files to add all source files of different devices that make the library So the batch file gen_zsl_ project bat generates the project file It calls gen_zsl_project scr script file to create ZDS II proj
71. s viii high drive mode GPIO 28 include files 8 initialization routines 11 initialization GPIO port 13 Index initialization UART 72 input mode GPIO 19 interrupt mode compile option 74 F08 GPIO 49 F64 GPIO 52 55 GPIO port C 37 overview 73 read status 95 read UART 92 write status 91 write UART 88 XP GPIO 40 43 46 interrupt priority 75 K kbhit API 78 keystrokes 78 L LED drive mode GPIO 68 library 2 3 5 6 library files 2 3 5 6 8 macro definitions GPIO 70 make files 10 manual about v memory model 2 3 5 6 RM003805 0508 O online information ix open drain mode GPIO 25 open_Portx API 17 open UARTx API 80 optimization 2 3 5 6 options UART compile time 73 74 organization manual v output mode GPIO 22 overview UART 72 Zilog standard library 1 P parameter checking 9 parity 74 86 pins GPIO configure 19 poll mode compile option 74 overview 73 read UART 92 write UART 88 port initialization 13 power down up precautions ix priority interrupt 75 project file 9 pull up mode GPIO 33 putch API 77 R read_UARTx API 92 related documents vi RM003805 0508 Zilog Standard Library API Reference Manual j A N Z I LOC g 99 m release version 9 repository ZSL 10 root directory 7 S safeguards viii script files 9 setbaud UARTx API 84 setmodeAltFunc_Portx 35 setmodeAltFuncSetl_Portx 58 setmodeAltFuncSet2_Portx 61 64 66 setmodeHighD
72. t Pin 5 and Pin 7 of Port A into output mode the API is used as given below setmodeOutput_PortA PORTPIN FIVE PORTPIN SEVEN ye gt Note This API does not alter states of other pins ZSL GPIO API Description RM003805 0508 Argument s pins Zilog Standard Library API Reference Manual The bitwise ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the Example output mode successfully include lt ez8 h gt char init _ports void RM003805 0508 open Port A in default mode open PortA configure Port A pins for output mode if GPIOERR_INVALIDPINS setmodeOutput_PortA PORTPIN ALL return 1 open Port B in default input mode open PortB configure Port B pins for output mode if GPIOERR_INVALIDPINS setmodeOutput_PortB PORTPIN ALL return 1 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers a ZILOG void write _ports void Write to Port A pins PAOUT datal Write to Port B pins PBOUT data2 ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual setmodeOpendrain_Portx Prototy
73. ting from l 2 electrostatic discharge ESD Power up precautions a Apply power to the PC and ensure that it is running properly b Start the terminal emulator program on the PC c Apply power through the appropriate connector on the development platform Power down precautions a Quit the monitor program b Remove power from the development platform Online Information Zilog website provides valuable product information documentation and downloads of the latest production released version of the ZDS II devel opment tool The following documents are available for download at www zilog com RM003805 0508 Product Specifications User Manuals Application Notes Reference Manuals Product Briefs Introduction Zilog Standard Library API Reference Manual ZSL Overview This chapter provides an overview of Zilog Standard Library ZSL ZSL architecture debug and release versions of ZSL and how to build librar ies using the batch script files The startup routine and a summary of ZSL APIs are also included in this chapter ZSL for Z8 Encore is a set of library files which contains device driver APIs to program various on chip peripherals of Z8 Encore microcontrol ler Each library contains device drivers which allow you to communicate with on chip peripherals or devices without much knowledge of their reg ister and programming details ZSL APIs are easy to use refer to the source code fi
74. to LED Drive mode XP series Port C ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual open_Portx Prototype void open _Portx Description The open_Portx API opens the selected port by initializing the port registers to input mode The appropriate port register values are defined in the gpio h file Argument s None Return Value s None Example include lt ez8 h gt void init _ports void open Port A in default input mode open PortA open Port B in default input mode open PortB void get_ports void Read Port A pins datal PAIN Read Port B pins data2 PBIN RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers Zilog control_Portx Prototype void control_Portx PORT pPort Description The control_Portx API sets the values of the selected port registers by using the values in the PORT structure parameter This API is used to set all the registers of the port at one time To set individual registers the predefined macros defined in the gpio h file are used Argument s pPort A pointer to the structure of type PORT defined in the gpio h file Return Value s None ZSL GPIO API Description RM003805 0508 Zilog Standard Library API Reference Manual setmodelnput_Portx Prototype char setmodeInput_Portx
75. uchar pins Description The setmodeInput_Portx API is used to configure one or more pins of the selected GPIO port of Z8 Encore microcontroller to the input mode The mode for each pin is controlled by setting each register bit pertinent to the pin to be configured For example the input mode for Port A Pin 7 PA7 is set by the values in the registers PA_ADDR and PA CTL 7 To set Pin 1 of Port A into input mode call this API by specifying the bit corresponding to the pin by using the definitions in gpio h as given below setmodeInput_PortA PORTPIN ONE Similarly more than one pin is set to input mode by ORing the pins in the API call For example to set Pin 5 and Pin 7 of Port A into input mode the API is used as given below setmodeInput_PortA PORTPIN FIVE PORTPIN SEVEN F gt Note This API does not alter states of other pins RM003805 0508 ZSL GPIO API Description Zilog Standard Library API Z8 Encore Family of Microcontrollers r 20 Z l O g Argument s pins The bitwise ORed value indicating the pins of a port as defined in the gpio h file Return Value s GPIOERR_INVALIDPINS In DEBUG mode on some of the ports this value indicates that one or more pins specified are not supported for that target GPIOERR_SUCCESS Indicates that the port was configured to the input mode successfully Example include lt ez8 h gt char init _ports void open Port A in default mode
76. zilog Z8 Encore Family of Microcontrollers Zilog Standard Library API Reference Manual RM003805 0508 Copyright 2008 by Zilog Inc All rights reserved Zilog Standard Library API Z8 Encore Family of Microcontrollers A N Warning DO NOT USE IN LIFE SUPPORT LIFE SUPPORT POLICY ZILOG S PRODUCTS ARE NOT AUTHORIZED FOR USE AS CRITICAL COMPO NENTS IN LIFE SUPPORT DEVICES OR SYSTEMS WITHOUT THE EXPRESS PRIOR WRITTEN APPROVAL OF THE PRESIDENT AND GENERAL COUNSEL OF ZILOG CORPORATION As used herein Life support devices or systems are devices which a are intended for surgical implant into the body or b support or sustain life and whose failure to perform when properly used in accordance with instructions for use provided in the labeling can be reasonably expected to result in a significant injury to the user A critical component is any compo nent in a life support device or system whose failure to perform can be reasonably expected to cause the failure of the life support device or system or to affect its safety or effectiveness Document Disclaimer 2008 by Zilog Inc All rights reserved Information in this publication concerning the devices applications or technology described is intended to suggest possible uses and may be superseded ZILOG INC DOES NOT ASSUME LIABILITY FOR OR PRO VIDE A REPRESENTATION OF ACCURACY OF THE INFORMATION DEVICES OR TECHNOLOGY DESCRIBED IN THIS DOCUMENT ZILOG ALSO DOES

Z8 Encore! ZiLOG Standard Library API Reference Manual

Contents

Download Pdf Manuals

Related Search

Related Contents