[linux-2.6-block.git] / drivers / staging / tidspbridge / include / dspbridge / nldrdefs.h

/*
 * nldrdefs.h
 *
 * DSP-BIOS Bridge driver support functions for TI OMAP processors.
 *
 * Global Dynamic + static/overlay Node loader (NLDR) constants and types.
 *
 * Copyright (C) 2008 Texas Instruments, Inc.
 *
 * This package is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 *
 * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 */

#ifndef NLDRDEFS_
#define NLDRDEFS_

#include <dspbridge/dbdcddef.h>
#include <dspbridge/devdefs.h>

#define NLDR_MAXPATHLENGTH       255
/* NLDR Objects: */
struct nldr_object;
struct nldr_nodeobject;

/*
 *  ======== nldr_loadtype ========
 *  Load types for a node. Must match values in node.h55.
 */
enum nldr_loadtype {
	NLDR_STATICLOAD,	/* Linked in base image, not overlay */
	NLDR_DYNAMICLOAD,	/* Dynamically loaded node */
	NLDR_OVLYLOAD		/* Linked in base image, overlay node */
};

/*
 *  ======== nldr_ovlyfxn ========
 *  Causes code or data to be copied from load address to run address. This
 *  is the "cod_writefxn" that gets passed to the DBLL_Library and is used as
 *  the ZL write function.
 *
 *  Parameters:
 *      priv_ref:       Handle to identify the node.
 *      dsp_run_addr:   Run address of code or data.
 *      dsp_load_addr:  Load address of code or data.
 *      ul_num_bytes:     Number of (GPP) bytes to copy.
 *      mem_space:      RMS_CODE or RMS_DATA.
 *  Returns:
 *      ul_num_bytes:     Success.
 *      0:              Failure.
 *  Requires:
 *  Ensures:
 */
typedef u32(*nldr_ovlyfxn) (void *priv_ref, u32 dsp_run_addr,
			    u32 dsp_load_addr, u32 ul_num_bytes, u32 mem_space);

/*
 *  ======== nldr_writefxn ========
 *  Write memory function. Used for dynamic load writes.
 *  Parameters:
 *      priv_ref:       Handle to identify the node.
 *      dsp_add:        Address of code or data.
 *      pbuf:           Code or data to be written
 *      ul_num_bytes:     Number of (GPP) bytes to write.
 *      mem_space:      DBLL_DATA or DBLL_CODE.
 *  Returns:
 *      ul_num_bytes:     Success.
 *      0:              Failure.
 *  Requires:
 *  Ensures:
 */
typedef u32(*nldr_writefxn) (void *priv_ref,
			     u32 dsp_add, void *pbuf,
			     u32 ul_num_bytes, u32 mem_space);

/*
 *  ======== nldr_attrs ========
 *  Attributes passed to nldr_create function.
 */
struct nldr_attrs {
	nldr_ovlyfxn ovly;
	nldr_writefxn write;
	u16 dsp_word_size;
	u16 dsp_mau_size;
};

/*
 *  ======== nldr_phase ========
 *  Indicates node create, delete, or execute phase function.
 */
enum nldr_phase {
	NLDR_CREATE,
	NLDR_DELETE,
	NLDR_EXECUTE,
	NLDR_NOPHASE
};

/*
 *  Typedefs of loader functions imported from a DLL, or defined in a
 *  function table.
 */

/*
 *  ======== nldr_allocate ========
 *  Allocate resources to manage the loading of a node on the DSP.
 *
 *  Parameters:
 *      nldr_obj:          Handle of loader that will load the node.
 *      priv_ref:       Handle to identify the node.
 *      node_props:     Pointer to a dcd_nodeprops for the node.
 *      nldr_nodeobj:   Location to store node handle on output. This handle
 *                      will be passed to nldr_load/nldr_unload.
 *      pf_phase_split:   pointer to int variable referenced in node.c
 *  Returns:
 *      0:        Success.
 *      -ENOMEM:    Insufficient memory on GPP.
 *  Requires:
 *      nldr_init(void) called.
 *      Valid nldr_obj.
 *      node_props != NULL.
 *      nldr_nodeobj != NULL.
 *  Ensures:
 *      0:        IsValidNode(*nldr_nodeobj).
 *      error:          *nldr_nodeobj == NULL.
 */
