Much of an LCP's representation of LCP and library state can be represented generically. However, the LCP developer needs a way to customize this representation for a particular library and implementation.

The LCP framework provides a private data area and programmable LCP entry points as a means for the developer to customize the LCP's representation of LCP and library state. The private data area allows the developer to maintain additional information about the LCP and library; the programmable entry points allow the developer to customize actions associated with ALI command dispatch, deactivation (transition to ready lost state), graceful shutdown, and ALI/R command task ID generation. This arrangement allows the shared framework to invoke these entry points as appropriate.

Example 4-1 shows the framework's generic representation for a library.

struct libinfo
{
    /* elements from LCP config file. */
    char *client;                     /* MLM name of this library.   */
    char *instance;                   /* Client instance.            */
    char *mlmhost;                    /* MLM host.                   */
    int mlmport;                      /* MLM port.                   */
    int pollinterval;                 /* seconds between library polls */
    char *addr;                       /* library control address.    */
                                      /* elements initiated by LCP.  */
    char *type;                       /* Type of library.            */
    enum ALIR_msg_severity loglevel;  /* Log level for LCP messages  */
    enum ALIR_ready_type readystatus; /* ready, not r_, disconnected */
    int supportPCLs;                  /* 1 if barcode scanner, or 0  */
    char *vendor;                     /* Library vendor name.        */
    queue_t ALI_cmd_queue;            /* ALI command queue.          */
    queue_t ALIR_cmd_queue;           /* ALIR command queue.         */
    int waiting_for_ack;              /* 1 if waiting for ack, or 0  */
    char *taskid_for_ack;             /* TaskID of last ALIR command */
    void(*lcp_deactivate)(struct libinfo *libi);      /* deactivate  */
    void(*lcp_exit)(struct libinfo *libi, int abnormal); /* shutdown */
    void(*lcp_dispatch)(struct libinfo *libi, struct ALI_command *cmd);
    char *(*lcp_taskid)(struct libinfo *libi);  /* taskid generation */
    /* element map info, shared by do- and control-layers */
    element_map_t slotmap;            /* Slot map                    */
    element_map_t drivemap;           /* Drive map                   */
    element_map_t portmap;            /* Port map                    */
    element_map_t baymap;             /* Bay map                     */
    void *private;                    /* LCP private libary info     */
};

An LCP that makes use of this developer framework must call the lcp_init subroutine, shown in Example 4-2, to initialize the generic and private data areas for LCP and library information, and set the programmable LCP entry points:

void lcp_init(struct libinfo *libi,
        void lcp_init_private(),
        void lcp_deactivate(),
        void lcp_exit(),
        void lcp_dispatch(),
        char *lcp_taskid(),
        void slot_private(),
        void drive_private(),
        void bay_private(),
        void port_private());

This entry point is called one time only from lcp_init(); so the libinfo structure does not store it. Required entry point for LCP private data area allocation and initialization:

void lcp_init_private(struct libinfo *libi);

Remaining entry points are stored in the libinfo structure. Required entry point for LCP private actions to activate disable:

void lcp_deactivate(struct libinfo *libi);

Required entry point for LCP private actions to shut down gracefully and exit:

void lcp_exit(struct libinfo *libi, int abnormal);

Required entry point for ALI command dispatch from the command state machine:

void lcp_dispatch(struct libinfo *libi, struct ALI_command *cmd);

Required entry point for LCP to generate a task ID for ALI/R commands:

void char *lcp_taskid(struct libinfo *libi);

Optional entry points for element map allocation and initialization (may be NULL):

void slot_private(queue_t *q, int initflag);
void drive_private(queue_t *q, int initflag);
void bay_private(queue_t *q, int initflag);
void port_private(queue_t *q, int initflag);

Much of the information that an LCP needs to maintain about library elements, including slots, drives, bays, and ports, may be generically represented. However, LCP developers must be able to customize element information that the LCP maintains.

For example, typical information that an LCP needs to maintain about a slot includes the slotID, the device-specific address for this slot, the name of the bay in which this slot is located, whether the slot is accessible and occupied, the PCL of the cartridge that is currently occupying this slot (if any), and the name of the drive where the cartridge that was last in this slot is currently mounted (if any).

For typical slot information, the framework provides an extension to the common information by means of an LCP private data area and programmable entry points for allocating and deallocating this data area.

An example of how an LCP might use its private slot data area is for multi-sided media, where the library can mount the cartridge either “side A” up, or “side B” up. In addition to the typical slot information, an LCP for such a library would probably maintain the current orientation of a cartridge in its private data area for that slot.

The element map header file, maps.h, is separated from the LCP common header file, lcp_lib.h, so that the generic element map representation and subroutines may be used separately from the generic library piece. In the sample implementations, this permits the ALI semantic layer and the control layer modules for an LCP to share the element map representation, without both having to include the generic library piece. The control layer needs the generic element map piece, but not the generic library piece.

Example 4-3 illustrates the common representations for slot, drive, bay, and port:

