Re: LegOS Function/Command list...
		Posted on 2000-12-04 02:29 by Dave Chen

int main (void)
the user main().
this is what you supply ;-)

Display Control:
Defines
#define lcd_int (i) display an integer in decimal.
#define lcd_unsigned (u) display an unsigned value in decimal.
#define lcd_clock (t) display a clock. More...
#define lcd_digit (d) display a single digit right of the man symbol.
Enumerations
enum lcd_segment { man_stand, man_run, s1_select, s1_active, s2_select, s2_active, s3_select,
s3_active, a_select, a_left, a_right, b_select, b_left, b_right, c_select, c_left, c_right, unknown_1,
circle, dot, dot_inv, battery_x, ir_half, ir_full, everything }
enum lcd_number_style { digit, sign, unsign }
enum lcd_comma_style { digit_comma, e0, e_1, e_2, e_3 }
digit_comma=single digit on the right, e0=whole, e_1=10ths, e_2=100ths, e_3=1000th(problematic with negatives)

void lcd_show (lcd_segment segment)
show LCD segment.
Parameters:
segment - segment to show

void lcd_hide (lcd_segment segment)
hide LCD segment.
Parameters:
segment - segment to hide

void lcd_number (int i, lcd_number_style n, lcd_comma_style c)
show number on LCD display.
Parameters:
i - the number
n - a number style
c - a comma style

void lcd_refresh (void)
show LCD display contents to the world.
display updates are realized exclusively by calling this function.

void cputc_native (char mask, int pos)
display native mode segment mask.
Parameters:
mask - the segment mask.
pos - the desired display position.
this is a dispatcher for the fixed position routines.

void cputc_native_0 (char mask)
display native mode segment mask at display position 0.
Parameters:
mask - the mask to display
void cputc_native_1 (char mask)
display native mode segment mask at display position 1.
Parameters:
mask - the mask to display
void cputc_native_2 (char mask)
display native mode segment mask at display position 2.
Parameters:
mask - the mask to display
void cputc_native_3 (char mask)
display native mode segment mask at display position 3.
Parameters:
mask - the mask to display
void cputc_native_4 (char mask)
display native mode segment mask at display position 4.
Parameters:
mask - the mask to display
void cputc_native_5 (char mask)
display native mode segment mask at display position 5.
Parameters:
mask - the mask to display. only the middle segment is present on the display.

void cputw (unsigned word)
display a hexword in the four leftmost positions.
Parameters:
word - the hexword
position 0 is unaffected by this call.

void cputs (char * s)
display an ASCIIZ string.
Parameters:
s - the string
only the first 5 characters will be displayed.


IR:
size_t dir_write (void * const buf, size_t len)
write to IR port, blocking.
Parameters:
buf - data to transmit
len - number of bytes to transmit
Returns:
number of bytes written, -1 indicates error.

size_t dir_read (void * buf, size_t len)
read from IR port, blocking.
Parameters:
buf - allocated receive buffer
len - number of bytes to read
Returns:
number of bytes read, -1 indicates error.

void dir_fflush (void)
flush input buffer.

Memory Management:
void mm_update_first_free (size_t * start)
update first free block pointer.
Parameters:
start - pointer to owner field of a memory block to start with.

void * malloc (size_t size)
allocate a block of memory.
Parameters:
size - requested block size
Returns:
0 on error, else pointer to block.

void free (void * the_ptr)
free a previously allocated block of memory.
Parameters:
the_ptr - pointer to block
ever heard of free(software_paradigm)?

Void * calloc (size_t nmemb, size_t size)
allocate adjacent blocks of memory.
Parameters:
nmemb - number of blocks
size - individual block size
Returns:
0 on error, else pointer to block

void memcpy (void * dest, void * src, size_t size)
copy memory block from src to dest.
Parameters:
dest - destination
src - source
size - number of bytes to copy
Warning:
behaviour is undefined in case source and destination blocks overlap.

void * memset (void * s, int c, size_t n)
fill memory block with a byte value.
Parameters:
s - start
c - byte fill value
n - number of bytes to fill