typedef int(*nldr_allocatefxn) (struct nldr_object *nldr_obj,
				       void *priv_ref,
				       const struct dcd_nodeprops
				       * node_props,
				       struct nldr_nodeobject
				       **nldr_nodeobj,
				       bool *pf_phase_split);

/*
 *  ======== nldr_create ========
 *  Create a loader object. This object handles the loading and unloading of
 *  create, delete, and execute phase functions of nodes on the DSP target.
 *
 *  Parameters:
 *      nldr:           Location to store loader handle on output.
 *      hdev_obj:     Device for this processor.
 *      pattrs:         Loader attributes.
 *  Returns:
 *      0:        Success;
 *      -ENOMEM:    Insufficient memory for requested resources.
 *  Requires:
 *      nldr_init(void) called.
 *      nldr != NULL.
 *      hdev_obj != NULL.
 *	pattrs != NULL.
 *  Ensures:
 *      0:        Valid *nldr.
 *      error:          *nldr == NULL.
 */
typedef int(*nldr_createfxn) (struct nldr_object **nldr,
				     struct dev_object *hdev_obj,
				     const struct nldr_attrs *pattrs);

/*
 *  ======== nldr_delete ========
 *  Delete the NLDR loader.
 *
 *  Parameters:
 *      nldr_obj:          Node manager object.
 *  Returns:
 *  Requires:
 *      nldr_init(void) called.
 *      Valid nldr_obj.
 *  Ensures:
 *	nldr_obj invalid
 */
typedef void (*nldr_deletefxn) (struct nldr_object *nldr_obj);

/*
 *  ======== nldr_exit ========
 *  Discontinue usage of NLDR module.
 *
 *  Parameters:
 *  Returns:
 *  Requires:
 *      nldr_init(void) successfully called before.
 *  Ensures:
 *      Any resources acquired in nldr_init(void) will be freed when last NLDR
 *      client calls nldr_exit(void).
 */
typedef void (*nldr_exitfxn) (void);

/*
 *  ======== NLDR_Free ========
 *  Free resources allocated in nldr_allocate.
 *
 *  Parameters:
 *      nldr_node_obj:      Handle returned from nldr_allocate().
 *  Returns:
 *  Requires:
 *      nldr_init(void) called.
 *      Valid nldr_node_obj.
 *  Ensures:
 */
typedef void (*nldr_freefxn) (struct nldr_nodeobject *nldr_node_obj);

/*
 *  ======== nldr_get_fxn_addr ========
 *  Get address of create, delete, or execute phase function of a node on
 *  the DSP.
 *
 *  Parameters:
 *      nldr_node_obj:      Handle returned from nldr_allocate().
 *      str_fxn:        Name of function.
 *      addr:           Location to store function address.
 *  Returns:
 *      0:        Success.
 *      -ESPIPE:    Address of function not found.
 *  Requires:
 *      nldr_init(void) called.
 *      Valid nldr_node_obj.
 *      addr != NULL;
 *      str_fxn != NULL;
 *  Ensures:
 */
typedef int(*nldr_getfxnaddrfxn) (struct nldr_nodeobject
					 * nldr_node_obj,
					 char *str_fxn, u32 * addr);

/*
 *  ======== nldr_init ========
 *  Initialize the NLDR module.
 *
 *  Parameters:
 *  Returns:
 *      TRUE if initialization succeeded, FALSE otherwise.
 *  Ensures:
 */
typedef bool(*nldr_initfxn) (void);

/*
 *  ======== nldr_load ========
 *  Load create, delete, or execute phase function of a node on the DSP.
 *
 *  Parameters:
 *      nldr_node_obj:      Handle returned from nldr_allocate().
 *      phase:          Type of function to load (create, delete, or execute).
 *  Returns:
 *      0:                Success.
 *      -ENOMEM:            Insufficient memory on GPP.
 *      -ENXIO:     Can't overlay phase because overlay memory
 *                              is already in use.
 *      -EILSEQ:           Failure in dynamic loader library.
 *  Requires:
 *      nldr_init(void) called.
 *      Valid nldr_node_obj.
 *  Ensures:
 */
typedef int(*nldr_loadfxn) (struct nldr_nodeobject *nldr_node_obj,
				   enum nldr_phase phase);

