Naming Conventions for CPU Port API

[Sebastian Huber]

Hello,

the new CPU counter API gave rise to discuss the CPU port API naming conventions.

In the score we have the following pattern:

_Package_name_Sub_package_name_Function_name

We have the following names in RTEMS:

_CPU_altivec_ctxt_off
_CPU_altivec_load_all
_CPU_altivec_psim_cpu
_CPU_altivec_save_all
_CPU_altivec_set_vrsave_initval
_CPU_altivec_vrsave_initval
_CPU_altivec_vscr_initval
_CPU_atomic_Compare_exchange_ptr
_CPU_atomic_Compare_exchange_ulong
_CPU_atomic_Exchange_ptr
_CPU_atomic_Exchange_ulong
_CPU_atomic_Fetch_add_ptr
_CPU_atomic_Fetch_add_ulong
_CPU_atomic_Fetch_and_ptr
_CPU_atomic_Fetch_and_ulong
_CPU_atomic_Fetch_or_ptr
_CPU_atomic_Fetch_or_ulong
_CPU_atomic_Fetch_sub_ptr
_CPU_atomic_Fetch_sub_ulong
_CPU_atomic_Flag_clear
_CPU_atomic_Flag_test_and_set
_CPU_atomic_Init_ptr
_CPU_atomic_Init_ulong
_CPU_atomic_Load_ptr
_CPU_atomic_Load_ulong
_CPU_atomic_Store_ptr
_CPU_atomic_Store_ulong
_CPU_Bitfield_Find_first_bit
_CPU_cache_disable_data
_CPU_cache_disable_instruction
_CPU_cache_enable_data
_CPU_cache_enable_instruction
_CPU_cache_flush_1_data_line
_CPU_cache_flush_data_range
_CPU_cache_flush_entire_data
_CPU_cache_freeze_data
_CPU_cache_freeze_instruction
_CPU_cache_invalidate_1_data_line
_CPU_cache_invalidate_1_instruction_line
_CPU_cache_invalidate_data_range
_CPU_cache_invalidate_entire_data
_CPU_cache_invalidate_entire_instruction
_CPU_cache_invalidate_instruction_range
_CPU_cache_store_data_line
_CPU_cache_unfreeze_data
_CPU_cache_unfreeze_instruction
_CPU_CACR_AND
_CPU_CACR_OR
_CPU_cacr_shadow
_CPU_change_memory_mapping_attribute
_CPU_Context_Fp_start
_CPU_Context_Get_SP
_CPU_Context_Initialization_at_thread_begin
_CPU_Context_Initialize
_CPU_Context_initialize_altivec
_CPU_Context_Initialize_fp
_CPU_Context_Restart_self
_CPU_Context_restore
_CPU_Context_restore_fp
_CPU_Context_restore_fp_from_exception
_CPU_Context_save_fp
_CPU_Context_save_fp_from_exception
_CPU_Context_switch
_CPU_Context_switch_altivec
_CPU_Context_switch_restore
_CPU_Context_validate
_CPU_Context_volatile_clobber
_CPU_Counter_Read
_CPU_Counter_Subtract
_CPU_Data_Cache_Block_Flush
_CPU_Data_Cache_Block_Invalidate
_CPU_disable_cache
_CPU_disable_paging
_CPU_display_memory_attribute
_CPU_enable_cache
_CPU_enable_paging
_CPU_Exception_frame_print
_CPU_Fatal_halt
_CPU_Initialize
_CPU_Initialize_altivec
_CPU_Initialize_vectors
_CPU_Install_interrupt_stack
_CPU_Interrupt_stack_high
_CPU_Interrupt_stack_low
_CPU_Interrupt_stack_setup
_CPU_is_cache_enabled
_CPU_is_paging_enabled
_CPU_ISR_Disable
_CPU_ISR_Dispatch_disable
_CPU_ISR_Enable
_CPU_ISR_Flash
_CPU_ISR_Get_level
_CPU_ISR_handler_entry
_CPU_ISR_install_raw_handler
_CPU_ISR_install_vector
_CPU_ISR_jump_table
_CPU_ISR_LEVEL_DO_STRINGOF
_CPU_ISR_LEVEL_STRINGOF
_CPU_ISR_Set_level
_CPU_load_altivec_volatile
_CPU_m68k_BFFFO_table
_CPU_map_phys_address
_CPU_MCF5235_H
_CPU_MCF5282_H
_CPU_MCF5XXX_H
_CPU_MSR_GET
_CPU_MSR_SET
_CPU_Null_fp_context
_CPU_Priority_bits_index
_CPU_Priority_Mask
_CPU_save_altivec_volatile
_CPU_SMP_Get_current_processor
_CPU_SMP_lock_Acquire
_CPU_SMP_lock_Initialize
_CPU_SMP_lock_ISR_disable_and_acquire
_CPU_SMP_lock_Release
_CPU_SMP_lock_Release_and_ISR_enable
_CPU_SMP_Processor_event_broadcast
_CPU_SMP_Processor_event_receive
_CPU_SMP_Send_interrupt
_CPU_Start_multitasking
_CPU_STATE
_CPU_Thread_Idle_body
_CPU_Trap_slot_template
_CPU_unmap_virt_address
_CPU_virtual_to_physical

Some ports use the _CPU prefix even though it is not part of the general CPU 
port API.  This is bad.  CPU ports should use a port specific prefix to 
highlight that something is port specific.

So you can find examples for everything.  The question is now how should it 
look like ideally?

We have two options:

1. Use a package, sub-package, function scheme:

_Package_name_Sub_package_name_Function_name

Example:

package = CPU
sub-package = SMP_lock
function = Acquire

-> _CPU_SMP_lock_Acquire

2. Use a package, function scheme:

_Package_name_Function_name

Example:

package = CPU
function = SMP_lock_acquire

-> _CPU_SMP_lock_acquire

I am in favor of (2) since its simpler.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.