diff options
Diffstat (limited to 'doc/user/conf.t')
| -rw-r--r-- | doc/user/conf.t | 752 |
1 files changed, 752 insertions, 0 deletions
diff --git a/doc/user/conf.t b/doc/user/conf.t new file mode 100644 index 0000000000..126d9b584b --- /dev/null +++ b/doc/user/conf.t @@ -0,0 +1,752 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Configuring a System, Configuring a System Configuration Table, EXTENSION_DELETE - Delete a extension set, Top +@end ifinfo +@chapter Configuring a System +@ifinfo +@menu +* Configuring a System Configuration Table:: +* Configuring a System RTEMS API Configuration Table:: +* Configuring a System POSIX API Configuration Table:: +* Configuring a System CPU Dependent Information Table:: +* Configuring a System Initialization Task Table:: +* Configuring a System Driver Address Table:: +* Configuring a System User Extensions Table:: +* Configuring a System Multiprocessor Configuration Table:: +* Configuring a System Multiprocessor Communications Interface Table:: +* Configuring a System Determining Memory Requirements:: +* Configuring a System Sizing the RTEMS RAM Workspace:: +@end menu +@end ifinfo + +@ifinfo +@node Configuring a System Configuration Table, Configuring a System RTEMS API Configuration Table, Configuring a System, Configuring a System +@end ifinfo +@section Configuration Table + +The RTEMS Configuration Table is used to tailor an +application for its specific needs. For example, the user can +configure the number of device drivers or which APIs may be used. +THe address of the user-defined Configuration Table is passed as an +argument to the initialize_executive directive, which MUST be +the first RTEMS directive called. The RTEMS Configuration Table +is defined in the following C structure: + +@example +@group +typedef struct @{ + void *work_space_start; + rtems_unsigned32 work_space_size; + rtems_unsigned32 maximum_extensions; + rtems_unsigned32 microseconds_per_tick; + rtems_unsigned32 ticks_per_timeslice; + rtems_unsigned32 maximum_devices; + rtems_unsigned32 number_of_device_drivers; + rtems_driver_address_table *Device_driver_table; + rtems_extensions_table *User_extension_table; + rtems_multiprocessing_table *User_multiprocessing_table; + rtems_api_configuration_table *RTEMS_api_configuration; + posix_api_configuration_table *POSIX_api_configuration; +@} rtems_configuration_table; +@end group +@end example + +@table @b +@item work_space_start +is the address of the RTEMS RAM Workspace. +This area contains items such as the +various object control blocks (TCBs, QCBs, ...) and task stacks. +If the address is not aligned on a four-word boundary, then +RTEMS will invoke the fatal error handler during +initialize_executive. + +@item work_space_size +is the calculated size of the +RTEMS RAM Workspace. The section Sizing the RTEMS RAM Workspace +details how to arrive at this number. + +@item microseconds_per_tick +is number of microseconds per clock tick. + +@item ticks_per_timeslice +is the number of clock ticks for a timeslice. + +@item maximum_devices +is the maximum number of devices that can be registered. + +@item number_of_device_drivers +is the number of device drivers for the system. There should be +the same number of entries in the Device Driver Table. If this field +is zero, then the User_driver_address_table entry should be NULL. + +@item Device_driver_table +is the address of the Device Driver Table. This table contains the entry +points for each device driver. If the number_of_device_drivers field is zero, +then this entry should be NULL. The format of this table will be +discussed below. + +@item User_extension_table +is the address of the User +Extension Table. This table contains the entry points for the +static set of optional user extensions. If no user extensions +are configured, then this entry should be NULL. The format of +this table will be discussed below. + +@item User_multiprocessing_table +is the address of the Multiprocessor Configuration Table. This +table contains information needed by RTEMS only when used in a multiprocessor +configuration. This field must be NULL when RTEMS is used in a +single processor configuration. + +@item RTEMS_api_configuration +is the address of the RTEMS API Configuration Table. This table +contains information needed by the RTEMS API. This field should be +NULL if the RTEMS API is not used. [NOTE: Currently the RTEMS API +is required to support support components such as BSPs and libraries +which use this API.] + +@item POSIX_api_configuration +is the address of the POSIX API Configuration Table. This table +contains information needed by the POSIX API. This field should be +NULL if the POSIX API is not used. + +@end table + +@ifinfo +@node Configuring a System RTEMS API Configuration Table, Configuring a System POSIX API Configuration Table, Configuring a System Configuration Table, Configuring a System +@end ifinfo +@section RTEMS API Configuration Table + +The RTEMS API Configuration Table is used to configure the +managers which constitute the RTEMS API for a particular application. +For example, the user can configure the maximum number of tasks for +this application. The RTEMS API Configuration Table is defined in +the following C structure: + +@example +@group +typedef struct @{ + rtems_unsigned32 maximum_tasks; + rtems_unsigned32 maximum_timers; + rtems_unsigned32 maximum_semaphores; + rtems_unsigned32 maximum_message_queues; + rtems_unsigned32 maximum_partitions; + rtems_unsigned32 maximum_regions; + rtems_unsigned32 maximum_ports; + rtems_unsigned32 maximum_periods; + rtems_unsigned32 number_of_initialization_tasks; + rtems_initialization_tasks_table *User_initialization_tasks_table; +@} rtems_api_configuration_table; +@end group +@end example + +@table @b +@item maximum_tasks +is the maximum number of tasks that +can be concurrently active (created) in the system including +initialization tasks. + +@item maximum_timers +is the maximum number of timers +that can be concurrently active in the system. + +@item maximum_semaphores +is the maximum number of +semaphores that can be concurrently active in the system. + +@item maximum_message_queues +is the maximum number of +message queues that can be concurrently active in the system. + +@item maximum_partitions +is the maximum number of +partitions that can be concurrently active in the system. + +@item maximum_regions +is the maximum number of regions +that can be concurrently active in the system. + +@item maximum_ports +is the maximum number of ports into +dual-port memory areas that can be concurrently active in the +system. + +@item number_of_initialization_tasks +is the number of initialization tasks configured. At least one +initialization task must be configured. + +@item User_initialization_tasks_table +is the address of the Initialization Task Table. This table contains the +information needed to create and start each of the +initialization tasks. The format of this table will be discussed below. + +@end table + +@ifinfo +@node Configuring a System POSIX API Configuration Table, Configuring a System CPU Dependent Information Table, Configuring a System RTEMS API Configuration Table, Configuring a System +@end ifinfo +@section POSIX API Configuration Table + +The POSIX API Configuration Table is used to configure the +managers which constitute the POSIX API for a particular application. +For example, the user can configure the maximum number of threads for +this application. The POSIX API Configuration Table is defined in +the following C structure: + +@example +@group +typedef struct @{ + void *(*entry)(void *); +@} posix_initialization_threads_table; + +typedef struct @{ + int maximum_threads; + int maximum_mutexes; + int maximum_condition_variables; + int maximum_keys; + int maximum_queued_signals; + int number_of_initialization_tasks; + posix_initialization_threads_table *User_initialization_tasks_table; +@} posix_api_configuration_table; +@end group +@end example + +@table @b +@item maximum_threads +is the maximum number of threads that +can be concurrently active (created) in the system including +initialization threads. + +@item maximum_mutexes +is the maximum number of mutexes that can be concurrently +active in the system. + +@item maximum_condition_variables +is the maximum number of condition variables that can be +concurrently active in the system. + +@item maximum_keys +is the maximum number of keys that can be concurrently active in the system. + +@item maximum_queued_signals +is the maximum number of queued signals that can be concurrently +pending in the system. + +@item number_of_initialization_threads +is the number of initialization threads configured. At least one +initialization threads must be configured. + +@item User_initialization_threads_table +is the address of the Initialization Threads Table. This table contains the +information needed to create and start each of the initialization threads. +The format of each entry in this table is defined in the +posix_initialization_threads_table structure. + +@end table + +@ifinfo +@node Configuring a System CPU Dependent Information Table, Configuring a System Initialization Task Table, Configuring a System POSIX API Configuration Table, Configuring a System +@end ifinfo +@section CPU Dependent Information Table + +The CPU Dependent Information Table is used to +describe processor dependent information required by RTEMS. +This table is generally used to supply RTEMS with information +only known by the Board Support Package. The contents of this +table are discussed in the CPU Dependent Information Table +chapter of the C Applications Supplement document for a specific +target processor. + +@ifinfo +@node Configuring a System Initialization Task Table, Configuring a System Driver Address Table, Configuring a System CPU Dependent Information Table, Configuring a System +@end ifinfo +@section Initialization Task Table + +The Initialization Task Table is used to describe +each of the user initialization tasks to the Initialization +Manager. The table contains one entry for each initialization +task the user wishes to create and start. The fields of this +data structure directly correspond to arguments to the +task_create and task_start directives. The number of entries is +found in the number_of_initialization_tasks entry in the +Configuration Table. The format of each entry in the +Initialization Task Table is defined in the following C +structure: + +@example +typedef struct @{ + rtems_name name; + rtems_unsigned32 stack_size; + rtems_task_priority initial_priority; + rtems_attribute attribute_set; + rtems_task_entry entry_point; + rtems_mode mode_set; + rtems_task_argument argument; +@} rtems_initialization_tasks_table; +@end example + +@table @b +@item name +is the name of this initialization task. + +@item stack_size +is the size of the stack for this initialization task. + +@item initial_priority +is the priority of this initialization task. + +@item attribute_set +is the attribute set used during creation of this initialization task. + +@item entry_point +is the address of the entry point of this initialization task. + +@item mode_set +is the initial execution mode of this initialization task. + +@item argument +is the initial argument for this initialization task. + +@end table + +A typical declaration for an Initialization Task Table might appear as follows: + +@example +rtems_initialization_tasks_table +Initialization_tasks[2] = @{ + @{ INIT_1_NAME, + 1024, + 1, + DEFAULT_ATTRIBUTES, + Init_1, + DEFAULT_MODES, + 1 + + @}, + @{ INIT_2_NAME, + 1024, + 250, + FLOATING_POINT, + Init_2, + INTERRUPT_LEVEL(0)|NO_PREEMPT, + 2 + + @} +@}; +@end example + +@ifinfo +@node Configuring a System Driver Address Table, Configuring a System User Extensions Table, Configuring a System Initialization Task Table, Configuring a System +@end ifinfo +@section Driver Address Table + +The Device Driver Table is used to inform the I/O +Manager of the set of entry points for each device driver +configured in the system. The table contains one entry for each +device driver required by the application. The number of +entries is defined in the number_of_device_drivers entry in the +Configuration Table. The format of each entry in the Device +Driver Table is defined in the following C structure: + +@example +typedef struct @{ + rtems_device_driver_entry initialization; + rtems_device_driver_entry open; + rtems_device_driver_entry close; + rtems_device_driver_entry read; + rtems_device_driver_entry write; + rtems_device_driver_entry control; +@} rtems_driver_address_table; +@end example + +@table @b +@item initialization +is the address of the entry point called by io_initialize +to initialize a device driver and its associated devices. + +@item open +is the address of the entry point called by io_open. + +@item close +is the address of the entry point called by io_close. + +@item read +is the address of the entry point called by io_read. + +@item write +is the address of the entry point called by io_write. + +@item control +is the address of the entry point called by io_control. + +@end table + +Driver entry points configured as NULL will always +return a status code of SUCCESSFUL. No user code will be +executed in this situation. + +A typical declaration for a Device Driver Table might appear as follows: + +@example +rtems_driver_address_table Driver_table[2] = @{ + @{ tty_initialize, tty_open, tty_close, /* major = 0 */ + tty_read, tty_write, tty_control + @}, + @{ lp_initialize, lp_open, lp_close, /* major = 1 */ + NULL, lp_write, lp_control + @} +@}; +@end example + +More information regarding the construction and +operation of device drivers is provided in the I/O Manager +chapter. + +@ifinfo +@node Configuring a System User Extensions Table, Configuring a System Multiprocessor Configuration Table, Configuring a System Driver Address Table, Configuring a System +@end ifinfo +@section User Extensions Table + +The User Extensions Table is used to inform RTEMS of +the optional user-supplied static extension set. This table +contains one entry for each possible extension. The entries are +called at critical times in the life of the system and +individual tasks. The application may create dynamic extensions +in addition to this single static set. The format of each entry +in the User Extensions Table is defined in the following C +structure: + +@example +typedef struct @{ + User_extensions_thread_create_extension thread_create; + User_extensions_thread_start_extension thread_start; + User_extensions_thread_restart_extension thread_restart; + User_extensions_thread_delete_extension thread_delete; + User_extensions_thread_switch_extension thread_switch; + User_extensions_thread_post_switch_extension thread_post_switch; + User_extensions_thread_begin_extension thread_begin; + User_extensions_thread_exitted_extension thread_exitted; + User_extensions_fatal_error_extension fatal; +@} User_extensions_Table; +@end example + +@table @b + +@item thread_create +is the address of the +user-supplied subroutine for the TASK_CREATE extension. If this +extension for task creation is defined, it is called from the +task_create directive. A value of NULL indicates that no +extension is provided. + +@item thread_start +is the address of the user-supplied +subroutine for the TASK_START extension. If this extension for +task initiation is defined, it is called from the task_start +directive. A value of NULL indicates that no extension is +provided. + +@item thread_restart +is the address of the user-supplied +subroutine for the TASK_RESTART extension. If this extension +for task re-initiation is defined, it is called from the +task_restart directive. A value of NULL indicates that no +extension is provided. + +@item thread_delete +is the address of the user-supplied +subroutine for the TASK_DELETE extension. If this RTEMS +extension for task deletion is defined, it is called from the +task_delete directive. A value of NULL indicates that no +extension is provided. + +@item thread_switch +is the address of the user-supplied +subroutine for the task context switch extension. This +subroutine is called from RTEMS dispatcher after the current +task has been swapped out but before the new task has been +swapped in. A value of NULL indicates that no extension is +provided. As this routine is invoked after saving the current +task's context and before restoring the heir task's context, it +is not necessary for this routine to save and restore any +registers. + +@item thread_post_switch +is the address of the +user-supplied subroutine for the post task context switch +extension. This subroutine is called from RTEMS dispatcher in +the context of the task which has just been swapped in. + +@item thread_begin +is the address of the user-supplied +subroutine which is invoked immediately before a task begins +execution. It is invoked in the context of the beginning task. +A value of NULL indicates that no extension is provided. + +@item thread_exitted +is the address of the user-supplied +subroutine which is invoked when a task exits. This procedure +is responsible for some action which will allow the system to +continue execution (i.e. delete or restart the task) or to +terminate with a fatal error. If this field is set to NULL, the +default RTEMS task_exitted handler will be invoked. + +@item fatal +is the address of the user-supplied +subroutine for the FATAL extension. This RTEMS extension of +fatal error handling is called from the fatal_error_occurred +directive. If the user's fatal error handler returns or if this +entry is NULL then the default RTEMS fatal error handler will be +executed. + +@end table + +A typical declaration for a User Extension Table +which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and +FATAL extension might appear as follows: + +@example +rtems_extensions_table User_extensions = @{ + task_create_extension, + NULL, + NULL, + task_delete_extension, + task_switch_extension, + NULL, + NULL, + fatal_extension +@}; +@end example + +More information regarding the user extensions is +provided in the User Extensions chapter. + +@ifinfo +@node Configuring a System Multiprocessor Configuration Table, Configuring a System Multiprocessor Communications Interface Table, Configuring a System User Extensions Table, Configuring a System +@end ifinfo +@section Multiprocessor Configuration Table + +The Multiprocessor Configuration Table contains +information needed when using RTEMS in a multiprocessor +configuration. Many of the details associated with configuring +a multiprocessor system are dependent on the multiprocessor +communications layer provided by the user. The address of the +Multiprocessor Configuration Table should be placed in the +User_multiprocessing_table entry in the primary Configuration +Table. Further details regarding many of the entries in the +Multiprocessor Configuration Table will be provided in the +Multiprocessing chapter. The format of the Multiprocessor +Configuration Table is defined in the following C structure: + +@example +typedef struct @{ + rtems_unsigned32 node; + rtems_unsigned32 maximum_nodes; + rtems_unsigned32 maximum_global_objects; + rtems_unsigned32 maximum_proxies; + rtems_mpci_table *User_mpci_table; +@} rtems_multiprocessing_table; +@end example + +@table @b +@item node +is a unique processor identifier +and is used in routing messages between nodes in a +multiprocessor configuration. Each processor must have a unique +node number. RTEMS assumes that node numbers start at one and +increase sequentially. This assumption can be used to advantage +by the user-supplied MPCI layer. Typically, this requirement is +made when the node numbers are used to calculate the address of +inter-processor communication links. Zero should be avoided as +a node number because some MPCI layers use node zero to +represent broadcasted packets. Thus, it is recommended that +node numbers start at one and increase sequentially. + +@item maximum_nodes +is the number of processor nodes in the system. + +@item maximum_global_objects +is the maximum number of global objects which can exist at any +given moment in the entire system. If this parameter is not the +same on all nodes in the system, then a fatal error is generated +to inform the user that the system is inconsistent. + +@item maximum_proxies +is the maximum number of proxies which can exist at any given moment +on this particular node. A proxy is a substitute task control block +which represent a task residing on a remote node when that task blocks +on a remote object. Proxies are used in situations in which delayed +interaction is required with a remote node. + +@item User_mpci_table +is the address of the Multiprocessor Communications Interface +Table. This table contains the entry points of user-provided functions +which constitute the multiprocessor communications layer. This table +must be provided in multiprocessor configurations with all +entries configured. The format of this table and details +regarding its entries can be found in the next section. + +@end table + +@ifinfo +@node Configuring a System Multiprocessor Communications Interface Table, Configuring a System Determining Memory Requirements, Configuring a System Multiprocessor Configuration Table, Configuring a System +@end ifinfo +@section Multiprocessor Communications Interface Table + +The format of this table is defined in the following C structure: + +@example +typedef struct @{ + rtems_unsigned32 default_timeout; /* in ticks */ + rtems_unsigned32 maximum_packet_size; + rtems_mpci_initialization_entry initialization; + rtems_mpci_get_packet_entry get_packet; + rtems_mpci_return_packet_entry return_packet; + rtems_mpci_send_entry send; + rtems_mpci_receive_entry receive; +@} rtems_mpci_table; +@end example + +@table @b +@item default_timeout +is the default maximum length of time a task should block waiting for +a response to a directive which results in communication with a remote node. +The maximum length of time is a function the user supplied +multiprocessor communications layer and the media used. This +timeout only applies to directives which would not block if the +operation were performed locally. + +@item maximum_packet_size +is the size in bytes of the longest packet which the MPCI layer is capable +of sending. This value should represent the total number of bytes available +for a RTEMS interprocessor messages. + +@item initialization +is the address of the entry point for the initialization procedure of the +user supplied multiprocessor communications layer. + +@item get_packet +is the address of the entry point for the procedure called by RTEMS to +obtain a packet from the user supplied multiprocessor communications layer. + +@item return_packet +is the address of the entry point for the procedure called by RTEMS to +return a packet to the user supplied multiprocessor communications layer. + +@item send +is the address of the entry point for the procedure called by RTEMS to +send an envelope to another node. This procedure is part of the user +supplied multiprocessor communications layer. + +@item receive +is the address of the entry point for the +procedure called by RTEMS to retrieve an envelope containing a +message from another node. This procedure is part of the user +supplied multiprocessor communications layer. + +@end table + +More information regarding the required functionality of these +entry points is provided in the Multiprocessor chapter. + +@ifinfo +@node Configuring a System Determining Memory Requirements, Configuring a System Sizing the RTEMS RAM Workspace, Configuring a System Multiprocessor Communications Interface Table, Configuring a System +@end ifinfo +@section Determining Memory Requirements + +Since memory is a critical resource in many real-time +embedded systems, RTEMS was specifically designed to allow +unused managers to be excluded from the run-time environment. +This allows the application designer the flexibility to tailor +RTEMS to most efficiently meet system requirements while still +satisfying even the most stringent memory constraints. As +result, the size of the RTEMS executive is application +dependent. A Memory Requirements worksheet is provided in the C +Applications Supplement document for a specific target +processor. This worksheet can be used to calculate the memory +requirements of a custom RTEMS run-time environment. To insure +that enough memory is allocated for future versions of RTEMS, +the application designer should round these memory requirements +up. The following managers may be optionally excluded: + +@itemize @bullet +@item signal +@item region +@item dual ported memory +@item event +@item multiprocessing +@item partition +@item timer +@item semaphore +@item message +@item rate monotonic +@end itemize + +RTEMS based applications must somehow provide memory +for RTEMS' code and data space. Although RTEMS' data space must +be in RAM, its code space can be located in either ROM or RAM. +In addition, the user must allocate RAM for the RTEMS RAM +Workspace. The size of this area is application dependent and +can be calculated using the formula provided in the Memory +Requirements chapter of the C Applications Supplement document +for a specific target processor. + +All RTEMS data variables and routine names used by +RTEMS begin with the underscore ( _ ) character followed by an +upper-case letter. If RTEMS is linked with an application, then +the application code should NOT contain any symbols which begin +with the underscore character and followed by an upper-case +letter to avoid any naming conflicts. All RTEMS directive names +should be treated as reserved words. + +@ifinfo +@node Configuring a System Sizing the RTEMS RAM Workspace, Multiprocessing Manager, Configuring a System Determining Memory Requirements, Configuring a System +@end ifinfo +@section Sizing the RTEMS RAM Workspace + +The RTEMS RAM Workspace is a user-specified block of +memory reserved for use by RTEMS. The application should NOT +modify this memory. This area consists primarily of the RTEMS +data structures whose exact size depends upon the values +specified in the Configuration Table. In addition, task stacks +and floating point context areas are dynamically allocated from +the RTEMS RAM Workspace. + +The starting address of the RTEMS RAM Workspace must +be aligned on a four-byte boundary. Failure to properly align +the workspace area will result in the fatal_error_occurred +directive being invoked with the INVALID_ADDRESS error code. + +A worksheet is provided in the Memory Requirements +chapter of the C Applications Supplement document for a specific +target processor to assist the user in calculating the minimum +size of the RTEMS RAM Workspace for each application. The value +calculated with this worksheet is the minimum value that should +be specified as the work_space_size parameter of the +Configuration Table. The user is cautioned that future versions +of RTEMS may not have the same memory requirements per object. +Although the value calculated is sufficient for a particular +target processor and release of RTEMS, memory usage is subject +to change across versions and target processors. The user is +advised to allocate somewhat more memory than the worksheet +recommends to insure compatibility with future releases for a +specific target processor and other target processors. To avoid +problems, the user should recalculate the memory requirements +each time one of the following events occurs: + +@itemize @bullet +@item a configuration parameter is modified, +@item task or interrupt stack requirements change, +@item task floating point attribute is altered, +@item RTEMS is upgraded, or +@item the target processor is changed. +@end itemize + +Failure to provide enough space in the RTEMS RAM +Workspace will result in the fatal_error_occurred directive +being invoked with the appropriate error code. |