Commit cbf5f4fb authored by Ingo Molnar's avatar Ingo Molnar
Browse files

x86/headers: Clean up and better document uapi/asm/sigcontext.h 



Clean up sigcontext.h:

 - the explanations were full of typos and were hard to read in general
 - use consistent and readable vertical spacing
 - fix, harmonize and extend comments

No field name has been changed, user-space might be relying on
them.

Acked-by: default avatarMikko Rapeli <mikko.rapeli@iki.fi>
Cc: Andy Lutomirski <luto@amacapital.net>
Cc: Borislav Petkov <bp@alien8.de>
Cc: Brian Gerst <brgerst@gmail.com>
Cc: Denys Vlasenko <dvlasenk@redhat.com>
Cc: H. Peter Anvin <hpa@zytor.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Oleg Nesterov <oleg@redhat.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: linux-kernel@vger.kernel.org
Link: http://lkml.kernel.org/r/1441438363-9999-4-git-send-email-mingo@kernel.org


Signed-off-by: default avatarIngo Molnar <mingo@kernel.org>
parent c3f4986f

arch/x86/include/uapi/asm/sigcontext.h

+182 −148
Original line number Diff line number Diff line 
#ifndef _UAPI_ASM_X86_SIGCONTEXT_H

#define _UAPI_ASM_X86_SIGCONTEXT_H



/*

 * Linux signal context definitions. The sigcontext includes a complex hierarchy of CPU

 * and FPU state, available to user-space (on the stack) when a signal handler is

 * executed.

 *

 * As over the years this ABI grew from its very simple roots towards supporting more and

 * more CPU state organically, some of the details (which were rather clever hacks back

 * in the days) became a bit quirky by today.

 *

 * The current ABI includes flexible provisions for future extensions, so we won't have

 * to grow new quirks for quite some time. Promise!

 */



#include <linux/compiler.h>

#include <linux/types.h>
@@ -9,67 +22,82 @@ 
#define FP_XSTATE_MAGIC2_SIZE		sizeof(FP_XSTATE_MAGIC2)



/*

 * bytes 464..511 in the current 512byte layout of fxsave/fxrstor frame

 * are reserved for SW usage. On cpu's supporting xsave/xrstor, these bytes

 * are used to extended the fpstate pointer in the sigcontext, which now

 * Bytes 464..511 in the current 512-byte layout of the FXSAVE/FXRSTOR frame

 * are reserved for SW usage. On CPUs supporting XSAVE/XRSTOR, these bytes

 * are used to extend the fpstate pointer in the sigcontext, which now

 * includes the extended state information along with fpstate information.

 *

 * Presence of FP_XSTATE_MAGIC1 at the beginning of this SW reserved

 * area and FP_XSTATE_MAGIC2 at the end of memory layout

 * (extended_size - FP_XSTATE_MAGIC2_SIZE) indicates the presence of the

 * extended state information in the memory layout pointed by the fpstate

 * pointer in sigcontext.

 * If sw_reserved.magic1 == FP_XSTATE_MAGIC1 then there's a sw_reserved.extended_size

 * bytes large extended context area present. (The last 32-bit word of this extended

 * area (at the fpstate+extended_size-FP_XSTATE_MAGIC2_SIZE address) is set to

 * FP_XSTATE_MAGIC2 so that you can sanity check your size calculations.)

 *

 * This extended area typically grows with newer CPUs that have larger and larger

 * XSAVE areas.

 */

struct _fpx_sw_bytes {

	__u32 magic1;		/* FP_XSTATE_MAGIC1 */

	__u32 extended_size;	/* total size of the layout referred by

				 * fpstate pointer in the sigcontext.

	/* If set to FP_XSTATE_MAGIC1 then this is an xstate context. 0 if a legacy frame. */

	__u32				magic1;



	/*

	 * Total size of the fpstate area:

	 *

	 *  - if magic1 == 0 then it's sizeof(struct _fpstate)

	 *  - if magic1 == FP_XSTATE_MAGIC1 then it's sizeof(struct _xstate) plus extensions (if any)

	 */

	__u64 xfeatures;

				/* feature bit mask (including fp/sse/extended

				 * state) that is present in the memory

				 * layout.

	__u32				extended_size;



	/*

	 * Feature bit mask (including FP/SSE/extended state) that is present

	 * in the memory layout:

	 */

	__u32 xstate_size;	/* actual xsave state size, based on the

				 * features saved in the layout.

				 * 'extended_size' will be greater than

				 * 'xstate_size'.

	__u64				xfeatures;



	/*

	 * Actual XSAVE state size, based on the xfeatures saved in the layout.

	 * 'extended_size' is greater than 'xstate_size':

	 */

	__u32 padding[7];	/*  for future use. */

	__u32				xstate_size;



	/* For future use: */

	__u32				padding[7];

};



#ifdef __i386__

/*

 * As documented in the iBCS2 standard..

 * As documented in the iBCS2 standard:

 *

 * The first part of "struct _fpstate" is just the normal i387

 * hardware setup, the extra "status" word is used to save the

 * coprocessor status word before entering the handler.

 *

 * Pentium III FXSR, SSE support

 *	Gareth Hughes <gareth@valinux.com>, May 2000

 *

 * The FPU state data structure has had to grow to accommodate the

 * extended FPU state required by the Streaming SIMD Extensions.

 * There is no documented standard to accomplish this at the moment.

 */



