Speaking of platforms. We currently differentiate between platform ports and application ports. A platform port ports the existing application to a new platform. The application port has a defined feature set and should be similar across all platforms it has been ported too. A new application port is needed where the feature set differs significantly from existing application ports.

In practice: if apps/ code doesn't notice the difference between two platform ports, then it should be a single application port. But if apps/ notices it, because the one platform supports FM radio (which makes themes behave differently) and the other doesn't, then there should be two separate application ports.

This differentiation could possibly change in the future, it hasn't been set in stone at the time of writing.

This document will largely cover platform ports.

Because Rockbox has always been an OS, OS for embedded systems, it has virtually no dependencies. But to reach the best degree of integration and to reduce Rockbox' memory footprint the goal is to use supporting OS/library routines where possible.

Functions marked with extern are already implemented in Rockbox, but you need to call them somehow from the platform drivers.

typedef unsigned short fb_data;

#define LCD_FBWIDTH ((LCD_WIDTH+7)/8)

#define LCD_FBHEIGHT LCD_HEIGHT

fb_data lcd_framebuffer[LCD_FBHEIGHT][LCD_FBWIDTH];

extern void lcd_init_device(void);

extern void lcd_update(void);

extern void lcd_update_rect(int x, int y, int width, int height);

extern void button_init_device(void);

int button_read_device(int *data);

extern int button_read_device touchscreen_to_pixels (int x, int y, int *data);

You need to implement the above functions. button_init_device() is much like the aforementioned lcd_init_device() functions, i.e. you use it to initialize the driver and connect it with the host.

• button_init_device() is much like the aforementioned lcd_init_device() functions, i.e. you use it to initialize the driver and connect it with the host.
• button_read_device() is what's being called periodically, every tick. It should be fast to execute. It only has the data parameter if you implement the touchscreen interface. It's expected to return the appropriate bit for each pressed button (e.g. BUTTON_UP|BUTTON_LEFT), or BUTTON_NONE if nothing was pressed. You should return the value of touchscreen_to_pixels() if you received a button press with the touchscreen interface. Pass through the data parameter if you call it. It'll handle the current touchscreen mode for you and return the correct press on its own.

button_read_device() is what's being Example: The Android port called periodically, every tick. It should be fast to execute. It only has some functions which the data parameter if OS calls whenever you implement the touchscreen interface. It's expected to return the appropriate bit for each pressed button (e.g. BUTTON_UP|BUTTON_LEFT), or BUTTON_NONE if nothing was pressed. You should return the value of touchscreen_to_pixels() if you received a button touchscreen press with is detected. Those function write the touchscreen interface. Pass through the data parameter if you call state into variables. button_read_device() only reads that state, calls touchscreen_to_pixels() it. It'll handle the current touchscreen mode for you and return returns the correct result. press on its own.

int touchscreen_to_pixels(int x, int y, int *data);



extern bool timer_register(int reg_prio, void (*unregister_callback)(void),
                   long cycles, void (*timer_callback)(void))

extern bool timer_set_period(long cycles);

extern void timer_unregister(void);

#define HZ 100

extern void tick_start(unsigned int interval_in_ms);extern void call_tick_tasks(void); 

extern void call_tick_tasks(void);

• timer_* need to be stubbed, for now, since it's only used in (some) plugins which the application doesn't build right now.
• tick_start() is important. It acts as an initializing function, meaning it needs to initializes the driver and connects to the host. This function needs to set up a mechanism which enables the tick tasks to be called. In most cases this means setting up a timer task, which runs periodically at a HZ rate.

The first three functions need to be stubbed, for now, since it's only used in (some) plugins which the application doesn't build right now.

The last however, tick_start(), is important. This function needs to set up a mechanism which enables the tick tasks to be called. In most cases this means setting up a timer task, which runs periodically at a HZ rate.

Threads Example: The SDL port creates a SDL_Timer, sets it to run each each interval_in_ms, and calls call_tick_tasks() from it.

PCM driver

Rockbox continuously writes the decoded audio data into the pcm buffer, which acts as a ring buffer. Since that can wrap, the pcm driver needs to ask for a chunk raw pcm data. Then, that chunk is to be fed to host, who doesn't need to do any more than writing it to the hardware.