/*
 *  ======== nldr_unload ========
 *  Unload create, delete, or execute phase function of a node on the DSP.
 *
 *  Parameters:
 *      nldr_node_obj:      Handle returned from nldr_allocate().
 *      phase:          Node function to unload (create, delete, or execute).
 *  Returns:
 *      0:        Success.
 *      -ENOMEM:    Insufficient memory on GPP.
 *  Requires:
 *      nldr_init(void) called.
 *      Valid nldr_node_obj.
 *  Ensures:
 */
typedef int(*nldr_unloadfxn) (struct nldr_nodeobject *nldr_node_obj,
				     enum nldr_phase phase);

/*
 *  ======== node_ldr_fxns ========
 */
struct node_ldr_fxns {
	nldr_allocatefxn allocate;
	nldr_createfxn create;
	nldr_deletefxn delete;
	nldr_exitfxn exit;
	nldr_getfxnaddrfxn get_fxn_addr;
	nldr_initfxn init;
	nldr_loadfxn load;
	nldr_unloadfxn unload;
};

#endif /* NLDRDEFS_ */
Commit	Line	Data
6280238c ORL	1	/*
	2	* nldrdefs.h
	3	*
	4	* DSP-BIOS Bridge driver support functions for TI OMAP processors.
	5	*
	6	* Global Dynamic + static/overlay Node loader (NLDR) constants and types.
	7	*
	8	* Copyright (C) 2008 Texas Instruments, Inc.
	9	*
	10	* This package is free software; you can redistribute it and/or modify
	11	* it under the terms of the GNU General Public License version 2 as
	12	* published by the Free Software Foundation.
	13	*
	14	* THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
	15	* IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
	16	* WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
	17	*/
	18
	19	#ifndef NLDRDEFS_
	20	#define NLDRDEFS_
	21
	22	#include <dspbridge/dbdcddef.h>
	23	#include <dspbridge/devdefs.h>
	24
	25	#define NLDR_MAXPATHLENGTH 255
	26	/* NLDR Objects: */
	27	struct nldr_object;
	28	struct nldr_nodeobject;
	29
	30	/*
	31	* ======== nldr_loadtype ========
	32	* Load types for a node. Must match values in node.h55.
	33	*/
	34	enum nldr_loadtype {
	35	NLDR_STATICLOAD, /* Linked in base image, not overlay */
	36	NLDR_DYNAMICLOAD, /* Dynamically loaded node */
	37	NLDR_OVLYLOAD /* Linked in base image, overlay node */
	38	};
	39
	40	/*
	41	* ======== nldr_ovlyfxn ========
	42	* Causes code or data to be copied from load address to run address. This
	43	* is the "cod_writefxn" that gets passed to the DBLL_Library and is used as
	44	* the ZL write function.
	45	*
	46	* Parameters:
	47	* priv_ref: Handle to identify the node.
5e2eae57 RS	48	* dsp_run_addr: Run address of code or data.
5e2eae57 RS	49	* dsp_load_addr: Load address of code or data.
6280238c	50	* ul_num_bytes: Number of (GPP) bytes to copy.
95870a88	51	* mem_space: RMS_CODE or RMS_DATA.
6280238c ORL	52	* Returns:
	53	* ul_num_bytes: Success.
	54	* 0: Failure.
	55	* Requires:
	56	* Ensures:
	57	*/
