All Common Function Documentation

TAP_SetSoundLevel

Topfield Documentation

int TAP_SetSoundLevel(byte soundLevel);

It adjusts the sound volume.

  • soundLevel : 0 ~ 31

Additional Documentation


TAP_GetTime

Topfield Documentation

int TAP_GetTime(word *mjd, byte *hour, byte *min, byte *sec);

It gets the current time.

  • mjd : date information in MJD format
  • hour : hour (0 ~ 23)
  • min : minute (0 ~ 59)
  • sec : second (0 ~ 59)

Additional Documentation

MJD = Modified Julian Date


TAP_MemInfo

Topfield Documentation

void TAP_MemInfo(dword *heapSize, dword *freeHeapSize, dword *availHeapSize)

It finds the usable HEAP information.

  • heapSize : total HEAP size
  • freeHeapSize : free HEAP size
  • availHeapSize : available HEAP size

Additional Documentation

The difference between Free and Available

Malloc will normally allocate memory in chunks; so if you ask for 1 byte, it may actually allocate 100 bytes. Malloc also has to keep track of all the used/unused blocks, and it is not obliged to return freed blocks immediately - it may hang on to some smaller blocks to avoid fragmenting the ram too much, and to keep its lists reasonably small.

The free size is the total unused ram, including the unreachable parts, the available ram is amount that you can actually use.

  • you should use the available value, as this is always lower than the free size.
  • but the available ram may be fragmented, so you will probably not be able to malloc a block of available size; so always check the return value, rather than as the topfield api suggests, by calling TAP_MemInfo()


TAP_MemAlloc

Topfield Documentation

void* TAP_MemAlloc(dword size);

allocates the memory at the HEAP.

  • size : the memory size to be allocated
  • return value : the allocated memory address
CAUTION : This function SHOULD be preceded by the TAP_MemInfo() to check the memory size.

Additional Documentation

Although Topfield advise checking against the values returned by TAP_MemInfo, TAP_MemAlloc internally calls TAP_MemInfo and returns 0 if size is greater than availHeapSize-8k.

TAP_MemAlloc allocates memory in blocks of at least 1280 bytes (0x500), so allocating lots of small chunks is will cause excessive memory use.

TAP_MemAlloc and TAP_MemFree seem to be very slow - nearly 1 millisecond for a single Alloc/Free pair on the TF5800. This is 100's of times slower than you'd expect. Consider using dlmalloc/dlfree from the libcutils? library instead. These implement a heap on top of 64kb blocks allocated from the underlying system and make dynamic memory management on a fine grain level a realistic possibility.

You should call dlmalloc_exit() before TAP_Exit() to release all blocks back to the underlying firmware. You should also consider calling dlmalloc_trim() intermittently to release any unused blocks.


TAP_MemFree

Topfield Documentation

int TAP_MemFree(const void* addr);

It frees the allocated memory at the HEAP.

  • addr : the start address to be freed

Additional Documentation

The firmware is known to keep a list of which memory block is assigned to which TAP, presumably so that it can free all memory allocated to a TAP when that TAP unloads regardless of whether the TAP cleaned up properly. Of course this is no excuse to allow your TAP to leak memory...

Question: Does anyone know the behaviour of TAP_MemFree on being passed a NULL pointer? Most (all?) implementations of free() will just return immediately, and delete in C++ does the same - does TAP_MemFree?


TAP_GetTick

Topfield Documentation

dword TAP_GetTick();

It returns the counter value from the power on. The counter value is increased by 1 at every 10ms.

Additional Documentation


TAP_Delay

Topfield Documentation

void TAP_Delay(dword dm10);

It delays the TAP application by the specified time.

  • dm10 : the delay time in 10ms unit

Additional Documentation


TAP_ExtractMjd

Topfield Documentation

int TAP_ExtractMjd(word mjd, word *year, byte *month, byte *day, byte *weekDay);

It gets the year, month, day and weekday from the date information of MJD format.

  • mjd : date information in MJD format
  • year : year
  • month : month
  • day : day
  • weekDay : weekday
return value : 1 if the input MJD data is normal. If it is abnormal value, it returns 0

Additional Documentation

MJD = Modified Julian Date


TAP_MakeMjd

Topfield Documentation

int TAP_MakeMjd(word year, byte month, byte day);

It makes the MJD format from the year, month, and day.

return value : date information in MJD format

Additional Documentation

MJD = Modified Julian Date


TAP_Sin

Topfield Documentation

long TAP_Sin(long mul, long th);

It calculates the value of sine function.

  • mul : parameter for multiplying
  • th : angle degree between 0 to 360
return value : mul * sin(th)

Additional Documentation


TAP_Cos

Topfield Documentation

long TAP_Cos(long mul, long th);

It calculates the value of cosine function.

  • mul : parameter for multiplying
  • th : angle degree between 0 to 360
return value : mul * cos(th)

Additional Documentation


TAP_SPrint

Topfield Documentation

void TAP_SPrint(void *str, const void *fmt, ...);

It puts the formatted string to str.

Additional Documentation

TAP API header file (TAP.H) contains next line:

#define sprintf TAP_SPrint
so instead of using TAP_SPrint in your code you can also use keyword sprintf.


TAP_GetSignalLevel

Topfield Documentation

int TAP_GetSignalLevel();

It returns the signal level of current transponder.

return value : signal level ( 0 ~ 100 % )

Additional Documentation


TAP_GetSignalQuality

Topfield Documentation

int TAP_GetSignalQuality();

It returns the signal quality of current transponder.

return value : signal quality ( 0 ~ 100 % )

Additional Documentation


TAP_SetInfoboxTime

Topfield Documentation

int TAP_SetInfoboxTime(int sec);

It controls the display time of Infobox.

  • sec : displaying time ( 0 ~ 30 )

Additional Documentation


TAP_PlayPCM

Topfield Documentation

int TAP_PlayPCM(void *pcmdata, int size, int freq, void (*Callback)(void));

It plays PCM data.

  • pcmdata : pointer of PCM data
  • size : size of PCM data
  • freq : frequency of PCM
  • Callback : It will be called after out the PCM data.

Additional Documentation


TAP_CaptureScreen

Topfield Documentation

int TAP_CaptureScreen(int mainSub, TYPE_VideoBank *videoBank);

It captures the picture.

  • mainSub : 1 - main screen, 0 - sub screen
  • videoBank : The pointer of TYPE_VideoBank that has the information for captured picture.
return value : 0 for Success, other value for ERROR

The structure of the TYPE_VideoBank is as follows.

typedef struct
{
    byte *yAddress;
    byte *cAddress;
    word width;
    word height;
} TYPE_VideoBank;
( Refer the ScreenCapture among the examples. )

Additional Documentation