Rockbox usually decodes at 44100Hz, and the result is 16bit signed interleaved pcm data.

void pcm_play_lock(void);

void pcm_play_unlock(void);

void pcm_dma_apply_settings(void);

void pcm_play_dma_start(const void *addr, size_t size);

void pcm_play_dma_stop(void);

void pcm_play_dma_pause(bool pause);

size_t pcm_get_bytes_waiting(void);

const void * pcm_play_dma_get_peak_buffer(int *count);

void pcm_play_dma_init(void);

void pcm_postinit(void);

extern void pcm_play_get_more_callback(void **start, size_t *size);

These are quite a lot of functions, but it's not actually complicated.

• pcm_play_dma_init() initializes the driver and connects to the host's pcm playback mechanism.
• pcm_post_init() can most probably be stubbed, unless you need initializing stuff that can't be done in pcm_play_dma_init().
• pcm_play_dma_pause and _stop should be self-explanatory.
• pcm_dma_apply_settings() should configure the host for a 44.1Khz signed 16bit interleaved pcm stream (but that's usually the default anyway).
• pcm_play_dma_get_peak_buffer() shall return the start and size of the current pcm data that has not been fed to the host yet.
• pcm_play_lock() shall lock out the host (i.e. preventing it from calling get_more callbacks), finishing any pending pcm transfers. pcm_play_unlock() shall get the host in again. Both should be fine if stubbed, as they're intended for hardware dma which you probably won't have.

Now, if the current pcm chunk has been played, you want to get a new one for the host so it can continue playing. This is where pcm_play_get_more_callback() comes into play. This is where you get a new chunk from. It shall be called after each chunk and thus establishes a continuous pcm stream. Make the host call it so that it can fetch new data automatically on its own.

Threads

Rockbox relies on cooperative multi-tasking. This is very tricky, because host's usually don't offer that. Preemptive multi-tasking seems to be generally accepted and chosen over cooperative multi-tasking.

One has 4(5) choices basically:

• If the CPU the platform runs on is known, and if it's one of ARM, Coldfire, SH or MIPS, then you can use the Rockbox implementation. This is the easiest way but possibly not applicable. The Android port does this.
• Gnu Pth threads (http://www.gnu.org/software/pth/) can be used, it has been implemented as threading engine for Rockbox as a proof of concept (http://repo.or.cz/w/kugel-rb.git/shortlog/refs/heads/gnu-pth-sim, this should probably be committed to Rockbox SVN). It requires a Unix environment though.
• Emulating cooperative threads with preemptive ones. This can be done by locking out all but the current thread with a single mutex (a mutex provided by the host, not a Rockbox mutex). The context switch would also transfer ownership of the mutex to a different thread. The SDL port does this.
• Implementing a custom context switch mechanism for your platform, so that firmware/thread.c can be used. The only platform specific bit is load_context() and store_context(). If that's a Unix environment, it looks like {get,set,swap,make}context can probably be used for this. This means implementing a user thread library without using the standard threads that the host offers
• Nobody has tried it so far, because it's expected to need a hell lot of effort with all sorts of strange synchronization issues...but one could try to fix Rockbox to run under preemptive threads.

It's not very useful to list all the functions now. One basically needs to implement all of firmware/thread.c (unless it can be re-used).

One particular function worthwhile to mention, though, is core_sleep(). If you don't use the host's thread, then this function shall notify the host that "Rockbox doesn't do anything right now", i.e. that all threads are asleep. If this is not implemented, then the scheduler in thread.c will busy wait for the next thread to be runnable, which wastes a lot CPU time for nothing. If you use the host's thread then the host should be able to figure it out on its own.

Adding a platform port

I don't want to recite much information here, because it's largely covered by PortingHowTo.

However, at the time of writing, there are only two platform ports which have the same feature set. Because of that, they are not treated differently throughout the Rockbox code (except the target tree code). They share a single firmware/export/config/application.h and a single entry in tools/configure. There's effectively only a single application port; but the application is ported to different platforms.

This application port should be re-used if possible. This reduces the amount of work needed to add a new platform port to the target tree platform drivers (including conditional compilation of it, in firmware/SOURCES) and to logic to pick the right build tools in tools/configure.

However, if it needs a new application port, then refer to PortingHowTo.