[people/ms/u-boot.git] / api / README

U-Boot machine/arch independent API for external apps
=====================================================

1.  Main assumptions

  - there is a single entry point (syscall) to the API

  - per current design the syscall is a C-callable function in the U-Boot
    text, which might evolve into a real syscall using machine exception trap
    once this initial version proves functional

  - the consumer app is responsible for producing appropriate context (call
    number and arguments)

  - upon entry, the syscall dispatches the call to other (existing) U-Boot
    functional areas like networking or storage operations

  - consumer application will recognize the API is available by searching
    a specified (assumed by convention) range of address space for the
    signature

  - the U-Boot integral part of the API is meant to be thin and non-intrusive,
    leaving as much processing as possible on the consumer application side,
    for example it doesn't keep states, but relies on hints from the app and
    so on

  - optional (CONFIG_API)


2. Calls

  - console related (getc, putc, tstc etc.)
  - system (reset, platform info)
  - time (delay, current)
  - env vars (enumerate all, get, set)
  - devices (enumerate all, open, close, read, write); currently two classes
    of devices are recognized and supported: network and storage (ide, scsi,
    usb etc.)


3. Structure overview

  - core API, integral part of U-Boot, mandatory
    - implements the single entry point (mimics UNIX syscall)

  - glue
    - entry point at the consumer side, allows to make syscall, mandatory
      part

    - helper conveniency wrappers so that consumer app does not have to use
      the syscall directly, but in a more friendly manner (a la libc calls),
      optional part

  - consumer application
    - calls directly, or leverages the provided glue mid-layer
Commit	Line	Data
500856eb RJ	1	U-Boot machine/arch independent API for external apps
	2	=====================================================
	3
	4	1. Main assumptions
	5
	6	- there is a single entry point (syscall) to the API
	7
	8	- per current design the syscall is a C-callable function in the U-Boot
	9	text, which might evolve into a real syscall using machine exception trap
	10	once this initial version proves functional
	11
	12	- the consumer app is responsible for producing appropriate context (call
	13	number and arguments)
	14
	15	- upon entry, the syscall dispatches the call to other (existing) U-Boot
	16	functional areas like networking or storage operations
	17
	18	- consumer application will recognize the API is available by searching
	19	a specified (assumed by convention) range of address space for the
	20	signature
	21
	22	- the U-Boot integral part of the API is meant to be thin and non-intrusive,
	23	leaving as much processing as possible on the consumer application side,
	24	for example it doesn't keep states, but relies on hints from the app and
d3a6532c	25	so on
500856eb RJ	26
	27	- optional (CONFIG_API)
	28
	29
	30	2. Calls
	31
	32	- console related (getc, putc, tstc etc.)
	33	- system (reset, platform info)
	34	- time (delay, current)
	35	- env vars (enumerate all, get, set)
	36	- devices (enumerate all, open, close, read, write); currently two classes
	37	of devices are recognized and supported: network and storage (ide, scsi,
	38	usb etc.)
	39
	40
	41	3. Structure overview
	42
	43	- core API, integral part of U-Boot, mandatory
	44	- implements the single entry point (mimics UNIX syscall)
	45
	46	- glue
	47	- entry point at the consumer side, allows to make syscall, mandatory
	48	part
	49
	50	- helper conveniency wrappers so that consumer app does not have to use
	51	the syscall directly, but in a more friendly manner (a la libc calls),
	52	optional part
	53
	54	- consumer application
	55	- calls directly, or leverages the provided glue mid-layer