ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / oslib / oslib_1 / OSLib / ReadMe < prev next >

Wrap

Text File | 1995-08-22 | 18.4 KB | 470 lines

Introduction ============ OSLib is a set of functions and C headers to provide complete coverage of the RISC O S application programmer's interface in C. It provides access from C code to all RISC O S system calls ("SWI's") which is efficient: often, memory access is completely avoided; type-safe: every argument can be type-checked by the compiler; obvious: a SWI is called by the "obvious" syntax; complete: every SWI is covered; register-safe: hides (often idiosyncratic) register allocation; language-independent: although the headers are specific to C, the library is not - any A P C S-conformant language can call it. It also provides names for all the data structures and reason codes used by the A P I. Code that uses it is superior to similar code using _kernel_swi() or _swix(), both in terms of the compile-time checking that is available, and the size and speed of the code generated. In addition to the module files, there is also a file "types.h" which contains macros and types useful for any programme. This file explains how OSLib relates to the P R M descriptions of the SWI's in complete detail. It is best read in conjunction with the header files themselves. The OSLib Structuring Conventions === ===== =========== =========== Each header file provides function prototypes typedefs macros that completely specify the interface to a module. All symbols provided by "<module>.h" are of the form <module>_<name> (except some of the form <module><name>_<reason>). For functions, <name> is the name of the SWI, converted to lower-case, and with underscores inserted between each word: SWI Function --- -------- OS_ReadLine os_read_line Wimp_CreateWindow wimp_create_window For typedefs, <name> is a sequence of words in lower-case, separated by underscores: Type Meaning ---- ------- os_colour a palette entry value (0xbbggrr00) wimp_window a window definition structure For macros, <name> is a sequence of words in upper-case, separated by underscores: Macro Meaning ----- ------- os_MODEVAR_XEIG_FACTOR a value for os_read_mode_variable error_ESCAPE the error number of Escape (17) wimp_ICON_NAME_LIMIT the largest length of an icon name (all macros for maximum values end in _LIMIT). There is also a special set of macros provided for more convenient handling of structures with a variable number of trailing parts, as used for mode selectors or Wimp window definitions, for example: Macro Meaning ----- ------- os_PALETTE (nc) Declarator for a palette with |nc| colours os_SIZEOF_PALETTE (nc) Size of that palette wimp_WINDOW (ni) Declarator for a window with |ni| icons wimp_SIZEOF_WINDOW (ni) Size of the complete window definition Furthermore, every SWI number and SWI reason code has a macro defined of the form <Module>_<Name> (in mixed case form): Macro Value ----- ----- OS_WriteC 0 Font_FindFont 0x40081 These are rarely needed. In fact, for each SWI, two functions are provided: one has a name prefixed with an x and returns a value of type |os_error *|, which is non- null if the SWI fails; the other does not start with an x, and never returns an error: if the SWI fails, a signal (|SIGOSERROR|, number 10) is raised, and may be caught by installing a signal handler for it. The non-x form can therefore return a result, instead of having to write to an output argument: for example, the SWI Wimp_CreateWindow can be called by either of the prototypes os_error *xwimp_create_window (wimp_window *window, wimp_w *w); wimp_w wimp_create_window (wimp_window *window); They have exactly the same effect if all goes well, but if there is an error, the first just returns it, while the other raises |SIGOSERROR| and does not return at all. (If you use the second, the signal handler for |SIGOSERROR| can use _kernel_last_oserror() to find out what the error was.) The function prototype is derived from the SWI description in the following way. Arguments corresponding to input registers appear first in order in the argument list, followed by the addresses of variables in which the output registers' values are to be written. If an output register value is not needed, a null pointer can be written in that position. (Since |int| and all pointer types are 32 bits on the ARM, it doesn't matter which type of null pointer is used.) Most of the types are fully defined: e g, a |wimp_window| is a structure type with all the fields defined with the right type and name to be passed to any SWI that uses it. Some types are "abstract," however: they are exported by a module, but the internal structure is not accessible to its clients. The best way of representing this in C is by an unspecified pointer type: a definition of the form typedef struct <tag> *<type> where the structure is never defined in full. Doing this allows the compiler to typecheck arguments of these types, as in the wimp_- create_window() example above. In addition, various modules use values from name spaces that are centrally allocated by Acorn. These include: |error_|, |message_|, |...v|, |event_| and |upcall_|, and they each have their own prefix. They correspond to error numbers, WIMP message numbers, vectors (which are reason codes for OS_CallAVector), service calls (reason codes for OS_ServiceCall), events (reason codes for OS_GenerateEvent) and upcalls (reason codes for OS_UpCall), respectively. In cases where name clashes are possible, the module name occurs in the <name> part: error_BUFFER_MANAGER_BUFFER_TOO_SMALL error_COLOUR_TRANS_BAD_DEPTH (Vectors are represented by a suffix, |...v|, rather than a prefix, since this is familiar.) These rules mean that if you are writing code for RISC O S, and you avoid (a) all names that start with the name <module> of any "<module>.h" you need to include; (b) all names that start with |error|, |message|, |event| or |upcall|, or end with |v|; then no names clashes will occur. Types.h ======= All OSLib header files ensure that "types.h" is included. This file contains various types, macros for values, and function-like macros that are generally useful. There are further macros in "macros.h." They are described here: Types ----- |bits|: Used for flags values and masks, normally consisting of fields of 1 or more bits. Macros are normally provided to help with getting these fields out: for a 1-bit field, a macro |X| such that To Use -- --- Read the field (v & X) != NONE Write a 0 v &= ~X Write a 1 v |= X and for a multi-bit field, macros X and X_SHIFT such that To Use -- --- Read the field (v & X) >> X_SHIFT Write a value |w| v = (v & ~X) | w << X_SHIFT. |bool|: Used for a truth value. |byte|: Used for a single byte value, as an alternative to |char| when the values are just data, rather than being characters as such. It is an unsigned type, which means that 2 instructions can be saved in P C C mode, where |char| is signed and must be sign-extended. Constant-like macros ------------- ------ |NULL|: the usual C null pointer constant. |FALSE|: value of type |bool| representing falsehood. |TRUE|: value of type |bool| representing truth. |NONE|: value of type |bits| with all bits clear. |ALL|: value of type |bits| with all bits set. |SKIP|: may be used as a "don't care" value for |int|, pointers, |bits|. |SIG_LIMIT|: largest signal number + 1. |_C|, |_Z|, |_N|, |_V|: masks for the flags in the P S R. |DEC_WIDTH|: the length of INT_MAX (2147483647) printed with %d. |SHORT_DEC_WIDTH|: the length of SHRT_MAX (32767) printed with %hd. |LONG_DEC_WIDTH|: the length of LONG_MAX (2147483647) printed with %ld. |OCT_WIDTH|: the length of UINT_MAX (37777777777) printed with %o. |SHORT_OCT_WIDTH|: the length of USHRT_MAX (177777) printed with %ho. |LONG_OCT_WIDTH|: the length of ULONG_MAX (37777777777) printed with %lo. |UNSIGNED_WIDTH|: the length of UINT_MAX (4294967295) printed with %u. |SHORT_UNSIGNED_WIDTH|: the length of USHRT_MAX (65535) printed with %hu. |LONG_UNSIGNED_WIDTH|: the length of ULONG_MAX (4294967295) printed with %lu. |HEX_WIDTH|: the length of UINT_MAX (FFFFFFFF) printed with %x. |SHORT_HEX_WIDTH|: the length of USHRT_MAX (FFFF) printed with %hx. |LONG_HEX_WIDTH|: the length of ULONG_MAX (FFFFFFFF) printed with %lx. |FLT_WIDTH|: the precision needed to distinguish 1 + FLT_EPSILON from 1 printed with %f. |DBL_WIDTH|: the precision needed to distinguish 1 + DBL_EPSILON from 1 printed with %f. |LDBL_WIDTH|: the precision needed to distinguish 1 + LDBL_EPSILON from 1 printed with %Lf. |FLT_EXP_WIDTH|: the length of the exponent of FLT_MAX printed with %f. |DBL_EXP_WIDTH|: the length of the exponent of DBL_MAX printed with %f. |LDBL_EXP_WIDTH|: the length of the exponent of LDBL_MAX printed with %Lf. |ERROR|: intended as an "out-of-band" value to be returned by functions like fgetc() which return |EOF| on end-of-file. |ERROR| may be used to indicate an error condition. |UNKNOWN|: used to declare (but not define) arrays of unknown size, as an argument to the type macros (e g, wimp_WINDOW()) described above. Function-like macros ------------- ------ |WHETHER|: convert a bool value to a string. |MAX|: larger of two values. |MIN|: smaller of two values. |MAXAB|: larger of two values and assign. |MINAB|: smaller of two values and assign. |ABS|: absolute value. |SGN|: signum. |DIM|: positive difference. |SQR|: square. |RATIO|: integer division, rounding to nearer. |BOOL|: convert an integer to bool. |UCHAR|: character corresponding to a digit (upper case preferred). |LCHAR|: ditto, lower case. |BINEXP|: 2 to the power of. |ISDIGIT|: a digit? |ISXDIGIT|: a hex digit? |DIGIT|: if a digit, then which, else undefined. |XDIGIT|: if a hex digit, then which, else undefined. |DBLEQ|: equality for floating-point numbers (requires a tolerance) |BIT|: the bit at an offset from a pointer. |SET|: set a bit at an offset from a pointer. |CLR|: clear a bit at an offset from a pointer. |CLEAR|: clear a string. |EMPTY|: is a string empty? |NCOPY|: copy at most a given number of characters from a string, and terminate it. |STR_|: helper macro for STR. |STR|: convert a macro to source string. |COUNT|: number of elements in an array. |ALIGN|: round an integer up to the next multiple of 4. |WORD|: assembles an |int| from an unaligned byte pointer. |SHORT|: assembles a |short| from an unaligned byte pointer. Macros that "change the language" ------ ---- ------- --- --------- (Not everyone likes using these!) |AS| is the same as |.|, but can be used to let the reader know that the left operand is a |union| rather than a |struct|. |ASREF| is the same as |->|, but can be used to let the reader know that the left operand is a |union *| rather than a |struct *|. |_| is the same as |,|, but if used to separate the arguments of a macro call is not recognised as a comma by the preprocessor. This lets you write macros with variable numbers of arguments. |__swi| is understood as a compiler directive by C release 5 (but not by earlier versions of C, nor by CFront) to call a function using a SWI instruction rather than by a BL. "Types.h" therefore includes some directives to enable the uses of |__swi| in the headers to be "hidden" in these cases by using -D__swi on the cc command line. Macros to suppress compiler warnings ------ -- -------- -------- -------- |NOT_USED|: Suppress "variable not used" message. |UNSET|: Suppress "variable may be used before being set" message. Additional Structuring Rules ========== =========== ===== The design aims listed in paragraph 1 are not completely compatible. In order to provide type-safety, it is necessary to provide multiple veneers for some SWI's. These fall into two classes: where a SWI has multiple reason codes, each reason code is provided with a separate function; and where a SWI has two or more different variants, each variant is provided with its own function. Reason codes ------ ----- Many SWI's have several reason codes each of which has its own distinct purpose and register usage. In this case, each reason code is provided with its own function. (SWI's with a "reason code" parameter which does not affect the interpretation of the other parameters are not treated like this: instead, the reason codes are just provided as macros.) In some cases, one reason code may itself have different sub-reason codes. In every case, the functions that are derived from the SWI use the entirety of the SWI name (with no underscore) as their prefix. Some have their own header file (e g, OS_SpriteOp, reason codes in "osspriteop.h"), others share the header file with the SWI (e g, PDriver_MiscOp, reason codes in "pdriver.h"). Toolbox_object_misc_op() has a dynamically extensible set of reason codes provided by object modules: these use the name of the object, and are in the object's header file. Where a header file name is longer than 10 characters, the full name should be used in |#include| statements. FileCore-based filing systems will truncate the file name to 10 characters, if the *Configure option 'Truncate' is 'On' (which is recommended). This means that, for example, the line |#include "messagetrans.h"| will work on all filing systems: FileCore-based ones will convert the name to "messagetra.h." OS_WriteI might be considered to have a reason code (the character to be written), but since it is part of the SWI number, each character has a separate function. This is not worthwhile for printing characters, but for other VDU codes gives useful calls like os_clg() (to clear the graphics window), os_bell() (to ring the bell) etc. (The complete list is in "os.h.") Many of the reason codes of OS_CallAVector have been omitted, namely, those where there are many sub-reason codes, and the purpose of the vector is exactly duplicated by a SWI or SWI's. So you will not find findv_- openin() (to call sub-reason code OSFind_OpenIn of reason code FindV of SWI OS_CallAVector), because it is identical in purpose to osfind_openin(). If there are reason codes but no SWI, the reason codes do have functions provided (e g, PaletteV), and if there are no reason codes, the function is provided even if it does duplicate a SWI - for example, you can call os_writec() or wrchv() with the same effect (unless you are implementing them, of course). This is all just to keep the library size down: if it causes a problem, it can be reviewed. (Since calls to OS_GenerateEvent and OS_UpCall are already distributed through many files, vectored versions of them would have to be distributed in the same way.) Lastly, calls provided by FileSwitch are in "fileswitch.h", unless they have their own header. (The separate headers are "osargs.h," osfile.h," osfind.h," osfscontrol.h," "osgbpb.h.") Also, some of the types that might be expected to be defined in these headers are actually defined in "fileswitch.h," to avoid circular references. Variants -------- Some SWI's have two or more different functions that call them, because they have two different calling conventions that cannot be easily captured using C's type system. These should be obvious from the name; failing that, the header file says exactly which SWI is called, and which values are placed into which registers. A few examples are described here, to give an idea of why variants exist. Colourtrans_select_table_for_sprite() (variant of colourtrans_select_- table()) takes an |osspriteop_area *| and an |osspriteop_id|, rather than an |os_mode| and an |os_palette *|, as its first two arguments. The same applies to colourtrans_generate_table_for_sprite() (variant of colourtrans_- generate_table()) and colourtrans_select_gcol_table_for_sprite() (variant of colourtrans_select_gcol_table()). Os_read_colour() (variant of os_set_colour()) is provided so that os_set_colour() can remain backwards-compatible. Squash_compress_return_sizes() (variant of squash_compress()) and squash_decompress_return_sizes() (variant of squash_decompress()) are provided because of the different purposes dependent on bit 3 of R0. Stringset{set,get}selected_string() and stringset{set,get}selected_index() are both provided, to allow correct typechecking of the string or integer argument. Territory_read_symbols() is divided into 3 variants, territory_read_- boolean_symbols(), territory_read_integer_symbols() and territory_read_- string_symbols(), because different symbols have different types. Wimp_send_message_to_window() (variant of wimp_send_message()) takes a |wimp_w| and a |wimp_i| rather than a |wimp_t|, and returns a result (the task handle) which wimp_send_message() does not. Conclusion ========== Although there seem to be a lot of rules, that is because the RISC O S A P I is large. For normal application programming, most of it is not needed: applications don't normally deal with vectors, upcalls or service calls, for example, or do any direct access to disc structures. However, this is not ruled out. The C headers contain the complete description of exactly what each function does in terms of the mapping of the arguments to ARM registers, so no other documentation is needed. OSLib provides a very convenient interface to the RISC O S programmer, since all the facilities of the C compiler are available to catch errors and generate good code. It is conceptually very small, in that it is completely documented by this file. As a bonus, code written using it is smaller and faster than code written using other means. Disclaimer ========== OSLib is copyright © 1995 Acorn Computers Ltd. It is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. Fault reports and suggestions for improvement may be sent to the author, Jonathan Coxhead <jcoxhead@acorn.co.uk>. Although this is an Acorn address, OSLib is not an official Acorn product.