Application Note AND9382/D LibMF (AX8052 Support Library) Software Manual Revision 2 2 TA B L E OF CONTENTS 1.Introduction........................................................................................................... 7 2.Microprocessor Functions......................................................................................... 7 2.1.ax8052.h, ax8052f131.h, ax8052f142.h, ax8052f143.h, ax8052f151.h...................7 2.2.ax8052regaddr.h..............................................................................................8 2.3.libmftypes.h.................................................................................................... 8 2.3.1.LIBMFVERSION..........................................................................................8 2.3.2.__code, __data, __xdata, __pdata, __generic...............................................8 2.3.3.int8_t, int16_t, int32_t uint8_t, uint16_t, uint32_t........................................8 2.3.4.void delay(uint16_t us)..............................................................................8 2.3.5.uint16_t random(void) uint16_t __data random_seed....................................8 2.3.6.uint8_t hweight8(uint8_t x) uint8_t hweight16(uint16_t x) uint8_t hweight32(uint32_t x)........................................................................................8 2.3.7.uint8_t parity8(uint8_t x) uint16_t parity16(uint16_t x) uint32_t parity32(uint32_t x)...........................................................................................9 2.3.8.uint8_t rev8(uint8_t x)..............................................................................9 2.3.9.int32_t signextend12(int16_t x) int32_t signextend16(int16_t x) int32_t signextend20(int32_t x) int32_t signextend24(int32_t x).......................................9 2.3.10.int16_t signedlimit16(int16_t x, int16_t lim) int32_t signedlimit32(int32_t x, int32_t lim).......................................................................................................9 2.3.11.uint8_t checksignedlimit16(int16_t x, int16_t lim) uint8_t checksignedlimit32(int32_t x, int32_t lim) ............................................................9 2.3.12.void wtimer_standby(void).......................................................................9 2.3.13.void enter_standby(void)..........................................................................9 2.3.14.void enter_sleep(void)..............................................................................9 2.3.15.void enter_sleep_cont(void)....................................................................10 2.3.16.void enter_deepsleep(void).....................................................................10 2.3.17.WRNUM_SIGNED, WRNUM_PLUS, WRNUM_ZEROPLUS, WRNUM_PADZERO, WRNUM_TSDSEP, WRNUM_LCHEX..................................................................... 10 2.4.libmfdbglink.h................................................................................................11 2.4.1.void dbglink_init(void) ............................................................................. 11 2.4.2.uint8_t dbglink_rx(void)...........................................................................11 2.4.3.void dbglink_tx(uint8_t v)........................................................................ 11 2.4.4.void dbglink_writestr(const char *ch).........................................................11 2.4.5.void dbglink_writehex16(uint16_t val, uint8_t nrdig, uint8_t flags) void dbglink_writehex32(uint32_t val, uint8_t nrdig, uint8_t flags) ...............................11 2.4.6.void dbglink_writenum16(uint16_t val, uint8_t nrdig, uint8_t flags) void dbglink_writenum32(uint32_t val, uint8_t nrdig, uint8_t flags) ............................. 12 2.4.7.uint8_t dbglink_txbuffersize(void) uint8_t dbglink_rxbuffersize(void).............12 2.4.8.uint8_t dbglink_rxcount(void)................................................................... 12 2.4.9.uint8_t dbglink_txfree(void)......................................................................12 2.4.10.uint8_t dbglink_txidle(void).................................................................... 12 2.4.11.void dbglink_wait_rxcount(uint8_t v)....................................................... 12 2.4.12.void dbglink_wait_txdone(void)...............................................................12 2.4.13.void dbglink_wait_txfree(uint8_t v)..........................................................12 2.4.14.void dbglink_rxadvance(uint8_t idx)........................................................ 12 2.4.15.void dbglink_txadvance(uint8_t idx).........................................................12 3 2.4.16.uint8_t dbglink_rxpeek(uint8_t idx).........................................................13 2.4.17.void dbglink_txpoke(uint8_t idx, uint8_t ch)............................................. 13 2.4.18.void dbglink_txpokehex(uint8_t idx, uint8_t ch)........................................ 13 2.4.19.uint8_t dbglink_poll(void) .......................................................................13 2.4.20.DBGLINK_DEFINE_TXBUFFER(sz) DBGLINK_DEFINE_RXBUFFER(sz).............13 2.5.libmfuart.h.................................................................................................... 13 2.5.1.void uart_timer0_baud(uint8_t clksrc, uint32_t baud, uint32_t clkfreq) void uart_timer1_baud(uint8_t clksrc, uint32_t baud, uint32_t clkfreq) void uart_timer2_baud(uint8_t clksrc, uint32_t baud, uint32_t clkfreq).........................13 2.6.libmfuart0.h, libmfuart1.h............................................................................... 14 2.6.1.void uart0_init(uint8_t timernr, uint8_t wl, uint8_t stop) void uart0_init(uint8_t timernr, uint8_t wl, uint8_t stop).......................................................................14 2.6.2.uint8_t uart0_rx(void) uint8_t uart1_rx(void)............................................. 14 2.6.3.void uart0_tx(uint8_t v) void uart1_tx(uint8_t v)........................................ 14 2.6.4.void uart0_writestr(const char *ch) void uart1_writestr(const char *ch).........15 2.6.5.void uart0_writehex16(uint16_t val, uint8_t nrdig, uint8_t flags) void uart0_writehex32(uint32_t val, uint8_t nrdig, uint8_t flags) void uart1_writehex16(uint16_t val, uint8_t nrdig, uint8_t flags) void uart1_writehex32(uint32_t val, uint8_t nrdig, uint8_t flags)................................. 15 2.6.6.void uart0_writenum16(uint16_t val, uint8_t nrdig, uint8_t flags) void uart0_writenum32(uint32_t val, uint8_t nrdig, uint8_t flags) void uart1_writenum16(uint16_t val, uint8_t nrdig, uint8_t flags) void uart1_writenum32(uint32_t val, uint8_t nrdig, uint8_t flags)................................ 15 2.6.7.uint8_t uart0_txbuffersize(void) uint8_t uart1_txbuffersize(void) uint8_t uart0_rxbuffersize(void) uint8_t uart1_rxbuffersize(void)..................................... 15 2.6.8.uint8_t uart0_rxcount(void) uint8_t uart1_rxcount(void) ..............................15 2.6.9.uint8_t uart0_txfree(void) uint8_t uart1_txfree(void) ...................................15 2.6.10.uint8_t uart0_txidle(void) uint8_t uart1_txidle(void)..................................16 2.6.11.void uart0_wait_rxcount(uint8_t v) void uart1_wait_rxcount(uint8_t v) ........16 2.6.12.void uart0_wait_txdone(void) void uart1_wait_txdone(void) .......................16 2.6.13.void uart0_wait_txfree(uint8_t v) void uart1_wait_txfree(uint8_t v)............16 2.6.14.void uart0_rxadvance(uint8_t idx) void uart1_rxadvance(uint8_t idx) ..........16 2.6.15.void uart0_txadvance(uint8_t idx) void uart1_txadvance(uint8_t idx) ..........16 2.6.16.uint8_t uart0_rxpeek(uint8_t idx) uint8_t uart1_rxpeek(uint8_t idx) ...........16 2.6.17.void uart0_txpoke(uint8_t idx, uint8_t ch) void uart1_txpoke(uint8_t idx, uint8_t ch)......................................................................................................17 2.6.18.void uart0_txpokehex(uint8_t idx, uint8_t ch) void uart1_txpokehex(uint8_t idx, uint8_t ch)................................................................................................17 2.6.19.uint8_t uart0_poll(void) uint8_t uart1_poll(void) .......................................17 2.6.20.UART0_DEFINE_TXBUFFER(sz) UART1_DEFINE_TXBUFFER(sz) UART0_DEFINE_RXBUFFER(sz) UART1_DEFINE_RXBUFFER(sz)..............................17 2.7.libmfflash.h................................................................................................... 17 2.7.1.void flash_unlock(void)............................................................................ 17 2.7.2.void flash_lock(void)................................................................................17 2.7.3.int8_t flash_pageerase(uint16_t pgaddr)....................................................18 www.onsemi.com AND9382/D 4 2.7.4.int8_t flash_write(uint16_t waddr, uint16_t wdata)..................................... 18 2.7.5.uint16_t flash_read(uint16_t raddr)...........................................................18 2.7.6.uint8_t flash_apply_calibration(void)......................................................... 18 2.8.libmfradio.h...................................................................................................18 2.8.1.uint16_t radio_read16(uint16_t addr) uint32_t radio_read24(uint16_t addr) uint32_t radio_read32(uint16_t addr)................................................................ 18 2.8.2.void radio_write16(uint16_t addr, uint16_t d) void radio_write24(uint16_t addr, uint32_t d) void radio_write32(uint16_t addr, uint32_t d).................................... 19 2.8.3.uint8_t ax5031_reset(void) uint8_t ax5042_reset(void) uint8_t ax5043_reset(void) uint8_t ax5051_reset(void)..................................................19 2.8.4.void ax5031_commsleepexit(void) void ax5042_commsleepexit(void) void ax5043_commsleepexit(void) void ax5051_commsleepexit(void)...........................19 2.8.5.void ax5031_comminit(void) void ax5042_comminit(void) void ax5043_comminit(void) void ax5051_comminit(void)...........................................19 2.8.6.void ax5031_rclk_enable(uint8_t div) void ax5042_rclk_enable(uint8_t div) void ax5043_rclk_enable(uint8_t div) void ax5051_rclk_enable(uint8_t div)...........19 2.8.7.void ax5042_rclk_disable(void) void ax5031_rclk_disable(void) void ax5043_rclk_disable(void) void ax5051_rclk_disable(void)................................... 20 2.8.8.void ax5043_enter_deepsleep(void)...........................................................20 2.8.9.uint8_t ax5043_wakeup_deepsleep(void)...................................................20 2.8.10.void ax5043_readfifo(uint8_t *ptr, uint8_t len)......................................... 20 2.8.11.void ax5043_writefifo(const uint8_t *ptr, uint8_t len) ................................20 2.9.libmfadc.h..................................................................................................... 20 2.9.1.int16_t adc_measure_temperature(void)....................................................20 2.9.2.uint16_t adc_singleended_offset_x1(void)..................................................21 2.10.libmfwtimer.h...............................................................................................21 2.10.1.uint32_t wtimer0_curtime(void) uint32_t wtimer1_curtime(void) ................23 2.10.2.void wtimer0_addabsolute(__xdata struct wtimer_desc *desc) void wtimer1_addabsolute(__xdata struct wtimer_desc *desc) void wtimer0_addrelative(__xdata struct wtimer_desc *desc) void wtimer1_addrelative(__xdata struct wtimer_desc *desc)......................................23 2.10.3.uint8_t wtimer0_remove(__xdata struct wtimer_desc *desc) uint8_t wtimer1_remove(__xdata struct wtimer_desc *desc) uint8_t wtimer_remove(__xdata struct wtimer_desc *desc)................................................................................ 23 2.10.4.void wtimer_add_callback(__xdata struct wtimer_callback *desc)................23 2.10.5.uint8_t wtimer_remove_callback(__xdata struct wtimer_callback *desc)......23 2.10.6.uint8_t wtimer_idle(uint8_t flags)............................................................23 2.10.7.uint8_t wtimer_runcallbacks(void)...........................................................24 2.10.8.uint8_t wtimer_cansleep(void)................................................................ 24 2.10.9.void wtimer0_setclksrc(uint8_t clksrc, unit8_t prescaler) void wtimer1_setclksrc(uint8_t clksrc, unit8_t prescaler).............................................24 2.10.10.void wtimer_init(void) .......................................................................... 24 2.11.libmfosc.h....................................................................................................24 2.11.1.void turn_off_xosc(void).........................................................................24 2.11.2.void turn_off_lpxosc(void)...................................................................... 24 2.11.3.void setup_xosc(void).............................................................................24 www.onsemi.com AND9382/D 5 2.11.4.void setup_lpxosc(void)..........................................................................24 2.11.5.uint8_t setup_osc_calibration(uint32_t reffreq, uint8_t refosc)....................25 2.11.6.setup_osc_calibration_const(reffreq,refosc)...............................................25 3.Convenience Functions...........................................................................................25 3.1.libmfbch.h.....................................................................................................25 3.1.1.uint16_t bch3121_syndrome(uint32_t cw)..................................................25 3.1.2.uint32_t bch3121_encode(uint32_t cw)......................................................26 3.1.3.uint32_t bch3121_encode_parity(uint32_t cw)............................................26 3.1.4.uint32_t bch3121_decode(uint32_t cw)......................................................26 3.1.5.uint32_t bch3121_decode_parity(uint32_t cw)............................................26 3.2.libmfcrc.h......................................................................................................26 3.2.1.uint8_t crc8_ccitt_byte(uint8_t crc, uint8_t c).............................................26 3.2.2.uint8_t crc8_ccitt(const uint8_t *buf, uint8_t len, uint8_t init) ......................26 3.2.3.uint8_t crc8_onewire_byte(uint8_t crc, uint8_t c)........................................26 3.2.4.uint8_t crc8_onewire(const uint8_t *buf, uint8_t len, uint8_t init) .................27 3.2.5.uint8_t crc_crc8ccitt_byte(uint8_t crc, uint8_t c).........................................27 3.2.6.uint8_t crc_crc8ccitt_msb_byte(uint8_t crc, uint8_t c).................................27 3.2.7.uint8_t crc_crc8onewire_byte(uint8_t crc, uint8_t c)....................................27 3.2.8.uint8_t crc_crc8onewire_msb_byte(uint8_t crc, uint8_t c)............................27 3.2.9.uint16_t crc_ccitt_byte(uint16_t crc, uint8_t c)...........................................27 3.2.10.uint16_t crc_ccitt_msb_byte(uint16_t crc, uint8_t c)..................................28 3.2.11.uint16_t crc_crc16_byte(uint16_t crc, uint8_t c)....................................... 28 3.2.12.uint16_t crc_crc16_msb_byte(uint16_t crc, uint8_t c)................................28 3.2.13.uint16_t crc_crc16dnp_byte(uint16_t crc, uint8_t c).................................. 28 3.2.14.uint16_t crc_crc16dnp_msb_byte(uint16_t crc, uint8_t c)...........................28 3.2.15.uint32_t crc_crc32_byte(uint32_t crc, uint8_t c)....................................... 28 3.2.16.uint32_t crc_crc32_msb_byte(uint32_t crc, uint8_t c)................................29 3.2.17.uint8_t crc_crc8ccitt(const uint8_t *buf, uint16_t buflen, uint8_t crc) uint8_t crc_crc8ccitt_msb(const uint8_t *buf, uint16_t buflen, uint8_t crc) uint8_t crc_crc8onewire(const uint8_t *buf, uint16_t buflen, uint8_t crc) uint8_t crc_crc8onewire_msb(const uint8_t *buf, uint16_t buflen, uint8_t crc) uint16_t crc_ccitt(const uint8_t *buf, uint16_t buflen, uint16_t crc) uint16_t crc_ccitt_msb(const uint8_t *buf, uint16_t buflen, uint16_t crc) uint16_t crc_crc16(const uint8_t *buf, uint16_t buflen, uint16_t crc) uint16_t crc_crc16_msb(const uint8_t *buf, uint16_t buflen, uint16_t crc) uint16_t crc_crc16dnp(const uint8_t *buf, uint16_t buflen, uint16_t crc) uint16_t crc_crc16dnp_msb(const uint8_t *buf, uint16_t buflen, uint16_t crc) uint32_t crc_crc32(const uint8_t *buf, uint16_t buflen, uint32_t crc) uint32_t crc_crc32_msb(const uint8_t *buf, uint16_t buflen, uint32_t crc)..........................29 3.2.18.uint16_t pn9_advance(uint16_t pn9)....................................................... 29 3.2.19.uint16_t pn9_advance_bit(uint16_t pn9)..................................................29 3.2.20.uint16_t pn9_advance_bits(uint16_t pn9, uint16_t bits).............................29 3.2.21.uint16_t pn9_advance_byte(uint16_t pn9)............................................... 29 3.2.22.uint16_t pn9_buffer(uint8_t __generic *buf, uint16_t buflen, uint16_t pn9, uint8_t xor).....................................................................................................30 www.onsemi.com AND9382/D 6 4.Evaluation Board Peripherals.................................................................................. 30 4.1.libmflcd.h......................................................................................................33 4.1.1.void lcd_init(void)....................................................................................33 4.1.2.void lcd_portinit(void)..............................................................................33 4.1.3.void lcd_setpos(uint8_t v)........................................................................ 34 4.1.4.void lcd_writestr(const char *ch)...............................................................34 4.1.5.void lcd_writehex16(uint16_t val, uint8_t nrdig, uint8_t flags) void lcd_writehex32(uint32_t val, uint8_t nrdig, uint8_t flags).....................................34 4.1.6.void lcd_writenum16(uint16_t val, uint8_t nrdig, uint8_t flags) void lcd_writenum32(uint32_t val, uint8_t nrdig, uint8_t flags)....................................34 4.1.7.void lcd_cleardisplay(void)........................................................................34 4.1.8.void lcd_clear(uint8_t pos, uint8_t len)...................................................... 34 4.1.9.void lcd_waitlong(void) void lcd_waitshort(void)..........................................34 4.1.10.void lcd_writecmd(uint8_t cmd).............................................................. 34 4.1.11.void lcd_writedata(uint8_t d).................................................................. 35 5.Contact Information...............................................................................................36 www.onsemi.com AND9382/D Introduction 1. I N T R O D U C T I O N LibMF is a convenience library to ease the use of ON Semiconductor AX8052 Microprocessor and Evaluation Board features. It contains the following features: • DebugLink UART • RS-232 UART • FLASH writing under Software Control • Radio Initialization and Probing • CRC-8 and CRC-16 routines • Evaluation Board LCD access LibMF is available in source and binary form for SDCC, Keil C51 and IAR ICC. 2. M I C R O P R O C E S S O R F U N C T I O N S 2.1. A X 8052. H , A X 8052 F 131. H , A X 8052 F 142. H , A X 8052 F 143. H , A X 8052 F 151. H These headers define the special function registers (SFR) of the ON Semiconductor AX8052 Microprocessor. ax8052.h defines the SFR's of the microcontroller core only. It is suitable for the AX8052F101, or the AX8052F100 without any ON Semiconductor radio chip connected. ax8052f131.h, ax8052f142.h, ax8052f143.h and ax8052f151.h define the special function registers of the microcontroller core as well as the respective radio peripheral. So for example ax8052f151.h is suitable for the SoC AX8052F151, as well as the two-chip combination AX8052F100 plus AX5051. www.onsemi.com AND9382/D 7 8 Microprocessor Functions 2.2. A X 8052 R E G A D D R . H This header provides defines for the AX8052 special function register (SFR) addresses. Contrary to ax8052.h, which provides defines that, when used like variables, access the registers, the ax8052regaddr.h header file only provides defines for the register addresses. 2.3. LIBMFTYPES.H 2.3.1. LIBM FVE RSION This preprocessor define specifies the version of the libmf library. It can be used for version specific processing, for example to accommodate incompatible changes to libmf. 2.3.2. __ C O D E , __ D A T A , __ X D A T A , __ P D A T A , __ G E N E R I C These defines provide compiler independent address space specifiers. 2.3.3. I N T 8_ T , I N T 16_ T , I N T 32_ T U I N T 8_ T , U I N T 16_ T , U I N T 32_ T These are C99 style sized integer types. u signifies unsigned (the default is signed), and the number specifies the size in bits. So uint16_t is a 16 bit (2 byte) unsigned integer. 2.3.4. V O I D D E L A Y ( U I N T 16_ T U S ) This routine busy waits for the given number of microseconds. The wait duration is approximately correct when the microprocessor runs at 20 MHz. This routine should not be used for long delays for power consumption reasons. For long delays, enter standby or sleep mode and wake up using the wakeup timer peripheral. 2.3.5. U I N T 16_ T U I N T 16_ T R A N D O M ( V O I D ) __ D A T A RANDOM_SEED This function provides a simple linear congruential random number generator. Its seed is stored in the variable random_seed. This is not a cryptographic quality random number generator. For cryptographic quality random number, use the true random number generator peripheral and mix its output sufficiently. 2.3.6. U I N T 8_ T H W E I G H T 8( U I N T 8_ T X ) U I N T 8_ T H W E I G H T 16( U I N T 16_ T X ) U I N T 8_ T H W E I G H T 32( U I N T 32_ T X ) These functions compute the hamming weight or population count, i.e. the number of bits set. www.onsemi.com AND9382/D Microprocessor Functions 2.3.7. U I N T 8_ T P A R I T Y 8( U I N T 8_ T X ) U I N T 16_ T P A R I T Y 16( U I N T 16_ T X ) U I N T 32_ T P A R I T Y 32( U I N T 32_ T X ) These functions compute the odd parity of the argument, i.e. they return one if the argument contains an odd number of bits set. 2.3.8. U I N T 8_ T R E V 8( U I N T 8_ T X ) This functions reverses the bits of its argument, i.e. Bits 0 and 7 are swapped, Bits 1 and 6, and so on. 2.3.9. I N T 32_ T I N T 32_ T I N T 32_ T I N T 32_ T S I G N E X T E N D 12( I N T 16_ T X ) S I G N E X T E N D 16( I N T 16_ T X ) S I G N E X T E N D 20( I N T 32_ T X ) S I G N E X T E N D 24( I N T 32_ T X ) These functions sign extend a given number. 2.3.10. I N T 32_ T I N T 16_ T S I G N E D L I M I T 16( I N T 16_ T X , I N T 16_ T L I M ) S I G N E D L I M I T 32( I N T 32_ T X , I N T 32_ T L I M ) This function returns –lim if x is less than –lim, lim if x is more than lim, and x otherwise. lim must be in the range from 0…215-1 or 0…231-1 for these functions to work correctly. 2.3.11. U I N T 8_ T U I N T 8_ T C H E C K S I G N E D L I M I T 16( I N T 16_ T X , I N T 16_ T L I M ) C H E C K S I G N E D L I M I T 32( I N T 32_ T X , I N T 32_ T L I M ) These functions return zero if x is less than –lim or more than lim, and one otherwise. lim must be in the range from 0…215-1 or 0…231-1 for these functions to work correctly. 2.3.12. VOID FMEMSET(VOID __ G E N E R I C * P , C H A R C , U I N T 16_ T N ) fmemset is a fast version of the standard C library memset function. It however takes a generic pointer, and internally uses separate implementations depending on the address space the pointer points to. 2.3.13. N) VOID FMEMCPY(VOID __ G E N E R I C * D , CONST VOID __ G E N E R I C * S , U I N T 16_ T fmemcpy is a fast version of the standard C library memcpy function. It however takes generic pointers, and internally uses separate implementations depending on the address space combinations the pointers point to. www.onsemi.com AND9382/D 9 10 Microprocessor Functions 2.3.14. VOID WTIMER_STANDBY( VOID) On SDCC, this function calls wtimer_runcallbacks and wtimer_idle(WTFLAG_CANSTANDBY) if the wakeup timer module is used in the project. Otherwise, or when using Keil or IAR, it calls enter_standby(), below. 2.3.15. VOID ENTER_STANDBY(VOID) This macro enters standby mode. enter_standby should be preferred over directly writing to PCON, as it includes a NOP instruction after writing to PCON, to ensure correct processing. 2.3.16. VOID ENTER_SLEEP( VOID) This routine enters the sleep mode. enter_sleep should be preferred over directly writing to PCON, as it ensures the same behaviour whether or not the debugger is attached. An incompatible change to this macro has been made. Earlier libmf versions took an argument to specify which XRAM blocks should be kept. This argument has been removed. The XRAM blocks to keep should be directly written to PCON (with bits 1:0 written to 00). This change has been done for efficiency. After wake-up, program execution restarts at the reset vector. Reset and wake-up can be distinguished by PCON.6. 2.3.17. VOID ENTER_SLEEP_CONT(VOID) This routine enters the sleep mode. Contrary to enter_sleep(), this function returns after wake-up and execution continues. _sdcc_external_startup() is called after wake-up, before the function returns. All peripherals, except the system controller, need to be reinitialized (but note silicon revision V1 errata). This function is only available for SDCC. It is incompatible with the external stack. 2.3.18. VOID ENTER_DEEPSLEEP( VOID) This macro causes the processor to enter deepsleep mode. It should be preferred over directly writing to PCON, as it ensures the same behaviour whether or not the debugger is attached. 2.3.19. WRNUM_SIGNED, WRNUM_PLUS, WRNUM_ZEROPLUS, WRNUM_PADZE RO, WRNUM_T SDSEP, WRNUM_LCHEX These or'able constants are used as flags to the wrnum16/wrnum32/wrhex16/wrhex32 family of functions to specify the behavior. • WRNUM_SIGNED: treat the argument as signed number. The default is unsigned. www.onsemi.com AND9382/D Microprocessor Functions • WRNUM_PLUS: Output a plus sign for positive number. Default is to output a sign character only for negative numbers. • WRNUM_ZEROPLUS: Output a plus sign for zero arguments. Default is to omit a sign character for zeros. • WRNUM_PADZERO: Pad the output with leading zeros. Default is to pad the output with space characters. • WRNUM_TSDSEP: Output a thousands separator (apostrophe). Default is to not output a thousands separator. For hexadecimal output, the separator separates word (16bit) numbers. • WRNUM_LCHEX: Output upper case hexadecimal characters. Default is to output lowercase hexadecimal characters. 2.4. LIBMFDBGLINK.H DebugLink is an UART whose input/output is sent over the debug link interface to the debugger. It is displayed in a window of the ON Semiconductor AxCode::Blocks IDE. When using SDCC, libmfdbglink.h must be included in the file containing the definition for main. 2.4.1. VOID DBGLINK_INIT( VOID) dbglink_init initializes the DebugLink driver. It installs an interrupt handler and initializes the FIFOs (64 Bytes in XRAM for each direction). It must be called before using DebugLink, and should be called before interrupts are globally enabled. 2.4.2. U I N T 8_ T D B G L I N K _ R X ( V O I D ) dbglink_rx reads a character from the receive FIFO. It blocks until a character is available. If blocking is undesirable, it should only be called when dbglink_rxcount() returns a nonzero result. 2.4.3. V O I D D B G L I N K _ T X ( U I N T 8_ T V ) dbglink_tx puts one character into the transmit FIFO and starts the transmitter, if it is not already running. It blocks if the FIFO is full. If blocking is not desirable, it should only be called if dbglink_txfree() returns a nonzero value. www.onsemi.com AND9382/D 11 12 Microprocessor Functions 2.4.4. VOID DBGLINK_WRITESTR(CONST CHAR *CH) dbglink_writestr writes the null terminated C string to the DebugLink interface. It is blocking if the string exceeds the FIFO free space. 2.4.5. V O I D D B G L I N K _ W R I T E H E X 16( U I N T 16_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T FLAGS) V O I D D B G L I N K _ W R I T E H E X 32( U I N T 32_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) dbglink_writehex16 and dbglink_writehex32 write a hexadecimal number to the DebugLink interface. The number of desired digits must be given in the nrdig parameter. It is blocking if the number of digits exceed the FIFO free space. flags is a bitwise or combination of the WRNUM constants documented in section 2.3.19 2.4.6. V O I D D B G L I N K _ W R I T E N U M 16( U I N T 16_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T FLAGS) V O I D D B G L I N K _ W R I T E N U M 32( U I N T 32_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) dbglink_writenum16 and dbglink_writenum32 write a hexadecimal number to the DebugLink interface. The number of desired digits must be given in the nrdig parameter. It is blocking if the number of digits exceed the FIFO free space. flags is a bitwise or combination of the WRNUM constants documented in section 2.3.19 2.4.7. U I N T 8_ T D B G L I N K _ T X B U F F E R S I Z E ( V O I D ) U I N T 8_ T D B G L I N K _ R X B U F F E R S I Z E ( V O I D ) These functions return the transmit and receive buffer sizes. Buffer sizes are configurable. 2.4.8. U I N T 8_ T D B G L I N K _ R X C O U N T ( V O I D ) dbglink_rxcount returns the number of characters in the receive FIFO. 2.4.9. U I N T 8_ T D B G L I N K _ T X F R E E ( V O I D ) dbglink_txfree returns the number of free space for characters in the transmit FIFO. 2.4.10. U I N T 8_ T D B G L I N K _ T X I D L E ( V O I D ) dbglink_txidle returns one if the transmitter is idle, i.e. all transmit characters have left the wire. This routine can be used to determine whether the microprocessor can enter sleep. 2.4.11. V O I D D B G L I N K _ W A I T _ R X C O U N T ( U I N T 8_ T V ) dbglink_wait_rxcount blocks until the number of characters in the receive FIFO reach or exceed v. www.onsemi.com AND9382/D Microprocessor Functions 2.4.12. VOID DBGLINK_WAIT_TXDONE( VOID) dbglink_wait_txdone blocks until the last character in the transmit FIFO has been transmitted. 2.4.13. V O I D D B G L I N K _ W A I T _ T X F R E E ( U I N T 8_ T V ) dbglink_wait_txfree blocks until the number of free space for characters in the transmit FIFO reaches or exceeds v. 2.4.14. V O I D D B G L I N K _ R X A D V A N C E ( U I N T 8_ T I D X ) dbglink_rxadvance drops the given number of characters from the front of the FIFO. 2.4.15. V O I D D B G L I N K _ T X A D V A N C E ( U I N T 8_ T I D X ) dbglink_txadvance adds the given number of characters at the end of the transmit FIFO. They must have been defined by dbglink_txpoke or dbglink_txpokehex before, otherwise the transmitted characters are undefined. 2.4.16. U I N T 8_ T D B G L I N K _ R X P E E K ( U I N T 8_ T I D X ) dbglink_rxpeek returns the idx'th character in the receive FIFO without modifying the FIFO. 2.4.17. V O I D D B G L I N K _ T X P O K E ( U I N T 8_ T I D X , U I N T 8_ T C H ) dbglink_txpoke puts a character at the idx'th position after the end of the transmit FIFO. It does not become part of the FIFO. In order to actually transmit the character, dbglink_txadvance must be called. 2.4.18. V O I D D B G L I N K _ T X P O K E H E X ( U I N T 8_ T I D X , U I N T 8_ T C H ) dbglink_txpoke puts a hexadecimal character at the idx'th position after the end of the transmit FIFO. It does not become part of the FIFO. In order to actually transmit the character, dbglink_txadvance must be called. 2.4.19. U I N T 8_ T D B G L I N K _ P O L L ( V O I D ) Normally, data is transferred between the FIFO and the hardware using an interrupt handler. Sometimes though, an interrupt handler is undesirable; in this case, dbglink_poll can be called periodically to transfer data between the FIFO and the hardware if available. It returns a bit mask with bit 0 set if a byte was transferred from the hardware to the receive FIFO, and bit 1 set if a byte was transferred from the transmit FIFO to the hardware. www.onsemi.com AND9382/D 13 14 Microprocessor Functions 2.4.20. DBGLI NK_DEFI NE_TXBUFFE R( S Z ) DBGLI NK_DEFI NE_RXBUFFER( S Z ) These macros define the transmit and receive buffer sizes, respectively. The argument needs to lie between 2 and 256 (inclusive). Note that the argument specifies the total buffer size; one character is unusable due to the design of the buffer pointers, therefore dbglink_txbuffersize and dbglink_rxbuffersize will return one byte less than the argument. 2.5. LIBMFUART.H This header file defines routines that are common to both UARTs. 2.5.1. V O I D U A R T _ T I M E R 0_ B A U D ( U I N T 8_ T C L K S R C , U I N T 32_ T B A U D , U I N T 32_ T CLKFREQ) V O I D U A R T _ T I M E R 1_ B A U D ( U I N T 8_ T C L K S R C , U I N T 32_ T B A U D , U I N T 32_ T C L K F R E Q ) V O I D U A R T _ T I M E R 2_ B A U D ( U I N T 8_ T C L K S R C , U I N T 32_ T B A U D , U I N T 32_ T C L K F R E Q ) Each UART needs to be paired with a general purpose Timer for Baud rate generation. Both UARTs can be paired with the same Timer if the same Baud rate is desired. These routines set up a particular timer for baud rate generation. clksrc may be one of CLKSRC_FRCOSC, CLKSRC_LPOSC, CLKSRC_XOSC, CLKSRC_LPXOSC, CLKSRC_RSYSCLK, CLKSRC_TCLK, CLKSRC_SYSCLK or CLKSRC_OFF. If clksrc is CLKSRC_XOSC or CLKSRC_LPXOSC, the frequency of the connected crystal must be given as argument xtalclk (in Hz). Baud is the baudrate in bits/s, while clkfreq is the clock frequency of the selected oscillator. 2.6. L I B M F U A R T 0. H , L I B M F U A R T 1. H When using SDCC, libmfuart0.h/libmfuart1.h must be included in the file containing the definition for main. 2.6.1. V O I D U A R T 0_ I N I T ( U I N T 8_ T T I M E R N R , U I N T 8_ T W L , U I N T 8_ T S T O P ) V O I D U A R T 0_ I N I T ( U I N T 8_ T T I M E R N R , U I N T 8_ T W L , U I N T 8_ T S T O P ) uart0_init / uart1_init initializes the UART driver. It installs an interrupt handler and initializes the FIFOs (64 Bytes in XRAM for each direction and UART). It must be called before using the UART, and should be called before interrupts are globally enabled. www.onsemi.com AND9382/D Microprocessor Functions timernr (0...2) specifies the timer that should be used as baud rate generator. The corresponding timer must be initialized with uart_timerx_baud. wl (5...9) specifies the word length, i.e. the number of bits between start and stop bit(s). stop (1...2) specifies the number of stop bits. This affects only the transmitter; the receiver always accepts 1 stop bit. 2.6.2. V O I D U A R T 0_ S T O P ( V O I D ) V O I D U A R T 1_ S T O P ( V O I D ) uart0_stop / uart1_stop can be used to stop the UART after it has been initialized with uart0_init / uart1_init. After stopping, no reads or writes to the UART should be performed. In order to restart the UART, uart0_init / uart1_init must be used. 2.6.3. U I N T 8_ T U A R T 0_ R X ( V O I D ) U I N T 8_ T U A R T 1_ R X ( V O I D ) uart0_rx / uart1_rx reads a character from the receive FIFO. It blocks until a character is available. If blocking is undesirable, it should only be called when uart0_rxcount() / uart1_rxcount() returns a nonzero result. 2.6.4. V O I D U A R T 0_ T X ( U I N T 8_ T V ) V O I D U A R T 1_ T X ( U I N T 8_ T V ) uart0_tx / uart1_tx puts one character into the transmit FIFO and starts the transmitter, if it is not already running. It blocks if the FIFO is full. If blocking is not desirable, it should only be called if uart0_txfree() / uart1_txfree() returns a nonzero value. 2.6.5. V O I D U A R T 0_ W R I T E S T R ( C O N S T C H A R V O I D U A R T 1_ W R I T E S T R ( C O N S T C H A R *CH) *CH) uart0_writestr / uart1_writestr writes the null terminated C string to the UART. It is blocking if the string exceeds the FIFO free space. 2.6.6. V O I D U A R T 0_ W R I T E H E X 16( U I N T 16_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) V O I D U A R T 0_ W R I T E H E X 32( U I N T 32_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) V O I D U A R T 1_ W R I T E H E X 16( U I N T 16_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) V O I D U A R T 1_ W R I T E H E X 32( U I N T 32_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) uart0_writehex16 / uart1_writehex16 and uart0_writehex32 / uart1_writehex32 write a hexadecimal number to the UART. The number of desired digits must be given in the nrdig parameter. It is blocking if the number of digits exceed the FIFO free space. flags is a bitwise or combination of the WRNUM constants documented in section 2.3.19 www.onsemi.com AND9382/D 15 16 Microprocessor Functions 2.6.7. V O I D U A R T 0_ W R I T E N U M 16( U I N T 16_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) V O I D U A R T 0_ W R I T E N U M 32( U I N T 32_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) V O I D U A R T 1_ W R I T E N U M 16( U I N T 16_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) V O I D U A R T 1_ W R I T E N U M 32( U I N T 32_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) uart0_writenum16 / uart1_writenum16 and uart0_writenum32 / uart1_writenum32 write a hexadecimal number to the UART. The number of desired digits must be given in the nrdig parameter. It is blocking if the number of digits exceed the FIFO free space. flags is a bitwise or combination of the WRNUM constants documented in section 2.3.19 2.6.8. U I N T 8_ T U A R T 0_ T X B U F F E R S I Z E ( V O I D ) U I N T 8_ T U A R T 1_ T X B U F F E R S I Z E ( V O I D ) U I N T 8_ T U A R T 0_ R X B U F F E R S I Z E ( V O I D ) U I N T 8_ T U A R T 1_ R X B U F F E R S I Z E ( V O I D ) These functions return the transmit and receive buffer sizes. Buffer sizes are configurable. 2.6.9. U I N T 8_ T U A R T 0_ R X C O U N T ( V O I D ) U I N T 8_ T U A R T 1_ R X C O U N T ( V O I D ) uart0_rxcount / uart1_rxcount returns the number of characters in the receive FIFO. 2.6.10. U I N T 8_ T U I N T 8_ T U A R T 0_ T X F R E E ( V O I D ) U A R T 1_ T X F R E E ( V O I D ) uart0_txfree / uart1_txfree returns the number of free space for characters in the transmit FIFO. 2.6.11. U I N T 8_ T U I N T 8_ T U A R T 0_ T X I D L E ( V O I D ) U A R T 1_ T X I D L E ( V O I D ) uart0_txidle / uart1_txidle returns one if the transmitter is idle, i.e. all transmit characters have left the wire. This routine can be used to determine whether the microprocessor can enter sleep. 2.6.12. V O I D U A R T 0_ W A I T _ R X C O U N T ( U I N T 8_ T V ) V O I D U A R T 1_ W A I T _ R X C O U N T ( U I N T 8_ T V ) uart0_wait_rxcount / uart1_wait_rxcount blocks until the number of characters in the receive FIFO reach or exceed v. 2.6.13. V O I D U A R T 0_ W A I T _ T X D O N E ( V O I D ) V O I D U A R T 1_ W A I T _ T X D O N E ( V O I D ) uart0_wait_txdone / uart1_wait_txdone blocks until the last character in the transmit FIFO has been transmitted. www.onsemi.com AND9382/D Microprocessor Functions 2.6.14. V O I D U A R T 0_ W A I T _ T X F R E E ( U I N T 8_ T V ) V O I D U A R T 1_ W A I T _ T X F R E E ( U I N T 8_ T V ) uart0_wait_txfree / uart1_wait_txfree blocks until the number of free space for characters in the transmit FIFO reaches or exceeds v. 2.6.15. V O I D U A R T 0_ R X A D V A N C E ( U I N T 8_ T I D X ) V O I D U A R T 1_ R X A D V A N C E ( U I N T 8_ T I D X ) uart0_rxadvance / uart1_rxadvance drops the given number of characters from the front of the FIFO. 2.6.16. V O I D U A R T 0_ T X A D V A N C E ( U I N T 8_ T I D X ) V O I D U A R T 1_ T X A D V A N C E ( U I N T 8_ T I D X ) uart0_txadvance / uart1_txadvance adds the given number of characters at the end of the transmit FIFO. They must have been defined by uart0_txpoke / uart1_txpoke or uart0_txpokehex / uart1_txpokehex before, otherwise the transmitted characters are undefined. 2.6.17. U I N T 8_ T U I N T 8_ T U A R T 0_ R X P E E K ( U I N T 8_ T I D X ) U A R T 1_ R X P E E K ( U I N T 8_ T I D X ) uart0_rxpeek / uart1_rxpeek returns the idx'th character in the receive FIFO without modifying the FIFO. 2.6.18. V O I D U A R T 0_ T X P O K E ( U I N T 8_ T I D X , U I N T 8_ T C H ) V O I D U A R T 1_ T X P O K E ( U I N T 8_ T I D X , U I N T 8_ T C H ) uart0_txpoke / uart1_txpoke puts a character at the idx'th position after the end of the transmit FIFO. It does not become part of the FIFO. In order to actually transmit the character, uart0_txadvance / uart1_txadvance must be called. 2.6.19. V O I D U A R T 0_ T X P O K E H E X ( U I N T 8_ T I D X , U I N T 8_ T C H ) V O I D U A R T 1_ T X P O K E H E X ( U I N T 8_ T I D X , U I N T 8_ T C H ) uart0_txpoke / uart1_txpoke puts a hexadecimal character at the idx'th position after the end of the transmit FIFO. It does not become part of the FIFO. In order to actually transmit the character, uart0_txadvance / uart1_txadvance must be called. 2.6.20. U I N T 8_ T U I N T 8_ T U A R T 0_ P O L L ( V O I D ) U A R T 1_ P O L L ( V O I D ) Normally, data is transferred between the FIFO and the hardware using an interrupt handler. Sometimes though, an interrupt handler is undesirable; in this case, uart0_poll / uart1_poll can be called periodically to transfer data between the FIFO and the hardware if www.onsemi.com AND9382/D 17 18 Microprocessor Functions available. It returns a bit mask with bit 0 set if a byte was transferred from the hardware to the receive FIFO, and bit 1 set if a byte was transferred from the transmit FIFO to the hardware. 2.6.21. UART0_DEFINE_TXBUFFE R( S Z ) UART1_DEFINE_TXBUFFE R( S Z ) UART0_DEFINE_RXBUFFER( S Z ) UART1_DEFINE_RXBUFFER( S Z ) These macros define the transmit and receive buffer sizes, respectively. The argument needs to lie between 2 and 256 (inclusive). Note that the argument specifies the total buffer size; one character is unusable due to the design of the buffer pointers, therefore uart0_txbuffersize / uart1_txbuffersize and uart0_rxbuffersize / uart1_rxbuffersize will return one byte less than the argument. 2.7. LIBMFFLASH.H 2.7.1. VOID FLASH_UNLOCK(VOID) flash_unlock prepares the FLASH controller for subsequent erase or write operations. 2.7.2. VOID FLASH_LOCK( VOID) flash_lock disables further erase and write operations until flash_unlock is called again. This provides some protection against accidental FLASH modifications. 2.7.3. I N T 8_ T F L A S H _ P A G E E R A S E ( U I N T 16_ T P G A D D R ) AX8052 FLASH memory is organized as 64 sectors of 1kByte. Each sector may be erased individually. Erasing a sector sets it to all ones. An abritrary address located inside the desired sector must be given as pgaddr. flash_pageerase only succeeds if the flash controller has been enabled previously, using flash_unlock. It returns zero on success and nonzero on error. 2.7.4. I N T 8_ T F L A S H _ W R I T E ( U I N T 16_ T W A D D R , U I N T 16_ T W D A T A ) flash_write writes the 16 bit word wdata to the given address waddr. The AX8052 FLASH is organized as 16 bit words. waddr must be an even address. flash_write can only program FLASH bits from 1 to 0, therefore the respective FLASH sector should be erased before calling write. flash_write only succeeds if the flash controller has been enabled previously, using flash_unlock. It returns zero on success and nonzero on error. 2.7.5. U I N T 16_ T F L A S H _ R E A D ( U I N T 16_ T R A D D R ) flash_read is a convenience function to read from FLASH. Reading from FLASH can also be accomplished by dereferencing a __code *. www.onsemi.com AND9382/D Microprocessor Functions 2.7.6. U I N T 8_ T F L A S H _ A P P L Y _ C A L I B R A T I O N ( V O I D ) The last FLASH sector from address 0xFC00 to 0xFFFF should not be used by the user. It may store factory calibration data. flash_apply_calibration writes the calibration data to the respective chip registers if found. It should be called very early during program initialization. Before calling flash_apply_calibration, the correct LPOSC operating mode should be set (Bit LPOSCFAST of Register LPOSCCONFIG); different calibration values are used for both modes. flash_apply_calibration returns a nonzero value if valid calibration data is found. 2.8. LIBMFRADIO.H libmfradio.h contains access, initialization and configuration routines for the radio peripheral. 2.8.1. U I N T 16_ T R A D I O _ R E A D 16( U I N T 16_ T A D D R ) U I N T 32_ T R A D I O _ R E A D 24( U I N T 16_ T A D D R ) U I N T 32_ T R A D I O _ R E A D 32( U I N T 16_ T A D D R ) These routines read radio registers using 16-bit, 24-bit or 32-bit (plus address) SPI transactions. 2.8.2. V O I D R A D I O _ W R I T E 16( U I N T 16_ T A D D R , U I N T 16_ T D ) V O I D R A D I O _ W R I T E 24( U I N T 16_ T A D D R , U I N T 32_ T D ) V O I D R A D I O _ W R I T E 32( U I N T 16_ T A D D R , U I N T 32_ T D ) These routines write radio registers using 16-bit, 24-bit or 32-bit (plus address) SPI transactions. 2.8.3. U I N T 8_ T A X 5031_ R E S E T ( V O I D ) U I N T 8_ T A X 5042_ R E S E T ( V O I D ) U I N T 8_ T A X 5043_ R E S E T ( V O I D ) U I N T 8_ T A X 5051_ R E S E T ( V O I D ) These functions probe for the respective radio peripheral and reset it if found. They return zero if the respective radio peripheral is found, or a nonzero error code. These routines work both for the SoC devices, as well as the two-chip combination of AX8052F100 plus the respective ON Semiconductor Radio Chip. There are small differences between the SoC and the two chip solution; these routines automatically detect and handle those differences. www.onsemi.com AND9382/D 19 20 Microprocessor Functions 2.8.4. V O I D A X 5031_ C O M M S L E E P E X I T ( V O I D ) V O I D A X 5042_ C O M M S L E E P E X I T ( V O I D ) V O I D A X 5043_ C O M M S L E E P E X I T ( V O I D ) V O I D A X 5051_ C O M M S L E E P E X I T ( V O I D ) These functions (re)initialize the communication with the radio peripheral. They should be called after waking up the microcontroller from sleep or deep sleep, unless the radio was also in deep sleep, in which case axxxx_wakeup_deepsleep() should be called. During cold boot, axxxxx_reset() should be called instead. 2.8.5. V O I D A X 5031_ C O M M I N I T ( V O I D ) V O I D A X 5042_ C O M M I N I T ( V O I D ) V O I D A X 5043_ C O M M I N I T ( V O I D ) V O I D A X 5051_ C O M M I N I T ( V O I D ) These functions perform basic (re)initialization of the radio communication interface. They do not set up interrupt routing. These routines are infrequently used. 2.8.6. V O I D A X 5031_ R C L K _ E N A B L E ( U I N T 8_ T D I V ) V O I D A X 5042_ R C L K _ E N A B L E ( U I N T 8_ T D I V ) V O I D A X 5043_ R C L K _ E N A B L E ( U I N T 8_ T D I V ) V O I D A X 5051_ R C L K _ E N A B L E ( U I N T 8_ T D I V ) These functions enable the radio system clock RSYSCLK. The div argument can be within the range 0...11. It causes the radio system clock to be divided by 2div. After calling this function, the radio system clock may be used by any of the AX8052 core peripherals, such as the general purpose timers, the wakeup timers, or even as the system clock. Often, the radio peripheral has the most accurate clock (crystal or even TCXO derived). These functions allow the precise clock to be used for other purposes within the microcontroller. On the other hand, RSYSCLK should not be enabled needlessly to save energy. 2.8.7. V O I D A X 5042_ R C L K _ D I S A B L E ( V O I D ) V O I D A X 5031_ R C L K _ D I S A B L E ( V O I D ) V O I D A X 5043_ R C L K _ D I S A B L E ( V O I D ) V O I D A X 5051_ R C L K _ D I S A B L E ( V O I D ) These functions disable the radio system clock RSYSCLK forwarding to the microcontroller. It may still be used within the radio peripheral. 2.8.8. V O I D A X 5043_ E N T E R _ D E E P S L E E P ( V O I D ) This function puts the radio into deep sleep mode. Note that the radio power states are distinct from the microcontroller core power states. www.onsemi.com AND9382/D Microprocessor Functions 2.8.9. U I N T 8_ T A X 5043_ W A K E U P _ D E E P S L E E P ( V O I D ) This function wakes the radio up from deep sleep. Note that the radio power states are distinct from the microcontroller core power states. 2.8.10. V O I D A X 5043_ R E A D F I F O ( U I N T 8_ T *PTR, U I N T 8_ T L E N ) This functions reads a given number of bytes from the FIFO and stores it at the given location. 2.8.11. V O I D A X 5043_ W R I T E F I F O ( C O N S T U I N T 8_ T *PTR, U I N T 8_ T L E N ) This functions writes a given number of bytes at the pointer to the FIFO. 2.9. LIBMFADC.H libmfadc.h contains utility functions for use with the on-chip Analog to Digital Converter (ADC). 2.9.1. I N T 16_ T A D C _ M E A S U R E _ T E M P E R A T U R E ( V O I D ) This function measures the temperature of the microcontroller die. With the default calibration (after calling flash_apply_calibration()), the function returns whole degrees celsius in the upper byte, and fractional degrees in the lower byte. The temperature is therefore return value / 256 °C. This function sets up the A/D controller for temperature conversion, and restores the old settings afterwards. It disables all interrupts during conversion to reduce noise on the conversion result. One conversion takes approximately 500µs. 2.9.2. U I N T 16_ T A D C _ S I N G L E E N D E D _ O F F S E T _ X 1( V O I D ) In single ended ⨯1 mode, the ADC exhibits a small offset. It is recommended to cancel the offset by adding the value returned by this function to all ADC single ended ⨯1 mode results. The return value of this function is only valid if called after flash_apply_calibration() has been called. 2.10. L I B M F W T I M E R . H libmfwtimer.h provides sophisticated timer event handling. It manages both timers. Timer 0 is intended to be clocked with one of the low power clocks, i.e. LPOSC or, if an external tuning fork crystal is connected, with LPXOSC. Its time is kept even during sleep periods. In www.onsemi.com AND9382/D 21 22 Microprocessor Functions contrast, Timer 1 is intended to time shorter intervals. It is clocked by one of the faster clocks (such as FRCOSC, XOSC or the radio clock), but its time is not kept during sleep. The wakeup timer module keeps times as 32 bit integers with wrap-around. This results in events that can be scheduled approximately 230 in the future. The absolute time depends on the clock frequency and the prescaler setting of the timer. In order to schedule a timer event, the user has to allocate a wtimer_desc structure in xdata memory, write the address of a handler function into the wtimer_desc structure, write the expiry time, and call wtimer{0,1}_add{absolute,relative} function, supplying the address of the descriptor. The wakeup timer module then keeps a linked list of descriptors, sorted by expiry time. When the time comes, the handler is not called directly from the interrupt handler; doing so would have the following disadvantages: • Interrupt handlers should be short running, since other interrupts of the same priority level are blocked while an interrupt handler runs • Handler functions would need to be declared reentrant, and also all the routines it calls. Failure to do so would result in hard to find bugs. Instead, the descriptor is moved to the end of a third queue, the pending queue. Handlers in the pending queue are called as soon as wtimer_runcallbacks is called. This mechanism is also available for other interrupt handlers by using wtimer_add_callback. www.onsemi.com AND9382/D Microprocessor Functions wtimer_desc wtimer0 queue wtimer_desc next handler next handler time time wtimer1 queue wtimer pending void handler(wtimer_desc *desc) { ... } void handler(wtimer_desc *desc) { ... } wtimer_desc wtimer_desc next next handler handler time time void handler(wtimer_desc *desc) { ... } void handler(wtimer_desc *desc) { ... } wtimer_desc/wtimer_callback wtimer_desc/wtimer_callback next handler time void handler(wtimer_desc *desc) { ... } next handler time void handler(wtimer_desc *desc) { ... } Figure 1: Wakeup Timer Queues The main loop should repeatedly call wtimer_idle. The program structure should look like this: void main(void) { wtimer0_setclksrc(…); wtimer1_setclksrc(…); flash_apply_calibration(); wtimer_init(…); … for (;;) { uint8_t flg; wtimer_runcallbacks(); flg = WTFLAG_CANSTANDBY; if (dbglink_txidle() && ...) flg |= WTFLAG_CANSLEEP; wtimer_idle(flg); } } www.onsemi.com AND9382/D 23 24 Microprocessor Functions When using SDCC, libmfwtimer.h must be included in the file containing the definition for main. 2.10.1. U I N T 32_ T W T I M E R 0_ C U R T I M E ( V O I D ) U I N T 32_ T W T I M E R 1_ C U R T I M E ( V O I D ) These functions retrieve the current time of the respective timer. 2.10.2. V O I D W T I M E R 0_ A D D A B S O L U T E (__ X D A T A S T R U C T W T I M E R _ D E S C V O I D W T I M E R 1_ A D D A B S O L U T E (__ X D A T A S T R U C T W T I M E R _ D E S C V O I D W T I M E R 0_ A D D R E L A T I V E (__ X D A T A S T R U C T W T I M E R _ D E S C V O I D W T I M E R 1_ A D D R E L A T I V E (__ X D A T A S T R U C T W T I M E R _ D E S C *DESC) *DESC) *DESC) *DESC) These functions add a descriptor to the queue of the respective timer (maintaining the ascending time property of the queue). The relative versions first add the current time to the time field of the descriptor. Care must be taken not to re-add a descriptor already in a queue (call wtimer{0,1}_remove first if in doubt). 2.10.3. U I N T 8_ T U I N T 8_ T U I N T 8_ T W T I M E R 0_ R E M O V E (__ X D A T A S T R U C T W T I M E R _ D E S C *DESC) W T I M E R 1_ R E M O V E (__ X D A T A S T R U C T W T I M E R _ D E S C W T I M E R _ R E M O V E (__ X D A T A S T R U C T W T I M E R _ D E S C *DESC) *DESC) Remove a descriptor from the respective timer's queue or the pending queue. The handler is not called. These functions return whether the descriptor was found in any of the queues. wtimer_remove examines both timer queues. 2.10.4. V O I D W T I M E R _ A D D _ C A L L B A C K (__ X D A T A S T R U C T W T I M E R _ C A L L B A C K *DESC) Add a callback descriptor to the pending queue. Care must be taken not to re-add a descriptor already in the pending queue. If in doubt, call wtimer_remove_callback first. 2.10.5. *DESC) U I N T 8_ T W T I M E R _ R E M O V E _ C A L L B A C K (__ X D A T A S T R U C T W T I M E R _ C A L L B A C K Remove a callback descriptor from the pending queue. Returns whether the descriptor was found in the pending queue. The handler is not called. 2.10.6. U I N T 8_ T W T I M E R _ I D L E ( U I N T 8_ T F L A G S ) Send the microprocessor to standby or sleep, unless there are pending timer or callback events. The processor will only go to sleep if WTFLAG_CANSLEEP or WTFLAG_CANSLEEPCONT is set in the flags argument, and if there are no timer events set on wakeup timer 1. Otherwise it will go into standby mode if WTFLAG_CANSTANDBY is set in the flags argument. The function returns WTIDLE_WORK if there are pending timer events or callbacks, WTIDLE_SLEEP if enter_sleep_cont() was called and peripherals should now be reinitialized, and zero otherwise. Before calling wtimer_idle, wtimer_runcallbacks should be called. www.onsemi.com AND9382/D Microprocessor Functions 2.10.7. U I N T 8_ T W T I M E R _ R U N C A L L B A C K S ( V O I D ) This function runs all pending timer and callback events. It returns the number of callbacks called. 2.10.8. U I N T 8_ T W T I M E R _ C A N S L E E P ( V O I D ) This function returns one if the microprocessor can safely go to sleep mode. It returns zero if the timer 1 queue is not empty. Furthermore, the SDCC version also returns zero if any of the used UARTs or DebugLink (if used) still has transmit data queued. 2.10.9. V O I D W T I M E R 0_ S E T C L K S R C ( U I N T 8_ T C L K S R C , U N I T 8_ T P R E S C A L E R ) V O I D W T I M E R 1_ S E T C L K S R C ( U I N T 8_ T C L K S R C , U N I T 8_ T P R E S C A L E R ) These functions set the clock sources for both wakeup timers. These functions should be called as early as possible; when using SDCC, call them from _sdcc_external_startup. These functions take care not to accidentally enable a crystal oscillator when switching sources. For the first argument, use one of the constants CLKSRC_FRCOSC, CLKSRC_LPOSC, CLKSRC_XOSC, CLKSRC_LPXOSC, CLKSRC_RSYSCLK, CLKSRC_TCLK, CLKSRC_SYSCLK, CLKSRC_OFF. For the second argument, 0 means ✕2, 1 means ✕1, 2 means ÷2, 3 means ÷4, … and 7 means ÷64. 2.10.10. VOID WTIMER_INIT(VOID) This function initializes the wakeup timer core. It must be called before any other wakeup timer function, except wtimer0/1_setclksrc, can be called. When waking up from deep sleep, wtimer_init_deepsleep must be called instead. 2.10.11. VOID WTIMER_INIT_DEEPSLEEP( VOID) This function performs initialization of the wakeup timer core, like wtimer_init, but for the case of waking up from deep sleep. 2.11. L I B M F O S C . H libmfosc.h contains oscillator related utility functions. www.onsemi.com AND9382/D 25 26 Microprocessor Functions 2.11.1. VOID TURN_OFF_XOSC( VOID) This function turns the crystal oscillator off if it has been accidentally enabled, but no crystal is connected to its pins. This function needs to drive and toggle pins PA0 and PA1, so its usability depends on the target board design. 2.11.2. VOID TURN_OFF_LPXOSC( VOID) This function turns the low power crystal oscillator off if it has been accidentally enabled, but no crystal is connected to its pins. This function needs to drive and toggle pins PA4 and PA5, so its usability depends on the target board design. 2.11.3. VOID SETUP_XOSC( VOID) This function sets up the I/O pins and other configuration suitably so that the crystal oscillator may run. Call this function if a crystal is connected to the pins PA0/PA1. 2.11.4. VOID SETUP_LPXOSC( VOID) This function sets up the I/O pins and other configuration suitably so that the low power crystal oscillator may run. Call this function if a crystal is connected to the pins PA3/PA4. 2.11.5. U I N T 8_ T S E T U P _ O S C _ C A L I B R A T I O N ( U I N T 32_ T R E F F R E Q , U I N T 8_ T R E F O S C ) This function sets up the low power and the fast RC oscillator configuration circuit for calibration from a given reference frequency and source. The parameter refosc specifies the oscillator to use as a reference. Valid values are CLKSRC_XOSC, CLKSRC_LPXOSC and CLKSRC_RSYSCLK. reffreq specifies the frequency of the reference source in Hz. The reference frequency must lie between 500 Hz and 32.768 MHz. For ON Semiconductor Transceivers with a faster crystal or TCXO (such as the AX8052F143 with an 48 MHz TCXO), it is recommended to divide SYSCLK in the transceiver block to obtain a reference clock within range (for example with the AX5043_PINFUNCSYSCLK register). This function returns zero on success, or non-zero if the input parameters are out of range. 2.11.6. SETUP_OSC_CALIBRATION_CONST( REFFREQ,REFOSC) This is a macro version of the setup_osc_calibration function. It may be used if both reffreq and refosc are compile time constants (which they often are). It can be simplified by the compiler to register writes with constants, therefore producing very little code. If one or more of the parameters is outside the valid range, calibration is not set up and no error is returned. For the parameter valid range, see setup_osc_calibration. www.onsemi.com AND9382/D Convenience Functions 3. C O N V E N I E N C E F U N C T I O N S 3.1. LIBMFBCH.H Bose-Chaudhuri-Hocquenghem (BCH) codes are a class of cyclic error correcting codes. Error correcting codes add redundancy to codewords, which allows the receiver to correct some bit errors. This header file provides functions which work on BCH(31,21,5) codewords, with an additional parity bit. This code is primarily used in paging systems. This code can correct up to two erroneous bits per 32 bit codeword. The routines work on 32 bit words. Bits 31—11 are the 21 data bits. Bits 10—1 are the BCH parity bits. Bit 0 is an even parity bit. 3.1.1. U I N T 16_ T B C H 3121_ S Y N D R O M E ( U I N T 32_ T C W ) This function computes the syndrome for the codeword. Bit 0 needs not be valid. 3.1.2. U I N T 32_ T B C H 3121_ E N C O D E ( U I N T 32_ T C W ) This function calculates the BCH parity bits. The argument only needs to have the data part valid. It returns the data with the BCH parity bits added. The additional parity bit is not computed. 3.1.3. U I N T 32_ T B C H 3121_ E N C O D E _ P A R I T Y ( U I N T 32_ T C W ) This function performs the same calculation as bch3121_encode, and additionally also computes the additional parity bit. 3.1.4. U I N T 32_ T B C H 3121_ D E C O D E ( U I N T 32_ T C W ) This function tries to decode a BCH codeword. It returns the codeword with bit errors corrected and bit 0 cleared if successful, or bit 1 set to indicate a decoding error. A decoding error can happen if there were more than 2 bit errors in the codeword. 3.1.5. U I N T 32_ T B C H 3121_ D E C O D E _ P A R I T Y ( U I N T 32_ T C W ) This function performs the same calculation as bch3121_decode, but additionally checks whether the additional parity bit matches the (corrected) codeword parity. www.onsemi.com AND9382/D 27 28 Convenience Functions 3.2. LIBMFCRC.H 3.2.1. U I N T 8_ T C R C 8_ C C I T T _ B Y T E ( U I N T 8_ T C R C , U I N T 8_ T C ) This function computes an 8-bit CRC (Cyclic Redundancy Check) (polynomial x8+x2+x1+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This routine does not use a table, and is therefore smaller but slower than the table driven version below. 3.2.2. U I N T 8_ T C R C 8_ C C I T T ( C O N S T U I N T 8_ T *BUF, U I N T 8_ T L E N , U I N T 8_ T I N I T ) This function computes an 8-bit CRC (Cyclic Redundancy Check) (polynomial x8+x2+x1+1) of a buffer addressed by buf of length len with the initial state vector init. This routine does not use a table, and is therefore smaller but slower than the table driven version below. 3.2.3. U I N T 8_ T C R C 8_ O N E W I R E _ B Y T E ( U I N T 8_ T C R C , U I N T 8_ T C ) This function computes an 8-bit CRC (Cyclic Redundancy Check) (polynomial x8+x5+x4+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This routine does not use a table, and is therefore smaller but slower than the table driven version below. 3.2.4. U I N T 8_ T C R C 8_ O N E W I R E ( C O N S T U I N T 8_ T *BUF, U I N T 8_ T L E N , U I N T 8_ T INIT) This function computes an 8-bit CRC (Cyclic Redundancy Check) (polynomial x8+x5+x4+1) of a buffer addressed by buf of length len with the initial state vector init. This routine does not use a table, and is therefore smaller but slower than the table driven version below. 3.2.5. U I N T 8_ T C R C _ C R C 8 C C I T T _ B Y T E ( U I N T 8_ T C R C , U I N T 8_ T C ) This function computes the 8-bit CCITT CRC (Cyclic Redundancy Check) (polynomial x8+x2+x1+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c LSB first, and the state vector is bit reversed. 3.2.6. U I N T 8_ T C R C _ C R C 8 C C I T T _ M S B _ B Y T E ( U I N T 8_ T C R C , U I N T 8_ T C ) This function computes the 8-bit CCITT CRC (Cyclic Redundancy Check) (polynomial x8+x2+x1+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c MSB first. www.onsemi.com AND9382/D Convenience Functions 3.2.7. U I N T 8_ T C R C _ C R C 8 O N E W I R E _ B Y T E ( U I N T 8_ T C R C , U I N T 8_ T C ) This function computes the 8-bit OneWire CRC (Cyclic Redundancy Check) (polynomial x8+x5+x4+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c LSB first, and the state vector is bit reversed. 3.2.8. U I N T 8_ T C R C _ C R C 8 O N E W I R E _ M S B _ B Y T E ( U I N T 8_ T C R C , U I N T 8_ T C ) This function computes the 8-bit OneWire CRC (Cyclic Redundancy Check) (polynomial x8+x5+x4+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c MSB first. 3.2.9. U I N T 16_ T C R C _ C C I T T _ B Y T E ( U I N T 16_ T C R C , U I N T 8_ T C ) This function computes the 16-bit CCITT CRC (Cyclic Redundancy Check) (polynomial x16+x12+x5+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c LSB first, and the state vector is bit reversed. 3.2.10. U I N T 16_ T C R C _ C C I T T _ M S B _ B Y T E ( U I N T 16_ T C R C , U I N T 8_ T C ) This function computes the 16-bit CCITT CRC (Cyclic Redundancy Check) (polynomial x16+x12+x5+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c MSB first. 3.2.11. U I N T 16_ T C R C _ C R C 16_ B Y T E ( U I N T 16_ T C R C , U I N T 8_ T C ) This function computes the 16-bit CRC-16 CRC (Cyclic Redundancy Check) (polynomial x16+x15+x2+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c LSB first, and the state vector is bit reversed. 3.2.12. U I N T 16_ T C R C _ C R C 16_ M S B _ B Y T E ( U I N T 16_ T C R C , U I N T 8_ T C ) This function computes the 16-bit CRC-16 CRC (Cyclic Redundancy Check) (polynomial x16+x15+x2+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c MSB first. www.onsemi.com AND9382/D 29 30 Convenience Functions 3.2.13. U I N T 16_ T C R C _ C R C 16 D N P _ B Y T E ( U I N T 16_ T C R C , U I N T 8_ T C ) This function computes the 16-bit CRC-16 DNP CRC (Cyclic Redundancy Check) (polynomial x16+x13+x12+x11+x10+x8+x6+x5+x2+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c LSB first, and the state vector is bit reversed. 3.2.14. U I N T 16_ T C R C _ C R C 16 D N P _ M S B _ B Y T E ( U I N T 16_ T C R C , U I N T 8_ T C ) This function computes the 16-bit CRC-16 DNP CRC (Cyclic Redundancy Check) (polynomial x16+x13+x12+x11+x10+x8+x6+x5+x2+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c MSB first. 3.2.15. U I N T 32_ T C R C _ C R C 32_ B Y T E ( U I N T 32_ T C R C , U I N T 8_ T C ) This function computes the 32-bit CRC-32 CRC (Cyclic Redundancy Check) (polynomial x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x1+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c LSB first, and the state vector is bit reversed. 3.2.16. U I N T 32_ T C R C _ C R C 32_ M S B _ B Y T E ( U I N T 32_ T C R C , U I N T 8_ T C ) This function computes the 32-bit CRC-32 CRC (Cyclic Redundancy Check) (polynomial x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x1+1) of one data byte c given the initial state vector crc. The CRC of a whole buffer may be computed by calling this function repeatedly for each byte, supplying the return value of the previous byte as state vector input of the current byte. This function processes c MSB first. www.onsemi.com AND9382/D Convenience Functions 3.2.17. U I N T 8_ T C R C _ C R C 8 C C I T T ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 8_ T C R C ) U I N T 8_ T C R C _ C R C 8 C C I T T _ M S B ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 8_ T CRC) U I N T 8_ T C R C _ C R C 8 O N E W I R E ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 8_ T C R C ) U I N T 8_ T C R C _ C R C 8 O N E W I R E _ M S B ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 8_ T CRC) U I N T 16_ T C R C _ C C I T T ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 16_ T C R C ) U I N T 16_ T C R C _ C C I T T _ M S B ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 16_ T C R C ) U I N T 16_ T C R C _ C R C 16( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 16_ T C R C ) U I N T 16_ T C R C _ C R C 16_ M S B ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 16_ T CRC) U I N T 16_ T C R C _ C R C 16 D N P ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 16_ T C R C ) U I N T 16_ T C R C _ C R C 16 D N P _ M S B ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 16_ T CRC) U I N T 32_ T C R C _ C R C 32( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 32_ T C R C ) U I N T 32_ T C R C _ C R C 32_ M S B ( C O N S T U I N T 8_ T * B U F , U I N T 16_ T B U F L E N , U I N T 32_ T CRC) These functions compute the CRC of a full buffer. The initial CRC register value is passed in parameter crc, the final crc value is returned. The buffer length may be zero, in which case the initial CRC value is returned. See a description of the bytewise CRC functions above for a description of the polynomials and the bit order. 3.2.18. U I N T 16_ T P N 9_ A D V A N C E ( U I N T 16_ T P N 9) This function computes the next state value (i.e. after one byte, that is after eight bits) of the PN-9 whitening sequence. The polynomial of the PN-9 sequence is x9+x4+1. This function uses a table-driven implementation, requiring 512 bytes of table data. 3.2.19. U I N T 16_ T P N 9_ A D V A N C E _ B I T ( U I N T 16_ T P N 9) This function computes the PN-9 whitening sequence state after one bit. 3.2.20. U I N T 16_ T P N 9_ A D V A N C E _ B I T S ( U I N T 16_ T P N 9, U I N T 16_ T B I T S ) This function computes the PN-9 whitening sequence state after a given number of bits. 3.2.21. U I N T 16_ T P N 9_ A D V A N C E _ B Y T E ( U I N T 16_ T P N 9) This function computes the PN-9 whitening sequence state after a byte (that is, eight bits). It computes the same value as pn9_advance, but uses a bit-wise implementation instead of a table-driven implementation. It therefore requires less FLASH space, but may take slightly longer, depending on compiler optimization. www.onsemi.com AND9382/D 31 32 Convenience Functions 3.2.22. U I N T 16_ T P N 9_ B U F F E R ( U I N T 8_ T __ G E N E R I C * B U F , U I N T 16_ T P N 9, U I N T 8_ T X O R ) U I N T 16_ T B U F L E N , This function xor's a buffer with a PN-9 sequence and the additional xor byte xor. The PN-9 start value is given by the parameter pn9, and the final value is returned. The additional xor byte may be used to invert the buffer by setting it to 0xff. 4. E V A L U A T I O N B O A R D P E R I P H E R A L S In order to better separate the universally useful routines of LibMF from the routines only useful for the ON Semiconductor AX-DVK2 evaluation board, the latter routines will be removed from LibMF in the future. Therefore, the functions in this chapter are deprecated and should no longer be used. Instead, a new library called libaxdvk2 will provide support routines for the AX-DVK2 board. The LCD routines are also provided by libaxdvk2. In order to convert existing projects to use the LCD routines of libaxdvk2, perform the following steps: www.onsemi.com AND9382/D Evaluation Board Peripherals 1. For existing AxCode::Blocks installations, add the include and library paths of libaxdvk2 to the global compiler settings. New installations will have the paths automatically configured. Open Settings → Compiler, click on the Search directories tab, and add the paths to the Compiler and Linker sub-tab as illustrated in the following two screen-shots: www.onsemi.com AND9382/D 33 34 Evaluation Board Peripherals 2. For existing projects that use libmflcd.h, replace the include statements for libmflcd.h with include statements for libaxlcd.h www.onsemi.com AND9382/D Evaluation Board Peripherals 3. For existing projects for the AX-DVK2 evaluation board, add libaxdvk2 to the list of libraries to be linked. Open Project → Build Options, click on the Linker settings tab, select the root of the tree in the left pane of the window (marked by 1), and add libaxdvk2 to the list of libraries in the right pane (marked by 2). 4.1. LIBMFLCD.H libmflcd.h contains routines for accessing the alphanumeric 2x16 character liquid crystal display (LCD) on the evaluation board. libmflcd.h routines are blocking and do not require an interrupt. The routines may take a very long time to complete due to the slowness of the LCD. 4.1.1. VOID LCD_INIT( VOID) This function initializes the interface and resets the LC display and sets it up. www.onsemi.com AND9382/D 35 36 Evaluation Board Peripherals 4.1.2. VOID LCD_PORTINIT( VOID) This function only initializes the interface, but leaves the display alone. It can be used instead of lcd_init() when waking up from sleep or deepsleep while the display was kept powered, and it is undesirable if the display contents change. 4.1.3. V O I D L C D _ S E T P O S ( U I N T 8_ T V ) This function positions the LC display write cursor. Top line characters are numbered from left to right from 0x00 to 0x0F, and bottom line characters are numbered from 0x40 to 0x4F. The cursor does not auto-wrap from the top to the bottom line. After calling lcd_setpos(), lcd_waitshort() must be called or an equivalent delay must be kept before accessing the LCD again. 4.1.4. VOID LCD_WRITESTR(CONST CHAR *CH) This function writes the null terminated C string pointed to by ch to the display at the current write cursor location. \n causes the output to continue at the beginning of the second line. 4.1.5. V O I D L C D _ W R I T E H E X 16( U I N T 16_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) V O I D L C D _ W R I T E H E X 32( U I N T 32_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) These functions write a hexadecimal number (val) to the display. The number of digits is given by nrdig. Leading characters are filled with zeros. flags is a bitwise or combination of the WRNUM constants documented in section 2.3.19 4.1.6. V O I D L C D _ W R I T E N U M 16( U I N T 16_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) V O I D L C D _ W R I T E N U M 32( U I N T 32_ T V A L , U I N T 8_ T N R D I G , U I N T 8_ T F L A G S ) These functions write a decimal number (val) to the display. The number of digits is given by nrdig. flags is a bitwise or combination of the WRNUM constants documented in section 2.3.19 4.1.7. VOID LCD_CLEARDISPLAY( VOID) This function clears the complete LC Display. It must be followed by lcd_waitlong, or the equivalent delay, before accessing the LC Display again. 4.1.8. V O I D L C D _ C L E A R ( U I N T 8_ T P O S , U I N T 8_ T L E N ) This function clears len characters starting at position pos. 4.1.9. VOID LCD_WAITLONG( VOID) VOID LCD_WAITSHORT( VOID) The LC display is very slow processing commands and data. These routines delay the microprocessor by a certain time by busy waiting. One of those routines, or the equivalent www.onsemi.com AND9382/D Evaluation Board Peripherals delay, should be called after each LC command or character. Which LC commands require the long delay is detailed in the LC display datasheet. 4.1.10. V O I D L C D _ W R I T E C M D ( U I N T 8_ T C M D ) This low level routine writes a command to the display. 4.1.11. V O I D L C D _ W R I T E D A T A ( U I N T 8_ T D ) This low level routine writes a character to the display. ON Semiconductor and the ON logo are registered trademarks of Semiconductor Components Industries, LLC (SCILLC) or its subsidiaries in the United States and/or other countries. SCILLC owns the rights to a number of patents, trademarks, copyrights, trade secrets, and other intellectual property. A listing of SCILLC’s product/patent coverage may be accessed at www.onsemi.com/site/pdf/Patent-Marking.pdf. SCILLC reserves the right to make changes without further notice to any products herein. SCILLC makes no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does SCILLC assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation special, consequential or incidental damages. “Typical” parameters which may be provided in SCILLC data sheets and/or specifications can and do vary in different applications and actual performance may vary over time. All operating parameters, including “Typicals” must be validated for each customer application by customer’s technical experts. SCILLC does not convey any license under its patent rights nor the rights of others. SCILLC products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the SCILLC product could create a situation where personal injury or death may occur. Should Buyer purchase or use SCILLC products for any such unintended or unauthorized application, Buyer shall indemnify and hold SCILLC and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that SCILLC was negligent regarding the design or manufacture of the part. SCILLC is an Equal Opportunity/Affirmative Action Employer. This literature is subject to all applicable copyright laws and is not for resale in any manner. PUBLICATION ORDERING INFORMATION LITERATURE FULFILLMENT: Literature Distribution Center for ON Semiconductor 19521 E. 32nd Pkwy, Aurora, Colorado 80011 USA Phone: 303-675-2175 or 800-344-3860 Toll Free USA/Canada Fax: 303-675-2176 or 800-344-3867 Toll Free USA/Canada Email: [email protected] N. American Technical Support: 800-282-9855 Toll Free USA/Canada. Europe, Middle East and Africa Technical Support: Phone: 421 33 790 2910 Japan Customer Focus Center Phone: 81-3-5817-1050 www.onsemi.com Order Literature: http://www.onsemi.com/orderlit For additional information, please contact your local Sales Representative ON Semiconductor Website: www.onsemi.com AND9382/D 37