void mem_clear (void * start, void * end)
set memory block [start,end[ to zero.
Parameters:
start - start
end - end (non-inclusive).
Bugs and limitations:
FIXME: seems buggy. memset() usage advised.

char * strcpy (char * dest, const char * src)
Copy null-terminated string from src to dest.
Parameters:
src - source
dest - destination
Returns:
pointer to dest

int strlen (const char * s)
Determine string length.
Parameters:
s - string
s2 - second string
Returns:
string length

int strcmp (const char * s1, const char * s2)
Compare two strings.
Parameters:
s1 - first string
s2 - second string
Returns:
<0: s1<s2, ==0: s1==s2, >0: s1>s2

void mm_reaper ()
free all blocks allocated by the current process.

size_t mm_try_join (size_t *ptr)
check for free blocks after this one and join them if possible.
void mm_update_first_free (size_t *start)
update first free block pointer. More...
void mm_init ()
initialize memory management.

Misc:
void power_off (void)
enters software standby mode.

void power_init (void)
disables software standby mode so tm_idle_task() can use the sleep instruction.

void rom_reset (void) __asm__ ("0x03ae") __attribute__ ((noreturn))
erases legOS, returning control to ROM.

void delay (unsigned ms)
uncalibrated delay loop.
Parameters:
ms - approximate time in ms

volatile time_t sys_time
current system time in ms.
Warning:
This is a 32 bit value which will overflow after 49.7 days of continuous operation.

void systime_handler (void)
system time handler for the 16bit timer OCIA irq.
this is the pulse of the system. task switcher and motor driver calls are initiated here.
void systime_init (void)
initialize system timer.
task switcher initialized to empty handler motors turned off
void systime_shutdown (void)
shutdown system timer.
will also stop task switching and motors.
void systime_set_switcher (void * switcher)
set task switcher vector.
Parameters:
switcher - the switcher
void systime_set_timeslice (unsigned char slice)
set multitasking timeslice in ms.
Parameters:
slice - the timeslice. must be at least 5ms.

Motors:  
const void motor_a_dir (MotorDirection dir)
set motor A direction.
const void motor_b_dir (MotorDirection dir)
set motor B direction.
const void motor_c_dir (MotorDirection dir)
set motor C direction.
Parameters:
dir = enum MotorDirection { off, fwd, rev, brake }

const void motor_a_speed (unsigned char speed)
set motor A speed.
const void motor_b_speed (unsigned char speed)
set motor B speed.
const void motor_c_speed (unsigned char speed)
set motor C speed.
Parameters:
speed - the speed
#define MIN_SPEED
#define MAX_SPEED

Multi-Tasking:
void tm_switcher (void)
the task switcher.
saves active context and passes sp to scheduler then restores new context from returned sp

size_t * tm_scheduler (size_t * old_sp)
the process scheduler.
Parameters:
old_sp - current task's current stack pointer
Returns:
new task's current stack pointer
actual context switches performed by tm_switcher (assembler wrapper)

unsigned int sleep (unsigned int sec)
delay execution allowing other tasks to run.
Parameters:
sec - sleep duration in seconds
Returns:
number of seconds left if interrupted, else 0.
Bugs and limitations:
interruptions not implemented.

unsigned int msleep (unsigned int msec)
delay execution allowing other tasks to run.
Parameters:
msec - sleep duration in milliseconds
Returns:
number of milliseconds left if interrupted, else 0.
Bugs and limitations:
interruptions not implemented.

void yield (void)
yield the rest of the current timeslice.
doesn't speed up the system clock.

int tm_idle_task (void)
the idle task.
infinite sleep instruction to conserve power.

void tm_init (void)
init task management.
called in single tasking mode before task setup.

void tm_start (void)
start task management.
called in single tasking mode after task setup

pid_t execi (int(* code_start)(void), priority_t priority, size_t stack_size)
execute a memory image.
Parameters:
code_start - start address of code to execute
priority - new task's priority
stack_size - stack size for new process
Returns:
-1: fail, else pid.
will return to caller in any case.

void exit (int code)
exit task, returning code.
Parameters:
code - The return code

wakeup_t wait_event (wakeup_t(* wakeup)(wakeup_t), wakeup_t data)
suspend process until wakeup function is non-null.
Parameters:
wakeup - the wakeup function. called in task scheduler context.
data - argument passed to wakeup function by scheduler
Returns:
return value passed on from wakeup

wakeup_t tm_sleep_wakeup (wakeup_t data)
wakeup function for sleep.
Parameters:
data - time to wakeup encoded as a wakeup_t

void kill (pid_t pid)
kill a process.
Parameters:
pid - must be valid process ID, or undefined behaviour will result!


Semaphores:
wakeup_t sem_event_wait (wakeup_t data)
the semaphore event wakeup function for wait_event().
Parameters:
data - pointer to the semaphore passed as a wakeup_t

int sem_wait (sem_t * sem)
wait on a semaphore.
Parameters:
sem - a valid semaphore
suspends the calling thread until the semaphore has non-zero count. It then atomically decreases the
semaphore count.
implemented with wait_event().

int sem_trywait (sem_t * sem)
non-blocking check on a semaphore.
Parameters:
sem - a valid semaphore
a non-blocking variant of sem_wait. If the semaphore has non-zero count, the count is atomically
decreased and sem_trywait immediately returns 0. If the semaphore count is zero, sem_trywait
immediately returns with error EAGAIN.
this is IRQ handler safe.

int sem_post (sem_t * sem)
increase semaphore count.
Parameters:
sem - a valid semaphore
atomically increases the count of the semaphore. This function never blocks and can safely be used in
asynchronous signal handlers.

Sensors:  (Note:  Unplug all sensors when attempting to upload .lx programs to the RCX...)
Sensor values can be read like any unsigned variable. Assignments will have undefined effects, as they periodically overwritten by the A/D conversion routine. The variable names are:
SENSOR_1
SENSOR_2
SENSOR_3
BATTERY = unsigned* const battery (RCX battery sensor address.)

Active sensors
--------------
The Mindstorms light and rotation sensors are active components. They require pulsed alimenation to operate. That is, power supply must be cut when performing A/D conversion on the respective channel.
To enable this functionality, use ds_active(&SENSOR_n). Otherwise, the light sensor detects ambient light, while the rotation sensor doesn't work at all. To disable, use ds_passive(&SENSOR_n).
A macro LIGHT(a) to scale active light sensor values to 0 .. LIGHT_MAX is supplied, as well as convenience macros
LIGHT_1
LIGHT_2
LIGHT_3
The kernel initializes all sensors to passive mode on startup and restores this state on termination of the user module.

Rotation sensors
----------------
Mindstorms rotation sensors provide different resistances to encode rotational position. With a finite state machine, this can be decoded into relative position. 
To enable this functionality, use ds_rotation_on(&SENSOR_n). To disable, use ds_rotation_off(&SENSOR_n). The decoded relative position can be read from these unsigned variables:
ROTATION_1
ROTATION_2
ROTATION_3
Note that these are relative positions. By default, the sensor cannot identify absolute positions. If this information is supplied by external means, ds_rotation_set(&SENSOR_n,int pos) can be used to set an absolute position.
The kernel disables rotation tracking by default. The absolute rotational position is undefined on startup.

void ds_active(unsigned * const sensor)

void ds_passive(unsigned * const sensor)

void ds_rotation_on(unsigned * const sensor)

void ds_rotation_off(unsigned * const sensor)

void ds_rotation_set (unsigned * const sensor, int pos)
set rotation to an absolute value.
Parameters:
sensor - the sensor address, can be &SENSOR_1, &SENSOR_2 or &SENSOR_3
pos - desired absolute position
axis should be inert during the function call

Sound:
void sound_system (unsigned nr)
play one of the system sounds.

int sound_playing ()
is a sound playing?
Returns:
0=no, else yes

void ds_play (unsigned char * sample, unsigned length)
start playing sound.
Parameters:
sample - an 1 bit / 8 kHz sample. util/sample-convert.pl will perform a conversion for standard wav
files.
length - sample length in bytes
Warning:
output sounds horrible
cycles not implemented.

void ds_stop (void)
stop playing sound.