/* 10-byte legacy floating point register: */

struct _fpreg {

	unsigned short			significand[4];

	unsigned short			exponent;

};



/* 16-byte floating point register: */

struct _fpxreg {

	unsigned short			significand[4];

	unsigned short			exponent;

	unsigned short			padding[3];

};



/* 16-byte XMM register: */

struct _xmmreg {

	unsigned long			element[4];

};



#define X86_FXSR_MAGIC			0x0000



struct _fpstate {

	/* Regular FPU environment */

	/* Legacy FPU environment: */

	unsigned long			cw;

	unsigned long			sw;

	unsigned long			tag;
@@ -79,25 +107,23 @@ struct _fpstate { 
	unsigned long			datasel;

	struct _fpreg			_st[8];

	unsigned short			status;

	unsigned short	magic;		/* 0xffff = regular FPU data only */

	unsigned short			magic;		/* 0xffff: regular FPU data only */

							/* 0x0000: FXSR FPU data */



	/* FXSR FPU environment */

	unsigned long			_fxsr_env[6];	/* FXSR FPU env is ignored */

	unsigned long			mxcsr;

	unsigned long			reserved;

	struct _fpxreg			_fxsr_st[8];	/* FXSR FPU reg data is ignored */

	struct _xmmreg	_xmm[8];

	unsigned long	padding1[44];

	struct _xmmreg			_xmm[8];	/* First 8 XMM registers */

	unsigned long			padding1[44];	/* Second 8 XMM registers plus padding */



	union {

		unsigned long		padding2[12];

		struct _fpx_sw_bytes sw_reserved; /* represents the extended

						   * state info */

		struct _fpx_sw_bytes	sw_reserved;	/* Potential extended state is encoded here */

	};

};



#define X86_FXSR_MAGIC		0x0000



# ifndef __KERNEL__

/*

 * User-space might still rely on the old definition:
@@ -128,28 +154,35 @@ struct sigcontext { 
};

# endif /* !__KERNEL__ */



#else /* __i386__ */

#else /* __x86_64__: */



/* FXSAVE frame */

/* Note: reserved1/2 may someday contain valuable data. Always save/restore

   them when you change signal frames. */

/*

 * The FXSAVE frame.

 *

 * Note1: If sw_reserved.magic1 == FP_XSTATE_MAGIC1 then the structure is

 *        larger: 'struct _xstate'. Note that 'struct _xstate' embedds

 *        'struct _fpstate' so that you can always assume the _fpstate portion

 *        exists so that you can check the magic value.

 *

 * Note2: Reserved fields may someday contain valuable data. Always save/restore

 *        them when you change signal frames.

 */

struct _fpstate {

	__u16				cwd;

	__u16				swd;

	__u16	twd;		/* Note this is not the same as the

				   32bit/x87/FSAVE twd */

	/* Note this is not the same as the 32-bit/x87/FSAVE twd: */

	__u16				twd;

	__u16				fop;

	__u64				rip;

	__u64				rdp;

	__u32				mxcsr;

	__u32				mxcsr_mask;

	__u32	st_space[32];	/* 8*16 bytes for each FP-reg */

	__u32	xmm_space[64];	/* 16*16 bytes for each XMM-reg  */

	__u32				st_space[32];	/*  8x  FP registers, 16 bytes each */

	__u32				xmm_space[64];	/* 16x XMM registers, 16 bytes each */

	__u32				reserved2[12];

	union {

		__u32			reserved3[12];

		struct _fpx_sw_bytes sw_reserved; /* represents the extended

						   * state information */

		struct _fpx_sw_bytes	sw_reserved;	/* Potential extended state is encoded here */

	};

};
@@ -184,7 +217,7 @@ struct sigcontext { 
	__u64				trapno;

	__u64				oldmask;

	__u64				cr2;

	struct _fpstate __user *fpstate;	/* zero when no FPU context */

	struct _fpstate __user		*fpstate;	/* Zero when no FPU context */

#  ifdef __ILP32__

	__u32				__fpstate_pad;

#  endif
@@ -192,7 +225,7 @@ struct sigcontext { 
};

# endif /* !__KERNEL__ */



#endif /* !__i386__ */

#endif /* __x86_64__ */



struct _header {

	__u64				xfeatures;
@@ -201,21 +234,22 @@ struct _header { 
};



struct _ymmh_state {

	/* 16 * 16 bytes for each YMMH-reg */

	/* 16x YMM registers, 16 bytes each: */

	__u32				ymmh_space[64];

};



/*

 * Extended state pointed by the fpstate pointer in the sigcontext.

 * In addition to the fpstate, information encoded in the xstate_hdr

 * indicates the presence of other extended state information

 * supported by the processor and OS.

 * Extended state pointed to by sigcontext::fpstate.

 *

 * In addition to the fpstate, information encoded in _xstate::xstate_hdr

 * indicates the presence of other extended state information supported

 * by the CPU and kernel:

 */

struct _xstate {

	struct _fpstate			fpstate;

	struct _header			xstate_hdr;

	struct _ymmh_state		ymmh;

	/* new processor state extensions go here */

	/* New processor state extensions go here: */

};



#endif /* _UAPI_ASM_X86_SIGCONTEXT_H */

CRA Git | Maintained and supported by SUSTech CRA and CCSE