typedef struct slot {
    char       *name;        /* Slot id.                            */
    char       *addr;        /* Hardware address.                   */
    char       *bayid;       /* Name of bay where slot resides      */
    char       *shape;       /* Of cartridges fitting this slot     */
    int        access;       /* T/F: is slot accessible?            */
    int        occupied;     /* T/F: is slot occupied?              */
    char       *PCL;         /* Label of cartridge in slot, if any  */
    char       *driveid;     /* Drive with slot's cartridge, if any */
    void       *private;     /* LCP private data area.              */
    queue_t    queue;        /* To next/prev slots.                 */
} slot_t;
typedef struct drive {
    char       *name;        /* Name of drive.                       */
    char       *addr;        /* Hardware address.                    */
    char       *bayid;       /* Name of bay where drive resides      */
    char       *shape;       /* Of cartridges that fit in this drive */
    int        access;       /* T/F: is drive accessible?            */
    int        occupied;     /* T/F: is drive occupied?              */
    char       *PCL;         /* Label of cartridge in drive, if any  */
    char       *slotid;      /* Slot from where cartridge mounted    */
    void       *private;     /* LCP private data area                */
    queue_t    queue;        /* To next/prev drives                  */
} drive_t;
typedef struct bay {
    char       *name;        /* Name of bay                          */
    char       *addr;        /* Hardware address                     */
    int        access;       /* T/F: is bay accessible?              */
    void       *private;     /* LCP private data area                */
    queue_t    queue;        /* To next/prev bays                    */
} bay_t;
typedef struct port {
    char       *name;        /* Name of port                         */
    char       *addr;        /* Hardware address                     */
    char       *bayid;       /* Name of bay where port resides       */
    int        access;       /* T/F: is port accessable?             */
    element_map_t slots;     /* Separately addressable slots in port */
    void       *private;     /* LCP private data area                */
    queue_t    queue;        /* To next/prev ports                   */
} port_t;

The element map header file is separated from generic library representation, to allow element maps to be shared between potentially different layers of an LCP, for instance between the ALI semantic layer and the device access layer. In sample implementations, the device layer fills in some of this information and the ALI semantic layer fills in the rest, then passes element maps to the MLM server with an ALI/R config command.

The following convenience routines are provided in module ovsrc/include/util.c to handle LCP element maps. See the ovsrc/include/maps.h file for subroutine prototypes.

This section summarizes convenience routines available in module ovsrc/include/util.c, grouped by purpose:

Example 4-4 shows the ovsrc/clients/lcp/EXABYTE-210/config file, which describes both the library and MLM server.

localhost          # MLM server host name
739                # MLM server TCP socket
wilma              # OpenVault name for library
host-bedrock       # LCP instance name
/dev/scsi/sc0d510  # SCSI drive control access path
60                 # Library polling interval
fred:82            # Map OpenVault drive name to library address
barney:83          # Do likewise for second drive

The ovsrc/clients/lcp/EXABYTE-210/control.h header file contains the device access layer device representation, and declares subroutine entry points for the ALI semantics layer to access the device. The ovsrc/clients/lcp/EXABYTE-210/control.c module implements these subroutines.

This layer, named after its many functions starting with “do,” is where the LCP interprets ALI commands. The programmer customizes this layer, based on the generic library methods that are provided as part of the LCP developer framework.

The ovsrc/clients/lcp/EXABYTE-210/main.h header file contains the LCP private data area of a generic library representation, and associated macros and subroutine prototypes, including four programmable LCP entry points used by the framework, and semantic support routines. The ovsrc/clients/lcp/EXABYTE-210/main.c module is where ALI semantic handling routines are implemented, and where ALI commands are dispatched to the appropriate semantic handling routine. For example, the ALI mount command would be dispatched to the do_mount() function.

The EXABYTE 210 LCP does not require custom element maps, because the developer framework provides an adequate generic representation. Other LCPs may require customization. Programmers can customize element map representation by creating the ovsrc/src.BSD/lcp/NAME/maps_private.h and ovsrc/src.BSD/lcp/NAME/maps_private.c files, where NAME represents the LCP name.

Certain media libraries may perform parallel (instead of serial) execution of commands, and complex (not simple) mappings of ALI to underlying library control. Some libraries, such as SCSI-2 media changers, execute device control commands in a blocking or serial fashion. For most of these devices, there is a one-to-one mapping between an ALI command and the underlying SCSI-2 request. The LCP implementation for such a device may be trivial. For this sort of device, the LCP implementor may simply implement all ALI commands in a serial fashion. No extension of the framework is needed.

Other libraries, such as the StorageTek ACSLS and the IBM 3494, provide some parallelism in control command execution. Optimal use of these devices requires some extra work on the part of the LCP developer to extend the framework. These controllers tend to be more complex than SCSI-2, and require one ALI command to be mapped to potentially multiple underlying control requests. This requires a command execution state machine. Also, developers must understand command dependencies and how the underlying library or controller executes commands, to ensure proper sequencing.