View PPSMMANUAL_1394047.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

ii table of contents pda personal portable system manager programmers manual 3.1 ppsm initialization and applications integration . . . . . . . . . . . . . . . . 3-1 ppsm initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 task registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3.2 ppsm application programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 active area registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 messages from ppsm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 3.3 data representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 3.4 naming convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 constants and labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 local variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 local pointer variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 global pointer variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 part ii writing ppsm applications chapter 4 pen input handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 4.1 active area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 icon area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 input area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 4.2 creating an active area. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 4.3 removing an active area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 4.4 suspending an active area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 4.5 active area enquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 4.6 put active area to front of list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 4.7 pen echoing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 4.8 pen color and pen size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 4.9 creating a control active area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 4.10 removing a control active area . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 4.11 push active area list into background . . . . . . . . . . . . . . . . . . . . . . . 4-6 4.12 pop active area list to foreground . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 personal portable system manager motorola semiconductor products sector f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
copyright 1995-1999 by motorola, inc. produced by dragonball operation, wssg, motorola fax: (852) 2666-6551 email: portable@email.sps.mot.com website: http://www.apspg.com/products/ppsm/ppsm.html document number ppsm version release date comment pdapsm01u18-10 2.0 november 15, 1995 pdapsm01u18-11 2.1 may 13, 1996 addendum to ppsm v2.0 pdapsm03spm1-10 3.0 march 5, 1997 pdapsm03spm1-11 3.1 november 15, 1998 pdapsm03spm1-12 3.11 apirl 20, 1999 motorola reserves the right to make any modifications or updates to this product or any component thereof for any reason whatsoever without further notice to anyone. motorola does not assume any liability arising out of the application or use of this product nor any component thereof; neither does it convey nor license under its patent rights or copyrights nor the patent rights or copyrights of others all or any portion of this product. motorola products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, other applications intended to support or sustain life, or for any other application in which the failure of the motorola product could create a situation where personal injury or death may occur. should buyer purchase or use motorola products for such unintended or unauthorized application, buyer shall indemnify and hold motorola 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 claims alleges that motorola was negligent regarding the design or manufacture of the part. motorola and are registered trademarks of motorola, inc. all rights reserved. pda personal portable system manager programmers manual table of contents i table of contents table of contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii part i ppsm architecture chapter 1 introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 1.1 what is ppsm? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 1.2 strengths and features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 1.3 software development environment . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 1.4 hardware development environment . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 chapter 2 ppsm system overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 2.1 interrupt handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 2.2 error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 2.3 i/o devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 pen input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 screen format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 hardware cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 2.4 data storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 2.5 font management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 2.6 memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 2.7 power management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 direct control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 automatic control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 2.8 task management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 ppsm tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 application state transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 task swapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 2.9 timer management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 chapter 3 ppsm programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
vi table of contents pda personal portable system manager programmers manual 11.2 power modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 11.3 system internal modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 initialization mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 system mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 wake-up mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 11.4 application modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 normal mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4 doze mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4 sleep mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5 11.5 power management tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6 setting duty cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6 setting doze period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6 setting sleep period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6 going into doze mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7 going into sleep mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7 11.6 i/o ports control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7 disabling i/o port before doze mode . . . . . . . . . . . . . . . . . . . . 11-7 enabling i/o port after doze mode . . . . . . . . . . . . . . . . . . . . . . 11-7 disabling i/o port before sleep mode . . . . . . . . . . . . . . . . . . . . 11-7 enabling i/o port after sleep mode . . . . . . . . . . . . . . . . . . . . . . 11-8 chapter 12 12-1 chapter 13 uart communication support . . . . . . . . . . . . . . . . . . . . . . 12-3 13.1 uart communication architecture . . . . . . . . . . . . . . . . . . . . . . . . . 12-3 uart hardware flow control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3 uart interface constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4 uart interface interrupt message . . . . . . . . . . . . . . . . . . . . . . . 12-9 13.2 uart configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9 configuring the uart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10 inquiring the uart configurations . . . . . . . . . . . . . . . . . . . . . . 12-11 setting data transmission time out . . . . . . . . . . . . . . . . . . . . 12-11 setting data transmission delay . . . . . . . . . . . . . . . . . . . . . . . 12-11 13.3 sending data to the uart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12 initiating a send request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12 terminating a send request . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13 13.4 receiving data from the uart . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13 initiating a receive request . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-14 reading received data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-14 terminating a receive request . . . . . . . . . . . . . . . . . . . . . . . . 12-14 setting data reception time out . . . . . . . . . . . . . . . . . . . . . . . 12-15 pda personal portable system manager programmers manual table of contents iii chapter 5 character input methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 5.1 soft keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 starting soft keyboard character input . . . . . . . . . . . . . . . . . . . . 5-2 auto-key-repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 terminating soft keyboard character input . . . . . . . . . . . . . . . . . 5-3 suspend soft keyboard character input . . . . . . . . . . . . . . . . . . . 5-3 5.2 handwriting recognition input pad . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 the input pad mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5 starting handwriting character input . . . . . . . . . . . . . . . . . . . . . . 5-5 terminating handwriting character input . . . . . . . . . . . . . . . . . . . 5-6 chapter 6 using graphics tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1 6.1 display screen format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 lcd display screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 panning display screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 6.2 screen initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 lcd display screen in relation to the touch panel . . . . . . . . . . . 6-3 screen resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 6.3 sample lcd display screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 6.4 1 bit-per-pixel graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 drawing operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 6.5 2 bits-per-pixel graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 drawing operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 6.6 graphics tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10 6.7 get lcd display screen width . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11 6.8 get lcd display screen height . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11 6.9 get panning screen width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12 6.10 get panning screen height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12 6.11 set pattern fill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12 6.12 set dot width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13 6.13 displaymove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13 6.14 direct all graphics output to off-screen memory . . . . . . . . . . . . . . . 6-13 6.15 change panning screen parameters . . . . . . . . . . . . . . . . . . . . . . . . 6-14 6.16 fill the whole panning screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17 6.17 draw a dot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17 6.18 draw a horizontal line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19 6.19 draw a vertical line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
iv table of contents pda personal portable system manager programmers manual 6.20 draw a line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22 6.21 draw a rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23 6.22 draw a circle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25 6.23 draw an ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26 6.24 draw an arc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27 6.25 draw a vector from a list of points . . . . . . . . . . . . . . . . . . . . . . . . . 6-30 6.26 put a rectangular area on panning screen . . . . . . . . . . . . . . . . . . 6-30 special cases of putrec() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31 6.27 save a rectangular area from panning screen . . . . . . . . . . . . . . . 6-33 6.28 exchange a rectangular area with memory . . . . . . . . . . . . . . . . . . 6-33 6.29 fill a rectangular area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34 6.30 inverse a rectangular area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34 6.31 hardware cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35 set hardware cursor size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35 set hardware cursor position . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36 set hardware cursor status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36 get hardware cursor status . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36 set hardware cursor blinking frequency . . . . . . . . . . . . . . . . . 6-37 turn hardware cursor off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37 6.32 display other region of panning screen . . . . . . . . . . . . . . . . . . . . . 6-37 6.33 get lcd display origin on panning screen . . . . . . . . . . . . . . . . . . 6-37 6.34 allocate memory for panning screen . . . . . . . . . . . . . . . . . . . . . . . . 6-38 chapter 7 database management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 7.1 data format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 formatted data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 unformatted data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 7.2 the database manipulation tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 7.3 creating and editing a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 7.4 searching and retrieving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 7.5 navigating along a record list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 chapter 8 text display management . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1 8.1 text representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1 8.2 text display area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1 8.3 text templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 pda personal portable system manager programmers manual table of contents v creating text templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 deleting text templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 8.4 text properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 setting text display layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 setting text outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 setting font attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 8.5 text mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 displaying text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 removing text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 8.6 text character cursor position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8 setting the character cursor position . . . . . . . . . . . . . . . . . . . . . . 8-8 reading the character cursor position . . . . . . . . . . . . . . . . . . . . . 8-8 chapter 9 timer management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 9.1 reading system date and time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 9.2 setting system date and time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 9.3 reading clock alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 9.4 setting clock alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 9.5 clearing clock alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 9.6 setting periodic alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 9.7 setting timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 9.8 setting input timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 9.9 continuous reference timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 9.10 read the reference timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 9.11 set reference timer alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 9.12 compute reference times differences . . . . . . . . . . . . . . . . . . . . . . . 9-4 chapter 10 memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 10.1 allocating memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 10.2 freeing memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 10.3 reallocating memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 10.4 copying memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 10.5 inquiring memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 chapter 11 power management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1 11.1 power control module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
x table of contents pda personal portable system manager programmers manual 21.3 clearrec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4 21.4 clearscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5 21.5 cursorgetorigin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5 21.6 cursorgetpos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6 21.7 cursorgetstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7 21.8 cursorinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7 21.9 cursoroff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-8 21.10 cursorset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-8 21.11 cursorsetblink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-9 21.12 cursorsetorigin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10 21.13 cursorsetpos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10 21.14 cursorsetstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-11 21.15 displaymove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-12 21.16 drawarc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-13 21.17 drawcircle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-13 21.18 drawdot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-14 21.19 drawellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-15 21.20 drawhorz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-16 21.21 drawline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-17 21.22 drawrec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-18 21.23 drawvector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-19 21.24 drawvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-20 21.25 exchangerec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-21 21.26 getdisplayx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-22 21.27 getdisplayy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-23 21.28 getlogicalx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-23 21.29 getlogicaly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-24 21.30 getscreenmem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-24 21.31 invrec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-25 21.32 lcdcontrast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-26 21.33 lcdrefreshrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-27 21.34 lcdscreenmove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-27 pda personal portable system manager programmers manual table of contents vii 13.5 uart hardware flow control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-15 enabling rts/cts hardware flow control . . . . . . . . . . . . . . . . 12-15 disabling rts/cts hardware flow control . . . . . . . . . . . . . . . . 12-15 13.6 data reception with hardware flow control . . . . . . . . . . . . . . . . . . . 12-16 pause data reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16 continue data reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16 13.7 data transmission with hardware flow control . . . . . . . . . . . . . . . . 12-16 pause data transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16 continue data transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17 chapter 14 task management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1 14.1 main task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1 system task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1 14.2 sub-task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2 sub-task management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 14.3 task switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 14.4 message broadcasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 14.5 task control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 14.6 task swapping example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5 14.7 creating a task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-6 14.8 creating a task with specific task parameters . . . . . . . . . . . . . . . . 13-6 14.9 creating a sub task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7 14.10 starting a task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7 14.11 termination of a task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-8 14.12 task reinitialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-8 14.13 task hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-8 14.14 stop task swapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9 chapter 15 inter-task messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1 15.1 message passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1 with delayed task swapping . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2 with immediate task swapping . . . . . . . . . . . . . . . . . . . . . . . . . 14-2 with immediate task swapping and delayed swap back . . . . . 14-2 message passing without task swapping . . . . . . . . . . . . . . . . . 14-3 15.2 message structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3 15.3 sending message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3 15.4 advanced sending message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
viii table of contents pda personal portable system manager programmers manual 15.5 deleting message for current task . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 15.6 deleting message for any task . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 15.7 receiving message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 chapter 16 interrupt handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1 16.1 system interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1 irpt_audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2 irpt_pen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2 irpt_input_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2 irpt_icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3 irpt_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 irpt_rtc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 irpt_timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 irpt_hwr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 irpt_uart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 16.2 device interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 user defined interrupt handlers . . . . . . . . . . . . . . . . . . . . . . . . . 15-6 device interrupt identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-7 application access to handlers . . . . . . . . . . . . . . . . . . . . . . . . . 15-7 request and release interrupt handler service . . . . . . . . . . . . 15-7 16.3 message handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-9 chapter 17 using system tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1 17.1 ppsm initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1 motorola logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2 chapter 18 audio tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-151 18.1 audio playing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-151 18.2 tone playing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-151 18.3 wave playing (dragonball-ez only) . . . . . . . . . . . . . . . . . . . . . . . 17-152 18.4 stop the audio playing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-153 part iii api toolset chapter 19 pen input tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1 19.1 activeareadisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1 pda personal portable system manager programmers manual table of contents ix 19.2 activeareaenable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1 19.3 activearearead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2 19.4 activeareasuspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3 19.5 activeareatofront . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4 19.6 activelistpop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4 19.7 activelistpush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5 19.8 areaechodisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6 19.9 areaechoenable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6 19.10 activeareaposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-7 19.11 ctrlicondisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-7 19.12 ctrliconenable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-8 19.13 iconscanoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-9 19.14 iconscanon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-10 19.15 pencalibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-10 19.16 penechoparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-11 19.17 pengetinput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-11 19.18 pensetinputmax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-12 19.19 pensetinputorg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-13 19.20 pensetrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-13 19.21 scanningoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-14 19.22 scanningon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-14 chapter 20 character input tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1 20.1 advopeninputpad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1 20.2 advopensoftkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2 20.3 closeinputpad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3 20.4 closesoftkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4 20.5 openinputpad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5 20.6 opensoftkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6 chapter 21 graphics tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1 21.1 changepanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1 21.2 changewindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
xiv table of contents pda personal portable system manager programmers manual 28.4 taskcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-4 28.5 taskhook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-5 28.6 taskreinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-5 28.7 taskstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6 28.8 taskterminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-7 chapter 29 inter-task messaging tools . . . . . . . . . . . . . . . . . . . . . . . . . 28-1 29.1 advmessagedelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-1 29.2 advsendmessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-1 29.3 messagedelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-3 29.4 sendmessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-3 chapter 30 interrupt handling tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-1 30.1 irptgetdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-1 30.2 irptrelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-3 30.3 irptrequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-4 30.4 irptsenddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-6 chapter 31 system tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-1 31.1 ppsminit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-1 31.2 readsmversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-3 chapter 32 audio tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-1 32.1 advaudioplaywave (dragonball-ez only) . . . . . . . . . . . . . . . . . . . . 31-1 32.2 audioinuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2 32.3 audioplaytone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2 32.4 audioplaywave (dragonball-ez only) . . . . . . . . . . . . . . . . . . . . . . . 31-3 32.5 audiostoptone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-4 32.6 audiostopwave (dragonball-ez only) . . . . . . . . . . . . . . . . . . . . . . . 31-4 part iv system integrators pda personal portable system manager programmers manual table of contents xi 21.35 putchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-28 21.36 putrec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-29 21.37 saverec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-30 21.38 setdotwidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-31 21.39 setpatternfill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-31 chapter 22 database management tools . . . . . . . . . . . . . . . . . . . . . . . 21-1 22.1 dbadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1 22.2 dbaddrecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1 22.3 dbaddrectotop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2 22.4 dbappendrecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-3 22.5 dbchangestddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-4 22.6 dbchangeunfdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-5 22.7 dbdelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-6 22.8 dbdeleterecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-6 22.9 dbgetfirstrecid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-7 22.10 dbgetnextrecid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-8 22.11 dbgetprevrecid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-8 22.12 dbreaddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9 22.13 dbreadtotalnumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10 22.14 dbreadtotalnumberrecords . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11 22.15 dbreadunfdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11 22.16 dbrecordsecret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12 22.17 dbsearchdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-13 22.18 dbsecretflag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-14 22.19 dbsetrecordsecretflag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15 22.20 dbsetsecretflag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15 chapter 23 text tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1 23.1 textcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1 23.2 textdelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1 23.3 textmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2 23.4 textreadcursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
xii table of contents pda personal portable system manager programmers manual 23.5 textsetcursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3 23.6 textsetdisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-4 23.7 textsetfont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5 23.8 textsetoutlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-6 23.9 textsetup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-7 23.10 textunmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9 chapter 24 timer tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-1 24.1 alarmclear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-1 24.2 alarmclearid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-1 24.3 alarmread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2 24.4 alarmreadid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2 24.5 alarmset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-3 24.6 alarmsetid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-4 24.7 datetimeread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5 24.8 datetimeset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6 24.9 deletetimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7 24.10 inputtimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7 24.11 reffinetimealarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8 24.12 reffinetimealarmid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8 24.13 reffinetimediff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-9 24.14 reffinetimeread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10 24.15 reftimealarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10 24.16 reftimealarmid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11 24.17 reftimediff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11 24.18 reftimeread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-12 24.19 setperiod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-12 24.20 setperiodid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-13 24.21 timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-14 24.22 timeoutid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-15 chapter 25 memory management tools . . . . . . . . . . . . . . . . . . . . . . . . . 24-1 25.1 lcalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-1 pda personal portable system manager programmers manual table of contents xiii 25.2 lfree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-1 25.3 lmalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-2 25.4 lrealloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-3 25.5 moveblock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-3 25.6 taskmemused . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-4 25.7 taskstackavail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-4 25.8 totalmemsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5 25.9 totalmemused . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5 chapter 26 power management tools . . . . . . . . . . . . . . . . . . . . . . . . . . 25-1 26.1 setdozemode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-1 26.2 setdozeperiod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-1 26.3 setdutycycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2 26.4 setsleepmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-3 26.5 setsleepperiod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-3 chapter 27 uart communication tools . . . . . . . . . . . . . . . . . . . . . . . 26-1 27.1 uartconfigure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-1 27.2 uartflowctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3 27.3 uartinquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3 27.4 uartrcvctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-4 27.5 uartreaddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-6 27.6 uartreceive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-6 27.7 uartsend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-7 27.8 uartsendabort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-8 27.9 uartsendctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-9 27.10 uartsetdelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-10 27.11 uarttimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-11 chapter 28 task handling tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-1 28.1 advtaskcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-1 28.2 appswap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-2 28.3 subtaskcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-3 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
xviii personal portable system manager programmers manual pda personal portable system manager programmers manual table of contents xv guide chapter 33 how to make rom? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-1 33.1 boot strap code (boot.s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-1 68k start-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-1 chip selects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-3 peripheral devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-3 33.2 linker supplications file for rom . . . . . . . . . . . . . . . . . . . . . . . . . . 32-3 33.3 generating s-record file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-4 loader options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-4 loader commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-5 chapter 34 device drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-1 34.1 system configuration drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-1 boot strap driver (boot.s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-1 user interrupt handler installation driver (irptdev.c) . . . . . . . . . 33-1 34.2 pen input device driver (pendev.c) . . . . . . . . . . . . . . . . . . . . . . . . . 33-3 pen initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-4 pen interrupt enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-5 pen interrupt disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-6 pen read device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-7 34.3 pen calibration(peninit.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-8 34.4 lcd device drivers (lcddev.s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-8 1 bit/pixel initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-8 2 bits/pixel initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-9 34.5 handwriting recognition engine driver (hwr.c) . . . . . . . . . . . . . . . . 33-9 handwriting recognition engine reset . . . . . . . . . . . . . . . . . . . 33-9 handwriting recognition engine initialization . . . . . . . . . . . . . . 33-10 process one stroke of handwriting input data . . . . . . . . . . . . 33-10 initiate character recognition for the handwriting input . . . . . 33-11 34.6 font driver (font.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-11 font library information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-12 font library or font generation engine initialization . . . . . . . . 33-12 font accessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-13 34.7 uart device driver (uartdev.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-14 sending the break character . . . . . . . . . . . . . . . . . . . . . . . . . 33-14 34.8 power management driver (iodev.c) . . . . . . . . . . . . . . . . . . . . . . . 33-14 enabling i/o ports when leaving from doze mode . . . . . . . . . . 33-15 disabling i/o ports when going to doze mode . . . . . . . . . . . . . 33-15 enabling i/o ports when leaving from sleep mode . . . . . . . . . . 33-15 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
xvi table of contents pda personal portable system manager programmers manual disabling i/o ports when going to sleep mode . . . . . . . . . . . . . 33-16 chapter 35 linker specification file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-1 35.1 .spc file for a ram-only system . . . . . . . . . . . . . . . . . . . . . . . . . . 34-1 35.2 .spc file for a rom-ram system . . . . . . . . . . . . . . . . . . . . . . . . . 34-2 35.3 for singlestep debugging system (sds) user . . . . . . . . . . . . . . . . 34-2 chapter 36 trap usage in ppsm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 36.1 ppsm tools calling structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 36.2 trap implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 stub library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 trap service handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 appendices a error code definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . a-1 b list of references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . b-1 c index of ppsm tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . c-1 personal portable system manager programmers manual xvii what is ppsm? audience & purpose part i part ii part iii part iv appendices preface personal portable system manager (ppsm) is a compact operating system designed specifically for the dragonball tm family of the micro-controllers. this operating system enables most handheld electronic products with lcd displays such as advanced pagers, advanced cellular phones, game machines, gps, instruments, organizers, and personal digital assistants (pda). the first three parts of this manual are oriented to those software engineers want- ing to learn the important "rules" of ppsm programming. each chapter concen- trates on a specific aspect of the ppsm application programming interface (api). the forth part of this manual is oriented to system integrators who are responsible for building and configuring ppsm systems. "ppsm architecture" describes the ppsm environment and architecture. "writing ppsm applications" concentrates on the features supported by ppsm for application development. examples are given to better illustrate the methodology. this part is targeted particularly to beginners who are exploring the use of ppsm tools. therefore, the tools in each chapter are arranged in the suggested order of tools for writing ppsm applications. "api toolset" details the usage of each of the tools. this part is targeted particu- larly to those experienced engineers who are familiar with the ppsm program- ming methodology. therefore, the tools in each chapters are arranged in alphabetical order for quick referencing. "system integrators guide" focuses on assisting the system integrators to build and configure ppsm system by providing the necessary background information. at the end of the manual, "appendices" is included to supplement the manual with information. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
1-2 introduction personal portable system manager programmers manual 1.2 strengths and features ppsm is modularly designed to speed the application development cycle time by shielding the developer from the intricacies of the dragonball tm hardware and providing a good toolset for the application software developer to concentrate on their specific product design. perfect for handheld devices, ppsm is a resource effective system which requires very small memory space and is pen-centric. strengths: ? speeds up application development cycle time ? compact rom size perfect for handheld devices ? modular software architecture ?pen-centric ? third party applications successfully ported on ppsm such as multilingual handwriting recognition, scalable and bitmap fonts, infrared and email communication. ? application code is completely device independent ? microsoft windows based ansi c development tools for rapid application development features: ? pen / touch panel input support ? 32-bit real time operating system ? real time interrupt handling ? power management ? 16-bit text data representation for multilingual support figure 1-1 architecture of ppsm on the mc68328 platform application ppsm kernel ppsm tools pen input driver lcd driver pc card driver irda driver flexstack tm driver pen input lcd pc card irda flex tm dragonball tm based portable system software hardware personal portable system manager programmers manual part i ppsm architecture f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
personal portable system manager programmers manual personal portable system manager programmers manual introduction 1-1 chapter 1 introduction 1.1 what is ppsm? personal portable system manager (ppsm) is a compact operating system designed specifically for the dragonball tm family of the microcontrollers. this operating system enables most handheld electronic products with lcd displays such as advanced pagers, advanced cellular phones, game machines, gps, instruments, organizers, and personal digital assistants (pda). ppsm is a real time 32-bit kernel with prioritized interrupt scheduling. all tasks are interrupt-driven, e.g. applications are activated by selecting the corresponding icons. because ppsm is written in c, it's highly portable. it contains thorough, configurable, and easy to learn toolsets which aid developers in their application development process. the ppsm tools consist of pen input, graphics, database, text, character input, system and communication. application developers have the freedom to design a sophisticated user-interface and to configure dragonball tm with easy-to-use api for lcd based products. the ppsm toolset, together with its device drivers, provides the basic control of the lcd, the drawing functions, the real time clock and the uart. the ppsm kernel does not access hardware devices directly. all peripheral devices are controlled by the kernel indirectly through software device drivers. by supplying the appropriate device drivers with each peripheral, it gives system integrators greater flexibility to use various types of hardware devices without changing the core of the software. figure 1-1 shows the architecture of ppsm on the dragonball tm family platform. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
2-2 ppsm system overview personal portable system manager programmers manual 2.2 error handling unless otherwise specified, all ppsm tools return ppsm_ok upon successful completion. a value other than ppsm_ok is the error code, indicating an error has occurred. each error code uniquely defines the cause and nature of the error. refer to appendix a - error code definition for a complete error code listing. 2.3 i/o devices this section describes the lcd display screen and the touch sensitive panel. figure 2-2 shows the screen format for the ppsm system. there are three major areas: ? pen input area ? display screen ? panning screen figure 2-2 an example of ppsm coordinate system (0,0) lcd panel (319,239) (379,259) (-59,-29) (379,-29) (-59,259) (0,239) (319,0) lcd origin (xinputorigin, yinputorigin) - ve - ve + ve + ve touch panel (xinputmax, yinputmax) (xlcdmax, ylcdmax) personal portable system manager programmers manual introduction 1-3 ? high level api toolsets ? multiple grey levels and software configurable lcd display support ? lcd hardware cursor and panning support 1.3 software development environment ansi c is the main programming language, with m68k assembly language for implementation of low level routines, such as interrupt, trap vector initialization and hardware device driver. the development environment is on ibm-compatible pc running under windows 3.1 and windows 95 with singlestep compiler/ debugger, from software development systems, inc. singlestep provides source level and instruction debugging on the hardware target machine, as well as a simulator running on the host pc. 1.4 hardware development environment the m68328 and m68ez328 application development system (ads) is used as the reference development platform throughout this manual. the a/d convertor used is a 10-bit component, giving a resolution of 1024 in x and 1024 in y direction. for details on the hardware configuration, please refer to m68328 ads users manual v2.0 and m68ez328 ads users manual v1.1. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
1-4 introduction personal portable system manager programmers manual personal portable system manager programmers manual ppsm system overview 2-1 chapter 2 ppsm system overview 2.1 interrupt handling an application will always be running under the ppsm at any given time. it will either be the active task, or a suspended task while ppsm is servicing an interrupt. an application is scheduled out under any one of the following conditions: ? interrupt from pen ? interrupt from a communication device ? interrupt from power management ? interrupt from timer ? interrupt from messages application execution pen input handler timer handler handler handler communication message swap task swap task pen sampling power mode pen-down detection a/d doze/sleep timer interrupt device interrupt message passing pen interrupt figure 2-1 task execution states handwriting recognition direct doze/sleep f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
2-6 ppsm system overview personal portable system manager programmers manual choose to control the system's power management features directly, or use the ppsm's automatic power management features. 2.7.1 direct control a set of tools provide the applications the ability to directly control the following during normal mode: ? switch into any of the power saving modes ? the duty cycle of the processor for each application 2.7.2 automatic control a set of tools are available for the caller to set the parameters for automatic power management features provided by ppsm: ? to switch automatically to a lower power saving mode when system is idle ? to control user defined i/o ports during transitions of the power saving modes 2.8 task management each application running on ppsm is considered as a task. only one of these tasks can be actively running at anytime. 2.8.1 ppsm tasks there are two types of ppsm tasks: application task that are stand alone (main task) and tasks that are spawned off by another task (sub-task). 2.8.1.1 main task most applications fall into the main task category. main tasks run independently of each other. there cannot be more than 1 main task running at anytime. they are created by the system tool taskcreate() or advtaskcreate(). once a main task is created, it can be started in one of the following ways: ? by using the system tool taskstart() ? by pressing the application icon ? by messages sent by another task 2.8.1.2 sub-task sub-task, on the other hand, can be active at the same time as the parent task that generated the sub-task. message passing is possible between the sub-task and its parent. sub-task uses the display resource of its parent and can only be started with the system tool subtaskcreate(). sub-tasks are tied to the parent task. if the parent task is swapped out or personal portable system manager programmers manual ppsm system overview 2-3 2.3.1 pen input 2.3.1.1 pen input area this is the touch sensitive panel input area. the coordinate system used for the touch panel is the same as that for the lcd display screen. the reference point, (0,0) or the origin, is at the top-left corner of the lcd display screen. as you can see from figure 2-3 , the input coordinates outside of the lcd display screen can have a negative value. ppsm allows negative coordinates for pen input. this allows applications to implement features such as off screen icon and off screen writing area. if the lcd display screen physical size is exactly the same as the touch panel, all coordinates from the pen input will always be positive. 2.3.1.2 active area an active area is defined as a rectangular region of the pen input area where an application or an action will execute if the region is pressed. an example of this is an icon, or an action button. active areas are classified into two groups, icon area and input area. please refer to section 4.1 - active area for full details on active area definition. lcd display panel origin (0,0) negative coordinates positive coordinates touch panel figure 2-3 ppsm coordinate system f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
2-4 ppsm system overview personal portable system manager programmers manual 2.3.2 screen format 2.3.2.1 lcd display screen the display screen is the lcd display area where applications can display images. the lcd module can handle both 1 bit per pixel and 2 bits per pixel graphics, giving black and white display or 4 grey levels display respectively. display data, such as graphics and text, can only be seen within the display screen area. 2.3.2.2 panning screen the panning screen is an extension to the lcd display screen. its main purpose is to allow applications to write data to an area outside of the actual display area. although applications can write to this area, data will not be displayed on the screen unless this area is being mapped to the lcd display screen. pen input areas on the panning screen will receive pen input data only when they overlap with the lcd display screen. 2.3.3 hardware cursor the maximum hardware cursor size is 31 pixels wide by 31 pixels high. during task swapping, the hardware cursor status, size, position and the offset of display origin on panning screen in current task will be saved a nd the new tasks cursor status, position, size and the offset of display origin on panning screen will be used. 2.4 data storage databases are the main means of data storage in ppsm. a set of database tools is available in ppsm to support data storage and manipulation. ppsm database are in global database which can be shared among different tasks. when a database is created, ppsm will pass back a unique database identifier to the application. application will need to use this identifier as the key for subsequent access to that particular database. a ppsm database does not have any limit in number of database nor record in database except the memory limitation in creating these database and record. the ppsm database tools provides basic operations such as add, delete, modify and search for particular data. additional tools are provided to help manipulate the record list. in particular, the tool dbgetfirstrecid(), dbgetnextrecid(), and dbgetprevrecid() are meant to facilitate the implementation of more sophisticated searching algorithm. the description, calling convention, and example usage of each database tool will appear in chapter 7 - database management and chapter 21 - database management tools personal portable system manager programmers manual ppsm system overview 2-5 2.5 font management ppsm supports 8x10 english, 16x20 english, 16x16 big5 chinese and 16x16 gb chinese bitmap fonts, and big5 chinese scalable fonts. the english bitmap fonts are included in ppsm. the other fonts are provided by third party vendors. system integrators need to work with third party vendors about the availability of these fonts. the font bitmap lookup or generation is handled by a font driver, refer to section 33.6 - font driver (font.c) , and is transparent to the applications. applications gain access to these fonts for displaying text using the ppsm text tools. 2.6 memory management ppsm provides a set of memory management tools for application to access local memory space. a heap is managed by ppsm which allows callers to dynamically allocate memory from the system. when using ppsm, the standard memory tools provided by the compiler will be disabled. four memory management tools are available: ? lcalloc() memory allocation with initialization with zero ? lmalloc () memory allocation ? lrealloc() memory re-allocation ? lfree() memory release ppsm also provides a set of memory inquiry tools for application to get the run- time memory size. three memory inquiry tools are available: ? taskmemused() memory used by a task through lmalloc() ? totalmemused() memory used by the whole system through lmalloc() ? totalmemsize() memory available through lmalloc() ? taskstackavail() stack can be used by the current task the size of the largest chunk of memory can be allocated through lmalloc() can be known by calling lmalloc( largest_malloc_size ). the size of the heap memory depends very much on the amount of memory available in the hardware system, please refer to chapter 32 - how to make rom? on how memory size is specified in ppsm. for singlestep debugging system (sds) user, please refer to chapter 34.3 for further description in how to set an optimum size for malloc space. 2.7 power management ppsm utilizes the power control module of dragonball tm to implement a set of power management tools to achieve system power saving. applications can f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
3-2 ppsm programming personal portable system manager programmers manual handler assignment. it must be called before any other ppsm tool. as an option, it can also perform the pen to screen calibration. this should only be done once at system start-up. 3.1.2 task registration an application is treated as a task in ppsm. after ppsm is initialized, each application task on the system must be registered with ppsm before the application can make use of the ppsm tools. when integrating the individual applications onto the system, the system integrator must first call one of the task creation tools for each application. there are two types of tasks, main task or sub task (refer to section 13.1 - main task and section 13.2 - sub-task ). this registration of tasks ensures that the run time memory and stack required for each application are allocated within ppsm's memory system. associated with each main application task is an optional application launch icon. this launch icons position on the touch panel can be specified in the task creation tool. the application is put to the foreground whenever this application icon is selected by the pen input device. when writing an application task, the developer can treat each task as a stand alone procedure as ppsm resources are individually allocated. this implementation of tasks allow a number of applications to be written independently and linked together at the end to form a single system. for details of the task creation tools, please refer to section 13.7 - creating a task , section 13.8 - creating a task with specific task parameters and section 13.9 - creating a sub task . after all applications have been registered, the first application task can be started by calling the tool taskstart(). this tool never returns and other applications within the system will be started when the corresponding application launch icon is pressed. 3.2 ppsm application programming this section describes the general flow for most applications operating under the ppsm environment. the typical flow for most ppsm applications is shown in figure 3-2 . after the application initializes itself and registers icons and draw areas with ppsm, it would continuously call irptgetdata() to check for incoming events. when an event occurs, the application would process the event and then loop back to irptgetdata() to wait for more events. personal portable system manager programmers manual ppsm system overview 2-7 terminated, the sub-task will be swapped out or terminated too. sub-task inherits the input pad and panning screen properties from the parent task at creation. 2.8.2 application state transition application tasks have three states. figure 2-4 shows the three states of an application. ?active ? suspended ? stopped 2.8.2.1 active state this is the state when an application is actively being accessed by the user. all hardware resources are available to an active task. 2.8.2.2 suspended state an application task is put into suspended state when the kernel is interrupted during active state execution. the interrupt service routine, running in supervisor mode, will become the active task. during the active-to-suspended transition, only the registers that are used by the interrupt handler are saved. the suspended task will return to active state if no other application is selected, otherwise it will be put into stopped state. 2.8.2.3 stopped state an application changes from suspended state to stopped state when another application is selected. in this execution state, all registers and application display bitmap image are stored by the kernel. a task will exit from the stopped state to active state when the application is re- figure 2-4 application state transitions active suspended stopped interrupt application selected interrupt return from return from interrupt application terminated f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
2-8 ppsm system overview personal portable system manager programmers manual selected. it will continue execution from the point when it was put into stopped state. 2.8.3 task swapping task swapping is performed by ppsm transparent to the application programmer. a task swapping is executed when an application, other than the actively running application, needs to become active. this normally occurs when ppsm kernel receives an interrupt, such as timer or user pen-down. for example, when an application icon for a new application is pressed, the task that is actively running will be put into stopped state and the new task will become active. 2.9 timer management ppsm maintains a reprogrammable clock that is defaulted to 9:00am 1 st of january, 1997 upon start up. this clock is incremented in 1 second interval and never stops. a set of timer tools are available for time management. this allows the programmer to set system clock, clock alarm, time-out, and input time-out in their application. personal portable system manager programmers manual ppsm programming 3-1 chapter 3 ppsm programming ppsm programming mainly consists of two parts: ? ppsm initialization and applications integration ? individual ppsm application programming 3.1 ppsm initialization and applications integration a ppsm system must first be initialized before any ppsm tools and resources can be assigned and used. system integrators may choose to integrate multiple individual ppsm applications into one ppsm system. for example, a simple ppsm organizer may consist of applications such as address book, calendar, scheduler and calculator. figure 3-1 shows a typical ppsm system start up flow. first, ppsm must be initialized, then applications to be integrated onto the system must be registered with ppsm individually. the last step to get the system going is to start the application which is chosen to run first. 3.1.1 ppsm initialization the ppsminit() tool performs all the internal resources initialization and interrupt register task 1 figure 3-1 ppsm system start up flow chart start chosen task initialize ppsm register task 2 register task n . . . f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
3-6 ppsm programming personal portable system manager programmers manual ?ok ? unknown 3.4.3 local variables all local variables start with lower case, with capitalised words in the variable names. there are no underscores between words. example 3-3 local variable names ?xpos ?ypos ? datalen ?temp ?rate 3.4.4 global variables same as local variables, except that all global variable names starts with a lower case g. example 3-4 global variable names ?gcurrenttask ?girptmask ?gsystemclock 3.4.5 local pointer variables all local pointer variables start with a lower case p, with capitalised words in the variable names. there are no underscores between words. example 3-5 local pointer variable names ? psourceaddr ?pdestaddr ? p ta s kta b l e ?preturnsize 3.4.6 global pointer variables same as local pointer variables, except that all global variable names starts with a lower case gp example 3-6 global pointer variable names ? gpsyslist ? gpphonebook ? gpsrcmem personal portable system manager programmers manual ppsm programming 3-3 3.2.1 active area registration ppsm is designed as a pen-centric system. input from the input panel is through initialize other application specifics any interrupt pending? figure 3-2 application flow chart call irptgetdata is interrupt irpt_icon? is interrupt irpt_pen? is interrupt irpt_xxx? no no no no yes yes yes yes process icon process pen process xxx . . . . . . . . . register icons and draw areas f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
3-4 ppsm programming personal portable system manager programmers manual regions defined in ppsm as active areas. active area provides an easy method for applications to receive pen input samples from the input panel without the need to monitor the hardware constantly. ppsm uses interrupt to perform pen sampling, maximizing processor power utilization. an active area is defined as a rectangular region of the input panel where interrupt messages are generated to the application when the region is pressed. active areas only generate messages to the application that created the area. an example of an active area is an icon, an action button, scratch pad or drawing area. when application needs to perform pen input, it must define the area location and register each active area with ppsm before the area can respond to a pen input. all remaining areas on the input panel not registered with ppsm will not generate any information to the application. for details on active areas and input methods, please refer to chapter 4 - pen input handling and chapter 5 - character input methods . 3.2.2 messages from ppsm ppsm application should take a pro-active role, i.e., an event driven approach. when external events occur, such as pressing of the input panel, ppsm system automatically intercepts and interprets the event. if the events require attention from the application, such as an active area being pressed, or incoming data from uart, ppsm will package the data in the pre-defined message format and send to the waiting applications interrupt buffer (please refer to chapter 15 - interrupt handling ). however, if the event is not intended for the application, such as pressing of input panel that is not defined as active area, or timeout for going into power saving mode, the event is handled by ppsm internally without any message sent to the application. upon receiving soft interrupt messages sent from ppsm, application tasks should act upon the nature of the message. there are a set of pre-defined messages types for different types of interrupts (refer to section 15.1 - system interrupts and section 15.2 - device interrupts ). application tasks can receive the soft interrupt messages by using the system tool irptgetdata(). the application task should call this tool periodically in the programs flow to check for any incoming events (refer to section 29.1 - irptgetdata ). 3.3 data representation ppsm is a 32-bit system. table 3-1 shows the data types used in ppsm table 3-1 data type definition used in ppsm data type description size (in bytes) u8 unsigned byte 1 p_u8 unsigned byte pointer 4 personal portable system manager programmers manual ppsm programming 3-5 3.4 naming convention for consistency, a set of guidelines is set up for the naming conventions during software development. this is not a fixed requirement, but a recommendation. 3.4.1 procedure all procedure names are in lower case except the first letter of each word within the name will be in upper case. example 3-1 procedure names ?peninit() ? pagercheck() ? drawdot() 3.4.2 constants and labels all constants and labels are in upper case, underscores are permitted. example 3-2 constants and labels ?display_mode ? default_mode s8 signed byte 1 p_s8 signed byte pointer 4 u16 unsigned short 2 p_u16 unsigned short pointer 4 s16 signed short 2 p_s16 signed short pointer 4 u32 unsigned int 4 p_u32 unsigned int pointer 4 s32 signed int 4 p_s32 signed int pointer 4 status unsigned short 2 text unsigned short 2 p_text unsigned short pointer 4 p_void void pointer 4 table 3-1 data type definition used in ppsm data type description size (in bytes) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
4-2 pen input handling personal portable system manager programmers manual upon release, either by pen-up or drag out of the area into another part of the touch panel, another soft interrupt is sent to the application to notify the user of the event. this type of area is designed for buttons and selection icons. 4.1.2 input area input area is an area where writing or drawing is performed. once defined, ppsm will monitor the area with the given pen input characteristics such as sampling rate, pen echoing and pen position sampling. pen echoing is programmable. three modes of operation are available for this type of area, stroke, confined or continuous. 4.1.2.1 stroke mode drawing on stroke type of input area will produce a list of the x and y coordinate integers to the application at the end of the drawing input sequence, usually with a pen-up. this list consists of all points of that single stroke from the pen-input device. when the pen leaves the active area, or pen-up is detected, then the stroke data ends. 4.1.2.2 confined mode confined mode is very much like stroke mode excepts that when the pen input moves out of the defined active area, the coordinates for those points outside the region are truncated to the value defined by the boundary of the active area. this means a stroke will not be broken until pen-up is detected. 4.1.2.3 continuous mode drawing on continuous type of input area will continuously produce individual x and y coordinates to the application as the pen moves across the pen input panel. with this type of input, soft interrupt is generated for each individual point. the last input point will be a set of (-1, -1) for pen-up. developers using this type of area must ensure the soft interrupts are acknowledged as their number can be very significant. 4.2 creating an active area. status activeareaenable (p _u32 areaid , u32 type , u32 mode , s16 xsrc , s16 ysrc , s16 xdest , s16 ydest ) this tool creates a new active area for reading pen input. it returns an identifier of the new area to the caller. once created, the new active area identifier will be returned to the application. the argument type is used to specify whether an icon area or an input area is required. mode specifies the input mode for input area. example 4-1 create an active area 49 u32 nextwinid;/* nextwin's id */ . personal portable system manager programmers manual part ii writing ppsm applications f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
personal portable system manager programmers manual personal portable system manager programmers manual pen input handling 4-1 chapter 4 pen input handling the pen input tools enable application to: ? define active areas to control pen input ? control ink echoing refer to section 6.2.2 - screen resolution . 4.1 active area active area provides an easy method for applications to receive pen input samples from the touch panel without the need to monitor the hardware constantly. ppsm uses interrupt to perform pen sampling, maximizing processors utilization. an active area is defined as a rectangular region of the touch panel where interrupt messages are generated to the creator task when the region is pressed. an example of this is an icon, an action button, scratch pad or drawing area. active areas are only "active" for the task which the pen down has occurred until the corresponding pen up. for example, a main task created active areas "a" and "b", and one of its sub-task( chapter 13 - task management ) created active areas "c" and "d". when a user taps on active area "a"(i.e. a pen down on "a"), only active areas "a" and "b", but not "c" nor "d", will receive messages if the pen moves across them. by the same token, if pen down is made on "c", only "c" and "d" will receive messages. if active areas are overlapping, only the active areas of current task will be able to receive pen messages. there are two types of active areas, icon area and input area. input area types have three different modes of operation. 4.1.1 icon area icon area is for the purpose of selection only. when an icon area is pressed, either from a pen-down or drag in from another area on the touch panel, ppsm generates a soft interrupt and returns the active area identifier to the application. type mode description icon_area n/a icon area has only one mode input_area stroke_mode stroke input mode continuous_mode pen position sampling mode confined_mode strokes confined within the area f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
4-6 pen input handling personal portable system manager programmers manual 114 if ( ctrliconenable(&abortrcv, button_x+20, button_y+30, ppsm_icon_16_done) 115 != ppsm_ok ) 116 return (ppsm_error); 4.10 removing a control active area status ctrlicondisable (u32 iconid ) remove the control icon from ppsm. this will remove the icon and the icon will no longer generate icon interrupt to the application. 4.11 push active area list into background status activelistpush (void) ppsm maintains a stack for storing active area lists. when this tool is called, all the active areas that have been created so far will be pushed into background, and a new list begins. a new list has no element by default. subsequent active area created will belong to the new active list. this tool allow applications to create a temporary active area list, and return to the original active areas when the temporary list is no longer required. example 4-7 push active area list into background /* push all existing active areas to background */ if (rv = activelistpush()) { /* error */ return (rv); } /* create new set of active areas */ generatenew(); /* call subroutine */ scratchpad(); /* restore original active areas */ if (rv = activelistpop()) { /* error */ return (rv); } 4.12 pop active area list to foreground status activelistpop (void) ppsm maintains a stack for storing active area lists. when this tool is called, the least recently pushed in active area list becomes the current active area list. this tool must be called after an activelistpush() call has been made previously. otherwise, an error will be returned. personal portable system manager programmers manual pen input handling 4-3 . . 104 /* create an active area for the nextwin icon with the coordinates 105 * as specified below. 106 */ 107 108 if (activeareaenable(&nextwinid, icon_area, 0, next_win_xsrc, 109 next_win_ysrc, next_win_xdest, next_win_ydest) 110 != ppsm_ok) 111 return ppsm_error; 112 4.3 removing an active area status activeareadisable (u32 areaid ) removes a valid active area from the application. the argument supplied into this tool must be a valid active area identifier that was generated by the activeareaenable tool. this shall be called within the task that creates the active area. once removed, the region of touch panel that was previously defined by the identifier will no longer respond to pen input. example 4-2 remove an active area 74 u32 backid; . . . 262 if ( activeareadisable(backid) != ppsm_ok ) 263 return (ppsm_error); 4.4 suspending an active area status activeareasuspend (u32 areaid , u32 flag) activate or deactivate a valid active area. once an active area has been created, it can be suspended from pen input response at anytime. to suspend, call this tool with the area_suspend flag. once suspended, the active area no longer sends out interrupt messages to the application when writing in the region. to re-enable the active area, simply call this tool with the area_reenable flag. example 4-3 suspend an active area if ((rv = activeareasuspend( iconid, area_suspend)) { /* error */ return (rv); } example 4-4 re-enable an active area if ((rv = activeareasuspend( iconid, area_reenable)) { /* error */ return (rv); } f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
4-4 pen input handling personal portable system manager programmers manual 4.5 active area enquiry status activearearead (u32 areaid , p_s16 xsrc , p_s16 ysrc , p_s16 xdest , p_s16 ydest) given a valid active area identifier, this tool will return to the caller the coordinates of the active area. example 4-5 enquire coordinates of the active area 85 u32 id, size; 86 p_u16 indata; 87 s16 xsrc, ysrc, xdest, ydest; . . . 180 activearearead(id, &xsrc, &ysrc, &xdest, &ydest); 4.6 put active area to front of list status activeareatofront (u32 areaid ) given the active area identifier, this tool will extract the element from the active area linked list and insert the element at the front of the list. once the element is at the front of the list, it will be the active area to receive pen input if there are other active areas that overlaps the same physical area. 4.7 pen echoing status areaechoenable (u32 areaid ) status areaechodisable (u32 areaid ) for input active areas, echoing can be disabled. by default, ink echoing is enabled when input active areas are created. the argument to both tools must be valid active area identifier generated from actvieareaenable tool. 4.8 pen color and pen size status penechoparam (u16 echocol, u16 echowidth ) ppsm allows the application developer to set the echoing pen width and echo pen color. this tool only sets the echoing property of the calling task, and will not affect other applications within the system. 4.9 creating a control active area status ctrliconenable (p_u32 iconid , s16 xsrc, s16 ysrc, u16 icontype ) a pre-defined group of direction control icons are available in ppsm for the personal portable system manager programmers manual pen input handling 4-5 purpose of scrolling. they are basically icon areas with specific bitmaps mapped to the icon area. two sets of icons are defined; 8x8 icons and 16x16 icons. an identifier is returned to the caller for the new control icon. example 4-6 create a control active area 80 u32 sendbutton, rcvbutton, abortsend, abortrcv; . . . 102 /* create control buttons with up/down arrow and done */ 103 if ( ctrliconenable(&sendbutton, button_x, button_y, ppsm_icon_16_up) 104 != ppsm_ok ) 105 return (ppsm_error); 106 107 if ( ctrliconenable(&abortsend, button_x+20, button_y, ppsm_icon_16_done) 108 != ppsm_ok ) 109 return (ppsm_error); 110 111 if ( ctrliconenable(&rcvbutton, button_x, button_y+30, ppsm_icon_16_down) 112 != ppsm_ok ) 113 return (ppsm_error); icon type description ppsm_icon_8_up 8 x 8 icon with up arrow bitmap ppsm_icon_8_down 8 x 8 icon with down arrow bitmap ppsm_icon_8_left 8 x 8 icon with left arrow bitmap ppsm_icon_8_right 8 x 8 icon with right arrow bitmap ppsm_icon_8_done 8 x 16 icon with rectangle bitmap ppsm_icon_16_up 16 x 16 icon with up arrow bitmap ppsm_icon_16_down 16 x 16 icon with down arrow bitmap ppsm_icon_16_left 16 x 16 icon with left arrow bitmap ppsm_icon_16_right 16 x 16 icon with right arrow bitmap ppsm_icon_16_done 16 x 32 icon with rectangle bitmap figure 4-1 control icon bitmaps f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
5-4 character input methods personal portable system manager programmers manual break; /* close keyboard icon selected */ case irpt_icon: if (id == closeiconid) closesoftkey(); break; /* no more interrupt */ default: break; } /* switch */ } /* while */ 5.2 handwriting recognition input pad the handwriting recognition input pad consists of a number of square boxes in a row by column format layout (refer to figure 5-3 ). it serves as an interface between the user and the underlying handwriting recognition engine. it captures the stroke data generated from the users handwriting input, and passes these data to the handwriting recognition engine for processing. (refer to figure 5-4 for the flow of input and output data passing through the input pad). figure 5-3 an example input pad with 1 row by 4 columns layout personal portable system manager programmers manual character input methods 5-1 chapter 5 character input methods ppsm supports two types of input methods for applications to receive character input from the user. there is a soft keyboard for typed english character and numeric input, and an input pad for handwritten character input. the input pad will support any coded language that the handwriting recognition engine supports. this chapter describes the mechanism of the input methods and the character input tools provided by ppsm to support them. 5.1 soft keyboard a default qwerty soft keyboard with key size of 15x15 pixels can be opened at any position within the panning screen. there are two soft keyboard layouts: one for upper case letters and numbers (refer to figure 5-1 ); the other for lower case letters and symbols (refer to figure 5-2 ). the user can toggle between the two layouts by pressing one of the shift buttons. as an alternative, an user may define its own keyboard with required number of column and row in number of keys, key width and height in number of pixels, user defined return keycode and the bitmap needed to be used for the soft keyboard. 1 2 3 4 5 6 7 8 9 0 q w e r t y u i o p a s d f g h j k l back shift z x c v b n m ret figure 5-1 upper case soft keyboard layout figure 5-2 lower case soft keyboard layout shift z x c v b n m ret a s d f g h j k l back q w e r t y u i o p ! @ # $ & ; : * , . f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
5-2 character input methods personal portable system manager programmers manual for both of the above keyboards, together with the keycode, the coordinate (s16, s16) of the pen on the key is also returned to users. only one soft keyboard can be opened within each task. 5.1.1 starting soft keyboard character input status opensoftkey (u16 xpos , u16 ypos ) opensoftkey() opens the soft, or pseudo, keyboard input module. a soft keyboard (as shown in figure 5-1 above) is drawn on the panning screen, with its upper-left corner position specified by the caller. when this function is called, ppsm saves the display area covered by the soft keyboard and monitors the input keys automatically. the soft keyboard is now ready for users input. when the user presses a key on the soft keyboard, the ascii code for that key will be returned to the calling application by way of irpt_key messages when the application calls irptgetdata(). (refer to section 29.1 - irptgetdata ). one irpt_key interrupt message is generated for each key pressed by the user. the ascii code returned is of type text, i.e. 2-byte format with zero extended in high byte. example 5-1 open soft keyboard for input 118 /* open soft keyboard for input */ 119 if ( opensoftkey(keybd_x, keybd_y) != ppsm_ok ) 120 return (ppsm_error); status advopensoftkey ( u16 xpos, u16 ypos, u16 keywidth, u16 keyheight, u16 numcol, u16 numrow, p_u16 keymap, p_u8 bitmap) advopensoftkey() opens the soft keyboard input module with advanced configurable details. ? location of the soft keyboard ? width and height of the keys in number of pixels ? number of rows and columns of keys ? the return code of each key (keycode) ? the bitmap user interface for the soft keyboard the return codes are defined in an array(keymap). the order of the keys in the array is from top left key across to the right, then next row and so on, until the bottom right key. the contents of this array should not be changed after advopensoftkey() has been called. the bitmap has to be either a null pointer or it must fit to cover the entire soft keyboard area. hence, the width and height of this soft keyboard must be (keywidth*numcol) and (keyheight*numrow) in number of pixels. for the null pointer case, it will not draw anything on the screen. example 5-2 open soft keyboard for input /* 7, 8, 9, 4, 5, 6, 1, 2, 3, *, 0, # */ static const u16 keymap[] = {55, 56, 57 ,52, 53, 54, 49, 50, 51, 42, 48, 35}; personal portable system manager programmers manual character input methods 5-3 /* open user specified soft keyboard for input like below */ /* with 10x10 key size and 3 col. x 4 rows. */ /* 7 8 9 */ /* 4 5 6 */ /* 1 2 3 */ /* * 0 # */ if ( advopensoftkey(keybd_x, keybd_y, 10, 10, 3, 4, (p_u16)keymap, bitmap) != ppsm_ok ) return (ppsm_error); 5.1.2 auto-key-repeat continually pressing a key would result in auto-key-repeat. the time between the first and second returned key is called auto_repeat_limit. it is currently set to be 20. the time duration between returned keys after the second one is called auto_repeat_rate. it is 5. they are actually the number of pen sampling tick. for example, a 32hz pen sampling would result in the second key after 20/32 sec, then, for every 5/32 sec each. 5.1.3 terminating soft keyboard character input status closesoftkey (void) closesoftkey() closes the soft keyboard which is opened by either opensoftkey() or advopensoftkey(). ppsm will restore the display area that was covered by the soft keyboard automatically. 5.1.4 suspend soft keyboard character input status activelistpop (void) status activelistpush (void) activelistpush() pushes the current active area list and the soft keyboard of the current task into background. activelistpop() pops the top background active list and soft keyboard of the current task from the active area stack. the active list that is currently being used is destroyed, replaced by the top background active list. for more details, please see section 4.1 - active area . example 5-3 display characters received from soft keyboard if (rv = opensoftkey(50, 50)) { /* error */ return (rv); } while (running) { switch(irptgetdata((p_u32)&id, (p_u32*)&indata, (p_u32)&size)) { /* any key pressed */ case irpt_key: /* user writing in soft keyboard */ displaykey((u16) (size >> 1), (p_u16)indata); /* (x, y) store the position of the key being pressed */ x=*(++indata); y=*(++indata); displayxy(x, y); f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
5-8 character input methods personal portable system manager programmers manual personal portable system manager programmers manual character input methods 5-5 5.2.1 the input pad mechanism the user writes a character within an input box to input it into the system. the system proceeds to recognize a character when the user starts writing in a different box, or when a predefined time has passed since the user lifts the pen, whichever occurs first. the characters are recognized in the order they are entered, independent of the box location. the application must define its own mechanism to determine when character input is finished and close the input pad (e.g. the user clicks on a close input pad button created by the application). the input pad is a subtask. once it is opened, handwriting recognition interrupt messages, irpt_hwr, are generated to its main task when characters are being recognized. each individual recognized character generates an individual irpt_hwr interrupt message. through this interrupt message, the system returns the recognized character candidates to the main task which opened the input pad. (refer to section 15.1.8 - irpt_hwr ). only one instance of the input pad is supported per main task(ie. shared among parent and sub-tasks). if the user opened an input pad in one of the tasks, an attempt to open the input pad in any other task in its parent/sub-tasks chain would fail. if the user switches to another task chain while an input pad has been opened in the current task. the handwriting recognition engine is reset and the input box area is cleaned if the areaclean(see below) flag has been set to be 1 (true). 5.2.2 starting handwriting character input status openinputpad (u16 xpos , u16 ypos , u16 numrow , u16 numcol , u16 areasize ) an application can open the input pad anywhere within the panning screen. the handwriting recognition engine users handwriting stroke data character candidates application ppsm input pad open/close character candidates and error code figure 5-4 data flow of handwriting recognition input f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
5-6 character input methods personal portable system manager programmers manual application needs to specify the xy-coordinate of the upper left corner of the input pad, the number of rows and columns of input boxes, and the size of each input box (in units of pixel). if the input pad is not already opened by another application and that the specified layout fits within the panning screen, it will be displayed at the specified location ready for users input. the area of the panning screen covered by the input pad is saved at the time this function is called. any changes to this covered area by the application after this function is called will not be recorded by the system. the default length of timeout for openinputpad() after the last stroke is 1sec. status advopeninputpad (u16 xpos, u16 ypos, u16 numrow, u16 numcol, u16 areawidth, u16 areaheight, u16 echocol, u16 echowidth, u32 timeout, u16 samplingrate, u8 areaclean, u16 stacksize) advopeninputpad is similar to the tool openinputpad but with advanced configurable details. it allows the caller to specify: ? position of the input pad ? number of rows and columns of input boxes ? the width and the height of the input boxes ? the echo ink colour and dot width ? the length of time out after a stroke(no more than 1sec) ? the sampling rate of the pen ? if the system should clean the input box for the user after each character is written ? the stack size for the input pad subtask 5.2.3 terminating handwriting character input status closeinputpad (void) closeinputpad() closes the input pad that has been opened either by openinputpad() or advopeninputpad(). after it is closed, no more handwriting recognition messages will be generated from the system to the application. the original image covered by the input pad is restored by the system if the areaclean flag has been set to be 1(true) before. example 5-4 display characters receive from input pad /* open an input pad at location (50, 50) that has 1 row of 4 boxes with the boxes being 64x64 pixels each */ if (rv = openinputpad(50, 50, 1, 4, 64)) { /* error */ return (rv); } while (running) { switch(irptgetdata((p_u32)&id, (p_u32*)&indata, (p_u32)&size)) { /* any icon pressed or handwritten character input */ personal portable system manager programmers manual character input methods 5-7 case irpt_hwr: /* code here to handle the irpt_hwr interrupt to receive the recognized character candidates from the system */ displaykey((u16) (size >> 1), (p_u8)indata); break; /* close keyboard icon selected */ case irpt_icon: if (id == closeiconid) closeinputpad(); break; /* no more interrupt */ break; } /* switch */ } /* while */ f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-4 using graphics tools personal portable system manager programmers manual 6.2.2 screen resolution lcd display screen resolution is the number of pixels that are available on the hardware. this is normally a fixed figure for each lcd hardware panel. the touch panel resolution must be equal to or greater than the lcd resolution or the pen cannot point at every pixel of the lcd display. 6.3 sample lcd display screen the following two figures show example systems used by the m68328ads hardware platform. the lcd display screen area has two sizes, 320 pixels wide by 240 pixels high and 320 pixels wide by 200 pixels high. the touch panel resolution is 1024x1024. figure 6-2 320x240 lcd panel with a larger touch panel 320 pixels 240 pixels pen input area graphics & text x pixels y pixels for panning screen display origin (0,0) input origin (0,0) (319, 239) display coordinate lcd display screen panning screen origin (0,0) 340 pixels input coordinate (1023,1023) personal portable system manager programmers manual using graphics tools 6-1 chapter 6 using graphics tools ppsm supports lcd modules with capabilities such as multiple grey levels, hardware cursor, hardware panning and software configurable display size. the graphics tools enable applications to: ? draw lines and shapes (e.g. dotted line, circle, etc.) ? display and manipulate bitmap images ? swap bitmap images ? control and restore bitmap images ? control hardware cursor ? set grey levels ? get information about the lcd display screen and panning screen. ? change the panning screen size ? direct all drawing effect to memory area apart from panning screen area ? hardware cursor in inverse and/or blinking mode ? allocate memory for panning screen ? set dot width in pixels for drawing dot, line, rectangle, circle, ellipse, arc and vector ? set pattern fill mode for drawing rectangle, circle, ellipse and arc ? draw vector by connecting consecutive points in a list this chapter will describe the display screen format, graphics routines and hardware cursor control provided by ppsm. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-2 using graphics tools personal portable system manager programmers manual 6.1 display screen format figure 6-1 shows the general screen architecture for the ppsm system. there are three major areas: ? pen input area ? lcd display screen ? panning display screen 6.1.1 lcd display screen the display screen is the region of the lcd display where applications can display output data. its size will depend on manufacturer, e.g. 320 pixels wide by 200 pixels high or 320 pixels wide by 240 pixels high, etc. the lcd module is capable of 1 bit per pixel or 2 bits per pixel output, giving 2 grey levels or 4 grey levels respectively. hence, there are white and black for 1 bit per pixel and white, light_grey, dark_grey and black for 2 bits per figure 6-1 generic screen format lcd display panel origin (0,0) negative coordinates positive coordinates touch panel personal portable system manager programmers manual using graphics tools 6-3 pixel. the reference coordinate point for the lcd display screen is at the top left corner, the display origin. this has the values of (0, 0) initially. coordinates associated with the lcd screen are referred to as the display coordinates. 6.1.2 panning display screen the panning screen is an extension to the lcd display screen. its main purpose is to allow applications to write data to an area outside of the actual display area. although applications can write to this area, data will not be displayed on the screen unless this area is being mapped to the lcd display screen. pen input areas on the panning screen will receive pen input data only when they overlap with the lcd display screen. panning screen has a similar coordinate system as the lcd display screen with different origin. it is configurable but limited by the following: ? the maximum memory size for a panning screen is limited to 64k byte. ? in 1 bit per pixel mode, the width of the panning screen must be divisible by 16 and limited to a maximum of 4096 pixels. in 2 bits per pixel mode, the width must be divisible by 8 and limited to a maximum of 2048 pixels. ? the height of the display is only limited by the amount of memory that is available for a given width. 6.2 screen initialization because every hardware system will not be identical, a screen initialization procedure is required when ppsm is first activated. this is essential for the calibration of the alignment between the pen input device and lcd display screen. screen initialization is implemented when ppsminit() is called. example 6-1 initialize screen through ppsminit() 57 main() 58 { . . . 62 /* initialize ppsm with pen calibration */ 63 ppsminit(true); 6.2.1 lcd display screen in relation to the touch panel the touch panel can be larger than the lcd display screen. however, the ppsm tools will only return lcd display screen coordinate. when a pen is touching outside the lcd display region, the display coordinate returned may be negative or even greater than the display screen size. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-8 using graphics tools personal portable system manager programmers manual putrec(), and clearrec(). the following tables show the grey level result of a pixel after a drawing operator is applied. x is the existing grey level on the screen. y is the grey level to be put on screen and r is the final grey level on screen after implementation. and_style or_style table 6-6 r = x and y xyr 00 00 00 01 00 00 10 00 00 11 00 00 00 01 00 01 01 01 10 01 00 11 01 01 00 10 00 01 10 00 10 10 10 11 10 10 00 11 00 01 11 01 10 11 10 11 11 11 table 6-7 r = x or y xyr 00 00 00 01 00 01 10 00 10 11 00 11 00 01 01 personal portable system manager programmers manual using graphics tools 6-5 6.4 1 bit-per-pixel graphics the graphics routines will handle drawing of black and white pixels on the panning screen. the byte and bit within byte ordering are both in big-endian format. for example: the above image will be represented by 1000101010001000 in binary and 0x8a88 in hexadecimal. figure 6-3 320x200 lcd panel with a same size touch panel 320 pixels 200 pixels pen input area graphics & text x pixels y pixel s for panning screen display origin (0,0) input origin (0,0) (319, 199) display coordinate lcd display screen panning screen origin (0,0) input coordinate (1023,1023) black (1) white (0) 1 0 0 0 1 0 1 0 1 0 0 0 1 0 0 0 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-6 using graphics tools personal portable system manager programmers manual 6.4.1 drawing operators ppsm supports drawing operators in drawdot(), drawhorz(), drawvert(), drawline(), drawcircle(), drawellipse(), drawarc(), drawvector(), drawrec(), putrec(), and clearrec(). the following tables show the grey level result of a pixel after a drawing operator is applied. x is the existing grey level on the screen. y is the grey level to be put on screen and r is the final grey level on screen after implementation. and_style or_style exor_style table 6-1 r = x and y xyr 000 100 010 111 table 6-2 r = x or y xyr 000 101 011 111 table 6-3 r = x exor y xyr 000 101 011 110 personal portable system manager programmers manual using graphics tools 6-7 replace_style invert_style 6.5 2 bits-per-pixel graphics the graphics routine will handle drawing of 4 grey levels: white, light grey, dark grey and black. the byte and bit within byte ordering are both in big-endian format. for example: the above image will be represented by 11010000100011001100010010000000 in binary and 0xd08cc480 in hexadecimal. 6.5.1 drawing operators ppsm supports drawing operators in drawdot(), drawhorz(), drawvert(), drawline(), drawcircle(), drawellipse(), drawarc(), drawvector(), drawrec(), table 6-4 r = y xyr 000 100 011 111 table 6-5 r = not x xr 01 10 black (11) dark grey (10) light grey (01) white (00) 11 01 00 00 10 00 11 00 11 00 01 00 10 00 00 00 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-12 using graphics tools personal portable system manager programmers manual 6.9 get panning screen width u16 getlogicalx (void) getlogicalx() returns to the caller the panning screen width, in terms of pixels, of the current application. the panning screen width is dynamically configurable at run time and it is recommended to use this tool to obtain the panning screen width for panning purposes. 6.10 get panning screen height u16 getlogicaly (void) getlogicaly() returns to the caller the panning screen height, in terms of pixels, of the current application. the panning screen height is dynamically configurable at run time and it is recommended to use this tool to obtain the panning screen height for panning purposes. 6.11 set pattern fill status setpatternfill (u16 mode , u16 backgrey , u16 bordermode , u16 fillspace ) this routine allows application programmers to decide on the fill pattern settings. these settings include the pattern mode, the spacing between the pattern lines, the background grey level, and the existence of a border. once setpatternfill() is called, the settings will be applied to all subsequent drawrec(), drawcircle(), drawellipse(), and drawarc(). the pattern will be drawn with the specified grey level in the parameter of drawrec(), drawcircle(), drawellipse(), and drawarc(). the argument fillspace lets application developers define the size of the gap between the pattern lines. the size of the gap equals to 2 fillspace number of pixels. there are 8 fill patterns available (mode 0 will turn off the pattern fill feature): 123 4 567 8 personal portable system manager programmers manual using graphics tools 6-9 exor_style 01 01 01 10 01 11 11 01 11 00 10 10 01 10 11 10 10 10 11 10 11 00 11 11 01 11 11 10 11 11 11 11 11 table 6-8 r = x exor y xyr 00 00 00 01 00 01 10 00 10 11 00 11 00 01 01 01 01 00 10 01 11 11 01 10 00 10 10 01 10 11 10 10 00 11 10 01 00 11 11 01 11 10 10 11 01 11 11 00 table 6-7 r = x or y xyr f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-10 using graphics tools personal portable system manager programmers manual replace_style invert_style 6.6 graphics tools the following sections explain each graphics tool with examples. top left corner of the panning screen is (0, 0) which is the panning screen origin. top left corner of the lcd display screen is an offset from the panning screen table 6-9 r = y xyr 00 00 00 01 00 00 10 00 00 11 00 00 00 01 01 01 01 01 10 01 01 11 01 01 00 10 10 01 10 10 10 10 10 11 10 10 00 11 11 01 11 11 10 11 11 11 11 11 table 6-10 r = not x xr 00 11 01 10 10 01 11 00 personal portable system manager programmers manual using graphics tools 6-11 origin. all co-ordinates given to the graphics routines are referred to the panning screen origin. there is no negative co-ordinate for panning screen. some of the graphics routines need to draw dotted line where one of the argument in calling the routine specifying the length of the dot, e.g. 5 means drawing 5 dots with specifying grey level and then skipping 5 dots and so on. those graphics routines providing dotted line function are drawhorz(), drawvert(), drawline() and drawrec(). drawdot(), drawhorz(), drawvert(), drawline(), drawrec(), drawcircle(), drawellipse(), drawarc(), clearrec() and putrec() provides function of style which is described above as or_style, exor_style, and_style, etc. for all the following examples in this chapter, the panning screen size is 640x480, lcd display screen size is 320x240 and the lcd display origin is at an offset of (50, 50) from panning screen origin. 6.7 get lcd display screen width u16 getdisplayx (void) getdisplayx() returns to the caller the physical width, in terms of pixels, of the lcd display panel being used. when writing an application, this routine should be used instead of using specific numbers for the width of the lcd display screen as it will make the code more flexible to run on different lcd panels. 6.8 get lcd display screen height u16 getdisplayy (void) getdisplayy() returns to the caller the physical height, in terms of pixels, of the lcd display panel being used. when writing an application, this routine should be used instead of using specific numbers for the height of the lcd display as it will make the code more flexible to run on different lcd panels. example 6-2 get lcd display screen width and height 362 status drawtexticon(p_u32 areaid, u16 xsrc, u16 ysrc, u16 width, u16 height, 363 u16 font, p_text message) 364 { 365 366 u16 xdest, ydest; . . . 375 /* check to see if the coordinates are fall within the lcd screen */ 376 if ( (xsrc < 0) || (xdest >= getdisplayx()) || (ysrc < 0) || 377 (ydest >= getdisplayy()) ) 378 return ppsm_error; f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-16 using graphics tools personal portable system manager programmers manual equals to false to copy all properties of the common panning screen to the tasks own context example 6-5 use changepanning() to let all tasks share the same panning screen #include #include #include pan_screen newscreen; status testapp() { /* use the common panning screen in this task */ changepanning(&newscreen, false, 0); /* draw a circle with center at (100, 100) and radius 80 pixels */ drawcircle(black, 100, 100, 80, replace_style); } main() { u32 taskid; p_u8 newpanning; ppsminit(false); /* create a common panning screen with size 640x400 */ newpanning = (p_u8)getscreenmem(640, 400); newscreen.panaddress = (u32)newpanning; newscreen.displayscreenaddr = (u32)newpanning; newscreen.horzsize = 640; newscreen.vertsize = 400; newscreen.displayxorigin = 0; newscreen.displayyorigin = 0; newscreen.regposr = 0; newscreen.regpsw = 80;/* as the lcd panel used is 2 bits per pixel, psw = 640/8 = 80. */ /* destroy the system panning screen and use the new panning screen created above */ changepanning(&newscreen, false, 0); /* clear whole panning screen */ clearscreen(white); /* draw a circle with center at (100, 100) and radius 20 pixels to the new panning screen */ drawcircle(black, 100, 100, 20, replace_style); /* create a new task with no panning screen */ advtaskcreate(&taskid, (p_void)testapp, 0, 0, 0, 0, 3048, ppsm_noscreen, 0, 0, 0); taskstart(taskid); } in the example above, both the system task in main() and task testapp() share the same panning screen. so whatever done on the panning screen by the system task or task testapp() will have effect on the panning screen. if a panning screen is shared among tasks. calls changepanning() to free the screen in one of the task can also free/corrupt the others screen memory area. personal portable system manager programmers manual using graphics tools 6-13 the pattern fill mode 0 will turn off the pattern fill feature. 6.12 set dot width status setdotwidth (u16 newwidth , p_u16 oldwidth ) after this routine is called, the new dot width will take effect in all subsequent drawdot(), drawhorz(), drawvert(), drawrec(), drawline(), drawcircle(), drawellipse(), drawarc(), and drawvector(). if the dot width is larger than 1, a thick dot, thick line, thick circle, thick ellipse, thick arc and thick vector lines can be drawn. example 6-3 set dot width 160 * drawing1 - draw a line and then an ellipse with pattern filled on screen1. 161 * both have a dot width = 6, but no border on the ellipse is 162 * drawn as the bordermode in setpatternfill is set to 0. . . . 170 setdotwidth(6, 0); 171 setpatternfill(2, white, 0, 3); 6.13 displaymove status displaymove (u16 xpos , u16 ypos ) this function is to set the relative coordinate of top left corner of lcd in panning screen. it sets the display region on lcd from panning screen. whenever this function is called, the new area in panning screen will be refreshed on lcd. 6.14 direct all graphics output to off-screen memory status changewindow (u32 addr , u16 width , u16 height , p_u32 oldaddr , p_u16 oldwidth , p_u16 oldheight ) run-time computation intensive image generation and display could be slow. users may see the graphics output appears slowly on the lcd display screen. changewindow() allows applications to direct all output from ppsm graphics routines to an off-screen memory area temporarily, so that no changes will appear on the lcd display screen while the image is being built. once the image is generated, it can be displayed onto the panning screen. this will give the effect that the image is displayed instantaneously. changewindow() assumes that all input parameters are valid. no zero or invalid values are supposed to be passed as input to this routine. example 6-4 use changewindow() to draw image u32 oldscreen1, oldscreen2; u16 oldwidth1, oldheight1; f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-14 using graphics tools personal portable system manager programmers manual u16 oldwidth2, oldheight2; u32 tempscreen = (u32)getscreenmem(64, 64); /* direct all graphic routine to memory area pointed by tempscreen with width 64 pixels and height 64 pixels */ changewindow(tempscreen, 64, 64, &oldscreen1, &oldwidth1, &oldheight1); /* this may be any routine for calculating the co-ordinates to be drawn or drawing anything by calling graphics routines */ docalculation(); /* direct all graphic routine back to original panning screen */ changewindow(oldscreen1, oldwidth1, oldheight1, &oldscreen2, &oldwidth2, &oldheight2); 6.15 change panning screen parameters status changepanning (p_pan_screen newpanning , u16 flag , p_pan_screen oldpanning ) changepanning() allows applications to change the active panning screen to another memory area during run-time. the flag is to indicate whether the old panning screen is still needed or it will be destroyed. p_pan_screen is a pointer to structure pan_screen which has the following elements: table 12-11 panning screen parameters name description panaddress the memory address where panning screen origin is located. all graphics routines will draw in the area relative to this address. horzsize the panning screen width in number of pixels. vertsize the panning screen height in number of pixels. displayxorigin the x-coordinate of the lcd display screen relative to the panning screen. in normal case, when changewindow() is not called, displayxorigin and displayyorigin are used to calculate the value of displayscreenadd r and regposr . displayyorigin the y-coordinate of the lcd display screen relative to the panning screen. in normal case, when changewindow() is not called, displayxorigin and displayyorigin are used to calculate the value of displayscreenadd r and regposr . personal portable system manager programmers manual using graphics tools 6-15 upon start-up, panaddress equals displayscreenaddr , regposr is 0, displayxorigin and displayyorigin are 0 and regpsw equals horzsize /8 for a 2 bits per pixel display or horzsize /16 for a 1 bit per pixel display. when displaymove() is called, both displayscreenaddr and regposr will be modified so that the system will know from which word and from which pixel position within the word the lcd display screen should start mapping. when changewindow() is called, panaddress , horzsize and vertsize will be changed so that all graphics routines will use these 3 parameters for calculation and image processing. if all or several tasks in a system want to share a common panning screen to save memory, the following steps can be followed: 1) in main() ? call getscreenmem() to create a memory area for the common panning screen ? call changepanning() to free the ppsm system panning screen ? for each task that shares the common panning screen, call advtaskcreate() with parameter ppsm_noscreen to create the task with no panning screen 2) for each corresponding task that shares the common panning screen ? during initialization, call changepanning() with flag parameter displayscreenaddr the memory address where the lcd display screen origin is located. in normal case, when changewindow() is not called, this is calculated from panaddress , displayxorigin and displayyorigin . this is where the system will retrieve the first word to display on lcd display screen. this is used in the screen starting address register (ssa) described in 4.7.1.1 of mc68328/ mc68ez328 integrated processor users manual. regposr this is the pixel offset within the word pointed to by displayscreenaddr where the first pixel on lcd display screen will be retrieved. this is used in the panning offset register (posr) in 4.7.5.5 of mc68328/mc68ez328 integrated processor users manual. regpsw this is the panning screen width in number of words. this is used in the virtual page width register (vpw) in 4.7.1.2 of mc68328/mc68ez328 integrated processor users manual. table 12-11 panning screen parameters name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-20 using graphics tools personal portable system manager programmers manual example 6-12 draw a thick horizontal line status ret; /* set dot width to 4 */ ret = setdotwidth(4, 0); if (ret !=ppsm_ok) return ret; /* draw a black horizontal line from (60, 60) with width 2 */ ret = drawhorz(black, 60, 60, 2, 0, replace_style); if (ret != ppsm_ok) return ret; in the above example, a thick horizontal line will be drawn as follow: 6.19 draw a vertical line status drawvert (u16 greylevel , u16 xsrc , u16 ysrc , u16 height , u16 dotline , u16 style ) this routine will draw a vertical line from (xsrc, ysrc) to (xsrc, ysrc + height - 1). figure 6-9 screen output for example 6-11 lcd panning screen (50, 50) (0, 0) (50, 60) (580, 60) (369, 60) figure 6-10 screen output for example 6-12 (61, 60) (60, 60) personal portable system manager programmers manual using graphics tools 6-17 6.16 fill the whole panning screen status clearscreen (u16 greylevel ) this routine will fill the whole panning screen with the specified grey level. example 6-6 fill the whole screen with white status ret; /* fill the whole panning screen with white */ ret = clearscreen(white); 6.17 draw a dot status drawdot (u16 greylevel , u16 xpos , u16 ypos , u16 style ) this routine will draw a dot at the specified position ( xpos , ypos ). if dot width is 1, a pixel will be drawn. if dot width is 2, a square dot of length 2 will be drawn with top left pixel position as the dot co-ordinate, ( xpos , ypos ). when the dot width is greater than 2, a circular disc with radius to be truncated integer value of (dot width - 1)/2 will be drawn. the center of the disc will be the dot co- ordinate, ( xpos , ypos ). example 6-7 draw a black dot status ret; /* draw a dot at (52, 52) */ ret = drawdot(black, 52, 52, replace_style); the calling of drawdot(black, 52, 52) will draw a black pixel at (52, 52) in panning screen. as the lcd display screen origin is at (50, 50), the point drawn on screen is at (2, 2) in display co-ordinate. hence, the expected outcome will have a dot which is very close to the display origin. example 6-8 draw a dot with dot width 2 status ret; figure 6-4 screen output for example 6-6 lcd panning screen f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-18 using graphics tools personal portable system manager programmers manual /* set dot width to 2 */ setdotwidth(2, 0); /* draw a dot at (52, 52) */ ret = drawdot(black, 52, 52, replace_style); when the dot width equals 2, a square dot with length of 2 will be drawn. example 6-9 draw a dot with dot width 3 status ret; /* set dot width to 3 */ setdotwidth(3, 0); /* draw a dot at (52, 52 */ ret = drawdot(black, 52, 52, replace_style); when the dot width is 3, a circular disc with radius of (3-1)/2 (which is 1) will be drawn. example 6-10 draw a dot with dot width 4 status ret; figure 6-5 screen output for example 6-7 lcd panning screen (52, 52) (50, 50) (0, 0) figure 6-6 screen output for example 6-8 (52, 52) figure 6-7 screen output for example 6-9 (52, 52) personal portable system manager programmers manual using graphics tools 6-19 /* set dot width to 4 */ setdotwidth(4, 0); /* draw a dot at (52, 52) */ ret = drawdot(black, 52, 52, replace_style); when the dot width is 4, a circular disc with radius of (4-1)/2 (which is 1) will be drawn. 6.18 draw a horizontal line status drawhorz (u16 greylevel , u16 xsrc , u16 ysrc , u16 width , u16 dotline , u16 style ) this routine will draw a horizontal line from (xsrc, ysrc) to (xsrc + width - 1, ysrc). if the dot width is greater than 1, the specified horizontal line will have integer truncated of (dot width - 1)/2 horizontal lines above it, and (dot width)/2 horizontal lines below it. the length of each of these lines will be extended by (dotwidth - 1)/ 2 pixels to the left of the source, and by (dotwidth/2) pixels to the right of the end point. if the width of the horizontal line is 1, a square dot will be drawn. example 6-11 draw a horizontal black line status ret; /* draw a black horizontal line from (30, 60) with width 551 */ ret = drawhorz(black, 30, 60, 551, 0, replace_style); in this example, the dot width is 1. the calling of drawhorz(black, 30, 60, 551, 0, replace_style) will draw a black horizontal line from (30, 60) to (580, 60) on panning screen. only the portion of (50, 60) to (369, 60) will be seen on lcd display. figure 6-8 screen output for example 6-10 (52, 52) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-24 using graphics tools personal portable system manager programmers manual example 6-17 draw a rectangle with black outline status ret; /* draw a black rectangle with top left corner at (310, 250) and bottom right corner at (500, 400) */ ret = drawrec(black, 310, 250, 500, 400, 0, replace_style); in this example, the dot width is 1. the calling of drawrec(black, 310, 250, 500, 400, 0, replace_style) will draw a rectangle with top left corner at (310, 250) and bottom right corner at (500, 400) on panning screen. however, only a horizontal line from (310, 250) to (369, 250) and a vertical line from (310, 250) to (310, 289) will be seen on the lcd display screen. example 6-18 draw a rectangle with black outline in dot width 3 and fill pattern mode 1 status ret; /* set dot width to 3 */ ret = setdotwidth(3, 0); if (ret !=ppsm_ok) return ret; /* set pattern fill mode to 1 which is solid fill */ ret = setpatternfill(1, white, true, 1); if (ret !=ppsm_ok) return ret; /* fill a rectangle from top left corner at (310, 250) to (500, 400) */ ret = drawrec(black, 310, 250, 500, 400, 0, replace_style); figure 6-15 screen output for example 6-17 lcd panning screen (50, 50) (0, 0) (310, 250) (500, 400) (369, 250) (310, 288) personal portable system manager programmers manual using graphics tools 6-21 if the dot width is greater than 1, the specified vertical line will have integer truncated of (dot width - 1)/2 vertical lines to its left, and (dot width)/2 vertical lines at right. the height of each of these lines will be extended by (dotwidth - 1)/2 pixels above the source and by (dot width)/2 below the end point. if the height of the vertical line is 1, a square dot will be drawn. example 6-13 draw a vertical black line status ret; /* draw a black vertical line from (60, 60) with height 361 */ ret = drawvert(black, 60, 60, 361, 2, replace_style); in this example, the dot width is 1. the calling of drawvert(black, 60, 60, 361, 0, replace_style) will draw a black line from (60, 60) to (60, 420) on panning screen. however, only the portion of the line on lcd display screen will be seen which is (60, 60) to (60, 289). since the parameter for dotted line is 2, the line is drawn in the form of 2 black pixels and then 2 white pixels and then 2 black pixels, and so on. example 6-14 draw a thick vertical line status ret; /* set dot width to 4 */ ret = setdotwidth(4, 0); if (ret !=ppsm_ok) return ret; /* draw a black thick horizontal line from (10, 10) with height 2 */ ret = drawvert(black, 10, 10, 2, 0, replace_style); if (ret != ppsm_ok) return ret; figure 6-11 screen output for example 6-13 lcd panning screen (50, 50) (0, 0) (60, 60) (60, 420) (60, 289) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-22 using graphics tools personal portable system manager programmers manual in the above example, a thick vertical line will be drawn as follow: 6.20 draw a line status drawline (u16 greylevel , u16 xsrc , u16 ysrc , u16 xdest , u16 ydest , u16 dotline , u16 style ) this routine will draw a line from (xsrc, ysrc) to (xdest, ydest). if dot width is greater than 1, each dot on the specified line will be represented by a thick square dot. each of the thick square dot is generated by extending integer truncated (dot width - 1)/2 pixels above, (dot width)/2 below, (dot width - 1)/2 pixels to the left and (dot width)/2 pixels to the right of the original dot. the thick line is then generated by overlapping these thick dots accordingly. example 6-15 draw a black line status ret; /* draw a black line from (60, 240) to (630, 470) */ ret = drawline(black, 60, 240, 630, 470, 0, replace_style); figure 6-12 screen output for example 6-14 (10, 11) (10, 10) figure 6-13 screen output for example 6-15 lcd panning screen (50, 50) (0, 0) (60, 240) (630, 470) personal portable system manager programmers manual using graphics tools 6-23 in this example, the dot width is 1. the calling of drawline(black, 60, 240, 630, 470, 0, replace_style) will draw a black line from (60, 240) to (630, 470) on panning screen. however, only the portion of the line on lcd display screen will be seen. example 6-16 draw a thick line status ret; /* set dot width to 4 */ ret = setdotwidth(4, 0); if (ret !=ppsm_ok) return ret; /* draw a black thick line from (10, 10) to (11, 11) */ ret = drawline(black, 10, 10, 11, 11, 0, replace_style); if (ret != ppsm_ok) return ret; in the above example, a thick horizontal line will be drawn as follow: 6.21 draw a rectangle status drawrec (u16 greylevel , u16 xsrc , u16 ysrc , u16 xdest , u16 ydest , u16 dotline , u16 style ) this routine draws a rectangle with top left corner at (xsrc, ysrc) and bottom corner at (xdest, ydest). if the dot width is greater than 1, integer truncated (dot width - 1)/2 lines are drawn inside the rectangle and (dot width)/2 lines drawn outside the rectangle. if both fill pattern mode and border mode are set, those area inside the rectangle which is not covered by the border will be filled. if fill pattern mode is set and border mode is off, the area inside and on the rectangle border will be filled. figure 6-14 screen output for example 6-16 (10, 10) (11, 11) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-28 using graphics tools personal portable system manager programmers manual if the dot width is greater than 1, integer truncated (dot width - 1)/2 lines are drawn inside the arc and (dot width)/2 lines drawn outside the arc. if both fill pattern mode and border mode are set, those area inside arc which is not covered by the border of the arc will be filled. if fill pattern is set and border is off, those area inside and on the arc border will be filled. (x1 < x2) and (y1 < y2) (x1 < x2) and (y1 > y2) (x1 > x2) and (y1 < y2) (x1 > x2) and (y1 > y2) figure 6-19 cases of drawarc (x1, y1) (x2, y2) (x1, y1) (x2, y2) (x2, y2) (x1, y1) (x1, y1) (x2, y2) personal portable system manager programmers manual using graphics tools 6-25 in this example, the dot width is 3 and fill pattern mode is 1. the calling of drawrec(black, 310, 250, 500, 400, 0, replace_style) will fill a rectangle with top left corner at (309, 249) and bottom right corner at (501, 401) on panning screen. however, only a smaller rectangular area from (309, 249) to (369, 289) will be seen on the lcd display screen. 6.22 draw a circle status drawcircle (u16 greylevel , u16 xcenter , u16 ycenter , u16 radius , u16 style ) this routine will draw a circle centering at (xcenter, ycenter) with the specified radius and grey level. if the dot width is greater than 1, integer truncated (dot width - 1)/2 lines are drawn inside the circle and (dot width)/2 lines drawn outside the circle. if both fill pattern mode and border mode are set, those area inside the circle which is not covered by border will be filled. if fill pattern mode is set and border mode is off, the area inside and on the circle border will be filled. example 6-19 draw a circle with black outline status ret; /* draw a black outlined circle with center at (560, 290) and radius 150 */ ret = drawcircle(black, 560, 290, 150, replace_style); figure 6-16 screen output for example 6-17 lcd panning screen (50, 50) (0, 0) (310, 250) (500, 400) (369, 250) (310, 288) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-26 using graphics tools personal portable system manager programmers manual in this example, the dot width is 1. the calling of drawcircle(black, 560, 290, 150, replace_style) will draw a circle centering at (560, 290) with radius 150. as the circle is drawn outside the lcd display screen, nothing will be seen on the lcd. 6.23 draw an ellipse status drawellipse (u16 greylevel , u16 xcenter , u16 ycenter , u16 xlength , u16 ylength , u16 style ) this routine will draw a ellipse centering at (xcenter, ycenter) with the specified size. if the dot width is greater than 1, integer truncated (dot width - 1)/2 lines are drawn inside the ellipse and (dot width)/2 lines drawn outside the ellipse. if both fill pattern mode and border mode are set, those area inside ellipse which is not covered by the border will be filled. if fill pattern mode is set and border mode is off, the area inside and on the ellipse border will be filled. example 6-20 draw an ellipse with black outline status ret; /* draw an ellipse with center at (560, 290), horizontal length 150 and vertical length 100 */ ret = drawellipse(black, 560, 290, 150, 100, replace_style); figure 6-17 screen output for example 6-19 lcd panning screen (50, 50) (0, 0) (560, 290) 150 personal portable system manager programmers manual using graphics tools 6-27 in this example, the dot width is 1. the calling of drawellipse(black, 560, 290, 150, 100, replace_style) will draw an ellipse centering at (560, 290) with the longest distance on y axis from center to border is 100 pixels and the longest distance on x axis from center to border is 150 pixels. 6.24 draw an arc status drawarc (u16 greylevel , u16 x1 , u16 y1 , u16 x2 , u16 y2 , u16 style ) this routine will draw an arc connecting (x1, y1) and (x2, y2). drawarc() will draw a quarter of an ellipse centering at (x2, y1). if drawarc(black, x1, y1, x2, y2, replace_style) is called, the following arcs will be drawn according to the values of (x1, y1) and (x2, y2): figure 6-18 screen output for example 6-20 lcd panning screen (50,50) (0,0) (560,290) 100 150 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-32 using graphics tools personal portable system manager programmers manual the following will be seen on lcd display screen: example 6-26 when lcd display screen crosses the bottom bound- ary of the panning screen the following will be seen: the pattern of the noise part of the display depends on the content of the memory that follows the panning screen. if the memory following the panning screen is all 0, the noise will appear as a blank image. if the memory following the panning figure 6-25 screen output for example 6-25 lcd display screen figure 6-26 screen output for example 6-26 lcd panning screen (0, 0) figure 6-27 screen output for example 6-26 lcd display screen noise personal portable system manager programmers manual using graphics tools 6-29 example 6-21 draw a black arc with or style status ret; /* draw an arc from (240, 150) to (100, 100) */ ret = drawarc(black, 240, 150, 100, 100, or_style); in this example, the dot width is 1. the calling of drawarc(black, 100, 100, 50, 50, or_style) will draw an arc from (100, 100) to (240, 150) on panning screen. the arc is actually a quarter of an ellipse centering at (100, 150) with the longest distance of 141 pixels in x axis and the longest distance of 51 pixels in y axis. the center is determined by the x axis value of the second point and the y axis value of the first point which is 100 and 150 respectively. example 6-22 draw a black arc with exor style /* draw an arc from (100, 100) to (240, 150) */ ret = drawarc(black, 100, 100, 240, 150, exor_style); in this example, the dot width is 1. as the lcd display screen is all black and the calling of drawarc() is in exclusive or style, the arc turns out to be white on a black background. figure 6-20 screen output for example 6-21 lcd panning screen (50, 50) (0, 0) (100, 100) (240, 150) figure 6-21 screen output for example 6-22 lcd panning screen (50, 50) (0, 0) (100, 100) (240, 150) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-30 using graphics tools personal portable system manager programmers manual 6.25 draw a vector from a list of points status drawvector (u16 greylevel , u16 numberofpoints , p_point pointptr , u16 style , u16 mode ) this routine will draw lines to connect the points in the given list. it has options on whether the first point and last point need to be connected. 6.26 put a rectangular area on panning screen status putrec (p_u8 bitmap , u16 xsrc , u16 ysrc , u16 width , u16 height , u16 style , u16 reserved ) this routine puts an image from memory to panning screen. putrec() supports style such as replace_style, or_style, exor_style and and_style. there is error checking done on the argument style , but not on the value of bitmap. example 6-23 put a bitmap on screen with replace_style /* put an image on panning screen with top left corner at (0, 0), width 640 and height 480 */ ret = putrec(bitmap, 0, 0, 640, 480, replace_style, 0); the calling of putrec(bitmap, 0, 0, 640, 480, replace_style, 0) copies the image from the memory area pointed to by bitmap onto the panning screen. figure 6-22 screen output for example 6-23 lcd panning screen (50, 50) (0, 0) personal portable system manager programmers manual using graphics tools 6-31 6.26.1 special cases of putrec() the following are the few special cases of putrec(). example 6-24 display one bit per pixel image on 2 bits per pixel lcd setting two similar images will be seen horizontally. example 6-25 lcd display screen crosses the right boundary of the panning screen figure 6-23 screen output for example 6-24 lcd display screen (0, 0) figure 6-24 screen output for example 6-25 lcd panning screen (0, 0) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-36 using graphics tools personal portable system manager programmers manual /* set hardware cursor width to 15 and height to 15 pixels */ cursorinit(15, 15); /* turn on the hardware cursor in full density mode */ cursorsetstatus(ppsm_cursor_on); the above will create a cursor at (150, 158) with 15 pixels wide by 15 pixels high, and will turn the cursor on. 6.31.2 set hardware cursor position status cursorsetpos (u16 xpos , u16 ypos ) this routine will set the hardware cursor top left corner position at (xpos, ypos). example 6-32 when the hardware cursor needs to be changed to other position: /* set hardware cursor position to (15, 150) */ cursorsetpos(15, 150); this will change cursor to new position at (15, 150) 6.31.3 set hardware cursor status status cursorsetstatus (u16 status ) this routine will change the hardware cursor status to one of the following states: ppsm_cursor_off, ppsm_cursor_on or ppsm_cursor_reversed. example 6-33 when hardware cursor is turned off after creation and it needs to be on with reverse video mode: u16 x, y; /* turn on hardware cursor in reverse video mode */ cursorsetstatus(ppsm_cursor_reversed); 6.31.4 get hardware cursor status status cursorgetstatus (p_u16 status ) this routine will return the current hardware cursor status. the status will be one of the following states: ppsm_cursor_off, ppsm_cursor_on or table 6-12 status name descriptions ppsm_cursor_off temporarily turn cursor off ppsm_cursor_on turn cursor on ppsm_cursor_reversed reverse cursor personal portable system manager programmers manual using graphics tools 6-33 memory is invalid, a bus address error will be generated. 6.27 save a rectangular area from panning screen status saverec (p_u8 bitmap , u16 xsrc , u16 ysrc , u16 width , u16 height , u16 reserved ) this routine saves an image from the panning screen to memory. example 6-27 save a bitmap /* save the portion of image on panning screen from top left corner at (50, 50), width 320 and height 120 */ ret = saverec(bitmap, 50, 50, 320, 120, 0); the calling of saverec(bitmap, 50, 50, 320, 120, 0) will save the top half of lcd display image into memory area pointed to by bitmap . 6.28 exchange a rectangular area with memory status exchangerec (u16 xsrc , u16 ysrc , u16 width , u16 height , p_u8 reserved ) this routine exchanges images between the panning screen and memory. example 6-28 save a bitmap /* exchange the image on panning screen with top left corner at (50, 50), width 320 and height 120 to the image in memory pointed by bitmap */ ret = exchangerec(bitmap, 50, 50, 320, 120); this example swaps the image pointed to by bitmap with the image in the rectangular region from top left corner at (50, 50) to bottom right corner at (369, 169). after this call, bitmap now points to the original image of the rectangular region (50, 50) to (369, 169), while the image pointed to by bitmap is now displayed on the rectangular region (50, 50) to (369, 169) on the panning screen. figure 6-28 screen output for example 6-27 panning screen (50, 50) (0, 0) lcd f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-34 using graphics tools personal portable system manager programmers manual 6.29 fill a rectangular area status clearrec (u16 greylevel , u16 xsrc , u16 ysrc , u16 width , u16 height , u16 style ) this routine fills an rectangular area with the specified grey level. example 6-29 fill a rectangular region with black and or style status ret; /* fill a rectangular area with top left corner at (300, 240), width 261 and height 161 */ ret = clearrec(black, 300, 240, 261, 161, or_style); this example fills the rectangular region from top left corner at (300, 240) on panning screen with width 261 pixels and height 161 pixels. 6.30 inverse a rectangular area status invrec (u16 xsrc , u16 ysrc , u16 width , u16 height ) this routine will inverse the grey level of the rectangular area with top left corner at (xsrc, ysrc) and bottom right corner at (xsrc + width - 1, ysrc + height - 1). example 6-30 inverse a rectangular region status ret; /* inverse a rectangular area with top left corner at (250, 200), width 200 and height 100 */ ret = invrec(250, 200, 200, 100); figure 6-29 screen output for example 6-29 lcd panning screen (50, 50) (0, 0) (560, 400) (300, 240) personal portable system manager programmers manual using graphics tools 6-35 in this example, the lcd display screen is black and the rest of the panning screen is white. after inverting the rectangular region with top left corner at (250, 200) and 200 pixels wide by 100 pixels high, a white box can be seen in the lcd screen at bottom right position. 6.31 hardware cursor when there is no hardware cursor in current task, the creation of hardware cursor requires to set the cursor characteristic and follows by calling cursorsetstatus(ppsm_cursor_on). when hardware cursor is created and it needs to be turned off, the application should call cursoroff(). if the application needs to turn on the cursor once again. it has to set the cursor characteristic and follows by calling cursorsetstatus(ppsm_cursor_on) again. when hardware cursor is to be suspended, the application should call cursorsetstatus(ppsm_cursor_off). a application can change the hardware cursor to new position. it can inquire the hardware cursor status from the system. when the hardware cursor is on, the calling of functions to change the size or position of the hardware cursor will have immediate effect. 6.31.1 set hardware cursor size status cursorinit (u16 cursorwidth , u16 cursorheight ) this routine will change the hardware cursor width and height. the valid range for both width and height is from 1 through 31. example 6-31 when there is no hardware cursor in current task: /* set hardware cursor position at (150, 150) */ cursorsetpos(150, 158); figure 6-30 screen output for example 6-30 lcd panning screen (50, 50) (0, 0) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
7-2 database management personal portable system manager programmers manual 7.1.2 unformatted data unformatted data is data that has to be accessed as one complete block. there is only one unformatted data field allowed per record. the unformatted data can be one of the following eight types defined as follows: ? type 0 text (ascii code record) ? type 1 decompressed ppsm lcd bitmap ? type 2 compressed ppsm lcd bitmap ? type 3 mixed text and graphics ? type 4 reserved ? type 5 text followed by decompressed ppsm lcd bitmap ? type 6 text followed by compressed ppsm lcd bitmap ? type 7 text followed by mixed text and graphics ppsm will keep track of the size of the unformatted data field of a record in the record information field. 7.2 the database manipulation tools ppsm provides a set of tools to operate on databases and records. conceptually, they can be grouped together in the following way: 1) operate at the database level: ? add or delete a database. ? inquire the total number of database present in the current environment. ? set or clear the database secret flag. ? interrogate the database secret flag. 2) operate at the individual record level: ? add or delete a record. ? add a blank record to the top of the record list. ? append a blank record after a specified record in the record list. ? write or read formatted data of a record. ? write or read unformatted data of a record. ? get the id of the first record in the list. ? get the id of the previous or next record in the list. ? search for a record using a formatted data field as a key. ? set or clear the record secret flag. ? interrogate the record secret flag. ? inquire the total number of record present in a particular db_company company 60 1,2,3,4,5 5 additional fields 60 table 7-1 predefined field format used in the pda environment field index field name max. field size personal portable system manager programmers manual using graphics tools 6-37 ppsm_cursor_reversed. example 6-34 when the hardware cursor status is needed: u16 status; /* get the hardware cursor status */ cursorgetstatus(&status); 6.31.5 set hardware cursor blinking frequency status cursorsetblink (u16 frequency ) this routine will set the hardware cursor blinking frequency to frequency number of blinks per 10 seconds. 6.31.6 turn hardware cursor off status cursoroff (void) this routine will turn off the hardware cursor permanently. in order to turn on the hardware cursor again, the application has to set the characteristics of the cursor and follows by calling cursorsetstatus(ppsm_cursor_on). 6.32 display other region of panning screen status cursorsetorigin (u16 xpos , u16 ypos ) status lcdscreenmove (u16 x , u16 y ) these two routines together will move the lcd display origin to (x, y) so that different regions of the panning screen can be displayed instantaneously. these two routines must be used together. in ppsm v3.11, these 2 routines are replaced by displaymove(). example 6-35 display other region of panning screen u16 x=50, y=50; /* set the lcd display screen origin to be (50, 50) on panning screen */ cursorsetorigin(x, y); /* change the hardware register to display the rectangular on panning screen with top left corner at (50, 50) */ lcdscreenmove(x, y); the lcd display screen will now display the rectangular region of the panning screen with top left corner at (50, 50). 6.33 get lcd display origin on panning screen status cursorgetorigin (p_u16 xpos , p_u16 ypos ) this routine will return the current lcd display screen origin relative to the f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
6-38 using graphics tools personal portable system manager programmers manual panning screen. example 6-36 get lcd display origin on panning screen u16 x, y; /* get the position of lcd display screen on panning screen */ cursorgetorigin(&x, &y); 6.34 allocate memory for panning screen p_void getscreenmem (u16 width , u16 height ) this routine will allocate memory for panning screen with specified size. however, the size of the new panning screen area cannot be larger than 64k. if no memory is available, it will return null. example 6-37 allocate memory for panning screen p_u8 screenptr; /* allocate memory for panning screen with width 320 and height 240 */ screenptr = (p_u8)getscreenmem(320, 240); personal portable system manager programmers manual database management 7-1 chapter 7 database management ppsm supports global database for applications to store and manage data. data type may be formatted or unformatted. the database tools enable applications to: ? create and delete multiple databases ? add and delete records from databases ? store, retrieve and modify data ? search for particular data in a database ? get status about a database this chapter gives some example usages of the database tools to help user getting up to speed fast. the system will call lmalloc() to create the database. in power reset, all database content will be erased. application programmer needs to save the database information into the flash or eeprom individually. 7.1 data format ppsm database tools support two types of data, formatted and unformatted. 7.1.1 formatted data formatted data means text data, and is field accessible. seven fields, as labeled in table 7-1 , will be used frequently in the pda environment and have been predefined. other formatted data fields can be defined by an application should need arise. when a new record is created, the number of formatted data fields is seven by default. ppsm allows users to add additional user-defined fields in a record. the number of maximum user defined field allowed in ppsm is defined by ppsm at compile time, currently it is five. notice that searching is only done on formatted data, not unformatted data. there is a size limit of 60 bytes imposed on each formatted data field. table 7-1 predefined field format used in the pda environment field index field name max. field size db_last last name 60 db_first first name 60 db_home home phone 60 db_office office phone 60 db_address address 60 db_fax fax 60 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
7-6 database management personal portable system manager programmers manual personal portable system manager programmers manual database management 7-3 database. 7.3 creating and editing a database whenever a record is created, ppsm will pass back a unique record identifier. application will need to use this identifier as the key for subsequent access of that particular record. the following example illustrates a routine build database and its associated memory variables which create a database, add new record and initialize four formatted data field in a record. note that user must have already declared the variable gaddbkdbaseid before calling dbadd(). it is important that the database id must remain intact since access to the database need this as the key. note also that in the example, recid is used as a temporary variable only, the creation of the next record will overwrite the former recid. this is permissible because of the linked list structure of the record list, we can traverse the list to retrieve the record that we need without needing you keep track of every record id. however, for those frequently called record, it would be better to allocate a memory variable to keep its record id for speedy access. example 7-1 create a database, add record, write data to record, and read number of records in database /* database identifier * u32 gaddbkdbaseid; /* data to be written in record 1 */ text grec1lname[5]={'a','d','a','m',0}; text grec1fname[4]={'k','e','n',0}; text grec1phone[9]={'2','2','2','-','6','7','8','9',0}; text grec1add[17]={'1','0',' ','m','a','v','e','n',' ','a','v','e',0}; /* data to be written in record 2 */ text grec2lname[8]={'a','p','p','l','e',0}; text grec2fname[4]={'j','o','e',0}; text grec2phone[9]={'6','6','6','-','1','3','3','1',0}; text grec2add[17]={'1','2',' ','m','a','i','n',' ','s','t','r','e','e','t',0}; status builddbase(void) { status ret; u32 recid; s32 numrec; ret = dbadd(&gaddbkdbaseid); if(ret != ppsm_ok) return(-1); /* add record 1 */ dbaddrecord(gaddbkdbaseid,&recid, 0); dbchangestddata(gaddbkdbaseid,recid, db_last,grec1lname); dbchangestddata(gaddbkdbaseid,recid, db_first,grec1fname); dbchangestddata(gaddbkdbaseid,recid, db_home,grec1phone); dbchangestddata(gaddbkdbaseid,recid, db_address,grec1add); /* add record 2 */ dbaddrecord(gaddbkdbaseid,&recid, 0); dbchangestddata(gaddbkdbaseid,recid, db_last,grec2lname); dbchangestddata(gaddbkdbaseid,recid, db_first,grec2fname); dbchangestddata(gaddbkdbaseid,recid, db_home,grec2phone); dbchangestddata(gaddbkdbaseid,recid, db_address,grec2add); /* read back no of record in the database, should be 2*/ f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
7-4 database management personal portable system manager programmers manual dbreadtotalnumberrecords(gaddbkdbaseid, &numrec); } 7.4 searching and retrieving data the following example uses the database created from example 7-1 , and searches for a particular record using a formatted data field as the key. it is good programming practice to check the returned status of the call dbsearchdata() ensuring that a match is found before using the recid returned for subsequent operation. example 7-2 search a database record list using a formatted data field and retrieve record data /* global database identifier */ u32 gaddbkdbaseid; /* this is the search key */ text grec1fname[4]={'k','e','n',0}; status searchrec(void) { status ret; u32 recid; /* pointers to the formatted data field to be read out */ p_text templname, tempfname, tempphone, tempaddress; /* search for a record in the record list with the db_first formatted data field matching the key string grec1fname */ ret = dbsearchdata(gaddbkdbaseid,db_first,grec1fname,&recid); if (ret != ppsm_ok) return (-1); /* search unsuccessful! */ /* recid now is the record which match the search key */ /* we can now access the data contained in the record via recid */ dbreaddata(gaddbkdbaseid, recid, db_last, &templname); dbreaddata(gaddbkdbaseid, recid, db_first, &tempfname); dbreaddata(gaddbkdbaseid, recid, db_home, &tempphone); dbreaddata(gaddbkdbaseid, recid, db_address, &tempaddress); /* templname, tempfname, tempphone, tempaddress now points to data field stored in the record identified by recid */ } /* end searchrec() */ 7.5 navigating along a record list the following example uses the record list navigation tools to access record sequentially. it is assumed that a database with the identifier gaddbkdbaseid has already existed. initially, the first record id in the record list is retrieved. then a while loop is set up to access record in the list sequentially. termination of the loop is by using the botflag passed to the routine dbgetnextrecid(). when this flag is set to 1, it signifies that the current record is the last record of the record list. example 7-3 use the record list navigation tools to access record sequen- tially /* global database identifier */ u32 gaddbkdbaseid; status seqaccessofrec(void) { u32 recid,nextrecid; s32 srchtoken = 1; u16 botflag = 0; p_text stddataout; personal portable system manager programmers manual database management 7-5 status ret; /* get the first record id for the database */ ret = dbgetfirstrecid(gaddbkdbaseid, &recid); /* check if the database record list is empty */ if (ret == ppsm_error) return(-1); /* read back data */ dbreaddata(gaddbkdbaseid, recid, db_first, &stddataout); . /* do something here */ . /* get next record */ while(srchtoken) { dbgetnextrecid(gaddbkdbaseid, recid, &nextrecid, &botflag); /* the recid passed is already at the end of list, exit loop */ if(botflag == 1){ srchtoken = 0; break;} /* read back data */ dbreaddata(gaddbkdbaseid, nextrecid, db_first, &stddataout); . /* do something here */ . /* continue search */ recid = nextrecid; } /* end while (srchtoken) */ } /* end of seqaccessofrec() */ f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
8-4 text display management personal portable system manager programmers manual 8.4.2.1 text output style the output style defines an operation between the text bitmap and the existing image at a specified display location. five output styles are supported. the text bitmap can replace, or with, and with, exclusive or with, or be inverted to replace the existing image. 8.4.2.2 text grey levels depending on the hardware system, up to four grey levels (0 to 3) can be supported. for details about the grey levels, refer to section 6.4 - 1 bit-per-pixel graphics and section 6.5 - 2 bits-per-pixel graphics . 8.4.3 setting font attributes status textsetfont (u32 templateid , p_fontattr pfontattr ) font attributes includes font type, font size (where applicable), and any attributes (e.g. outline) thats related to a particular font type. a font attribute data structure, called fontattr, needs to be filled with the desired values in order for these font attributes to be modified. these new font attributes will take effect when text is displayed using the text template which has these new values set. the following is the font attribute structure defined in ppsm.h: typedef struct { u16 type; /* font type */ u16 width; /* font width (in #pixels) */ u16 height; /* font height (in #pixels) */ u16 attrib; /* other font attributes */ table 8-1 supported output styles output styles operation replace_style replace or_style or with and_style and with exor_style exclusive-or with inverse_style invert and replace table 8-2 supported grey levels grey level values color black black dark_grey dark grey light_grey light grey white white personal portable system manager programmers manual text display management 8-1 chapter 8 text display management applications must map the text with its properties described in a text template to an area on the display screen, called the text display area, before any text can be seen. this chapter describes the set of text tools provided by ppsm to manage the display of text on the panning display screen. ppsm supports 16-bit text data representation which allows the support of any coded languages. the default is the support for various font types and sizes of asian and english characters display. the low level font driver supports both the scalable and bitmap font technologies. ppsm provides a set of default english fonts with size 8 x 10 and 16 x 20. if other fonts are needed, please contact the isv. 8.1 text representation both ascii and asian characters are stored internally as 16-bit values (type text) system-wide. for 8-bit ascii, they are zero-extended to 16-bit. for chinese, both gb and big-5 code formats are supported. the most significant byte of a 16-bit word is used to distinguish between 16-bit zero-extended ascii and asian codes; all 16-bit ascii characters have a zero most significant byte while all asian codes will have a non-zero most significant byte. 8.2 text display area text can be displayed anywhere within the panning screen (refer to section 2.3.2.2 - panning screen ). text is displayed starting at a specified location in a row by column format one character at a time as shown in figure 8-1 . f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
8-2 text display management personal portable system manager programmers manual 8.3 text templates a text template refers to a collection of text properties that describes the text to be displayed. these text properties include font type, font size, grey level, output style, coordinates and size of the text display, and the position of the display soft cursor. these text templates are independent of the text itself and provide the flexibility for applications to change the appearance of text in a collective and efficient manner. applications can create and delete the text templates at their discretion on an as needed basis. the soft cursor in text is an invisible position indicator showing where the text should be mapped. 8.3.1 creating text templates status textcreate (p_u32 templateid ) a text template needs to be created before any text can be displayed. a unique unsigned 32-bit text template identifier is returned from the system for each text template created. this text template identifier is used for future references to the created text template. refer to table 8-4 for the default values of the text properties when a text template is created. example 8-1 create a text template 336 u32 tid; /* textid for the text template */ 337 338 if(textcreate(&tid) != ppsm_ok) ........... ........... .... .... 01 2 n-1 ............................... 0 1 2 m-1 ............... n columns m rows y-coord x-coord a b c figure 8-1 a text display area on the panning display screen panning display screen width panning display screen height personal portable system manager programmers manual text display management 8-3 339 return ppsm_error; 340 8.3.2 deleting text templates status textdelete (p_u32 templateid ) when a text template is not needed anymore, applications should delete it to free up space that is being used to store the text properties. the text template identifier returned by textcreate() is used to specify which text template to be deleted. example 8-2 delete a text template 352 /* delete the text when it's no longer needed */ 353 if(textdelete(tid) != ppsm_ok) 354 return ppsm_error; 8.4 text properties text properties describes the layout and appearance of the text to be displayed on the panning display screen. these text properties, stored collectively in a text template, include the position and size of the text display area, the outlook of the text characters, the font attributes, and the position of the text soft cursor within the text display area. refer to table 8-4 for the default values of these properties of a text template when it is created. 8.4.1 setting text display layout status textsetdisplay (u32 templateid , u16 xpos, u16 ypos, u16 width , u16 height , u16 cursor ) the text display layout of a text template is rectangular and must reside within the boundary of the panning screen. the layout is anchored by the xy-coordinate of the upper left corner, and the width and height of the area in number of characters. the size of the text display area in number of pixels will vary according to the size of the selected font type. the specified cursor positions must lie within the range of 0 and one less than the number of characters the text display area can display. in figure 8-1 , the text display area is located at location (x, y) and it is m rows by n columns in size. this text display area can be moved around as the application wishes. 8.4.2 setting text outlook status textsetoutlook (u32 templateid , u16 outputstyle , u16 greylevel ) the text outlook of a text template are the output style and the grey level of the text to be displayed on the text display area. the new output style and grey level will take effect on subsequent text mapped using the text template after its been modified. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
8-8 text display management personal portable system manager programmers manual 8.6 text character cursor position the character cursor position determines where within the text display area text will be displayed next. this position is relative to the origin of the text display area specified in the given text template. the range of valid cursor positions is zero through one less than the size of the text display area in number of characters. in figure 8-1 , the range of valid cursor positions is zero through (m * n - 1), and the current cursor position is 3 after abc is displayed 8.6.1 setting the character cursor position status textsetcursor (u32 templateid , u16 cursor) setting the character cursor position of the text display area of the specified text template to the given value. subsequent displaying of text start at this new character cursor position. example 8-5 set character cursor position 53 static u32 gtextid, gtmptextid; . . . 279 /* clear the text on the display and reset cursor */ 280 textunmap(gtextid); 281 textsetcursor(gtextid, 0); 8.6.2 reading the character cursor position status textreadcursor (u32 templateid , p_u16 cursor ) applications can inquire the current character cursor position of a text display area specified by a text template. the returned character cursor position is where text will be displayed next. example 8-6 set and read the character cursor position u32 tid; /* text template id */ text moto[] = {'m', 'o', 't', 'o', 'r', 'o', 'l', 'a', 0};/* text to be displayed */ u16 len; /* # chars to be displayed */ u16 curpos;/* cursor position */ . . . /* create a text template */ textcreate(&tid); /* calculate # chars to be displayed */ len = strlen(moto); /* set up text properties. */ textsetup(tid, large_normal_font, exor_style, 3, 102, 0, len, 6); /* set current character cursor position to beginning of 2nd row in the text template */ textsetcursor(tid, len); /* display motorola using the modified text properties */ personal portable system manager programmers manual text display management 8-5 p_u8 bitmap; /* pointer to character bitmap */ } fontattr, *p_fontattr; 8.4.3.1 font types eight font types are supported. small normal and small italic are 8 x 10 pixels english fonts. large normal and large italic are 16 x 20 pixels english fonts. gb normal is 16 x 16 chinese font in gb code format. chinese normal is the same as gb normal (for backward compatibility). big5 normal is 16 x 16 chinese font in big5 code format. big5 variable is a variable size font in big5 code format. note: asian fonts are supplied by third parties. 8.4.3.2 font sizes if a scalable font engine is available, the big5_variable_font font type allows an application to specify the font width and height of the characters in a text template. the minimum and maximum width and height supported depend on the particular scalable font engine being provided. all the other font types are fixed size fonts. any attempt to modify the font width and height of those font types is ignored. 8.4.3.3 special font attributes no other special font attributes are currently being supported. so, attempts to modify the font attributes field of a text template is ignored. the attribute field is table 8-3 supported font types and sizes output styles operation small_normal_font 8 x 10 english normal small_italic_font 8 x 10 english italic large_normal_font 16 x 20 english normal large_italic_font 16 x 20 english italic gb_normal_font 16 x 16 gb normal chinese_normal_font same as gb_normal_font big5_normal_font 16 x 16 big5 normal big5_variable_font variable size big5 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
8-6 text display management personal portable system manager programmers manual reserved for future extensions and is set to zero. example 8-3 setting text properties u32 tid; /* text template id */ /* text to be displayed */ text moto[] = {'m', 'o', 't', 'o', 'r', 'o', 'l', 'a', 0}; /* this is to initialize every ascii character in 2-byte format with high byte being zero */ u16 len; /* # chars to be displayed */ fontattr fontattr; /* font attributes */ . . . /* create a text template */ textcreate(&tid); /* calculate # chars to be displayed */ len = strlen(moto); /* subsequent text displayed with text template tid will be located at (102, 0), length of moto characters wide and 6 characters high, starting at text cursor position zero. */ textsetdisplay(tid, 102, 0, len, 6, 0); /* subsequent text displayed with text template tid will be exclusive ored with the existing image on screen, with grey level black. */ textsetoutlook(tid, exor_style, black); /* set up font attributes */ fontattr.type = big5_variable_font; fontattr.width = fontattr.height = 20; fontattr.attrib = 0; /* subsequent text displayed with text template tid will be of big5 variable font type of size 20x20 pixels. */ textsetfont(tid, &fontattr); /* delete unused text template */ table 8-4 text properties default values text properties default value (x,y)-coordinate of the origin (top left corner) of the text display area (0, 0) width of text display area in number of characters 0 height of text display area in number of characters 0 character cursor position relative to origin of text display area 0 font type small_normal_font font width 8 font height 10 special font attributes 0 text grey level value black text output style or_style personal portable system manager programmers manual text display management 8-7 textdelete(tid); . . . 8.5 text mapping mapping functions are provided for applications to display and remove text on the panning display screen area. the display and removal of text are tied to a text template. 8.5.1 displaying text status textmap (u32 templateid , p_text buffer , u16 numchar ) the given text is displayed, one character at a time, starting at the current character cursor position of the text display area and with text attributes as described by the specified text template. there is no word-wrap function. text is treated as individual characters, i.e. characters of a word that extends beyond a row will appear on the next row of the text display area. text displaying stops when the character cursor position is at the end of the text display area, when all characters supplied by the application are mapped, or when numchar characters are mapped. after displaying characters on panning screen, character cursor position will be advanced to the next available position, or (the end of the template + 1) if the last character displayed is at the end of the template. any out standing characters are going to be ignored without returning any error. example 8-4 display text on text display area 333 status displaystring(u8 font, u8 style, u8 greylev, u16 xsrc, u16 ysrc, text str[]) 334 { 335 u16 len; /* length of the string */ 336 u32 tid; /* textid for the text template */ . . . 341 /* get the string length */ 342 if (len = strlen(str)) 343 { 344 /* set up the text attributes */ 345 if(textsetup(tid, font, style, greylev, xsrc, ysrc, len, 1) != ppsm_ok) 346 return ppsm_error; 347 348 /* map the text to the screen */ 349 if(textmap(tid, (p_text)str, len) != ppsm_ok); 350 return ppsm_error; 8.5.2 removing text status textunmap (u32 templateid ) the unmapping of text means clearing the entire text display area. the location and size of the text display area to be cleared is specified in the given text template. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
9-2 timer management personal portable system manager programmers manual status alarmreadid (u32 alarmid , p_u16 year , p_u16 month , p_u16 day , p_u16 hour , p_u16 minute , p_u16 second ) read the coming clock alarm time using alarmread() and read the specific clock alarm time by using alarmreadid(). if no alarm is set, all arguments will return zero. 9.4 setting clock alarm status alarmset (u16 year , u16 month, u16 day , u16 hour , u16 minute, u16 second ) status alarmsetid (p_u32 alarmid , u16 year , u16 month, u16 day , u16 hour , u16 minute, u16 second ) set the clock alarm. when the alarm time is reached, ppsm will generate a soft interrupt to the application that called this tool. the interrupt message type will be irpt_rtc. if alarmsetid() is used, the alarm id. will be returned with the irpt_rtc when time is reached. 9.5 clearing clock alarm void alarmclear (void) void alarmclearid (u32 alarmid ) clear the clock alarm in current task using alarmclear() or clear specific alarm using alarmclearid(). ppsm will no longer generate the irpt_rtc message to the application. 9.6 setting periodic alarm status setperiod (u16 period ) status setperiodid (p_u32 alarmid , u16 period ) set or clear the periodic alarm. ppsm generates periodic interrupts to the application that calls this tool. the hour periodic interrupt is applicable to mc68ez328 only. if setperiodid() is used to set a periodic alarm, the alarm id. will be returned. the period that is allowed are: rtc_peri_none disable periodic interrupt rtc_peri_second second periodic interrupt rtc_peri_minute minute periodic interrupt rtc_peri_hour hour periodic interrupt rtc_peri_midnight midnight periodic interrupt personal portable system manager programmers manual text display management 8-9 textmap(tid, (p_text)moto, len); /* read current character cursor position (should be at beginning of 3rd row in this case) */ textreadcursor(tid, &curpos); . . . f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
8-10 text display management personal portable system manager programmers manual personal portable system manager programmers manual timer management 9-1 chapter 9 timer management ppsm uses one dragonball tm family timer to maintain a continuous 32-bit system reference timer and the system clock. the reference timer has a resolution of 100 microseconds and the system clock has a resolution of 1 second. a set of timer tools are included for applications to set the system clock, system date, periodic alarm, clock alarm and time-out. ppsm manages all the timer devices. the tools allow the application to set a specific time-out or alarm, then continue with other operations. when the appropriate alarm time or time-out period is reached, ppsm generates the soft interrupt to notify the application of the event. the system default time at power reset is at 9:00am, 1st of january, 1997. two types of interrupt messages are defined for timer functions: ?irpt_rtc ? irpt_timer irpt_rtc message is sent to the application for clock alarm and periodic alarm. irpt_timer message is sent to the application for time-out. if the timeout or alarm happens when the current task is not the timer nor the alarm task, the timer or alarm task will be swapped in once all messages in current task are handled. 9.1 reading system date and time status datetimeread (p_u16 year , p_u16 month , p_u16 day , p_u16 hour , p_u16 minute , p_u16 second ) read the system date and time. 9.2 setting system date and time status datetimeset (u16 year , u16 month , u16 day , u16 hour , u16 minute , u16 second ) set the system date and time. the year cannot be set less than 1900. 9.3 reading clock alarm status alarmread (p_u16 year , p_u16 month , p_u16 day , p_u16 hour , p_u16 minute , p_u16 second ) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
9-6 timer management personal portable system manager programmers manual personal portable system manager programmers manual timer management 9-3 9.7 setting timeout status timeout (u32 millisecond ) status timeoutid (p_u32 timerid, u32 millisecond ) general time-out tool. ppsm will generate a single soft interrupt message to the caller once the time-out period has elapsed. an input value of zero will immediately disable the time-out function for the current task including those timeout set by reference timer alarm tools. timeoutid() will output the timerid which will be returned in irptgetdata() if time elapsed. irpt_timer is the interrupt message sent to the caller application when time-out occurs. 9.8 setting input timeout status inputtimeout (u32 millisecond ) set the repetitive time-out period for data input from the touch panel. this time-out routine is an explicit time-out routine dedicated for the pen input device. once this time-out is activated, the specified time-out period count down begins immediately after a valid pen input stroke. if the time-out period expires before the next pen input occurs, ppsm will generate a timer interrupt to the caller; otherwise, the time-out period is reset for the next pen input. this is a repetitive time-out because once activated, the timer will continuously be set for time-out after each pen input stoke until the time-out is cancelled. irpt_timer is the interrupt message sent to the caller application. the timer id. returned in irptgetdata() will be 0xffffffff to distinguish it from the normal timer set by timeout(), timeoutid(), reftimealarm(), etc. to cancel the input time-out for current task, call this function with zero as the argument. rtc_peri_no_second disable second interrupt for current task rtc_peri_no_minute disable minute interrupt for current task rtc_peri_no_hour disable hour interrupt for current task rtc_peri_no_midnight disable midnight interrupt for current task f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
9-4 timer management personal portable system manager programmers manual 9.9 continuous reference timer ppsm provides a continuous 32-bit reference timer to applications. this 32-bit value wraps around about every 5 days, but ppsm takes care of the wrap-around condition, making it transparent to the application. applications can select to use either a resolution of 1 millisecond unit or 100 microsecond unit. the following tools allow the user to make use of this reference timer for functions, such as time- stamping and time-out. note that there are two sets of timer tools, one for millisecond resolution, one for 100 microsecond resolution. the reference value returned by these two separate sets of tools should not be mixed. that is, values returned from the millisecond tools cannot be used in the 100 microsecond tools. the millisecond resolution timer tools are named with prefix "reftime", and the 100 microsecond resolution tools are named with prefix "reffinetime". 9.10 read the reference timer u32 reftimeread (void) u32 reffinetimeread (void) read the reference timer value. the return value is an unsigned 32-bit integer representing the current reference timer value, either in millisecond resolution for reftimeread(), or in 100 microsecond resolution for reffinetimeread(). 9.11 set reference timer alarm status reftimealarm (u32 alarmtime ) status reffinetimealarm (u32 alarmtime ) status reftimealarmid (p_u32 alarmid , u32 alarmtime ) status reffinetimealarmid (p_u32 alarmid , u32 alarmtime ) set the alarm time, using the reference value as reference. this is a relative alarm tool. when using this tool, the input argument is the time that the system will generate an alarm interrupt to the caller application. this value can easily be obtained by calling the respective reftimeread() or reffinetimeread() tool. the alarmid output from this functions will be returned in irptgetdata() once the alarm time is reached. 9.12 compute reference times differences u32 reftimediff (u32 begintime, u32 endtime ) u32 reffinetimediff (u32 begintime, u32 endtime ) personal portable system manager programmers manual timer management 9-5 compute the difference in time for the given two reference times. the return value is in millisecond resolution for reftimediff(), and in 100 microsecond for reffinetimediff(). example 9-1 timer usage u32 (*timeread)(); status (*timealarm)(u32 alarmtime); u32 (*timediff)(u32 begintime, u32 endtime); . . status reftimer(void) { . . while ( 1 ) { /* initialize all the variable for holding the time value */ goldtime = 0; gnewtime = 0; gdifftime = 0; /* set up time function for reference timer to read the time, * to start the alarm and to calculate the time difference. */ if (gunit == milli_second) /* unit in millisecond */ { /* assign the function pointer to its corresponding reference * timer function. */ timeread = reftimeread; timealarm = reftimealarm; timediff = reftimediff; } else if (gunit==micro_second) /* unit in microsecond */ { timeread = reffinetimeread; timealarm = reffinetimealarm; timediff = reffinetimediff; } setunit(milli_second); /* use reftime toolset */ . if (*indata == ppsm_icon_pen_up) { . . if (id == readtimerid) { /* put the previous time to the goldtime buffer, then read * the latest time and store in the gnewtime. get the * difference of both and store in the gdifftime. */ goldtime = gnewtime; gnewtime = (*timeread)(); gdifftime= (*timediff)(goldtime, gnewtime); displaytime(); }/*if readtimerid*/ . . } }/*while*/ }/*reftimer*/ f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
11-2 power management personal portable system manager programmers manual are driven by the system clock, power saving on the cpu core can be achieved without sacrificing peripheral response time. 11.2 power modes figure 11-1 shows the state diagram for the power modes. there are six modes defined in ppsm. system internal modes: ? initialization mode ? system mode ? wake-up mode application modes: ? normal mode ? doze mode ? sleep mode 11.3 system internal modes initialization, system and wake-up modes are only used internally by ppsm. doze sleep wake-up power on / reset normal system initialization figure 11-1 ppsm power modes application modes system internal modes personal portable system manager programmers manual memory management 10-1 chapter 10 memory management in order for ppsm to manage system memory usage, the standard memory management tools provided by the compiler are disabled. ppsm provides a set of its own memory tools that allow the application programmers to dynamically allocate memory from the system. the size of this dynamic memory available to ppsm is specified in the linker specification file (refer to chapter 34 - linker specification file ). note: for allocating memory to panning screen, a special memory allocation function called getscreenmem() in chapter 6 - using graphics tools is used. 10.1 allocating memory void * lmalloc (u32 size) void * lcalloc (u32 size) memory can be allocated to the application at run time. ppsm returns to the caller a pointer to a block of available memory of the specified size. the memory returned to the caller is not initialized if lmalloc() is called, or is initialized to zero if lcalloc() is used. no automatic boundary checking is performed on the memory when used by the caller. the size of the largest block of memory can be allocated through lmalloc() can be found by calling lmalloc( largest_malloc_size ). if no memory is left in the system, these routines return a null. the actual size of memory allocated by the system is larger than the size requested by user. a header is embedded in the allocated memory block for memory management. nevertheless, it is transparent to user. user can directly use the required size of memory block start at the returned address if the returned value is not null. 10.2 freeing memory void lfree (void *ptr) when an application finishes with a block of dynamically allocated memory, the memory can be recycled by using the lfree() tool. it puts the memory block back into the system heap and the memory is ready for allocation again. the pointer passed into this routine must be a valid pointer returned from lmalloc() ,lcalloc() or lrealloc(). f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
10-2 memory management personal portable system manager programmers manual 10.3 reallocating memory void * lrealloc (void *src, u32 size) moving of memory. this routine re-allocates the memory that is being used in the system from one location to another. it allocates a new area, then copies the content from the old location to the new area and free up the old memory, putting it back into the system heap. the purpose of this routine is for defragmentation of the system memory. 10.4 copying memory status moveblock (p_u32 srcaddr , p_u32 destaddr , u32 size ) copying memory from one region to another. this tool can cope with over-lapping area. it performs memory copy in 32-bit operations whenever possible. 10.5 inquiring memory status taskmemused (u32 taskid, p_u32 psizeused ) u32 totalmemused (void) u32 totalmemsize (void) s32 taskstackavail (void) memory allocated to the application and the whole system can be inquired at run time. ppsm returns to the caller the total number of bytes of memory allocated to the task with the given task identifier when calling taskmemused(), or number of bytes of memory allocated to the whole system when calling totalmemused(). ppsm returns the number of bytes of memory on the system can be allocated through lmalloc(), lcalloc() or lrealloc() when calling totalmemsize(). ppsm returns to the caller the total number of bytes of stack can still be used by current task when calling taskstackavail(). positive returned value indicates stack has not been used up, negative value implies stack has already overflowed. user can inquire the size of the largest continuous memory block by calling lmalloc() with input flag largest_malloc_size. personal portable system manager programmers manual power management 11-1 chapter 11 power management ppsm utilizes the power control module of dragonball tm to implement a set of power management tools to achieve system power saving. the power management tools enable applications to: ? switch to one of the power saving modes ? control the duty cycle of the processor for each application in normal mode ? switch automatically to a lower power saving mode when system is idle ? control user defined i/o ports in any of the power saving mode transition applications can choose to: ? control the systems power management features directly, or ? use the ppsms automatic power management features. by default, the system will go to doze mode if there is no more task swapping nor message waiting to be served in current task. so the default state is 0 sec. doze period and sleep period counting will start if its set in setsleepperiod(). 11.1 power control module ppsm makes use of the power control module, pcm, to improve system power efficiency. it allows the allocation of system clock cycles to the cpu core under software control. system clocks generated from the phase locked loop are sent to the cpu via the pcm. by controlling the pcm register, clocks can be bursted to the cpu core from a minimum of 3% to the full 100% in steps of 3%. this is referred to as the cpu core duty cycle. ? while the cpu demand is low, for example in a calculator application, the clock can be bursted with a low duty cycle. ? while the cpu demand is high, for example in a handwriting recognition application, the clock can be running continuously at a 100% duty cycle. the pcm uses a period of 32 clock cycles to burst the cpu core. ? for example, with a low duty cycle value of 12%, in any given period of time, the cpu core is active for 4 clock cycles (12% of 32 clock cycles), followed by 28 clock cycles of idle cpu core. please refer to the mc68328 user's manual for full details on the operation of the pcm. when using the pcm to control power management, the system clock from the phase locked loop remains in high frequency. since all peripherals on mc68328 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
11-6 power management personal portable system manager programmers manual mode. ? if a wake-up condition is met anytime during doze mode before the time-out countdown for sleep is reached, ppsm will reset the countdown and return the system to wake-up mode. this automatic sleep mode time-out countdown is repeatedly performed in doze mode until the sleep mode period is set to zero, i.e. disabling sleep mode transi- tion. 11.4.3.3 waking up from sleep any one of the following internal or external interrupts can wake up ppsm from sleep mode. the interrupts are: ? pen interrupt ? real time clock alarm, periodic and mid-night interrupts ? external interrupts from irq1, irq2, irq3, irq6, int0-7, uart and pwm for mid-night interrupt, system will wake up from sleep mode, update system date and time and then go back to sleep mode. for other interrupts listed above, system will wake up from sleep mode and go to normal mode. 11.5 power management tools 11.5.1 setting duty cycle u16 setdutycycle (u16 percentage ) this tool allows the application task to set the duty cycle level for itself in normal mode. applications within a system can have different duty cycle percentages. ppsm automatically changes the pcm accordingly when an application task becomes active. 11.5.2 setting doze period status setdozeperiod (u16 millisecond ) sets the countdown period, in units of millisecond, to switch the system from nor- mal mode to doze mode. a value of ppsm_no_doze disables the system from going into doze mode automatically which implies no automatically to sleep mode. a value of zero will bring back the system to default doze setting. the default doze setting is to go to doze mode whenever there is no task swap nor message in cur- rent task to be handled. 11.5.3 setting sleep period status setsleepperiod (u16 second ) sets the countdown period, in units of second, to switch the system from doze personal portable system manager programmers manual power management 11-3 applications need not be concerned with the three system internal modes. they are included in this chapter as a reference on the design of ppsm power man- agement. all of these are intermediate modes among the application modes, where ppsm takes control to perform necessary system operations, such as task swapping, message passing and power management decisions. 11.3.1 initialization mode this is the power on or system reset mode. boot strapping and initialization of ppsm occur in this mode. the system never enters into this mode again once ppsm is initialized, unless system reset occurs. 11.3.2 system mode ppsm performs all of its task swapping, message passing, interrupt handling, power module controlling and modes switching in the system mode. this mode is frequently invoked, only for a very short duration, when the system is actively run- ning, for example, to handle pen sampling, task swapping and message passing. to minimize the actual time spent in this mode, the duty cycle is set to 100% regardless of its set value prior to entering system mode. when the system leaves system mode, it will restore the duty cycle of the previous mode. 11.3.3 wake-up mode this is invoked either from doze or sleep mode. when the system is in doze or sleep mode, only internal or external interrupts can wake up the system (please refer to section 11.4.2.3 - waking up from doze and section 11.4.3.3 - waking up from sleep for the wake-up conditions). in wake-up mode, the system determines ? which of the interrupts occurred, ? where the interrupt messages, if any, should be sent to, ? which application, if any, needs rescheduling, and ? which mode the system should go into next. for example, mid-night interrupt from the real time clock, the system will: 1) go into wake-up mode from sleep 2) determine that the interrupt is intended for system only 3) update the system date 4) go directly back to sleep mode 11.4 application modes normal, doze and sleep modes are the application modes. these are the modes that an application sees and can have control over. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
11-4 power management personal portable system manager programmers manual 11.4.1 normal mode in this mode, applications can make use of the power control module to control the cpu duty cycle value, please refer to section 11.5.1 - setting duty cycle . the phase locked loop is on, all peripherals are active, lcd controller is enabled. application is actively executing code. ppsm is designed as an event driven system. it determines interrupt activities by monitoring the calls to the system tool irptgetdata(). ? when there are interrupts, irptgetdata() returns to the application with interrupt messages. these messages are processed by the application accordingly. ? when there is no more interrupt pending for processing, a special message, irpt_none is returned to the application. 11.4.2 doze mode in this mode, the cpu is disabled to save power consumption. the lcd control- ler, real time clock, timer and phase locked loop remain operational but all other peripherals are disabled. system is waiting for interrupts to wake up the cpu for more activities. there are two ways for applications to enter doze mode: ? direct system call ? automatic time-out 11.4.2.1 direct system call to doze mode application can go into doze mode directly by calling setdozemode(), please refer to section 11.5.4 - going into doze mode . in this operation, ppsm will put the system into doze mode immediately, until a wake-up condition is met. 11.4.2.2 automatic time-out to doze mode application can set a time-out period for the system to go into doze mode from normal mode. when ppsm detects that there are no more interrupt activities, either from the pen, timers, real time clock or external i/o, it will start this time-out period countdown. when this time-out expires, it will switch the system to doze mode. ppsm uses irpt_none as an indication that the application is waiting for events and is ready to go into doze mode. the doze time-out countdown, if set, begins. however, if a wake-up condition occurs before the doze time-out has expired, the doze time-out countdown is reset, and ppsm will return to the monitoring stage. this automatic doze mode time-out monitoring is repeatedly performed in normal mode until the doze mode period is set to zero, i.e. disabling doze mode transi- tion. personal portable system manager programmers manual power management 11-5 11.4.2.3 waking up from doze any one of the following internal or external interrupts can wake up ppsm from doze mode in mc68328. the interrupts are: ? pen interrupt ? real time clock alarm, periodic and mid-night interrupts ? timer 1 and timer 2 interrupts ? external interrupts from irq1, irq2, irq3, irq6, int0-7 for mc68ez328, whatever active interrupt before going to doze will be able to wake up the system. the kind of interrupt to wake up the system can also be changed in portdozedis- able() and restored in portdozeenable() in device driver. the system can also be waked up by using sendmessage() or advsendmes- sage() to send message to the current task. for mid-night interrupt, system will wake up from doze mode, update system date and time and then go back to doze mode. for other interrupts existed above, sys- tem will wake up from doze mode and go to normal mode. 11.4.3 sleep mode in this mode, ? cpu, phase locked loop, lcd controller, and all peripherals are disabled. ? only the real time clock and interrupt handler module are active. this is the mode where power consumption is kept to a minimum as the most power consuming parts of the system, cpu and lcd, are off. there are two ways for applications to enter sleep mode: ? direct system call ? automatic time-out 11.4.3.1 direct system call to sleep mode application can go into sleep mode directly by calling setsleepmode(), please refer to section 11.5.5 - going into sleep mode . in this operation, ppsm will put the system into sleep mode immediately, until a wake-up condition is met. 11.4.3.2 automatic timeout to sleep mode application can set a time-out period for the system to go from doze mode to sleep mode. when ppsm puts the system into doze mode, it will automatically start the doze to sleep time-out countdown, if set. ? when this time-out expires, ppsm will put the system into sleep f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-2 personal portable system manager programmers manual personal portable system manager programmers manual power management 11-7 mode to sleep mode. a value of zero disables the system from going into sleep mode. 11.5.4 going into doze mode void setdozemode (void) system goes directly to doze mode. system will stay in doze mode until a wake- up condition is met. 11.5.5 going into sleep mode void setsleepmode (void) system goes directly to sleep mode. system will stay in sleep mode until a wake- up condition is met. 11.6 i/o ports control for those i/o ports that are used by the hardware system, special handling will be required as ppsm does not have any knowledge of usage of these i/o ports. the system integrator will need to supply specific device routines that ppsm can call to disable and enable these i/o ports during normal, doze and sleep mode tran- sitions. 11.6.1 disabling i/o port before doze mode void portdozedisable (void) just before ppsm goes into doze mode, it will call this routine to disable any user defined i/o ports that are not handled internally by ppsm. user must add in the code to disable the i/o ports in this routine. 11.6.2 enabling i/o port after doze mode void portdozeenable (void) when ppsm wakes up from doze mode, it will call this routine to re-enable any user defined i/o ports that are not handled internally by ppsm. user must add in their own i/o initialization code in this routine. 11.6.3 disabling i/o port before sleep mode void portsleepdisable (void) just before ppsm goes into sleep mode, it will call this routine to disable any user defined i/o ports that are not handled internally by ppsm. user must add in the code to disable the i/o ports in this routine. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
11-8 power management personal portable system manager programmers manual 11.6.4 enabling i/o port after sleep mode void portsleepenable (void) when ppsm wakes up from sleep mode, it will call this routine to re-enable any user defined i/o ports that are not handled internally by ppsm. user must add in their own i/o initialization code in this routine. personal portable system manager programmers manual 12-1 chapter 12 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-6 uart communication support personal portable system manager programmers manual data transmit application ppsm h/w figure 12-2 uart communication architecture - data transmit request access check access permission release access & acknowledge send data to hardware & acknowledge request transmit access permission request (if not already) granted / denied transmit request & data complete / error release access request data sent acknowledge release access personal portable system manager programmers manual uart communication support 12-3 chapter 12 uart communication support ppsm supports serial communication through the uart in both normal mode and irda mode. a set of interface tools is provided for applications to send and receive data through the uart. 12.1 uart communication architecture the uart interface tools provide an easy-to-use api for applications to send and receive data serially with or without hardware flow control. refer to figure 12-1 and figure 12-2 for an overview of the uart communication architecture between a calling application and ppsm at system start up and during data transmission. ppsm monitors the use of the uart among applications through irptrequest() and irptrelease() (refer to chapter 15 - interrupt handling ). the uart interface tools will have effect only after the calling application has been granted permission to access the uart. the data transmission is interrupt-driven. once permission is granted, the calling application can configure the uart, send or receive data through the uart, and be notified of the result of the send or receive operation. the same set of api tools is used for irda communication if the uart hardware is configured to run in irda mode. 12.1.1 uart hardware flow control in ppsm v3.11, data communication between dragonball and other communication devices using uart supports rts, cts hardware flow control. rts is asserted automatically by calling uartsend() and uartreceive() when hardware flow control is enabled. in null modem configuration, when dragonball is sender, receiver needs to acknowledge dragonball ready to receive by asserting its rts pin. when dragonball is receiver, it acknowledges the sender side by asserting rts pin. thus, if both rts pins of dragonball and the other communication device are asserted, data transfer can be full-duplex. three apis are available for rts, cts hardware flow control. they are uartflowctrl(), uartrcvctrl() and uartsendctrl(). hardware flow control can be enabled or disabled by calling uartflowctrl(). by calling uartrcvctrl() and uartsendctrl(), ppsm can pause or continue data reception and data transmission respectively. an api, uartsendabort(), is used for returning the current position of software send buffer and number of bytes have been transmitted by dragonball. also, this api can abort the transmission with appropriate input flag. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-4 uart communication support personal portable system manager programmers manual 12.1.2 uart interface constraints only one task in the system can access the uart at any one time. except for inquiring current settings, an error code will be returned to the application if it attempts to use the uart interface tools before permission is granted. applications swapping is inhibited during uart data transmission and reception. once a data transmission or reception request has been initiated by an application, pen touches on application icons will be ignored. this constraint prevents data loss due to suspension of the application which initiated the request. the enforcement of these constraints requires cooperation among applications in initiating a request only when it is needed, and cancelling a request as soon as data transmission or reception is completed. personal portable system manager programmers manual uart communication support 12-5 data receive application ppsm h/w figure 12-1 uart communication architecture - data receive request access check access permission release access & acknowledge read data & determine end of data abort read data read data from hardware request receive access permission request (if not already) granted / denied receive request granted / denied data read / error data receive request data requested abort read data request release access request read request data / error acknowledge release access check receive permission f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-10 uart communication support personal portable system manager programmers manual mode, various baud rates, parity settings, stop bit settings, character length settings, and data transmission time out settings. when configured to operate in normal mode, the minimum and maximum baud rates supported are 300 bps (bits per second) and 115200 bps respectively. when configured to operate in irda mode, only the 115200 bps baud rate is guaranteed. there is no default uart configuration after system start-up. please make sure uart is configured properly by calling uartconfigure() before initiating any data communciation. please note that the application must have the permission to access the uart before it can configure the uart. refer to chapter 15 - interrupt handling regarding the usage of irptrequest() to request permission. 12.2.1 configuring the uart status uartconfigure (u8 mode, u16 baudrate , u8 parity , u8 stopbits , u8 charlen ) applications can use uartconfigure() to reconfigure the uart to the required settings. any on-going data transmission request will be aborted and the data transmission time out reset to the default. the actual baud rate will be the closest approximation to the specified baud rate. table 12-2 shows the list of configurations and settings supported, and the corresponding selection flag to be used with uartconfigure(). (refer to section 26.1 - uartconfigure for details) table 12-2 uart configurations and supported settings configurations supported settings operating mode ? normal nrz mode ? irda mode baud rate ? 300 bps ? 600 bps ? 1200 bps ? 2400 bps ? 4800 bps ? 9600 bps ? 14400 bps ? 19200 bps ? 28800 bps ? 38400 bps ? 57600 bps ? 115200 bps parity ? no parity ? odd parity ? even parity personal portable system manager programmers manual uart communication support 12-7 data receive application ppsm h/w figure 12-3 uart communication architecture - data receive with rts/cts flow control request access check access permission release access & acknowledge read data & determine end of data abort read data read data from hardware request receive access permission request (if not already) granted / denied receive request granted / denied data read / error data receive request data requested abort read data request release access request read request data / error acknowledge release access check receive permission with rts/cts flow control assert rts and initiate rx timeout negate rts and clear rx timeout pull low rts pin pull high rts pin f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-8 uart communication support personal portable system manager programmers manual data transmit application ppsm h/w figure 12-4 uart communication architecture - data transmit with rts/cts flow control request access check access permission release access & acknowledge send data to hardware & acknowledge request transmit access permission request (if not already) granted / denied complete / error release access request data sent acknowledge release access with rts/cts flow control assert rts and initiate tx timeout pull low rts pin check transmit permission granted / denied wait for end of transmission transmit request & data negate rts and clear tx timeout pull high rts pin personal portable system manager programmers manual uart communication support 12-9 12.1.3 uart interface interrupt message the uart interface communicates with an application via an interrupt message returned by irptgetdata(), called irpt_uart. please refer to chapter 15 - interrupt handling for details about irptgetdata(). after an application is granted permission to use the uart, it can initiate a data transmission request. as the data transmission progressed, it will receive the irpt_uart interrupt message with the corresponding message data under the following circumstances. ? an error condition has occurred. the interrupt message data, uart_error, appended with an error code will be returned to the calling application. the error codes are: ? uart_err_tmout for data transmission time out condition once the transmission has started. ? uart_err_frame for frame error condition during data receive. ? uart_err_parity for parity error condition during data receive. ? uart_err_overrun for overrun error condition during data receive. ? uart_err_nodata for prematurely requesting ppsm for data before data has been received. ? data has been received from the uart. the interrupt message data, uart_data_received, will be returned to the calling application. ? data send request has been completed. the interrupt message data, uart_data_sent, will be returned to the calling application. table 12-1 shows the new uart interrupt message and the related data returned with it during irptgetdata(). 12.2 uart configurations ppsm allows applications to configure the uart to operate in normal or irda table 12-1 uart interrupt message and related message data interrupt message data returned data type irpt_uart uart_error followed by the actual error code: ? uart_err_tmout ? uart_err_frame ? uart_err_parity ? uart_err_overrun ? uart_err_nodata uart_data_received uart_data_sent 16-bit integer f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-14 uart communication support personal portable system manager programmers manual 12.4.1 initiating a receive request applications can receive data from the uart by calling uartreceive() to initiate receive requests. a receive request will be accepted if both of the following is true: ? the application has permission to access the uart (refer to chapter 15 - interrupt handling ) ? there is no other on-going receive request actual data receiving does not happen within the scope of uartreceive(). if uartreceive() returns success for the request, ppsm will handle the uart interrupts and start waiting for data in the background. the application will be able to handle other interrupts (e.g. pen interrupts) in the foreground. for power saving reason, system is in doze mode during data reception. for fast data reception, it is recommended to disable the doze mode before calling uartreceive(). note: application swapping is disabled when there is an on-going receive request. 12.4.2 reading received data when ppsm has received data from the uart, it will post an irpt_uart interrupt message with message data uart_data_received to the calling application. the calling application should then call uartreaddata() as soon as possible to read the received data from ppsm. as ppsm is receiving data from the uart, the following error conditions may arise: ? a frame error generated by the uart hardware ? a parity error generated by the uart hardware ? an overrun error when ppsm or the calling application is falling behind in reading the received data in any of the above error conditions, ppsm will post the irpt_uart interrupt message with message data uart_error and the corresponding error code. these error related interrupt messages only serve as a notification to the calling application, and does not stop ppsm from continuing the receive request. the calling application should determine the appropriate recovery actions. (refer to section 15.1.9 - irpt_uart for details about the uart interrupt message). if rts/cts is enabled, rts pin is negated when ppsm running uartreaddata() and asserted after data reading completed. 12.4.3 terminating a receive request a receive request will be terminated under the following circumstances: ? if a timed out error condition occurs during the course of receiving data, ppsm will post the irpt_uart interrupt message with message data uart_error and the corresponding error code. personal portable system manager programmers manual uart communication support 12-11 12.2.2 inquiring the uart configurations void uartinquire (p_u8 mode, p_u32 baudrate , p_u8 parity , p_u8 stopbits , p_u8 charlen ) uartinquire() provides the interface for applications to inquire the current configuration settings of the uart. uartinquire() returns the selection flag for the corresponding configuration setting as shown in table 12-2 , except for baud rate. the actual baud rate in bps is returned instead. note: uartinquire() is the only uart api tool that does not require uart access permission. 12.2.3 setting data transmission time out status uarttimeout (u16 tmout ) the data transmission time out is defined to be the time interval between two hardware uart interrupts. this time out is set to safe-guard the application from deadlocking itself when the data stream terminates unexpectedly. if rts/cts is enabled, after called uartsend() to initiate transmission, application will receive a time out error if cts is not asserted within the time out period. if cts is asserted, application will receive a time out error if the time interval between two hardware uart interrupts is larger than the time out period. the range of time out values supported is zero to 60,000. ? zero means disabling the time out function. ? 1 to 60,000 means allowing the time interval between two hardware uart interrupts to be 1 millisecond to 1 minute. 12.2.4 setting data transmission delay status uartsetdelay (u8 type, u16 delay ) in order to communicate with application in pc, such as hyperterminal and telix, transmitting data in a burst of pulses periodically would greatly increase the accuracy of transmission. this function allows user to set a delay, in unit of 100us, between each transmission of all data in transmit fifo (between two hardware interrupts). in example 12-1 , an application is going to transmit data through uart to hyperterminal under window95. a 400 microseconds delay is set between each uart hardware interrupt. number of stop bits ? 1 stop bit ? 2 stop bit character length ? 7-bit character ? 8-bit character table 12-2 uart configurations and supported settings configurations supported settings f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-12 uart communication support personal portable system manager programmers manual the range of delay values supported is 1 to 60,000. ? uart_txdelay_clear means clear the delay during transmission ? 1 to 60,000 means allowing the delay interval between two hardware uart interrupts to be 100 microsecond to 6 seconds. example 12-1 setting delay within transmission ..... irptrequest(irpt_uart_flag); /* enable rts/cts flow control */ uartflowctrl(uart_rcts_enable); /* configure uart */ uartconfigure( uart_normal_mode, uart_115200_bps, no_parity, one_stop_bit, eight_bit_char); /* set a 600 us delay between each hardware interrupt */ _uartsetdelay(uart_txhalf_delay, 6); /* release irpt */ irptrelease(irpt_uart_flag); ..... 12.3 sending data to the uart status uartsend (u8 sendflag, p_u8 data, u16 datalen ) refer to figure 12-2 and figure 12-4 for an overview of the data transmit architecture. 12.3.1 initiating a send request applications can send data out to the uart by calling uartsend() to initiate send requests. a send request will be accepted if both of the following are true: ? the application has permission to access the uart (refer to chapter 15 - interrupt handling ) ? there is no other on-going send request actual data sending does not happen within the scope of uartsend(). if uartsend() returns success for the request, ppsm will handle the uart interrupts and start sending data in the background. the application will be able to handle other interrupts (e.g. pen interrupts) in the foreground. the calling application cannot modify the content of the data buffer during the entire course of the send request. if rts/cts hardware flow control is enabled, ppsm only transmits data through uart when cts pin is asserted by receiver. for power saving reason, system is in doze mode during transmission. however, transmission speed is reduced. for fast data transmission, it is recommended to disable the doze mode before calling uartsend() which is shown in example 12-2 . note: application swapping is disabled when there is an on-going data transmission. personal portable system manager programmers manual uart communication support 12-13 example 12-2 initiating a send request ..... irptrequest(irpt_uart_flag); setdozeperiod(ppsm_no_doze); uartsend(uart_send_request,gsendmsg,gsenddatalen); ..... 12.3.2 terminating a send request a send request will be terminated under the following circumstances: ? after ppsm finishes sending all data, it will post an irpt_uart interrupt message with message data uart_data_sent to the calling application. this marks the completion of the send request. (refer to section 15.1.9 - irpt_uart for details about the uart interrupt message). ? if a timed out error condition occurs during the course of sending data, ppsm will post the irpt_uart interrupt message with message data uart_error and the corresponding error code. this marks a failed send request, and the calling application should determine the recovery actions. the current transmission is aborted after time out happened. ? an application aborts the on-going send request by calling uartsend() or uartsendabort() with the abort flag. the calling application should release the uart access permission by calling irptrelease() as soon as it is not needed anymore. it is recommended to force system to doze mode after terminated a transmission or a transmission is completed which is illustrated in example 12-3 . note: application swapping is re-enabled after a transmission is completed or aborted. example 12-3 terminating a transmission ..... /* abort send. store the pointer of send buffer and no. of bytes have been..*/ /* .. sent in gpsendbuf and gsendbyte respectively */ uartsendabort(uart_send_abort, &gpsendbuf, &gsendbyte); irptrelease(irpt_uart_flag); /* release interrupt */ setdozeperiod(0); /* go to doze mode */ ..... 12.4 receiving data from the uart status uartreceive (u8 receiveflag ) status uartreaddata (p_u8 data, u16 bufsize, p_u16 sizeread ) refer to figure 12-1 and figure 12-3 for an overview of the data receive architecture. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-18 uart communication support personal portable system manager programmers manual personal portable system manager programmers manual uart communication support 12-15 this marks a failed receive request, and the calling application should determine the recovery actions. the current data reception is aborted after time out happened. ? an application aborts the on-going receive request by calling uartreceive() with the abort flag. the calling application should release the uart access permission as soon as it is not needed anymore. it is recommended to force system to doze mode after terminated a data reception or a reception is completed for power saving. note: application swapping is re-enabled after a receive request is terminated. 12.4.4 setting data reception time out if rts/cts is enabled, after uartreceive() is called, application may receive a time out error depends on whether cts is asserted or not. if cts is negated, application will not receive time out error because the other communication device is off. on the other hand, if cts is asserted, application will receive time out error if no data arrived within the time out period. for the former case, application programmer is prefer to set a timeout by reftimealarmid() after called uartreceive() to avoid deadlocking as shown in example 12-4 . example 12-4 setting initial time out for data reception ..... irptrequest(irpt_uart_flag); /* request interrupt */ uarttimeout(1000); /* set 1 sec time out between two receive interrupts */ uartreceive(uart_receive_request); /* request to receive */ reftimealarmid(&rxalarmid, reftimeread()+2000); /* initiate 2 sec time out */ ..... if(*indata==uart_data_received) { deletetimer(grxalarmid); /* data arrived, delete init time out */ uartreaddata(gpbuf, grcvbufsize, &gsizeread); /* read data */ ..... } 12.5 uart hardware flow control 12.5.1 enabling rts/cts hardware flow control applications can enable rts/cts hardware flow control by calling uartflowctrl(uart_rcts_enable). if hardware flow control is not enabled when calling rts/cts flow control apis, error code ppsm_err_rcts_idle is returned to the application. rts is asserted after enabled rts/cts flow control. 12.5.2 disabling rts/cts hardware flow control applications can disable rts/cts hardware flow control by calling uartflowctrl(uart_rcts_disable). system negates rts pin immediately after disabled hardware flow control. any further changes in rts or cts pin are f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
12-16 uart communication support personal portable system manager programmers manual ignored by the system. rts is asserted after disabled rts/cts flow control. 12.6 data reception with hardware flow control 12.6.1 pause data reception after rts/cts hardware flow control is enabled, ppsm automatically pauses data reception once internal uart buffer (not fifo) is full. data reception is resumed after data is read out by uartreaddata() in application. if the interval of cts remain negated is longer than the time out period, time out error will occur. applications can pause data reception of uart when hardware flow control is enabled. error code ppsm_err_rcts_idle is returned if hardware flow control is not enabled. applications can resume data reception by calling uartrcvctrl(uart_rcts_cont). there will be no receive timeout error occur after pausing the data reception. because the purpose of uarttimeout( ) is mainly for avoiding the system stays in dead loop when transmitting or receiving data. user can set a timeout by calling reftimealarmid( ). the receive timeout is restarted when data reception is resumed by calling uartrcvctrl(uart_rcts_cont). 12.6.2 continue data reception applications can continue data reception which has been paused by uartrcvctrl(uart_rcts_pause) when hardware flow control is enabled. error code ppsm_err_rcts_idle is returned if hardware flow control is not enabled. 12.7 data transmission with hardware flow control 12.7.1 pause data transmission applications can pause data transmission of uart when hardware flow control is enabled. error code ppsm_err_rcts_idle is returned if hardware flow control is not enabled. applications can resume data transmission by calling uartsendctrl(uart_rcts_cont). there will be no transmit timeout error occur after pausing the data transmission. because the purpose of uarttimeout( ) is mainly for avoiding the system stays in dead loop when transmitting or receiving data. user can set a timeout by calling reftimealarmid( ). the transmit timeout is restarted when data transmission is resumed by calling uartsendctrl(uart_rcts_cont). personal portable system manager programmers manual uart communication support 12-17 12.7.2 continue data transmission applications can continue data transmission which has been paused by uartsendctrl(uart_rcts_pause) when hardware flow control is enabled. error code ppsm_err_rcts_idle is returned if hardware flow control is not enabled. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
13-4 task management personal portable system manager programmers manual needs to be swapped in later by advsendmessage() with swap_task_back_later, the current task will be put in the head of the queue while its swapped out. if the current task is parent task and there is no more message to be handled, the system will check whether there is need to swap to next parent task in the queue. if there is no more main task to be swapped in, the system will check from the head of subtask to see whether any subtask needs to be swapped in. the subtask to be swapped in may due to message in the queue or the task swapping flag in the subtask is on. if the current task is subtask and there is no more message to be handled, the system will check whether there is need to swap to the next subtask in the head of subtask queue. if not, system will check for the parent and then rest of the subtask to see whether they need to be swapped in or they have message to handle. if no more message or task to swap in, system will check the head of the main task queue to see whether it needs to be swapped in. task switching can be disabled by calling appswap(false). appswap() is a function to stop task swapping while the system is transferring uart data or any other critical operations. if the appswap(false) is called several times, the same number of times of appswap(true) must be called to let the task switching active again. 13.4 message broadcasting if the application programmer stores the task id, including main and sub tasks, into a global list, message can be broadcasted to this list of task by using advsendmessage() with or without task switching. 13.5 task control if the application programmer stores the task id, including main and sub tasks, into a global list, the task swapping sequence can be controlled by using advsendmessage() with or without message passing. however, those task on the task swapping queue will not be affected. so if a task is already on the task swapping queue, nothing can be used to change it. for those task not being on swapping queue, advsendmessage() can be used to put it into the task swapping queue. the earlier the task is put into the task swapping queue, the higher priority the task will be swapped in. in task swapping, ppsm will check whether there is other main task to swap to before checking the sub tasks of current main task. the system will always check to see whether their are any messages need to be handled within the family and swap to that member task to finish the job. sometimes the message in current task are cleared and swap_task is called immediately to other member of the family. this task may be swapped bad later as the memory for the last message is not free yet. message is still in the task until next irptgetdata() is called. and next task swapping for swap_task_later in that task will be next irptgetdata() after the one freeing last messages memory. personal portable system manager programmers manual task management 13-1 chapter 13 task management each application running on ppsm is considered as a task. there are two types of ppsm tasks: ? main task - application task that is stand alone ? sub-task - task that is spawned off by another task either main or sub task. the task management tools enable applications to: ? create a main task or a sub-task ? start execution of a task ? terminate execution of a task this chapter describes how applications can make use of ppsm tools to generate ppsm tasks. message passing or task swapping are possible among any sub tasks, its parent task and any other main tasks. changing of panning screen in main task will affect the panning screen parameter of its sub tasks. changing of panning screen in sub task will affect the panning screen parameter of its main task and other sub tasks belonging to the same main task. 13.1 main task most applications fall into the main task category. main tasks run independently of each other. there cannot be more than 1 main task running at any given time. they are created by the system tool taskcreate() or advtaskcreate(). once a main task is created, there are three ways it can be started: ? by using the system tool taskstart() ? by pressing the application icon ? by messages sent from another task 13.1.1 system task system task is a special main task which is created in ppsminit(). its never terminated since creation. the stack used in this task comes from the stack defined in spc file so it cannot be freed. the panning screen created in this task can be deleted and replaced by another global panning screen by the following method: example 13-1 sharing system tasks panning screen using global variable /* global variable for sharing panning screen */ u32 gpanscreen; status taskapp() f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
13-2 task management personal portable system manager programmers manual { pan_screen tempscreen ; tempscreen.panaddress = tempscreen.displayscreenaddr = gpanscreen; tempscren.horzsize = 160; tempscreen.vertsize = 240; tempscreen.displayxorigin = tempscreen.displayyorigin = 0; tempscreen.regposr = 0; tempscreen.regpsw = tempscreen.horzsize/pixels; /* where pixels=8 if the lcd is set to 2 bits/pixel and pixels=16 if the lcd is set to 1 bit/pixel. */ /* set the panning screen of current task to the sharing panning screen */ changepanning(tempscreen, 0); while(1) { .... } } main() { u32 taskappid; pan_screen tempscreen; /* ppsm initialization */ ppsminit(false); /* get screen memory */ gpanscreen = (u32)getscreenmem(160, 240); /* assign panning screen parameters */ tempscreen.panaddress = tempscreen.displayscreenaddr = gpanscreen; tempscren.horzsize = 160; tempscreen.vertsize = 240; tempscreen.displayxorigin = tempscreen.displayyorigin = 0; tempscreen.regposr = 0; tempscreen.regpsw = tempscreen.horzsize/pixels; /* where pixels=8 if the lcd /* delete the default system panning screen and assign the new panning screen to system task */ changepanning(tempscreen, 0); /* create a main task without application icon nor panning screen */ advtaskcreate(taskappid, taskapp, 0, 0, 0, 0, 2048, ppsm_screen_noscreen, 0, 0, null); taskstart(taskappid); } 13.2 sub-task sub-task, on the other hand, can be active at the same time as the parent task that generated the sub-task and other sub tasks with same parent task. a main task can create multiple sub-tasks. these sub-tasks are queued in the reverse order they are created initially. however, the order may be changed when any sub task is swapping in or out by using sendmessage() or advsendmessage(). sub-task uses the display resource, hardware cursor and input pad of its parent and can only be created with the system tool subtaskcreate(). sub-tasks are tied to the parent task. if the parent task is swapped out or terminated, the sub-task will be swapped out or terminated too. sub-task inherits the input pad properties from the parent task at creation. there can only be one input pad among the main task and its sub-tasks. personal portable system manager programmers manual task management 13-3 13.2.1 sub-task management when the active area of sub task is touched, that sub task will be swapped in as the current task. the irptgetdata() tool is another task swapping point. if no interrupt message is pending among a main task and its sub-task when irptgetdata() is called, the current main or sub-task remains active. if message is pending in any of the main task or its sub tasks, task swapping will happen in irptgetdata(). if there are multiple sub-tasks, they will be parsed using round-robin method. the most recently swapped out sub-task will be put to the end of the queue. when the system is ready to restart a new sub-task, it always searches from the beginning of the queue. 13.3 task switching when the task is started for the first time, it will execute from the beginning of the task application. when the task needs to be swapped out, ppsm will save the current program counter value. then, when this task is swapped back in, it will resume execution from where it was left off. example 13-2 task switching at arrow 1, taskapp1() is started for the first time. then, at arrow 2, taskapp2() is also started for the first time, so taskapp1() will be swapped out. at arrow 3, taskapp1() is swapped back in and is resumed from where it was left off. if the task is swapped by pen interrupt or advsendmessage() with input parameter being swap_task or swap_task_back_later. if the task is swapped by sendmessage() or advsendmessage() with input parameter being swap_task_later , the current task will not be swapped out immediately. it will be swapped out in irptgetdata() when all messages in current task are handled. if the target task is a subtask in other family, it will swap to the parent of the other family before swapping to the target subtask. all tasks to be swapped in will be in a fifo queue. the current task to be swapped out will be put at the end of the queue. however, if the current task taskapp1() 2 { taskinit(); while(true) { switch(irptgetdata... ...... ...... } taskapp2() { taskinit(); while(true) 3 { switch(irptgetdata... ...... ...... } 1 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
13-8 task management personal portable system manager programmers manual this tool launches a task that has been created by the tool taskcreate() or advtaskcreate(). this routine never terminates. it takes the task identifier as input argument and begins execution of the task. since this tool may prevent the application caller from executing again, it should always be called at the end of main() to start the first task. example 13-4 start a task 59 u32 slidetask; /* task id for slide */ . . . 91 /* slide is the default task to be run when the system starts up */ 92 taskstart(slidetask); 13.11 termination of a task status taskterminate (u32 taskid ) termination of a task. the task identifier can be of a main or sub-task. all system memory associated with the task and its sub-tasks that are allocated by ppsm are freed, such as stack memory and screen, if any. any memory that was explicitly allocated by the task through lmalloc(), lcalloc() or lrealloc(), is not going to be freed by the system because that area may be shared by several tasks. that area can be freed by calling lfree() in application program. a task cannot terminate itself. if it is a sub-task, it cannot terminate its parent task either. 13.12 task reinitialization status taskreinit (u32 taskid, u16 flag ) this tool will set the reinit flag in the specified task. if the flag is true, whenever the task is swapped in, it will start at the beginning of the task function. however, application programmer needs to handle the cleaning up of memory in task swapping using taskhook(). in task swapping, the pc and stack, etc. will be restored to the value when the task is not executed. this function must be called immediately after taskcreate() or advtaskcreate() when the task is created. this function can be called to disable the task reinitialization at anytime but cannot be called to enable the reinitialization again. 13.13 task hook status taskhook (u32 taskid, p_void entrycallback , p_void exitcallback ) this tool will hook the entrycallback() and exitcallback() functions to the specified task. when the task is swapped in, the entrycallback() will be called after updating the registers. when the task is swapped out, the exitcallback() will be called personal portable system manager programmers manual task management 13-5 13.6 task swapping example taskappa() { subtaskcreate(&subtaska1, ...); subtaskcreate(&subtaska2,....); advsendmessage(taskb, 0, swap_task_back_later); ..... while(1) { irptgetdata(...); .... } } taskappb() { subtaskcreate(&subtaskb1,...); subtaskcreate(&subtaskb2, ...); ..... while(1) { irptgetdata(....); ..... } } subtaskappa1() { ..... while(1) { irptgetdata(....); ..... } } subtaskappa2() { ..... advsendmessage(taskb, 0, swap_task); ..... while(1) { irptgetdata(....); ..... } } subtaskappb1() { ..... while(1) { irptgetdata(....); ..... } } subtaskappb2() { ..... advsendmessage(taskb, 0, swap_task_later); advsendmessage(taska1, 0, swap_task_later); advsendmessage(taskb1, 0, swap_task_later); ...... while(1) { irptgetdata(....); ..... } f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
13-6 task management personal portable system manager programmers manual } task swapping sequence is a->b->a->a1->a2->b->b1->b2->b1->b->a->a1 when task a is created, it will create subtask a1 and subtask a2. these 2 subtasks wouldnt be executed until irptgetdata() is called. however, advsendmessage() with swap_task_back_later is called before irptgetdata() so the next task is b. in task b, subtask b1 and subtask b2 are created. in irptgetdata() of task b2, it will swap back to a as the previous command is swap_task_back_later. then subtask a1 and subtask a2 will be executed in sequence. in subtask a2, swap_task to b is executed so next task is b. in irptgetdata() of task b, it will swap to b1 as b1 is not executed yet. then in irptgetdata() of subtask b1, it will swap to subtask b2. in subtask b2, swap_task_later is called for task b, subtask a1 and subtask b1. as the system will check for next subtask first, subtask b1 will be swapped in irptgetdata() of subtask b2. in irptgetdata() of subtask b1, it will swap to b as it will check for the parent after checking the next subtask. then it will swap to task a and then a1 in irptgetdata() of these tasks as advsendmessage() is called for swapping task to a1 in subtask b2. whenever swap_task_later is called for subtask in other family, the parent of the other family will be swapped in first. 13.7 creating a task status taskcreate (p_u32 taskid , p_void procaddr , s16 xsrc , s16 ysrc , s16 xdest , s16 ydest , p_u8 bitmap ) ppsm needs to know the existence of each application task before the task can access ppsm resources. the main body of a ppsm system must call this routine once for each application. ppsm will create the necessary data structure and memory space required to run the application. an application icon is created for each application with the coordinates as supplied in the argument list. the application is put to the foreground whenever this icon is selected. this tool does not start the execution of the application. it registers the task with ppsm only. if the user does not want to have an application icon, the user should set either width or height to be zero( xsrc = xdest or ysrc = ydest ). hence, there is no application icon to be created. by default, a screen is created with the task. ppsm uses the system default physical size as the dimension for this screen. the default physical size is specified in the linker specification file, as described in chapter 34 - linker specification file . a 2k byte of memory is allocated for each task as the tasks stack. 13.8 creating a task with specific task parameters status advtaskcreate (p_u32 taskid, p_void procaddr, s16 xsrc, s16 ysrc, s16 xdest, s16 ydest, s32 stacksize, u16 newscreen, u16 screenwidth, u16 screenheight, p_u8 bitmap ) creation of a new ppsm task. this tool creates a ppsm application task in the personal portable system manager programmers manual task management 13-7 same manner as the existing tool taskcreate(), with the difference that it also allows the caller to specify the launch icon position and size, the stack memory required by the application and the screen memory size, if any is required. two settings for the panning screen variable, newscreen, are available: ? ppsm_screen_noscreen will have no screen. ? ppsm_screen_new will take the arguments screenwidth and screenheight and creates a new screen for the application task. however, if either one of the arguments, screenwidth and screenheight , is zero, the default panning screen size taken from the linker specification file will be used. a default of 512 byte of memory is allocated for the tasks stack if the input argument is negative. example 13-3 create a task 57 main() 58 { 59 u32 slidetask; /* task id for slide */ 60 u32 uartdemotask, timertask; /* task id for uart and reference timer */ . . . 66 /* create the uart application task with a stack size = 2k, 67 * and a panning screen with default width & height is required. 68 */ 69 if (advtaskcreate(&uartdemotask, (p_void) uartdemo, src_x[uart_icon], 70 src_y[uart_icon], dest_x[uart_icon], dest_y[uart_icon], 2048, 71 ppsm_screen_new, 0, 0, 0)) 72 return(ppsm_error); 13.9 creating a sub task status subtaskcreate (p_u32 taskid , p_void procaddr , u16 stacksize , u16 numarg , ...) creating a sub-task. any task can use this tool to create sub-tasks. if the calling task is itself a sub-task, the new sub-task will belong to the calling sub-tasks parent(ie. the calling and the created sub-task will become siblings). if the calling task has already created more than one sub-task, the new sub-task will be added to the head of the sub-task list. there is currently no limit on the number of sub- task a parent task can create. this routine accepts variable length input argument. these arguments are passed into the sub-task by ppsm, meaning that the actual sub-task routine can accept input arguments. subtask will be started when the current task has no more messages to be handled and there is no need to swap to the other task. subtask will be started in the irptgetdata() routine in current task. 13.10 starting a task status taskstart (u32 taskid ) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
14-2 inter-task messaging personal portable system manager programmers manual in the above example, task b will be put on the head of task swapping queue and then task c will be put after task b. so when all messages in task a are handled, system will swap to task b. when all messages in task b are handled, system will swap to task c. note: if uartsend() or uartreceive() is called, no task swapping can be happened in any case until transmission or reception is aborted. it is applied to all task swapping cases discussing in this chapter. 14.1.1 with delayed task swapping in the diagram above, taskapp1() will call sendmessage() to send a message to taskapp2(). however, the active taskapp1() will not be swapped out. it will still be active until it executes irptgetdata() as in arrow 1. then, taskapp2() will be swapped back in as in arrow 2. message from taskapp1() will be received in irptgetdata() of taskapp2() as in arrow 3. the task swapping happens when all messages in taskapp1() are handled. this will happen if sendmessage() or advsendmessage() with swap_task_later are used. the target task will be push into the tail of main task swapping queue if the target task is main task or the tail of sub task swapping queue otherwise. 14.1.2 with immediate task swapping in advsendmessage(), if the flag is swap_task, message passing and task swapping will happen inside advsendmessage() immediately if the pen is not touching the panel. 14.1.3 with immediate task swapping and delayed swap back in advsendmessage(), if the flag is swap_task_back_later, message passing and task swapping will happen immediately inside advsendmessage() if the pen is not touching the panel and the current task will be put into the head of the task swapping queue. so when all messages are handled in target task, the current task will be swapped back. taskapp1() { taskinit(); while(true) { switch(irptgetdata... ...... sendmessage(taskapp2id... ...... } taskapp2() { taskinit(); while(true) { switch(irptgetdata... ...... ...... } 1 2 3 personal portable system manager programmers manual task management 13-9 before storing the registers value. the entrycallback and exitcallback must be an one input parameter function. the input parameter for entrycallback will be the task id. for the task just swapped out and the input parameter for exitcallback will be the task id. for the task swapping in . e.g. status entry(u32 previoustaskid); and status exit(u32 nexttaskid) this function can be called outside or within the task. however, if its called within the task, the entry routine is not executed and so it needs to be called after this function. example 13-5 taskhook() inside task void entryr(u32 oldid) { ...... } void exitr(u32 nextid) { ...... } task1() { task1init(); taskhook(task1id, entryr, exitr); entryr(0); while(1) .... } if taskhook() is called outside its task, the entry routine will be executed automatically once the task is executed. 13.14 stop task swapping void appswap (u16 flag ) if flag is false, no task swapping will be allowed by any means. if sendmessage() or advsendmessage() is called after calling appswap(false), the message will be sent but no task swap later nor task swap immediately will be executed. this function will increment a flag for task swapping, if its called with false several times, the same number of times appswap(true) must be called before task swapping is allowed. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
13-10 task management personal portable system manager programmers manual personal portable system manager programmers manual inter-task messaging 14-1 chapter 14 inter-task messaging ppsm supports asynchronous message passing between tasks using the provided tools. this tool cannot be used to pass message between sub tasks with different parent tasks. the sender task sends out the message stored in the pre-defined message structure using the tool sendmessage() or advsendmessage(). it must know the task identifier of the task that it wants to send the message to. the receiving task receives the sent message in its software interrupt buffer, in the same way as other interrupt messages sent from ppsm system. accessing this message by the application is done by using the irptgetdata() tool. the messaging tool enables applications to: ? notify other applications of user defined events ? pass data between tasks within the system ? swap to the specified task immediately or later the format of the data passed by these tools are not defined. the caller and receiver must have their own mutual agreement on the form of data being sent. ppsm only performs the actual message passing and informing the receiving application task of the arrival of the message. the advsendmessage() can be used to control task swapping sequence with or without message passing. this can be used to send message to the task itself. whenever these functions are called to send message or control task swapping in interrupt routines when the system is in doze mode, it will wake up the system. 14.1 message passing message can be sent between any tasks even the current task itself. sendmessage() will send message to the target task and set the flag to swap to the target task once all messages for current task are handled. advsendmessage() has more flexibility. task swapping can happen without any message sent to the target task using advsendmessage(). advsendmessage() can be used to send message to target task without task swapping which is used as a purely message passing tool. example 14-1 multiple swap task later taska() { ...... sendmessage(taskbid, msg); sendmessage(taskcid, msg); ..... } f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
14-6 inter-task messaging personal portable system manager programmers manual personal portable system manager programmers manual inter-task messaging 14-3 14.1.4 message passing without task swapping in advsendmessage(), if the flag is no_swap_task, it will act as a message passing only and no task swapping activity will happen. 14.2 message structure a pre-defined structure is used to store and forward messages from the sender. typedef struct _message { u16 messagetype; /* message type */ u16 message; /* message */ u32 misc; /* short data (32bit) */ p_void data; /* associated data, if any */ u16 size; /* size of data in bytes */ u16 reserved; /* for future (broadcast, etc.) */ } ppsm_message, *p_message; 14.3 sending message status sendmessage (u32 taskid , p_message msg ) this tool sends a message to a known task. if the receiver tasks task identifier is table 12-1 message structure name description messagetype the type of message being sent. currently only one type of message is defined for application usage. this is message_irpt. application must set this field to message_irpt, otherwise, the message will not be sent. message the interrupt message. this is passed directly to the receiving application as the return value when the irptgetdata() tool is called. default value should be set to irpt_user, as a user-defined interrupt type. application developers can set their own 16- bit value. see section 14.7 - receiving message for details. misc unformatted 32-bit value. this is passed directly to the sdata field of the irptgetdata() tool. data pointer to any data that might be passing from the sender to the receiver. the data type and format is user defined. ppsm does not put any protocol into this data format. size size of the data in the data pointer list. this is in number of bytes. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
14-4 inter-task messaging personal portable system manager programmers manual not known, this tool cannot be used. all data that the sender wants to send must be stored in the form of message structure. no protocol or data format is put on the message data. the sender and receiver must have a mutual understanding of the representation of the data being transferred. 14.4 advanced sending message status advsendmessage (u32 taskid , p_message msg, u8 flag ) this is similar to sendmessage() except it enhances the task swapping control. the flag can control whether the target task is swapped in immediately or later. it also controls whether the current task will be swapped in again after all messages in target task are handled. if msg is null, this is a task swapping control function without message passing. if flag is no_task_swap, this is a message passing tool without task swapping control. 14.5 deleting message for current task status messagedelete (u16 type ) this is for deleting all messages in current task with the same type as the input parameter such as irpt_pen, irpt_uart, etc. 14.6 deleting message for any task status advmessagedelete (u32 taskid , u16 type , u32 shortdata ) this is for deleting messages in specific task matching the type and shortdata . the short data here refers to the area id. for active area, timeout id. for reference timer, etc. if taskid is 0xffffffff and the current task is a main task, all messages in main task queue with matching type and shortdata will be deleted. if the taskid is 0xffffffff and the current task is a subtask, all messages with matching type and shortdata in current sub task list will be deleted. if the type is 0xffff, all messages with matching taskid and shortdata will be deleted. if type is 0xffff and shortdata is 0xffffffff, all messages in the specific task will be deleted. 14.7 receiving message status irptgetdata (p_u32 sdata , p_u32 *data , p_u32 size ) this tool is used to receive the messages sent by another task, as well as to receive the standard software interrupt message (see section 29.1 - irptgetdata ). personal portable system manager programmers manual inter-task messaging 14-5 the arguments returned by this tool can be mapped directly to the data stored in the message structure sent by the sendmessage() tool. they are as follows: example 14-2 receive messages 73 status uartdemo() 74 { 75 p_u16 indata; 76 u8 selected; 77 u32 size, id; . . . 134 while (1) 135 { 136 switch (irptgetdata( (p_u32)&id, (p_u32*)&indata, (p_u32)&size)) 137 { 138 case irpt_uart: 139 switch (*indata) 140 { 141 case uart_data_received: 142 143 /* data has been received, read data from system */ irptgetdata data type data field in message structure data type return value status message u16 sdata p_u32 misc u32 data p_u32* data p_void size p_u32 size u16 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
15-4 interrupt handling personal portable system manager programmers manual 15.1.5 irpt_key ppsm provides a soft keyboard as part of the character input tool. once activated, a keyboard is displayed on the display area. pressing any one of the keys on the soft keyboard will result in a irpt_key message generated by ppsm to the application. the message will also include the ascii code of the key that was pressed. the ascii code returned is of type text, i.e. 2-byte format with zero extended in high byte and the coordinate of pen touch on the key. ppsm_icon_touch and ppsm_input_touch ppsm_icon_pen_up and ppsm_input_pen_up ppsm_icon_drag and ppsm_input_drag ppsm_icon_drag_up and ppsm_input_drag_up figure 15-2 icon and input area pen status messages personal portable system manager programmers manual interrupt handling 15-1 chapter 15 interrupt handling ppsm maintains a set of interrupt handlers internally to handle external and internal hardware events. ppsm application programmers do not need to be aware of the characteristics of hardware such as pen device, timer, uart and real time clock. the kernel intercepts all interrupts and data generated from the event and send them to the application in a pre-defined format. ppsm maintains a unique software interrupt buffer for each application. when a hardware interrupt occurs, the event and data generated from the interrupt are stored into this software interrupt buffer. this buffer is the interface between ppsm and the application, making sure that data and interrupt will not be missed if the application is slow in response to an interrupt. hence de-coupling the real- time interrupt of the peripheral devices from the application. ppsm has two distinct types of interrupts: ? system interrupt ? user defined interrupt 15.1 system interrupts these are interrupts that are automatically handled by ppsm system. application developers can make use of the services provided by ppsm to manage the hardware resources such as the touch panel, timer, uart, rtc and screen. table 15-1 shows the list of interrupt identifiers that are generated by the system hardware interrupt ppsm interrupt handlers interrupt buffer 1 interrupt buffer n app 1 app n figure 15-1 ppsm interrupt message handling f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
15-2 interrupt handling personal portable system manager programmers manual to the application. 15.1.1 irpt_audio it is a message generated from audio tools. an audio stops after it has finished or the user has called audiostoptone() or audiostopwave(). after audio playing stops, this interrupt is sent to the task that called audioplaytone() or audioplaywave() to indicate that the audio playing is finished. 15.1.2 irpt_pen it is a message generated from a pen active area. when the application defines an active area as pen area on the display, this message is sent to the application when pen input sequence occurs over this active area. the message returns the coordinates of the pen input points. the data message returned by irpt_pen consists of a list of 16-bit words. each pair of 16-bit words in the list represents the x and y coordinate of a pen input point on the touch panel. there will always be at least 1 pair of coordinate. a pair of (-1,-1) signals the end of the list. 15.1.3 irpt_input_status this message is sent to the application to report the pen action status at the beginning and the end of each pen action within a valid pen active area. for example, when an active area created for pen input is touched, this message, table 15-1 system interrupt identifiers interrupt identifier interrupt source data from handler irpt_audio ppsm audio tools, indicating audio stopped n/a irpt_hwr handwriting recognition data from handwriting recognition engine irpt_icon icon input icon active area identifier and status irpt_input_status pen input with pen status pen status information irpt_key soft keyboard input keycode, coordinate of pen touch irpt_none no interrupt n/a irpt_pen pen input pointer to (x,y) list irpt_rtc system clock alarm n/a irpt_timer timer timeout and alarm n/a irpt_uart uart data transfer data transmission status irpt_user user user defined personal portable system manager programmers manual interrupt handling 15-3 together with the pen status, is sent to the application before any of the pen (x, y) coordinates are sent; then, when the pen stroke is finished and the pen leaves the touch panel, this message is again sent to the application after the last (x, y) coordinate to report the pen-up condition. this status allows the application to be aware of the pen action sequence, whether it has been dragged in from another area, or it is a pen down, etc. table 15-2 shows the messages types that are returned. figure 15-2 shows the pen actions that would generate these pen messages. 15.1.4 irpt_icon icon area is for the purpose of selection only. it does not yield any coordinate data from the pen interrupt handler. when an icon active area is touched, ppsm sends a soft interrupt with its i dentifier to the applications interrupt buffer. two soft interrupts will be generated from each action: one interrupt for pen-down or pen drag in, and one interrupt for pen-up or pen drag up. this type of area is designed for buttons, and selection icons. table 15-3 shows the messages types that are returned. table 15-2 messages generated for irpt_input_status message description ppsm_input_touch a pen down condition ppsm_input_drag pen is dragged in from another area ppsm_input_pen_up pen has left the touch panel ppsm_input_drag_up pen is dragged out of the current pen area into another area table 15-3 messages generated for irpt_icon message description ppsm_icon_touch an icon pen down condition ppsm_icon_drag pen is dragged in from another area ppsm_icon_pen_up pen has left the touch panel ppsm_icon_drag_up pen is dragged out of the current pen area into another area f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
15-8 interrupt handling personal portable system manager programmers manual the irpt_user is intended for internal software interrupt use. for example, user defined interrupt messages to inform caller of particular event. users can specify their own meanings to this message. example 15-1 request an interrupt handler 203 /* request usage of uart */ 204 if ( irptrequest(irpt_uart_flag) != irpt_uart_flag ) 205 return (ppsm_error); . . . 216 /* release the handler after use */ 217 irptrelease(irpt_uart_flag); 15.3 message handling status irptsenddata (u16 irpttype, u32 sdata, p_u32 data, u32 size ) status irptgetdata (p_u32 sdata , p_u32 *data , p_u32 size ) user can send messages, with or without extra data information, to the application using irptsenddata(). this tool can only be used within a user installed handler. when an application requested and has been granted access to a user installed handler, any messages sent by irptsenddata() from that handler will always be directed to that application, until the application has released the handler. irptsenddata() appends the message from the handler at the end of the applications software interrupt buffer. the receiving application retrieves the message via the system tool irptgetdata(), in the same manner as other system messages. spi slave irpt_spis_flag(dragonball only) irq1 irpt_irq1_flag irq2 irpt_irq2_flag irq3 irpt_irq3_flag irq6 irpt_irq6_flag int0 - int7 irpt_int_flag watchdog irpt_wdog_flag pwm irpt_pwm_flag uart irpt_uart_flag user defined irpt_user_flag table 15-6 interrupt handler flags interrupt handler interrupt flag personal portable system manager programmers manual interrupt handling 15-5 15.1.6 irpt_rtc this is the clock alarm. when an application sets an alarm for a specific time, this message will be generated by ppsm to the application when the time is reached. no data is included in this message. 15.1.7 irpt_timer time-out message. this message is sent to the application when a specified time- out period is reached. no data is included in this message. 15.1.8 irpt_hwr ppsm provides an input method for handwriting character input (refer to chapter 5 - character input methods ). if a handwriting recognition engine is used, the resultant characters generated by it are passed on to the application using this message. the data passed to the application is a list of language codes of the character candidates and the size of this list in number of bytes. 15.1.9 irpt_uart when an application is granted permission to use the uart (see chapter 12 - uart communication support ), this message is generated to the application to report uart data transmission status. a 16-bit message data is also sent to the application with this message. it can have one of the following values: 15.2 device interrupts ppsm supports another set of interrupt identifiers and handlers for hardware table 15-4 messages generated for irpt_uart message description uart_data_sent data sent request has been completed uart_data_received data has been received from the uart uart_error an uart error condition has occurred. ? uart_error an additional 16-bit word follows that identifies the error condition: ? uart_err_tmout ? uart_err_frame ? uart_err_parity ? uart_err_overrun ? uart_err_nodata f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
15-6 interrupt handling personal portable system manager programmers manual devices. the list of device interrupt identifiers are list in table 15-5 . 15.2.1 user defined interrupt handlers for each of the external interrupts not used by ppsm system, user can install their own handler. the generic, or stub, handler source is provided in the ppsm device library. these are: ?spi master ? spi slave(dragonball only) ?irq6 ?irq3 ?irq2 ?irq1 ?int0 - int7 ?watch dog ?pwm ?uart each of the stub handler is associated with an external interrupt. for example, _irq6irpthandler is associated with the irq6 external interrupt. when the external interrupt event occurs, ppsm automatically calls up the associated handler as part of the interrupt handling procedure. for system that uses any of the external interrupts, they can supply their own handler such that integration into ppsm is possible. for ppsm source licensee, if _uartirpthandler() needs to be used, "- dno_uart_handler" needs to be included in the compiler option to indicate that the internal ppsm uart interrupt handler need not be used. table 15-5 interrupt identifiers and user defined handlers interrupt source interrupt identifier ppsm user defined handler spi master irpt_spim _spimirpthandler spi slave irpt_spis _spisirpthandler(dragonball only) irq1 irpt_irq1 _irq1irpthandler irq2 irpt_irq2 _irq2irpthandler irq3 irpt_irq3 _irq3irpthandler irq6 irpt_irq6 _irq6irpthandler int0 - int7 irpt_int _intirpthandler watchdog irpt_wdog _watchdogirpthandler pwm irpt_pwm _pwmirpthandler uart irpt_uart _uartirpthandler user defined irpt_user none personal portable system manager programmers manual interrupt handling 15-7 15.2.2 device interrupt identifiers the device interrupt identifiers listed in table 15-5 can be used by the interrupt handlers to send soft interrupt messages from the handler to the application, much like the system pen and timer interrupt identifiers. ppsm provides a tool, irptsenddata(), to allow messages be sent from the user installed interrupt handlers to the application. for example, user installed irq6 handlers can use irptsenddata() to send a message to the application from the irq6 handler to inform the application of the event, or to pass data from the hardware layer to the application layer. 15.2.3 application access to handlers by isolating the interrupt handler from the application, multiple applications can have access to the same hardware resource. however, an interrupt handler can only be registered with a single application at any one time. if more than one application is requesting the services of a single handler, it will be granted to the first application making the request. the other applications cannot access the handler until it is released by the first application. to control access conflict between multiple application tasks accessing the same hardware concurrently, a set of interrupt tools are defined. ? irptrequest() requests for an interrupt handler ? irptrelease() releases an interrupt handler 15.2.4 request and release interrupt handler service u32 irptrequest (u32 handlerflag ) status irptrelease (u32 handlerflag ) when an application task needs the resource of a particular hardware peripheral, it must first request for service with the interrupt handler. once the task successfully registers with the handler, all messages received from that peripheral are directed to the registered task until the task releases the service of the handler. one application task can request and register with any number of interrupt handlers in the system, but each of the handlers in the system can only be attached to one single application task. because of this, applications tasks must release the handler after use in order for the peripherals to be fully utilized. to request or release a handler, the flags in the table 15-6 below are used in all the interrupt tools to specify which of the handlers to use. these flags are bit values representing individual interrupt handlers. table 15-6 interrupt handler flags interrupt handler interrupt flag spi master irpt_spim_flag f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
16-2 using system tools personal portable system manager programmers manual 16.1.1 motorola logo depending on the physical lcd size, an appropriate motorola logo is displayed on the lcd display during pen calibration stage. for lcd display that is larger than 280 pixels wide by 150 pixels high, the standard logo will be displayed. this logo is 256 pixels wide by 97 pixels high, figure 16-2 . for lcd display that is larger than 150 pixels wide by 80 pixels high, but smaller than 280 pixels by 150 pixels, a smaller motorola logo will be used. this smaller motorola logo will be 104 pixels by 25 pixels, figure 16-3 . for lcd display that is smaller than 150 pixels wide by 80 pixels high, no motorola logo will be drawn. figure 16-2 standard motorola logo personal portable system manager software licensed ? 1995-1999 motorola inc. by motorola semiconductor h.k. ltd. figure 16-3 small motorola logo personal portable system manager programmers manual interrupt handling 15-9 15.3.1 example assuming that an application has already given access to an irq6 handler by ppsm, when the user defined irq6 handler calls irptsenddata(), the data are sent to the application immediately. shortmessage = command_event; messagesize = 4; messagedata = pindata; irptsenddata( irpt_irq6, shortmessage, &messagedata, messagesize); the application retrieve the message via the irptgetdata() call. switch (irptgetdata( &event, &indata, &insize)) . . . case irpt_irq6: /* irq6 event has occurred */ if (event == command_event) . . . default; in the above example, the following data are passed from the irq6 handler to the application: table 15-7 data passed from handler to application irptsenddata irptgetdata argument data argument data irpttype irpt_irq6 return value irpt_irq6 sdata shortmessage sdata event data messagedata data indata size messagesize size insize f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
15-10 interrupt handling personal portable system manager programmers manual personal portable system manager programmers manual using system tools 16-1 chapter 16 using system tools ppsm provides additional tools for applications to access and control system resources. 16.1 ppsm initialization status ppsminit (u16 calibration ) ppsm needs to be initialized. ppsminit() must first be called before any of the ppsm tools can be called. it performs all the system initialization, hardware devices initialization and performs calibration for the pen input panel and the lcd display. a device driver (peninit.c) function calibratepen( u16 logoflag) is called to set the touch panel origin and touch panel maximum value if ppsminit(true) is called. this function should call pensetinputorg(x, y) and pensetinputmax(x, y). the coordinate of origin is the top left corner of the touch panel in terms of display screen coordinate. the coordinate of maximum is the bottom right corner of the touch panel in terms of display screen coordinate. the default touch panel calculation value is based on a touch panel that has 320 pixels by 240 pixels (physical sizes 12 cm by 9 cm), using a 10-bit a/d convertor. an offset of 100 (in a/d output unit) is chosen as the a/d non-linear area around the edge of the touch panel. the caller of calibratepen() can specify if logo display is required or not. if the logoflag is false, no logo is displayed. by default, a motorola logo and two cross-hairs (one at top right corner and the other at bottom left corner) are displayed on the lcd screen for calibration. the user must press these two cross- hairs, in no particular order, before ppsm will continue execution. example 16-1 initialize ppsm 62 /* initialize ppsm with pen calibration */ 63 ppsminit(true); lcd screen (160 x 240) touch panel org - (-10, -10) max - (169, 249) figure 16-1 example of calibarting a system f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
17-154 audio tools personal portable system manager programmers manual /* display message to indicate the audio has stopped */ .... break; case irpt_icon: /* click icon to stop the wave playing */ rv = audiostopwave(); .... break; } personal portable system manager programmers manual audio tools 17-151 chapter 17 audio tools 17.1 audio playing ppsm supports two types of audio, wave playing and tone playing. due to the hardware limitation, the wave playing is only available for dragonball-ez. the audio tools have the following properties. ? only one wave file or tone can be played during a given moment. ? a wave file or tone cannot be played if the pwm(pulse width modulation) module is in used by another task or application ? an interrupt "irpt_audio" message will be sent to the task that called audioplaytone() or audioplaywave() to indicate the audio playing has finished. 17.2 tone playing status audioplaytone (p_u16 tonedata, u32 tonesize, u16 toneduration, u8 autorepeat) ppsm supports tone playing for both dragonball and dragonball-ez through the pwm module. tone playing can play a melody with user specified fixed duration and changeable frequencies throughout that duration. for better frequency resolution, the tone frequency is limited between 31hz and 4048hz. name description tonedata the pointer to the tone sequence, with frequencies between 31hz and 4048hz. tonesize total number of tone frequencies to be played. toneduration the duration of each tone frequency for dragonball-ez ? tone_dur_512hz ? tone_dur_256hz ? tone_dur_128hz ? tone_dur_64hz ? tone_dur_32hz ? tone_dur_16hz ? tone_dur_8hz ? tone_dur_4hz for dragonball 0 to 1000, length of duration in number of milliseconds. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
17-152 audio tools personal portable system manager programmers manual example 16-1 ppsm tone playing /* 100hz, 1000hz, 500hz and 600hz */ u16 tonedata[] = {100, 1000, 500, 600}; /* play a melody with 4 different tone frequencies, each with 250ms duration */ #ifdef ez328 audioplaytone((p_u16)tonedata, 4, tone_dur_4hz, 1); #else audioplaytone((p_u16)tonedata, 4, 250, 1); #endif to stop the tone playing, a user can call audiostoptone(). to check if the audio tools are currently being used, a user can call audioinuse(). note: this is impossible to play a tone with value of frequency less than the value of duration, since the duration of this frequency is longer than the allowed duration. 17.3 wave playing (dragonball-ez only) ppsm audio tools can play back a pcm(pulse code modulation) audio wave file that can be generated by many audio programs. wave playing can be done by two ppsm audio tools - advaudioplaywave() and audioplaywave(). advaudioplaywave() is provided for users with solid knowledge of pwm who want to have advanced configuration details over the dragonball-ez pwm module. for most cases, audioplaywave should be used. status audioplaywave (p_u8 wavedata, u32 wavesize, u8 samplingrate) example 16-2 ppsm wave playing /* some pwm wave data */ u16 wavedata[] = {...}; autorepeat to indicate if auto-repeat is needed or not 0 - no autorepeat. 1 - autorepeat. name description wavedata the pointer to the pcm audio wave signal wavesize total number of data bytes occupied by the audio signal samplingrate the requested sampling rate ? sampling_32khz ? sampling_16khz ? sampling_11khz ? sampling_8khz ? sampling_4khz name description personal portable system manager programmers manual audio tools 17-153 /* play a melody with 1000 data bytes at 16khz sampling/reconstruction rate */ audioplaywave((p_u8)wavedata, 1000, sampling_16khz); status advaudioplaywave (p_u8 wavedata, u32 wavesize, u8 prescaler, u8 repeat, u8 clksel) the sampling rate can be calculated by the above input parameters. for more detail information, please refer to the dragonball-ez users manual. example 16-3 ppsm wave playing /* some pwm wave data */ u16 wavedata[] = {...}; /* play a melody with 1000 data bytes at 16khz sampling/reconstruction rate */ /* 16khz = 16.58mz/(2 x 1 x 2 x 256) */ advaudioplaywave((p_u8)wavedata, 1000, 0, 2, 0); the device driver function _pwmirpthandler() under irptdev.c should return true for proper wave playing with ppsm audio tools. if the user is going to use his/her own pwm interrupt function and wants to disable ppsm audio wave playing tools, the _pwmirpthandler() should return false instead. 17.4 stop the audio playing an audio stops after it has finished or the user has called audiostoptone() or audiostopwave(). after audio playing stops, an interrupt is sent to the task that called audioplaytone() or audioplaywave() to indicate that the audio playing is finished. example 16-4 stopping an audio play /* some pwm wave data */ u16 wavedata[] = {...}; /* play a melody with 1000 data bytes at 16khz sampling/reconstruction rate */ audioplaywave((p_u8)wavedata, 1000, sampling_16khz); switch( irptgetdata((p_u32)&id, (p_u32*) &indata, (p_u32) &size) ) { case irpt_audio: name description wavedata the pointer to the pcm audio wave signal wavesize total number of byte of the audio signal prescaler (see dragonball-ez users manual) bit 14~8 of the pwm control register, value from 0 to 127 repeat(see dragonball-ez users manual) bit 2,3 of the pwm control register, value from 0 to 3 clksel(see dragonball-ez users manual) bit 0,1 of the pwm control register, value from 0 to 3 samplingrate 16.58 mhz () prescalar 1 + () clksel () repeat () 256 () = f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
18-2 pen input tools personal portable system manager programmers manual parameter return value 18.3 activearearead syntax name description areaid returns an active area identifier. this identifier is used by the ppsm to refer to the active area until it is removed from the list. code type of active area. it takes either one of the following two value: ? icon_area area for icon ? input_area area for pen input mode this argument is valid only if input_area is selected. it can take one of the following modes: ? stroke_mode one interrupt per input stroke ? continuous_mode one interrupt per sampled points ? confined_mode same as stroke_mode but pen confined within active area xsrc top left x-coordinate of the active area ysrc top left y-coordinate of the active area xdest bottom right x-coordinate of the active area ydest bottom right y-coordinate of the active area name description ppsm_ok successful operation ppsm_err_area_id invalid active area identifier pointer ppsm_err_area_code invalid area code ppsm_err_coordinate invalid coordinates ppsm_err_no_memory not enough memory personal portable system manager programmers manual part iii api toolset f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
personal portable system manager programmers manual personal portable system manager programmers manual pen input tools 18-1 chapter 18 pen input tools 18.1 activeareadisable syntax status activeareadisable (u32 areaid ) description removes an active area entry from the active scan list. the identifier areaid specifies the entry that is to be deleted. this identifier must be a valid identifier obtained from the activeareaenable(). this shall be called within the task that creates the active area. parameter return value 18.2 activeareaenable syntax status activeareaenable (p _u32 areaid , u32 code , u32 mode , s16 xsrc , s16 ysrc , s16 xdest , s16 ydest ) description creates and enables an active area onto the applications list of active input area. an active area is defined as a rectangular region of the display panel where a software interrupt message will be sent to the application that created the area when the region is pressed. for the type of messages that are returned to the application, see the tool irptgetdata(). active areas can be created on or off the lcd display area but must be within the boundary of the touch panel. the properties of the areas on and off the display area are the same except for those areas that are outside the lcd display area, echoing is not allowed. name description areaid identifier of the active area to be removed from the active area list name description ppsm_ok successful operation ppsm_err_area_id invalid active area identifier f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
18-6 pen input tools personal portable system manager programmers manual 18.8 areaechodisable syntax status areaechodisable (u32 areaid ) description disables active area pixel echoing mode. once disabled, all pen-input device selected pixels will not be echoed back on the lcd display. echoing is disabled for all active input area by default. parameter return value 18.9 areaechoenable syntax status areaechoenable (u32 areaid ) description enables active area pixel echoing mode. once enabled, all pen-input device selected pixels will be echoed back on the lcd display. echoing is disabled for all active input area by default. parameter return value name description areaid active area identifier name description ppsm_ok successful operation ppsm_err_area_id invalid active area identifier name description areaid active area identifier name description ppsm_ok successful operation ppsm_err_area_id invalid active area identifier personal portable system manager programmers manual pen input tools 18-3 status activearearead (u32 areaid , p_s16 xsrc , p_s16 ysrc , p_s16 xdest , p_s16 ydest ) description reads the area coordinates of an active area entry in the active scan list. the identifier areaid specifies the entry that is to be read. parameter return value 18.4 activeareasuspend syntax status activeareasuspend (u32 areaid , u32 flag) description suspend or re-enable an active area that has already been created. when an active area is suspended, it will no longer response to pen-input interrupt but it will remain in the active list. when an active area is re-enabled, it will once again respond to pen-input. parameter name description areaid active area identifier xsrc returns the top left x-coordinate of the active area ysrc returns the top left y-coordinate of the active area xdest returns the bottom right x-coordinate of the active area ydest returns the bottom right y-coordinate of the active area name description ppsm_ok successful operation ppsm_err_area_id invalid active area identifier name description areaid active area identifier, must be a valid identifier returned by ppsm. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
18-4 pen input tools personal portable system manager programmers manual return value 18.5 activeareatofront syntax status activeareatofront (u32 areaid ) description given the active area identifier, this tool will extract the element from the active area linked list and insert the element at the front of the list. once the element is at the front of the list, it becomes the active area to receive pen input if other active areas that are overlapping the same physical area. parameter return value 18.6 activelistpop syntax status activelistpop (void) flag flag to indicate whether to suspend or re- enable the active area: ? area_suspend suspend the active area ? area_reenable re-enable the active area name description ppsm_ok successful operation ppsm_err_area_id invalid active area identifier name description areaid active area identifier. must be a valid identifier returned by ppsm name description ppsm_ok successful operation ppsm_err_area_id invalid active area identifier name description personal portable system manager programmers manual pen input tools 18-5 description pops the top background active list of the current task from the active area stack. the active list that is currently being used is destroyed, replaced by the top background active list. parameter return value 18.7 activelistpush syntax status activelistpush (void) description pushes the current active area list of the current task into background and creates a new empty active area list. once in the background, scanning on these areas is disabled. any new active areas registering to ppsm will belong to the new active list. the number of active lists in the background is restricted to 8 levels. they are stored internally in an active area stack. parameter return value name description none name description ppsm_ok successful operation ppsm_error active list stack empty name description none name description ppsm_ok successful operation ppsm_err_active_push unable to push active list f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
18-10 pen input tools personal portable system manager programmers manual return value 18.14 iconscanon syntax void iconscanon (void) description switches on system application icon scanning for the current task. this is on by default. parameter return value 18.15 pencalibration syntax status pencalibration (u16 logoflag) description this function performs pen calibration routine. it calls calibratepen()(in peninit.c of the device driver library) to calibrate the touch panel. user may use different calibration method by changing calibratepen() in peninit.c. the default driver will clear the screen and wait for pen data until 2 valid points for pen calibration are captured. parameter name description none name description none name description none name description logoflag true - put a motorola logo on screen false - no motorola logo will be put. personal portable system manager programmers manual pen input tools 18-7 18.10 activeareaposition syntax status activeareaposition (u32 areaid , s16 xsrc , s16 ysrc , s16 xdest , s16 ydest ) description this function will change the position and the size of the active area specified by areaid . parameter return value 18.11 ctrlicondisable syntax status ctrlicondisable (u32 iconid ) description removes a predefined icon area from an application. the argument iconid must be a valid active area identifier supplied by ppsm. name description areaid existing valid active area id. xsrc top left corner x coordinate ysrc top left corner y coordinate xdest bottom right x coordinate ydest bottom right y coordinate name description ppsm_ok successful operation ppsm_err_area_id error if area id is invalid ppsm_err_coordinate error if any point is outside touch panel or the active area lies in the boundary between lcd area and touch panel only area. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
18-8 pen input tools personal portable system manager programmers manual parameter return value 18.12 ctrliconenable syntax status ctrliconenable (p_u32 iconid , s16 xsrc, s16 ysrc, u16 icontype ) description adds a predefined icon area to an application. the icon area can be placed anywhere on the applications display area. the argument ( xsrc , ysrc ) specifies the position of the icons top left corner. an area identifier is returned to the caller. parameter name description iconid the identifier of the predefined icon area to be removed name description ppsm_ok successful operation ppsm_err_area_id invalid active area identifier name description iconid returns an area identifier. this identifier is used by the ppsm to refer to the predefined icon area until it is removed from the list. xsrc x coordinate for the predefined icons top left corner ysrc y coordinate for the predefined icons top left corner personal portable system manager programmers manual pen input tools 18-9 return value 18.13 iconscanoff syntax void iconscanoff (void) description switches off system application icon scanning of all icon active areas of the current task. parameter icontype the type of predefined icon to use. it can be any of the followings: ? ppsm_icon_8_up 8x8 up icon ? ppsm_icon_8_down 8x8 down icon ? ppsm_icon_8_left 8x8 left icon ? ppsm_icon_8_right 8x8 right icon ? ppsm_icon_8_done 8x16 done icon ? ppsm_icon_16_up 16x16 up icon ? ppsm_icon_16_down 16x16 down icon ? ppsm_icon_16_left 16x16 left icon ? ppsm_icon_16_right 16x16 right icon ? ppsm_icon_16_done 16x32 done icon name description ppsm_ok successful operation ppsm_err_icon_type invalid predefined icon type ppsm_err_coordinate invalid coordinates ppsm_err_area_id invalid active area identifier pointer name description none name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
18-14 pen input tools personal portable system manager programmers manual for mc68ez328 only return value 18.21 scanningoff syntax void scanningoff (void) description switches off touch panel scanning for the current application. all application active areas will not response to pen-input interrupt. parameter return value 18.22 scanningon syntax void scanningon (void) sampling period pen sampling rate samplingperiod>= 250 250>samplingperiod>=125 125>samplingperiod>= 62 62>samplingperiod>= 31 31>samplingperiod>= 15 15>samplingperiod>= 7 7>samplingperiod>= 3 3>samplingperiod>= 1 4hz 8hz 16hz 32hz 64hz 128hz 256hz 512hz name description ppsm_ok successful operation ppsm_err_pen_rate invalid sampling period specified name description none name description none personal portable system manager programmers manual pen input tools 18-11 return value 18.16 penechoparam syntax status penechoparam (u16 echocol, u16 echowidth ) description this tool allows the application to set the color and the drawing width for system pen echoing. parameter return value 18.17 pengetinput syntax status pengetinput (p_s16 xpos , p_s16 ypos ) description name description ppsm_ok successful operation name description echocol pen echo color. for 1bit/pixel graphics, can be: ?white ?black. for 2bit/pixel graphics, can be: ?white ? light_grey ? dark_grey ?black echowidth pen echo width in number of pixels name description ppsm_ok successful operation ppsm_err_colour invalid pen color ppsm_error unsuccessful operation f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
18-12 pen input tools personal portable system manager programmers manual returns a single pair of x and y coordinates of the pen-touch panel contact point. a set of -1 will be returned from this module if the pen is out of the touch panel range, i.e. pen up. parameter return value 18.18 pensetinputmax syntax status pensetinputmax( s16 x, s16 y) description it allows the user to define the bottom-right corner of the touch panel coordinate in terms of screen display coordinate. it is usually called when the system is doing calibration/re-calibration and should only be called by calibratepen( u16 logoflag) at the device driver level. parameter return value name description xpos returns the x position of pen input point ypos returns the y position of pen input point name description ppsm_ok successful operation name description x x-coordinate of the bottom-right corner of the touch panel coordinate in turn of screen display coordinate. y y-coordinate of the bottom-right corner of the touch panel coordinate in turn of screen display coordinate. name description ppsm_ok successful operation personal portable system manager programmers manual pen input tools 18-13 18.19 pensetinputorg syntax status pensetinputorg ( s16 x, s16 y) description it allows the user to define the top-left corner of the touch panel coordinate in terms of screen display coordinate. it is usually called when the system is doing calibration/re-calibration and should only be called by calibratepen( u16 logoflag) at the device driver level. parameter return value 18.20 pensetrate syntax status pensetrate (u16 samplingperiod ) description to allow user to define the period for pen sampling dynamically. the sampling period set in an task does not affect other tasks sampling period. it only takes effect after at least one active area has been created under the calling task. parameter name description x x-coordinate of the top-left corner of the touch panel coordinate in turn of screen display coordinate. y y-coordinate of the top-left corner of the touch panel coordinate in turn of screen display coordinate. name description ppsm_ok successful operation name description samplingperiod sampling period in milliseconds. this is the time between a/d sampling of the pen input coordinates. it has a range of 1 to 1000 milliseconds (e.g. samplingperiod of 25milliseconds translates to 40 samples/ sec) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
19-2 character input tools personal portable system manager programmers manual return value 19.2 advopensoftkey syntax status advopensoftkey ( u16 xpos, u16 ypos, u16 keywidth, u16 keyheight, u16 numcol, u16 numrow, p_u16 keymap, p_u8 bitmap) description opens a soft keyboard module in a similar manner as the tool opensoftkey() but with advanced configuration details. it allows the caller to specify: ? location of the soft keyboard timeout length of time to wait between a written stroke and recognition start in number of milliseconds with range of 0 to 1000. if it is zero, time-out is disabled. so, recognition will only start after writing a stroke in another input box. samplingtime it is the time between two pen samples. it has range of 0 to 1000 milliseconds areaclean cleans after each character input or not 0 - do not clean 1 - clean stacksize the stack size of input pad subtask name description ppsm_ok successful operation ppsm_err_input_pad_opened input pad is already opened - by the same task or its sibling sub-task or its parent task. ppsm_err_input_pad_width invalid width ppsm_err_input_pad_height invalid height ppsm_err_input_pad_x_pos invalid x-coordinate ppsm_err_input_pad_y_pos invalid y-coordinate ppsm_err_pen_rate invalid pen sampling time ppsm_err_pan_init panning screen has not been initialized ppsm_err_no_memory not enough memory ppsm_err_tmout_value invalid time out value name description personal portable system manager programmers manual pen input tools 18-15 description switches on touch panel scanning for the current application. this will enable all application active area scanning of the current task. parameter return value name description none name description none f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
18-16 pen input tools personal portable system manager programmers manual personal portable system manager programmers manual character input tools 19-1 chapter 19 character input tools 19.1 advopeninputpad syntax status advopeninputpad (u16 xpos, u16 ypos, u16 numrow, u16 numcol, u16 areawidth, u16 areaheight, u16 echocol, u16 echowidth, u32 timeout, u16 samplingtime, u8 areaclean, u16 stacksize) description opens the input pad for handwritten character input(similar to the tool openinputpad() but with advanced configuration details). it allows the caller to specify: ? position of the input pad ? number of rows and columns of input boxes ? the width and the height of the input boxes ? the echo ink colour and dot width ? the length of time out after a stroke ? the sampling rate of the pen ? if the system should clean the input box for the user after each character is written ? the stack size for the input pad subtask parameter name description xpos x-coordinate of the top left corner of the input pad ypos y-coordinate of the top left corner of the input pad numrow number of rows of input boxes numcol number of columns of input boxes areawidth width of each input box in number of pixels areaheight height of each input box in number of pixels echocol colour of the echo ink echowidth dot width of the echo ink f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
19-6 character input tools personal portable system manager programmers manual 19.6 opensoftkey syntax status opensoftkey (u16 xpos , u16 ypos ) description opens a soft keyboard module for type-written english character input. a soft keyboard is drawn at the position specified by the application. once the keyboard is opened, key-pressed interrupt messages (irpt_key) are generated to the application when key icons on the soft keyboard module are pressed. each individual key pressed generates an individual interrupt message. only one soft keyboard is allowed for each application. the image that is covered by the pseudo keyboard is saved by the system automatically, which will be restored upon closing of the keyboard. note that the image saved by the system is a snap-shot of the display screen at the time this tool is called. any changes to this area by the application will not be recorded by the system. parameter return value ppsm_err_input_pad_opened input pad already opened by the same task or its sibling sub-task or its parent task ppsm_err_input_pad_x_pos input pad x-coordinate out of range ppsm_err_input_pad_y_pos input pad y-coordinate out of range ppsm_err_input_pad_width input pad width out of range ppsm_err_input_pad_height input pad height out of range ppsm_err_no_memory not enough memory name description xpos x-coordinate of the top left corner of the soft keyboard ypos y-coordinate of the top left corner of the soft keyboard name description ppsm_ok successful operation ppsm_err_skbd_x_pos input pad x-coordinate out of range name description personal portable system manager programmers manual character input tools 19-3 ? width and height of each key in number of pixels ? number of rows and columns of keys ? the return code of each key(ie, key code or scan code) ? the bitmap of the soft keyboard user interface parameter return value 19.3 closeinputpad syntax name description xpos x-coordinate of the top left corner of the soft keyboard ypos y-coordinate of the top left corner of the soft keyboard keywidth width of each key in number of pixels keyheight height of each key in number of pixels numrow number of rows of keys numcol number of columns of keys keymap pointer to an array of return key codes, from the top left key towards to the right, then next row and so on, until the bottom right key bitmap bitmap of the soft keyboard area interface width = (keywidth * numcol) height = (keyheight * numrow) in number of pixels name description ppsm_ok successful operation ppsm_err_skbd_used soft keyboard has already being used by current task ppsm_err_pan_init panning screen info is not initialized yet ppsm_err_input_pad_noscre en no panning screen memory is allocated for this task ppsm_err_skbd_xsize soft keyboard x-coordinate out of range ppsm_err_skbd_ysize soft keyboard y-coordinate out of range ppsm_err_no_memory not enough memory f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
19-4 character input tools personal portable system manager programmers manual status closeinputpad (void) description closes the handwritten character input pad. the input pad image is removed from the panning screen display and no more handwriting recognition messages (irpt_hwr) will be generated from the system to the application. the original image covered by the input pad is restored by the system. parameter return value 19.4 closesoftkey syntax status closesoftkey (void) description closes the soft keyboard module. the soft keyboard image is removed from the display area and no more key pressed messages (irpt_key) will be generated from the system to the application. the original image covered by the keyboard is restored by the system. parameter return value name description none name description ppsm_ok successful operation ppsm_err_pen_init no active area found ppsm_err_input_pad_closed input pad is not opened name description none name description ppsm_ok successful operation personal portable system manager programmers manual character input tools 19-5 19.5 openinputpad syntax status openinputpad (u16 xpos , u16 ypos , u16 numrow , u16 numcol , u16 areasize ) description opens the input pad for handwritten character input. the input pad is drawn at the specified position in a row by column format. the input pad has numrow by numcol number of square input boxes. each input box is of size areasize by areasize pixels. once the input pad is opened, handwriting recognition interrupt messages (irpt_hwr) are generated to the application when characters are being recognized. each recognized character generates an individual interrupt message. only one input pad is allowed among all applications. the image that is covered by the input pad is saved by the system automatically, which will be restored upon closing of the input pad. note that the image saved by the system is a snap-shot of the display screen at the time this tool is called. any changes to this area by the application will not be recorded by the system. the input pad needs to be closed before any of the other applications can open it. the default length of input timeout is 1sec. parameter return value ppsm_error soft keyboard is not opened name description xpos x-coordinate of the top left corner of the input pad ypos y-coordinate of the top left corner of the input pad numrow number of rows of input boxes numcol number of columns of input boxes areasize size of each input box in number of pixels name description ppsm_ok successful operation name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-2 graphics tools personal portable system manager programmers manual parameter return value name description newpanning a pan_screen structure containing the properties to set to: ? p_u32 panaddress - panning screen address ? u16 horzsize - panning screen horizontal size ? u16 vertsize - panning screen vertical size ? u16 displayxorigin - x-coordinate of lcd display origin relative to panning screen ? u16 displayyorigin - y-coordinate of lcd display origin relative to panning screen ? p_u32 displayscreenaddr - the lcd display screen address used in hardware register display screen address ? u8 regposr - the bit position offset used in hardware register posr ? u16 regpsw - (panning screen width * number of bit per pixel)/16 flag false if the old panning screen is not needed any more and true if the old panning screen needs to be kept and returned in oldpanning oldpanning a pan_screen structure returned by the system containing the original settings: ? p_u32 panaddress ? u16 horzsize ? u16 vertsize ? u16 displayxorigin ? u16 displayyorigin ? p_u32 displayscreenaddr ? u8 regposr ? u16 regpsw name description ppsm_ok successful operation personal portable system manager programmers manual character input tools 19-7 ppsm_err_skbd_y_pos input pad y-coordinate out of range ppsm_err_skbd_used soft keyboard already being used ppsm_err_no_memory not enough memory name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
19-8 character input tools personal portable system manager programmers manual personal portable system manager programmers manual graphics tools 20-1 chapter 20 graphics tools all coordinates mentioned in the following tools are panning screen coordinates: ? the range of valid (x, y) coordinates is from (0, 0) through (panning screen width - 1, panning screen height - 1). ? the range of valid width is from 1 through panning screen width ? the range of valid height is from 1 through panning screen height 20.1 changepanning syntax status changepanning (p_pan_screen newpanning , u16 flag , p_pan_screen oldpanning ) description this function changes the current tasks panning screen address, size, etc. the panning screen width must be divisible by 8 for 2 bits/pixel and divisible by 16 for 1 bit/pixel display. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-6 graphics tools personal portable system manager programmers manual return value hint the lcd display origin is the co-ordinate of top left corner of the lcd display screen relative to the panning screen origin. 20.6 cursorgetpos syntax status cursorgetpos (p_u16 xpos , p_u16 ypos ) description returns the coordinate ( *xpos , *ypos ) of the hardware cursor of the current task. if this function is called after calling cursoroff(), error will be returned as no more information about cursor exists after calling cursoroff(). parameter return value name description ppsm_err_pan_init error when the current task has no panning screen ppsm_error if any of xpos or ypos is 0 ppsm_ok successful operation name description xpos pointer to x coordinate of the top-left corner of the cursor ypos pointer to y coordinate of the top-left corner of the cursor name description ppsm_err_cursor_init error if cursor is never set or cursoroff() is just called. ppsm_err_pan_init error when the cursor is not set ppsm_error if any of xpos and ypos is 0 ppsm_ok successful operation personal portable system manager programmers manual graphics tools 20-3 hint the panning screen address must be created by using getscreenmem(). in some cases, a common panning screen may be shared among multiple tasks. to achieve that, the common panning screen is created by getscreenmem(), and changepanning() is called at the beginning of each task. 20.2 changewindow syntax status changewindow (u32 addr , u16 width , u16 height , p_u32 oldaddr , p_u16 oldwidth , p_u16 oldheight ) description this tool will direct all graphics routines to the memory at addr so that nothing will be changed on the panning screen being displayed. the width must be divisible by 8 for 2 bits/pixel display and divisible by 16 for 1 bit/pixel display. the original settings will be returned to the calling application. parameter return value ppsm_err_pan_address invalid panning screen address ppsm_err_pan_width invalid panning screen width ppsm_err_pan_height invalid panning screen height name description addr new graphics output area address width new graphics output area width in number of pixels height new graphics output area height in number of pixels oldaddr old graphics output area address oldwidth old graphics output area width in number of pixels oldheight old graphics output area height in number of pixels name description ppsm_ok successful operation name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-4 graphics tools personal portable system manager programmers manual hint this is used for displaying image which needs a long time to generate. the image can be plotted in other memory area by using changewindow(). when the image is drawn, it can be copied to the panning screen by calling changewindow() and putrec(). 20.3 clearrec syntax status clearrec (u16 greylevel , u16 xsrc , u16 ysrc , u16 width , u16 height , u16 style ) description fills the given area with grey level indicated by greylevel with style . parameter return value ppsm_err_width invalid graphics output area width ppsm_err_height invalid graphics output area height name description greylevel grey level of the line xsrc top left x-coordinate of the rectangular area ysrc top left y-coordinate of the rectangular area width width of the rectangular area in pixels height height of the rectangular area in pixels style output style (and_style, or_style, exor_style, or replace_style). name description ppsm_ok successful operation ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_width invalid width ppsm_err_height invalid height name description personal portable system manager programmers manual graphics tools 20-5 hint if ( xsrc , ysrc ) is (5, 10), width equals 20, and height equals 10, this will fill the rectangle with top left corner at (5, 10) and bottom right corner at (24, 39) on lcd with specified greylevel with style . 20.4 clearscreen syntax void clearscreen (u16 greylevel ) description fills the whole panning screen with grey level indicated by greylevel . parameter return value 20.5 cursorgetorigin syntax status cursorgetorigin (p_u16 xpos , p_u16 ypos ) description returns the coordinate ( *xpos , *ypos ) of the display origin. parameter ppsm_err_lcd_style invalid style name description greylevel grey level of screen name description none name description xpos pointer to x coordinate of the display origin ypos pointer to y coordinate of the display origin name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-10 graphics tools personal portable system manager programmers manual 20.12 cursorsetorigin syntax status cursorsetorigin (u16 xpos , u16 ypos ) description sets the lcd display screen origin to ( xpos , ypos ). parameter return value hint this must be used with lcdscreenmove(). 20.13 cursorsetpos syntax status cursorsetpos (u16 xpos , u16 ypos ) description sets the top left corner position of the hardware cursor to be at ( xpos , ypos ) ppsm_err_cursor_init no more memory to create the hardware cursor information record ppsm_error error if the frequency cannot be set name description xpos x coordinate of the display origin ypos y coordinate of the display origin name description ppsm_err_pan_init current task has no panning screen ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_ok successful operation name description personal portable system manager programmers manual graphics tools 20-7 20.7 cursorgetstatus syntax status cursorgetstatus (p_u16 status ) description returns the status of the hardware cursor of the current task. parameter return value 20.8 cursorinit syntax status cursorinit (u16 cursorwidth , u16 cursorheight ) description changes hardware cursor size to be of width cursorwidth and height cursorheight . the width and height must be less than 31 pixels. parameter name description status pointer to status flag of the cursor. it can be one of the following values: ? ppsm_cursor_off cursor is off ? ppsm_cursor_on cursor is on in full density ? ppsm_cursor_reversed cursor is on in reverse video name description ppsm_err_cursor_init error if cursor is never set or cursoroff() is just called. ppsm_ok successful operation name description cursorwidth width of the cursor in number of pixels cursorheight height of the cursor in number of pixels f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-8 graphics tools personal portable system manager programmers manual return value hint if the cursor is large, programmer may use invrec() to implement a soft cursor. 20.9 cursoroff syntax status cursoroff (void) description turns off the hardware cursor permanently. parameter return value 20.10 cursorset syntax status cursorset (u16 xpos , u16 ypos ) description name description ppsm_err_pan_init error when the current task has no panning screen ppsm_err_cursor_init no more memory to create the hardware cursor information record ppsm_err_width if cursorwidth is larger than 31 ppsm_err_height if cursorheight is larger than 31 ppsm_ok successful operation name description none name description ppsm_err_cursor_init error if cursor is never set or cursoroff() is just called. ppsm_ok successful operation personal portable system manager programmers manual graphics tools 20-9 sets the top left corner of the hardware cursor to be at ( xpos , ypos ). the current task must have panning screen. the ( xpos , ypos ) must be within the panning screen. however, it doesnt check whether the right boundary exceeds the panning screen coordinate. parameter return value 20.11 cursorsetblink syntax status cursorsetblink (u16 frequency ) description this will set the hardware cursor in blinking mode with frequency indicating the number of blinks per 10 seconds. however, the cursor will be seen only if the cursor is set on by calling cursorsetstatus(). parameter return value name description xpos x coordinate of the top-left corner of the hardware cursor ypos y coordinate of the top-left corner of the hardware cursor name description ppsm_err_pan_init current task has no panning screen ppsm_err_cursor_init no more memory to create the hardware cursor information record ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_ok successful operation name description frequency blinking rate of the cursor in number of blinks per 10 seconds name description ppsm_err_pan_init current task has no panning screen f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-14 graphics tools personal portable system manager programmers manual status drawcircle (u16 greylevel , u16 xcenter , u16 ycenter , u16 radius , u16 style ) description draws a circle centered at ( xcenter , ycenter ) with radius and style as specified. if dot width is greater than 1, a thick circle will be drawn. if both fill pattern mode and border mode are set, those area inside the circle which is not covered by border will be filled. if fill pattern mode is set and border mode is off, the area inside and on the circle border will be filled. parameter return value 20.18 drawdot syntax status drawdot (u16 greylevel , u16 xpos , u16 ypos , u16 style ) description outputs a dot with grey level greylevel onto the screen at position ( xpos , ypos ) with indicated style. name description greylevel grey level of the circle xcenter x-coordinate of the center of circle ycenter y-coordinate of the center of circle radius radius of the circle in number of pixels style output style (and_style, or_style, exor_style or replace_style) name description ppsm_ok successful operation ppsm_err_lcd_grey invalid grey level value ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_lcd_radius invalid radius ppsm_err_lcd_style invalid style personal portable system manager programmers manual graphics tools 20-11 parameter return value 20.14 cursorsetstatus syntax status cursorsetstatus (u16 status ) description this will set the hardware cursor mode to on in full density, on in reverse video mode, or temporary off. the hardware cursor will be set on when this function is called with ppsm_cursor_on or ppsm_cursor_reversed. parameter name description xpos x coordinate of the top-left corner of the cursor ypos y coordinate of the top-left corner of the cursor name description ppsm_err_pan_init current task has no panning screen ppsm_err_cursor_init no more memory to create the hardware cursor information record ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_ok successful operation name description status specify whether a hardware cursor is needed and if so, in what mode it should be: ? ppsm_cursor_off - temporary no hardware cursor ? ppsm_cursor_on - full density hardware cursor is needed ? ppsm_cursor_reversed - reverse video mode hardware cursor is needed. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-12 graphics tools personal portable system manager programmers manual return value hint cursorinit() is called to set the hardware cursor width and height which ranges from 0 to 31 in pixels. cursorsetpos() is called to set the co-ordinate of the top left corner of the hardware cursor. then finally, cursorsetstatus is called to turn the hardware cursor on. after cursorsetstatus() is called and hardware cursor is on, cursorsetpos() and cursorinit() may be called to change the hardware cursor position or size with immediate effect without calling cursorsetstatus() again. 20.15 displaymove syntax status displaymove( u16 xpos, u16 ypos) description this function is to replace the calling of lcdscreenmove() and cursorsetorigin(). whenever the user wants to display a region of panning screen with top left corner of the display at (xpos, ypos) of the panning screen, displaymove(xpos, ypos) should be called. parameter return value name description ppsm_err_pan_init current task has no panning screen ppsm_err_cursor_init no more memory to create the hardware cursor information record ppsm_ok successful operation name description xpos x coordinate ypos y coordinate name description ppsm_ok successful operation ppsm_err_pan_init error when the current task has no panning screen ppsm_err_coordinate error when any part of lcd is going to display the region outside panning screen personal portable system manager programmers manual graphics tools 20-13 20.16 drawarc syntax status drawarc (u16 greylevel , u16 x1 , u16 y1 , u16 x2 , u16 y2 , u16 style ) description draws an arc from ( x1 , y1 ) to ( x2 , y2 ). the arc is actually a quarter of an ellipse with center at ( x2 , y1 ) on which both ( x1 , y1 ) and ( x2 , y2 ) lie. if dot width is greater than 1, a thick arc will be drawn. if both fill pattern mode and border mode are set, those area inside arc which is not covered by the border of the arc will be filled. if fill pattern is set and border is off, those area inside and on the arc border will be filled. parameter return value 20.17 drawcircle syntax name description greylevel grey level of the arc x1 x-coordinate of the first point y1 y-coordinate of the first point x2 x-coordinate of the second point y2 y-coordinate of the second point style output style (and_style, or_style, exor_style or replace_style) name description ppsm_ok successful operation ppsm_err_lcd_grey invalid grey level value ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_lcd_style invalid style f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-18 graphics tools personal portable system manager programmers manual parameter return value 20.22 drawrec syntax status drawrec (u16 greylevel , u16 xsrc , u16 ysrc , u16 xdest , u16 ydest , u16 dotline , u16 style ) description draws a rectangular outline with the top-left corner at ( xsrc , ysrc ) and bottom- right corner at ( xdest , ydest ). if dot width is greater than 1, a thick rectangle will be drawn. if both fill pattern mode and border mode are set, those area inside the rectangle which is not covered by the border will be filled. if fill pattern mode is set and border mode is off, the area inside and on the rectangle border will be filled. name description greylevel grey level of the line xsrc x-coordinate of the source point ysrc y-coordinate of the source point xdest x-coordinate of the destination point ydest y-coordinate of the destination point dotline dotted line drawing. this argument accepts a number which represents an equal number of solid dots and skipped dots during line drawing. a value of 0 represents a solid line. style output style (and_style, or_style, exor_style, or replace_style). name description ppsm_ok successful operation ppsm_err_lcd_grey invalid grey level value ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_lcd_style invalid style personal portable system manager programmers manual graphics tools 20-15 if dot width is 2, a square dot of length 2 will be drawn where the top left corner is ( xpos , ypos ). if dot width is greater than 2, a disc with the center at ( xpos , ypos ) will be drawn. parameter return value 20.19 drawellipse syntax status drawellipse (u16 greylevel , u16 xcenter , u16 ycenter , u16 xlength , u16 ylength , u16 style ) description draws an ellipse centered at ( xcenter , ycenter ) with the xlength as the width in the x-axis, and ylength as the height in the y-axis. if dot width is greater than 1, a thick ellipse will be drawn. if both fill pattern mode and border mode are set, those area inside ellipse which is not covered by the border will be filled. if fill pattern mode is set and border mode is off, the area inside and on the ellipse border will be filled. name description greylevel grey level of the dot xpos x-coordinate of the dot ypos y-coordinate of the dot style output style (and_style, or_style, exor_style, or replace_style). name description ppsm_ok successful operation ppsm_err_lcd_grey invalid grey level value ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_lcd_style invalid style f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-16 graphics tools personal portable system manager programmers manual parameter return value 20.20 drawhorz syntax status drawhorz (u16 greylevel , u16 xsrc , u16 ysrc , u16 width , u16 dotline , u16 style ) description draws a horizontal line from ( xsrc , ysrc ) to the right for width dots. if dot width is greater than 1, a thick horizontal line will be drawn. if dot width is greater than 1 and the width of the horizontal line is 1, a square dot of size indicated by dot width will be drawn. if dotline is non-zero, dotline number of dots will be drawn with the specified grey level; then, the dotline number of dots will be skipped; then, the dotline number of dots will be drawn; and so on. parameter name description greylevel grey level of the ellipse xcenter x-coordinate of the center of ellipse ycenter y-coordinate of the center of ellipse xlength the length of the ellipse in x-axis in pixels ylength the length of the ellipse in y-axis in pixels style output style (and_style, or_style, exor_style or replace_style) name description ppsm_ok successful operation ppsm_err_lcd_grey invalid grey level value ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_lcd_style invalid style name description greylevel grey level of the line personal portable system manager programmers manual graphics tools 20-17 return value 20.21 drawline syntax status drawline (u16 greylevel , u16 xsrc , u16 ysrc , u16 xdest , u16 ydest , u16 dotline , u16 style ) description draws a line from ( xsrc , ysrc ) to ( xdest , ydest ). if dot width is greater than 1, a thick line will be drawn. if dot width is greater than 1 and ( xsrc , ysrc ) equals ( xdest , ydest ), a square dot of size indicated by dot width will be drawn. if dotline is non-zero, dotline number of dots will be drawn with the specified grey level; then, the dotline number of dots will be skipped; then, the dotline number of dots will be drawn; and so on. xsrc x-coordinate of the left end-point of the line ysrc y-coordinate of the left end-point of the line width the length of the line in pixels dotline dotted line drawing. this argument accepts a number which represents an equal number of solid dots and skipped dots during line drawing. a value of 0 represents a solid line. style output style (and_style, or_style, exor_style, or replace_style). name description ppsm_ok successful operation ppsm_err_lcd_grey invalid grey level value ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_lcd_style invalid style name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-22 graphics tools personal portable system manager programmers manual parameter return value 20.26 getdisplayx syntax u16 getdisplayx (void) description returns the lcd display screen width in number of pixels. parameter return value hint name description xsrc top left x-coordinate of the rectangular image to be stored ysrc top left y-coordinate of the rectangular image to be stored width width of the rectangular image to be stored in pixels height height of the rectangular image to be stored in pixels bitmap bitmap image to be displayed name description ppsm_ok successful operation ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_width invalid width ppsm_err_height invalid height name description none name description n/a the display screen width in pixels personal portable system manager programmers manual graphics tools 20-19 parameter return value 20.23 drawvector syntax status drawvector (u16 greylevel , u16 numberofpoints , p_point ppoints , u16 style , u16 mode ) description draws lines to connect points according to the sequence of the data points input. no connection will be made between the first and last points unless it is specified by mode or when the last point is the same as the first point. drawvector() does not support pattern fill. name description greylevel grey level of the rectangle xsrc x-coordinate of the top-left corner ysrc y-coordinate of the top-left corner xdest x-coordinate of the bottom-right corner ydest y-coordinate of the bottom-right corner dotline dotted line drawing. this argument accepts a number which represents an equal number of solid dots and skipped dots during line drawing. a value of 0 represents a solid line. style output style (and_style, or_style, exor_style, or replace_style). name description ppsm_ok successful operation ppsm_err_lcd_grey invalid grey level value ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_lcd_style invalid style f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-20 graphics tools personal portable system manager programmers manual parameter return value hint if the output style is exor_style, special care should be taken regarding overlapped points. 20.24 drawvert syntax status drawvert (u16 greylevel , u16 xsrc , u16 ysrc , u16 height , u16 dotline , u16 style ) description draws a vertical line from ( xsrc , ysrc ) down for height dots. if dot width is greater than 1, a thick vertical line will be drawn. if dot width is greater than 1 and the height of the vertical line is 1, a square dot of size indicated by dot width will be drawn. name description greylevel grey level of the lines numberofpoints number of points in the list ppoints pointer to the list of points to be connected style output style can be: ? exor_style ? or_style ? and_style ? replace_style mode mode should be set to true if the first and last points need to be connected; otherwise, it should be false name description ppsm_ok successful operation ppsm_error numberofpoints is 0 ppsm_err_lcd_grey invalid grey level ppsm_err_lcd_style invalid style ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate personal portable system manager programmers manual graphics tools 20-21 if dotline is non-zero, dotline number of dots will be drawn with the specified grey level; then, the dotline number of dots will be skipped; then, the dotline number of dots will be drawn; and so on. parameter return value 20.25 exchangerec syntax status exchangerec (u16 xsrc , u16 ysrc , u16 width , u16 height , p_u8 bitmap ) description swaps the image in memory pointed to by bitmap with the image at the specified location of the panning screen. the image pointed to by bitmap will now be displayed while the rectangular region on the panning screen will be stored at bitmap . note that the image stored in bitmap must be the same size as the specified rectangle in the arguments. name description greylevel grey level of the line xsrc x-coordinate of the top end-point of the line ysrc y-coordinate of the top end-point of the line height the length of the line in pixels dotline dotted line drawing. this argument accepts a number which represents an equal number of solid dots and skipped dots during line drawing. a value of 0 represents a solid line. style output style (and_style, or_style, exor_style, or replace_style). name description ppsm_ok successful operation ppsm_err_lcd_grey invalid grey level value ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_lcd_style invalid style f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-26 graphics tools personal portable system manager programmers manual 20.32 lcdcontrast syntax status lcdcontrast (u8 contrast) description this tool will pass the value of contrast to the contrast control pwm register. the user needs to set or reset the contrast control pwm enable bit. parameter return value name description contrast an 8 bit values to pass to pwm name description ppsm_ok successful operation personal portable system manager programmers manual graphics tools 20-23 application programmers should make use of this function to make the applications size independent. 20.27 getdisplayy syntax u16 getdisplayy (void) description returns the display screen height in number of pixels. parameter return value hint application programmers should make use of this function to make the applications size independent. 20.28 getlogicalx syntax u16 getlogicalx (void) description returns the current panning screen width in number of pixels. this value gives the size that an application can write to, which may be larger than the lcd display screen (i.e. the whole image might not be displayed on the lcd display screen). parameter name description none name description n/a the display screen height in pixels name description none f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-24 graphics tools personal portable system manager programmers manual return value 20.29 getlogicaly syntax u16 getlogicaly (void) description returns the current panning screen height in number of pixels. this value gives the size that an application can write to, which may be larger than the lcd display screen (i.e. the whole image might not be displayed on the lcd display screen). parameter return value 20.30 getscreenmem syntax p_void getscreenmem (u16 width , u16 height ) description this tool will allocate appropriate memory for a panning screen of size width and height . parameter name description n/a the panning screen width in pixels name description none name description n/a the panning screen height in pixels name description width panning screen width in pixels height panning screen height in pixels personal portable system manager programmers manual graphics tools 20-25 return value 20.31 invrec syntax status invrec (u16 xsrc , u16 ysrc , u16 width , u16 height ) description inverts the grey level of the specified rectangular area on the panning screen. parameter return value name description n/a returns an address for panning screen use or 0 if there is an error name description xsrc top left x-coordinate of the rectangular area ysrc top left y-coordinate of the rectangular area width width of the rectangular area in pixels height height of the rectangular area in pixels name description ppsm_ok successful operation ppsm_err_lcd_x invalid lcd x-coordinate ppsm_err_lcd_y invalid lcd y-coordinate ppsm_err_width invalid width ppsm_err_height invalid height f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-30 graphics tools personal portable system manager programmers manual return value 20.37 saverec syntax status saverec (p_u8 bitmap , u16 xsrc , u16 ysrc , u16 width , u16 height , u16 reserved ) description saves a rectangular bitmap image from the specified location on the panning screen to memory. parameter return value reserved reserved for future use name description ppsm_ok successful operation ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_width invalid width ppsm_err_height invalid height ppsm_err_lcd_style invalid style name description bitmap pointer to address where bitmap image is to be saved xsrc top left x-coordinate of the rectangular image area ysrc top left y-coordinate of the rectangular image area width width of the image in pixels height height of the image in pixels reserved reserved for future use name description ppsm_ok successful operation name description personal portable system manager programmers manual graphics tools 20-27 20.33 lcdrefreshrate syntax status lcdrefreshrate( u16 refreshrate, p_u16 refreshrateset) description this tool will set the lcd refresh rate to refreshrate number of frames per second. as the frame rate will be limited by pixel clock divider register, refresh rate adjustment register, screen width register, screen height register and pll control register, ppsm will only set the refresh rate to the closest possible value. if refreshrate is 0, the lcd module will be off. refreshrateset will be the previous refresh rate. if user wants to know whether the calling of lcdrefreshrate() is successful, lcdrefreshrate() can be called once more to get the current actual refresh rate returned by refreshrateset . parameter return value 20.34 lcdscreenmove syntax status lcdscreenmove (u16 x , u16 y ) description this function is replaced by displaymove(). maps the lcd display screen origin to ( x , y ). the rectangular portion of the panning screen with top left corner ( x , y ) will be displayed on the lcd display screen. it is assumed that ( x , y ) is within the valid range of panning screen coordinates. name description refreshrate number of frames per second. refreshrateset pointer to old frame rate before changes. name description ppsm_ok successful operation f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-28 graphics tools personal portable system manager programmers manual parameter return value hint this must be used with cursorsetorigin(). 20.35 putchar syntax status putchar (u16 greylevel, p_u8 character, u16 xpos, u16 ypos, u16 font, u16 width, u16 height, u16 style) description this tool will put a 1 bit/pixel font image on 1 bit/pixel or 2 bit/pixel display depending on whether ppsm1.a or ppsm2.a is linked. parameter name description x new x-coordinate of the origin of the lcd display screen y new y-coordinate of the origin of the lcd display screen name description ppsm_ok successful operation name description greylevel grey level of the character to put on panning screen character pointer to the character bitmap xpos x coordinate of the top left corner where font is going to put ypos y coordinate of the top left corner where font is going to put font small_italic_font and large_italic_font font will be handled differently to generate the italic effect from a rectangular font bitmap. width width of the character in number of pixels height height of the character in number of pixels personal portable system manager programmers manual graphics tools 20-29 return value 20.36 putrec syntax status putrec (p_u8 bitmap , u16 xsrc , u16 ysrc , u16 width , u16 height , u16 style , u16 reserved ) description puts a rectangular bitmap image from memory to the specified location of the panning screen. parameter style it can be replace_style, or_style, name description ppsm_ok successful operation ppsm_err_pan_init error if the task has no panning screen ppsm_err_grey invalid grey level ppsm_err_lcd_x draw outside the panning screen. invalid x coordinate ppsm_err_lcd_y draw outside the panning screen. invalid y coordinate ppsm_err_lcd_font invalid font ppsm_err_lcd_style invalid style ppsm_error invalid character pointer name description bitmap pointer to the bitmap image to be displayed xsrc top left x-coordinate of where the bitmap image will be mapped ysrc top left y-coordinate of where the bitmap image will be mapped width width of the image in pixels height height of the image in pixels style output style (and_style, or_style, exor_style or replace_style) name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
21-2 database management tools personal portable system manager programmers manual parameter return value hint for dbaddrecord() to work, the reference database id must have been created by calling dbadd() prior to the calling of dbaddrecord(). 21.3 dbaddrectotop syntax status dbaddrectotop (u32 dbid , s32 numfmt , p_u32 outrecid ) description adds a blank record at the beginning of the record list of a given database. user has the option to specify additional formatted data fields to be allocated. the valid range of numfmt is from 0 to 5. this tool is meant to complement the action of dbaddrecord(). parameter name description dbid identifier of the database recid returns the identifier of the record added numfmt number of additional formatted data fields in the record name description ppsm_ok successful operation ppsm_err_db_dbid invalid database identifier ppsm_err_num_fmt invalid user format field number name description dbid identifier of the database numfmt number of additional formatted data fields in the record outrecid returns the identifier of the added record personal portable system manager programmers manual graphics tools 20-31 20.38 setdotwidth syntax status setdotwidth (u16 newwidth , p_u16 oldwidth ) description this tool sets the width for a dot in number of pixels so that a thick dot can be drawn by drawdot(), a thick line can be drawn by drawline(), etc. this dot width is applied to drawdot(), drawline(), drawrec(), drawcircle(), drawellipse(), drawarc() and drawvector(). if oldwidth is non-zero, the current dot width will be saved in oldwidth. parameter return value 20.39 setpatternfill syntax status setpatternfill (u16 mode , u16 backgrey , u16 bordermode , u16 fillspace ) description ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_width invalid width ppsm_err_height invalid height name description newwidth new dot width in pixels oldwidth previous dot width in pixels name description ppsm_ok successful operation ppsm_err_dot_width newwidth is 0 name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
20-32 graphics tools personal portable system manager programmers manual this tool sets the pattern fill mode to be applied to drawrec(), drawcircle(), drawellipse() and drawarc(). the fill pattern modes are: the pattern fill mode 0 will turn off the pattern fill feature. parameter return value name description mode there are 8 modes of pattern fill (see description above) backgrey the grey level used for the background space bordermode border on-off flag ? true - a border will be drawn around the shape ? false - no border will be drawn around the shape fillspace the gap between the pattern lines. the larger this value is, the more space the pattern will appear. name description ppsm_ok successful operation ppsm_err_fill_pattern invalid fill pattern mode ppsm_err_lcd_grey invalid background grey level ppsm_err_fill_space invalid space gap in fill pattern 123 4 567 8 personal portable system manager programmers manual database management tools 21-1 chapter 21 database management tools 21.1 dbadd syntax status dbadd (p_u32 dbid ) description adds a new database for an application to ppsm. this is the first routine to be called whenever a database is created. the database added is a global database. parameter return value hint the returned dbid must remain intact. application uses this as a key to access the database. 21.2 dbaddrecord syntax status dbaddrecord (u32 dbid , p_u32 recid , s32 numfmt ) description appends a blank record to the end of the record list for a particular database. user has the option to specify additional formatted data fields to be allocated. the valid range of numfmt is from 0 to 5. name description dbid returns a database identifier. this identifier is used by the ppsm to refer to this particular database. name description ppsm_ok successful operation ppsm_err_db_add unable to add database f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
21-6 database management tools personal portable system manager programmers manual hint the record and database referred to must be valid objects in the ppsm environment. observes the unformatted data type specification for interchangeability. 21.7 dbdelete syntax status dbdelete (u32 dbid ) description removes a database from ppsm, and frees up all associated memory. parameter return value hint the database referred to must be a valid object in the ppsm environment. 21.8 dbdeleterecord syntax status dbdeleterecord (u32 dbid , u32 recid ) description removes a particular record from the specified database, and frees up all associated memory. ppsm_err_db_type invalid data type name description dbid identifier of the database to be removed name description ppsm_ok successful operation ppsm_err_db_dbid invalid database identifier name description personal portable system manager programmers manual database management tools 21-3 return value hint this tool is meant to facilitate the implementation of insertion operation for an ordered record list. for dbaddrectotop() to work, the reference database id must have been created by calling dbadd() prior to the calling of dbaddrectotop(). also, the recid passed must be a valid record id in the database to be operated on. 21.4 dbappendrecord syntax status dbappendrecord (u32 dbid , u32 recid , s32 numfmt , p_u32 outrecid ) description appends a blank record to the record identified by the given recid and output the record identifier, outrecid , corresponding to the new record. user has the option to specify additional formatted data fields to be allocated. the valid range of numfmt is from 0 to 5. parameter return value name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_num_fmt invalid user format field number name description dbid identifier of the database recid identifier of the record in the record list which the new record is to be appended numfmt number of additional formatted data fields in the new record outrecid returns the record identifier of the new record name description ppsm_ok successful operation f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
21-4 database management tools personal portable system manager programmers manual hint this tool is meant to facilitate the implementation of insertion operation for an ordered record list. for dbappendrecord() to work, the reference database id must have been created by calling dbadd() prior to the calling of dbappendrecord(). also, the recid passed must be a valid record id in the database to be operated on. 21.5 dbchangestddata syntax status dbchangestddata (u32 dbid , u32 recid , s32 fieldid , p_text data ) description changes the data in a predefined standard field of a record in the specified database. parameter ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier ppsm_err_num_fmt invalid user format field number name description dbid identifier of the database recid identifier of the record fieldid identifier of the field: ? db_last last name ? db_first first name ? db_home home phone ? db_office office phone ? db_address address ?db_fax fax ? db_company company ? 1, 2, 3, 4, 5 additional fields data data to be put into the field name description personal portable system manager programmers manual database management tools 21-5 return value hint adheres to the size limit of each data field when writing data into it. the record and database referred to must be valid objects in the ppsm environment. 21.6 dbchangeunfdata syntax status dbchangeunfdata (u32 dbid , u32 recid , s32 type , p_u32 data , s32 size ) description changes the data in the unformatted data portion of a record. parameter return value name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier ppsm_err_db_fdid invalid field identifier name description dbid identifier of the database recid identifier of the record type type of data data starting address of the data size size of the data (in bytes) name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
21-10 database management tools personal portable system manager programmers manual parameter return value hint the database and record referred to must be valid objects in the ppsm environment. if a user defined field is to be read, it is the use rs responsibility to check the return status for ppsm_ok, to ensure that the user defined field does exist before using the returned data for subsequent processing. 21.13 dbreadtotalnumber syntax status dbreadtotalnumber (p_s32 numdb ) description reads the total number of databases in the ppsm environment. parameter return value name description dbid identifier of the database recid identifier of the record fieldid identifier of the field data returns the pointer to the starting address of the data name description ppsm_ok successful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier ppsm_err_db_fdid invalid field identifier name description numdb returns the total number of databases name description ppsm_ok successful operation personal portable system manager programmers manual database management tools 21-7 parameter return value hint the database and record referred to must be valid objects in the ppsm environment. 21.9 dbgetfirstrecid syntax status dbgetfirstrecid (u32 dbid , p_u32 recid ) description gets the record id of the first record in the record list of the given database. parameter return value hint name description dbid identifier of the database recid identifier of the record to be removed name description ppsm_ok successful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier name description dbid identifier of the database recid returns the identifier of the top record in the record list name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
21-8 database management tools personal portable system manager programmers manual this tool is useful for implementing searching on the record list. the database referred to must be a valid object in the ppsm environment. 21.10 dbgetnextrecid syntax status dbgetnextrecid (u32 dbid , u32 recid , p_u32 nextid , p_u16 botlistflag ) description gets the identifier of the record following the specified record. if the specified record is the last record, nextid returned will be the same as recid , and the botlistflag will be set. parameter return value hint this tool is for implementing searching on the record list. the database and record referred to must be valid objects in the ppsm environment 21.11 dbgetprevrecid syntax name description dbid identifier of the database recid identifier of specified record nextid returns the identifier of the next record botlistflag true if the record identified by recid is the last record name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier personal portable system manager programmers manual database management tools 21-9 status dbgetprevrecid (u32 dbid , u32 recid , p_u32 previd , p_u16 toplistflag ) description gets the identifier of the record fore-running the specified record. if the specified record is the first record, the previd returned will be the same as recid , and the toplistflag will be set. parameter return value hint this tool is useful for implementing searching on the record list. the database and record referred to must be valid objects in the ppsm environment. 21.12 dbreaddata syntax status dbreaddata (u32 dbid , u32 recid , s32 fieldid , p_text *data ) description reads the formatted data from the specified database, record and field. name description dbid identifier of the database recid identifier of the specified record previd returns the identifier of the previous record toplistflag true if the record identified by recid is the first record name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
21-14 database management tools personal portable system manager programmers manual hint current implementation of tool stop searching once an exact match is found. there is no provision for the case where multiple matches exist. for good programming practice, user must check the status returned to ensure a valid search is found before using the record identifier returned. 21.18 dbsecretflag syntax status dbsecretflag (u32 dbid , p_s32 sflag ) description checks if the secret flag of a particular database is set or not. parameter return value hint the database referred to must be a valid object in the ppsm environment. ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier ppsm_err_db_fdid invalid field identifier ppsm_no_match no match of data name description dbid identifier of the database sflag returns the secret flag of the database. it can take either of the following two values: ? 0 secret flag is cleared ? 1 secret flag is set name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier name description personal portable system manager programmers manual database management tools 21-11 21.14 dbreadtotalnumberrecords syntax status dbreadtotalnumberrecords (u32 dbid , p_s32 numrec ) description reads the total number of records in a given database. parameter return value hint the database referred to must be a valid object in the ppsm environment. 21.15 dbreadunfdata syntax status dbreadunfdata (u32 dbid , u32 recid , p_s32 type , p_u32 *data , p_s32 size ) description reads the data in the unformatted data portion of a record. it will pass back the pointer to the unformatted data being stored in the record. in addition, it will also pass back the type and size information of the unformatted data. ppsm_err_db_readno invalid number found name description dbid identifier of the database numrec returns the number of the records in the database name description ppsm_ok successful operation ppsm_err_db_dbid invalid database identifier name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
21-12 database management tools personal portable system manager programmers manual parameter return value hint the database and record referred to must be valid objects in the ppsm environment. it is good practice for user to check that the return status is ppsm_ok before using the data . 21.16 dbrecordsecret syntax status dbrecordsecret (u32 dbid , u32 recid , p_s32 sflag ) description checks if the secret flag of a particular record in a given database is set or not. parameter name description dbid identifier of the database recid identifier of the record type returns type of the data data returns pointer to the starting address of the data size returns size of the data (in bytes) name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier name description dbid identifier of the database recid identifier of the record personal portable system manager programmers manual database management tools 21-13 return value hint the database and record referred to must be valid objects in the ppsm environment. 21.17 dbsearchdata syntax status dbsearchdata (u32 dbid , s32 fieldid , p_text data , p_u32 recid ) description searches though the record list of the given database, finds if there is a record that matches the specified data in the specified field. returns status of operation. if ppsm_ok is returned, the recid passed back is the record identifier of the record with the specified data. parameter return value sflag returns the secret flag of the database. it can take either of the following two values: ? 0 secret flag is cleared ? 1 secret flag is set name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier name description dbid identifier of the database fieldid identifier of the field data data to be found recid returns the identifier of the record name description ppsm_ok successful operation name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
22-2 text tools personal portable system manager programmers manual return value 22.3 textmap syntax status textmap (u32 templateid , p_text buffer , u16 numchar ) description displays the given text onto the panning screen with properties specified in the text template identified by templateid . the text will be displayed starting at the current character cursor position. the font type, output style and grey level of the text are specified by the text template. text that extends beyond the size of the text display area specified by the text template will be truncated. the current character cursor position is automatically updated by the system. parameter return value 22.4 textreadcursor syntax status textreadcursor (u32 templateid , p_u16 cursor ) description name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier name description templateid identifier of the text template with current text properties buffer pointer to text string to be displayed numchar number of characters to be displayed name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier ppsm_err_text_cur invalid character cursor position personal portable system manager programmers manual database management tools 21-15 21.19 dbsetrecordsecretflag syntax status dbsetrecordsecretflag (u32 dbid , u32 recid , s32 sflag ) description sets the secret flag of a particular record. parameter return value hint the database and record referred to must be a valid object in the ppsm environment. note that when a new record is created, its secret flag will be set according to the secret flag of the database which it belongs to. if a user wants all records in the database to be set secret, it should call dbsetsecretflag() immediately after dbadd() is called. 21.20 dbsetsecretflag syntax status dbsetsecretflag (u32 dbid , s32 sflag ) description name description dbid identifier of the database recid identifier of the record sflag secret flag of the database. it can take either of the following two values: ? 0 clears the secret flag ? 1 sets the secret flag name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_recid invalid record identifier ppsm_err_db_sflag invalid secret flag value f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
21-16 database management tools personal portable system manager programmers manual sets the secret flag of a database. if it is set, all new records created subsequently in the specified database will be set to secret. parameter return value hint the database referred to must be a valid object in the ppsm environment. user can use this flag to implement data security mechanism at a higher level. note that the secret flag is set to 0 when the database is created. if a user wants all records in the database to be set secret, it should call dbsetsecretflag() immediately after dbadd() is called. name description dbid identifier of the database sflag secret flag of the database. it can take either of the following two values: ? 0 clears the secret flag ? 1 sets the secret flag name description ppsm_ok successful operation ppsm_error unsuccessful operation ppsm_err_db_dbid invalid database identifier ppsm_err_db_sflag invalid secret flag value personal portable system manager programmers manual text tools 22-1 chapter 22 text tools 22.1 textcreate syntax status textcreate (p_u32 templateid ) description creates and initializes a text template for storing text properties. an identifier for the created text template will be returned. this is the first text tool an application must call before any text can be displayed on the panning screen. the templateid returned is required for further references to this particular text template. parameter return value 22.2 textdelete syntax status textdelete (u32 templateid ) description deletes a text template created by textcreate(). this should be done when the text template is not needed anymore. parameter name description templateid identifier of the newly created text template. this is valid only when ppsm_ok is returned. name description ppsm_ok successful operation ppsm_err_text_cr error while creating text template name description templateid identifier of the text template to be deleted f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
22-6 text tools personal portable system manager programmers manual return value 22.8 textsetoutlook syntax status textsetoutlook (u32 templateid , u16 outputstyle , u16 greylevel ) description sets up the output style and grey level of the given text template with the given values. subsequent text mapped using this text template will be displayed with these new settings. the output style is defined as the arithmetic operation between the text character bitmap and the image on the panning screen where the character bitmap will be displayed. five output styles are supported. the text bitmap can replace, or with, and with, exclusive or with, or be inverted and replace the existing image. up to four grey levels are currently supported. for a 1 bit per pixel system, the grey levels supported are white and black. for a 2 bits per pixel system, the grey levels supported are white, light grey, dark grey and black. pfontattr pointer to a text font attributes data structure. supported font types are: ? small_normal_font small normal (english) ? small_italic_font small italic (english) ?large_normal_font large normal (english) ? large_italic_font large italic (english) ? gb_normal_font gb normal ? chinese_normal_font same as gb normal ? big5_normal_font big5 normal ? big5_variable_font big5 variable name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier ppsm_err_text_font invalid font type ppsm_err_no_memory not enough memory name description personal portable system manager programmers manual text tools 22-3 reads the current character cursor position of the text template identified by templateid . the character cursor position returned is relative to the origin of the text display area. parameter return value 22.5 textsetcursor syntax status textsetcursor (u32 templateid , u16 cursor) description sets the current character cursor position of the text template identified by templateid to the new position as specified. the range of valid character cursor positions to set to is zero through (text display area size in number of characters - 1). parameter return value name description templateid text template identifier cursor current character cursor position name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier name description templateid text template identifier cursor the character cursor position to set to name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier ppsm_err_text_cur invalid character cursor position f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
22-4 text tools personal portable system manager programmers manual 22.6 textsetdisplay syntax status textsetdisplay (u32 templateid , u16 xpos, u16 ypos, u16 width , u16 height , u16 cursor ) description sets up the text display layout of the given text template with the corresponding given values. the text display layout comprises of the location and size of a text template. subsequent text mapped using this text template will be displayed with the new layout. the text display layout specified must reside within the boundary of the panning screen. the size of the text display area in number of pixels varies with the size of the font type specified in the text template. the range of valid character cursor positions to set to is zero through (text display area size in number of characters - 1). parameter return value name description templateid identifier of text template to be modified xpos x-coordinate of top left corner of text display area ypos y-coordinate of top left corner of text display area width width of text display area in number of columns of characters height height of text display area in number of rows of characters cursor character cursor position within the text display area where text will be displayed next name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier ppsm_err_text_x text template x-coordinate out of range ppsm_err_text_y text template y-coordinate out of range ppsm_err_text_width given width extends text display area beyond the panning screen personal portable system manager programmers manual text tools 22-5 22.7 textsetfont syntax status textsetfont (u32 templateid , p_fontattr pfontattr ) description sets up the font attributes of the given text template. subsequent text mapped using this text template will be displayed with these new font attributes. eight font types are currently supported. small normal and small italic are 8 x 8 pixels english fonts. large normal and large italic are 16 x 16 pixels english fonts. gb normal is 16 x 16 chinese font in gb code format. chinese normal is the same as gb normal (for backward compatibility). big5 normal is 16 x 16 chinese font in big5 code format. big5 variable is a variable size font in big5 code format. note: asian fonts are supplied by third parties. the specified font width and height will only take effect if the big5 variable font type is specified. the minimum and maximum size will depend on the specific font libraries being provided. the attribute field is for future extensions and should be set to zero. parameter ppsm_err_text_height given height extends text display area beyond the panning screen ppsm_err_text_cur invalid character cursor position name description templateid identifier of text template to be modified name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
22-10 text tools personal portable system manager programmers manual personal portable system manager programmers manual text tools 22-7 parameter return value 22.9 textsetup syntax status textsetup (u32 templateid , u8 fonttype , u8 outputstyle , u8 greylevel, u16 xpos, u16 ypos, u16 width , u16 height ) description sets up the font type, output style, grey level, location and size of the given text template with the given values. subsequent text mapped using this text template will be displayed with these new settings. name description templateid identifier of text template to be modified outputstyle output style of text to be displayed: ? replace_style replace existing image ? or_style or with existing image ? and_style and with existing image ? exor_style exclusive or with existing image ? inverse_style invert and replace existing image greylevel grey level value of the characters: ?white white color text ? light_grey light grey color text ? dark_grey dark grey color text ?black black color text name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier ppsm_err_text_style invalid output style ppsm_err_text_grey invalid grey level value f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
22-8 text tools personal portable system manager programmers manual this tool does not support the variable size of big5_variable_font font type and is provided for backward compatibility. if big5_variable_font is used, default font size of 16 x 16 is used. please refer to textsetdisplay() ( section 22.6 - textsetdisplay ), textsetfont() ( section 22.7 - textsetfont ), and textsetoutlook() ( section 22.8 - textsetoutlook ) for detailed descriptions of the corresponding parameters. parameter return value name description templateid identifier of text template to be modified fonttype font type of text to be displayed: ? small_normal_font ? small_italic_font ?large_normal_font ? large_italic_font ? chinese_normal_font ? big5_normal_font ? big5_variable_font outputstyle output style of text to be displayed: ? replace_style ? or_style ? and_style ? exor_style ? inverse_style greylevel grey level value of the characters: ?white ? light_grey ? dark_grey ?black xpos x-coordinate of top left corner of text display area ypos y-coordinate of top left corner of text display area width width of text display area in number of columns of characters height height of text display area in number of rows of characters name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier personal portable system manager programmers manual text tools 22-9 22.10 textunmap syntax status textunmap (u32 templateid ) description clears the entire text display area specified by the given text template. parameter return value ppsm_err_text_font invalid font type ppsm_err_text_style invalid output style value ppsm_err_text_grey invalid text grey level value ppsm_err_text_x text template x-coordinate out of range ppsm_err_text_y text template y-coordinate out of range ppsm_err_text_width given width extends text display area beyond the panning screen ppsm_err_text_height given height extends text display area beyond the panning screen name description templateid identifier of text template name description ppsm_ok successful operation ppsm_err_text_id invalid text template identifier name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
23-4 timer tools personal portable system manager programmers manual return value 23.6 alarmsetid syntax status alarmsetid (p_u32 alarmid , u16 year , u16 month , u16 date , u16 hour , u16 minute , u16 second ) description set alarm at specific time and return the alarm id. when the time reaches the alarm time, a message with the alarm id, will be passed to the task. even if the task is swapped out or the system goes to sleep, the alarm task will still be swapped in and the system will wake up. however, if more than one alarm tasks happen, the earlier the alarm is set, the earlier the task will be swapped in. if alarmid is 0, no alarm id will be given but the alarm will still be set. so if several alarms are set at the same time, the task will first swap to the alarm task which set the alarm first, then the second, etc. however, this version the alarm will stop in the task which set the alarm first only, although the alarm messages are sent to other tasks also. parameter name description ppsm_ok successful operation ppsm_err_year invalid year value ppsm_err_month invalid month value ppsm_err_day invalid day value ppsm_err_hour invalid hour value ppsm_err_minute invalid minute value ppsm_err_second invalid second value name description alarmid the pointer to the alarm id set with specific time year alarm year which must be greater than or equal to 1900 month alarm month from 1 to 12 date alarm date from 1 to 28, 30 or 31 depending on the month and year values. hour alarm hour from 0 to 23 personal portable system manager programmers manual timer tools 23-1 chapter 23 timer tools 23.1 alarmclear syntax void alarmclear (void) description clear all alarms set for current task. this will not affect those alarms set for other tasks. parameter return value 23.2 alarmclearid syntax void alarmclearid (u32 alarmid ) description this function will clear the alarm in the alarm list specified by alarmid . the alarm set can be of any task. parameter return value name description none name description none name description alarmid the identifier of the alarm to be cleared name description none f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
23-2 timer tools personal portable system manager programmers manual 23.3 alarmread syntax status alarmread (p_u16 year , p_u16 month , p_u16 day , p_u16 hour , p_u16 minute , p_u16 second ) description reads the up coming alarm set for the current task in alarm list. parameter return value 23.4 alarmreadid syntax status alarmreadid (u32 alarmid, p_u16 year, p_u16 month , p_u16 day , p_u16 hour , p_u16 minute , p_u16 second ) description this function will read the alarm time set in alarmid . parameter name description year pointer to the year value of the alarm month pointer to the month value of the alarm day pointer to the day value of the alarm hour pointer to the hour value of the alarm minute pointer to the minute value of the alarm second pointer to the second value of the alarm name description ppsm_ok successful operation ppsm_err_no_alarm no alarm is set name description alarmid the identifier of the alarm to be read year pointer to the year of the alarm month pointer to the month of the alarm personal portable system manager programmers manual timer tools 23-3 return value 23.5 alarmset syntax status alarmset (u16 year , u16 month, u16 day , u16 hour , u16 minute, u16 second ) description sets the year , month , day , hour , minute and second values of an alarm. once set, the application will receive a software interrupt message from the system when the specified time is reached. parameter day pointer to the day of the alarm hour pointer to the hour of the alarm minute pointer to the minute of the alarm second pointer to the second of the alarm name description ppsm_ok successful operation ppsm_error error if any of the year, month, day, hour, minute or second is null ppsm_err_no_alarm no alarm with the specified alarmid found in alarm list name description year the new year for the alarm month the new month for the alarm day the new day for the alarm hour the new hour for the alarm, in 24-hour clock unit minute the new minute for the alarm, in 60- minute clock unit second the new second for the alarm, in 60- second clock unit name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
23-8 timer tools personal portable system manager programmers manual for dragonball not dragonball-ez, the inputtimeout() is also limited by the pen input sampling rate. a higher sampling rate is more likely to give a more accurate result. parameter return value 23.11 reffinetimealarm syntax status reffinetimealarm (u32 alarmtime ) description sets up an alarm time with respect to the current reference timer in unit of 100 microseconds. maximum period between alarm time and current time is 0x7fffffff/10 millisecond. parameter return value 23.12 reffinetimealarmid syntax name description millisecond time-out period in units of millisecond. if this value is zero, time-out is disabled. name description ppsm_ok successful operation ppsm_err_tmout_value invalid time-out period name description alarmtime the absolute value of the alarm time with respect to the current reference timer value in unit of 100 microseconds. maximum alarm time period is 0x7fffffff/10 milliseconds from the current reference time. name description ppsm_ok successful operation personal portable system manager programmers manual timer tools 23-5 return value 23.7 datetimeread syntax status datetimeread (p_u16 year , p_u16 month , p_u16 day , p_u16 hour , p_u16 minute , p_u16 second ) description gets the system date and time. parameter return value minute alarm minute from 0 to 59 second alarm second from 0 to 59 name description ppsm_ok successful operation ppsm_err_year invalid year ppsm_err_month invalid month ppsm_err_day invalid date ppsm_err_hour invalid hour ppsm_err_minute invalid minute ppsm_err_second invalid second name description year pointer to the year value month pointer to the month value day pointer to the day value hour pointer to the hour value minute pointer to the minute value second pointer to the second value name description ppsm_ok successful operation name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
23-6 timer tools personal portable system manager programmers manual 23.8 datetimeset syntax status datetimeset (u16 year , u16 month , u16 day , u16 hour , u16 minute , u16 second ) description sets the system date and time. parameter return value ppsm_err_year invalid year pointer ppsm_err_month invalid month pointer ppsm_err_day invalid day pointer ppsm_err_hour invalid hour pointer ppsm_err_minute invalid minute pointer ppsm_err_second invalid second pointer name description year input year value, starts from 1900 month input month value, in range 1 - 12 day input day value, in range 1 - 31 hour input hour value, in range 0 - 23 minute input minute value, in range 0 - 59 second input second value, in range 0 - 59 name description ppsm_ok successful operation ppsm_err_year invalid year value ppsm_err_month invalid month value ppsm_err_day invalid day value ppsm_err_hour invalid hour value ppsm_err_minute invalid minute value ppsm_err_second invalid second value name description personal portable system manager programmers manual timer tools 23-7 23.9 deletetimer syntax status deletetimer (u32 timerid ) description delete the timer in timer list specified by timerid . timer can be deleted in any task as far as the timer identifier is known. parameter return value 23.10 inputtimeout syntax status inputtimeout (u32 millisecond ) description sets the repetitive time-out period for data input from the touch panel. this time-out routine is an explicit time-out routine dedicated for the pen input device. once this time-out routine is activated, the time-out period specified in the argument list is set and count down begins immediately after pen up condition is detected. if the time-out period expires before the next pen down has occurred, ppsm will generate a timer interrupt to the calling application; otherwise, the time-out period is reset ready for the next pen input sequence. this is a repetitive time-out that will continuously set the timer for time-out after each pen input stroke, until it is disabled. to disable the time-out, call this function with zero as the argument. maximum value allowed is 1000. in irptgetdata(), the alarm id read will be 0xffffffff to distinguish this input timeout from normal timeout. name description timerid the timer identifier returned after calling timeoutid(), reffinetimealarmid() or reftimealarmid(). name description ppsm_ok successful operation ppsm_error if the timerid is not valid. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
23-12 timer tools personal portable system manager programmers manual this routine takes in two reference times and return to the caller the difference between the two. this routine takes care of wrapped around condition of the 32-bit continuous reference value. all reference timer values in this routine are in unit of milliseconds. parameter return value 23.18 reftimeread syntax u32 reftimeread (void) description returns the current 32-bit reference timer value to the caller in unit of milliseconds. the calling of this function will occupy longer cpu time than reffinetimeread(). parameter return value 23.19 setperiod syntax name description begintime the begin reference time in unit of millisecond endtime the end reference time in unit of millisecond name description n/a the elapsed time between the two given reference times in unit of milliseconds name description void - name description n/a returns a 32-bit reference timer value in unit of milliseconds personal portable system manager programmers manual timer tools 23-9 status reffinetimealarmid (p_u32 alarmid , u32 alarmtime ) description sets up an alarm time with respect to the current reference timer in unit of 100 microseconds. maximum period between alarm time and current time is 0x7fffffff/10 milliseconds. the timerid will be returned in irptgetdata(). parameter return value 23.13 reffinetimediff syntax u32 reffinetimediff (u32 begintime, u32 endtime ) description this routine takes in two reference times and return to the caller the difference between the two times. this routine takes care of wrapped around condition of the 32-bit continuous reference value. all reference timer values in this routine are in unit of 100 microseconds. parameter name description alarmid pointer to reference timer alarm identifier alarmtime the absolute value of the alarm time with respect to the current reference timer value in unit of 100 microseconds. name description ppsm_ok successful operation name description begintime the begin reference time in unit of 100 microseconds endtime the end reference time in unit of 100 microseconds f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
23-10 timer tools personal portable system manager programmers manual return value 23.14 reffinetimeread syntax u32 reffinetimeread (void) description returns the current 32-bit reference timer value to the caller in unit of 100 microseconds. this is recommended to be used to read the reference timer as it doesnt involve much calculation and simply return the value. reftimeread() will need more cpu time to convert the reference timer to resolution of millisecond. parameter return value 23.15 reftimealarm syntax status reftimealarm (u32 alarmtime ) description sets up an alarm time with respect to the current reference timer in unit of milliseconds. maximum period between alarm time and current time is 0x7fffffff/10 milliseconds. name description n/a the elapsed time between the two given reference times in unit of 100 microseconds name description void name description n/a returns a 32-bit reference timer value in unit of 100 microseconds personal portable system manager programmers manual timer tools 23-11 parameter return value 23.16 reftimealarmid syntax status reftimealarmid (p_u32 alarmid , u32 alarmtime ) description sets up an alarm time with respect to the current reference timer in unit of milliseconds. maximum period between alarm time and current time is 0x7fffffff/10 milliseconds. the alarmid will be returned in irptgetdata(). parameter return value 23.17 reftimediff syntax u32 reftimediff (u32 begintime, u32 endtime ) description name description alarmtime the absolute value of the alarm time with respect to the current reference timer value in unit of milliseconds. maximum alarm time period is 0x7fffffff/10 seconds from the current reference time. name description ppsm_ok successful operation name description alarmid pointer to reference timer alarm identifier alarmtime the absolute value of the alarm time with respect to the current reference timer value in unit of milliseconds. name description ppsm_ok successful operation f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
23-16 timer tools personal portable system manager programmers manual personal portable system manager programmers manual timer tools 23-13 status setperiod (u16 period ) description sets the periodic interrupt from the system. this routine will cause ppsm to send a periodic interrupt message with the specified duration between messages, to the calling application. parameter return value 23.20 setperiodid syntax status setperiodid (p_u32 alarmid, u16 period ) description this function will set the periodic interrupt for current task. hour periodic interrupt is available for mc68ez328 but not mc68328. if the periodic alarm is going to be killed with rtc_peri_none, rtc_peri_no_second, etc., the returned value of the alarmid is going to be meaningless. parameter name description period the period of interrupt can have any one of the following values: ? rtc_peri_none disable periodic interrupt ? rtc_peri_second interrupt per second ? rtc_peri_minute interrupt per minute name description ppsm_ok successful operation ppsm_err_period invalid time-out period name description alarmid the pointer the alarm id set with specific period f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
23-14 timer tools personal portable system manager programmers manual return value 23.21 timeout syntax status timeout (u32 millisecond ) description general timer time-out routine. this is a one-shot time-out. the application that calls this routine will register a time-out interval with ppsm. a time interrupt is generated to the task when this time-out period is expired. maximum allowed value for timeout() is 1000. period it can be: rtc_peri_none - kill all period interrupts in all tasks rtc_peri_second - set second periodic interrupts for current task rtc_peri_minute - set minute periodic interrupts for current task rtc_peri_hour - set hour periodic interrupts for current task which is only available for ez328 rtc_peri_midnight - set midnight periodic interrupts for current task rtc_peri_no_second - kill second periodic interrupt for current task rtc_peri_no_minute - kill minute interrupt for current task rtc_peri_no_hour - kill hour interrupt for current task which is only available for ez328 rtc_peri_no_midnight - kill midnight interrupt for current task name description ppsm_ok successful operation ppsm_err_period invalid period flag ppsm_err_no_memory out of memory name description personal portable system manager programmers manual timer tools 23-15 parameter return value 23.22 timeoutid syntax status timeoutid (p_u32 timerid , u32 millisecond ) description general timer time-out routine. this is a one-shot time-out. the application that calls this routine will register a time-out interval with ppsm. a time interrupt is generated to the task when this time-out period is expired with the timer id. passed to task. maximum allowed value for timeout() is 1000. parameter return value name description millisecond time-out period in unit of millisecond. if this value is zero, time-out is disabled. name description ppsm_ok successful operation ppsm_err_tmout_value invalid time-out period name description timerid pointer to the timer identifier millisecond time-out period in unit of millisecond. if this value is zero, time-out is disabled. name description ppsm_ok successful operation ppsm_err_tmout_value invalid time-out period f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
24-4 memory management tools personal portable system manager programmers manual return value 24.6 taskmemused syntax status taskmemused (u32 taskid, p_u32 psizeused ) description inquire memory usage of a task. this routine returns to the caller total number of bytes of memory allocated to the given task through lmalloc(), lcalloc or lrealloc(). parameter return value 24.7 taskstackavail syntax s32 taskstackavail (void) description ppsm returns to the caller the total number of bytes of stack can still be used by current task when calling taskstackavail(). positive returned value indicates stack has not been used up, negative value implies stack has already overflow. name description ppsm_ok successful operation ppsm_error invalid input arguments name description taskid identifier of the task psizeused returns the total number of bytes of memory used by the task with the given taskid name description ppsm_ok successful operation ppsm_err_task_id invalid task identifier personal portable system manager programmers manual memory management tools 24-1 chapter 24 memory management tools 24.1 lcalloc syntax void * lcalloc (u32 size ) description dynamic allocation of run-time memory to the caller. this routine returns to the caller a pointer to a region of free memory within the malloc size specified in the linker specification file (.spc). ppsm returns at least the amount of memory, in number of bytes, that the caller asked for. if there is not enough memory available in the system, a null pointer is returned. the memory pointed to by the pointer is initialized to zero. parameter return value 24.2 lfree syntax void lfree (void *ptr ) description returns the memory back into the system heap for reuse. the parameter supplied must be a valid pointer obtained from one of the ppsm memory allocation tools. name description size the size of memory required by the caller in number of bytes name description n/a zero - not enough memory in the system non-zero - pointer to an initialized free memory region f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
24-2 memory management tools personal portable system manager programmers manual parameter return value 24.3 lmalloc syntax void * lmalloc (u32 size ) description dynamic allocation of run-time memory to the caller. this routine returns to the caller a pointer to a region of free memory within the malloc size specified in the linker specification file (.spc). ppsm returns at least the amount of memory, in number of bytes, that the caller asked for. if there is not enough memory available in the system, a null pointer is returned. the memory pointed to by the pointer is un-initialized. ppsm returns the size of the largest continuous memory block can be used when calling lmalloc( largest_malloc_size ). parameter return value name description ptr pointer to a valid memory location. it must be a pointer returned from one of the ppsm memory allocation tools. name description none name description size the size of memory required by the caller in number of bytes or flag largest_malloc_size when inquiring the size of the largest continuous memory block name description n/a zero - not enough memory in the system non-zero - pointer to an initialized free memory region or the size of the largest continuous memory block personal portable system manager programmers manual memory management tools 24-3 24.4 lrealloc syntax void * lrealloc (void *ptr , u32 size ) description moving of memory. this routine re-allocates the memory that is being used from one location to another. it allocates a new area, then copies the content at the original location to the new area, and frees the original memory back into the heap. the purpose of this routine is to defragmentize the system memory. parameter return value 24.5 moveblock syntax status moveblock (p_u32 srcaddr , p_u32 destaddr , u32 size ) description copies a block of memory from the specified source location to the specified destination location. the tool automatically detects the direction of movement. overlapping of memory regions is allowed. parameter name description ptr pointer to a valid memory location. it must be a pointer returned from one of the ppsm memory allocation tools. size the size of memory to be reallocated name description n/a zero - not enough memory in the system non-zero - pointer to a valid free memory region with the original regions content name description srcaddr address of source location destaddr address of destination location size size of transfer in bytes f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
25-2 power management tools personal portable system manager programmers manual parameter return value 25.3 setdutycycle syntax u16 setdutycycle (u16 percentage ) description this tool allows the application to set its own duty cycle level. applications within a system can have different duty cycle percentages. ppsm automatically changes the pcm correspondingly when the application tasks become active. parameter name description millisecond specifies the doze mode time-out period in unit of milliseconds. the range is from 0 to 60000 milliseconds. the 0 default value means that ppsm enters doze mode whenever there is no messages and no task swapping is needed. if its ppsm_no_doze, no automatically going to doze after doze timeout nor sleep timeout will happen. name description ppsm_ok successful operation ppsm_err_doze_time doze time-out period out of range name description percentage specifies the percentage of duty cycle required from the processor core. range from a minimum of 3% processor usage to a maximum of 100% usage in unit of 3% steps. anything less than 3% will be set to 3; anything more than 100% will be set to 100. by default, all applications start at 100% duty cycle personal portable system manager programmers manual memory management tools 24-5 parameter return value 24.8 totalmemsize syntax u32 totalmemsize (void) description this routine returns to the caller the number of bytes of memory can be allocated through lmalloc(), lcalloc() or lrealloc() on the system. value returned by this function is a constant which is the same as the malloc size specified in the linker specification file (.spc). parameter return value 24.9 totalmemused syntax u32 totalmemused (void) description name description none name description n/a total number of bytes of stack can still be used by current task name description none name description n/a the number of bytes of mallocable memory on the system f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
24-6 memory management tools personal portable system manager programmers manual inquire run-time memory usage of the system. this routine returns to the caller the total number of bytes of memory have been allocated to the whole system through lmalloc(), lcalloc() or lrealloc(). parameter return value note: value returned by totalmemused() does not equal to the actual size of all memory resources used by the system. global variables and strings memory usage are not counted by this function. for sds user, the initial memory usage can be found by the symbol lister, sym.exe, provided in sds command directory. name description none name description n/a the total number of bytes of memory allocated to the whole system personal portable system manager programmers manual power management tools 25-1 chapter 25 power management tools 25.1 setdozemode syntax void setdozemode (void) description sets system to go into doze mode immediately. parameter return value 25.2 setdozeperiod syntax status setdozeperiod (u16 millisecond ) description sets the countdown period to switch the system from normal mode to doze mode. a value of zero forces the system to go to doze mode whenever there is no message to be handled and no task swapping is needed. if millisecond equals ppsm_no_doze, no automatically going to doze will be executed and so no automatically going to sleep mode even setsleepperiod() is called. name description none name description none f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
26-2 uart communication tools personal portable system manager programmers manual return value baudrate baud rate flag ? uart_300_bps 300 bits per second ? uart_600_bps 600 bits per second ? uart_1200_bps 1200 bits per second ? uart_2400_bps 2400 bits per second ? uart_4800_bps 4800 bits per second ? uart_9600_bps 9600 bits per second ? uart_14400_bps 14400 bits per second ? uart_19200_bps 19200 bits per second ? uart_28800_bps 28800 bits per second ? uart_38400_bps 38400 bits per second ? uart_57600_bps 57600 bits per second ? uart_115200_bps 115200 bits per second parity parity flag ? no_parity disable parity ? odd_parity enable odd parity ? even_parity enable even parity stopbits stop bits flag ? one_stop_bit one stop bit after a character ? two_stop_bit two stop bits after a character charlen character length flag ? seven_bit_char 7-bit character mode ? eight_bit_char 8-bit character mode name description ppsm_ok successful operation name description personal portable system manager programmers manual power management tools 25-3 return value 25.4 setsleepmode syntax void setsleepmode (void) description sets system to go into sleep mode immediately. parameter return value 25.5 setsleepperiod syntax status setsleepperiod (u16 second ) description sets the countdown period to switch the system from doze mode to sleep mode. a value of zero disables the system from going into sleep mode. parameter name description u16 returns the previous duty cycle name description none name description none name description second specifies the sleep mode time-out period in unit of seconds, in the range from 0 to 512 seconds. the default value is 0, meaning no sleep mode is required. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
25-4 power management tools personal portable system manager programmers manual return value name description ppsm_ok successful operation ppsm_err_sleep_time sleep time-out period out of range personal portable system manager programmers manual uart communication tools 26-1 chapter 26 uart communication tools 26.1 uartconfigure syntax status uartconfigure (u8 mode, u16 baudrate , u8 parity , u8 stopbits , u8 charlen ) description configures the uart with the given operating mode , baudrate , parity , number of stopbits , and charlen flag settings. the uart hardware and the data transmission time-out are reset during the course of this configuration. any on-going send or receive request are also aborted. both the normal nrz and irda operating modes are supported. the minimum and maximum baud rates supported are 300 bits per second and 115200 bits per second correspondingly. parameter name description mode operating mode flag ? uart_normal_mode normal nrz mode ? uart_irda_mode irda mode f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
26-6 uart communication tools personal portable system manager programmers manual 26.5 uartreaddata syntax status uartreaddata (p_u8 pdata, u16 bufsize, p_u16 sizeread ) description reads data received from the uart. an application can initiate a receive request to start receiving data from the uart by calling uartreceive() ( section 26.6 - uartreceive ). when ppsm receives data from the uart, it will post an interrupt message to notify the calling application. the calling application can then read the data by calling uartreaddata(). the calling application needs to pass a buffer, with its size, to ppsm for storing the received data. ppsm will pass back to the calling application the actual number of bytes of data read into the application buffer. an error condition will be returned if the calling application was not granted permission to use the uart, or no receive request has been initiated when uartreaddata() is called. if rts/cts is enabled, rts pin is negated when ppsm running uartread- data() and asserted after data reading completed. parameter return value 26.6 uartreceive syntax status uartreceive (u8 receiveflag ) name description pdata pointer to buffer for storing received data bufsize size of data buffer (in number of bytes) sizeread number of bytes of data read name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart ppsm_err_no_request receive request was not initiated personal portable system manager programmers manual uart communication tools 26-3 26.2 uartflowctrl syntax status uartflowctrl (u8 controltype ) description enable or disable hardware flow control in uart data communication. ppsm can handle data communication with another device by uart with rts/cts hardware flow control. an application can enable hardware control by calling uartflowctrl() with appropriate flag. parameter return value 26.3 uartinquire syntax ppsm_err_invalid_access invalid access of uart ppsm_err_mode invalid operating mode flag ppsm_err_baud invalid baud rate flag ppsm_err_parity invalid parity flag ppsm_err_stopbit invalid number of stop bits flag ppsm_err_charlen invalid character length flag name description controltype controltype ? uart_rcts_enable enable rts/cts hardware flow control ? uart_rcts_disable disable rts/cts hardware flow control name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart ppsm_error invalid input argument name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
26-4 uart communication tools personal portable system manager programmers manual void uartinquire (p_u8 mode, p_u32 baudrate , p_u8 parity , p_u8 stopbits , p_u8 charlen ) description returns the current operating mode , baudrate , parity , number of stopbits , and charlen settings of the uart to the calling application. the returned values, except for baudrate , are flag values as described in uartconfigure() ( section 26.1 - uartconfigure ). the baud rate value returned is in unit of bits per second. parameter return value 26.4 uartrcvctrl syntax status uartrcvctrl (u8 controltype ) description pause or continue receiving data through uart from another device. an application can pause or continue data reception through uart when hardware control is enabled. error message is returned if rts/cts hardware flow control is not enabled. name description mode current operating mode flag baudrate current baud rate (in units of bps) parity current parity flag stopbits current number of stop bits flag charlen current character length flag name description none personal portable system manager programmers manual uart communication tools 26-5 parameter return value name description controltype controltype ? uart_rcts_pause pause data reception through uart ? uart_rcts_cont continue data reception through uart name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart ppsm_err_rcts_idle rts/cts hardware flow control is not enabled f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
26-10 uart communication tools personal portable system manager programmers manual return value 26.10 uartsetdelay syntax status uartsetdelay (u8 type , u16 delay) description in order to communicate with application in pc, such as hyperterminal and telix, transmitting data in a burst of pulses periodically would greatly increase the accu- racy of transmission. this function allows user to set a delay, in unit of 100us, between each transmission of all data in transmit fifo (between two hardware interrupts). the range of delay values supported is 1 to 60,000. parameter return value name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart ppsm_err_rcts_idle rts/cts hardware flow control is not enabled name description type delay type ? uart_txhalf_delay set a delay between each txhalf interrupts ? uart_txdelay_clear clear delay within transmission delay transmission delay value in 100 microseconds ? 100 microseconds to 60,000 microseconds (6 seconds) name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart ppsm_err_invalid_txdelay delay value out of range personal portable system manager programmers manual uart communication tools 26-7 description initiates or aborts a uart receive request. if receiveflag is uart_receive_request, the receive request will be initiated, and ppsm will start waiting for incoming data from the uart. if receiveflag is uart_receive_abort, the on-going receive request will be aborted. when ppsm receives data, it will post an interrupt message to the calling application notifying it that data is available for it to read. application can then read the received data by calling uartreaddata() ( section 26.5 - uartreaddata ). application task swapping is disabled while the receive request is in progress, and re-enabled after the receive request is terminated. parameter return value 26.7 uartsend syntax status uartsend (u8 sendflag, p_u8 pdata, u16 datalen ) description initiates or aborts a uart send request. if sendflag is uart_send_request, the send request will be initiated, and ppsm will start sending data to the uart. if sendflag is uart_send_abort, the on-going send request will be aborted. name description receiveflag operation flag ? uart_receive_request initiates a receive request ? uart_receive_abort aborts a receive request name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart ppsm_err_busy there is already an on-going receive request (when trying to initiate one) f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
26-8 uart communication tools personal portable system manager programmers manual the calling application needs to pass the data byte stream, with its size, to ppsm for sending out. when ppsm finishes sending the data, it will post an interrupt message to the calling application notifying it that all data has been sent. application task swapping is disabled while the send request is in progress, and re-enabled after the send request is terminated. parameter return value 26.8 uartsendabort syntax status uartsendabort (u8 abortflag , p_u8 * psenddata , p_u32 sendsize ) description terminate the current uart transmission. the transmission abort process is the same as calling uartsend(uart_send_abort). moreover, beside aborting the ongoing transmission, ppsm returns a pointer which points to the current position of internal transmission buffer and the number of bytes of data have been sent. caller can get those information without abort uart transmission by calling uartsendabort() with uart_inquire_sbyte. name description sendflag operation flag ? uart_send_request initiates a send request ? uart_send_abort aborts a send request pdata pointer to data byte stream datalen number of bytes of data to be sent name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart ppsm_err_busy there is already an on-going send request (when trying to initiate one) personal portable system manager programmers manual uart communication tools 26-9 parameter return value 26.9 uartsendctrl syntax status uartsendctrl (u8 controltype ) description pause or continue sending data through uart to another device. an application can pause or continue data transmission through uart when hardware control is enabled. error message is returned if rts/cts hardware flow control is not enabled. parameter name description abortflag abortflag ? uart_send_abort aborts a send request ? uart_inquire_sbyte returns the number of bytes of data have been sent and the position of transmission pointer psenddata position of internal transmission pointer sendsize number of bytes of data have been sent name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart name description controltype controltype ? uart_rcts_pause pause data transmission through uart ? uart_rcts_cont continue data transmission through uart f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
27-2 task handling tools personal portable system manager programmers manual return value 27.2 appswap syntax void appswap (u16 flag ) description if flag is false, no task swapping is allowed by any means such as pen down on application icon nor using sendmessage(), etc. if sendmessage() or advsendmessage() are called after this function with false in flag , the message will still be sent to the target task but the task swapping action will be newscreen screen flag - ? ppsm_screen_noscreen no panning screen is needed ? ppsm_screen_new a panning screen of size screenwidth by screenheight is required screenwidth if newscreen == ppsm_screen_new, this argument is the panning screen width in number of pixels. if this value is 0, the default screen width and height are used screenheight if newscreen == ppsm_screen_new, this argument is the panning screen height in number of pixels. if this value is 0, the default screen height and width are used bitmap the bitmap for launch icon within lcd display name description ppsm_ok successful operation ppsm_err_task_id invalid address for storing task identifier ppsm_err_task_flag invalid screen flag ppsm_err_task_width invalid screen width ppsm_err_task_height invalid screen height ppsm_err_coordinate invalid coordinates ppsm_err_no_memory not enough memory name description personal portable system manager programmers manual uart communication tools 26-11 26.11 uarttimeout syntax status uarttimeout (u16 tmout ) description sets the maximum time interval allowed between two hardware uart interrupts. this time-out function prevents application from deadlocking itself when the data stream terminates unexpectedly. system do not initiate a timeout right after uarttimeout() is called. ppsm starts timeout with the given timeout interval after calling uartsend(), uartreceive(), uartsendctrl() and uartrcvctrl(). the valid range of time-out values can be set is zero through 60,000 (in units of milliseconds). a time-out value of zero means disabling all the time-out function related to uart. parameter return value name description tmout transmission time-out value in milliseconds ? 0 - to disable time out function ? 1 to 60,000 milliseconds name description ppsm_ok successful operation ppsm_err_invalid_access invalid access of uart ppsm_err_invalid_tmout time-out value out of range f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
26-12 uart communication tools personal portable system manager programmers manual personal portable system manager programmers manual task handling tools 27-1 chapter 27 task handling tools 27.1 advtaskcreate syntax status advtaskcreate (p_u32 taskid, p_void procaddr, s16 xsrc, s16 ysrc, s16 xdest, s16 ydest, s32 stacksize, u16 newscreen, u16 screenwidth, u16 screenheight, p_u8 bitmap ) description creation of a new ppsm task. this tool creates a ppsm application task in the same manner as the tool taskcreate() but with advanced configuration details. it allows the caller to specify: ? the launch icon position and size. launch icon can be on screen or off screen. for either width or height is zero, no launch icon is going to be created. ? the stack memory size required by the task. ? the panning screen dimensions. ppsm task can have no associated screen, or a screen with user specified dimension. the default screen dimensions are taken from the linker specification file, lcdvirtwidth and lcdvirtheight. parameter name description taskid returns a task identifier. this identifier is used by ppsm to refer to the task when it uses the system resources. procaddr address of the application task xsrc top-left x-coordinate of task icon ysrc top-left y-coordinate of task icon xdest bottom-right x-coordinate of task icon ydest bottom-right y-coordinate of task icon stacksize required stack size in bytes. if a negative number is used, a default of 512 bytes is used. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
27-6 task handling tools personal portable system manager programmers manual description to set the specific task to be in reinit mode so that each time the task is swapped in, it will start from beginning of the task again. this function is generally called once the task is created. parameter return value 27.7 taskstart syntax status taskstart (u32 taskid ) description begin execution of the first application task. this routine will never returns. it launches the first ppsm application, and all other applications are started by activating the application icons. this routine is used at the start to kick off the system. parameter return value name description taskid the task identifier of the task to be set. flag true or false to indicate whether the task needs to be in reinit mode. name description ppsm_ok successful operation ppsm_err_task_id invalid task id. name description taskid the task identifier for the first application to be launched. name description ppsm_error invalid taskid ppsm_ok task started successfully personal portable system manager programmers manual task handling tools 27-3 ignored. moreover, if several appswap(false) are called, the same number of appswap(true) must be called before the task swapping is enabled. parameter return value 27.3 subtaskcreate syntax status subtaskcreate (p_u32 taskid , p_void procaddr , u16 stacksize , u16 numarg , ...) description creating a sub-task. any task can use this tool to create sub-tasks. if the calling task is itself a sub-task, the new sub-task will belong to its parent(i.e. the calling sub-task and the newly created sub-task become siblings). if more than one sub-task has been created under a parent, the new sub-task will be added to the head of the sub task list. there is currently no limit on the number of sub- task a parent task can have. however, the order of the sub-task chain may change in run-time. this routine accepts variable length input arguments. these arguments are passed into the sub-task by ppsm, meaning that the actual sub-task routine can accept input arguments. parameter name description flag true - enable task swapping false - disable task swapping name description none name description taskid returns a task identifier. this identifier is used by ppsm to refer to the task when it uses the system resources procaddr address of the sub task routine stacksize stack size required for the sub task. if a zero is used, the default of 2k byte is used numarg number of variable arguments. each argument takes up 4 bytes in the argument stack. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
27-4 task handling tools personal portable system manager programmers manual return value 27.4 taskcreate syntax status taskcreate (p_u32 taskid , p_void procaddr , s16 xsrc , s16 ysrc , s16 xdest , s16 ydest , p_u8 bitmap ) description ppsm needs to know the existence of each application during initialization stage. the main body of a ppsm system must call this routine once for each application. ppsm will create the necessary data structure and memory space required to run the application. parameter return value ... variable arguments. these are passed to the sub task routine when the sub task begins execution name description ppsm_ok successful operation ppsm_err_no_memory not enough memory name description taskid returns a task identifier. this identifier is used by ppsm to refer to the task when it uses the system resources. procaddr address location of the application xsrc top left x-coordinate of the task icon ysrc top left y-coordinate of the task icon xdest bottom right x-coordinate of the task icon ydest bottom right y-coordinate of the task icon bitmap pointer to bitmap of the task icon ? 0 - no on-screen icon is needed name description ppsm_ok successful operation name description personal portable system manager programmers manual task handling tools 27-5 27.5 taskhook syntax status taskhook (u32 taskid, p_void entrycallback, p_void exitcallback) description set the entry and exit routines to the specific task. whenever the task is going to be swapped in, entrycallback function will be executed. whenever the task is going to be swapped out, exitcallback will be executed. the entrycallback and exitcallback should be function calls with u32 as input parameter and the function should not involve interrupts, e.g. entry(u32 oldapp) and exit(u32 newapp) where oldapp will be the task identifier of the task just swapped out and newapp will be the next task to be swapped in. parameter return value 27.6 taskreinit syntax status taskreinit (u32 taskid , u16 flag ) ppsm_err_task_id invalid task identifier ppsm_err_coordinate invalid coordinates ppsm_err_no_memory not enough memory name description taskid task identifier of the task to be hooked with the entry and exit functions. entrycallback the entry function to be executed before swapping in the task. if null is input, no entry function will be executed. exitcallback the exit function to be executed after swapping out the task. if null is input, no exit function will be executed. name description ppsm_ok successful operation ppsm_err_task_id invalid task id. name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
28-2 inter-task messaging tools personal portable system manager programmers manual all data that the sender wants to send must be stored in the form of message structure. no protocol or data format is put on the message data. the sender and receiver must have a mutual understanding of the data representation of the message being sent. the data structure for the structure message is: typedef struct _message { u16 messagetype; /* message type */ u16 message; /* message */ u32 misc; /* short data (32bit) */ p_void data; /* associated data, if any */ u16 size; /* size of data in bytes */ u16 reserved; /* for future (broadcast, etc) */ } ppsm_message, *p_message; if appswap(false) is called before calling this function, the message will still be sent but any form of task swapping action will be ignored. if the system is in doze mode, calling this function will wake up the system. parameter name description taskid the receiver task identifier msg the message to send. all data to send are stored in the ppsm_message structure, with the following representation: ? messagetype - must set to message_irpt. ? message - the type of message being sent to the receiver. normally set to irpt_user. ? misc - 32-bit short data ? data - data pointer to the buffer that is storing the message data ? size - size of data buffer, in number of bytes ? reserved - not used flag it can be: swap_task_later - task swapping will happen in irptgetdata() when all messages in current task are handled. swap_task_back_later - task swapping will happen immediately if the pen is not touching the panel and the current task will be swapped back when all messages in the target task are handled. swap_task - task swapping will happen immediately if the pen is not touching the panel. no_swap_task - no task swapping will happen. personal portable system manager programmers manual task handling tools 27-7 27.8 taskterminate syntax status taskterminate (u32 taskid ) description termination of a task. the task identifier can be of a main or sub task. all system memory, such as stack memory and screen (if any), associated with the task and its subtasks that are allocated by ppsm will be freed. a task cannot terminate itself nor its parent task if it is a sub-task. taskterminate() will not free the memory that has been explicitly allocated by the task with lmalloc(). parameter return value name description taskid the task identifier of the task to be terminated name description ppsm_ok task successfully terminated ppsm_err_task_id invalid task identifier f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
27-8 task handling tools personal portable system manager programmers manual personal portable system manager programmers manual inter-task messaging tools 28-1 chapter 28 inter-task messaging tools 28.1 advmessagedelete syntax status advmessagedelete (p_taskdesc task,u16 type, u32 shortdata ) description this function will delete those messages in a tasks message queue with specific task, type and shortdata matched. if any of the parameter value is 0xffffffff in task and shortdata or 0xffff in type, it means "dont care" in that field. so if task is 0xffffffff, all tasks will be check and the matched messages in all tasks will be deleted, etc. parameter return value 28.2 advsendmessage syntax status advsendmessage (u32 taskid , p_message msg, u8 flag ) description this tool is used when the current task wants to send a message to another task. if the receiver tasks task identifier is not known, this tool cannot be used. if msg is 0, no message will be sent but the task swapping may still be executed. name description task task identifier type the message type such as irpt_uart, etc. shortdata this field is generally returned in irptgetdata() as alarmid, timerid, areaid, taskid, etc. name description ppsm_err_task_id invalid task id. ppsm_ok successful operation f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
28-6 inter-task messaging tools personal portable system manager programmers manual personal portable system manager programmers manual inter-task messaging tools 28-3 return value 28.3 messagedelete syntax status messagedelete (u16 type ) description this function will delete those messages in current tasks message queue with specific type matched. if the input parameter value is 0xffff in type, it means "dont care" in that field and all messages in current task will be deleted. parameter return value 28.4 sendmessage syntax status sendmessage (u32 taskid , p_message msg ) description this tool is used when the current task wants to send a message to another task. if the receiver tasks task identifier is not known, this tool cannot be used. name description ppsm_ok message successfully sent ppsm_err_task_id invalid task identifier ppsm_err_no_memory not enough memory ppsm_error invalid flag or appswap(false) is called before calling this function name description type the message type such as irpt_uart, etc. name description ppsm_err_task_id invalid task id. ppsm_ok successful operation f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
28-4 inter-task messaging tools personal portable system manager programmers manual all data that the sender wants to sent must be stored in the form of message structure. no protocol or data format is put on the message data. the sender and receiver must have a mutual understanding of the data representation of the message being sent. on the receiving side, irptgetdata() is where the message received. the data structure for the structure message is: typedef struct _message { u16 messagetype; /* message type */ u16 message; /* message */ u32 misc; /* short data (32bit) */ p_void data; /* associated data, if any */ u16 size; /* size of data in bytes */ u16 reserved; /* for future (broadcast, etc) */ } ppsm_message, *p_message; if appswap(false) is called before calling this function, the message will still be sent but any form of task swapping action will be ignored. if the system is in doze mode, calling this function will wake up the system. parameter corresponding values between sendmessage() and irptgetdata() name description taskid the receiver tasks identifier msg the message to send. all data to send are stored in the ppsm_message structure, with the following representation: ? messagetype - must set to message_irpt. ? message - the type of message being sent to the receiver. normally set to irpt_user. ? misc - 32-bit short data ? data - data pointer pointing a buffer that is storing the message data ? size - size of data buffer, in number of bytes ? reserved - not used sendmessage irptgetdata status sendmessage (u32 taskid , p_message msg ) status irptgetdata (p_u32 sdata , p_u32 *data , p_u32 size ) msg.messagetype must be message_irpt msg.message returned value msg.misc *sdata personal portable system manager programmers manual inter-task messaging tools 28-5 return value msg.data data msg.size size msg.reserved n/a name description ppsm_ok message successfully sent ppsm_err_task_id invalid task identifier ppsm_err_no_memory not enough memory ppsm_error appswap(false) is called before calling this function sendmessage irptgetdata f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
29-4 interrupt handling tools personal portable system manager programmers manual parameter return value 29.3 irptrequest syntax u32 irptrequest (u32 handlerflag ) description this tool is used by the application task to request the services of the interrupt handlers. once requested and granted, all interrupt messages sent from the handlers are directed to the application with the appropriate interrupt identifiers. when calling this tool, the user must specify which of the handlers it wishes to request. the interrupt flags can be or ed together to request more than one handler with a single call. if the requested handlers are installed and available, ppsm system will hook the handlers to the application; if not, ppsm will do nothing. the return value from this tool is a 16-bit word, returning the flags of the handlers that have been granted, if any. it uses the same format as the input handler flag parameter. for example, if a caller makes a request for a specific set of handlers, and if all are granted, then the return value from the tool will be the same as the input handler flag parameter. if any one of the requested handlers cannot be granted, the return value will be different from the input flag parameter. if none is granted, a zero is returned. name description handlerflag flag to indicate which of the handler the caller is releasing. ? irpt_spim_flag ? irpt_spis_flag(dragonball only) ? irpt_uart_flag ? irpt_irq1_flag ? irpt_irq2_flag ? irpt_irq3_flag ? irpt_irq6_flag ? irpt_int_flag ? irpt_wdog_flag ? irpt_pwm_flag ? irpt_user_flag name description ppsm_ok successful operation ppsm_err_release unable to release handler personal portable system manager programmers manual interrupt handling tools 29-1 chapter 29 interrupt handling tools 29.1 irptgetdata syntax status irptgetdata (p_u32 sdata , p_u32 *data , p_u32 size ) description this tool reads the applications interrupt buffer for any pending interrupt message. the interrupt source of the message and data collected from the interrupt handler is returned. each application has its own unique interrupt buffer. the data returned from this routine depends on the nature of the interrupt type. different messages from different interrupt sources represent different types of data. the pre-defined format for the data generated by system interrupts are listed below. the size of the data collected during an interrupt event is returned in the last argument size . it is in number of byte. ppsm does not impose any format or protocol for message data generated from user defined handlers since such data is programmable by the system integrator. parameter return value *sdata *(*data) *size irpt_audio n/a u16 - audio_stop_wave or audio_stop_tone 2 irpt_hwr n/a u16, .... - list of candidates 2 x no. of candidat es irpt_icon u32 - areaid u16 - ppsm_icon_touch or ppsm_icon_drag or ppsm_icon_pen_up or ppsm_icon_drag_up 2 irpt_input_ status u32 - areaid u16 - ppsm_input_touch or ppsm_input_drag or ppsm_input_pen_up or ppsm_input_drag_up 2 irpt_key n/a text, s16, s16 - keycode, (x, y) 6 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
29-2 interrupt handling tools personal portable system manager programmers manual return value irpt_pen u32 - areaid s16, s16 - (x, y) 4 irpt_rtc u32 - timerid n/a 0 irpt_timer u32 - timerid n/a 0 irpt_uart n/a u16, u16 - uart_error, uart_err_tmout or uart_err_frame or uart_err_parity or uart_err_overrun or uart_err_nodata or u16 - uart_data_received or uart_data_sent 4 2 irpt_user user defined user defined user defined name description irpt_audio indicating audio stopped irpt_error invalid function parameter irpt_hwr handwriting recognition interrupt irpt_icon pen input on icon active area interrupt irpt_input_status pen action status for pen input irpt_int int0-int7 user defined handler irpt_irq1 irq1 user defined handler irpt_irq2 irq2 user defined handler irpt_irq3 irq3 user defined handler irpt_irq6 irq6 user defined handler irpt_key external and soft keyboard interrupt irpt_none no application interrupt has occur irpt_pen pen input on application active area interrupt irpt_pwm pwm user defined handler irpt_rtc real time clock interrupt return value *sdata *(*data) *size personal portable system manager programmers manual interrupt handling tools 29-3 29.2 irptrelease syntax status irptrelease (u32 handlerflag ) description this tool is used by the application to release an interrupt handler that the caller has successfully requested previously. the interrupt handler that is being released must be a valid handler that has been granted to the application via the irptrequest() tool. if a handler that the application has no hook to is being requested for release, an error message will be returned. when a handler is released, any data or message still pending in the interrupt handler is flushed out and removed. once an interrupt handler is released, ppsm can then grant the handler to other applications that request for the handler. the application should release the handlers one at a time. irpt_spim spi master user defined handler irpt_spis spi slave user defined handler(dragonball only) irpt_timer preset timer interrupt irpt_uart uart user defined handler irpt_user user defined handler irpt_wdg watchdog user defined handler name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
30-2 system tools personal portable system manager programmers manual parameter return value name description calibration flag to indicate if touch panel calibration is required. ? true - do pen calibration ? false - do not do pen calibration name description ppsm_ok successful operation ppsm_err_no_memory not enough memory ppsm_error initialization failed figure 29-1 standard motorola logo personal portable system manager software licensed ? 1995-1998 motorola inc . by motorola semiconductor h.k. ltd. figure 29-2 small motorola logo personal portable system manager programmers manual interrupt handling tools 29-5 a request is successful if and only if the handler being requested has not been granted to another task. parameter return value name description handlerflag flag to indicate which of the handlers the caller is requesting. each bit of this flag represents a specific handler. the following flag values can be ored together if more than one handler is being requested: ? irpt_spim_flag ? irpt_spis_flag(dragonball only) ? irpt_uart_flag ? irpt_irq1_flag ? irpt_irq2_flag ? irpt_irq3_flag ? irpt_irq6_flag ? irpt_int_flag ? irpt_wdog_flag ? irpt_pwm_flag ? irpt_user_flag name description n/a returns the handlers that has/have been granted. each bit in the returned 16-bit word represents a specific handler: ? irpt_spim_flag ? irpt_spis_flag(dragonball only) ? irpt_uart_flag ? irpt_irq1_flag ? irpt_irq2_flag ? irpt_irq3_flag ? irpt_irq6_flag ? irpt_int_flag ? irpt_wdog_flag ? irpt_pwm_flag ? irpt_user_flag f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
29-6 interrupt handling tools personal portable system manager programmers manual 29.4 irptsenddata syntax status irptsenddata (u16 irpttype, u32 sdata, p_u32 data, u32 size ) description passes the user defined interrupt message from interrupt handler back to application level. this routine should be called from the user installed interrupt handler only. after this message is sent from the interrupt handler, the application that has requested the handler will be able to receive this message via the irptgetdata() tool. parameter return value name description irpttype interrupt identifier: ? irpt_spim ? irpt_spis(dragonball only) ? irpt_irq1 ? irpt_irq2 ? irpt_irq3 ? irpt_irq6 ? irpt_int ?irpt_wdog ? irpt_pwm ? irpt_user sdata this field can be used to send 4 bytes or less data to the application data data buffer for storing data to send to the application size the size of data being sent, in number of bytes name description ppsm_ok successful operation ppsm_err_irpt_handler handler not requested by application ppsm_no_memory not enough memory personal portable system manager programmers manual system tools 30-1 chapter 30 system tools 30.1 ppsminit syntax status ppsminit (u16 calibration ) description ppsm initialization routine. this routine must be called at the beginning of the system file before any of the ppsm tools can be used. the input argument allows the system caller to decide if pen calibration is required at this time. with the default calibration device driver, two cross-hairs will be drawn on the screen, one near the top-right corner and the other near the bottom-left corner. the user must press the center of these cross-hairs one at a time to perform the pen input calibration. the default calculation value is based on a lcd that has 320 pixels by 240 pixels (physical sizes 12 cm by 9 cm), using a 10-bit a/d convertor. an offset of 100 (in a/d output unit) is chosen as the a/d non-linear area around the edge of the touch panel. user may define his own calibration method by changing calibratepen() in peninit.c of the device driver library. if logo displaying is required, a motorola logo will be displayed on the lcd screen during the pen calibration. depending on the physical lcd screen dimensions, a different logo is displayed. there are 2 logos, one for a large screen, one for a small screen. if the lcd screen width is less than 150 pixels or the lcd height is less than 80 pixels, no logo is displayed. width (pixels) height (pixels) motorola logo width => 280 height => 150 standard logo 150 <= width < 280 80 <= height < 150 new small logo width < 150 height < 80 none f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
31-2 audio tools personal portable system manager programmers manual 31.2 audioinuse syntax u8 audioinuse (void) description it checks if ppsm audio tools are currently being used. parameter return value 31.3 audioplaytone syntax status audioplaytone (p_u16 tonedata, u32 tonesize, u16 toneduration, u8 autorepeat) description ppsm plays a sequence of different tone frequencies with each tone frequency having a fixed duration. parameter name description none name description audio_off ppsm audio tools are not being used wave_in_use ppsm wave play back audio tool is being used tone_in_use ppsm tone play back audio tool is being used name description tonedata the pointer to the tone frequency sequence, with frequency between 31hz and 4048hz tonesize total number of tone frequencies to play. personal portable system manager programmers manual system tools 30-3 30.2 readsmversion syntax status readsmversion (p_u32 major , p_u32 minor ) description returns ppsm major and minor version number. for example, for version 3.0, major number will be 3 and minor number will be 0. parameter return value name description major returns the ppsm major version number minor returns the ppsm minor version number name description ppsm_ok successful operation ppsm_err_no_memory invalid input memory pointer f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
30-4 system tools personal portable system manager programmers manual personal portable system manager programmers manual audio tools 31-1 chapter 31 audio tools 31.1 advaudioplaywave (dragonball-ez only) syntax status advaudioplaywave (p_u8 wavedata, u32 wavesize, u8 prescaler, u8 repeat, u8 clksel) description this tool is valid for dragonball-ez only. this tool plays back a pcm audio wave signal. this is similar to the tool audioplaywave() but with advanced configuration details. it allows the caller to specify: ? the value of prescaler in the pwm module of dragonball-ez ? the repeat rate of the audio. ? the clksel in the pwm module of dragonball-ez this tool assumes the user has solid knowledge of the dragonball-ez pwm module. for most cases, audioplaywave should be used. parameter return value name description wavedata the pointer to the pcm audio wave signal wavesize total number of data bytes occupied by the audio signal prescaler bit 14~8 of the pwm control register, value from 0 to 127 repeat bit 2,3 of the pwm control register, value from 0 to 3 clksel bit 0,1 of the pwm control register, value from 0 to 3 name description ppsm_ok successful operation ppsm_err_audio_regs invalid values for prescaler, repeat or clksel ppsm_err_audio_inuse the pwm module is being used by another task f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
31-6 audio tools personal portable system manager programmers manual personal portable system manager programmers manual audio tools 31-3 return value 31.4 audioplaywave (dragonball-ez only) syntax status audioplaywave (p_u8 wavedata, u32 wavesize, u8 samplingrate) description this tool is for dragonball-ez only. ppsm plays back a pcm audio wave signal with requested sampling rate. parameter toneduration the duration of each tone frequency for dragonball-ez ? tone_dur_512hz ? tone_dur_256hz ? tone_dur_128hz ? tone_dur_64hz ? tone_dur_32hz ? tone_dur_16hz ? tone_dur_8hz ? tone_dur_4hz for dragonball 0 to 1000, length of duration in number of milliseconds. autorepeat if auto-repeat is needed or not 0 - no autorepeat. 1 - autorepeat. name description ppsm_ok successful operation ppsm_err_audio_inuse the pwm module is being used by another task ppsm_err_audio_tonedur invalid tone duration the requested rtc-sampling interrupt is already being used(this only happens on the mc68ez328) name description wavedata the pointer to the pcm audio wave signal name description f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
31-4 audio tools personal portable system manager programmers manual return value 31.5 audiostoptone syntax status audiostoptone (void) description terminates the tone playing. parameter return value 31.6 audiostopwave (dragonball-ez only) syntax status audiostopwave (void) wavesize total number of data bytes occupied by the audio signal samplingrate the requested sampling rate ? sampling_32khz ? sampling_16khz ? sampling_11khz ? sampling_8khz ? sampling_4khz name description ppsm_ok successful operation ppsm_err_audio_inuse the pwm module is being used by another task. name description none name description ppsm_ok successful operation ppsm_err_audio the audio tool is not playing tone name description personal portable system manager programmers manual audio tools 31-5 description terminates the wave playing. parameter return value name description none name description ppsm_ok successful operation ppsm_err_audio the audio tool is not playing wave f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
32-2 how to make rom? personal portable system manager programmers manual 32.1.1.1 rom_reset this is used to map the 68k first 256 locations. in the boot strap code, it is defined as: section rom_reset ; section declaration dc.l mon_stacktop ; stack address for boot code dc.l rom_start-romaddr ; absolute address of boot code dcb.l 254,0 ; interrupt vector space the labels mon_stacktop and rom_start declared in this region are resolved with their absolute address only during link time. this implementation makes the values for these locations dynamic and system integration can be independent to the absolute location and size of the hardware system. romaddr is declared in the linker specification file. 32.1.1.2 rom_code this regions is declared to store the boot strap code. because this code is not part of ppsm library, they are declared and executed in the beginning of the memory map to avoid memory conflict. the first line of this region must declare the label rom_start. this is required by the region rom_reset to work out the pc start address. the last line of this region should be a " jmp start" instruction. this is used to start ppsm start-up code. the label start is pre-defined as the start location for the startup code. figure 30-1 memory map for boot strap code 0x000 0x008 pc/stack vectors 0x400 0x1000 boot strap code ppsm application tasks rom_reset rom_code personal portable system manager programmers manual part iv system integrators guide f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
personal portable system manager programmers manual personal portable system manager programmers manual how to make rom? 32-1 chapter 32 how to make rom? to make ppsm applications into rom code, two items are needed which are different from running ppsm applications using ram memory version. these two items are: ? boot strap code ? linker specification file for rom this chapter gives some description of how to make a rom code version of ppsm applications. 32.1 boot strap code (boot.s) the boot strap code performs the following functions: ? starts the 68k core upon reset ? map the chip-selects of mc68328 to run on a particular hardware platform ? initialization of peripheral devices on the mc68328 ? jump into ppsm start-up code depending on the size and address of rom that are used, the chip selects inside boot.s need to be changed accordingly. 32.1.1 68k start-up in 68k architecture, the first 256 locations in the memory address space, 0x0 to 0x400, are reserved for system vector usage and cannot be over-written with random values. the first two 32-bit words locations (address 0x00 and 0x04) are defined for the start program counter address and the stack address upon power reset. in order to make this assignment of addresses re-locatable at link time, rather than hard-coding the addresses at compilation time, two new regions, rom_reset and rom_code, are defined by ppsm in the linker specification file to perform the mapping. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
32-6 how to make rom? personal portable system manager programmers manual personal portable system manager programmers manual how to make rom? 32-3 32.1.2 chip selects for the m68328ads development board, chip-select group a is used for rom and chip-select group b is used for ram. please refer to the mc68328 integrated processor users manual, mc68328um/ad, for details on chip select programming. 32.1.3 peripheral devices initialization of the peripherals such as default interrupt vector, watchdog and lcd controller. please refer to the mc68328 integrated processor users manual, mc68328um/ad, for details on chip select programming. 32.2 linker supplications file for rom the linker supplications file for rom is different to that for ram system. the main difference being that some of the defined regions need to go into rom address, and some regions need to go into ram address. in general, regions that are read-only, such as constants, strings and code, go into rom area; while read/write regions, such as ram, stack and heap space go into ram area. the listing below shows an example of such spc file. example 30-1 linker specification file example for rom partition { overlay { region {} rom_reset[addr=0x0];/* reset vector in rom */ region {} rom_code[addr=0x400];/* start of bootstrap code */ region {} code[addr=0x1000]; /* start of application code */ region {} const; /* constant data */ region {} string; /* constant strings */ data = $; /* pre-defined constants for initialized variables */ lcdphyswidth = 320; /* lcd display width */ lcdphysheight = 240; /* lcd display height */ lcdvirtwidth = 640; /* lcd virtual width */ lcdvirtheight = 480; /* lcd virtual height */ uartrcvbuf = 256; /* system uart receive buffer size(in #bytes) */ } area2; } rom[addr=0x400000,size=0x100000];/* 1m byte rom */ partition { overlay { region {} data[addr=0x400]; /* initialized on reset */ region {} ram[roundsize=4]; /* zeroed on reset */ region {} malloc[size=0x80000];/* malloc space */ region {} stack[size=0x4000];/* stack */ stktop = $; /* sp reset value */ } area1; } ram[addr=0x0, size=0x100000];/* 1m byte ram */ in this example, a system that has 1 mbyte of rom space mapped from address location 0x400000 and 1 mbyte of ram memory mapped from address location 0x0 has the following characteristics: ? the rom area starts at base address 0x400000 ? the region rom_reset starts from offset 0x0 from the rom base address, which is 0x400000 ? the region rom_code starts from offset 0x400 from the rom base address, which is 0x400400 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
32-4 how to make rom? personal portable system manager programmers manual ? as much executable code space in rom as required, round to 4- byte boundary starting from 0x401000 ? as much constant data space in rom as required, round to 4-byte boundary ? as much constant strings space in rom as required, round to 4- byte boundary ? data symbol to point to the downloadable address of the initialized constants to pre-initialized variables ? a lcd physical display screen of 320 pixels wide by 240 pixels high ? a panning screen of 640 pixels wide by 480 pixels high ? a 256 byte internal uart receive buffer ? the ram area starts at base address 0x0 ? as much initialized data space as required starting from an offset of 0x400, round to 4-byte boundary ? as much zeroed uninitialized data space as required, round to 4- byte boundary ? 512 kbyte of heap space for dynamic memory allocation ? 128 kbyte of stack space for system context switching ? a stktop symbol to point to the address of the 128 kbyte stack 32.3 generating s-record file after the ppsm application has linked with the rom spc file, the sds tools generates an output file in a proprietary format that is not suitable to download to roms. sds provides a tool, the loader tool, that allows the conversion from this output file into s-record format. 32.3.1 loader options to convert .out file into s-record file, the following options are used: options -d mot generate motorola s-record format output file -o \.dwn the full name of the output file -m data, data copy the initial values of initialized data into rom area -w

generate s-record with offset

which is the base address of rom personal portable system manager programmers manual how to make rom? 32-5 32.3.2 loader commands example 30-2 loader command down -d mot sample.out -m data, data -o sample.dwn -w 0x400000 this will convert the sample.out to s-record format named sample.dwn which will be burned into rom address of 0x400000. example 30-3 loader command down -d mot sample.out -m data, data -o sample.dwn this will convert the sample.out to s-record format named sample.dwn which will be burned into rom address of 0x0. convert .out file format to motorola s-record format down -d mot .out -m data, data -o \.dwn -w

f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
33-4 device drivers personal portable system manager programmers manual 33.2.1 pen initialization syntax void pendevinit (void) description this function initializes spi master and all the ports that are used for pen sampling. m68328ads implementation: port j is used to control the transistor network connected to the touch panel. the default initialization values for port j are to set all pins to be output i/o pins. for spi master, the control register, 0xfff802, is set for the following: m68ez328ads implementation: ads version q3 q4 q5 q6 cs m68328ads pj3 pj1 pj2 pj0 pj7 m68ez328ads pd3 pd1 pd2 pd0 pe3 table 31-2 port j assignment port j address bit 7 bit 6 bit 5 bit 4 bit 3 bit 2 bit 1 bit 0 direction register 0xfff428 1 x x x 1111 select register0xfff42b1xxx1111 table 31-3 spim assignment spim control register, 0xfff802 bit position default value (binary) data rate 15 - 13 0 1 0 spim enable 9 1 exchange bit 8 0 spim interrupt enable 6 1 phase shift 5 0 polarity 4 0 clock count 3 - 0 1 1 1 1 personal portable system manager programmers manual device drivers 33-1 chapter 33 device drivers ppsm supports device drivers that are either hardware dependent or third-party vendor dependent. these device drivers include: ? system configuration drivers ? pen input driver ? lcd driver ? handwriting recognition driver ? font driver ? uart driver in compilation, pixel_1 or pixel_2 needs to be defined so that the corresponding device driver library will be created. 33.1 system configuration drivers there are 2 system configuration drivers: ? boot strap driver ? interrupt handler installation for the mc68328. 33.1.1 boot strap driver (boot.s) description the boot strap code is responsible for initialization of the mc68328 internal devices and to map chip-selects for the rom and ram of the hardware system at boot time. different hardware memory configuration and system requires different boot strap code. an example boot strap code is included in ppsm device driver library to demonstrate how to boot strap and initialize the chip- selects for the m68328ads system. please refer to chapter 34 - linker specification file and chapter 35 - trap usage in ppsm for more details on hardware configuration mapping. for hardware characteristics of the mc68328 processor, please refer to the mc68328 integrated processor users manual, mc68328um/ad . 33.1.2 user interrupt handler installation driver (irptdev.c) description this interrupt handler device driver allows users to install their own interrupt handlers for certain kinds of interrupt. users can replace the default handler with their interrupt handler in the device driver to perform exception handling. since ppsm does not manage or monitor these user-defined handlers, care must be taken when installing them. please f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
33-2 device drivers personal portable system manager programmers manual refer to chapter 15 - interrupt handling and chapter 29 - interrupt handling tools for details on interrupt handling. please refer to the mc68328 integrated processor users manual, mc68328um/ad , for details on the interrupt controller. a single argument is passed into the interrupt handler. this argument is supplied by ppsm system to specify the address of the stack pointer just before calling the user-defined interrupt handler. table 31-1 shows the locations of the registers relative to this stack address. m68328ads implementation: these interrupt handlers perform no operation and return to the interrupted application immediately. in general, _uartirpthandler() will not be executed. for ppsm source licensee, a "-dno_uart_handler" option can be used in compiler option to indicate that the internal uart interrupt handler is not used and this _uartirpthandler() is used instead. table 31-1 interrupt stack layout d0 - d7 a0 - a6 a7 pc argument is the address that points to here -> sr (16-bit) the following functions are the user defined interrupt handlers: void _spimirpthandler(p_u32 stackptr) spi master void _spisirpthandler(p_u32 stackptr) spi slave(not available in ez) void _irq6irpthandler(p_u32 stackptr) irq6 void _uartirpthandler(p_u32 stackptr) uart void _watchdogirpthandler(p_u32 stackptr) watch dog timer void _keyboardirpthandler(p_u32 stackptr) keyboard void _pwmirpthandler(p_u32 stackptr) pulse width modulator void _intirpthandler(p_u32 stackptr) int0-int7 void _irq3irpthandler(p_u32 stackptr) irq3 void _irq2irpthandler(p_u32 stackptr) irq2 void _irq1irpthandler(p_u32 stackptr) irq1 personal portable system manager programmers manual device drivers 33-3 33.2 pen input device driver (pendev.c) figure 31-1 shows the configuration of the hardware used in m68328ads for the pen input device: ? 4 i/o pins on port j, pj0 to pj3, are used to control the transistor network. ? i/o pin 7 on port j, pj7, is used to control the chip-select on the a/ d convertor. ? the spi master rxd line is connected to the a/d convertors digital output for the sample result. please refer to the m68328ads users manual for details on the operation of the hardware configuration. there are 4 functions in this driver: ? pen initialization ? pen interrupt enable ? pen interrupt disable ? pen read device for m68ez328ads, the pen input device driver is similar as above, but it uses port d and e instead of port j in m68328ads. q6 q3 q4 q5 pj0 pj2 pj1 pj3 an0 an1 pj0 pj1 pj2 pj3 0110 q6 q4 q5 q3 on on off off pj0 pj1 pj2 pj3 1001 q6 q4 q5 q3 off off on on x position y position vcc vcc pj7 cs a/d spimrxd dout penirq figure 31-1 transistor network for pen sampling f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
33-8 device drivers personal portable system manager programmers manual for x sampling, the transistors q4 and q6 needs to be on while transistors q3 and q5 are off, see figure 31-1 , i.e. set port d data register, to 0xf9. while the transistors are in this setting, port e pin 3 is asserted to activate the a/d convertor for the sampling. the digital value returned from the a/d convertor is stored in the spi data register. for y sampling, the procedure is the same as x sampling except that the transistors q3 and q5 needs to be on while transistors q4 and q6 are off, see figure 31-1 , i.e. set port d data register, to 0xf6. the x and y samples thus obtained are returned to the caller in the pointer arguments passed in by the caller. 33.3 pen calibration(peninit.c) user normally needs to do calibration once the system startup time, in order to do a correct mapping between touch panel coordination and screen display coordination. the system needs to have at least the upper-left and bottom-right corner of the touch panel coordinate in terms of the screen display coordinate to do this coordinate mapping. syntax status calibratepen( u16 logoflag) description when pen calibration is necessary, ppsm calls this routine. user can replace the default pen calibration algorithm with their own. at the end of this device driver routine, the origin and maximum point of the touch panel (in terms of display screen coordinate) should be fed back to ppsm by calling pensetinputmax(x, y) and pensetinputorg(x, y). by default, the motorola logo is displayed and two cross-hair, at the upper right and the bottom left corners, are used for pen calibration. 33.4 lcd device drivers (lcddev.s) two functions are needed in this driver for lcd controller initialization to drive the lcd panel being used in the system. only one of the following initialization functions will be called according to the graphics mode desired. 33.4.1 1 bit/pixel initialization syntax void _lcddev1 (void) description this function initializes the lcd controller for 1 bit/pixel graphics mode. application programmer may add whatever statement to initialize the lcd personal portable system manager programmers manual device drivers 33-5 port d and e are used to control the transistor network connected to the touch panel. the default initialization values for d port is to set all pins to be output i/ o pins. port e3 is initialized to enable the a/d converter while pe0, pe1, pe2 are initialized to spm function pins (spmtxd, spmrxd, spmclk respectively). for spi master, the control register, 0xfff802, is set for the following: 33.2.2 pen interrupt enable syntax void penirptenable (void) description this function enables the pen interrupt, penirq , for pen down detection. table 31-4 port d assignment port d address bit 7 bit 6 bit 5 bit 4 bit 3 bit 2 bit 1 bit 0 direction register 0xfff418 xxxx 1111 select register 0xfff419 xxxx 1111 pullup register0xfff41axxxx 1111 select register0xfff41bxxxx 1111 polarity 0xfff41cxxxx 0000 int enable 0xfff41dxxxx 0000 int edge 0xfff41exxxxxxxx table 31-5 spim assignment spim control register, 0xfff802 bit position default value (binary) data rate 15 - 13 0 1 0 spim enable 9 1 exchange bit 8 0 spim interrupt enable 6 1 phase shift 5 0 polarity 4 0 clock count 3 - 0 1 1 1 1 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
33-6 device drivers personal portable system manager programmers manual m68328ads implementation: port m pin 6 is assigned as the penirq pin. to enable penirq , the following sequence is required: ? enable port m pin 6 pull-up resistor ? discharge the transistor network such that all vcc are on, ground are off, i.e. set port j data register, 0xfff439, to 0xf0 ? charge up the transistor that is connected to penirq , i.e. set port j data register, 0xfff439, to 0x0d ? switch port m pin 6 to interrupt pin, i.e. set port m selector register, 0xfff448, bit 6 to 0 ? enable interrupt mask register, 0xfff304, bit 20 for interrupt please refer to the m68328ads users manual for details on transistor network switching. m68ez328ads implementation: irq5(port f1) is assigned as the penirq pin. to enable penirq , the following sequence is required: ? enable port f pin 1 pull-up resistor ? discharge the transistor network such that all vcc are on, ground are off, i.e. set port d data register, to 0xf0 ? charge up the transistor that is connected to penirq , i.e. set port d data register, to 0x0d ? switch port f pin 1 to interrupt pin, i.e. set port f selector register, bit 1 to 0 ? enable interrupt mask register, bit 20 for interrupt please refer to the m68ez328ads users manual for details on transistor network switching. 33.2.3 pen interrupt disable syntax void penirptdisable (void) description this function disables the pen interrupt, penirq . m68328ads implementation: port m pin 6 is assigned as the penirq pin. to disable penirq , the following sequence is required: ? disable interrupt mask register, 0xfff304, bit 20 for interrupt ? switch port m pin 6 to i/o pin, i.e. set port m selector register, 0xfff448, bit 6 to 1 ? disable port m pin 6 pull-up resistor. if not switched off, it will interfere with a/d sampling personal portable system manager programmers manual device drivers 33-7 ? discharge the transistor network such that all vcc are on, ground are off, i.e. set port j data register, 0xfff439, to 0xf0 ? switch transistor network to idle mode, i.e. set port j data register, 0xfff439, to 0x05 please refer to m68328ads users manual for details on transistor network switching. m68ez328ads implementation: irq5 is assigned as the penirq pin. to disable penirq , the following sequence is required: ? disable interrupt mask register, bit 20 for interrupt ? switch port f pin 1 to i/o pin, i.e. set port f selector register, bit 1 to 1 ? disable port f pin 1 pull-up resistor. if not switched off, it will interfere with a/d sampling ? discharge the transistor network such that all vcc are on, ground are off, i.e. set port d data register, to 0xf0 ? switch transistor network to idle mode, i.e. set port d data register, to 0x05 please refer to m68ez328ads users manual for details on transistor network switching. 33.2.4 pen read device syntax void penreaddevice (p_s16 x , p_s16 y ) description this function returns a reading for x and y to the caller and switches the transistor network accordingly for reading x and y. m68328ads implementation: for x sampling, the transistors q4 and q6 needs to be on while transistors q3 and q5 are off, see figure 31-1 , i.e. set port j data register, 0xfff439, to 0xf9. while the transistors are in this setting, port j pin 7 is asserted to activate the a/d convertor for the sampling. the digital value returned from the a/d convertor is stored in the spim data register, 0xfff800. for y sampling, the procedure is the same as x sampling except that the transistors q3 and q5 needs to be on while transistors q4 and q6 are off, see figure 31-1 , i.e. set port j data register, 0xfff439, to 0xf6. the x and y samples thus obtained are returned to the caller in the pointer arguments passed in by the caller. m68ez328ads implementation: f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
33-12 device drivers personal portable system manager programmers manual 33.6.1 font library information a data structure type fontlib is required to store information about the font libraries being used. the fontlib type is defined as follow: typedef struct { p_u8 baseaddr; u16 fonttype; u16 fontwidth; u16 fontheight; u16 bitmapsize; } fontlib, *p_fontlib; where: 1) baseaddr is the base address of the font bitmap library 2) fonttype is the font type to be used for font look-up or generation 3) fontwidth is the width of the font bitmap of a character in number of pixels 4) fontheight is the height of the font bitmap of a character in number of pixels 5) bitmapsize is the amount of memory occupied by one character font bitmap in unit of bytes assuming there is font bitmap or font generation engine available for each font type, the default font library information data structure could be initialized as follow: fontlib fontlib[] = { {(p_u8)small_eng_font_addr, small_normal_font, 8, 10, 10}, {(p_u8)small_eng_font_addr, small_italic_font, 8, 10, 10}, {(p_u8)large_eng_font_addr, large_normal_font, 16, 20, 40}, {(p_u8)large_eng_font_addr, large_italic_font, 16, 20, 40}, {(p_u8)gb_font_addr, gb_normal_font, 16, 16, 32}, {(p_u8)bitmap_big5_font_addr, big5_normal_font, 16, 16, 32}, {(p_u8)scalable_big5_font_addr, default_scalable_font, 16, 16, 32} }; the fontlib data structure above are indexed into by the corresponding ppsm font types. 33.6.2 font library or font generation engine initialization syntax void fontinit (void) description this function initializes the font libraries and font generation engines, if applicable. this function will be called at ppsm initialization time. note: font bitmaps libraries usually do not require any initialization, whereas font generation engines do. therefore, when applicable, this driver function should call an initialization personal portable system manager programmers manual device drivers 33-9 module. generally, lcd panel is polarity dependent which can be set in move.b #$00,$21(a0) in lcddev.s to be adjusted for individual lcd panel. 33.4.2 2 bits/pixel initialization syntax void _lcddev2 (void) description this function initializes the lcd controller for 2 bits/pixel graphics mode. application programmer may add whatever statement to initialize the lcd module. generally, lcd panel is polarity dependent which can be set in move.b #$00,$21(a0) in lcddev.s to be adjusted for individual lcd panel. please refer to the mc68328 integrated processor users manual, mc68328um/ ad , for details on the lcd controller and the registers definitions. m68328ads implementation: _lcddev1 initializes the following registers: ? panel interface configuration register (picf) for a 4-bit lcd panel bus size and no gray scale ? pixel clock divider register (pxcd) to divide the clock source by 3 ? polarity configuration register (polcf) to the characteristics of the lcd panel used _lcddev2 initializes the following registers: ? panel interface configuration register (picf) for a 4-bit lcd panel bus size with gray scale enabled ? pixel clock divider register (pxcd) to use the system clock directly ? gray palette mapping register (gpmr) to gray scale intensity of 0x3075 ? polarity configuration register (polcf) to the characteristics of the lcd panel used 33.5 handwriting recognition engine driver (hwr.c) this driver is required for providing a common api in ppsm for recognizing handwriting input while supporting various third party handwriting recognition engines. the driver functions are needed by the character input tools when handwriting recognition input is called for. this driver consists of four functions as described in the following sections. 33.5.1 handwriting recognition engine reset syntax f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
33-10 device drivers personal portable system manager programmers manual void resetrecengine (void) description this function resets the handwriting recognition engine to its default state. this function should call a reset function (if any) provided by the handwriting recognition engine. in some cases, resetrecengine() may perform the same functions as initrecengine() ( section 33.5.2 - handwriting recognition engine initialization ). this function is called once when initializing the character input pad during the call of openinputpad(). 33.5.2 handwriting recognition engine initialization syntax void initrecengine (void) description this function initializes or installs the handwriting recognition engine. this function should call an initialization function (if any) provided by the handwriting recognition engine and set up data structures required by the engine for the recognition process. this function is called once at ppsm initialization time. 33.5.3 process one stroke of handwriting input data syntax void processstroke (u16 numpoints , p_point strokedata , u32 inputareaid ) description this function processes one stroke of handwriting input data collected by the system. based on the input parameters, this function should convert the handwriting data for one stroke of input (if necessary) into the format being acceptable by the corresponding handwriting recognition engine. the reformatted stroke data should then be sent to the handwriting recognition engine (by calling a function provided in the handwriting recognition engine) for pre-processing or optimization before the actual handwriting recognition is initiated. this function is called for every stroke of data collected. personal portable system manager programmers manual device drivers 33-11 parameter 33.5.4 initiate character recognition for the handwriting input syntax void recognizeinput (p_u16 numcandidates , p_text * candidates ) description this function performs the character recognition of the handwriting input. this function should call a character recognition function provided in the handwriting recognition engine which initiates the recognition of the pre- processed stroke data collected so far. the character recognition function is expected to return to the driver function the number of character candidates being recognized, and the character codes for these candidates. this function is called if the pen points to other character input box or there is an input time-out. return value note: since ppsm does not include a specific handwriting recognition engine, the driver functions mentioned above are default to perform no operation. 33.6 font driver (font.c) this driver is required for providing a common api in ppsm for font look-up while supporting multiple font technologies and libraries supplied by various third party vendors. the font driver consists of a data structure and two functions. name description numpoints the number of points in a stroke strokedata a pointer to a list of xy-coordinates that make up the stroke inputareaid an id of the input box in which the stroke data is collected. (i.e. the identifier of the active area for the input box) name description numcandidates the number of character candidates candidates a pointer to a list of the character codes for the candidates f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
33-16 device drivers personal portable system manager programmers manual return value note: the driver function mentioned above is default to perform no operation. 33.8.4 disabling i/o ports when going to sleep mode syntax void portsleepdisable (void) description just before ppsm goes into sleep mode, it will call this routine to disable any user defined i/o ports that are not handled internally by ppsm. user must add in the code to disable the i/o ports in this routine. return value note: the driver function mentioned above is default to perform no operation. name description none name description none personal portable system manager programmers manual device drivers 33-13 routine provided by the font generation engine. since ppsm does not include a specific font generation engine, this driver function is default to perform no operation. 33.6.3 font accessing syntax p_u8 fontgetcharaddr (p_fontattr pfont , text code ) description this function returns the font bitmap of a character based on the given font attributes and character code. please refer to section 8.4.3 - setting font attributes for the explanation of the fontattr data structure. font lookup or generation algorithms are assumed to be provided by the font supplier. this driver function should call the lookup method for the corresponding font type, to get the font bitmap of the character described by the font attributes. since ppsm includes 8 x 10 and 16 x 20 ascii english fonts, the lookup method for mapping ascii codes to english bitmap fonts are provided. the font types that use this method are: ? small_normal_font ? small_italic_font ? large_normal_font ? large_italic_font parameter return value name description pfont pointer to a fontattr structure which describes the font code character code for which the font lookup or generation is performed name description n/a pointer to the bitmap of the character specified by the given character code (the bitmap is represented by unsigned 8-bit values f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
33-14 device drivers personal portable system manager programmers manual 33.7 uart device driver (uartdev.c) this uart device driver is a supplement to the ppsm serial communication tools as described in chapter 26 - uart communication tools . currently this driver contains the uartdevsendbreak() function which allows applications to send the break character. this uartdevsendbreak() function manipulates the mc68328 uart hardware registers. it is assumed that the saving, setting and restoring of appropriate system interrupt level is handled by the caller of this device driver. 33.7.1 sending the break character syntax void uartdevsendbreak (u8 sendbreak ) description this function starts or stops the mc68328 uart hardware to send the break character depending on the given flag. if sendbreak flag is uart_send_break, the uart hardware will start sending the break character. if sendbreak flag is uart_abort_break, the uart hardware will stop sending the break character. it is assumed that sendbreak has to be one of the values stated. any other value will be treated as uart_abort_break. parameter return value 33.8 power management driver (iodev.c) 4 functions are located in iodev.c for enabling or disabling i/o ports before going to doze or sleep mode or leaving doze or sleep mode. name description sendbreak operation flag ? uart_send_break starts sending break characters ? uart_abort_break stops sending break characters name description none personal portable system manager programmers manual device drivers 33-15 33.8.1 enabling i/o ports when leaving from doze mode syntax void portdozeenable (void) description when ppsm wakes up from doze mode, it will call this routine to re-enable any user defined i/o ports that are not handled internally by ppsm. user must add in their own i/o initialization code in this routine. return value note: the driver function mentioned above is default to perform no operation. 33.8.2 disabling i/o ports when going to doze mode syntax void portdozedisable (void) description just before ppsm goes into doze mode, it will call this routine to disable any user defined i/o ports that are not handled internally by ppsm. user must add in the code to disable the i/o ports in this routine. return value note: the driver function mentioned above is default to perform no operation. 33.8.3 enabling i/o ports when leaving from sleep mode syntax void portsleepenable (void) description when ppsm wakes up from sleep mode, it will call this routine to re-enable any user defined i/o ports that are not handled internally by ppsm. user must add in their own i/o initialization code in this routine. name description none name description none f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
34-4 linker specification file personal portable system manager programmers manual personal portable system manager programmers manual linker specification file 34-1 chapter 34 linker specification file ppsm makes use of the linker specification file (.spc file) of the sds development environment for memory mapping and configuration. this spc file defines the locations and contents of memory regions and allow user-defined symbols. it is written in a c-like language. for full details on linker specification files, please refer to the sds user manual. ppsm required a few user-defined symbols for it to operate. they are listed in table 32-1 . system integrators inform ppsm of the physical memory size available in a given hardware system using this linker specification file. ppsm maintains a stack and heap for memory usage in the application program. the system integrator must decide how much memory is to be given for the stack and heap. in general, the heap memory is used as the dynamic allocatable memory for application use, and the stack memory is mostly used by the system. for details on memory mapping, please refer to chapter 32 - how to make rom? . ppsm also maintains an internal uart receive buffer which is used as temporary storage for data received from the uart. the system integrator must decide what is the optimal buffer size for a given hardware system. 34.1 .spc file for a ram-only system following is an example of a spc file for a m68328ads with debug monitor rom (for sds use only) with 2 mbyte of ram for system use. this 2 mbyte ram-only system has the following characteristics: ? the ram system starts at address 0x0 ? 4 kbyte of reserved memory starting from address 0x0 for reset vectors and sds debug monitor use ? as much executable code space as required, round to 4-byte boundary ? as much constant data space as required, round to 4-byte boundary table 32-1 symbols definitions for linker specification file symbol name description lcdphyswidth lcd physical display screen width in pixels lcdphysheight lcd physical display screen height in pixels lcdvirtwidth lcd virtual screen (panning screen) width in pixels lcdvirtheight lcd virtual screen (panning screen) height in pixels uartrcvbuf internal uart receive buffer size in number of bytes f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
34-2 linker specification file personal portable system manager programmers manual ? as much constant strings space as required, round to 4-byte boundary ? as much initialized data space as required upon reset, round to 4- byte boundary ? as much zeroed memory space as required, round to 4-byte boundary ? 704 kbyte of heap space for dynamic memory allocation ? 128 kbyte of stack space for system context switching ? a stktop symbol to point to the top of the 128 kbyte stack ? a data symbol to point to the downloadable address ? a lcd physical display screen of 320 pixels wide by 240 pixels high ? a panning screen of 640 pixels wide by 480 pixels high ? a 256 byte internal uart receive buffer ? 2 mbyte of ram example 32-1 linker specification file example partition { overlay { region {} reset[addr=0,size=0x1000];/* reset vector */ region {} code[roundsize=4];/* executable code */ region {} const[roundsize=4];/* constant data */ region {} string[roundsize=4];/* constant strings */ region {} data[roundsize=4];/* initialized on reset */ region {} ram[roundsize=4];/* zeroed on reset */ region {} malloc[size=0xb0000];/* malloc space */ region {} stack[size=0x20000];/* stack */ stktop = $;/* sp reset value */ data = $; /* data download addr */ lcdphyswidth = 320;/* lcd display width */ lcdphysheight = 240;/* lcd display height */ lcdvirtwidth = 640;/* lcd virtual width */ lcdvirtheight = 480;/* lcd virtual height */ uartrcvbuf = 256; /* system uart receive buffer size(in #bytes) */ } example; } ram[addr=0x0, size=0x200000] 34.2 .spc file for a rom-ram system the .spc file for a rom-ram system consists of two partitions. one partition for the rom layout and one partition for the ram layout on the system. please refer to chapter 32 - how to make rom? for a specific example of a .spc file for such a system. 34.3 for singlestep debugging system (sds) user one of the methods to find out the optimum size specified in the malloc field in the .spc file will be shown below. this method may not be applicable to other debugging system. 1) first of all, we set the ram size to 2 m, so as the malloc size. for example, partition { overlay { region {} reset[addr=0x0]; /* reset vector */ ..... personal portable system manager programmers manual linker specification file 34-3 region {} malloc[size= 0x200000 ]; /* malloc space */ ...... } example; } ram[addr=0x400000, size= 0x200000 ]; 2) following error messages will be generated after linking: linker: error: actual 'ram' size ( 0x21f762 ) is larger than specified size linker: error: overlay 'example' is larger than the partition containing it nmake : fatal error u1077: 'linker' : return code '0x1' stop. 3) then, we can calculate the optimum malloc size by subtracting exceeding bytes from the total memory size: 0x200000 - 0x1f762 = 0x1e089e 4) finally, we can write the optimum size in the malloc field: partition { overlay { region {} reset[addr=0x0]; /* reset vector */ ..... region {} malloc[size= 0x1e089e ]; /* malloc space */ ...... } example; } ram[addr=0x400000, size=0x200000]; 5) this optimum malloc size needed to be found again after modified source code by similar method. this size is recommended to be found after debugging stage. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
35-8 trap usage in ppsm personal portable system manager programmers manual personal portable system manager programmers manual trap usage in ppsm 35-5 chapter 35 trap usage in ppsm ppsm tools access the ppsm system kernel internally via the trap instruction. when an application makes a ppsm toolset call, a pre-defined trap instruction is called with the correct arguments assigned to the various registers instead of calling the actual function. on the 68k, there are 16 traps that can be used. table 34-2 shows the trap instruction mapping for the ppsm tools. 35.1 ppsm tools calling structure for the protection of the ppsm object code and security, two levels of indirection is introduced in the ppsm when an application makes a system call. the first level is a stub library call. a ppsm tools stub interface is supplied to the application developers. this is a complete library of the ppsm tools but the function body consists of parameter passing and trap instruction call only. the second level is the trap system call, which takes in the parameters passed in by the stub library and makes an actual system call to the ppsm function. with this implementation, application developed code can reside in ram, while ppsm system code can be in rom. hence, ensuring object code protection and portability of the ppsm system code. 35.2 trap implementation figure 34-1 shows a block diagram of the event that takes place when an application makes a system call. the stub library and the trap instruction jump sections are implemented in low level assembler language to minimize the table 34-2 trap instructions mapping trap number trap vector trap address ppsm tools 1 0x21 0x84 ppsm basic tools 2 0x22 0x88 ppsm extended tools 3 0x23 0x8c touch panel tools 4 0x24 0x90 lcd display tools 5 0x25 0x94 timer tools 6 0x26 0x98 pcmcia ic card 7 0x27 0x9c communication tools f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
35-6 trap usage in ppsm personal portable system manager programmers manual overhead induces during a system call. 35.2.1 application applications are written in ansi c. all ppsm system tools use ansi c procedure calling convention. because singlestep c compiler allows assembly language in c source code, it is also allowed in ppsm applications. 35.2.2 stub library the stub library provides an interface between application code and system routines. its main function is for parameter passing and calling trap instruction with the correct arguments. it is written in a ansi c with 68k assembly language embedded format. each function in the stub library has the general layout as shown below: int simplification( int a, int b) #define no_of_argument2 #define func_number5 #define trap_number3 int rv; /* return value */ asm( lea 8(a6),a0, move.w #no_of_argument,d1, move.w #func_number,d0, trap #trap_number, move.l d0,{rv}, ); return (rv); } the first instruction that singlestep c compiler generates for the start of a c procedure is a link instruction. this instruction sets the frame pointer, a6, to points to the stack that is used by the procedure caller. to access the first argument, an offset of 8 is added to a6, see figure 34-2 . the stub library passes system call stub call trap call system code figure 34-1 ppsm tools calling structure c written in written in written in written in c assembly assembly ram rom language c and application stub library trap handler actual tool personal portable system manager programmers manual trap usage in ppsm 35-7 the callers argument list to the trap instruction via the address register a0 and the ppsm tools function number via d0. 35.2.3 trap service handler the trap service handler routines are implemented in 68k assembly language. there are 7 jump tables, one for each trap service handler (see table 34-2 ). the jump table consists of an array of ppsm tool addresses. these addresses are used as the ppsm system function procedure addresses by the trap service handler when it receives a call from the stub library. the listing below shows the general code layout for a trap service handler. .fref _func_1,2 .fref _func_2,8 jmptable: dc.l _func_1, _func_2 trap_1: lsl.w #2,d1 ; multiply no of arg by 4 add.l d1,a0 ; move a0 to end of arg list lsr.w #2,d1 ; move d1 back to no of arg loop_1: tst.w d1 ; any parameter left beq loop_2 ; if not, goto loop_2 move.l -(a0),-(a7); move parameter to stack subq.w #1,d1 ; decrement d1 bra loop_1 ; loop_2: lea jmptable,a0; get jump table address lsl #2,d0 ; get function offset add.l d0,a0 ; find function address movea.l(a0),a1; move address to a1 jsr (a1) ; jump to system routine rte last function argument first function argument return address previous value of a6 automatic/scratch variable a6 (-4) (+4) (+8) (+12) figure 34-2 frame pointer location in stack layout saved registers f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
a-2 error code definition personal portable system manager programmers manual ppsm_err_db_add unable to add database ppsm_err_db_dbid invalid database identifier ppsm_err_db_fdid invalid field identifier ppsm_err_db_readno invalid number found ppsm_err_db_recid invalid record identifier ppsm_err_db_sflag invalid secret flag value ppsm_err_db_type invalid data type ppsm_err_dot_width newwidth is 0 ppsm_err_doze_time doze time-out period out of range ppsm_err_draw_init invalid draw pointer ppsm_err_fill_pattern invalid fill pattern mode ppsm_err_fill_space invalid space gap in fill pattern ppsm_err_grey invalid grey level value ppsm_err_height invalid graphics output area height invalid height ppsm_err_hour invalid hour pointer invalid hour value ppsm_err_icon_type invalid predefined icon type for control icon ppsm_err_input_pad_closed input pad is not opened ppsm_err_input_pad_height input pad height out of range ppsm_err_input_pad_noscreen no panning screen for input pad ppsm_err_input_pad_opened input pad already opened ppsm_err_input_pad_width input pad width out of range ppsm_err_input_pad_x_pos input pad x-coordinate out of range ppsm_err_input_pad_y_pos input pad y-coordinate out of range ppsm_err_invalid_access invalid access of uart ppsm_err_invalid_tmout time-out value out of range ppsm_err_irpt_hdler handler not requested by application ppsm_err_lcd_font invalid font type ppsm_err_lcd_grey invalid background grey level invalid grey level value table a-1 error code definition error code definition personal portable system manager programmers manual appendices f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
personal portable system manager programmers manual personal portable system manager programmers manual error code definition a-1 appendix a error code definition the following are the definitions of all the possible error codes: table a-1 error code definition error code definition ppsm_ok message successfully sent successful operation task successfully terminated ppsm_error active list stack empty initialization failed numberofpoints is 0 soft keyboard is not opened unsuccessful operation ppsm_err_active_pop active list stack empty ppsm_err_active_push unable to push active list ppsm_err_area_code invalid area code for active area type ppsm_err_area_id invalid active area identifier invalid active area pointer ppsm_err_audio_inuse the pwm module is being used by another task ppsm_err_audio_regs invalid values for prescaler, repeat or clksel ppsm_err_audio_sam invalid audio sampling rate ppsm_err_audio_tonedur invalid tone duration ppsm_err_baud invalid baud rate flag ppsm_err_busy there is already an on-going receive request (when trying to initiate one) ppsm_err_charlen invalid character length flag ppsm_err_colour invalid pen color ppsm_err_coordinate invalid coordinates ppsm_err_cursor_init invalid cursor pointer ppsm_err_day invalid day pointer invalid day value f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
b-2 list of references personal portable system manager programmers manual personal portable system manager programmers manual error code definition a-3 ppsm_err_lcd_radius invalid radius ppsm_err_lcd_style invalid style ppsm_err_lcd_x invalid x-coordinate ppsm_err_lcd_y invalid y-coordinate ppsm_err_minute invalid minute pointer invalid minute value ppsm_err_mode invalid operating mode flag ppsm_err_month invalid month pointer invalid month value ppsm_err_no_alarm no alarm is set ppsm_err_no_memory not enough memory ppsm_err_no_request receive request was not initiated ppsm_err_num_fmt invalid user format field number ppsm_err_pan_address invalid panning screen address ppsm_err_pan_height invalid panning screen height ppsm_err_pan_init no panning screen has been created ppsm_err_pan_width invalid panning screen width ppsm_err_parity invalid parity flag ppsm_err_pen_get no active area has been created ppsm_err_pen_init no touch panel exist ppsm_err_pen_rate invalid sampling period specified ppsm_err_period invalid time-out period ppsm_err_rcts_idle rts/cts flow control is not enabled ppsm_err_ref_max alarm time is more than 1 minute from current time ppsm_err_release unable to release handler ppsm_err_second invalid second pointer invalid second value ppsm_err_skbd_used soft keyboard already being used ppsm_err_skbd_xsize soft keyboard width out of range ppsm_err_skbd_x_pos soft keyboard x-coordinate out of range ppsm_err_skbd_ysize soft keyboard height out of range table a-1 error code definition error code definition f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
a-4 error code definition personal portable system manager programmers manual ppsm_err_skbd_y_pos soft keyboard y-coordinate out of range ppsm_err_sleep_time sleep timeout period out of range ppsm_err_stopbit invalid number of stop bits flag ppsm_err_task_flag invalid screen flag ppsm_err_task_height invalid screen height ppsm_err_task_id invalid address for storing task identifier invalid task identifier ppsm_err_task_width invalid screen width ppsm_err_text_cr error while creating text template ppsm_err_text_cur invalid character cursor position ppsm_err_text_font invalid font type ppsm_err_text_grey invalid text grey level value ppsm_err_text_height given height extends text display area beyond the panning screen ppsm_err_text_id invalid text template identifier ppsm_err_text_style invalid output style type ppsm_err_text_width given width extends text display area beyond the panning screen ppsm_err_text_x text template x-coordinate out of range ppsm_err_text_y text template y-coordinate out of range ppsm_err_tmout_value invalid time-out period ppsm_err_width invalid graphics output area width invalid width ppsm_err_x_pos invalid dot x position ppsm_err_year invalid year pointer invalid year value ppsm_err_y_pos invalid dot y position ppsm_no_match no match of data table a-1 error code definition error code definition personal portable system manager programmers manual list of references b-1 appendix b list of references 1) addendum and errata to mc68328 dragonball tm integrated microprocessor users manual . motorola, inc. 2) computer graphics principles and practices . foley, van dam, feiner and huges. addison wesley, 1993. 3) crosscode a c for the 68000 microprocessor family . software development systems, inc. 4) mc68328ads application system users manual . motorola, inc. 5) mc68328 integrated processor users manua l, mc68328um/ ad.motorola, inc. 6) singlestep tm debugger for the 68000 microprocessor family . software development systems, inc. 7) m68ez328ads application development system users manual . motorola, inc. 8) mc68ez328 integrated processor users manual . motorola inc. f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
c-4 index of ppsm tools personal portable system manager programmers manual reftimealarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10 reftimealarmid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11 reftimediff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11 reftimeread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-12 s saverec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-30 scanningoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-14 scanningon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-14 sendmessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-3 setdotwidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-31 setdozemode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-1 setdozeperiod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-1 setdutycycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2 setpatternfill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-31 setperiod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-12 setperiodid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-13 setsleepmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-3 setsleepperiod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-3 subtaskcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-3 t taskcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-4 taskhook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-5 taskmemused . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-4 taskreinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-5 taskstackavail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-4 taskstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6 taskterminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-7 textcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1 textdelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1 textmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2 textreadcursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2 textsetcursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3 textsetdisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-4 textsetfont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5 textsetoutlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-6 textsetup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-7 textunmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9 timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23-12 , 23-14 timeoutid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-15 totalmemsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5 totalmemused . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5 u uartconfigure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-1 uartflowctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3 uartinquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3 uartrcvctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-4 personal portable system manager programmers manual index of ppsm tools c-1 appendix c index of ppsm tools a activeareadisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1 activeareaenable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1 activeareaposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-7 activearearead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2 activeareasuspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3 activeareatofront . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4 activelistpop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4 activelistpush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5 advaudioplaywave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-1 advmessagedelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-1 advopeninputpad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1 advopensoftkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2 advsendmessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-1 advtaskcreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-1 alarmclear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-1 alarmclearid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-1 alarmread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2 alarmreadid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2 alarmset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-3 alarmsetid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-4 appswap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-2 areaechodisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6 areaechoenable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6 audioinuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2 audioplaytone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2 audioplaywave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-3 audiostopwave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-4 c changepanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1 changewindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3 clearrec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4 clearscreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5 closeinputpad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3 closesoftkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4 ctrlicondisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-7 ctrliconenable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-8 cursorgetorigin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5 cursorgetpos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6 cursorgetstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7 cursorinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7 cursoroff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-8 cursorset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-8 cursorsetblink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-9 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
c-2 index of ppsm tools personal portable system manager programmers manual cursorsetorigin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10 cursorsetpos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10 cursorsetstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-11 d datetimeread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5 datetimeset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6 dbadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1 dbaddrecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1 dbaddrectotop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2 dbappendrecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-3 dbchangestddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-4 dbchangeunfdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-5 dbdelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-6 dbdeleterecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-6 dbgetfirstrecid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-7 dbgetnextrecid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-8 dbgetprevrecid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-8 dbreaddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9 dbreadtotalnumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10 dbreadtotalnumberrecords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11 dbreadunfdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11 dbrecordsecret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12 dbsearchdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-13 dbsecretflag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-14 dbsetrecordsecretflag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15 dbsetsecretflag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15 deletetimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7 displaymove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-12 drawarc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-13 drawcircle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-13 drawdot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-14 drawellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-15 drawhorz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-16 drawline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-17 drawrec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-18 drawvector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-19 drawvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-20 e exchangerec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-21 g getdisplayx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-22 getdisplayy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-23 getlogicalx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-23 getlogicaly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-24 getscreenmem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-24 personal portable system manager programmers manual index of ppsm tools c-3 i iconscanoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-9 iconscanon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-10 inputtimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7 invrec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-25 irptgetdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-1 irptrelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-3 irptrequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-4 irptsenddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-6 l lcalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-1 lcdcontrast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-26 lcdrefreshrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-27 lcdscreenmove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-27 lfree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-1 lmalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-2 , 24-6 lrealloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-3 m messagedelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-3 moveblock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-3 o openinputpad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5 opensoftkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6 p pencalibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-10 penechoparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-11 pengetinput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-11 pensetinputmax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-12 pensetinputorg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-13 pensetrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-13 ppsminit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-1 putchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-28 putrec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-29 r readsmversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-3 reffinetimealarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7 , 23-8 reffinetimealarmid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8 reffinetimediff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-9 reffinetimeread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8 , 23-10 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .
c-6 index of ppsm tools personal portable system manager programmers manual personal portable system manager programmers manual index of ppsm tools c-5 uartreaddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-6 uartreceive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-6 uartsend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-7 uartsendabort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-8 uartsendctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-9 uartsetdelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-10 uarttimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-11 f r e e s c a l e s e m i c o n d u c t o r , i freescale semiconductor, inc. f o r m o r e i n f o r m a t i o n o n t h i s p r o d u c t , g o t o : w w w . f r e e s c a l e . c o m n c . . .

▲Up To Search▲

Price & Availability of PPSMMANUAL

	To Download PPSMMANUAL Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .