/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/*
* Copyright 1999-2002 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _SYS_1394_T1394_H
#define _SYS_1394_T1394_H
#pragma ident "%Z%%M% %I% %E% SMI"
/*
* t1394.h
* Contains all of the prototypes, defines, and structures necessary
* for building drivers using the Solaris 1394 Software Framework.
*/
#include <sys/dditypes.h>
#ifdef __cplusplus
extern "C" {
#endif
/*
* Macro to convert a byte stream into a big endian quadlet or octlet or
* back the other way. All data is treated as byte streams over the 1394
* bus. These macros will convert the data to a big endian "integer" on
* x86 platforms, and it will do nothing if it is not on x86.
*/
#ifdef _LITTLE_ENDIAN
#else
#endif
/* The various "handles" returned by the 1394 Framework */
/* Target handle type */
/* Address handle type */
/* Isoch single handle type */
/* Isoch CEC handle type */
/* Config ROM handle type */
/*
* t1394_localinfo_t
* is filled in and returned by the 1394 Framework at attach time
* (in the t1394_attachinfo_t structure returned from t1394_attach())
* to provide the local host nodeID and the current bus generation.
*/
typedef struct t1394_localinfo_s {
/*
* t1394_attachinfo_t
* is filled in and returned by the 1394 Framework at attach time
* (returned from the call to t1394_attach()). This structure contains
* the t1394_localinfo_t structure described above, as well as the
* iblock cookie and the attributes necessary for DMA allocations, etc.
*/
typedef struct t1394_attachinfo_s {
/*
* t1394_addr_enable_t
* is used in the t1394_alloc_addr_t structure, passed to
* t1394_alloc_addr(), to indicate what types of (incoming)
* asynchronous requests will be allowed in a given address block.
* If, for example, an address block is intended to be read-only,
* then only the T1394_ADDR_RDENBL bit should be enabled at allocation
* time. Then, when incoming requests of an inappropriate type (write
* or lock requests, in this case) arrive, the 1394 Framework can
* automatically respond to them with TYPE_ERROR in the response
* without having to notify the target driver.
*/
typedef enum {
/*
* t1394_addr_type_t
* is used in the t1394_alloc_addr_t structure, passed to
* t1394_alloc_addr(), to indicate what type of address block the
* target driver would like to allocate.
* T1394_ADDR_POSTED_WRITE indicates posted write memory, where
* incoming write requests are automatically acknowledged as complete.
* T1394_ADDR_NORMAL indicates memory, unlike the posted write area,
* where all requests regardless of type are ack_pended upon receipt
* and are subsequently responded to.
* T1394_ADDR_CSR memory range is generally used by target drivers
* that are implementing a well-defined protocol.
* And T1394_ADDR_FIXED is used to indicate to t1394_alloc_addr()
* that a specific set of addresses are needed. Unlike the other three
* types, this type of request is used to choose a specific address or
* range of addresses in 1394 address space.
*/
typedef enum {
/*
* t1394_addr_evts_t
* is used in the t1394_alloc_addr_t structure, passed to
* t1394_alloc_addr(), to specify callback routines for the
* allocated address block. When a request of the appropriate type
* block, the appropriate callback routine is consulted and if it is
* non-NULL it is called and passed a cmd1394_cmd_t structure used to
* describe the incoming asynch request.
*/
typedef struct t1394_addr_evts {
/*
* t1394_alloc_addr_t
* is passed to t1394_alloc_addr(), when 1394 address space is being
* allocated, to describe the type of address space. The target driver
* is responsible for specifying the aa_enable, aa_type, and aa_evts
* fields described above as well as the size of the allocated block.
* Additionally, the target driver may specify backing store
* (aa_kmem_bufp), a specific address (in aa_address if aa_type is
* T1394_ADDR_FIXED), and a callback argument (in aa_arg) to be
* passed to the target in any of its callback routines.
* When it returns, t1394_alloc_addr() will return in aa_address the
* starting address of the requested block of 1394 address space and
* and address block handle (aa_hdl) used to free the address block
* in a call to t1394_free_addr().
*/
typedef struct t1394_alloc_addr {
/*
* t1394_fcp_evts_t
* is used in t1394_fcp_register_controller(). FCP only allows writes.
*/
typedef struct t1394_fcp_evts {
/* values returned by the FCP callback */
enum {
};
/*
* t1394_cmp_reg_t
* CMP register types
*/
typedef enum {
/*
* t1394_cmp_evts_t
* is used in t1394_cmp_register().
*/
typedef struct t1394_cmp_evts {
/*
* t1394_isoch_rsrc_error_t
* is used in the rsrc_fail_target() callback to indicate the reason
* for the resource allocation failure. T1394_RSRC_BANDWIDTH indicates
* that insufficient bandwidth was available for the requested allocation,
* and T1394_RSRC_CHANNEL indicates that none of the requested channels
* were available.
*/
typedef enum {
/*
* t1394_isoch_singleinfo_t
* is passed to the t1394_alloc_isoch_single() routine. A target
* driver will use this structure to indicate the channels it supports,
* the maximum speed for the isochronous channel, the amount of
* bandwidth required, and the callback (and callback arg) to be used
* when notifying the target of resource reallocation failures.
*/
typedef struct t1394_isoch_singleinfo_s {
void (*rsrc_fail_target)(
/*
* t1394_isoch_single_out_t
* is filled in and returned to the target by the
* t1394_alloc_isoch_single() routine. It indicates the number of the
* channel that was actually allocated for the target driver. This
* channel number will typically be used by a target driver to setup
* isochronous DMA or other resources.
*/
typedef struct t1394_isoch_single_out_s {
/*
* t1394_setup_target_args_t
* is used in the setup_target() callback to indicate the channel number
* and channel speed for the isochronous channel coordinated by the
* Isoch CEC routines.
*/
typedef struct t1394_setup_target_args_s {
/*
* t1394_cec_options_t
* is used in the t1394_isoch_cec_props_t structure, passed to
* t1394_alloc_isoch_cec(). As the cec_options field in that
* structure, it can be used to request that the 1394 Framework
* NOT automatically reallocate the same isochronous channel and
* bandwidth, if a bus reset happens. The default behavior is to
* let the 1394 Framework attempt to reallocate the same channel and
* bandwidth the target had after a bus reset, but some target drivers
* may not require this functionality and they therefore have the option
* to decline this service.
*/
typedef enum {
/*
* t1394_isoch_cec_props_t
* is used in calls to the t1394_alloc_isoch_cec() routine. The
* minimum and maximum speeds, channels supported, and the amount
* of bandwidth necessary for the channel are specified. These
* characteristics of the Isoch CEC are specified at allocation time
* and are used to pass or fail targets that try to join the Isoch
* CEC later.
*/
typedef struct t1394_isoch_cec_props_s {
/*
* t1394_isoch_cec_evts_t
* is used in the t1394_join_isochinfo_t structure, passed to
* t1394_join_isoch_cec(). This structure is a list of callbacks
* for each of the various events the Isoch CEC is responsible for
* coordinating.
* The setup_target() callback is called after the isochronous
* channel and bandwidth for the Isoch CEC have been allocated
* (as a result of a call to t1394_setup_isoch_cec()) to inform the
* member targets of the channel number and speed.
* The start_target() callback is called for all member targets
* as a result of a call to t1394_start_isoch_cec().
* The stop_target() callback is called for all member targets
* as a result of a call to t1394_stop_isoch_cec().
* The rsrc_fail_target() callback (as mentioned above) is called
* to indicate that the 1394 Framework was unable to reallocate
* isochronous resources and the reason for the failure.
* And the teardown_target() callback is called as a result of
* a call to t1394_teardown_isoch_cec() to indicate that the
* isochronous channel and bandwidth are being freed up.
*/
typedef struct t1394_isoch_cec_evts_s {
int (*setup_target)(
int (*start_target)(
void (*stop_target)(
void (*rsrc_fail_target)(
void (*teardown_target)(
/*
* t1394_jii_options_t
* is used in the t1394_join_isochinfo_t structure, passed to
* t1394_join_isoch_cec(). As the jii_options field in that
* structure, it is used to indicate to the 1394 Framework
* that the member target is the talker on the channel. There can
* be no more than one talker per Isoch CEC, and a member target
* may fail in t1394_join_isoch_cec() because there is already a
* talker on the Isoch CEC.
*/
typedef enum {
/*
* t1394_join_isochinfo_t
* is used in calls to the t1394_join_isoch_cec() routine. The
* req_channel_mask field indicate the channels that a member
* target can support. If these channels are inconsistent with
* the characteristics passed in at allocation or with the current
* characteristics of the other members of the Isoch CEC, then the
* t1394_join_isoch_cec() call will fail.
* The req_max_speed field is used similarly. If the member target's
* maximum speed is inconsistent with the other members of the
* Isoch CEC, then the t1394_join_isoch_cec() will fail.
* In addition to the above fields, a joining member target will pass
* the jii_options (indicate talker or listener), the callbacks and
* the callback arg (see above).
*/
typedef struct t1394_join_isochinfo_s {
/*
* t1394_targetinfo_t
* is used in calls to the t1394_get_targetinfo() routine. The
* structure returned to the target contains current_max_payload,
* the default maximum block size that the host device will use in
* asynchronous block reads and writes to the target's device.
* It also contains current_max_speed, the default maximum speed at
* which the host device will communicate with the target's device.
* The structure also contains the target driver's target nodeID,
* the number assigned to the device for the current bus
* generation. It will contain T1394_INVALID_NODEID if the target
* device is no longer connected to the 1394 Serial Bus.
*/
typedef struct t1394_targetinfo_s {
/*
* t1394_cfgrom_entryinfo_t
* is used in calls to the t1394_add_cfgrom_entry() routine. The
* t1394_cfgrom_entryinfo_t structure contains the information necessary
* to add the Config ROM entry. The ce_buffer and ce_size are used to
* describe the data to be added, and the ce_key is used to indicate
* what type of entry in the Config ROM buffer the data represents
* (see ieee1212.h fro key types).
*/
typedef struct t1394_cfgrom_entryinfo_s {
/*
* ATTACH and DETACH:
* These are the calls into 1394 Framework used during target driver
* attach() and detach(). The t1394_attach() routine takes a dip and
* a version (T1394_VERSION_V1) as its input arguments, and it fills
* in and returns a t1394_attachinfo_t structure (described above) and
* the t1394_handle_t. This target handle is used in all subsequent
* calls into the 1394 Framework.
* The t1394_detach() routine is called from a target driver's detach()
* routine to unregister itself from the 1394 Framework.
*/
/* Version value */
/*
* OUTGOING ASYNCHRONOUS COMMANDS:
* These are the calls into 1394 Framework used for allocating/freeing
* and sending (outgoing) asynchronous requests. The t1394_alloc_cmd()
* routine takes a target driver's handle as an input argument and
* returns the cmd1394_cmd_t structure necessary for sending asynch
* requests. The flags parameter is used to indicate whether or not the
* 1394 Framework may sleep while allocating memory for the command.
* The t1394_free_cmd() routine is used to free up commands allocated
* by t1394_alloc_cmd(). Commands should not be in use at the time
* t1394_free_cmd() is called or the call may fail (return DDI_FAILURE).
* After an asynch command has been allocated and filled in (see
* the cmd1394.h file for more details) to indicate the type of request,
* (if necessary), the command is passed to either t1394_read(),
* t1394_write(), or t1394_lock(). These routines will return DDI_SUCCESS
* or DDI_FAILURE depending on whether the command has been successfully
* accepted by the 1394 Framework. If the command is a "blocking"
* command, the function will not return until the command has completed.
* If, however, a callback has been specified in the command, that
* function will be called when the command completes.
*/
cmd1394_cmd_t **cmdp);
/* Flags passed to t1394_alloc_cmd() */
cmd1394_cmd_t **cmdp);
/*
* 1394 ADDRESS SPACE AND INCOMING ASYNCHRONOUS COMMANDS:
* These are the calls into the 1394 Framework used for allocating/freeing
* 1394 address space and handling incoming asynchronous requests. The
* t1394_alloc_addr() routine is used to allocate 1394 address space. It
* is passed the target handle and a t1394_alloc_addr_t structure
* (described above).
* The t1394_free_addr() routine is used to free any allocated address
* space that the target may have. Typically, this will be done in a
* target driver's detach() routine (before calling t1394_detach()).
* The t1394_recv_request_done() routine is used after a target has
* received and handled an incoming asynch request. It is used to send
* a response to the request. After the command is sent to
* t1394_recv_request_done(), it should not be modified or used because
* the 1394 Framework may free it up without notifying the target driver.
*/
/* Results codes returned by t1394_alloc_addr() */
/*
* NOTE: Make sure T1394_EADDR_LAST is updated if a new error code is
* added. t1394_errmsg.c uses *FIRST and *LAST as bounds checks.
*/
/*
* FCP SERVICES:
* Function Control Protocol (FCP) is defined in IEC 61883-1 and supported
* by the 1394 Framework. While target drivers could use t1394_alloc_addr()
* and standard asynchronous services, only one driver could use FCP at a
* time, because the FCP addresses have fixed values. To allow sharing of
* FCP address space, the following Framework services should be used.
*
* t1394_fcp_register_controller() registers the target as an FCP controller,
* which allows it to write into target's FCP command register and receive
* write requests into host's FCP response register. It takes a valid
* t1394_handle_t argument, hence it should be called after t1394_attach().
* t1394_fcp_unregister_controller() unregisters the target.
*
* t1394_fcp_register_target() and t1394_fcp_unregister_target() are
* target counterparts of the above controller functions.
*/
/*
* CMP services:
* Connection Management Procedures (CMP) is defined in IEC 61883-1 and
* supported by the 1394 Framework by providing the drivers with shared
* access to iMPR and oMPR registers, which are created by the Framework
* when t1394_cmp_register() is called and destroyed when
* t1394_cmp_unregister() is called. These registers can be read using
* t1394_cmp_read() function and compare-swapped using t1394_cmp_cas().
*
* oPCR and iPCR registers can be allocated by the drivers using
* t1394_alloc_addr() function.
*/
/*
* ISOCHRONOUS SERVICES:
* These are the calls into the 1394 Framework used for isochronous
* services. The t1394_alloc_isoch_single() routine takes a target
* handle and a t1394_isoch_singleinfo_t structure (see above). It will
* attempt to setup an isochronous channel (which will be automatically
* reallocated after bus resets), and it will return the channel number
* of the allocated channel in the t1394_isoch_single_out_t structure.
* Additionally, it returns a t1394_isoch_single_handle_t structure
* which is passed to t1394_free_isoch_single() when the isochronous
* channel is no longer required.
* The t1394_alloc_isoch_cec() and t1394_free_isoch_cec() are used to
* allocate and free an Isoch Channel Event Coordinator (CEC). Target
* drivers pass a t1394_isoch_cec_props_t structure (described above)
* to specify the initial characteristics of the Isoch CEC.
* Targets will subsequently join the Isoch CEC with t1394_join_isoch_cec()
* before setting up the channel with t1394_setup_isoch_cec().
* Calls to t1394_join_isoch_cec() are used by targets who wish to join
* the Isoch CEC and receive all of the channel event notifications.
* When they want to leave target drivers call t1394_leave_isoch_cec().
* The t1394_setup_isoch_cec(), as described above, is used to setup the
* the isochronous channel and bandwidth and to notify all member targets
* of the allocated channel number and speed. After targets have finished
* using the isoch channel, the resources can be torn down with a call to
* t1394_teardown_isoch_cec().
* Additionally, the t1394_start_isoch_cec() and t1394_stop_isoch_cec()
* routines can be used by member targets to coordinate additional events,
* such as the starting and stopping of isochronous DMA or other resources.
*/
/* Results codes returned by t1394_setup_isoch_cec() */
/*
* NOTE: Make sure T1394_ERR_LAST is updated if a new error code is
* added. t1394_errmsg.c uses *FIRST and *LAST as bounds checks.
*/
/*
* ISOCHRONOUS DMA (LOCAL ISOCH DMA) SERVICES:
* These are the calls into the 1394 Framework used for local
* isochronous DMA services. The t1394_alloc_isoch_dma() routine
* takes a target handle and an id1394_isoch_dmainfo_t structure
* (see id1394.h for details) as its input arguments and returns a
* t1394_isoch_dma_handle_t that the target driver will use with all
* other local host DMA calls. After allocating a local host DMA
* resource, a target driver may start and stop it as often as desired
* using the t1394_start_isoch_dma() and t1394_stop_isoch_dma() calls.
* The t1394_start_isoch_dma() takes an id1394_isoch_dma_ctrlinfo_t
* structure (also discussed in more detail in id1394.h) as an
* additional argument to indicate among other things the conditions
* under which the host DMA will be started.
* The t1394_free_isoch_dma() is used, not surprisingly, to free up
* allocate isoch DMA resources.
* And the t1394_update_isoch_dma() routine is used to update a running
* isochronous stream. By creating and passing a temporary IXL command
* or set of commands and both the kernel virtual addresses of the
* temporary and original commands, a target driver can request that the
* 1394 Framework replace the original field contents with those in the
* temporary command and update the corresponding hardware DMA elements.
*/
/*
* Results codes returned by t1394_alloc_isoch_dma(). See ixl1394.h for possible
* IXL1394 compilation errors.
* NOTE: Make sure T1394_IDMA_ERR_LAST is updated if a new error code is
* added.
*/
/* See ixl1394.h for possible IXL1394 t1394_update_isoch_dma() errors. */
/*
* MISCELLANEOUS SERVICES:
* These are the calls into the 1394 Framework used for miscellaneous
* services, including getting target information and topology map,
* adding to and removing from local Config ROM, initiating bus resets,
* etc. The t1394_get_targetinfo() routine is used to get information
* about the target driver's device and about current bus conditions
* that might be useful to a target. By passing the target handle and
* current bus generation, a target driver can expect to receive a filled
* in t1394_targetinfo_t structure (see above) that contains the
* current_max_payload, current_max_speed, and device's nodeID.
* The t1394_initiate_bus_reset() routine can be used by target drivers
* to initiate a bus reset. This call should be used only when it is
* absolutely imperative, however, as bus resets affect all devices on
* the 1394 Serial Bus and excessive use of bus resets can have an
* adverse effect on overall bus performance.
* The t1394_get_topology_map() will return the TOPOLOGY_MAP (see
* IEEE 1394-1995, Section 8.3.2.4.1) which is a list of SelfID packets
* from the current bus generation.
* The t1394_CRC16() call is used to calculate cyclic redundancy checks
* (CRCs) necessary for use in Config ROM buffers.
* The t1394_add_cfgrom_entry() and t1394_rem_cfgrom_entry() calls are
* used, respectively, to add and remove entries from the local host
* Config ROM buffer. (See above for a description of the
* t1394_cfgrom_entryinfo_t structure.)
* And the t1394_errmsg() routine is used to convert result codes which
* have been returned by the 1394 Framework into character strings for
* use in error messages.
*/
/* Results codes returned by t1394_add_cfgrom_entry() */
/*
* NOTE: Make sure T1394_ECFG_LAST is updated if a new error code is
* added. t1394_errmsg.c uses *FIRST and *LAST as bounds checks.
*/
#ifdef __cplusplus
}
#endif
#endif /* _SYS_1394_T1394_H */