5e2eae57 RS	58	typedef u32(nldr_ovlyfxn) (void priv_ref, u32 dsp_run_addr,
5e2eae57 RS	59	u32 dsp_load_addr, u32 ul_num_bytes, u32 mem_space);
6280238c ORL	60
	61	/*
	62	* ======== nldr_writefxn ========
	63	* Write memory function. Used for dynamic load writes.
	64	* Parameters:
	65	* priv_ref: Handle to identify the node.
5e2eae57	66	* dsp_add: Address of code or data.
6280238c ORL	67	* pbuf: Code or data to be written
6280238c ORL	68	* ul_num_bytes: Number of (GPP) bytes to write.
95870a88	69	* mem_space: DBLL_DATA or DBLL_CODE.
6280238c ORL	70	* Returns:
	71	* ul_num_bytes: Success.
	72	* 0: Failure.
	73	* Requires:
	74	* Ensures:
	75	*/
	76	typedef u32(nldr_writefxn) (void priv_ref,
5e2eae57	77	u32 dsp_add, void *pbuf,
95870a88	78	u32 ul_num_bytes, u32 mem_space);
6280238c ORL	79
	80	/*
	81	* ======== nldr_attrs ========
	82	* Attributes passed to nldr_create function.
	83	*/
	84	struct nldr_attrs {
09f13304	85	nldr_ovlyfxn ovly;
dab7f7fe	86	nldr_writefxn write;
085467b8 RS	87	u16 dsp_word_size;
085467b8 RS	88	u16 dsp_mau_size;
6280238c ORL	89	};
	90
	91	/*
	92	* ======== nldr_phase ========
	93	* Indicates node create, delete, or execute phase function.
	94	*/
	95	enum nldr_phase {
	96	NLDR_CREATE,
	97	NLDR_DELETE,
	98	NLDR_EXECUTE,
	99	NLDR_NOPHASE
	100	};
	101
	102	/*
	103	* Typedefs of loader functions imported from a DLL, or defined in a
	104	* function table.
	105	*/
	106
	107	/*
	108	* ======== nldr_allocate ========
	109	* Allocate resources to manage the loading of a node on the DSP.
	110	*
	111	* Parameters:
	112	* nldr_obj: Handle of loader that will load the node.
	113	* priv_ref: Handle to identify the node.
	114	* node_props: Pointer to a dcd_nodeprops for the node.
e436d07d	115	* nldr_nodeobj: Location to store node handle on output. This handle
6280238c ORL	116	* will be passed to nldr_load/nldr_unload.
	117	* pf_phase_split: pointer to int variable referenced in node.c
	118	* Returns:
	119	* 0: Success.
	120	* -ENOMEM: Insufficient memory on GPP.
	121	* Requires:
	122	* nldr_init(void) called.
	123	* Valid nldr_obj.
	124	* node_props != NULL.
e436d07d	125	* nldr_nodeobj != NULL.
6280238c	126	* Ensures:
e436d07d RS	127	* 0: IsValidNode(*nldr_nodeobj).
e436d07d RS	128	* error: *nldr_nodeobj == NULL.
6280238c ORL	129	*/
	130	typedef int(nldr_allocatefxn) (struct nldr_object nldr_obj,
	131	void *priv_ref,
9d7d0a52	132	const struct dcd_nodeprops
6280238c	133	* node_props,
e6bf74f0	134	struct nldr_nodeobject
e436d07d	135	**nldr_nodeobj,
e6bf74f0	136	bool *pf_phase_split);
6280238c ORL	137
	138	/*
	139	* ======== nldr_create ========
	140	* Create a loader object. This object handles the loading and unloading of
	141	* create, delete, and execute phase functions of nodes on the DSP target.
	142	*
	143	* Parameters:
daa89e6c	144	* nldr: Location to store loader handle on output.
6280238c ORL	145	* hdev_obj: Device for this processor.
	146	* pattrs: Loader attributes.
	147	* Returns:
	148	* 0: Success;
	149	* -ENOMEM: Insufficient memory for requested resources.
	150	* Requires:
	151	* nldr_init(void) called.
daa89e6c	152	* nldr != NULL.
6280238c ORL	153	* hdev_obj != NULL.
	154	* pattrs != NULL.
	155	* Ensures:
daa89e6c RS	156	* 0: Valid *nldr.
daa89e6c RS	157	* error: *nldr == NULL.
6280238c	158	*/
e6bf74f0	159	typedef int(nldr_createfxn) (struct nldr_object *nldr,
6280238c	160	struct dev_object *hdev_obj,
9d7d0a52	161	const struct nldr_attrs *pattrs);
6280238c ORL	162
	163	/*
	164	* ======== nldr_delete ========
	165	* Delete the NLDR loader.
	166	*
	167	* Parameters:
	168	* nldr_obj: Node manager object.
	169	* Returns:
	170	* Requires:
	171	* nldr_init(void) called.
	172	* Valid nldr_obj.
	173	* Ensures:
	174	* nldr_obj invalid
	175	*/
	176	typedef void (nldr_deletefxn) (struct nldr_object nldr_obj);
	177
	178	/*
	179	* ======== nldr_exit ========
	180	* Discontinue usage of NLDR module.
	181	*
	182	* Parameters:
	183	* Returns:
	184	* Requires:
	185	* nldr_init(void) successfully called before.
	186	* Ensures:
	187	* Any resources acquired in nldr_init(void) will be freed when last NLDR
	188	* client calls nldr_exit(void).
	189	*/
	190	typedef void (*nldr_exitfxn) (void);
	191
	192	/*
	193	* ======== NLDR_Free ========
	194	* Free resources allocated in nldr_allocate.
	195	*
	196	* Parameters:
	197	* nldr_node_obj: Handle returned from nldr_allocate().
	198	* Returns:
	199	* Requires:
	200	* nldr_init(void) called.
	201	* Valid nldr_node_obj.
	202	* Ensures:
	203	*/
	204	typedef void (nldr_freefxn) (struct nldr_nodeobject nldr_node_obj);
	205
	206	/*
	207	* ======== nldr_get_fxn_addr ========
	208	* Get address of create, delete, or execute phase function of a node on
	209	* the DSP.
	210	*
	211	* Parameters:
	212	* nldr_node_obj: Handle returned from nldr_allocate().
383b8345 RS	213	* str_fxn: Name of function.
383b8345 RS	214	* addr: Location to store function address.
6280238c ORL	215	* Returns:
	216	* 0: Success.
	217	* -ESPIPE: Address of function not found.
	218	* Requires:
	219	* nldr_init(void) called.
	220	* Valid nldr_node_obj.
383b8345 RS	221	* addr != NULL;
383b8345 RS	222	* str_fxn != NULL;
6280238c ORL	223	* Ensures:
	224	*/
	225	typedef int(*nldr_getfxnaddrfxn) (struct nldr_nodeobject
	226	* nldr_node_obj,
383b8345	227	char str_fxn, u32 addr);
6280238c ORL	228
	229	/*
	230	* ======== nldr_init ========
	231	* Initialize the NLDR module.
	232	*
	233	* Parameters:
	234	* Returns:
	235	* TRUE if initialization succeeded, FALSE otherwise.
	236	* Ensures:
	237	*/
	238	typedef bool(*nldr_initfxn) (void);
	239
	240	/*
	241	* ======== nldr_load ========
	242	* Load create, delete, or execute phase function of a node on the DSP.
	243	*
	244	* Parameters:
	245	* nldr_node_obj: Handle returned from nldr_allocate().
	246	* phase: Type of function to load (create, delete, or execute).
	247	* Returns:
	248	* 0: Success.
	249	* -ENOMEM: Insufficient memory on GPP.
	250	* -ENXIO: Can't overlay phase because overlay memory
	251	* is already in use.
	252	* -EILSEQ: Failure in dynamic loader library.
	253	* Requires:
	254	* nldr_init(void) called.
	255	* Valid nldr_node_obj.
	256	* Ensures:
	257	*/
	258	typedef int(nldr_loadfxn) (struct nldr_nodeobject nldr_node_obj,
	259	enum nldr_phase phase);
	260
	261	/*
	262	* ======== nldr_unload ========
	263	* Unload create, delete, or execute phase function of a node on the DSP.
	264	*
	265	* Parameters:
	266	* nldr_node_obj: Handle returned from nldr_allocate().
	267	* phase: Node function to unload (create, delete, or execute).
	268	* Returns:
	269	* 0: Success.
	270	* -ENOMEM: Insufficient memory on GPP.
	271	* Requires:
	272	* nldr_init(void) called.
	273	* Valid nldr_node_obj.
	274	* Ensures:
	275	*/
	276	typedef int(nldr_unloadfxn) (struct nldr_nodeobject nldr_node_obj,
	277	enum nldr_phase phase);
	278
	279	/*
	280	* ======== node_ldr_fxns ========
	281	*/
	282	struct node_ldr_fxns {
3c882de5	283	nldr_allocatefxn allocate;
e17ba7f2 RS	284	nldr_createfxn create;
e17ba7f2 RS	285	nldr_deletefxn delete;
09f13304 RS	286	nldr_exitfxn exit;
	287	nldr_getfxnaddrfxn get_fxn_addr;
	288	nldr_initfxn init;
	289	nldr_loadfxn load;
	290	nldr_unloadfxn unload;
6280238c ORL	291	};
	292
	293	#endif /* NLDRDEFS_ */